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

package/dist/commands/read/search.js

@@ -11,18 +11,20 @@
  * a registry search behind `--source registry|both`, and log a usage event.
  * Provider `search()` methods do not exist.
  */
-import { parseAssetRef, refToString } from "../../core/asset/asset-ref.js";
-import { loadConfig } from "../../core/config/config.js";
+import { getSources, loadConfig } from "../../core/config/config.js";
 import { rethrowIfTestIsolationError, UsageError } from "../../core/errors.js";
 import { appendEvent } from "../../core/events.js";
 import { isTransientStashPath } from "../../core/paths.js";
-import { bumpUtilityScoresBatch, getEntryIdByFilePath } from "../../indexer/db/db.js";
 import { resolveReadSources } from "../../indexer/read-preflight.js";
 import { searchLocal } from "../../indexer/search/db-search.js";
+import { getSearchHitAttribution, usageEventAttributionMetadata, } from "../../indexer/search/search-attribution.js";
+import { getEntryIdByFilePath, getItemRefById } from "../../storage/repositories/index-entries-repository.js";
+import { bumpUtilityScoresBatch } from "../../storage/repositories/index-utility-repository.js";
 import { getCurrentWorkflowScopeKey } from "../../workflows/authoring/scope-key.js";
 // Eagerly import source providers to trigger self-registration before the
 // indexer or path-resolution code runs.
 import "../../sources/providers/index.js";
+import { withStateDbTelemetry } from "../../core/state-db.js";
 import { insertUsageEvent } from "../../indexer/usage/usage-events.js";
 import { TELEMETRY_BUSY_TIMEOUT_MS, withIndexDb } from "../../storage/repositories/index-db.js";
 import { searchRegistry } from "./registry-search.js";
@@ -36,23 +38,14 @@ export async function akmSearch(input) {
     const parsedSource = parseSearchSource(input.source ?? "stash");
     const config = loadConfig();
     // Named-source filter: when --source is not a standard enum value, treat it
-    // as a named source from config.sources[].name. Validate early (before
+    // 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.
     let namedSourceName;
     let source;
     if (parsedSource !== "stash" && parsedSource !== "registry" && parsedSource !== "both") {
         namedSourceName = parsedSource;
-        // Check that the named source exists in the config before touching the stash.
-        const configSources = config.sources ?? [];
-        const foundInConfig = configSources.some((s) => s.name === namedSourceName) || configSources.some((s) => s.path === namedSourceName);
-        if (!foundInConfig) {
-            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.";
-            throw new UsageError(`Unknown source name: "${namedSourceName}". ${hint}`, "INVALID_SOURCE_VALUE");
-        }
+        assertNamedSourceExists(config, namedSourceName);
         source = "stash";
     }
     else {
@@ -79,8 +72,7 @@ export async function akmSearch(input) {
             warnings: ["No stashes configured. Run `akm init` to create your working stash."],
             timing: { totalMs: Date.now() - t0 },
         };
-        if (!input.skipLogging)
-            logSearchEvent(query, response, undefined, input.eventSource);
+        maybeLogSearchEvent(input, query, response);
         return response;
     }
     // Primary stash directory — used for DB path lookups and as the default
@@ -126,9 +118,7 @@ export async function akmSearch(input) {
             warnings: localResult?.warnings?.length ? localResult.warnings : undefined,
             timing: { totalMs: Date.now() - t0, rankMs: localResult?.rankMs, embedMs: localResult?.embedMs },
         };
-        if (!input.skipLogging) {
-            logSearchEvent(query, response, localResult?.mode ?? "keyword", input.eventSource, input.disableScopedUtility === true);
-        }
+        maybeLogSearchEvent(input, query, response, localResult?.mode ?? "keyword");
         return response;
     }
     const registryHits = (registryResult?.hits ?? []).map((hit) => {
@@ -162,8 +152,7 @@ export async function akmSearch(input) {
             warnings: registryResult?.warnings.length ? registryResult.warnings : undefined,
             timing: { totalMs: Date.now() - t0 },
         };
-        if (!input.skipLogging)
-            logSearchEvent(query, response, undefined, input.eventSource, input.disableScopedUtility === true);
+        maybeLogSearchEvent(input, query, response);
         return response;
     }
     // source === "both"
@@ -180,10 +169,14 @@ export async function akmSearch(input) {
         warnings: warnings.length ? warnings : undefined,
         timing: { totalMs: Date.now() - t0 },
     };
-    if (!input.skipLogging)
-        logSearchEvent(query, response, undefined, input.eventSource, input.disableScopedUtility === true);
+    maybeLogSearchEvent(input, query, response);
     return response;
 }
