akm-cli 0.6.0 → 0.7.0-rc1

package/dist/{commands → src/commands}/config-cli.js

@@ -62,9 +62,10 @@ export function parseConfigValue(key, value) {
         case "security.installAudit.allowedFindings":
             return { security: { installAudit: { allowedFindings: parseAllowedFindingsValue(value, key) } } };
         default:
-            throw new UsageError(`Unknown config key: ${key}`);
+            throw new UsageError(`Unknown config key: ${key}`, "INVALID_FLAG_VALUE", UNKNOWN_CONFIG_KEY_HINT);
     }
 }
+const UNKNOWN_CONFIG_KEY_HINT = "Valid top-level keys: stashDir, embedding, llm, registries, sources, agent, output, semanticSearchMode. Use dotted paths like `embedding.endpoint` or `output.format` for nested values.";
 export function getConfigValue(config, key) {
     switch (key) {
         case "stashDir":
@@ -114,7 +115,7 @@ export function getConfigValue(config, key) {
         case "security.installAudit.allowedFindings":
             return config.security?.installAudit?.allowedFindings ?? null;
         default:
-            throw new UsageError(`Unknown config key: ${key}`);
+            throw new UsageError(`Unknown config key: ${key}`, "INVALID_FLAG_VALUE", UNKNOWN_CONFIG_KEY_HINT);
     }
 }
 export function setConfigValue(config, key, rawValue) {
@@ -168,7 +169,7 @@ export function setConfigValue(config, key, rawValue) {
             return { ...config, defaultWriteTarget: name };
         }
         default:
-            throw new UsageError(`Unknown config key: ${key}`);
+            throw new UsageError(`Unknown config key: ${key}`, "INVALID_FLAG_VALUE", UNKNOWN_CONFIG_KEY_HINT);
     }
 }
 export function unsetConfigValue(config, key) {
@@ -241,7 +242,7 @@ export function unsetConfigValue(config, key) {
                 }),
             };
         default:
