akm-cli 0.9.30 → 0.10.261001-beta

package/docs/guides/use-with-any-agent.md

@@ -0,0 +1,174 @@
+# Use AKM With Any Agent
+
+AKM works from any shell-capable coding agent — Claude Code, OpenCode, Cursor,
+Windsurf, Aider, and others. No plugins or SDKs are required for the core
+workflow: a three-line system prompt block plus shell access is all an agent
+needs to start using your bundle.
+
+## AGENTS.md / CLAUDE.md snippet
+
+Add this block to your `AGENTS.md`, `CLAUDE.md`, or system prompt. It tells
+the agent that `akm` is available and how to discover it.
+
+```markdown
+## Resources & Capabilities
+
+You have access to a searchable library of scripts, skills, commands, agents,
+knowledge, workflows, env files, secrets, lessons, memories, tasks, sessions,
+and facts via the `akm` CLI. Use `akm -h` for details.
+```
+
+That is the minimum. The agent can then run `akm curate <task>` at the start
+of any complex task to pull the most relevant assets into context, and
+`akm show <ref>` to load any asset by ref.
+
+For a longer, agent-facing instruction block — usage patterns, flag guidance,
+the full ref format — generate one instead of hand-writing it:
+
+```sh
+akm hints --detail brief >> AGENTS.md
+```
+
+The output is stable across patch releases and designed for agents rather
+than humans: it describes the lookup workflow (`curate` → `show` →
+`feedback`) and explains how refs work. It prints a short guide by default;
+pass `--full` for the complete one.
+
+## The retrieval loop: curate, show, feedback
+
+Once an agent knows `akm` is available, the working pattern is always the
+same three calls:
+
+```sh
+# 1. Curate assets for the current task
+akm curate "deploy to production" --limit 3
+
+# 2. Load the best match by ref from the curate output
+akm show workflows/deploy-to-prod
+
+# 3. Record outcome
+akm feedback workflows/deploy-to-prod --positive --reason "Completed without issues"
+```
+
+**Get refs from search.** Agents should call `akm search --detail agent` or
+`akm curate` to discover refs — not guess them. The `ref` field in search
+results is the stable token to pass to `akm show`. Feedback closes the loop.
+Record `--negative` only when the asset's content is wrong or stale; a note that
+simply did not fit the task is not negative feedback, so record nothing for it.
+`akm feedback <ref> --negative --reason "<what is wrong and what should change>"`
+flags the asset, and the next improve run may repair its description, title or
+`when_to_use` from your reason. Once you have verified the correct fact, attach
+the exact fix with `--replace`, `--with` and `--source`. `--positive` records
+that an asset helped (it raises its ranking) and does not trigger a rewrite. See
+[Improve the Library](improve-the-library.md) for what happens to feedback after
+it's recorded.
+
+## Compatibility matrix
+
+Not every agent surface integrates with AKM the same way. The table below
+sets expectations by environment.
+
+| Environment | Core support | Optional/extended support |
+| --- | --- | --- |
+| Shell-capable coding agent | `curate` / `show` / `feedback` via the CLI | Generated prompt block (`akm hints`) or a platform plugin |
+| Claude/OpenCode project layout | Indexed in place through a `BundleAdapter` — no migration needed | `akm clone` selected assets into a writable bundle for editing |
+| IDE assistant without shell access | Not a direct core integration | Requires a plugin, an `akm task`, or an external bridge that can shell out on the assistant's behalf |
+
+A Claude Code `.claude` directory or an OpenCode `.opencode` directory is
+recognized and indexed automatically once added as a source — see
+[Bundle Types](../reference/bundle-types.md) for the full adapter list and
+which formats are read-only versus writable in the current release.
+The native directory remains the source of truth: AKM translates recognized
+assets while reading the bundle and does not synchronize, copy, or write them
+back. The approved target execution rules for these translated agents and
+commands are documented in
+[Agent, Command, Engine, and Model Resolution](../architecture/specs/agent-command-engine-model-design.md).
+
+## AKM complements, rather than replaces
+
+AKM is not a competitor to assistant-native rules/skills or to MCP — it fills
+a different layer. Assistant-native rules and skills give a specific tool
+built-in, tool-specific activation. MCP exposes live tools and resources over
+a protocol. AKM manages portable, versionable capability assets — and the
+retrieval loop that finds and loads them — across whichever tool you're
+sitting in. In short, AKM complements MCP and assistant-native skills rather
+than replacing either.
+
+## Also available
+
+- **Tab completion.** `akm completions --install` sets up shell completions
+  for subcommands and flags. See [CLI Reference](../reference/cli.md#completions).
+- **Dispatching a bundle agent asset.** `akm agent agents/<name> --engine
+  <engine> --prompt "..."` runs a bundle `agents/<name>` persona and model
+  defaults through a named engine — including built-in model aliases like
+  `sonnet` and `opus` that resolve per platform. The current CLI rejects a
+  nonempty tool request at its separate authorization boundary; asset metadata
+  is never authorization by itself. See
+  [Configuration](../reference/configuration.md#engines) for the alias table
+  and [Architecture](../architecture/architecture.md) for how dispatch is
+  built into platform-specific CLI argv per backend.
+- **Install refs vs. asset refs.** `npm:@scope/pkg` and `github:owner/repo`
+  are install refs, accepted only by `akm bundle add`/`akm clone`, and are a
+  different grammar from the `[bundle//]conceptId` refs `show`/`search` use.
+  See [Refs](../reference/refs.md) for the full grammar.
+- **Plugin integrations.** For tighter editor and agent integrations,
+  platform-specific plugins are available in
+  [akm-plugins](https://github.com/itlackey/akm-plugins) (current
+  integrations include OpenCode). Plugins add richer UX — in-editor asset
+  browsing, automatic context injection — but the core `akm` CLI works
+  without them.
+
+## OpenCode plugins: one package per OpenCode major
+
+OpenCode 1 and OpenCode 2 load different plugin APIs, so akm ships one plugin
+package for each. Install only the one that matches the `opencode` you run; akm
+never installs or replaces the `opencode` binary, and `akm upgrade` never adds
+one plugin to the other major's config.
+
+| OpenCode | Plugin package | Config key | Plugin cache |
+| --- | --- | --- | --- |
+| 1 | `akm-opencode` | `"plugin"` | `~/.cache/opencode/packages/akm-opencode@<tag>/` |
+| 2 | `akm-opencode-v2` | `"plugins"` (the key `opencode plugin add` writes) | `~/.cache/opencode/npm/akm-opencode-v2@<tag>/<build>/` |
+
+(`$XDG_CACHE_HOME` and `$XDG_CONFIG_HOME` move both.) Both packages declare the
+same `akm-cli` dependency.
+
+**OpenCode 1.** Add `akm-opencode` to the global config
+(`~/.config/opencode/opencode.json`):
+
+```json
+{ "plugin": ["akm-opencode"] }
+```
+
+**OpenCode 2.**
+
+```sh
+opencode plugin add akm-opencode-v2
+```
+
+This installs the package and adds it to `plugins` in the global config.
+
+**Updating.** `akm upgrade` refreshes the cached plugin of each major it finds,
+holds the CLI to the `akm-cli` those plugins pin, and leaves a plugin alone
+whose config pins another spec such as `akm-opencode@0.8.0`. Use
+`akm upgrade --next` with `akm-opencode@next` / `akm-opencode-v2@next` in the
+config to follow prereleases. The exact rules are in the
+[`akm upgrade` reference](../reference/cli.md#harness-plugins). `akm health`
+warns when either plugin's bundled `akm-cli` differs from the running CLI.
+
+**Which OpenCode akm drives** is detected, not configured: an `opencode` or
+`opencode-sdk` agent engine runs the most recent OpenCode on `PATH` (or its own
+`bin`) and uses the adapters for the major that binary reports; OpenCode 1 logs a
+warning recommending OpenCode 2 (see
+[Configuration](../reference/configuration.md#engines)). It does not change
+which plugin you install, and the plugin choice does not change it.
+
+## See also
+
+- [Configuration](../reference/configuration.md#engines) — named agent engines and model aliases
+- [Discover and Load](discover-and-load.md) — the full curate → show retrieval path
+- [Knowledge Management](knowledge-management.md) — capturing agent-generated memories
+- [Improve the Library](improve-the-library.md) — feeding back usage signals
+- [CLI Reference](../reference/cli.md) — `completions`, `agent`, and `hints` command documentation
+- [Concepts](concepts.md) — refs, origins, and the asset type system
+- [Bundle Types](../reference/bundle-types.md) — how AKM indexes existing project layouts in place

package/docs/guides/wikis.md

@@ -0,0 +1,81 @@
+# LLM Wikis
+
+akm supports [Andrej Karpathy's LLM
+Wiki](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f)
+pattern: a markdown-based knowledge base that an LLM agent maintains
+together with a human, on a filesystem it can read and write directly,
+with no special SDK.
+
+**As of 0.9.0 an LLM wiki is a bundle format, not an akm asset type.**
+The `akm wiki` command family was removed with the 0.9.0 bundle-adapter
+architecture; recognition moved into the first-class LLM Wiki adapter.
+
+## The design
+
+A wiki is a directory. Full stop.
+
+```
+<wiki-root>/
+  schema.md                  rulebook the agent reads first
+  index.md                   catalog of pages, regenerable
+  log.md                     append-only activity log
+  raw/                       immutable ingested sources (never edit)
+  pages/<page>.md            agent-authored pages
+  pages/<topic>/<page>.md    optional nesting
+```
+
+Three layers, from Karpathy's gist:
+
+- **Raw sources** (`raw/`) — what you ingest. Articles, papers,
+  transcripts, notes. Immutable.
+- **Wiki pages** (`pages/<page>.md`, optionally nested) — what the agent
+  writes. Summaries, entity pages, concept pages, FAQs. Cross-referenced
+  via `xrefs:` frontmatter; provenance recorded via `sources:`
+  frontmatter pointing at the cited raw files.
+- **Schema** (`schema.md`) — the per-wiki configuration: voice, page
+  kinds, contradiction policy, any conventions the agent should follow.
+  akm never touches it.
+
+### Principle — akm surfaces, the agent writes
+
+Karpathy's workflow is a conversation between a human, an agent, and a
+filesystem. akm is not that agent. Page writes — create, append, xref,
+log — all use the agent's native `Read` / `Write` / `Edit` tools. akm's
+job is recognition and discovery: it mounts the wiki, indexes the pages,
+and makes them searchable alongside every other asset.
+
+No LLM calls are made anywhere in the wiki surface. No network access.
+
+## How akm sees a wiki (0.9.0)
+
+The LLM Wiki adapter recognizes a wiki **deterministically at install
+time**: a bundle component whose root holds a `schema.md` plus a
+`pages/` directory is mounted as an `llm-wiki` component. From there:
+
+- `pages/**.md` are indexed as searchable documents; each page's ref is
+  `bundle//conceptId`, where the conceptId is the root-relative path
+  minus `.md` (a page at `pages/attention.md` in bundle `research-wiki`
+  is `research-wiki//pages/attention`).
+- `raw/**.md` **are** indexed — as first-class, addressable, searchable
+  `wiki-source` documents (not `page`-type items; a ref looks like
+  `bundle//raw/<slug>`), so citations resolve and raw content is
+  discoverable by search too.
+- `schema.md`, `index.md`, and `log.md` are structural and are never
+  indexed as a concept.
+- `xrefs:` frontmatter becomes cross-reference edges; `sources:`
+  frontmatter becomes citation edges back to raw files.
+
+## Working with a wiki
+
+```sh
+akm bundle add github:team/research-wiki        # install a wiki bundle (or point at a local dir)
+akm search "attention"                   # pages rank alongside all other indexed content
+akm show research-wiki//pages/attention  # read a page by ref
+akm show research-wiki//pages/attention#history
+```
+
+To build a new wiki, create the directory shape above by hand (or have
+your agent do it — `schema.md` plus an empty `pages/` is enough for
+recognition), then add it as a bundle. Ingesting raw sources, writing
+pages, and maintaining `index.md`/`log.md` are the agent's job, guided
+by `schema.md`.

package/docs/integration/bundling-akm.md

@@ -30,10 +30,11 @@ akm migrate apply
 In order, every run applies (or, under `status`/`--dry-run`, plans):
 
 1. **config.json in its current shape** (`configFile`): retired and unknown
-   keys dropped, legacy `extraParams` lifted onto first-class fields, the
-   legacy `stashDir`/`sources[]`/`installed` layout converted to
-   `bundles`/`defaultBundle`. Config loading already does all of this in
-   memory; this persists it under a backup.
+   keys dropped, `configVersion` set. Config loading already does this in
+   memory; this persists it under a backup. A config older than 0.9.15 (the
+   legacy `stashDir`/`sources[]`/`installed` layout, an `extraParams` key
+   that shadows a first-class field) is not converted by 0.10: it blocks
+   with a message to run `akm migrate apply` under akm 0.9.x first.
 2. **Pending `state.db` migrations**, historical-destructive ones included
    (`stateMigrations`). This is the only path (besides `akm upgrade`, which
    calls the same code) that is allowed to apply a destructive migration to an
@@ -98,7 +99,7 @@ same step names):
 `status` is one of:
 
 - **`current`** — no task-source file needs converting, and no config
-  extraParams lift is pending. A no-op boot.
+  rewrite is pending. A no-op boot.
 - **`ready`** — task sources have eligible changes and no config-lift
   conflict; a real `apply` will clear them.
 - **`blocked`** — at least one item cannot be applied automatically (a
@@ -244,7 +245,7 @@ akm-migrate apply
 
 `akm migrate status`/`apply` (under the `akm` CLI) are a thin wrapper over
 this same executable — same plan, same exit codes. Reach for `akm-migrate`
-directly when you don't want `akm`'s `--format`/`--shape`/`--detail` output
+directly when you don't want `akm`'s `--format`/`--detail` output
 handling in the way, e.g. a shell script that just wants the raw JSON line
 on stdout and a plain exit code.
 

package/docs/maintainers/README.md

@@ -0,0 +1,19 @@
+# Maintainer Docs
+
+This is maintainer/contributor documentation, not user-facing. It covers how
+to work on `akm` itself — running it from source, measuring whether changes
+actually improve it, and the current state of the `curate` implementation.
+
+- [Local Development](local-development.md) — the explicit launcher for each
+  kind of contributor check (live source, built launcher, packed-package
+  acceptance, global checkout install) and the verification commands to run
+  before pushing.
+- [Release Checklist](release-checklist.md) — local release validation, exact
+  candidate-SHA semantic/Docker/native-scheduler gates, and the evidence links
+  required before publication.
+- [akm-eval](https://github.com/itlackey/akm-eval) — the evals and benchmarks
+  that measure whether `akm improve` and retrieval changes are actually
+  working. The old in-repo toolkit is retired: see [eval.md](eval.md).
+- [Curate Workmap](curate-workmap.md) — the current `akm curate` contract,
+  where its implementation diverges from intended behavior, and the
+  highest-value next fixes.

package/docs/maintainers/curate-workmap.md

@@ -0,0 +1,335 @@
+# Curate Workmap
+
+> **Implementation note (added later, verified against `src/commands/read/curate.ts`):**
+> much of the "Preferred direction" / "Next Fix Candidates" work below has
+> already shipped. `curateSearchResults` now selects via `selectCuratedStashHits`
+> (score-first ranking through `annotateCurateHit`/`compareCurateHits`/
+> `passesCurateScoreFloor`, not "take the first hit per type"),
+> `collapseCurateFamilies`/`preferBroadRootRepresentative`/`getCurateFamily`
+> implement the asset-family root/child collapsing this document recommends,
+> `shouldRunCurateFallback` triggers fallback on a weak result set (not only
+> on zero hits, reversing the "Fallback Search Behavior" section below), and
+> `appendCurateSupportRef`/`mergeCurateSupportRefs` attach graph-derived
+> support refs (the "Graph Leverage" recommendation). The `orderCuratedTypes`
+> function this document's "Execution Path" section names no longer exists —
+> regex-based type reordering was replaced by the scoring pipeline above. The
+> "Current Behavior" / "Current Curate Contract" sections below were accurate
+> at the time they were written but are now describing the PRE-fix state in
+> several places; re-verify against the functions above before trusting any
+> specific "current behavior" claim in this document. Not fully re-audited
+> line by line — this note flags the drift rather than rewriting the
+> analysis.
+
+## When To Read This
+
+Read this before changing `akm curate` ranking, fallback, follow-up generation, or agent-facing output.
+
+This page is the shortest path to understanding:
+- how `akm curate` currently works
+- which tests pin that behavior
+- where the current implementation diverges from intended product behavior
+- what fix direction has the strongest support from recent review
+
+## Debate Outcome
+
+Recent multi-agent review converged on the same conclusion:
+
+- `curate` should be relevance-first, not diversity-first
+- search ranking should remain the backbone of the shortlist
+- type diversity should be a soft preference for later slots, not a hard override
+- fallback search should run when the initial result set is weak or noisy, not only when it is empty
+- `followUp` should become more action-aware over time, but ranking/fallback correctness comes first
+
+Recommended fix order:
+
+1. Make curate selection score-first and diversity-second.
+2. Relax fallback suppression so one weak phrase hit does not block token fallback.
+3. Revisit follow-up generation after ranking quality improves.
+
+Additional debate outcome:
+
+- simple type-aware reranking is useful only as a thin post-search correction layer
+- root-vs-derived asset families should usually be collapsed to one representative in the top-level shortlist
+- graph data is better suited for attached support refs or navigation hints than for primary reranking in the first iteration
+
+## Current Curate Contract
+
+- CLI entry lives in `src/commands/read/search-cli.ts`.
+- Public entry point is `akmCurate()` in `src/commands/read/curate.ts`.
+- Default curated limit is `4`.
+- Default search source is `stash`.
+- Curate fetches more search hits than it returns: `limit * 4`, minimum `12`.
+- `--type <type>` bypasses diversification and returns top hits of that type.
+- Default multi-type curate currently keeps one best hit per type, then reorders types using regex heuristics.
+- Registry hits only fill leftover slots and are capped at `2`.
+- Bundle items are enriched via `akmShowUnified()` best-effort.
+- Bundle `followUp` is always `akm show <ref>` today.
+- Curate logs both a summary event and per-item retrieval rows for bundle refs.
+
+## Execution Path
+
+Read these first:
+
+- `src/commands/read/search-cli.ts`
+- `src/commands/read/curate.ts`
+- `src/output/shapes/curate.ts`
+- `src/output/text/helpers.ts`
+- `src/commands/read/search.ts`
+- `src/commands/read/show.ts`
+
+Key functions in `src/commands/read/curate.ts` (current names; `orderCuratedTypes()`
+no longer exists — see the implementation note above):
+
+- `akmCurate()`
+- `searchForCuration()`
+- `deriveCurateFallbackQueries()`
+- `mergeCurateSearchResponses()`
+- `curateSearchResults()`
+- `selectCuratedStashHits()` / `annotateCurateHit()` / `compareCurateHits()` / `passesCurateScoreFloor()`
+- `collapseCurateFamilies()` / `preferBroadRootRepresentative()` / `getCurateFamily()`
+- `shouldRunCurateFallback()`
+- `appendCurateSupportRef()` / `mergeCurateSupportRefs()`
+- `enrichCuratedStashHit()`
+
+## Ranking And Selection Rules
+
+Current behavior:
+
+- Search returns scored, ordered hits.
+- Curate then discards most of that ordering by taking the first hit per type.
+- Those per-type winners are reordered using query regex boosts such as `deploy`, `review`, `guide`, `agent`, and `memory`.
+- This can promote obviously lower-score items above much stronger hits.
+
+Why this is a problem:
+
+- search already has strong ranking tests and should remain the primary relevance signal
+- current curate can surface irrelevant filler to satisfy type variety
+- users experience curate as a flagship shortlist, so wrong top results damage trust more than low variety does
+
+Preferred direction:
+
+- preserve top-ranked overall hits first
+- allow diversity only when alternatives are close in score and plausibly relevant
+- keep explicit `--type` behavior unchanged
+
+Small type-aware corrections that are considered in-bounds:
+
+- prefer runnable `script` / concrete `command` over similarly scored `memory` for execution-heavy queries
+- prefer `workflow` / `skill` over adjacent explanation docs for multi-step task queries
+- include `agent` mainly for explicit delegation / persona / prompt-building queries
+- keep `memory` for recall/context queries, not as generic filler
+
+Corrections that are currently considered too risky:
+
+- hard one-per-type quotas
+- large hand-authored type matrices
+- LLM reranking
+- blanket demotion of `memory` or `agent` as types
+
+## Asset Families
+
+Curate should think in terms of asset families, not just isolated types.
+
+Practical examples in this repo:
+
+- `skills/docker-homelab`
+- `knowledge/skills/docker-homelab/references/compose`
+
+Desired behavior:
+
+- broad query like `docker homelab` -> prefer the root asset
+- narrow query like `docker compose reference` -> prefer the child reference page
+- if both are useful, attach the weaker sibling as support instead of spending two top-level slots by default
+
+This should start as an explicit structural heuristic, not semantic lineage inference.
+
+## Fallback Search Behavior
+
+Current behavior:
+
+- `searchForCuration()` only runs fallback token searches when the initial query returns zero hits
+- if the initial query returns even one weak or irrelevant hit, fallback does not run
+- fallback token extraction removes filler words, dedupes tokens, drops tokens shorter than 3 chars, and caps the set at 6
+- fallback is also skipped when normalization leaves only one usable token
+
+Why this is a problem:
+
+- one weak phrase hit can block much better token hits
+- prompt-style queries like `the docker` do not get the obvious one-token fallback
+- meaningful short tokens such as `ai`, `ci`, `cd`, `go`, `js`, or `ts` are lost today
+
+Preferred direction:
+
+- suppress fallback only when the initial result set is actually strong enough
+- allow one-token fallback when that token is clearly the meaningful residue of a prompt-style query
+- preserve a narrow allowlist of meaningful short tokens
+
+## Enrichment And Follow-Up Fields
+
+Current behavior:
+
+- curate enriches bundle hits by calling `akmShowUnified({ ref })`
+- if show fails, enrichment silently degrades to raw search-hit data
+- bundle follow-up remains `akm show <ref>` even for runnable scripts with a concrete `run`
+- registry follow-up uses the registry action, usually `akm bundle add ...`
+
+Product implication:
+
+- output is inspect-first, not act-first
+- this is acceptable for now, but becomes more visible once result quality improves
+
+For agent consumers, the desired optimization order is:
+
+- actionability
+- relevance
+- low duplication / root-asset preference
+- navigability
+- type diversity
+
+## Output Shape And Formatting
+
+Read:
+
+- `src/output/shapes/curate.ts`
+- `src/output/text/helpers.ts`
+
+Important details:
+
+- `curate` has a dedicated output shaper now
+- `brief` still keeps `followUp` and `reason`
+- `--detail agent` trims fields down for agent use
+- text output prints fixed `Next steps:` guidance that assumes `akm show <ref>` is the next action
+
+## Telemetry And Retrieval Signal
+
+Read:
+
+- `src/commands/read/curate.ts`
+- `tests/integration/get-retrieval-counts.test.ts`
+
+Important detail:
+
+- curate writes per-item `usage_events` rows for bundle refs so curated items count as retrieval signal
+
+This means ranking changes do not just affect UX. They also affect downstream improvement-loop evidence.
+
+## Graph Leverage
+
+> **Retired (0.9.17-alpha.9):** the LLM entity graph this section recommends
+> leveraging is gone — `graph-extraction`, `graph_meta`/`graph_files`/
+> `graph_file_entities`/`graph_file_relations`, and `akm show`'s `related`
+> block it fed are all deleted. It was already superseded before that: #935
+> (0.9.17-alpha.8) added the first-class asset->asset edge table this section
+> says doesn't exist (`asset_links`, declared links), and curate's support
+> refs (`buildCurateSupportRefs` in `src/commands/read/curate.ts`) come from
+> declared links now, not graph data — the implementation note at the top of
+> this document already flags that rename. Kept below for historical context
+> only; do not implement against it.
+
+Existing graph signal:
+
+- there is no first-class asset->asset edge table
+- asset relatedness is already derivable via shared-entity overlap
+- `listRelatedPathsForFile()` in `src/indexer/graph/graph-boost.ts` returns related assets with `ref`, `type`, `sharedEntities`, and `relationCount`
+- `akm show` already exposes a lightweight `related` block using that signal
+
+Limits:
+
+- graph coverage depends on graph extraction having run
+- graph is thin or absent on cold bundles
+- graph quality is uneven and generic entities can over-connect assets
+- graph coverage is strongest for `knowledge` / `memory` and should not be assumed for every asset family
+
+Recommended first graph-aware use in curate:
+
+- do not use graph as a primary reranker yet
+- use graph to attach 1-2 support refs or navigation hints to a top-level curated result
+- prefer hints like `see also`, `related`, or `inspect next` over full graph payloads
+- keep full graph exploration in `akm show`'s `related` block
+
+What not to do yet:
+
+- no graph-only reranking
+- no graph-required curate path
+- no full graph dumps in curate output
+- no semantic asset-lineage inference from sparse graph data
+
+## Tests That Pin Behavior
+
+Start with these:
+
+- `tests/integration/curate-command.test.ts`
+- `tests/curate-logic.test.ts`
+- `tests/integration/curate-search-for-curation.test.ts`
+
+What they cover:
+
+- CLI JSON/text output
+- shape/detail behavior
+- usage logging
+- fallback token derivation
+- merge semantics
+- type ordering
+- diversification logic
+- registry filler cap
+- blank query rejection
+- default limit
+- phrase-hit fallback suppression
+- current quality baselines showing irrelevant filler
+
+Search-ranking baselines that curate should respect:
+
+- `tests/integration/db-scoring.test.ts` (no `tests/commands/search.test.ts` exists in the current tree; this is the closest surviving search-scoring baseline, not a confirmed direct successor)
+- `tests/integration/ranking-regression.test.ts`
+
+## Known Gaps / Mismatches
+
+- `docs/guides/discover-and-load.md` currently says curate prefers one strong match per type; that wording is too strong if curate becomes relevance-first.
+- `docs/reference/cli.md` documents `--type`, `--limit`, and `--source`, but does not currently explain the effective `--detail` and `--shape` behavior alongside curate.
+- Some historical AKM refs about curate output shaping are stale because curate now has a dedicated shape implementation.
+
+## Safe Edit Checklist
+
+Before editing curate:
+
+1. Read the three curate-focused test files.
+2. Read `src/commands/read/curate.ts` top to bottom.
+3. Confirm whether you are changing:
+   - post-search selection
+   - fallback triggering
+   - fallback token extraction
+   - output contract
+   - telemetry side effects
+4. Keep CLI surface and output-shape tests passing unless you intentionally change the public contract.
+5. If you improve ranking quality, convert current characterization tests that encode bad behavior into regression tests for the new intended behavior.
+
+## Useful AKM Queries And Refs
+
+Queries:
+
+```sh
+akm search "curate rerank"
+akm search "curate output shape"
+akm search "search discovery curate"
+akm search "curate telemetry usage_events"
+akm search "curate fallback query"
+akm search "curate quality baseline"
+```
+
+Historical context refs:
+
+- `memories/curate-weak-for-ui-test-audit.derived`
+- `knowledge/curate-command-flags-inert`
+
+Note: `knowledge/curate-command-flags-inert` is historical context only. It describes an older output-shaping limitation that is no longer current now that `src/output/shapes/curate.ts` exists.
+
+## Next Fix Candidates
+
+Highest-value next changes:
+
+1. Replace hard one-per-type selection with score-first shortlist selection plus optional soft diversity.
+2. Replace empty-only fallback triggering with weak-result fallback triggering.
+3. Add simple family-aware root/child collapsing for obvious structural bundles.
+4. Add regression tests asserting that docker-specific curate queries stop surfacing unrelated `commands/release-manager` filler.
+5. Attach lightweight related-asset hints using existing graph data after ranking quality is fixed.
+6. Revisit `followUp` generation after ranking quality is fixed.

package/docs/maintainers/eval.md

@@ -0,0 +1,3 @@
+# akm-eval — retired from this repository
+
+The `scripts/akm-eval/` toolkit has left akm: its code is kept, to read and not to run, in [`retired/akm-scripts-akm-eval/`](https://github.com/itlackey/akm-eval/tree/main/retired/akm-scripts-akm-eval) of [itlackey/akm-eval](https://github.com/itlackey/akm-eval), where [`reports/retired-evals.md`](https://github.com/itlackey/akm-eval/blob/main/reports/retired-evals.md) says what each retired eval asked, found and why it ended. It is also in this repository's history, at commit `f57a7fd44b37` and in the tag `v0.9.27-alpha.1`.