AI Docs Toolkit

AI Docs Toolkit is a documentation toolkit for AI-assisted software development.

It treats documentation as an engineering interface between humans, AI agents, code, tests and change management. It provides versioned CLI and MCP tools, reusable agent instructions and project-owned documentation workflows.

Purpose

The toolkit is intended for projects where:

• AI agents participate in implementation;
• system knowledge must stay readable for humans and usable by automation;
• documentation should define constraints, expected behavior and validation rules;
• changes should be traceable across business rules, architecture, contracts, modules, acceptance criteria and code.

The core idea is that documentation should not be a secondary artifact created after implementation. It should guide implementation, validation and review.

Current Status

Version 0.19.0 includes:

• schema and structure validation for Markdown documents with YAML front matter;
• read-only ownership and declared-dependency diagnostics through ownership-report;
• document graph output;
• impact analysis with linked test cases and changed-path discovery coverage;
• optional saved review evidence and the read-only ai-docs review-check command;
• an optional convention for documentation links beside key code;
• the opt-in ai-docs code-links-check command for Python comment paths and primary IDs;
• optional document-owned Python AST, xUnit and pytest reference checks with explicit native execution;
• test-evidence review connecting requirements to assertions and proportionate sensitivity checks;
• focused document context with owner/ancestor/required constraints and explicit knowledge diagnostics;
• an executable ai-docs CLI;
• optional local MCP runtime entrypoint.
• opt-in workspace impact analysis through CLI and MCP, with explicit manifests, repository-scoped IDs, public event interfaces and visible partial results.

External Work: local execution and feedback

Schema2 connects external intake to an existing local plan. Explicit checkpoints receive new/edited comments; exact-version review records accepted decisions. Offline deterministic reports consume real verification evidence. Explicit sync posts one comment with durable intent, receipts and reconciliation after unknown outcomes. No task/status/label/Git mutation is implied. Schema1 remains read-only and compatible. Both modes require explicit config; credentials stay at runtime.

Installation

After publication, install 0.19.0 with Python 3.14 or newer. Before publication, use only a reviewed local wheel/native artifact:

python -m pip install ai-docs-toolkit==0.19.0
ai-docs --version

For ephemeral execution with uvx:

uvx --python 3.14 --from ai-docs-toolkit==0.19.0 ai-docs --version

For the optional local MCP runtime:

python -m pip install "ai-docs-toolkit[mcp]==0.19.0"
ai-docs-mcp --project-root .

For the latest stable release, use python -m pip install --upgrade ai-docs-toolkit without an exact version pin.

Release 0.19.0

The Python package remains a supported distribution channel. The native Codex plugin is an additional option; replacing Python package delivery is not planned.

Adds explicit complete project releases for the experimental native Codex adapter: local verified import/cache, tracked pin, exact versioned resources, per-project read-only MCP routing and target init/validation migration with pending recovery. Adapter updates preserve project pins. Native Linux checks need no consumer Python; external artifact delivery remains separate from this Python package.

Python CLI/MCP semantics and private runtime config remain supported. Review normal init preflight to refresh the existing release-state ignore rules; no new managed path or project-document migration is introduced. Native adoption is explicit and requires a trusted full release plus matching provenance or target migration. See packaged agent-installation.md, Migration0.18.1 To0.19.0, for commands/recovery.

Release 0.17.1

Strict bounded xUnit discovery accepts explicit parallel or serial collections, with the same positive integer cap, conservative algorithm and copied-JSON checks. No report/config format migration; regenerate discovery after the tool upgrade. Preview ordinary init to refresh the existing agent-profile evidence reference. The source-only Codex plugin prototype remains experimental: this Python release contains no native plugin binary and does not activate it. See “Migration 0.17.0 To 0.17.1” in the installed agent instructions.

Release 0.17.0

External issue intake, authoritative local planning, checkpoint/review and comment reports are opt-in schema2 operations. Existing schema1 sessions are not converted. Refresh the existing external-work reference in both profiles after init preview; there is no new managed path or automatic data migration. See “Migration 0.16.0 To 0.17.0” and “External Work: local planning migration” in installed agent instructions.

Release 0.16.0

