akm-cli 0.8.0 → 0.8.2

package/dist/commands/improve-profiles.js

@@ -1,6 +1,11 @@
 // This Source Code Form is subject to the terms of the Mozilla Public
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
+import profileDefault from "../assets/profiles/default.json" with { type: "json" };
+import profileGraphRefresh from "../assets/profiles/graph-refresh.json" with { type: "json" };
+import profileMemoryFocus from "../assets/profiles/memory-focus.json" with { type: "json" };
+import profileQuick from "../assets/profiles/quick.json" with { type: "json" };
+import profileThorough from "../assets/profiles/thorough.json" with { type: "json" };
 import { parseAssetRef } from "../core/asset-ref";
 import { warn } from "../core/warn";
 /** Profile name used as the final fallback when nothing else resolves. */
@@ -11,66 +16,15 @@ export const DEFAULT_ALLOWED_TYPES = {
     distill: ["memory"],
     consolidate: ["memory"],
 };
+// Built-in profiles are loaded from embedded JSON files in src/assets/profiles/.
+// To add a new profile: create a new .json file there, import it above, and add
+// it to this map. No code change needed beyond those two steps.
 const BUILTIN_PROFILES = {
-    default: {
-        description: "Standard improve pass — all sub-processes, markdown asset types.",
-        processes: {
-            reflect: { enabled: true, allowedTypes: DEFAULT_ALLOWED_TYPES.reflect },
-            distill: { enabled: true, allowedTypes: DEFAULT_ALLOWED_TYPES.distill },
-            consolidate: { enabled: true, allowedTypes: DEFAULT_ALLOWED_TYPES.consolidate },
-            memoryInference: { enabled: true },
-            graphExtraction: { enabled: true },
-            // validation: deliberately undefined — third-tier classifier is opt-in.
-            triage: { enabled: false, applyMode: "queue", policy: "personal-stash" },
-        },
-        sync: { enabled: true, push: true },
-    },
-    quick: {
-        description: "Reflect-only pass — no distill, consolidate, memoryInference, or graphExtraction.",
-        processes: {
-            reflect: { enabled: true, allowedTypes: DEFAULT_ALLOWED_TYPES.reflect },
-            distill: { enabled: false },
-            consolidate: { enabled: false },
-            memoryInference: { enabled: false },
-            graphExtraction: { enabled: false },
-            triage: { enabled: false },
-        },
-        // Lightweight passes opt out of end-of-run sync: a reflect-only `quick`
-        // run should not auto-commit/push the git-backed stash to its remote.
-        // (The auto-sync gate in improve.ts treats an absent sync block as
-        // ENABLED + push, so we set this explicitly to avoid a surprise push.)
-        sync: { enabled: false },
-    },
-    thorough: {
-        // Reserved for future divergence; for now behaviorally identical to
-        // `default`. Documented here so callers picking `--profile thorough` do
-        // not expect a different code path until we wire stricter limits in.
-        description: "All sub-processes enabled (currently identical to default; reserved for future divergence).",
-        processes: {
-            reflect: { enabled: true, allowedTypes: DEFAULT_ALLOWED_TYPES.reflect },
-            distill: { enabled: true, allowedTypes: DEFAULT_ALLOWED_TYPES.distill },
-            consolidate: { enabled: true, allowedTypes: DEFAULT_ALLOWED_TYPES.consolidate },
-            memoryInference: { enabled: true },
-            graphExtraction: { enabled: true },
-            triage: { enabled: true, applyMode: "queue" },
-        },
-        sync: { enabled: true, push: true },
-    },
-    "memory-focus": {
-        description: "Memory and lesson improvement only — no distill or consolidate.",
-        processes: {
-            reflect: { enabled: true, allowedTypes: ["memory", "lesson"] },
-            distill: { enabled: false },
-            consolidate: { enabled: false },
-            memoryInference: { enabled: true },
-            graphExtraction: { enabled: false },
-            triage: { enabled: false },
-        },
-        // Limited pass opts out of end-of-run sync for the same reason as `quick`:
-        // a memory/lesson-only run should not auto-commit/push the stash. Explicit
-        // here because improve.ts treats an absent sync block as ENABLED + push.
-        sync: { enabled: false },
-    },
+    default: profileDefault,
+    quick: profileQuick,
+    thorough: profileThorough,
+    "memory-focus": profileMemoryFocus,
+    "graph-refresh": profileGraphRefresh,
 };
 /**
  * Default enabled-state for known improve processes when neither the user

package/dist/commands/improve-result-file.js

@@ -73,14 +73,19 @@ export function relativeImproveResultPath(runId) {
  * (closes the dry-run/real-run artifact-trap recorded in MEMORY.md
  * `feedback_akm_dryrun_artifact_trap`).
  */
