agent-wiki-cli 2.5.0__tar.gz → 3.1.0__tar.gz

{agent_wiki_cli-2.5.0 → agent_wiki_cli-3.1.0}/MANIFEST.in

@@ -2,6 +2,7 @@ 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-normalization-diagnostic-v1.schema.json
 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
@@ -18,5 +19,6 @@ include docs/security-model.md
 include docs/native-knowledge-provider.md
 include docs/native-agent-workflow.md
 prune reports
+recursive-include tests/fixtures/knowledge-evidence *.json
 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.5.0/src/agent_wiki_cli.egg-info → agent_wiki_cli-3.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-wiki-cli
-Version: 2.5.0
+Version: 3.1.0
 Summary: CLI tool to maintain hybrid LLM Wikis for multi-language projects.
 Author-email: Denis Sivagin <denissvgn@gmail.com>
 License-Expression: MIT
@@ -87,6 +87,12 @@ a package upgrade or use `llm-wiki prepare-extractors --src-dir .` separately.
 llm-wiki bootstrap --src-dir . --wiki-dir docs/llm_wiki
 ```
 
+Bootstrap selects current compressed native storage and indexed maintenance
+ownership automatically. Task and compact-view requests can omit version fields;
+the library selects current contracts. Existing projects receive these defaults
+by updating the package and running `llm-wiki upgrade` from their project root.
+Upgrade retains recovery copies and reports their locations.
+
 Open `docs/llm_wiki/index.md` to browse the wiki. Use your coding agent to enrich
 semantic descriptions, guides, and behavior notes; generated diagrams, tables,
 and machine-readable artifacts are maintained by the CLI.
@@ -180,7 +186,7 @@ Use `llm-wiki <command> --help` for available options.
 | [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 |
+| [Knowledge storage](docs/knowledge-storage.md) | Current compressed snapshots, recoverable upgrades, 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.5.0 → agent_wiki_cli-3.1.0}/README.md

@@ -50,6 +50,12 @@ a package upgrade or use `llm-wiki prepare-extractors --src-dir .` separately.
 llm-wiki bootstrap --src-dir . --wiki-dir docs/llm_wiki
 ```
 
+Bootstrap selects current compressed native storage and indexed maintenance
+ownership automatically. Task and compact-view requests can omit version fields;
+the library selects current contracts. Existing projects receive these defaults
+by updating the package and running `llm-wiki upgrade` from their project root.
+Upgrade retains recovery copies and reports their locations.
+
 Open `docs/llm_wiki/index.md` to browse the wiki. Use your coding agent to enrich
 semantic descriptions, guides, and behavior notes; generated diagrams, tables,
 and machine-readable artifacts are maintained by the CLI.
@@ -143,7 +149,7 @@ Use `llm-wiki <command> --help` for available options.
 | [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 |
+| [Knowledge storage](docs/knowledge-storage.md) | Current compressed snapshots, recoverable upgrades, 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.5.0 → agent_wiki_cli-3.1.0}/docs/automation.md

