ai-docs-toolkit 0.1.0b1__tar.gz

ai_docs_toolkit-0.1.0b1/PKG-INFO

@@ -0,0 +1,186 @@
+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).

ai_docs_toolkit-0.1.0b1/README.md

@@ -0,0 +1,172 @@
+# 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).

ai_docs_toolkit-0.1.0b1/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["setuptools>=69"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ai-docs-toolkit"
+version = "0.1.0b1"
+description = "AI-oriented documentation toolkit."
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+  "jsonschema>=4.26",
+  "PyYAML>=6.0",
+]
+
+[project.optional-dependencies]
+dev = [
+  "build>=1.2",
+  "pytest>=8.0",
+]
+mcp = [
+  "mcp>=1.27,<2",
+]
+
+[project.scripts]
+ai-docs = "ai_docs_toolkit.cli:main"
+ai-docs-mcp = "ai_docs_toolkit.mcp:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = [
+  "tests",
+]
+pythonpath = [
+  "src",
+]

ai_docs_toolkit-0.1.0b1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

ai_docs_toolkit-0.1.0b1/src/ai_docs_toolkit/__init__.py

@@ -0,0 +1,3 @@
+"""AI Docs Toolkit package baseline."""
+
+__version__ = "0.1.0b1"

ai_docs_toolkit-0.1.0b1/src/ai_docs_toolkit/__main__.py

@@ -0,0 +1,4 @@
+from ai_docs_toolkit.cli import main
+
+
+raise SystemExit(main())

ai_docs_toolkit-0.1.0b1/src/ai_docs_toolkit/cli/__init__.py

