akm-cli 0.9.0-beta.9 → 0.9.0-rc.0

package/dist/tasks/runner.js

@@ -33,13 +33,14 @@ import { loadConfig } from "../core/config/config.js";
 import { NotFoundError, rethrowIfTestIsolationError } from "../core/errors.js";
 import { buildTaskRunId, insertTaskLogLines, openLogsDatabase, } from "../core/logs-db.js";
 import { getTaskLogDir } from "../core/paths.js";
-import { getTaskHistory, openStateDatabase, queryTaskHistory, upsertTaskHistory } from "../core/state-db.js";
+import { withStateDb } from "../core/state-db.js";
 import { error } from "../core/warn.js";
 import { requireAgentProfile, runAgent } from "../integrations/agent/index.js";
 import { resolveProcessAgentProfile } from "../integrations/agent/config.js";
 import { resolveRunner } from "../integrations/agent/runner.js";
 import { spawn } from "../runtime.js";
 import { resolveAssetPath } from "../sources/resolve.js";
+import { getTaskHistory, queryTaskHistory, upsertTaskHistory } from "../storage/repositories/task-history-repository.js";
 import { startWorkflowRun } from "../workflows/runtime/runs.js";
 import { parseTaskDocument } from "./parser.js";
 export async function runTask(id, options = {}) {
@@ -131,6 +132,11 @@ async function runCommandTask(input) {
             stdout: "pipe",
             stderr: "pipe",
             cwd: process.env.HOME ?? "/tmp",
+            // Stamp task-runner provenance so any akm invocation in the command tree
+            // records usage events as machine traffic, not user demand (DRIFT-6).
+            // A more specific stamp already in the environment (e.g. improve's
+            // AKM_EVENT_SOURCE=improve on its child spawns) still wins in children.
+            env: { ...process.env, AKM_EVENT_SOURCE: process.env.AKM_EVENT_SOURCE ?? "task" },
         });
         let timer;
         let timedOut = false;
@@ -351,6 +357,10 @@ async function runPromptTask(input) {
         timeoutMs: agentTimeoutMs,
         cwd: stashDir,
         ...agentOptions,
+        // Stamp task-runner provenance for any akm invocation the agent makes
+        // (DRIFT-6: agent-task traffic must not be recorded as user demand).
+        // Caller-supplied env still wins on conflicts.
+        env: { AKM_EVENT_SOURCE: "task", ...agentOptions?.env },
     });
     const finishedAt = now();
     const log = renderPromptLog({ task, profileName: profile.name, result });
