ai-docs-toolkit 0.1.0b1

AI-oriented documentation toolkit.

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:

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

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

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 for supported and deferred channels.

Quick Start

Validate this repository:

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

Documentation Map

Start here:

• Vision
• Documentation as Interface
• Document Taxonomy
• Change Cascade
• Planning as Execution Interface

Architecture:

• Repository Structure
• Schemas and Templates
• CLI Architecture

Planning:

• MVP Plan
• Backlog

Workflows:

• Plan Stage Workflow

Reference:

• Document Types
• Front Matter Fields
• Planning Document Model
• Source Of Truth Model
• Test Case Documentation
• Distribution Strategy
• CI And Agent Integration

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

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
• MVP Plan

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.