Metadata-Version: 2.4
Name: ai-docs-toolkit
Version: 0.3.2
Summary: AI-oriented documentation toolkit.
Requires-Python: >=3.14
Description-Content-Type: text/markdown
Requires-Dist: jsonschema>=4.26
Requires-Dist: PyYAML>=6.0
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"
Provides-Extra: mcp
Requires-Dist: mcp<3,>=2; extra == "mcp"

# 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.3.2 includes:

- schema and structure validation for Markdown documents with YAML front matter;
- 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;
- context bundle output;
- an executable `ai-docs` CLI;
- optional local MCP runtime entrypoint.

## Installation

Install this version with Python 3.14 or newer once it is available on PyPI:

```bash
python -m pip install ai-docs-toolkit==0.3.2
ai-docs --version
```

For ephemeral execution with `uvx`:

```bash
uvx --python 3.14 --from ai-docs-toolkit==0.3.2 ai-docs --version
```

For the optional local MCP runtime:

```bash
python -m pip install "ai-docs-toolkit[mcp]==0.3.2"
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.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:

```bash
ai-docs init
ai-docs validate
```

For a documentation-only bootstrap without `AGENTS.md`:

```bash
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:

```bash
ai-docs validate
```

Generate machine-readable validation output:

```bash
ai-docs validate --json
```

Build a document graph:

```bash
ai-docs graph --format json
```

Analyze impact for changed files:

```bash
ai-docs impact --changed
```

Check optional saved review evidence:

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

Prepare an agent context bundle for changed files:

```bash
ai-docs context --changed
```

## Repository Bootstrap

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

Default agent-oriented bootstrap:

```bash
ai-docs init
```

Minimal bootstrap:

```bash
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:

```text
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:

```bash
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:

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

Current CI/source checkout install contract:

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

## License

License is not selected yet.
