akm-cli 0.9.0-rc.8 → 0.9.0

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

@@ -15,36 +15,53 @@
 import { getParsedInvocation } from "../../cli/invocation.js";
 import { parsePositiveIntFlag } from "../../cli/parse-args.js";
 import { defineJsonCommand, output, parseAllFlagValues } from "../../cli/shared.js";
-import { parseRefInput } from "../../core/asset/resolve-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 { resolveUsageEventSource } from "../../indexer/usage/usage-events.js";
-import { getHyphenatedBoolean, getOutputMode } from "../../output/context.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";
+/**
+ * `--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). A ref-prefix query — "<type>:<prefix>/" or bare "<type>:" — enumerates that subtree/type instead of keyword-matching; an explicit --type wins over the parsed type.',
+            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, 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: {
@@ -52,35 +69,54 @@ 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,
@@ -91,8 +127,10 @@ export const searchCommand = defineJsonCommand({
             includeProposed,
             belief,
             includeSessions,
-            disableProjectContext: noProjectContext,
-            disableScopedUtility: noProjectContext,
+            disableProjectContext,
+            disableScopedUtility: disableProjectContext,
+            skipLogging,
+            assets,
             eventSource: resolveUsageEventSource(),
             attributionProjection: outputMode.shape === "agent" ? "agent" : outputMode.detail,
         });
@@ -100,7 +138,10 @@ export const searchCommand = defineJsonCommand({
     },
 });
 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
@@ -108,54 +149,126 @@ 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, 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 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 ([bundle//]conceptId) 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 }) {
@@ -163,55 +276,44 @@ export const showCommand = defineJsonCommand({
         // not a typed asset ref — skip ref validation and let akmShowUnified
         // direct-read it. (the ref parser would reject the non-type `meta`.)
         if (!parseMetaRef(args.ref))
-            parseRefInput(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 `getParsedInvocation()` so the flags don't surface as
-        // user-facing options in `akm show --help`.
+            parseBundleRef(args.ref);
+        rejectRemovedScopeFlag(args.ref);
+        rejectExtraShowPositionals(args._, args.ref);
         const invocation = getParsedInvocation();
-        const akmView = invocation.getFlagValue("--akmView");
-        const akmHeading = invocation.getFlagValue("--akmHeading");
-        const akmStart = invocation.getFlagValue("--akmStart");
-        const akmEnd = invocation.getFlagValue("--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`);
-            }
-        }
         const cliShape = getOutputMode().shape;
+        // 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
-        // (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");
+        // `--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,
+            skipLogging,
             eventSource: resolveUsageEventSource(),
         });
         output("show", result);

package/dist/commands/read/search.js

@@ -8,7 +8,7 @@
  * because there is one data store. Provider fan-out is gone.
  *
  * The orchestration here is thin: build the FTS query, optionally interleave
- * a registry search behind `--source registry|both`, and log a usage event.
+ * a registry search behind `--from registry|all`, and log a usage event.
  * Provider `search()` methods do not exist.
  */
 import { getSources, loadConfig } from "../../core/config/config.js";