-export function writeImproveResultFile(stashDir, runId, result) {
+export function writeImproveResultFile(stashDir, runId, result, startedAt) {
     const db = openStateDatabase();
     try {
-        const startedAt = new Date().toISOString();
+        const completedAt = new Date().toISOString();
+        // startedAt is the ISO timestamp captured at process launch (passed from the
+        // CLI entry point). If omitted, fall back to the run-id's embedded timestamp
+        // so started_at != completed_at even on older call sites.
+        const resolvedStartedAt = startedAt ??
+            runId.slice(0, 24).replace(/^(\d{4}-\d{2}-\d{2}T)(\d{2})-(\d{2})-(\d{2})-(\d{3})Z$/, "$1$2:$3:$4.$5Z");
         recordImproveRun(db, {
             id: runId,
-            startedAt,
-            completedAt: startedAt,
+            startedAt: resolvedStartedAt,
+            completedAt,
             stashDir,
             dryRun: Boolean(result.dryRun),
             profile: null,

package/dist/commands/improve.js

@@ -25,7 +25,7 @@ import { resolveAssetPath } from "../indexer/path-resolver";
 import { getWritableStashDirs, resolveSourceEntries } from "../indexer/search-source";
 import { runStalenessDetectionPass } from "../indexer/staleness-detect";
 import { resolveImproveProcessRunnerFromProfile, resolveTriageJudgmentRunner } from "../integrations/agent/runner";
-import { getAvailableHarnesses, getExecutionLogCandidates } from "../integrations/session-logs";
+import { getAvailableHarnesses } from "../integrations/session-logs";
 import { isLlmFeatureEnabled, isProcessEnabled } from "../llm/feature-gate";
 import { isGitBackedStash, resolveWritableOverride, saveGitStash } from "../sources/providers/git";
 import { akmConsolidate } from "./consolidate";
@@ -36,8 +36,8 @@ import { akmExtract } from "./extract";
 import { makeGateConfig, resolveExtractConfidence, runAutoAcceptGate } from "./improve-auto-accept";
 import { isProfileFilteredForAllPasses, resolveImproveProfile, resolveProcessEnabled, shouldSkipRef, } from "./improve-profiles";
 import { akmLint } from "./lint/index";
-import { drainProposals } from "./proposal-drain";
-import { resolveDrainPolicy } from "./proposal-drain-policies";
+import { drainProposals } from "./proposal/drain";
+import { resolveDrainPolicy } from "./proposal/drain-policies";
 import { akmReflect } from "./reflect";
 import { runSchemaRepairPass } from "./schema-repair";
 import { checkDeadUrls } from "./url-checker";
@@ -674,7 +674,13 @@ export async function akmImprove(options = {}) {
     // lives in the outer scope. It is always assigned at the top of the try.
     let eventsCtx = {};
     try {
-        const budgetTimer = setTimeout(() => budgetAbortController.abort("improve budget exhausted"), budgetMs);
+        const budgetTimer = setTimeout(() => {
+            budgetAbortController.abort("improve budget exhausted");
+            // Grace period: let finally run to release improve.lock, then hard-exit
+            // to prevent the process outliving the task timeout window (lock-cascade fix).
+            // Exit 0: budget exhaustion is a normal scheduled-task condition, not an error.
+            setTimeout(() => process.exit(0), 5_000);
+        }, budgetMs);
         // Clear the timer when the run ends to avoid keeping the event loop alive.
         clearBudgetTimer = () => clearTimeout(budgetTimer);
         try {
@@ -724,7 +730,7 @@ export async function akmImprove(options = {}) {
                 rejectedProposalsByRef.set(e.ref, e);
             }
         }
-        const { reflectsWithErrorContext, memoryRefsForInference, gateAutoAcceptedCount: loopGateCount, } = await runImproveLoopStage({
+        const { reflectsWithErrorContext, memoryRefsForInference, gateAutoAcceptedCount: loopGateCount, gateAutoAcceptFailedCount: loopGateFailedCount, } = await runImproveLoopStage({
             scope,
             options,
             primaryStashDir,
@@ -743,7 +749,7 @@ export async function akmImprove(options = {}) {
             eventsCtx,
             improveProfile,
         });
-        const { allWarnings, consolidation, deadUrls, memoryInference, graphExtraction, stalenessDetection, maintenanceActions, memoryInferenceDurationMs, graphExtractionDurationMs, orphansPurged, proposalsExpired, gateAutoAcceptedCount: postLoopGateCount, } = await runImprovePostLoopStage({
+        const { allWarnings, consolidation, deadUrls, memoryInference, graphExtraction, stalenessDetection, maintenanceActions, memoryInferenceDurationMs, graphExtractionDurationMs, orphansPurged, proposalsExpired, gateAutoAcceptedCount: postLoopGateCount, gateAutoAcceptFailedCount: postLoopGateFailedCount, } = await runImprovePostLoopStage({
             scope,
             options,
             primaryStashDir,
@@ -798,9 +804,6 @@ export async function akmImprove(options = {}) {
             ...(preparation.lintSummary !== undefined ? { lintSummary: preparation.lintSummary } : {}),
             ...(preparation.memoryIndexHealth !== undefined ? { memoryIndexHealth: preparation.memoryIndexHealth } : {}),
             ...(preparation.coverageGaps.length > 0 ? { coverageGaps: preparation.coverageGaps } : {}),
-            ...(preparation.executionLogCandidates.length > 0
-                ? { executionLogCandidates: preparation.executionLogCandidates }
-                : {}),
             ...(preparation.extract && preparation.extract.length > 0 ? { extract: preparation.extract } : {}),
             ...(primaryStashDir !== undefined ? { evalCasesWritten: countEvalCases(primaryStashDir) } : {}),
             ...(deadUrls !== undefined && deadUrls.length > 0 ? { deadUrls } : {}),
@@ -831,6 +834,10 @@ export async function akmImprove(options = {}) {
                 const t = preparation.gateAutoAcceptedCount + loopGateCount + postLoopGateCount;
                 return t > 0 ? { gateAutoAcceptedCount: t } : {};
             })(),
+            ...(() => {
+                const f = preparation.gateAutoAcceptFailedCount + loopGateFailedCount + postLoopGateFailedCount;
+                return f > 0 ? { gateAutoAcceptFailedCount: f } : {};
+            })(),
         };
         if (!result.dryRun)
             emitImproveCompletedEvent(result, {
@@ -990,7 +997,6 @@ function emitImproveCompletedEvent(result, durations, eventsCtx) {
             reflectSkippedActions: actionCounts.reflectSkipped,
             reflectsWithErrorContext: result.reflectsWithErrorContext ?? 0,
             coverageGapCount: result.coverageGaps?.length ?? 0,
-            executionLogCandidateCount: result.executionLogCandidates?.length ?? 0,
             evalCasesWritten: result.evalCasesWritten ?? 0,
             deadUrlCount: result.deadUrls?.length ?? 0,
             memoryEligible: result.memorySummary.eligible,
@@ -1047,15 +1053,6 @@ async function runImprovePreparationStage(args) {
             }
         }
     }
-    // Phase 0 — execution log synthesis
-    let executionLogCandidates = [];
-    try {
-        const logEntries = getExecutionLogCandidates(7);
-        executionLogCandidates = logEntries.filter((e) => e.isFailurePattern).map((e) => e.topic);
-    }
-    catch {
-        // best-effort
-    }
     // Phase 0.4 — session-extract pass.
     //
     // Reads native session files (claude-code JSONL, opencode storage tree)
@@ -1074,6 +1071,7 @@ async function runImprovePreparationStage(args) {
     // The extract envelope's own `warnings` field surfaces what went wrong.
     let extractResults;
     let gateAutoAcceptedCount = 0;
+    let gateAutoAcceptFailedCount = 0;
     const extractConfig = options.config ?? loadConfig();
     const extractGateCfg = makeGateConfig("extract", {
         globalThreshold: options.autoAccept,
@@ -1095,12 +1093,16 @@ async function runImprovePreparationStage(args) {
                         dryRun: options.dryRun ?? false,
                     });
                     extractResults.push(result);
-                    gateAutoAcceptedCount += (await runAutoAcceptGate(primaryStashDir
-                        ? result.proposals.map((proposalId) => {
-                            const proposal = getProposal(primaryStashDir, proposalId);
-                            return { proposalId, confidence: resolveExtractConfidence(proposal) };
-                        })
-                        : [], extractGateCfg)).promoted.length;
+                    {
+                        const gr = await runAutoAcceptGate(primaryStashDir
+                            ? result.proposals.map((proposalId) => {
+                                const proposal = getProposal(primaryStashDir, proposalId);
+                                return { proposalId, confidence: resolveExtractConfidence(proposal) };
+                            })
+                            : [], extractGateCfg);
+                        gateAutoAcceptedCount += gr.promoted.length;
+                        gateAutoAcceptFailedCount += gr.failed.length;
+                    }
                 }
                 catch (err) {
                     const msg = err instanceof Error ? err.message : String(err);
@@ -1126,7 +1128,9 @@ async function runImprovePreparationStage(args) {
                 proposalId: p.id,
                 confidence: resolveExtractConfidence(p),
             }));
-            gateAutoAcceptedCount += (await runAutoAcceptGate(backlogCandidates, extractGateCfg)).promoted.length;
+            const backlogGr = await runAutoAcceptGate(backlogCandidates, extractGateCfg);
+            gateAutoAcceptedCount += backlogGr.promoted.length;
+            gateAutoAcceptFailedCount += backlogGr.failed.length;
         }
     }
     // eligibleCount = raw pre-filter count (before cooldown/signal/cleanup filters).
@@ -1539,7 +1543,6 @@ async function runImprovePreparationStage(args) {
         cleanupWarnings,
         appliedCleanup,
         memoryIndexHealth,
-        executionLogCandidates,
         extract: extractResults,
         actionableRefs,
         signalBearingSet,
@@ -1553,6 +1556,7 @@ async function runImprovePreparationStage(args) {
         recentErrors,
         utilityMap,
         gateAutoAcceptedCount,
+        gateAutoAcceptFailedCount,
     };
 }
 // TODO(refactor): 13 args including `actions`/`recentErrors` mutation channels. Restructure into immutable plan + mutable context objects — deferred to dedicated refactor with isolated testing.
@@ -1636,6 +1640,7 @@ async function runImproveLoopStage(args) {
         ? listProposals(dedupeStashDirForProposals, { status: "pending" }).map((p) => p.ref)
         : []);
     let gateAutoAcceptedCount = 0;
+    let gateAutoAcceptFailedCount = 0;
     const reflectGateCfg = makeGateConfig("reflect", {
         globalThreshold: options.autoAccept,
         dryRun: options.dryRun ?? false,
@@ -1812,7 +1817,9 @@ async function runImproveLoopStage(args) {
                         },
                     }, eventsCtx);
                     if (reflectResult.ok) {
-                        gateAutoAcceptedCount += (await runAutoAcceptGate([{ proposalId: reflectResult.proposal.id, confidence: reflectResult.proposal.confidence }], reflectGateCfg)).promoted.length;
+                        const reflectGr = await runAutoAcceptGate([{ proposalId: reflectResult.proposal.id, confidence: reflectResult.proposal.confidence }], reflectGateCfg);
+                        gateAutoAcceptedCount += reflectGr.promoted.length;
+                        gateAutoAcceptFailedCount += reflectGr.failed.length;
                     }
                 } // end else (reflect type/profile check)
             }
@@ -1923,7 +1930,9 @@ async function runImproveLoopStage(args) {
                 });
                 actions.push({ ref: planned.ref, mode: "distill", result: distillResult });
                 if (distillResult.outcome === "queued" && distillResult.proposal) {
-                    gateAutoAcceptedCount += (await runAutoAcceptGate([{ proposalId: distillResult.proposal.id, confidence: distillResult.proposal.confidence }], distillGateCfg)).promoted.length;
+                    const distillGr = await runAutoAcceptGate([{ proposalId: distillResult.proposal.id, confidence: distillResult.proposal.confidence }], distillGateCfg);
+                    gateAutoAcceptedCount += distillGr.promoted.length;
+                    gateAutoAcceptFailedCount += distillGr.failed.length;
                 }
                 if (parsedPlannedRef.type === "memory") {
                     const promotedToKnowledge = distillResult.outcome === "queued" && distillResult.proposalKind === "knowledge";
@@ -1996,7 +2005,7 @@ async function runImproveLoopStage(args) {
         completedCount++;
         info(`[improve] ${completedCount}/${loopRefs.length} ${planned.ref}`);
     }
-    return { reflectsWithErrorContext, memoryRefsForInference, gateAutoAcceptedCount };
+    return { reflectsWithErrorContext, memoryRefsForInference, gateAutoAcceptedCount, gateAutoAcceptFailedCount };
 }
 async function runImprovePostLoopStage(args) {
     const { scope, options, primaryStashDir, actionableRefs, appliedCleanup, cleanupWarnings, memorySummary, memoryRefsForInference, reindexFn, eventsCtx, budgetSignal, improveProfile, } = args;
@@ -2092,6 +2101,7 @@ async function runImprovePostLoopStage(args) {
         durationMs: 0,
     };
     let gateAutoAcceptedCount = 0;
+    let gateAutoAcceptFailedCount = 0;
     const consolidateGateCfg = makeGateConfig("consolidate", {
         globalThreshold: options.autoAccept,
         dryRun: options.dryRun ?? false,
@@ -2111,13 +2121,16 @@ async function runImprovePostLoopStage(args) {
             // Tie consolidate proposals back to this improve invocation so
             // accept-rate-per-run aggregation works. Mirrors reflect/propose/extract.
             sourceRun: `consolidate-${Date.now()}`,
-            // Incremental consolidation: in steady state (not bootstrap, not volume-
-            // triggered) pass the last-consolidation timestamp so akmConsolidate skips
-            // chunks with no memory changed since then. Converts consolidation cost
-            // from O(pool) to O(changed clusters) — the fix for the rising p95 tail
-            // where full-pool re-judging produced 5–10 min runs that promoted ~0.
-            // undefined → full pass (bootstrap, or volume-triggered large-pool sweep).
-            incrementalSince: volumeTriggered ? undefined : lastConsolidateTs,
+            // Incremental consolidation: pass the last-consolidation timestamp so
+            // akmConsolidate skips chunks with no memory changed since then. Converts
+            // consolidation cost from O(pool) to O(changed clusters) — the fix for
+            // the rising p95 tail where full-pool re-judging produced 5–10 min runs
+            // that promoted ~0. undefined → full pass on first-ever run (bootstrap).
+            // volumeTriggered correctly forces the run past cooldown but must NOT
+            // override incrementalSince — the stash has ~1400 eligible memories so
+            // volumeTriggered=true on every run, permanently forcing full 12-chunk
+            // scans (~264s) instead of the intended 1-2 chunk incremental path (~44s).
+            incrementalSince: lastConsolidateTs,
             maxChunkSize: improveProfile?.processes?.consolidate?.maxChunkSize,
             // Honor profile.autoAccept (already merged into options.autoAccept at the
             // top of akmImprove). The CLI parser always supplies 90 when --auto-accept
@@ -2127,17 +2140,21 @@ async function runImprovePostLoopStage(args) {
             // still wins because the spread above runs first.
             autoAccept: options.consolidateOptions?.autoAccept ?? options.autoAccept,
         });
-        gateAutoAcceptedCount += (await runAutoAcceptGate(consolidation.promoted.map((proposalId) => {
-            try {
-                if (!primaryStashDir)
+        {
+            const consolidateGr = await runAutoAcceptGate(consolidation.promoted.map((proposalId) => {
+                try {
+                    if (!primaryStashDir)
+                        return { proposalId, confidence: undefined };
+                    const proposal = getProposal(primaryStashDir, proposalId);
+                    return { proposalId, confidence: proposal.confidence };
+                }
+                catch {
                     return { proposalId, confidence: undefined };
-                const proposal = getProposal(primaryStashDir, proposalId);
-                return { proposalId, confidence: proposal.confidence };
-            }
-            catch {
-                return { proposalId, confidence: undefined };
-            }
-        }), consolidateGateCfg)).promoted.length;
+                }
+            }), consolidateGateCfg);
+            gateAutoAcceptedCount += consolidateGr.promoted.length;
+            gateAutoAcceptFailedCount += consolidateGr.failed.length;
+        }
         if (consolidation.processed > 0) {
             appendEvent({
                 eventType: "consolidate_completed",
@@ -2212,6 +2229,7 @@ async function runImprovePostLoopStage(args) {
         orphansPurged: maintenanceResult.orphansPurged,
         proposalsExpired: maintenanceResult.proposalsExpired,
         gateAutoAcceptedCount,
+        gateAutoAcceptFailedCount,
     };
 }
 // TODO(refactor): mutates the passed-in `allWarnings` array as a hidden side channel. Return warnings in ImproveMaintenanceResult and merge in caller — invasive signature change deferred to next refactor pass.
@@ -2287,25 +2305,25 @@ async function runImproveMaintenancePasses(args) {
         }
         const graphEnabled = isProcessEnabled("index", "graph_extraction", config);
         const graphExtractionDisabledByProfile = improveProfile?.processes?.graphExtraction?.enabled === false;
+        const graphExtractionFullScan = improveProfile?.processes?.graphExtraction?.fullScan === true;
         // Build the set of refs actually touched this run.
         const touchedRefs = new Set();
         for (const r of args.actionableRefs)
             touchedRefs.add(r.ref);
         for (const r of memoryRefsForInference)
             touchedRefs.add(r);
-        // INVARIANT: graph extraction must never run on the full corpus from the
-        // improve post-loop. Full-corpus scans belong in `akm index`. We enforce
-        // this by ALWAYS passing `candidatePaths` (possibly an empty Set) to the
-        // extractor — never `undefined`. With an empty Set, the extractor's
-        // filter (graph-extraction.ts ~L452) rejects every file and returns the
-        // empty result without scanning. The pass is still invoked so that the
-        // action is recorded, the D9 post-consolidation reindex still fires, and
-        // mock injection (graphExtractionFn) used by tests stays exercised.
+        // INVARIANT: graph extraction normally runs only on files touched by
+        // actionable refs (candidatePaths). Full-corpus scans are opt-in via
+        // profile.processes.graphExtraction.fullScan = true (used by the
+        // `graph-refresh` built-in profile and its weekly scheduled task).
+        // The empty-Set fallback is intentional when no refs were touched —
+        // the extractor's filter rejects every file and returns empty, keeping
+        // the pass invoked so the action is recorded and tests stay exercised.
         if (graphExtractionDisabledByProfile) {
             info("[improve] graph extraction skipped (disabled by improve profile)");
         }
         else if (sources.length > 0 && graphEnabled) {
-            info("[improve] graph extraction starting");
+            info(`[improve] graph extraction starting${graphExtractionFullScan ? " (full-corpus scan)" : ""}`);
             const extractionStart = Date.now();
             try {
                 // D9: if consolidation ran but memory inference did not reindex, force a reindex
@@ -2325,15 +2343,18 @@ async function runImproveMaintenancePasses(args) {
                     closeDatabase(db);
                     db = openDatabase(getDbPath(), config.embedding?.dimension ? { embeddingDim: config.embedding.dimension } : undefined);
                 }
-                // Resolve touched refs to absolute file paths. Empty Set is intentional
-                // when no refs were touched — see INVARIANT above.
-                const candidatePaths = new Set();
-                if (primaryStashDir && touchedRefs.size > 0) {
-                    const writableDirSet = new Set(getWritableStashDirs(primaryStashDir).map((d) => path.resolve(d)));
-                    const resolved = await Promise.all([...touchedRefs].map((ref) => findAssetFilePath(ref, primaryStashDir, writableDirSet).catch(() => null)));
-                    for (const p of resolved) {
-                        if (typeof p === "string" && p.length > 0)
-                            candidatePaths.add(p);
+                // Resolve touched refs to absolute file paths. Skipped for fullScan
+                // (candidatePaths stays undefined → extractor processes all files).
+                let candidatePaths;
+                if (!graphExtractionFullScan) {
+                    candidatePaths = new Set();
+                    if (primaryStashDir && touchedRefs.size > 0) {
+                        const writableDirSet = new Set(getWritableStashDirs(primaryStashDir).map((d) => path.resolve(d)));
+                        const resolved = await Promise.all([...touchedRefs].map((ref) => findAssetFilePath(ref, primaryStashDir, writableDirSet).catch(() => null)));
+                        for (const p of resolved) {
+                            if (typeof p === "string" && p.length > 0)
+                                candidatePaths.add(p);
+                        }
                     }
                 }
                 const progressHandler = (event) => {

package/dist/commands/info.js

@@ -46,8 +46,11 @@ export function assembleInfo(options) {
         ...(s.url ? { url: s.url } : {}),
         ...(s.enabled !== undefined ? { enabled: s.enabled } : {}),
     }));
-    // Index stats
-    const indexStats = readIndexStats(options?.dbPath);
+    // Index stats — resolve the DB path from config so info reads the same
+    // database that health and search use, rather than a bare getDbPath() call
+    // that ignores XDG_DATA_HOME or per-config overrides.
+    const resolvedDbPath = options?.dbPath ?? getDbPath();
+    const indexStats = readIndexStats(resolvedDbPath);
     return {
         schemaVersion: 1,
         version: pkgVersion,
@@ -64,38 +67,30 @@ export function assembleInfo(options) {
         indexStats,
     };
 }
-function readIndexStats(dbPath) {
-    const resolvedPath = dbPath ?? getDbPath();
-    // If no index file exists, return zeros
-    if (!fs.existsSync(resolvedPath)) {
-        return {
-            entryCount: 0,
-            lastBuiltAt: null,
-            hasEmbeddings: false,
-            vecAvailable: false,
-        };
-    }
+function readIndexStats(resolvedPath) {
+    const EMPTY = {
+        entryCount: 0,
+        lastBuiltAt: null,
+        hasEmbeddings: false,
+        vecAvailable: false,
+    };
+    if (!fs.existsSync(resolvedPath))
+        return EMPTY;
     let db;
     try {
         db = openExistingDatabase(resolvedPath);
-        const entryCount = getEntryCount(db);
-        const lastBuiltAt = getMeta(db, "builtAt") ?? null;
-        const vecAvailable = isVecAvailable(db);
-        const hasEmbeddings = getMeta(db, "hasEmbeddings") === "1";
         return {
-            entryCount,
-            lastBuiltAt,
-            hasEmbeddings,
-            vecAvailable,
+            entryCount: getEntryCount(db),
+            lastBuiltAt: getMeta(db, "builtAt") ?? null,
+            hasEmbeddings: getMeta(db, "hasEmbeddings") === "1",
+            vecAvailable: isVecAvailable(db),
         };
     }
-    catch {
-        return {
-            entryCount: 0,
-            lastBuiltAt: null,
-            hasEmbeddings: false,
-            vecAvailable: false,
-        };
+    catch (err) {
+        // Surface the error so operators can diagnose mismatches between
+        // `akm info` and `akm health` rather than silently returning zeros.
+        process.stderr.write(`[akm info] failed to read index stats from ${resolvedPath}: ${String(err)}\n`);
+        return EMPTY;
     }
     finally {
         if (db) {

package/dist/commands/init.js

@@ -14,7 +14,8 @@ import { TYPE_DIRS } from "../core/asset-spec";
 import { loadUserConfig, saveConfig } from "../core/config";
 import { ConfigError } from "../core/errors";
 import { assertSafeStashDir, getBinDir, getConfigPath, getDefaultStashDir } from "../core/paths";
-import { ensureRg } from "../setup/ripgrep-install";
+import { ensureRg } from "../core/ripgrep/install";
+import { copyStashSkeleton, scaffoldStashMeta } from "./stash-skeleton";
 /**
  * Refuse to persist a temporary-directory stashDir to the user's config when
  * running under a test runner AND `--dir <tempdir>` was passed explicitly.
@@ -74,6 +75,10 @@ export async function akmInit(options) {
     }
     // Ensure the default stash is a local git repo (no remote required)
     ensureGitRepo(stashDir);
+    if (created) {
+        copyStashSkeleton(stashDir);
+        scaffoldStashMeta(stashDir);
+    }
     // Persist stashDir in config.json
     const configPath = getConfigPath();
     const existing = loadUserConfig();

package/dist/commands/{proposal-drain-policies.js → proposal/drain-policies.js}

@@ -16,8 +16,8 @@
  */
 import fs from "node:fs";
 import { z } from "zod";
-import { UsageError } from "../core/errors";
-import { PROPOSAL_SOURCES } from "../core/proposals";
+import { UsageError } from "../../core/errors";
+import { PROPOSAL_SOURCES } from "../../core/proposals";
 // Valid `generator` values for a drain rule are exactly the canonical proposal
 // `source` values (see {@link PROPOSAL_SOURCES} in src/core/proposals.ts). The
 // engine matches rules via `policy.accept.find(r => r.generator === proposal.source)`,

package/dist/commands/{proposal-drain.js → proposal/drain.js}

@@ -36,16 +36,16 @@
  */
 import fs from "node:fs";
 import path from "node:path";
-import { parseAssetRef } from "../core/asset-ref";
-import { resolveAssetPathFromName, TYPE_DIRS } from "../core/asset-spec";
-import { appendEvent } from "../core/events";
-import { parseFrontmatter } from "../core/frontmatter";
-import { listProposals } from "../core/proposals";
-import { info, warn } from "../core/warn";
-import { runAgent } from "../integrations/agent";
-import { runOpencodeSdk } from "../integrations/agent/sdk-runner";
-import { chatCompletion, stripJsonFences } from "../llm/client";
-import { akmProposalAccept, akmProposalReject } from "./proposal";
+import { parseAssetRef } from "../../core/asset-ref";
+import { resolveAssetPathFromName, TYPE_DIRS } from "../../core/asset-spec";
+import { appendEvent } from "../../core/events";
+import { parseFrontmatter } from "../../core/frontmatter";
+import { listProposals } from "../../core/proposals";
+import { info, warn } from "../../core/warn";
+import { runAgent } from "../../integrations/agent";
+import { runOpencodeSdk } from "../../integrations/agent/sdk-runner";
+import { chatCompletion, stripJsonFences } from "../../llm/client";
+import { akmProposalAccept, akmProposalReject } from "../proposal";
 // ---------------------------------------------------------------------------
 // Content helpers
 // ---------------------------------------------------------------------------

package/dist/commands/show.js

@@ -24,6 +24,7 @@ import { loadConfig } from "../core/config";
 import { NotFoundError, rethrowIfTestIsolationError, UsageError } from "../core/errors";
 import { appendEvent, readEvents } from "../core/events";
 import { parseFrontmatter } from "../core/frontmatter";
+import { META_DIR, parseMetaRef, resolveMetaFilePath } from "../core/stash-meta";
 import { closeDatabase, findEntryIdByRef, openExistingDatabase } from "../indexer/db";
 import { ensureIndex } from "../indexer/ensure-index";
 import { buildFileContext, buildRenderContext, getRenderer, runMatchers } from "../indexer/file-context";
@@ -105,6 +106,16 @@ function resolveRegisteredWikiAssetPath(wikiRoot, wikiName, assetName) {
  */
 export async function akmShowUnified(input) {
     const ref = input.ref.trim();
+    // 0a. Stash `.meta/` convention: `[origin//]meta[:name]` direct-reads a
+    //     human-authored orientation doc from the stash's `.meta/` directory.
+    //     These files are not indexed (the walker skips dot-dirs), so they are
+    //     resolved here before the index lookup and the `type:name` parser,
+    //     which would otherwise reject the non-asset-type `meta`.
+    {
+        const metaRef = parseMetaRef(ref);
+        if (metaRef)
+            return showStashMeta(metaRef);
+    }
     // 0. Wiki-root shortcut: `wiki:<name>` with no page path routes to the
     //    wiki summary (same payload as `akm wiki show <name>`). Honour
     //    `parsed.origin` by resolving against the matching stash source(s),
@@ -152,6 +163,42 @@ export async function akmShowUnified(input) {
     }
     return result;
 }
+/**
+ * Resolve a stash `.meta/` doc and return it as a lightweight ShowResponse.
+ *
+ * With no origin the working stash (and other configured sources, in order)
+ * is searched and the first hit wins. With an origin the lookup is narrowed
+ * to that stash; an uninstalled origin yields an actionable "not installed"
+ * error. The file is read directly from disk — `.meta/` is never indexed.
+ */
+async function showStashMeta(metaRef) {
+    const allSources = resolveSourceEntries();
+    const sources = resolveSourcesForOrigin(metaRef.origin, allSources);
+    if (metaRef.origin && sources.length === 0) {
+        throw new NotFoundError(`Stash "${metaRef.origin}" is not installed, so its ${META_DIR}/ docs are unavailable. ` +
+            `Run: akm add ${metaRef.origin}`);
+    }
+    const config = loadConfig();
+    for (const source of sources) {
+        const filePath = resolveMetaFilePath(source.path, metaRef.name);
+        if (!filePath)
+            continue;
+        const content = fs.readFileSync(filePath, "utf8");
+        const editable = isEditable(filePath, config);
+        appendEvent({ eventType: "show", ref: `meta:${metaRef.name}`, metadata: { type: "meta", name: metaRef.name } });
+        return {
+            type: "meta",
+            name: metaRef.name,
+            path: filePath,
+            content,
+            origin: source.registryId ?? null,
+            editable,
+        };
+    }
+    throw new NotFoundError(`No ${META_DIR}/${metaRef.name} doc found${metaRef.origin ? ` in "${metaRef.origin}"` : ""}. ` +
+        `Stash maintainers can create ${META_DIR}/${metaRef.name}.md to describe this stash ` +
+        `(purpose, key assets, conventions, maintainer).`);
+}
 function hasAnyScopeKey(scope) {
     return Boolean(scope.user || scope.agent || scope.run || scope.channel);
 }