akm-cli 0.9.0-rc.0 → 0.9.0-rc.13

package/dist/commands/read/remember-cli.js

@@ -1,21 +1,29 @@
 // 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/.
+import { getParsedInvocation } from "../../cli/invocation.js";
 import { getStringArg } from "../../cli/parse-args.js";
 import { defineJsonCommand, output, parseAllFlagValues } from "../../cli/shared.js";
 import { UsageError } from "../../core/errors.js";
 import { appendEvent } from "../../core/events.js";
-import { buildMemoryFrontmatter, parseDuration, readMemoryContent, resolveRememberContentArg, runAutoHeuristics, runLlmEnrich, } from "../remember.js";
-import { assertFlatAssetName, inferAssetName, writeMarkdownAsset } from "./knowledge.js";
+import { resolveUsageEventSource } from "../../indexer/usage/usage-events.js";
+import { buildMemoryFrontmatter, parseDuration, readMemoryContent, runAutoHeuristics, runLlmEnrich } from "../remember.js";
+import { assertFlatAssetName, inferAssetName, resolveSupersedesForWrite, resolveSupersedesWriteTarget, resolveXrefsForWrite, writeMarkdownAsset, } from "./knowledge.js";
 import { akmSearch } from "./search.js";
 // ── Helper: similar memory search ────────────────────────────────────────────
 /**
  * Best-effort top-3 similar memory search for `--show-similar`.
  * Scoped to memory: type; excludes the just-written ref.
  */