@@ -35,23 +35,31 @@ export async function akmSearch(input) {
     const normalizedQuery = query.toLowerCase();
     const searchType = input.type ?? "any";
     const limit = normalizeLimit(input.limit);
-    const parsedSource = parseSearchSource(input.source ?? "stash");
+    const parsedSource = parseSearchSource(input.source ?? "local");
     const config = loadConfig();
-    // Named-source filter: when --source is not a standard enum value, treat it
+    // Named-source filter: when --from is not a standard enum value, treat it
     // as a named source (a `bundles` key). Validated early (before
     // resolveSourceEntries, which can throw STASH_DIR_NOT_FOUND) so that a bad
-    // --source name always produces INVALID_SOURCE_VALUE regardless of stash state.
+    // --from name always produces INVALID_SOURCE_VALUE regardless of stash state.
     let namedSourceName;
     let source;
-    if (parsedSource !== "stash" && parsedSource !== "registry" && parsedSource !== "both") {
+    if (parsedSource !== "local" && parsedSource !== "registry" && parsedSource !== "all") {
         namedSourceName = parsedSource;
         assertNamedSourceExists(config, namedSourceName);
-        source = "stash";
+        source = "local";
     }
     else {
         source = parsedSource;
     }
-    let allSources = resolveReadSources(undefined, config).sources;
+    // A pure `--from registry` search needs no local stash at all (this is the
+    // one path folded in from the retired `akm registry search`, which never
+    // touched local source/stash resolution either) — only resolve local
+    // sources when local hits are actually needed, or a named source narrows
+    // to a local bundle. Without this, `resolveReadSources` (which can throw
+    // STASH_DIR_NOT_FOUND via `resolveStashDir()`) would make registry-only
+    // search fail on a machine with no stash ever configured.
+    const needsLocalSources = source !== "registry" || namedSourceName !== undefined;
+    let allSources = needsLocalSources ? resolveReadSources(undefined, config).sources : [];
     // When a named source was requested, narrow the sources list to just that entry.
     // `resolveSourceEntries` sets `registryId` to `entry.name` for each config source.
     if (namedSourceName !== undefined) {
@@ -61,23 +69,24 @@ export async function akmSearch(input) {
         // disk (resolveSourceEntries skips non-existent dirs). Fall through to the
         // zero-sources guard below which emits a friendly warning.
     }
-    if (allSources.length === 0) {
+    if (needsLocalSources && allSources.length === 0) {
         // stashDir: "" is a safe sentinel here — the response carries zero hits
         // and a warning, so no downstream code will try to use the empty path.
         const response = {
             schemaVersion: 1,
-            stashDir: "",
+            bundleDir: "",
             source,
             hits: [],
-            warnings: ["No stashes configured. Run `akm init` to create your working stash."],
+            warnings: ["No bundles configured. Run `akm bundle create` to create your working bundle."],
             timing: { totalMs: Date.now() - t0 },
         };
         maybeLogSearchEvent(input, query, response);
         return response;
     }
     // Primary stash directory — used for DB path lookups and as the default
-    // stash root. Safe because the empty-sources case is handled above.
-    const stashDir = allSources[0].path;
+    // stash root. Empty when a pure registry search skipped local resolution
+    // entirely (safe: registry-only responses never read `stashDir`).
+    const stashDir = allSources[0]?.path ?? "";
     // Expose the filtered source list to downstream search calls.
     const sources = allSources;
     const filters = normalizeScopeFilters(input.filters);
@@ -95,7 +104,7 @@ export async function akmSearch(input) {
             filters,
             includeProposed,
             beliefFilter: belief,
-            // When `--source <name>` narrowed the source list above, propagate
+            // When `--from <name>` narrowed the source list above, propagate
             // that intent down to the database layer so FTS/vector hits from
             // sources outside the narrowed set are filtered out post-ranking.
             // Without this, the index (which spans every configured source)
@@ -105,13 +114,15 @@ export async function akmSearch(input) {
             disableProjectContext: input.disableProjectContext === true,
             disableScopedUtility: input.disableScopedUtility === true,
         });
-    const registryResult = source === "stash" ? undefined : await searchRegistry(query, { limit, registries: config.registries });
-    if (source === "stash") {
+    const registryResult = source === "local"
+        ? undefined
+        : await searchRegistry(query, { limit, includeAssets: input.assets === true, registries: config.registries });
+    if (source === "local") {
         const localHits = localResult?.hits ?? [];
         const hasResults = localHits.length > 0;
         const response = {
             schemaVersion: 1,
-            stashDir,
+            bundleDir: stashDir,
             source,
             hits: localHits,
             tip: hasResults ? undefined : localResult?.tip,
@@ -122,18 +133,14 @@ export async function akmSearch(input) {
         return response;
     }
     const registryHits = (registryResult?.hits ?? []).map((hit) => {
-        // Use the provider-supplied installRef when available (already correctly
-        // prefixed), otherwise derive it from source + ref for backward compat.
-        const installRef = hit.installRef ??
-            (hit.source === "npm" ? `npm:${hit.ref}` : hit.source === "git" ? `git+${hit.ref}` : `github:${hit.ref}`);
-        // The legacy registry boolean `curated` was removed in v1 (spec §4.2).
+        const installRef = hit.installRef;
         // Hit-level `warnings` are forwarded when the provider surfaced any.
         return {
             type: "registry",
             name: hit.title,
             id: hit.id,
             description: hit.description,
-            action: `akm add ${installRef} -> then search again`,
+            action: `akm bundle add ${installRef} -> then search again`,
             score: hit.score,
             registryName: hit.registryName,
             ...(hit.warnings && hit.warnings.length > 0 ? { warnings: hit.warnings } : {}),
@@ -144,7 +151,7 @@ export async function akmSearch(input) {
         const hasResults = slicedRegistryHits.length > 0;
         const response = {
             schemaVersion: 1,
-            stashDir,
+            bundleDir: stashDir,
             source,
             hits: [],
             registryHits: slicedRegistryHits,
@@ -155,13 +162,13 @@ export async function akmSearch(input) {
         maybeLogSearchEvent(input, query, response);
         return response;
     }
-    // source === "both"
+    // source === "all"
     const allStashHits = (localResult?.hits ?? []).slice(0, limit);
     const warnings = [...(localResult?.warnings ?? []), ...(registryResult?.warnings ?? [])];
     const hasResults = allStashHits.length > 0 || registryHits.length > 0;
     const response = {
         schemaVersion: 1,
-        stashDir,
+        bundleDir: stashDir,
         source,
         hits: allStashHits,
         registryHits,
@@ -209,7 +216,7 @@ function resolveEntryIds(db, hits) {
  *   - `stashHitCount`: number of local stash hits (response.hits, source-only
  *     entries). Always 0 for registry-only searches.
  *   - `registryHitCount`: number of registry hits (response.registryHits).
- *     Only non-zero when source is "registry" or "both".
+ *     Only non-zero when source is "registry" or "all".
  *   - `resultCount`: total across both pools so telemetry reflects the actual
  *     number of results the user saw, regardless of source mode.
  *
@@ -273,7 +280,7 @@ function logSearchEvent(query, response, mode = "keyword", eventSource = "user",
             if (resolvedIds.length > 0) {
                 let scopeKey;
                 try {
-                    const stashPath = response.stashDir;
+                    const stashPath = response.bundleDir;
                     const disabled = disableScopedUtility || (stashPath && isTransientStashPath(stashPath));
                     scopeKey = disabled ? undefined : getCurrentWorkflowScopeKey();
                 }
@@ -291,7 +298,7 @@ function logSearchEvent(query, response, mode = "keyword", eventSource = "user",
 }
 // ── Helpers ──────────────────────────────────────────────────────────────────
 /**
- * Validate a named `--source` against the bundle-derived source list (0.9.0
+ * Validate a named `--from` against the bundle-derived source list (0.9.0
  * spec §10.1: a named source is a `bundles` key, matched via its derived
  * source entry's `name`, or an exact path). Throws INVALID_SOURCE_VALUE with
  * the known names before any stash access can fail differently.
@@ -303,7 +310,7 @@ function assertNamedSourceExists(config, namedSourceName) {
         const validNames = configSources.map((s) => s.name).filter((n) => Boolean(n));
         const hint = validNames.length > 0
             ? `Known source names: ${validNames.join(", ")}`
-            : "No named sources are configured. Run `akm list` to see installed stashes.";
+            : "No named sources are configured. Run `akm bundle list` to see installed bundles.";
         throw new UsageError(`Unknown source name: "${namedSourceName}". ${hint}`, "INVALID_SOURCE_VALUE");
     }
 }
@@ -314,13 +321,12 @@ function normalizeLimit(limit) {
     return Math.min(Math.floor(limit), 200);
 }
 /**
- * Parse the `--source` flag value.
+ * Parse the `--from` flag value.
  *
  * Accepts:
- *   - `stash` (default) — search the local stash index only
+ *   - `local` (default) — search the local stash index only
  *   - `registry`        — search remote registries only
- *   - `both`            — search stash and registries
- *   - `local`           — alias for `stash`
+ *   - `all`             — search local and registries
  *   - Any named source from `config.sources[].name` — filters stash results to
  *     that single source only. The named-source path is detected and resolved
  *     inside `akmSearch`; this function returns the raw name so the caller can
@@ -332,13 +338,21 @@ function normalizeLimit(limit) {
  * at parse time.
  */
 export function parseSearchSource(source) {
-    if (source === "stash" || source === "registry" || source === "both")
+    if (source === "local" || source === "registry" || source === "all")
         return source;
-    // Accept "local" as alias for "stash"
-    if (source === "local")
-        return "stash";
     if (typeof source === "undefined")
-        return "stash";
+        return "local";
+    // 0.9.0 (S8): `--source stash`/`--source both` renamed to `--from
+    // local`/`--from all`. Reject the retired values explicitly — otherwise
+    // they fall through to the named-source lookup below and surface as a
+    // misleading "no source named stash/both" error instead of naming the
+    // rename.
+    if (source === "stash") {
+        throw new UsageError('"stash" was renamed to "local" in 0.9. Use `--from local` instead.', "INVALID_FLAG_VALUE");
+    }
+    if (source === "both") {
+        throw new UsageError('"both" was renamed to "all" in 0.9. Use `--from all` instead.', "INVALID_FLAG_VALUE");
+    }
     // Pass through unknown strings — they may be valid named sources.
     // `akmSearch` will validate against config.sources and throw a UsageError
     // with a helpful message if the name isn't found.
@@ -369,11 +383,12 @@ function normalizeScopeFilters(raw) {
     return Object.keys(out).length > 0 ? out : undefined;
 }
 /**
- * Parse repeated `--filter k=v` / `--scope k=v` argv tokens into a
+ * Parse repeated `--filter k=v` argv tokens into a
  * `StashEntryScope`. Throws a {@link UsageError} for malformed tokens
  * (missing `=`, unknown key) so callers don't see ambiguous misses.
  *
- * Used by both `akm search --filter` and `akm show --scope`.
+ * Used by both `akm search --filter` and `akm show --filter` — the two
+ * commands share one spelling for the scope-narrowing axis.
  */
 export function parseScopeFilterFlags(values, flagName = "--filter") {
     if (values.length === 0)
@@ -398,11 +413,11 @@ export function parseScopeFilterFlags(values, flagName = "--filter") {
 }
 /**
  * Returns true iff `entry.scope` (when present) satisfies every key in
- * `filters`. A missing `entry.scope` (legacy memories) only matches when
- * `filters` is empty / undefined.
+ * `filters`. A missing `entry.scope` only matches when `filters` is empty or
+ * undefined.
  *
  * Filter semantics:
- *   - No filter passed → all entries match (legacy behavior preserved).
+ *   - No filter passed → all entries match.
  *   - `filters.user = "alice"` → entry must have `scope.user === "alice"`.
  *   - Multiple keys → AND-joined; every supplied key must match.
  */