akm-cli 0.9.30 → 0.10.261001-beta

package/docs/reference/configuration.md

@@ -95,6 +95,23 @@ kebab-case, at most 63 characters, and cannot start with `akm-`.
 | `llm` | `endpoint`, `model` | OpenAI-compatible chat completions |
 | `agent` | `platform` | A registered dispatch-capable harness |
 
+The registered harnesses (generated from the harness registry; do not edit):
+
+<!-- harness-table:start (generated by scripts/gen-config-schema.ts) -->
+| `platform` | Harness | Binary | Session logs | Model work | Native `agent` |
+| --- | --- | --- | --- | --- | --- |
+| `opencode` | OpenCode | `opencode` | yes | yes | yes |
+| `claude` | Claude Code | `claude` | yes | yes | yes |
+| `opencode-sdk` | OpenCode SDK | in-process | no | yes | yes |
+| `codex` | OpenAI Codex CLI | `codex` | yes | no | no |
+| `copilot` | GitHub Copilot CLI | `copilot` | no | no | no |
+| `pi` | Pi | `pi` | no | no | no |
+| `gemini` | Gemini CLI | `gemini` | no | no | no |
+| `aider` | Aider | `aider` | no | no | no |
+| `amazonq` | Amazon Q Developer CLI | `q` | no | no | no |
+| `openhands` | OpenHands | `openhands` | no | no | no |
+<!-- harness-table:end -->
+
 LLM endpoints must be complete `http://` or `https://` chat-completions URLs
 ending in `/chat/completions`, without userinfo, query, or fragment. API keys
 are symbolic only: `$VAR` or `${VAR}`. AKM resolves them only at dispatch.
@@ -141,6 +158,33 @@ the LLM engine used as that SDK engine's fallback connection. With no
 provider, model and auth from its own configuration. `defaults.llmEngine` is
 not a substitute.
 
