akm-cli 0.9.0-rc.3 → 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/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

@@ -7,8 +7,10 @@ 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.

package/docs/migration/v0.8-to-v0.9.md

@@ -25,25 +25,34 @@ Use this package-manager/manual boundary procedure instead:
    package; a standalone operator should retain the old executable. Keep the
    independent data backup in either case.
 5. Invoke the newly installed or staged 0.9 binary, whose migration startup
-   bypass can read the old installation without loading its config normally:
+   bypass can read the old installation without loading its config normally.
+6. After apply succeeds, run `akm tasks sync` with that same 0.9 binary and
+   inspect `skipped` before restarting schedulers. Sync registers the migrated
+   task view and quarantines the obsolete published backup task described below.
 
 Package-manager installation examples for step 4:
 
+Package-manager installs require Node.js >= 20.12. If Bun >= 1.0 is also on
+`PATH`, the installed launcher prefers Bun after Node.js bootstraps it.
+
 ```sh
 npm install -g akm-cli@0.9.0
-# or: bun install -g akm-cli@0.9.0
 # or: pnpm add -g akm-cli@0.9.0
 ```
 
+Commands for steps 5 and 6:
+
 ```sh
 # Package-manager install: this `akm` is now the 0.9 binary.
 akm migrate status --config ./prepared-0.9.json
 akm migrate apply --config ./prepared-0.9.json --dry-run
 akm migrate apply --config ./prepared-0.9.json
+akm tasks sync
 
 # Or invoke a checksummed staged standalone binary explicitly.
 ./akm-0.9 migrate status --config ./prepared-0.9.json
 ./akm-0.9 migrate apply --config ./prepared-0.9.json
+./akm-0.9 tasks sync
 ```
 
 Status and dry-run perform the same read-only eligibility checks and report the
@@ -113,8 +122,10 @@ Replace `profiles.llm.<name>` and `profiles.agent.<name>` with one
 Do not reuse a colliding LLM and agent profile name without deciding which new
 engine names make the distinction clear. AKM cannot safely infer that choice.
 
