akm-cli 0.9.0-rc.4 → 0.9.0-rc.6

package/dist/commands/proposal/validators/proposal-quality-validators.js

@@ -59,7 +59,23 @@
  */
 // ── Reflect-size guard ───────────────────────────────────────────────────────
 import { parseFrontmatter } from "../../../core/asset/frontmatter.js";
+import { parseRefInput } from "../../../core/asset/resolve-ref.js";
 import { DESCRIPTION_MAX_CHARS, DESCRIPTION_MIN_CHARS, WHEN_TO_USE_MAX_CHARS, WHEN_TO_USE_MIN_CHARS, } from "../../../core/authoring-rules.js";
+import { proposalContent } from "../../../core/file-change.js";
+/**
+ * The canonical asset NAME an inputRef names, lower-cased — the tail the
+ * "just restates the ref" heuristics compare against. WI-8.5c: the ref is the
+ * conceptId (`<subdir>/<name>`), so the name is parsed off the conceptId; a
+ * legacy `type:name` falls back to the post-colon segment.
+ */
+function refNameTail(inputRef) {
+    try {
+        return parseRefInput(inputRef).name.toLowerCase();
+    }
+    catch {
+        return (inputRef.split(":").pop() ?? "").toLowerCase();
+    }
+}
 import { detectTruncatedDescription, TRUNCATION_TRAILING_WORDS } from "../../../core/text-truncation.js";
 // ── Description / when_to_use shape ─────────────────────────────────────────
 export const HEADING_FRAGMENT_PATTERNS = [
@@ -122,7 +138,7 @@ export function isValidDescription(value, inputRef, options = {}) {
             severity: "warn",
         };
     if (!options.skipRefTailCheck) {
-        const refTail = inputRef.split(":").pop()?.toLowerCase() ?? "";
+        const refTail = refNameTail(inputRef);
         if (refTail.length >= 6 && v.toLowerCase().includes(refTail) && v.length < refTail.length + 40)
             return { ok: false, reason: "description appears to just name the input ref" };
     }
@@ -140,7 +156,7 @@ export function isValidWhenToUse(value, inputRef) {
         return { ok: false, reason: `when_to_use is too long (${v.length} chars; max ${WHEN_TO_USE_MAX_CHARS})` };
     if (/^when working with\b/i.test(v))
         return { ok: false, reason: "when_to_use is the circular 'When working with ...' fallback" };
-    const refTail = inputRef.split(":").pop()?.toLowerCase() ?? "";
+    const refTail = refNameTail(inputRef);
     if (refTail.length >= 6 && v.toLowerCase().includes(refTail) && v.length < refTail.length + 25)
         return { ok: false, reason: "when_to_use appears to just name the input ref" };
     return { ok: true };
@@ -267,7 +283,7 @@ const descriptionQualityValidator = {
             return [];
         let fm;
         try {
-            fm = parseFrontmatter(proposal.payload.content).data;
+            fm = parseFrontmatter(proposalContent(proposal)).data;
         }
         catch {
             return [];
@@ -293,7 +309,7 @@ const lessonContentQualityValidator = {
             return [];
         let fm;
         try {
-            fm = parseFrontmatter(proposal.payload.content).data;
+            fm = parseFrontmatter(proposalContent(proposal)).data;
         }
         catch {
             return [];
@@ -322,7 +338,7 @@ const lessonContentQualityValidator = {
                 message: `Lesson proposal ${proposal.id} (${proposal.ref}) has identical description and when_to_use.`,
             });
         }
-        const dfm = detectDoubleFrontmatter(proposal.payload.content);
+        const dfm = detectDoubleFrontmatter(proposalContent(proposal));
         if (dfm)
             findings.push({ kind: dfm.kind, message: `Lesson proposal ${proposal.id} (${proposal.ref}): ${dfm.message}` });
         return findings;
@@ -356,7 +372,7 @@ const reflectSizeGuardValidator = {
     },
     validate(proposal, ctx) {
         const sourceBody = stripFrontmatterBody(ctx.source?.content ?? "");
-        const proposedBody = typeof proposal.payload?.content === "string" ? stripFrontmatterBody(proposal.payload.content) : "";
+        const proposedBody = typeof proposal.payload?.content === "string" ? stripFrontmatterBody(proposalContent(proposal)) : "";
         const outcome = checkReflectSize(sourceBody, proposedBody);
         if (outcome.ok)
             return [];

package/dist/commands/proposal/validators/proposal-validators.js

@@ -1,8 +1,9 @@
 // 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 { parseAssetRef } from "../../../core/asset/asset-ref.js";
 import { parseFrontmatter } from "../../../core/asset/frontmatter.js";
+import { parseRefInput } from "../../../core/asset/resolve-ref.js";
+import { proposalContent } from "../../../core/file-change.js";
 import { lintLessonContent } from "../../../core/lesson-lint.js";
 import { defaultProposalQualityValidators } from "./proposal-quality-validators.js";
 const genericProposalValidator = {
@@ -14,7 +15,7 @@ const genericProposalValidator = {
             findings.push({ kind: "empty-content", message: `Proposal ${proposal.id} has empty content.` });
         }
         try {
-            ctx.parsedRef = parseAssetRef(proposal.ref);
+            ctx.parsedRef = parseRefInput(proposal.ref);
         }
         catch (err) {
             findings.push({
@@ -24,9 +25,9 @@ const genericProposalValidator = {
             ctx.stop = true;
             return findings;
         }
-        if (proposal.payload.content.startsWith("---")) {
+        if (proposalContent(proposal).startsWith("---")) {
             try {
-                parseFrontmatter(proposal.payload.content);
+                parseFrontmatter(proposalContent(proposal));
             }
             catch (err) {
                 findings.push({
@@ -44,7 +45,7 @@ const lessonProposalValidator = {
         return ctx.parsedRef?.type === "lesson";
     },
     validate(proposal) {
-        return lintLessonContent(proposal.payload.content, `proposal:${proposal.id}`).findings.map((finding) => ({
+        return lintLessonContent(proposalContent(proposal), `proposal:${proposal.id}`).findings.map((finding) => ({
             kind: finding.kind,
             message: finding.message,
         }));

package/dist/commands/proposal/validators/proposals.js

@@ -4,10 +4,11 @@
 /**
  * Proposal validation and content repair.
  *
- * The proposal repository, domain service, and legacy filesystem import moved
- * to `../repository.ts` and `../legacy-import.ts` (#578 storage consolidation).
- * This module keeps only the two proposal *validators* — {@link validateProposal}
- * and {@link repairProposalContent}.
+ * The proposal repository and domain service moved to `../repository.ts` (#578
+ * storage consolidation); the legacy filesystem import now lives in the migrator
+ * (`../../../migrate/legacy/proposal-fs-import.ts`). This module keeps only the
+ * two proposal *validators* — {@link validateProposal} and
+ * {@link repairProposalContent}.
  */
 import { repairTruncatedDescription } from "../../../core/text-truncation.js";
 import { runProposalValidators } from "./proposal-validators.js";

package/dist/commands/read/curate.js

@@ -14,17 +14,20 @@
  * `mergeCurateSearchResponses`) by importing them directly.
  */
 import fs from "node:fs";
-import { parseAssetRef, refToString } from "../../core/asset/asset-ref.js";
 import { parseFrontmatter } from "../../core/asset/frontmatter.js";
+import { parseRefInput } from "../../core/asset/resolve-ref.js";
 import { getIndexPassConfig, loadConfig } from "../../core/config/config.js";
 import { rethrowIfTestIsolationError, UsageError } from "../../core/errors.js";
 import { appendEvent } from "../../core/events.js";
-import { computeBodyHash } from "../../indexer/db/db.js";
+import { withStateDbTelemetry } from "../../core/state-db.js";
 import { enqueueGraphExtraction, hasGraphData } from "../../indexer/db/graph-db.js";
+import { copySearchHitAttribution, getSearchHitAttribution, usageEventAttributionMetadata, } from "../../indexer/search/search-attribution.js";
 import { findSourceForPath, resolveSourceEntries } from "../../indexer/search/search-source.js";
 import { insertUsageEvent } from "../../indexer/usage/usage-events.js";
 import { truncateDescription } from "../../output/shapes.js";
 import { TELEMETRY_BUSY_TIMEOUT_MS, withIndexDb } from "../../storage/repositories/index-db.js";
+import { findEntryIdByRef, getItemRefById } from "../../storage/repositories/index-entries-repository.js";
+import { computeBodyHash } from "../../storage/repositories/index-llm-cache-repository.js";
 import { akmSearch, parseSearchSource } from "./search.js";
 import { akmShowUnified } from "./show.js";
 const CURATE_FALLBACK_FILTER_WORDS = new Set([
@@ -58,7 +61,7 @@ const CURATE_REFERENCE_QUERY_RE = /\b(?:reference|docs?|guide|how|explain|learn|
  * Fire-and-forget: log a curate event to the usage_events table and events.jsonl.
  * Never blocks the caller; errors are silently ignored.
  */
-function logCurateEvent(query, result, eventSource = "user") {
+function logCurateEvent(query, result, eventSource = "user", attributionProjection = "full") {
     const itemRefs = result.items.map((item) => ("ref" in item ? item.ref : `registry:${item.id}`));
     appendEvent({
         eventType: "curate",
@@ -66,27 +69,39 @@ function logCurateEvent(query, result, eventSource = "user") {
     });
     try {
         withIndexDb((db) => {
-            insertUsageEvent(db, {
-                event_type: "curate",
-                query,
-                metadata: JSON.stringify({
-                    itemCount: result.items.length,
-                    itemRefs,
-                }),
-                source: eventSource,
+            // Resolve each curated item's DURABLE fully-qualified `item_ref` (D-R3)
+            // + entry_id from index.db (`db`); the usage_events writes land in
+            // state.db (Chunk-8 WI-8.3).
+            const perItem = result.items
+                .filter((item) => "ref" in item && typeof item.ref === "string")
+                .map((item) => {
+                const entryId = findEntryIdByRef(db, item.ref);
+                const itemRef = entryId !== undefined ? getItemRefById(db, entryId) : null;
+                // Post-flip the resolved row carries `item_ref`; fall back to the
+                // item's own (new-grammar) ref for an unresolved straggler.
+                return { entryRef: itemRef ?? item.ref, entryId, item };
             });
-            for (const item of result.items) {
-                if (!("ref" in item) || typeof item.ref !== "string")
-                    continue;
-                const parsed = parseAssetRef(item.ref);
-                const itemOrigin = "origin" in item && typeof item.origin === "string" ? item.origin : undefined;
-                insertUsageEvent(db, {
+            withStateDbTelemetry((stateDb) => {
+                insertUsageEvent(stateDb, {
                     event_type: "curate",
                     query,
-                    entry_ref: refToString({ ...parsed, ...(parsed.origin || !itemOrigin ? {} : { origin: itemOrigin }) }),
+                    metadata: JSON.stringify({
+                        itemCount: result.items.length,
+                        itemRefs,
+                    }),
                     source: eventSource,
                 });
-            }
+                for (const { entryRef, entryId, item } of perItem) {
+                    insertUsageEvent(stateDb, {
+                        event_type: "curate",
+                        query,
+                        entry_ref: entryRef,
+                        entry_id: entryId,
+                        metadata: usageEventAttributionMetadata(getSearchHitAttribution(item), entryRef, attributionProjection),
+                        source: eventSource,
+                    });
+                }
+            }, TELEMETRY_BUSY_TIMEOUT_MS);
         }, { busyTimeoutMs: TELEMETRY_BUSY_TIMEOUT_MS });
     }
     catch (err) {
@@ -107,11 +122,11 @@ export async function akmCurate(options) {
             limit: Math.max(limit * CURATE_SEARCH_LIMIT_MULTIPLIER, MIN_CURATE_SEARCH_LIMIT),
             source,
         }));
-    const result = await curateSearchResults(options.query, searchResponse, limit, options.type);
-    logCurateEvent(options.query, result, options.eventSource);
+    const result = await curateSearchResults(options.query, searchResponse, limit, options.type, options.eventSource);
+    logCurateEvent(options.query, result, options.eventSource, options.attributionProjection);
     return result;
 }
-export async function curateSearchResults(query, result, limit, selectedType) {
+export async function curateSearchResults(query, result, limit, selectedType, eventSource) {
     const stashHits = result.hits.filter((hit) => hit.type !== "registry");
     const registryHits = result.registryHits ?? [];
     let selectedStashHits;
@@ -130,7 +145,7 @@ export async function curateSearchResults(query, result, limit, selectedType) {
     const items = [
         ...(await Promise.all(selectedStashHits
             .slice(0, limit)
-            .map((hit) => enrichCuratedStashHit(query, hit, supportRefsByRef.get(hit.ref) ?? [], selectedRefs)))),
+            .map((hit) => enrichCuratedStashHit(query, hit, supportRefsByRef.get(hit.ref) ?? [], selectedRefs, eventSource)))),
         ...selectedRegistryHits.map((hit) => buildCuratedRegistryItem(query, hit)),
     ].slice(0, limit);
     return {
@@ -141,10 +156,10 @@ export async function curateSearchResults(query, result, limit, selectedType) {
         ...(result.tip ? { tip: result.tip } : {}),
     };
 }
-async function enrichCuratedStashHit(query, hit, supportRefs, selectedRefs) {
+async function enrichCuratedStashHit(query, hit, supportRefs, selectedRefs, eventSource) {
     let shown;
     try {
-        shown = await akmShowUnified({ ref: hit.ref });
+        shown = await akmShowUnified({ ref: hit.ref, eventSource, skipLogging: true });
     }
     catch {
         shown = undefined;
@@ -157,7 +172,7 @@ async function enrichCuratedStashHit(query, hit, supportRefs, selectedRefs) {
     const description = shown?.description ?? hit.description;
     const preview = buildCuratedPreview(shown, hit);
     const mergedSupportRefs = mergeCurateSupportRefs(supportRefs, shown?.related?.hits, selectedRefs, hit.ref);
-    return {
+    const item = {
         source: "stash",
         type: shown?.type ?? hit.type,
         name: shown?.name ?? hit.name,
@@ -172,6 +187,8 @@ async function enrichCuratedStashHit(query, hit, supportRefs, selectedRefs) {
         reason: buildCuratedReason(query, shown?.type ?? hit.type),
         ...(hit.score !== undefined ? { score: hit.score } : {}),
     };
+    copySearchHitAttribution(hit, item, item.description);
+    return item;
 }
 /**
  * #624-P3 — enqueue an ungraphed asset for lazy graph extraction when the
@@ -256,7 +273,9 @@ function buildCurateSummary(query, items) {
     if (items.length === 0) {
         return `No curated assets were selected for "${query}".`;
     }
-    const labels = items.map((item) => `${item.type}:${item.name}`);
+    // F4b: emit the flipped conceptId ref for stash items (registry items have no
+    // ref — keep their `registry:<name>` label).
+    const labels = items.map((item) => ("ref" in item ? item.ref : `${item.type}:${item.name}`));
     return `Selected ${items.length} curated result${items.length === 1 ? "" : "s"}: ${labels.join(", ")}.`;
 }
 export function deriveCurateFallbackQueries(query) {
@@ -425,7 +444,10 @@ function computeCurateTypeNudge(type, intent) {
 }
 function getCurateFamily(ref) {
     try {
-        const parsed = parseAssetRef(ref);
+        // F4b: `ref` is a search-hit ref in the 0.9.0 conceptId grammar — parse via
+        // the new-grammar `parseRefInput` so skill/reference family grouping still
+        // recognizes it.
+        const parsed = parseRefInput(ref);
         if (parsed.type === "skill") {
             return { key: parsed.name, role: "root" };
         }

package/dist/commands/read/knowledge.js

@@ -12,10 +12,10 @@ import fs from "node:fs";
 import path from "node:path";
 import { parse as yamlParse } from "yaml";
 import { assertFlatAssetName, combineCreatePath, normalizeCreateSubPath } from "../../core/asset/asset-create.js";
-import { makeAssetRef, parseAssetRef } from "../../core/asset/asset-ref.js";
+import { assetPathForName, stashDirFor } from "../../core/asset/asset-placement.js";
 import { assembleAsset } from "../../core/asset/asset-serialize.js";
-import { resolveAssetPathFromName, TYPE_DIRS } from "../../core/asset/asset-spec.js";
 import { parseFrontmatter } from "../../core/asset/frontmatter.js";
+import { conceptIdFromTypeName, parseRefInput } from "../../core/asset/resolve-ref.js";
 import { isHttpUrl, isWithin, resolveStashDir, tryReadStdinText } from "../../core/common.js";
 import { loadConfig } from "../../core/config/config.js";
 import { UsageError } from "../../core/errors.js";
@@ -24,7 +24,7 @@ import { warn } from "../../core/warn.js";
 import { commitWriteTargetBoundary, formatRefForMessage, recordWriteTargetPath, resolveWriteTarget, writeAssetToSource, } from "../../core/write-source.js";
 import { indexWrittenAssets } from "../../indexer/index-written-assets.js";
 import { resolveSourceEntries } from "../../indexer/search/search-source.js";
-import { fetchWebsiteMarkdownSnapshot, shouldAllowPrivateWebsiteUrlForTests } from "../../sources/website-ingest.js";
+import { fetchWebsiteMarkdownSnapshot, shouldAllowPrivateWebsiteUrlForTests, } from "../../sources/snapshot-fetchers/website-ingest.js";
 import { writeSupersededEdge } from "../improve/memory/memory-belief.js";
 import { refToRelPath, resolveRefPathInStash } from "../lint/base-linter.js";
 const MAX_CAPTURED_ASSET_SLUG_LENGTH = 64;
@@ -121,9 +121,11 @@ export async function readKnowledgeInput(source, options) {
     return { content: snapshot.content, preferredName: snapshot.preferredName };
 }
 /**
- * Parse a `--xref` / `--supersedes` value through the canonical ref parser
- * (`parseAssetRef`) so malformed and origin-prefixed spellings get a
- * structured error instead of a misleading "did not resolve". A `local//`
+ * Parse a `--xref` / `--supersedes` value through the new-grammar input parser
+ * (`parseRefInput`, the 0.9.0 `[bundle//]conceptId` grammar) so malformed and
+ * origin-prefixed spellings get a structured error instead of a misleading "did
+ * not resolve". Chunk-8 WI-8.5c: the legacy `[origin//]type:name` content-surface
+ * arm is retired — `--xref`/`--supersedes` take the conceptId form. A `local//`
  * origin is accepted (it names the same local resolution this validator
  * performs, mirroring lint's `local//` strip); any other origin is rejected —
  * write-time validation only resolves local stash roots.
@@ -131,18 +133,21 @@ export async function readKnowledgeInput(source, options) {
 function parseWriteRef(raw, flag) {
     let parsed;
     try {
-        parsed = parseAssetRef(raw);
+        parsed = parseRefInput(raw);
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
-        throw new UsageError(`${flag} "${raw}" is not a valid asset ref: ${message}`, "INVALID_FLAG_VALUE", `Refs use the form type:name, e.g. ${flag} knowledge:auth-flow.`);
+        throw new UsageError(`${flag} "${raw}" is not a valid asset ref: ${message}`, "INVALID_FLAG_VALUE", `Refs use the conceptId form, e.g. ${flag} knowledge/auth-flow.`);
     }
     if (parsed.origin && parsed.origin !== "local") {
-        throw new UsageError(`${flag} "${raw}" carries the origin prefix "${parsed.origin}//" — ${flag} only resolves refs in the write target, the working stash, and configured sources.`, "INVALID_FLAG_VALUE", `Pass the plain type:name form, e.g. ${flag} ${parsed.type}:${parsed.name}.`);
+        throw new UsageError(`${flag} "${raw}" carries the origin prefix "${parsed.origin}//" — ${flag} only resolves refs in the write target, the working stash, and configured sources.`, "INVALID_FLAG_VALUE", `Pass the plain conceptId form, e.g. ${flag} ${conceptIdFromTypeName(parsed.type, parsed.name)}.`);
     }
-    // Canonical bare form: type alias resolved, name normalized, `local//`
-    // dropped (it names the same local resolution this validator performs).
-    return { ref: makeAssetRef(parsed.type, parsed.name), type: parsed.type, name: parsed.name };
+    // Canonical bare conceptId: type alias resolved, name normalized, `local//`
+    // dropped (it names the same local resolution this validator performs). The
+    // bare `<stash-subdir>/<name>` short ref (WI-8.5a) is what lands in the
+    // containing bundle's frontmatter (§11.1 short-ref rule); the name is already
+    // normalized by the parser.
+    return { ref: conceptIdFromTypeName(parsed.type, parsed.name), type: parsed.type, name: parsed.name };
 }
 /**
  * Trim, parse, and dedupe `--xref` / `--supersedes` flag values, in argv
@@ -213,8 +218,8 @@ function isFailOpenRefType(type, name) {
  */
 function locateWriteRefInRoot(type, name, root) {
     if (type === "workflow") {
-        const typeRoot = path.join(root, TYPE_DIRS.workflow ?? "workflows");
-        const candidate = resolveAssetPathFromName("workflow", typeRoot, name);
+        const typeRoot = path.join(root, stashDirFor("workflow") ?? "workflows");
+        const candidate = assetPathForName("workflow", typeRoot, name);
         if (fs.existsSync(candidate))
             return candidate;
     }
@@ -226,7 +231,7 @@ function locateWriteRefInRoot(type, name, root) {
 /** Build the shared exit-2 error for refs that resolved in no root. */
 function unresolvedRefsError(flag, unresolved) {
     const first = unresolved[0];
-    return new UsageError(`${flag} ref${unresolved.length > 1 ? "s" : ""} did not resolve in the write target or any configured source: ${unresolved.map((u) => u.ref).join(", ")}`, "INVALID_FLAG_VALUE", `Find the intended asset with \`akm search "${first.name}" --type ${first.type}\`. Refs use the form type:name.`);
+    return new UsageError(`${flag} ref${unresolved.length > 1 ? "s" : ""} did not resolve in the write target or any configured source: ${unresolved.map((u) => u.ref).join(", ")}`, "INVALID_FLAG_VALUE", `Find the intended asset with \`akm search "${first.name}" --type ${first.type}\`. Refs use the form [bundle//]conceptId (e.g. knowledge/guide.md).`);
 }
 // ── Cross-references (--xref) ────────────────────────────────────────────────
 /**
@@ -466,7 +471,7 @@ export async function writeMarkdownAsset(options) {
     // Pre-flight: existence + force semantics. The helper itself overwrites
     // unconditionally; the CLI surfaces a friendlier UsageError before any
     // disk activity when --force is absent.
-    const assetPath = resolveAssetPathFromName(options.type, typeRoot, normalizedName);
+    const assetPath = assetPathForName(options.type, typeRoot, normalizedName);
     if (!isWithin(assetPath, typeRoot)) {
         throw new UsageError(`Resolved ${options.type} path escapes the stash: "${normalizedName}"`);
     }
@@ -527,6 +532,10 @@ export async function writeMarkdownAsset(options) {
         // on a git target, uncommitted (and a re-run hits RESOURCE_ALREADY_EXISTS).
         // Degrade to the same applied:false report the non-writable path uses.
         try {
+            // supersededBy points at the correction's canonical write ref (F4b-flipped
+            // display spelling), keeping it in lockstep with the reported `result.ref`.
+            // The --xref/--supersedes input path (resolveXrefsForWrite/parseWriteRef)
+            // is now the new-grammar conceptId surface too (WI-8.5c).
             writeSupersededEdge(item.filePath, result.ref);
             if (path.resolve(item.stashRoot) === path.resolve(source.path)) {
                 recordWriteTargetPath(source, item.filePath);

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

@@ -5,6 +5,7 @@ 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 { resolveUsageEventSource } from "../../indexer/usage/usage-events.js";
 import { buildMemoryFrontmatter, parseDuration, readMemoryContent, resolveRememberContentArg, runAutoHeuristics, runLlmEnrich, } from "../remember.js";
 import { assertFlatAssetName, inferAssetName, resolveSupersedesForWrite, resolveXrefsForWrite, writeMarkdownAsset, } from "./knowledge.js";
 import { akmSearch } from "./search.js";
@@ -13,9 +14,15 @@ import { akmSearch } from "./search.js";
  * 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)
@@ -111,6 +118,7 @@ export const rememberCommand = defineJsonCommand({
     },
     async run({ args }) {
         const body = readMemoryContent(resolveRememberContentArg(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.
@@ -178,7 +186,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 {
@@ -287,7 +295,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,34 +6,23 @@
  * 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 { parseRefInput } from "../../core/asset/resolve-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 { getHyphenatedBoolean, 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;
-}
 export const searchCommand = defineJsonCommand({
     meta: { name: "search", description: "Search the stash" },
     args: {
@@ -45,7 +34,7 @@ export const searchCommand = defineJsonCommand({
         },
         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 (skill, command, agent, knowledge, workflow, script, memory, env, secret, lesson, or any). 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" },
@@ -92,6 +81,7 @@ export const searchCommand = defineJsonCommand({
         const belief = parseBeliefFilterMode(typeof args.belief === "string" ? args.belief : undefined);
         const noProjectContext = getHyphenatedBoolean(args, "no-project-context");
         const includeSessions = args["include-sessions"];
+        const outputMode = getOutputMode();
         const result = await akmSearch({
             query,
             type,
@@ -103,7 +93,8 @@ export const searchCommand = defineJsonCommand({
             includeSessions,
             disableProjectContext: noProjectContext,
             disableScopedUtility: noProjectContext,
-            eventSource: resolveEventSource(),
+            eventSource: resolveUsageEventSource(),
+            attributionProjection: outputMode.shape === "agent" ? "agent" : outputMode.detail,
         });
         output("search", result);
     },
@@ -117,7 +108,7 @@ 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 (skill, command, agent, knowledge, workflow, script, memory, env, secret, lesson, or any). 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" },
@@ -136,19 +127,27 @@ export const curateCommand = defineJsonCommand({
         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 outputMode = getOutputMode();
+        const curated = await akmCurate({
+            query: args.query,
+            type,
+            limit,
+            source,
+            eventSource: resolveUsageEventSource(),
+            attributionProjection: outputMode.shape === "agent" ? "agent" : outputMode.detail,
+        });
         output("curate", curated);
     },
 });
 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 stash asset by ref (e.g. akm show knowledge/guide.md toc, akm show knowledge/guide.md section '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) 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"`.',
             required: true,
         },
         format: { type: "string", description: "Output format (json|jsonl|text|yaml)" },
@@ -162,18 +161,19 @@ export const showCommand = defineJsonCommand({
     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"`)
+            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 `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");
+        // directly via `getParsedInvocation()` so the flags don't surface as
+        // user-facing options in `akm show --help`.
+        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) {
@@ -197,7 +197,7 @@ export const showCommand = defineJsonCommand({
             }
         }
         const cliShape = getOutputMode().shape;
-        const explicitDetail = parseFlagValue(process.argv, "--detail");
+        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
@@ -212,7 +212,7 @@ export const showCommand = defineJsonCommand({
             view,
             detail: showDetail,
             scope,
-            eventSource: resolveEventSource(),
+            eventSource: resolveUsageEventSource(),
         });
         output("show", result);
     },