context --id ID --intent document selects one owned document plus its owner, ancestors and transitive required constraints, without expanding peers. Mandatory bodies survive soft budgets. Existing intents remain compatible. Optional prospective knowledge and per-document protection/byte diagnostics make implementation, intent and history easier to distinguish. Dated/stage headings are advisory review candidates, never automatic history. Unsupported impact source types produce coverage warnings.

Refresh the existing common schema in both init profiles and the module-documentation reference in the agent profile after preview; preserve project-owned bootstrap and private JSON. New features are opt-in, and init does not restructure product docs. See “Migration 0.15.1 To 0.16.0” in the packaged installation guide for exact checks, manual adoption, MCP reconnect and rollback.

Release 0.15.1

Corrects the0.14.0 migration inventory: the agent profile refreshes the update skill; the packaged init-contract reference is not an init-managed consumer target. Launcher behavior and the four managed assets are unchanged. Existing0.15.0 users need no data migration; verify the selected runtime and reconnect MCP after upgrade. See “Migration 0.15.0 To 0.15.1” in the packaged installation guide.

Release 0.15.0

Both init profiles now deliver .ai-docs/bin/ai-docs.py, a tracked JSON template, a narrow Git ignore rule and the runtime-launcher reference. The launcher chooses an explicit per-checkout executable, forwards arguments/cwd/exit status and never falls back to PATH. It needs only Python 3.10+; the Toolkit package needs Python3.14+.

Personal .ai-docs/local/runtime.json is outside init ownership, including force. Existing bootstrap/config/document IDs and CLI/MCP entrypoints are preserved. Review managed target conflicts before normal refresh. Existing projects can opt in without changing their runtime selection; custom launchers migrate by updating callers and removing the redundant implementation after owner verification. See “Migration 0.14.0 To 0.15.0” in the packaged agent-installation guide.

Release 0.14.0

Native pytest collection uses explicit config/interpreter selection and exact parameter nodeids. Python AST and xUnit-only v1 reports retain compatibility; pytest/mixed discovery uses v2. Separate test-run-capture / test-run-check commands capture pytest JUnit XML with provenance and reuse current results without rerunning tests. Skipped, failed, error and missing cases remain visible. Raw historical XML cannot establish current inputs; Git fingerprints exclude external dependencies/environment, which need owner review.

Testing methodology and scoped .NET/Python/TypeScript skills belong to explicitly adopted AI Project Blueprints sets. Refresh the existing agent-profile evidence reference and routing index with reviewed ordinary init. No new managed path, project-data migration or automatic runner/CI activation is introduced. See “Migration 0.13.0 To 0.14.0” in the packaged agent-installation guide.

Release 0.13.0

The additive ai-docs ownership-report --format json command reports Git-visible file mappings, document owners and declared dependencies. Optional cross-owner references are review candidates, not inferred requirements; missing coverage stays visible. It reads project files without importing or executing project code.

Internal loading and capability/CLI boundaries are clearer; existing commands, JSON formats and legacy core imports remain compatible. Source module entrypoints, current/history separation, runnable examples and delivery inventory are improved. Consumer documents are not relocated. Refresh the existing agent-profile module reference with normal doctor/init preflight; no schema/config/data migration or new managed target is required. See “Migration 0.12.0 To 0.13.0” in the packaged agent-installation guide and retain independent project checks.

Release 0.12.0

Routine check excludes historical source documents by default; deliberate historical analysis uses --history include. Links from current documents into history still validate targets and anchors. Doctor reports bounded capabilities of the configured common schema, without modifying it. Explicit trusted local --discovery-report input reuses fresh xUnit identities without running projects; missing or stale evidence never establishes coverage. Refresh the managed module documentation and test-evidence references after diff review. No document move, ID/type change or new config is required. See Migration 0.11.0 To 0.12.0 in the packaged agent-installation guide; restart long-lived MCP clients after upgrade.

Release 0.9.0

