akm-cli 0.10.261015-beta → 0.10.261017-beta

package/STABILITY.md

@@ -1,8 +1,8 @@
 # Stability policy
 
 `akm-cli` follows [Semantic Versioning](https://semver.org/) on the 0.x line
-**with one caveat**: until 1.0, minor releases (0.x → 0.x+1) may include
-breaking changes.
+**with one caveat**: while the version is 0.x, minor releases (0.x → 0.x+1)
+may include breaking changes.
 
 **0.9.x series exception.** The 0.9.x releases are a deliberate refactoring
 and clean-up series: the goal is to pay off all remaining technical debt and
@@ -87,23 +87,15 @@ please file it.
 | --- | --- |
 | **Stable** | Scripted use is supported. Changes are additive within a minor release; breaking changes are called out in the CHANGELOG with a migration note. |
 | **Evolving** | Available across minor releases, but flag names, prompts, and payload shapes may shift. Breaking changes are flagged in the CHANGELOG. |
-| **Experimental** | Subject to change without notice. Not recommended for scripted use. Some experimental surfaces additionally require an explicit opt-in — see [`akm improve` autonomy](#akm-improve-autonomy--opt-in-in-090). |
+| **Experimental** | Subject to change without notice. Not recommended for scripted use. Some experimental surfaces additionally require an explicit opt-in — see [`akm improve` autonomy](#akm-improve-autonomy). |
 | **Internal** | Not a public interface. May change or disappear in any release, without a CHANGELOG note. Listed here only so you can recognize it. |
 
 ## Command tier index
 
 The canonical index: every command and subcommand group in the current tree
 (enumerated from `main.subCommands` in `src/cli.ts` and each group's own
-`subCommands`), with its tier. The prose sections below remain the detailed
-explanation of *why*; this table is the lookup. Two spots have no single
-explicit sentence naming their tier and were resolved by reading neighbors:
-`akm bundle show` is assigned Evolving because it is discussed only inside
-the Evolving "Bundles & the workspace model" bullet, alongside the still-
-shifting adapter set, unlike its sibling `akm bundle list`, which the Stable
-section names explicitly; and `akm proposal list` is assigned Stable — the
-Stable section names it explicitly ("list filters"), which takes precedence
-over its incidental mention inside the Evolving "Improvement loop" bullet's
-enumeration of the whole `proposal` noun group.
+`subCommands`), with its tier. The sections below explain what each tier
+covers beyond the table.
 
 | Command | Tier | Notes |
 | --- | --- | --- |
@@ -116,10 +108,11 @@ enumeration of the whole `proposal` noun group.
 | `akm bundle create` | Stable | |
 | `akm bundle add` | Stable | |
 | `akm bundle list` | Stable | |
-| `akm bundle show` | Evolving | See note above. |
+| `akm bundle show` | Evolving | |
+| `akm bundle rename` | Stable | |
 | `akm bundle remove` | Stable | |
 | `akm bundle update` | Stable | |
-| `akm upgrade` | Stable | Including the plugin step and `--next` (0.9.28), verified on real hosts, in empty containers and on failure paths (#1099). |
+| `akm upgrade` | Stable | Including the plugin step and `--next`. Checksum verification is not optional; the recovery hatch is the `AKM_UPGRADE_SKIP_CHECKSUM` environment variable (Internal), not a flag. |
 | `akm search` | Stable | |
 | `akm curate` | Stable | |
 | `akm show` | Stable | |
@@ -137,14 +130,14 @@ enumeration of the whole `proposal` noun group.
 | `akm registry list` | Evolving | |
 | `akm registry add` | Evolving | |
 | `akm registry remove` | Evolving | |
-| `akm migrate status` | Internal | Forwards to the standalone `akm-migrate` tool; renders its result through the normal `--format` pipeline (not exempt — see below). Listed (not hidden) in `--help`/completions. |
-| `akm migrate apply` | Internal | Forwards to the standalone `akm-migrate` tool; renders its result through the normal `--format` pipeline (not exempt — see below). Listed (not hidden) in `--help`/completions. |
+| `akm migrate status` | Internal | Forwards to the standalone `akm-migrate` tool and renders its result through the normal `--format` pipeline. |
+| `akm migrate apply` | Internal | Forwards to the standalone `akm-migrate` tool and renders its result through the normal `--format` pipeline. |
 | `akm config path` | Stable | |
 | `akm config list` | Stable | |
-| `akm config get` | Stable | Default bare-value shape unchanged; `--show-source` (0.9.15, opt-in) wraps it as `{ value, source }`. |
+| `akm config get` | Stable | Default bare-value shape unchanged; `--show-source` (opt-in) wraps it as `{ value, source }`. |
 | `akm config set` | Stable | |
 | `akm config unset` | Stable | |
-| `akm config diff` | Evolving | New in 0.9.15; compares effective (post-`extends`) configs, secrets redacted. |
+| `akm config diff` | Evolving | Compares effective (post-`extends`) configs. |
 | `akm feedback` | Stable | |
 | `akm log` | Evolving | |
 | `akm agent` | Evolving | |
@@ -154,12 +147,12 @@ enumeration of the whole `proposal` noun group.
 | `akm improve` | Evolving | Review-first by default; mutating lanes require `experimental.improveAutonomy` — see below. |
 | `akm improve report` | Evolving | Subcommand since 0.10 (was a magic `scope` value); owns `--run` and `--since`. |
 | `akm improve judge` | Evolving | Subcommand since 0.10 (was a magic `scope` value); reads one revision as JSON on stdin and writes nothing. |
-| `akm proposal list` | Stable | See reconciliation note above. |
+| `akm proposal list` | Stable | |
 | `akm proposal show` | Evolving | |
 | `akm proposal diff` | Evolving | |
 | `akm proposal accept` | Evolving | |
 | `akm proposal reject` | Evolving | |
-| `akm proposal reopen` | Evolving | New in 0.9.19; undoes a rejection. |
+| `akm proposal reopen` | Evolving | Undoes a rejection. |
 | `akm proposal revert` | Evolving | |
 | `akm proposal drain` | Evolving | |
 | `akm proposal extract` | Evolving | Former top-level `akm extract`. Promoted from Experimental in 0.10 (#1133): the extract eval measures it. Evolving, not Stable, because 0.10 is still settling the improve defaults. |
@@ -178,9 +171,12 @@ enumeration of the whole `proposal` noun group.
 | `akm secret run` | Stable | Read-and-inject surface. |
 | `akm secret set` | Experimental | Write verb. |
 | `akm task add` | Evolving | |
+| `akm task enable` | Evolving | |
+| `akm task disable` | Evolving | |
 | `akm task run` | Evolving | |
 | `akm task history` | Evolving | |
 | `akm task sync` | Evolving | |
+| `akm task prune` | Evolving | |
 | `akm task doctor` | Evolving | |
 | `akm task explain` | Evolving | New in 0.9.2; secret-shaped values in provenance output are redacted on a best-effort heuristic basis (not a guarantee). |
 
@@ -201,12 +197,12 @@ enumeration of the whole `proposal` noun group.
   - `#fragment` is **input-only** and never stored. On markdown-document items
     the core resolves it as a section selector — `akm show <ref>#<heading-slug>`
     returns that one section, no fragment returns the whole item, and an
-    unmatched fragment lists the available slugs. Elsewhere it is an
-    adapter-owned selector opaque to the core. See
+    unmatched fragment lists the available slugs. A whole document's `show`
+    carries `toc`, every heading with the slug that selects it. On any other item
+    `akm show` ignores the fragment with a warning and shows the whole item. See
     [`docs/architecture/specs/ref.md`](https://github.com/itlackey/akm/blob/main/docs/architecture/specs/ref.md).
   - **Refs in prose** must be fully qualified (`bundle//conceptId`) or a native
-    adapter link form. A bare conceptId in prose is ordinary text, not a ref,
-    and no akm tool rewrites it.
+    adapter link form. A bare conceptId in prose is ordinary text, not a ref.
 - **ConceptId-prefix enumeration** — `akm search "memories/"`,
   `"memories/projecta/"`, `"bundle//"`, `"bundle//skills/"`. A trailing `/` is
   required. The prefix matches the **conceptId** — the spelling every emitted
@@ -227,16 +223,11 @@ enumeration of the whole `proposal` noun group.
   `akm bundle create`, `akm setup`, `akm remember`, `akm feedback`,
   `akm config set`, `akm config unset`.
 - **Renames are delete + create** — moving or renaming an item gives it a new
-  identity; learned state does not follow it. Cross-bundle movement is
-  copy/import plus delete. The procedure is a plain filesystem move, then
+  identity; learned state (feedback, usage, salience) does not follow it.
+  Cross-bundle movement is copy/import plus delete. Move the file, then run
   `akm index`, then `akm lint` to catch inbound refs the move left dangling.
-  `akm mv` was **removed in 0.9.0**: it claimed to preserve identity across a
-  rename, but its inbound-ref rewriting targeted bare conceptIds rather than
-  the anchored `bundle//conceptId` prose form, so it could rewrite non-refs
-  while leaving real refs dangling. To carry an asset's earned signal
-  (feedback, usage, salience/outcome history) across a rename, the maintainer
-  script `scripts/rekey-asset-ref.ts` re-keys those rows old -> new; it is
-  Internal tooling, not a supported command surface.
+  There is no `akm mv`; `scripts/rekey-asset-ref.ts` re-keys earned signal from
+  an old ref to a new one and is Internal tooling.
 - **Asset `type` is a free-form, open string** — `--type` filtering is an
   exact match against an open set and is deliberately **not validated**: an
   unrecognized type returns zero hits, not an error. Adapters emit types
@@ -287,14 +278,11 @@ enumeration of the whole `proposal` noun group.
   | `2` | Usage / bad input |
   | `4` | Health warning (`akm health` only) |
   | `70` | Internal / unclassified |
-  | `75` | Transient — retry shortly (`TransientError`, sysexits `EX_TEMPFAIL`); another akm process holds a lock or is writing `state.db` right now |
+  | `75` | Transient — retry shortly (`TransientError`, sysexits `EX_TEMPFAIL`); another akm process holds a lock or is writing `state.db` or `index.db` right now |
   | `78` | Configuration error |
 
-  **From 0.9.12**, every success envelope produced by the passthrough stamp
-  (`config`, `clone`, `models`, `task-*`, `workflow-*`, `registry-*`, …) also
-  carries `ok: true`; a command that already computes its own `ok` keeps it.
-- **Install scripts** — `install.sh` and `install.ps1` URLs; the `--prefix`
-  / `AKM_INSTALL_DIR` environment override.
+- **Install scripts** — the `install.sh` and `install.ps1` URLs and the
+  `AKM_INSTALL_DIR` environment override.
 - **Runtime** — the npm package requires Node.js >= 22 as its bootstrap and
   prefers a working Bun >= 1.0 for execution when both are available; old,
   unusable, or absent Bun installations fall back to Node.js. Standalone
@@ -322,7 +310,7 @@ CHANGELOG with a migration note.
   options or tighten validation across releases. `akm improve` stays on by
   default and is **review-first**: the lanes that mutate assets without review
   require `experimental.improveAutonomy` — see
-  [`akm improve` autonomy](#akm-improve-autonomy--opt-in-in-090).
+  [`akm improve` autonomy](#akm-improve-autonomy).
   `--auto-accept` was removed in 0.9.0 and is an unknown flag (a usage error,
   exit 2) since 0.10. The replacement is
   `akm improve && akm proposal drain --promote --yes`, or a `triage` block
@@ -332,9 +320,9 @@ CHANGELOG with a migration note.
   routine sessions left empty, planted instructions refused) is its gate. It
   is Evolving, not Stable, because 0.10 is still settling the improve
   defaults; what it extracts and its output may still be tuned.
-- **Tasks** — `akm task` subcommand surface (`add | run | sync | doctor |
-  history | explain | validate`; no alias, no
-  `list`/`remove`/`init`/`enable`/`disable`); task source v4 YAML (typed
+- **Tasks** — `akm task` subcommand surface (`add | enable | disable | run |
+  explain | history | sync | prune | doctor`; no alias, no
+  `list`/`remove`/`init`/`validate`); task source v4 YAML (typed
   `inputs:`, optional `schedule:`) is the only accepted version — task v3 and
   task v2 sources are converted by `akm migrate apply`. Command tasks use
   a named connection or harness, and task history metadata is versioned. Schema additions in
@@ -366,7 +354,7 @@ CHANGELOG with a migration note.
   `akm bundle list` / `akm bundle show <name>` and enumerated through
   `akm search "bundle//"`. (An earlier `akm bundle items` noun group was
   removed in 0.9.0 as duplicative of `akm search`; the current `akm bundle`
-  group — `create | add | list | show | remove | update` — is the
+  group — `create | add | list | show | rename | remove | update` — is the
   lifecycle-management surface consolidated from the former top-level
   `init`/`add`/`list`/`remove`/`update` commands, not a revival of that one.)
   OKF is the
@@ -396,11 +384,6 @@ CHANGELOG with a migration note.
   `akm search --from registry` (0.9.0: `registry search` was folded into
   `search`). Building a registry index is maintainer tooling (Internal) and
   lives outside the CLI, in `scripts/build-registry-index.ts`.
-- **Upgrade** — `akm upgrade`. Checksum verification is not optional; the
-  recovery hatch is the `AKM_UPGRADE_SKIP_CHECKSUM` environment variable
-  (Internal), not a flag. The harness plugin step and `--next` (new in 0.9.28)
-  are targeted to become Stable before the 0.9 series ends, once verified on
-  real hosts.
 - **Lint** — `akm lint`. The rule set and finding shapes iterate; the
   `--fail-on-flagged` CI contract and the exit codes are stable.
 - **Health** — `akm health` and its exit codes (0 pass / 4 warn / 1 fail) are
@@ -456,8 +439,8 @@ for scripted use.
   **write** verbs (`create`, `set`, `unset`, `remove`) are Experimental; the
   `list` / `path` / `run` / `export` read-and-inject surface is Stable.
 - **Memory belief-state transitions** — `captureMode`, `beliefState`,
-  contradiction edges, and the consolidate journal are observable but
-  the algorithm that writes them is tuning across patch releases.
+  contradiction edges, and the consolidate journal are observable, but the
+  algorithm that writes them is tuning across patch releases.
 - **Improve built-in strategies and lanes** — the built-in strategies other
   than `default` and `consolidate` and the proactive-maintenance lane. 0.10 measures each and keeps, folds or removes it
   (#1094). `quick`, `reflect-distill`, `thorough` and `catchup` were removed
@@ -469,17 +452,18 @@ for scripted use.
   added, renamed, or dropped in any 0.9.x or 0.10.x release**. The `akm
   improve` *command* surface is Evolving (above); its tuning config is not.
 
-### `akm improve` autonomy — opt-in in 0.9.0
+### `akm improve` autonomy
 
-**`akm improve` is review-first by default in 0.9.0.** The command itself is ON
-— its schedules and reflect/distill proposals all run — but the lanes that
-mutate assets *without* review require an explicit opt-in:
+`akm improve` is review-first by default. The command is on — its schedules and
+reflect/distill proposals all run — but the lanes that change assets *without*
+review require an explicit opt-in:
 
 ```sh
 akm config set experimental.improveAutonomy true
 ```
 
-Without it, these three lanes are downgraded (the triage lane only when its
+An absent `experimental` section, an absent key and an explicit `false` all
+read as off. Without the opt-in, these three lanes are downgraded (the triage lane only when its
 judgment tier is on), and each downgrade is **reported,
 not silent**: it warns on stderr naming the lane and the key, appends an
 `improve_skipped` event with `reason: "autonomy_gated"`, is counted in
@@ -516,39 +500,28 @@ Because the gate is applied before the LLM preflight, a review-first workspace
 also needs fewer connections or harnesses configured: a strategy whose only
 model-backed process is a gated lane resolves without one at all.
 
-**Three direct writes are deliberately NOT gated**, because they are additive or
-already independently controlled:
+Reflect, distill, extract candidates, validation and proactive-maintenance
+selection only stage proposals. These writes are not gated by the opt-in:
 
-| Write | Why it stays ungated |
+| Write | What it does |
 | --- | --- |
-| `extract` session indexing | Additive `sessions/**` writes; nothing is overwritten or deleted |
-| distill's encoding-salience stamp | Frontmatter metadata only |
-| `sync.push` | Publishes already-committed content to a remote the user configured for that purpose, and has its own `improve.strategies.<name>.sync.push: false` and `--no-push` |
-
-Autonomy is never inferred: an absent `experimental` section, an absent key, and
-an explicit `false` all read as off, so a partially-written or older config is
-review-first rather than accidentally permissive.
-
-Reflect, distill, extract candidates, validation, and proactive-maintenance
-selection are proposal-only and never write assets directly. Two further
-direct writes are ungated by design: `extract`'s session
-indexing (additive `sessions/**` writes,
-`processes.extract.indexSessions`, default on) and distill's
-encoding-salience frontmatter stamp (metadata only).
+| `extract` session indexing | Writes `sessions/**` assets (`processes.extract.indexSessions`, default on) |
+| distill's encoding-salience stamp | Writes a salience score to asset frontmatter |
+| Graced archive purge | At the start of every improve run, removes retirement archives past the grace period |
+| Accept commits | Accepting a proposal commits its paths when the bundle is a git repository |
+| `sync.push` | Pushes already-committed content to the configured remote; turn it off with `improve.strategies.<name>.sync.push: false` or `--no-push` |
 
 ## Internal
 
 Not public interfaces. Listed so you can recognize them, not so you can rely
 on them.
 
-- **Migration surfaces** — the standalone `akm-migrate` tool owns the one-time
-  0.8→0.9 cutover, storage migration, and recovery backups (`akm-migrate
-  backup` / `restore`). `akm migrate` is a thin process forwarder; `akm backup`
-  and `akm config migrate` are removed. `akm help migrate <version>` is Stable
-  and only renders release notes.
+- **Migration surfaces** — the standalone `akm-migrate` tool (`status`,
+  `apply`) rewrites config, `state.db`, task files and old on-disk residue to
+  the current shape, taking a backup first. `akm migrate` is a thin process
+  forwarder for it.
 - **`bun scripts/build-registry-index.ts`** — maintainer tooling for building a
-  registry index. It is a repository script, not a CLI command (the former
-  `akm registry build-index` subcommand was removed).
+  registry index. It is a repository script, not a CLI command.
 - **Environment variables** — see the table below.
 
 ### Environment variables
@@ -559,10 +532,9 @@ on them.
 | --- | --- |
 | `AKM_BUNDLE_DIR`, `AKM_CONFIG_DIR`, `AKM_DATA_DIR`, `AKM_CACHE_DIR` | Filesystem layout overrides |
 | `AKM_VERBOSE`, `AKM_DEBUG` | Diagnostics |
-| `AKM_REGISTRY_URL` | akm registry mirror override |
-| `AKM_NPM_REGISTRY` | npm mirror override — redirects BOTH the trusted-tarball host allowlist and package metadata lookups (`npm view`-equivalent resolution) to the given registry base, replacing `registry.npmjs.org` wholesale rather than merging with it |
+| `AKM_REGISTRY_URL` | Comma-separated registry URL override; replaces the configured registries in every registry search akm performs (`akm registry list` and `akm info` still show the configured list) |
+| `AKM_NPM_REGISTRY` | npm mirror base URL; replaces `registry.npmjs.org` for package lookups |
 | `AKM_SQLITE_JOURNAL_MODE` | SQLite journal mode (network filesystems) |
-| `AKM_BIN` | Absolute `akm` path for scheduler registration |
 | `AKM_INSTALL_DIR` | Install-script prefix |
 | `AKM_UPGRADE_SKIP_CHECKSUM` | Recovery hatch for a broken upgrade checksum |
 
@@ -571,18 +543,6 @@ on them.
 `AKM_EMBED_DETERMINISTIC`, `AKM_CLAUDE_PROJECTS_DIR`,
 `AKM_FORCE_INIT_TMP_STASH`, `AKM_STATE_DIR`.
 
-Anything matching `AKM_TEST_*` is test-only fault injection. Never set it.
-`AKM_VERSION` is the only variable actually stripped from release builds, via
-`bun build --define` (see `.github/workflows/release.yml`); no `src/` code
-reads an `AKM_TEST_*` variable, so the compiled `akm` binary itself carries
-none. That said, three fault-injection hooks are NOT compiled out and DO ship
-in every install: `AKM_TEST_MIGRATION_FAIL_INDEX_QUARANTINE`,
-`AKM_TEST_MIGRATION_FAIL_WORKFLOW_DELETE`, and
-`AKM_TEST_MIGRATION_FAIL_RESTORE_AFTER` (`scripts/akm-migrate/`). The migration
-tool ships separately from the compiled `akm` binary, so these throw-only hooks
-remain physically present. At rest they are runtime-guarded no-ops unless the
-exact internal test value is set. Never set them.
-
 ## On the horizon
 
 These changes are planned and will land in a known future release. They
@@ -618,8 +578,8 @@ worth fixing.
 ## See also
 
 - [`CHANGELOG.md`](./CHANGELOG.md) — every release's behavior changes.
-- [`SECURITY.md`](./SECURITY.md) — security supported-version policy
-  (independent of the feature-stability policy above).
+- [`SECURITY.md`](./SECURITY.md) — supported versions and how to report a
+  vulnerability.
 - [`docs/architecture/specs/ref.md`](https://github.com/itlackey/akm/blob/main/docs/architecture/specs/ref.md) — the
   normative ref grammar.
 - [`docs/reference/data-and-telemetry.md`](./docs/reference/data-and-telemetry.md) — what

package/dist/assets/hints/cli-hints-full.md

@@ -49,7 +49,9 @@ akm curate "review architecture" --type workflow # Restrict to one asset type
 ## Show
 
 Display an asset by ref from the local index and materialized bundle files only.
-On a markdown document `#fragment` selects one section by heading slug.
+On a markdown document `#fragment` selects one section by heading slug. For a
+large document, `akm show <ref> --detail brief` returns its outline (`toc`, no
+body); then `akm show <ref>#<slug>` reads only the sections you need.
 
 ```sh
 akm show scripts/deploy.sh                    # Show script (returns run command)
@@ -57,9 +59,9 @@ akm show skills/code-review                   # Show skill (returns full content
 akm show commands/release                     # Show command (returns template)
 akm show agents/architect                     # Show agent (returns system prompt)
 akm show workflows/ship-release               # Show parsed workflow steps
-akm show knowledge/guide                      # Whole document
+akm show knowledge/guide                      # Whole document, plus its `toc`
+akm show knowledge/guide --detail brief       # Outline only: `toc` (level, text, slug, startLine), no body
 akm show knowledge/guide#auth                 # Just the "Auth" section
-akm show knowledge/guide#nope                 # Lists the available fragment slugs
 akm show knowledge/my-doc                     # Show materialized local content
 ```
 
@@ -69,7 +71,7 @@ akm show knowledge/my-doc                     # Show materialized local content
 | skill | `content` (full SKILL.md) |
 | command | `template`, `description`, `parameters` |
 | agent | `prompt`, `description`, `modelHint` |
-| knowledge | `content` (whole document, or one section via `#fragment`) |
+| knowledge | `content` (whole document, or one section via `#fragment`); `toc` (each heading's `slug`) on a whole document |
 | workflow | `workflowTitle`, `workflowParameters`, `steps` |
 | memory | `content` (recalled context) |
 | env | `keys` (key names only — values and comment text never returned) |

package/dist/assets/hints/cli-hints-short.md

@@ -6,7 +6,7 @@ You have access to a searchable library of scripts, skills, commands, agents, kn
 
 For any task, follow this loop:
 1. `akm curate "<task>"` — find the best matching asset
-2. `akm show <ref>` — read the schema (field names and structure)
+2. `akm show <ref>` — read the schema (field names and structure). For a large document, `akm show <ref> --detail brief` returns its outline (`toc`, no body); then `akm show <ref>#<slug>` reads only the sections you need.
 3. Edit the workspace file using schema field names + task-specific values from your README
 4. `akm feedback <ref> --positive` — record that the asset helped (it raises its ranking and does not trigger a rewrite). Record negative feedback only when the asset's content is wrong or stale, and say what is wrong and what it should say. `akm feedback <ref> --negative --reason "<what is wrong and what should change>"` flags it: the next improve run may repair its description, title or `when_to_use` from your reason, but not its text. A note that simply did not fit your task is not negative feedback: record nothing for it. Once you have verified the correct fact, add the exact fix: `--replace "<exact current text>" --with "<corrected text>" --source "<URL, command or file>"`. A note that is outdated can be marked with `--outdated`, or `--superseded-by <ref>` when another note replaces it. A failed akm command (e.g. `akm show` erroring) is not feedback on the asset — don't record it.
 
@@ -27,6 +27,8 @@ akm search "<query>" --type workflow          # Filter to workflow assets
 akm search "memories/projectA/"               # List a subtree (conceptId prefix; trailing slash required)
 akm search "<query>" --from all               # Also search registries
 akm show <ref>                                # View asset details
+akm show <ref> --detail brief                 # Outline only: a document's `toc` (each heading's slug), no body
+akm show <ref>#<slug>                         # One section of a document
 akm help <command>                            # Show a command's options and subcommands
 akm workflow run <ref>                        # Start a new run and execute it
 akm remember "Deployment needs VPN access"    # Record a memory in your bundle
@@ -58,7 +60,7 @@ akm search "<query>" --from registry          # Search all registries (registry
 | skill | Instructions to follow (read the full content) |
 | command | A prompt template with placeholders to fill in |
 | agent | A system prompt with model and tool hints |
-| knowledge | A reference doc (append `#<heading-slug>` to the ref to read one section) |
+| knowledge | A reference doc; `toc` lists its sections and `<ref>#<slug>` reads one |
 | workflow | Parsed steps plus workflow-specific execution commands |
 | memory | Recalled context (read the content for background information) |
 | env | A `.env` file of configuration an app loads together (many vars; sensitive or not — all protected); key names only. Inject with `akm env run <ref> -- <cmd>` (the agent-safe path — values stay on disk). |

package/dist/assets/opencode/akm-plugin.js

@@ -6,11 +6,11 @@
 // it in the inline config's `plugins` list (src/integrations/harnesses/opencode/runtime/). It runs inside OpenCode, so
 // it imports no package: only Node's own child_process, to call back into akm.
 //
-//   - akm's three read tools, each a run of the akm that started OpenCode, with `--detail agent --format json`. akm
-//     passes the argv that runs it in `AKM_OPENCODE_CLI`, a JSON array: the executable alone for a compiled akm, the
-//     runtime and the script for one run as a script (Node and `dist/akm`, say), so no shebang or shell is needed on
-//     any platform. The run's environment is the call's, so a stamped run's reads (`AKM_EVENT_SOURCE`) are recorded as
-//     that run's.
+//   - akm's three read tools, each a run of the akm that started OpenCode, with `--detail agent --format json`
+//     (`--detail brief` when akm_show asks for a document's outline). akm passes the argv that runs it in
+//     `AKM_OPENCODE_CLI`, a JSON array: the executable alone for a compiled akm, the runtime and the script for one
+//     run as a script (Node and `dist/akm`, say), so no shebang or shell is needed on any platform. The run's
+//     environment is the call's, so a stamped run's reads (`AKM_EVENT_SOURCE`) are recorded as that run's.
 //   - The environment of the commands the agent runs: the variables akm set for the OpenCode process (its roots and
 //     its OpenCode settings) are put back to what akm runs in, or removed, so the agent's shell sees the environment a
 //     harness's child would.
@@ -59,8 +59,16 @@ const TOOLS = [
     name: "akm_show",
     command: "show",
     positional: "ref",
-    description: "Read one akm asset by its ref, as returned by akm_curate or akm_search.",
-    input: { type: "object", properties: { ref: { type: "string" } }, required: ["ref"] },
+    description:
+      'Read one akm asset by its ref, as returned by akm_curate or akm_search. For a large document, call it with detail "brief" for its outline (toc, no body), then with ref#<slug> for only the sections you need.',
+    input: {
+      type: "object",
+      properties: {
+        ref: { type: "string" },
+        detail: { type: "string", enum: ["brief"], description: "brief: the outline (toc) without the body" },
+      },
+      required: ["ref"],
+    },
   },
 ];
 
@@ -78,7 +86,7 @@ function cliArguments(tool, input) {
     ...(type && tool.positional !== "ref" ? ["--type", type] : []),
     ...(limit && tool.positional !== "ref" ? ["--limit", limit] : []),
     "--detail",
-    "agent",
+    tool.positional === "ref" && input?.detail === "brief" ? "brief" : "agent",
     "--format",
     "json",
   ];

package/dist/assets/prompts/workflow-unit-preamble.md

@@ -9,7 +9,9 @@ Ground rules for this unit:
 
 1. Pull knowledge on demand instead of guessing: `akm search '<query>'` to find
    relevant assets, `akm show <ref>` to read one, `akm curate '<query>'` to let
-   akm select the best match. Only pull what this unit actually needs.
+   akm select the best match. Only pull what this unit actually needs: for a
+   large document, `akm show <ref> --detail brief` returns its outline (`toc`,
+   no body), then `akm show <ref>#<slug>` reads one section.
 2. Environment values and secrets are provided through your process
    environment when the workflow declares them. Never print secret values to
    stdout or embed them in your answer. If you need an env file path, use

package/dist/assets/stash-skeleton/facts/conventions/backlinks.md

@@ -72,8 +72,8 @@ xrefs:
 ## Self-situating headers and canonical naming
 
 Put the one-line orientation in `description:` and the trigger conditions in
-`when_to_use:` — those remain the higher-weight indexed fields. Bounded body
-prose is indexed in the lowest-weight `content` field, so
+`when_to_use:`; both are indexed, and search weighs every indexed field
+equally. Bounded body prose is indexed in the `content` field.
 `description:`/`when_to_use:` remain the primary orientation channel. Then
 open the body with a plain title plus a one-line
 orientation naming what it is, its scope/domain, and its key entities in

package/dist/assets/stash-skeleton/facts/conventions/organization.md

@@ -23,11 +23,10 @@ path is therefore the one facet you **cannot express twice and cannot change
 without breaking the ref** — so spend it deliberately, on exactly one axis.
 
 Retrieval is search, not browse: no one walks these folders at query time. A
-subdirectory buys you three things: its tokens are indexed as part of the
-asset's **name** (the highest-weighted search field), they are auto-added to
-`tags` (even when you set `tags` explicitly), and for scope-born types a slug
-matching the current repo's name earns an automatic in-project ranking boost.
-Every other facet belongs in frontmatter, where the index can actually read it.
+subdirectory buys you two things: its tokens are indexed as part of the
+asset's **name**, and they are auto-added to `tags` (even when you set `tags`
+explicitly). Search weighs every indexed field equally. Every other facet
+belongs in frontmatter, where the index can actually read it.
 
 ## Choose the partition axis by asset TYPE, not per-asset judgment
 
@@ -38,9 +37,8 @@ differently and bake the wrong guess into an immutable ref. Decide by type:
   `memory`, `lesson`, `task`, `env`, `secret`. These are born bound to the work
   in front of you, so the working context *is* the answer — no judgment needed.
   When the scope is a single repo, use its repo/package name as the slug (as
-  `git remote`/package.json spell it) — ranking auto-boosts assets whose name
-  or tags match the current repo. Client/team slugs get no such boost; just
-  reuse the existing spelling.
+  `git remote`/package.json spell it). For a client or team slug, reuse the
+  existing spelling.
   - `memories/projectA/auth-token-refresh`
   - `lessons/clientX/migration-rollback-gotcha`
   - `secrets/clientX/api-key`
@@ -58,11 +56,8 @@ differently and bake the wrong guess into an immutable ref. Decide by type:
   the type root — if any single project would break when it changes, it is
   scope-born.
 
-**Why reuse types don't take the project axis:** project relevance is already
-recovered at query time — AKM blends a per-project usage signal into ranking
-(scoped utility, keyed off the current repo, not the asset's path). Free the
-scarce path segment for the domain — the *only* handle that co-locates
-cross-project reuse.
+**Why reuse types don't take the project axis:** free the scarce path segment
+for the domain — the *only* handle that co-locates cross-project reuse.
 
 ## Placement rules
 
@@ -86,16 +81,15 @@ cross-project reuse.
   (`acme` vs `acme-corp`) so the prefix does not fragment. Keep the domain
   vocabulary in `facts/conventions/domains`.
 - **Off-axis facets go in `tags:`, not a bare field.** The indexed FTS fields are
-  name, description, tags, hints, and bounded low-weight body content — there is **no `project`
+  name, description, tags, hints, and bounded body content — there is **no `project`
   field**, so `project: projectA` in
   frontmatter is invisible to search. Put the off-axis facet in `tags` instead
   (a project-scoped memory adds `tags: [auth]`; a domain-scoped asset genuinely
   tied to a project adds `tags: [projectA]` sparingly).
 - **Directory tokens join `tags` on their own.** The scope/domain segments of
   the path are always auto-added to `tags` — even when you set `tags`
-  explicitly — so there is no need to restate them; the tag-match ranking
-  boost fires for the scope token either way. Filename tokens are auto-added
-  only when `tags` is empty.
+  explicitly — so there is no need to restate them. Filename tokens are
+  auto-added only when `tags` is empty.
 
 ## Renames and evolution