akm-cli 0.8.6 → 0.8.14

package/dist/commands/{curate.js → read/curate.js}

@@ -13,13 +13,13 @@
  * pure helpers (`curateSearchResults`, `orderCuratedTypes`,
  * `deriveCurateFallbackQueries`) by importing them directly.
  */
-import { rethrowIfTestIsolationError, UsageError } from "../core/errors";
-import { appendEvent } from "../core/events";
-import { closeDatabase, openExistingDatabase } from "../indexer/db";
-import { insertUsageEvent } from "../indexer/usage-events";
-import { truncateDescription } from "../output/shapes";
-import { akmSearch, parseSearchSource } from "./search";
-import { akmShowUnified } from "./show";
+import { rethrowIfTestIsolationError, UsageError } from "../../core/errors.js";
+import { appendEvent } from "../../core/events.js";
+import { closeDatabase, openExistingDatabase } from "../../indexer/db/db.js";
+import { insertUsageEvent } from "../../indexer/usage/usage-events.js";
+import { truncateDescription } from "../../output/shapes.js";
+import { akmSearch, parseSearchSource } from "./search.js";
+import { akmShowUnified } from "./show.js";
 const CURATE_FALLBACK_FILTER_WORDS = new Set([
     "a",
     "an",

package/dist/commands/{knowledge.js → read/knowledge.js}

@@ -10,12 +10,13 @@
  */
 import fs from "node:fs";
 import path from "node:path";
-import { resolveAssetPathFromName } from "../core/asset-spec";
-import { isHttpUrl, isWithin, tryReadStdinText } from "../core/common";
-import { loadConfig } from "../core/config";
-import { UsageError } from "../core/errors";
-import { resolveWriteTarget, writeAssetToSource } from "../core/write-source";
-import { fetchWebsiteMarkdownSnapshot } from "../sources/website-ingest";
+import { assertFlatAssetName, combineCreatePath, normalizeCreateSubPath } from "../../core/asset/asset-create.js";
+import { resolveAssetPathFromName } from "../../core/asset/asset-spec.js";
+import { isHttpUrl, isWithin, tryReadStdinText } from "../../core/common.js";
+import { loadConfig } from "../../core/config/config.js";
+import { UsageError } from "../../core/errors.js";
+import { commitWriteTargetBoundary, formatRefForMessage, resolveWriteTarget, writeAssetToSource, } from "../../core/write-source.js";
+import { fetchWebsiteMarkdownSnapshot } from "../../sources/website-ingest.js";
 const MAX_CAPTURED_ASSET_SLUG_LENGTH = 64;
 // ── Asset-name normalisation ─────────────────────────────────────────────────
 /**
@@ -38,6 +39,9 @@ export function normalizeMarkdownAssetName(name, fallback) {
     }
     return trimmed;
 }
+// `--path`/`--name` create semantics are shared across all asset-creating
+// commands; re-exported here so existing `./knowledge` importers keep working.
+export { assertFlatAssetName, combineCreatePath, normalizeCreateSubPath };
 function slugifyAssetName(value, fallbackPrefix) {
     const slug = value
         .toLowerCase()
@@ -114,9 +118,14 @@ export async function readKnowledgeInput(source) {
  */
 export async function writeMarkdownAsset(options) {
     const cfg = loadConfig();
-    const { source, config } = resolveWriteTarget(cfg, options.target);
+    const target = resolveWriteTarget(cfg, options.target);
+    const { source, config } = target;
     const typeRoot = path.join(source.path, options.type === "knowledge" ? "knowledge" : "memories");
-    const normalizedName = normalizeMarkdownAssetName(options.name, inferAssetName(options.content, options.fallbackPrefix, options.preferredName));
+    // `--name` is the flat asset name; `--path` is the subdirectory under the
+    // type root. Combine them into the nested name the path resolver expects.
+    const subPath = normalizeCreateSubPath(options.path);
+    const baseName = normalizeMarkdownAssetName(options.name, inferAssetName(options.content, options.fallbackPrefix, options.preferredName));
+    const normalizedName = combineCreatePath(subPath, baseName);
     // Pre-flight: existence + force semantics. The helper itself overwrites
     // unconditionally; the CLI surfaces a friendlier UsageError before any
     // disk activity when --force is absent.
@@ -127,7 +136,11 @@ export async function writeMarkdownAsset(options) {
     if (fs.existsSync(assetPath) && !options.force) {
         throw new UsageError(`${options.type === "knowledge" ? "Knowledge" : "Memory"} "${normalizedName}" already exists. Re-run with --force to overwrite it.`, "RESOURCE_ALREADY_EXISTS");
     }
-    const result = await writeAssetToSource(source, config, { type: options.type, name: normalizedName }, options.content);
+    const ref = { type: options.type, name: normalizedName };
+    const result = await writeAssetToSource(source, config, ref, options.content);
+    // 0.9.0 (issue #507): single batch commit at the write boundary for git
+    // targets. No-op for filesystem/primary-stash targets.
+    commitWriteTargetBoundary(target, `Update ${formatRefForMessage(ref)}`);
     return {
         ref: result.ref,
         path: result.path,

package/dist/commands/{registry-search.js → read/registry-search.js}

@@ -1,12 +1,12 @@
 // 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 { toErrorMessage } from "../core/common";
-import { DEFAULT_CONFIG } from "../core/config";
-import { warn } from "../core/warn";
-import { resolveProviderFactory } from "../registry/factory";
+import { toErrorMessage } from "../../core/common.js";
+import { DEFAULT_CONFIG } from "../../core/config/config.js";
+import { warn } from "../../core/warn.js";
+import { resolveProviderFactory } from "../../registry/factory.js";
 // ── Eagerly import providers to trigger self-registration ───────────────────
-import "../registry/providers/index";
+import "../../registry/providers/index.js";
 // ── Public API ──────────────────────────────────────────────────────────────
 export async function searchRegistry(query, options) {
     const trimmed = query.trim();

package/dist/commands/{remember-cli.js → read/remember-cli.js}

@@ -2,12 +2,12 @@
 // 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 { defineCommand } from "citty";
-import { output, parseAllFlagValues, runWithJsonErrors } from "../cli/shared";
-import { UsageError } from "../core/errors";
-import { appendEvent } from "../core/events";
-import { inferAssetName, writeMarkdownAsset } from "./knowledge";
-import { buildMemoryFrontmatter, parseDuration, readMemoryContent, resolveRememberContentArg, runAutoHeuristics, runLlmEnrich, } from "./remember";
-import { akmSearch } from "./search";
+import { output, parseAllFlagValues, runWithJsonErrors } from "../../cli/shared.js";
+import { UsageError } from "../../core/errors.js";
+import { appendEvent } from "../../core/events.js";
+import { buildMemoryFrontmatter, parseDuration, readMemoryContent, resolveRememberContentArg, runAutoHeuristics, runLlmEnrich, } from "../remember.js";
+import { assertFlatAssetName, inferAssetName, writeMarkdownAsset } from "./knowledge.js";
+import { akmSearch } from "./search.js";
 // ── Helper: similar memory search ────────────────────────────────────────────
 /**
  * Best-effort top-3 similar memory search for `--show-similar`.
@@ -39,7 +39,11 @@ export const rememberCommand = defineCommand({
         },
         name: {
             type: "string",
-            description: "Memory name (defaults to a slug from the content)",
+            description: "Memory name (flat, no '/'; defaults to a slug from the content). Use --path for a subdirectory.",
+        },
+        path: {
+            type: "string",
+            description: "Relative subdirectory under memories/ to place the memory in (e.g. 'personal/projects'). The filename still comes from --name or the content slug.",
         },
         force: {
             type: "boolean",
@@ -100,6 +104,8 @@ export const rememberCommand = defineCommand({
     async run({ args }) {
         return runWithJsonErrors(async () => {
             const body = readMemoryContent(resolveRememberContentArg(args.content));
+            // `--name` is a flat name; subdirectory placement is `--path`'s job.
+            assertFlatAssetName(args.name);
             // Determine if the user has requested any structured metadata mode.
             // Collect all --tag occurrences directly from process.argv because citty
             // only exposes the last value for repeated string flags.
@@ -138,6 +144,7 @@ export const rememberCommand = defineCommand({
                     preferredName: inferAssetName(body, "memory"),
                     force: args.force,
                     target: args.target,
+                    path: args.path,
                 });
                 appendEvent({
                     eventType: "remember",
@@ -232,6 +239,7 @@ export const rememberCommand = defineCommand({
                 fallbackPrefix: "memory",
                 force: args.force,
                 target: args.target,
+                path: args.path,
             });
             appendEvent({
                 eventType: "remember",

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

@@ -0,0 +1,207 @@
+// 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/.
+/**
+ * `akm search`, `akm curate`, and `akm show` command family. Extracted verbatim
+ * 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`
+ * 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 { parsePositiveIntFlag } from "../../cli/parse-args.js";
+import { defineJsonCommand, output, parseAllFlagValues } from "../../cli/shared.js";
+import { parseAssetRef } from "../../core/asset/asset-ref.js";
+import { parseMetaRef } from "../../core/asset/stash-meta.js";
+import { UsageError } from "../../core/errors.js";
+import { getHyphenatedBoolean, getOutputMode, parseFlagValue } from "../../output/context.js";
+import { 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 or the internal
+// `improve` loop so the event log can distinguish them; any other value is
+// treated as unset.
+function resolveEventSource() {
+    const raw = process.env.AKM_EVENT_SOURCE;
+    if (raw === "improve")
+        return "improve";
+    if (raw === "user")
+        return "user";
+    return undefined;
+}
+export const searchCommand = defineJsonCommand({
+    meta: { name: "search", description: "Search the stash" },
+    args: {
+        query: { type: "positional", description: "Search query (omit to list all assets)", required: false, default: "" },
+        type: {
+            type: "string",
+            description: "Asset type filter (skill, command, agent, knowledge, workflow, script, memory, env, secret, wiki, lesson, or any). Use workflow to find step-by-step task assets.",
+        },
+        limit: { type: "string", description: "Maximum number of results" },
+        source: { type: "string", description: "Search source (stash|registry|both)", default: "stash" },
+        filter: {
+            type: "string",
+            description: "Scope filter (repeatable): --filter user=<id> --filter agent=<id> --filter run=<id> --filter channel=<name>. Narrows results without changing ranking.",
+        },
+        "include-proposed": {
+            type: "boolean",
+            description: 'Include entries with quality:"proposed" in the result set. Excluded by default (v1 spec §4.2).',
+            default: false,
+        },
+        belief: {
+            type: "string",
+            description: "Memory belief filter: all|current|historical. current keeps active memory beliefs; historical keeps contradicted/superseded/archived memory beliefs.",
+            default: "all",
+        },
+        format: { type: "string", description: "Output format (json|jsonl|text|yaml)" },
+        detail: { type: "string", description: "Detail level (brief|normal|full)" },
+        "no-project-context": {
+            type: "boolean",
+            description: "Disable the automatic project-context ranking boost (also disabled by AKM_DISABLE_PROJECT_CONTEXT=1).",
+            default: false,
+        },
+    },
+    async run({ args }) {
+        const query = (args.query ?? "").trim();
+        if (!query) {
+            throw new UsageError('A search query is required. Usage: akm search "<query>" [--type <type>] [--limit <n>]', "MISSING_REQUIRED_ARGUMENT", 'Pass a query like `akm search "docker"` or `akm search "code review" --type skill`.');
+        }
+        const type = args.type;
+        const limit = parsePositiveIntFlag(args.limit ?? undefined);
+        const source = parseSearchSource(args.source);
+        // Repeatable; citty exposes only the last `--filter` value, so read all
+        // occurrences directly from argv (same pattern as `--tag`).
+        const filterTokens = parseAllFlagValues("--filter");
+        const filters = parseScopeFilterFlags(filterTokens, "--filter");
+        const includeProposed = args["include-proposed"] === true;
+        const belief = parseBeliefFilterMode(typeof args.belief === "string" ? args.belief : undefined);
+        const noProjectContext = getHyphenatedBoolean(args, "no-project-context");
+        // --no-project-context sets env so searchDatabase picks it up without
+        // threading the flag through the entire call stack.
+        if (noProjectContext)
+            process.env.AKM_DISABLE_PROJECT_CONTEXT = "1";
+        const result = await akmSearch({
+            query,
+            type,
+            limit,
+            source,
+            filters,
+            includeProposed,
+            belief,
+            eventSource: resolveEventSource(),
+        });
+        output("search", result);
+    },
+});
+export const curateCommand = defineJsonCommand({
+    meta: { name: "curate", description: "Curate the best matching assets for a task or prompt" },
+    args: {
+        // Optional in citty so run() is invoked when omitted; we re-validate
+        // below to surface a structured UsageError (exit 2) instead of citty's
+        // default help-banner exit-0.
+        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.",
+        },
+        limit: { type: "string", description: "Maximum number of curated results", default: "4" },
+        source: { type: "string", description: "Search source (stash|registry|both)", default: "stash" },
+        // Output-contract flags. The active values are read from the process-level
+        // singleton (parsed from argv at startup); these declarations make them
+        // visible in `akm curate --help` and document the supported axes.
+        format: { type: "string", description: "Output format (json|jsonl|text|yaml)" },
+        detail: { type: "string", description: "Detail level (brief|normal|full)" },
+        shape: { type: "string", description: "Output projection (human|agent)" },
+    },
+    async run({ args }) {
+        if (!args.query || !String(args.query).trim()) {
+            throw new UsageError('A curate query is required. Usage: akm curate "<task or prompt>" [--type <type>] [--limit <n>]', "MISSING_REQUIRED_ARGUMENT", 'Describe the task you want assets for, e.g. `akm curate "deploy to prod"`.');
+        }
+        const type = args.type;
+        const limitParsed = parsePositiveIntFlag(args.limit ?? undefined);
+        const limit = limitParsed && limitParsed > 0 ? limitParsed : 4;
+        const source = parseSearchSource(args.source ?? "stash");
+        const curated = await akmCurate({ query: args.query, type, limit, source });
+        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')",
+    },
+    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"`.',
+            required: true,
+        },
+        format: { type: "string", description: "Output format (json|jsonl|text|yaml)" },
+        detail: { type: "string", description: "Detail level (brief|normal|full)" },
+        shape: { type: "string", description: "Output projection (human|agent|summary)" },
+        scope: {
+            type: "string",
+            description: "Scope filter (repeatable): --scope user=<id> --scope agent=<id> --scope run=<id> --scope channel=<name>. Narrows resolution to assets whose frontmatter scope matches.",
+        },
+    },
+    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`.)
+        if (!parseMetaRef(args.ref))
+            parseAssetRef(args.ref);
+        // The knowledge-view positional syntax (`akm show knowledge:foo section "Auth"`)
+        // is rewritten to `--akmView` / `--akmHeading` / `--akmStart` / `--akmEnd`
+        // by `normalizeShowArgv` before citty parses argv. We read those values
+        // directly via `parseFlagValue` so the flags don't surface as user-facing
+        // options in `akm show --help`.
+        const akmView = parseFlagValue(process.argv, "--akmView");
+        const akmHeading = parseFlagValue(process.argv, "--akmHeading");
+        const akmStart = parseFlagValue(process.argv, "--akmStart");
+        const akmEnd = parseFlagValue(process.argv, "--akmEnd");
+        let view;
+        if (akmView) {
+            switch (akmView) {
+                case "section":
+                    view = { mode: "section", heading: akmHeading ?? "" };
+                    break;
+                case "lines":
+                    view = {
+                        mode: "lines",
+                        start: Number(akmStart ?? "1"),
+                        end: akmEnd ? parseInt(akmEnd, 10) : Number.MAX_SAFE_INTEGER,
+                    };
+                    break;
+                case "toc":
+                case "frontmatter":
+                case "full":
+                    view = { mode: akmView };
+                    break;
+                default:
+                    throw new UsageError(`Unknown view mode: ${akmView}. Expected one of: full|toc|frontmatter|section|lines`);
+            }
+        }
+        const cliShape = getOutputMode().shape;
+        const explicitDetail = parseFlagValue(process.argv, "--detail");
+        // `--shape summary` selects the compact metadata projection for show
+        // (the legacy `--detail summary` spelling still maps here via the
+        // back-compat path in resolveOutputMode). `--detail brief` forces the
+        // brief response regardless of shape.
+        const showDetail = explicitDetail === "brief" ? "brief" : cliShape === "summary" ? "summary" : undefined;
+        // `--scope` is repeatable — citty only exposes the last value, so read
+        // every occurrence directly from argv (same pattern as `--filter`).
+        const scopeTokens = parseAllFlagValues("--scope");
+        const scope = parseScopeFilterFlags(scopeTokens, "--scope");
+        const result = await akmShowUnified({
+            ref: args.ref,
+            view,
+            detail: showDetail,
+            scope,
+            eventSource: resolveEventSource(),
+        });
+        output("show", result);
+    },
+});

package/dist/commands/{search.js → read/search.js}

@@ -11,19 +11,20 @@
  * a registry search behind `--source registry|both`, and log a usage event.
  * Provider `search()` methods do not exist.
  */
-import { loadConfig } from "../core/config";
-import { rethrowIfTestIsolationError, UsageError } from "../core/errors";
-import { appendEvent } from "../core/events";
-import { isTransientStashPath } from "../core/paths";
-import { bumpUtilityScoresBatch, closeDatabase, openExistingDatabase } from "../indexer/db";
-import { searchLocal } from "../indexer/db-search";
-import { resolveSourceEntries } from "../indexer/search-source";
-import { getCurrentWorkflowScopeKey } from "../workflows/scope-key";
+import { 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 { searchLocal } from "../../indexer/search/db-search.js";
+import { resolveSourceEntries } from "../../indexer/search/search-source.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";
-import { insertUsageEvent } from "../indexer/usage-events";
-import { searchRegistry } from "./registry-search";
+import "../../sources/providers/index.js";
+import { insertUsageEvent } from "../../indexer/usage/usage-events.js";
+import { withIndexDb } from "../../storage/repositories/index-db.js";
+import { searchRegistry } from "./registry-search.js";
 const DEFAULT_LIMIT = 20;
 export async function akmSearch(input) {
     const t0 = Date.now();
@@ -78,7 +79,7 @@ export async function akmSearch(input) {
             timing: { totalMs: Date.now() - t0 },
         };
         if (!input.skipLogging)
-            logSearchEvent(query, response, undefined, undefined, input.eventSource);
+            logSearchEvent(query, response, undefined, input.eventSource);
         return response;
     }
     // Primary stash directory — used for DB path lookups and as the default
@@ -122,7 +123,7 @@ export async function akmSearch(input) {
             timing: { totalMs: Date.now() - t0, rankMs: localResult?.rankMs, embedMs: localResult?.embedMs },
         };
         if (!input.skipLogging)
-            logSearchEvent(query, response, undefined, localResult?.mode ?? "keyword", input.eventSource);
+            logSearchEvent(query, response, localResult?.mode ?? "keyword", input.eventSource);
         return response;
     }
     const registryHits = (registryResult?.hits ?? []).map((hit) => {
@@ -157,7 +158,7 @@ export async function akmSearch(input) {
             timing: { totalMs: Date.now() - t0 },
         };
         if (!input.skipLogging)
-            logSearchEvent(query, response, undefined, undefined, input.eventSource);
+            logSearchEvent(query, response, undefined, input.eventSource);
         return response;
     }
     // source === "both"
@@ -175,7 +176,7 @@ export async function akmSearch(input) {
         timing: { totalMs: Date.now() - t0 },
     };
     if (!input.skipLogging)
-        logSearchEvent(query, response, undefined, undefined, input.eventSource);
+        logSearchEvent(query, response, undefined, input.eventSource);
     return response;
 }
 /**
@@ -183,12 +184,11 @@ export async function akmSearch(input) {
  */
 function resolveEntryIds(db, hits) {
     const results = [];
-    const stmt = db.prepare("SELECT id FROM entries WHERE file_path = ? LIMIT 1");
     for (const hit of hits) {
         try {
-            const row = stmt.get(hit.path);
-            if (row)
-                results.push({ entryId: row.id, ref: hit.ref });
+            const entryId = getEntryIdByFilePath(db, hit.path);
+            if (entryId !== undefined)
+                results.push({ entryId, ref: hit.ref });
         }
         catch {
             /* skip unresolvable */
@@ -211,7 +211,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, existingDb, mode = "keyword", eventSource = "user") {
+function logSearchEvent(query, response, mode = "keyword", eventSource = "user") {
     // 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");
@@ -223,8 +223,7 @@ function logSearchEvent(query, response, existingDb, mode = "keyword", eventSour
         metadata: { query, hitCount: stashHits.length, resultRefs: allResultRefs, mode },
     });
     try {
-        const db = existingDb ?? openExistingDatabase();
-        try {
+        withIndexDb((db) => {
             const resolved = resolveEntryIds(db, stashHits.slice(0, 50));
             for (const { entryId, ref } of resolved) {
                 insertUsageEvent(db, {
@@ -266,11 +265,7 @@ function logSearchEvent(query, response, existingDb, mode = "keyword", eventSour
                 }),
                 source: eventSource,
             });
-        }
-        finally {
-            if (!existingDb)
-                closeDatabase(db);
-        }
+        });
     }
     catch (err) {
         rethrowIfTestIsolationError(err);

package/dist/commands/{show.js → read/show.js}

@@ -18,32 +18,33 @@
  */
 import fs from "node:fs";
 import path from "node:path";
-import { parseAssetRef } from "../core/asset-ref";
-import { asNonEmptyString } from "../core/common";
-import { loadConfig } from "../core/config";
-import { NotFoundError, rethrowIfTestIsolationError, UsageError } from "../core/errors";
-import { appendEvent, readEvents } from "../core/events";
-import { parseFrontmatter } from "../core/frontmatter";
-import { META_DIR, parseMetaRef, resolveMetaFilePath } from "../core/stash-meta";
-import { closeDatabase, findEntryIdByRef, openExistingDatabase } from "../indexer/db";
-import { ensureIndex } from "../indexer/ensure-index";
-import { buildFileContext, buildRenderContext, getRenderer, runMatchers } from "../indexer/file-context";
-import { listRelatedPathsForFile } from "../indexer/graph-boost";
-import { lookup } from "../indexer/indexer";
-import { resolveAssetPath } from "../indexer/path-resolver";
-import { buildEditHint, findSourceForPath, isEditable, resolveSourceEntries } from "../indexer/search-source";
-import { insertUsageEvent } from "../indexer/usage-events";
-import { resolveSourcesForOrigin } from "../registry/origin-resolve";
+import { parseAssetRef } from "../../core/asset/asset-ref.js";
+import { parseFrontmatter } from "../../core/asset/frontmatter.js";
+import { META_DIR, parseMetaRef, resolveMetaFilePath } from "../../core/asset/stash-meta.js";
+import { asNonEmptyString } from "../../core/common.js";
+import { loadConfig } from "../../core/config/config.js";
+import { NotFoundError, rethrowIfTestIsolationError, UsageError } from "../../core/errors.js";
+import { appendEvent, readEvents } from "../../core/events.js";
+import { findEntryIdByRef } from "../../indexer/db/db.js";
+import { ensureIndex } from "../../indexer/ensure-index.js";
+import { listRelatedPathsForFile } from "../../indexer/graph/graph-boost.js";
+import { lookup } from "../../indexer/indexer.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 { resolveAssetPath } from "../../indexer/walk/path-resolver.js";
+import { resolveSourcesForOrigin } from "../../registry/origin-resolve.js";
+import { withIndexDb } from "../../storage/repositories/index-db.js";
 // Eagerly import source providers to trigger self-registration.
-import "../sources/providers/index";
-import { getActiveWorkflowRun } from "../workflows/runs";
-import { getCurrentWorkflowScopeKey } from "../workflows/scope-key";
+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 { showWiki } = await import("../../wiki/wiki.js");
     const result = showWiki(stashDir, wikiName);
     return {
         type: "wiki",
@@ -59,7 +60,7 @@ async function showWikiRoot(stashDir, wikiName) {
     };
 }
 async function showWikiRootForSource(stashDir, source, wikiName) {
-    const { showWikiAtPath } = await import("../wiki/wiki.js");
+    const { showWikiAtPath } = await import("../../wiki/wiki.js");
     if (source.wikiName === wikiName) {
         const result = showWikiAtPath(wikiName, source.path);
         return {
@@ -156,7 +157,7 @@ export async function akmShowUnified(input) {
     }
     // Count prior shows of this ref before logging the current one.
     const priorShowCount = recentShowCount(ref);
-    logShowEvent(ref, undefined, input.eventSource);
+    logShowEvent(ref, input.eventSource);
     if (priorShowCount >= 2) {
         // Agent has shown this same asset 3+ times — inject a loop-break hint.
         result.showLoopWarning = priorShowCount + 1;
@@ -253,7 +254,7 @@ function recentShowCount(ref) {
         return 0;
     }
 }
-function logShowEvent(ref, existingDb, eventSource = "user") {
+function logShowEvent(ref, eventSource = "user") {
     // Emit a structured event to events.jsonl so workflow-trace consumers
     // detect akm show invocations without relying on stdout scraping.
     const parsed = parseAssetRef(ref);
@@ -288,19 +289,14 @@ function logShowEvent(ref, existingDb, eventSource = "user") {
         /* fire-and-forget — select is best-effort */
     }
     try {
-        const db = existingDb ?? openExistingDatabase();
-        try {
+        withIndexDb((db) => {
             insertUsageEvent(db, {
                 event_type: "show",
                 entry_ref: ref,
                 entry_id: findEntryIdByRef(db, ref),
                 source: eventSource,
             });
-        }
-        finally {
-            if (!existingDb)
-                closeDatabase(db);
-        }
+        });
     }
     catch (err) {
         rethrowIfTestIsolationError(err);
@@ -371,20 +367,16 @@ export async function showLocal(input) {
         editable,
         ...(!editable ? { editHint: buildEditHint(assetPath, parsed.type, parsed.name, source?.registryId) } : {}),
         related: (() => {
-            let db;
             try {
-                db = openExistingDatabase();
-                const related = listRelatedPathsForFile(sourceStashDir, assetPath, 5, db);
-                return { total: related.length, hits: related };
+                return withIndexDb((db) => {
+                    const related = listRelatedPathsForFile(sourceStashDir, assetPath, 5, db);
+                    return { total: related.length, hits: related };
+                });
             }
             catch (err) {
                 rethrowIfTestIsolationError(err);
                 return { total: 0, hits: [] };
             }
-            finally {
-                if (db)
-                    closeDatabase(db);
-            }
         })(),
     };
     const activeRun = await getActiveWorkflowRun(getCurrentWorkflowScopeKey());
@@ -482,8 +474,6 @@ export function normalizeShowArgv(argv) {
     // argv[0]=bun argv[1]=script argv[2]=subcommand argv[3]=ref argv[4..]=rest
     if (argv[2] !== "show")
         return argv;
-    if (argv[3] === "proposal")
-        return argv;
     if (argv.includes("--view") || argv.includes("--heading") || argv.includes("--start") || argv.includes("--end")) {
         throw new UsageError('Legacy show flags are no longer supported. Use positional syntax like `akm show knowledge:guide toc` or `akm show knowledge:guide section "Auth"`.');
     }
@@ -494,11 +484,7 @@ export function normalizeShowArgv(argv) {
     const showArgs = [];
     for (let i = 0; i < rest.length; i++) {
         const arg = rest[i];
-        if (arg === "--quiet" ||
-            arg === "-q" ||
-            arg === "--verbose" ||
-            arg === "--for-agent" ||
-            arg === "--for-agent=true") {
+        if (arg === "--quiet" || arg === "-q" || arg === "--verbose") {
             globalFlags.push(arg);
             continue;
         }