akm-cli 0.9.31 → 0.10.26101002-alpha

package/dist/api.js

@@ -0,0 +1,45 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * `akm-cli/api` — the one supported programmatic entry point. Everything else
+ * in this package is CLI-only. See docs/reference/api.md for the contract.
+ *
+ * Each export runs the same code path as its CLI command and computes the
+ * document the CLI would print, in-process: no child process, no write to
+ * stdout/stderr, no `process.chdir`, no change to the host's `process.env`,
+ * and no process-level output-mode, quiet or verbose state left changed.
+ */
+import { renderOutput } from "./cli/shared.js";
+import { runCurate } from "./commands/read/search-cli.js";
+import { loadConfig } from "./core/config/config.js";
+import { UsageError } from "./core/errors.js";
+import { withQuiet } from "./core/warn.js";
+import { installLlmUsagePersistenceIfAbsent } from "./llm/usage-persist.js";
+import { resolveOutputMode } from "./output/context.js";
+import { stdoutText } from "./output/stdout.js";
+/**
+ * Returns exactly the stdout text of
+ * `akm --detail agent -q curate <query> [--limit N] [--type T] --format <format>`
+ * including its trailing newline. Rejects with the error the CLI
+ * would fail with: its message, and its error code on the `code` property.
+ */
+export async function curate(query, options = {}) {
+    const format = options.format ?? "json";
+    if (format !== "text" && format !== "json") {
+        throw new UsageError(`Invalid value for --format: ${format}. Expected one of: json|text`, "INVALID_FORMAT_VALUE");
+    }
+    return withQuiet(async () => {
+        // Same startup order as the CLI: config first (an invalid config fails
+        // the call before anything runs), then the output mode from argv + config.
+        const mode = resolveOutputMode(["--detail", "agent", "--format", format], loadConfig().output ?? {});
+        const disposeLlmUsageSink = installLlmUsagePersistenceIfAbsent();
+        try {
+            const curated = await runCurate({ query, type: options.type, limit: options.limit === undefined ? undefined : String(options.limit) }, mode);
+            return stdoutText(renderOutput("curate", curated, { ...mode, format }));
+        }
+        finally {
+            disposeLlmUsageSink();
+        }
+    });
+}

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

@@ -23,8 +23,7 @@ akm search "team-catalog//"                   # List every item in one bundle
 | `--from` | `local`, `registry`, `all`, or a configured bundle name | `local` |
 | `--limit` | number | `20` |
 | `--format` | `json`, `jsonl`, `text`, `yaml`, `md`, `html` | `json` |
-| `--detail` | `brief`, `normal`, `full` | `brief` |
-| `--shape` | `human`, `agent`, `summary` (`summary` only on `show`) | `human` |
+| `--detail` | `brief`, `normal`, `full`, `agent` (`agent`: search, curate and show only) | `brief` |
 
 Ref-prefix queries (a conceptId prefix ending in `/`, optionally bundle-qualified)
 return a deterministic listing, not a relevance ranking. Drop the trailing slash
@@ -90,9 +89,9 @@ akm import ./doc.md --xref knowledge/auth-flow # Merge provenance xrefs into the
 akm import ./new.md --supersedes knowledge/old # Import a correction AND demote the doc it replaces
 akm import - --name scratch-notes < notes.md   # Import stdin as a knowledge doc
 akm import https://example.com/docs/auth       # Fetch one URL and import it as knowledge
-akm import ./doc.md --target my-other-bundle    # Route import to a named writable bundle source
+akm import ./doc.md --bundle my-other-bundle    # Route import to a named writable bundle source
 akm workflow create ship-release               # Create a workflow asset in the bundle
-akm lint --type workflows                      # Parse and compile every .md/.yml workflow source; list every error
+akm lint --type workflows                      # Parse and compile every workflow source; list every error
 akm workflow run workflows/ship-release        # Start or resume and execute the workflow
 akm feedback skills/code-review --positive     # Record that an asset helped (ranks it higher; no rewrite)
 akm feedback agents/reviewer --negative --reason "says to run jest; the suite runs on vitest" # Content wrong or stale: lowers its ranking; improve may repair its frontmatter
@@ -176,9 +175,8 @@ akm secret run secrets/deploy-token GITHUB_TOKEN -- gh release create v1.0.0  #
 
 ## Workflows
 
-Workflows live under `<bundle>/workflows/` as peer `.md` and `.yml` sources.
-Both compile to the same source IR; see `docs/reference/workflow-schema.md` for
-the bounded GitHub-shaped YAML subset.
+Workflows live under `<bundle>/workflows/` as `.md` sources; see
+`docs/reference/workflow-schema.md` for the frontmatter and body syntax.
 
 Ref-based workflow commands are scoped to the current project/worktree/directory,
 so one active run does not block unrelated directories from starting the same