+An `opencode` or `opencode-sdk` engine has no setting for the OpenCode major: akm
+detects it. With no `bin`, the engine runs the most recent OpenCode on `PATH`
+(`opencode2`, OpenCode 2's own alias, when present, else `opencode`); with a
+`bin`, it runs that binary. akm runs `<bin> --version` once per binary per
+process and uses the OpenCode 2 or OpenCode 1 adapters to match. OpenCode 1 keeps
+working and logs a warning recommending OpenCode 2. A `--version` akm cannot read
+(or a major it does not know) uses the OpenCode 2 adapters and logs a warning
+with the raw output. To run a particular OpenCode, set the engine's `bin`, e.g.
+`{"kind":"agent","platform":"opencode-sdk","bin":"/opt/opencode1/bin/opencode"}`.
+
+**Permissions in a dispatch.** akm answers every OpenCode permission request of a
+dispatch with "reject" (there is no one to approve it), and the rejection reaches
+the model as a tool error. akm changes no OpenCode permission default, so what
+gets asked is OpenCode's own setting:
+
+- **OpenCode 1** asks before reading or writing outside the project directory
+  (`external_directory`), so akm rejects it.
+- **OpenCode 2** (2.0.26) does not ask: a read or write outside the project
+  directory just runs, and akm's rejection never happens, unless your OpenCode
+  config says to ask. Add a rule to the global `opencode.json`, e.g.
+  `"permissions": [{"action": "external_directory", "resource": "*", "effect": "ask"}]`
+  (`"read"` and `"shell"` are actions too).
+
+On OpenCode 2 a rejection ends the turn: the dispatch returns `ok: false` with
+`reason: "aborted"` and the declined tool call in `error`. On OpenCode 1 the model
+carries on.
+
 On an engine without `timeoutMs`, model work (an improve process, a quality or
 triage judge, or an index pass) stops after 600 seconds, whatever the engine's
 kind; other work on an agent engine runs until it finishes. An improve stage's
@@ -191,7 +235,7 @@ Reasoning effort has one word in a request, `reasoningEffort`. `effort`, as a
 Unattended model work is the work akm hands a model with no one watching:
 - the improve processes (reflect, distill, consolidate, memory inference,
   extract, and validation's repair);
-- the quality, triage and retrieval-gate judges;
+- the quality and triage judges;
 - index passes;
 - `akm remember --enrich`.
 
@@ -209,7 +253,7 @@ cannot enforce:
 | LLM | No tools. |
 | `claude` | Read and Edit inside the working directory, and Bash for `akm search` and `akm show` only. akm runs it with `--restricted`, so your user, project and local settings cannot widen that. |
 | `opencode`, `opencode-sdk` | Read, grep and glob in the working directory and the stash, edit in the working directory only, and `akm_search` and `akm_show`, through an injected `akm-model-work` agent. No bash, because opencode cannot stop a redirect such as `akm show x > file` from writing elsewhere. |
-| `codex`, `copilot`, `pi`, `gemini`, `aider`, `amazonq`, `openhands` | Cannot run model work: akm refuses the request before it starts. |
+| Every other `agent` harness | Cannot run model work: akm refuses the request before it starts. |
 
 **The one rule.** Every key model work reads its engine from must name an
 LLM engine or a `claude`, `opencode` or `opencode-sdk` agent engine. Those
@@ -235,7 +279,9 @@ key, the engine and its platform. Other engine keys, `defaults.engine` and
 - opencode model work may read the stash and write only its working directory.
   `akm_search` and `akm_show` come from the akm-opencode plugin (0.9.21 or
   later), which akm does not load: put it in your opencode config
-  (`"plugin": ["akm-opencode"]`). akm turns off the plugin's curation, learning
+  (`"plugin": ["akm-opencode"]` for OpenCode 1; for OpenCode 2 install
+  `akm-opencode-v2` with `opencode plugin add akm-opencode-v2`, see
+  [Use AKM With Any Agent](https://github.com/itlackey/akm/blob/main/docs/guides/use-with-any-agent.md#opencode-plugins-one-package-per-opencode-major)). akm turns off the plugin's curation, learning
   and write gate for these dispatches and keeps its state in akm's state
   directory. The stash is protected from edits only while the temporary
   directory is outside a git repository.
@@ -442,11 +488,21 @@ can select `engine`, `model`, `timeoutMs`, and LLM request overrides:
 
 An improve process's engine follows
 [the one rule](#engines-for-unattended-model-work); an explicit invalid or
-incompatible engine never falls back to another engine. Built-in strategies
-are complete presets. User-defined strategies inherit omitted fields from the
-built-in `default` strategy before applying their own overrides. The built-in
-strategies other than `default` and `consolidate` are Experimental (see
-[STABILITY.md](../../STABILITY.md)): 0.10 measures each and keeps, folds or removes it.
+incompatible engine never falls back to another engine. The built-in strategies
+are `default` and `consolidate`. `consolidate` is a patch that
+is deep-merged onto `default`, and a user-defined strategy of the same name is
+merged on top of that; so every strategy, built-in or user-defined, inherits
+omitted fields from `default`. `quick`, `reflect-distill`, `thorough`,
+`catchup` were removed in 0.10 (#1130): measured, none beat `default` (`thorough`
+and `catchup` added only a judged triage drain, and `catchup` was identical to
+`consolidate`). `proactive-maintenance` was removed too (#1129): its lane now
+lives in `default`. A `improve.strategies.<name>` block with one of those names is
+now an ordinary user-defined strategy that inherits `default`, so it no longer
+carries the old built-in's settings; `--strategy` or `defaults.improveStrategy`
+naming one with no such block fails with an error that names `default`. To keep
+the old judged drain, set `processes.triage` (`enabled`, `applyMode: "promote"`,
+`judgment: true`) in your own strategy. The built-in strategies other than
+`default` and `consolidate` are Experimental (see [STABILITY.md](../../STABILITY.md)).
 
 `processes.triage.judgment` explicitly controls the optional judgment tier.
 Use `true` to enable it, `false` to disable it, or an object with `enabled`,
@@ -457,6 +513,22 @@ the retired `mode` and `profile` keys continue to report their engine migration
 guidance. When enabled, engine selection is judgment → triage → strategy →
 `defaults.llmEngine`, and resolution fails closed if none is available.
 
+The `default` strategy runs triage in `promote` mode with judgment off and
+`maxAcceptsPerRun: 200` (#1143), so the proposal backlog drains through the
+deterministic gates without `experimental.improveAutonomy`. Turning judgment on
+in a promote strategy is what that opt-in gates.
+
+Judgment is off in every built-in strategy, and the judgment tier may accept
+only a consolidate promotion. Retirements and reflect revisions it
+would accept are left for a person. This is measured, not cautious by habit
+(#1132, #1094): with `experimental.improveAutonomy` and judgment over every
+proposal kind, the nightly eval solved 0.49 (gpt-5.6-terra) and 0.53
+(qwen3.8-27b) of its items while harming 14 and 11, and changed 18 and 21 notes
+outside the planted set; the judge accepted unsafe retirements and applied exact
+fixes unreviewed. Judging promotions alone was reasonable: on qwen3.8-27b it
+had precision 0.87 and recall 0.78 and accepted 4.8% of bad promotions; on
+gpt-5.6-terra it was very cautious (precision 1.0, recall 0.17).
+
 ```jsonc
 {
   "improve": {
@@ -557,10 +629,15 @@ off too. Every entry must be a non-empty string, or the config does not load.
 ```
 
 No shipped strategy turns improve-stage session extraction on.
-`proactiveMaintenance` is on only in the `proactive-maintenance` preset; run
-`akm improve --strategy proactive-maintenance` to use that opt-in preset.
-Because strategies inherit from `default`, a preset that omits either process
-also inherits the off value. User strategy overrides
+`proactiveMaintenance` is on in `default` and off in `consolidate`, the only
+other shipped strategy. It plans stable assets that have had no feedback: at most
+`maxPerRun` (default 15) per run, only assets not reflected or distilled for
+`dueDays` (default 30), so each comes up at most once a month, and reflect's
+`limit` (25) still bounds the run. A preset that omits either process
+inherits the `default` value; set `processes.proactiveMaintenance.enabled: false` in the
+selected strategy to turn the lane off. A proposal from this lane is never
+accepted by `proposal drain`: it waits for a person (reason
+`proactive-needs-review`, #1147). User strategy overrides
 are applied last, so an explicit `enabled: true` still opts the selected
 strategy in.
 
@@ -789,8 +866,7 @@ explicit destination flag is given and the command isn't already scoped to a
 specific source. It must name a configured bundle; setting it with no
 `bundles` configured, or naming an unconfigured bundle, is rejected at
 `config set` (or config load) time. The full write-target resolution order
-is the command's destination flag (`--bundle` on `remember`/`clone`/
-`improve`, `--target` on `env`/`secret create`) -> `defaultWriteTarget` ->
+is the command's destination flag (`--bundle`) -> `defaultWriteTarget` ->
 working bundle (`defaultBundle`) -> `ConfigError`.
 
 ### Memory scope
@@ -857,7 +933,8 @@ section, an absent key, and an explicit `false` all read identically as off.
 ```
 
 - **`experimental.improveAutonomy`** — gates only the autonomous
-  `memoryInference`, `triagePromote`, and `memoryCleanup` lanes. `akm improve`
+  `memoryInference`, `triagePromote` (a promote with triage judgment on; a
+  deterministic-only promote runs without it), and `memoryCleanup` lanes. `akm improve`
   itself always runs; this only gates mutations without a human in the loop.
   Consolidation is not gated: it remains advisory and emits reviewable
   proposals. `sync.push` is deliberately **not** gated by this key.
@@ -1034,11 +1111,15 @@ network filesystem for the data directory and falls back to `DELETE`.
 
 ## Retired Configuration
 
-`profiles`, `llm`, `agent`, `features`, `stashes`, `defaults.llm`,
-`defaults.agent`, and `defaults.improve` are rejected in 0.9. Recreate the
-configuration using `engines`, `defaults.engine`, `defaults.llmEngine`, and
-`improve.strategies`; AKM deliberately does not infer or rename ambiguous
-profile identities.
+`profiles`, `llm`, `agent`, `features`, and `stashes` are rejected in 0.9.
+Recreate the configuration using `engines`, `defaults.engine`,
+`defaults.llmEngine`, and `improve.strategies`; AKM deliberately does not infer
+or rename ambiguous profile identities. `defaults.llm`, `defaults.agent`,
+`defaults.improve`, `index.stalenessDetection`, the engine settings that used to
+sit under `index.<pass>` (`endpoint`, `provider`, `apiKey`, `baseUrl`,
+`temperature`, `maxTokens`, `capabilities`) and the `feedbackDistillation`
+process (use `processes.distill.enabled`) load like any other unknown key: named
+once by the unknown-key warning, ignored, and dropped by `akm migrate apply`.
 
 `embedding.chunkSize` was never read by anything under `src/` (#954), so a
 config that still sets it is simply ignored — it still loads, unvalidated

package/docs/reference/data-and-telemetry.md

@@ -163,7 +163,7 @@ the set of types the code actually emits at HEAD (verified against every
 | `sync` | `akm sync` | `name`, `message`, `ok` |
 | `index_db_vacuumed` | `akm index` VACUUMed index.db, after an index layout migration or because more than half its pages were free | `pagesBefore`, `pagesAfter`, `freelistRatioBefore` |
 | `index_completed` | `akm index`, once when a run finishes | `mode`, `totalMs`, `walkMs`, `llmMs`, `embedMs`, `ftsMs`, `finalizeMs` (phase timings in milliseconds) |
-| `stash_synced` | `akm improve`'s internal auto-sync pass (the `sync.push` feature), **distinct from** the `akm sync` command above | `committed`, `pushed`, `skipped`, `reason`, `attributed` (paths the run wrote and staged), `unattributed` (in-scope paths that went dirty during the run without the run writing them — left for their author) |
+| `stash_synced` | `akm improve`'s internal sync passes (the `sync.push` feature), before the run and at its end, **distinct from** the `akm sync` command above | `phase` (`pre-run` or `end-of-run`), `committed`, `pushed`, `skipped`, `reason`, `attributed` (paths the run wrote and staged), `unattributed` (in-scope paths that went dirty during the run without the run writing them — left for their author) |
 | `env_access` | `akm env run <name> -- <command>` (audit trail: key **names** only, values never recorded) | `ref`, `keys` |
 | `secret_access` | `akm secret run <ref> <VAR> -- <command>` (audit trail: var **name** only, value never recorded) | `ref`, `var` |
 
@@ -189,7 +189,7 @@ the set of types the code actually emits at HEAD (verified against every
 | `improve_invoked` | Start of an `akm improve` run | `ref` (scope); `strategy`, `scope`, `dryRun`, `eligibleCount` |
 | `improve_completed` | `akm improve` run finished | run stats |
 | `improve_failed` | `akm improve` run errored | error |
-| `improve_skipped` | `akm improve` left a ref, a lane, or a group of refs out | `reason` (`no_new_signal`, `not_retrieved`, `distill_no_new_signal`, `budget_exhausted`, `budget_exhausted_batch`, `asset_missing_on_disk`, `strategy_filtered_all_passes`, `autonomy_gated`, `engine_unavailable`, `pool_below_min_size`, `consolidation_no_memory_updates`, `below_min_new_sessions`, `derived_memory_reflect_skipped`, `memory_distill_requires_feedback`, `distill_flagged_wrong`, `distill_positive_without_reason`, `distill_deprecated_or_superseded`); `count`, `remaining`, `strategy`, `lane` or `configKey` where they apply |
+| `improve_skipped` | `akm improve` left a ref, a lane, or a group of refs out | `reason` (`no_new_signal`, `not_retrieved`, `distill_no_new_signal`, `budget_exhausted`, `budget_exhausted_batch`, `asset_missing_on_disk`, `strategy_filtered_all_passes`, `autonomy_gated`, `engine_unavailable`, `consolidation_no_memory_updates`, `below_min_new_sessions`, `derived_memory_reflect_skipped`, `memory_distill_requires_feedback`, `distill_flagged_wrong`, `distill_positive_without_reason`, `distill_deprecated_or_superseded`); `count`, `remaining`, `strategy`, `lane` or `configKey` where they apply |
 | `improve_lock_recovered` | Stale improve lock cleared at startup | |
 | `improve_review_needed` | `akm feedback` pushed a high-utility asset's utility below the review threshold — a review-needed escalation is recorded (not a proposal, so it can't accidentally overwrite the asset) | `ref`, `previousUtility`, `nextUtility` |
 | `reflect_invoked` | Start of reflect phase in `akm improve` | `ref`, engine |

package/docs/reference/env-and-secrets.md

@@ -0,0 +1,126 @@
+# Environment & Secrets
+
+Reference for `akm env` and `akm secret` — the two protected-value asset
+types. For task-oriented guidance on capturing knowledge in general, see
+[Capture Knowledge](../guides/capture-knowledge.md); this page states exact
+contract, defaults, and security behavior.
+
+## env vs secret
+
+`akm env` manages a `.env`-backed group of configuration (a whole `.env` file
+loaded wholesale). `akm secret` manages a single standalone sensitive value —
+one value per file, mirroring Docker's secret model. There is no `akm vault`
+command; use `env` or `secret`.
+
+| | `env` | `secret` |
+| --- | --- | --- |
+| Purpose | configuration — related settings for an app/service | authentication — one sensitive value |
+| Holds | a `.env` file of many `KEY=value` pairs | one value per file |
+| Discoverable | key *names* (not values) | name only (the whole file is the value) |
+| Injects | many vars at once (`env run`) | one var (`secret run <ref> <VAR>`) |
+
+## Core security guarantee
+
+Values never appear in akm's structured output. `env list` and `akm show
+env/<name>` surface key names only — comment text is never surfaced either,
+since comments routinely contain commented-out credentials and are treated
+like values. `secret list` surfaces the secret's name only; the file content
+is never shown. Values reach a process only through the safe injection
+paths, `akm env run` and `akm secret run`, which pass values directly into
+the child process — never through akm's own stdout, the index, or `akm
+show`.
+
+```sh
+akm env create prod                       # create an empty .env group
+akm env create prod --from-file ./.env    # or ingest an existing .env
+
+# akm does not manage individual keys — edit the whole file with your own editor:
+$EDITOR "$(akm env path env/prod --quiet)"
+
+akm env list
+akm show env/prod                         # key names only
+
+# Inject the whole .env into a subprocess (never onto stdout):
+akm env run env/prod -- ./deploy.sh
+akm env run env/prod -- $SHELL            # interactive session with the env loaded
+akm env run env/prod --only DATABASE_URL -- ./migrate
+
+# Store a single credential as a secret:
+printf '%s' "$TOKEN" | akm secret set secrets/deploy-token
+akm secret run secrets/deploy-token GITHUB_TOKEN -- gh release create v1.0.0
+
+# Write into a specific source instead of the working bundle:
+akm secret set secrets/deploy-token --bundle team --from-file ./token
+```
+
+`env export --out <file>` writes a safe, sourceable `export KEY='value'`
+script (re-serialised single-quoted, so shell substitutions in the source
+`.env` become literal strings) — it requires `--out` and never prints values
+to stdout.
+
+## File modes and storage
+
+`.env` files are stored at mode 0600 under `env/` in the target bundle;
+standalone secrets are stored at mode 0600 under `secrets/`. A secret write
+is atomic under an exclusive per-secret lock held in akm's data directory;
+maximum secret size is 5 MB.
+Values never cross argv (no `/proc/cmdline` exposure). An `env` file or
+secret can carry a sibling `.sensitive` marker that excludes it from `list`
+output and from the search index entirely; the value remains usable via
+`run`.
+
+## Write-target resolution
+
+Env/secret **mutations** (`env create`, `env remove`, `secret set`) choose
+their write destination like every other write command: an explicit
+`--bundle <source>` wins, else `defaultWriteTarget`, else the working
+bundle. The chosen source must be writable — a non-writable target fails
+with a `ConfigError` before anything is written — and a git-backed writable
+target commits the mutation at a single operation boundary. Reads (`list`,
+`show`, `path`, `run`, `export`) still span all configured sources.
+
+## Subprocess residency
+
+`akm env run` and `akm secret run` inject values directly into the child
+process — never through a shell — but the child controls its own
+stdout/stderr, so a command that prints its own environment will still leak
+values into your terminal or agent transcript. Injected values live in the
+child process environment for its entire lifetime and are visible to every
+subprocess the child spawns.
+
+- Prefer `akm secret run secrets/<name> <VAR> -- <command>` over `akm env
+  run` when a command only needs one value.
+- Avoid `env run` / `secret run` for long-lived daemon or server processes;
+  for those, point the process at the secret file directly
+  (`<bundle>/secrets/<name>`) so the value never sits in a process
+  environment variable at all.
+- Avoid running commands that print the environment (`env`, `printenv`,
+  shell tracing, verbose diagnostics) in agent contexts unless you
+  explicitly intend to expose the child environment.
+- Before spawning, injected key names are scanned for known
+  process-hijacking variables (`LD_PRELOAD`, `PATH`, `GIT_CONFIG_*`, ...): a
+  first-party bundle warns and proceeds, a third-party-sourced bundle is
+  refused.
+
+## Stability
+
+`env list`, `env path`, `env export`, `env run`, `secret list`, and `secret
+run` — the read-and-inject surface — are Stable. `env create`, `env remove`,
+and `secret set` — the write verbs — are Experimental. Check
+[STABILITY.md](../../STABILITY.md) for the current tier of any command
+before depending on its exact output shape.
+
+## What this page does not cover
+
+This page documents akm's own guarantees for these two asset types, not the
+broader threat model (what a compromised bundle or malicious script could
+still do, what filesystem-level exposure remains, how this compares to a
+dedicated secrets manager). See [SECURITY.md](../../SECURITY.md) for that
+fuller picture, including plaintext-at-rest scope and rotation guidance.
+
+## See also
+
+- [Capture Knowledge](../guides/capture-knowledge.md) — `remember`, `import`,
+  and when to reach for each
+- [CLI Reference](cli.md) — full flag documentation for `env` and `secret`
+- [SECURITY.md](../../SECURITY.md) — full threat model

package/docs/reference/memory.md

@@ -0,0 +1,124 @@
+# Memory
+
+Reference for the `memory` asset type: capture, belief states, and derived
+memories.
+
+## Contract
+
+Memories are context fragments — observations, decisions, snippets —
+captured as markdown files. Capture one directly in your working bundle with
+`akm remember "..."`, or point akm at any directory of memory files written
+by another tool:
+
+```sh
+# File-based memory store from another tool
+akm bundle add ~/my-agent/memories
+```
+
+Memory assets appear in search results with the `memory` type, giving agents
+access to recalled context from previous sessions.
+
+## Schema
+
+Memories captured with `akm remember` can carry optional YAML frontmatter
+that the indexer records:
+
+| Field | Purpose |
+| --- | --- |
+| `tags` | Free-form categorization |
+| `source` | Where the memory came from (also used as the derived-memory parent backref — see below) |
+| `observed_at` | When the observation happened |
+| `expires` | When the memory should stop being considered current |
+| `subjective` | Marks the memory as opinion/preference rather than fact |
+| `description` | Short human-readable summary |
+| `captureMode` | `hot` (written via `akm remember`) or `background` (inferred by `akm improve`) |
+| `beliefState` | See belief states below |
+| `supersededBy` | Points at the memory that replaced this one |
+
+Supply frontmatter fields explicitly with `--tag`/`--expires`/`--source`,
+derive them from the body heuristically with `--auto`, or have the
+configured LLM propose them with `--enrich`. See
+[`akm remember`](cli.md#remember) for the full flag list.
+
+### Belief states
+
+Memories carry a `beliefState` field that records how current they are.
+Search ranking does not read it; the `--belief` filter below does. The
+supported values, from strongest to weakest authority:
+
+| State | When it's set | `--belief` |
+| --- | --- | --- |
+| `asserted` | Written directly by `akm remember` (user-explicit) | current |
+| `active` | Default for memories with no explicit state | current |
+| `deprecated` | Marked as no-longer-current but not yet superseded; frozen (never auto-refreshed) | historical |
+| `superseded` | Replaced by another memory via the `supersededBy` field | historical |
+| `contradicted` | Marked as contradicted by other evidence | historical |
+| `archived` | Soft-deleted; retained for audit | historical |
+
+`akm search` filters via `--belief current|historical|all`:
+
+- `current` → `active` + `asserted`
+- `historical` → `deprecated` + `superseded` + `contradicted` + `archived`
+- `all` (default — no filter) → every belief state, including `archived` and
+  `contradicted` memories, is eligible to surface.
+
+### Derived memories as retrieval shortcuts
+
+When `akm improve` infers a derived memory from a parent (e.g. distilling a
+verbose memory into a focused summary), the derived memory is written with a
+`source:` frontmatter backref naming the parent, and the indexer records the
+parent/child link in the `derived_from` column. This provenance backref is a
+sanctioned internal channel that carries a bare parent name, not a public
+[ref](refs.md) — agents never construct it.
+
+Search hits for the parent memory are then enriched in-place: the parent's
+description and tags are swapped with the derived child's surface text, and
+an `expandTo: memories/<derived>` field on the hit points at the richer
+derived ref. The parent ref itself is preserved on the hit, so existing
+automation keeps working — agents that want the deeper summary follow
+`expandTo`.
+
+## Defaults
+
+- Hot-path memories (those written via `akm remember`) receive
+  `captureMode: hot` and `beliefState: asserted` in their frontmatter
+  automatically.
+- Background-derived memories (those inferred from other assets by `akm
+  improve`) receive `captureMode: background`.
+- A memory with no explicit `beliefState` defaults to `active`.
+- `akm search --belief` defaults to `all` — no filter is applied unless you
+  pass `current` or `historical` explicitly.
+
+## Security / persistence implications
+
+- Memories are plain markdown files inside a bundle directory; there is no
+  separate memory store. `akm improve` and `akm lint` only operate on
+  writable sources — a read-only registry-cached memory source is excluded
+  from cleanup and derivation passes even if it's indexed.
+- The derived-memory `source:` backref and the index's `derived_from` column
+  are an internal provenance channel, not a ref an agent should read,
+  construct, or rely on programmatically. Use the `expandTo` field on a
+  search hit instead.
+- Belief-state frontmatter is rewritten in place by `akm improve`'s memory
+  cleanup lane when autonomy is enabled (`experimental.improveAutonomy`);
+  with autonomy off, cleanup is analyzed but not applied. See
+  `STABILITY.md`'s "`akm improve` autonomy" section.
+
+## Stability
+
+Per `STABILITY.md`, **memory belief-state transitions are Experimental**:
+`captureMode`, `beliefState`, contradiction edges, and the consolidate
+journal are observable but the algorithm that writes them is tuning across
+patch releases. Do not script against the exact transition logic — the
+frontmatter fields and their meanings above are the stable-enough surface to
+read, but when and how akm assigns them is still settling. The `lesson`
+asset type, which shares the same distillation pipeline, is also
+Experimental for the same reason.
+
+## See also
+
+- [Concepts](../guides/concepts.md) — how a memory fits the capability model
+- [Refs](refs.md) — the public ref grammar (distinct from the internal derived-memory backref)
+- [Asset Types](asset-types.md) — where `memory` sits in the full type taxonomy
+- [`akm remember`](cli.md#remember) — the capture command and its flags
+- `STABILITY.md` — the full stability tier index, including `akm improve` autonomy

package/docs/reference/refs.md

@@ -0,0 +1,156 @@
+# Refs
+
+Reference for the ref grammar `akm search` emits and `akm show` consumes,
+rename semantics, and namespacing conventions.
+
+## Contract
+
+A **ref** is a compact handle identifying one capability. Agents should
+treat refs as opaque tokens — get them from search or curate, pass them to
+show. The structured `conceptId` and `bundle` fields in search results
+provide the same information in parseable form; never parse a ref string by
+hand.
+
+## Grammar
+
+```text
+[bundle//]conceptId[#fragment]
+```
+
+| Part | Required | Description |
+| --- | --- | --- |
+| `bundle` | no | Narrows lookup to one installed bundle, separated from the rest of the ref by `//`. Omit it and the ref resolves against the workspace `defaultBundle`, then the remaining bundles in installation-priority order. |
+| `conceptId` | yes | Subdir-qualified within its bundle: the placement subdirectory followed by the item's canonical name (extension stripped for markdown-like types; scripts and secrets keep their natural filename). `type` is not part of a ref — the subdirectory carries that signal. |
+| `fragment` | no | A selector for part of the item. Input-only — never stored. |
+
+Examples: `scripts/deploy.sh`, `agents/reviewer`, `knowledge/api-guide`,
+`workflows/ship-release`, `team-catalog//scripts/deploy.sh`,
+`personal//knowledge/guide`, `knowledge/api-guide#authentication`.
+
+Source locators like `github:owner/repo` and `npm:@scope/pkg` are **install
+refs**, a distinct grammar accepted only by `akm bundle add` and `akm
+clone`. They are not asset refs and are never addressable through `akm
+show`.
+
+This reference page is deliberately non-normative prose over the same
+grammar; [`docs/architecture/specs/ref.md`](https://github.com/itlackey/akm/blob/main/docs/architecture/specs/ref.md)
+is the normative spec, including the `parseBundleRef` grammar, fragment
+resolution rules, and reserved-name handling.
+
+## Namespacing
+
+AKM supports **physical-subdirectory namespacing** — no extra flags
+required. Drop assets under nested directories beneath the type folder and
+the path becomes part of the ref's name:
+
+```text
+memories/projectA/auth-tip.md    →  memories/projectA/auth-tip
+memories/teamA/clientX/notes.md  →  memories/teamA/clientX/notes
+skills/projectB/lint-fix.md      →  skills/projectB/lint-fix
+knowledge/clientX/api-guide.md   →  knowledge/clientX/api-guide
+```
+
+This works for **any** asset type. The subpath segments become part of the
+conceptId, so `akm search "projectA" --type memory` narrows results to that
+subtree, and `akm show memories/projectA/auth-tip` resolves the full ref.
+
+There is also a **ref-prefix query syntax** — a query that is a conceptId
+prefix ending in `/` enumerates that subtree instead of keyword-matching:
+
+```sh
+akm search "memories/"                  # every memory
+akm search "memories/projectA/"         # exactly that subtree
+akm search "team-catalog//"             # every item in one bundle
+akm search "team-catalog//skills/"      # one subtree of one bundle
+```
+
+Enumeration is `/`-boundary exact — a sibling `projectAlpha/` scope does not
+leak — and hits are a deterministic listing with the fixed browse score `1`,
+not a relevance ranking. Because it matches conceptIds, it works for items
+from every adapter, and you can copy a ref prefix straight out of search
+output and paste it back as a query. A complete ref
+(`memories/projectA/auth-tip`, no trailing `/`) stays an ordinary keyword
+search — resolving a single ref is `akm show`'s job.
+
+**Recommendation:** use physical subdirectories now to organize multi-project
+or multi-team bundles. They sort cleanly on disk and require no
+configuration.
+
+**Which subdirectory?** Choose the partition axis by asset **type**:
+scope-born types (`memory`, `lesson`, `task`, `env`, `secret`) take the
+current **project/client** slug; reuse-born types (`knowledge`, `skill`,
+`fact`, `script`) take a stable **domain**; global types (`command`, `agent`,
+`workflow`) stay at the type root or a tool slug. The full rules — depth
+limits, no-volatile-facets, off-axis facets as tags, and how to cross-link
+for retrieval — ship as the `facts/conventions/organization`,
+`facts/conventions/backlinks`, and `facts/conventions/domains` convention
+facts in the bundle skeleton, and are surfaced to agents automatically at
+authoring time.
+
+### Planned
+
+Not part of the current stability contract; see
+[ROADMAP.md](../../ROADMAP.md) for what's committed:
+
+- A `--namespace <ns>` flag to provide a thin name-prefix normalizer on
+  `search`, `remember`, `improve`, and `feedback` so the same prefix doesn't
+  have to be typed every time.
+- A `::` delimiter (for example `projectA::memories/auth-tip`) to provide
+  strict isolation so refs from different namespaces never collide in
+  ranking or recall.
+
+Until those land, physical subdirectories remain the recommended pattern.
+
+## Renames and moves
+
+**Treat a ref as permanent.** A rename is **delete plus create**: the new
+path is a new identity, so the destination starts with fresh learned state
+(utility, salience, usage history) and any inbound refs to the old path
+dangle. When you must rename:
+
+```sh
+mv ~/akm/memories/old-note.md ~/akm/memories/new-note.md
+# update any intentional refs (they are fully qualified: bundle//memories/old-note)
+akm index
+akm lint          # confirms nothing dangles
+```
+
+Moving an item between bundles is copy/import followed by deletion from the
+source — both the bundle and the concept identity change. `akm mv`, which
+promised identity-preserving renames, was removed in 0.9.0: 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. The procedure above is the only supported path today.
+
+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 onto the new ref before `akm index` runs; it is Internal
+tooling, not a supported command surface. See
+[the decision record](https://github.com/itlackey/akm/blob/main/docs/architecture/specs/0.9.0-decisions.md#d3--renames-are-delete--create-akm-mv-ships-experimental).
+
+## Refs in prose
+
+Refs embedded in prose must use the fully-qualified `bundle//conceptId` form
+— the bundle-slug charset makes such a token lexically anchored — or a
+native link form owned by the adapter (OKF links, wiki links). A bare
+conceptId in prose is ordinary text, not a ref, and no akm tool rewrites it.
+
+## Stability
+
+Per `STABILITY.md`, this is **Stable** surface: the
+`[bundle//]conceptId[#fragment]` grammar (durable state always stores the
+fully-qualified `bundle//conceptId`; the short form is accepted input only),
+conceptId-prefix enumeration, and the rename-is-delete-plus-create procedure
+are all named explicitly in the Stable tier, and the ref grammar is called
+out as frozen at 1.0 alongside the supported source model, search behavior,
+and write-target rules. The `--namespace` flag and `::` delimiter above are
+On the horizon, not yet part of the contract. See `STABILITY.md` for the
+full command- and surface-level tier index.
+
+## See also
+
+- [Concepts](../guides/concepts.md) — where refs fit in the retrieval loop
+- [Asset Types](asset-types.md) — how a conceptId's subdirectory maps to an asset type
+- [Memory](memory.md) — parent/derived-memory provenance backrefs
+- [`docs/architecture/specs/ref.md`](https://github.com/itlackey/akm/blob/main/docs/architecture/specs/ref.md) — the normative ref grammar spec
+- [ROADMAP.md](../../ROADMAP.md) — planned ref-syntax additions