agent-wiki-cli 2.1.0__tar.gz → 2.3.0__tar.gz

agent_wiki_cli-2.3.0/MANIFEST.in

@@ -0,0 +1,22 @@
+prune examples
+recursive-include examples/plugins/documentation-hooks *.py *.json *.md
+include release_build_backend.py
+include src/llm_wiki_cli/py.typed
+include src/llm_wiki_cli/schemas/llm-wiki-knowledge-v1.schema.json
+include src/llm_wiki_cli/schemas/llm-wiki-knowledge-v2.schema.json
+include src/llm_wiki_cli/schemas/llm-wiki-knowledge-v3.schema.json
+include src/llm_wiki_cli/schemas/llm-wiki-knowledge-v4.schema.json
+include src/llm_wiki_cli/schemas/llm-wiki-knowledge-pack-index-v1.schema.json
+include src/llm_wiki_cli/schemas/llm-wiki-knowledge-pack-index-v2.schema.json
+include src/llm_wiki_cli/schemas/llm-wiki-knowledge-object-v1.schema.json
+include src/llm_wiki_cli/extractors/ts_scripts/package-lock.json
+include docs/standalone-documentation.md
+include docs/wiki-guide.md
+include docs/cli-reference.md
+include docs/automation.md
+include docs/security-model.md
+include docs/native-knowledge-provider.md
+include docs/native-agent-workflow.md
+prune reports
+include src/llm_wiki_cli/schemas/llm-wiki-manifest-v6.schema.json
+include src/llm_wiki_cli/schemas/llm-wiki-manifest-catalog-v1.schema.json