+function maybeLogSearchEvent(input, query, response, mode) {
+    if (input.skipLogging)
+        return;
+    logSearchEvent(query, response, mode, input.eventSource, input.disableScopedUtility === true, input.attributionProjection);
+}
 /**
  * Resolve entry IDs by file_path lookup (exact match, not LIKE).
  */
@@ -193,9 +186,13 @@ function resolveEntryIds(db, hits) {
         try {
             const entryId = getEntryIdByFilePath(db, hit.path);
             if (entryId !== undefined) {
-                const parsed = parseAssetRef(hit.ref);
-                const origin = parsed.origin ?? hit.origin ?? undefined;
-                results.push({ entryId, ref: refToString({ ...parsed, ...(origin ? { origin } : {}) }) });
+                // F4c: persist the DURABLE fully-qualified `bundle//conceptId` spelling,
+                // derived from the resolved entry row's `item_ref` (D-R3: durable keys
+                // come from the resolved item, never raw input).
+                const itemRef = getItemRefById(db, entryId);
+                if (itemRef !== null) {
+                    results.push({ entryId, ref: itemRef, hit });
+                }
             }
         }
         catch {
@@ -219,7 +216,7 @@ function resolveEntryIds(db, hits) {
  * Per-entry events are recorded only for stash hits because registry hits
  * have no local entry_id to reference.
  */
-function logSearchEvent(query, response, mode = "keyword", eventSource = "user", disableScopedUtility = false) {
+function logSearchEvent(query, response, mode = "keyword", eventSource = "user", disableScopedUtility = false, attributionProjection = "full") {
     // 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");
@@ -236,21 +233,42 @@ function logSearchEvent(query, response, mode = "keyword", eventSource = "user",
         // Under contention these usage hints are skipped, not waited for.
         withIndexDb((db) => {
             const resolved = resolveEntryIds(db, stashHits.slice(0, 50));
-            for (const { entryId, ref } of resolved) {
-                insertUsageEvent(db, {
+            // usage_events telemetry now writes to state.db (Chunk-8 WI-8.3);
+            // entry_id/entry_ref are resolved from index.db above and carried across.
+            const stashHitCount = response.hits.length;
+            const registryHitCount = Array.isArray(response.registryHits) ? response.registryHits.length : 0;
+            withStateDbTelemetry((stateDb) => {
+                for (const { entryId, ref, hit } of resolved) {
+                    insertUsageEvent(stateDb, {
+                        event_type: "search",
+                        query,
+                        entry_id: entryId,
+                        entry_ref: ref,
+                        metadata: usageEventAttributionMetadata(getSearchHitAttribution(hit), ref, attributionProjection),
+                        source: eventSource,
+                    });
+                }
+                // Count registry hits separately so registry-only searches record a
+                // non-zero resultCount. response.hits is always [] when source="registry".
+                insertUsageEvent(stateDb, {
                     event_type: "search",
                     query,
-                    entry_id: entryId,
-                    entry_ref: ref,
+                    metadata: JSON.stringify({
+                        resultCount: stashHitCount + registryHitCount,
+                        stashHitCount,
+                        registryHitCount,
+                        resolvedCount: resolved.length,
+                        mode,
+                    }),
                     source: eventSource,
                 });
-            }
+            }, TELEMETRY_BUSY_TIMEOUT_MS);
             // Bump utility scores for all resolved entries (MemRL retrieval signal).
             // The indexer overwrites these at next reindex; bumps are temporary hints.
             // Gated to user-sourced events: pipeline searches (improve probes, task
             // runner) must not feed the utility signal (meta-review 05 DRIFT-6 —
             // the bump previously fired unconditionally, so even correctly-tagged
-            // machine traffic inflated utility).
+            // machine traffic inflated utility). utility_scores stays in index.db.
             const resolvedIds = eventSource === "user" ? resolved.map((r) => r.entryId).filter((id) => id !== undefined) : [];
             if (resolvedIds.length > 0) {
                 let scopeKey;
@@ -264,22 +282,6 @@ function logSearchEvent(query, response, mode = "keyword", eventSource = "user",
                 }
                 bumpUtilityScoresBatch(db, resolvedIds, 1.0, 0.1, scopeKey);
             }
-            // 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: stashHitCount + registryHitCount,
-                    stashHitCount,
-                    registryHitCount,
-                    resolvedCount: resolved.length,
-                    mode,
-                }),
-                source: eventSource,
-            });
         }, { busyTimeoutMs: TELEMETRY_BUSY_TIMEOUT_MS });
     }
     catch (err) {
@@ -288,6 +290,23 @@ function logSearchEvent(query, response, mode = "keyword", eventSource = "user",
     }
 }
 // ── Helpers ──────────────────────────────────────────────────────────────────
+/**
+ * Validate a named `--source` 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.
+ */
+function assertNamedSourceExists(config, namedSourceName) {
+    const configSources = getSources(config);
+    const foundInConfig = configSources.some((s) => s.name === namedSourceName) || configSources.some((s) => s.path === namedSourceName);
+    if (!foundInConfig) {
+        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.";
+        throw new UsageError(`Unknown source name: "${namedSourceName}". ${hint}`, "INVALID_SOURCE_VALUE");
+    }
+}
 function normalizeLimit(limit) {
     if (typeof limit !== "number" || Number.isNaN(limit) || limit <= 0) {
         return DEFAULT_LIMIT;
@@ -399,9 +418,3 @@ export function entryMatchesScopeFilters(scope, filters) {
     }
     return true;
 }
-/**
- * Merge stash hits and registry hits via simple concatenation.
- */
-export function mergeSearchHits(localHits, registryHits, limit) {
-    return [...localHits, ...registryHits].slice(0, limit);
-}

package/dist/commands/read/show.js

@@ -8,100 +8,45 @@
  *
  *   show(ref) → indexer.lookup(ref) → readFile(entry.filePath)
  *
- * The richer presentation logic (matchers, renderers, wiki-root handling,
- * edit-hints, summary-detail truncation) lives below in this file. The flow:
+ * The richer presentation logic (matchers, renderers, edit-hints,
+ * summary-detail truncation) lives below in this file. The flow:
  *
- *   1. Special-case wiki-root refs (`wiki:<name>` with no page path).
- *   2. Auto-index when stale so the index is current.
- *   3. Ask `indexer.lookup(ref)` for the row in the FTS index.
- *   4. Render the file via the matcher/renderer pipeline.
+ *   1. Auto-index when stale so the index is current.
+ *   2. Ask `indexer.lookup(ref)` for the row in the FTS index.
+ *   3. Render the file via the matcher/renderer pipeline.
  */
 import fs from "node:fs";
-import path from "node:path";
 import { findCittyTopLevelCommandIndex } from "../../cli/parse-args.js";
-import { parseAssetRef, refToString } from "../../core/asset/asset-ref.js";
+import { recognizeMatch } from "../../core/adapter/recognize-match.js";
 import { parseFrontmatter } from "../../core/asset/frontmatter.js";
+import { displayRef, parseQualifiedRefInput } from "../../core/asset/resolve-ref.js";
 import { META_DIR, parseMetaRef, resolveMetaFilePath } from "../../core/asset/stash-meta.js";
 import { asNonEmptyString } from "../../core/common.js";
 import { getIndexPassConfig, loadConfig } from "../../core/config/config.js";
 import { NotFoundError, rethrowIfTestIsolationError, UsageError } from "../../core/errors.js";
 import { appendEvent, readEvents } from "../../core/events.js";
-import { closeDatabase, computeBodyHash, findEntryIdByRef, getEntryIdByFilePath, openExistingDatabase, } from "../../indexer/db/db.js";
+import { withStateDbTelemetry } from "../../core/state-db.js";
 import { hasGraphData } from "../../indexer/db/graph-db.js";
 import { listRelatedPathsForFile } from "../../indexer/graph/graph-boost.js";
 import { extractGraphForSingleFile } from "../../indexer/graph/graph-extraction.js";
 import { lookup } from "../../indexer/indexer.js";
 import { ensurePrimaryIndexForRead, resolveReadSources } from "../../indexer/read-preflight.js";
+import { usageEventAttributionMetadata } from "../../indexer/search/search-attribution.js";
 import { buildEditHint, findSourceForPath, isEditable, resolveSourceEntries } from "../../indexer/search/search-source.js";
 import { insertUsageEvent } from "../../indexer/usage/usage-events.js";
-import { buildFileContext, buildRenderContext, getRenderer, runMatchers } from "../../indexer/walk/file-context.js";
+import { buildFileContext, buildRenderContext, getRenderer } from "../../indexer/walk/file-context.js";
 import { resolveAssetPath } from "../../indexer/walk/path-resolver.js";
 import { resolveIndexPassLLM } from "../../llm/index-passes.js";
 import { resolveSourcesForOrigin } from "../../registry/origin-resolve.js";
 import { resolveStorageLocations } from "../../storage/locations.js";
+import { closeDatabase, openExistingDatabase } from "../../storage/repositories/index-connection.js";
 import { TELEMETRY_BUSY_TIMEOUT_MS, withIndexDb } from "../../storage/repositories/index-db.js";
+import { findEntryIdByRef, getEntryById, getEntryIdByFilePath, getItemRefById, } from "../../storage/repositories/index-entries-repository.js";
+import { computeBodyHash } from "../../storage/repositories/index-llm-cache-repository.js";
 // Eagerly import source providers to trigger self-registration.
 import "../../sources/providers/index.js";
 import { getCurrentWorkflowScopeKey } from "../../workflows/authoring/scope-key.js";
 import { getActiveWorkflowRun } from "../../workflows/runtime/runs.js";
-/**
- * Show a wiki root (no page path) — returns the same payload as
- * `akm wiki show <name>`.
- */
-async function showWikiRoot(stashDir, wikiName) {
-    const { showWiki } = await import("../../wiki/wiki.js");
-    const result = showWiki(stashDir, wikiName);
-    return {
-        type: "wiki",
-        name: result.ref,
-        path: result.path,
-        ...(result.description ? { description: result.description } : {}),
-        origin: null,
-        editable: false,
-        pages: result.pages,
-        raws: result.raws,
-        ...(result.lastModified ? { lastModified: result.lastModified } : {}),
-        recentLog: result.recentLog,
-    };
-}
-async function showWikiRootForSource(stashDir, source, wikiName) {
-    const { showWikiAtPath } = await import("../../wiki/wiki.js");
-    if (source.wikiName === wikiName) {
-        const result = showWikiAtPath(wikiName, source.path);
-        return {
-            type: "wiki",
-            name: result.ref,
-            path: result.path,
-            ...(result.description ? { description: result.description } : {}),
-            origin: null,
-            editable: false,
-            pages: result.pages,
-            raws: result.raws,
-            ...(result.lastModified ? { lastModified: result.lastModified } : {}),
-            recentLog: result.recentLog,
-        };
-    }
-    return showWikiRoot(stashDir, wikiName);
-}
-function resolveRegisteredWikiAssetPath(wikiRoot, wikiName, assetName) {
-    const pageName = assetName === wikiName ? "" : assetName.slice(wikiName.length + 1);
-    if (!pageName) {
-        throw new NotFoundError(`Wiki page not found: wiki:${assetName}`);
-    }
-    const candidate = path.resolve(wikiRoot, `${pageName}.md`);
-    const resolvedRoot = fs.realpathSync(wikiRoot);
-    if (!candidate.startsWith(resolvedRoot + path.sep)) {
-        throw new UsageError("Ref resolves outside the stash root.", "PATH_ESCAPE_VIOLATION");
-    }
-    if (!fs.existsSync(candidate) || !fs.statSync(candidate).isFile()) {
-        throw new NotFoundError(`Stash asset not found for ref: wiki:${assetName}`);
-    }
-    const realTarget = fs.realpathSync(candidate);
-    if (!realTarget.startsWith(resolvedRoot + path.sep)) {
-        throw new UsageError("Ref resolves outside the stash root.", "PATH_ESCAPE_VIOLATION");
-    }
-    return realTarget;
-}
 /**
  * Unified show: queries the local FTS5 index, then falls back to on-disk
  * type-dir resolution if the index has no row. Spec §6.2; no remote provider
@@ -122,30 +67,6 @@ export async function akmShowUnified(input) {
         if (metaRef)
             return showStashMeta(metaRef);
     }
-    // 0. Wiki-root shortcut: `wiki:<name>` with no page path routes to the
-    //    wiki summary (same payload as `akm wiki show <name>`). Honour
-    //    `parsed.origin` by resolving against the matching stash source(s),
-    //    falling back to the primary stash when no origin is given.
-    {
-        const parsed = parseAssetRef(ref);
-        if (parsed.type === "wiki" && !parsed.name.includes("/")) {
-            const allSources = resolveSourceEntries();
-            const searchSources = resolveSourcesForOrigin(parsed.origin, allSources);
-            let lastError;
-            for (const source of searchSources) {
-                try {
-                    return await showWikiRootForSource(allSources[0]?.path ?? source.path, source, parsed.name);
-                }
-                catch (err) {
-                    if (!(err instanceof NotFoundError))
-                        throw err;
-                    lastError = err;
-                }
-            }
-            throw (lastError ??
-                new NotFoundError(`Wiki not found: ${parsed.name}. Run \`akm wiki create ${parsed.name}\` to create it.`));
-        }
-    }
     // Auto-index when stale so the index is current before lookup.
     const { primarySource } = resolveReadSources();
     await ensurePrimaryIndexForRead(primarySource);
@@ -159,11 +80,13 @@ export async function akmShowUnified(input) {
         enforceScopeOrThrow(result.path, ref, input.scope);
     }
     // Count prior shows of this ref before logging the current one.
-    const priorShowCount = recentShowCount(ref);
-    logShowEvent(ref, input.eventSource, result.path, result.origin);
-    if (priorShowCount >= 2) {
-        // Agent has shown this same asset 3+ times — inject a loop-break hint.
-        result.showLoopWarning = priorShowCount + 1;
+    if (!input.skipLogging) {
+        const priorShowCount = recentShowCount(ref);
+        logShowEvent(ref, input.eventSource, result.path, result.origin);
+        if (priorShowCount >= 2) {
+            // Agent has shown this same asset 3+ times — inject a loop-break hint.
+            result.showLoopWarning = priorShowCount + 1;
+        }
     }
     return result;
 }
@@ -260,8 +183,10 @@ function recentShowCount(ref) {
 function logShowEvent(ref, eventSource = "user", filePath, origin) {
     // Emit a structured event to events.jsonl so workflow-trace consumers
     // detect akm show invocations without relying on stdout scraping.
-    const parsed = parseAssetRef(ref);
-    const eventRef = refToString({ ...parsed, ...(parsed.origin || !origin ? {} : { origin }) });
+    const parsed = parseQualifiedRefInput(ref);
+    // New-grammar display ref: also the lookup key below, which `findEntryIdByRef`
+    // resolves against `item_ref`.
+    const eventRef = displayRef({ type: parsed.type, name: parsed.name, bundleId: parsed.origin ?? origin ?? undefined });
     appendEvent({ eventType: "show", ref: eventRef, metadata: { type: parsed.type, name: parsed.name } });
     // Detect if this show is a selection from a recent search result.
     try {
@@ -294,12 +219,22 @@ function logShowEvent(ref, eventSource = "user", filePath, origin) {
     }
     try {
         withIndexDb((db) => {
-            insertUsageEvent(db, {
-                event_type: "show",
-                entry_ref: eventRef,
-                entry_id: filePath ? getEntryIdByFilePath(db, filePath) : findEntryIdByRef(db, eventRef),
-                source: eventSource,
-            });
+            const entryId = filePath ? getEntryIdByFilePath(db, filePath) : findEntryIdByRef(db, eventRef);
+            // The DURABLE usage-event key is the resolved entry's fully-qualified
+            // `item_ref`; the new-grammar `eventRef` is the fallback for an
+            // unresolved / not-yet-indexed show. entry_id/item_ref resolve from
+            // index.db (`db`); the usage_events write lands in state.db (WI-8.3).
+            const entryRef = (entryId !== undefined ? getItemRefById(db, entryId) : null) ?? eventRef;
+            const entry = entryId !== undefined ? getEntryById(db, entryId) : undefined;
+            withStateDbTelemetry((stateDb) => {
+                insertUsageEvent(stateDb, {
+                    event_type: "show",
+                    entry_ref: entryRef,
+                    entry_id: entryId,
+                    metadata: usageEventAttributionMetadata(entry?.entry.derivedFrom ? { memoryInference: { exposure: "direct" } } : undefined, entryRef),
+                    source: eventSource,
+                });
+            }, TELEMETRY_BUSY_TIMEOUT_MS);
         }, { busyTimeoutMs: TELEMETRY_BUSY_TIMEOUT_MS });
     }
     catch (err) {
@@ -309,51 +244,34 @@ function logShowEvent(ref, eventSource = "user", filePath, origin) {
 }
 /** @internal Use akmShowUnified() for all external callers. */
 export async function showLocal(input) {
-    const parsed = parseAssetRef(input.ref);
+    const parsed = parseQualifiedRefInput(input.ref);
     const displayType = parsed.type;
     const config = loadConfig();
     const allSources = resolveSourceEntries(input.stashDir);
     const searchSources = resolveSourcesForOrigin(parsed.origin, allSources);
     const allSourceDirs = searchSources.map((s) => s.path);
-    let assetPath;
-    const matchedSource = parsed.type === "wiki" ? searchSources.find((source) => parsed.name.startsWith(`${source.wikiName}/`)) : undefined;
-    let lastError;
-    if (parsed.type === "wiki" && matchedSource?.wikiName) {
-        try {
-            assetPath = resolveRegisteredWikiAssetPath(matchedSource.path, matchedSource.wikiName, parsed.name);
-        }
-        catch (err) {
-            lastError = err instanceof Error ? err : new Error(String(err));
-        }
-    }
-    if (!assetPath) {
-        const resolvedAssetPath = await resolveAssetPath(parsed, {
-            stashDir: input.stashDir,
-            mode: "index-first",
-        });
-        assetPath = resolvedAssetPath ?? undefined;
-    }
+    const resolvedAssetPath = await resolveAssetPath(parsed, {
+        stashDir: input.stashDir,
+        mode: "index-first",
+    });
+    const assetPath = resolvedAssetPath ?? undefined;
     if (!assetPath && parsed.origin && searchSources.length === 0) {
         const installCmd = `akm add ${parsed.origin}`;
         throw new NotFoundError(`Stash asset not found for ref: ${displayType}:${parsed.name}. ` +
             `Stash "${parsed.origin}" is not installed. Run: ${installCmd}`);
     }
     if (!assetPath) {
-        throw (lastError ??
-            new NotFoundError(`Stash asset not found for ref: ${displayType}:${parsed.name}. ` +
-                "Check the name with `akm search` or verify the asset exists in your stash."));
+        throw new NotFoundError(`Stash asset not found for ref: ${displayType}:${parsed.name}. ` +
+            "Check the name with `akm search` or verify the asset exists in your stash.");
     }
-    const source = matchedSource ?? findSourceForPath(assetPath, allSources);
+    const source = findSourceForPath(assetPath, allSources);
     const sourceStashDir = source?.path ?? allSourceDirs[0];
     if (!sourceStashDir) {
         throw new UsageError(`Could not determine stash root for asset: ${displayType}:${parsed.name}. ` +
             "Run `akm init` to create the stash directory, or check `akm stash list` for configured paths.");
     }
     const fileCtx = buildFileContext(sourceStashDir, assetPath);
-    const forcedWikiMatch = parsed.type === "wiki" && source?.wikiName && parsed.name.startsWith(`${source.wikiName}/`)
-        ? { type: "wiki", specificity: 20, renderer: "wiki-md", meta: {} }
-        : undefined;
-    const match = forcedWikiMatch ?? (await runMatchers(fileCtx));
+    const match = recognizeMatch(fileCtx);
     if (!match) {
         throw new UsageError(`Could not display asset "${displayType}:${parsed.name}" — unsupported file type or unrecognized layout`);
     }
@@ -477,7 +395,7 @@ async function maybeExtractGraphInline(config, sourceStashDir, assetPath) {
  * renderer graph. Spec §6.2's literal flow.
  */
 export async function showByRef(ref) {
-    const parsed = parseAssetRef(ref);
+    const parsed = parseQualifiedRefInput(ref);
     const entry = await lookup(parsed);
     if (!entry) {
         throw new NotFoundError(`Asset not found for ref: ${parsed.type}:${parsed.name}`);
@@ -587,8 +505,9 @@ export function normalizeShowArgv(argv) {
         }
         if (arg === "--format" || arg === "--detail" || arg === "--shape") {
             globalFlags.push(arg);
-            if (rest[i + 1] !== undefined) {
-                globalFlags.push(rest[i + 1]);
+            const nextArg = rest[i + 1];
+            if (nextArg !== undefined) {
+                globalFlags.push(nextArg);
                 i++;
             }
             continue;

package/dist/commands/remember.js

@@ -8,14 +8,15 @@
  * heuristic derivation, LLM enrichment) is testable in isolation and the
  * CLI entry point stays focused on argument parsing + output routing.
  */
+import { getParsedInvocation } from "../cli/invocation.js";
 import { serializeFrontmatter } from "../core/asset/asset-serialize.js";
 import { toErrorMessage, tryReadStdinText } from "../core/common.js";
-import { getDefaultLlmConfig, loadConfig } from "../core/config/config.js";
+import { loadConfig } from "../core/config/config.js";
 import { UsageError } from "../core/errors.js";
 import { DURATION_UNITS, parseDuration as parseDurationSpec } from "../core/time.js";
 import { warn } from "../core/warn.js";
 import { SCOPE_KEYS } from "../indexer/passes/metadata.js";
-import { parseFlagValue } from "../output/context.js";
+import { getDefaultLlmConfig } from "../integrations/agent/engine-resolution.js";
 /**
  * Parse a shorthand duration string to a number of milliseconds.
  * Supports the CLI-wide canonical grammar: `30d` (days), `12h` (hours),
@@ -215,13 +216,14 @@ Return ONLY the JSON object, no prose, no markdown fences.`;
 export function resolveRememberContentArg(content) {
     if (content === undefined)
         return undefined;
-    const parsedFormat = parseFlagValue(process.argv, "--format");
+    const invocation = getParsedInvocation();
+    const parsedFormat = invocation.getFlagValue("--format");
     if (parsedFormat !== undefined &&
         content === parsedFormat &&
         wasRememberFlagValueConsumedAsContent(content, parsedFormat, "--format")) {
         return undefined;
     }
-    const parsedDetail = parseFlagValue(process.argv, "--detail");
+    const parsedDetail = invocation.getFlagValue("--detail");
     if (parsedDetail !== undefined &&
         content === parsedDetail &&
         wasRememberFlagValueConsumedAsContent(content, parsedDetail, "--detail")) {
@@ -230,7 +232,7 @@ export function resolveRememberContentArg(content) {
     return content;
 }
 function wasRememberFlagValueConsumedAsContent(content, flagValue, flagName) {
-    const argv = process.argv.slice(2);
+    const argv = getParsedInvocation().userArgs;
     const rememberIndex = argv.indexOf("remember");
     const tokens = rememberIndex >= 0 ? argv.slice(rememberIndex + 1) : argv;
     let flagIndex = -1;

package/dist/commands/sources/add-cli.js

@@ -5,13 +5,14 @@ import fs from "node:fs";
 import path from "node:path";
 import * as p from "../../cli/clack.js";
 import { defineJsonCommand, output } from "../../cli/shared.js";
+import { decideDangerousKeyInstall } from "../../core/activation-policy.js";
 import { UsageError } from "../../core/errors.js";
 import { appendEvent } from "../../core/events.js";
 import { warn } from "../../core/warn.js";
 import { akmRemove } from "./installed-stashes.js";
 import { akmAdd } from "./source-add.js";
 import { addStash } from "./source-manage.js";
-// ── Shared website-options helper (also used by wikiRegisterCommand) ──────────
+// ── Shared website-options helper ──────────
 export function buildWebsiteOptions(args) {
     const websiteOptions = {};
     if (typeof args["max-pages"] === "string" && args["max-pages"].length > 0)
@@ -79,9 +80,15 @@ export async function auditInstalledStashForDangerousKeys(opts) {
     catch {
         return { blocked: false };
     }
-    if (allFindings.length === 0)
+    // The workspace activation policy fixes the baseline stance; the interactive
+    // confirm / rollback below is layered on top of the `"gate"` stance only.
+    const stance = decideDangerousKeyInstall({
+        findingsPresent: allFindings.length > 0,
+        allowInsecure: allowDangerousKeys,
+    });
+    if (stance === "allow")
         return { blocked: false };
-    if (allowDangerousKeys) {
+    if (stance === "warn-allow") {
         // Operator has explicitly accepted the risk — warn and continue.
         for (const f of allFindings) {
             warn(`[dangerous-vault-key] ${f.relPath}: key \`${f.keyName}\` in ${f.vaultRef} can hijack process execution via \`akm env run\`. Proceeding because --allow-insecure was set.`);
@@ -166,10 +173,6 @@ export const addCommand = defineJsonCommand({
             description: "Mark a git stash as writable so changes can be pushed back",
             default: false,
         },
-        type: {
-            type: "string",
-            description: "Override asset type for all files in this stash (currently supports: wiki)",
-        },
         "max-pages": { type: "string", description: "Maximum pages to crawl for website sources (default: 50)" },
         "max-depth": { type: "string", description: "Maximum crawl depth for website sources (default: 3)" },
         "allow-insecure": {
@@ -228,25 +231,9 @@ export const addCommand = defineJsonCommand({
             warn("Warning: source URL uses plain HTTP (not HTTPS). --allow-insecure was set; an on-path attacker could substitute a malicious payload.");
         }
         const websiteOptions = buildWebsiteOptions(args);
-        if (args.type === "wiki") {
-            const { registerWikiSource } = await import("./source-add.js");
-            const result = await registerWikiSource({
-                ref,
-                name: args.name,
-                options: Object.keys(websiteOptions).length > 0 ? websiteOptions : undefined,
-                writable: args.writable,
-            });
-            appendEvent({
-                eventType: "add",
-                metadata: { target: ref, type: "wiki", name: args.name ?? null, writable: args.writable === true },
-            });
-            output("add", result);
-            return;
-        }
         const result = await akmAdd({
             ref,
             name: args.name,
-            overrideType: args.type,
             options: Object.keys(websiteOptions).length > 0 ? websiteOptions : undefined,
             writable: args.writable,
         });
@@ -255,7 +242,6 @@ export const addCommand = defineJsonCommand({
             metadata: {
                 target: ref,
                 name: args.name ?? null,
-                overrideType: args.type ?? null,
                 writable: args.writable === true,
             },
         });