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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ai-docs-toolkit
-Version: 0.3.0
+Version: 0.3.2
 Summary: AI-oriented documentation toolkit.
 Requires-Python: >=3.14
 Description-Content-Type: text/markdown
@@ -30,41 +30,72 @@ The core idea is that documentation should not be a secondary artifact created a
 
 ## Current Status
 
-Version 0.3.0 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.
 
 ## Installation
 
-Install the stable release with Python 3.14 or newer:
+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.0
+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.0 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.0"
+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
+revert and verifying the restored files and environment. See
+`ai_docs_toolkit/docs/agent-installation.md`, “Rollback Verification”.
+The patch requires no managed-file refresh, schema or project-data migration
+from 0.3.0. After installation, verify the version, run `ai-docs validate --json`,
+`ai-docs doctor --format json`, `ai-docs init --check`, and the project's checks.
+Preserve historical review rounds: the version change causes `tool_changed`
+findings even when project files are unchanged. See “Migration 0.3.0 To 0.3.1”
+in the packaged guide for installation and verification commands.
+
 ## Release 0.3.0
 
 Impact now reaches explicitly linked test cases from business rules, scenarios

{ai_docs_toolkit-0.3.0 → 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.0 adds linked test cases to impact, changed-path coverage and optional review evidence checks. 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,14 +83,32 @@ pipx install ai-docs-toolkit
 uvx --from ai-docs-toolkit ai-docs validate
 ```
 
-For upgrades to 0.3.0, follow the [consumer migration guide](src/ai_docs_toolkit/docs/agent-installation.md#migration-020-to-030).
+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.1.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).
 Use Python 3.14+, review managed-file changes and preserve existing project rules
 and task records before refreshing. Completed standalone tasks are archived;
 tasks in a plan remain in place until the whole plan is archived.
 
+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. [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.0 → ai_docs_toolkit-0.3.2}/packaging/pypi/README.md

@@ -16,41 +16,72 @@ The core idea is that documentation should not be a secondary artifact created a
 
 ## Current Status
 
-Version 0.3.0 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.
 
 ## Installation
 
-Install the stable release with Python 3.14 or newer:
+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.0
+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.0 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.0"
+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
+revert and verifying the restored files and environment. See
+`ai_docs_toolkit/docs/agent-installation.md`, “Rollback Verification”.
+The patch requires no managed-file refresh, schema or project-data migration
+from 0.3.0. After installation, verify the version, run `ai-docs validate --json`,
+`ai-docs doctor --format json`, `ai-docs init --check`, and the project's checks.
+Preserve historical review rounds: the version change causes `tool_changed`
+findings even when project files are unchanged. See “Migration 0.3.0 To 0.3.1”
+in the packaged guide for installation and verification commands.
+
 ## Release 0.3.0
 
 Impact now reaches explicitly linked test cases from business rules, scenarios

{ai_docs_toolkit-0.3.0 → 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.0"
+version = "0.3.2"
 description = "AI-oriented documentation toolkit."
 readme = "packaging/pypi/README.md"
 requires-python = ">=3.14"

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

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

{ai_docs_toolkit-0.3.0 → 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.0"
+python -m pip install "ai-docs-toolkit==0.3.2"
 ai-docs --version
 ```
 
@@ -89,6 +89,135 @@ 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
+changes the package version. No managed-file refresh, schema, layout or
+project-data migration is required from 0.3.0; Python 3.14+ remains required.
+Consumers on older versions must also apply the relevant migration sections
+below. Install the exact version only once it is available on the selected index.
+
+Record `ai-docs --version`, `ai-docs doctor --format json`, `ai-docs init --check`
+and existing validation findings before upgrading. Preserve project files,
+local rules, ids, links, registry paths, archives and saved review evidence.
+Use the project's existing installer:
+
+```bash
+python --version
+python -m pip install --upgrade "ai-docs-toolkit==0.3.1"
+# MCP users install the complete extra instead:
+python -m pip install --upgrade "ai-docs-toolkit[mcp]==0.3.1"
+# Isolated CLI alternatives:
+pipx install --force --python python3.14 "ai-docs-toolkit==0.3.1"
+uvx --python 3.14 --from ai-docs-toolkit==0.3.1 ai-docs --version
+```
+
+Reconnect long-lived MCP clients. Run verification with the upgraded runtime
+and, for `pip check`, in the environment that owns the installed package:
+
+```bash
+ai-docs --version
+ai-docs validate --json
+ai-docs doctor --format json
+ai-docs init --check
+python -m pip check
+```
+
+Expect version 0.3.1, successful validation and no new doctor or managed-file
+findings. Review existing drift separately; do not force an init refresh to
+clear it. Keep independent project tests and review gates. Stop for owner
+review on new validation errors or unresolved local-policy conflicts.
+
+If a saved review exists, run `ai-docs review-check <record-path> --format json`.
+The version change alters checker identity and causes `tool_changed` findings
+for a 0.3.0 record even when its inputs are unchanged. Preserve the old round;
+create a new round only after reviewing current inputs, candidates and decisions.
+Do not rewrite historical tool identity or hashes merely to clear findings.
+
+For rollback, follow [Rollback Verification](#rollback-verification), including
+preserving the applicable instructions and evidence before reverting files.
+
 ## Migration 0.1.0 To 0.2.0
 
 From: `0.1.0`. To: `0.2.0`. Older installations should also review the applicable
@@ -151,10 +280,9 @@ before continuing. Independent project checks still apply.
 
 Follow “Consumer Migration: Task Archive Retention” in the installed
 `.ai-docs/reference/planning-document-model.md` for subsequent archive operations.
-For rollback, restore reviewed policy files and the managed manifest together,
-reinstall the previously recorded package/environment, and preserve retained
-planning records. Package rollback does not reverse archive moves or external
-effects. Keep package versions and artifact hashes with the migration evidence.
+For rollback, follow [Rollback Verification](#rollback-verification) and preserve
+retained planning records. Package rollback does not reverse archive moves or
+external effects.
 
 ## Migration 0.2.0 To 0.3.0
 
@@ -219,12 +347,9 @@ about an older tool are expected and need review, not automatic evidence edits.
 Keep independent project tests/review gates. Stop for owner review on unmanaged
 rewrites, unresolved local-policy conflicts or new validation errors.
 
-For rollback, restore reviewed managed files and their manifest together,
-reinstall the recorded previous package/environment and reconnect MCP clients.
-Keep project ids, links, task history and review rounds. An executable downgrade
-does not reverse manual edits or external effects; consumers using the new CLI
-or JSON field must also revert that integration. Record package/artifact hashes
-and validation results with the upgrade evidence.
+For rollback, follow [Rollback Verification](#rollback-verification). Consumers
+using the new CLI or JSON field must also revert that integration. Keep historical
+review rounds; an older version may lack `review-check` or linked test-case impact.
 
 ### Optional Review Evidence (0.3.0)
 
@@ -631,8 +756,45 @@ and transitive-path fields. Repeat init and confirm no further managed changes.
 Preserve independent project checks; toolkit validation does not replace them.
 Investigate new errors or conflicts outside this refresh before continuing.
 
-To roll back this documentation refresh, restore the reviewed project files and
-managed manifest together and reinstall the previously recorded package version.
-Do not restore unrelated user changes or treat package rollback as reversal of
-external application effects. Keep old/new package hashes with migration evidence:
-an unchanged development version string alone does not identify the build.
+To roll back this documentation refresh, follow
+[Rollback Verification](#rollback-verification). An unchanged development version
+string alone does not identify the build; retain old/new package artifact hashes.
+
+## Rollback Verification
+
+Use this sequence for an authorized rollback of the reviewed migration scope.
+For a rehearsal, use a separate repository copy and environment.
+
+1. Before reverting files or downgrading the package, preserve review rounds,
+   execution evidence and the applicable rollback instructions outside the paths
+   being restored. A whole-commit `git revert` can remove newly added review files
+   from the working tree. Verify the preserved copies and keep durable evidence
+   in Git or another project-approved location, beyond temporary logs.
+2. Restore the reviewed files and `.ai-docs/managed-files.json` together, reinstall
+   the recorded previous package/environment with the project installer, and
+   reconnect long-lived MCP clients if used. Preserve ids, links, task history,
+   local policy and unrelated work. Review conflicts before continuing; a package
+   downgrade does not undo manual edits, archive moves or external effects.
+3. Using the restored project's interpreter and CLI, run:
+
+   ```bash
+   python --version
+   ai-docs --version
+   ai-docs validate --json
+   ai-docs doctor --format json
+   ai-docs init --check
+   python -m pip check
+   ```
+
+   Confirm the intended version, successful validation, no unexpected doctor
+   findings and no outstanding managed refresh. Compare restored files with the
+   recorded baseline within the rollback scope; verify retained history and
+   evidence separately. Keep applicable project checks and existing findings.
+   Record unsupported checks and expected lost capabilities of the older version;
+   preserving a review record does not make its decisions current.
+4. Record the baseline and restored commit/tree or file hashes, actual Python,
+   package and dependency versions (for pip, `python -m pip freeze --all`), hashes
+   of artifacts actually used, commands, results and remaining gaps in the existing
+   migration record. Fresh dependency resolution may differ from the historical
+   environment. Report functional recovery separately from exact reconstruction;
+   newly collected hashes cannot attest a previous installation retroactively.

{ai_docs_toolkit-0.3.0 → 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.0 → 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.0 → 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.0 → 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.0
+Version: 0.3.2
 Summary: AI-oriented documentation toolkit.
 Requires-Python: >=3.14
 Description-Content-Type: text/markdown
@@ -30,41 +30,72 @@ The core idea is that documentation should not be a secondary artifact created a
 
 ## Current Status
 
-Version 0.3.0 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.
 
 ## Installation
 
-Install the stable release with Python 3.14 or newer:
+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.0
+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.0 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.0"
+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
+revert and verifying the restored files and environment. See
+`ai_docs_toolkit/docs/agent-installation.md`, “Rollback Verification”.
+The patch requires no managed-file refresh, schema or project-data migration
+from 0.3.0. After installation, verify the version, run `ai-docs validate --json`,
+`ai-docs doctor --format json`, `ai-docs init --check`, and the project's checks.
+Preserve historical review rounds: the version change causes `tool_changed`
+findings even when project files are unchanged. See “Migration 0.3.0 To 0.3.1”
+in the packaged guide for installation and verification commands.
+
 ## Release 0.3.0
 
 Impact now reaches explicitly linked test cases from business rules, scenarios

{ai_docs_toolkit-0.3.0 → 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.0" 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.0"
+    assert output.out.strip() == "0.3.2"
     assert output.err == ""