akm-cli 0.9.30 → 0.10.261001-beta

package/docs/guides/discover-and-load.md

@@ -0,0 +1,158 @@
+# Discover and Load
+
+Load only what the current task needs. Agents rarely know the exact name of
+the asset they need, and front-loading every skill, script, and doc into the
+prompt wastes context on capability the task will never touch. akm keeps the
+full library indexed and searchable, then lets an agent pull a shortlist,
+inspect one candidate, and load exactly the ref (or document section) the
+task requires — nothing more.
+
+## End-to-end example
+
+An agent picks up the task "deploy the app to staging." It doesn't know
+whether a script, a workflow, or a skill covers this, so it starts broad,
+narrows to a ref, and loads that ref's content:
+
+```sh
+akm curate "deploy the app to staging" --detail agent
+# → ranked shortlist; top hit: {"type":"script","ref":"scripts/deploy.sh","score":0.91,...}
+
+akm show scripts/deploy.sh
+# → {"run": "...", "setup": "...", ...} — ready to execute
+```
+
+That three-step arc — discover, load, and later record how it went — is the
+whole retrieval loop this guide covers.
+
+## 1. When to use search vs. curate
+
+Reach for `akm search` when you already know roughly what you're looking for
+— a type, a keyword, a conceptId prefix — and want a ranked list of matches.
+Reach for `akm curate` when you're starting a task and want akm to do the
+narrowing for you: curate runs a search, attaches previews and follow-up
+commands, and returns a small, high-confidence shortlist rather than a long
+results page. In short: search when you know what you're querying for,
+curate when you know what you're trying to do.
+
+## 2. Discover a shortlist
+
+`akm search` queries the unified index and ranks hits by relevance — keyword
+(BM25) and semantic (vector) matches fused into one list:
+
+```sh
+akm search "deploy" --type script --detail agent
+# → [{"type":"script","name":"deploy.sh","ref":"scripts/deploy.sh","score":0.0328,...}]
+```
+
+`akm curate` goes further: it takes the top search hits in order and attaches
+a preview, run details and related support refs — all while including a
+direct `akm show <ref>` follow-up on every result:
+
+```sh
+akm curate "review an architecture proposal" --type skill
+# → ranked shortlist with akm show skills/code-review as the top follow-up
+```
+
+Use `--detail agent` on either command to get the `ref`/`path`/`editable`
+fields an agent needs to act on a hit. See [CLI Reference](../reference/cli.md)
+for the full flag tables and exact output-field lists per `--detail` level.
+
+## 3. Load the selected capability
+
+Once you have a ref, `akm show` loads its full content. Every asset type
+returns type-specific fields — scripts include `run` and `setup`, skills
+return `content`, workflows return parsed `steps`:
+
+```sh
+akm show scripts/deploy.sh
+# → {"run": "...", "setup": "...", "cwd": "...", ...}
+```
+
+The ref format is `[bundle//]conceptId` — the `bundle//` prefix narrows
+lookup to one installed bundle when a conceptId is ambiguous across bundles.
+
+## 4. Load a document section
+
+Knowledge docs and other markdown assets can be large. Append `#fragment` to
+a ref to return one section by heading slug instead of the whole document:
+
+```sh
+akm show knowledge/api-guide#authentication
+# → just the "Authentication" section, not the full document
+```
+
+Search can also return an opaque `#akm-fragment-...` selector for a bounded
+piece of a long document. The exact selector remains the default. For memories
+whose opening context helps interpret a later matching turn, opt into bounded
+lead context:
+
+```sh
+akm show '<ref-from-search>' --context lead --max-tokens 800
+# → indexed-safe document lead, then [Selected matching fragment] and the match
+```
+
+AKM preserves the selected match before lead bytes when the budget is tight and
+reports `contextTruncated` in JSON. The response also distinguishes canonical
+`parentRef` from `selectedRef` and includes fragment position, line bounds,
+neighbors, and separate fragment/parent size estimates.
+
+An unmatched fragment lists the available slugs instead of erroring, so a
+guess that misses still tells you what to try next.
+
+## 5. Record the outcome
+
+After acting on a loaded asset, close the loop with `akm feedback` so the
+improvement pipeline learns from the outcome:
+
+```sh
+akm feedback scripts/deploy.sh --positive
+akm feedback skills/code-review --negative --reason "references a removed flag"
+```
+
+Record `--negative` only when the asset's content is wrong or stale, and say what
+is wrong and what it should say. A note that simply did not fit your task is not
+negative feedback: record nothing for it.
+`akm feedback <ref> --negative --reason "<what is wrong and what should change>"`
+flags the asset: it ranks lower right away, and the next `akm improve` run may
+repair its description, title or `when_to_use` from your reason. Improve does
+not rewrite an asset's text, so once you have verified the correct fact, attach
+the exact fix: `--replace "<exact current text>" --with "<corrected text>"
+--source "<URL, command or file that shows it>"`. That is how a one-off task
+turns into a durable improvement to the shared library rather than a result
+nobody else benefits from. `--positive` records that an asset helped (it raises
+its ranking) and does not trigger a rewrite.
+
+## 6. Troubleshoot an empty or poor result
+
+- **Zero hits on an exact-sounding query** — the search pipeline already
+  retries with prefix matching when the exact query returns nothing, so a
+  true zero usually means the term genuinely isn't indexed yet. Run `akm
+  index` (or `akm index --full` after adding a new source) and search again.
+- **Query looks right but nothing comes back** — check `--type`: it's
+  free-form and unvalidated, so a typo'd type (`scrpit` instead of `script`)
+  silently returns no hits rather than erroring.
+- **Local results are missing something you know exists** — confirm
+  `--from` matches where the asset lives (`local` is the default; use
+  `registry` or `all` to include the public registry).
+- **A known-good asset doesn't show up** — session assets and
+  `proposed`-quality entries are excluded from default results
+  (`--include-sessions` / `--include-proposed` bring them back), and
+  `--filter user=...`/`--filter agent=...` scoping can silently exclude
+  entries that don't carry a matching scope.
+- **Curate's shortlist feels off-topic** — narrow with `--type` to steer it
+  toward workflows, skills, or scripts specifically, or fall back to `akm
+  search` for a plain ranked list.
+
+## 7. Reference links
+
+- [CLI Reference](../reference/cli.md) — full `--detail` flag
+  semantics, complete flag tables, and exact output-field lists for `search`,
+  `curate`, `show`, and `index`
+- [Architecture](../architecture/architecture.md) — ranking and search
+  implementation detail (Search Pipeline, Show Resolution, Utility Scoring)
+- [Bundles](bundles.md) — where indexed assets come from
+- [Knowledge Management](knowledge-management.md) — capturing and importing
+  assets before they're discoverable
+- [Use akm with any agent](use-with-any-agent.md) — how agents reference
+  assets by ref in practice
+- [Concepts](concepts.md) — refs, search priority, and the FTS5 index

package/docs/guides/getting-started.md

@@ -0,0 +1,240 @@
+# Getting Started
+
+Install akm, connect a capability source, and pull a curated shortlist for a
+real task. This path takes about five to seven minutes end to end.
+
+## Runtime Requirement
+
+The npm package requires Node.js >= 22 to bootstrap its command on every
+platform. If a working Bun >= 1.0 is also on `PATH`, the package launcher
+prefers Bun for execution; old, unusable, or absent Bun installations fall back
+to Node.js. The standalone binaries are runtime-free.
+
+## 1. Install
+
+**Option 1 — npm package (recommended; requires [Node.js](https://nodejs.org) >= 22):**
+
+```sh
+npm install -g akm-cli
+```
+
+**Option 2 — Prebuilt binary (no runtime required):**
+
+```sh
+# Linux / macOS
+curl -fsSL https://github.com/itlackey/akm/releases/latest/download/install.sh | bash
+
+# Windows (PowerShell)
+irm https://github.com/itlackey/akm/releases/latest/download/install.ps1 | iex
+```
+
+Or download a standalone binary directly from the
+[GitHub releases](https://github.com/itlackey/akm/releases) page.
+
+Hitting a PowerShell execution-policy error on Windows? See
+[Troubleshooting](#troubleshooting) at the end of this guide.
+
+**Success check:**
+
+```sh
+akm --version
+```
+
+## 2. Run setup
+
+Guided, interactive setup is the default:
+
+```sh
+akm setup
+```
+
+`akm setup` walks through bundle location, embedding/LLM settings, semantic
+search asset preparation, registries, sources, and task definitions. It also
+reviews your scheduled task definitions and asks whether to activate them in
+the OS scheduler — that part of the flow, plus how to migrate or repair
+scheduler bindings later, is covered in [Scheduling](scheduling.md).
+
+For non-interactive use — scripting, CI, or when you just want a working
+bundle fast — use `--yes`:
+
+```sh
+akm setup --yes
+akm setup --dir ~/custom-bundle   # optional: a non-default bundle location
+```
+
+**Success check:** either form creates `~/akm` (or your `--dir` path) — your
+working bundle, the primary directory where your personal assets live — with
+subdirectories for each asset type: `scripts/`, `skills/`, `commands/`,
+`agents/`, `knowledge/`, `instructions/`, `workflows/`, `memories/`, `env/`,
+`secrets/`, `facts/`, `lessons/`, `tasks/`, and `sessions/`. See
+[Filesystem Layout](../architecture/internals/storage-locations.md) for
+platform-specific paths and environment variable overrides.
+
+## Isolated sandbox workflow
+
+Need a throwaway install for agent tests, CI repros, or docs verification? Run
+akm inside a temporary HOME/XDG sandbox so nothing touches your normal local
+state:
+
+```sh
+export AKM_SANDBOX="$(mktemp -d /tmp/akm-sandbox.XXXXXX)"
+export HOME="$AKM_SANDBOX/home"
+export XDG_CONFIG_HOME="$HOME/.config"
+export XDG_DATA_HOME="$HOME/.local/share"
+export XDG_CACHE_HOME="$HOME/.cache"
+export XDG_STATE_HOME="$HOME/.local/state"
+mkdir -p "$XDG_CONFIG_HOME" "$XDG_DATA_HOME" "$XDG_CACHE_HOME" "$XDG_STATE_HOME"
+akm setup --yes --dir "$AKM_SANDBOX/bundle"
+```
+
+Delete `$AKM_SANDBOX` when you're done to remove the whole throwaway install.
+
+## 3. Connect a capability source
+
+Add something to search. Point akm at a directory you already have, or
+install the official onboarding bundle:
+
+```sh
+akm bundle add ~/.claude/skills              # an existing capability directory
+akm bundle add github:itlackey/akm-stash     # the official onboarding bundle
+```
+
+Every source materialises files to a directory; akm indexes them locally.
+
+**Success check:**
+
+```sh
+akm bundle list
+```
+
+lists the source you just added.
+
+## 4. Index
+
+```sh
+akm index
+```
+
+`akm index` scans every configured source, then builds the search database.
+Run it again whenever you add or change assets. Use `akm index --full` to
+force a complete rebuild instead of an incremental update.
+
+**Success check:** the command reports how many assets it indexed. If a
+workflow file is malformed, akm skips that one asset, continues indexing the
+rest of the bundle, and reports the skipped file in `warnings`.
+
+## 5. Curate for a real task
+
+Describe what you're trying to do, in plain language, instead of guessing an
+exact asset name:
+
+```sh
+akm curate "deploy a Bun app"
+```
+
+Unlike `akm search`, `akm curate` attaches a preview and run details per hit,
+adds related support refs, and summarizes the set — it's the usual starting
+point for an agent.
+
+**Success check:** the response includes a small shortlist; each entry
+carries a `ref` field and a direct follow-up command such as `akm show <ref>`
+or `akm bundle add <ref>`.
+
+## 6. Show one of the results
+
+Pick a `ref` from your curate output and load its full payload:
+
+```sh
+akm show <ref>            # e.g. akm show workflows/deploy
+```
+
+**Success check:** structured JSON with everything an agent needs to use the
+asset — a `run` command plus optional `cwd` and `setup` for scripts, a
+`prompt` payload for agents, or the document `content` for knowledge (append
+`#<heading-slug>` to a ref for one section).
+
+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 — `show` hands
+your agent the payload; running it is a deliberate next step.
+
+## 7. Tell your agent about akm
+
+```sh
+akm hints --detail brief >> AGENTS.md
+```
+
+**Success check:** `AGENTS.md` now has a block of agent-facing usage
+instructions for the `akm` CLI, so any agent reading that file knows how to
+call it.
+
+## Optional: hand-write a script
+
+Curious how classification works on a file you wrote yourself, rather than
+one that came from a bundle? Add a small script and index it:
+
+```sh
+cat > ~/akm/scripts/hello.sh << 'EOF'
+#!/usr/bin/env bash
+# A simple greeting script
+echo "Hello from akm!"
+EOF
+chmod +x ~/akm/scripts/hello.sh
+akm index
+akm show scripts/hello.sh
+```
+
+Any file with a known extension (`.sh`, `.ts`, `.py`, etc.) placed in your
+working bundle is automatically recognized — the `scripts/` directory isn't
+required, it just increases classification confidence. Assets use inline
+metadata, not `.stash.json` sidecars: markdown assets use frontmatter, and
+scripts use structured header comments (a short leading description,
+`@param`, and execution hints like `@run` / `@setup` / `@cwd` when needed).
+See [Concepts](concepts.md) for how classification works.
+
+## What just happened?
+
+You ran the retrieval loop end to end: **connect** (added a source),
+**index** (built the search database), **curate** (got a relevance-ranked
+shortlist for a real task), and **show** (loaded one asset's full payload).
+The remaining links in that loop — **use/run** the asset, send **feedback**
+on whether it helped, and let akm turn accumulated signal into a
+**proposal** — are what the guides below cover.
+
+## Next steps
+
+- [Discover & Load](discover-and-load.md) — search, curate, and show in depth
+- [Bundles](bundles.md) — sources, registries, and installing more capability
+- [Capture Knowledge](capture-knowledge.md) — memories, imports, and wikis
+- [Improve the Library](improve-the-library.md) — feedback, proposals, and
+  the improvement loop
+- [Run Workflows](run-workflows.md) — structured, resumable
+  multi-step procedures
+
+Scheduling `akm improve` and other background tasks — see
+[Scheduling](scheduling.md).
+
+## Troubleshooting
+
+**Windows PowerShell execution policy.** `install.ps1` requires Windows
+PowerShell 5.1 or newer (default on Windows 10 and Windows 11). If
+`irm ... | iex` triggers a SmartScreen prompt or an ExecutionPolicy error, do
+one of:
+
+```powershell
+# Allow scripts in this session only, then re-run the install:
+Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
+irm https://github.com/itlackey/akm/releases/latest/download/install.ps1 | iex
+```
+
+```powershell
+# Or download the script, unblock the file, and run it:
+Invoke-WebRequest -Uri https://github.com/itlackey/akm/releases/latest/download/install.ps1 -OutFile install.ps1
+Unblock-File .\install.ps1
+.\install.ps1
+```
+
+Windows ARM64 hosts install the x64 binary, which Windows runs via x86_64
+emulation. Native ARM64 support is tracked alongside Bun's ARM64-on-Windows
+progress.

package/docs/guides/improve-the-library.md

@@ -0,0 +1,247 @@
+# Improve the Library
+
+AKM learns from outcomes, but changes remain reviewable. Every time an agent
+uses a capability and reports back whether it helped, AKM folds that signal
+into the asset's utility score; when the report says the content was wrong, it
+proposes a concrete edit. Nothing lands in your bundle automatically: every
+generated change queues as a proposal you (or an explicit policy) accept,
+reject, or revert.
+
+```text
+agent selects capability -> agent records outcome -> AKM updates utility and analyzes evidence ->
+AKM creates a proposal -> human or policy reviews the diff -> accept / reject / revert
+```
+
+## akm feedback
+
+`akm feedback` records a positive or negative signal for any indexed asset.
+The signal updates the asset's utility score immediately, so highly-rated
+assets rank higher and assets flagged wrong or stale surface less often right
+away. See
+[Architecture: The Improvement Loop](../architecture/improvement.md#utility-scoring)
+for how that score is computed.
+
+`akm feedback <ref> --negative --reason "<what is wrong and what should change>"`
+flags the asset: it ranks lower right away, and the next improve run may repair
+its description, title or `when_to_use` from your reason. Improve does not
+rewrite an asset's text. Once you have verified the correct fact, attach the
+exact fix: `--replace "<exact current text>" --with "<corrected text>"
+--source "<URL, command or file that shows it>"` (repeat `--replace`/`--with`
+for several edits). akm checks that each `--replace` text appears exactly once,
+records nothing if one does not, and applies the edit at once: no review, no
+gate (the `feedback` proposal it files is accepted on the spot, so
+`akm proposal revert` undoes it). `--positive` records that an asset helped (it raises its ranking)
+and does not trigger a rewrite.
+
+```sh
+akm feedback skills/code-review --positive
+akm feedback agents/reviewer --negative --reason "Gave outdated migration steps"
+akm feedback knowledge/opencode-server --negative --reason "the default port is 4096, not 8000" --replace "port 8000" --with "port 4096" --source "https://opencode.ai/docs/server/"
+akm feedback workflows/ship-release --positive --reason "Worked end-to-end on 0.8.0"
+
+# With a structured reason slug (consumed by improve/distill prompts):
+akm feedback skills/planner --negative --reason "wrong-default-timeout"
+```
+
+Specify exactly one of `--positive` or `--negative`. The ref must be present in
+the current local index. `--negative` additionally requires `--reason`, and
+omitting it exits 2. Full flag reference:
+[CLI Reference — feedback](../reference/cli.md#feedback---reason).
+
+Record feedback about the asset's content: that it helped, or that it turned
+out wrong or stale. Record `--negative` only for content that is wrong or stale,
+and say what is wrong and what it should say. A note that simply did not fit
+your task is not negative feedback: record nothing for it. A failed `akm`
+command, such as an `akm show` that errors on the ref, says nothing about the
+asset, so don't record it as feedback on it: reflect and distill read each
+reason as a report about the asset's content.
+
+**Example: flag a skill that gave bad advice**
+
+```sh
+akm feedback skills/deploy --negative \
+  --reason "Skips the dry-run step; caused prod incident 2026-05-10"
+```
+
+## akm log
+
+`akm log` is the realtime append-only event stream that every mutating CLI
+verb writes to — the record of what agents selected and what feedback they
+gave.
+
+```sh
+akm log                                         # All events, oldest first
+akm log --type feedback                         # Filter by event type
+akm log --ref skills/deploy
+akm log --since '@offset:12345'                 # Resume from a durable cursor
+```
+
+See [CLI Reference — log](../reference/cli.md#log) for the full filter list
+and cursor format.
+
+## akm improve
+
+`akm improve` is the main entry point for the self-improvement pass. It reads
+feedback signals and usage patterns, then generates proposals — it never
+writes directly to your bundle. By default, generated proposals always queue
+for review; the underlying autonomy gate and strategy configuration are
+covered in [Architecture: The Improvement Loop](../architecture/improvement.md).
+
+```sh
+akm improve                           # Full bundle pass
+akm improve memory                    # Scope to memory assets only
+akm improve skills/code-review         # One asset
+akm improve --task "reduce duplication"
+akm improve --dry-run                 # Show planned refs without generating proposals
+akm improve --limit 10                # Cap the refs the run processes
+```
+
+A run improves one bundle, the one it writes to (`--bundle`, else
+`defaultWriteTarget`, else your working bundle), and leaves assets in your other
+bundles alone even when they are writable. Run `akm improve --bundle team` to
+improve another one. A scheduled run covers the same single bundle, so schedule
+one `akm improve --bundle <name>` run per other bundle you want improved.
+`--dry-run` previews the bundle a live run would improve.
+
+A rewrite (reflect) is planned only for assets with negative feedback in the
+last 30 days that is newer than the last time improve tried them, or for an
+explicit ref; a positive or note-only signal never plans one, and neither does a negative whose exact fix (`--replace`, `--outdated`, `--superseded-by`) has since been accepted. Distill reads any
+feedback on a memory in that window, but skips a memory flagged wrong and not
+edited since: a negative feedback in that window judged the body it still has
+(or, recorded without that body's hash, is newer than its file's last write).
+It also skips a memory whose only feedback in that window is a positive with no
+reason or note: say what helped (`--reason`), or the lesson has nothing to
+distil.
+Unless `--require-feedback-signal` is set,
+the proactive-maintenance lane (on in `default`) also plans assets with no such
+feedback that are due for a revisit: at most 15 per run
+(`processes.proactiveMaintenance.maxPerRun`), and only assets not reflected or
+distilled for 30 days (`dueDays`), so each comes up at most once a month. The
+planned assets are ranked by salience and cut to `--limit`.
+Improve reworks only what gets read: without fresh feedback, the lane
+picks an asset (and a memory is judged for consolidation) only if `search`,
+`curate` or `show` returned it, or feedback named it, in the last 90 days — the
+usage log's retention — or if it is new material no improve stage has processed
+yet. An explicit ref (`akm improve skills/code-review`) is always reworked.
+Full flag reference: [CLI Reference — improve](../reference/cli.md#improve).
+
+`--dry-run` is an execution-plan preview, not a raw scope listing. Its
+`plannedRefs` are the final ranked refs after validation, retrieval, signal,
+disk, and limit gates. The accompanying `plan` keeps the pre-gate `rawInScope` count,
+per-gate removal counts and reasons, configured versus effective limits, and
+the selection lane for each final ref. `plan.snapshot` explains whether the
+existing index was readable; a missing or incompatible index produces an
+explicit empty snapshot without creating or migrating it. The plan reports the
+cap as `limits.effective` (`limits.additiveReplayAllowance` is always `0` and
+`limits.totalCeiling` equals the cap, because the replay lane is retired). It
+also reports proactive-maintenance due statistics, consolidation pool gates and
+chunk estimate, extract/memory-inference stage decisions, and proposal-triage
+mode and caps. The plan has
+`mode: "estimate"` and `dispatch: false`; producing it does not acquire the
+improve lock, invoke an LLM, create state, or write proposals, events, assets,
+cache files, or result records.
+
+The preview is a best-effort observation assembled during the invocation, not
+an atomic cross-store snapshot or a reservation. A later live run re-inspects
+mutable index, state, filesystem, and session-log inputs before dispatch, so
+concurrent changes can legitimately produce a different plan.
+
+**Example: auto-generate lessons from usage patterns**
+
+```sh
+akm improve --dry-run        # preview what would be processed
+akm improve --limit 20       # process at most 20 refs
+akm proposal list            # review what was generated
+```
+
+## akm proposal (list, show, diff, accept, reject, reopen, revert)
+
+`akm proposal list` lists pending proposals in the queue. Each proposal is an
+AI-generated suggested change — an edit to an existing asset, a new lesson, a
+memory consolidation, or a deprecation. Review the diff, then accept or reject.
+
+```sh
+# List proposals
+akm proposal list
+akm proposal list --status pending
+akm proposal list --ref skills/code-review
+
+# Inspect a proposal
+akm proposal show <id>
+akm proposal diff <id>                          # Preview the change vs. the live asset
+
+# Apply or discard
+akm proposal accept <uuid-or-prefix>
+akm proposal accept skills/akm-dream --bundle team-bundle
+akm proposal reject <uuid-or-prefix> --reason "duplicates existing workflow"
+```
+
+Accepts full UUIDs, 8-character UUID prefixes, or asset refs. `akm proposal accept` runs
+full validation before promoting the proposal into your bundle.
+`akm proposal revert` restores the prior content of an accepted proposal from
+its captured backup, and `akm proposal reopen <id>` undoes a rejection (it puts
+a rejected proposal back to pending unless its target has changed since). Full
+flag reference:
+[CLI Reference — proposal](../reference/cli.md#proposal).
+
+**Example: review and accept a memory consolidation**
+
+```sh
+akm proposal list --status pending
+akm proposal diff abc12345             # preview the proposed consolidation
+akm proposal accept abc12345           # write it to the bundle
+```
+
+## akm proposal new
+
+`akm proposal new` asks an engine to author a brand-new asset — useful
+when you want to create something from scratch rather than improving an
+existing asset. Any engine kind works (an LLM engine, an agent CLI or
+`opencode-sdk`): the engine returns the asset as JSON, which akm validates.
+Output always goes to the proposal queue, never directly to the bundle.
+
+```sh
+akm proposal new skill code-review --task "PR-style review skill for TypeScript repos"
+akm proposal new lesson docker-cleanup --file ./prompts/docker-cleanup.md
+```
+
+After the proposal is generated, review it with `akm proposal diff <id>` and apply with
+`akm proposal accept`.
+
+## End-to-end example: from bad experience to a reviewed fix
+
+```sh
+# 1. An agent hits a problem and records it
+akm feedback skills/deploy --negative \
+  --reason "Skips the dry-run step; caused prod incident 2026-05-10"
+
+# 2. The event lands in the log immediately
+akm log --ref skills/deploy --type feedback
+
+# 3. A later improve pass reads the signal and drafts a fix
+akm improve skills/deploy
+
+# 4. The fix is a proposal, not a live edit — review it
+akm proposal list --ref skills/deploy
+akm proposal diff <id>
+
+# 5. Accept, reject, or revert after acceptance if it doesn't hold up
+akm proposal accept <id>
+akm proposal reject <id> --reason "not the right fix"
+akm proposal revert <id>
+```
+
+Nothing in this loop bypasses review by default: `akm improve` only ever
+queues proposals, and promotion into the bundle happens through an explicit
+`akm proposal accept` (or an explicit opt-in policy) — see
+[Architecture: The Improvement Loop](../architecture/improvement.md) for the
+autonomy gate that governs the few lanes that can act without one.
+
+## See also
+
+- [Discover & Load](discover-and-load.md) — finding and loading assets
+- [Knowledge Management](knowledge-management.md) — capturing memories and docs
+- [Agent Integration](use-with-any-agent.md) — wiring feedback into agent workflows
+- [CLI Reference](../reference/cli.md) — full flag documentation for `feedback`, `log`, `improve`, `proposal`
+- [Architecture: The Improvement Loop](../architecture/improvement.md) — utility scoring, strategies, autonomy gates, auto-sync, and session extraction
+- [Concepts](../guides/concepts.md) — bundles, refs and the index

package/docs/guides/knowledge-management.md

@@ -0,0 +1,18 @@
+# Knowledge Management
+
+Capturing and protecting knowledge are two different jobs: `akm remember`,
+`akm import`, `akm bundle add`, and LLM wikis turn what an agent or teammate
+learns into searchable assets any agent can find, while `akm env` and
+`akm secret` hold configuration and credentials under a stricter guarantee —
+values never appear in akm's structured output. This page has moved; the
+content now lives in two focused pages.
+
+## Where things moved
+
+- [Capture Knowledge](capture-knowledge.md) — `akm remember`, `akm import`,
+  when to reach for each versus `akm bundle add` or a wiki, and how captured
+  material becomes available to every agent
+- [Wikis](wikis.md) — the LLM-wiki bundle format for maintained, structured
+  knowledge
+- [Environment & Secrets](../reference/env-and-secrets.md) — exact env/secret
+  operations, file modes, subprocess residency, and the security guarantee