akm-cli 0.10.261016-beta → 0.10.261017-beta

package/CHANGELOG.md

@@ -6,6 +6,95 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.10.261017] - 2026-10-27
+
+### Changed
+
+- `akm search` finds knowledge whose answer sits in fenced code (#1260). The
+  `content` search projection now keeps the identifiers of fenced code (names,
+  CLI flags, config keys, paths, dotted references such as `process.env.CI`)
+  and still drops their literal values (quoted strings, assignment values, URLs,
+  long token-like strings). On akm-eval's code-lookup set nDCG@10 rose from
+  0.530 to 0.764 (keyword) and 0.494 to 0.614 (semantic); the library set
+  improved slightly and the prose-only books set is unchanged. Search results
+  carry no `content`, so what search hands an agent is the same size. Fragments,
+  fragment ids and `akm show` are unchanged. The next `akm index` (including the
+  one `akm upgrade` runs) re-projects every directory once and re-embeds only
+  the entries whose embedded text changed; no `--full` needed.
+
+### Fixed
+
+- The first `akm index` after upgrading re-embeds only the entries whose
+  embedded text changed (follow-up to #1260). The fenced-code identifiers now in
+  the search text come after the prose, past the first `embedding.maxInputTokens`
+  (default 512, about 2,048 characters) that are embedded, so a longer document
+  keeps its vector and only its keyword row is rewritten. The index prints how
+  many entries it is embedding (`Embedding 3,712 changed entries (15,050
+  unchanged)`), and `akm upgrade` shows that line and the rest of the index's
+  progress instead of waiting silently.
+- Documentation sentences that were false on 0.10 are corrected (review of
+  #1273, #1251 follow-up). `asset-types.md` lists every way an env or secret
+  value reaches a process. `classification.md` says that `akm`, `okf`, `claude`,
+  `opencode` and `generic-files` reserve `index.md` and `log.md` at every depth
+  and `llm-wiki` reserves `schema.md`, `index.md` and `log.md` only at the wiki
+  root (`adapters.md` agrees), and that a `.yml` under `workflows/` is typed
+  `workflow`, then skipped at index time. `ref.md`, `workflow-engine.md` (no
+  isolated units; a plan from a newer akm is refused unread) and `workflows.md`
+  say 0.10. `configuration.md` and the stash skeleton's `backlinks.md` no longer
+  call `content` the lowest-weight search field: BM25 weighs the five fields
+  equally. The skeleton's `organization.md` no longer calls the name the
+  highest-weighted field or promises repo-match, tag-match or per-project
+  ranking boosts, which search does not have. `persisted-data-compat.md` has its
+  downgrade warning for retire proposals back. A bare `akm proposal drain`
+  follows the apply mode of `improve.strategy` (`default`, which promotes,
+  unless set); the `--promote` help text, `cli.md` and the improve guide said it
+  queues (whether it should is #1274). The feedback pages and
+  `akm feedback --help` say that in keyword-only search one vote moves a hit
+  one place whatever the keyword margin, and that with embeddings it breaks
+  only near-ties, where they said feedback does not override relevance. The
+  `AKM_REGISTRY_URL` rows say it replaces the configured registries in every
+  registry search. The migration guide and the 0.10.0 release notes name the
+  full refs `akm env` and `akm secret` now require, the removed
+  `akm search --assets`, the end of the index's bundle refresh, the retired
+  `secret://` and `${secret:NAME}`, the `--belief current` default, the
+  Codex and Aider flags akm no longer passes, 0.9 retire proposals, the
+  `akm health` warning where local embeddings are not offered, the dropped JSON
+  fields, the workflow redaction scope, and (in the notes) the frontmatter date
+  keys, symlinked and trimmed secrets, the SIGINT-first stop and the Claude Code
+  and Codex plugin branches, and no longer list `GET /api/config` as a breaking
+  change (`akm ui` is new in 0.10). The fixture READMEs match the code.
+- **`akm bundle rename` keeps the bundle's recorded feedback** (#1250). It rewrote
+  proposals, task history and workflow refs but left `usage_events` under the old
+  prefix, so after a rename no feedback counted in search ranking for any asset
+  in the bundle, improve stopped reading its feedback, and the next `akm index`
+  cut the events off from their entries. It now moves the bundle's
+  `usage_events`, `events`, `improve_ledger`, `asset_salience` and
+  `asset_outcome` rows to the new name too, and matches the old name
+  case-sensitively, so renaming `team` no longer moves or overwrites the rows of
+  a bundle named `Team`.
+- A negative whose exact fix was applied no longer keeps demoting the corrected
+  asset in `akm search` and `akm curate` (#1249). A negative recorded with
+  `--replace`/`--with`, `--superseded-by` or `--outdated` stops counting against
+  the asset once its fix is accepted, the same "already acted on" rule
+  `akm improve` uses; reverting the fix with `akm proposal revert` makes the
+  negative count again. A fix the accept refused, and every negative without a
+  fix, still lower the asset's ranking.
+- **The architecture and CLI reference pages now say that feedback reorders search hits
+  (#1251).** They said a hit's `score` was its fused score and that nothing else changed the
+  order. They now say that after fusion the score is multiplied by
+  `1 + 0.03 × (ln(1 + positives) − ln(1 + negatives))` over the user's recorded feedback for
+  the asset, the list is re-sorted (equal scores by fully qualified ref), and
+  one-hit-per-file and identical-content deduplication then drop entries without reordering
+  it. They also say filters drop ineligible entries from each candidate list before its 100
+  candidates are taken, not from the fused list afterwards. The storage, indexing, registry
+  and improve-guide pages no longer say that search ranking reads the utility score: improve
+  and `akm metrics` read it, search does not.
+- `AKM_REGISTRY_URL` now takes effect in `akm search` and `akm curate` with
+  `--from registry` or `--from all` (#1275). The variable is meant to replace the
+  configured registries, but search always passed the configured list, which
+  won, so a mirror or CI override was never read and your `registries` were
+  queried instead. When it is set, only its comma-separated URLs are searched.
+
 ## [0.10.261016] - 2026-10-27
 
 ### Added
@@ -1558,6 +1647,17 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
   schema rejection: one retry without the schema, remembered for the connection. `gpt-oss:120b` through the lab
   gateway needed `supportsJsonSchema: false` set by hand. Other 5xx answers keep the transient-retry path. (#1150)
 
+## [0.9.32] - 2026-10-13
+
+A patch release: `akm feedback` no longer reports success for feedback it could not store.
+
+### Fixed
+
+- **`akm feedback` fails when it cannot record the feedback.** When `state.db` was read-only to the process, as it is
+  inside an agent sandbox that only allows writes in the workspace, the feedback row was silently dropped and the
+  command still printed `"ok": true`. It now fails with a `DATA_DIR_NOT_WRITABLE` config error (exit 78) and records
+  nothing, so an agent knows its feedback was lost. Add akm's data directory to the sandbox's writable paths.
+
 ## [0.9.31] - 2026-10-09
 
 A patch release: concurrent config writes no longer lose a change, OpenAI's reasoning models work as `llm`

package/README.md

@@ -69,14 +69,12 @@ akm show scripts/deploy.sh         # View details and run command
 - **One library for every agent** -- Use the same capability library from Claude Code, OpenCode, Cursor, Aider, Windsurf, or any assistant that can run shell commands.
 - **Load only what the task needs** -- Search or curate a shortlist, then load full content by ref. No giant startup prompt is required.
 - **Package complete capabilities** -- Install and share bundles containing skills, scripts, workflows, agents, instructions, memories, and knowledge -- not just prompt snippets.
-- **Improve through evidence, with review** -- Feedback re-ranks assets right away. A negative report can carry an exact text fix, and `akm improve` repairs metadata; every edit lands as a diffable proposal you accept, reject or revert, and only writable bundles are changed.
-- **Turn knowledge into repeatable work** -- Run persisted workflows with dispatch, gates, retries, budgets, and resume instead of reconstructing a process from prose every session.
+- **Improve through evidence, with review** -- Feedback re-ranks assets right away. A negative report can carry an exact text fix, and `akm improve` repairs metadata. Edits land as diffable proposals: the default improve strategy accepts the ones its quality judge passed, the rest wait for you to accept or reject, and any accept can be reverted. Only writable bundles are changed.
+- **Turn knowledge into repeatable work** -- Run persisted workflows with dispatch, gates, retries, budgets, and resume instead of reconstructing a process from prose every session. Workflows are Experimental.
 
-akm retrieves every supported capability type. It directly orchestrates
-defined execution surfaces such as workflows, agent dispatch, tasks, and
-guarded subprocess injection -- it does not blindly execute arbitrary indexed
-content merely because that content appears in search results. It
-complements MCP and assistant-native skills rather than replacing them.
+Search and show only return content; running a workflow, task, script, or
+agent is a separate command. akm complements MCP and assistant-native skills
+rather than replacing them.
 
 ## Agent Integration
 
@@ -90,7 +88,7 @@ knowledge, instructions, memories, workflows, env files, secrets, lessons, tasks
 sessions, and facts via the `akm` CLI. Use `akm -h` for details.
 ```
 
-Or generate it directly: `akm help agents >> AGENTS.md`
+Or generate it directly: `akm hints --detail brief >> AGENTS.md`
 
 ## Documentation
 
@@ -99,8 +97,8 @@ Full docs, CLI reference, and guides are at **[akm.fwdslsh.dev](https://akm.fwds
 - [Getting Started](https://akm.fwdslsh.dev/docs/guides/getting-started/)
 - [Supported Formats](https://akm.fwdslsh.dev/docs/reference/supported-formats/)
 - [CLI Reference](https://akm.fwdslsh.dev/docs/reference/cli/)
-- [Task v3 Reference](https://akm.fwdslsh.dev/docs/reference/tasks/)
-- [0.9.2 Migration Guide](https://akm.fwdslsh.dev/docs/migration/v0.9.1-to-v0.9.2/)
+- [Tasks Reference](https://akm.fwdslsh.dev/docs/reference/tasks/)
+- [Migration guides](https://akm.fwdslsh.dev/docs/migration/README/)
 - [Configuration](https://akm.fwdslsh.dev/docs/reference/configuration/)
 - [Bundle Authoring Guide](https://akm.fwdslsh.dev/docs/guides/author-bundles/)
 - [Registry](https://akm.fwdslsh.dev/docs/reference/registry/)

package/SECURITY.md

@@ -2,108 +2,16 @@
 
 ## Supported versions
 
-Security fixes are made on the latest minor release line of `akm-cli`. The
-0.x line is pre-1.0 — please upgrade promptly when a fix lands.
-
 | Version | Supported |
 | --- | --- |
-| 0.9.x | ✅ active |
-| 0.8.x | ❌ no longer maintained |
-| < 0.8 | ❌ no longer maintained |
+| 0.10.x | Yes |
+| Older | No |
 
 ## Reporting a vulnerability
 
-Please report security issues **privately** via GitHub Security Advisories:
-
-- https://github.com/itlackey/akm/security/advisories/new
-
-If GitHub Security Advisories is unavailable, email `itlackey@gmail.com`
-with the word `SECURITY` in the subject. Please include reproduction steps,
-the impacted akm version, and your operating environment.
-
-We will acknowledge receipt within 72 hours and aim to ship a fix or a
-mitigation guidance within two weeks, depending on severity.
-
-## Threat model
-
-`akm` is a local CLI that reads and writes user files, executes user-authored
-shell commands (via scripts, workflows, and agent dispatch), and talks to
-explicitly configured external services (LLM endpoints, git remotes, npm,
-HTTP sources). It does **not** ship telemetry, send data to anyone by
-default, or open network listeners. See
-[`docs/reference/data-and-telemetry.md`](docs/reference/data-and-telemetry.md) for the on-disk
-inventory.
-
-Several akm surfaces execute user-controlled code or data with the full
-permissions of the akm process. These are documented design decisions, not
-bugs, but you should be aware of them:
-
-### Workflows execute shell commands with full environment access
-
-Workflow steps run in your shell with your PATH and your environment
-variables — including any secrets you have exported or loaded via
-`akm env run` / `akm secret run`. **Only add workflow sources you trust.** See
-[`docs/guides/run-workflows.md` — "Security: workflow sources are executed
-code"](docs/guides/run-workflows.md#security-workflow-sources-are-executed-code)
-for the full discussion.
-
-### Scripts execute shell commands
-
-`akm show scripts/<name>` returns a `run:` command line the user (or an
-integrating agent) then executes. The same trust model applies: scripts you
-install from third-party stashes are third-party code.
-
-### Agents and commands embed user-authored prompts
-
-`akm show agents/<name>` and `akm show commands/<name>` return prompt
-templates and system prompts that an LLM will execute. A malicious stash
-maintainer could write a system prompt that instructs the LLM to read
-sensitive files in your working tree and exfiltrate them via the LLM
-response. Audit the prompt body the same way you'd audit a script.
-
-### Installing a stash means trusting its code
-
-Installing a stash is not a data-only operation: **`<stashDir>/scripts/wiki-fetchers/*.{ts,js,mjs}` is imported and EXECUTED during `akm index`** (when a website-snapshot source in that stash is synced), with no gate, no prompt, and no allowlist. Every file in that directory is dynamically `import()`ed, and only *after* the module has fully evaluated does akm check that its default export looks like a fetcher (`{ name, matches, fetch }`) — module-level code (anything outside the exported functions) runs unconditionally before that check ever happens, and a file that fails the check still ran. There is no sandboxing: a wiki-fetcher script executes with the full permissions of the akm process, exactly like the scripts and workflow steps documented above.
-
-This is a deliberate design decision (owner ruling), not an oversight, and it will not change without a separate decision to add a gate. **If you install a stash from a source you do not trust, you are trusting its code to run on your machine at index time** — audit `scripts/wiki-fetchers/` the same way you would audit any other executable you're about to run, before installing.
-
-The built-in YouTube snapshot fetcher (`src/sources/snapshot-fetchers/youtube.ts`) deliberately **impersonates the YouTube Android app's InnerTube client** (`clientName: "ANDROID"`, a spoofed `clientVersion`) when calling YouTube's private `youtubei/v1/player` endpoint, because the public web client's caption URLs are Proof-of-Origin-Token gated and return empty bodies. This is known, intentional behavior needed to fetch captions at all, not a bug — documented here so it isn't mistaken for one.
-
-### Environment and secret assets are plaintext on disk
-
-`env` and `secret` assets are owner-permissioned plaintext under `<stash>/env/`
-and `<stash>/secrets/`. They are protected against other local users by
-filesystem permissions but are not encrypted at rest. Do not commit these
-files to source control. Normal `akm env` and `akm secret` output never echoes
-values; materialize values only at the command boundary with `akm env run`
-or `akm secret run`.
-
-The knowledge graph extracted from your assets (entities/relations) lives
-only in `$DATA/index.db` and is surfaced as aggregate counts via `akm health`
-(`--report` for the full breakdown) — there is no export command that writes
-graph content to an arbitrary path.
-
-### Improve / propose send asset content to the configured LLM
-
-`akm improve` (whose strategies run processes such as reflect, distill, and
-consolidate) and `akm proposal new` can send asset frontmatter and body to the
-connection (or harness) selected by the command, strategy, or current defaults.
-Connections live under `connections.<name>` in `~/.config/akm/config.json`,
-with their keys in the environment or in `~/.config/akm/credentials.json`. If you
-configure a third-party LLM, your asset content goes to that third party, and a
-harness you enable (Claude Code, Codex, ...) sends it wherever it is configured
-to. Use a local endpoint (for example, `http://localhost:11434/v1` via Ollama)
-for assets containing secrets or private notes.
-
-## Known non-issues
+Report security issues privately through GitHub Security Advisories:
+<https://github.com/itlackey/akm/security/advisories/new>
 
-- **The `akm-cli` npm package requires Node.js >= 22 as its bootstrap.** A
-  working Bun >= 1.0 is preferred for execution when it is also on `PATH`; old,
-  unusable, or absent Bun installations fall back to Node.js. Bun does not
-  remove the package's Node.js requirement. Standalone binaries are
-  runtime-free. This is a compatibility limitation, not a security risk.
-- **Workflows can read any file the akm process can read.** This is not a
-  bug — see "Threat model" above.
-- **Installing `akm-cli` runs no install script.** Neither `akm-cli` nor any
-  package it depends on declares one. The Node.js version is checked when akm
-  starts, not when it installs.
+If that is unavailable, email `itlackey@gmail.com` with `SECURITY` in the
+subject. Include reproduction steps, the akm version, and your operating
+environment.

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). |
 
@@ -202,12 +198,11 @@ enumeration of the whole `proposal` noun group.
     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. A whole document's `show`
-    carries `toc`, every heading with the slug that selects it. Elsewhere it is an
-    adapter-owned selector opaque to the core. See
+    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
@@ -228,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
@@ -288,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
@@ -323,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
@@ -333,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
@@ -367,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
@@ -397,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
@@ -457,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
@@ -470,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
@@ -517,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
@@ -560,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 |
 
@@ -572,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
@@ -619,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/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