Opt-in module-local/interaction context selects owned documents, ancestors and explicit dependencies with visible gaps. Explicit current/history roles separate retained evidence. Migration inventory/check accounts for baseline sections, destinations and review hashes. Combined docs-check validates local links/anchors and test identities without executing runners. Existing graph context remains the default; all metadata extensions are optional. Refresh managed schemas and instructions through ordinary init after preview. See packaged agent-installation.md, “Migration 0.8.1 To 0.9.0”; preserve project-owned documents and identifiers.

Release 0.8.1

Resource cleanup guidance covers task closure and last-use/allocation checkpoints in long-running work. Preserve useful evidence in canonical locations and register continuing runtime ownership. Project cleanup gates, retention limits, completion evidence and runtime guards remain binding; registration cannot waive them. Retry cleanup independently without repeating successful builds/deployments.

The planning workflow, skill and model are refreshed through ordinary managed init. No cleaner, schema or CLI change is introduced. Preserve owner instructions, configuration and history; reconcile local managed conflicts without blanket force. See packaged agent-installation.md, “Migration 0.8.0 To 0.8.1”, for exact checks and rollback. Older consumers also review intervening migration notes.

Release 0.8.0

Scripts-first evidence processing ships as the economical-evidence skill and reference. Optional artifacts.local_root config gives scripts a discoverable ignored local output location through ai-docs artifacts path --json and MCP config. Lookup is read-only; invalid containment, documentation/tooling overlap, unignored or tracked output roots fail explicitly. Unset projects keep existing behavior. No automatic model routing, directory creation or file migration.

Review init --check/--dry-run, preserve local owner config and instructions, refresh adopted guidance, and run validate/doctor. Opt in to the path separately when useful; exact instructions and rollback are in packaged agent-installation.md, “Migration 0.7.2 To 0.8.0”. Python3.14 and MCP extras remain unchanged.

Release 0.7.2

Portable architecture boundaries, observability design and verification guidance now ship in the agent profile. Typed access can move checks earlier without making query translation or deployed schema compile-checked. Monitoring guidance separates SDK aggregation, durable queues and backend recovery. Stack/runtime choices remain consumer-owned; no automatic application or documentation-layout migration.

Review ai-docs init --profile agent --check and --dry-run, reconcile local edits, refresh managed instructions and run validate/doctor. Preserve owner docs and IDs. Exact migration and rollback are in “Migration 0.7.1 To 0.7.2” in packaged agent-installation.md. Minimal profile content is unchanged.

Release 0.7.1

New project guidance uses one ai-docs knowledge tree for people and agents, module-owned contracts/scenarios/test descriptions, current development procedures and separate dated evidence. .ai-docs remains tooling and policy. Existing layouts stay valid; upgrading the package does not move project documents.

From0.7.0, review ai-docs init --check and --dry-run using the adopted profile, then refresh the managed authoring reference with ordinary init. Manually merge the concise AGENTS pointer if useful. Preserve local rules, IDs and history; no schema, CLI/MCP API or project-data migration is required. Exact commands and rollback are in “Migration 0.7.0 To 0.7.1” in packaged agent-installation.md.

Release 0.7.0

ai-docs test-evidence-check resolves exact file/selector references from an optional test_evidence block in test-case documents. Python uses AST without imports; xUnit v3 builds/discovers only explicitly selected trusted projects after owner restore. Unavailable evidence never passes. Many-to-many links and explicit coverage gaps are supported; unmapped methods are reported for review. The command checks identity, not assertions, test execution or semantic completeness. Ordinary validation remains non-executing; no automatic CI adoption occurs.

Upgrade from0.6.1, review ai-docs init --dry-run with the existing profile and refresh unchanged managed files without blanket force. Agent profiles add the test-evidence.md reference and refresh documentation review guidance. Minimal profiles need no managed content refresh. Preserve owner documents, local rules, IDs and prior evidence. Exact commands, limitations and rollback are in “Migration 0.6.1 To0.7.0” in the packaged ai_docs_toolkit/docs/agent-installation.md.

Release 0.6.1

CLI and MCP validation share faster safe YAML parsing, an AST cache for Python test references and a path-resolution cache scoped to each validation call. Files and symlinks are read again on the next call; concurrent validations keep separate caches. LibYAML is optional, and malformed YAML retains the previous SafeLoader diagnostics. Public commands, JSON, rules and configuration are unchanged.

