akm-cli 0.7.0-rc1 → 0.7.0

package/dist/src/cli.js

@@ -183,10 +183,11 @@ const searchCommand = defineCommand({
     },
     async run({ args }) {
         await runWithJsonErrors(async () => {
+            // An empty query enumerates all indexed assets (list mode).
+            // The guard that rejected empty queries was removed; akmSearch handles
+            // empty strings end-to-end via getAllEntries (DB path) and the
+            // substring-search fallback's query-less branch.
             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", "Provide a query string. Filter by type with --type skill|command|...; limit results with --limit N.");
-            }
             const type = args.type;
             const limitRaw = args.limit ? parseInt(args.limit, 10) : undefined;
             if (limitRaw !== undefined && Number.isNaN(limitRaw)) {
@@ -502,6 +503,15 @@ const showCommand = defineCommand({
     },
     async run({ args }) {
         await runWithJsonErrors(async () => {
+            try {
+                parseAssetRef(args.ref);
+            }
+            catch (error) {
+                if (error instanceof UsageError && error.code === "MISSING_REQUIRED_ARGUMENT") {
+                    throw new UsageError(error.message, "INVALID_FLAG_VALUE", error.hint());
+                }
+                throw error;
+            }
             // 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
@@ -863,8 +873,8 @@ const registryCommand = defineCommand({
         "build-index": defineCommand({
             meta: { name: "build-index", description: "Build a v2 registry index from discovery and manual entries" },
             args: {
-                out: { type: "string", description: "Output path for the generated index", default: "index.json" },
-                manual: { type: "string", description: "Manual entries JSON file", default: "manual-entries.json" },
+                out: { type: "string", description: "Output path for the generated index" },
+                manual: { type: "string", description: "Manual entries JSON file" },
                 "npm-registry": { type: "string", description: "Override npm registry base URL" },
                 "github-api": { type: "string", description: "Override GitHub API base URL" },
             },
@@ -892,15 +902,26 @@ const registryCommand = defineCommand({
 const feedbackCommand = defineCommand({
     meta: {
         name: "feedback",
-        description: "Record positive or negative feedback for any indexed stash asset",
+        description: "Record positive or negative feedback for any indexed stash asset.\n\n" +
+            "Positive feedback boosts an asset's EMA utility score, making it rank higher\n" +
+            "in future searches without requiring a full reindex.\n\n" +
+            "Negative feedback records a negative signal in usage_events and events.jsonl.\n" +
+            "It does NOT immediately lower the asset's ranking — the EMA utility score is\n" +
+            "updated the next time `akm index` runs (incremental or full). Run `akm index`\n" +
+            "after recording negative feedback to have it reflected in search results.",
     },
     args: {
         // Optional in citty so run() is invoked even when omitted; we re-validate
         // and throw a structured UsageError below so exit code is 2 (USAGE) rather
         // than citty's default 0 (help banner).
         ref: { type: "positional", description: "Asset ref (type:name)", required: false },
-        positive: { type: "boolean", description: "Record positive feedback", default: false },
-        negative: { type: "boolean", description: "Record negative feedback", default: false },
+        positive: { type: "boolean", description: "Record positive feedback (boosts ranking immediately)", default: false },
+        negative: {
+            type: "boolean",
+            description: "Record negative feedback (suppresses ranking after next `akm index`). " +
+                "Reindexing is required for the signal to affect search results.",
+            default: false,
+        },
         note: { type: "string", description: "Optional note to attach to the feedback" },
     },
     run({ args }) {
@@ -924,6 +945,11 @@ const feedbackCommand = defineCommand({
                 if (entryId === undefined) {
                     throw new UsageError(`Ref "${ref}" is not in the current index. Run "akm index" and try again.`);
                 }
+                // Persist the feedback signal into usage_events. For positive signals,
+                // the EMA utility score is updated immediately on the next read path.
+                // For negative signals, the score is adjusted the next time `akm index`
+                // runs — the signal is durable in the DB but does NOT suppress ranking
+                // in search results until after reindexing.
                 insertUsageEvent(db, {
                     event_type: "feedback",
                     entry_ref: ref,
@@ -947,11 +973,22 @@ const feedbackCommand = defineCommand({
 const historyCommand = defineCommand({
     meta: {
         name: "history",
-        description: "Show mutation/usage history for a single asset (--ref) or stash-wide. Backed by the internal usage_events log.",
+        description: "Show mutation/usage history for a single asset (--ref) or stash-wide.\n\n" +
+            "Event sources:\n" +
+            "  usage_events (default): search, show, and feedback events from the local index.\n" +
+            "  events.jsonl (--include-proposals): proposal lifecycle events (promoted, rejected)\n" +
+            "    emitted by `akm proposal accept` / `akm proposal reject`.\n\n" +
+            "Results from all active sources are merged and sorted chronologically.",
     },
     args: {
         ref: { type: "string", description: "Asset ref (type:name). Omit for stash-wide history." },
         since: { type: "string", description: "ISO timestamp or epoch ms — only events on/after this time" },
+        "include-proposals": {
+            type: "boolean",
+            description: "Also include proposal lifecycle events (promoted, rejected) from events.jsonl. " +
+                "Default: false (usage_events only).",
+            default: false,
+        },
         format: { type: "string", description: "Output format (json|jsonl|text|yaml)" },
     },
     run({ args }) {
@@ -959,6 +996,7 @@ const historyCommand = defineCommand({
             const result = await akmHistory({
                 ref: args.ref,
                 since: args.since,
+                includeProposals: args["include-proposals"],
             });
             output("history", result);
         });
@@ -1397,7 +1435,7 @@ const rememberCommand = defineCommand({
     },
     async run({ args }) {
         return runWithJsonErrors(async () => {
-            const body = readMemoryContent(args.content);
+            const body = readMemoryContent(resolveRememberContentArg(args.content));
             // 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.
@@ -1415,8 +1453,8 @@ const rememberCommand = defineCommand({
             if (typeof args.channel === "string" && args.channel.trim())
                 scopeFields.channel = args.channel.trim();
             const hasScope = Object.keys(scopeFields).length > 0;
-            const hasTagRequiringArgs = rawTags.length > 0 || !!args.expires || !!args.source || !!args.description || args.auto || args.enrich;
-            const hasStructuredArgs = hasTagRequiringArgs || hasScope;
+            const hasTagRequiringArgs = rawTags.length > 0 || !!args.expires || !!args.source || !!args.description || args.enrich;
+            const hasStructuredArgs = hasTagRequiringArgs || hasScope || args.auto;
             if (!hasStructuredArgs) {
                 const result = await writeMarkdownAsset({
                     type: "memory",
@@ -1476,10 +1514,12 @@ const rememberCommand = defineCommand({
                     observed_at = enriched.observed_at;
             }
             // ── Required-field check (before any write) ───────────────────────────
-            // Tags remain required when the user opted into a tag-producing mode
-            // (--tag / --auto / --enrich / --description / --source / --expires).
-            // Scope-only writes (`akm remember "..." --user u1`) skip this check —
-            // scope is independent metadata and a memory with only scope is valid.
+            // Tags remain required when the user explicitly asked for tag-bearing
+            // metadata (--tag / --enrich / --description / --source / --expires).
+            // `--auto` alone is allowed even when its heuristics derive zero tags.
+            // Scope-only writes (`akm remember "..." --user u1`) also skip this
+            // check — scope is independent metadata and a memory with only scope is
+            // valid.
             const missing = [];
             if (hasTagRequiringArgs && tags.length === 0)
                 missing.push("tags");
@@ -1522,6 +1562,50 @@ const rememberCommand = defineCommand({
         });
     },
 });
+function resolveRememberContentArg(content) {
+    if (content === undefined)
+        return undefined;
+    const parsedFormat = parseFlagValue(process.argv, "--format");
+    if (parsedFormat !== undefined &&
+        content === parsedFormat &&
+        wasRememberFlagValueConsumedAsContent(content, parsedFormat, "--format")) {
+        return undefined;
+    }
+    const parsedDetail = parseFlagValue(process.argv, "--detail");
+    if (parsedDetail !== undefined &&
+        content === parsedDetail &&
+        wasRememberFlagValueConsumedAsContent(content, parsedDetail, "--detail")) {
+        return undefined;
+    }
+    return content;
+}
+function wasRememberFlagValueConsumedAsContent(content, flagValue, flagName) {
+    const argv = process.argv.slice(2);
+    const rememberIndex = argv.indexOf("remember");
+    const tokens = rememberIndex >= 0 ? argv.slice(rememberIndex + 1) : argv;
+    let flagIndex = -1;
+    let flagConsumesNextToken = false;
+    for (let i = 0; i < tokens.length; i += 1) {
+        const token = tokens[i];
+        if (token === flagName) {
+            flagIndex = i;
+            flagConsumesNextToken = true;
+            break;
+        }
+        if (token === `${flagName}=${flagValue}`) {
+            flagIndex = i;
+            break;
+        }
+    }
+    if (flagIndex === -1)
+        return false;
+    if (tokens.slice(0, flagIndex).includes(content))
+        return false;
+    const firstTokenAfterFlag = flagIndex + (flagConsumesNextToken ? 2 : 1);
+    if (tokens.slice(firstTokenAfterFlag).includes(content))
+        return false;
+    return true;
+}
 const importKnowledgeCommand = defineCommand({
     meta: {
         name: "import",

package/dist/src/commands/config-cli.js

@@ -31,6 +31,12 @@ export function parseConfigValue(key, value) {
             return { embedding: mergeLlmLikeEmbedding(undefined, { model: requireNonEmptyString(value, key) }) };
         case "embedding.apiKey":
             return { embedding: mergeLlmLikeEmbedding(undefined, { apiKey: requireNonEmptyString(value, key) }) };
+        case "embedding.contextLength":
+            return { embedding: mergeLlmLikeEmbedding(undefined, { contextLength: parsePositiveInteger(value, key) }) };
+        case "embedding.ollamaOptions.numCtx":
+            return {
+                embedding: mergeLlmLikeEmbedding(undefined, { ollamaOptions: { num_ctx: parsePositiveInteger(value, key) } }),
+            };
         case "llm":
             return { llm: parseLlmConnectionValue(value) };
         case "llm.endpoint":
@@ -82,6 +88,10 @@ export function getConfigValue(config, key) {
             return config.embedding?.model ?? null;
         case "embedding.apiKey":
             return config.embedding?.apiKey ?? null;
+        case "embedding.contextLength":
+            return config.embedding?.contextLength ?? null;
+        case "embedding.ollamaOptions.numCtx":
+            return config.embedding?.ollamaOptions?.num_ctx ?? null;
         case "llm":
             return config.llm ?? null;
         case "llm.endpoint":
@@ -152,6 +162,18 @@ export function setConfigValue(config, key, rawValue) {
                 ...config,
                 embedding: mergeLlmLikeEmbedding(config.embedding, { apiKey: requireNonEmptyString(rawValue, key) }),
             };
+        case "embedding.contextLength":
+            return {
+                ...config,
+                embedding: mergeLlmLikeEmbedding(config.embedding, { contextLength: parsePositiveInteger(rawValue, key) }),
+            };
+        case "embedding.ollamaOptions.numCtx":
+            return {
+                ...config,
+                embedding: mergeLlmLikeEmbedding(config.embedding, {
+                    ollamaOptions: { ...(config.embedding?.ollamaOptions ?? {}), num_ctx: parsePositiveInteger(rawValue, key) },
+                }),
+            };
         case "llm.endpoint":
             return { ...config, llm: mergeLlmLike(config.llm, { endpoint: requireNonEmptyString(rawValue, key) }) };
         case "llm.model":
@@ -190,6 +212,19 @@ export function unsetConfigValue(config, key) {
             const { apiKey: _a, ...rest } = config.embedding;
             return { ...config, embedding: rest };
         }
+        case "embedding.contextLength": {
+            if (!config.embedding)
+                return config;
+            const { contextLength: _cl, ...rest } = config.embedding;
+            return { ...config, embedding: rest };
+        }
+        case "embedding.ollamaOptions.numCtx": {
+            if (!config.embedding?.ollamaOptions)
+                return config;
+            const { num_ctx: _nc, ...restOpts } = config.embedding.ollamaOptions;
+            const ollamaOptions = Object.keys(restOpts).length > 0 ? restOpts : undefined;
+            return { ...config, embedding: { ...config.embedding, ollamaOptions } };
+        }
         case "llm":
             return { ...config, llm: undefined };
         case "llm.endpoint":
@@ -479,6 +514,13 @@ function parseUnknownPositiveInteger(value, key) {
     }
     return value;
 }
+function parsePositiveInteger(value, key) {
+    const n = Number(value);
+    if (!Number.isFinite(n) || !Number.isInteger(n) || n <= 0) {
+        throw new UsageError(`Invalid value for ${key}: expected a positive integer`);
+    }
+    return n;
+}
 function parseStashesValue(value) {
     if (value === "null" || value === "")
         return undefined;

package/dist/src/commands/history.js

@@ -1,16 +1,25 @@
 /**
- * `akm history` — surfaces internal mutation/usage events captured in the
- * `usage_events` SQLite table for a single asset (`--ref`) or stash-wide.
+ * `akm history` — surfaces internal mutation/usage events for a single asset
+ * (`--ref`) or stash-wide.
  *
- * Backed by `usage_events` (search/show/feedback today). Richer per-asset
- * lifecycle entries (add/edit/delete) require the events stream introduced
- * in #204; this command surfaces whatever the indexer has captured so
- * downstream tooling stops reinventing audit trails.
+ * Event sources:
+ *   - `usage_events` SQLite table: search, show, and feedback events recorded
+ *     by the local indexer during normal CLI use.
+ *   - `events.jsonl` append-only stream (opt-in via `--include-proposals`):
+ *     proposal lifecycle events (`promoted`, `rejected`) emitted by
+ *     `akm proposal accept` / `akm proposal reject`. Use this flag to see
+ *     the full proposal review trail alongside usage events.
+ *
+ * The two sources are merged and sorted chronologically (oldest first) so
+ * consumers see a coherent lifecycle trail in a single output.
  */
 import { parseAssetRef } from "../core/asset-ref";
 import { UsageError } from "../core/errors";
+import { readEvents } from "../core/events";
 import { closeDatabase, openDatabase } from "../indexer/db";
 import { ensureUsageEventsSchema } from "../indexer/usage-events";
+// Proposal lifecycle event types emitted by the proposal substrate (#225).
+const PROPOSAL_EVENT_TYPES = new Set(["promoted", "rejected"]);
 // ── Helpers ──────────────────────────────────────────────────────────────────
 function normalizeSince(since) {
     // Accept "YYYY-MM-DD", "YYYY-MM-DDTHH:MM:SSZ", epoch ms, or anything Date can parse.
@@ -62,11 +71,27 @@ function toEntry(row) {
         createdAt: row.created_at,
     };
 }
+/**
+ * Convert an ISO timestamp from events.jsonl ("2026-04-01T12:00:00.000Z")
+ * to the SQLite-style format used in HistoryEntry.createdAt
+ * ("2026-04-01 12:00:00") so entries sort consistently.
+ */
+function isoToSqliteTimestamp(ts) {
+    // Normalise to the "YYYY-MM-DD HH:MM:SS" format used by usage_events rows.
+    return ts
+        .replace("T", " ")
+        .replace(/\.\d+Z$/, "")
+        .replace("Z", "");
+}
 // ── Main ─────────────────────────────────────────────────────────────────────
 /**
  * Read mutation/usage history. When `ref` is provided, results are filtered to
  * that asset (validated via `parseAssetRef`). Always returns chronological
  * order (oldest first) so consumers can display a lifecycle trail.
+ *
+ * When `includeProposals` is true, proposal lifecycle events (`promoted`,
+ * `rejected`) from events.jsonl are merged into the result set. This provides
+ * one coherent view of both usage signals and proposal review decisions.
  */
 export async function akmHistory(options = {}) {
     let normalizedRef;
@@ -103,13 +128,59 @@ export async function akmHistory(options = {}) {
                  FROM usage_events ${where}
                  ORDER BY id ASC`;
         const rows = db.prepare(sql).all(...params);
-        const entries = rows.map(toEntry);
+        const usageEntries = rows.map(toEntry);
+        // ── Proposal lifecycle events (opt-in) ────────────────────────────────
+        const sources = ["usage_events"];
+        const proposalEntries = [];
+        if (options.includeProposals === true) {
+            sources.push("events.jsonl");
+            // Convert sinceNormalized ("YYYY-MM-DD HH:MM:SS") to ISO for readEvents
+            // which uses `ts >= since` where `ts` is ISO-8601.
+            const sinceIso = sinceNormalized !== undefined ? `${sinceNormalized.replace(" ", "T")}Z` : undefined;
+            const { events } = readEvents({
+                since: sinceIso,
+                ref: normalizedRef,
+            }, options.eventsCtx);
+            // Keep only proposal lifecycle event types.
+            let counter = -1_000_000; // negative ids mark proposal-stream entries
+            for (const event of events) {
+                if (!PROPOSAL_EVENT_TYPES.has(event.eventType))
+                    continue;
+                const createdAt = event.ts ? isoToSqliteTimestamp(event.ts) : "";
+                // Skip if before `since` (readEvents already filters by ts >= since,
+                // but the isoToSqliteTimestamp conversion may introduce drift so we
+                // guard again with the normalised form).
+                if (sinceNormalized !== undefined && createdAt < sinceNormalized)
+                    continue;
+                proposalEntries.push({
+                    id: counter--,
+                    eventType: event.eventType,
+                    ref: event.ref ?? null,
+                    entryId: null,
+                    query: null,
+                    signal: null,
+                    metadata: event.metadata ?? null,
+                    createdAt,
+                });
+            }
+        }
+        // ── Merge and sort ────────────────────────────────────────────────────
+        const entries = [...usageEntries, ...proposalEntries].sort((a, b) => {
+            // Primary sort: chronological by createdAt (string compare is safe for
+            // "YYYY-MM-DD HH:MM:SS" format). Secondary sort: id ascending for ties.
+            if (a.createdAt < b.createdAt)
+                return -1;
+            if (a.createdAt > b.createdAt)
+                return 1;
+            return a.id - b.id;
+        });
         const response = {
             schemaVersion: 1,
             ...(normalizedRef !== undefined ? { ref: normalizedRef } : {}),
             ...(sinceNormalized !== undefined ? { since: sinceNormalized } : {}),
             totalCount: entries.length,
             entries,
+            sources,
         };
         return response;
     }

package/dist/src/commands/registry-search.js

@@ -23,6 +23,9 @@ export async function searchRegistry(query, options) {
         return provider.search({ query: trimmed, limit, includeAssets: options?.includeAssets });
     }));
     // Merge results grouped by provider
+    // Each provider batch is normalized to [0, 1] before merging so that raw
+    // scores from different providers (e.g. static-index can exceed 1.85 while
+    // skills-sh uses installs-relative scoring) are comparable in the merged list.
     const allHits = [];
     const allAssetHits = [];
     for (let i = 0; i < results.length; i++) {
@@ -36,23 +39,34 @@ export async function searchRegistry(query, options) {
             continue;
         const registryLabel = entries[i].name ? `"${entries[i].name}"` : entries[i].url;
         let dropped = 0;
+        const validHits = [];
         for (const hit of value.hits) {
             if (isCompleteHit(hit)) {
-                allHits.push(hit);
+                validHits.push(hit);
             }
             else {
                 dropped++;
             }
         }
+        // Normalize scores within this provider's batch before merging
+        normalizeScores(validHits);
+        for (const hit of validHits) {
+            allHits.push(hit);
+        }
         if (value.assetHits) {
+            const validAssetHits = [];
             for (const hit of value.assetHits) {
                 if (isCompleteAssetHit(hit)) {
-                    allAssetHits.push(hit);
+                    validAssetHits.push(hit);
                 }
                 else {
                     dropped++;
                 }
             }
+            normalizeScores(validAssetHits);
+            for (const hit of validAssetHits) {
+                allAssetHits.push(hit);
+            }
         }
         if (dropped > 0) {
             warnings.push(`Registry ${registryLabel} returned ${dropped} incomplete hit(s); dropped from response.`);
@@ -60,7 +74,7 @@ export async function searchRegistry(query, options) {
         if (value.warnings)
             warnings.push(...value.warnings);
     }
-    // Sort merged hits by score descending, apply limit
+    // Sort merged hits by normalized score descending, apply limit
     allHits.sort((a, b) => (b.score ?? 0) - (a.score ?? 0));
     const limitedHits = allHits.slice(0, limit);
     allAssetHits.sort((a, b) => (b.score ?? 0) - (a.score ?? 0));
@@ -80,6 +94,11 @@ export async function searchRegistry(query, options) {
  * 1. AKM_REGISTRY_URL env var (CI override, comma-separated)
  * 2. config.registries (filtered by enabled !== false)
  * 3. Default registries from DEFAULT_CONFIG
+ *
+ * AKM_REGISTRY_URL syntax (comma-separated):
+ *   - Bare URL: `https://example.com/index.json`  → defaults to provider "static-index"
+ *   - Typed URL: `skills-sh::https://skills.sh/api`  → explicit provider type
+ *     Format: `<provider-type>::<url>`
  */
 export function resolveRegistries(configRegistries) {
     // Allow env var override (comma-separated URLs) — CI escape hatch
@@ -87,14 +106,30 @@ export function resolveRegistries(configRegistries) {
     if (envUrls) {
         const entries = [];
         for (const raw of envUrls.split(",")) {
-            const url = raw.trim();
-            if (!url)
+            const trimmed = raw.trim();
+            if (!trimmed)
                 continue;
+            // Parse optional `<provider-type>::<url>` prefix
+            let provider;
+            let url;
+            const colonColonIdx = trimmed.indexOf("::");
+            if (colonColonIdx !== -1 && !trimmed.startsWith("http://") && !trimmed.startsWith("https://")) {
+                // Only treat as `provider::url` if the prefix doesn't look like a URL scheme itself
+                provider = trimmed.slice(0, colonColonIdx).trim();
+                url = trimmed.slice(colonColonIdx + 2).trim();
+                if (!provider) {
+                    warn(`[akm] Ignoring AKM_REGISTRY_URL entry: empty provider type before "::" in "${trimmed}"`);
+                    continue;
+                }
+            }
+            else {
+                url = trimmed;
+            }
             if (!url.startsWith("http://") && !url.startsWith("https://")) {
                 warn(`[akm] Ignoring AKM_REGISTRY_URL entry: must start with http:// or https://, got "${url}"`);
                 continue;
             }
-            entries.push({ url });
+            entries.push(provider ? { url, provider } : { url });
         }
         return entries;
     }
@@ -113,6 +148,34 @@ function createProvider(entry, warnings) {
     return factory(entry);
 }
 // ── Utilities ───────────────────────────────────────────────────────────────
+/**
+ * Normalize the `score` field of a batch of hits in-place to [0, 1].
+ *
+ * Different registry providers use incompatible score scales
+ * (static-index can exceed 1.85; skills-sh uses installs-relative values
+ * in [0, 1]).  Normalizing each provider's batch independently before merging
+ * makes the merged sort order meaningful.
+ *
+ * When all scores are identical (or absent), scores are left unchanged so
+ * relative ordering within the batch is preserved (all-same is effectively
+ * already normalized).
+ */
+function normalizeScores(hits) {
+    if (hits.length === 0)
+        return;
+    const rawScores = hits.map((h) => h.score ?? 0);
+    const max = Math.max(...rawScores);
+    if (max <= 0)
+        return; // all zero or negative — leave as-is
+    const min = Math.min(...rawScores);
+    const range = max - min;
+    for (let i = 0; i < hits.length; i++) {
+        const raw = rawScores[i];
+        // Min-max normalize: [0, 1]. When all scores are equal (range === 0),
+        // fall back to dividing by max so the value stays in [0, 1].
+        hits[i].score = range > 0 ? (raw - min) / range : raw / max;
+    }
+}
 function clampLimit(limit) {
     if (!limit || !Number.isFinite(limit))
         return 20;

package/dist/src/commands/search.js

@@ -10,6 +10,7 @@
  */
 import { loadConfig } from "../core/config";
 import { UsageError } from "../core/errors";
+import { appendEvent } from "../core/events";
 import { closeDatabase, openDatabase } from "../indexer/db";
 import { searchLocal } from "../indexer/db-search";
 import { resolveSourceEntries } from "../indexer/search-source";
@@ -147,13 +148,30 @@ function resolveEntryIds(db, hits) {
 /**
  * Fire-and-forget: log a search event to the usage_events table.
  * Never blocks the caller; errors are silently ignored.
+ *
+ * Result count semantics:
+ *   - `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".
+ *   - `resultCount`: total across both pools so telemetry reflects the actual
+ *     number of results the user saw, regardless of source mode.
+ *
+ * Per-entry events are recorded only for stash hits because registry hits
+ * have no local entry_id to reference.
  */
 function logSearchEvent(query, response, existingDb) {
+    // Emit a structured event to events.jsonl so workflow-trace consumers
+    // detect akm search invocations without relying on stdout scraping.
+    const stashHits = response.hits.filter((h) => h.type !== "registry");
+    appendEvent({
+        eventType: "search",
+        metadata: { query, hitCount: stashHits.length, resultRefs: stashHits.map((h) => h.ref) },
+    });
     try {
         const db = existingDb ?? openDatabase();
         try {
-            const stashHits = response.hits.filter((h) => h.type !== "registry").slice(0, 50);
-            const resolved = resolveEntryIds(db, stashHits);
+            const resolved = resolveEntryIds(db, stashHits.slice(0, 50));
             for (const { entryId, ref } of resolved) {
                 insertUsageEvent(db, {
                     event_type: "search",
@@ -162,10 +180,19 @@ function logSearchEvent(query, response, existingDb) {
                     entry_ref: ref,
                 });
             }
+            // Count registry hits separately so registry-only searches record a
+            // non-zero resultCount. response.hits is always [] when source="registry".
+            const stashHitCount = response.hits.length;
+            const registryHitCount = Array.isArray(response.registryHits) ? response.registryHits.length : 0;
             insertUsageEvent(db, {
                 event_type: "search",
                 query,
-                metadata: JSON.stringify({ resultCount: response.hits.length, resolvedCount: resolved.length }),
+                metadata: JSON.stringify({
+                    resultCount: stashHitCount + registryHitCount,
+                    stashHitCount,
+                    registryHitCount,
+                    resolvedCount: resolved.length,
+                }),
             });
         }
         finally {

package/dist/src/commands/show.js

@@ -24,6 +24,7 @@ import path from "node:path";
 import { parseAssetRef } from "../core/asset-ref";
 import { loadConfig } from "../core/config";
 import { NotFoundError, UsageError } from "../core/errors";
+import { appendEvent, readEvents } from "../core/events";
 import { parseFrontmatter, toStringOrUndefined } from "../core/frontmatter";
 import { closeDatabase, findEntryIdByRef, openDatabase } from "../indexer/db";
 import { buildFileContext, buildRenderContext, getRenderer, runMatchers } from "../indexer/file-context";
@@ -35,6 +36,7 @@ import { resolveSourcesForOrigin } from "../registry/origin-resolve";
 // Eagerly import source providers to trigger self-registration.
 import "../sources/providers/index";
 import { resolveAssetPath } from "../sources/resolve";
+import { getActiveWorkflowRun } from "../workflows/runs";
 /**
  * Show a wiki root (no page path) — returns the same payload as
  * `akm wiki show <name>`.
@@ -136,7 +138,13 @@ export async function akmShowUnified(input) {
     if (input.scope && hasAnyScopeKey(input.scope) && result.path) {
         enforceScopeOrThrow(result.path, ref, input.scope);
     }
+    // Count prior shows of this ref before logging the current one.
+    const priorShowCount = recentShowCount(ref);
     logShowEvent(ref);
+    if (priorShowCount >= 2) {
+        // Agent has shown this same asset 3+ times — inject a loop-break hint.
+        result.showLoopWarning = priorShowCount + 1;
+    }
     return result;
 }
 function hasAnyScopeKey(scope) {
@@ -176,7 +184,24 @@ function enforceScopeOrThrow(filePath, ref, scope) {
         }
     }
 }
+/**
+ * Count how many times `ref` has been shown in the current session by reading
+ * recent events. Returns the count BEFORE the current invocation.
+ */
+function recentShowCount(ref) {
+    try {
+        const { events } = readEvents({ type: "show", ref });
+        return events.length;
+    }
+    catch {
+        return 0;
+    }
+}
 function logShowEvent(ref, existingDb) {
+    // Emit a structured event to events.jsonl so workflow-trace consumers
+    // detect akm show invocations without relying on stdout scraping.
+    const parsed = parseAssetRef(ref);
+    appendEvent({ eventType: "show", ref, metadata: { type: parsed.type, name: parsed.name } });
     try {
         const db = existingDb ?? openDatabase();
         try {
@@ -295,6 +320,10 @@ export async function showLocal(input) {
         editable,
         ...(!editable ? { editHint: buildEditHint(assetPath, parsed.type, parsed.name, source?.registryId) } : {}),
     };
+    const activeRun = getActiveWorkflowRun();
+    if (activeRun) {
+        fullResponse.activeRun = activeRun;
+    }
     if (input.detail === "brief") {
         return buildBriefResponse(fullResponse, assetPath);
     }