akm-cli 0.8.1 → 0.8.2

package/CHANGELOG.md

@@ -4,6 +4,77 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [0.8.2] - 2026-06-05
+
+### Added
+
+- **LM Studio auto-detection in setup wizard** — `akm setup` now probes
+  `localhost:1234/v1/models` at startup and, when the server is running, pre-fills
+  the LLM backend with the active model list, mirroring the existing Ollama detection
+  flow (#522).
+- **Agent harness config import** — `akm setup` detects installed AI coding harnesses
+  (currently Claude Code and OpenCode) and pre-populates LLM provider, model, and
+  base-URL fields from the harness configuration. The importer registry
+  (`HARNESS_CONFIG_IMPORTERS`) makes adding future harnesses a single append (#523).
+  API key *values* are never read or stored — only the environment variable name is
+  imported.
+- **Registry-driven stash selection** — the "Add Sources" step now fetches available
+  stashes from the official AKM registry at startup. `DEFAULT_SELECTED_STASH_IDS`
+  in `src/setup/registry-stash-loader.ts` is the single edit point for changing
+  which stashes are pre-checked. Falls back to a hardcoded list on network error (#520).
+- **`improve.autoAccept.{promoted,validationFailed}` health metrics** — auto-accepted
+  proposals that pass the confidence threshold but fail validation (truncated
+  description, invalid frontmatter) are now counted as `gateAutoAcceptFailedCount`
+  in the improve result envelope and surfaced as `improve.autoAccept.validationFailed`
+  in `akm health` reports.
+- **`auto-accept-validation` health advisory** — heuristic advisory that warns when
+  `validationFailed > 0` so malformed proposals are visible before they pile up in
+  the queue.
+
+### Fixed
+
+- **`akm-improve` tasks recorded as failed on budget exhaustion** — the budget
+  exhaustion timer called `process.exit(1)`, causing every budget-limited run to be
+  recorded as a task failure. Changed to `process.exit(0)`; budget exhaustion is a
+  normal exit condition.
+- **`improve_runs.started_at` always equal to `completed_at`** — `writeImproveResultFile`
+  was called at end-of-run, so `new Date()` captured the completion time and both
+  columns held the same value (649/661 real runs affected, regressed ~May 26).
+  `started_at` now uses the timestamp captured at process launch, passed in from the
+  CLI entry point. A regex-based fallback decodes the timestamp embedded in the run ID
+  for any call site that does not supply an explicit value (#524).
+- **`akm-health-report` task fails on transient DNS errors** — the Discord webhook
+  script caught `HTTPError` but not the parent `URLError`, so DNS blips caused the
+  task runner to record the health report as failed. `URLError` is now caught and
+  logged as a warning with a clean exit.
+
+### Added
+
+- **Stash `.meta/` convention** — a stash may carry an optional, human-authored
+  `.meta/` directory at its root for orientation: purpose, key assets, conventions,
+  and maintainer info. Surface it on demand with `akm show meta` (the working
+  stash's `.meta/index.md`), `akm show meta:<name>` (e.g. `.meta/about.md`), or
+  scope it to a specific stash with `akm show <origin>//meta[:<name>]`. Because
+  `.meta/` is a dot-directory, the indexer already skips it, so these docs never
+  pollute search results — they are direct-read on demand. Owners extend the
+  convention by dropping new files (`.meta/about.md`, `.meta/conventions.md`,
+  `.meta/license`) with no code changes. `akm init` scaffolds a `.meta/index.md`
+  template into newly created stashes.
+- **Default stash skeleton** — `akm init` (and `akm setup`) now copies
+  `src/assets/stash-skeleton/` into every newly created stash. Currently ships
+  a `README.md` covering what the stash contains and how agents use `akm` to
+  access assets. Existing files are never overwritten. Add files to
+  `src/assets/stash-skeleton/` to extend what ships with a fresh install.
+
+### Improved
+
+- **Setup wizard pre-populates from existing config** — on re-run, `akm setup`
+  initialises every prompt default from the current saved configuration so users
+  only need to change what has actually changed (#519).
+- **Config backup before every setup write** — `backupExistingConfig()` is now called
+  before each `saveConfig` in the setup wizard, ensuring the previous config is always
+  recoverable if a wizard run is interrupted (#521).
+
 ## [0.8.1] - 2026-06-05
 
 ### Added

package/dist/assets/stash-skeleton/README.md

@@ -0,0 +1,76 @@
+# AKM Stash
+
+This is an **AKM stash** — a structured knowledge repository that stores reusable
+assets for you and your AI agents. AKM (Agent Knowledge Management) indexes, ranks,
+and surfaces these assets at the right moment during coding sessions, improving
+consistency and reducing repeated context-setting.
+
+## What this stash contains
+
+| Directory | Asset type | Purpose |
+|-----------|-----------|---------|
+| `skills/` | Skills | Step-by-step instructions agents follow for specific tasks |
+| `knowledge/` | Knowledge | Reference documents, guides, architecture notes |
+| `memories/` | Memories | Persistent facts and preferences learned over time |
+| `commands/` | Commands | Parameterised prompt templates for common workflows |
+| `agents/` | Agents | Agent definitions with system prompts and tool policies |
+| `workflows/` | Workflows | Multi-step orchestration sequences |
+| `tasks/` | Tasks | Scheduled or on-demand automation tasks |
+| `lessons/` | Lessons | Durable lessons extracted from past sessions |
+
+Add your own assets to any of these directories. AKM will index them automatically
+on the next `akm index` run (or when the background improve pipeline picks them up).
+
+## For agents: how to access this stash
+
+All assets in this stash are searchable via the `akm` CLI. Use these commands to
+find and read assets during a session:
+
+```sh
+# Find assets relevant to your current task (recommended first step)
+akm curate "<task description including project name>"
+
+# Full-text + semantic search
+akm search "<query>"
+akm search "<query>" --type skill
+akm search "<query>" --type knowledge
+
+# Show a specific asset by ref
+akm show skill:<name>
+akm show knowledge:<name>
+akm show memory:<name>
+akm show command:<name>
+
+# List available assets by type
+akm list --type skill
+akm list --type knowledge
+```
+
+### Recording feedback and new knowledge
+
+```sh
+# Mark an asset as helpful (improves future rankings)
+akm feedback <ref> --positive
+
+# Capture a durable lesson or memory from the current session
+akm remember "<fact or lesson>"
+```
+
+### Improving and maintaining the stash
+
+```sh
+# Run the self-improvement pipeline (extract, reflect, consolidate)
+akm improve
+
+# Check stash health and pipeline metrics
+akm health
+
+# Review pending improvement proposals
+akm proposal list
+akm proposal show <id>
+akm proposal accept <id>
+```
+
+---
+
+*Created by `akm init`. See `akm --help` for full command reference.*

package/dist/cli.js

@@ -92,8 +92,8 @@ function resolveEventSource() {
 }
 import { resolveImproveProfile } from "./commands/improve-profiles";
 import { akmProposalAccept, akmProposalDiff, akmProposalList, akmProposalReject, akmProposalRevert, akmProposalShow, } from "./commands/proposal";
-import { drainProposals } from "./commands/proposal-drain";
-import { resolveDrainPolicy } from "./commands/proposal-drain-policies";
+import { drainProposals } from "./commands/proposal/drain";
+import { resolveDrainPolicy } from "./commands/proposal/drain-policies";
 import { akmPropose } from "./commands/propose";
 import { akmSearch, parseBeliefFilterMode, parseScopeFilterFlags, parseSearchSource } from "./commands/search";
 import { checkForUpdate, performUpgrade } from "./commands/self-update";
@@ -107,6 +107,7 @@ import { DEFAULT_CONFIG, loadConfig, loadUserConfig, resolveConfiguredSources, s
 import { ConfigError, NotFoundError, UsageError } from "./core/errors";
 import { appendEvent } from "./core/events";
 import { getCacheDir, getConfigPath, getDbPath, getDefaultStashDir } from "./core/paths";
+import { parseMetaRef } from "./core/stash-meta";
 import { plainize } from "./core/tty";
 import { clearLogFile, info, isQuiet, isVerbose, setLogFile, setQuiet, setVerbose, warn } from "./core/warn";
 import { closeDatabase, openExistingDatabase } from "./indexer/db";
@@ -872,7 +873,11 @@ const showCommand = defineCommand({
                 output("proposal-show", result);
                 return;
             }
-            parseAssetRef(args.ref);
+            // `[origin//]meta[:name]` targets the stash `.meta/` convention, which is
+            // not a typed asset ref — skip ref validation and let akmShowUnified
+            // direct-read it. (`parseAssetRef` would reject the non-type `meta`.)
+            if (!parseMetaRef(args.ref))
+                parseAssetRef(args.ref);
             // The knowledge-view positional syntax (`akm show knowledge:foo section "Auth"`)
             // is rewritten to `--akmView` / `--akmHeading` / `--akmStart` / `--akmEnd`
             // by `normalizeShowArgv` before citty parses argv. We read those values

package/dist/commands/consolidate.js

@@ -170,7 +170,7 @@ export function isHotCapturedMemory(filePath) {
         return false;
     }
 }
-export function consolidateGuardStatus(filePath) {
+function consolidateGuardStatus(filePath) {
     if (!fs.existsSync(filePath))
         return "missing";
     let content;
@@ -395,7 +395,7 @@ export function buildChunkPrompt(sourceName, memories, chunkIndex, totalChunks,
  * trimmed). Empty set on any read/parse error — fail-safe to "annotate
  * nothing" so the LLM still proposes, just slightly more wastefully.
  */
-export function loadPendingConsolidateProposalHashes(stashDir) {
+function loadPendingConsolidateProposalHashes(stashDir) {
     const hashes = new Set();
     try {
         const pending = listProposals(stashDir, { status: "pending" }).filter((p) => p.source === "consolidate");
@@ -1924,7 +1924,7 @@ export function normalizeUpdatedField(fm) {
  * Two slugs that normalise to the same string are considered the same asset
  * for dedup purposes even if they don't share an exact ref.
  */
-export function normalizeSlugForDedup(ref) {
+function normalizeSlugForDedup(ref) {
     const slug = ref.replace(/^[^:]+:/, "");
     const monthRe = /(?:jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec)/i;
     const tokens = slug
@@ -1962,7 +1962,7 @@ export function normalizeSlugForDedup(ref) {
  * improve invocation — a different concern from the cross-run content-hash
  * dedup, and cheap (no embeddings, no DB query).
  */
-export async function checkPreEmitDedup(opts) {
+async function checkPreEmitDedup(opts) {
     const normCandidate = normalizeSlugForDedup(opts.candidateRef);
     // Pending consolidate proposals (slug match) — within the same improve run.
     const pendingConsolidate = listProposals(opts.stashDir, { status: "pending" }).filter((p) => p.source === "consolidate");

package/dist/commands/health.js

@@ -71,6 +71,7 @@ function createUnknownImproveMetrics() {
             graphExtraction: 0,
             error: 0,
         },
+        autoAccept: { promoted: 0, validationFailed: 0 },
         reflectsWithErrorContext: 0,
         coverageGapCount: 0,
         evalCasesWritten: 0,
@@ -293,6 +294,8 @@ function projectRunMetrics(result) {
             }
         }
     }
+    metrics.autoAccept.promoted += toFiniteNumber(result.gateAutoAcceptedCount);
+    metrics.autoAccept.validationFailed += toFiniteNumber(result.gateAutoAcceptFailedCount);
     metrics.reflectsWithErrorContext += toFiniteNumber(result.reflectsWithErrorContext);
     if (Array.isArray(result.coverageGaps))
         metrics.coverageGapCount += result.coverageGaps.length;
@@ -481,6 +484,8 @@ function mergeImproveMetrics(dst, src) {
     dst.actions.memoryInference += src.actions.memoryInference;
     dst.actions.graphExtraction += src.actions.graphExtraction;
     dst.actions.error += src.actions.error;
+    dst.autoAccept.promoted += src.autoAccept.promoted;
+    dst.autoAccept.validationFailed += src.autoAccept.validationFailed;
     dst.reflectsWithErrorContext += src.reflectsWithErrorContext;
     dst.coverageGapCount += src.coverageGapCount;
     dst.evalCasesWritten += src.evalCasesWritten;
@@ -923,6 +928,8 @@ const INTERESTING_DELTA_PATHS = [
     "improve.graphExtraction.failures",
     "improve.sessionExtraction.sessionsScanned",
     "improve.sessionExtraction.proposalsCreated",
+    "improve.autoAccept.promoted",
+    "improve.autoAccept.validationFailed",
     "improve.wallTime.medianMs",
     "improve.wallTime.p95Ms",
 ];
@@ -1183,6 +1190,19 @@ export function akmHealth(options = {}) {
                 durationMs: sx.durationMs,
             },
         });
+        const aa = improveSummary.autoAccept;
+        advisories.push({
+            name: "auto-accept-validation",
+            kind: "heuristic",
+            status: aa.validationFailed > 0 ? "warn" : "pass",
+            confidence: aa.promoted + aa.validationFailed > 0 ? "high" : "low",
+            message: aa.validationFailed > 0
+                ? `${aa.validationFailed} proposal(s) passed confidence threshold but failed auto-accept validation (truncated description, invalid frontmatter, etc.) — they remain in the queue for manual review.`
+                : aa.promoted > 0
+                    ? `Auto-accept healthy: ${aa.promoted} proposal(s) promoted, 0 validation failures.`
+                    : "Auto-accept gate did not run (disabled or no proposals above threshold).",
+            evidence: { promoted: aa.promoted, validationFailed: aa.validationFailed },
+        });
         const metrics = {
             taskFailRate: roundRate(taskFailRate),
             agentFailureRate: roundRate(agentFailureRate),

package/dist/commands/improve-cli.js

@@ -217,7 +217,7 @@ export const improveCommand = defineCommand({
             runRecorded = true; // Suppress any late signal-handler write — the success path owns the row now.
             if (primaryStashDir) {
                 try {
-                    writeImproveResultFile(primaryStashDir, runId, improveResult);
+                    writeImproveResultFile(primaryStashDir, runId, improveResult, startedAtIso);
                 }
                 catch (err) {
                     // Stderr warning on the failure path is preferable to crashing

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

@@ -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";
@@ -678,7 +678,8 @@ export async function akmImprove(options = {}) {
             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).
-            setTimeout(() => process.exit(1), 5_000);
+            // 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);
@@ -729,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,
@@ -748,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,
@@ -833,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, {
@@ -1066,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,
@@ -1087,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);
@@ -1118,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).
@@ -1544,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.
@@ -1627,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,
@@ -1803,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)
             }
@@ -1914,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";
@@ -1987,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;
@@ -2083,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,
@@ -2121,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",
@@ -2206,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.

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);
 }