akm-cli 0.7.5 → 0.8.0-rc.6

package/dist/workflows/db.js

@@ -1,7 +1,44 @@
+// 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 { Database } from "bun:sqlite";
 import fs from "node:fs";
 import path from "node:path";
 import { getWorkflowDbPath } from "../core/paths";
+/**
+ * workflow.db — Durable SQLite database for workflow run state.
+ *
+ * Owns the `workflow_runs` and `workflow_run_steps` tables that track active /
+ * completed workflow executions. Like `state.db` (and unlike `index.db`), the
+ * rows here are NON-REGENERABLE — losing them is data loss. Schema must evolve
+ * via incremental, additive migrations recorded in `schema_migrations`.
+ *
+ * ## Migration-safety contract
+ *
+ * The `schema_migrations` table records every applied migration by a stable
+ * string ID. `runMigrations(db)` is idempotent: new installs run every
+ * migration in order; upgrades run only the ones not yet applied. The
+ * migration framework here intentionally mirrors `src/core/state-db.ts` so
+ * future schema evolution follows a single proven pattern.
+ *
+ * Permitted schema evolution operations (always migration-safe in SQLite):
+ *   - ALTER TABLE … ADD COLUMN <name> <type> DEFAULT <value>
+ *   - CREATE INDEX IF NOT EXISTS …
+ *   - CREATE TABLE IF NOT EXISTS … (additive new tables)
+ *
+ * ## Bootstrapping pre-versioning databases
+ *
+ * Workflow databases created before this file gained `schema_migrations`
+ * already have the `workflow_runs.scope_key` column applied by the previous
+ * ad-hoc `PRAGMA table_info` + `ALTER TABLE` code. To avoid re-running the
+ * migration (which would no-op but still wastes work and clutters logs), the
+ * runner detects this state and back-fills the `schema_migrations` row for
+ * the scope-key migration before evaluating the migration list. See
+ * `bootstrapPreVersioningDb()`.
+ *
+ * @module workflows/db
+ */
+// ── Public API ───────────────────────────────────────────────────────────────
 export function openWorkflowDatabase(dbPath = getWorkflowDbPath()) {
     const dir = path.dirname(dbPath);
     if (!fs.existsSync(dir)) {
@@ -10,18 +47,29 @@ export function openWorkflowDatabase(dbPath = getWorkflowDbPath()) {
     const db = new Database(dbPath);
     db.exec("PRAGMA journal_mode = WAL");
     db.exec("PRAGMA foreign_keys = ON");
-    ensureWorkflowSchema(db);
+    ensureBaseSchema(db);
+    runMigrations(db);
     return db;
 }
 export function closeWorkflowDatabase(db) {
     db.close();
 }
-function ensureWorkflowSchema(db) {
+// ── Base schema ──────────────────────────────────────────────────────────────
+/**
+ * Create the baseline `workflow_runs` and `workflow_run_steps` tables if they
+ * do not exist. These statements are idempotent: existing databases keep their
+ * current schema, and migrations evolve them further.
+ *
+ * NOTE: the `scope_key` column on `workflow_runs` is intentionally NOT declared
+ * here. It is added by migration `001-add-scope-key`. Fresh databases will run
+ * the migration immediately on first open; pre-versioning databases that
+ * already have the column are bootstrapped — see {@link runMigrations}.
+ */
+function ensureBaseSchema(db) {
     db.exec(`
     CREATE TABLE IF NOT EXISTS workflow_runs (
       id                TEXT PRIMARY KEY,
       workflow_ref      TEXT NOT NULL,
-      scope_key         TEXT,
       workflow_entry_id INTEGER,
       workflow_title    TEXT NOT NULL,
       status            TEXT NOT NULL CHECK (status IN ('active', 'completed', 'blocked', 'failed')),
@@ -53,12 +101,94 @@ function ensureWorkflowSchema(db) {
     CREATE INDEX IF NOT EXISTS idx_workflow_run_steps_run_sequence
       ON workflow_run_steps(run_id, sequence_index);
   `);
-    const columns = db
-        .query("PRAGMA table_info(workflow_runs)")
-        .all()
-        .map((column) => column.name);
-    if (!columns.includes("scope_key")) {
-        db.exec("ALTER TABLE workflow_runs ADD COLUMN scope_key TEXT");
+}
+/**
+ * All workflow.db migrations in application order. New migrations are
+ * APPENDED — never inserted in the middle or reordered.
+ */
+const MIGRATIONS = [
+    // ── Migration 001 — add scope_key column ────────────────────────────────────
+    //
+    // Adds the `scope_key` column to `workflow_runs` so runs can be partitioned
+    // per stash/scope. Pre-versioning databases that already have this column
+    // are bootstrapped before this migration runs — see runMigrations().
+    {
+        id: "001-add-scope-key",
+        up: `
+      ALTER TABLE workflow_runs ADD COLUMN scope_key TEXT;
+
+      CREATE INDEX IF NOT EXISTS idx_workflow_runs_scope_ref_status
+        ON workflow_runs(scope_key, workflow_ref, status);
+    `,
+    },
+];
+/**
+ * Stable id of the scope_key migration. Exported for bootstrap detection and
+ * tests.
+ */
+const SCOPE_KEY_MIGRATION_ID = "001-add-scope-key";
+/**
+ * Create the migrations table if it does not exist. Called unconditionally on
+ * every open so a fresh database bootstraps correctly.
+ */
+function ensureMigrationsTable(db) {
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS schema_migrations (
+      id         TEXT    PRIMARY KEY,
+      applied_at TEXT    NOT NULL DEFAULT (datetime('now'))
+    );
+  `);
+}
+/**
+ * Detect whether a column exists on a given table.
+ */
+function hasColumn(db, table, column) {
+    const rows = db.query(`PRAGMA table_info(${table})`).all();
+    return rows.some((r) => r.name === column);
+}
+/**
+ * Back-fill `schema_migrations` rows for any schema state that existed before
+ * this file gained migration tracking.
+ *
+ * The pre-versioning code added the `scope_key` column on `workflow_runs` via
+ * an ad-hoc PRAGMA / ALTER TABLE pair. Those databases must not re-run the
+ * scope_key migration (the ALTER would fail with "duplicate column name"
+ * since the migration body does not use IF NOT EXISTS — SQLite does not
+ * support that clause on ALTER TABLE ADD COLUMN). Instead, we mark the
+ * migration as already applied.
+ *
+ * This function is a no-op on fresh databases: the `scope_key` column does
+ * not exist, so the migration runs normally and records itself.
+ */
+function bootstrapPreVersioningDb(db) {
+    const alreadyRecorded = db.prepare("SELECT 1 FROM schema_migrations WHERE id = ?").get(SCOPE_KEY_MIGRATION_ID);
+    if (alreadyRecorded)
+        return;
+    if (hasColumn(db, "workflow_runs", "scope_key")) {
+        db.prepare("INSERT INTO schema_migrations (id) VALUES (?)").run(SCOPE_KEY_MIGRATION_ID);
+    }
+}
+/**
+ * Apply every pending migration in a single transaction per migration.
+ *
+ * Each migration is applied in its own transaction so a failure in migration N
+ * does not roll back already-applied migrations 1..N-1. The migration row is
+ * inserted AFTER the DDL succeeds — a crash mid-migration leaves no row and
+ * the migration is retried on next open.
+ *
+ * Called automatically by {@link openWorkflowDatabase}.
+ */
+export function runMigrations(db) {
+    ensureMigrationsTable(db);
+    bootstrapPreVersioningDb(db);
+    const appliedRows = db.prepare("SELECT id FROM schema_migrations").all();
+    const applied = new Set(appliedRows.map((r) => r.id));
+    for (const migration of MIGRATIONS) {
+        if (applied.has(migration.id))
+            continue;
+        db.transaction(() => {
+            db.exec(migration.up);
+            db.prepare("INSERT INTO schema_migrations (id) VALUES (?)").run(migration.id);
+        })();
     }
-    db.exec("CREATE INDEX IF NOT EXISTS idx_workflow_runs_scope_ref_status ON workflow_runs(scope_key, workflow_ref, status)");
 }

package/dist/workflows/document-cache.js

@@ -1,13 +1,6 @@
-/**
- * Side-channel cache that lets the workflow renderer hand a validated
- * `WorkflowDocument` to the indexer without persisting it through the
- * `entry_json` column or widening `StashEntry` with a workflow-shaped field.
- *
- * The renderer is called during metadata generation; the indexer writes the
- * document to `workflow_documents` after `upsertEntry` returns the row id.
- * A WeakMap keyed by the entry object preserves the parse work between the
- * two phases without leaking memory if the entry is dropped.
- */
+// 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/.
 const cache = new WeakMap();
 export function cacheWorkflowDocument(entry, doc) {
     cache.set(entry, doc);

package/dist/workflows/parser.js

@@ -1,3 +1,6 @@
+// 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/.
 /**
  * Workflow markdown → WorkflowDocument JSON.
  *

package/dist/workflows/renderer.js

@@ -1,3 +1,6 @@
+// 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/.
 /**
  * Show + indexing renderer for workflow assets.
  *
@@ -8,6 +11,7 @@
  */
 import { makeAssetRef } from "../core/asset-ref";
 import { UsageError } from "../core/errors";
+import { registerMetadataContributor } from "../indexer/metadata-contributors";
 import { cacheWorkflowDocument } from "./document-cache";
 import { parseWorkflow } from "./parser";
 function shellQuote(value) {
@@ -54,8 +58,12 @@ export const workflowMdRenderer = {
             })),
         };
     },
-    extractMetadata(entry, ctx) {
-        const doc = loadDocument(ctx);
+};
+registerMetadataContributor({
+    name: "workflow-document-metadata",
+    appliesTo: ({ rendererName }) => rendererName === "workflow-md",
+    contribute(entry, { renderContext }) {
+        const doc = loadDocument(renderContext);
         const hints = new Set(entry.searchHints ?? []);
         hints.add(doc.title);
         for (const step of doc.steps) {
@@ -75,4 +83,4 @@ export const workflowMdRenderer = {
         }
         cacheWorkflowDocument(entry, doc);
     },
-};
+});

package/dist/workflows/runs.js

@@ -1,3 +1,6 @@
+// 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 { randomUUID } from "node:crypto";
 import fs from "node:fs";
 import { parseAssetRef } from "../core/asset-ref";
@@ -13,64 +16,58 @@ import { formatWorkflowErrors } from "./authoring";
 import { closeWorkflowDatabase, openWorkflowDatabase } from "./db";
 import { parseWorkflow } from "./parser";
 import { getCurrentWorkflowScopeKey } from "./scope-key";
+async function withWorkflowDb(fn) {
+    const db = openWorkflowDatabase();
+    try {
+        return await Promise.resolve(fn(db));
+    }
+    finally {
+        closeWorkflowDatabase(db);
+    }
+}
 export async function startWorkflowRun(ref, params = {}) {
     const asset = await loadWorkflowAsset(ref);
-    const workflowDb = openWorkflowDatabase();
-    try {
+    return withWorkflowDb(async (db) => {
         const now = new Date().toISOString();
         const runId = randomUUID();
         const scopeKey = getCurrentWorkflowScopeKey();
         const currentStepId = asset.steps[0]?.id ?? null;
         const workflowEntryId = resolveWorkflowEntryId(asset.sourcePath, asset.ref);
-        workflowDb.transaction(() => {
-            workflowDb
-                .prepare(`INSERT INTO workflow_runs (
+        db.transaction(() => {
+            db.prepare(`INSERT INTO workflow_runs (
           id, workflow_ref, scope_key, workflow_entry_id, workflow_title, status, params_json, current_step_id, created_at, updated_at
-        ) VALUES (?, ?, ?, ?, ?, 'active', ?, ?, ?, ?)`)
-                .run(runId, asset.ref, scopeKey, workflowEntryId, asset.title, JSON.stringify(params), currentStepId, now, now);
-            const insertStep = workflowDb.prepare(`INSERT INTO workflow_run_steps (
+        ) VALUES (?, ?, ?, ?, ?, 'active', ?, ?, ?, ?)`).run(runId, asset.ref, scopeKey, workflowEntryId, asset.title, JSON.stringify(params), currentStepId, now, now);
+            const insertStep = db.prepare(`INSERT INTO workflow_run_steps (
           run_id, step_id, step_title, instructions, completion_json, sequence_index, status
         ) VALUES (?, ?, ?, ?, ?, ?, 'pending')`);
             for (const step of asset.steps) {
                 insertStep.run(runId, step.id, step.title, step.instructions, step.completionCriteria ? JSON.stringify(step.completionCriteria) : null, step.sequenceIndex ?? 0);
             }
         })();
-        const result = getWorkflowStatus(runId);
+        const result = await getWorkflowStatus(runId);
         appendEvent({
             eventType: "workflow_started",
             ref: ref,
             metadata: { runId: result.run.id, title: result.run.workflowTitle },
         });
         return result;
-    }
-    finally {
-        closeWorkflowDatabase(workflowDb);
-    }
+    });
 }
-export function getWorkflowStatus(runId) {
-    const workflowDb = openWorkflowDatabase();
-    try {
-        const run = readWorkflowRun(workflowDb, runId);
-        const steps = readWorkflowRunSteps(workflowDb, run.id);
+export async function getWorkflowStatus(runId) {
+    return withWorkflowDb((db) => {
+        const run = readWorkflowRun(db, runId);
+        const steps = readWorkflowRunSteps(db, run.id);
         return buildWorkflowRunDetail(run, steps);
-    }
-    finally {
-        closeWorkflowDatabase(workflowDb);
-    }
+    });
 }
-export function hasWorkflowRun(runId) {
-    const workflowDb = openWorkflowDatabase();
-    try {
-        const row = workflowDb.prepare("SELECT 1 FROM workflow_runs WHERE id = ? LIMIT 1").get(runId);
+export async function hasWorkflowRun(runId) {
+    return withWorkflowDb((db) => {
+        const row = db.prepare("SELECT 1 FROM workflow_runs WHERE id = ? LIMIT 1").get(runId);
         return !!row;
-    }
-    finally {
-        closeWorkflowDatabase(workflowDb);
-    }
+    });
 }
-export function listWorkflowRuns(input) {
-    const workflowDb = openWorkflowDatabase();
-    try {
+export async function listWorkflowRuns(input) {
+    return withWorkflowDb((db) => {
         const filters = [];
         const params = [];
         const scopeKey = getCurrentWorkflowScopeKey();
@@ -88,20 +85,16 @@ export function listWorkflowRuns(input) {
             filters.push("status IN ('active', 'blocked')");
         }
         const where = filters.length > 0 ? `WHERE ${filters.join(" AND ")}` : "";
-        const rows = workflowDb
+        const rows = db
             .prepare(`SELECT * FROM workflow_runs ${where} ORDER BY updated_at DESC, created_at DESC`)
             .all(...params);
         return { runs: rows.map(toWorkflowRunSummary) };
-    }
-    finally {
-        closeWorkflowDatabase(workflowDb);
-    }
+    });
 }
 export async function getNextWorkflowStep(specifier, params) {
-    const workflowDb = openWorkflowDatabase();
-    try {
-        const { run, autoStarted } = await resolveRunSpecifier(workflowDb, specifier, params);
-        const steps = readWorkflowRunSteps(workflowDb, run.id);
+    return withWorkflowDb(async (db) => {
+        const { run, autoStarted } = await resolveRunSpecifier(db, specifier, params);
+        const steps = readWorkflowRunSteps(db, run.id);
         const currentStep = resolveCurrentStep(run, steps);
         const done = run.status === "completed" ? true : undefined;
         return {
@@ -115,54 +108,44 @@ export async function getNextWorkflowStep(specifier, params) {
             ...(done ? { done } : {}),
             ...(autoStarted ? { autoStarted } : {}),
         };
-    }
-    finally {
-        closeWorkflowDatabase(workflowDb);
-    }
+    });
 }
-export function resumeWorkflowRun(runId) {
-    const workflowDb = openWorkflowDatabase();
-    try {
-        const run = readWorkflowRun(workflowDb, runId);
+export async function resumeWorkflowRun(runId) {
+    return withWorkflowDb((db) => {
+        const run = readWorkflowRun(db, runId);
         if (run.status === "completed") {
             throw new UsageError(`Workflow run ${run.id} is already completed and cannot be resumed.`);
         }
         if (run.status === "active") {
-            const steps = readWorkflowRunSteps(workflowDb, run.id);
+            const steps = readWorkflowRunSteps(db, run.id);
             return buildWorkflowRunDetail(run, steps);
         }
         // blocked or failed → flip back to active and re-open the current step so
         // it can be reclassified (completed, failed, skipped) after resuming.
         const now = new Date().toISOString();
-        workflowDb.transaction(() => {
+        db.transaction(() => {
             if (run.current_step_id) {
-                workflowDb
-                    .prepare(`UPDATE workflow_run_steps
+                db.prepare(`UPDATE workflow_run_steps
              SET status = 'pending', notes = NULL, evidence_json = NULL, completed_at = NULL
-             WHERE run_id = ? AND step_id = ? AND status IN ('blocked', 'failed')`)
-                    .run(run.id, run.current_step_id);
+             WHERE run_id = ? AND step_id = ? AND status IN ('blocked', 'failed')`).run(run.id, run.current_step_id);
             }
-            workflowDb.prepare("UPDATE workflow_runs SET status = 'active', updated_at = ? WHERE id = ?").run(now, run.id);
+            db.prepare("UPDATE workflow_runs SET status = 'active', updated_at = ? WHERE id = ?").run(now, run.id);
         })();
         const updated = { ...run, status: "active", updated_at: now };
-        const steps = readWorkflowRunSteps(workflowDb, run.id);
+        const steps = readWorkflowRunSteps(db, run.id);
         return buildWorkflowRunDetail(updated, steps);
-    }
-    finally {
-        closeWorkflowDatabase(workflowDb);
-    }
+    });
 }
-export function completeWorkflowStep(input) {
-    const workflowDb = openWorkflowDatabase();
-    try {
+export async function completeWorkflowStep(input) {
+    return withWorkflowDb((db) => {
         let updatedRun;
         let refreshedSteps = [];
-        workflowDb.transaction(() => {
-            const run = readWorkflowRun(workflowDb, input.runId);
+        db.transaction(() => {
+            const run = readWorkflowRun(db, input.runId);
             if (run.status !== "active") {
                 throw new UsageError(`Workflow run ${run.id} is ${run.status} and cannot be updated.`);
             }
-            const existing = workflowDb
+            const existing = db
                 .prepare("SELECT * FROM workflow_run_steps WHERE run_id = ? AND step_id = ?")
                 .get(run.id, input.stepId);
             if (!existing) {
@@ -175,18 +158,14 @@ export function completeWorkflowStep(input) {
                 throw new UsageError(`Step "${input.stepId}" is not the current step for workflow run ${run.id}. Complete "${run.current_step_id}" first.`);
             }
             const completedAt = new Date().toISOString();
-            workflowDb
-                .prepare(`UPDATE workflow_run_steps
+            db.prepare(`UPDATE workflow_run_steps
            SET status = ?, notes = ?, evidence_json = ?, completed_at = ?
-           WHERE run_id = ? AND step_id = ?`)
-                .run(input.status, input.notes?.trim() || null, input.evidence ? JSON.stringify(input.evidence) : null, completedAt, run.id, input.stepId);
-            refreshedSteps = readWorkflowRunSteps(workflowDb, run.id);
+           WHERE run_id = ? AND step_id = ?`).run(input.status, input.notes?.trim() || null, input.evidence ? JSON.stringify(input.evidence) : null, completedAt, run.id, input.stepId);
+            refreshedSteps = readWorkflowRunSteps(db, run.id);
             const state = deriveRunState(refreshedSteps);
-            workflowDb
-                .prepare(`UPDATE workflow_runs
+            db.prepare(`UPDATE workflow_runs
            SET status = ?, current_step_id = ?, updated_at = ?, completed_at = ?
-           WHERE id = ?`)
-                .run(state.status, state.currentStepId, completedAt, state.completedAt, run.id);
+           WHERE id = ?`).run(state.status, state.currentStepId, completedAt, state.completedAt, run.id);
             updatedRun = {
                 ...run,
                 status: state.status,
@@ -205,10 +184,7 @@ export function completeWorkflowStep(input) {
             appendEvent({ eventType: "workflow_finished", ref: detail.run.workflowRef, metadata: { runId: input.runId } });
         }
         return detail;
-    }
-    finally {
-        closeWorkflowDatabase(workflowDb);
-    }
+    });
 }
 async function resolveRunSpecifier(db, specifier, params) {
     const explicitRun = db.prepare("SELECT * FROM workflow_runs WHERE id = ?").get(specifier);
@@ -262,7 +238,7 @@ async function loadWorkflowAsset(ref) {
     if (!assetPath) {
         throw new NotFoundError(`Workflow not found for ref: workflow:${parsed.name}`);
     }
-    const resolvedSourcePath = sourcePath ?? loadConfig().stashDir ?? assetPath;
+    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);
@@ -452,18 +428,13 @@ function parseJsonArray(value) {
     }
     return undefined;
 }
-export function getActiveWorkflowRun(scopeKey = getCurrentWorkflowScopeKey()) {
-    try {
-        const workflowDb = openWorkflowDatabase();
-        const row = workflowDb
+export async function getActiveWorkflowRun(scopeKey = getCurrentWorkflowScopeKey()) {
+    return withWorkflowDb((db) => {
+        const row = db
             .query("SELECT id, current_step_id, workflow_ref FROM workflow_runs WHERE scope_key = ? AND status IN ('active', 'blocked') ORDER BY updated_at DESC LIMIT 1")
             .get(scopeKey);
-        closeWorkflowDatabase(workflowDb);
         if (!row)
             return null;
         return { runId: row.id, stepId: row.current_step_id, workflowRef: row.workflow_ref };
-    }
-    catch {
-        return null; // fail-open: never crash show output due to DB error
-    }
+    }).catch(() => null); // fail-open: never crash show output due to DB error
 }

package/dist/workflows/schema.js

@@ -1,3 +1,6 @@
+// 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/.
 /**
  * Validated JSON shape for a workflow asset.
  *

package/dist/workflows/scope-key.js

@@ -1,3 +1,6 @@
+// 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 { createHash } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";

package/dist/workflows/validator.js

@@ -1,12 +1,8 @@
-/**
- * Cross-cutting semantic checks over an assembled WorkflowDocument draft.
- *
- * The parser handles per-line shape checks; this module runs rules that need
- * the whole document or the raw frontmatter at once: duplicate step IDs,
- * step-id format, and the frontmatter key whitelist.
- */
+// 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/.
 const STEP_ID_REGEX = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
-const ALLOWED_FRONTMATTER_KEYS = new Set(["description", "tags", "params"]);
+const ALLOWED_FRONTMATTER_KEYS = new Set(["description", "tags", "params", "name", "updated"]);
 export function runSemanticChecks(draft, frontmatterData, frontmatterEndLine, errors) {
     checkFrontmatterKeys(frontmatterData, frontmatterEndLine, errors);
     checkStepIdFormat(draft, errors);

package/dist/workflows/workflow-template.md

@@ -0,0 +1,24 @@
+---
+description: Describe what this workflow accomplishes
+tags:
+  - example
+params:
+  example_param: Explain this parameter
+---
+
+# Workflow: {{TITLE}}
+
+## Step: {{FIRST_STEP_TITLE}}
+Step ID: {{FIRST_STEP_ID}}
+
+### Instructions
+Describe what to do in this step.
+
+### Completion Criteria
+- Confirm the first step is complete
+
+## Step: Second Step
+Step ID: second-step
+
+### Instructions
+Describe what happens next.

package/docs/README.md

@@ -11,7 +11,7 @@
 ## Upgrading
 
 - [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.7.0)](migration/release-notes/0.7.0.md) -- Per-release notes drop into `migration/release-notes/`, including current pre-release removals
+- [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
 
 ## Reference
@@ -28,17 +28,24 @@
 - [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
 
+## Operations
+
+- [Improve Stats](improve-stats.md) -- Analyze `akm improve` run logs with the `scripts/improve-stats/` toolkit (runs-trend, run-show, actions-breakdown, lint-current)
+
 ## Internals
 
 - [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
+- [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
 - [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
-- [akm-bench](technical/benchmark.md) -- Search-quality benchmark suite
+- `technical/benchmark.md` (planned) -- Search-quality benchmark suite
 
 ## Posts