No project-data or managed-file migration is required from 0.6.0. Upgrade the package, keep the MCP extra when used, restart long-lived MCP servers, then run ai-docs --version, ai-docs validate --json, ai-docs doctor --format json and ai-docs init --check. Preserve project checks and historical review evidence. Exact commands and rollback are in “Migration 0.6.0 To 0.6.1” in the packaged ai_docs_toolkit/docs/agent-installation.md.

Release 0.5.1

Changed-path routing treats only Markdown (.md, case insensitive) inside configured roots as document candidates. Other files use explicit module ownership even within those roots. Local changed context now uses the same ownership declarations, preserving every matching module and changed path. Broken or deleted Markdown retains diagnostics; it cannot fall back to an owner. Unmapped paths remain visible. CLI names, config and JSON shapes are unchanged.

Upgrade the pinned package to 0.5.1, review ai-docs init --dry-run and refresh known unchanged managed references using ordinary ai-docs init. Preserve local policies, IDs, links and historical review evidence; do not use blanket force. Run validation and repeat the actual changed-path review, including mixed roots. Detailed commands and rollback: “Migration 0.5.0 To 0.5.1” in packaged agent docs.

Release 0.5.0

ai-docs workspace impact --workspace ./ai-docs.workspace.yaml --input ./change.yaml --format json analyzes explicitly connected independent repositories. Stable repository IDs namespace document IDs; a system repository owns public event contracts and producer/consumer roles, while local bindings select implementation modules. Modules may be nested within a repository. Cross-repository related.* links and inferred dependency discovery are not required.

The MCP tool is registered only when the server starts with --workspace; ordinary local commands retain their scope. JSON v1 preserves candidates, provenance and diagnostics when a checkout, binding or interface version is missing. A partial result is not a clean review, and resolved routing does not prove sufficient context or implementation compatibility.

Upgrading from 0.4.2 refreshes four managed workspace schemas and the consumer reference in both minimal and agent profiles. Review init --dry-run and init --check with the existing profile, reconcile local modifications, then run ordinary init without blanket --force. Project documents, IDs, local policy and configuration remain project-owned. Repository IDs, manifests and bindings require manual opt-in; init does not discover neighboring repositories. Exact commands and rollback are in “Migration 0.4.2 To 0.5.0” in the packaged ai_docs_toolkit/docs/agent-installation.md.

Verification includes installed CLI/MCP and upgrade matrices plus a bounded HAM documentation evaluation. Its accepted result retains native-format validation findings; it is not a full HAM migration or service runtime check.

Release 0.4.2

The package now declares the MIT license in its metadata and includes the full license text in source and wheel distributions. Repository and package guidance reflects the current release and planning state. CLI behavior, schemas, templates, configuration and MCP surfaces are unchanged from 0.4.1. Source builds without build isolation require setuptools 77 or newer for SPDX license metadata; normal isolated builds install the declared requirement.

No consumer data or managed-file migration is required. After upgrading, verify the version, run ai-docs validate --json, and retain independent project checks. The packaged ai_docs_toolkit/docs/agent-installation.md contains the complete 0.4.1 to 0.4.2 upgrade instructions.

Release 0.4.1

Impact now includes test cases explicitly linked to a module, including modules selected from changed code through cascade.module_ownership. Both incoming related.modules and outgoing related.test_cases links work. Test cases remain terminal review candidates; output fields and exit codes are unchanged.

No schema, configuration or managed-template content migration is required from 0.4.0. Upgrade the package, reconnect MCP clients, rerun impact discovery and review newly included candidates before reusing saved evidence. Preserve project files, IDs, local rules and historical review rounds. See “Migration 0.4.0 To 0.4.1” in ai_docs_toolkit/docs/agent-installation.md for commands and rollback.

Release 0.4.0

ai-docs code-links-check FILE... --format json checks documentation paths and primary IDs in real Python comments without importing code or changing files. Explicit files, repository boundaries and unverified inputs remain visible; strings/docstrings are ignored and links remain optional. Semantic agreement between documentation, comments, implementation and tests still requires review. The command does not add a gate to ordinary validation or new graph edges.