{agent_wiki_cli-2.1.0/src/agent_wiki_cli.egg-info → agent_wiki_cli-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-wiki-cli
-Version: 2.1.0
+Version: 2.3.0
 Summary: CLI tool to maintain hybrid LLM Wikis for multi-language projects.
 Author-email: Denis Sivagin <denissvgn@gmail.com>
 License-Expression: MIT
@@ -45,7 +45,7 @@ and guides that static analysis cannot provide.
 The PyPI package is `agent-wiki-cli`, the command is `llm-wiki`, and the Python
 import package is `llm_wiki_cli`.
 
-[Quick start](#quick-start) · [Command reference](docs/cli-reference.md) ·
+[Quick start](#quick-start) · [Examples](examples/README.md) · [Command reference](docs/cli-reference.md) ·
 [Standalone documentation](docs/standalone-documentation.md)
 
 ## Installation
@@ -93,6 +93,10 @@ llm-wiki lint --strict --src-dir . --wiki-dir docs/llm_wiki --jobs 1
 For an isolated documentation workspace from source or an existing enriched
 wiki, follow the [standalone documentation guide](docs/standalone-documentation.md).
 
+For a small project you can copy and change, try the
+[Python, FastAPI, Go, and plugin tutorials](examples/README.md). They show the
+generated pages, a source edit, and the next sync without requiring a model service.
+
 ## What It Creates
 
 The default `docs/llm_wiki/` contains an index, module and entity pages,
@@ -165,6 +169,8 @@ Use `llm-wiki <command> --help` for available options.
 | [Wiki guide](docs/wiki-guide.md) | Page structure, ownership, source selection, and agent setup |
 | [Standalone documentation](docs/standalone-documentation.md) | An isolated documentation workspace, agent handoffs, and export |
 | [Native knowledge](docs/native-knowledge.md) | Evidence, freshness, durable identity, and read APIs |
+| [Native coding workflow](docs/native-agent-workflow.md) | Explicit task evidence, bounded context, sessions, and resumable handoffs |
+| [Knowledge storage](docs/knowledge-storage.md) | Sharded snapshots, explicit migration, bounded reads, and Git size checks |
 | [Qualified context packets](docs/qualified-context-packets.md) | Validated context handoffs and packet contracts |
 | [Automation](docs/automation.md) | CI integrity, diagnostics, and explicit triggers |
 | [Changelog](CHANGELOG.md) | Release history and compatibility changes |

{agent_wiki_cli-2.1.0 → agent_wiki_cli-2.3.0}/README.md

@@ -8,7 +8,7 @@ and guides that static analysis cannot provide.
 The PyPI package is `agent-wiki-cli`, the command is `llm-wiki`, and the Python
 import package is `llm_wiki_cli`.
 
-[Quick start](#quick-start) · [Command reference](docs/cli-reference.md) ·
+[Quick start](#quick-start) · [Examples](examples/README.md) · [Command reference](docs/cli-reference.md) ·
 [Standalone documentation](docs/standalone-documentation.md)
 
 ## Installation
@@ -56,6 +56,10 @@ llm-wiki lint --strict --src-dir . --wiki-dir docs/llm_wiki --jobs 1
 For an isolated documentation workspace from source or an existing enriched
 wiki, follow the [standalone documentation guide](docs/standalone-documentation.md).
 
+For a small project you can copy and change, try the
+[Python, FastAPI, Go, and plugin tutorials](examples/README.md). They show the
+generated pages, a source edit, and the next sync without requiring a model service.
+
 ## What It Creates
 
 The default `docs/llm_wiki/` contains an index, module and entity pages,
@@ -128,6 +132,8 @@ Use `llm-wiki <command> --help` for available options.
 | [Wiki guide](docs/wiki-guide.md) | Page structure, ownership, source selection, and agent setup |
 | [Standalone documentation](docs/standalone-documentation.md) | An isolated documentation workspace, agent handoffs, and export |
 | [Native knowledge](docs/native-knowledge.md) | Evidence, freshness, durable identity, and read APIs |
+| [Native coding workflow](docs/native-agent-workflow.md) | Explicit task evidence, bounded context, sessions, and resumable handoffs |
+| [Knowledge storage](docs/knowledge-storage.md) | Sharded snapshots, explicit migration, bounded reads, and Git size checks |
 | [Qualified context packets](docs/qualified-context-packets.md) | Validated context handoffs and packet contracts |
 | [Automation](docs/automation.md) | CI integrity, diagnostics, and explicit triggers |
 | [Changelog](CHANGELOG.md) | Release history and compatibility changes |

{agent_wiki_cli-2.1.0 → agent_wiki_cli-2.3.0}/docs/automation.md

@@ -17,6 +17,11 @@ llm-wiki install-ci --action-ref "$RELEASE_COMMIT_SHA" --dry-run
 llm-wiki install-ci --action-ref "$RELEASE_COMMIT_SHA"
 ```
 
+Use the full 40-character commit SHA of a release whose integrity Action supports
+`report-schema: v4`. The installer validates the SHA spelling locally; it does
+not contact GitHub to discover that commit's capabilities. Workflows pinned to
+older Actions require a compatible older installer and wiki snapshot.
+
 The command writes only
 `.github/workflows/llm-wiki-integrity.yml`. Rerunning it with the same inputs is
 an exact no-op, while an older unmodified workflow installed by this command is
@@ -26,7 +31,11 @@ are never modified.
 
 The installed workflow checks out the project without persisted credentials
 and calls the release's reusable full-integrity action with read-only
-permissions. That action installs the CLI from its immutable action checkout,
+permissions. It explicitly sets `report-schema: v4` and
+`comparison-policy: auto`, supporting migrated knowledge while retaining
+conservative comparison for legacy knowledge. These inputs also apply when an
+older unmodified managed workflow is updated. That action installs the CLI from
+its immutable action checkout,
 discovers helper languages through default source-selection discovery (using
 `.llm-wiki/source-selection.json` when present), installs their
 checksum-verified toolchains in runner-temporary storage, and prepares detected
@@ -44,6 +53,30 @@ diagnostics, verifies that the project worktree stayed clean, and uploads a
 fixed, allowlisted set of validation, cache-measurement, and toolchain evidence
 even when validation fails.
 
+When called directly without schema inputs, the full-integrity Action defaults
+to `report-schema: v2` and `comparison-policy: auto`. The generated workflow
+explicitly selects v4; the CLI's unpinned output instead selects v1 for legacy
+knowledge and v4 for migrated knowledge. For migrated knowledge in a custom
+workflow, set `report-schema: v4` and `comparison-policy: auto` together.
+To retain explicit v2 or v3 output for migrated knowledge, set
+`comparison-policy: exact-v1` with the chosen schema.
+V3 retains captured health coverage and producer details in its JSON artifact.
+The integrity policy and worktree requirement remain unchanged.
+The v3 summary separates modeled, comparable, current, incompatible and unmodeled
+concepts. It shows captured producer versions, primary causes and a suggested
+next action. Unmodeled concepts are a coverage limitation; they are not counted
+as current. Legacy reports identify unavailable detail explicitly.
+
+For this CLI repository's own candidate maintenance, the action also accepts
+`maintenance-candidate-sha` with `report-schema: v4` and
+`comparison-policy: analysis-v1`. The action checks the
+installed implementation and committed producer basis, then derives a separate
+policy receipt from the existing integrity report. A frozen source invocation
+also supplies both `maintenance-identity` and `maintenance-source-archive`.
+The receipt binds the candidate, source/wiki scope, selection, snapshot and
+original report bytes. These optional diagnostics do not change the ordinary
+integrity exit policy. Producer alignment alone does not establish freshness.
+
 Installed pull-request workflows fetch full history and supply the fetched
 base and head commits to the same action for advisory change impact. The action
 adds a bounded job summary, up to 50 warning/notice annotations, and
@@ -60,6 +93,34 @@ Installation does not bootstrap or synchronize the wiki, change branch
 protection, install hooks, push commits, or add repository secrets. Those
 remain explicit maintainer actions.
 
+For knowledge carrying analysis compatibility metadata, select `report-schema: v4`.
+Both Actions accept `comparison-policy: auto`, `exact-v1`, or `analysis-v1`.
+Use `exact-v1` when retaining an explicitly older report format. The v4 dashboard
+shows the captured comparison policy alongside exact producer versions and coverage.
+
+### Repository release maintenance
+
+This repository controls its additional release-health prerequisite through
+[`release/knowledge-maintenance.json`](../release/knowledge-maintenance.json):
+
+- `shadow` retains a diagnostic comparison between the derived policy and
+  standalone strict doctor on the same candidate. It adds no release blocker.
+- `required` requires complete, healthy modeled coverage for the actual
+  repository, matching installed implementation and authenticated maintenance
+  evidence. Missing, failed or mismatched evidence prevents release completion.
+  Activation records the reviewed candidate, hosted run/attempt, comparison
+  digest and a composite policy implementation digest. Changes to the classifier,
+  compatibility evaluator, registry or admission wrapper require new proof.
+- `disabled` explicitly disables only this additional prerequisite. Existing
+  integrity and release requirements continue to apply, and the summary records
+  the disabled state.
+
+Refresh a stale committed wiki with the intended installed candidate before
+qualification. Review the sync preview, commit the coherent result, and qualify
+that exact commit. Routine pull-request health remains advisory. The release
+workflow retains `evidence-rd-10` with original maintenance inputs and
+`knowledge-maintenance-verification` with the separate verification result.
+
 ## Git hook retirement
 
 Git hook installation has been removed. After updating the package, run the
@@ -145,6 +206,8 @@ wiki checks, trusted plugin validation, or team-owned review policy.
     source-selection: .llm-wiki/source-selection.json
     strict: "true"
     fail-on: unhealthy
+    report-schema: v4
+    comparison-policy: auto
     evidence-id: default
 ```
 
@@ -153,8 +216,8 @@ mixed snapshots, invalid governance, confirmed stale concepts, and invalid
 verification receipts. Use `fail-on: degraded` when any degraded result must
 block the job. `strict: "true"` also classifies indeterminate or nonsemantic
 source drift as unhealthy. Replace `<FULL_RELEASE_COMMIT_SHA>` with the full
-40-character SHA of the immutable released commit; never use a branch or tag
-for a protected workflow.
+40-character SHA of an immutable released commit supporting v4; never use a
+branch or tag for a protected workflow.
 
 The action installs `agent-wiki-cli` from the same action checkout, so pinning
 the action reference also binds the CLI implementation. Through the same
@@ -162,13 +225,27 @@ default source-selection discovery used by the CLI, it plans and prepares any
 detected TypeScript/JavaScript, Go, Rust, or Haskell extractor helper with the
 release's checksum-verified toolchains; Python extraction needs no helper. It
 then invokes `llm-wiki doctor --format json` and reads only the complete,
-versioned `llm-wiki-doctor/v1` object. The renderer rejects a report when its
-strictness or declared exit code does not match the captured request and
-process status, and it never scrapes human output. Within that schema major,
+versioned doctor object (`llm-wiki-doctor/v4` in the example above). The renderer
+rejects a report when its strictness or declared exit code does not match the captured request and
+process status, and it never scrapes human output. Within the v1 schema major,
 required fields and documented state values remain strict while additive
 object fields are ignored. A wiki that has not been initialized is reported as
 `absent` and fails either threshold.
 
+Without explicit inputs, the dashboard Action defaults to `report-schema: v1`
+(the `llm-wiki-doctor/v1` contract) and `comparison-policy: auto`.
+For migrated knowledge, use the v4/auto inputs
+shown above, or select `comparison-policy: exact-v1` with an older report schema.
+Select `report-schema: v3` for
+detailed JSON coverage, primary concept reason counts and captured producer
+versions. V3 and v4 reject unknown fields in their closed contracts and use a
+`llm-wiki-doctor-dashboard/v2` receipt bound to the report bytes. The default
+report and receipt retain their v1 contracts. These versions preserve the
+configured strictness and failure threshold.
+The v3 dashboard and CLI text show the same captured coverage, old/new producer
+versions and remediation guidance. Optional governance and verification absence
+remain neutral under the default policy.
+
 The action reserves isolated runner-temporary cache, toolchain, and evidence
 paths and uploads only the JSON
 report, a hash-bound dashboard receipt, the extractor plan, and the preparation

{agent_wiki_cli-2.1.0 → agent_wiki_cli-2.3.0}/docs/cli-reference.md

@@ -5,6 +5,10 @@
 Use `llm-wiki <command> --help` for the complete option list. The sections below
 explain command behavior, output contracts, and recovery procedures.
 
+Follow the [runnable examples](../examples/README.md) for a complete Python
+documentation cycle, production FastAPI contracts, Go HTTP analysis, or a custom
+task detector with Mermaid styling.
+
 | Task | Commands |
 |---|---|
 | Set up a wiki | [init](#init), [prepare-extractors](#prepare-extractors), [bootstrap](#bootstrap) |
@@ -338,6 +342,8 @@ execution order. Workflow pages require resolved direct calls into at least
 three other selected project modules; an executable need not meet that threshold.
 When a receiver type and its method are declared in different files, workflow
 entry labels and source paths use the file that defines the method.
+The [Go HTTP example](../examples/go-http/README.md) demonstrates helper
+preparation, cross-file handlers, package calls, and sync after a method rename.
 Haskell file entries are additive under `llm-wiki-extract/v1`. A Haskell entry
 uses `language: "haskell"`, `imports`, `classes`, and `functions`, with `module`
 present when the source declares one. Import records use `module`, `qualified`,
@@ -599,7 +605,7 @@ llm-wiki ci-check --helper-cache-dir .cache/llm-wiki-helpers --src-dir . --wiki-
 llm-wiki ci-check --include-tests go --src-dir . --wiki-dir docs/llm_wiki
 llm-wiki ci-check --src-dir /path/to/repo --wiki-dir docs/llm_wiki --allow-external-src
 llm-wiki ci-check --format json --report .git/llm-wiki-ci-report.md
-llm-wiki ci-check --format json --report-schema v2 --no-report --cache-dir .cache/llm-wiki-inventory
+llm-wiki ci-check --format json --report-schema v2 --comparison-policy exact-v1 --no-report --cache-dir .cache/llm-wiki-inventory
 llm-wiki ci-check --format markdown
 ```
 
@@ -609,8 +615,10 @@ exits nonzero on validation failure. Native freshness/drift is disabled unless
 `--knowledge-drift-report` is supplied, and enabled findings remain
 nonblocking. Structured output discloses the report mode through
 `knowledge_drift_report`; the legacy `knowledge_drift_gate` compatibility field
-is always `false`. JSON output uses the closed `llm-wiki-ci-check/v1`
-envelope. Its `knowledge_health` member is a `llm-wiki-doctor/v1` projection
+is always `false`. For legacy knowledge, automatic JSON output uses the closed
+`llm-wiki-ci-check/v1` envelope with a `llm-wiki-doctor/v1` health projection.
+Migrated knowledge selects `llm-wiki-ci-check/v4` with a `llm-wiki-doctor/v4`
+projection and captured analysis compatibility. The `knowledge_health` member is
 composed from the same lint report, not a second source scan. The top-level
 `ok`, issue count, and process exit remain the authoritative blocking integrity
 result; the nested health status presents availability, freshness, snapshot,
@@ -618,7 +626,19 @@ governance, drift, and verification state without changing that policy.
 Use `--report-schema v2` for the `llm-wiki-ci-check/v2` envelope. It adds
 `runtime.cache`, `runtime.report`, `check_exit_code`, and `command_exit_code`.
 Report status is `written`, `disabled`, or `failed`; the nested doctor health
-continues to describe the check itself. The default schema remains v1.
+continues to describe the check itself. Automatic output selects v1 for legacy
+knowledge and v4 for knowledge carrying analysis compatibility metadata.
+
+For migrated knowledge, explicit v2 and v3 formats require
+`--comparison-policy exact-v1`. Use
+`--report-schema v3 --comparison-policy exact-v1` for `llm-wiki-ci-check/v3`.
+It retains the v2 runtime
+fields and includes a `llm-wiki-doctor/v3` health projection with captured
+coverage, snapshot commitments and producer versions. It reuses the same
+evaluation and preserves the integrity exit policy. Generic lint and MCP lint
+payloads retain their existing contracts.
+Detailed coverage describes the captured evaluation; `knowledge_drift_report`
+continues to control lint diagnostic occurrences.
 
 CI accepts the same `--cache-dir`, `--no-cache`, `--rebuild-cache`, and
 `--cache-stats` controls as lint and sync. Reports are replaced atomically.
@@ -637,6 +657,20 @@ disclosed with a warning, symlinks owned by another user are rejected, and
 `--report` is an output path, so explicit
 absolute paths and relative artifact paths outside the project root are allowed.
 
+### Analysis comparison policy
+
+`doctor`, `ci-check`, `context` and `mcp` accept
+`--comparison-policy auto|exact-v1|analysis-v1`. `auto` uses supported analysis
+commitments after sync and conservative comparison for legacy knowledge.
+`exact-v1` additionally requires producer versions to match. `analysis-v1` requires
+supported analysis commitments and reports unknown or incompatible inputs.
+
+`--report-schema v4` selects `llm-wiki-doctor/v4` or `llm-wiki-ci-check/v4`, with
+`llm-wiki-health-details/v2`. These reports retain exact versions and add the
+comparison policy and captured compatibility identities. Explicit older health
+report formats require `--comparison-policy exact-v1` for migrated knowledge.
+The capability report remains the separate doctor v2 contract.
+
 ## `doctor`
 
 Inspect current wiki knowledge health in one read-only command:
@@ -650,10 +684,38 @@ llm-wiki doctor --wiki-dir docs/llm_wiki --src-dir . --strict
 The report composes the existing availability, live freshness, snapshot parity,
 governance and review, drift, and verification-receipt checks. It does not
 define a separate source analyzer. Human output is a compact screen summary.
-JSON output uses the stable `llm-wiki-doctor/v1` schema and contains the same
+For legacy knowledge, automatic JSON output uses `llm-wiki-doctor/v1` and contains the same
 six named sections, complete freshness counts when evaluation succeeds, and
 the required evaluated or snapshot-only disclosure.
 
+Select conservative detailed JSON with
+`--report-schema v3 --comparison-policy exact-v1 --format json`, or call
+`llm_wiki_cli.api.doctor(..., report_schema="v3", comparison_policy="exact-v1")`.
+The default `auto` selects v1 for legacy knowledge and v4 for migrated knowledge.
+The v3 `health_details` object adds:
+
+- Captured source/wiki scope, source-selection fingerprints and snapshot hashes.
+- Recorded and live tool, extractor and plugin versions, configuration hashes
+  and generation-option hashes. Comparison still uses exact producer versions;
+  `analysis_contract: null` means no cross-version compatibility contract is available.
+- Disjoint `modeled` and `unmodeled` counts whose sum is `total`. Modeled outcomes
+  distinguish current, nonsemantic change, changed/missing source, incompatible
+  basis and unknown evidence. Missing recorded evidence does not make a modeled
+  concept unmodeled.
+- Separate evaluation, comparison-attempt and compatible-content counts.
+  Confirmed missing sources are outside compatible-content comparisons, because
+  absence can be established before comparing producer versions.
+- Primary reason counts in unique concepts, with at most three sorted example
+  locators per reason and an exact omitted count. Diagnostic occurrence counts
+  remain separate and can include overlapping findings.
+
+Unavailable inventory and unevaluated comparison counts are `null`, not zero.
+Partial extraction is disclosed explicitly. These details describe the captured
+evaluation; later filesystem or installed-package changes do not rewrite it.
+Snapshot hashes identify declared input sets and do not themselves prove freshness.
+The v3 option cannot be combined with `--capabilities`, which retains its
+separate v2 contract.
+
 To keep the health read from executing project plugin code, `doctor` never
 loads source plugins. Evidence that only a source plugin can produce may
 therefore be unavailable or basis-incompatible; strict mode can classify the
@@ -707,6 +769,14 @@ Text output shows these next steps directly.
 
 ## `context`
 
+Use `--request FILE --format packet` to deliver a canonical v1/v2 packet from
+a filter-bearing request file. The file owns semantic options; explicit
+budget, focus, freshness-preference, or knowledge-mode overrides are rejected.
+The file's inner format remains JSON or Markdown. For v3 requests, the declared
+outer format must agree with any explicit format flag. See
+[qualified context packets](qualified-context-packets.md) for request examples,
+error codes, and the distinction between validation and currentness.
+
 Build a token-budgeted source snapshot for agents.
 
 ```bash
@@ -792,6 +862,10 @@ same optional `knowledge_mode`. Qualified packet versioning and validation are
 described in [Qualified context packets](qualified-context-packets.md).
 
 `filters.language` and `filters.module` scope the budgeted `files` payload.
+Module filters are glob patterns over extensionless paths or dotted module
+names: use `app/service` or `app.service`, rather than `app/service.py`.
+Check the returned file set and native selection before relying on the result;
+an unmatched valid filter can correctly produce an empty selection.
 `filters.symbol`, `filters.entrypoint`, and `filters.surface` add bounded
 `graphs` and `surface` sections without changing the file-priority budget.
 `filters.freshness` and `filters.evidence` refine concept references and require
@@ -1089,6 +1163,10 @@ plugins cannot inject Markdown, labels, hrefs, or raw Mermaid lines. Core
 renderers keep labels Unicode-safe and bounded, and validate and percent-encode
 relative `click` hrefs.
 
+Data-flow style contexts also include `flow_id`, `category`, and the entry
+`symbol` with its original case. Hooks can use `symbol` to match the first
+numbered node label, such as `1. HANDLE_TASK`.
+
 These hooks are deterministic local extension contracts over explicit inputs;
 they do not perform network discovery and they do not mutate Markdown directly.
 They are not a sandbox, though: installing a plugin runs trusted project-local
@@ -1744,6 +1822,17 @@ of UTF-8 content, with 1–100 returned results. Exceeding a corpus limit fails
 explicitly; narrow `--kind` or choose a smaller wiki. Search is read-only and
 does not require embeddings or a model service.
 
+The query must contain a non-whitespace character. Nonblank queries retain
+their original whitespace, including in substring mode. `--limit` accepts a
+positive integer, defaults to 20, and caps the returned results at 100 even when
+a larger value is requested. Blank queries and invalid limits exit `2`, leave
+stdout empty, and print argument diagnostics to stderr in both output formats.
+A valid query with no matches exits `0` with empty results.
+
+JSON responses from both the CLI and MCP disclose `mode` (`ranked` or
+`substring`), `total`, `returned`, and `bounds.results`, including truncation.
+Ranked scores and provenance remain specific to ranked mode.
+
 ## `queue`
 
 Select advisory maintenance work for a managed wiki:
@@ -1762,6 +1851,20 @@ reuses existing freshness and worklist evidence, loads no project plugins, and
 does not edit pages or change the integrity gate. Prepared helpers are required
 for the selected source languages; `--helper-cache-dir` selects their cache.
 
+`--limit` accepts integers from 1 through 1000 inclusive and defaults to 30.
+Invalid limits exit `2` before reading the queue inputs, with empty stdout and
+an argument diagnostic on stderr in either output format.
+
+The JSON report includes the requested `limit`, `total`, `returned`, and
+`omitted`; `returned` equals the number of `items`, and `total` equals
+`returned + omitted`. The `limit` field is additive metadata in
+`llm-wiki-maintenance-queue/v1`. Consumers should accept additional fields.
+The `queue_id` hashes the complete report, including `limit`: identical inputs
+and limits give the same identity, while different limits give different
+identities even if every item fits. Reports from versions without this field
+have different identities. A valid advisory queue exits `0`, including when
+there is no recommended work.
+
 ## `upgrade`
 
 Refresh framework-managed artifacts in place.
@@ -1808,6 +1911,23 @@ managed instruction block or change its compact/expanded delivery, use
 
 ## `knowledge`
 
+Read eligibility and freshness diagnostics without enabling governance:
+
+```bash
+llm-wiki knowledge coverage --wiki-dir wiki
+llm-wiki knowledge coverage --src-dir src --wiki-dir wiki --live --format json
+```
+
+The default reads the committed snapshot only. `--live` performs source
+extraction with prepared helpers; `--source-selection`, `--helper-cache-dir`
+and `--allow-external-src` preserve the corresponding source options.
+The versioned report separates modeled concepts, intentionally unmodeled
+content, actual comparisons and missing/incompatible bases. It is advisory;
+`unknown` over all concepts is not a defect rate. Unavailable knowledge has
+null counts, while a valid empty model has zeroes. JSON failures leave stdout
+empty and emit a safe code/field record on stderr with exit 1; usage errors
+retain exit 2. See [coverage diagnostics](native-knowledge.md#coverage-diagnostics).
+
 Initialize durable identity, inspect governance, record explicit lifecycle or
 section review events, stage ambiguous moves, and run application-owned pure
 verification checkers:

agent_wiki_cli-2.3.0/docs/native-agent-workflow.md

@@ -0,0 +1,161 @@
+# Native coding workflow
+
+Install `agent-wiki-cli` 2.3.0 or newer to use task context, workflow profiles
+and context sessions.
+
+For large native snapshots, [knowledge storage](knowledge-storage.md) describes
+explicit sharded or packed storage adoption and task request v2 with selected validation.
+Task request v1 retains its existing full-validation behavior.
+
+An explicit task request gathers qualified source and wiki evidence. The provider
+reads and reports; your coding host decides what to include, edit, execute and
+publish. Existing context calls retain their defaults.
+
+## Choose an interface
+
+| Operation | Python API | CLI | MCP |
+|---|---|---|---|
+| Ranked discovery | `search_wiki` | `search` | `search_wiki` |
+| Advisory maintenance | `build_maintenance_queue` | `queue` | `get_maintenance_queue` |
+| Exact query | `query_documentation` | `query --request FILE` | `query_documentation` |
+| Complete output budget | `build_budgeted_context` | `context --request FILE` | `build_budgeted_context` |
+| Task evidence | `build_task_context` | `task-context --request FILE` | `build_task_context` |
+| Validated reuse | `open_context_session` | — | `open_context_session`, `read_context_session`, `hint_context_session`, `close_context_session` |
+
+Search discovery preserves ranking reasons and corpus bounds. Exact queries use
+the existing [native query contract](native-knowledge-provider.md). A maintenance
+queue is advisory and never applies recommendations.
+
+## Declare evidence requirements
+
+```python
+from llm_wiki_cli import api
+
+request = {
+    "schema_version": "llm-wiki-task-request/v1",
+    "text": "Inspect the configured retry count.",
+    "kind": "bug-diagnosis",
+    "requirements": [
+        {"id": "retry-contract", "facet": "source-contract",
+         "selector": "retry.py:retry"}
+    ],
+}
+result = api.build_task_context(request, src_dir="src", wiki_dir="wiki")
+if result.ok:
+    payload = api.validate_task_context(result.rendered, request)
+    print(payload["coverage"])
+```
+
+Task kinds are `orientation`, `bug-diagnosis`, `contract-change` and `refactor`.
+Anchors have a `kind` (`source`, `symbol`, `wiki` or `concept`) and a `value`.
+Source selectors are portable relative paths. Declaration coordinates may include
+an exact owner and occurrence, such as `retry.py:Client.retry#2`. An unqualified
+name can remain ambiguous. An optional `task_ref` is a host label, separate from
+the provider's content identity.
+
+Requirements declare `id`, `facet`, `selector` and optionally `criterion`
+(`present` or `complete`). Supported facets are `source-contract`, `callers`,
+`callees`, `concept`, `semantic-section`, `typed-relationships`, `entrypoint` and
+`dependency`. A `behavior` requirement reports that host verification is needed.
+Static observations cannot establish complete runtime behavior or prove the
+absence of callers. Coverage concerns emitted evidence; it does not mean the task
+is solved or that prose is correct.
+
+Results preserve a captured basis, citations, qualifiers and every requirement's
+gap. Follow-ups contain bounded selectors and reasons for the host to consider.
+JSON serialization keeps unclosed source Markdown fences inside their data fields.
+
+## Explicit profiles and work limits
+
+Use `api.load_workflow_profile(FILE)` or pass a `WorkflowProfile`/profile mapping.
+The profile schema is `llm-wiki-workflow-profile/v1` with a `settings` object.
+Profiles are never discovered automatically. The bundled `native-coding` skill
+includes a starting profile; adopt it explicitly with the existing skills lifecycle.
+
+Defaults use native `auto` mode, freshness preference, selected source reads,
+estimated counting, 32,000 output tokens, 64 captured inputs, 8 MiB each of source
+and wiki inputs, four read rounds and four follow-up proposals. A trusted
+`WorkflowPolicy` constrains scopes and limits. Request `options` can choose
+per-call settings within those ceilings. Neither profiles nor task text can
+change roots, load tokenizer paths, prepare helpers, enable plugins or execute
+commands. Source selection and helper configuration remain host arguments.
+
+`snapshot` reads wiki evidence without extracting source. `selected` captures
+explicit source coordinates and relevant selection/package/infrastructure inputs.
+`full-inventory` requires permission from the host policy and an explicit request.
+An empty selection never expands into a full scan. Questions outside the permitted
+scope return a gap and a proposed next read.
+
+Request text is limited to 16 KiB, coordinates to 4 KiB, and anchors/requirements
+to 100 each. CLI JSON input is limited to 1 MiB and rejects duplicate keys,
+unknown fields, unsupported versions and coerced values. CLI input errors exit 2;
+workspace errors exit 1; a minimum context that cannot fit exits 3 with no partial
+context. Input byte limits apply per capture; validation rereads and parser work
+are separate costs.
+
+Source directory discovery is capped at `max(4096, 128 × max_files)` entries,
+up to 100,000; wiki discovery is capped at 10,000 entries. Excessive discovery returns an explicit work-limit gap before
+source extraction. A narrower source root or an allowed higher limit can help.
+
+Native `required` mode requires availability. It does not require a positive
+currentness verdict. Freshness preference does not enable native mode or approve
+semantic content.
+
+## Counting and MCP delivery
+
+The v3 MCP tool requires `protocol: "llm-wiki-context/v3"` and `changes`, which
+accepts explicit paths, a base/head range, or staged changes. Use
+`{"mode": "paths", "paths": []}` for no supplied changes. Old MCP context tools and
+resource URIs retain their response shapes.
+
+V3 and task tools return one canonical text block without a structured copy of
+the context. Include that text once. Exact counting requires a trusted Python
+counter or an explicitly configured server `--tokenizer FILE`; tool input cannot
+choose the tokenizer file. Estimated counts remain labeled estimates. Accounting
+covers canonical context text, including its accounting fields. MCP and host
+framing, session metadata and model-side framing are separate costs.
+
+## Optional sessions and resume
+
+```python
+with api.open_context_session(src_dir="src", wiki_dir="wiki") as session:
+    first = session.read(request)
+    again = session.read(request, if_result_id=first.result_id)
+    # Unchanged requires current input validation.
+```
+
+Sessions default to eight entries, 16 MiB retained state and a five-minute expiry.
+They serialize calls within one instance, return detached data, and bind to their
+creating workspace. Changed roots or working directories require a new session.
+Close sessions at disconnect or cancellation. Set `reuse=False`, use zero entries,
+or use `build_task_context` for cold reads with the same feature coverage.
+
+Source membership and bytes, ignore/selection inputs, wiki artifacts, producer
+configuration and Git metadata are rechecked. Events only invalidate state;
+lost events cannot authorize reuse. Unsaved buffers require save/defer handling.
+Helper-backed captures use cold reads when a complete bounded producer check is
+unavailable. No continuous freshness or general speedup is promised.
+
+Session metadata reports reuse, validation work, elapsed time and retained memory
+outside the portable task identity. Embedded task work describes its originating
+read. Optional deltas require an exact retained base; use
+`api.apply_task_delta(base_text, delta, request)` to reconstruct and validate the
+full canonical context. Missing bases fall back to a full result. Wrong and
+out-of-order bases are rejected. Whole-value array replacement preserves deletions
+and changed qualifiers.
+
+MCP sessions require `--enable-sessions`. Handles belong to that server and its
+configured workspace. Full responses carry canonical context in text and separate
+session metadata in structured content. Delta text is a delta envelope; embedded
+accounting describes reconstructed context. Session delivery counters describe
+the transmitted context or delta. Reconnect with a fresh session and validate
+saved context before reuse.
+
+For a persisted handoff, `api.reconcile_task_context(saved_text, request, ...)`
+returns one fresh scoped context together with the input-basis comparison and
+the existing packet reconciliation facets. A matching basis and semantic approval
+are separate results. Legacy packet reconciliation keeps its existing read scope.
+
+See the [downstream coding example](../examples/native-workflow/README.md) for a
+host-owned edit, behavior check, durable explanation and resumed handoff. This
+workflow remains opt-in; comparative model benefit has not been established.