ai-docs-toolkit 0.3.1__tar.gz → 0.3.2__tar.gz

{ai_docs_toolkit-0.3.1 → ai_docs_toolkit-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ai-docs-toolkit
-Version: 0.3.1
+Version: 0.3.2
 Summary: AI-oriented documentation toolkit.
 Requires-Python: >=3.14
 Description-Content-Type: text/markdown
@@ -30,12 +30,13 @@ The core idea is that documentation should not be a secondary artifact created a
 
 ## Current Status
 
-Version 0.3.1 includes:
+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.
@@ -45,26 +46,44 @@ Version 0.3.1 includes:
 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.1
+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.1 ai-docs --version
+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.1"
+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

{ai_docs_toolkit-0.3.1 → ai_docs_toolkit-0.3.2}/README.md

@@ -2,7 +2,7 @@
 
 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.3.1 clarifies rollback verification, alongside the linked test cases, changed-path coverage and optional review evidence checks introduced in 0.3.0. Python 3.14 or newer is required.
+It treats documentation as an engineering interface between humans, AI agents, code, tests and change management. Version 0.3.2 is prepared with an optional convention for links from key code to its documentation, alongside rollback guidance, linked test cases, changed-path coverage and optional review evidence checks. Python 3.14 or newer is required.
 
 ## Purpose
 
@@ -83,9 +83,11 @@ pipx install ai-docs-toolkit
 uvx --from ai-docs-toolkit ai-docs validate
 ```
 
-For upgrades from 0.3.0 to 0.3.1, follow the [consumer migration guide](src/ai_docs_toolkit/docs/agent-installation.md#migration-030-to-031).
+For upgrades from 0.3.1 to 0.3.2, follow the [consumer migration guide](src/ai_docs_toolkit/docs/agent-installation.md#migration-031-to-032).
 Install the exact version only after it is available on PyPI; a source preparation
-commit does not publish the package. Consumers on 0.2.0 must also apply the
+commit does not publish the package. Consumers on 0.3.0 must also read the
+[0.3.1 migration](src/ai_docs_toolkit/docs/agent-installation.md#migration-030-to-031).
+Consumers on 0.2.0 must also apply the
 [0.3.0 migration](src/ai_docs_toolkit/docs/agent-installation.md#migration-020-to-030);
 consumers on 0.1.0 must also apply the
 [0.2.0 prerequisites](src/ai_docs_toolkit/docs/agent-installation.md#migration-010-to-020).
@@ -93,11 +95,19 @@ Use Python 3.14+, review managed-file changes and preserve existing project rule
 and task records before refreshing. Completed standalone tasks are archived;
 tasks in a plan remain in place until the whole plan is archived.
 
-The 0.3.1 release preparation includes a clarification of
+Version 0.3.2 adds an optional short explanation, document ID and path from the
+Git repository root beside key operations and structures. The
+[canonical convention](.ai-docs/reference/documentation-cascade-authoring-skill.md#optional-code-documentation-links)
+preserves documentation as primary and requires semantic review of existing
+comments. Agent-profile consumers refresh two managed references and may manually
+merge the pointer into their existing AGENTS.md. No parser or mandatory gate is added.
+This version is prepared in source; publication is a separate step.
+
+Version 0.3.1 includes a clarification of
 [rollback verification](src/ai_docs_toolkit/docs/agent-installation.md#rollback-verification):
 preserve review/evidence before revert, then check restored files and the actual
 environment. No managed-file refresh or data migration is required for this
-clarification. Publication is pending; the published 0.3.0 package is unchanged.
+clarification. [Version 0.3.1 is available on Public PyPI](https://pypi.org/project/ai-docs-toolkit/0.3.1/).
 
 Docker, npm/npx and standalone binary distribution are deferred.
 See [Distribution Strategy](.ai-docs/reference/distribution-strategy.md) for supported and deferred channels.

{ai_docs_toolkit-0.3.1 → ai_docs_toolkit-0.3.2}/packaging/pypi/README.md

@@ -16,12 +16,13 @@ The core idea is that documentation should not be a secondary artifact created a
 
 ## Current Status
 
-Version 0.3.1 includes:
+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.
@@ -31,26 +32,44 @@ Version 0.3.1 includes:
 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.1
+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.1 ai-docs --version
+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.1"
+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

{ai_docs_toolkit-0.3.1 → ai_docs_toolkit-0.3.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ai-docs-toolkit"
-version = "0.3.1"
+version = "0.3.2"
 description = "AI-oriented documentation toolkit."
 readme = "packaging/pypi/README.md"
 requires-python = ">=3.14"

{ai_docs_toolkit-0.3.1 → ai_docs_toolkit-0.3.2}/src/ai_docs_toolkit/__init__.py

@@ -1,3 +1,3 @@
 """AI Docs Toolkit package baseline."""
 
-__version__ = "0.3.1"
+__version__ = "0.3.2"

{ai_docs_toolkit-0.3.1 → ai_docs_toolkit-0.3.2}/src/ai_docs_toolkit/docs/agent-installation.md

@@ -47,7 +47,7 @@ ai-docs --version
 Pinned install:
 
 ```bash
-python -m pip install "ai-docs-toolkit==0.3.1"
+python -m pip install "ai-docs-toolkit==0.3.2"
 ai-docs --version
 ```
 
@@ -89,6 +89,87 @@ bulk task deletion is required. Detailed migration and rollback guidance is in
 the installed `.ai-docs/reference/planning-document-model.md`, under
 “Consumer Migration: Proportionate Workflow”.
 
+## Migration 0.3.1 To 0.3.2
+
+From: `0.3.1`. To: `0.3.2`. Install the target version only once it is available
+on the selected index. Python 3.14+ remains required; consumers on older versions
+must also apply the relevant migration sections below.
+
+This patch adds an optional convention for comments beside key code:
+a short explanation, document ID and repository-root-relative path. The rule
+is in `.ai-docs/reference/documentation-cascade-authoring-skill.md`, under
+“Optional Code Documentation Links”; change-review guidance links to that owner.
+
+Before installation, record the current version, validation/doctor findings and
+managed-file state. Preserve project files, ids, links, task registry/archive,
+saved review evidence, local rules and a Git diff or backup of managed policy,
+`.ai-docs/managed-files.json` and `AGENTS.md`.
+The commands below use the agent profile. For a minimal-profile project, add
+`--profile minimal` to each `ai-docs init` command; no reference refresh is needed.
+
+```bash
+python --version
+ai-docs --version
+ai-docs validate --json
+ai-docs doctor --format json
+ai-docs init --check
+```
+
+Use the project's existing installer and update its version pin when applicable:
+
+```bash
+python -m pip install --upgrade "ai-docs-toolkit==0.3.2"
+# MCP users install the complete extra instead:
+python -m pip install --upgrade "ai-docs-toolkit[mcp]==0.3.2"
+# Isolated CLI alternatives:
+pipx install --force --python python3.14 "ai-docs-toolkit==0.3.2"
+uvx --python 3.14 --from ai-docs-toolkit==0.3.2 ai-docs --version
+```
+
+Reconnect long-lived MCP clients. Inspect `ai-docs init --check` and
+`ai-docs init --dry-run` with the upgraded runtime. Agent-profile refresh from
+unmodified 0.3.1 updates exactly two existing managed references:
+
+- `.ai-docs/reference/documentation-cascade-authoring-skill.md`;
+- `.ai-docs/reference/documentation-change-review-skill.md`.
+
+Reconcile local policy changes before `ai-docs init`; stop for owner review on
+unresolved policy conflicts, unexpected project rewrites or new validation errors.
+Do not use blanket `--force`. Refresh also updates managed-file provenance.
+Existing `AGENTS.md` is preserved by default; manually merge this pointer if the
+project adopts the convention:
+
+```markdown
+For optional links from key code to its documentation, use the
+[code-link convention](.ai-docs/reference/documentation-cascade-authoring-skill.md#optional-code-documentation-links).
+```
+
+Preserve `.ai-docs/local/**` and independent project gates. After reconciliation:
+
+```bash
+ai-docs init
+ai-docs --version
+ai-docs validate --json
+ai-docs doctor --format json
+ai-docs init --check
+python -m pip check
+```
+
+Expect version 0.3.2, successful validation and no unexpected doctor or managed
+findings; retain and disposition pre-existing findings. Run project-specific
+tests and `pip check` in the environment that owns the installation.
+If a saved review exists, run `ai-docs review-check <record-path> --format json`.
+The new version changes checker identity; refreshed references can also change
+review inputs. Preserve historical rounds and create a new round only after
+reviewing current inputs, candidates and decisions, rather than rewriting hashes
+or tool identity merely to clear findings.
+
+Existing `Docs:` comments remain compatible. No new managed paths, schema,
+project-data migration, mandatory code annotations or CI gate are added.
+For rollback, use the preserved pre-refresh files/diff and manifest under
+[Rollback Verification](#rollback-verification); package downgrade alone does not
+restore refreshed policy or a manually merged AGENTS pointer.
+
 ## Migration 0.3.0 To 0.3.1
 
 From: `0.3.0`. To: `0.3.1`. This patch clarifies rollback verification and

{ai_docs_toolkit-0.3.1 → ai_docs_toolkit-0.3.2}/src/ai_docs_toolkit/templates/project/.ai-docs/reference/documentation-cascade-authoring-skill.md

@@ -120,6 +120,40 @@ Update indexes, `related.*`, module hierarchy, parent requirements and owners.
 Retain stable ids when moving knowledge; generated artifacts preserve source
 identity and are not edited as canonical originals.
 
+## Optional Code Documentation Links
+
+Use this optional convention where a key operation or structure benefits from
+a direct link to its documented behavior, business scenario or constraint.
+Prefer one or two relevant documents; avoid annotating every helper or repeating
+whole requirements. Keep a short explanation beside the code, followed by its
+document ID and file path. Adapt the comment delimiter and language to the project.
+Example, substituting the project's actual document ID and path:
+
+```python
+# Validate manifest shape before checking semantic constraints.
+# Docs: CON-WORKSPACE-MANIFEST-001 | ai-docs/product/workspace-contract/manifest.md
+```
+
+Paths start at the root of the Git repository containing the source file, not
+at the source directory or a shared workspace containing several repositories.
+Use `/` separators and no leading `/`. A reader can open the file without Toolkit;
+clickable navigation depends on the editor. Moving code within that repository
+keeps the path valid. When moving documentation, retain its ID and update the
+path in affected comments; verify the ID against the destination's front matter.
+
+Documentation remains primary; comments are derived local explanations. Quick
+edits may start from code and comments within the existing assignment. Before
+committing or closing the change, review document → comment → implementation →
+applicable tests and synchronize affected parts. Resolve intent conflicts through
+the existing source-of-truth review; a comment cannot authorize a behavior change.
+
+Check file existence and ID agreement separately from semantic consistency.
+Compare the explanation and actual implementation boundary with the document and
+test evidence; a link does not assert complete implementation of its target.
+These comments are a navigation aid: current Toolkit graph/context/impact and
+validation do not parse them. This convention adds no mandatory annotation,
+parser, decorator or CI gate and does not replace module ownership or review.
+
 ## Conflicts And Validation
 
 Stop dependent writes for conflicting product intent, unknown canonical owners,

{ai_docs_toolkit-0.3.1 → ai_docs_toolkit-0.3.2}/src/ai_docs_toolkit/templates/project/.ai-docs/reference/documentation-change-review-skill.md

@@ -18,6 +18,7 @@ related:
     - REF-CONTEXT-BUNDLE-001
     - REF-IMPACT-ANALYSIS-001
     - REF-SOURCE-OF-TRUTH-MODEL-001
+    - REF-DOCUMENTATION-CASCADE-AUTHORING-SKILL-001
 ai:
   priority: high
   load_when:
@@ -70,6 +71,11 @@ when internal evidence is insufficient. External findings cannot silently replac
 accepted constraints; propose their canonical owner or task context before relying
 on them for implementation. Semantic judgment is not machine proof.
 
+When the scope includes code documentation comments or their targets, apply the
+[optional code-link convention](documentation-cascade-authoring-skill.md#optional-code-documentation-links)
+to their navigation and semantic review. Absence of these optional comments is
+not a finding by itself.
+
 ## Impact And Findings
 
 Give each relevant impacted document a reviewed disposition:

{ai_docs_toolkit-0.3.1 → ai_docs_toolkit-0.3.2}/src/ai_docs_toolkit/templates/project/AGENTS.md

@@ -15,6 +15,9 @@ If implementation and documentation conflict:
 - update the source-of-truth document or the implementation in the same change unit;
 - do not let code silently become the only source of meaning.
 
+For optional links from key code to its documentation, use the
+[code-link convention](.ai-docs/reference/documentation-cascade-authoring-skill.md#optional-code-documentation-links).
+
 ## Documentation Structure
 
 For non-trivial modules or functional blocks, prefer grouping documents in a dedicated folder instead of adding many flat files to a domain root.

{ai_docs_toolkit-0.3.1 → ai_docs_toolkit-0.3.2}/src/ai_docs_toolkit.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ai-docs-toolkit
-Version: 0.3.1
+Version: 0.3.2
 Summary: AI-oriented documentation toolkit.
 Requires-Python: >=3.14
 Description-Content-Type: text/markdown
@@ -30,12 +30,13 @@ The core idea is that documentation should not be a secondary artifact created a
 
 ## Current Status
 
-Version 0.3.1 includes:
+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.
@@ -45,26 +46,44 @@ Version 0.3.1 includes:
 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.1
+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.1 ai-docs --version
+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.1"
+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

{ai_docs_toolkit-0.3.1 → ai_docs_toolkit-0.3.2}/tests/test_cli_baseline.py

@@ -10,7 +10,7 @@ def test_cli_help(capsys):
     assert main(["--help"]) == 0
 
     output = capsys.readouterr()
-    assert "ai-docs 0.3.1" in output.out
+    assert "ai-docs 0.3.2" in output.out
     assert "ai-docs doctor" in output.out
     assert "ai-docs validate" in output.out
     assert "ai-docs validate --json" in output.out
@@ -24,7 +24,7 @@ def test_cli_version(capsys):
     assert main(["--version"]) == 0
 
     output = capsys.readouterr()
-    assert output.out.strip() == "0.3.1"
+    assert output.out.strip() == "0.3.2"
     assert output.err == ""