-            throw new UsageError(`Unknown or unsupported unset key: ${key}`);
+            throw new UsageError(`Unknown or unsupported unset key: ${key}`, "INVALID_FLAG_VALUE", UNKNOWN_CONFIG_KEY_HINT);
     }
 }
 export function listConfig(config) {

package/dist/src/commands/distill.js

@@ -0,0 +1,283 @@
+/**
+ * `akm distill <ref>` — feedback distillation into lesson proposals (#228).
+ *
+ * The command reads a target asset and any recent feedback events about it,
+ * asks an LLM to distil a *lesson* (per v1 spec §13) the agent should
+ * remember next time, and queues the result as a {@link Proposal} (source
+ * `"distill"`). The proposal queue is the *only* path to a live asset — this
+ * command never mutates source files directly. Acceptance is a human (or
+ * automated) decision via `akm proposal accept`.
+ *
+ * # Architectural seams
+ *
+ *   - **Single bounded in-tree LLM call.** Wrapped in {@link tryLlmFeature}
+ *     under the `feedback_distillation` gate (v1 spec §14). The wrapper
+ *     enforces the 30 s hard timeout and converts disable / throw / timeout
+ *     into a `null` return from `fn`, which we treat as a graceful
+ *     "skipped" outcome (exit 0, no proposal, `distill_invoked` event with
+ *     `outcome: "skipped"`).
+ *   - **Stateless.** No module-level state — every callable is a pure
+ *     function of its arguments and an injectable `chat` seam. The
+ *     architecture seam test (`tests/architecture/llm-stateless-seam.test.ts`)
+ *     applies.
+ *   - **Output substrate.** Proposal creation goes through the `proposals`
+ *     module so distill shares its persistence + validation pipeline with
+ *     `akm reflect` / `akm propose`. Validation failures (LLM returned a
+ *     lesson without required `description` / `when_to_use` frontmatter) are
+ *     a *different* graceful path: no proposal is created, the structured
+ *     error is surfaced, and the command exits non-zero.
+ *
+ * # Lesson-name derivation rule
+ *
+ * The proposed lesson ref is `lesson:<original-ref-slug>-lesson`, where
+ * `<original-ref-slug>` is `<type>-<name>` from the parsed input ref (so
+ * `skill:deploy` → `lesson:skill-deploy-lesson`, and `team//memory:auth-tips`
+ * → `lesson:memory-auth-tips-lesson`). Origin prefixes are dropped from the
+ * derived name so two sources with the same asset-type/name collapse onto
+ * the same lesson queue entry rather than each generating its own — the
+ * proposal queue tolerates duplicate refs (id is a UUID), so the human
+ * reviewer can decide which one to accept.
+ *
+ * # Why we do not call `runAgent`
+ *
+ * Distillation is in-tree per the v1 spec ("bounded in-tree LLM call"). The
+ * agent dispatch path is a heavier shell-out used by the curator/agent
+ * surfaces — distill must be cheap, deterministic-ish, and bounded so it can
+ * be invoked from CI / automation without spinning up an agent harness.
+ */
+import fs from "node:fs";
+import { parseAssetRef } from "../core/asset-ref";
+import { resolveStashDir } from "../core/common";
+import { loadConfig } from "../core/config";
+import { ConfigError, UsageError } from "../core/errors";
+import { appendEvent, readEvents } from "../core/events";
+import { parseFrontmatter } from "../core/frontmatter";
+import { lintLessonContent } from "../core/lesson-lint";
+import { createProposal } from "../core/proposals";
+import { lookup as indexerLookup } from "../indexer/indexer";
+import { chatCompletion } from "../llm/client";
+import { tryLlmFeature } from "../llm/feature-gate";
+// ── Lesson-ref derivation ───────────────────────────────────────────────────
+/** Derive the proposed lesson ref from the input ref. See module docblock. */
+export function deriveLessonRef(inputRef) {
+    const parsed = parseAssetRef(inputRef);
+    // Strip origin: a feedback signal recorded against `team//skill:deploy`
+    // distils into the same lesson namespace as `skill:deploy`. The proposal
+    // id (a UUID) keeps the queue entries distinct, so collisions are not a
+    // problem — and reviewers want to see them next to each other anyway.
+    const slug = `${parsed.type}-${parsed.name}`.toLowerCase();
+    // Replace anything outside the canonical asset-name charset with `-`. Keep
+    // it deterministic so re-runs produce the same ref.
+    const safe = slug
+        .replace(/[^a-z0-9-]+/g, "-")
+        .replace(/-+/g, "-")
+        .replace(/^-|-$/g, "");
+    return `lesson:${safe}-lesson`;
+}
+// ── Prompt assembly ─────────────────────────────────────────────────────────
+const SYSTEM_PROMPT = [
+    "You are the akm `distill` distiller.",
+    "Given an asset and recent feedback events about it, produce a single",
+    "concise *lesson* an agent should remember next time it works on this",
+    "asset's domain.",
+    "",
+    "Output MUST be a complete markdown file with YAML frontmatter:",
+    "  ---",
+    "  description: <one-line summary of what the lesson teaches>",
+    "  when_to_use: <one-line trigger that should make a caller apply it>",
+    "  ---",
+    "",
+    "  <lesson body, plain markdown, 1–3 short paragraphs>",
+    "",
+    "Both `description` and `when_to_use` MUST be non-empty single-line strings.",
+    "Output ONLY the lesson file contents — no prose, no fences, no preamble.",
+].join("\n");
+/** Pure: build the user-prompt body. Exported for tests. */
+export function buildDistillPrompt(input) {
+    const lines = [];
+    lines.push(`Asset ref: ${input.inputRef}`);
+    lines.push("");
+    lines.push("Asset content:");
+    if (input.assetContent) {
+        lines.push("```");
+        lines.push(input.assetContent.trim());
+        lines.push("```");
+    }
+    else {
+        lines.push("(asset is not currently indexed; distil from feedback signal alone)");
+    }
+    lines.push("");
+    lines.push("Recent feedback events (most recent last):");
+    if (input.feedback.length === 0) {
+        lines.push("(no feedback events recorded — distil from the asset itself)");
+    }
+    else {
+        for (const event of input.feedback) {
+            const meta = event.metadata ? ` ${JSON.stringify(event.metadata)}` : "";
+            lines.push(`- ${event.ts} ${event.eventType}${meta}`);
+        }
+    }
+    lines.push("");
+    lines.push("Produce the lesson markdown file now.");
+    return lines.join("\n");
+}
+// ── Main entry point ────────────────────────────────────────────────────────
+/**
+ * Run a single bounded distillation pass for `ref`. Always emits exactly one
+ * `distill_invoked` event (with `outcome` in the metadata) regardless of the
+ * branch taken — so observers can count invocations cheaply.
+ */
+export async function akmDistill(options) {
+    const inputRef = options.ref.trim();
+    if (!inputRef) {
+        throw new UsageError("Asset ref is required. Usage: akm distill <ref>", "MISSING_REQUIRED_ARGUMENT");
+    }
+    // Validate the ref shape up front so a typo never reaches the LLM.
+    parseAssetRef(inputRef);
+    const lessonRef = deriveLessonRef(inputRef);
+    const config = options.config ?? loadConfig();
+    const stash = options.stashDir ?? resolveStashDir();
+    const chat = options.chat ?? chatCompletion;
+    const lookup = options.lookupFn ?? defaultLookup;
+    const readEventsImpl = options.readEventsFn ?? readEvents;
+    // Best-effort load: when the asset is not yet indexed we still proceed —
+    // the LLM is asked to distil from "available signal" (feedback alone).
+    let assetContent = null;
+    try {
+        const filePath = await lookup(inputRef);
+        if (filePath && fs.existsSync(filePath)) {
+            assetContent = fs.readFileSync(filePath, "utf8");
+        }
+    }
+    catch {
+        assetContent = null;
+    }
+    const { events } = readEventsImpl({ ref: inputRef, type: "feedback" });
+    // #267 — feedback exclusion. Filter events whose `ref` matches the
+    // exclusion list BEFORE the prompt is built. The original event stream
+    // is never mutated; only the `feedback` slice that reaches the LLM is
+    // affected. The exclusion set is normalised through `parseAssetRef` →
+    // re-serialised so callers can pass canonical or origin-prefixed refs
+    // and the comparison still works against the event payload's `ref`.
+    const exclusionList = options.excludeFeedbackFromRefs ?? [];
+    const exclusionSet = new Set(exclusionList.map((ref) => ref.trim()).filter((ref) => ref.length > 0));
+    const originalEventCount = events.length;
+    const filteredEvents = exclusionSet.size > 0 ? events.filter((e) => !(e.ref !== undefined && exclusionSet.has(e.ref))) : events;
+    const filteredFeedbackCount = originalEventCount - filteredEvents.length;
+    const feedbackFullyFiltered = exclusionSet.size > 0 && originalEventCount > 0 && filteredEvents.length === 0;
+    const feedback = filteredEvents.slice(-20).map((e) => ({
+        ts: e.ts,
+        eventType: e.eventType,
+        ...(e.metadata !== undefined ? { metadata: e.metadata } : {}),
+    }));
+    const userPrompt = buildDistillPrompt({ inputRef, assetContent, feedback });
+    const messages = [
+        { role: "system", content: SYSTEM_PROMPT },
+        { role: "user", content: userPrompt },
+    ];
+    // Single bounded LLM call. The wrapper handles the gate-check, 30 s
+    // timeout, and error fallback (returning `null`).
+    const raw = await tryLlmFeature("feedback_distillation", config, async () => {
+        if (!config.llm) {
+            // No LLM connection configured — treat as gate-disabled. Throwing
+            // here lets `tryLlmFeature` route us through the "error" fallback,
+            // which is the same graceful skipped path.
+            throw new ConfigError("No LLM connection configured. Set `llm.endpoint` and `llm.model` in the akm config.", "LLM_NOT_CONFIGURED");
+        }
+        return chat(config.llm, messages);
+    }, null);
+    if (raw === null || raw.trim() === "") {
+        appendEvent({
+            eventType: "distill_invoked",
+            ref: inputRef,
+            metadata: {
+                outcome: "skipped",
+                lessonRef,
+                ...(exclusionSet.size > 0 ? { filteredFeedbackCount } : {}),
+            },
+        });
+        return {
+            schemaVersion: 1,
+            ok: true,
+            outcome: "skipped",
+            inputRef,
+            lessonRef,
+            message: "feedback distillation is disabled or the LLM call failed; no proposal created.",
+            ...(exclusionSet.size > 0 ? { filteredFeedbackCount, feedbackFullyFiltered } : {}),
+        };
+    }
+    // Strip any stray fence the LLM might have added around the markdown.
+    const content = stripMarkdownFences(raw);
+    // Parse + lint the lesson before creating the proposal. The lint is the
+    // canonical gate for required frontmatter (v1 spec §13). On failure we
+    // surface a structured error and exit non-zero — but still emit
+    // `distill_invoked` so the failure is observable.
+    const lintReport = lintLessonContent(content, `distill:${inputRef}`);
+    if (lintReport.findings.length > 0) {
+        appendEvent({
+            eventType: "distill_invoked",
+            ref: inputRef,
+            metadata: {
+                outcome: "validation_failed",
+                lessonRef,
+                findingKinds: lintReport.findings.map((f) => f.kind),
+                ...(exclusionSet.size > 0 ? { filteredFeedbackCount } : {}),
+            },
+        });
+        const message = lintReport.findings.map((f) => f.message).join("\n");
+        throw new UsageError(`Distilled lesson failed validation:\n${message}`, "MISSING_REQUIRED_ARGUMENT", "Lessons require non-empty `description` and `when_to_use` frontmatter fields. See v1 spec §13.");
+    }
+    // Round-trip the parsed frontmatter so the proposal carries it as a
+    // structured payload alongside the raw content (matches the shape used by
+    // other proposal sources).
+    const parsed = parseFrontmatter(content);
+    const proposal = createProposal(stash, {
+        ref: lessonRef,
+        source: "distill",
+        ...(options.sourceRun !== undefined ? { sourceRun: options.sourceRun } : {}),
+        payload: {
+            content,
+            ...(Object.keys(parsed.data).length > 0 ? { frontmatter: parsed.data } : {}),
+        },
+    }, options.ctx);
+    appendEvent({
+        eventType: "distill_invoked",
+        ref: inputRef,
+        metadata: {
+            outcome: "queued",
+            lessonRef,
+            proposalId: proposal.id,
+            ...(options.sourceRun !== undefined ? { sourceRun: options.sourceRun } : {}),
+            ...(exclusionSet.size > 0 ? { filteredFeedbackCount } : {}),
+        },
+    });
+    return {
+        schemaVersion: 1,
+        ok: true,
+        outcome: "queued",
+        inputRef,
+        lessonRef,
+        proposalId: proposal.id,
+        proposal,
+        ...(exclusionSet.size > 0 ? { filteredFeedbackCount, feedbackFullyFiltered } : {}),
+    };
+}
+// ── Helpers ─────────────────────────────────────────────────────────────────
+async function defaultLookup(ref) {
+    try {
+        const entry = await indexerLookup(parseAssetRef(ref));
+        return entry?.filePath ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Best-effort fence stripping. Keeps the body intact when no fence is present. */
+function stripMarkdownFences(raw) {
+    const trimmed = raw.trim();
+    // Only strip outer triple-fence pairs — leave inner code blocks alone.
+    const fence = trimmed.match(/^```(?:markdown|md)?\s*\n([\s\S]*?)\n```\s*$/i);
+    if (fence)
+        return fence[1].trim();
+    return trimmed;
+}

package/dist/src/commands/events.js

@@ -0,0 +1,108 @@
+/**
+ * `akm events list` and `akm events tail` (#204).
+ *
+ * Programmatic surface — the CLI dispatcher in `src/cli.ts` registers two
+ * verbs that delegate here. Both return JSON envelopes shaped by
+ * `src/output/shapes.ts` so the output flows through the same shape and
+ * text-renderer pipeline as the rest of the CLI (no silent
+ * `JSON.stringify` fallback).
+ */
+import { parseAssetRef } from "../core/asset-ref";
+import { UsageError } from "../core/errors";
+import { readEvents, tailEvents } from "../core/events";
+/**
+ * Parse `--since` accepting either a byte-offset cursor (`@offset:<int>`) for
+ * cross-process resumption, or a timestamp / epoch-ms (the existing form).
+ * Returns one of `{ sinceOffset }` or `{ since }`.
+ */
+function parseSinceFlag(since) {
+    if (since === undefined)
+        return {};
+    const trimmed = since.trim();
+    if (!trimmed) {
+        throw new UsageError("--since cannot be empty.", "INVALID_FLAG_VALUE");
+    }
+    if (trimmed.startsWith("@offset:")) {
+        const raw = trimmed.slice("@offset:".length);
+        const value = Number.parseInt(raw, 10);
+        if (Number.isNaN(value) || value < 0) {
+            throw new UsageError(`Invalid --since byte offset: "${since}". Expected @offset:<non-negative integer>.`, "INVALID_FLAG_VALUE");
+        }
+        return { sinceOffset: value };
+    }
+    return { since: normalizeSince(trimmed) };
+}
+function validateRef(ref) {
+    if (ref === undefined)
+        return undefined;
+    const trimmed = ref.trim();
+    if (!trimmed) {
+        throw new UsageError("--ref cannot be empty.", "INVALID_FLAG_VALUE");
+    }
+    parseAssetRef(trimmed);
+    return trimmed;
+}
+function normalizeSince(since) {
+    if (since === undefined)
+        return undefined;
+    const trimmed = since.trim();
+    if (!trimmed) {
+        throw new UsageError("--since cannot be empty.", "INVALID_FLAG_VALUE");
+    }
+    // Accept ISO timestamp (preferred), epoch ms, or plain date.
+    if (/^\d+$/.test(trimmed)) {
+        const ms = Number.parseInt(trimmed, 10);
+        const d = new Date(ms);
+        if (Number.isNaN(d.getTime())) {
+            throw new UsageError(`Invalid --since value: ${since}`, "INVALID_FLAG_VALUE");
+        }
+        return d.toISOString();
+    }
+    const parsed = new Date(trimmed);
+    if (Number.isNaN(parsed.getTime())) {
+        throw new UsageError(`Invalid --since value: ${since}. Expected ISO timestamp (e.g. 2026-04-01T00:00:00Z) or epoch ms.`, "INVALID_FLAG_VALUE");
+    }
+    return parsed.toISOString();
+}
+export function akmEventsList(options = {}) {
+    const ref = validateRef(options.ref);
+    const parsed = parseSinceFlag(options.since);
+    const result = readEvents({ since: parsed.since, sinceOffset: parsed.sinceOffset, type: options.type, ref }, options.ctx);
+    return {
+        schemaVersion: 1,
+        totalCount: result.events.length,
+        ...(ref !== undefined ? { ref } : {}),
+        ...(options.type !== undefined ? { type: options.type } : {}),
+        ...(parsed.since !== undefined ? { since: parsed.since } : {}),
+        ...(parsed.sinceOffset !== undefined ? { sinceOffset: parsed.sinceOffset } : {}),
+        nextOffset: result.nextOffset,
+        events: result.events,
+    };
+}
+export async function akmEventsTail(options = {}) {
+    const ref = validateRef(options.ref);
+    const parsed = parseSinceFlag(options.since);
+    const tailOptions = {
+        since: parsed.since,
+        sinceOffset: parsed.sinceOffset,
+        type: options.type,
+        ref,
+        intervalMs: options.intervalMs,
+        maxDurationMs: options.maxDurationMs,
+        maxEvents: options.maxEvents,
+        signal: options.signal,
+        onEvent: options.onEvent,
+    };
+    const result = await tailEvents(tailOptions, options.ctx);
+    return {
+        schemaVersion: 1,
+        totalCount: result.events.length,
+        ...(ref !== undefined ? { ref } : {}),
+        ...(options.type !== undefined ? { type: options.type } : {}),
+        ...(parsed.since !== undefined ? { since: parsed.since } : {}),
+        ...(parsed.sinceOffset !== undefined ? { sinceOffset: parsed.sinceOffset } : {}),
+        nextOffset: result.nextOffset,
+        events: result.events,
+        reason: result.reason,
+    };
+}

package/dist/src/commands/history.js

@@ -0,0 +1,120 @@
+/**
+ * `akm history` — surfaces internal mutation/usage events captured in the
+ * `usage_events` SQLite table for a single asset (`--ref`) or stash-wide.
+ *
+ * Backed by `usage_events` (search/show/feedback today). Richer per-asset
+ * lifecycle entries (add/edit/delete) require the events stream introduced
+ * in #204; this command surfaces whatever the indexer has captured so
+ * downstream tooling stops reinventing audit trails.
+ */
+import { parseAssetRef } from "../core/asset-ref";
+import { UsageError } from "../core/errors";
+import { closeDatabase, openDatabase } from "../indexer/db";
+import { ensureUsageEventsSchema } from "../indexer/usage-events";
+// ── Helpers ──────────────────────────────────────────────────────────────────
+function normalizeSince(since) {
+    // Accept "YYYY-MM-DD", "YYYY-MM-DDTHH:MM:SSZ", epoch ms, or anything Date can parse.
+    const trimmed = since.trim();
+    if (!trimmed) {
+        throw new UsageError("--since cannot be empty.", "INVALID_FLAG_VALUE");
+    }
+    // Pure-digit input → epoch milliseconds
+    if (/^\d+$/.test(trimmed)) {
+        const ms = Number.parseInt(trimmed, 10);
+        const d = new Date(ms);
+        if (Number.isNaN(d.getTime())) {
+            throw new UsageError(`Invalid --since value: ${since}`, "INVALID_FLAG_VALUE");
+        }
+        return d
+            .toISOString()
+            .replace("T", " ")
+            .replace(/\.\d+Z$/, "");
+    }
+    const parsed = new Date(trimmed);
+    if (Number.isNaN(parsed.getTime())) {
+        throw new UsageError(`Invalid --since value: ${since}. Expected ISO timestamp (e.g. 2026-04-01T00:00:00Z) or epoch ms.`, "INVALID_FLAG_VALUE");
+    }
+    // Match the "YYYY-MM-DD HH:MM:SS" format SQLite's datetime('now') stores.
+    return parsed
+        .toISOString()
+        .replace("T", " ")
+        .replace(/\.\d+Z$/, "");
+}
+function parseMetadata(raw) {
+    if (!raw)
+        return null;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return raw;
+    }
+}
+function toEntry(row) {
+    return {
+        id: row.id,
+        eventType: row.event_type,
+        ref: row.entry_ref,
+        entryId: row.entry_id,
+        query: row.query,
+        signal: row.signal,
+        metadata: parseMetadata(row.metadata),
+        createdAt: row.created_at,
+    };
+}
+// ── Main ─────────────────────────────────────────────────────────────────────
+/**
+ * Read mutation/usage history. When `ref` is provided, results are filtered to
+ * that asset (validated via `parseAssetRef`). Always returns chronological
+ * order (oldest first) so consumers can display a lifecycle trail.
+ */
+export async function akmHistory(options = {}) {
+    let normalizedRef;
+    if (options.ref !== undefined) {
+        const trimmed = options.ref.trim();
+        if (!trimmed) {
+            throw new UsageError("--ref cannot be empty.", "INVALID_FLAG_VALUE");
+        }
+        // Validate the ref grammar; we still query by exact entry_ref string so
+        // the user gets back exactly what they asked for.
+        parseAssetRef(trimmed);
+        normalizedRef = trimmed;
+    }
+    const sinceNormalized = options.since !== undefined ? normalizeSince(options.since) : undefined;
+    const db = options.db ?? openDatabase();
+    const ownsDb = options.db === undefined;
+    try {
+        // The schema is normally created during `akm index`; ensure it exists so
+        // `akm history` works on a freshly-initialised stash that has never been
+        // indexed (and just returns an empty list rather than an error).
+        ensureUsageEventsSchema(db);
+        const conditions = [];
+        const params = [];
+        if (normalizedRef !== undefined) {
+            conditions.push("entry_ref = ?");
+            params.push(normalizedRef);
+        }
+        if (sinceNormalized !== undefined) {
+            conditions.push("created_at >= ?");
+            params.push(sinceNormalized);
+        }
+        const where = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
+        const sql = `SELECT id, event_type, query, entry_id, entry_ref, signal, metadata, created_at
+                 FROM usage_events ${where}
+                 ORDER BY id ASC`;
+        const rows = db.prepare(sql).all(...params);
+        const entries = rows.map(toEntry);
+        const response = {
+            schemaVersion: 1,
+            ...(normalizedRef !== undefined ? { ref: normalizedRef } : {}),
+            ...(sinceNormalized !== undefined ? { since: sinceNormalized } : {}),
+            totalCount: entries.length,
+            entries,
+        };
+        return response;
+    }
+    finally {
+        if (ownsDb)
+            closeDatabase(db);
+    }
+}

package/dist/{commands → src/commands}/installed-stashes.js

@@ -6,7 +6,7 @@
  */
 import fs from "node:fs";
 import path from "node:path";
-import { resolveStashDir } from "../core/common";
+import { isWithin, resolveStashDir } from "../core/common";
 import { loadConfig } from "../core/config";
 import { NotFoundError, UsageError } from "../core/errors";
 import { akmIndex } from "../indexer/indexer";
@@ -14,6 +14,7 @@ import { removeLockEntry, upsertLockEntry } from "../integrations/lockfile";
 import { parseRegistryRef } from "../registry/resolve";
 import { syncFromRef } from "../sources/providers/sync-from-ref";
 import { ensureWebsiteMirror } from "../sources/providers/website";
+import { listWikis, resolveWikisRoot } from "../wiki/wiki";
 import { auditInstallCandidate, deriveRegistryLabels, enforceRegistryInstallPolicy, formatInstallAuditFailure, } from "./install-audit";
 import { removeInstalledRegistryEntry, upsertInstalledRegistryEntry } from "./source-add";
 import { removeStash } from "./source-manage";
@@ -57,6 +58,31 @@ export async function akmListSources(input) {
             status: { exists: directoryExists(entry.stashRoot) },
         });
     }
