akm-cli 0.6.1 → 0.7.0

package/dist/tests/e2e.test.js

@@ -0,0 +1,1419 @@
+/**
+ * End-to-end tests that replicate real-world usage of akm.
+ *
+ * Uses realistic fixtures in tests/fixtures/ representing a typical user's
+ * stash directory with scripts, skills, commands, and agents.
+ *
+ * Tests cover:
+ * - Full lifecycle: index → search → show
+ * - CLI interface via subprocess
+ * - Metadata generation and persistence
+ * - Semantic search ranking quality
+ * - Ripgrep pre-filtering
+ * - Multi-script directories with .stash.json
+ * - Graceful degradation (no index, no ripgrep)
+ * - Edge cases and error handling
+ */
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { akmSearch } from "../src/commands/search";
+import { akmShowUnified as akmShow } from "../src/commands/show";
+import { loadConfig, saveConfig } from "../src/core/config";
+import { closeDatabase, DB_VERSION, getAllEntries, getMeta, openDatabase } from "../src/indexer/db";
+import { akmIndex } from "../src/indexer/indexer";
+import { loadStashFile } from "../src/indexer/metadata";
+// ── Helpers ─────────────────────────────────────────────────────────────────
+const FIXTURES = path.join(__dirname, "fixtures");
+const CLI = path.join(__dirname, "..", "src", "cli.ts");
+function expectDefined(value) {
+    expect(value).toBeDefined();
+    if (value === undefined || value === null) {
+        throw new Error("Expected value to be defined");
+    }
+    return value;
+}
+function isLocalHit(hit) {
+    return hit.type !== "registry";
+}
+function copyFixturesToTmp() {
+    const tmpStash = fs.mkdtempSync(path.join(os.tmpdir(), "akm-e2e-"));
+    copyDirRecursive(FIXTURES, tmpStash);
+    return tmpStash;
+}
+// `tests/fixtures/stashes/` is the shared fixture-stash tree (issue #235); it
+// must not be copied into the per-scenario e2e fixture root or its assets
+// will leak into search results.
+const E2E_FIXTURE_SKIP_AT_ROOT = new Set(["stashes"]);
+function copyDirRecursive(src, dest, depth = 0) {
+    fs.mkdirSync(dest, { recursive: true });
+    for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+        if (depth === 0 && E2E_FIXTURE_SKIP_AT_ROOT.has(entry.name))
+            continue;
+        const srcPath = path.join(src, entry.name);
+        const destPath = path.join(dest, entry.name);
+        if (entry.isDirectory()) {
+            copyDirRecursive(srcPath, destPath, depth + 1);
+        }
+        else {
+            fs.copyFileSync(srcPath, destPath);
+        }
+    }
+}
+function runCli(...args) {
+    const result = spawnSync("bun", [CLI, ...args], {
+        encoding: "utf8",
+        timeout: 30_000,
+        env: { ...process.env },
+    });
+    return {
+        stdout: result.stdout?.trim() ?? "",
+        stderr: result.stderr?.trim() ?? "",
+        exitCode: result.status ?? 1,
+    };
+}
+function parseJson(text) {
+    return JSON.parse(text);
+}
+function createEmptyStashDir(prefix) {
+    const stashDir = fs.mkdtempSync(path.join(os.tmpdir(), prefix));
+    for (const sub of ["skills", "commands", "agents", "knowledge", "scripts"]) {
+        fs.mkdirSync(path.join(stashDir, sub), { recursive: true });
+    }
+    return stashDir;
+}
+async function withMockedFetch(handler, run) {
+    const originalFetch = globalThis.fetch;
+    globalThis.fetch = (async (input) => {
+        const url = typeof input === "string" ? input : input instanceof URL ? input.toString() : input.url;
+        return handler(url);
+    });
+    try {
+        return await run();
+    }
+    finally {
+        globalThis.fetch = originalFetch;
+    }
+}
+const originalXdgCacheHome = process.env.XDG_CACHE_HOME;
+const originalXdgConfigHome = process.env.XDG_CONFIG_HOME;
+const originalAkmStashDir = process.env.AKM_STASH_DIR;
+let testCacheDir = "";
+let testConfigDir = "";
+beforeAll(async () => {
+    testCacheDir = fs.mkdtempSync(path.join(os.tmpdir(), "akm-e2e-cache-"));
+    testConfigDir = fs.mkdtempSync(path.join(os.tmpdir(), "akm-e2e-config-"));
+    process.env.XDG_CACHE_HOME = testCacheDir;
+    process.env.XDG_CONFIG_HOME = testConfigDir;
+});
+beforeEach(() => {
+    // Re-create per-test config dir for isolation (describe-level beforeAll
+    // already set XDG_CONFIG_HOME so akmIndex doesn't read real user config)
+    if (testConfigDir && fs.existsSync(testConfigDir)) {
+        fs.rmSync(testConfigDir, { recursive: true, force: true });
+    }
+    testConfigDir = fs.mkdtempSync(path.join(os.tmpdir(), "akm-e2e-config-"));
+    process.env.XDG_CONFIG_HOME = testConfigDir;
+});
+afterAll(() => {
+    if (originalXdgCacheHome === undefined) {
+        delete process.env.XDG_CACHE_HOME;
+    }
+    else {
+        process.env.XDG_CACHE_HOME = originalXdgCacheHome;
+    }
+    if (originalXdgConfigHome === undefined) {
+        delete process.env.XDG_CONFIG_HOME;
+    }
+    else {
+        process.env.XDG_CONFIG_HOME = originalXdgConfigHome;
+    }
+    if (originalAkmStashDir === undefined) {
+        delete process.env.AKM_STASH_DIR;
+    }
+    else {
+        process.env.AKM_STASH_DIR = originalAkmStashDir;
+    }
+    if (testCacheDir) {
+        fs.rmSync(testCacheDir, { recursive: true, force: true });
+        testCacheDir = "";
+    }
+    if (testConfigDir) {
+        fs.rmSync(testConfigDir, { recursive: true, force: true });
+        testConfigDir = "";
+    }
+});
+afterEach(() => {
+    // Don't restore XDG_CONFIG_HOME here — it's managed by beforeAll/afterAll.
+    // Restoring it between tests would expose real user config to describe-level
+    // beforeAll hooks that run between describe blocks.
+    if (testConfigDir) {
+        fs.rmSync(testConfigDir, { recursive: true, force: true });
+        testConfigDir = "";
+    }
+});
+// ═══════════════════════════════════════════════════════════════════════════
+// Scenario 1: Full lifecycle — user sets up stash, indexes, searches, runs
+// ═══════════════════════════════════════════════════════════════════════════
+describe("Scenario: Full lifecycle (index → search → show)", () => {
+    let stashDir;
+    let scenarioCacheDir;
+    beforeAll(async () => {
+        stashDir = copyFixturesToTmp();
+        scenarioCacheDir = fs.mkdtempSync(path.join(os.tmpdir(), "akm-e2e-cache-s1-"));
+        process.env.AKM_STASH_DIR = stashDir;
+        process.env.XDG_CACHE_HOME = scenarioCacheDir;
+    });
+    beforeEach(() => {
+        process.env.AKM_STASH_DIR = stashDir;
+        process.env.XDG_CACHE_HOME = scenarioCacheDir;
+    });
+    afterAll(() => {
+        fs.rmSync(stashDir, { recursive: true, force: true });
+        fs.rmSync(scenarioCacheDir, { recursive: true, force: true });
+    });
+    test("search works without index (substring fallback)", async () => {
+        const result = await akmSearch({ query: "deploy", type: "script" });
+        expect(result.hits.length).toBeGreaterThan(0);
+        expect(result.hits.some((h) => h.name.includes("deploy"))).toBe(true);
+        // Substring mode computes a relevance score
+        expect(result.hits[0].score).toBeGreaterThan(0);
+        expect(result.hits[0].score).toBeLessThanOrEqual(1);
+    });
+    test("index generates metadata and builds search index", async () => {
+        const result = await akmIndex({ stashDir });
+        expect(result.stashDir).toBe(stashDir);
+        expect(result.totalEntries).toBeGreaterThanOrEqual(8);
+        expect(result.generatedMetadata).toBeGreaterThan(0);
+        expect(fs.existsSync(result.indexPath)).toBe(true);
+    });
+    test("index generates metadata in database for directories that lack .stash.json", async () => {
+        // git/ directory had no .stash.json — metadata generated in DB only
+        expect(fs.existsSync(path.join(stashDir, "scripts", "git", ".stash.json"))).toBe(false);
+        const db = openDatabase();
+        const entries = getAllEntries(db, "script");
+        const gitEntries = entries.filter((e) => e.dirPath.includes(path.join("scripts", "git")));
+        expect(gitEntries.length).toBeGreaterThanOrEqual(2);
+        // Each generated entry should be marked
+        for (const e of gitEntries) {
+            expect(e.entry.quality).toBe("generated");
+            expect(e.entry.type).toBe("script");
+            expect(e.entry.filename).toBeTruthy();
+        }
+        closeDatabase(db);
+    });
+    test("index preserves hand-written .stash.json (docker/ has intent fields)", async () => {
+        const dockerStash = loadStashFile(path.join(stashDir, "scripts", "docker"));
+        expect(dockerStash).not.toBeNull();
+        expect(dockerStash?.entries.length).toBe(2);
+        // These were hand-written, should NOT have generated flag
+        expect(dockerStash?.entries[0].quality).not.toBe("generated");
+        expect(dockerStash?.entries[0].intent).toBeDefined();
+        expect(dockerStash?.entries[0].intent?.when).toBeTruthy();
+    });
+    test("index extracts description from code comments", async () => {
+        const db = openDatabase();
+        const entries = getAllEntries(db, "script");
+        const diffEntry = entries.find((e) => e.entry.name.includes("summarize-diff"));
+        expect(diffEntry).toBeDefined();
+        // Should have extracted the JSDoc comment as description
+        expect(diffEntry?.entry.description).toBeTruthy();
+        expect(diffEntry?.entry.description?.toLowerCase()).toContain("git diff");
+        closeDatabase(db);
+    });
+    test("index extracts metadata from package.json", async () => {
+        const db = openDatabase();
+        const entries = getAllEntries(db, "script");
+        const lintEntry = entries.find((e) => e.entry.name.includes("eslint-check"));
+        expect(lintEntry).toBeDefined();
+        // package.json had description and keywords
+        expect(lintEntry?.entry.description).toContain("ESLint");
+        expect(lintEntry?.entry.tags).toContain("eslint");
+        closeDatabase(db);
+    });
+    test("search with index returns scored results with descriptions", async () => {
+        const result = await akmSearch({ query: "docker build image", type: "any" });
+        expect(result.schemaVersion).toBe(1);
+        expect(result.hits.length).toBeGreaterThan(0);
+        // Docker-build should be ranked first
+        const topHit = result.hits[0];
+        expect(topHit.name).toContain("docker");
+        expect(topHit.score).toBeDefined();
+        expect(topHit.score).toBeGreaterThan(0);
+        expect(topHit.description).toBeTruthy();
+    });
+    test.skipIf(!!process.env.CI)("search ranks keyword-relevant results higher (FTS-only)", async () => {
+        // NOTE: This test uses FTS keyword matching (BM25), not semantic/vector search.
+        const result = await akmSearch({ query: "summarize commit changes", type: "any" });
+        expect(result.hits.length).toBeGreaterThan(0);
+        // Git scripts should rank higher than docker scripts for this query
+        const topNames = result.hits.slice(0, 5).map((h) => h.name.toLowerCase());
+        const hasGitRelated = topNames.some((n) => n.includes("git") || n.includes("diff") || n.includes("commit") || n.includes("summarize"));
+        expect(hasGitRelated).toBe(true);
+    });
+    test("search type filter restricts results to that type", async () => {
+        const skillResult = await akmSearch({ query: "review", type: "skill" });
+        expect(skillResult.hits.every((h) => h.type === "skill")).toBe(true);
+        const cmdResult = await akmSearch({ query: "", type: "command" });
+        expect(cmdResult.hits.every((h) => h.type === "command")).toBe(true);
+    });
+    test("search with empty query returns all entries of that type", async () => {
+        const result = await akmSearch({ query: "", type: "agent" });
+        expect(result.hits.length).toBe(2); // architect.md and debugger.md
+    });
+    test("search respects limit parameter", async () => {
+        const result = await akmSearch({ query: "", type: "any", limit: 3 });
+        expect(result.hits.length).toBeLessThanOrEqual(3);
+    });
+    test("show a script returns run", async () => {
+        const searchResult = await akmSearch({ query: "deploy", type: "script" });
+        const deployHit = searchResult.hits.find((h) => isLocalHit(h) && h.name.includes("deploy"));
+        const resolvedDeployHit = expectDefined(deployHit);
+        const openResult = await akmShow({ ref: expectDefined(resolvedDeployHit.ref) });
+        expect(openResult.type).toBe("script");
+        expect(openResult.run).toBeTruthy();
+        expect(openResult.run).toContain("bash");
+    });
+    test("show a skill returns full SKILL.md content", async () => {
+        const openResult = await akmShow({ ref: "skill:code-review" });
+        expect(openResult.type).toBe("skill");
+        expect(openResult.content).toContain("Code Review Skill");
+        expect(openResult.content).toContain("security vulnerabilities");
+    });
+    test("show a command returns template and description", async () => {
+        const openResult = await akmShow({ ref: "command:release.md" });
+        expect(openResult.type).toBe("command");
+        expect(openResult.description).toBe("Create a new release with changelog and version bump");
+        expect(openResult.template).toContain("npm version");
+    });
+    test("show an agent returns prompt, description, model hint, and tool policy", async () => {
+        const openResult = await akmShow({ ref: "agent:architect.md" });
+        expect(openResult.type).toBe("agent");
+        expect(openResult.description).toContain("architect");
+        expect(openResult.prompt).toContain("software architect");
+        expect(openResult.modelHint).toBe("claude-sonnet-4-20250514");
+        expect(openResult.toolPolicy).toEqual({ allow: "Read,Glob,Grep" });
+    });
+});
+// ═══════════════════════════════════════════════════════════════════════════
+// Scenario 2: Agent workflow — discover capability for a natural language task
+// ═══════════════════════════════════════════════════════════════════════════
+describe("Scenario: Agent discovers capabilities for task", () => {
+    let stashDir;
+    let scenarioCacheDir;
+    beforeAll(async () => {
+        stashDir = copyFixturesToTmp();
+        scenarioCacheDir = fs.mkdtempSync(path.join(os.tmpdir(), "akm-e2e-cache-s2-"));
+        process.env.AKM_STASH_DIR = stashDir;
+        process.env.XDG_CACHE_HOME = scenarioCacheDir;
+        await akmIndex({ stashDir });
+    });
+    beforeEach(() => {
+        process.env.AKM_STASH_DIR = stashDir;
+        process.env.XDG_CACHE_HOME = scenarioCacheDir;
+    });
+    afterAll(() => {
+        fs.rmSync(stashDir, { recursive: true, force: true });
+        fs.rmSync(scenarioCacheDir, { recursive: true, force: true });
+    });
+    test.skipIf(!!process.env.CI)("agent asks 'set up local dev environment' → docker-compose ranks high", async () => {
+        const result = await akmSearch({ query: "set up local development environment" });
+        const names = result.hits.map((h) => h.name.toLowerCase());
+        // Docker compose should appear because its intent says "start local development services"
+        expect(names.some((n) => n.includes("compose") || n.includes("docker"))).toBe(true);
+    });
+    test("agent asks 'check code quality' → lint script ranks high", async () => {
+        const result = await akmSearch({ query: "check code quality style" });
+        expect(result.hits.length).toBeGreaterThan(0);
+        const names = result.hits.map((h) => h.name.toLowerCase());
+        expect(names.some((n) => n.includes("lint") || n.includes("eslint"))).toBe(true);
+    });
+    test.skipIf(!!process.env.CI)("agent asks 'review my pull request' → code-review skill found", async () => {
+        const result = await akmSearch({ query: "review pull request code changes" });
+        expect(result.hits.length).toBeGreaterThan(0);
+        // Skill ref contains "code-review" (directory name), even though display name is "SKILL"
+        expect(result.hits.some((h) => (isLocalHit(h) && h.ref.includes("code-review")) || h.description?.toLowerCase().includes("review"))).toBe(true);
+    });
+    test.skipIf(!!process.env.CI)("agent asks 'help me design the system' → architect agent found", async () => {
+        const result = await akmSearch({ query: "system design architecture" });
+        expect(result.hits.length).toBeGreaterThan(0);
+        expect(result.hits.some((h) => h.name.includes("architect"))).toBe(true);
+    });
+    test("agent workflow: search → show (end-to-end)", async () => {
+        // Step 1: Agent searches for a script to run tests
+        const searchResult = await akmSearch({ query: "run tests" });
+        expect(searchResult.hits.length).toBeGreaterThan(0);
+        const testScript = searchResult.hits.find((h) => isLocalHit(h) && h.type === "script" && h.name.includes("test"));
+        const resolvedTestScript = expectDefined(testScript);
+        // Step 2: Agent reads the script to get run command for host execution
+        const showResult = await akmShow({ ref: expectDefined(resolvedTestScript.ref) });
+        expect(showResult.run).toBeTruthy();
+    });
+});
+describe("Scenario: Mixed local + registry search compatibility", () => {
+    let stashDir;
+    let scenarioCacheDir;
+    beforeAll(async () => {
+        stashDir = copyFixturesToTmp();
+        scenarioCacheDir = fs.mkdtempSync(path.join(os.tmpdir(), "akm-e2e-cache-s2b-"));
+        process.env.AKM_STASH_DIR = stashDir;
+        process.env.XDG_CACHE_HOME = scenarioCacheDir;
+        await akmIndex({ stashDir });
+    });
+    // Isolate registry index cache per test so mocked fetch responses
+    // aren't shadowed by a cached index from a previous test.
+    // We use a per-test cache dir but copy the index DB so local search still works.
+    beforeEach(() => {
+        process.env.AKM_STASH_DIR = stashDir;
+        const perTestCache = fs.mkdtempSync(path.join(os.tmpdir(), "akm-e2e-reg-cache-"));
+        // Copy the scenario's index DB so local search still finds it
+        const srcDb = path.join(scenarioCacheDir, "akm", "index.db");
+        const destDir = path.join(perTestCache, "akm");
+        if (fs.existsSync(srcDb)) {
+            fs.mkdirSync(destDir, { recursive: true });
+            fs.copyFileSync(srcDb, path.join(destDir, "index.db"));
+        }
+        process.env.XDG_CACHE_HOME = perTestCache;
+    });
+    afterEach(() => {
+        const tmpCache = process.env.XDG_CACHE_HOME;
+        if (tmpCache && tmpCache !== scenarioCacheDir) {
+            fs.rmSync(tmpCache, { recursive: true, force: true });
+        }
+    });
+    afterAll(() => {
+        fs.rmSync(stashDir, { recursive: true, force: true });
+        fs.rmSync(scenarioCacheDir, { recursive: true, force: true });
+    });
+    test("local source does not call registry providers", async () => {
+        const result = await withMockedFetch(() => {
+            throw new Error("fetch should not be called for source=local");
+        }, () => akmSearch({ query: "docker", source: "local" }));
+        expect(result.source).toBe("stash");
+        expect(result.hits.length).toBeGreaterThan(0);
+        expect(result.hits.every((h) => h.type !== "registry")).toBe(true);
+    });
+    test("registry source returns install guidance", async () => {
+        const registryIndex = {
+            version: 3,
+            updatedAt: "2026-03-09T00:00:00Z",
+            stashes: [
+                {
+                    id: "npm:@scope/stash",
+                    name: "@scope/stash",
+                    description: "Example registry stash",
+                    ref: "@scope/stash",
+                    source: "npm",
+                    homepage: "https://www.npmjs.com/package/@scope/stash",
+                    tags: ["stash"],
+                    latestVersion: "1.2.3",
+                },
+                {
+                    id: "github:itlackey/example-stash",
+                    name: "Example Stash",
+                    description: "Example GitHub stash",
+                    ref: "itlackey/example-stash",
+                    source: "github",
+                    homepage: "https://github.com/itlackey/example-stash",
+                    tags: ["stash"],
+                },
+            ],
+        };
+        const result = await withMockedFetch(() => new Response(JSON.stringify(registryIndex), { status: 200 }), () => akmSearch({ query: "stash", source: "registry" }));
+        expect(result.source).toBe("registry");
+        expect(result.hits.length).toBe(0);
+        expect(result.registryHits).toBeDefined();
+        expect(result.registryHits?.length).toBeGreaterThan(0);
+        const registryHits = result.registryHits ?? [];
+        for (const hit of registryHits) {
+            expect(hit.type).toBe("registry");
+            expect(hit.action?.startsWith("akm add ")).toBe(true);
+            expect(hit.id.length).toBeGreaterThan(0);
+        }
+    });
+    test("both source includes local and registry hits", async () => {
+        const registryIndex = {
+            version: 3,
+            updatedAt: "2026-03-09T00:00:00Z",
+            stashes: [
+                {
+                    id: "npm:docker-stash",
+                    name: "docker-stash",
+                    description: "Registry docker helper",
+                    ref: "docker-stash",
+                    source: "npm",
+                    tags: ["docker"],
+                    latestVersion: "0.1.0",
+                },
+            ],
+        };
+        const result = await withMockedFetch(() => new Response(JSON.stringify(registryIndex), { status: 200 }), () => akmSearch({ query: "docker", source: "both", limit: 10 }));
+        expect(result.source).toBe("both");
+        expect(result.hits.some((h) => h.type !== "registry")).toBe(true);
+        expect(result.registryHits).toBeDefined();
+        expect(result.registryHits?.length).toBeGreaterThan(0);
+    });
+});
+// ═══════════════════════════════════════════════════════════════════════════
+// Scenario 3: CLI interface — real subprocess execution
+// ═══════════════════════════════════════════════════════════════════════════
+describe("Scenario: CLI subprocess execution", () => {
+    let stashDir;
+    let scenarioCacheDir;
+    beforeAll(async () => {
+        stashDir = copyFixturesToTmp();
+        scenarioCacheDir = fs.mkdtempSync(path.join(os.tmpdir(), "akm-e2e-cache-s3-"));
+        process.env.AKM_STASH_DIR = stashDir;
+        process.env.XDG_CACHE_HOME = scenarioCacheDir;
+        await akmIndex({ stashDir });
+    });
+    beforeEach(() => {
+        process.env.AKM_STASH_DIR = stashDir;
+        process.env.XDG_CACHE_HOME = scenarioCacheDir;
+    });
+    afterAll(() => {
+        fs.rmSync(stashDir, { recursive: true, force: true });
+        fs.rmSync(scenarioCacheDir, { recursive: true, force: true });
+    });
+    test("cli: akm search returns JSON with hits", async () => {
+        const result = runCli("search", "docker");
+        expect(result.exitCode).toBe(0);
+        const json = parseJson(result.stdout);
+        expect(json.hits).toBeInstanceOf(Array);
+        expect(json.hits.length).toBeGreaterThan(0);
+        expect(json.stashDir).toBeUndefined();
+        expect(json.hits[0].name).toBeTruthy();
+        expect(json.hits[0].action).toBeTruthy();
+    });
+    test("cli: akm search --type script filters by type", async () => {
+        const result = runCli("search", "deploy", "--type", "script");
+        expect(result.exitCode).toBe(0);
+        const json = parseJson(result.stdout);
+        expect(json.hits.every((h) => h.type === "script")).toBe(true);
+    });
+    test("cli: akm search --type knowledge filters by type", async () => {
+        const result = runCli("search", "guide", "--type", "knowledge");
+        expect(result.exitCode).toBe(0);
+        const json = parseJson(result.stdout);
+        expect(json.hits.length).toBeGreaterThan(0);
+        expect(json.hits.every((h) => h.type === "knowledge")).toBe(true);
+    });
+    // Issue 9: empty query must list all assets rather than throwing UsageError.
+    // The CLI contract (--help text) promises omitting the query returns all
+    // indexed assets. The akmSearch function handles empty queries end-to-end
+    // via getAllEntries (DB path) and the substring-fallback's query-less branch.
+    test("cli: akm search with no query lists all assets (empty-query listing)", async () => {
+        const result = runCli("search");
+        expect(result.exitCode).toBe(0);
+        const json = parseJson(result.stdout);
+        expect(json.hits).toBeInstanceOf(Array);
+        expect(json.hits.length).toBeGreaterThan(0);
+        // Brief output: ref is NOT present (only full/agent levels include ref)
+        expect(json.hits.every((h) => h.type !== undefined)).toBe(true);
+        expect(json.hits.every((h) => h.name !== undefined)).toBe(true);
+    });
+    test("cli: akm search with no query and --type filters by type", async () => {
+        const result = runCli("search", "--type", "skill");
+        expect(result.exitCode).toBe(0);
+        const json = parseJson(result.stdout);
+        expect(json.hits).toBeInstanceOf(Array);
+        expect(json.hits.every((h) => h.type === "skill")).toBe(true);
+    });
+    test("cli: akm search --limit 2 respects limit", async () => {
+        const result = runCli("search", "docker", "--limit", "2");
+        expect(result.exitCode).toBe(0);
+        const json = parseJson(result.stdout);
+        expect(json.hits.length).toBeLessThanOrEqual(2);
+    });
+    test("cli: akm search defaults to brief JSON output", async () => {
+        const result = runCli("search", "docker", "--type", "script");
+        expect(result.exitCode).toBe(0);
+        const json = parseJson(result.stdout);
+        expect(json.source).toBeUndefined();
+        expect(json.timing).toBeUndefined();
+        // REC-03: ref is now included at brief detail so agents can run `akm show <ref>`
+        expect(json.hits.every((h) => h.ref !== undefined)).toBe(true);
+        expect(json.hits.every((h) => h.type !== undefined)).toBe(true);
+        expect(json.hits.every((h) => h.name !== undefined)).toBe(true);
+        expect(json.hits.every((h) => h.action !== undefined)).toBe(true);
+    });
+    test("cli: akm search default source is stash", async () => {
+        const result = runCli("search", "docker", "--detail", "full");
+        expect(result.exitCode).toBe(0);
+        const json = parseJson(result.stdout);
+        expect(json.source).toBe("stash");
+        expect(json.hits.every((h) => h.type !== "registry")).toBe(true);
+    });
+    test("cli: akm search --detail normal includes score and description", async () => {
+        const result = runCli("search", "docker", "--type", "script", "--detail", "normal");
+        expect(result.exitCode).toBe(0);
+        const json = parseJson(result.stdout);
+        expect(json.hits.some((h) => h.score !== undefined)).toBe(true);
+        expect(json.hits.some((h) => h.action !== undefined)).toBe(true);
+    });
+    test("cli: akm search --detail full includes timing and whyMatched", async () => {
+        const result = runCli("search", "docker", "--detail", "full");
+        expect(result.exitCode).toBe(0);
+        const json = parseJson(result.stdout);
+        expect(json.timing).toBeDefined();
+        expect(json.hits.every((h) => h.whyMatched !== undefined)).toBe(true);
+    });
+    test("cli: akm search --format yaml returns valid YAML output", async () => {
+        const result = spawnSync("bun", [CLI, "search", "docker", "--format", "yaml"], {
+            encoding: "utf8",
+            timeout: 30_000,
+            env: { ...process.env },
+        });
+        expect(result.status).toBe(0);
+        // Output must be YAML (unquoted keys like "hits:"), not JSON (quoted keys like '"hits"')
+        const hasYaml = result.stdout.includes("hits:") && !result.stdout.includes('"hits"');
+        expect(hasYaml).toBe(true);
+        expect(result.stdout).toContain("docker");
+        // Should not contain the fallback warning
+        expect(result.stderr).not.toContain("YAML output not available");
+    });
+    test("cli: akm show --format text includes execution fields", async () => {
+        const result = spawnSync("bun", [CLI, "show", "command:release.md", "--format", "text"], {
+            encoding: "utf8",
+            timeout: 30_000,
+            env: { ...process.env },
+        });
+        expect(result.status).toBe(0);
+        expect(result.stdout).toContain("# command: release");
+        expect(result.stdout).toContain("description:");
+        expect(result.stdout).toContain("Create a new release");
+        expect(result.stdout).toContain("npm version");
+    });
+    test("cli: akm search --format invalid value fails with clear error", async () => {
+        const result = runCli("search", "docker", "--format", "xml");
+        expect(result.exitCode).not.toBe(0);
+        const output = result.stdout + result.stderr;
+        expect(output).toContain("Invalid value for --format: xml. Expected one of: json|yaml|text");
+    });
+    test("cli: akm search --detail invalid value fails with clear error", async () => {
+        const result = runCli("search", "docker", "--detail", "max");
+        expect(result.exitCode).not.toBe(0);
+        const output = result.stdout + result.stderr;
+        expect(output).toContain("Invalid value for --detail: max. Expected one of: brief|normal|full");
+    });
+    test("cli: akm search --source invalid value fails with clear error", async () => {
+        const result = runCli("search", "docker", "--source", "bad");
+        expect(result.exitCode).not.toBe(0);
+        const output = result.stdout + result.stderr;
+        expect(output).toContain("Invalid value for --source: bad. Expected one of: stash|registry|both");
+    });
+    test("cli: akm search default output excludes full-detail fields", async () => {
+        const result = runCli("search", "docker");
+        expect(result.exitCode).toBe(0);
+        const json = parseJson(result.stdout);
+        expect(json.hits.length).toBeGreaterThan(0);
+        for (const hit of json.hits) {
+            expect(hit.whyMatched).toBeUndefined();
+            expect(hit.editable).toBeUndefined();
+            expect(hit.editHint).toBeUndefined();
+        }
+        expect(json.timing).toBeUndefined();
+    });
+    test("cli: akm show returns asset content", async () => {
+        const result = runCli("show", "skill:code-review");
+        expect(result.exitCode).toBe(0);
+        const json = parseJson(result.stdout);
+        expect(json.type).toBe("skill");
+        expect(json.content).toContain("Code Review Skill");
+        // QA #7: path is now always included in the JSON shape (not just --detail full)
+        expect(json.path).toBeDefined();
+    });
+    test("cli: akm show --detail full includes schemaVersion and path", async () => {
+        const result = runCli("show", "command:release.md", "--detail", "full");
+        expect(result.exitCode).toBe(0);
+        const json = parseJson(result.stdout);
+        expect(json.type).toBe("command");
+        expect(json.schemaVersion).toBe(1);
+        expect(json.path).toBeTruthy();
+    });
+    test("cli: akm show command returns template", async () => {
+        const result = runCli("show", "command:release.md");
+        expect(result.exitCode).toBe(0);
+        const json = parseJson(result.stdout);
+        expect(json.type).toBe("command");
+        expect(json.description).toBeTruthy();
+        expect(json.template).toContain("npm version");
+    });
+    test("cli: akm index builds index and reports stats", async () => {
+        const result = runCli("index");
+        expect(result.exitCode).toBe(0);
+        const json = parseJson(result.stdout);
+        expect(json.totalEntries).toBeGreaterThan(0);
+        expect(json.indexPath).toBeTruthy();
+    });
+    test("cli: akm index --full returns mode full", async () => {
+        const result = runCli("index", "--full");
+        expect(result.exitCode).toBe(0);
+        const json = parseJson(result.stdout);
+        expect(json.mode).toBe("full");
+    });
+    test("cli: akm config set/get manages llm settings via JSON", async () => {
+        const setResult = runCli("config", "set", "llm", '{"endpoint":"http://localhost:11434/v1/chat/completions","model":"llama3.2","maxTokens":256}');
+        expect(setResult.exitCode).toBe(0);
+        const getResult = runCli("config", "get", "llm");
+        expect(getResult.exitCode).toBe(0);
+        const json = parseJson(getResult.stdout);
+        expect(json).toMatchObject({
+            endpoint: "http://localhost:11434/v1/chat/completions",
+            model: "llama3.2",
+            maxTokens: 256,
+        });
+    });
+    test("cli: akm with no command prints usage", async () => {
+        const result = runCli();
+        expect(result.exitCode).not.toBe(0);
+        const output = result.stdout + result.stderr;
+        expect(output).toContain("No command specified");
+    });
+    test("cli: akm show with no ref prints error", async () => {
+        const result = runCli("show");
+        expect(result.exitCode).not.toBe(0);
+        const output = result.stdout + result.stderr;
+        expect(output).toContain("Missing required positional argument");
+    });
+});
+describe("Scenario: Registry lifecycle CLI (no network)", () => {
+    let savedStashDir;
+    beforeEach(() => {
+        savedStashDir = process.env.AKM_STASH_DIR;
+    });
+    afterEach(() => {
+        if (savedStashDir === undefined) {
+            delete process.env.AKM_STASH_DIR;
+        }
+        else {
+            process.env.AKM_STASH_DIR = savedStashDir;
+        }
+    });
+    test("cli: akm list returns empty installed set when none configured", async () => {
+        const stashDir = createEmptyStashDir("akm-e2e-registry-empty-");
+        process.env.AKM_STASH_DIR = stashDir;
+        saveConfig({ semanticSearchMode: "off" });
+        try {
+            const result = runCli("list");
+            expect(result.exitCode).toBe(0);
+            const json = parseJson(result.stdout);
+            expect(json.totalSources).toBe(0);
+            expect(json.sources).toEqual([]);
+        }
+        finally {
+            fs.rmSync(stashDir, { recursive: true, force: true });
+        }
+    });
+    test("cli: registered external wikis appear in list and wiki remove clears stale search hits", async () => {
+        const stashDir = createEmptyStashDir("akm-e2e-wiki-source-");
+        const externalWiki = fs.mkdtempSync(path.join(os.tmpdir(), "akm-e2e-ext-wiki-"));
+        process.env.AKM_STASH_DIR = stashDir;
+        saveConfig({ semanticSearchMode: "off" });
+        fs.mkdirSync(path.join(externalWiki, "tools", "documentation", "how-to"), { recursive: true });
+        fs.writeFileSync(path.join(externalWiki, "tools", "documentation", "how-to", "001-get-started.md"), "---\ndescription: External docs\n---\n# Start\n", "utf8");
+        try {
+            const registerResult = runCli("wiki", "register", "ics-docs", externalWiki, "--format", "json");
+            expect(registerResult.exitCode).toBe(0);
+            const registerJson = parseJson(registerResult.stdout);
+            expect(registerJson.ref).toBe("ics-docs");
+            expect(registerJson.sourceAdded).toEqual(expect.objectContaining({
+                type: "filesystem",
+                name: "ics-docs",
+                wiki: "ics-docs",
+            }));
+            const listResult = runCli("list", "--format", "json");
+            expect(listResult.exitCode).toBe(0);
+            const listJson = parseJson(listResult.stdout);
+            expect(listJson.sources).toEqual(expect.arrayContaining([
+                expect.objectContaining({
+                    name: "ics-docs",
+                    kind: "filesystem",
+                    wiki: "ics-docs",
+                }),
+            ]));
+            const searchResult = runCli("search", "documentation", "--type", "wiki", "--detail", "normal", "--format", "json");
+            expect(searchResult.exitCode).toBe(0);
+            const searchJson = parseJson(searchResult.stdout);
+            expect(searchJson.hits).toEqual(expect.arrayContaining([
+                expect.objectContaining({
+                    name: "ics-docs/tools/documentation/how-to/001-get-started",
+                    action: "akm show wiki:ics-docs/tools/documentation/how-to/001-get-started -> read the wiki page",
+                }),
+            ]));
+            const removeResult = runCli("wiki", "remove", "ics-docs", "--force", "--format", "json");
+            expect(removeResult.exitCode).toBe(0);
+            const removedSearchResult = runCli("search", "documentation", "--type", "wiki", "--format", "json");
+            expect(removedSearchResult.exitCode).toBe(0);
+            const removedSearchJson = parseJson(removedSearchResult.stdout);
+            expect(removedSearchJson.hits).toEqual([]);
+        }
+        finally {
+            fs.rmSync(stashDir, { recursive: true, force: true });
+            fs.rmSync(externalWiki, { recursive: true, force: true });
+        }
+    });
+    test("cli: wiki remove --force hides preserved raw-only leftovers from wiki list", async () => {
+        const stashDir = createEmptyStashDir("akm-e2e-wiki-remove-");
+        const rawSource = path.join(stashDir, "source.md");
+        process.env.AKM_STASH_DIR = stashDir;
+        saveConfig({ semanticSearchMode: "off" });
+        fs.writeFileSync(rawSource, "# Test\n", "utf8");
+        try {
+            const createResult = runCli("wiki", "create", "my-notes", "--format", "json");
+            expect(createResult.exitCode).toBe(0);
+            const stashResult = runCli("wiki", "stash", "my-notes", rawSource, "--as", "test-page", "--format", "json");
+            expect(stashResult.exitCode).toBe(0);
+            const removeResult = runCli("wiki", "remove", "my-notes", "--force", "--format", "text");
+            expect(removeResult.exitCode).toBe(0);
+            expect(removeResult.stdout).toContain("raw/ preserved at");
+            const listResult = runCli("wiki", "list", "--format", "json");
+            expect(listResult.exitCode).toBe(0);
+            const listJson = parseJson(listResult.stdout);
+            expect(listJson.wikis).toEqual([]);
+            const showResult = runCli("wiki", "show", "my-notes", "--format", "json");
+            expect(showResult.exitCode).not.toBe(0);
+            expect(showResult.stderr).toContain("Wiki not found: my-notes");
+            const cleanupResult = runCli("wiki", "remove", "my-notes", "--force", "--with-sources", "--format", "json");
+            expect(cleanupResult.exitCode).toBe(0);
+        }
+        finally {
+            fs.rmSync(stashDir, { recursive: true, force: true });
+        }
+    });
+    test("cli: akm index text output surfaces skipped-asset warnings", async () => {
+        const stashDir = createEmptyStashDir("akm-e2e-index-warn-");
+        process.env.AKM_STASH_DIR = stashDir;
+        saveConfig({ semanticSearchMode: "off" });
+        fs.mkdirSync(path.join(stashDir, "workflows"), { recursive: true });
+        fs.writeFileSync(path.join(stashDir, "workflows", "good.md"), [
+            "---",
+            "description: Good workflow",
+            "---",
+            "",
+            "# Workflow: Good",
+            "",
+            "## Step: First",
+            "Step ID: first",
+            "### Instructions",
+            "Do it.",
+            "",
+        ].join("\n"), "utf8");
+        // Truly malformed: no `# Workflow:` heading. Intro prose between the
+        // title and the first step is now permitted (#158).
+        fs.writeFileSync(path.join(stashDir, "workflows", "bad.md"), [
+            "---",
+            "description: Bad workflow",
+            "---",
+            "",
+            "## Step: First",
+            "Step ID: first",
+            "### Instructions",
+            "Do it.",
+            "",
+        ].join("\n"), "utf8");
+        try {
+            const result = runCli("index", "--full", "--format", "text");
+            expect(result.exitCode).toBe(0);
+            expect(result.stdout).toContain("Warnings (");
+            expect(result.stdout).toContain(path.join(stashDir, "workflows", "bad.md"));
+        }
+        finally {
+            fs.rmSync(stashDir, { recursive: true, force: true });
+        }
+    });
+    test("cli: akm remove resolves parsed ref id and removes cache directory", async () => {
+        const stashDir = createEmptyStashDir("akm-e2e-registry-remove-");
+        const stashRoot = path.join(stashDir, "registry-stash");
+        const cacheDir = fs.mkdtempSync(path.join(os.tmpdir(), "akm-e2e-cache-remove-"));
+        fs.mkdirSync(path.join(stashRoot, "scripts"), { recursive: true });
+        process.env.AKM_STASH_DIR = stashDir;
+        saveConfig({
+            semanticSearchMode: "off",
+            installed: [
+                {
+                    id: "npm:@scope/stash",
+                    source: "npm",
+                    ref: "npm:@scope/stash@1.0.0",
+                    artifactUrl: "https://registry.npmjs.org/@scope/stash/-/stash-1.0.0.tgz",
+                    resolvedVersion: "1.0.0",
+                    resolvedRevision: "abc123",
+                    stashRoot,
+                    cacheDir,
+                    installedAt: new Date().toISOString(),
+                },
+            ],
+        });
+        try {
+            const result = runCli("remove", "npm:@scope/stash@latest");
+            expect(result.exitCode).toBe(0);
+            const json = parseJson(result.stdout);
+            expect(expectDefined(json.removed).id).toBe("npm:@scope/stash");
+            const config = loadConfig();
+            expect(config.installed).toBeUndefined();
+            expect(fs.existsSync(cacheDir)).toBe(false);
+        }
+        finally {
+            fs.rmSync(stashDir, { recursive: true, force: true });
+            fs.rmSync(cacheDir, { recursive: true, force: true });
+        }
+    });
+    test("cli: akm update requires target or --all", async () => {
+        const stashDir = createEmptyStashDir("akm-e2e-registry-update-");
+        process.env.AKM_STASH_DIR = stashDir;
+        saveConfig({ semanticSearchMode: "off" });
+        try {
+            const result = runCli("update");
+            expect(result.exitCode).not.toBe(0);
+            const output = result.stdout + result.stderr;
+            expect(output).toContain("Either <target> or --all is required.");
+        }
+        finally {
+            fs.rmSync(stashDir, { recursive: true, force: true });
+        }
+    });
+    test("cli: akm update rejects target with --all", async () => {
+        const stashDir = createEmptyStashDir("akm-e2e-registry-update-both-");
+        process.env.AKM_STASH_DIR = stashDir;
+        saveConfig({ semanticSearchMode: "off" });
+        try {
+            const result = runCli("update", "npm:@scope/stash", "--all");
+            expect(result.exitCode).not.toBe(0);
+            const output = result.stdout + result.stderr;
+            expect(output).toContain("Specify either <target> or --all, not both.");
+        }
+        finally {
+            fs.rmSync(stashDir, { recursive: true, force: true });
+        }
+    });
+    test("cli: akm update missing target returns stable not-installed error", async () => {
+        const stashDir = createEmptyStashDir("akm-e2e-registry-missing-");
+        process.env.AKM_STASH_DIR = stashDir;
+        saveConfig({ semanticSearchMode: "off" });
+        try {
+            const result = runCli("update", "npm:@scope/stash");
+            expect(result.exitCode).not.toBe(0);
+            const output = result.stdout + result.stderr;
+            expect(output).toContain("No matching source for target: npm:@scope/stash");
+        }
+        finally {
+            fs.rmSync(stashDir, { recursive: true, force: true });
+        }
+    });
+});
+// ═══════════════════════════════════════════════════════════════════════════
+// Scenario 3a: CLI upgrade and update --force commands
+// ═══════════════════════════════════════════════════════════════════════════
+describe("Scenario: upgrade and update --force (no network)", () => {
+    let savedStashDir;
+    beforeEach(() => {
+        savedStashDir = process.env.AKM_STASH_DIR;
+    });
+    afterEach(() => {
+        if (savedStashDir === undefined) {
+            delete process.env.AKM_STASH_DIR;
+        }
+        else {
+            process.env.AKM_STASH_DIR = savedStashDir;
+        }
+    });
+    test("upgrade --check returns version info (mocked fetch)", async () => {
+        const { checkForUpdate } = await import("../src/commands/self-update");
+        const result = await withMockedFetch(() => Response.json({ tag_name: "v0.0.14" }), () => checkForUpdate("0.0.13"));
+        expect(result.currentVersion).toBe("0.0.13");
+        expect(result.latestVersion).toBe("0.0.14");
+        expect(result.updateAvailable).toBe(true);
+        expect(["binary", "bun", "npm", "pnpm", "unknown"]).toContain(result.installMethod);
+    });
+    test("performUpgrade detects non-binary install and returns guidance", async () => {
+        const { performUpgrade } = await import("../src/commands/self-update");
+        const result = await performUpgrade({
+            currentVersion: "0.0.13",
+            latestVersion: "0.0.14",
+            updateAvailable: true,
+            installMethod: "unknown",
+        });
+        expect(result.upgraded).toBe(false);
+        expect(["bun", "npm", "pnpm", "unknown"]).toContain(result.installMethod);
+        expect(result.message).toBeTruthy();
+    });
+    test("cli: akm update --help shows --force flag", async () => {
+        const result = spawnSync("bun", [CLI, "update", "--help"], {
+            encoding: "utf8",
+            timeout: 10_000,
+        });
+        const output = (result.stdout ?? "") + (result.stderr ?? "");
+        expect(output).toContain("--force");
+        expect(output).toContain("Force fresh download");
+    });
+    test("cli: akm update --force requires target or --all", async () => {
+        const stashDir = createEmptyStashDir("akm-e2e-update-force-");
+        process.env.AKM_STASH_DIR = stashDir;
+        saveConfig({ semanticSearchMode: "off" });
+        try {
+            const result = runCli("update", "--force");
+            expect(result.exitCode).not.toBe(0);
+            const output = result.stdout + result.stderr;
+            expect(output).toContain("Either <target> or --all is required.");
+        }
+        finally {
+            fs.rmSync(stashDir, { recursive: true, force: true });
+        }
+    });
+    test("cli: akm upgrade --help shows --check and --force flags", async () => {
+        const result = spawnSync("bun", [CLI, "upgrade", "--help"], {
+            encoding: "utf8",
+            timeout: 10_000,
+        });
+        const output = (result.stdout ?? "") + (result.stderr ?? "");
+        expect(output).toContain("--check");
+        expect(output).toContain("--force");
+    });
+    test("cli: akm help migrate prints migration guidance for a release", async () => {
+        const result = spawnSync("bun", [CLI, "help", "migrate", "0.5.0"], {
+            encoding: "utf8",
+            timeout: 10_000,
+        });
+        const output = (result.stdout ?? "") + (result.stderr ?? "");
+        expect(result.status).toBe(0);
+        expect(output).toContain("Migration notes for akm v0.5.0");
+        expect(output).toContain("## [0.5.0]");
+    });
+    test("cli: akm --help lists the help command", async () => {
+        const result = spawnSync("bun", [CLI, "--help"], {
+            encoding: "utf8",
+            timeout: 10_000,
+        });
+        const output = (result.stdout ?? "") + (result.stderr ?? "");
+        expect(output).toContain("help");
+        expect(output).toContain("focused help topics");
+    });
+    test("cli: akm setup --help shows the wizard description (issue #273)", async () => {
+        // The setup subcommand should advertise its purpose so operators can
+        // see what the wizard configures (embeddings, LLM, registries, sources,
+        // agent profiles) without running the interactive flow.
+        const result = spawnSync("bun", [CLI, "setup", "--help"], {
+            encoding: "utf8",
+            timeout: 10_000,
+        });
+        const output = (result.stdout ?? "") + (result.stderr ?? "");
+        expect(output).toContain("Interactive configuration wizard");
+        expect(output).toContain("embeddings");
+        expect(output).toContain("LLM");
+        expect(output).toContain("registries");
+        expect(output).toContain("sources");
+        expect(output).toContain("agent profiles");
+    });
+});
+// ═══════════════════════════════════════════════════════════════════════════
+// Scenario 3b: CLI knowledge view modes (positional syntax)
+// ═══════════════════════════════════════════════════════════════════════════
+describe("Scenario: CLI knowledge view modes (positional)", () => {
+    let stashDir;
+    beforeAll(async () => {
+        stashDir = copyFixturesToTmp();
+        process.env.AKM_STASH_DIR = stashDir;
+    });
+    beforeEach(() => {
+        process.env.AKM_STASH_DIR = stashDir;
+    });
+    afterAll(() => {
+        fs.rmSync(stashDir, { recursive: true, force: true });
+    });
+    test("cli: show knowledge with positional toc", async () => {
+        const result = runCli("show", "knowledge:guide.md", "toc");
+        expect(result.exitCode).toBe(0);
+        const json = parseJson(result.stdout);
+        expect(json.type).toBe("knowledge");
+        expect(json.content).toContain("# API Reference Guide");
+        expect(json.content).toContain("## Getting Started");
+        expect(json.content).toContain("lines total");
+    });
+    test("cli: show knowledge with positional section heading", async () => {
+        const result = runCli("show", "knowledge:guide.md", "section", "Getting Started");
+        expect(result.exitCode).toBe(0);
+        const json = parseJson(result.stdout);
+        expect(json.type).toBe("knowledge");
+        expect(json.content).toContain("Getting Started");
+        expect(json.content).toContain("install the package");
+        // Should include sub-headings but not sibling headings
+        expect(json.content).toContain("Prerequisites");
+        expect(json.content).not.toContain("Authentication");
+    });
+    test("cli: show knowledge with positional lines start end", async () => {
+        const result = runCli("show", "knowledge:guide.md", "lines", "1", "5");
+        expect(result.exitCode).toBe(0);
+        const json = parseJson(result.stdout);
+        expect(json.type).toBe("knowledge");
+        // Lines 1-5 cover the frontmatter start
+        expect(json.content).toContain("---");
+    });
+    test("cli: show knowledge rejects legacy --view flag", async () => {
+        const result = runCli("show", "knowledge:guide.md", "--view", "toc");
+        expect(result.exitCode).not.toBe(0);
+        expect(result.stderr).toContain("Legacy show flags are no longer supported");
+    });
+    test("cli: show knowledge default (no view mode) returns full content", async () => {
+        const result = runCli("show", "knowledge:guide.md");
+        expect(result.exitCode).toBe(0);
+        const json = parseJson(result.stdout);
+        expect(json.type).toBe("knowledge");
+        expect(json.content).toBeDefined();
+        // Full content should include everything
+        expect(json.content).toContain("API Reference Guide");
+        expect(json.content).toContain("Getting Started");
+        expect(json.content).toContain("Authentication");
+    });
+    test("cli: show knowledge --detail brief omits full content", async () => {
+        const result = runCli("show", "knowledge:guide.md", "--detail", "brief");
+        expect(result.exitCode).toBe(0);
+        const json = parseJson(result.stdout);
+        expect(json.type).toBe("knowledge");
+        expect(json.name).toBe("guide.md");
+        expect(json.description).toBe("Comprehensive guide for the example API");
+        expect(json.action).toContain("Reference material");
+        expect(json.content).toBeUndefined();
+    });
+});
+// ═══════════════════════════════════════════════════════════════════════════
+// Scenario 4: Progressive improvement — user drops scripts, indexes later
+// ═══════════════════════════════════════════════════════════════════════════
+describe("Scenario: Zero-config progressive improvement", () => {
+    let stashDir;
+    let scenarioCacheDir;
+    beforeAll(async () => {
+        stashDir = fs.mkdtempSync(path.join(os.tmpdir(), "akm-e2e-prog-"));
+        scenarioCacheDir = fs.mkdtempSync(path.join(os.tmpdir(), "akm-e2e-cache-s4-"));
+        for (const sub of ["scripts", "skills", "commands", "agents"]) {
+            fs.mkdirSync(path.join(stashDir, sub), { recursive: true });
+        }
+        process.env.AKM_STASH_DIR = stashDir;
+        process.env.XDG_CACHE_HOME = scenarioCacheDir;
+    });
+    beforeEach(() => {
+        process.env.AKM_STASH_DIR = stashDir;
+        process.env.XDG_CACHE_HOME = scenarioCacheDir;
+    });
+    afterAll(() => {
+        fs.rmSync(stashDir, { recursive: true, force: true });
+        fs.rmSync(scenarioCacheDir, { recursive: true, force: true });
+    });
+    test("user drops a script in scripts/ — search finds it by name (no index)", async () => {
+        fs.mkdirSync(path.join(stashDir, "scripts", "format"), { recursive: true });
+        fs.writeFileSync(path.join(stashDir, "scripts", "format", "prettier-check.sh"), "#!/usr/bin/env bash\n# Format code with Prettier\nprettier --check .\n");
+        const result = await akmSearch({ query: "prettier", type: "script" });
+        expect(result.hits.length).toBe(1);
+        expect(result.hits[0].name).toContain("prettier");
+    });
+    test("user runs index — metadata generated in database with description from comments", async () => {
+        await akmIndex({ stashDir });
+        // No .stash.json should be auto-generated
+        expect(fs.existsSync(path.join(stashDir, "scripts", "format", ".stash.json"))).toBe(false);
+        const db = openDatabase();
+        const entries = getAllEntries(db, "script");
+        const formatEntry = entries.find((e) => e.entry.name.includes("prettier"));
+        expect(formatEntry).toBeDefined();
+        expect(formatEntry?.entry.quality).toBe("generated");
+        expect(formatEntry?.entry.description).toContain("Format code");
+        closeDatabase(db);
+    });
+    test("user adds more scripts — re-index picks them up", async () => {
+        fs.mkdirSync(path.join(stashDir, "scripts", "db"), { recursive: true });
+        fs.writeFileSync(path.join(stashDir, "scripts", "db", "migrate.sh"), "#!/usr/bin/env bash\n# Run database migrations\necho 'migrating...'\n");
+        const result = await akmIndex({ stashDir });
+        expect(result.totalEntries).toBeGreaterThanOrEqual(2);
+        const db = openDatabase();
+        const entries = getAllEntries(db, "script");
+        const migrateEntry = entries.find((e) => e.entry.name.includes("migrate"));
+        expect(migrateEntry).toBeDefined();
+        expect(migrateEntry?.entry.description).toContain("database migrations");
+        closeDatabase(db);
+    });
+    test("user creates .stash.json manually — overrides used on next index", async () => {
+        // User creates a .stash.json override for the format script
+        const stashPath = path.join(stashDir, "scripts", "format", ".stash.json");
+        fs.writeFileSync(stashPath, JSON.stringify({
+            entries: [
+                {
+                    name: "prettier-check",
+                    type: "script",
+                    description: "Check code formatting with Prettier",
+                    tags: ["prettier", "format", "style"],
+                    filename: "prettier-check.sh",
+                },
+            ],
+        }, null, 2));
+        // Re-index — should use user override
+        await akmIndex({ stashDir });
+        const reloaded = expectDefined(loadStashFile(path.join(stashDir, "scripts", "format")));
+        expect(reloaded.entries[0].description).toBe("Check code formatting with Prettier");
+        expect(reloaded.entries[0].tags).toContain("prettier");
+        expect(reloaded.entries[0].quality).not.toBe("generated");
+    });
+    test("semantic search finds user-edited metadata after re-index", async () => {
+        // Re-index to pick up manual edits in the search index
+        await akmIndex({ stashDir });
+        const result = await akmSearch({ query: "format code style" });
+        expect(result.hits.length).toBeGreaterThan(0);
+        expect(result.hits.some((h) => h.name.includes("prettier"))).toBe(true);
+    });
+});
+// ═══════════════════════════════════════════════════════════════════════════
+// Scenario 5: Multi-script directory with .stash.json
+// ═══════════════════════════════════════════════════════════════════════════
+describe("Scenario: Multi-script directory with hand-written .stash.json", () => {
+    let stashDir;
+    let scenarioCacheDir;
+    beforeAll(async () => {
+        stashDir = copyFixturesToTmp();
+        scenarioCacheDir = fs.mkdtempSync(path.join(os.tmpdir(), "akm-e2e-cache-s5-"));
+        process.env.AKM_STASH_DIR = stashDir;
+        process.env.XDG_CACHE_HOME = scenarioCacheDir;
+        await akmIndex({ stashDir });
+    });
+    beforeEach(() => {
+        process.env.AKM_STASH_DIR = stashDir;
+        process.env.XDG_CACHE_HOME = scenarioCacheDir;
+    });
+    afterAll(() => {
+        fs.rmSync(stashDir, { recursive: true, force: true });
+        fs.rmSync(scenarioCacheDir, { recursive: true, force: true });
+    });
+    test("docker/ directory exposes two scripts from single .stash.json", async () => {
+        const stash = expectDefined(loadStashFile(path.join(stashDir, "scripts", "docker")));
+        expect(stash.entries).toHaveLength(2);
+        const names = stash.entries.map((e) => e.name);
+        expect(names).toContain("docker-build");
+        expect(names).toContain("docker-compose");
+    });
+    test("search for 'docker build' returns docker-build as top result", async () => {
+        const result = await akmSearch({ query: "docker build" });
+        expect(result.hits[0].name).toContain("docker");
+        expect(result.hits[0].description).toContain("Docker image");
+    });
+    test("search for 'compose development' returns docker-compose", async () => {
+        const result = await akmSearch({ query: "compose development" });
+        const composeHit = result.hits.find((h) => h.name.includes("compose"));
+        expect(composeHit).toBeDefined();
+        expect(composeHit?.tags).toContain("compose");
+    });
+});
+// ═══════════════════════════════════════════════════════════════════════════
+// Scenario 6: Index persistence and cache
+// ═══════════════════════════════════════════════════════════════════════════
+describe("Scenario: Index persistence across sessions", () => {
+    let stashDir;
+    let scenarioCacheDir;
+    beforeAll(async () => {
+        stashDir = copyFixturesToTmp();
+        scenarioCacheDir = fs.mkdtempSync(path.join(os.tmpdir(), "akm-e2e-cache-s6-"));
+        process.env.AKM_STASH_DIR = stashDir;
+        process.env.XDG_CACHE_HOME = scenarioCacheDir;
+    });
+    beforeEach(() => {
+        process.env.AKM_STASH_DIR = stashDir;
+        process.env.XDG_CACHE_HOME = scenarioCacheDir;
+    });
+    afterAll(() => {
+        fs.rmSync(stashDir, { recursive: true, force: true });
+        fs.rmSync(scenarioCacheDir, { recursive: true, force: true });
+    });
+    test("index is persisted and loadable", async () => {
+        await akmIndex({ stashDir });
+        const db = openDatabase();
+        const version = getMeta(db, "version");
+        expect(version).toBe(String(DB_VERSION));
+        const storedStashDir = getMeta(db, "stashDir");
+        expect(storedStashDir).toBe(stashDir);
+        const entries = getAllEntries(db);
+        expect(entries.length).toBeGreaterThan(0);
+        const builtAt = getMeta(db, "builtAt");
+        expect(builtAt).toBeTruthy();
+        closeDatabase(db);
+    });
+    test("search uses persisted index (simulates new session)", async () => {
+        // First index
+        await akmIndex({ stashDir });
+        // Simulate a new session by just doing search (no re-index)
+        const result = await akmSearch({ query: "docker" });
+        expect(result.hits.length).toBeGreaterThan(0);
+        // Should have scores from semantic search, not substring
+        expect(result.hits[0].score).toBeDefined();
+    });
+    test("re-index updates the persisted index", async () => {
+        await akmIndex({ stashDir });
+        const db1 = openDatabase();
+        const entries1 = getAllEntries(db1);
+        const builtAt1 = expectDefined(getMeta(db1, "builtAt"));
+        closeDatabase(db1);
+        // Add a new script
+        fs.mkdirSync(path.join(stashDir, "scripts", "new-script"), { recursive: true });
+        fs.writeFileSync(path.join(stashDir, "scripts", "new-script", "hello.sh"), "#!/bin/bash\necho hello\n");
+        await akmIndex({ stashDir });
+        const db2 = openDatabase();
+        const entries2 = getAllEntries(db2);
+        const builtAt2 = expectDefined(getMeta(db2, "builtAt"));
+        closeDatabase(db2);
+        expect(entries2.length).toBeGreaterThan(entries1.length);
+        expect(new Date(builtAt2).getTime()).toBeGreaterThanOrEqual(new Date(builtAt1).getTime());
+    });
+});
+// ═══════════════════════════════════════════════════════════════════════════
+// Scenario 7: Error handling and edge cases
+// ═══════════════════════════════════════════════════════════════════════════
+describe("Scenario: Error handling and edge cases", () => {
+    let savedStashDir;
+    beforeEach(() => {
+        savedStashDir = process.env.AKM_STASH_DIR;
+    });
+    afterEach(() => {
+        if (savedStashDir === undefined) {
+            delete process.env.AKM_STASH_DIR;
+        }
+        else {
+            process.env.AKM_STASH_DIR = savedStashDir;
+        }
+    });
+    test("search with non-existent AKM_STASH_DIR throws clear error", async () => {
+        const orig = process.env.AKM_STASH_DIR;
+        process.env.AKM_STASH_DIR = "/nonexistent/path";
+        try {
+            await expect(akmSearch({ query: "test" })).rejects.toThrow(/Unable to read/);
+        }
+        finally {
+            if (orig === undefined)
+                delete process.env.AKM_STASH_DIR;
+            else
+                process.env.AKM_STASH_DIR = orig;
+        }
+    });
+    test("search with unset AKM_STASH_DIR throws clear error", async () => {
+        const orig = process.env.AKM_STASH_DIR;
+        const origHome = process.env.HOME;
+        delete process.env.AKM_STASH_DIR;
+        // Point HOME somewhere without an akm directory to force the "no stash" error
+        const tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), "akm-e2e-nohome-"));
+        process.env.HOME = tmpHome;
+        try {
+            await expect(akmSearch({ query: "test" })).rejects.toThrow(/No stash directory found/);
+        }
+        finally {
+            if (orig === undefined)
+                delete process.env.AKM_STASH_DIR;
+            else
+                process.env.AKM_STASH_DIR = orig;
+            if (origHome === undefined)
+                delete process.env.HOME;
+            else
+                process.env.HOME = origHome;
+            fs.rmSync(tmpHome, { recursive: true, force: true });
+        }
+    });
+    test("show with invalid ref format throws", async () => {
+        const stashDir = fs.mkdtempSync(path.join(os.tmpdir(), "akm-e2e-err-"));
+        process.env.AKM_STASH_DIR = stashDir;
+        try {
+            await expect(akmShow({ ref: "badref" })).rejects.toThrow(/Invalid ref/);
+        }
+        finally {
+            fs.rmSync(stashDir, { recursive: true, force: true });
+        }
+    });
+    test("show with unknown type throws", async () => {
+        const stashDir = fs.mkdtempSync(path.join(os.tmpdir(), "akm-e2e-err-"));
+        process.env.AKM_STASH_DIR = stashDir;
+        try {
+            await expect(akmShow({ ref: "widget:foo" })).rejects.toThrow(/Invalid asset type/);
+        }
+        finally {
+            fs.rmSync(stashDir, { recursive: true, force: true });
+        }
+    });
+    test("show with path traversal attempt throws", async () => {
+        const stashDir = fs.mkdtempSync(path.join(os.tmpdir(), "akm-e2e-err-"));
+        fs.mkdirSync(path.join(stashDir, "scripts"), { recursive: true });
+        process.env.AKM_STASH_DIR = stashDir;
+        try {
+            await expect(akmShow({ ref: "script:../../etc/passwd" })).rejects.toThrow(/Path traversal/);
+        }
+        finally {
+            fs.rmSync(stashDir, { recursive: true, force: true });
+        }
+    });
+    test("search on empty stash returns no hits with tip", async () => {
+        const stashDir = fs.mkdtempSync(path.join(os.tmpdir(), "akm-e2e-empty-"));
+        for (const sub of ["scripts", "skills", "commands", "agents"]) {
+            fs.mkdirSync(path.join(stashDir, sub), { recursive: true });
+        }
+        process.env.AKM_STASH_DIR = stashDir;
+        try {
+            const result = await akmSearch({ query: "anything" });
+            expect(result.hits).toHaveLength(0);
+            expect(result.tip).toBeTruthy();
+        }
+        finally {
+            fs.rmSync(stashDir, { recursive: true, force: true });
+        }
+    });
+    test("index on empty stash succeeds with zero entries", async () => {
+        const stashDir = fs.mkdtempSync(path.join(os.tmpdir(), "akm-e2e-empty-"));
+        for (const sub of ["scripts", "skills", "commands", "agents"]) {
+            fs.mkdirSync(path.join(stashDir, sub), { recursive: true });
+        }
+        try {
+            const result = await akmIndex({ stashDir });
+            expect(result.totalEntries).toBe(0);
+            expect(result.generatedMetadata).toBe(0);
+        }
+        finally {
+            fs.rmSync(stashDir, { recursive: true, force: true });
+        }
+    });
+});
+// ═══════════════════════════════════════════════════════════════════════════
+// Scenario 8: Mixed asset type discovery
+// ═══════════════════════════════════════════════════════════════════════════
+describe("Scenario: Cross-type discovery", () => {
+    let stashDir;
+    let scenarioCacheDir;
+    beforeAll(async () => {
+        stashDir = copyFixturesToTmp();
+        scenarioCacheDir = fs.mkdtempSync(path.join(os.tmpdir(), "akm-e2e-cache-s8-"));
+        process.env.AKM_STASH_DIR = stashDir;
+        process.env.XDG_CACHE_HOME = scenarioCacheDir;
+        await akmIndex({ stashDir });
+    });
+    beforeEach(() => {
+        process.env.AKM_STASH_DIR = stashDir;
+        process.env.XDG_CACHE_HOME = scenarioCacheDir;
+    });
+    afterAll(() => {
+        fs.rmSync(stashDir, { recursive: true, force: true });
+        fs.rmSync(scenarioCacheDir, { recursive: true, force: true });
+    });
+    test("search 'any' type returns mixed results across scripts, skills, commands, agents", async () => {
+        const result = await akmSearch({ query: "", type: "any" });
+        const types = new Set(result.hits.map((h) => h.type));
+        // Should have at least scripts and one other type
+        expect(types.has("script")).toBe(true);
+        expect(types.size).toBeGreaterThan(1);
+    });
+    test("each hit has a valid ref that can be used with show", async () => {
+        const result = await akmSearch({ query: "", type: "any", limit: 10 });
+        for (const hit of result.hits.filter(isLocalHit)) {
+            expect(hit.ref).toBeTruthy();
+            expect(hit.ref).toContain(":");
+            // Should not throw when opening
+            const openResult = await akmShow({ ref: expectDefined(hit.ref) });
+            expect(openResult.type).toBe(hit.type);
+        }
+    });
+    test("script hits have run", async () => {
+        const result = await akmSearch({ query: "", type: "script" });
+        for (const hit of result.hits) {
+            expect(hit.type).toBe("script");
+        }
+    });
+});