After upgrading from 0.3.3, inspect init --check and --dry-run, then refresh the existing authoring reference with init. Preserve local rules, project documents and review history; no schema or bulk annotation migration is required. Minimal profile needs no reference refresh. See “Migration 0.3.3 To 0.4.0” in the packaged ai_docs_toolkit/docs/agent-installation.md for commands, checks and rollback.

Release 0.3.3

Documentation change review now traces material requirements to test inputs and specific assertions. Review depth depends on impact and uncertainty; a concrete risk of masked violations calls for a focused check within existing authority. For a deliberate weakening, verify that the test fails for the intended reason against the altered code. Preserve limitations and historical evidence. The code-link convention points to this rule. No universal mutation-testing requirement, CLI/schema change or mandatory CI gate is introduced.

After upgrading from 0.3.2, inspect ai-docs init --check and --dry-run, reconcile local policy and run ai-docs init to refresh two existing agent references: documentation change review and documentation cascade authoring. Existing project files and AGENTS.md are preserved. Minimal-profile consumers need no reference refresh; managed provenance records the new version. Verify validation, doctor, init state and project-specific checks. See “Migration 0.3.2 To 0.3.3” in the packaged ai_docs_toolkit/docs/agent-installation.md for commands and rollback.

Release 0.3.2

An optional comment convention links key operations and structures to their documentation through a short explanation, document ID and a path from the Git repository root. Documentation remains primary; file/ID checks do not prove semantic consistency or full implementation of the linked document. Review the document, comment, implementation and applicable tests before committing changes. This adds no parser, mandatory annotation or CI gate.

After upgrading from 0.3.1, inspect ai-docs init --check and --dry-run, reconcile local policy and refresh the agent profile with ai-docs init. Two managed references change: documentation cascade authoring and documentation change review. Existing AGENTS.md is preserved; manually merge its optional pointer if useful. Minimal-profile projects require no reference refresh. Preserve local rules, project documents and historical review rounds; verify the version, validation, doctor, init state and project checks. See “Migration 0.3.1 To 0.3.2” in the packaged ai_docs_toolkit/docs/agent-installation.md for exact commands and rollback.

Release 0.3.1

The package installation guide now describes preserving review/evidence before revert and verifying the restored files and environment. See ai_docs_toolkit/docs/agent-installation.md, “Rollback Verification”. The patch requires no managed-file refresh, schema or project-data migration from 0.3.0. After installation, verify the version, run ai-docs validate --json, ai-docs doctor --format json, ai-docs init --check, and the project's checks. Preserve historical review rounds: the version change causes tool_changed findings even when project files are unchanged. See “Migration 0.3.0 To 0.3.1” in the packaged guide for installation and verification commands.

Release 0.3.0

Impact now reaches explicitly linked test cases from business rules, scenarios and acceptance criteria. Test cases end traversal. Changed-mode JSON adds a coverage object with path counts and unmapped reasons; strict JSON clients must accept that field. Explicit-id output keeps its shape. Coverage describes discovery and does not establish semantic completeness or successful tests.

The optional ai-docs review-check RECORD --format json command compares a saved YAML review with current input hashes, tool identity, impact candidates and decisions. It supports YAML files and fenced YAML in Markdown. It is read-only; exit 0 means no mechanical discrepancy, not review approval. Git discovery preserves literal Unicode/whitespace paths and rename/deletion evidence. Existing CLI/MCP entrypoints and independent project gates remain.

After upgrading from 0.2.0, review ai-docs init --check and ai-docs init --dry-run, reconcile local overrides, then refresh the existing managed review skill/reference with ai-docs init. Run project validation and representative impact checks. No schema, id, layout or mandatory review-record migration is required. Preserve historical review evidence; a new tool identity requires a new reviewed round instead of silently rewriting previous evidence.

See the packaged ai_docs_toolkit/docs/agent-installation.md, “Migration 0.2.0 To 0.3.0”, for commands, preservation rules and rollback. Consumers on 0.1.0 must also apply the Python/archive prerequisites below.

Earlier Stable 0.2.0

Completed task files are retained as execution history. Standalone tasks are archived after closure; tasks in a plan stay in place with status done until the complete plan, including its stages and execution material, is archived. Archive moves preserve task ids and update registry paths. This policy replaces the completed-task deletion guidance from beta 16.

