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. The project is post-MVP and is hardening planning, validation, distribution and integration 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

The published beta package includes:

• schema and structure validation for Markdown documents with YAML front matter;
• document graph output;
• impact analysis;
• context bundle output;
• an executable ai-docs CLI;
• optional local MCP runtime entrypoint.

Installation

Install the published beta package:

python -m pip install ai-docs-toolkit==0.1.0b20
ai-docs --version

For ephemeral execution with uvx:

uvx --from ai-docs-toolkit==0.1.0b20 ai-docs --version

For the optional local MCP runtime:

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

After a stable release exists, package install commands can omit the beta version pin.

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 adds explicit completed-task retirement after current knowledge is transferred to canonical documents. Existing projects should follow the packaged .ai-docs/templates/release/task-retirement-beta-16.md migration note.

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.

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

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

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

License is not selected yet.