@@ -235,7 +233,6 @@ rename instead of starting fresh, run `bun scripts/rekey-asset-ref.ts <old-ref>
 ## Sync
 
 Commit local changes in a git-backed bundle. Behaviour adapts automatically.
-(`akm save` was the pre-0.8 spelling; it was removed in 0.9.0 — use `akm sync`.)
 
 - **No `.git` directory** — no-op (silent skip)
 - **Git repo, no remote** — stage and commit only (the default bundle always falls here)
@@ -255,15 +252,13 @@ akm sync my-skills -m "Update patterns"      # Sync named bundle with message
 The `--sync` / `--no-sync` and `--push` / `--no-push` flags control this:
 
 ```sh
-akm improve                                   # auto-sync per strategy default (most strategies: on; proactive-maintenance/reflect-distill: off)
+akm improve                                   # auto-sync per strategy default (both strategies: on)
 akm improve --no-sync                         # skip the end-of-run commit
 akm improve --no-push                         # commit but skip push for this run
 akm improve --sync                            # force sync even on strategies that disable it
 ```
 
-Strategy sync defaults: `catchup`, `consolidate`, `default`, `quick`, and
-`thorough` auto-commit + push; `proactive-maintenance` and `reflect-distill`
-skip sync entirely. Override with `--sync` / `--no-sync` flags.
+Strategy sync defaults: `consolidate` and `default` auto-commit + push. Override with `--sync` / `--no-sync` flags.
 
 The `--writable` flag on `akm bundle add` opts a remote git bundle into push-on-sync:
 
@@ -313,7 +308,6 @@ akm config list                               # Show current config
 akm config get <key>                          # Read a value
 akm config set <key> <value>                  # Set a value
 akm config unset <key>                        # Remove a key
-akm config path --all                         # Show all config paths
 ```
 
 ## Other Commands
@@ -331,11 +325,10 @@ akm lint --fix                                # Auto-fix Tier 1 issues
 akm lint --fail-on-flagged                    # Exit non-zero when summary.flagged > 0 (CI-friendly)
 akm upgrade                                   # Upgrade akm using its install method, then update installed harness plugins
 akm upgrade --check                           # Report pending CLI and plugin updates, changing nothing
-akm upgrade --next                            # Follow prereleases (@next); OpenCode needs "akm-opencode@next" in its plugin list
+akm upgrade --next                            # Follow prereleases (@next); OpenCode needs "akm-opencode@next" (or "akm-opencode-v2@next" on OpenCode 2) in its plugin list
 akm help migrate 0.6.0                        # Print migration notes for a release (or: latest)
 akm help bundle                               # Print options and subcommands for one command
-akm help agents --full                        # Print this reference
-akm hints                                     # Print this complete agent guide
+akm hints                                     # Print this complete agent guide (--detail brief for the short one)
 akm completions                               # Print bash completion script
 akm completions --install                     # Install completions
 ```
@@ -354,7 +347,7 @@ akm proposal show <id>                                  # Render the proposal bo
 akm proposal diff <ref-or-id>                           # Diff by ref, UUID, or 8-char prefix
 akm proposal diff skills/akm-dream                      # Diff by asset ref
 akm proposal accept 7c115132                            # Accept by UUID prefix
-akm proposal accept <id> --target team-bundle            # Accept to a named writable bundle source
+akm proposal accept <id> --bundle team-bundle            # Accept to a named writable bundle source
 akm proposal reject skills/my-skill --reason "not ready" # Reject by asset ref
 akm proposal reject <id> --reason "..."                 # Archive with a reason
 akm proposal reopen <id> --reason "..."                 # Undo a rejection: back to pending (refused if the target changed)
@@ -364,11 +357,6 @@ akm proposal extract --auto                             # Mine native session fi
 akm proposal extract --type claude                 # Restrict extraction to one harness
 ```
 
-The flat verbs `akm proposals` / `akm show proposal` / `akm accept` /
-`akm reject` / `akm diff` / `akm revert` were removed in 0.9.0 — use the
-`akm proposal <verb>` forms above. `akm extract` and `akm propose` moved
-here as `proposal extract` / `proposal new`.
-
 ## Scheduled Tasks
 
 Tasks are pure-YAML assets at `<bundle>/tasks/<id>.yml`, bound to the OS
@@ -387,7 +375,7 @@ akm task doctor                                # Scheduler binding + runtime eli
 akm task history                               # Recent run rows (status, timing)
 akm task run <id>                              # Run one task immediately (works when disabled)
 akm task explain <ref>                         # Read-only: declared inputs, target, schedule — spawns nothing