Python 3.14+ is now required; 0.1.0 supported Python 3.11+. Recreate older environments before upgrading. After installation, review ai-docs init --check and ai-docs init --dry-run, reconcile local policy, then run ai-docs init and ai-docs validate. Refreshing instructions does not move project-owned task files. Existing archives and retired ids remain valid; no schema migration or restoration of deleted tasks is required.

See the packaged ai_docs_toolkit/docs/agent-installation.md, “Migration 0.1.0 To 0.2.0”, for exact install, preservation and rollback steps.

Earlier Stable 0.1.0

This release completes the 0.1.0 beta series. Small edits and short bounded work can use sufficient session context; task records remain available when durable continuation, handoff or project policy requires them. Agent instructions are in English and were reviewed for compactness. Existing assignments carry across technical steps, and significant work includes a proportionate retrospective.

Context excludes archived history by default, supports an optional body budget and configurable traversal depth, and explains selection, exclusions and gaps. The budget is off by default; required documents remain whole on overflow. Strict JSON consumers must accept the added context metadata. CLI/MCP names and existing task/document ids are preserved.

When upgrading from 0.1.0b25, review ai-docs init --dry-run and ai-docs init --check, resolve modified managed files, then run ai-docs init. Existing AGENTS.md, config and local policy require a deliberate merge where applicable; keep project checks and restart MCP clients. Validate the project and inspect representative context output. See the packaged ai_docs_toolkit/docs/agent-installation.md, “Integrated Consumer Migration”, for commands, preservation rules and rollback. No bulk task/schema migration is required.

Compatibility was checked with five synthetic consumer profiles. Agent behavior was observed on one runtime; these checks do not establish universal performance improvements or real consumer pilot coverage.

Earlier Beta Changes

Beta 12 excludes Markdown documents under work_history.archive_root from ai-docs validate checks while retaining successfully parsed archive ids for active-document relationship resolution. Validation summaries include archived_documents_excluded. Set work_history.archive_root: null to retain the previous validate-all behavior.

Beta 13 updates toolkit-managed agent instructions so agents proactively report blocking decisions, safe non-blocking defaults and implementation proposals. Existing projects should follow the packaged .ai-docs/templates/release/decision-visibility-beta-13.md migration note.

Beta 14 adds explicit code-to-module ownership mapping for ai-docs impact --changed, plus --base REF support for clean CI checkouts. Existing projects should follow the packaged .ai-docs/templates/release/cascade-impact-beta-14.md migration note.

Beta 15 restores the toolkit update route alongside the cascade adoption route in the managed agent-profile skill index. Existing projects should follow the packaged .ai-docs/templates/release/routing-restoration-beta-15.md migration note.

Beta 16 introduced pathless registry entries for retired task ids. Version 0.2.0 replaces its completed-task deletion guidance with archive retention; existing retired ids remain reserved.

Beta 17 reconciles incoming request storage under canonical ai-docs/requests/, packages the referenced incoming request model and adds safe migration guidance for records created under legacy docs/requests/. Existing projects should follow the packaged .ai-docs/templates/release/incoming-request-storage-beta-17.md migration note.

Beta 19 bounds doctor Markdown discovery to project documentation roots, skips symlinked files and tolerates entries removed during traversal. Existing projects should follow .ai-docs/templates/release/doctor-filesystem-traversal-beta-19.md.

Beta 20 adds stable JSON output for ai-docs doctor, exposes the same contract through the read-only ai_docs_doctor MCP tool and records managed-file provenance in .ai-docs/managed-files.json. Existing projects should follow .ai-docs/templates/release/doctor-json-provenance-beta-20.md and reconnect long-lived MCP processes after upgrading.

Beta 21 adds the toolkit-managed documentation-change-review skill and its normative reference contract. Existing projects should follow .ai-docs/templates/release/documentation-change-review-beta-21.md and review managed-file changes before refreshing the agent profile.

Beta 22 adds the toolkit-managed incoming-request-triage skill, its normative contract and safe composition with the existing request/planning lifecycle. Existing projects should follow .ai-docs/templates/release/incoming-request-triage-beta-22.md and review managed-file changes before refreshing the agent profile.