@@ -0,0 +1,232 @@
+from ai_docs_toolkit import __version__
+from ai_docs_toolkit.context import (
+    context_project,
+    format_context_json,
+    format_context_markdown,
+)
+from ai_docs_toolkit.graph import GraphFilters, format_graph_json, graph_project
+from ai_docs_toolkit.impact import (
+    format_impact_human,
+    format_impact_json,
+    impact_changed_project,
+    impact_project,
+)
+from ai_docs_toolkit.validation import (
+    format_human_validation_result,
+    format_json_validation_result,
+    validate_project_human,
+)
+
+
+def _help_text() -> str:
+    return "\n".join(
+        [
+            f"ai-docs {__version__}",
+            "",
+            "Usage:",
+            "  ai-docs --help",
+            "  ai-docs --version",
+            "  ai-docs validate",
+            "  ai-docs validate --json",
+            "  ai-docs graph --format json [--type TYPE] [--module MODULE] [--id ID]",
+            "  ai-docs impact (--id ID | --changed) [--format json]",
+            "  ai-docs context (--id ID | --module MODULE | --feature FEATURE | --changed) [--format json]",
+        ]
+    )
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = list(argv) if argv is not None else None
+
+    if args is None:
+        import sys
+
+        args = sys.argv[1:]
+
+    if not args or "--help" in args or "-h" in args:
+        print(_help_text())
+        return 0
+
+    if "--version" in args or "-V" in args:
+        print(__version__)
+        return 0
+
+    if args == ["validate"]:
+        result = validate_project_human(".")
+        print(format_human_validation_result(result))
+        return result.exit_code
+
+    if args == ["validate", "--json"] or args == ["--json", "validate"]:
+        result = validate_project_human(".")
+        print(format_json_validation_result(result))
+        return result.exit_code
+
+    graph_filters = _parse_graph_args(args)
+    if graph_filters is not None:
+        result = graph_project(".", filters=graph_filters)
+        print(format_graph_json(result))
+        return result.exit_code
+
+    impact_args = _parse_impact_args(args)
+    if impact_args is not None:
+        impact_mode, impact_source_ids, impact_format = impact_args
+        result = (
+            impact_changed_project(".")
+            if impact_mode == "changed"
+            else impact_project(impact_source_ids, ".")
+        )
+        print(
+            format_impact_json(result)
+            if impact_format == "json"
+            else format_impact_human(result)
+        )
+        return result.exit_code
+
+    context_args = _parse_context_args(args)
+    if context_args is not None:
+        context_mode, context_value, context_format = context_args
+        result = context_project(mode=context_mode, value=context_value, project_root=".")
+        print(
+            format_context_json(result)
+            if context_format == "json"
+            else format_context_markdown(result)
+        )
+        return result.exit_code
+
+    if args and args[0] == "graph":
+        import sys
+
+        print("Usage: ai-docs graph --format json", file=sys.stderr)
+        return 3
+
+    if args and args[0] == "impact":
+        import sys
+
+        print("Usage: ai-docs impact (--id ID | --changed) [--format json]", file=sys.stderr)
+        return 3
+
+    if args and args[0] == "context":
+        import sys
+
+        print(
+            "Usage: ai-docs context (--id ID | --module MODULE | --feature FEATURE | --changed) [--format json]",
+            file=sys.stderr,
+        )
+        return 3
+
+    import sys
+
+    print(f"Unknown command or option: {' '.join(args)}", file=sys.stderr)
+    print("Run `ai-docs --help` for usage.", file=sys.stderr)
+    return 3
+
+
+def _parse_graph_args(args: list[str]) -> GraphFilters | None:
+    if not args or args[0] != "graph":
+        return None
+
+    values = args[1:]
+    if len(values) < 2 or values[:2] != ["--format", "json"]:
+        return None
+
+    document_type: str | None = None
+    module: str | None = None
+    document_id: str | None = None
+    index = 2
+    while index < len(values):
+        option = values[index]
+        if index + 1 >= len(values):
+            return None
+
+        value = values[index + 1]
+        if option == "--type":
+            document_type = value
+        elif option == "--module":
+            module = value
+        elif option == "--id":
+            document_id = value
+        else:
+            return None
+        index += 2
+
+    return GraphFilters(
+        document_type=document_type,
+        module=module,
+        document_id=document_id,
+    )
+
+
+def _parse_impact_args(args: list[str]) -> tuple[str, tuple[str, ...], str] | None:
+    if not args or args[0] != "impact":
+        return None
+
+    values = args[1:]
+    if len(values) not in (1, 2, 3, 4):
+        return None
+
+    if len(values) == 2 and values[0] == "--id":
+        return ("id", (values[1],), "human")
+
+    if len(values) == 4 and values[0] == "--id" and values[2:] == ["--format", "json"]:
+        return ("id", (values[1],), "json")
+
+    if len(values) == 4 and values[:2] == ["--format", "json"] and values[2] == "--id":
+        return ("id", (values[3],), "json")
+
+    if values == ["--changed", "--format", "json"]:
+        return ("changed", (), "json")
+
+    if values == ["--format", "json", "--changed"]:
+        return ("changed", (), "json")
+
+    if values == ["--changed"]:
+        return ("changed", (), "human")
+
+    return None
+
+
+def _parse_context_args(args: list[str]) -> tuple[str, str, str] | None:
+    if not args or args[0] != "context":
+        return None
+
+    values = args[1:]
+    if len(values) not in (1, 2, 3, 4):
+        return None
+
+    if values == ["--changed"]:
+        return ("changed", "", "markdown")
+
+    if values == ["--changed", "--format", "json"]:
+        return ("changed", "", "json")
+
+    if values == ["--format", "json", "--changed"]:
+        return ("changed", "", "json")
+
+    if len(values) == 2:
+        option, value = values
+        mode = _context_mode(option)
+        if mode is not None and value:
+            return (mode, value, "markdown")
+        return None
+
+    if values[2:] == ["--format", "json"]:
+        mode = _context_mode(values[0])
+        if mode is not None and values[1]:
+            return (mode, values[1], "json")
+
+    if values[:2] == ["--format", "json"]:
+        mode = _context_mode(values[2])
+        if mode is not None and values[3]:
+            return (mode, values[3], "json")
+
+    return None
+
+
+def _context_mode(option: str) -> str | None:
+    if option == "--id":
+        return "id"
+    if option == "--module":
+        return "module"
+    if option == "--feature":
+        return "feature"
+    return None

ai_docs_toolkit-0.1.0b1/src/ai_docs_toolkit/context/__init__.py

@@ -0,0 +1,13 @@
+from ai_docs_toolkit.context.markdown_output import (
+    ContextBuildResult,
+    context_project,
+    format_context_json,
+    format_context_markdown,
+)
+
+__all__ = [
+    "ContextBuildResult",
+    "context_project",
+    "format_context_json",
+    "format_context_markdown",
+]