-Task files are strict YAML v2. Add `version: 2`, replace prompt `profile:` with
-`engine:`, and retain only fields valid for the target:
+New task files use strict YAML v2. Existing valid 0.8 task files continue to
+load without being rewritten: AKM normalizes their missing/`1` version,
+prompt `profile:` field, permissive scalar forms, and `akm improve --profile`
+commands in memory. Update user-authored files to `version: 2` when editing them:
 
 ```yaml
 version: 2
@@ -128,11 +139,55 @@ enabled: true
 
 Prompt tasks may use `engine`, `model`, `timeoutMs`, and `llm`; command tasks
 may use `timeoutMs`; workflow tasks may use `params`. Unknown and wrong-target
-keys are errors. `akm tasks list`, `sync`, and `doctor` report stale v1 files;
-`show`, `run`, `enable`, and `disable` reject them without mutation. Regenerate
-the known default improve tasks or replace `akm improve --profile <name>` with
-`akm improve --strategy <name>` yourself. AKM never rewrites arbitrary shell
-commands.
+keys are errors in v2. Unsupported future versions are reported by `akm tasks
+list`, `sync`, and `doctor`. The 0.8 reader normalization changes only the
+removed AKM spellings; arbitrary shell commands and task files are never
+rewritten.
+
+For 0.8 command tasks, syntax migration and self-invocation routing are separate.
+`--profile` is lowered only for a PATH-selected bare `akm`/`akm.exe`, including
+when it follows supported `env` options and assignments. The scanner recognizes
+citty-valid global forms before `improve`, including `--no-quiet`,
+`--no-verbose`, `--quiet=false`, `--verbose=false`, and value options such as
+`--format json`. An explicit `./akm`, `/opt/vendor/akm`, or other executable path
+is operator-owned: it keeps selecting that exact binary and its command argv is
+retained exactly. In particular, AKM does not change syntax sent to a retained
+0.8 binary. Version-2 commands receive no compatibility rewriting.
+
+The published 0.8 core `backup.yml` is a special unsafe legacy definition. It
+was enabled and ran `akm db backups`, but that command only listed snapshots; it
+did not create a recurring backup. In 0.9, `tasks add` refuses the enabled exact
+bare-self command before changing its source file or scheduler. `tasks sync`
+reports it in `skipped`, does not install a missing entry, and disables an
+existing scheduler entry while preserving the task file byte-for-byte. `tasks
+enable` also refuses to re-enable it. This quarantine applies only when bare
+`akm`/`akm.exe` is followed by exactly `db backups`; an explicit executable path
+is operator-owned and is not quarantined. Use `akm backup create --for 0.9.0`
+for an explicit migration recovery snapshot. Existing 0.8 data-directory backup
+folders are left untouched by migration.
+
+Task `enabled` state controls scheduler-originated execution, not explicit
+operator invocation. `akm tasks run <id>` intentionally runs a disabled task so
+manual catch-up definitions remain useful. Backend-generated invocations carry
+the internal `--scheduled` marker and record a `disabled` result without running
+the target. Do not use the manual command as a scheduler replacement.
+
+Canonical task IDs contain only letters, digits, dots, underscores, and dashes,
+start with a letter or digit, are at most 228 characters, omit `.yml`/`.yaml`,
+and cannot use Windows device aliases such as `CON`, `NUL`, `COM1`, or `LPT1`
+(including aliases followed by a dot). The 228-character limit is the final
+portable bound after scheduler and filename overhead. These portability checks
+apply on every platform. For command-line compatibility only, a trailing
+lowercase `.yml` or legacy `.md` is stripped from an ID; a filename discovered
+under `tasks/` must already be canonical and is never renamed. Sync skips a
+non-portable file and disables any matching installed entry rather than guessing
+a replacement ID.
+
+Canonical migration preserves 0.8 `state.db` task-history rows and their log
+paths. One historical detail cannot be recovered: published 0.8.14 stored
+command-task history with `target_kind=prompt`. Because the durable row contains
+no command marker, 0.9 preserves and exposes it as legacy prompt history rather
+than inventing a command classification. New runs use the correct target kind.
 
 ## CLI rename table (old → new, removed 0.9.0)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akm-cli",
-  "version": "0.9.0-rc.3",
+  "version": "0.9.0-rc.4",
   "type": "module",
   "description": "akm (Agent Knowledge Management) — A package manager for AI agent skills, commands, tools, and knowledge. Works with Claude Code, OpenCode, Cursor, and any AI coding assistant.",
   "keywords": [
@@ -52,7 +52,7 @@
     "akm-migrate-storage": "dist/akm-migrate-storage"
   },
   "scripts": {
-    "preinstall": "node -e \"var ua=process.env.npm_config_user_agent||'';var v=(process.versions.node||'0').split('.').map(function(n){return parseInt(n,10)||0});var ok=v[0]>20||(v[0]===20&&(v[1]>12||(v[1]===12&&v[2]>=0)));if(process.versions.bun||ua.startsWith('bun/')||process.env.BUN_INSTALL||ok){process.exit(0)}console.error('\\n  ERROR: akm-cli requires the Bun runtime (https://bun.sh), Node.js >= 20.12, or the prebuilt binary.\\n  Install options:\\n    1. Bun:    curl -fsSL https://bun.sh/install | bash  &&  bun install -g akm-cli\\n    2. Node:   upgrade to Node.js 20.12 or newer (https://nodejs.org)\\n    3. Binary: curl -fsSL https://github.com/itlackey/akm/releases/latest/download/install.sh | bash\\n');process.exit(1)\"",
+    "preinstall": "node -e \"var v=(process.versions.node||'0').split('.').map(function(n){return parseInt(n,10)||0});var ok=v[0]>20||(v[0]===20&&(v[1]>12||(v[1]===12&&v[2]>=0)));if(ok){process.exit(0)}console.error('\\n  ERROR: the akm-cli npm package requires Node.js >= 20.12.\\n  A working Bun >= 1.0 on PATH is optional and preferred for execution.\\n  Upgrade Node.js (https://nodejs.org), or install the runtime-free standalone binary:\\n    curl -fsSL https://github.com/itlackey/akm/releases/latest/download/install.sh | bash\\n');process.exit(1)\"",
     "build": "rm -rf dist && bun scripts/gen-config-schema.ts &&bun run tsc --project ./tsconfig.build.json && bun scripts/copy-assets.ts && bun scripts/fix-esm-extensions.ts",
     "check": "bun run lint && bunx tsc --noEmit && bun run test:unit && bun run test:integration",
     "check:fast": "bun run lint && bunx tsc --noEmit && bun run test:unit",
@@ -94,7 +94,6 @@
     "sqlite-vec": "^0.1.9"
   },
   "engines": {
-    "bun": ">=1.0.0",
     "node": ">=20.12.0"
   },
   "dependencies": {