+    if (!kindFilter || kindFilter.includes("filesystem")) {
+        const wikisRoot = resolveWikisRoot(stashDir);
+        const seenPaths = new Set(sources
+            .map((source) => source.path)
+            .filter((sourcePath) => typeof sourcePath === "string")
+            .map((sourcePath) => path.resolve(sourcePath)));
+        for (const wiki of listWikis(stashDir)) {
+            // `listWikis()` also includes externally-registered wikis. `akm list`
+            // should synthesize source entries here only for stash-owned wiki dirs.
+            if (!isWithin(wiki.path, wikisRoot))
+                continue;
+            const resolvedPath = path.resolve(wiki.path);
+            if (seenPaths.has(resolvedPath))
+                continue;
+            seenPaths.add(resolvedPath);
+            sources.push({
+                name: wiki.name,
+                kind: "filesystem",
+                wiki: wiki.name,
+                path: wiki.path,
+                writable: true,
+                status: { exists: directoryExists(wiki.path) },
+            });
+        }
+    }
     return {
         schemaVersion: 1,
         stashDir,
@@ -307,7 +333,7 @@ function selectTargets(installed, target, all) {
         }
         throw new UsageError(`"${target}" is a local directory — it reflects your files in place. To refresh the search index, run: akm index`, "TARGET_NOT_UPDATABLE");
     }
-    throw new NotFoundError(`No matching source for target: ${target}`);
+    throw new NotFoundError(`No matching source for target: ${target}`, "SOURCE_NOT_FOUND");
 }
 function tryResolveInstalledTarget(installed, target) {
     const byId = installed.find((entry) => entry.id === target);