@foldrun/core 1.3.0 → 1.4.0

package/dist/src/scan.js

@@ -29,6 +29,7 @@ import crypto from "node:crypto";
 import matter from "gray-matter";
 import { refNames } from "./refs.js";
 import { resolveNetwork } from "./network.js";
+import { frontmatterProblems, schemaKindOf } from "./frontmatter-schema.js";
 export const OWASP_URL = "https://genai.owasp.org/resource/owasp-top-10-for-agentic-applications-for-2026";
 export const SCAN_RULES = [
     {
@@ -120,9 +121,32 @@ export const SCAN_RULES = [
         id: "config/unknown-field",
         category: "config",
         level: "warn",
-        title: "A frontmatter field foldrun does not read — likely a typo",
+        title: "A frontmatter field foldrun does not read here",
         help: "A misspelt field is not an error to YAML, so it is silently ignored: `tolls: [web]` leaves the agent with no tools. " +
-            "Use the field the message suggests.",
+            "A near-miss names the field it meant; a field read in another kind of file says where it belongs (warnings). " +
+            "A field like nothing foldrun reads is a note, since another tool may own it.",
+    },
+    {
+        id: "config/wrong-type",
+        category: "config",
+        level: "warn",
+        title: "A frontmatter field holding the wrong kind of value",
+        help: "A list where one name was meant, a map where a word was meant: the runtime does not read it. The message says what the field takes.",
+    },
+    {
+        id: "config/invalid-value",
+        category: "config",
+        level: "warn",
+        title: "A frontmatter value that does nothing",
+        help: "`effort: extreme`, `size: giant`, `trigger: sometimes`, a cron the scheduler cannot read: each is ignored or falls back, " +
+            "so the agent or flow quietly does something else. The message lists what the field takes.",
+    },
+    {
+        id: "config/missing-field",
+        category: "config",
+        level: "warn",
+        title: "A required frontmatter field is missing",
+        help: "A skill with no description is never loaded: the model chooses skills by their descriptions.",
     },
     {
         id: "check/ignore-needs-reason",
@@ -459,28 +483,6 @@ function unpinned(pkg) {
     return !/[=<>~!]/.test(s) && !/.@./.test(s.replace(/^@/, "x"));
 }
 // ── frontmatter ────────────────────────────────────────────────────────────
-/** What foldrun reads in an agent's frontmatter — the fields documented in
- *  agents.md, the Claude Code subagent fields an import carries, and the
- *  older spellings check already teaches about. Used only to suggest the
- *  field a typo meant: an unknown key that is nothing like any of these is
- *  left alone, since another tool may own it. */
-const AGENT_FIELDS = [
-    "name", "description", "model", "effort", "size", "tools", "disallowedTools", "skills", "hooks", "scripts",
-    "apis", "mcpServers", "agents", "subagents", "secrets", "limits", "network", "provider", "permissionMode",
-    "runtime", "ask", "web", "budget", "timezone", "language", "region", "currency", "units", "schedule", "color",
-    "memory", "foldrun_version", "use", "kind", "type", "notify", "triggers", "inputs", "outputs",
-];
-const FLOW_FIELDS = [
-    "name", "description", "trigger", "schedule", "timezone", "language", "region", "currency", "units", "model",
-    "effort", "overlap", "priority", "throttle", "debounce", "sla", "catchup", "pause_when", "disable_after",
-    "approvers", "approve_within", "notify", "at", "every", "budget", "limits", "size", "hooks", "inputs",
-    "webhook", "signing_secret", "signature", "idempotency", "filter", "after", "tags", "network", "secrets",
-];
-const TOOL_FIELDS = [
-    "name", "description", "transport", "type", "base", "methods", "headers", "query", "auth", "run", "args",
-    "command", "url", "env", "outward", "runtime", "secrets", "network", "timeout", "spec", "operations", "body",
-    "oauth", "limits", "input", "output", "schema", "kind",
-];
 function editDistance(a, b) {
     const d = Array.from({ length: a.length + 1 }, (_, i) => [i, ...Array(b.length).fill(0)]);
     for (let j = 1; j <= b.length; j++)
@@ -658,7 +660,7 @@ export function scanFiles(files, options = {}) {
     const findings = [];
     const seen = new Set();
     const ignoresByFile = new Map();
-    const push = (rule, file, line, text, message) => {
+    const push = (rule, file, line, text, message, level) => {
         if (!enabled(rule))
             return;
         const ig = ignoresByFile.get(file);
@@ -668,7 +670,7 @@ export function scanFiles(files, options = {}) {
         if (seen.has(key))
             return;
         seen.add(key);
-        findings.push({ rule, level: scanRule(rule)?.level ?? "warn", file, ...(line ? { line } : {}), message, fingerprint: findingFingerprint(rule, file, text) });
+        findings.push({ rule, level: level ?? scanRule(rule)?.level ?? "warn", file, ...(line ? { line } : {}), message, fingerprint: findingFingerprint(rule, file, text) });
     };
     const outward = new Set(options.outwardTools ?? []);
     const agents = [];
@@ -679,18 +681,23 @@ export function scanFiles(files, options = {}) {
         scanSecrets(f, lines, push);
         scanContent(f, lines, push);
         scanSupplyChain(f, lines, push);
-        const kind = docKind(f.path);
-        if (!kind)
-            continue;
-        const data = frontOf(f.content);
+        const schema = schemaKindOf(f.path);
+        // A skill with no frontmatter at all is the clearest one that never
+        // loads: read it as empty, so its required fields are reported.
+        const data = schema || docKind(f.path) ? (frontOf(f.content) ?? (schema === "skill" && !/^\uFEFF?---\r?\n/.test(f.content) ? {} : null)) : null;
         if (!data)
             continue;
-        const known = kind === "agent" ? AGENT_FIELDS : kind === "flow" ? FLOW_FIELDS : TOOL_FIELDS;
-        for (const key of Object.keys(data)) {
-            const near = nearestField(key, known);
-            if (near && near !== key)
-                push("config/unknown-field", f.path, keyLine(lines, key), `field ${key}`, `\`${key}:\` is not a field foldrun reads — did you mean \`${near}:\`? As written it is ignored`);
+        if (schema) {
+            for (const p of frontmatterProblems(schema, data, nearestField)) {
+                // Fingerprint the key's own line, not the parsed value: a YAML alias
+                // can make the value circular, and JSON of it would throw.
+                const at = keyLine(lines, p.key);
+                push(p.rule, f.path, at, `${p.rule} ${at ? lines[at - 1] : p.key}`, p.message, p.level);
+            }
         }
+        const kind = docKind(f.path);
+        if (!kind)
+            continue;
         if (kind === "agent") {
             const rel = f.path.replace(/^library\//, "");
             const name = /^agents\/([^/]+)\//.exec(rel)?.[1] ?? rel.replace(/^.*\/|\.md$/g, "");

package/dist/src/store.d.ts

@@ -1,3 +1,4 @@
+import { EFFORT_LEVELS, FLOW_TRIGGERS } from "./frontmatter-fields.ts";
 import type { BrowserPodOutcome } from "./browser-pod.ts";
 import { singleWorkspace } from "./paths.ts";
 import type { TestEffect } from "./test-mode.ts";
@@ -354,7 +355,7 @@ export type Tier = keyof typeof MODEL_TIERS;
  *  `model:` does — one vocabulary, not two. */
 export declare function resolveTier(value: unknown): Tier | null;
 export declare function resolveModel(value: unknown): string;
-export declare const EFFORT_LEVELS: readonly ["low", "medium", "high", "xhigh", "max"];
+export { EFFORT_LEVELS } from "./frontmatter-fields.ts";
 export type Effort = (typeof EFFORT_LEVELS)[number];
 /**
  * `null` for both "not set" and "not a level we know" — unlike a model, the
@@ -607,7 +608,7 @@ export interface FlowInfo {
     frontProblems: string[];
     steps: FlowStep[];
 }
-export declare const FLOW_TRIGGERS: readonly ["manual", "schedule", "webhook", "email", "flow", "once", "watch", "storage"];
+export { FLOW_TRIGGERS } from "./frontmatter-fields.ts";
 export type FlowTrigger = (typeof FLOW_TRIGGERS)[number];
 export interface AgentAssets {
     skills: string[];
@@ -615,6 +616,12 @@ export interface AgentAssets {
 }
 export declare function agentAssets(tenant: string, workspace: string, agent: string): AgentAssets;
 export declare function listAgents(tenant: string, workspace: string): AgentInfo[];
+/** The option keys a step actually has. An indented `word: rest` that is
+ *  NOT one of these is a line of the instruction — "Warning: do not
+ *  publish" is prose that happens to contain a colon, and it used to be
+ *  swallowed as an unknown option, silently, along with any typo of a real
+ *  key. The consistency suite reads this list against the docs. */
+export declare const STEP_OPTION_KEYS: ReadonlySet<string>;
 /** The most fan-out instances `parallel:` may run at once — the fan-out's
  *  own hard cap, since more slots than items is no cap. */
 export declare const PARALLEL_CAP = 20;

package/dist/src/store.js

@@ -20,6 +20,7 @@
 //
 // An account is a named directory (per OKF: tenancy is a hosting concern).
 import { expandPlatformVars } from "./host-env.js";
+import { FLOW_TRIGGERS } from "./frontmatter-fields.js";
 import fs from "node:fs";
 import path from "node:path";
 import { recordRevision, registerTreeReader } from "./history.js";
@@ -899,7 +900,7 @@ export function resolveModel(value) {
 // model is which brain, effort is how long it thinks before answering. The
 // five levels are the SDK's own union — we neither invent our own scale nor
 // narrow theirs, so a level added upstream is one line here.
-export const EFFORT_LEVELS = ["low", "medium", "high", "xhigh", "max"];
+export { EFFORT_LEVELS } from "./frontmatter-fields.js";
 const EFFORT_ALIASES = {
     low: "low",
     min: "low",
@@ -1020,7 +1021,8 @@ export function parseApis(raw) {
     }
     return out;
 }
-export const FLOW_TRIGGERS = ["manual", "schedule", "webhook", "email", "flow", "once", "watch", "storage"];
+// The list lives with every other frontmatter field (frontmatter-fields.ts).
+export { FLOW_TRIGGERS } from "./frontmatter-fields.js";
 export function agentAssets(tenant, workspace, agent) {
     const base = path.join(workspaceDir(tenant, workspace), "agents", agent);
     const nameOf = (file, fallback) => {
@@ -1177,7 +1179,7 @@ const OPTION_RE = /^(\s+)([a-z_-]+):(.*)$/;
  *  publish" is prose that happens to contain a colon, and it used to be
  *  swallowed as an unknown option, silently, along with any typo of a real
  *  key. The consistency suite reads this list against the docs. */
-const STEP_OPTION_KEYS = new Set([
+export const STEP_OPTION_KEYS = new Set([
     "approve", "ask", "case", "delegate", "each", "effort", "else", "limits", "loop", "max", "max_turns", "model",
     "on-fail", "onfail", "output", "parallel", "preview", "retry", "schema", "timeout", "until", "verify", "wait", "when",
 ]);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foldrun/core",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Agents are just folders. The format, the runner, the checks.",
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",

package/src/completions.ts

@@ -10,6 +10,7 @@
 // renders them.
 
 import { PROVIDERS } from "./providers.ts";
+import { FRONTMATTER, type SchemaKind } from "./frontmatter-fields.ts";
 
 export interface Vocabulary {
   agents: string[];
@@ -207,8 +208,6 @@ const FIELDS: Record<string, Completion[]> = {
     { label: "trigger", insert: "trigger: manual" },
     { label: "schedule", insert: "schedule: \"0 6 * * MON\"" },
     { label: "timezone", insert: "timezone: Australia/Sydney" },
-    { label: "language", insert: "language: en-AU" },
-    { label: "region", insert: "region: au", hint: "currency, units, calendar, weekend and text direction follow" },
     { label: "model", insert: "model: fast", hint: "every step, unless the step says" },
     { label: "effort", insert: "effort: high", hint: "every step, unless the step says" },
   ],
@@ -264,6 +263,27 @@ export function fileKind(path: string): FileKind {
   return "note";
 }
 
+/** Which frontmatter schema a completion kind offers. */
+const SCHEMA_OF: Partial<Record<FileKind, SchemaKind>> = { agent: "agent", flow: "flow", tool: "tool", skill: "skill", evalFile: "eval" };
+
+/**
+ * The fields to offer at the start of a frontmatter line: the hand-written
+ * snippets above where a field has one, then every other field the schema
+ * says this kind of file takes — so a field added to frontmatter-fields.ts is
+ * offered here with no second edit, and a snippet for a field the runtime no
+ * longer reads is dropped. AGENTS.md takes its own set, not an agent's.
+ */
+function fieldsFor(path: string, kind: FileKind): Completion[] {
+  const agentsMd = /(^|\/)AGENTS\.md$/.test(path) || path === "project.md";
+  const schema = agentsMd ? FRONTMATTER["agents-md"] : SCHEMA_OF[kind] ? FRONTMATTER[SCHEMA_OF[kind]!] : null;
+  if (!schema) return FIELDS[kind];
+  const offered = schema.filter((f) => !f.legacy);
+  const keys = new Set(offered.map((f) => f.key));
+  const curated = FIELDS[kind].filter((c) => keys.has(c.label.split(".")[0]!));
+  const have = new Set(curated.map((c) => c.label.split(".")[0]));
+  return [...curated, ...offered.filter((f) => !have.has(f.key)).map((f) => ({ label: f.key, insert: `${f.key}: `, hint: f.help }))];
+}
+
 /**
  * Does [[ ]] in this file get expanded into a path, or stay literal?
  *
@@ -654,9 +674,9 @@ export function completionsAt(
   //    this kind of file. This is where you learn the format by writing it.
   const fmEnd = text.indexOf("\n---", text.indexOf("---") + 3);
   const inFrontmatter = text.startsWith("---") && (fmEnd === -1 || cursor <= fmEnd);
-  if (inFrontmatter && /^[a-zA-Z_]*$/.test(line)) {
+  if (inFrontmatter && /^[a-zA-Z_][a-zA-Z_-]*$|^$/.test(line)) {
     const from = cursor - line.length;
-    return { from, query: line, items: filter(FIELDS[kind], line), title: `${kind} fields` };
+    return { from, query: line, items: filter(fieldsFor(path, kind), line), title: `${kind} fields` };
   }
 
   return null;

package/src/cron.ts

@@ -0,0 +1,120 @@
+// Cron: the one reading of a flow's `schedule:`.
+//
+// Moved here from the platform's scheduler so `foldrun check`, the deploy and
+// the scheduler ask the same function whether a schedule is one — a cron the
+// scheduler cannot parse used to be skipped silently, and nothing earlier
+// said so. The scheduler imports this; the expansion is unchanged.
+
+
+export const NAMED: Record<string, string> = {
+  "@hourly": "0 * * * *",
+  "@daily": "0 0 * * *",
+  "@midnight": "0 0 * * *",
+  "@weekly": "0 0 * * 0",
+  "@monthly": "0 0 1 * *",
+};
+
+export const DOW_NAMES = ["sun", "mon", "tue", "wed", "thu", "fri", "sat"];
+const MONTH_NAMES = ["jan", "feb", "mar", "apr", "may", "jun", "jul", "aug", "sep", "oct", "nov", "dec"];
+
+// Expand one cron field ("*", "*/15", "1-5", "mon,fri", "3") to a value set.
+function expandField(field: string, min: number, max: number, names?: string[]): Set<number> | null {
+  const out = new Set<number>();
+  for (const part of field.split(",")) {
+    const [rangePart, stepPart] = part.split("/");
+    const step = stepPart ? Number(stepPart) : 1;
+    if (!Number.isInteger(step) || step < 1) return null;
+
+    let lo = min;
+    let hi = max;
+    if (rangePart !== "*") {
+      const bounds = rangePart.split("-");
+      const parse = (raw: string): number | null => {
+        const token = raw.trim().toLowerCase();
+        if (names) {
+          // A name counts from the field's own minimum: SUN is 0 on the
+          // weekday field, JAN is 1 on the month field. Indexed from zero,
+          // JAN read as 0 (refused — the flow never fired) and FEB…DEC as
+          // the month before.
+          const idx = names.indexOf(token);
+          if (idx !== -1) return min + idx;
+        }
+        const n = Number(token);
+        return Number.isInteger(n) ? n : null;
+      };
+      const a = parse(bounds[0]);
+      if (a === null) return null;
+      lo = a;
+      if (bounds.length > 1) {
+        const b = parse(bounds[1]);
+        if (b === null) return null;
+        hi = b;
+      } else {
+        hi = stepPart ? max : a; // "5" → just 5; "5/10" → 5,15,25...
+      }
+    }
+    if (lo < min || hi > max || lo > hi) return null;
+    for (let v = lo; v <= hi; v += step) out.add(v);
+  }
+  return out;
+}
+
+export interface Cron {
+  minute: Set<number>;
+  hour: Set<number>;
+  dom: Set<number>;
+  month: Set<number>;
+  dow: Set<number>;
+  domRestricted: boolean;
+  dowRestricted: boolean;
+  /** Neither minute nor hour is a wildcard: a job at a time of day, which
+   *  is what the DST rules in cronMatches apply to (as in Vixie cron). */
+  fixedTime: boolean;
+}
+
+/** `@daily` → its five fields; anything else as written. An own-property
+ *  lookup, so `schedule: constructor` is a bad cron, not a crash. */
+function expand(expr: string): string {
+  const key = expr.trim().toLowerCase();
+  return (Object.hasOwn(NAMED, key) ? NAMED[key]! : expr).trim();
+}
+
+export function parseCron(expr: string): Cron | null {
+  if (typeof expr !== "string") return null;
+  const normalized = expand(expr);
+  const fields = normalized.split(/\s+/);
+  if (fields.length !== 5) return null;
+  const [mi, ho, dm, mo, dw] = fields;
+
+  const minute = expandField(mi, 0, 59);
+  const hour = expandField(ho, 0, 23);
+  const dom = expandField(dm, 1, 31);
+  const month = expandField(mo, 1, 12, MONTH_NAMES);
+  const dowRaw = expandField(dw, 0, 7, DOW_NAMES);
+  if (!minute || !hour || !dom || !month || !dowRaw) return null;
+
+  // cron allows both 0 and 7 for Sunday.
+  const dowSet = new Set([...dowRaw].map((d) => (d === 7 ? 0 : d)));
+
+  return {
+    minute,
+    hour,
+    dom,
+    month,
+    dow: dowSet,
+    domRestricted: dm.trim() !== "*",
+    dowRestricted: dw.trim() !== "*",
+    fixedTime: !mi.startsWith("*") && !ho.startsWith("*"),
+  };
+}
+
+
+/** Why `schedule:` is not a cron the scheduler can run, or null when it is. */
+export function cronProblem(expr: unknown): string | null {
+  if (typeof expr !== "string" || !expr.trim()) return "schedule: is a cron expression — five fields, or @hourly, @daily, @weekly, @monthly";
+  if (parseCron(expr)) return null;
+  const fields = expand(expr).split(/\s+/).length;
+  return fields !== 5
+    ? `schedule: "${expr}" has ${fields} field${fields === 1 ? "" : "s"}; cron has five — minute hour day-of-month month day-of-week ("0 9 * * MON"), or @hourly, @daily, @weekly, @monthly. As written the flow never fires`
+    : `schedule: "${expr}" is not a cron the scheduler can read — a field is out of range or not a number (minute 0-59, hour 0-23, day 1-31, month 1-12, weekday 0-7 or sun-sat). As written the flow never fires`;
+}

package/src/frontmatter-fields.ts

@@ -0,0 +1,225 @@
+// Every frontmatter field foldrun reads, per kind of file — as data.
+//
+// The one list. Before it, the fields lived in five places that drifted: the
+// runtime's reads, the dashboard's completions, the scanner's typo lists, the
+// docs, and the assistant's vocabulary — the completions offered `language:`
+// on a flow, which no run reads. Now:
+//
+//   · completions.ts offers exactly these, in the browser (so this file is
+//     pure data: no fs, no store);
+//   · frontmatter-schema.ts checks values against them, for `foldrun check`,
+//     the Checks page, the editor and the deploy's view;
+//   · tests/frontmatter-schema.test.ts fails when the runner, parseFlow or a
+//     tool parser reads a field missing here, or a completion offers one
+//     that is not; foldrun-web's consistency test fails when one here is not
+//     in the docs.
+//
+// A new field is added here first, then read.
+
+export type FieldType = "string" | "number" | "boolean" | "list" | "object";
+
+export interface FieldSpec {
+  key: string;
+  /** What YAML may hand over. "list" is also offered where the runtime
+   *  splits `a, b` on one line, so such fields list "string" too. */
+  type: FieldType | FieldType[];
+  /** The values that do something, when the set is closed and has no
+   *  aliases. Anything else is reported. */
+  values?: readonly string[];
+  /** Another function validates this field in full and is the one place
+   *  that does; the schema only says the field exists. */
+  validated?: boolean;
+  /** An older name still read, or kept so the right message (not
+   *  "unknown") reaches whoever wrote it. Not offered as a completion. */
+  legacy?: boolean;
+  /** One line: what it is. The completion's hint. */
+  help: string;
+}
+
+export type SchemaKind = "agent" | "agents-md" | "flow" | "tool" | "skill" | "eval" | "hook";
+
+/** What can start a flow. store.ts re-exports it; parseFlow and the editor
+ *  read this one. */
+export const FLOW_TRIGGERS = ["manual", "schedule", "webhook", "email", "flow", "once", "watch", "storage"] as const;
+
+/** The effort levels; store.ts re-exports it with the aliases beside. */
+export const EFFORT_LEVELS = ["low", "medium", "high", "xhigh", "max"] as const;
+
+const LOCALE = { validated: true } as const;
+
+const AGENT: FieldSpec[] = [
+  { key: "name", type: "string", help: "kebab-case; the folder is the identity" },
+  { key: "description", type: "string", help: "what it does and when — other agents and people read it" },
+  { key: "model", type: "string", help: "fast | default | max, an alias, or a full model id" },
+  { key: "effort", type: "string", values: EFFORT_LEVELS, help: "how long it thinks" },
+  { key: "size", type: "string", values: ["small", "large", "heavy"], help: "the sandbox it rents; anything else becomes large" },
+  { key: "permissionMode", type: "string", values: ["plan"], help: "plan = read-only; no other mode changes anything here" },
+  { key: "tools", type: ["list", "string"], help: "the one grant list" },
+  { key: "disallowedTools", type: ["list", "string"], help: "subtract from what it would otherwise have" },
+  { key: "skills", type: ["list", "string"], help: "an allowlist; absent inherits every skill" },
+  { key: "hooks", type: ["list", "string", "object"], help: "hook names; a Claude Code hooks: object is read as none" },
+  { key: "scripts", type: "list", help: "programs in scripts/, each a tool" },
+  { key: "apis", type: "list", help: "an HTTP API as a tool" },
+  { key: "mcpServers", type: "object", help: "MCP servers, name → {command | url, args, env, headers}" },
+  { key: "agents", type: ["list", "string"], help: "colleagues it may consult" },
+  { key: "subagents", type: ["list", "string"], help: "colleagues it may delegate to" },
+  { key: "secrets", type: ["list", "string"], help: "keys it spends itself" },
+  { key: "budget", type: ["number", "string"], help: "USD per run" },
+  { key: "limits", type: "object", validated: true, help: "per-step call limits" },
+  { key: "network", type: ["string", "list", "object"], validated: true, help: "open | trusted | none, sites, or {level, allow, defaults}" },
+  { key: "web", type: "object", validated: true, help: "providers for the web tool's actions" },
+  { key: "provider", type: "object", help: "an Anthropic- or OpenAI-format endpoint for this agent" },
+  { key: "runtime", type: "object", help: "packages and system packages for its sandbox" },
+  { key: "ask", type: "object", help: "{timeout} for tools: [ask]" },
+  { key: "timezone", type: "string", ...LOCALE, help: "IANA name or offset" },
+  { key: "language", type: "string", ...LOCALE, help: "BCP-47 tag" },
+  { key: "region", type: "string", ...LOCALE, help: "two-letter country" },
+  { key: "currency", type: "string", ...LOCALE, help: "three letters" },
+  { key: "units", type: "string", ...LOCALE, help: "metric | imperial" },
+  { key: "calendar", type: "string", ...LOCALE, help: "an Intl calendar" },
+  { key: "schedule", type: ["string", "object"], validated: true, legacy: true, help: "refused: only a flow has a clock" },
+  { key: "use", type: ["list", "string"], validated: true, legacy: true, help: "retired: write tools:" },
+];
+
+const AGENTS_MD: FieldSpec[] = [
+  { key: "foldrun_version", type: ["string", "number"], help: "the format version this account targets" },
+  { key: "mdagent_version", type: ["string", "number"], legacy: true, help: "older spelling of foldrun_version" },
+  { key: "name", type: "string", help: "the workspace's name" },
+  { key: "description", type: "string", help: "shown in the workspace list" },
+  { key: "provider", type: "object", help: "the model endpoint every agent here uses unless it names its own" },
+  { key: "runtime", type: "object", help: "packages for agents that declare none" },
+  { key: "web", type: "object", validated: true, help: "web.browse defaults" },
+  { key: "network", type: ["string", "list", "object"], validated: true, help: "every agent's default network" },
+  { key: "limits", type: "object", validated: true, help: "default call limits" },
+  { key: "hooks", type: ["list", "string"], help: "hooks every agent here runs" },
+  { key: "timezone", type: "string", ...LOCALE, help: "default timezone" },
+  { key: "language", type: "string", ...LOCALE, help: "default language" },
+  { key: "region", type: "string", ...LOCALE, help: "default region" },
+  { key: "currency", type: "string", ...LOCALE, help: "default currency" },
+  { key: "units", type: "string", ...LOCALE, help: "default units" },
+  { key: "calendar", type: "string", ...LOCALE, help: "default calendar" },
+  { key: "notify", type: ["string", "object"], help: "an email or URL told about failed runs and waiting approvals" },
+  { key: "budget", type: ["number", "string"], help: "USD per month, or N/day | N/week | N/month" },
+  { key: "priority", type: "string", values: ["high", "normal", "low"], help: "account: where its runs stand in the queue" },
+  { key: "concurrency", type: ["number", "string"], help: "account: runs at once" },
+  { key: "schedule", type: ["string", "object"], validated: true, legacy: true, help: "refused: only a flow has a clock" },
+];
+
+const FLOW: FieldSpec[] = [
+  { key: "name", type: "string", help: "the flow's name" },
+  { key: "description", type: "string", help: "what it is for" },
+  { key: "trigger", type: "string", values: FLOW_TRIGGERS, help: "what starts it; any other value never fires" },
+  { key: "schedule", type: "string", help: "cron, when trigger: schedule" },
+  { key: "timezone", type: "string", validated: true, help: "the zone its schedule reads in" },
+  { key: "model", type: "string", help: "every step's model unless the step says" },
+  { key: "effort", type: "string", values: EFFORT_LEVELS, help: "every step's effort unless the step says" },
+  { key: "overlap", type: "string", validated: true, help: "skip | queue" },
+  { key: "priority", type: "string", validated: true, help: "high | normal | low" },
+  { key: "catchup", type: "string", validated: true, help: "last | none" },
+  { key: "on", type: "string", validated: true, help: "trigger: flow — completed | failed | blocked | any" },
+  { key: "signature", type: "string", validated: true, help: "github | stripe | slack | hmac" },
+  { key: "signing_secret", type: "string", help: "the secret a webhook's signature is checked with" },
+  { key: "after", type: ["string", "list"], help: "trigger: flow — the flow this one follows" },
+  { key: "at", type: "string", help: "trigger: once — when" },
+  { key: "url", type: "string", help: "trigger: watch — the page watched" },
+  { key: "every", type: ["string", "number"], help: "trigger: watch — how often" },
+  { key: "path", type: "string", help: "trigger: storage — the prefix under storage/" },
+  { key: "idempotency", type: "string", help: "a header name, or body:<field>, that marks a repeat delivery" },
+  { key: "debounce", type: ["string", "number"], help: "wait for a burst to end" },
+  { key: "throttle", type: ["string", "number"], help: "at most one run per window" },
+  { key: "sla", type: ["string", "number"], help: "tell someone when a run outlives it" },
+  { key: "approve_within", type: ["string", "number"], help: "how long an approval may wait" },
+  { key: "disable_after", type: ["number", "string"], help: "switch the flow off after this many failures in a row" },
+  { key: "pause_when", type: "string", help: "a marker that pauses the flow when a run's result says it" },
+  { key: "approvers", type: ["list", "string"], help: "who may approve its gates" },
+  { key: "budget", type: ["number", "string"], help: "USD per run" },
+  { key: "live", type: "boolean", help: "true: steps may act for real in a test run" },
+];
+
+const TOOL: FieldSpec[] = [
+  { key: "name", type: "string", help: "defaults to the file or folder name" },
+  { key: "description", type: "string", help: "what it does — the model chooses by it" },
+  { key: "transport", type: "string", values: ["http", "script", "mcp"], help: "http | script | mcp" },
+  { key: "type", type: "string", legacy: true, help: "older spelling of transport" },
+  { key: "outward", type: "boolean", help: "true: it changes something outside the workspace" },
+  { key: "base", type: "string", help: "http: the API's base URL" },
+  { key: "headers", type: "object", help: "http or mcp: request headers; ${SECRET} is filled server-side" },
+  { key: "query", type: "object", help: "http: query parameters on every call" },
+  { key: "methods", type: ["list", "string"], help: "http: GET, POST, PUT, PATCH, DELETE" },
+  { key: "openapi", type: "string", help: "http: an OpenAPI document for the operations" },
+  { key: "operations", type: ["list", "object"], help: "http: which operations to offer" },
+  { key: "rate", type: ["string", "number"], help: "http: N/s, N/minute, N/hour, or a number per second" },
+  { key: "timeout", type: ["number", "string"], help: "seconds one call may take" },
+  { key: "run", type: "string", help: "script: the program, relative to the tool" },
+  { key: "args", type: ["object", "list"], help: "script: its arguments, name → what it is; mcp: the command's arguments" },
+  { key: "interpreter", type: "string", help: "script: what runs it" },
+  { key: "test_mode", type: "string", values: ["allow"], help: "script: allow — it may run in a test run" },
+  { key: "secrets", type: ["list", "string"], help: "script: secret names, or proxied | materialised" },
+  { key: "runtime", type: "object", help: "script: packages it needs" },
+  { key: "code", type: "string", help: "script: the program inline" },
+  { key: "command", type: "string", help: "mcp: the server's command" },
+  { key: "env", type: "object", help: "mcp: its environment" },
+  { key: "url", type: "string", help: "mcp: a server over http" },
+  { key: "guide", type: "string", legacy: true, help: "ignored — the guide is the body" },
+];
+
+const SKILL: FieldSpec[] = [
+  { key: "name", type: "string", help: "defaults to the folder" },
+  { key: "description", type: "string", help: "required — the model chooses a skill by it" },
+  { key: "when", type: ["list", "string"], help: "run tags it loads on" },
+  // The Agent Skills format's own optional fields: not read, not wrong.
+  { key: "license", type: "string", help: "Agent Skills format" },
+  { key: "compatibility", type: "string", help: "Agent Skills format" },
+  { key: "metadata", type: "object", help: "Agent Skills format" },
+  { key: "allowed-tools", type: ["string", "list"], help: "Agent Skills format: space-separated pre-approved tools (experimental)" },
+];
+
+const EVAL: FieldSpec[] = [
+  { key: "name", type: "string", help: "the eval's name" },
+  { key: "agent", type: "string", help: "the agent it tests" },
+  { key: "flow", type: "string", help: "or the flow" },
+  { key: "model", type: "string", help: "the judge's model" },
+  { key: "effort", type: "string", values: EFFORT_LEVELS, help: "the judge's effort" },
+  { key: "trigger", type: "string", values: ["deploy", "manual"], help: "deploy (default) | manual; anything else is deploy" },
+  { key: "live", type: "boolean", help: "true: real calls" },
+  { key: "inputs", type: "boolean", help: "true: cases carry inputs" },
+];
+
+const HOOK: FieldSpec[] = [
+  { key: "on", type: "string", validated: true, help: "tool.call | tool.result | step.start | step.end" },
+  { key: "tool", type: "string", validated: true, help: "only on tool events" },
+  { key: "timeout", type: "number", validated: true, help: "seconds, 1 to 120" },
+  { key: "description", type: "string", help: "what it guards" },
+  { key: "name", type: "string", help: "the folder is the name" },
+];
+
+/** `kind:` and `type:` were how a document once said what it was; the path
+ *  says it now, and `foldrun check` has its own message for them. */
+const SAID_WHAT_IT_IS: FieldSpec[] = [
+  { key: "kind", type: "string", validated: true, legacy: true, help: "no longer read — the path says what this is" },
+  { key: "type", type: "string", validated: true, legacy: true, help: "no longer read — the path says what this is" },
+];
+
+export const FRONTMATTER: Readonly<Record<SchemaKind, readonly FieldSpec[]>> = {
+  agent: [...AGENT, ...SAID_WHAT_IT_IS],
+  "agents-md": AGENTS_MD,
+  flow: [...FLOW, ...SAID_WHAT_IT_IS],
+  tool: [...TOOL, ...SAID_WHAT_IT_IS.filter((f) => f.key !== "type")],
+  skill: [...SKILL, ...SAID_WHAT_IT_IS],
+  eval: [...EVAL, ...SAID_WHAT_IT_IS],
+  hook: HOOK,
+};
+
+/** Which schema a workspace-relative path is read with, or null. */
+export function schemaKindOf(p: string): SchemaKind | null {
+  // A library entry is `library/<kind>/<path>`; read it as `<kind>/<path>`.
+  const rel = p.replace(/^library\/(?=[a-z]+\/)/, "");
+  if (/^agents\/[^/]+\/agent\.md$/.test(rel) || /^\.(?:claude|agents)\/agents\/[^/]+\.md$/.test(rel)) return "agent";
+  if (rel === "AGENTS.md" || rel === "project.md") return "agents-md";
+  if (/^flows\/[^/]+\.md$/.test(rel)) return "flow";
+  if (/^tools\/[^/]+\/tool\.md$/.test(rel) || /^tools\/[^/]+\.md$/.test(rel)) return "tool";
+  if (/(?:^|\/)skills\/[^/]+\/SKILL\.md$/.test(rel)) return "skill";
+  if (/^evals\/[^/]+\.md$/.test(rel)) return "eval";
+  if (/^hooks\/[^/]+\/hook\.md$/.test(rel)) return "hook";
+  return null;
+}