agent-wiki-cli 3.2.0__tar.gz → 4.0.0__tar.gz

{agent_wiki_cli-3.2.0/src/agent_wiki_cli.egg-info → agent_wiki_cli-4.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-wiki-cli
-Version: 3.2.0
+Version: 4.0.0
 Summary: CLI tool to maintain hybrid LLM Wikis for multi-language projects.
 Author-email: Denis Sivagin <denissvgn@gmail.com>
 License-Expression: MIT
@@ -13,33 +13,36 @@ Classifier: Environment :: Console
 Classifier: Programming Language :: Python :: 3
 Classifier: Operating System :: OS Independent
 Classifier: Topic :: Software Development :: Documentation
-Requires-Python: >=3.10
+Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: PyYAML>=6
-Requires-Dist: tomli>=2; python_version < "3.11"
 Provides-Extra: tokens
-Requires-Dist: tokenizers<0.23,>=0.22; extra == "tokens"
+Requires-Dist: tokenizers<0.23,>=0.22; python_version >= "3.11" and extra == "tokens"
+Requires-Dist: filelock>=4.2.1; python_version >= "3.11" and extra == "tokens"
 Provides-Extra: dev
+Requires-Dist: pip==26.2.2; extra == "dev"
 Requires-Dist: pytest>=7.0; extra == "dev"
 Requires-Dist: pytest-cov>=4.0; extra == "dev"
 Requires-Dist: jsonschema>=4.18; extra == "dev"
 Requires-Dist: markdown-it-py<5,>=4.0; extra == "dev"
-Requires-Dist: setuptools==83.0.0; extra == "dev"
+Requires-Dist: setuptools==84.1.0; extra == "dev"
 Requires-Dist: tomli>=2; extra == "dev"
 Provides-Extra: typescript
 Provides-Extra: go
 Provides-Extra: rust
 Provides-Extra: mcp
-Requires-Dist: mcp<2,>=1.27; python_version >= "3.10" and extra == "mcp"
-Requires-Dist: pydantic-settings<2.15,>=2.5.2; python_version >= "3.10" and extra == "mcp"
+Requires-Dist: mcp<2,>=1.27; python_version >= "3.11" and extra == "mcp"
+Requires-Dist: pydantic<3,>=2.11; python_version >= "3.11" and extra == "mcp"
+Requires-Dist: pydantic-settings<2.15,>=2.5.2; python_version >= "3.11" and extra == "mcp"
+Requires-Dist: uvicorn<1,>=0.31.1; (python_version >= "3.11" and sys_platform != "emscripten") and extra == "mcp"
 Dynamic: license-file
 
 # LLM Wiki CLI
 
 [![CI](https://github.com/Denissvgn/python-wiki-llm/actions/workflows/ci.yml/badge.svg)](https://github.com/Denissvgn/python-wiki-llm/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
 
 Build and maintain an architectural wiki for your codebase. LLM Wiki scans
 source into Markdown pages, keeps generated structure in sync, and supplies
@@ -54,7 +57,11 @@ import package is `llm_wiki_cli`.
 
 ## Installation
 
-Requires Python 3.10 or later.
+Requires Python 3.11 or later.
+
+The optional `agent-wiki-cli[tokens]` backend counts tokens exactly with a
+caller-supplied local tokenizer JSON. The core CLI, MCP, and optional backends
+all use the Python 3.11+ package baseline.
 
 ```bash
 pip install agent-wiki-cli
@@ -128,7 +135,7 @@ for [Obsidian](docs/cli-reference.md#obsidian) or a
 
 | Area | Implementation | Runtime requirement |
 |---|---|---|
-| Python | stdlib `ast` | Python 3.10+ |
+| Python | stdlib `ast` | Python 3.11+ |
 | TypeScript / JavaScript / TSX / JSX | `ts-morph` | prepared Node.js dependencies |
 | Go | `go/ast` | prepared helper binary |
 | Rust | `syn` | prepared helper binary |

{agent_wiki_cli-3.2.0 → agent_wiki_cli-4.0.0}/README.md

@@ -2,7 +2,7 @@
 
 [![CI](https://github.com/Denissvgn/python-wiki-llm/actions/workflows/ci.yml/badge.svg)](https://github.com/Denissvgn/python-wiki-llm/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
 
 Build and maintain an architectural wiki for your codebase. LLM Wiki scans
 source into Markdown pages, keeps generated structure in sync, and supplies
@@ -17,7 +17,11 @@ import package is `llm_wiki_cli`.
 
 ## Installation
 
-Requires Python 3.10 or later.
+Requires Python 3.11 or later.
+
+The optional `agent-wiki-cli[tokens]` backend counts tokens exactly with a
+caller-supplied local tokenizer JSON. The core CLI, MCP, and optional backends
+all use the Python 3.11+ package baseline.
 
 ```bash
 pip install agent-wiki-cli
@@ -91,7 +95,7 @@ for [Obsidian](docs/cli-reference.md#obsidian) or a
 
 | Area | Implementation | Runtime requirement |
 |---|---|---|
-| Python | stdlib `ast` | Python 3.10+ |
+| Python | stdlib `ast` | Python 3.11+ |
 | TypeScript / JavaScript / TSX / JSX | `ts-morph` | prepared Node.js dependencies |
 | Go | `go/ast` | prepared helper binary |
 | Rust | `syn` | prepared helper binary |

{agent_wiki_cli-3.2.0 → agent_wiki_cli-4.0.0}/docs/automation.md

@@ -128,6 +128,11 @@ a different runtime identity and can prevent portable release-health comparison.
 On a source checkout, prepare and activate the ignored local toolchain before
 refreshing:
 
+Routine Node/npm preparation supports Linux x86_64, Linux ARM64 and macOS ARM64
+with platform-specific checksum-verified artifacts. Other language toolchains
+retain their own declared host limits; an ARM64 capture does not establish
+x86_64 execution or portable comparison.
+
 ```bash
 bash .github/scripts/setup-llm-wiki-ci-toolchains.sh --mode routine \
   --install-root .git/llm-wiki-ci-toolchains \
@@ -250,6 +255,29 @@ main changes, current native CI and the existing qualification and publication
 procedure using its verified artifacts. Local rehearsal distributions and
 receipts cannot replace that evidence.
 
+### Reviewed broad release captures
+
+The ordinary convergence observer keeps its normal sync limits. A generator
+upgrade that exceeds those limits needs a complete preview and a separately
+authorized broad write. **Reviewed release wiki capture** provides that manual
+route without changing the observer or publishing repository changes.
+
+Dispatch `reviewed-wiki-capture.yml` from main with `operation=preview` and the
+exact current main SHA as `candidate-sha`. Review the full `preview.stdout` and
+its source, wiki, installed package, runtime and prepared-helper binding in
+`preview.json`. Preview does not produce an owning-sync receipt or a snapshot.
+After explicitly approving that complete plan, dispatch `operation=apply` with
+the same candidate and `approved-preview-sha256` from the reviewed result.
+Apply recomputes the complete preview and refuses a changed binding before
+invoking the broad writer. It never automatically retries a failed normal sync
+with force.
+
+The workflow retains the drift decision and complete successful writer output
+for review. A drift result can fail the run while retaining a valid snapshot;
+that snapshot is not policy approval or release qualification. Review and
+validate the whole capture before a separate wiki pull request. Neither
+operation commits, pushes, tags or publishes anything.
+
 ### Qualification after merging
 
 Repository release automation is disabled by default in
@@ -267,6 +295,16 @@ qualification for that exact main commit. Normal qualification waits when the
 version, release tag, or changelog is not ready; unavailable remote checks are
 reported as blocked. Source, health, and integrity failures remain blocking.
 
+The final `qualified-release` ZIP has a dedicated reader. It validates the
+repository, source, run attempt and successful assembly job before download,
+then requires the API-declared ZIP length and SHA-256 digest exactly. Its
+transport is capped by the existing 256 MiB envelope; expanded bytes remain
+limited to 256 MiB and members to 10,000. Ordinary source and producer ZIPs
+retain their 64 MiB transport limit. Canonical paths, file kinds and portable
+collision checks precede extraction. The complete manifest, distribution and
+producer-evidence verification still governs qualification. Existing valid
+small bundles remain supported; this reader does not enable automation.
+
 Configure the following before setting `enabled` to `true`:
 
 - Enable repository auto-merge and protect main through pull requests, with no

{agent_wiki_cli-3.2.0 → agent_wiki_cli-4.0.0}/docs/cli-reference.md

@@ -155,12 +155,32 @@ llm-wiki bootstrap --format json --source-adapter
 `bootstrap` is first-use only. It accepts a nonexistent or empty target and the
 exact untouched scaffold created by `llm-wiki init`. If the target already
 contains a manifest, legacy or partial pages, custom prose, governance, or
-verification state, it stops before source extraction or target writes. Use
-`sync --jobs 1` for a maintained wiki and `migrate --dry-run` before migrating an
+verification state unrelated to an interrupted bootstrap, it stops before
+source extraction or target writes. Use `sync --jobs 1` for a maintained wiki
+and `migrate --dry-run` before migrating an
 older or partial layout. The retained `--overwrite` compatibility option always
 fails; neither that option nor a request phrased as “re-bootstrap” authorizes
 replacement.
 
+Bootstrap acquires both writer locks before changing wiki content. If a lock
+cannot be opened, fix its access permissions and retry the same command. If
+bootstrap is interrupted later, retrying uses its local recovery journal to
+restore only unchanged output from that operation, then captures fresh source
+evidence. Edited pages or unrelated files stop recovery before restoration.
+Preserve the entire incomplete wiki outside the configured wiki path before
+starting over when those edits need to be kept. Keep the recovery journal until
+setup succeeds; it is stored under `.git/bootstrap-recovery` when a `.git`
+directory is available, otherwise under `llm-wiki/bootstrap-recovery` in the
+system temporary directory. Recovery state stays outside a non-Git source tree.
+
+An older failed bootstrap without a journal cannot be identified safely from
+its generated pages alone. For a confirmed new setup containing only that
+failed output, preserve the incomplete directory elsewhere and bootstrap a
+fresh target. `sync` retains unknown provenance when seeding existing pages;
+`--no-cache` and `--rebuild-knowledge` do not recover the missing evidence.
+An established adopted wiki with missing authority still requires its complete
+committed recovery snapshot.
+
 With built-in extractors and complete source evidence, full bootstrap records
 validated knowledge and matching reuse metadata with the generated pages. The
 first `sync` preserves those artifacts when the source, wiki content, and
@@ -266,6 +286,13 @@ observations. A changed file refreshes its observations; deletions remove them.
 Cross-file class classification is recalculated after cached and fresh files
 are combined.
 
+A cache hit does not mean that all analysis was avoided. Read the fresh-file
+counters and extractor phases as well as the hit count. Invocations that capture
+Python implementation observations still perform fresh Python extraction;
+ordinary inventory reuse and committed sync-analysis reuse have different work
+and qualification scopes. Source content, rather than size or modification time
+alone, determines whether a per-file entry matches.
+
 After a successful sync records its generation inputs, an unchanged run can
 reuse the validated knowledge snapshot without rebuilding the graph or
 rewriting artifacts. Source/configuration, Markdown, assets, implementation,
@@ -287,12 +314,23 @@ The command reports `Sync analysis reuse: hit` or `miss` with a reason, and
 progress includes a `sync_analysis_reuse` phase. Missing, corrupted, oversized
 or redirected cache files fall back to ordinary analysis. Source changes,
 generated-section changes, unavailable helpers and incompatible inputs prevent
-reuse. Governed, maintenance-adopted and plugin-configured projects use ordinary
-analysis. `--no-cache`, `--rebuild-cache` and `--rebuild-knowledge` disable this
+reuse. An eligible ordinary maintenance owner is part of the input binding;
+cached observations never acknowledge review or replace current owner checks.
+Governed and plugin-configured projects use ordinary analysis.
+`--no-cache`, `--rebuild-cache` and `--rebuild-knowledge` disable this
 shortcut. An established unchanged snapshot is preserved without adding cache
 metadata solely to warm a cache. Standalone strict lint and CI still validate
 their own invocation inputs.
 
+Keep inventory caches in a trusted project-owned location. Restoring a
+sync-analysis file alone cannot authorize reuse without the matching native
+commitment. The integrity Action already restores exact prepared-helper caches
+and saves newly prepared ones only after successful default-branch pushes.
+Additional transport of application analysis data needs its own source-root,
+producer/runtime, settings and trust boundaries. Assess archive size, transfer,
+validation and required fresh work together; local warm timings do not establish
+a hosted net saving.
+
 `sync`, `lint`, and `ci-check` accept `--progress auto|always|never` and
 `--progress-format text|json`. Progress events are flushed to stderr. `auto`
 shows phases in an interactive terminal and heartbeats for long phases in
@@ -454,8 +492,49 @@ llm-wiki extract --src-dir . --summary --output sources/code.json --read-only
 llm-wiki extract --src-dir /path/to/repo --allow-external-src --summary
 ```
 
+`--paths` selects emitted code, Docker/Compose records, and unsupported-source
+advisories by source-relative file path. Referenced Docker build contexts and
+`COPY` sources do not add files to that selection. Explicit ignored files can be
+inspected with `--paths`; configured source-selection exclusions still apply.
+`--changed` applies the same
+scope to files changed in the last commit; when a Git diff is unavailable or
+source-selection controls changed, extraction reevaluates the selected source
+tree. Use `--paths` for an exact file selection.
+`--package` uses the nearest recognized Python project marker (`pyproject.toml`
+or `setup.py`) to select Python code and infrastructure; nested projects own their own
+files. Its name must be a non-empty string; blank selectors are rejected before
+extraction. It can return infrastructure without code records. Combining package and
+path/change selectors takes their intersection. Project manifests and lockfiles
+remain context for package ownership and dependency reconciliation.
+In the Python API, an empty `paths` list selects no files; omitting `paths`
+selects the source tree.
+Scoped entry points bind to selected files. Unresolved project-script declarations
+remain visible when their `pyproject.toml` is selected, including full-tree reads.
+Distinct unresolved script names remain separate entries even when they share a
+callable name such as `main`; their handler analysis remains unavailable.
+
 The JSON output includes `schema_version: "llm-wiki-extract/v1"` plus
 `inventory` and optional `docker` and `unsupported_sources` objects.
+Deep flow output separates evaluated flow assembly from source effect analysis.
+Its additive `analysis` object (`llm-wiki-callable-effect-coverage/v1`) reports
+`evaluated`, `partial`, `unavailable`, or `not_applicable` effect coverage,
+with callable-record and collector-total availability for each step. Known
+limitations also appear in generated flow pages, including when no effects or
+call-resolution gaps were captured. Empty observations from an unavailable
+collector do not establish an empty handler body or runtime completeness.
+Known collector omissions remain visible as partial coverage with observed,
+emitted, and omitted counts. Collector subtotals include only source steps
+with available totals; unknown counts remain unavailable.
+Dockerfile records carry `stage_schema_version: "llm-wiki-dockerfile-stages/v1"`.
+Each stage owns its configuration declarations and ordered source instructions.
+An earlier named `FROM` stage is linked through `base_stage`; `COPY --from`
+records a file transfer. Infrastructure pages show each stage separately and
+identify inherited stages and unknown external defaults. The view records source
+declarations; effective image settings also depend on Docker's inheritance/reset
+rules, variable expansion, and build arguments. Flat configuration fields are
+qualified by `configuration_scope: "final-stage-declarations"` and `final_stage`.
+Aggregate copies and build arguments retain their owning stage and source line;
+global pre-FROM arguments are also available in `global_build_args`.
 To inspect one file without rebuilding the wiki, use
 `llm-wiki extract --src-dir . --paths src/dyn.mjs --deep --read-only`.
 The command prints JSON and uses the same prepared helper cache as other source
@@ -465,8 +544,54 @@ Unresolved JavaScript `import()` and computed `require()` calls remain explicit
 gap records in `imports`; they do not establish a resolved dependency or runtime
 completeness. Generated import tables label these gaps with their reason and
 source line.
+TypeScript deep declarations retain optional (`?`) and rest (`...`) parameter
+markers, generic binder declarations in `type_params`, and type-alias expressions
+in `target`. Interfaces keep their declaration kind in entity pages and module
+summaries. Alias expressions are limited to 4,096 Unicode characters; longer
+definitions carry `target_truncated: true` and a full-expression `target_sha256`.
+Their pages disclose the bounded preview and refer to source for the remainder.
+The digest keeps changes outside the preview visible to freshness comparisons.
+Deep function and class-method records retain declared overloads in `overloads`,
+including their source lines, generic binders, optional/rest markers and result
+types. Implementation records keep their existing identities for call analysis.
+Reference pages distinguish the implementation row from the generated overload
+declarations. The generated section has an explicit ownership marker; unmarked
+`Overloads` sections retain their authored content. Generic arguments in declared base and interface applications are
+retained; relationship lookup uses the named base identity.
+TypeScript imports retain explicit type-only binding and declaration markers
+as `type_only` and `type_only_declaration`. Their `runtime` qualification is
+`erased`, `conditional`, or `present`. Declaration-level `import type` and
+declaration-file imports are excluded from startup constraints. A specifier-only
+`import { type T }` can retain module evaluation, and ordinary binding imports
+depend on compiler emission, so both remain qualified as compiler-dependent.
+Bare side-effect imports remain startup constraints. The dependency view keeps
+explicit type dependencies and type cycles alongside the full coupling graph;
+load-order and cycle diagnostics distinguish possible runtime cycles from
+guaranteed-erased dependencies. Deep dependency output exposes these projections
+as optional `import_time_edges` (possible startup constraints), `type_only_edges`, `conditional_import_time_edges`, `type_cycles`,
+`preserved_cycles`, and `conditional_cycles` fields. Preserved startup cycles
+remain visible when compiler-dependent imports join them into a larger possible
+cycle group; `cycles` continues to describe the full possible startup projection.
+Import `scope` values must be strings when supplied. Malformed scope metadata
+cannot establish known inventory evidence; unclassified scopes remain possible
+startup dependencies unless a separate qualification guarantees erasure.
 Go `_test.go` files are omitted unless `--include-tests go` is supplied; Python
 test files remain part of normal Python extraction.
+Python deep extraction can capture a bounded static subset of nested helpers.
+A unique, unconditional, undecorated helper with no lexical free variables can
+resolve direct calls after its definition when its binding is neither reassigned
+nor escaped. These functions use qualified symbols such as
+`run.<locals>.clean` in the existing `nested_functions` list; optional
+`python_lexical_functions` witnesses identify the enclosing declaration and
+exact call locations. Their contract is `llm-wiki-python-lexical-functions/v1`.
+The original lexical call-binding records remain intact. Readers without these
+witnesses retain unresolved answers; malformed or unsupported witnesses cannot
+establish a target. Caller/callee queries and bounded flows use the same proven
+source target. Closure captures, callbacks, decorators, namespace mutation and
+ambiguous or reassigned bindings remain outside this subset. Extraction uses
+syntax and symbol tables without executing project imports; resolved static
+edges do not establish runtime behavior or complete flow coverage.
+
 JavaScript `.js` and `.jsx` files are handled by the TypeScript extractor
 family and use `language: "javascript"` in inventory output. Prepare the same
 helper with `llm-wiki prepare-extractors --language typescript`.
@@ -612,6 +737,21 @@ For automatic preparation during project setup, use
 missing or stale ones. `prepare-extractors` also checks the current build
 toolchain when explicitly rebuilding or refreshing the cache.
 
+TypeScript and JavaScript preparation records the complete cached `node_modules`
+tree, including sibling and nested dependencies. A dependency change makes that
+helper unavailable until explicit preparation succeeds again. Older receipts
+remain readable for diagnosis but cannot establish this complete identity;
+rerun `prepare-extractors --language typescript` with the same cache base after
+updating the CLI. Read-only commands do not migrate receipts or install packages.
+Go, Rust and Haskell retain their existing receipt formats.
+
+The TypeScript identity read is limited to 10,000 entries, 128 MiB total,
+32 MiB per file and 32 path components; receipt metadata is limited to 1 MiB.
+Links, reparse points, hard links,
+special files and detected changes during observation refuse qualification.
+These are observed cached bytes, independent of the active Node runtime and
+not proof of package authenticity.
+
 ```bash
 llm-wiki prepare-extractors --src-dir .
 llm-wiki prepare-extractors --src-dir . --plan --format json
@@ -680,6 +820,42 @@ retain their normal blocking policy.
 Legacy wikis with no declared knowledge projection continue in surface-only
 mode. See [Native knowledge reads][native-knowledge-strict]
 for the complete policy.
+
+CI text, Markdown and Action summaries show structural integrity separately
+from the embedded non-strict advisory health result. A passing integrity check
+can accompany degraded health. Native drift is explicitly `disabled` or
+`report-only`; that diagnostic mode does not change the blocking integrity
+checks. Ordinary CI and doctor reports disclose release policy as unavailable:
+only the separate release-policy verifier can establish its outcome from
+authenticated evidence matching the candidate, scope and captured inputs.
+
+Full Markdown reports start with captured health guidance and a bounded diagnostic
+preview. The complete diagnostic index reconciles category/kind totals and links
+to every emitted row. Routine external-call boundaries appear separately from
+unresolved or unfamiliar call findings and explicit step/depth truncation. Preview
+returned/omitted counts describe emitted records; they do not establish that the
+underlying source analysis was complete. Canonical lint/CI JSON retains the
+original findings, severities and hints. CI text and compact Action summaries use
+the same category/kind distinctions without changing their existing failure rules.
+
+Python coverage diagnostics distinguish static compatibility redirects from
+implementation gaps. A single unconditional, import-bound
+`sys.modules[__name__]` redirect can produce an informational
+`module_source_routes` record naming its selected, extracted destination.
+The source path and captured hash remain visible; the route creates no duplicate
+implementation or durable governance alias and does not prove runtime import
+behavior. Destination wiki coverage is checked separately. Re-exports keep
+their own module entries. Conditional or dynamic redirects, ambiguous package
+bindings, cycles, excluded targets and missing extraction remain uncovered or
+unresolved rather than acquiring an inferred owner.
+
+Comment/docstring-only package initializers produce informational
+`module_source_presence` records with their captured hashes when they have no
+module entry. Initializers with declarations, exports or executable setup retain
+the normal coverage checks. Classification reads at most 1 MiB per selected file
+and follows at most 16 redirect hops; unavailable or bounded-out proof stays
+unresolved. It never executes project imports or changes source selection.
+
 `--profile` suppresses the human-readable lint text and prints one JSON object
 to stdout containing the normal lint report, diagnostics, and phase timings.
 The JSON contract is preserved for extractor failures as well; lint still exits
@@ -799,6 +975,13 @@ dependencies as warning diagnostics. These warnings are visible in human output
 and profile JSON but do not make `lint`, `lint --strict`, or `ci-check` fail by
 themselves. Stale architecture pages with no current source modules remain hard
 issues.
+Skipped unused-dependency checks name the actual manifest paths and source scope.
+Where supported by the captured scope and package ownership guard, they distinguish
+excluded bundled helper implementations, missing source witnesses, source present
+without extraction, and unsupported inputs. Unknown ownership or coverage stays
+unknown. Skipping provides no unused-package verdict and does not diagnose helper
+preparation. Review the exact named paths read-only; helper-specific verification
+or preparation remains a separate operation with its existing toolchain needs.
 Python dependency reconciliation reads `pyproject.toml` and `requirements*.txt`
 manifests, including nested manifests scoped to their directory. Python imports
 use the selected source root, conventional `src` layouts, and declared packaging
@@ -945,6 +1128,22 @@ 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.
+It states the health classification mode; `--strict` does not by itself prove
+release admission. The doctor Action separately displays its configured failure
+threshold, which remains independent of the report's classification mode.
+
+Governance adoption and running verification checkers are explicit operations;
+expected optional absence is disclosed without inventing review or semantic approval.
+A valid governance ledger does not establish current human-review coverage,
+and zero expired findings does not mean every section was reviewed. Inspect
+the scoped review records. A valid machine receipt covers its recorded scope
+and checks only. A stale receipt retains its historical result while current
+validity fails; stale, failed and invalid receipts remain unhealthy. Missing
+previously committed governance authority remains invalid and requires the
+exact ledger to be restored. Reports never adopt governance, acknowledge a
+review or execute verification checkers. See [`knowledge`](#knowledge) for
+explicit adoption, review and verification operations.
+
 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.
@@ -977,6 +1176,18 @@ Snapshot hashes identify declared input sets and do not themselves prove freshne
 The v3 option cannot be combined with `--capabilities`, which retains its
 separate v2 contract.
 
+With native analysis metadata, fresh report diagnostics and live evidence
+explanations identify which contract, implementation, configuration or runtime
+commitments differ. Human health summaries use the same captured comparisons.
+Runtime-only drift calls for reviewing the execution runtime and target-host
+capture, rather than restoring unchanged configuration. Missing, unbound or
+unsupported comparisons remain explicitly unavailable.
+
+Historical primary reason codes and compact projection hints remain compatible.
+A configuration-related legacy reason code can group several analysis-basis
+differences; use the precise diagnostic and recorded/live commitments to choose
+the repair. Reporting does not perform preparation, sync or capture.
+
 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
@@ -1073,11 +1284,46 @@ supplied files or a supplied diff, use the bounded
 `query_documentation` tool with the `impact` operation. Exact concept,
 related-concept, surface, and typed queries use the committed snapshot;
 supplied file or unified-diff impact queries use targeted extraction. Symbol,
-entrypoint, and dependency queries
+entrypoint, flow-segment, and dependency queries
 perform a full inventory only when `allow_full_inventory=true` is supplied.
 The context budget and focus bound emitted output after a full deep inventory;
 they do not make that scan computationally cheap.
 
+Inspect transitions omitted from a bounded flow with an exact callable owner:
+
+```bash
+printf '%s\n' '{"operation":"flow-segment","value":"src/orders.py:submit","allow_full_inventory":true}' | llm-wiki query --request - --src-dir . --wiki-dir docs/llm_wiki
+```
+
+The same request works through Python `query_documentation` and MCP
+`query_documentation` (inside its `request` argument). The additive
+`llm-wiki-flow-segment/v1` result uses `file:symbol`, including class or nested
+qualification when present. Missing or duplicate owners remain unselected.
+It returns at most 12 trace rows and keeps the existing depth limit of 6;
+`limit` can request fewer rows. Legacy flow and data-flow results retain their
+existing shapes, ordering and limits.
+
+Follow an available top-level `follow_up.request` to inspect the next rows.
+An available `steps[].follow_up.request` narrows a depth frontier to a new
+root in the same graph; its depths and counts start from that root. Supply the
+returned request unchanged, with the same roots, source selection and prepared
+helpers. Its `basis` binds captured source bytes, source generation/selection,
+producer commitments, graph order and traversal options. Changed bindings are
+rejected; restart instead of appending results from a different basis. An
+unavailable follow-up includes its reason, including missing capture bindings
+or a row that exceeds the delivery byte budget.
+
+`coverage` separates observed reachable rows, depth-eligible rows, returned
+rows, omissions before/after the page, and depth omissions. `work` separately
+counts the complete inventory/graph binding and graph traversal/counting work.
+Every CLI/MCP dispatcher request repeats full source inventory; a smaller
+segment does not make that inventory cheaper. For repeated Python queries,
+reuse `api.flow_segment("src/orders.py:submit", service=service)` on a built
+documentation query service. That route performs no new extraction or file I/O
+and answers the service's captured view; build a fresh service after source
+changes. Static order, a complete page or a matching binding never proves
+runtime execution, runtime completeness or live freshness.
+
 Explain one exact concept using the existing evidence service:
 
 ```bash
@@ -1194,8 +1440,10 @@ llm-wiki context --budget 8000 --staged
 llm-wiki context --budget 8000 --changed-path src/app.py --changed-path src/models.py
 ```
 
-Exact mode requires the optional `agent-wiki-cli[tokens]` dependency and an
-explicit local tokenizer JSON file. The counter identity binds its bytes and
+The local tokenizer backend requires Python 3.11+, the optional
+`agent-wiki-cli[tokens]` dependency, and an explicit local tokenizer JSON file.
+All CLI, MCP, and counting modes require Python 3.11 or newer.
+The counter identity binds its bytes and
 backend version. Counting disables saved truncation, padding, and special-token
 insertion; it covers the output text, including knowledge, metadata, accounting,
 the packet envelope when selected, and its final newline. Host chat framing is
@@ -1203,10 +1451,26 @@ outside this budget. Estimated mode uses UTF-8 byte length divided by four,
 rounded up, and always reports `exact_compliance: false`.
 
 The v3 envelope reports a conservative `used_tokens` upper bound that can be
-recounted with the named counter. Whole source entries are reduced or omitted
-under pressure, with omissions disclosed. Required evidence is retained. If the
+recounted with the named counter. Broad fitting jointly reduces source detail,
+optional native relationships, and whole native concept/page groups. Relevance
+tiers take precedence; requested currentness preference applies within a tier.
+Within an equal rank, optional relationships and deep source detail yield before
+native concepts and whole source summaries. When available, a useful source row
+and a fully qualified native group remain. Explicit target enrichment is retained.
+Native collection maxima are ceilings rather than fixed budget reservations.
+Source omissions/detail reductions and independent native bounds disclose the
+actual selection; neither omitted evidence nor an unavailable result is a
+negative fact. Scoped task/session requirement semantics are separate. If the
 remaining envelope cannot fit, stdout is empty, stderr contains a JSON
 `cannot-fit` result, and the command exits `3` without writing an output file.
+Its bounded `diagnostics` bind the request and counter, describe exhausted
+selection reductions, and disclose source/native counts and serialized JSON
+component sizes. Component bytes are not additive tokenizer costs. Failure
+usage describes the rejected candidate, not emitted context or a global minimum.
+Choose a scoped task/session or documentation query matching the requirements,
+or explicitly authorize a larger complete-output budget and independently fit
+and recount it. Keep required native evidence and its qualifications. Do not
+repeat an unchanged broad read or execute generated recovery commands.
 Legacy v1/v2 allocation and qualified-packet schemas remain available.
 
 Explicit changes also opt into v3, using estimated mode unless exact mode is
@@ -1455,7 +1719,14 @@ and load order. It also exposes direct page tools including `get_flow(flow_id)`
 Use `query_graph({"type": "callers", "value": "run", "limit": 20})` for
 bounded graph queries; supported types are `flow_for_entrypoint`,
 `data_flow_for_entrypoint`, `callers`, `callees`, `dependency_neighborhood`,
-and `pages_for_symbol`. Bounded query collections expose exact
+and `pages_for_symbol`. Class lookups support the same source-qualified route as
+callables, such as `{"type": "pages_for_symbol", "value": "src/models.py:Item"}`.
+The source path and class name must match exactly. Names shared by files and
+callable/class collisions remain ambiguous. Repeated class declarations retain
+the existing graph's file/name identity. Missing or invalid source routes do not
+fall back to another file. Related pages retain their source identity and
+existing bounds.
+Bounded query collections expose exact
 `bounds.<response-path>` totals, returned counts, and truncation. Context
 payloads, lint summaries, and status
 information report the same canonical surfaces. HTTP mode is intended for local
@@ -1671,6 +1942,20 @@ the controller refreshes the native projection and re-anchors generated
 ownership before later validation or dispatch; workers never edit or report
 those generated files as their own changes.
 
+Generated ownership evidence includes a `coverage` disclosure alongside the
+legacy `fingerprints` map. It hashes five root files (manifest, surface,
+knowledge, governance and verification) when present, plus generated Markdown
+sections. The disclosure also names the ordinary maintenance adoption marker
+and immutable manifest objects, knowledge objects, packs, pack indexes and index
+pages, which this inventory does not fingerprint or include in root-file rollback.
+These roles describe custody;
+they do not establish that an artifact exists or has passed validation.
+Native readers and the maintenance owner guard retain their separate validation
+obligations, including ordinary pending and acknowledged review history.
+Workers may not create, change, remove or replace these native paths. The
+controller publishes new content-addressed objects through the native writers;
+the inventory grants no additional write, deletion or review authority.
+
 Preparation also writes a priority-blind calibration flow census and an
 evidence-only current-versus-candidate shadow under `.llm-wiki-docs/evidence/`.
 They preserve source citations, detector/language provenance, route,
@@ -2142,6 +2427,22 @@ user-flow pages, workflow pages, infrastructure notes, and dependency/load-order
 architecture pages all count as relevant review coverage when they describe the
 changed code or dependency relationship.
 
+When configured source selection excludes every requested changed path, review
+reports that exclusion before deep extraction or unrelated helper requirements.
+It distinguishes physical file metadata, selection and an extraction inventory
+that was not evaluated. Native impact and wiki accuracy remain unknown; empty
+impact arrays do not establish that a change has no effect. The configured
+source snapshot is still discovered and captured, so this is not a narrow
+filesystem scan. Metadata disclosure is bounded to 100 paths and 32 source-relative
+components, with exact omission counts and no excluded file-content reads.
+
+Mixed changes, selected paths and selection-control changes retain the full
+inventory and applicable helper requirements. Helpers are never prepared and
+source selection is never overridden implicitly. For configured selection,
+`impact-json` adds `review_scope` with path states, scope counts and actual
+inventory cost; plain review retains its existing JSON envelope and finding
+fields. Metadata limitations do not change path admission or extraction bounds.
+
 `impact-json` returns the stable `llm-wiki-impact/v1` payload, with direct
 source-to-page mappings, candidate dependency edges and manifests, static
 FastAPI operations, findings, limitations, and an impact identity. Equivalent
@@ -2409,6 +2710,38 @@ managed instruction block or change its compact/expanded delivery, use
 
 ## `knowledge`
 
+### Git delivery completeness
+
+```bash
+llm-wiki knowledge git-check --wiki-dir wiki
+llm-wiki knowledge git-check --wiki-dir wiki --staged
+```
+
+The read-only diagnostic follows the validated native snapshot, including
+referenced packs, manifest catalogs, governance records, Markdown and assets.
+It reports `delivery_state` as `git-eligible`, `local-only`, `mixed` or
+`indeterminate`, with counts and bounded ignored-path samples. Effective Git
+rules include nested ignores, repository excludes and global excludes. A check
+of only the wiki directory and `index.md` cannot establish completeness.
+
+Without `--staged`, a known local-only or mixed state is advisory and exits 0;
+inspect `delivery_state` before separately authorized staging. Intentionally
+local-only wikis can still pass local integrity checks. With `--staged`, success
+requires Git eligibility and every required file in the index with current
+content. The active Git index is checked, including a temporary index used for
+a partial commit. Unexpected staged governance or maintenance-adoption files
+also fail when the validated snapshot requires their absence.
+Native and binary bytes must match exactly; Markdown newline
+normalization is accepted. Missing, unmerged or mismatched files fail, and an
+unavailable or changing snapshot/index is indeterminate. Unreferenced caches
+and orphan objects are outside this snapshot check.
+
+Run the staged gate after authorized staging and before commit or delivery.
+Neither command authorizes Git writes, changes ignore rules, force-adds files,
+prepares helpers, accesses the network or changes the storage format.
+
+### Coverage and governance
+
 Read eligibility and freshness diagnostics without enabling governance:
 
 ```bash