akm-cli 0.9.0-rc.2 → 0.9.0-rc.4

package/dist/tasks/schedule.js

@@ -15,9 +15,9 @@
  *   • a launchd plist `<StartCalendarInterval>` / `<StartInterval>` (macOS),
  *   • Task Scheduler XML triggers (Windows).
  *
- * The shared subset is `*`, single integers, `*\/N`, plus the `@hourly /
+ * The shared subset is `*`, single integers, `*\/N`, `A-B/N`, plus the `@hourly /
  * @daily / @weekly / @monthly` aliases. Patterns outside that — multi-value
- * lists, ranges, step values other than `*\/N`, day-of-month AND
+ * lists, plain ranges, day-of-month AND
  * day-of-week combinations — are rejected with a {@link UsageError}.
  *
  * Cron is the most permissive of the three backends; some patterns it
@@ -41,9 +41,9 @@ const FIELD_LIMITS = {
     month: { min: 1, max: 12 },
     dow: { min: 0, max: 6 },
 };
-const SUPPORTED_HINT = "Supported subset: `*`, single integers (`5`), step-on-star (`*/N`), and comma lists (`7,37`). " +
+const SUPPORTED_HINT = "Supported subset: `*`, single integers (`5`), steps (`*/N`, `A-B/N`), and comma lists (`7,37`). " +
     "Aliases: `@hourly`, `@daily`, `@weekly`, `@monthly`. " +
-    "Lists, ranges, and named days/months are not supported.";
+    "Plain ranges and named days/months are not supported.";
 export function parseSchedule(input, backend) {
     const cron = expandAlias(input);
     const fields = parseCronFields(cron, input);
@@ -99,6 +99,16 @@ function parseField(raw, name, limit, original) {
         }
         return { kind: "step", step };
     }
+    const rangeStepMatch = raw.match(/^(\d+)-(\d+)\/(\d+)$/);
+    if (rangeStepMatch) {
+        const start = Number(rangeStepMatch[1]);
+        const end = Number(rangeStepMatch[2]);
+        const step = Number(rangeStepMatch[3]);
+        if (start < limit.min || end > limit.max || start > end || step <= 0) {
+            throw new UsageError(`Invalid ${name} range-step "${raw}" in schedule "${original}" (allowed ${limit.min}-${limit.max}).`, "INVALID_FLAG_VALUE");
+        }
+        return { kind: "rangeStep", start, end, step };
+    }
     if (/^\d+$/.test(raw)) {
         const value = Number(raw);
         if (value < limit.min || value > limit.max) {
@@ -128,22 +138,28 @@ export function translateToCron(spec) {
 }
 export function translateToLaunchd(spec) {
     const f = spec.fields;
-    // `*/N` minute (everything else `*`) → StartInterval = N*60 seconds.
-    if (f.minute.kind === "step" &&
+    rejectDomDowCombination(spec, "macOS launchd");
+    // Expand minute steps into clock-minute anchors. StartInterval would drift
+    // from cron whenever the agent is loaded away from a matching boundary.
+    if ((f.minute.kind === "step" || f.minute.kind === "rangeStep") &&
         f.hour.kind === "star" &&
         f.dom.kind === "star" &&
         f.month.kind === "star" &&
         f.dow.kind === "star") {
-        return { intervalSeconds: f.minute.step * 60 };
+        return { calendars: expandFieldValues(f.minute, FIELD_LIMITS.minute).map((Minute) => ({ Minute })) };
     }
-    // `*/N` hour → StartInterval = N*3600.
+    // Likewise, anchor hour steps to the same hours cron selects each day.
     if (f.minute.kind === "value" &&
-        f.minute.value === 0 &&
-        f.hour.kind === "step" &&
+        (f.hour.kind === "step" || f.hour.kind === "rangeStep") &&
         f.dom.kind === "star" &&
         f.month.kind === "star" &&
         f.dow.kind === "star") {
-        return { intervalSeconds: f.hour.step * 3600 };
+        return {
+            calendars: expandFieldValues(f.hour, FIELD_LIMITS.hour).map((Hour) => ({
+                Minute: f.minute.kind === "value" ? f.minute.value : 0,
+                Hour,
+            })),
+        };
     }
     // Otherwise build a calendar dict from concrete values. launchd treats any
     // omitted key as "every value", so a `*` field translates to "no key".
@@ -166,39 +182,101 @@ export function translateToLaunchd(spec) {
     if (f.dow.kind === "value")
         calendar.Weekday = f.dow.value;
     // launchd's CalendarInterval requires at least one specific key. If every
-    // field is `*` the schedule has no anchor and we'd need a StartInterval
-    // instead — treat this as "every minute".
+    // Expand every-minute to explicit minute boundaries rather than a
+    // load-relative 60-second interval.
     if (Object.keys(calendar).length === 0) {
-        return { intervalSeconds: 60 };
+        return {
+            calendars: expandFieldValues({ kind: "step", step: 1 }, FIELD_LIMITS.minute).map((Minute) => ({ Minute })),
+        };
     }
     return { calendar };
 }
+function expandFieldValues(field, limit) {
+    const start = field.kind === "rangeStep" ? field.start : limit.min;
+    const end = field.kind === "rangeStep" ? field.end : limit.max;
+    const values = [];
+    for (let value = start; value <= end; value += field.step)
+        values.push(value);
+    return values;
+}
 function rejectStepInsideCalendar(field, name, spec) {
     if (field.kind === "step") {
         throw new UsageError(`Schedule "${spec.raw}" uses step (${name} = */N) in a position macOS launchd cannot express. ${SUPPORTED_HINT}`, "INVALID_FLAG_VALUE", "Either restrict the step to the minute or hour field only, or rewrite the schedule with concrete values.");
     }
+    if (field.kind === "rangeStep") {
+        throw new UsageError(`Schedule "${spec.raw}" uses range-step (${name} = A-B/N) in a position macOS launchd cannot express. ${SUPPORTED_HINT}`, "INVALID_FLAG_VALUE", "Restrict the range-step to the minute or hour field, or rewrite the schedule with a concrete value.");
+    }
     if (field.kind === "list") {
         throw new UsageError(`Schedule "${spec.raw}" uses comma list (${name} = a,b,...) which macOS launchd cannot express as a single trigger. ${SUPPORTED_HINT}`, "INVALID_FLAG_VALUE", "Either install one task per list element, or rewrite the schedule with a step (`*/N`) or single value.");
     }
 }
+const MAX_SCHTASKS_TRIGGERS = 48;
 export function translateToSchtasks(spec) {
     const f = spec.fields;
-    // `*/N` minute → MINUTE, every N.
+    rejectDomDowCombination(spec, "Windows Task Scheduler");
+    // A repetition interval is cron-equivalent indefinitely only when it divides
+    // the field's wall-clock cycle. Other steps must reset at every hour.
     if (f.minute.kind === "step" &&
         f.hour.kind === "star" &&
         f.dom.kind === "star" &&
         f.month.kind === "star" &&
         f.dow.kind === "star") {
+        if (60 % f.minute.step !== 0) {
+            return minuteValuesTrigger(expandFieldValues(f.minute, FIELD_LIMITS.minute), spec);
+        }
         return { kind: "minute", everyMinutes: f.minute.step };
     }
-    // `0 */N * * *` → HOURLY, every N.
+    if (f.minute.kind === "rangeStep" &&
+        f.hour.kind === "star" &&
+        f.dom.kind === "star" &&
+        f.month.kind === "star" &&
+        f.dow.kind === "star") {
+        if (f.minute.start === FIELD_LIMITS.minute.min && f.minute.end === FIELD_LIMITS.minute.max) {
+            if (60 % f.minute.step === 0)
+                return { kind: "minute", everyMinutes: f.minute.step };
+        }
+        return minuteValuesTrigger(expandFieldValues(f.minute, FIELD_LIMITS.minute), spec);
+    }
+    // Fixed-minute hour schedules can use one daily-reset repetition only when
+    // the interval divides 24 hours. Non-divisors become explicit daily times.
     if (f.minute.kind === "value" &&
-        f.minute.value === 0 &&
         f.hour.kind === "step" &&
         f.dom.kind === "star" &&
         f.month.kind === "star" &&
         f.dow.kind === "star") {
-        return { kind: "hour", everyHours: f.hour.step };
+        if (24 % f.hour.step === 0 && f.hour.step < 24) {
+            return { kind: "hour", everyHours: f.hour.step, atMinute: f.minute.value };
+        }
+        return {
+            kind: "hourValues",
+            hours: expandFieldValues(f.hour, FIELD_LIMITS.hour),
+            atMinute: f.minute.value,
+        };
+    }
+    if (f.minute.kind === "value" &&
+        f.hour.kind === "rangeStep" &&
+        f.dom.kind === "star" &&
+        f.month.kind === "star" &&
+        f.dow.kind === "star") {
+        if (f.hour.start === FIELD_LIMITS.hour.min && f.hour.end === FIELD_LIMITS.hour.max) {
+            if (24 % f.hour.step === 0 && f.hour.step < 24) {
+                return { kind: "hour", everyHours: f.hour.step, atMinute: f.minute.value };
+            }
+        }
+        return {
+            kind: "hourValues",
+            hours: expandFieldValues(f.hour, FIELD_LIMITS.hour),
+            atMinute: f.minute.value,
+        };
+    }
+    // `M * * * *` includes the shipped top-of-hour task and arbitrary fixed
+    // minutes. A daily calendar trigger resets the hourly repetition each day.
+    if (f.minute.kind === "value" &&
+        f.hour.kind === "star" &&
+        f.dom.kind === "star" &&
+        f.month.kind === "star" &&
+        f.dow.kind === "star") {
+        return { kind: "hour", everyHours: 1, atMinute: f.minute.value };
     }
     // `M H * * *` → DAILY at H:M.
     if (f.minute.kind === "value" &&
@@ -221,7 +299,18 @@ export function translateToSchtasks(spec) {
             daysOfWeek: [f.dow.value],
         };
     }
-    throw new UsageError(`Schedule "${spec.raw}" cannot be expressed as a Windows Task Scheduler trigger. ${SUPPORTED_HINT}`, "INVALID_FLAG_VALUE", "Use one of: */N minutes, every N hours (0 */N * * *), daily at HH:MM, or weekly on a single weekday.");
+    throw new UsageError(`Schedule "${spec.raw}" cannot be expressed as a Windows Task Scheduler trigger. ${SUPPORTED_HINT}`, "INVALID_FLAG_VALUE", "Use one of: minute steps/range-steps, fixed-minute hour steps/range-steps, hourly, daily, or weekly on a single weekday.");
+}
+function minuteValuesTrigger(minutes, spec) {
+    if (minutes.length > MAX_SCHTASKS_TRIGGERS) {
+        throw new UsageError(`Schedule "${spec.raw}" requires ${minutes.length} native triggers; Windows Task Scheduler allows at most ${MAX_SCHTASKS_TRIGGERS}.`, "INVALID_FLAG_VALUE", "Use a full-field step whose interval divides 60, or reduce the minute range.");
+    }
+    return { kind: "minuteValues", minutes };
+}
+function rejectDomDowCombination(spec, backend) {
+    if (spec.fields.dom.kind !== "star" && spec.fields.dow.kind !== "star") {
+        throw new UsageError(`Schedule "${spec.raw}": day-of-month and day-of-week use OR semantics in cron, which ${backend} cannot express portably.`, "INVALID_FLAG_VALUE", "Use either day-of-month or day-of-week, but not both.");
+    }
 }
 /** Human-readable summary used by `tasks doctor`. */
 export const SCHEDULE_SUPPORTED_SUBSET_HINT = SUPPORTED_HINT;

package/dist/tasks/scheduler-invocation.js

@@ -0,0 +1,86 @@
+// 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 path from "node:path";
+import { resolveStashDir } from "../core/common.js";
+import { ConfigError } from "../core/errors.js";
+import { getCacheDir, getConfigDir, getDataDir } from "../core/paths.js";
+export const SCHEDULED_TASK_CONTEXT_KEYS = [
+    "AKM_STASH_DIR",
+    "AKM_CONFIG_DIR",
+    "AKM_DATA_DIR",
+    "AKM_CACHE_DIR",
+    "AKM_STATE_DIR",
+];
+/** Resolve the complete non-secret AKM directory context captured by schedulers. */
+export function resolveScheduledTaskContext(env = process.env, platform = process.platform) {
+    return canonicalContext({
+        AKM_STASH_DIR: path.resolve(resolveStashDir(undefined, env)),
+        AKM_CONFIG_DIR: path.resolve(getConfigDir(env, platform)),
+        AKM_DATA_DIR: path.resolve(getDataDir(env, platform)),
+        AKM_CACHE_DIR: path.resolve(getCacheDir(env)),
+        // Retain the legacy state root for scheduled commands and upgrade tooling
+        // that still honor it even though current durable state lives under DATA.
+        AKM_STATE_DIR: path.resolve(resolveStateDir(env, platform)),
+    });
+}
+/** Build the one scheduler-generated argv shape consumed by all backends. */
+export function buildScheduledTaskInvocation(akmArgv, id, context) {
+    const environment = canonicalContext(context);
+    return {
+        argv: [...akmArgv, "tasks", "run", id, "--scheduled"],
+        environment,
+    };
+}
+function canonicalContext(input) {
+    const inputKeys = Object.keys(input);
+    if (inputKeys.length !== SCHEDULED_TASK_CONTEXT_KEYS.length ||
+        inputKeys.some((key) => !SCHEDULED_TASK_CONTEXT_KEYS.includes(key))) {
+        throw invalidSchedulerContext();
+    }
+    const context = {};
+    for (const key of SCHEDULED_TASK_CONTEXT_KEYS) {
+        const value = input[key];
+        if (typeof value !== "string" ||
+            value.trim().length === 0 ||
+            containsControlCharacter(value) ||
+            (!path.posix.isAbsolute(value) && !path.win32.isAbsolute(value))) {
+            throw invalidSchedulerContext();
+        }
+        context[key] = value;
+    }
+    return context;
+}
+function containsControlCharacter(value) {
+    for (const char of value) {
+        const code = char.codePointAt(0) ?? 0;
+        if (code < 0x20 || (code >= 0x7f && code <= 0x9f))
+            return true;
+    }
+    return false;
+}
+function resolveStateDir(env, platform) {
+    const override = env.AKM_STATE_DIR?.trim();
+    if (override)
+        return override;
+    if (platform === "win32") {
+        const localAppData = env.LOCALAPPDATA?.trim();
+        if (localAppData)
+            return path.join(localAppData, "akm", "state");
+        const userProfile = env.USERPROFILE?.trim();
+        if (userProfile)
+            return path.join(userProfile, "AppData", "Local", "akm", "state");
+        const appData = env.APPDATA?.trim();
+        if (appData)
+            return path.join(appData, "..", "Local", "akm", "state");
+        throw new ConfigError("Unable to determine state directory. Set LOCALAPPDATA, USERPROFILE, or APPDATA.", "CONFIG_DIR_UNRESOLVABLE");
+    }
+    const xdgStateHome = env.XDG_STATE_HOME?.trim();
+    if (xdgStateHome)
+        return path.join(xdgStateHome, "akm");
+    const home = env.HOME?.trim();
+    return home ? path.join(home, ".local", "state", "akm") : path.join("/tmp", "akm-state");
+}
+function invalidSchedulerContext() {
+    return new ConfigError(`Invalid scheduler context; expected exactly ${SCHEDULED_TASK_CONTEXT_KEYS.join(", ")} as absolute paths.`, "INVALID_CONFIG_FILE");
+}

package/dist/tasks/task-id.js

@@ -0,0 +1,37 @@
+// 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 { UsageError } from "../core/errors.js";
+const VALID_TASK_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+const TASK_FILE_SUFFIX_RE = /\.(?:yml|yaml)$/i;
+const WINDOWS_RESERVED_DEVICE_RE = /^(?:CON|PRN|AUX|NUL|COM[1-9]|LPT[1-9])(?:\.|$)/i;
+const WINDOWS_TASK_PATH_MAX_LENGTH = 238;
+const WINDOWS_TASK_FOLDER_PREFIX_LENGTH = "\\akm\\".length;
+const PORTABLE_FILENAME_COMPONENT_MAX_LENGTH = 255;
+const LAUNCHD_FILENAME_OVERHEAD = "com.akm.task.".length + ".plist".length;
+const TASK_FILENAME_OVERHEAD = ".yml".length;
+const SCHTASKS_TEMP_FILENAME_OVERHEAD = "akm-task-".length + "-".length + 13 + ".xml".length;
+export const MAX_PORTABLE_TASK_ID_LENGTH = Math.min(WINDOWS_TASK_PATH_MAX_LENGTH - WINDOWS_TASK_FOLDER_PREFIX_LENGTH, PORTABLE_FILENAME_COMPONENT_MAX_LENGTH - LAUNCHD_FILENAME_OVERHEAD, PORTABLE_FILENAME_COMPONENT_MAX_LENGTH - TASK_FILENAME_OVERHEAD, PORTABLE_FILENAME_COMPONENT_MAX_LENGTH - SCHTASKS_TEMP_FILENAME_OVERHEAD);
+export function validateTaskId(id) {
+    if (!id) {
+        throw new UsageError("Task id must be non-empty.", "MISSING_REQUIRED_ARGUMENT");
+    }
+    if (!VALID_TASK_ID_RE.test(id)) {
+        throw new UsageError(`Task id "${id}" is invalid. Use letters, digits, dots, underscores, and dashes only.`, "INVALID_FLAG_VALUE");
+    }
+    if (id.length > MAX_PORTABLE_TASK_ID_LENGTH) {
+        throw new UsageError(`Task id "${id}" is invalid. Use at most ${MAX_PORTABLE_TASK_ID_LENGTH} characters for all supported schedulers.`, "INVALID_FLAG_VALUE");
+    }
+    if (TASK_FILE_SUFFIX_RE.test(id)) {
+        throw new UsageError(`Task id "${id}" is invalid. Use the bare task id without a .yml or .yaml suffix.`, "INVALID_FLAG_VALUE");
+    }
+    if (WINDOWS_RESERVED_DEVICE_RE.test(id)) {
+        throw new UsageError(`Task id "${id}" uses a reserved Windows device name. Choose a different task id.`, "INVALID_FLAG_VALUE");
+    }
+    return id;
+}
+export function normaliseTaskId(raw) {
+    // Keep accepting old task-file suffixes at the CLI boundary, but never
+    // normalize filesystem-derived ids into a different filename.
+    return validateTaskId(raw.trim().replace(/\.(yml|md)$/, ""));
+}

package/dist/workflows/db.js

@@ -4,10 +4,10 @@
 import fs from "node:fs";
 import path from "node:path";
 import { acquireMaintenanceActivitySync } from "../core/maintenance-barrier.js";
-import { ensureMigrationBackup, getMigrationBackupDir } from "../core/migration-backup.js";
+import { assertNoPendingMigrationOperation } from "../core/migration-operation.js";
 import { getWorkflowDbPath } from "../core/paths.js";
 import { openDatabase } from "../storage/database.js";
-import { runMigrations as runSqliteMigrations } from "../storage/engines/sqlite-migrations.js";
+import { assertCurrentMigrationLedger, assertMigrationLedger, 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.
@@ -45,24 +45,37 @@ import { applyStandardPragmas } from "../storage/sqlite-pragmas.js";
 // ── Public API ───────────────────────────────────────────────────────────────
 export function openWorkflowDatabase(dbPath = getWorkflowDbPath()) {
     const isCanonical = path.resolve(dbPath) === path.resolve(getWorkflowDbPath());
+    if (isCanonical)
+        assertNoPendingMigrationOperation();
     const releaseActivity = isCanonical ? acquireMaintenanceActivitySync("workflow-db") : undefined;
     let db;
     try {
-        // Preserve an originally absent workflow.db in the recovery manifest. SQLite
-        // creates the file at open time, so the cutover bundle must exist first.
-        if (isCanonical && !fs.existsSync(getMigrationBackupDir()))
-            ensureMigrationBackup();
+        if (isCanonical)
+            assertNoPendingMigrationOperation();
+        const existed = fs.existsSync(dbPath);
         const dir = path.dirname(dbPath);
         if (!fs.existsSync(dir)) {
             fs.mkdirSync(dir, { recursive: true });
         }
+        if (existed) {
+            const preflight = openDatabase(dbPath, { readonly: true });
+            try {
+                if (isCanonical)
+                    assertCurrentMigrationLedger(preflight, WORKFLOW_MIGRATIONS);
+                else
+                    assertMigrationLedger(preflight, WORKFLOW_MIGRATIONS);
+            }
+            finally {
+                preflight.close();
+            }
+        }
         db = openDatabase(dbPath);
         // #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. #628: journal_mode is configurable via AKM_SQLITE_JOURNAL_MODE.
         applyStandardPragmas(db, { dataDir: dir });
         ensureBaseSchema(db);
-        runMigrations(db, { ensureCutoverBackup: isCanonical });
+        runMigrations(db, { applyPending: !(isCanonical && existed) });
         if (!releaseActivity)
             return db;
         const openedDb = db;
@@ -156,7 +169,7 @@ function ensureBaseSchema(db) {
  * All workflow.db migrations in application order. New migrations are
  * APPENDED — never inserted in the middle or reordered.
  */
-const MIGRATIONS = [
+export const WORKFLOW_MIGRATIONS = [
     // ── Migration 001 — add scope_key column ────────────────────────────────────
     //
     // Adds the `scope_key` column to `workflow_runs` so runs can be partitioned
@@ -392,11 +405,9 @@ function bootstrapPreVersioningDb(db) {
  * Called automatically by {@link openWorkflowDatabase}.
  */
 export function runMigrations(db, options) {
-    runSqliteMigrations(db, MIGRATIONS, {
+    runSqliteMigrations(db, WORKFLOW_MIGRATIONS, {
         bootstrap: bootstrapPreVersioningDb,
-        beforeMigration(migration) {
-            if (options?.ensureCutoverBackup && migration.id === "010-ir-v3-engine")
-                ensureMigrationBackup();
-        },
+        applyPending: options?.applyPending,
+        generationMarker: options?.generationMarker,
     });
 }

package/dist/workflows/validator.js

@@ -8,15 +8,37 @@
  * the whole document or the raw frontmatter at once: duplicate step IDs,
  * step-id format, and the frontmatter key whitelist.
  */
+import { parseAssetRef, refToString } from "../core/asset/asset-ref.js";
 import { utf8Bytes, WORKFLOW_MAX_INSTRUCTION_BYTES, WORKFLOW_MAX_PARAMS, WORKFLOW_MAX_STEPS } from "./resource-limits.js";
 const STEP_ID_REGEX = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
-const ALLOWED_FRONTMATTER_KEYS = new Set(["description", "tags", "params", "name", "updated", "when_to_use"]);
+const ALLOWED_FRONTMATTER_KEYS = new Set(["description", "tags", "params", "name", "updated", "when_to_use", "xrefs"]);
 export function runSemanticChecks(draft, frontmatterData, frontmatterEndLine, errors) {
     checkFrontmatterKeys(frontmatterData, frontmatterEndLine, errors);
+    checkXrefs(frontmatterData.xrefs, frontmatterEndLine, errors);
     checkStepIdFormat(draft, errors);
     checkDuplicateStepIds(draft, errors);
     checkResourceLimits(draft, errors);
 }
+function checkXrefs(value, line, errors) {
+    if (value === undefined)
+        return;
+    if (!Array.isArray(value)) {
+        errors.push({ line, message: 'Workflow frontmatter "xrefs" must be an array of canonical asset refs.' });
+        return;
+    }
+    for (const ref of value) {
+        try {
+            if (typeof ref !== "string" || refToString(parseAssetRef(ref)) !== ref)
+                throw new Error("non-canonical ref");
+        }
+        catch {
+            errors.push({
+                line,
+                message: `Workflow frontmatter "xrefs" contains an invalid or non-canonical ref: ${String(ref)}.`,
+            });
+        }
+    }
+}
 function checkResourceLimits(draft, errors) {
     if (draft.steps.length > WORKFLOW_MAX_STEPS) {
         errors.push({ line: 1, message: `Workflow must contain at most ${WORKFLOW_MAX_STEPS} steps.` });
@@ -39,7 +61,7 @@ function checkFrontmatterKeys(data, fmEndLine, errors) {
             continue;
         errors.push({
             line: fmEndLine,
-            message: `Workflow frontmatter "${key}" is not supported. Use only: description, tags, params, name, updated, when_to_use.`,
+            message: `Workflow frontmatter "${key}" is not supported. Use only: description, tags, params, name, updated, when_to_use, xrefs.`,
         });
     }
 }

package/docs/README.md

@@ -0,0 +1,103 @@
+# Documentation
+
+## Getting Started
+
+- [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
+- [Configuration](configuration.md#engines) -- Named LLM and agent engines
+- [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
+- [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
+- [akm-eval](akm-eval.md) -- Standalone toolkit for measuring whether `akm improve` is working
+
+## Agents
+
+- [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
+
+- [Indexer Vertical Slice Refactor Plan](analysis/indexer-vertical-slice-refactor-plan.md)
+- [Indexer Refactor Review (Expert Options)](analysis/indexer-refactor-expert-options.md)
+
+## Design (unshipped work)
+
+- [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
+- [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
+- [Core Principles](technical/akm-core-principles.md) -- Design principles and constraints
+- [Claude Code workflows vs. akm workflows](technical/claude-code-vs-akm-workflows.md) -- Comparing the two things that share a name
+- [Workflow source and IR](features/workflows.md) -- Current workflow execution model
+
+## 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.

package/docs/migration/release-notes/0.9.0.md

@@ -1,13 +1,16 @@
 Migration notes for akm v0.9.0
 
-This is the final 0.9.0 cut. If you were already running a 0.9.0 beta, the
-main upgrade work is to align scripts, prompts, and stash layout with the
-released command surface.
+These notes apply to the 0.9.0 release candidates and final release. If you
+were already running a 0.9.0 beta, align scripts, prompts, and stash layout
+with the current command surface and verify every durable artifact before
+normal use.
 
 Key operator-facing changes:
 
-- Node.js is supported again for the published CLI. Install with Bun, Node.js
-  >= 20.12, or the prebuilt binary.
+- The published npm package requires Node.js >= 20.12 as its cross-platform
+  bootstrap. When a working Bun >= 1.0 is also on `PATH`, the launcher prefers
+  Bun after bootstrap; old, unusable, or absent Bun installations fall back to
+  Node.js. The standalone binaries are runtime-free.
 - The legacy `vault` asset type and `akm vault ...` command family are gone.
   Use `env:` for whole `.env` groups and `secret:` for a single sensitive
   value.
@@ -17,6 +20,9 @@ Key operator-facing changes:
 - Proposal workflow is fully consolidated around `akm improve`, `akm propose`,
   and `akm proposal ...`. Update any old `akm reflect`, `akm distill`,
   `akm accept`, `akm reject`, or `akm proposals` usage.
+- Config, `state.db`, and `workflow.db` are now classified independently by the
+  explicit `akm migrate` coordinator. Normal commands refuse old, future, or
+  divergent durable schemas instead of attempting migration as a side effect.
 
 Primary public command family for 0.9.0:
 
@@ -28,11 +34,24 @@ Primary public command family for 0.9.0:
 - `akm proposal accept <id>`
 - `akm proposal reject <id> --reason "..."`
 
-Recommended post-upgrade checks:
-
-- Run `akm help migrate 0.9.0` on every machine where the CLI is installed.
+Required upgrade checks:
+
+- Before crossing from 0.8 to 0.9, create an independent filesystem backup and
+  prepare a valid 0.9 config. The installed 0.8 binary does not know the 0.9
+  migration protocol: install or stage the 0.9 binary, then run
+  `akm migrate apply --config <prepared-0.9-config>` before any normal command.
+- On an existing 0.9 installation, run `akm migrate status`. If it reports
+  `ready`, run `akm migrate apply`; an already-current active config is used as
+  the target.
+- Do not continue when status reports `blocked`. Preserve the reported backup
+  run and resolve the named artifact or active-operation error first.
+- Restore is explicit and destructive: `akm backup restore --for 0.9.0 --run
+  <backup-run-id> --confirm`. It creates and verifies a rescue backup before
+  replacing current artifacts.
+- Run `akm help migrate 0.9.0` for the storage and command-surface checklist.
 - Run `akm-migrate-storage --yes` once if the stash ever used `vaults/`.
-- Rebuild the index with `akm index`.
+- Rebuild derived search data with `akm index` only after migration status is
+  `current`; indexing does not migrate config or durable schemas.
 - Review agent instructions and docs for old `vault`, `reflect`, and `distill`
   examples.