agent-wiki-cli 2.4.0__tar.gz → 3.0.0__tar.gz

{agent_wiki_cli-2.4.0/src/agent_wiki_cli.egg-info → agent_wiki_cli-3.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-wiki-cli
-Version: 2.4.0
+Version: 3.0.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.
@@ -127,8 +133,8 @@ for [Obsidian](docs/cli-reference.md#obsidian) or a
 | Go | `go/ast` | prepared helper binary |
 | Rust | `syn` | prepared helper binary |
 | Haskell | GHC parser, syntax-only inventory | prepared helper binary |
-| Docker / Compose | built-in parsers | none |
-| Runtime/config YAML | targeted built-in parsers | none |
+| Docker / Compose | Dockerfile parser / bounded YAML parser | included with the package |
+| Infrastructure / runtime YAML | structured format summaries | included with the package |
 | OpenAPI 3.0/3.1 JSON / YAML | `json` / PyYAML safe loader | included with the package |
 
 Discovery honors `.gitignore`. Use a
@@ -143,7 +149,9 @@ initialization. Every agent can use explicit sync, lint, and reviewed prompts;
 LLM Wiki does not install Git hooks.
 
 [Agent setup](docs/wiki-guide.md#agent-support) explains instruction files and
-skill export. The [MCP server](docs/cli-reference.md#mcp) provides read-only wiki
+skill export. [Workflow installation and upgrades](docs/native-agent-workflow.md#install-the-workflow-in-another-project)
+cover setup in another project, all agent targets, and the `--no-skills` inline fallback.
+The [MCP server](docs/cli-reference.md#mcp) provides read-only wiki
 access, and [bundled skills](docs/cli-reference.md#skills) guide documentation
 and analysis workflows.
 
@@ -178,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.4.0 → agent_wiki_cli-3.0.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.
@@ -90,8 +96,8 @@ for [Obsidian](docs/cli-reference.md#obsidian) or a
 | Go | `go/ast` | prepared helper binary |
 | Rust | `syn` | prepared helper binary |
 | Haskell | GHC parser, syntax-only inventory | prepared helper binary |
-| Docker / Compose | built-in parsers | none |
-| Runtime/config YAML | targeted built-in parsers | none |
+| Docker / Compose | Dockerfile parser / bounded YAML parser | included with the package |
+| Infrastructure / runtime YAML | structured format summaries | included with the package |
 | OpenAPI 3.0/3.1 JSON / YAML | `json` / PyYAML safe loader | included with the package |
 
 Discovery honors `.gitignore`. Use a
@@ -106,7 +112,9 @@ initialization. Every agent can use explicit sync, lint, and reviewed prompts;
 LLM Wiki does not install Git hooks.
 
 [Agent setup](docs/wiki-guide.md#agent-support) explains instruction files and
-skill export. The [MCP server](docs/cli-reference.md#mcp) provides read-only wiki
+skill export. [Workflow installation and upgrades](docs/native-agent-workflow.md#install-the-workflow-in-another-project)
+cover setup in another project, all agent targets, and the `--no-skills` inline fallback.
+The [MCP server](docs/cli-reference.md#mcp) provides read-only wiki
 access, and [bundled skills](docs/cli-reference.md#skills) guide documentation
 and analysis workflows.
 
@@ -141,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.4.0 → agent_wiki_cli-3.0.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.
@@ -357,15 +357,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.4.0 → agent_wiki_cli-3.0.0}/docs/cli-reference.md

@@ -126,9 +126,13 @@ dependency architecture, and manifest files. User-flow pages under `flows/` are
 generated from detected entry points with a call sequence, generated static
 `## Data flow` section, boundary-effects table, and editable `## Behavior`; use
 `--skip-flows` to omit them or `--skip-data-flow` to keep flow pages without the
-generated data-flow section. Large generated call-sequence diagrams are capped
-to the first 30 interactions and include an omitted-interaction note so Mermaid
+generated data-flow section. Large generated call-sequence diagrams select up to
+30 representative captured interactions and include an omitted-interaction note so Mermaid
 output stays readable on large repositories.
+Selection favors resolved internal continuations and distinct target coordinates,
+with captured boundary examples. Repeated sites remain in the underlying trace;
+the diagram reports display omissions separately from traversal limits and is
+not runtime execution order.
 Sequence participants distinguish same-named functions in different modules
 and calls through different receivers. A delegated call such as
 `service.check_wiki()` stays distinct from a `check_wiki` wrapper; genuine
@@ -222,6 +226,26 @@ and lifecycle changes invalidate reuse. Governed or plugin-driven generation
 uses the full path. `--rebuild-knowledge` explicitly runs the full knowledge
 builder; `--no-cache` controls source extraction independently.
 
+Eligible ordinary syncs also retain `llm-wiki-sync-analysis.json` beside the
+inventory cache. Its exact content is bound to the last complete knowledge
+commit. When source bytes, selection, generation settings, schema, implementation,
+and prepared helper identities match, a later Markdown edit can reuse static
+inventory, page maps and source graph observations. The source-derived typed
+graph is reused only when its inventory, producer, options and concept
+coordinates still match. Markdown sections, links, assets and final commitments
+are evaluated again; page ownership and required writes retain their ordinary
+checks.
+
+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
+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.
+
 `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
@@ -314,6 +338,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
@@ -533,6 +566,16 @@ 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.
 `lint --profile` and `ci-check --format json` additionally include this shape:
 
 ```json
@@ -821,6 +864,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,
@@ -999,7 +1044,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"}
@@ -1010,7 +1054,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
@@ -1019,9 +1063,24 @@ 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` 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 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.
+
+MCP `read_compact_context_session` with these v2 options retains identity,
+conditional base, state, validation scope and limitations in its smaller default
+envelope. Set `include_metadata: true` for full work/reuse telemetry; v1 retains
+its full envelope. Python session replies retain full metadata. Count host
+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
@@ -1037,6 +1096,29 @@ See [workflow recipes and limits](native-agent-workflow.md).
 
 ## Codebase source integration
 
+`llm-wiki doctor --analysis-inputs --format json` checks the installed provider's
+Python/helper classification and registered implementation files without
+scanning application source, executing code or preparing helpers. Python callers
+use `api.get_analysis_input_status(limit=20)`. The report lists bounded relative
+paths, reason, omitted counts and the registry-review route; exit 0 means the
+census/files are ready and exit 2 means unavailable. This mode is exclusive with
+`--capabilities` and explicit `--report-schema` selection. It does not establish
+runtime/helper readiness, semantic correctness or producer authority.
+
+The default and `--format text` show a readable summary with the same status,
+path and omission counts, corrective route and qualifications. Use `--format
+json` for the structured report and its schema; output format does not change
+the readiness exit policy or read scope.
+
+Provider source additions require deliberate review of
+`services/analysis_contracts.json`: classify presentation/consumer files in the
+census and observation changes in their correct producer input lists. Missing
+or unclassified inputs retain unavailable analysis. Inventory results expose
+`analysis_input_status`; affected canonical task v2 results include it in `work`
+and sync-cache misses emit the bounded diagnostic. Compact callers can inspect
+the host-owned canonical receipt. Healthy task output retains its existing
+shape; diagnostics provide information without changing source/review claims.
+
 For research or indexing systems that need codebase evidence without adopting
 the maintained wiki format, prefer the read-only source-adapter commands:
 
@@ -1919,6 +2001,15 @@ 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.
 
+Lexical-v2 uses approximate English word families for discovery while preserving
+literal page and symbol identity checks. Strong matches in diagnostic guide
+sections can also surface explicitly linked module/entity pages already in the
+captured corpus. These one-hop leads report `linked_evidence` with the guide's
+hash, section locator and target path. A link-derived candidate without its own
+text match has no fabricated matched-section location; its provenance identifies
+linked discovery. Links do not trigger network reads, source indexing or recursive
+traversal. Inspect exact source before treating any candidate as an explanation.
+
 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
@@ -1989,6 +2080,14 @@ Inspect the affected source and semantic prose; use explicit
 [ordinary review tracking](maintenance.md) when durable review is needed.
 An empty queue does not establish ordinary-review completion.
 
+On a coherent unadopted native wiki, captured source-backed semantic sections
+appear as informational coverage gaps, including after sync makes structural
+freshness current. Each item's `coverage_gaps` identifies the exact untracked
+section; `coverage_gap_bounds` reports omitted details. These candidates need
+source/prose inspection and remain untracked even after a prose correction.
+Durable pending and acknowledgment history require explicit ordinary-review
+adoption.
+
 ## `maintenance`
 
 Ordinary review tracking is optional and independent of human governance and

{agent_wiki_cli-2.4.0 → agent_wiki_cli-3.0.0}/docs/native-agent-workflow.md

@@ -1,21 +1,146 @@
 # Native coding workflow
 
-Use a provider whose CLI and Python API expose the task request, storage and
-optional delivery interfaces you select. Check `llm-wiki task-context --help`
-and `llm-wiki knowledge migrate --help` in each environment; a version number
-alone does not establish support for every format.
-
-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.
-
-Prefer task request v2 for compatible integrations. Canonical delivery stays
-the default; compact views, sessions and source-augmented discovery are explicit
-choices with their own limits and costs.
+Initialized projects receive a default development procedure through their
+managed agent instructions: define acceptance criteria, gather scoped evidence,
+inspect source, make bounded changes, verify independently, refresh affected
+knowledge, and preserve a qualified handoff. The managed
+`wiki-reference/references/development-workflow.md` topic owns that procedure;
+expanded instructions retain it when skills are disabled or unavailable.
+Package installation ships the reference; `llm-wiki init` establishes the
+project instructions, and `llm-wiki upgrade` refreshes them after a package update.
+
+The library selects current data and workflow contracts. Normal task and compact
+view requests omit version fields. Bootstrap creates compressed packed knowledge
+and indexed ordinary maintenance ownership; project upgrade brings valid older
+snapshots forward with recovery preimages. Review starts pending and never
+implies human approval. Readers never migrate or repair data.
+
+Canonical delivery stays the default. Compact delivery, session reuse and source
+indexing remain explicit behavior choices with their own bounds and costs. MCP
+session tools are available by default; opening a session is still explicit.
+Workflow profiles, human governance, application execution and Git actions keep
+their existing authorization requirements. Older explicit contracts remain
+available for integrations that require compatibility.
 
 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.
+publish.
+
+## Install the workflow in another project
+
+Run the following commands from the target project's root, using its own
+Python 3.10+ virtual environment at `.venv/`. Package installation supplies the
+CLI and bundled workflow; initialization writes the project-specific agent
+instructions and wiki scaffold.
+
+For a released package that includes the default development workflow:
+
+```bash
+.venv/bin/pip install agent-wiki-cli
+.venv/bin/llm-wiki init --agent generic
+```
+
+To use a source checkout, including changes that have not been published,
+install that checkout instead. Replace the quoted path with its absolute
+location; keep running commands from the target project:
+
+```bash
+.venv/bin/pip install "/absolute/path/python-wiki-llm"
+.venv/bin/llm-wiki init --agent generic
+```
+
+Choose the agent's instruction format with `--agent`:
+
+| Agent target | Project instruction file | Managed reference directory |
+|---|---|---|
+| `generic` | `AGENTS.md` | `.llm-wiki/skills/wiki-reference/` |
+| `claude` | `CLAUDE.md` | `.claude/skills/wiki-reference/` |
+| `cursor` | `.cursorrules` | `.llm-wiki/skills/wiki-reference/` |
+| `copilot` | `.github/copilot-instructions.md` | `.llm-wiki/skills/wiki-reference/` |
+| `aider` | `.aider.conf.yml` | `.llm-wiki/skills/wiki-reference/` |
+| `opencode` | `.opencode/instructions.md` | `.llm-wiki/skills/wiki-reference/` |
+
+Use `generic` for Codex or another agent that reads `AGENTS.md`. Initialization
+preserves existing user instructions outside the managed block and installs
+`references/development-workflow.md` within the managed reference directory.
+Start a new agent session, or reload its project instructions, so it reads the
+workflow. The default procedure is available without separately installing the
+optional `native-coding` skill.
+
+The default wiki scaffold is `docs/llm_wiki/`. To choose another location, pass
+`--wiki-dir .wiki` to initialization and keep that same path in subsequent
+commands. Initialization creates the scaffold; bootstrap populates the wiki
+from the project's sources:
+
+```bash
+.venv/bin/llm-wiki bootstrap --src-dir . --wiki-dir docs/llm_wiki
+```
+
+Use the actual source root and configured source selection. For languages that
+need extractor helpers, install the relevant toolchain and explicitly prepare
+the helpers with `init --prepare-extractors` or
+`llm-wiki prepare-extractors --src-dir .`; see
+[helper setup](cli-reference.md#prepare-extractors). Source-only task evidence
+can be used before bootstrap, following the [source-only route](#source-only-task-without-a-wiki).
+
+### Use the inline fallback
+
+For an agent or project that needs instructions in a single file, skip the
+managed reference installation:
+
+```bash
+.venv/bin/llm-wiki init --agent generic --no-skills
+```
+
+This writes expanded, self-contained instructions, including the development
+procedure, into the selected agent instruction file. It records the preference
+for later initialization and upgrades. An existing reference directory is
+preserved, and read-only context interfaces remain available. Initialization
+and upgrade also use expanded instructions when the managed reference is
+unavailable or cannot be verified current.
+
+### Upgrade an initialized project
+
+Update the package in the target project's environment, then refresh its
+managed instructions from that project's root:
+
+```bash
+.venv/bin/pip install --upgrade agent-wiki-cli
+.venv/bin/llm-wiki upgrade
+```
+
+For a source checkout, replace the package update command with
+`.venv/bin/pip install --upgrade "/absolute/path/python-wiki-llm"`. Package
+updates alone do not refresh project instructions or migrate project data. For a custom wiki location,
+use `.venv/bin/llm-wiki upgrade --wiki-dir .wiki`.
+
+Upgrade selects current storage formats and workflow contracts automatically.
+It preserves authored Markdown and existing governance, retains complete recovery
+preimages and prints their locations. Preserve those copies until the upgraded
+project is accepted. Damaged or unsupported authority requires recovery rather
+than automatic reseeding. Use `--src-dir src` when the source root is `src`, and
+carry the configured helper cache and source selection through setup.
+
+Upgrade retains the configured agent, source-selection preference and skills
+preference unless explicitly overridden. It refreshes the managed instruction
+block, reference topics and missing scaffold structure while preserving user
+instructions outside the managed block and existing wiki prose. When references
+are enabled, expected managed topic files are replaced even if edited locally;
+keep project-specific rules outside that tree or back up edits before upgrading.
+Conflicting or unsafe entries are preserved and reported. See the
+[managed skills lifecycle](cli-reference.md#skills) for recovery details.
+
+To change the instruction format, use `upgrade --agent claude` or another
+supported target. To change the skills preference explicitly:
+
+```bash
+.venv/bin/llm-wiki upgrade --no-skills
+.venv/bin/llm-wiki upgrade --skills
+```
+
+The first command selects inline instructions; the second restores managed
+references and compact routing when verification succeeds. Choose the command
+for your desired mode, then reload the agent's project instructions.
 
 ## Choose an interface
 
@@ -48,7 +173,7 @@ candidates and require exact inspection before a coding decision.
 Source text indexing is an explicit read and cost choice:
 
 ```bash
-llm-wiki search "retry failure" --src-dir src --wiki-dir wiki --mode ranked-v2 --include-source
+llm-wiki search "retry failure" --src-dir src --wiki-dir wiki --include-source
 ```
 
 It requires a valid committed manifest and indexes only its mapped module sources
@@ -105,7 +230,6 @@ Save this request as `source-task.json` outside `src`:
 
 ```json
 {
-  "schema_version": "llm-wiki-task-request/v2",
   "kind": "contract-change",
   "requirements": [
     {"id": "contract", "facet": "source-contract", "selector": "app.py:limit"}
@@ -139,47 +263,36 @@ Use your actual source root, configured selection and exact declaration instead
 of the example paths. Reads do not create the source file, install helpers or
 run the target project. One direct source read can be simpler for a tiny task.
 
-## Native task with explicit storage adoption
+<a id="native-task-with-explicit-storage-adoption"></a>
+
+## Native task with current storage
 
 Choose this route when a requirement needs committed concepts, semantic
-sections or typed relationships. For a new wiki, explicitly select bounded
-storage during authorized bootstrap:
+sections or typed relationships. Authorized bootstrap selects current bounded
+storage without a format argument:
 
 ```bash
-llm-wiki bootstrap --src-dir src --wiki-dir wiki --knowledge-format sharded-v2
+llm-wiki bootstrap --src-dir src --wiki-dir wiki
 ```
 
-For an existing flat wiki, keep its current pages and complete snapshot. A task
-v2 native read requires sharded or packed knowledge storage; a flat rejection
-does not authorize migration.
-
-For a captured valid flat model, the task CLI returns exit 2 with
-`error.details.reason: "flat-native-adoption-required"` and an authorized
-migration-preview next action. This identifies the storage prerequisite; it
-does not audit the complete snapshot. Unknown or damaged roots receive no
-adoption hint. Migration validates companion authority before applying.
-
-With migration authorized, preview and apply it using an empty recovery directory
-outside both `src` and `wiki`:
+For an existing project, update the package in every reader/writer environment,
+then run the authorized project upgrade with its actual roots:
 
 ```bash
-llm-wiki knowledge migrate --wiki-dir wiki --to sharded-v2 --dry-run --recovery-dir storage-recovery
-llm-wiki knowledge migrate --wiki-dir wiki --to sharded-v2 --recovery-dir storage-recovery
+llm-wiki upgrade --src-dir src --wiki-dir wiki
 llm-wiki knowledge storage-check --wiki-dir wiki --full
-llm-wiki knowledge inspect-storage --wiki-dir wiki --selector page:modules/app.md --limit 10
 llm-wiki doctor --capabilities --src-dir src --wiki-dir wiki --format json
 ```
 
-Dry-run does not write a recovery snapshot. Apply retains the prior snapshot;
-`storage-check --full` audits the result. Capability output can identify helper
-or producer prerequisites; resolve those only with setup authorization. Upgrade
-all readers and writers to support the selected schema before adoption.
+Upgrade chooses current formats and reports complete recovery locations. An
+explicit compatibility-format migration remains available through
+[knowledge storage](knowledge-storage.md). Missing, damaged or unsupported
+committed authority requires recovery; a failed read never authorizes migration.
 
 Save this native snapshot request as `native-task.json`:
 
 ```json
 {
-  "schema_version": "llm-wiki-task-request/v2",
   "requirements": [
     {"id": "concept", "facet": "concept", "selector": "llm-wiki://modules/app"}
   ],
@@ -209,8 +322,8 @@ refuses unrelated root edits, changed Markdown authority or newer committed
 work. Restore an authorized matching complete snapshot when that eligibility
 check fails; do not force a replacement.
 
-Storage adoption is separate from optional
-[ordinary review tracking](maintenance.md). A
+Current bootstrap and upgrade also establish pending
+[ordinary review tracking](maintenance.md), separate from human governance. A
 `.llm-wiki-maintenance-adoption.json` marker requires its matching maintenance
 owner. Restore missing or corrupt adopted authority through the complete
 [maintenance recovery route](maintenance.md#recover-complete-authority) before
@@ -312,7 +425,7 @@ Save the full canonical receipt outside the source and wiki trees and away
 from the request, profile, tokenizer and selection files:
 
 ```bash
-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
 ```
 
 The compact view goes to stdout. Add `--output views/source-context.json` for a
@@ -322,7 +435,7 @@ are rejected. A canonical receipt is host custody, not permission to include
 both representations in the model prompt.
 
 ```python
-view_options = {"schema_version": "llm-wiki-task-view-request/v1", "budget_tokens": 32000}
+view_options = {"budget_tokens": 32000}
 view = api.build_compact_task_context(
     request, view_options=view_options, src_dir="src", wiki_dir="wiki"
 )
@@ -348,8 +461,9 @@ with the compact view can cost more than canonical output alone.
 
 ## 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
+The budgeted MCP tool uses the current context contract when `protocol` is
+omitted. It requires `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.
 
@@ -389,7 +503,7 @@ 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
+MCP sessions are available by default; `--disable-sessions` removes their tools. 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