Metadata-Version: 2.4
Name: ai-docs-toolkit
Version: 0.1.0b1
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<2,>=1.27; 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. 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.

## Use Cases

AI Docs Toolkit is being designed to support:
- 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 repository has completed the local MVP loop:
- typed Markdown documents with YAML front matter;
- schema and structure validation;
- document graph output;
- impact analysis;
- context bundle output;
- 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
```

Published package commands are documented as contracts for after a package release exists:

```bash
python -m pip install ai-docs-toolkit
pipx install ai-docs-toolkit
uvx ai-docs-toolkit ai-docs validate
```

Docker, npm/npx and standalone binary distribution are deferred.
See [Distribution Strategy](docs/reference/distribution-strategy.md) for supported and deferred channels.

## Quick Start

Validate this repository:

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

## Documentation Map

Start here:
- [Vision](docs/concepts/vision.md)
- [Documentation as Interface](docs/concepts/documentation-as-interface.md)
- [Document Taxonomy](docs/concepts/document-taxonomy.md)
- [Change Cascade](docs/concepts/change-cascade.md)
- [Planning as Execution Interface](docs/concepts/planning-as-execution-interface.md)

Architecture:
- [Repository Structure](docs/architecture/repository-structure.md)
- [Schemas and Templates](docs/architecture/schemas-and-templates.md)
- [CLI Architecture](docs/architecture/cli-architecture.md)

Planning:
- [MVP Plan](docs/planning/2026-05-13-mvp/plan.md)
- [Backlog](docs/planning/backlog.md)

Workflows:
- [Plan Stage Workflow](docs/workflows/plan-stage-workflow.md)

Reference:
- [Document Types](docs/reference/document-types.md)
- [Front Matter Fields](docs/reference/frontmatter-fields.md)
- [Planning Document Model](docs/reference/planning-document-model.md)
- [Source Of Truth Model](docs/reference/source-of-truth-model.md)
- [Test Case Documentation](docs/reference/test-case-documentation.md)
- [Distribution Strategy](docs/reference/distribution-strategy.md)
- [CI And Agent Integration](docs/reference/ci-agent-integration.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](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](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](docs/planning/2026-05-15-post-mvp-hardening/plan.md)
- [MVP Plan](docs/planning/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](docs/planning/backlog/task-000009-product-core-documentation-gaps.md).