-akm search --type task                         # Enumerate task assets (there is no `task list`)
+akm search --type task                         # Enumerate task assets
 ```
 
 Task files use task source v4 (`version: 4`). There is no `akm:` options bag
@@ -428,7 +416,7 @@ akm log --run <run-id>                         # Events for one workflow-engine
 
 ## Output Control
 
-Result-envelope commands accept `--format`, `--detail`, and `--shape` flags:
+Result-envelope commands accept `--format` and `--detail` flags:
 
 - `--format json` (default) — structured JSON
 - `--format jsonl` — one JSON object per line (streaming-friendly)
@@ -439,9 +427,7 @@ Result-envelope commands accept `--format`, `--detail`, and `--shape` flags:
 - `--detail brief` (default) — compact output
 - `--detail normal` — adds tags, refs, origins
 - `--detail full` — includes scores, paths, timing, debug info
-- `--shape human` (default) — standard projection
-- `--shape agent` — agent-optimized output: strips non-actionable fields
-- `--shape summary` — metadata only (no content/template/prompt), under 200 tokens; only `akm show` has a dedicated summary projection — elsewhere it falls back to `agent` with a warning
+- `--detail agent` — agent-optimized output on `search`, `curate` and `show`: strips non-actionable fields (other commands ignore it)
 
 Run `akm help <command>` or `akm <command> -h` for per-command help. Run
 `akm --help` for the sectioned command overview.

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

@@ -35,7 +35,7 @@ akm remember "note" --bundle my-bundle         # Route write to a named writable
 akm remember "note" --xref knowledge/auth-flow # Cite provenance in frontmatter xrefs (repeatable)
 akm remember "fix" --supersedes memories/old-note # Write a correction AND demote the superseded asset
 akm import ./notes/release-checklist.md       # Import a knowledge doc into your bundle
-akm import ./doc.md --target my-bundle         # Route import to a named writable bundle source
+akm import ./doc.md --bundle my-bundle         # Route import to a named writable bundle source
 akm proposal diff skills/akm-dream            # Diff proposal by ref, UUID, or 8-char prefix
 akm proposal accept 7c115132                  # Accept by UUID prefix
 akm proposal reject skills/my-skill --reason "..."  # Reject by ref

package/dist/assets/improve-strategies/default.json

@@ -1,5 +1,5 @@
 {
-  "description": "Standard improve pass — reflect (rewrites only from negative feedback), distill, consolidation (promotion plus the reviewed pair-pass retire/supersede proposals), and validation. Memory inference is listed below but only runs when experimental.improveAutonomy is set; improve-stage extract and proactive maintenance off.",
+  "description": "Standard improve pass — reflect (rewrites only from negative feedback), distill, consolidation (promotion plus the reviewed pair-pass retire/supersede proposals), and validation. Memory inference is listed below but only runs when experimental.improveAutonomy is set; improve-stage extract off. Proactive maintenance plans up to 15 assets not reflected or distilled for 30 days.",
   "processes": {
     "reflect": {
       "enabled": true,
@@ -11,8 +11,8 @@
     "memoryInference": { "enabled": true },
     "extract": { "enabled": false, "triage": { "enabled": true, "minScore": 2 } },
     "validation": { "enabled": true },
-    "proactiveMaintenance": { "enabled": false, "dueDays": 30, "maxPerRun": 15 },
-    "triage": { "enabled": false, "applyMode": "queue", "policy": "personal-stash" }
+    "proactiveMaintenance": { "enabled": true, "dueDays": 30, "maxPerRun": 15 },
+    "triage": { "enabled": true, "applyMode": "promote", "maxAcceptsPerRun": 200 }
   },
   "sync": { "enabled": true, "push": true }
 }

package/dist/assets/prompts/consolidate-pair.md

@@ -1,19 +1,21 @@
-You compare two assets from one person's agent-memory library (memories and knowledge notes an AI coding agent reads). Asset A is the OLDER one and asset B the NEWER one, by the dates shown. akm deletes one of them only when the other keeps every claim a reader would need, so your two lists decide what is safe to delete.
+You compare two assets from one person's agent-memory library (memories and knowledge notes an AI coding agent reads). Asset A is the OLDER one and asset B the NEWER one, by the dates shown, unless both carry the same date and are labelled "same age". akm deletes one of them only when the other keeps every claim a reader would need, so your two lists decide what is safe to delete.
 
 First list what each asset has that the other lacks:
-- "onlyInA": every durable claim of A that B neither states nor updates.
-- "onlyInB": every durable claim of B that A neither states nor updates.
+- "onlyInA": every durable claim of A that B does not state or replace.
+- "onlyInB": every durable claim of B that A does not state or replace.
 
 A durable claim is a fact, decision, value, command, flag, path, file name, URL, number, version, name, error message, condition or rule someone would act on. Ignore wording, headings, dates of writing, tags and boilerplate. A claim is stated when the other asset says it in any wording or format. It is not stated when the other asset is vaguer (a config file instead of the specific path) or drops a number, command, step or condition. Write each item as a short phrase that quotes its identifier. Use [] when there is nothing.
 
+B replaces a claim of A only when both are about the same named thing (the same service, integration, partner, component, region or file) and B gives a new value for it that is current: B says so (now, instead of, since, renamed, corrected, no longer) or B is created later than A. Notes about different named things never replace each other, whatever their dates: list each one's own name, value and path as its claims. A different value for the same thing with neither sign is a conflict, not a replacement: list A's value in "onlyInA" and B's value in "onlyInB".
+
 Then classify the relation as exactly one of:
 - "duplicate": both lists are empty.
 - "subsumed": exactly one list is empty. The asset with the empty list is redundant.
-- "supersedes": B updates, corrects, reverses or replaces a claim in A (a newer version, a changed decision, a fixed bug, a new value), and onlyInA is empty.
-- "contradicts": they make logically exclusive claims about the same thing and nothing shows which one is current.
+- "supersedes": B replaces a claim in A as defined above (a newer version, a changed decision, a fixed bug, a new value), and onlyInA is empty.
+- "contradicts": they make logically exclusive claims about the same thing and nothing shows which one is current: B does not say it replaces the claim and was not created later.
 - "overlap": same subject, and both lists have items.
-- "unrelated": different subjects or different facts that happen to share words.
+- "unrelated": different subjects, or different named things written to one layout (two services, partners or regions), or different facts that happen to share words.
 
 Set "redundant" to the asset that could be deleted with no loss: "A" for "duplicate", the asset with the empty list for "subsumed", "A" for "supersedes"; else null. Set "stale" to "A" when the relation is "supersedes", else null.
 
-Answer ONLY with JSON: {"onlyInA": ["..."], "onlyInB": ["..."], "relation": "...", "redundant": "A"|"B"|null, "stale": "A"|null, "confidence": 0.0-1.0, "reason": "<at most 25 words: name the asset that can be deleted and what the other asset still holds>"}
+Answer ONLY with JSON: {"onlyInA": ["..."], "onlyInB": ["..."], "relation": "...", "redundant": "A"|"B"|null, "stale": "A"|null, "confidence": 0.0-1.0, "reason": "<at most 25 words: name the asset that can be deleted and what the other asset still holds; for supersedes, quote the words of B that replace the claim or say B is created later>"}

package/dist/cli/shared.js

@@ -156,19 +156,8 @@ export const GLOBAL_OUTPUT_ARGS = {
     format: { type: "string", description: "Output format: json|jsonl|yaml|text|md|html (global flag)" },
     detail: {
         type: "string",
-        description: "Detail level (verbosity): brief|normal|full (global flag).",
-    },
-    // R-050(c): single-sourced with the root command's own `--shape` help
-    // (`main.args.shape` in src/cli.ts, which spreads this object) so the
-    // caveat is visible from every leaf's own `--help`, not only the top-level
-    // one. `summary` outside `show` falls back to `agent` with a warning
-    // (shapeForCommand in src/output/shapes.ts) — `--shape` is a global flag,
-    // so a script that passes it to a mixed batch of commands still works.
-    shape: {
-        type: "string",
-        description: "Output projection: human|agent|summary (global flag). 'agent' trims to agent-essential fields; " +
-            "'summary' only has a dedicated projection on 'akm show' — elsewhere it falls back to 'agent' with a " +
-            "warning. Default: human.",
+        description: "Detail level: brief|normal|full (verbosity), or agent (trims search, curate and show to agent-essential " +
+            "fields; other commands ignore it) (global flag).",
     },
     output: {
         type: "string",
@@ -294,51 +283,45 @@ export function outputWithExitCode(command, result, exitCode) {
 }
 export function output(command, result) {
     const mode = getOutputMode();
-    const shaped = shapeForCommand(command, result, mode.detail, mode.shape);
-    if (mode.format === "jsonl") {
-        outputJsonl(command, shaped);
+    const { format } = mode;
+    if (format === "jsonl") {
+        outputJsonl(command, shapeForCommand(command, result, mode.detail, mode.shape));
         return;
     }
+    deliverRendered(renderOutput(command, result, { ...mode, format }), mode.outputPath);
+}
+/**
+ * Shape and render a command result into the document `output()` delivers.
+ * Pure: reads no process-level output mode and writes nothing, so in-process
+ * callers (`src/api.ts`) get text byte-identical to the CLI's stdout from an
+ * explicit `mode`.
+ */
+export function renderOutput(command, result, mode) {
+    const shaped = shapeForCommand(command, result, mode.detail, mode.shape);
     switch (mode.format) {
         case "json":
-            deliverRendered(JSON.stringify(shaped, null, 2), mode.outputPath);
-            return;
+            return JSON.stringify(shaped, null, 2);
         case "yaml":
-            deliverRendered(yamlStringify(shaped), mode.outputPath);
-            return;
-        case "text": {
+            return yamlStringify(shaped);
+        case "text":
             // D7 — registry first, generic rendering of the shaped envelope second.
-            // Mirrors the md/html fallback immediately below: a command with no
-            // registered text formatter used to fall through to
+            // A command with no registered text formatter used to fall through to
             // `JSON.stringify(shaped, null, 2)`, i.e. silently hand back JSON while
-            // claiming `--format text` — the same "wrong format wearing the right
-            // flag" bug D7 already closed for md/html. `renderGenericText` (a
-            // DISTINCT function from `renderGenericMarkdown` — see its doc comment
-            // in src/output/generic-render.ts for why reusing the md renderer here
-            // was itself a version of the same bug) renders flat `key=value` text
-            // matching the house style already established by registered text
-            // formatters like `config list`.
-            const plain = formatPlain(command, shaped, mode.detail);
-            deliverRendered(plain ?? renderGenericText(command, shaped), mode.outputPath);
-            return;
-        }
-        case "md": {
-            // D7 — registry first, generic rendering of the shaped envelope second.
-            // No command emits JSON under `--format md` any more: silently handing
-            // back the wrong format was the worst of the three behaviours this
-            // replaced.
-            const rendered = getMdRendererHandler(command)?.(shaped, mode.detail);
-            deliverRendered(rendered ?? renderGenericMarkdown(command, shaped), mode.outputPath);
-            return;
-        }
-        case "html": {
+            // claiming `--format text`. `renderGenericText` renders flat
+            // `key=value` text matching the house style of registered formatters
+            // like `config list`; it is a DISTINCT function from
+            // `renderGenericMarkdown` (see src/output/generic-render.ts).
+            return formatPlain(command, shaped, mode.detail) ?? renderGenericText(command, shaped);
+        case "md":
+            // D7 — registry first, generic rendering second; no command emits JSON
+            // under `--format md`.
+            return getMdRendererHandler(command)?.(shaped, mode.detail) ?? renderGenericMarkdown(command, shaped);
+        case "html":
             // `akm health` and `akm metrics` are the only commands with a bespoke
             // HTML report, so they are called directly rather than through a
             // registry with two possible registrants (see `output/render-registry.ts`).
-            const rendered = command === "health" ? renderHealthHtml(shaped) : command === "metrics" ? renderMetricsHtml(shaped) : null;
-            deliverRendered(rendered ?? renderGenericHtml(command, shaped), mode.outputPath);
-            return;
-        }
+            return ((command === "health" ? renderHealthHtml(shaped) : command === "metrics" ? renderMetricsHtml(shaped) : null) ??
+                renderGenericHtml(command, shaped));
     }
 }
 // parseAllFlagValues moved to ./invocation (chunk-9 WI-9.9 argv-normalization

package/dist/cli/unknown-flags.js

@@ -28,7 +28,6 @@
 import { UsageError } from "../core/errors.js";
 import { warn } from "../core/warn.js";
 import { cittyComparableName, findCittyTopLevelCommandIndex, toAliasArray, } from "./invocation.js";
-import { retiredFlagHint } from "./retired-commands.js";
 /**
  * Commands that must never refuse on an unrecognized flag — `akm info` warns
  * and continues instead of exiting 2, the same tolerance a bare `akm help