@@ -54,7 +54,7 @@ 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
+to `report-schema: v4` 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.
@@ -138,6 +138,108 @@ source .git/llm-wiki-ci-toolchains.env
   --src-dir . --wiki-dir docs/llm_wiki
 ```
 
+### Local release preparation
+
+This repository provides `release/preflight.py` for explicit local preparation
+and release rehearsal. Run it from the source checkout with the project virtual
+environment. It keeps source, runtime, dependency and evidence identities bound
+to the selected commit, and reports native or hosted requirements that remain
+outstanding. It has no publication or promotion authority.
+
+Choose new output paths already covered by the project's ignore rules. The
+controller refuses unignored output and occupied, unowned work directories;
+existing owned work retains separate attempts. For example:
+
+```bash
+PREFLIGHT_DIR=reports/local-preflight
+RELEASE_CANDIDATE_SHA="$(git rev-parse HEAD)"
+git check-ignore -q -- "$PREFLIGHT_DIR/before-prepare.json"
+git check-ignore -q -- "$PREFLIGHT_DIR/work"
+.venv/bin/python -I release/preflight.py plan \
+  --candidate-sha "$RELEASE_CANDIDATE_SHA" --check-registry \
+  --output "$PREFLIGHT_DIR/before-prepare.json"
+.venv/bin/python -I release/preflight.py prepare \
+  --plan "$PREFLIGHT_DIR/before-prepare.json" --work "$PREFLIGHT_DIR/work"
+```
+
+`plan` inspects the checkout and available capabilities without installing
+anything. `--check-registry` additionally requests read-only remote tag and
+package-registry inspection. An unavailable service stays unavailable; it does
+not establish that a version is free. Already published versions, including
+3.0.0, and unfinished version or changelog preparation prevent complete release
+rehearsal. Version selection, migration review and issue disposition remain
+explicit maintainer decisions.
+
+`prepare` explicitly invokes the maintained locked toolchain and helper setup
+routes on supported hosts. Review its result, activate the prepared Node/npm
+environment as described above, finish authorized source and wiki maintenance,
+and commit the coherent result. Preparation may change the captured environment;
+a fresh plan is required after those changes. The controller refuses stale
+plans instead of silently selecting a different commit or environment.
+
+Preparation also screens an archive of the exact committed HEAD against the
+existing hosted source-archive limits before requesting repository health. Its
+`archive-budget/report.json` records compressed and expanded bytes, member count
+and the archive digest when an archive is created. This measures committed
+source scope. An archive above the 64 MiB compressed limit, or another existing
+archive bound, stays blocked for reviewed correction. Preparation never prunes
+storage automatically, and this local screen cannot authenticate the eventual
+hosted archive.
+
+For complete rehearsal, first save the actual issue snapshot, dispositions and
+version rationale in an ignored `$PREFLIGHT_DIR/release-review.json`. Its JSON
+object has exactly these fields:
+
+- `schema_version`: `agent-wiki-local-release-review/v1`.
+- `candidate_sha` and `version`: the final full commit SHA and its package version.
+- `observed_at`: a timezone-aware ISO 8601 observation time, no more than 24 hours old.
+- `issues`: the observed issue rows, each containing integer `number` and string `title`.
+- `dispositions`: one row for every observed issue, each containing its `number`,
+  a `decision` of `blocker`, `resolved`, `deferred`, or `not-a-bug`, and a specific
+  nonempty `reason`.
+- `semver`: `baseline` as the previous three-part release version, `target` matching
+  the candidate version, and a nonempty `reason` for the version choice.
+
+Record the review that was actually performed. This local record does not prove
+independent approval or a complete authenticated GitHub issue inventory. A
+recorded blocker prevents full rehearsal. Omitting `--review-file` leaves review
+pending and still permits the early diagnostic invocation described below.
+
+```bash
+RELEASE_CANDIDATE_SHA="$(git rev-parse HEAD)"
+git check-ignore -q -- "$PREFLIGHT_DIR/release-review.json"
+git check-ignore -q -- "$PREFLIGHT_DIR/final-plan.json"
+.venv/bin/python -I release/preflight.py plan \
+  --candidate-sha "$RELEASE_CANDIDATE_SHA" --check-registry \
+  --review-file "$PREFLIGHT_DIR/release-review.json" \
+  --output "$PREFLIGHT_DIR/final-plan.json"
+.venv/bin/python -I release/preflight.py run \
+  --plan "$PREFLIGHT_DIR/final-plan.json" --work "$PREFLIGHT_DIR/work"
+.venv/bin/python -I release/preflight.py status --work "$PREFLIGHT_DIR/work"
+```
+
+Use the returned `receipt_path` with
+`.venv/bin/python -I release/preflight.py verify --receipt RECEIPT_PATH`.
+Verification checks retained evidence and its current applicability without
+executing recorded commands or repairing anything. `status` shows recorded
+attempts; it does not establish their current applicability. Plans expire after
+24 hours and require a new inspection.
+
+For an early diagnostic check before version preparation is complete, append
+`--stage contracts` to `run`. A partial invocation remains `blocked` for release
+readiness even when its checks succeed. Full execution runs the maintained
+host-applicable checks, independent builds and installed-artifact verification
+serially. It reports `failed`, `blocked`, or
+`local-ready-hosted-required`; the last result still requires normal hosted
+qualification and all required target environments.
+
+Local macOS success cannot establish Windows or Linux semantics, an unsupported
+helper or OCI architecture, an authenticated policy proof, or publication
+attestations. A missing capability remains pending. Continue through reviewed
+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.
+
 ### Qualification after merging
 
 Repository release automation is disabled by default in
@@ -357,15 +459,15 @@ 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`.
+Without explicit inputs, the dashboard Action defaults to `report-schema: v4`
+(the `llm-wiki-doctor/v4` 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
+`llm-wiki-doctor-dashboard/v2` receipt bound to the report bytes. Explicit
+`llm-wiki-doctor/v1` reports retain their v1 receipt contract. 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

{agent_wiki_cli-2.5.0 → agent_wiki_cli-3.1.0}/docs/cli-reference.md

@@ -19,6 +19,53 @@ task detector with Mermaid styling.
 | Extend and collaborate | [install / plugins](#install-and-plugins), [team](#team), [knowledge](#knowledge) |
 | Manage an installation | [upgrade](#upgrade), [migrate](#migrate), [metrics](#metrics), [status / release / bump / uninstall](#status-release-bump-and-uninstall) |
 
+## Recover captured evidence
+
+Keep the failure's source, cause and qualifications. Use the same source/wiki
+roots, selection, helper cache and generation options through diagnosis and
+repair. For example, with source `src`, wiki `wiki`, selection
+`config/sources.json` and an existing helper cache `.cache/helpers`, save a
+permitted request file `evidence.json` containing:
+
+```json
+{"operation":"explain","source":"orders.py","limit":5}
+```
+
+```bash
+llm-wiki query --request evidence.json --src-dir src --wiki-dir wiki --source-selection config/sources.json --helper-cache-dir .cache/helpers
+llm-wiki extract --src-dir src --paths orders.py --deep --read-only --source-selection config/sources.json --helper-cache-dir .cache/helpers
+llm-wiki sync --dry-run --jobs 1 --src-dir src --wiki-dir wiki --source-selection config/sources.json --helper-cache-dir .cache/helpers
+```
+
+Replace these example bindings with the original command's actual values.
+Request `source` and extract `--paths` are canonical POSIX paths relative to
+`--src-dir`; filesystem and cache arguments use native paths. Explanation is
+snapshot-only by default; choose an exact locator from ambiguous results.
+`live:true` plus `allow_full_inventory:true` authorizes full current analysis.
+The [explanation route](#context) separates captured/current source and producer
+bases, helper identity and active runtime. Raw extraction prints JSON, installs
+no dependencies and cannot repair a stored manifest.
+
+For a missing/stale helper, use its exact [preparation remedy](#prepare-extractors)
+with setup authority, then retry the original read once with the same selection
+and cache. Preparation takes `--cache-dir`, reads take `--helper-cache-dir`.
+Do not combine explicit `--language` preparation with `--source-selection`.
+A current helper with a runtime mismatch needs the reported runtime selected on
+PATH; preparation does not change PATH. No hand-linked dependencies or internal
+helper-script invocation is required.
+
+Fix fresh normalization rejection before repair; invalid evidence stays blocking.
+If raw output is valid but captured evidence is unavailable, the authorized
+[owning sync](#sync) must commit the repair. Review the complete preview, including
+removals. Broad changes require explicit authority for the same invocation with
+`--force` replacing `--dry-run`; never force automatically. Review again after
+any input change. The bounded `--repair-evidence` writer retains its own adoption,
+stable-producer and scope conditions and still performs full analysis.
+Missing/corrupt authority needs its recovery route, not generated JSON edits or
+reinitialization. Review semantic prose, re-anchor edits through owning sync,
+then run strict lint and CI with the same bindings. Keep current defaults and
+strict gates. Storage upgrade and diagnostic reads alone do not establish repair.
+
 ## Resource-aware execution
 
 In an interactive IDE or whenever host capacity is unknown, run one heavy gate
@@ -260,6 +307,77 @@ or controlled CI runner with known capacity.
 Sync repairs
 manifests with invalid source hashes without touching pages, and stops unusually
 broad diffs unless `--force` is used.
+
+The affected-source count names inputs whose wiki projections may change;
+sync does not rewrite those source files. A generator-version transition can
+refresh every managed source even when source bytes are unchanged. A storage
+repack alone is separate from that generator refresh.
+When a broad update is refused, the message separates source-change reasons
+from additional generator-refresh inputs, identifies captured/current generator
+versions when available, and shows a bounded path sample with omitted counts.
+Reason counts can overlap; the total source-input count is deduplicated.
+Use the supplied `--dry-run` command with the same source/wiki roots, source
+selection and cache bindings to inspect the full page and artifact plan before
+authorizing a broad write. The preview lists complete affected input paths and
+their reasons, including paths omitted from the refusal sample.
+An oversized, control-containing or non-UTF-8 command is not
+printed; repeat the original invocation with `--dry-run` and omit `--force`.
+The path sample bounds the diagnostic output, not extraction or preview work.
+
+For a generator upgrade, review the complete dry-run page and artifact actions,
+including removals, before explicitly repeating the same invocation with
+`--force` in place of `--dry-run`. Keep the source/wiki roots, selection,
+helper/cache bindings and generation options unchanged. This is an owning
+refresh: it regenerates evidence with the current provider and commits matching
+projections and provenance. Already matching managed pages keep their bytes and
+are not rewritten. Changed generated content still appears as a page update;
+it is not classified as a source metadata edit merely because sources match.
+
+A preview is not a saved approval token. `--force` computes a new plan from
+current inputs; repeat preview and review if source, helper, selection, provider
+or wiki inputs change. It can authorize broad changes and stale generated
+surface removal, including authored Behavior on those retired surfaces. It does
+not waive ownership or integrity checks, adopt foreign state or recover missing
+authority. After the refresh and semantic review, re-anchor any prose edits with
+ordinary sync, then run strict lint and CI integrity validation using the same
+roots and selection. A subsequent sync with unchanged inputs should be a no-op.
+If publication is rejected, follow its explicit recovery diagnostic before
+retrying; do not delete authority files or reinitialize an established wiki.
+
+For a narrowly authorized repair of captured invalid evidence, use
+`--repair-evidence` with canonical POSIX source paths relative to `--src-dir`:
+
+```bash
+llm-wiki sync --src-dir src --wiki-dir wiki --no-plugins --repair-evidence package/module.py --dry-run
+llm-wiki sync --src-dir src --wiki-dir wiki --no-plugins --repair-evidence package/module.py
+```
+
+Keep the project's source selection, helper/cache bindings and other applicable
+options on both invocations. This mode requires an already adopted, coherent
+wiki, unchanged source and generation policy, and matching complete built-in
+producer/helper/runtime commitments. Run the authorized ordinary owning update
+first after a generator or producer transition. Missing or corrupt authority
+requires its explicit recovery route; scoped repair never adopts or migrates it.
+
+The writer repairs a selected source's existing module and entity evidence
+together, preserves unselected captured failures and review history, and does
+not acknowledge review. It refuses mixed source/prose edits, missing or renamed
+pages, new/retired identities, and any reconciliation that changes unselected
+facts or the global typed graph. `--force` can authorize a reviewed broad input
+count; it cannot override these scope conditions. A selected known basis must
+match the fresh observation; otherwise use ordinary owning sync for full review.
+
+This is scoped application after **full analysis**, not one-file extraction.
+Source verification, global graph/projection reconciliation, an isolated wiki
+copy, native objects, log/cache metadata and complete recovery preimages still
+require global work. The command checks its candidate before live application
+and again before publication. A changed source, helper, provider, selection or
+wiki invalidates the prepared operation. Existing publication recovery remains
+active; the isolated preflight does not replace a recoverable owning commit.
+Already matching selected evidence produces no scoped publication. Success
+does not certify the whole wiki: unselected unknown evidence remains unknown,
+so repeat strict lint and CI validation afterward.
+
 `--initialize-surfaces` enters a surface-only backfill mode for `flows`,
 `dependencies`, and/or `api-contracts`: ordinary entity/module source changes
 are reported but deferred. `--flow-category` is repeatable, `--exclude-tests`
@@ -338,6 +456,15 @@ llm-wiki extract --src-dir /path/to/repo --allow-external-src --summary
 
 The JSON output includes `schema_version: "llm-wiki-extract/v1"` plus
 `inventory` and optional `docker` and `unsupported_sources` objects.
+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
+reads; it does not install helpers. If a helper is unavailable, follow its
+`prepare-extractors` recovery command and retry with the same cache base.
+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.
 Go `_test.go` files are omitted unless `--include-tests go` is supplied; Python
 test files remain part of normal Python extraction.
 JavaScript `.js` and `.jsx` files are handled by the TypeScript extractor
@@ -557,6 +684,67 @@ for the complete policy.
 to stdout containing the normal lint report, diagnostics, and phase timings.
 The JSON contract is preserved for extractor failures as well; lint still exits
 nonzero, but stdout remains machine-readable.
+Structural evidence errors retain their blocking policy. Where the manifest
+captures the information, the existing `message` field names the source path,
+extractor and underlying cause; `reason_code` retains the top-level category
+and `hint` gives the next action. For example, `promised-evidence-unknown`
+can report the underlying `invalid-inventory-shape` cause. The JSON finding
+fields remain unchanged for strict report consumers.
+Inspect the named source with the read-only
+single-file extraction command above, repair the underlying producer or source
+problem, then run owning sync before repeating strict validation. Editing a
+generated wiki table does not repair invalid extractor evidence.
+Diagnostics distinguish a captured failure with no fresh result, a captured
+failure whose fresh normalization succeeds, and a fresh observation that still
+fails normalization. Where captured source hashes exist, they distinguish
+unchanged bytes from changed or incomparable inputs. Producer metadata and
+version labels do not identify historical package bytes; unavailable provenance
+and rejected-record details remain explicit.
+
+Fresh normalization rejections can include `Fresh normalization diagnostic: `
+followed by a JSON object in the existing finding `message` or evidence freshness
+`description`. The object has its own
+[`llm-wiki-normalization-diagnostic/v1` schema](../src/llm_wiki_cli/schemas/llm-wiki-normalization-diagnostic-v1.schema.json).
+It identifies the source, scope and extractor, the entity's named occurrence
+when applicable, a record `pointer`, the failed `rule`, the `expected` shape,
+and redacted `actual` type/summary. For example, an import can identify
+`/imports/0/module` with rule `import-module`; a near-miss explicit dynamic
+import can instead identify its missing `/imports/0/reason`.
+
+Exact pointers use JSON Pointer with zero-based array indexes. Entity occurrence
+coordinates remain one-based among declarations with the same name. A missing
+occurrence points to the declaration collection, without inventing an index.
+An unknown recursion/encoding location uses a null pointer. When an arbitrary
+mapping key is redacted, the pointer identifies an ancestor and `pointer_exact`
+is false. Bounded coordinate prefixes are listed in `truncated_fields` and must
+not be treated as exact identities.
+
+The rendered diagnostic is limited to 4,096 UTF-8 bytes, including its prefix.
+Rejected string values, container contents and arbitrary mapping keys are redacted;
+actual summaries retain safe shape facts such as type, length, emptiness or
+non-finiteness. No arbitrary object representation is rendered. A surrounding
+query may impose a tighter response bound and disclose truncation separately.
+Missing detail does not establish valid evidence.
+
+This versioned object is carried as diagnostic text; existing outer report and
+evidence-basis fields are unchanged. Older decoders can retain that text without
+parsing it. A consumer interpreting the object must recognize its schema version;
+unknown versions are not an inferred current contract. Native comparison data
+still requires its compatible outer report schema. Raw `extract` output remains
+inventory, not an annotated normalization report. Historical reason-only snapshots
+do not acquire reconstructed record pointers: details describe only a rejection
+observed by the current normalization run. Valid observation hashes, reason codes
+and strict failure policy remain unchanged.
+
+Fresh extraction and evidence explanation are reads: a valid fresh observation
+does not make an unknown committed baseline current. Ordinary owning sync can
+refresh a captured invalid module/entity basis after current deep normalization
+succeeds, including when the generator version label is unchanged. Its preview
+labels this as `evidence-refresh-additional`, separately from source edits and
+generator transitions. Broad refreshes retain the normal review guards. If fresh
+normalization is still invalid, repair that cause; `--force` does not waive
+evidence validity. If fresh normalization succeeds but owning sync is refused by
+the broad-update guard, follow its complete preview and reviewed apply route.
 `lint --profile` and `ci-check --format json` additionally include this shape:
 
 ```json
@@ -845,6 +1033,8 @@ Text output shows these next steps directly.
 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.
+Packet flags and request files with no protocol use the current v2 contract
+and automatic native-knowledge selection. Explicit v1 requests remain supported.
 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,
@@ -888,6 +1078,40 @@ 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.
 
+Explain one exact concept using the existing evidence service:
+
+```bash
+printf '%s\n' '{"operation":"explain","value":"llm-wiki://modules/orders"}' | llm-wiki query --request - --src-dir . --wiki-dir docs/llm_wiki
+printf '%s\n' '{"operation":"explain","source":"src/orders.py","limit":10}' | llm-wiki query --request - --src-dir . --wiki-dir docs/llm_wiki
+printf '%s\n' '{"operation":"explain","value":"llm-wiki://modules/orders","live":true,"allow_full_inventory":true}' | llm-wiki query --request - --src-dir . --wiki-dir docs/llm_wiki --helper-cache-dir .git
+```
+
+Supply exactly one `value` (exact concept locator, UID or canonical route) or
+canonical POSIX `source` path relative to `--src-dir`. A source with multiple
+concepts returns bounded choices; repeat with one exact locator to see evidence.
+The default reads the committed snapshot without extraction. Set `live:true`
+and explicitly authorize `allow_full_inventory:true` to compare against a full
+current source inventory. Existing evidence freshness includes recorded/live
+source bases, cause and bounded fresh normalization detail when available;
+snapshot reads never reconstruct historical rejected-record details.
+
+`provenance` separates stored/live producer records, the installed package
+fingerprint and version, the structural inventory contract, and active Python
+runtime. The fingerprint covers installed files and runtime/version inputs; it
+does not identify the original distribution archive or prove release authenticity.
+For a selected external extractor, existing preparation receipt source/artifact
+identities and preparation toolchain are reported separately from active runtime.
+TypeScript also checks the source copy in the prepared execution directory against
+the bundled source fingerprint; missing or changed copies require preparation again.
+Artifact fingerprints cover the receipt's recorded path. For TypeScript this is
+the `ts-morph` subtree, which does not identify sibling transitive dependencies.
+Missing or mismatched data stays explicit. Reads do not install dependencies or
+update source, wiki or helper state. Missing helpers include the existing exact
+preparation command for the selected cache; setup requires authorization, then
+retry with the same roots, source selection and cache. A runtime mismatch also
+requires selecting the matching runtime on PATH. Output limits and truncation
+disclosures apply to explanation and provenance together.
+
 External tools can use the `llm-wiki-context/v1` JSON request protocol:
 
 ```bash
@@ -1023,7 +1247,6 @@ For example, with `src/app.py` defining `limit`, save `source-task.json`:
 
 ```json
 {
-  "schema_version": "llm-wiki-task-request/v2",
   "kind": "contract-change",
   "requirements": [
     {"id": "contract", "facet": "source-contract", "selector": "app.py:limit"}
@@ -1034,7 +1257,7 @@ For example, with `src/app.py` defining `limit`, save `source-task.json`:
 
 ```bash
 llm-wiki task-context --request source-task.json --src-dir src --wiki-dir wiki
-llm-wiki task-context --request source-task.json --src-dir src --wiki-dir wiki --view compact-v1 --view-budget-tokens 32000 --canonical-output receipts/source-context.json
+llm-wiki task-context --request source-task.json --src-dir src --wiki-dir wiki --view compact --view-budget-tokens 32000 --canonical-output receipts/source-context.json
 ```
 
 Canonical text is the default. Compact delivery is opt-in and needs a separate
@@ -1043,11 +1266,11 @@ selection, tokenizer and output paths distinct. `--view-budget-tokens` chooses
 its separate presentation budget; no fixed token saving or small-budget fit is
 promised. Include the selected view once in the coding host.
 
-Use `--view compact-v2` for readable JSON containing complete selected facts,
+Use `--view compact` for the current readable JSON containing complete selected facts,
 citations, requirements, coverage, gaps and limitations. It requires the same
 explicit view budget and canonical receipt destination. Python and session
-calls select it with `schema_version: "llm-wiki-task-view-request/v2"` in
-`view_options`. Validation and expansion require the original canonical text,
+calls omit the version field in `view_options`; an omitted view object uses
+the effective host budget. Explicit `compact-v1` and `compact-v2` remain compatibility aliases. Validation and expansion require the original canonical text,
 request and view options. The body is self-contained and may be larger than
 compact-v1's encoded body. Canonical delivery remains the default.
 
@@ -1059,8 +1282,8 @@ framing, setup and any required receipt/metadata follow-ups in addition to the
 view budget; no complete-host token cap is implied by `--view-budget-tokens`.
 
 Choose `knowledge_mode: "off"` only when no native evidence is required; this
-route works without a wiki. Native v2 requirements need explicitly adopted
-sharded or packed knowledge. Keep `required` mode and the native requirements
+route works without a wiki. Native requirements use current bounded storage from bootstrap or project
+upgrade. Keep `required` mode and the native requirements
 when a read fails; a failure never authorizes bootstrap or migration.
 `snapshot` reads committed native evidence, while `selected` captures declared
 source scope. `--allow-full-inventory` permits an explicitly requested broader
@@ -2114,6 +2337,32 @@ prepared-adoption and captured-preimage retries need their explicit options.
 See [ordinary review and recovery](maintenance.md) for exact eligibility and
 Python/MCP interfaces.
 
+### Recover new pages from a rejected sync
+
+If sync emits `new_page_recovery`, retain its recovery directory and exact
+`expected_journal_hash`. Preview the pages before applying recovery:
+
+```bash
+llm-wiki maintenance recover-new-pages --wiki-dir wiki --recovery-dir RECOVERY_DIR --expected-journal-hash JOURNAL_SHA256 --dry-run
+```
+
+After reviewing the list, repeat without `--dry-run` to remove only unchanged
+Markdown pages created by that rejected operation. Their exact postimages remain
+in the recovery directory. Existing prose, source files and committed authority
+are not restored or overwritten. Edited/replaced pages, changed selection or
+authority, unsafe links, another wiki and altered journals are refused.
+
+Run the original sync again after recovery. This command does not make an
+interrupted generation current, repair missing maintenance authority, or replace
+the complete adopted recovery route above. Recovery is not atomic across pages:
+an I/O failure can leave a partially removed set, with all original postimages
+retained for explicit inspection and restoration. A missing or changed candidate
+is refused; do not blindly replay or manufacture another journal hash.
+Capture is bounded to 10,000 baseline/created-page entries, an 8 MiB journal
+and individual postimages, and 64 MiB of postimages per operation. Limits stop
+the new write rather than authorize unrecorded pages. Without an original
+rejection journal, this command cannot authorize removal of older stranded pages.
+
 ## `upgrade`
 
 Refresh framework-managed artifacts in place.