akm-cli 0.5.0 → 0.6.0-rc2

package/dist/{config.js → core/config.js}

@@ -1,7 +1,10 @@
+import { createHash } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import { filterNonEmptyStrings } from "./common";
+import { ConfigError } from "./errors";
 import { getConfigDir as _getConfigDir, getConfigPath as _getConfigPath } from "./paths";
+import { warn } from "./warn";
 // ── Defaults ────────────────────────────────────────────────────────────────
 export const DEFAULT_CONFIG = {
     semanticSearchMode: "auto",
@@ -29,22 +32,56 @@ export function resetConfigCache() {
     cachedConfig = undefined;
     cachedUserConfig = undefined;
 }
+function hashString(text) {
+    // Simple, fast non-cryptographic hash (FNV-1a 32-bit) — sufficient to detect
+    // content changes between config writes when filesystem mtime resolution is
+    // too coarse to reflect rapid back-to-back writes (common in tests).
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < text.length; i++) {
+        hash ^= text.charCodeAt(i);
+        hash = Math.imul(hash, 0x01000193);
+    }
+    return (hash >>> 0).toString(16);
+}
 export function loadUserConfig() {
     const configPath = getConfigPath();
     let stat;
     try {
         stat = fs.statSync(configPath);
-        if (cachedUserConfig && cachedUserConfig.path === configPath && cachedUserConfig.mtime === stat.mtimeMs) {
-            return cachedUserConfig.config;
-        }
     }
     catch {
         cachedUserConfig = undefined;
         return applyRuntimeEnvApiKeys({ ...DEFAULT_CONFIG });
     }
-    const config = mergeLoadedConfig(DEFAULT_CONFIG, readNormalizedConfig(configPath));
+    // Cache key combines mtimeMs + size + content hash. mtimeMs alone is unreliable
+    // when tests write multiple times within the filesystem mtime resolution
+    // window (often 1ms+). Reading + hashing on cache miss is cheap and ensures
+    // we never serve stale config.
+    let text;
+    try {
+        text = fs.readFileSync(configPath, "utf8");
+    }
+    catch {
+        cachedUserConfig = undefined;
+        return applyRuntimeEnvApiKeys({ ...DEFAULT_CONFIG });
+    }
+    const contentHash = hashString(text);
+    if (cachedUserConfig &&
+        cachedUserConfig.path === configPath &&
+        cachedUserConfig.mtime === stat.mtimeMs &&
+        cachedUserConfig.size === stat.size &&
+        cachedUserConfig.contentHash === contentHash) {
+        return cachedUserConfig.config;
+    }
+    const config = mergeLoadedConfig(DEFAULT_CONFIG, readNormalizedConfigFromText(configPath, text));
     const finalConfig = applyRuntimeEnvApiKeys(config);
-    cachedUserConfig = { config: finalConfig, path: configPath, mtime: stat.mtimeMs };
+    cachedUserConfig = {
+        config: finalConfig,
+        path: configPath,
+        mtime: stat.mtimeMs,
+        size: stat.size,
+        contentHash,
+    };
     return finalConfig;
 }
 export function loadConfig() {
@@ -66,6 +103,7 @@ export function loadConfig() {
 }
 export function saveConfig(config) {
     cachedConfig = undefined;
+    cachedUserConfig = undefined;
     const configPath = getConfigPath();
     const dir = path.dirname(configPath);
     fs.mkdirSync(dir, { recursive: true });
@@ -150,16 +188,16 @@ function pickKnownKeys(raw) {
         const legacySemanticSearch = raw.semanticSearch;
         config.semanticSearchMode = legacySemanticSearch ? "auto" : "off";
     }
-    // Migrate legacy searchPaths into stashes
+    // Migrate legacy searchPaths into sources
     if (Array.isArray(raw.searchPaths)) {
         const legacyPaths = raw.searchPaths.filter((d) => typeof d === "string");
         if (legacyPaths.length > 0) {
-            const existing = config.stashes ?? [];
+            const existing = config.sources ?? [];
             const migrated = legacyPaths
                 .filter((p) => !existing.some((s) => s.type === "filesystem" && s.path === p))
                 .map((p) => ({ type: "filesystem", path: p }));
             if (migrated.length > 0) {
-                config.stashes = [...existing, ...migrated];
+                config.sources = [...existing, ...migrated];
             }
         }
     }
@@ -175,12 +213,32 @@ function pickKnownKeys(raw) {
     const registries = parseRegistriesConfig(raw.registries);
     if (registries)
         config.registries = registries;
-    if (typeof raw.disableGlobalStashes === "boolean") {
+    // Prefer the new `stashInheritance` field; fall back to the legacy boolean
+    // `disableGlobalStashes` so existing config files keep working unchanged.
+    if (raw.stashInheritance === "replace" || raw.stashInheritance === "merge") {
+        config.stashInheritance = raw.stashInheritance;
+    }
+    else if (typeof raw.disableGlobalStashes === "boolean") {
+        config.stashInheritance = raw.disableGlobalStashes ? "replace" : "merge";
         config.disableGlobalStashes = raw.disableGlobalStashes;
     }
-    const stashes = parseStashesConfig(raw.stashes);
-    if (stashes)
-        config.stashes = stashes;
+    // Load `sources` (new key) first, then fall back to legacy `stashes` key.
+    const sources = parseStashesConfig(raw.sources);
+    if (sources) {
+        config.sources = sources;
+    }
+    else {
+        const legacyStashes = parseStashesConfig(raw.stashes);
+        if (legacyStashes) {
+            // Backwards-compat migration: `stashes[]` → `sources[]` in-memory.
+            // Emit a one-time deprecation warning and carry the value forward as
+            // `sources`. The renamed key is persisted on the next `akm config` write.
+            warn('Config key "stashes" is deprecated; rename it to "sources" in your config file ' +
+                `(edit it directly at ${_getConfigPath()}). ` +
+                "Your configuration has been loaded successfully — no manual action is required right now.");
+            config.sources = legacyStashes;
+        }
+    }
     const security = parseSecurityConfig(raw.security);
     if (security)
         config.security = security;
@@ -190,6 +248,18 @@ function pickKnownKeys(raw) {
     if (typeof raw.writable === "boolean") {
         config.writable = raw.writable;
     }
+    if (typeof raw.defaultWriteTarget === "string" && raw.defaultWriteTarget.trim()) {
+        config.defaultWriteTarget = raw.defaultWriteTarget.trim();
+    }
+    if (typeof raw.search === "object" && raw.search !== null && !Array.isArray(raw.search)) {
+        const searchRaw = raw.search;
+        const searchConfig = {};
+        if (typeof searchRaw.minScore === "number" && Number.isFinite(searchRaw.minScore) && searchRaw.minScore >= 0) {
+            searchConfig.minScore = searchRaw.minScore;
+        }
+        if (Object.keys(searchConfig).length > 0)
+            config.search = searchConfig;
+    }
     return config;
 }
 function readNormalizedConfig(configPath) {
@@ -197,6 +267,19 @@ function readNormalizedConfig(configPath) {
     const expanded = raw ? expandEnvVars(raw) : undefined;
     return expanded ? pickKnownKeys(expanded) : undefined;
 }
+function readNormalizedConfigFromText(_configPath, text) {
+    let raw;
+    try {
+        raw = JSON.parse(stripJsonComments(text));
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw))
+        return undefined;
+    const expanded = expandEnvVars(raw);
+    return pickKnownKeys(expanded);
+}
 function parseOutputConfig(value) {
     if (typeof value !== "object" || value === null || Array.isArray(value))
         return undefined;
@@ -380,11 +463,10 @@ function parseLlmConfig(value) {
         console.warn(`[akm] Ignoring llm config: endpoint must start with http:// or https://, got "${obj.endpoint}"`);
         return undefined;
     }
-    if (typeof obj.model !== "string" || !obj.model)
-        return undefined;
+    const model = typeof obj.model === "string" ? obj.model : "";
     const result = {
         endpoint: obj.endpoint,
-        model: obj.model,
+        model,
     };
     if (typeof obj.provider === "string" && obj.provider) {
         result.provider = obj.provider;
@@ -428,11 +510,11 @@ function parseInstalledEntries(value) {
     if (!Array.isArray(value))
         return undefined;
     const entries = value
-        .map((entry) => parseInstalledKitEntry(entry))
+        .map((entry) => parseInstalledStashEntry(entry))
         .filter((entry) => entry !== undefined);
     return entries.length > 0 ? entries : undefined;
 }
-function parseInstalledKitEntry(value) {
+function parseInstalledStashEntry(value) {
     if (typeof value !== "object" || value === null || Array.isArray(value))
         return undefined;
     const obj = value;
@@ -470,6 +552,14 @@ function parseInstalledKitEntry(value) {
 function asNonEmptyString(value) {
     return typeof value === "string" && value ? value : undefined;
 }
+/**
+ * Validate a legacy lockfile/installed-entry source string.
+ *
+ * Restricted to the four kinds that the install pipeline produces
+ * (`"npm" | "github" | "git" | "local"`). The full {@link KitSource} union is
+ * wider, but persisted `installed[]` entries should never carry the runtime
+ * provider kinds (`"filesystem" | "website"`).
+ */
 function asKitSource(value) {
     if (value === "npm" || value === "github" || value === "git" || value === "local")
         return value;
@@ -489,7 +579,7 @@ function parseStashesConfig(value) {
     if (!Array.isArray(value))
         return undefined;
     const entries = value
-        .map((entry) => parseStashConfigEntry(entry))
+        .map((entry) => parseSourceConfigEntry(entry))
         .filter((entry) => entry !== undefined);
     return entries;
 }
@@ -550,13 +640,28 @@ function parseInstallAuditAllowedFinding(value) {
         finding.reason = reason;
     return finding;
 }
-function parseStashConfigEntry(value) {
+/**
+ * Legacy stash type aliases that are normalized to canonical types at
+ * config-load time. Both "context-hub" and "github" were never distinct
+ * provider types — they were always git stashes — so we normalize them in
+ * memory to "git" without rewriting `config.json` on disk.
+ */
+const STASH_TYPE_ALIASES = {
+    "context-hub": "git",
+    github: "git",
+};
+function parseSourceConfigEntry(value) {
     if (typeof value !== "object" || value === null || Array.isArray(value))
         return undefined;
     const obj = value;
-    const type = asNonEmptyString(obj.type);
-    if (!type)
+    const rawType = asNonEmptyString(obj.type);
+    if (!rawType)
         return undefined;
+    if (rawType === "openviking") {
+        const name = asNonEmptyString(obj.name) ?? "unnamed";
+        throw new ConfigError(`openviking is not supported in akm v1. API-backed sources will return as a\nseparate QuerySource tier post-v1. Remove the source named "${name}" from your config file\nor downgrade to 0.6.x. See docs/migration/v1.md.`, "INVALID_CONFIG_FILE", `Run \`akm remove ${name}\` then re-run, or edit your config file directly at ${_getConfigPath()} to remove the openviking entry.`);
+    }
+    const type = STASH_TYPE_ALIASES[rawType] ?? rawType;
     const entry = { type };
     const entryPath = asNonEmptyString(obj.path);
     if (entryPath)
@@ -571,6 +676,16 @@ function parseStashConfigEntry(value) {
         entry.enabled = obj.enabled;
     if (typeof obj.writable === "boolean")
         entry.writable = obj.writable;
+    if (typeof obj.primary === "boolean")
+        entry.primary = obj.primary;
+    // Locked decision 4 (§6 v1 implementation plan): reject writable: true on
+    // website / npm sources at config load. The next sync() would clobber
+    // writes — allowing this is a footgun, not a feature. Throw early so the
+    // user sees the problem at `akm` startup, not when they try to write.
+    if (entry.writable === true && (type === "website" || type === "npm")) {
+        const label = entry.name ? ` "${entry.name}"` : "";
+        throw new ConfigError(`writable: true is only supported on filesystem and git sources (got "${type}" on source${label}).`, "INVALID_CONFIG_FILE", "To author into a checked-out package, add the same path as a separate filesystem source.");
+    }
     if (typeof obj.options === "object" && obj.options !== null && !Array.isArray(obj.options)) {
         entry.options = obj.options;
     }
@@ -579,6 +694,124 @@ function parseStashConfigEntry(value) {
         entry.wikiName = wikiName;
     return entry;
 }
+// ── ConfiguredSource runtime construction ─────────────────────────────────────────
+/**
+ * Synthesize a stable identifier when a {@link SourceConfigEntry} omits its
+ * `name`. Uses a short hash of the discriminating fields so two equivalent
+ * entries collapse to the same generated name.
+ */
+function deriveStashEntryName(entry) {
+    if (entry.name)
+        return entry.name;
+    const seed = JSON.stringify({
+        type: entry.type,
+        path: entry.path ?? null,
+        url: entry.url ?? null,
+    });
+    const hash = createHash("sha256").update(seed).digest("hex").slice(0, 8);
+    return `${entry.type}-${hash}`;
+}
+/**
+ * Convert a persisted {@link SourceConfigEntry} into the runtime
+ * {@link SourceSpec} discriminated union. Returns `undefined` when the
+ * entry is missing the fields its provider type requires (e.g. a
+ * `filesystem` entry with no `path`); callers should drop or warn for those.
+ *
+ * Unknown provider types fall back to `{ type: "filesystem", path: ... }` so
+ * legacy aliases (`"context-hub"`, `"github"` for git) still produce a usable
+ * runtime value when a path/url is supplied.
+ */
+export function parseSourceSpec(entry) {
+    switch (entry.type) {
+        case "filesystem":
+            return entry.path ? { type: "filesystem", path: entry.path } : undefined;
+        case "git":
+        case "context-hub":
+        case "github":
+            // Note: a configured `github` provider entry historically meant "git
+            // repo over the GitHub web URL", not the registry-install `github:` ref.
+            return entry.url ? { type: "git", url: entry.url } : undefined;
+        case "website":
+            return entry.url
+                ? {
+                    type: "website",
+                    url: entry.url,
+                    ...(typeof entry.options?.maxPages === "number" ? { maxPages: entry.options.maxPages } : {}),
+                }
+                : undefined;
+        case "npm":
+            // Persisted `npm` stash entries are unusual but supported for symmetry.
+            return entry.path ? { type: "npm", package: entry.path } : undefined;
+        default:
+            // Unknown provider — best-effort fallback so callers still get something.
+            return entry.path ? { type: "filesystem", path: entry.path } : undefined;
+    }
+}
+/**
+ * Build the full ordered list of runtime {@link ConfiguredSource} values from a
+ * loaded {@link AkmConfig}. Order is the canonical iteration order:
+ *
+ *   1. The entry marked `primary: true` (or, as a backwards-compat shim,
+ *      a synthetic filesystem entry built from the top-level `stashDir`).
+ *   2. Remaining `sources[]` entries in declared order.
+ *   3. Legacy `installed[]` entries, mapped into runtime entries.
+ *
+ * Entries with `enabled: false` are still emitted — callers decide whether
+ * to honour the flag (mirrors how `installed[]` entries have always been
+ * unconditional). Entries that fail {@link parseSourceSpec} are
+ * dropped silently.
+ */
+export function resolveConfiguredSources(config) {
+    const entries = [];
+    // `sources` is the canonical key. `stashes` is the legacy key that the loader
+    // migrates in-memory; only one of the two should be set at runtime.
+    const stashes = config.sources ?? config.stashes ?? [];
+    // (1) Primary entry: explicit `primary: true` wins; fall back to top-level stashDir.
+    let primary = stashes.find((entry) => entry.primary === true);
+    if (!primary && config.stashDir) {
+        primary = { type: "filesystem", path: config.stashDir, primary: true };
+    }
+    if (primary) {
+        const runtime = toConfiguredSource(primary, true);
+        if (runtime)
+            entries.push(runtime);
+    }
+    // (2) Declared stashes (skip the primary entry — already added).
+    for (const entry of stashes) {
+        if (entry === primary)
+            continue;
+        const runtime = toConfiguredSource(entry, false);
+        if (runtime)
+            entries.push(runtime);
+    }
+    // (3) Legacy installed[] entries.
+    for (const installed of config.installed ?? []) {
+        entries.push({
+            name: installed.id,
+            type: "filesystem",
+            source: { type: "filesystem", path: installed.stashRoot },
+            enabled: true,
+            writable: installed.writable,
+            ...(installed.wikiName ? { wikiName: installed.wikiName } : {}),
+        });
+    }
+    return entries;
+}
+function toConfiguredSource(persisted, isPrimary) {
+    const source = parseSourceSpec(persisted);
+    if (!source)
+        return undefined;
+    return {
+        name: deriveStashEntryName(persisted),
+        type: persisted.type,
+        source,
+        ...(persisted.enabled !== undefined ? { enabled: persisted.enabled } : {}),
+        ...(persisted.writable !== undefined ? { writable: persisted.writable } : {}),
+        ...(isPrimary || persisted.primary ? { primary: true } : {}),
+        ...(persisted.options ? { options: persisted.options } : {}),
+        ...(persisted.wikiName ? { wikiName: persisted.wikiName } : {}),
+    };
+}
 function parseRegistryConfigEntry(value) {
     if (typeof value !== "object" || value === null || Array.isArray(value))
         return undefined;
@@ -621,7 +854,8 @@ function mergeInstallAuditConfig(base, override) {
  * Scalar fields follow normal override semantics. Known nested objects are
  * deep-merged so project config files can override individual fields without
  * clobbering sibling settings. `stashes` are additive by default, but a later
- * layer can set `disableGlobalStashes: true` to drop inherited stashes first.
+ * layer can set `stashInheritance: "replace"` (or the legacy
+ * `disableGlobalStashes: true`) to drop inherited stashes first.
  */
 function mergeLoadedConfig(base, override) {
     if (!override)
@@ -642,12 +876,25 @@ function mergeLoadedConfig(base, override) {
     if (base.security && override.security) {
         merged.security = mergeSecurityConfig(base.security, override.security);
     }
-    if (override.disableGlobalStashes) {
-        merged.stashes = [...(override.stashes ?? [])];
-    }
-    else if (override.stashes) {
-        merged.stashes = [...(base.stashes ?? []), ...override.stashes];
-    }
+    // The new `stashInheritance` field wins; fall back to the legacy
+    // `disableGlobalStashes` boolean so old config files behave identically.
+    const replaceStashes = override.stashInheritance === "replace" ||
+        (override.stashInheritance === undefined && override.disableGlobalStashes === true);
+    // Merge `sources` (canonical key). Legacy `stashes` key is handled via the
+    // pickKnownKeys migration which promotes it to `sources` at load time.
+    const overrideSources = override.sources ?? override.stashes ?? [];
+    const baseSources = base.sources ?? base.stashes ?? [];
+    if (replaceStashes) {
+        merged.sources = [...overrideSources];
+    }
+    else if (overrideSources.length > 0) {
+        merged.sources = [...baseSources, ...overrideSources];
+    }
+    else if (baseSources.length > 0) {
+        merged.sources = [...baseSources];
+    }
+    // Clear deprecated stashes field on the merged result — sources is canonical.
+    delete merged.stashes;
     return merged;
 }
 function applyRuntimeEnvApiKeys(config) {
@@ -713,7 +960,19 @@ function isFile(filePath) {
 }
 function getFileSignatureToken(filePath) {
     try {
-        return String(fs.statSync(filePath).mtimeMs);
+        const stat = fs.statSync(filePath);
+        // mtimeMs alone is unreliable on filesystems with low-resolution mtime
+        // (HFS+, some network FS, or very fast back-to-back writes in tests).
+        // Combine mtime + size + content hash so the signature actually changes
+        // when content does.
+        let contentHash = "";
+        try {
+            contentHash = hashString(fs.readFileSync(filePath, "utf8"));
+        }
+        catch {
+            // ignore — fall back to stat-only signature
+        }
+        return `${stat.mtimeMs}:${stat.size}:${contentHash}`;
     }
     catch {
         return "missing";

package/dist/core/errors.js

@@ -0,0 +1,90 @@
+/**
+ * Typed error classes for structured exit code classification.
+ *
+ * - ConfigError  -> exit 78  (configuration / environment problems)
+ * - UsageError   -> exit 2   (bad CLI arguments or invalid input)
+ * - NotFoundError -> exit 1  (requested resource missing)
+ *
+ * Each error carries a machine-readable `code` field. Codes are stable
+ * identifiers safe to consume from scripts and JSON output. Existing throw
+ * sites without an explicit code receive a default code per error class so
+ * older call sites continue to compile and behave unchanged.
+ *
+ * Each error also exposes a `hint()` method returning an actionable hint
+ * string (or `undefined`). Hints can be supplied at construction time or
+ * derived from the error `code` via the per-class default mapping below.
+ * The CLI surfaces this via `error.hint()` rather than message-regex parsing.
+ */
+/**
+ * Default hint for each ConfigError code. Keep these short, actionable, and
+ * imperative. Returning undefined means "no canned hint".
+ */
+const CONFIG_HINTS = {
+    STASH_DIR_NOT_FOUND: "Run `akm init` to create the default stash, or set stashDir in your config.",
+    STASH_DIR_NOT_A_DIRECTORY: "The configured stashDir exists but isn't a directory. Update stashDir to point at a folder.",
+    STASH_DIR_UNREADABLE: "Check the path exists and your user has read permission, or update stashDir.",
+    EMBEDDING_NOT_CONFIGURED: 'Run `akm config set embedding \'{"endpoint":"...","model":"..."}\'` to enable embeddings.',
+    LLM_NOT_CONFIGURED: 'Run `akm config set llm \'{"endpoint":"...","model":"..."}\'` to configure the LLM.',
+};
+/** Default hint for each UsageError code. */
+const USAGE_HINTS = {
+    INVALID_SOURCE_VALUE: "Pick one of: stash, registry, both.",
+    INVALID_FORMAT_VALUE: "Pick one of: json, jsonl, text, yaml.",
+    INVALID_DETAIL_VALUE: "Pick one of: brief, normal, full, summary, agent.",
+    INVALID_JSON_CONFIG_VALUE: 'Quote JSON values in your shell, for example: akm config set embedding \'{"endpoint":"http://localhost:11434/v1/embeddings","model":"nomic-embed-text"}\'.',
+    MISSING_OR_AMBIGUOUS_TARGET: "Use `akm update --all` or pass a target like `akm update npm:@scope/pkg` (not both).",
+    TARGET_NOT_UPDATABLE: "Run `akm list` to view your sources, then retry with one of those values.",
+    MISSING_REQUIRED_ARGUMENT: "Refs use the form type:name, e.g. `akm show skill:deploy` or `akm show knowledge:guide.md`.",
+};
+/** Default hint for each NotFoundError code. */
+const NOT_FOUND_HINTS = {
+    SOURCE_NOT_FOUND: "Run `akm list` to view your sources, then retry with one of those values.",
+};
+/** Raised when configuration or environment is invalid or missing. */
+export class ConfigError extends Error {
+    code;
+    _hint;
+    constructor(msg, code = "INVALID_CONFIG_FILE", hint) {
+        super(msg);
+        this.name = "ConfigError";
+        this.code = code;
+        this._hint = hint;
+        // Fixes `instanceof` checks under ES5 transpilation targets.
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+    hint() {
+        return this._hint ?? CONFIG_HINTS[this.code];
+    }
+}
+/** Raised when the user supplies invalid arguments or input. */
+export class UsageError extends Error {
+    code;
+    _hint;
+    constructor(msg, code = "INVALID_FLAG_VALUE", hint) {
+        super(msg);
+        this.name = "UsageError";
+        this.code = code;
+        this._hint = hint;
+        // Fixes `instanceof` checks under ES5 transpilation targets.
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+    hint() {
+        return this._hint ?? USAGE_HINTS[this.code];
+    }
+}
+/** Raised when a requested resource (asset, entry, file) is not found. */
+export class NotFoundError extends Error {
+    code;
+    _hint;
+    constructor(msg, code = "ASSET_NOT_FOUND", hint) {
+        super(msg);
+        this.name = "NotFoundError";
+        this.code = code;
+        this._hint = hint;
+        // Fixes `instanceof` checks under ES5 transpilation targets.
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+    hint() {
+        return this._hint ?? NOT_FOUND_HINTS[this.code];
+    }
+}

package/dist/{frontmatter.js → core/frontmatter.js}

@@ -11,13 +11,13 @@
  *
  * **Limitations**: This is a hand-rolled YAML-subset parser with intentional
  * constraints for simplicity and safety:
- * - **No list support**: YAML block sequences (`- item`) and flow arrays
- *   (`[a, b, c]`) are silently ignored. List-valued frontmatter keys will
- *   produce an empty string or be skipped. Callers must NOT rely on list-
- *   valued frontmatter.
+ * - **Top-level values**: string, boolean, and number scalars are supported,
+ *   as well as top-level list-valued keys using YAML block sequences
+ *   (`- item`) or flow arrays (`[a, b, c]`).
+ * - **List item types**: list items must be scalar values and may be strings,
+ *   booleans, or numbers.
  * - **No nested objects beyond one level**: Only a single level of indented
  *   key-value pairs is supported.
- * - **Scalar values only**: string, boolean, and number scalars are supported.
  */
 export function parseFrontmatter(raw) {
     const parsedBlock = parseFrontmatterBlock(raw);
@@ -26,28 +26,75 @@ export function parseFrontmatter(raw) {
     }
     const data = {};
     let currentKey = null;
+    /** "scalar" | "list" | "object" | "pending" — "pending" means empty value, mode determined by next line */
+    let mode = "scalar";
     let nested = null;
+    let currentList = null;
+    const flushPending = () => {
+        // Called when we start a new top-level key and the previous key was still "pending".
+        // An empty-value key followed by another top-level key means it was an empty scalar.
+        if (mode === "pending" && currentKey !== null) {
+            data[currentKey] = "";
+        }
+    };
     for (const line of parsedBlock.frontmatter.split(/\r?\n/)) {
+        // Block-sequence item: "- value" or "  - value" (optional 2-space indent)
+        // Only match when the current key is in list or pending mode.
+        const seqItem = line.match(/^(?: {2})?- (.*)$/);
+        if (seqItem && currentKey !== null && (mode === "list" || mode === "pending")) {
+            if (mode === "pending") {
+                // First block-sequence item after an empty-value key — switch to list mode
+                currentList = [];
+                data[currentKey] = currentList;
+                mode = "list";
+            }
+            currentList.push(parseYamlScalar(seqItem[1].trim()));
+            continue;
+        }
+        // Indented nested key-value (object under a key with empty value)
         const indented = line.match(/^ {2}(\w[\w-]*):\s*(.+)$/);
-        if (indented && currentKey && nested) {
+        if (indented && currentKey !== null && (mode === "object" || mode === "pending")) {
+            if (mode === "pending") {
+                // First indented k-v after an empty-value key — switch to object mode
+                nested = {};
+                data[currentKey] = nested;
+                mode = "object";
+            }
             nested[indented[1]] = parseYamlScalar(indented[2].trim());
             continue;
         }
+        // Top-level key (possibly with inline value)
         const top = line.match(/^(\w[\w-]*):\s*(.*)$/);
         if (!top) {
             continue;
         }
+        // Starting a new top-level key — flush any pending empty-value key
+        flushPending();
         currentKey = top[1];
         const value = top[2].trim();
         if (value === "") {
-            nested = {};
-            data[currentKey] = nested;
+            // Defer mode decision until we see the next line
+            mode = "pending";
+            nested = null;
+            currentList = null;
+            // Don't store anything yet — flushPending will set "" if no continuation
+        }
+        else if (value.startsWith("[") && value.endsWith("]")) {
+            // Inline flow array: tags: [ops, networking]
+            mode = "list";
+            nested = null;
+            currentList = parseFlowArray(value);
+            data[currentKey] = currentList;
         }
         else {
+            mode = "scalar";
             nested = null;
+            currentList = null;
             data[currentKey] = parseYamlScalar(value);
         }
     }
+    // Flush the last key if it was still pending (empty value, no continuation)
+    flushPending();
     return {
         data,
         content: parsedBlock.content,
@@ -55,6 +102,15 @@ export function parseFrontmatter(raw) {
         bodyStartLine: parsedBlock.bodyStartLine,
     };
 }
+/**
+ * Parse a YAML flow array string like `[a, b, c]` into an array of scalars.
+ */
+function parseFlowArray(value) {
+    const inner = value.slice(1, -1).trim();
+    if (!inner)
+        return [];
+    return inner.split(",").map((item) => parseYamlScalar(item.trim()));
+}
 export function parseFrontmatterBlock(raw) {
     // Handle both LF and CRLF line endings throughout.
     // The closing --- may be preceded by \r\n; capture and strip trailing \r