ai-docs-toolkit 0.1.0__tar.gz

ai_docs_toolkit-0.1.0/PKG-INFO

@@ -0,0 +1,269 @@
+Metadata-Version: 2.4
+Name: ai-docs-toolkit
+Version: 0.1.0
+Summary: AI-oriented documentation toolkit.
+Requires-Python: >=3.11
+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
+
+The stable 0.1.0 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 stable release:
+
+```bash
+python -m pip install ai-docs-toolkit==0.1.0
+ai-docs --version
+```
+
+For ephemeral execution with `uvx`:
+
+```bash
+uvx --from ai-docs-toolkit==0.1.0 ai-docs --version
+```
+
+For the optional local MCP runtime:
+
+```bash
+python -m pip install "ai-docs-toolkit[mcp]==0.1.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.
+
+## 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 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.
+
+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
+```
+
+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
+
+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.

ai_docs_toolkit-0.1.0/README.md

@@ -0,0 +1,203 @@
+# 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. Version 0.1.0 is the first stable release after the beta series.
+
+## 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.
+
+## Use Cases
+
+AI Docs Toolkit supports:
+- typed Markdown documents with YAML front matter;
+- document taxonomy and explicit relationships;
+- validation of metadata, required sections and links;
+- document graph construction;
+- impact analysis for planned and actual changes;
+- context bundles for AI agents;
+- CI, pre-commit and agent workflow integrations.
+
+## Current Status
+
+The stable package provides:
+- typed Markdown documents with YAML front matter;
+- schema and structure validation;
+- document graph output;
+- impact analysis;
+- context selection with history filtering, optional body budgets and configurable depth;
+- proportionate agent workflows and optional MCP integration;
+- CI, pre-commit and agent workflow examples.
+
+At this stage the repository contains:
+- concept documents that explain the methodology;
+- architecture and reference documents for repository structure, schemas, CLI, graph, impact, context, CI and distribution;
+- planning documents that define active post-MVP hardening work;
+- a workflow for implementing plan stages as documented change units;
+- YAML schemas for MVP front matter and document types;
+- Markdown document templates and a minimal project example;
+- Python package baseline and an executable `ai-docs` CLI.
+
+## Installation
+
+Current supported local development install from a source checkout:
+
+```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
+```
+
+For a consuming project using an installed package:
+
+```bash
+python -m pip install ai-docs-toolkit
+ai-docs init
+ai-docs validate
+```
+
+Install the stable package from Public PyPI with your preferred tool:
+
+```bash
+python -m pip install ai-docs-toolkit
+pipx install ai-docs-toolkit
+uvx --from ai-docs-toolkit ai-docs validate
+```
+
+For upgrades from beta 25, follow the [consumer migration guide](src/ai_docs_toolkit/docs/agent-installation.md#integrated-consumer-migration-010).
+Review managed-file changes and preserve existing project rules before refreshing.
+
+Docker, npm/npx and standalone binary distribution are deferred.
+See [Distribution Strategy](.ai-docs/reference/distribution-strategy.md) for supported and deferred channels.
+
+## Quick Start
+
+Validate this repository:
+
+```bash
+ai-docs validate
+```
+
+Bootstrap a consuming project after installing the package:
+
+```bash
+ai-docs init
+ai-docs validate
+```
+
+For an AI agent installing the package in a consuming project, use the packaged instruction document:
+
+```bash
+python -c "from importlib import resources; print(resources.files('ai_docs_toolkit').joinpath('docs/agent-installation.md'))"
+```
+
+The packaged instruction document also includes JetBrains MCP setup steps for both manual setup and agent-assisted setup.
+
+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
+ai-docs impact --changed --base <git-ref> --format json
+```
+
+Projects can opt in to code-to-document impact through `cascade.root_module` and `cascade.module_ownership` in `ai-docs.config.yaml`.
+
+Prepare an agent context bundle for changed files:
+
+```bash
+ai-docs context --changed
+```
+
+## Documentation Map
+
+Start here:
+- [Vision](ai-docs/concepts/vision.md)
+- [Documentation as Interface](ai-docs/concepts/documentation-as-interface.md)
+- [Document Taxonomy](ai-docs/concepts/document-taxonomy.md)
+- [Change Cascade](ai-docs/concepts/change-cascade.md)
+- [Planning as Execution Interface](ai-docs/concepts/planning-as-execution-interface.md)
+
+Architecture:
+- [Repository Structure](ai-docs/architecture/repository-structure.md)
+- [Schemas and Templates](ai-docs/architecture/schemas-and-templates.md)
+- [CLI Architecture](ai-docs/architecture/cli-architecture.md)
+
+Planning:
+- [MVP Plan](ai-docs/planning/archive/plans/2026-05-13-mvp/plan.md)
+- [Backlog](ai-docs/planning/backlog.md)
+
+Workflows:
+- [Plan Stage Workflow](.ai-docs/workflows/plan-stage-workflow.md)
+
+Reference:
+- [Document Types](.ai-docs/reference/document-types.md)
+- [Front Matter Fields](.ai-docs/reference/frontmatter-fields.md)
+- [Planning Document Model](.ai-docs/reference/planning-document-model.md)
+- [Source Of Truth Model](.ai-docs/reference/source-of-truth-model.md)
+- [Test Case Documentation](.ai-docs/reference/test-case-documentation.md)
+- [Distribution Strategy](.ai-docs/reference/distribution-strategy.md)
+- [CI And Agent Integration](.ai-docs/reference/ci-agent-integration.md)
+- [Init Command Contract](.ai-docs/reference/init-command-contract.md)
+
+## Development Model
+
+The toolkit is developed using its own documentation methodology.
+
+Changes should be handled as documented change units:
+- identify the active plan stage;
+- read [Plan Stage Workflow](.ai-docs/workflows/plan-stage-workflow.md) before executing planning tasks;
+- read the source documents for the task;
+- update affected documentation before or together with implementation;
+- keep planning documents aligned with the actual repository state;
+- run `ai-docs validate` before closure.
+
+For the current execution workflow, see [Plan Stage Workflow](.ai-docs/workflows/plan-stage-workflow.md).
+
+## Planning Direction
+
+The MVP plan is closed and retained as work history.
+Current work is tracked in the post-MVP hardening plan.
+
+Details:
+- [Post-MVP Hardening Plan](ai-docs/planning/archive/plans/2026-05-15-post-mvp-hardening/plan.md)
+- [MVP Plan](ai-docs/planning/archive/plans/2026-05-13-mvp/plan.md)
+
+## Non-Goals For MVP
+
+The MVP does not aim to provide:
+- semantic contradiction detection;
+- automatic documentation rewriting;
+- full IDE plugins;
+- hosted services;
+- database-backed graph storage;
+- cross-repository dependency graphs.
+
+## License
+
+License is not selected yet. This is tracked as a product documentation gap in [BLG-017 Product Core Documentation Gaps](ai-docs/planning/backlog/task-000009-product-core-documentation-gaps.md).