-async function fetchSimilarMemories(query, excludeRef) {
+async function fetchSimilarMemories(query, excludeRef, eventSource) {
     try {
-        const result = await akmSearch({ query, type: "memory", limit: 4 });
+        const result = await akmSearch({
+            query,
+            type: "memory",
+            limit: 4,
+            eventSource,
+            attributionProjection: "brief",
+        });
         return (result.hits ?? [])
             .filter((h) => "ref" in h && h.ref !== excludeRef)
             .slice(0, 3)
@@ -25,11 +33,22 @@ async function fetchSimilarMemories(query, excludeRef) {
         return [];
     }
 }
+/**
+ * `--target` was renamed to `--bundle` on `remember` in 0.9 (S8). citty is
+ * non-strict, so the retired spelling is silently absorbed rather than
+ * rejected — the memory then lands in the default bundle instead of the one
+ * the caller named, with exit 0 and no error. Reject it explicitly instead.
+ */
+function rejectRetiredTargetFlag() {
+    if (!getParsedInvocation().hasFlag("--target"))
+        return;
+    throw new UsageError("`akm remember --target` was renamed to `--bundle` in 0.9. Use `--bundle <name>` instead.", "INVALID_FLAG_VALUE");
+}
 // ── Command definition ────────────────────────────────────────────────────────
 export const rememberCommand = defineJsonCommand({
     meta: {
         name: "remember",
-        description: "Record a memory in the default stash",
+        description: "Record a memory in the default bundle",
     },
     args: {
         content: {
@@ -66,6 +85,14 @@ export const rememberCommand = defineJsonCommand({
             type: "string",
             description: "Source reference (URL, asset ref, file path, or any free-form string)",
         },
+        xref: {
+            type: "string",
+            description: "Cross-reference ref recorded in the memory's `xrefs:` frontmatter (repeatable: --xref knowledge/auth-flow --xref memories/vpn-note). Each ref must resolve in the write target or a configured source; an unresolvable ref aborts the write.",
+        },
+        supersedes: {
+            type: "string",
+            description: "Ref of an existing asset this memory corrects (repeatable: --supersedes memories/projectA/old-note). Writes the correction with an xref to the old asset AND demotes the old asset (`beliefState: superseded` + `supersededBy`, a metadata-only edit) so ranking prefers the correction and `--belief current` hides the stale version. An unresolvable or self-referencing ref aborts the write; a ref outside the write target and working bundle still writes the correction but skips the demotion (reported as applied: false).",
+        },
         auto: {
             type: "boolean",
             description: "Apply heuristic tagging (code, subjective, source, observed_at) from the body",
@@ -76,9 +103,9 @@ export const rememberCommand = defineJsonCommand({
             description: "Call the configured LLM to propose tags and description (requires LLM config)",
             default: false,
         },
-        target: {
+        bundle: {
             type: "string",
-            description: "Override the write destination. Accepts a source name from your config; falls back to defaultWriteTarget then the working stash.",
+            description: "Override the write destination. Accepts a source name from your config; falls back to defaultWriteTarget then the working bundle.",
         },
         user: {
             type: "string",
@@ -96,19 +123,50 @@ export const rememberCommand = defineJsonCommand({
             type: "string",
             description: "Scope this memory to a channel name (persisted as `scope_channel` frontmatter)",
         },
-        showSimilar: {
+        "show-similar": {
             type: "boolean",
-            description: "Return top-3 similar existing memories in output (opt-in)",
+            // R-062: canonical spelling is kebab-case, matching every other
+            // multi-word flag in the CLI (--fail-on-flagged, --auto-fix, …).
+            // `--showSimilar` (the pre-rename spelling) is kept as an explicit,
+            // documented alias rather than a silent citty auto-alias — citty
+            // registers BOTH the camelCase and kebab-case spelling of any
+            // declared flag name automatically, so this is a rename, not a
+            // breaking change: both spellings already worked, and both keep
+            // working.
+            alias: "showSimilar",
+            description: "Return top-3 similar existing memories in output (opt-in). Alias: --showSimilar.",
         },
     },
     async run({ args }) {
-        const body = readMemoryContent(resolveRememberContentArg(args.content));
+        rejectRetiredTargetFlag();
+        const body = readMemoryContent(args.content);
+        const eventSource = resolveUsageEventSource();
         // `--name` is a flat name; subdirectory placement is `--path`'s job.
         assertFlatAssetName(args.name);
         // Determine if the user has requested any structured metadata mode.
         // Collect all --tag occurrences directly from process.argv because citty
         // only exposes the last value for repeated string flags.
         const rawTags = parseAllFlagValues("--tag");
+        // Collect and validate --xref occurrences (repeatable, same argv pattern
+        // as --tag). Validation happens BEFORE any write: an unresolvable ref is
+        // input validation (UsageError → exit 2) and must leave the stash
+        // untouched. Refs resolvable only in a configured extra stash source are
+        // accepted (cross-stash provenance).
+        const rawSupersedes = parseAllFlagValues("--supersedes");
+        const writeTarget = resolveSupersedesWriteTarget(rawSupersedes, args.bundle);
+        const xrefs = resolveXrefsForWrite(parseAllFlagValues("--xref"), writeTarget);
+        // Collect and validate --supersedes occurrences (repeatable). Same
+        // before-any-write validation contract: an unresolvable ref exits 2 with
+        // nothing written AND nothing demoted (no partial correction). The
+        // superseded refs fold into the new memory's xrefs automatically
+        // (correction provenance per the back-linking conventions); the demotion
+        // itself runs inside writeMarkdownAsset, ordered before the git boundary
+        // commit.
+        const supersedes = resolveSupersedesForWrite(rawSupersedes, writeTarget);
+        for (const s of supersedes) {
+            if (!xrefs.includes(s.ref))
+                xrefs.push(s.ref);
+        }
         // Collect scope flags. Scope alone counts as structured metadata so we
         // emit frontmatter, but it does NOT trigger the "tags required" check —
         // memory + scope (no tags) is a valid combination for multi-tenant use.
@@ -120,7 +178,10 @@ export const rememberCommand = defineJsonCommand({
         }
         const hasScope = Object.keys(scopeFields).length > 0;
         const hasTagRequiringArgs = rawTags.length > 0 || !!args.expires || !!args.source || !!args.description;
-        const hasStructuredArgs = hasTagRequiringArgs || hasScope || args.auto;
+        // --xref counts as structured metadata (it must land in frontmatter) but,
+        // like scope, does NOT trigger the tags-required check — provenance
+        // without tags is a valid write.
+        const hasStructuredArgs = hasTagRequiringArgs || hasScope || args.auto || xrefs.length > 0;
         if (!hasStructuredArgs) {
             // Phase 1B / Rec 7: even the zero-flag hot-path emits
             // `captureMode: hot` + `beliefState: asserted` so user-supplied
@@ -139,8 +200,9 @@ export const rememberCommand = defineJsonCommand({
                 fallbackPrefix: "memory",
                 preferredName: inferAssetName(body, "memory"),
                 force: args.force,
-                target: args.target,
+                target: writeTarget,
                 path: args.path,
+                supersedes,
             });
             appendEvent({
                 eventType: "remember",
@@ -148,7 +210,7 @@ export const rememberCommand = defineJsonCommand({
                 metadata: { path: result.path, force: args.force === true },
             });
             if (args.showSimilar) {
-                const similar = await fetchSimilarMemories(body.slice(0, 500), result.ref);
+                const similar = await fetchSimilarMemories(body.slice(0, 500), result.ref, eventSource);
                 output("remember", { ok: true, ...result, similar });
             }
             else {
@@ -220,6 +282,7 @@ export const rememberCommand = defineJsonCommand({
             description,
             tags,
             source,
+            xrefs,
             observed_at,
             expires,
             subjective,
@@ -228,14 +291,20 @@ export const rememberCommand = defineJsonCommand({
             ...(hasScope ? { scope: scopeFields } : {}),
         });
         const contentWithFrontmatter = `${frontmatterBlock}\n${body}`;
+        // Derive the asset slug from the body, exactly like the hot path above:
+        // `contentWithFrontmatter` starts with the `---` fence, which
+        // inferAssetName would slugify to "" and fall back to a random
+        // memory-<epoch>-<rand> name.
         const result = await writeMarkdownAsset({
             type: "memory",
             content: contentWithFrontmatter,
             name: args.name,
             fallbackPrefix: "memory",
+            preferredName: inferAssetName(body, "memory"),
             force: args.force,
-            target: args.target,
+            target: writeTarget,
             path: args.path,
+            supersedes,
         });
         appendEvent({
             eventType: "remember",
@@ -250,7 +319,7 @@ export const rememberCommand = defineJsonCommand({
             },
         });
         if (args.showSimilar) {
-            const similar = await fetchSimilarMemories((body ?? args.content ?? "").slice(0, 500), result.ref);
+            const similar = await fetchSimilarMemories((body ?? args.content ?? "").slice(0, 500), result.ref, eventSource);
             output("remember", { ok: true, ...result, similar });
         }
         else {

package/dist/commands/read/search-cli.js

@@ -6,51 +6,62 @@
  * from src/cli.ts (WS6) so the God Module shrinks; the `main.subCommands.search`,
  * `.curate`, and `.show` keys and every command's args/output shape are
  * byte-identical. The three commands form a clean cluster: they share the
- * private `resolveEventSource()` helper and the `parseScopeFilterFlags`
+ * usage-event provenance and the `parseScopeFilterFlags`
  * search-source parsers. Handlers whose body is a plain
  * `runWithJsonErrors(async () => { … })` are migrated to `defineJsonCommand`,
  * which emits the same JSON envelope (stdout/stderr/exit-code) as the inline
  * form.
  */
+import { getParsedInvocation } from "../../cli/invocation.js";
 import { parsePositiveIntFlag } from "../../cli/parse-args.js";
 import { defineJsonCommand, output, parseAllFlagValues } from "../../cli/shared.js";
-import { parseAssetRef } from "../../core/asset/asset-ref.js";
+import { parseBundleRef } from "../../core/asset/asset-ref.js";
 import { parseMetaRef } from "../../core/asset/stash-meta.js";
 import { UsageError } from "../../core/errors.js";
-import { getHyphenatedBoolean, getOutputMode, parseFlagValue } from "../../output/context.js";
+import { resolveUsageEventSource } from "../../indexer/usage/usage-events.js";
+import { getOutputMode } from "../../output/context.js";
 import { akmCurate } from "./curate.js";
 import { akmSearch, parseBeliefFilterMode, parseScopeFilterFlags, parseSearchSource } from "./search.js";
 import { akmShowUnified } from "./show.js";
-// AKM_EVENT_SOURCE attributes a query to a `user` invocation, the internal
-// `improve` loop, or the `task` runner so the event log can distinguish
-// genuine demand from machine traffic; any other value is treated as unset.
-function resolveEventSource() {
-    const raw = process.env.AKM_EVENT_SOURCE;
-    if (raw === "improve")
-        return "improve";
-    if (raw === "task")
-        return "task";
-    if (raw === "user")
-        return "user";
-    return undefined;
+/**
+ * `--source` was renamed to `--from` on `search`/`curate` in 0.9 (S8). citty
+ * is non-strict, so the retired spelling is silently absorbed rather than
+ * rejected — the command then runs against the DEFAULT `--from` value
+ * (local) instead of the source the caller named, with exit 0 and no error.
+ * Reject it explicitly instead.
+ */
+function rejectRetiredSourceFlag() {
+    if (!getParsedInvocation().hasFlag("--source"))
+        return;
+    throw new UsageError("`--source` was renamed to `--from` in 0.9. Use `--from local|registry|all` instead.", "INVALID_FLAG_VALUE");
 }
 export const searchCommand = defineJsonCommand({
-    meta: { name: "search", description: "Search the stash" },
+    meta: { name: "search", description: "Search the bundle" },
     args: {
-        query: { type: "positional", description: "Search query (omit to list all assets)", required: false, default: "" },
+        query: {
+            type: "positional",
+            description: 'Search query (omit to list all assets). A conceptId-prefix query — "memories/projecta/", "bundle//", "bundle//skills/" — enumerates that subtree instead of keyword-matching; a trailing "/" is required, and an explicit --type wins over the prefix.',
+            required: false,
+            default: "",
+        },
         type: {
             type: "string",
-            description: "Asset type filter (skill, command, agent, knowledge, workflow, script, memory, env, secret, wiki, lesson, or any). Use workflow to find step-by-step task assets.",
+            description: "Asset type filter — free-form, exact match, unvalidated; an unknown type returns no hits (default: any). Built-ins: skill, command, agent, knowledge, workflow, script, memory, lesson, task, session, fact, env, secret, instruction — plus any adapter-defined type (e.g. website, wiki-source, a wiki pageKind). Use workflow to find step-by-step task assets.",
         },
         limit: { type: "string", description: "Maximum number of results" },
-        source: { type: "string", description: "Search source (stash|registry|both)", default: "stash" },
+        from: { type: "string", description: "Search source (local|registry|all)", default: "local" },
+        assets: {
+            type: "boolean",
+            description: "Include asset-level search results (only meaningful with --from registry|all)",
+            default: false,
+        },
         filter: {
             type: "string",
             description: "Scope filter (repeatable): --filter user=<id> --filter agent=<id> --filter run=<id> --filter channel=<name>. Narrows results without changing ranking.",
         },
         "include-proposed": {
             type: "boolean",
-            description: 'Include entries with quality:"proposed" in the result set. Excluded by default (v1 spec §4.2).',
+            description: 'Include entries with quality:"proposed" in the result set. Excluded by default.',
             default: false,
         },
         belief: {
@@ -58,35 +69,55 @@ export const searchCommand = defineJsonCommand({
             description: "Memory belief filter: all|current|historical. current keeps active memory beliefs; historical keeps contradicted/superseded/archived memory beliefs.",
             default: "all",
         },
-        format: { type: "string", description: "Output format (json|jsonl|text|yaml)" },
-        detail: { type: "string", description: "Detail level (brief|normal|full)" },
-        "no-project-context": {
+        // Declared as the POSITIVE name with `default: true` so citty's native
+        // `--no-<name>` negation (it strips a leading `--no-` from ANY token and
+        // negates the remainder BEFORE consulting the declared-args table — see
+        // node_modules/citty/dist/index.mjs) does the work, the same pattern
+        // `sync --push/--no-push` uses. A flag DECLARED as `no-project-context`
+        // can never be negated: `--no-project-context` parses as "negate
+        // `project-context`", a name nothing declared, leaving the real key at
+        // its default `false` forever (F1/A1).
+        "project-context": {
             type: "boolean",
-            description: "Disable the automatic project-context ranking boost (also disabled by AKM_DISABLE_PROJECT_CONTEXT=1).",
-            default: false,
+            default: true,
+            description: "Automatic project-context ranking boost: assets whose name/tags/aliases match the current working " +
+                "directory's project get a small score boost, and this search's usage also feeds the scoped-utility " +
+                "ranking signal. Default: on. Use --no-project-context to disable BOTH the project-context boost and " +
+                "the scoped-utility signal for this search only.",
         },
         "include-sessions": {
             type: "boolean",
             description: "Include session assets (excluded from default search results via config.search.defaultExcludeTypes).",
             default: false,
         },
+        // Declared as the POSITIVE name with `default: true` for the same reason
+        // as `project-context` above — never declare a flag whose NAME starts
+        // with `no-`.
+        "track-usage": {
+            type: "boolean",
+            default: true,
+            description: "A successful search updates ranking signals (usage-events telemetry and the MemRL utility-score bump " +
+                "used to prioritize future results). Default: on. Use --no-track-usage to run a read-only search that " +
+                "does not influence future ranking.",
+        },
     },
     async run({ args }) {
+        rejectRetiredSourceFlag();
         const query = (args.query ?? "").trim();
-        if (!query) {
-            throw new UsageError('A search query is required. Usage: akm search "<query>" [--type <type>] [--limit <n>]', "MISSING_REQUIRED_ARGUMENT", 'Pass a query like `akm search "docker"` or `akm search "code review" --type skill`.');
-        }
         const type = args.type;
         const limit = parsePositiveIntFlag(args.limit ?? undefined);
-        const source = parseSearchSource(args.source);
+        const source = parseSearchSource(args.from);
         // Repeatable; citty exposes only the last `--filter` value, so read all
         // occurrences directly from argv (same pattern as `--tag`).
         const filterTokens = parseAllFlagValues("--filter");
         const filters = parseScopeFilterFlags(filterTokens, "--filter");
         const includeProposed = args["include-proposed"] === true;
         const belief = parseBeliefFilterMode(typeof args.belief === "string" ? args.belief : undefined);
-        const noProjectContext = getHyphenatedBoolean(args, "no-project-context");
+        const disableProjectContext = args["project-context"] === false;
+        const skipLogging = args["track-usage"] === false;
         const includeSessions = args["include-sessions"];
+        const assets = args.assets === true;
+        const outputMode = getOutputMode();
         const result = await akmSearch({
             query,
             type,
@@ -96,15 +127,21 @@ export const searchCommand = defineJsonCommand({
             includeProposed,
             belief,
             includeSessions,
-            disableProjectContext: noProjectContext,
-            disableScopedUtility: noProjectContext,
-            eventSource: resolveEventSource(),
+            disableProjectContext,
+            disableScopedUtility: disableProjectContext,
+            skipLogging,
+            assets,
+            eventSource: resolveUsageEventSource(),
+            attributionProjection: outputMode.shape === "agent" ? "agent" : outputMode.detail,
         });
         output("search", result);
     },
 });
 export const curateCommand = defineJsonCommand({
-    meta: { name: "curate", description: "Curate the best matching assets for a task or prompt" },
+    meta: {
+        name: "curate",
+        description: "Pick the assets worth loading for a task. Unlike `akm search`, this reranks by intent, attaches a preview and run details per hit, adds related support refs, and summarizes the set — the usual starting point for an agent.",
+    },
     args: {
         // Optional in citty so run() is invoked when omitted; we re-validate
         // below to surface a structured UsageError (exit 2) instead of citty's
@@ -112,102 +149,172 @@ export const curateCommand = defineJsonCommand({
         query: { type: "positional", description: "Task or prompt to curate assets for", required: false },
         type: {
             type: "string",
-            description: "Asset type filter (skill, command, agent, knowledge, workflow, script, memory, env, secret, wiki, lesson, or any). Use workflow to curate step-by-step task assets.",
+            description: "Asset type filter — free-form, exact match, unvalidated; an unknown type returns no hits (default: any). Built-ins: skill, command, agent, knowledge, workflow, script, memory, lesson, task, session, fact, env, secret, instruction — plus any adapter-defined type (e.g. website, wiki-source, a wiki pageKind). Use workflow to curate step-by-step task assets.",
         },
         limit: { type: "string", description: "Maximum number of curated results", default: "4" },
-        source: { type: "string", description: "Search source (stash|registry|both)", default: "stash" },
-        // Output-contract flags. The active values are read from the process-level
-        // singleton (parsed from argv at startup); these declarations make them
-        // visible in `akm curate --help` and document the supported axes.
-        format: { type: "string", description: "Output format (json|jsonl|text|yaml)" },
-        detail: { type: "string", description: "Detail level (brief|normal|full)" },
-        shape: { type: "string", description: "Output projection (human|agent)" },
+        from: { type: "string", description: "Search source (local|registry|all)", default: "local" },
+        // Declared as the POSITIVE name with `default: true` — see the
+        // `project-context` comment on `searchCommand` above for why a flag NAME
+        // must never start with `no-`.
+        "track-usage": {
+            type: "boolean",
+            default: true,
+            description: "A successful curate updates ranking signals (usage-events telemetry for the curated items and the " +
+                "underlying search). Default: on. Use --no-track-usage to run a read-only curate that does not " +
+                "influence future ranking.",
+        },
     },
     async run({ args }) {
+        rejectRetiredSourceFlag();
         if (!args.query || !String(args.query).trim()) {
             throw new UsageError('A curate query is required. Usage: akm curate "<task or prompt>" [--type <type>] [--limit <n>]', "MISSING_REQUIRED_ARGUMENT", 'Describe the task you want assets for, e.g. `akm curate "deploy to prod"`.');
         }
         const type = args.type;
         const limitParsed = parsePositiveIntFlag(args.limit ?? undefined);
         const limit = limitParsed && limitParsed > 0 ? limitParsed : 4;
-        const source = parseSearchSource(args.source ?? "stash");
-        const curated = await akmCurate({ query: args.query, type, limit, source, eventSource: resolveEventSource() });
+        const source = parseSearchSource(args.from ?? "local");
+        const skipLogging = args["track-usage"] === false;
+        const outputMode = getOutputMode();
+        const curated = await akmCurate({
+            query: args.query,
+            type,
+            limit,
+            source,
+            skipLogging,
+            eventSource: resolveUsageEventSource(),
+            attributionProjection: outputMode.shape === "agent" ? "agent" : outputMode.detail,
+        });
         output("curate", curated);
     },
 });
+/**
+ * Reject `--scope` (either spelling) on `akm show` (E-3). `--scope` was
+ * removed in favor of `--filter` (R-047, guardrail 6 — no alias, must keep
+ * failing loudly, not silently). It is deliberately NOT a declared flag on
+ * this command, which means citty's default behavior for an undeclared flag
+ * kicks in — and that default is silent acceptance:
+ *
+ *   - `--scope=user=nobody` (equals form): citty consumes it as an unknown
+ *     flag's own inline value. It never reaches `args._`, so nothing downstream
+ *     ever notices — the command runs to completion and exits 0, having
+ *     silently ignored the caller's (unsatisfied) scope request. This is the
+ *     dangerous case: the caller believes a read was scoped when it was not,
+ *     and it directly violates guardrail 6's "removed spelling must fail
+ *     loudly, not silently".
+ *   - `--scope user=nobody` (space form): citty treats `--scope` as boolean
+ *     and pushes `user=nobody` into `args._` as a stray positional, which
+ *     incidentally trips `rejectExtraShowPositionals`'s arity check below —
+ *     but with the wrong diagnosis (it blames the unrelated retired
+ *     `toc|section|lines|frontmatter|full` view-mode grammar).
+ *
+ * This check runs FIRST, before the positional check, so both spellings are
+ * caught by one explicit, correctly-worded error — it does NOT make `--scope`
+ * work, it only makes the failure loud and the diagnosis accurate.
+ *
+ * NOTE (general issue, out of scope here): citty silently accepts ANY
+ * undeclared flag on ANY command (e.g. `akm info --totallybogus` exits 0) —
+ * this same silent-ignore failure mode applies repo-wide, not just to
+ * `--scope` on `show`. Fixing that generally is a separate, wide-blast-radius
+ * owner decision (same family as E-2, `akm list --type skill`); this function
+ * only closes the `--scope`/`show` instance of it.
+ */
+function rejectRemovedScopeFlag(ref) {
+    const usedScopeFlag = getParsedInvocation().userArgs.some((token) => token === "--scope" || token.startsWith("--scope="));
+    if (!usedScopeFlag)
+        return;
+    throw new UsageError("akm show has no --scope flag — it was removed in 0.9.0. Use --filter instead: " +
+        "--filter user=<id> --filter agent=<id> --filter run=<id> --filter channel=<name>.", "INVALID_FLAG_VALUE", `\`akm show ${ref} --filter user=<id>\` narrows resolution to assets whose frontmatter scope matches.`);
+}
+/**
+ * Reject any positional after the ref. The
+ * `akm show <ref> toc|section "H"|lines A B|frontmatter|full` view grammar was
+ * removed in 0.9.0; its keywords used to be rewritten into hidden flags before
+ * citty saw argv, so without this guard a stale invocation would silently
+ * render the whole item instead of the view the caller asked for.
+ *
+ * `--scope` is handled separately, and earlier, by {@link rejectRemovedScopeFlag}
+ * — by the time this runs, a `--scope`-caused stray positional has already
+ * been intercepted with the correct diagnosis, so this function's generic
+ * message is reached only by genuine leftover view-grammar tokens.
+ */
+function rejectExtraShowPositionals(positionals, ref) {
+    const extra = (Array.isArray(positionals) ? positionals.map(String) : []).slice(1);
+    if (extra.length === 0)
+        return;
+    throw new UsageError(`akm show takes a single ref, but got ${extra.map((token) => `"${token}"`).join(" ")} after "${ref}". ` +
+        "The view-mode grammar (toc|section|lines|frontmatter|full) was removed in 0.9.0 — use " +
+        `\`akm show ${ref}#<heading-slug>\` to read one section, or \`akm show ${ref}\` for the whole item.`, "INVALID_FLAG_VALUE", "An unmatched #fragment lists the available slugs.");
+}
 export const showCommand = defineJsonCommand({
     meta: {
         name: "show",
-        description: "Show a stash asset by ref (e.g. akm show knowledge:guide.md toc, akm show knowledge:guide.md section 'Auth')",
+        description: "Show a bundle asset by ref (e.g. akm show knowledge/guide.md, akm show knowledge/guide.md#auth)",
     },
     args: {
         ref: {
             type: "positional",
-            description: 'Asset ref ([origin//]type:name) optionally followed by a view mode. View modes: `toc` (table of contents), `section "Heading"` (extract one section), `lines <start> <end>` (line range), `frontmatter` (YAML metadata only), `full` (raw file). Example: `akm show knowledge:guide.md section "Auth"`.',
+            description: "Asset ref ([bundle//]conceptId[#fragment]). On a markdown document `#fragment` selects one section by heading slug, and an unmatched fragment lists the available slugs. Example: `akm show knowledge/guide.md#auth`.",
             required: true,
         },
-        format: { type: "string", description: "Output format (json|jsonl|text|yaml)" },
-        detail: { type: "string", description: "Detail level (brief|normal|full)" },
-        shape: { type: "string", description: "Output projection (human|agent|summary)" },
-        scope: {
+        filter: {
             type: "string",
-            description: "Scope filter (repeatable): --scope user=<id> --scope agent=<id> --scope run=<id> --scope channel=<name>. Narrows resolution to assets whose frontmatter scope matches.",
+            description: "Scope filter (repeatable): --filter user=<id> --filter agent=<id> --filter run=<id> --filter channel=<name>. Narrows resolution to assets whose frontmatter scope matches. Same axis as `akm search --filter`.",
+        },
+        // Declared as the POSITIVE name with `default: true` — see the
+        // `project-context` comment on `searchCommand` above for why a flag NAME
+        // must never start with `no-`.
+        "track-usage": {
+            type: "boolean",
+            default: true,
+            description: "A successful show updates ranking signals (usage-events telemetry, including the search-selection " +
+                "linkage when this show follows a recent search). Default: on. Use --no-track-usage to run a " +
+                "read-only show that does not influence future ranking.",
         },
     },
     async run({ args }) {
         // `[origin//]meta[:name]` targets the stash `.meta/` convention, which is
         // not a typed asset ref — skip ref validation and let akmShowUnified
-        // direct-read it. (`parseAssetRef` would reject the non-type `meta`.)
+        // direct-read it. (the ref parser would reject the non-type `meta`.)
         if (!parseMetaRef(args.ref))
-            parseAssetRef(args.ref);
-        // The knowledge-view positional syntax (`akm show knowledge:foo section "Auth"`)
-        // is rewritten to `--akmView` / `--akmHeading` / `--akmStart` / `--akmEnd`
-        // by `normalizeShowArgv` before citty parses argv. We read those values
-        // directly via `parseFlagValue` so the flags don't surface as user-facing
-        // options in `akm show --help`.
-        const akmView = parseFlagValue(process.argv, "--akmView");
-        const akmHeading = parseFlagValue(process.argv, "--akmHeading");
-        const akmStart = parseFlagValue(process.argv, "--akmStart");
-        const akmEnd = parseFlagValue(process.argv, "--akmEnd");
-        let view;
-        if (akmView) {
-            switch (akmView) {
-                case "section":
-                    view = { mode: "section", heading: akmHeading ?? "" };
-                    break;
-                case "lines":
-                    view = {
-                        mode: "lines",
-                        start: Number(akmStart ?? "1"),
-                        end: akmEnd ? parseInt(akmEnd, 10) : Number.MAX_SAFE_INTEGER,
-                    };
-                    break;
-                case "toc":
-                case "frontmatter":
-                case "full":
-                    view = { mode: akmView };
-                    break;
-                default:
-                    throw new UsageError(`Unknown view mode: ${akmView}. Expected one of: full|toc|frontmatter|section|lines`);
-            }
-        }
+            parseBundleRef(args.ref);
+        rejectRemovedScopeFlag(args.ref);
+        rejectExtraShowPositionals(args._, args.ref);
+        const invocation = getParsedInvocation();
         const cliShape = getOutputMode().shape;
-        const explicitDetail = parseFlagValue(process.argv, "--detail");
-        // `--shape summary` selects the compact metadata projection for show
-        // (the legacy `--detail summary` spelling still maps here via the
-        // back-compat path in resolveOutputMode). `--detail brief` forces the
-        // brief response regardless of shape.
-        const showDetail = explicitDetail === "brief" ? "brief" : cliShape === "summary" ? "summary" : undefined;
-        // `--scope` is repeatable — citty only exposes the last value, so read
-        // every occurrence directly from argv (same pattern as `--filter`).
-        const scopeTokens = parseAllFlagValues("--scope");
-        const scope = parseScopeFilterFlags(scopeTokens, "--scope");
+        // F6/R-021 — `show` deliberately does NOT inherit `output.detail` from
+        // config the way `search`/`curate` do via `getOutputMode().detail`
+        // (which merges an explicit `--detail` flag with the config default,
+        // "brief" out of the box). A bare `akm show <ref>` must always return
+        // the FULL asset body regardless of `config.output.detail` — that is
+        // the point of the command. This is a deliberate, permanent exemption,
+        // not an oversight, so it is resolved through exactly one path here:
+        // read the raw `--detail` flag directly (bypassing the config-merged
+        // output mode on purpose) and only ever narrow the response when the
+        // caller EXPLICITLY passed `--detail brief` on this invocation.
+        // `--detail full` (explicit or, since it's also the implicit default,
+        // omitted) and any other value fall through to the full response.
+        const explicitDetail = invocation.getFlagValue("--detail");
+        // `--shape summary` selects the compact metadata projection for show.
+        // `--detail brief` forces the brief response regardless of shape.
+        const showDetail = explicitDetail === "brief"
+            ? "brief"
+            : explicitDetail === "full"
+                ? "full"
+                : cliShape === "summary"
+                    ? "summary"
+                    : undefined;
+        // `--filter` is repeatable — citty only exposes the last value, so read
+        // every occurrence directly from argv (same helper as `akm search`; the two
+        // commands share one spelling for the scope-narrowing axis).
+        const scopeTokens = parseAllFlagValues("--filter");
+        const scope = parseScopeFilterFlags(scopeTokens, "--filter");
+        const skipLogging = args["track-usage"] === false;
         const result = await akmShowUnified({
             ref: args.ref,
-            view,
             detail: showDetail,
             scope,
-            eventSource: resolveEventSource(),
+            skipLogging,
+            eventSource: resolveUsageEventSource(),
         });
         output("show", result);
     },