@@ -460,8 +470,7 @@ function persistRunLog(input) {
 // ── history ─────────────────────────────────────────────────────────────────
 function appendHistory(result) {
     try {
-        const db = openStateDatabase();
-        try {
+        withStateDb((db) => {
             upsertTaskHistory(db, {
                 task_id: result.id,
                 status: result.status,
@@ -477,10 +486,7 @@ function appendHistory(result) {
                     profile: result.target.kind === "prompt" ? result.target.profile : undefined,
                 }),
             });
-        }
-        finally {
-            db.close();
-        }
+        });
     }
     catch (err) {
         rethrowIfTestIsolationError(err);
@@ -488,8 +494,7 @@ function appendHistory(result) {
     }
 }
 export function readTaskHistory(options = {}) {
-    const db = openStateDatabase();
-    try {
+    return withStateDb((db) => {
         let rows;
         if (options.id) {
             const row = getTaskHistory(db, options.id);
@@ -503,10 +508,7 @@ export function readTaskHistory(options = {}) {
             return rows.slice(0, options.limit);
         }
         return rows;
-    }
-    finally {
-        db.close();
-    }
+    });
 }
 /**
  * Convert a `TaskHistoryRow` from state.db back to a `TaskRunResult` shape

package/dist/wiki/wiki.js

@@ -58,6 +58,8 @@ export const SCHEMA_MD = "schema.md";
 export const INDEX_MD = "index.md";
 export const LOG_MD = "log.md";
 export const RAW_SUBDIR = "raw";
+/** Canonical location for agent-authored pages, mirroring RAW_SUBDIR. */
+export const PAGES_SUBDIR = "pages";
 /** Files at a wiki root that are not pages. */
 const WIKI_SPECIAL_FILES = new Set([SCHEMA_MD, INDEX_MD, LOG_MD]);
 const WIKI_NAME_RE = /^[a-z0-9][a-z0-9-]*$/;
@@ -224,6 +226,43 @@ function readSchemaDescription(wikiDir) {
         return undefined;
     }
 }
+/**
+ * Load a wiki's `schema.md` body and frontmatter.
+ *
+ * Unlike {@link readSchemaDescription} (which returns only the frontmatter
+ * `description` for `listWikis` summaries), this returns the markdown **body**
+ * — everything after the closing `---` of the frontmatter — which is where the
+ * page contract, operations, and hard rules live. The body is the rulebook
+ * injected into the write-time prompt for wiki-page edits.
+ *
+ * Swallow-and-degrade like the existing reader: a missing file, an unresolvable
+ * wiki dir, or malformed content yields `{ body: "", frontmatter: {} }`. Never
+ * throws.
+ */
+export function loadWikiSchema(stashRoot, name) {
+    const empty = { body: "", frontmatter: {} };
+    let wikiDir;
+    try {
+        wikiDir = resolveWikiDir(stashRoot, name);
+    }
+    catch {
+        return empty;
+    }
+    let raw;
+    try {
+        raw = fs.readFileSync(path.join(wikiDir, SCHEMA_MD), "utf8");
+    }
+    catch {
+        return empty;
+    }
+    try {
+        const parsed = parseFrontmatter(raw);
+        return { body: parsed.content, frontmatter: parsed.data };
+    }
+    catch {
+        return empty;
+    }
+}
 function toIsoDate(ms) {
     return new Date(ms).toISOString();
 }
@@ -369,18 +408,20 @@ export function createWiki(stashDir, name) {
         fs.writeFileSync(absPath, content, "utf8");
         created.push(absPath);
     }
-    // Ensure raw/ exists with a .gitkeep so empty wikis survive clean clones.
-    // Handle the dir-exists-but-no-.gitkeep case too (partial scaffolds,
+    // Ensure raw/ and pages/ exist with a .gitkeep so empty wikis survive clean
+    // clones. Handle the dir-exists-but-no-.gitkeep case too (partial scaffolds,
     // user-created directories) so the invariant always holds after `create`.
-    const rawDir = path.join(wikiDir, RAW_SUBDIR);
-    fs.mkdirSync(rawDir, { recursive: true });
-    const gitkeepPath = path.join(rawDir, ".gitkeep");
-    if (fs.existsSync(gitkeepPath)) {
-        skipped.push(gitkeepPath);
-    }
-    else {
-        fs.writeFileSync(gitkeepPath, "", "utf8");
-        created.push(gitkeepPath);
+    for (const subdir of [RAW_SUBDIR, PAGES_SUBDIR]) {
+        const dir = path.join(wikiDir, subdir);
+        fs.mkdirSync(dir, { recursive: true });
+        const gitkeepPath = path.join(dir, ".gitkeep");
+        if (fs.existsSync(gitkeepPath)) {
+            skipped.push(gitkeepPath);
+        }
+        else {
+            fs.writeFileSync(gitkeepPath, "", "utf8");
+            created.push(gitkeepPath);
+        }
     }
     return { name, ref: `wiki:${name}`, path: wikiDir, created, skipped };
 }

package/dist/workflows/cli.js

@@ -17,6 +17,7 @@ export const WORKFLOW_SUBCOMMANDS = new Set([
     "create",
     "template",
     "resume",
+    "abandon",
     "validate",
 ]);
 export function parseWorkflowJsonObject(raw, flagName) {

package/dist/workflows/db.js

@@ -6,6 +6,7 @@ import path from "node:path";
 import { getWorkflowDbPath } from "../core/paths.js";
 import { openDatabase } from "../storage/database.js";
 import { runMigrations as runSqliteMigrations } from "../storage/engines/sqlite-migrations.js";
+import { applyStandardPragmas } from "../storage/sqlite-pragmas.js";
 /**
  * workflow.db — Durable SQLite database for workflow run state.
  *
@@ -46,12 +47,10 @@ export function openWorkflowDatabase(dbPath = getWorkflowDbPath()) {
         fs.mkdirSync(dir, { recursive: true });
     }
     const db = openDatabase(dbPath);
-    db.exec("PRAGMA journal_mode = WAL");
     // #589: 30 s busy timeout, matching index.db / state.db. Without it the
     // default is 0 ms, so any concurrent writer fails immediately with
-    // SQLITE_BUSY.
-    db.exec("PRAGMA busy_timeout = 30000");
-    db.exec("PRAGMA foreign_keys = ON");
+    // SQLITE_BUSY. #628: journal_mode is configurable via AKM_SQLITE_JOURNAL_MODE.
+    applyStandardPragmas(db, { dataDir: dir });
     ensureBaseSchema(db);
     runMigrations(db);
     return db;

package/dist/workflows/runtime/runs.js

@@ -2,23 +2,16 @@
 // 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 { randomUUID } from "node:crypto";
-import fs from "node:fs";
 import { parseAssetRef } from "../../core/asset/asset-ref.js";
 import { loadConfig } from "../../core/config/config.js";
 import { NotFoundError, UsageError } from "../../core/errors.js";
 import { appendEvent } from "../../core/events.js";
-import { getDbPath } from "../../core/paths.js";
-import { closeDatabase, openExistingDatabase } from "../../indexer/db/db.js";
-import { resolveSourceEntries } from "../../indexer/search/search-source.js";
-import { resolveSourcesForOrigin } from "../../registry/origin-resolve.js";
-import { resolveAssetPath } from "../../sources/resolve.js";
 import { withWorkflowRunsRepo, } from "../../storage/repositories/workflow-runs-repository.js";
-import { formatWorkflowErrors } from "../authoring/authoring.js";
 import { getCurrentWorkflowScopeKey } from "../authoring/scope-key.js";
-import { parseWorkflow } from "../parser.js";
 import { validateStepSummary } from "../validate-summary.js";
 import { resolveAgentIdentity } from "./agent-identity.js";
 import { evaluateCheckin } from "./checkin.js";
+import { loadWorkflowAsset, resolveWorkflowEntryId } from "./workflow-asset-loader.js";
 export async function startWorkflowRun(ref, params = {}, options) {
     const asset = await loadWorkflowAsset(ref);
     return withWorkflowRunsRepo(async (repo) => {
@@ -74,10 +67,15 @@ export async function startWorkflowRun(ref, params = {}, options) {
             })));
         });
         const result = await getWorkflowStatus(runId);
+        // 07 P1-B: emit only the run id + status — NOT the raw workflowTitle (which
+        // comes verbatim from the workflow asset's frontmatter and is therefore
+        // attacker-influenceable). Keeping raw titles out of the events stream
+        // shrinks the injectable footprint for any consumer that re-surfaces events
+        // into agent context.
         appendEvent({
             eventType: "workflow_started",
             ref: ref,
-            metadata: { runId: result.run.id, title: result.run.workflowTitle },
+            metadata: { runId: result.run.id, status: result.run.status },
         });
         return result;
     });
@@ -164,6 +162,42 @@ export async function resumeWorkflowRun(runId) {
         return buildWorkflowRunDetail(updated, steps);
     });
 }
+/**
+ * Give up on a run (08-F6): flip it to `failed` so it stops counting as
+ * active — the run-level verb the concurrency-guard message in
+ * {@link startWorkflowRun} advertises. Terminal-state runs are refused;
+ * {@link resumeWorkflowRun} can reopen an abandoned run if it was a mistake.
+ */
+export async function abandonWorkflowRun(runId) {
+    return withWorkflowRunsRepo((repo) => {
+        const run = readWorkflowRun(repo, runId);
+        if (run.status === "completed" || run.status === "failed") {
+            throw new UsageError(`Workflow run ${run.id} is already ${run.status}.`);
+        }
+        const now = new Date().toISOString();
+        repo.updateRunState({
+            status: "failed",
+            currentStepId: run.current_step_id,
+            updatedAt: now,
+            completedAt: now,
+            checkinArmedAt: now,
+            runId: run.id,
+        });
+        const updated = {
+            ...run,
+            status: "failed",
+            updated_at: now,
+            completed_at: now,
+            checkin_armed_at: now,
+        };
+        const steps = readWorkflowRunSteps(repo, run.id);
+        const detail = buildWorkflowRunDetail(updated, steps);
+        // Same injectable-footprint rule as workflow_started (07 P1-B): ids and
+        // status only, never the frontmatter-derived title.
+        appendEvent({ eventType: "workflow_abandoned", ref: run.workflow_ref, metadata: { runId: run.id } });
+        return detail;
+    });
+}
 export async function completeWorkflowStep(input) {
     // Read the step (read-only) up front so the LLM validation gate runs OUTSIDE
     // the write transaction — a slow/hung LLM must never hold a db write lock.
@@ -299,115 +333,6 @@ async function resolveRunSpecifier(repo, specifier, params) {
     const started = await startWorkflowRun(ref, params ?? {});
     return { run: readWorkflowRun(repo, started.run.id), autoStarted: true };
 }
-async function loadWorkflowAsset(ref) {
-    const parsed = parseAssetRef(ref);
-    if (parsed.type !== "workflow") {
-        throw new UsageError(`Expected a workflow ref (workflow:<name>), got "${ref}".`);
-    }
-    const config = loadConfig();
-    const allSources = resolveSourceEntries(undefined, config);
-    const searchSources = resolveSourcesForOrigin(parsed.origin, allSources);
-    let assetPath;
-    let sourcePath;
-    for (const source of searchSources) {
-        try {
-            assetPath = await resolveAssetPath(source.path, "workflow", parsed.name);
-            sourcePath = source.path;
-            break;
-        }
-        catch {
-            /* continue */
-        }
-    }
-    if (!assetPath) {
-        throw new NotFoundError(`Workflow not found for ref: workflow:${parsed.name}`);
-    }
-    const resolvedSourcePath = sourcePath ?? config.stashDir ?? assetPath;
-    const fullRef = `${parsed.origin ? `${parsed.origin}//` : ""}workflow:${parsed.name}`;
-    const cached = readWorkflowDocumentFromIndex(resolvedSourcePath, fullRef);
-    const document = cached ?? loadWorkflowDocumentFromDisk(assetPath);
-    return projectAsset(document, fullRef, assetPath, resolvedSourcePath);
-}
-function loadWorkflowDocumentFromDisk(assetPath) {
-    const content = fs.readFileSync(assetPath, "utf8");
-    const result = parseWorkflow(content, { path: assetPath });
-    if (!result.ok) {
-        throw new UsageError(formatWorkflowErrors(assetPath, result.errors));
-    }
-    return result.document;
-}
-function readWorkflowDocumentFromIndex(sourcePath, ref) {
-    const dbPath = getDbPath();
-    if (!fs.existsSync(dbPath))
-        return null;
-    const db = openExistingDatabase(dbPath);
-    try {
-        const parsed = parseAssetRef(ref);
-        const entryKey = `${sourcePath}:${parsed.type}:${parsed.name}`;
-        const row = db
-            .prepare(`SELECT wd.document_json AS document_json
-           FROM workflow_documents wd
-           JOIN entries e ON e.id = wd.entry_id
-          WHERE e.entry_type = 'workflow' AND e.entry_key = ?
-          LIMIT 1`)
-            .get(entryKey);
-        if (!row)
-            return null;
-        try {
-            return JSON.parse(row.document_json);
-        }
-        catch {
-            return null;
-        }
-    }
-    finally {
-        closeDatabase(db);
-    }
-}
-function projectAsset(doc, ref, assetPath, sourcePath) {
-    return {
-        ref,
-        path: assetPath,
-        sourcePath,
-        title: doc.title,
-        ...(doc.parameters
-            ? {
-                parameters: doc.parameters.map((p) => ({
-                    name: p.name,
-                    ...(p.description ? { description: p.description } : {}),
-                })),
-            }
-            : {}),
-        steps: doc.steps.map((s) => ({
-            id: s.id,
-            title: s.title,
-            instructions: s.instructions.text,
-            ...(s.completionCriteria ? { completionCriteria: s.completionCriteria.map((c) => c.text) } : {}),
-            sequenceIndex: s.sequenceIndex,
-        })),
-    };
-}
-function resolveWorkflowEntryId(sourcePath, ref) {
-    const dbPath = getDbPath();
-    if (!fs.existsSync(dbPath))
-        return null;
-    const db = openExistingDatabase(dbPath);
-    try {
-        const parsed = parseAssetRef(ref);
-        const entryKey = `${sourcePath}:${parsed.type}:${parsed.name}`;
-        const row = db
-            .prepare(`SELECT id
-         FROM entries
-         WHERE entry_type = 'workflow'
-            AND entry_key = ?
-          LIMIT 1`)
-            .get(entryKey);
-        return row?.id ?? null;
-    }
-    finally {
-        closeDatabase(db);
-    }
-}
 function readWorkflowRun(repo, runId) {
     const run = repo.getRunById(runId);
     if (!run) {

package/dist/workflows/runtime/workflow-asset-loader.js

@@ -0,0 +1,125 @@
+// 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 fs from "node:fs";
+import { parseAssetRef } from "../../core/asset/asset-ref.js";
+import { loadConfig } from "../../core/config/config.js";
+import { NotFoundError, UsageError } from "../../core/errors.js";
+import { getDbPath } from "../../core/paths.js";
+import { resolveSourceEntries } from "../../indexer/search/search-source.js";
+import { resolveSourcesForOrigin } from "../../registry/origin-resolve.js";
+import { resolveAssetPath } from "../../sources/resolve.js";
+import { withIndexDb } from "../../storage/repositories/index-db.js";
+import { formatWorkflowErrors } from "../authoring/authoring.js";
+import { parseWorkflow } from "../parser.js";
+/**
+ * Resolve a `workflow:<name>` ref to a fully-projected {@link WorkflowAsset}.
+ *
+ * Prefers the parsed document cached in `index.db` (fast path) and falls back to
+ * reading + parsing the source file from disk. Pure loading/parsing concern —
+ * extracted from the run repository so run orchestration no longer owns asset
+ * resolution.
+ */
+export async function loadWorkflowAsset(ref) {
+    const parsed = parseAssetRef(ref);
+    if (parsed.type !== "workflow") {
+        throw new UsageError(`Expected a workflow ref (workflow:<name>), got "${ref}".`);
+    }
+    const config = loadConfig();
+    const allSources = resolveSourceEntries(undefined, config);
+    const searchSources = resolveSourcesForOrigin(parsed.origin, allSources);
+    let assetPath;
+    let sourcePath;
+    for (const source of searchSources) {
+        try {
+            assetPath = await resolveAssetPath(source.path, "workflow", parsed.name);
+            sourcePath = source.path;
+            break;
+        }
+        catch {
+            /* continue */
+        }
+    }
+    if (!assetPath) {
+        throw new NotFoundError(`Workflow not found for ref: workflow:${parsed.name}`);
+    }
+    const resolvedSourcePath = sourcePath ?? config.stashDir ?? assetPath;
+    const fullRef = `${parsed.origin ? `${parsed.origin}//` : ""}workflow:${parsed.name}`;
+    const cached = readWorkflowDocumentFromIndex(resolvedSourcePath, fullRef);
+    const document = cached ?? loadWorkflowDocumentFromDisk(assetPath);
+    return projectAsset(document, fullRef, assetPath, resolvedSourcePath);
+}
+/**
+ * Resolve the `entries.id` for an indexed workflow, or null when the index
+ * database does not yet exist or has no matching entry.
+ */
+export function resolveWorkflowEntryId(sourcePath, ref) {
+    if (!fs.existsSync(getDbPath()))
+        return null;
+    const parsed = parseAssetRef(ref);
+    const entryKey = `${sourcePath}:${parsed.type}:${parsed.name}`;
+    return withIndexDb((db) => {
+        const row = db
+            .prepare(`SELECT id
+         FROM entries
+         WHERE entry_type = 'workflow'
+            AND entry_key = ?
+          LIMIT 1`)
+            .get(entryKey);
+        return row?.id ?? null;
+    });
+}
+function loadWorkflowDocumentFromDisk(assetPath) {
+    const content = fs.readFileSync(assetPath, "utf8");
+    const result = parseWorkflow(content, { path: assetPath });
+    if (!result.ok) {
+        throw new UsageError(formatWorkflowErrors(assetPath, result.errors));
+    }
+    return result.document;
+}
+function readWorkflowDocumentFromIndex(sourcePath, ref) {
+    if (!fs.existsSync(getDbPath()))
+        return null;
+    const parsed = parseAssetRef(ref);
+    const entryKey = `${sourcePath}:${parsed.type}:${parsed.name}`;
+    return withIndexDb((db) => {
+        const row = db
+            .prepare(`SELECT wd.document_json AS document_json
+           FROM workflow_documents wd
+           JOIN entries e ON e.id = wd.entry_id
+          WHERE e.entry_type = 'workflow' AND e.entry_key = ?
+          LIMIT 1`)
+            .get(entryKey);
+        if (!row)
+            return null;
+        try {
+            return JSON.parse(row.document_json);
+        }
+        catch {
+            return null;
+        }
+    });
+}
+function projectAsset(doc, ref, assetPath, sourcePath) {
+    return {
+        ref,
+        path: assetPath,
+        sourcePath,
+        title: doc.title,
+        ...(doc.parameters
+            ? {
+                parameters: doc.parameters.map((p) => ({
+                    name: p.name,
+                    ...(p.description ? { description: p.description } : {}),
+                })),
+            }
+            : {}),
+        steps: doc.steps.map((s) => ({
+            id: s.id,
+            title: s.title,
+            instructions: s.instructions.text,
+            ...(s.completionCriteria ? { completionCriteria: s.completionCriteria.map((c) => c.text) } : {}),
+            sequenceIndex: s.sequenceIndex,
+        })),
+    };
+}

package/dist/workflows/validate-summary.js

@@ -16,14 +16,9 @@
  *
  * @module workflows/validate-summary
  */
+import validateSummaryJudgePrompt from "../assets/prompts/validate-summary-judge.md" with { type: "text" };
 import { parseJsonResponse } from "../core/parse.js";
-const JUDGE_SYSTEM = "You are a strict completion auditor for a software workflow engine. " +
-    "Given a step's completion criteria and a summary of the work an agent claims to have done, " +
-    "judge whether the summary provides concrete evidence that EVERY criterion is satisfied. " +
-    "Be skeptical: vague, hand-wavy, or unsubstantiated claims do NOT satisfy a criterion. " +
-    'Respond with ONLY a JSON object: {"complete": boolean, "missing": string[], "feedback": string}. ' +
-    '"missing" lists the exact criteria that are not yet satisfied; "feedback" is a short directive ' +
-    "telling the agent what to finish or fix. No prose, no markdown fences.";
+const JUDGE_SYSTEM = validateSummaryJudgePrompt;
 function buildUserPrompt(input) {
     const criteria = input.completionCriteria.map((c, i) => `${i + 1}. ${c}`).join("\n");
     return [

package/docs/README.md

@@ -4,50 +4,101 @@
 
 - [Concepts](concepts.md) -- Stashes, registries, asset types, and refs
 - [Getting Started](getting-started.md) -- Quick setup guide
+- [Local Development](local-development.md) -- Dogfooding akm while editing its own source
 - [Agent Install Guide](agents/agent-install.md) -- Step-by-step automated install for agents
 - [Stash Maker's Guide](stash-makers.md) -- Build and share a stash on GitHub, npm, or a network directory
 - [Wikis](wikis.md) -- Multi-wiki knowledge bases (Karpathy-style)
 
+## Configuration & Data
+
+- [Configuration](configuration.md) -- Providers, settings, and Ollama setup
+- [Configuring Agent Profiles](configuration-agent-profiles.md) -- How akm runs a coding agent, CLI or API
+- [Data & Telemetry](data-and-telemetry.md) -- Exactly what akm reads and writes on your machine (no remote telemetry)
+
+## Features
+
+- [Workflows](features/workflows.md) -- Structured, resumable multi-step procedures
+- [Search & Discovery](features/search-discovery.md) -- Finding assets without knowing their exact name
+- [Knowledge Management](features/knowledge-management.md) -- Lessons, incidents, and research as first-class assets
+- [Sources & Registries](features/sources-registries.md) -- Where assets come from and how to find more
+- [Wiki Snapshot Fetchers](features/wiki-snapshot-fetchers.md) -- Pluggable fetchers for URL-based knowledge reads
+- [Agent Integration](features/agent-integration.md) -- Wiring akm into any shell-capable coding agent
+- [The Improvement Loop](features/improvement-loop.md) -- How the stash adapts from usage and feedback
+
 ## Upgrading
 
 - [Roadmap](roadmap.md) -- High-level focus for the 0.9 and 1.0 releases
-- [v1 migration guide](migration/v1.md) -- The path from 0.x to v1.0, including the `.stash.json` removal scheduled for v0.8.0
-- [Release notes (latest: 0.8.0)](migration/release-notes/0.8.0.md) -- Per-release notes drop into `migration/release-notes/`, including current pre-release removals
-- [v0.5 → v0.6 migration guide](migration/v0.5-to-v0.6.md) -- Every breaking change with before/after code, publisher checklist, and troubleshooting
+- [v1 migration guide](migration/v1.md) -- The path from 0.x to v1.0
+- [v0.8 -> v0.9 migration guide](migration/v0.8-to-v0.9.md) -- Current-cycle breaking changes
+- [Release notes (latest: 0.9.0)](migration/release-notes/0.9.0.md) -- Per-release notes; see the [release-notes index](migration/release-notes/README.md) for every version
+- [v0.5 -> v0.6 migration guide](migration/v0.5-to-v0.6.md) -- Every breaking change with before/after code, publisher checklist, and troubleshooting
 
 ## Reference
 
 - [CLI](cli.md) -- All `akm` commands and flags
 - [Registry](registry.md) -- Registries, search, hosting, and managing sources
-- [Configuration](configuration.md) -- Providers, settings, and Ollama setup
-- [Filesystem](technical/filesystem.md) -- Directory layout plus `.stash.json` deprecation and migration notes
+- [akm-eval](akm-eval.md) -- Standalone toolkit for measuring whether `akm improve` is working
 
-## Official Ecosystem Repositories
+## Agents
 
-- [itlackey/akm-stash](https://github.com/itlackey/akm-stash) -- the official onboarding stash with ready-made assets you can install with `akm add`
-- [itlackey/akm-registry](https://github.com/itlackey/akm-registry) -- the official registry index that powers built-in discovery
-- [itlackey/akm-plugins](https://github.com/itlackey/akm-plugins) -- optional integrations for tools like OpenCode
-- [itlackey/akm-bench](https://github.com/itlackey/akm-bench) -- the standalone benchmark and evaluation repo for akm
+- [AGENTS.md](agents/AGENTS.md) -- The system-prompt reference agents load to use akm
+- [Curate Workmap](agents/curate-workmap.md) -- Read before changing `akm curate` ranking or output
+
+## Architecture
+
+- [Architecture](technical/architecture.md) -- How akm's sources, cache, index, and registries fit together
+- [Runtime Boundary Design](architecture/runtime-boundary-design.md) -- Isolating `bun:sqlite`/`Bun.*` from the core
+- [Brain Workflow (diagram)](architecture/brain-workflow.html) -- Visual map of the improve/self-learning loop
+
+## Example Stash
+
+- [Example Stash](example-stash/README.md) -- A documentation-backed example stash showing how asset types fit together
+
+## Analysis
 
-## Operations
+- [Indexer Vertical Slice Refactor Plan](analysis/indexer-vertical-slice-refactor-plan.md)
+- [Indexer Refactor Review (Expert Options)](analysis/indexer-refactor-expert-options.md)
 
-- Analyzing `akm improve` runs -- use [`akm health`](../src/commands/health.ts) (0.8.0+): `--since`, `--group-by run`, `--window-compare`, `--windows`. See [health-command-enhancements.md](technical/health-command-enhancements.md).
+## Design (unshipped work)
 
-## Internals
+- [Self-Improvement, Self-Learning & Memory Reference Index](design/self-improvement-learning-memory-reference-index.md) -- Master index for every unshipped improve/self-learning/memory design doc, with a subsystem-to-doc status table
 
+Every doc under `docs/design/` must carry a `Status` / `Supersedes` / `Date` header (pre-existing docs are grandfathered until next touched). When a design ships, the shipping PR moves it to `docs/archive/` in the same PR.
+
+## Archive
+
+- [Archive](archive/README.md) -- Design and implementation plans whose work has already shipped, retained as ADR-style records
+
+## Internals (technical/)
+
+- [Filesystem](technical/filesystem.md) -- Directory layout plus `.stash.json` deprecation and migration notes
 - [Search](technical/search.md) -- Hybrid search architecture and scoring
 - [Indexing](technical/indexing.md) -- How the search index is built
 - [Classification](technical/classification.md) -- Matcher and renderer behavior
+- [Storage Locations](technical/storage-locations.md) -- Authoritative inventory of every on-disk read/write path
+- [Improve Workflow](technical/improve-workflow.md) -- `akm improve` command surface and pipeline reference
+- [Health Advisories](technical/health-advisories.md) -- `akm health` advisory-to-action map for operators
+- [Fresh-Host Rebuild Runbook](technical/fresh-host-rebuild-runbook.md) -- Rebuild an akm install on a new machine
+- [Ranking Ablation & Saturation Analysis](technical/ranking-ablation-and-saturation-analysis.md) -- Reproducible contributor-ablation measurement and the score-saturation trap
 - [Functional Contract Patterns](technical/functional-contract-patterns.md) -- Quick reference for contributor pipelines and small process contracts
-- [Implementation Plan: Functional Contract Refactor](technical/implementation-plan-functional-contract-refactor.md) -- Phased plan to move behavior from type-centric switchboards to process-local contributors
-- [Architecture Cleanup Checklist](technical/architecture-cleanup-checklist.md) -- Living checklist for executing the cleanup plan with parity gates, reviews, and git hygiene
-- [Show Response](technical/show-response.md) -- `akm show` output fields by asset type
+- [Test Coverage Guide](technical/test-coverage-guide.md) -- High-value testing areas
 - [Testing Workflow](technical/testing-workflow.md) -- End-to-end, Docker, deployment, and upgrade validation
 - [Ref Format](technical/ref.md) -- Wire format for asset references
-- [Test Coverage Guide](technical/test-coverage-guide.md) -- High-value testing areas
 - [Core Principles](technical/akm-core-principles.md) -- Design principles and constraints
-- `technical/benchmark.md` (planned) -- Search-quality benchmark suite
+- [Claude Code workflows vs. akm workflows](technical/claude-code-vs-akm-workflows.md) -- Comparing the two things that share a name
+- [Extending akm workflows into a harness-agnostic orchestration engine](technical/akm-workflows-orchestration-plan.md) -- Current formalized plan, supersedes part of the doc above
+
+## Official Ecosystem Repositories
+
+- [itlackey/akm-stash](https://github.com/itlackey/akm-stash) -- the official onboarding stash with ready-made assets you can install with `akm add`
+- [itlackey/akm-registry](https://github.com/itlackey/akm-registry) -- the official registry index that powers built-in discovery
+- [itlackey/akm-plugins](https://github.com/itlackey/akm-plugins) -- optional integrations for tools like OpenCode
+- [itlackey/akm-bench](https://github.com/itlackey/akm-bench) -- the standalone benchmark and evaluation repo for akm
 
 ## Posts
 
 - [Blog posts](posts/) -- Articles and posts about akm
+
+---
+
+New docs, in five lines: keep one current-truth doc per subsystem, don't fork a second one. Unshipped designs live in `docs/design/` with a mandatory `Status` / `Supersedes` / `Date` header. The PR that ships the design moves its doc to `docs/archive/` in that same PR. Cite code by symbol and memories by search-terms -- not line numbers or exact refs, both rot. Nothing in `docs/` may reference `.plans/` (it's scratch -- promote the content or drop the link); no new improve-analysis docs until the 30-clean-day gate.