@@ -39,36 +38,6 @@ import { retiredFlagHint } from "./retired-commands.js";
 const UNKNOWN_FLAG_TOLERANT_COMMANDS = new Set(["info"]);
 /** Flags citty implements itself, which no command declares. */
 const IMPLICIT_FLAGS = ["help", "h", "version", "v"];
-/**
- * Retired flags whose commands still diagnose them THEMSELVES, with a message
- * that names the replacement ("`--scope` was removed, use `--filter`",
- * "`--source` was renamed to `--generator`"). A generic "unknown flag" would
- * preempt the better diagnosis, so these are passed through — but ONLY on the
- * command path that owns the diagnostic, keyed by the resolved path. On every
- * other command the same spelling is a genuine typo and still fails fast
- * A retired flag is rejected everywhere else, where silently dropping it could
- * run a real mutation.
- *
- * Shrink-only: when a command drops its bespoke diagnostic, drop the entry and
- * the generic error takes over.
- */
-const SELF_DIAGNOSED_FLAGS = new Map(Object.entries({
-    show: ["akmView", "scope"], // removed view grammar; --scope points at --filter
-    index: ["enrich", "re-enrich"], // removed index-time enrichment flags
-    "proposal accept": ["source"], // renamed to --generator
-    "proposal reject": ["source"], // renamed to --generator
-    "proposal drain": ["profile"], // retired, points at --strategy
-    search: ["source"], // renamed to --from
-    curate: ["source"], // renamed to --from
-    "task list": ["source"], // renamed to --from (alias of `search --type task`, #951)
-    remember: ["target"], // renamed to --bundle
-    clone: ["target"], // renamed to --bundle
-    improve: ["auto-accept", "target"], // retired in 0.9.0 / renamed to --bundle
-    "task add": ["target"], // renamed to --bundle
-    "task run": ["target"], // renamed to --bundle
-    "task history": ["target"], // renamed to --bundle
-    "task sync": ["target"], // renamed to --bundle
-}).map(([path, flags]) => [path, new Set(flags.map(cittyComparableName))]));
 /**
  * Union the arg definitions declared along the resolved command path. The
  * subcommand walk delegates to {@link findCittyTopLevelCommandIndex} — the
@@ -111,6 +80,12 @@ function collectKnownArgs(root, rawArgs) {
             break;
         const idx = findCittyTopLevelCommandIndex(args, (cmd.args ?? {}));
         const token = idx >= 0 ? args[idx] : undefined;
+        // A command that takes a positional AND has subcommands (`improve [scope]`
+        // beside `improve report`) is itself the target when the token is absent
+        // or names none of them.
+        const takesPositional = Object.values(cmd.args ?? {}).some((def) => def.type === "positional");
+        if (takesPositional && (token === undefined || !subCommands[token]))
+            break;
         // A group with no subcommand token: citty reports "no command specified".
         if (token === undefined)
             return { names, valueFlags, booleanFlags, displayNames, path, resolved: false };
@@ -166,15 +141,6 @@ export function closestMatch(attempted, candidates, threshold) {
  * @param attempted  The spelling to edit-distance against `--long` candidates.
  */
 function throwUnknownFlag(shown, attempted, known) {
-    // Flags the 0.9 overhaul removed outright get their retirement note, not a
-    // did-you-mean — same reasoning as `retiredCommandHint` in src/cli.ts:
-    // edit distance can point at an unrelated survivor rather than the real
-    // replacement procedure (e.g. `index --background` is closer to no other
-    // `index` flag than it is to any useful suggestion).
-    const retired = retiredFlagHint(known.path, attempted);
-    if (retired) {
-        throw new UsageError(`Unknown flag "${shown}".`, "UNKNOWN_FLAG", retired);
-    }
     const threshold = Math.max(2, Math.ceil(attempted.length / 3));
     const suggestion = closestMatch(attempted, known.displayNames, threshold);
     throw new UsageError(`Unknown flag "${shown}".`, "UNKNOWN_FLAG", suggestion
@@ -207,7 +173,6 @@ export function assertKnownFlags(root, rawArgs) {
     // scanner, so it needs the identical exemption).
     const dynamicNamedFlagCommands = new Set(["workflow run", "task run", "task explain"]);
     const dynamicWorkflowParams = dynamicNamedFlagCommands.has(known.path.join(" "));
-    const selfDiagnosed = SELF_DIAGNOSED_FLAGS.get(known.path.join(" "));
     const tolerant = UNKNOWN_FLAG_TOLERANT_COMMANDS.has(known.path.join(" "));
     for (let i = 0; i < ownArgs.length; i += 1) {
         const token = ownArgs[i];
@@ -250,8 +215,6 @@ export function assertKnownFlags(root, rawArgs) {
             ? rawName.slice(3)
             : undefined;
         const candidates = [cittyComparableName(rawName), ...(negated ? [cittyComparableName(negated)] : [])];
-        if (selfDiagnosed !== undefined && candidates.some((name) => selfDiagnosed.has(name)))
-            continue;
         if (!candidates.some((name) => known.names.has(name))) {
             // `workflow run` owns one deliberately dynamic namespace: long options
             // become exact-name workflow parameters and are checked against the

package/dist/cli.js

@@ -58,7 +58,6 @@ process.on("uncaughtException", (err) => {
 import fs from "node:fs";
 import { defineCommand, parseArgs, renderUsage, runCommand, showUsage } from "citty";
 import { findCittyTopLevelCommandIndex, getParsedInvocation, parseAllFlagValues, resolveHelpMigrateVersionArg, setParsedInvocation, } from "./cli/invocation.js";
-import { retiredCommandHint } from "./cli/retired-commands.js";
 import { defineGroupCommand, EXIT_CODES, emitJsonError, GLOBAL_OUTPUT_ARGS, output, runWithJsonErrors, } from "./cli/shared.js";
 import { assertKnownFlags, closestMatch } from "./cli/unknown-flags.js";
 import { agentCommand, lintCommand } from "./commands/agent/contribute-cli.js";
@@ -137,7 +136,7 @@ function printSetupTtyHint(result) {
     if (!result?.bundleDir)
         return;
     console.error(plainize(`\n✓ Bundle created at ${result.bundleDir}\n` +
-        '  Next: `akm bundle add <source>`, `akm index`, `akm search "<query>"`, `akm help agents`'));
+        '  Next: `akm bundle add <source>`, `akm index`, `akm search "<query>"`, `akm hints`'));
 }
 /**
  * Module Naming:
@@ -264,7 +263,7 @@ const healthCommand = defineCommand({
     args: {
         // R-051: `health` is a raw `defineCommand` (not `defineJsonCommand`), so
         // it does not get `GLOBAL_OUTPUT_ARGS` for free. `--format`/`--detail`/
-        // `--shape`/`--output` already parsed correctly here (this command has
+        // `--output` already parsed correctly here (this command has
         // no positional for a stray value to fall into), so this is purely a
         // `--help` visibility / consistency fix, not a behavior change.
         ...GLOBAL_OUTPUT_ARGS,
@@ -383,9 +382,6 @@ const healthCommand = defineCommand({
         }
     },
 });
-function loadAgentHints(full) {
-    return full ? EMBEDDED_HINTS_FULL : EMBEDDED_HINTS;
-}
 const hintsCommand = defineCommand({
     meta: {
         name: "hints",
@@ -401,7 +397,7 @@ const hintsCommand = defineCommand({
     run({ args }) {
         return runWithJsonErrors(() => {
             const detail = parseDetailLevel(args.detail) ?? "normal";
-            process.stdout.write(loadAgentHints(detail !== "brief"));
+            process.stdout.write(detail === "brief" ? EMBEDDED_HINTS : EMBEDDED_HINTS_FULL);
         });
     },
 });
@@ -504,24 +500,6 @@ const helpCommand = defineGroupCommand({
     },
     subCommands: {
         ...commandHelpTopics,
-        agents: defineCommand({
-            meta: {
-                name: "agents",
-                description: "Print agent instructions on how to use akm — the short guide by default; pass --full for the complete guide",
-            },
-            args: {
-                full: {
-                    type: "boolean",
-                    default: false,
-                    description: "Print the complete guide instead of the short one.",
-                },
-            },
-            run({ args }) {
-                return runWithJsonErrors(() => {
-                    process.stdout.write(loadAgentHints(args.full === true));
-                });
-            },
-        }),
         migrate: defineCommand({
             meta: {
                 name: "migrate",
@@ -855,7 +833,7 @@ function renderCommandSections() {
  * USAGE line + global OPTIONS, then cuts the string before citty's own
  * "COMMANDS" heading (present because `main` has `subCommands`) and appends
  * the grouped sections plus a one-line bundle/ref-grammar tagline and the
- * `akm help agents` pointer.
+ * `akm hints` pointer.
  */
 async function renderSectionedRootHelp() {
     const base = await renderUsage(main, undefined);
@@ -872,7 +850,7 @@ async function renderSectionedRootHelp() {
             "`akm search` output rather than synthesizing them.",
         "",
         "Run `akm help <command>` or `akm <command> --help` for details on any command.",
-        "Agents: run `akm hints` for the complete guide or `akm help agents` for the short guide.",
+        "Agents: run `akm hints` for the complete guide, or `akm hints --detail brief` for the short one.",
     ].join("\n");
     return [head, "", renderCommandSections(), "", epilogue].join("\n");
 }
@@ -910,7 +888,7 @@ function findUnknownCommandAttempt(rawArgs) {
 }
 /** Closest command within a length-scaled distance threshold (shared DP in cli/unknown-flags.ts). */
 function closestCommandMatch(attempted, candidates) {
-    return closestMatch(attempted, candidates, Math.max(2, Math.ceil(attempted.length / 2)));
+    return closestMatch(attempted, candidates, Math.floor(attempted.length / 3));
 }
 const CLI_HELP_POINTER = "Run `akm --help` for usage.";
 /**
@@ -944,12 +922,8 @@ function cittyCliErrorUsageCode(error) {
 function toUsageErrorFromCliError(error, rawArgs) {
     const code = cittyCliErrorUsageCode(error);
     const attempt = code === "UNKNOWN_COMMAND" ? findUnknownCommandAttempt(rawArgs) : undefined;
-    // Retired spellings from the 0.9 hard break get their replacement, not a
-    // did-you-mean: edit distance suggests the WRONG command for most of them
-    // (`init`→`info`, `update`→`upgrade`), and agents follow suggestions.
-    const retired = attempt ? retiredCommandHint(attempt.parentPath, attempt.attempted) : undefined;
-    const suggestion = retired === undefined && attempt ? closestCommandMatch(attempt.attempted, attempt.candidates) : undefined;
-    const hint = retired ?? (suggestion ? `Did you mean \`${suggestion}\`? ${CLI_HELP_POINTER}` : CLI_HELP_POINTER);
+    const suggestion = attempt ? closestCommandMatch(attempt.attempted, attempt.candidates) : undefined;
+    const hint = suggestion ? `Did you mean \`${suggestion}\`? ${CLI_HELP_POINTER}` : CLI_HELP_POINTER;
     // citty colorizes error.message with ANSI escapes even when stdout/stderr
     // is not a TTY. Strip them so the JSON envelope's `error` field is plain
     // text instead of embedding raw escape sequences.

package/dist/commands/agent/contribute-cli.js

@@ -112,7 +112,7 @@ export const lintCommand = defineCommand({
     args: {
         // R-051: `lint` is a raw `defineCommand` (not `defineJsonCommand`), so it
         // does not get `GLOBAL_OUTPUT_ARGS` for free. `--format`/`--detail`/
-        // `--shape`/`--output` already parsed correctly here (this command has no
+        // `--output` already parsed correctly here (this command has no
         // positional for a stray value to fall into), so this is purely a
         // `--help` visibility / consistency fix, not a behavior change.
         ...GLOBAL_OUTPUT_ARGS,

package/dist/commands/completions.js

@@ -7,8 +7,7 @@ import path from "node:path";
 import { placementTypes } from "../core/asset/asset-placement.js";
 const FLAG_VALUES = {
     "--format": [{ values: ["json", "jsonl", "yaml", "text", "md", "html"] }],
-    "--detail": [{ values: ["brief", "normal", "full"] }],
-    "--shape": [{ values: ["human", "agent", "summary"] }],
+    "--detail": [{ values: ["brief", "normal", "full", "agent"] }],
     "--type": [{ values: () => [...placementTypes(), "any"] }],
     "--shell": [{ values: ["bash"] }],
     "--from": [{ paths: ["akm search", "akm curate"], values: ["local", "registry", "all"] }],

package/dist/commands/config-cli.js

@@ -14,11 +14,11 @@
  */
 import { isDeepStrictEqual } from "node:util";
 import { defineGroupCommand, defineJsonCommand, output } from "../cli/shared.js";
-import { isRecord, resolveStashDir } from "../core/common.js";
+import { isRecord } from "../core/common.js";
 import { DEFAULT_CONFIG, getConfigValueSource, loadConfig, mutateConfig, parseAndValidateConfigText, resolveConfigRefSource, } from "../core/config/config.js";
 import { configGet, configSet, configUnset, unknownKeyHint } from "../core/config/config-walker.js";
 import { UsageError } from "../core/errors.js";
-import { getCacheDir, getConfigPath, getDbPath, getDefaultStashDir } from "../core/paths.js";
+import { getConfigPath } from "../core/paths.js";
 import { formatRegistryUrl } from "../core/registry-url.js";
 // ── Public API ──────────────────────────────────────────────────────────────
 export function getConfigValue(config, key) {
@@ -118,32 +118,9 @@ export const configCommand = defineGroupCommand({
     meta: { name: "config", description: "Show and manage configuration" },
     subCommands: {
         path: defineJsonCommand({
-            meta: { name: "path", description: "Show paths to config, bundle, cache, and index" },
-            args: {
-                all: { type: "boolean", description: "Show all paths (config, bundle, cache, index)", default: false },
-            },
-            run({ args }) {
-                const configPath = getConfigPath();
-                if (args.all) {
-                    let stashDir;
-                    try {
-                        stashDir = resolveStashDir();
-                    }
-                    catch {
-                        stashDir = `${getDefaultStashDir()} (not initialized)`;
-                    }
-                    const cacheDir = getCacheDir();
-                    const result = {
-                        config: configPath,
-                        bundle: stashDir,
-                        cache: cacheDir,
-                        index: getDbPath(),
-                    };
-                    output("config", result);
-                }
-                else {
-                    console.log(configPath);
-                }
+            meta: { name: "path", description: "Print the path to the config file" },
+            run() {
+                console.log(getConfigPath());
             },
         }),
         list: defineJsonCommand({