Beta 23 adds the toolkit-managed documentation-cascade-authoring skill and its normative contract for authorized, top-down documentation changes. Existing projects should follow .ai-docs/templates/release/documentation-cascade-authoring-beta-23.md and review managed-file changes before refreshing the agent profile.

Beta 24 moves the optional MCP runtime to the stable Python MCP SDK 2.x line with dependency range mcp>=2,<3. Existing MCP tool/resource names and stdio entrypoints remain unchanged. Consumers upgrading from beta 23 should reinstall the MCP extra and reconnect every long-lived MCP client before verification.

Beta 25 preserves printable Unicode characters when toolkit operations rewrite Markdown YAML front matter. Planning lifecycle commands, task registry updates and Azure DevOps write-back no longer replace readable non-ASCII text with \uXXXX escape sequences. No manual migration is required.

Quick Start

Bootstrap a repository for AI Docs Toolkit:

ai-docs init
ai-docs validate

For a documentation-only bootstrap without AGENTS.md:

ai-docs init --profile minimal

The command creates missing toolkit files and skips existing files by default. Use --force only when you explicitly want to overwrite toolkit-owned target files.

Validate a configured project:

ai-docs validate

Generate machine-readable validation output:

ai-docs validate --json

Build a document graph:

ai-docs graph --format json

Analyze impact for changed files:

ai-docs impact --changed

Check optional saved review evidence:

ai-docs review-check review.yaml --format json

Check existing documentation links in selected Python files:

ai-docs code-links-check src/example.py --format json

Prepare an agent context bundle for changed files:

ai-docs context --changed

Repository Bootstrap

Repository bootstrap is an explicit command. Package installation does not modify project files.

Default agent-oriented bootstrap:

ai-docs init

Minimal bootstrap:

ai-docs init --profile minimal

The source repository may be private or unavailable to agents in consuming projects. Package usage does not require access to repository-local documentation files.

AI Agent Instructions

The package includes an agent-readable instruction document for install, update, bootstrap, validation and context commands.

Give this short instruction to an agent that can inspect installed package resources:

Install `ai-docs-toolkit`, then configure this repository by following the packaged instructions in `ai_docs_toolkit/docs/agent-installation.md`.

After installation, an agent can locate it with:

python -c "from importlib import resources; print(resources.files('ai_docs_toolkit').joinpath('docs/agent-installation.md'))"

Operators can give the prompt from that document to an AI agent when asking it to install or update the toolkit in a consuming repository.

Development

Versions 0.2.0 and later require Python 3.14+. Earlier published releases retain their original Python requirements. Recreate older environments with Python 3.14+ before upgrading.

Source checkout development install:

python -m pip install -e ".[dev]"
ai-docs --version
ai-docs validate

Current CI/source checkout install contract:

python -m pip install -e .
ai-docs validate --json

License

AI Docs Toolkit is licensed under the MIT License. The full license text is included in the package distributions.

Release 0.10.0

Existing layouts can opt in to explicit module parents and document owners. Navigation files and declared workspace documentation links can be checked without requiring native frontmatter. Context reports include body-size/category diagnostics and non-blocking history/closed-plan advisories. Graph defaults remain unchanged. Follow “Migration 0.9.0 To 0.10.0” in the packaged agent-installation guide.

Release 0.11.0

ai-docs check and the read-only ai_docs_check MCP tool combine native validation, all registered documentation/navigation links and optional declarative context expectations. Configure stable required/excluded/historical document IDs; body sizes remain diagnostic. boilerplate_advisories: true reports known template paragraphs without failing the gate. Code examples and historical knowledge are excluded from that advisory check. See Migration 0.10.0 To 0.11.0 in the packaged agent-installation guide for opt-in configuration and managed reference refresh.

Optional task measurements

Version0.18.0 adds measure for explicit TASK binding, private immutable execution markers and bounded Codex metadata summaries. Installation is opt-out; optional hooks/MCP mutation tools require separate activation. See packaged agent migration instructions. Existing projects and the default read-only MCP remain compatible.