@bendyline/gezel 0.1.0

package/dist/markdown/index.js

@@ -0,0 +1,4022 @@
+// src/schemas/craftbook.ts
+import { z as z5 } from "zod";
+
+// src/roles/tier.ts
+var MODEL_TIER_ORDER = [
+  "tiny",
+  "small",
+  "medium",
+  "large",
+  "cloud"
+];
+
+// src/schemas/assignee.ts
+import { z } from "zod";
+var TaskAssigneeSchema = z.discriminatedUnion("kind", [
+  z.object({ kind: z.literal("gezel"), gezelId: z.string() }),
+  z.object({ kind: z.literal("user") })
+]);
+
+// src/schemas/gate.ts
+import { z as z3 } from "zod";
+
+// src/schemas/script.ts
+import { z as z2 } from "zod";
+var NamedScriptCapabilitySchema = z2.enum([
+  "llm",
+  "network",
+  "workspace.read",
+  "workspace.write",
+  "artifacts.read",
+  "artifacts.write",
+  "documents.read",
+  "documents.write",
+  "tasks.read",
+  "tasks.write",
+  "memory.read",
+  "memory.write"
+]);
+var CredentialCapabilitySchema = z2.string().regex(
+  /^credential:[a-zA-Z][\w.:-]*$/,
+  'credential capability must be of the form "credential:<name>" where <name> starts with a letter and contains letters, digits, underscore, hyphen, dot, or colon'
+);
+var ScriptCapabilitySchema = z2.union([
+  NamedScriptCapabilitySchema,
+  CredentialCapabilitySchema
+]);
+var ScriptStringInputSchema = z2.object({
+  type: z2.literal("string"),
+  description: z2.string(),
+  required: z2.boolean().optional(),
+  default: z2.string().optional(),
+  pattern: z2.string().optional(),
+  multiline: z2.boolean().optional()
+});
+var ScriptNumberInputSchema = z2.object({
+  type: z2.literal("number"),
+  description: z2.string(),
+  required: z2.boolean().optional(),
+  default: z2.number().optional(),
+  min: z2.number().optional(),
+  max: z2.number().optional(),
+  integer: z2.boolean().optional()
+});
+var ScriptBooleanInputSchema = z2.object({
+  type: z2.literal("boolean"),
+  description: z2.string(),
+  required: z2.boolean().optional(),
+  default: z2.boolean().optional()
+});
+var ScriptChoiceInputSchema = z2.object({
+  type: z2.literal("choice"),
+  description: z2.string(),
+  required: z2.boolean().optional(),
+  default: z2.string().optional(),
+  options: z2.array(
+    z2.object({
+      value: z2.string(),
+      label: z2.string().optional()
+    })
+  ).min(1)
+});
+var ScriptRefInputSchema = z2.object({
+  type: z2.literal("ref"),
+  description: z2.string(),
+  required: z2.boolean().optional(),
+  kind: z2.enum(["gezel", "task", "artifact", "document"])
+});
+var ScriptJsonInputSchema = z2.object({
+  type: z2.literal("json"),
+  description: z2.string(),
+  required: z2.boolean().optional(),
+  default: z2.unknown().optional(),
+  schema: z2.unknown().optional()
+});
+var ScriptInputFieldSchema = z2.discriminatedUnion("type", [
+  ScriptStringInputSchema,
+  ScriptNumberInputSchema,
+  ScriptBooleanInputSchema,
+  ScriptChoiceInputSchema,
+  ScriptRefInputSchema,
+  ScriptJsonInputSchema
+]);
+var ScriptInputsSchema = z2.record(z2.string(), ScriptInputFieldSchema);
+var ScriptStringOutputSchema = z2.object({
+  type: z2.literal("string"),
+  description: z2.string(),
+  nullable: z2.boolean().optional()
+});
+var ScriptNumberOutputSchema = z2.object({
+  type: z2.literal("number"),
+  description: z2.string(),
+  nullable: z2.boolean().optional()
+});
+var ScriptBooleanOutputSchema = z2.object({
+  type: z2.literal("boolean"),
+  description: z2.string(),
+  nullable: z2.boolean().optional()
+});
+var ScriptArrayOutputSchema = z2.object({
+  type: z2.literal("array"),
+  description: z2.string(),
+  itemType: z2.enum(["string", "number", "boolean", "object"])
+});
+var ScriptObjectOutputSchema = z2.object({
+  type: z2.literal("object"),
+  description: z2.string(),
+  schema: z2.unknown().optional()
+});
+var ScriptJsonOutputSchema = z2.object({
+  type: z2.literal("json"),
+  description: z2.string(),
+  schema: z2.unknown().optional()
+});
+var ScriptOutputFieldSchema = z2.discriminatedUnion("type", [
+  ScriptStringOutputSchema,
+  ScriptNumberOutputSchema,
+  ScriptBooleanOutputSchema,
+  ScriptArrayOutputSchema,
+  ScriptObjectOutputSchema,
+  ScriptJsonOutputSchema
+]);
+var ScriptOutputsSchema = z2.record(z2.string(), ScriptOutputFieldSchema);
+var ScriptMetaSchema = z2.object({
+  name: z2.string().regex(
+    /^[a-zA-Z][\w-]*$/,
+    "name must start with a letter and contain only letters, digits, underscore, or hyphen"
+  ),
+  description: z2.string().min(10),
+  /**
+   * What the script is for. `gate` = returns a structured GateResult
+   * (`{ decision, message, ... }`) and is meant to be attached to a
+   * step's gate. Advisory — pickers filter on it; the runtime validates
+   * gate outputs against the result schema regardless. Absent = 'action'.
+   */
+  kind: z2.enum(["action", "gate"]).optional(),
+  inputs: ScriptInputsSchema.optional(),
+  outputs: ScriptOutputsSchema.optional(),
+  requires: z2.array(ScriptCapabilitySchema).optional()
+});
+var ScriptScopeSchema = z2.enum(["project", "craftbook", "user", "standard"]);
+var ScriptOutputPredicateSchema = z2.discriminatedUnion("op", [
+  z2.object({ op: z2.literal("always") }),
+  z2.object({ op: z2.literal("never") }),
+  z2.object({ op: z2.literal("ok") }),
+  z2.object({
+    op: z2.literal("equals"),
+    field: z2.string().min(1),
+    value: z2.union([z2.string(), z2.number(), z2.boolean(), z2.null()])
+  }),
+  z2.object({
+    op: z2.literal("exists"),
+    field: z2.string().min(1),
+    negate: z2.boolean().optional()
+  }),
+  z2.object({
+    op: z2.literal("gt"),
+    field: z2.string().min(1),
+    value: z2.number()
+  })
+]);
+var ScriptRefSchema = z2.object({
+  name: z2.string().min(1),
+  /** Resolution scope; absent = 'project'. See {@link ScriptScopeSchema}. */
+  scope: ScriptScopeSchema.optional(),
+  inputs: z2.record(z2.string(), z2.unknown()).optional(),
+  autoAdvanceOnSuccess: z2.boolean().optional(),
+  autoAdvanceWhen: ScriptOutputPredicateSchema.optional()
+});
+var ScriptRefListSchema = z2.union([ScriptRefSchema, z2.array(ScriptRefSchema)]);
+function normalizeScriptRefs(value) {
+  if (value === void 0) return [];
+  return Array.isArray(value) ? value : [value];
+}
+var ScriptRunStatusSchema = z2.enum(["running", "ok", "error"]);
+var ScriptRunCallSchema = z2.object({
+  at: z2.string(),
+  kind: z2.string(),
+  argsSummary: z2.string(),
+  outputSummary: z2.string().optional(),
+  durationMs: z2.number().nonnegative(),
+  error: z2.string().optional()
+});
+var ScriptRunTriggerSchema = z2.discriminatedUnion("kind", [
+  z2.object({
+    kind: z2.literal("step"),
+    taskRef: z2.string(),
+    stepId: z2.string(),
+    moment: z2.enum(["enter", "exit", "gate"])
+  }),
+  z2.object({
+    kind: z2.literal("chat"),
+    sessionId: z2.string(),
+    gezelId: z2.string()
+  }),
+  z2.object({
+    kind: z2.literal("manual"),
+    userInitiated: z2.literal(true)
+  }),
+  z2.object({
+    kind: z2.literal("nested"),
+    parentRunId: z2.string()
+  }),
+  z2.object({
+    kind: z2.literal("connector"),
+    typeId: z2.string(),
+    bindingId: z2.string()
+  }),
+  /**
+   * A project-type page invoked one of its declared `pages.tools` through
+   * the first-party page-invoke route. User-click-shaped (like `manual`)
+   * and therefore ungated by `allowScriptExecution`; the distinct kind
+   * exists for auditability and future policy.
+   */
+  z2.object({
+    kind: z2.literal("page"),
+    /** The declared tool name the page invoked (not the script name). */
+    tool: z2.string()
+  })
+]);
+var ScriptRunSchema = z2.object({
+  id: z2.string(),
+  projectId: z2.string(),
+  scriptName: z2.string(),
+  startedAt: z2.string(),
+  finishedAt: z2.string().optional(),
+  status: ScriptRunStatusSchema,
+  trigger: ScriptRunTriggerSchema,
+  inputs: z2.record(z2.string(), z2.unknown()),
+  output: z2.unknown().optional(),
+  calls: z2.array(ScriptRunCallSchema),
+  logs: z2.string(),
+  error: z2.string().optional()
+});
+var RunScriptRequestSchema = z2.object({
+  name: z2.string().min(1),
+  /** Resolution scope (default 'project') — lets the editor test-run standard/user scripts. */
+  scope: ScriptScopeSchema.optional(),
+  input: z2.record(z2.string(), z2.unknown()).optional()
+});
+var RunScriptResponseSchema = z2.object({
+  runId: z2.string(),
+  status: ScriptRunStatusSchema,
+  output: z2.unknown().optional(),
+  callsSummary: z2.array(
+    z2.object({
+      kind: z2.string(),
+      durationMs: z2.number().nonnegative(),
+      error: z2.string().optional()
+    })
+  ),
+  error: z2.string().optional()
+});
+var InvokePageToolRequestSchema = z2.object({
+  tool: z2.string().regex(/^[a-z][a-z0-9_]*$/),
+  input: z2.record(z2.string(), z2.unknown()).optional()
+});
+var InvokePageToolResponseSchema = RunScriptResponseSchema.extend({
+  /** Present when the invoked tool declares a reaction. */
+  reaction: z2.object({
+    delivered: z2.boolean(),
+    gezelId: z2.string().optional(),
+    /** 'engagement-off' | 'project-inactive' | 'no-target' | 'send-failed' */
+    reason: z2.string().optional()
+  }).optional()
+});
+var ListScriptsResponseSchema = z2.object({
+  scripts: z2.array(
+    z2.object({
+      name: z2.string(),
+      meta: ScriptMetaSchema,
+      path: z2.string()
+    })
+  )
+});
+var ScriptNameSchema = z2.string().regex(
+  /^[a-zA-Z][\w-]*$/,
+  "script name must start with a letter and contain only letters, digits, underscore, or hyphen"
+);
+var ScriptDiagnosticSchema = z2.object({
+  severity: z2.enum(["error", "warning", "info"]),
+  source: z2.enum(["meta", "typescript", "runtime-compat"]),
+  message: z2.string(),
+  /** 1-based, when the diagnostic is anchored to a location. */
+  line: z2.number().optional(),
+  column: z2.number().optional()
+});
+var ScriptProvenanceSchema = z2.object({
+  kind: z2.enum(["craftbook", "import", "user", "standard"]),
+  /** e.g. "pu/pull-request-review@1.0.0", "skill-x#abc123", "stdlib@1.2.0". */
+  ref: z2.string()
+});
+var GetScriptSourceResponseSchema = z2.object({
+  name: ScriptNameSchema,
+  source: z2.string(),
+  /** sha256 hex of the file bytes; opaque token for conflict detection. */
+  hash: z2.string(),
+  mtimeMs: z2.number(),
+  meta: ScriptMetaSchema.optional(),
+  metaError: z2.string().optional(),
+  provenance: ScriptProvenanceSchema.optional()
+});
+var SaveScriptSourceRequestSchema = z2.object({
+  name: ScriptNameSchema,
+  source: z2.string(),
+  /**
+   * Hash the editor loaded/saved last. When set and it no longer matches
+   * the on-disk file, the save is rejected with `status: 'conflict'`
+   * (someone or something else wrote the file). Omit to overwrite
+   * unconditionally.
+   */
+  baseHash: z2.string().optional()
+});
+var SaveScriptSourceResponseSchema = z2.discriminatedUnion("status", [
+  z2.object({
+    status: z2.literal("saved"),
+    hash: z2.string(),
+    metaOk: z2.boolean(),
+    meta: ScriptMetaSchema.optional(),
+    diagnostics: z2.array(ScriptDiagnosticSchema)
+  }),
+  z2.object({
+    status: z2.literal("conflict"),
+    currentHash: z2.string(),
+    currentSource: z2.string()
+  })
+]);
+var ScriptTemplateIdSchema = z2.enum([
+  "blank",
+  "post-message",
+  "fetch-and-summarize",
+  "check-files",
+  "call-tool",
+  "ask-ai"
+]);
+var CreateScriptRequestSchema = z2.object({
+  name: ScriptNameSchema,
+  description: z2.string().optional(),
+  template: ScriptTemplateIdSchema.optional(),
+  /**
+   * Full source to write instead of a template scaffold. Used by the
+   * copy-on-write flow (duplicate a craftbook script minus its
+   * provenance marker) and by AI drafting.
+   */
+  source: z2.string().optional()
+});
+var CreateScriptResponseSchema = z2.object({
+  name: ScriptNameSchema,
+  source: z2.string(),
+  hash: z2.string()
+});
+var SdkTypesResponseSchema = z2.object({
+  version: z2.string(),
+  files: z2.array(z2.object({ name: z2.string(), content: z2.string() }))
+});
+var DraftScriptRequestSchema = z2.object({
+  name: ScriptNameSchema,
+  description: z2.string().min(1)
+});
+var DraftScriptResponseSchema = z2.object({
+  source: z2.string()
+});
+
+// src/schemas/gate.ts
+var StepSniffSchema = z3.enum([
+  "html-complete",
+  "html-game",
+  "nonempty",
+  "json-valid",
+  "data-table"
+]);
+var GateJsonScalarSchema = z3.union([z3.string(), z3.number(), z3.boolean(), z3.null()]);
+var GateCheckSchema = z3.discriminatedUnion("kind", [
+  /** A single file is at least `bytes` long (workspace, or the artifacts drawer when `artifact`). */
+  z3.object({
+    kind: z3.literal("minBytes"),
+    file: z3.string().min(1),
+    bytes: z3.number().int().positive(),
+    artifact: z3.boolean().optional()
+  }),
+  /** The summed size of several files clears `bytes` (e.g. index.html + game.js ≥ 5 KB). */
+  z3.object({
+    kind: z3.literal("totalMinBytes"),
+    files: z3.array(z3.string().min(1)).min(1),
+    bytes: z3.number().int().positive()
+  }),
+  /**
+   * At least `min` workspace files with one of `ext` exist (e.g. ≥3 images).
+   * `verifyImageBytes` additionally requires each raster candidate
+   * (png/jpg/jpeg/gif/webp) to carry real image bytes — magic signature
+   * plus a 1 KiB floor — so a text placeholder named `panel-1.png` stops
+   * counting. Set it on any gate whose deliverable is an actual rendered
+   * image; leave it off for listings that legitimately include vector or
+   * stub assets. The check fails loudly rather than degrading when the
+   * evaluating surface cannot read bytes.
+   */
+  z3.object({
+    kind: z3.literal("fileCount"),
+    ext: z3.array(z3.string().min(1)).min(1),
+    min: z3.number().int().positive(),
+    dir: z3.string().optional(),
+    verifyImageBytes: z3.boolean().optional()
+  }),
+  /** Inline `<style>` + linked `.css` in `file` (default index.html) clears `bytes`. */
+  z3.object({
+    kind: z3.literal("cssMinBytes"),
+    bytes: z3.number().int().positive(),
+    file: z3.string().optional()
+  }),
+  /** A named content sniff passes on `file` (workspace, or the artifacts drawer when `artifact`). */
+  z3.object({
+    kind: z3.literal("sniff"),
+    file: z3.string().min(1),
+    sniff: StepSniffSchema,
+    artifact: z3.boolean().optional()
+  }),
+  /** A JSON scalar at `path` equals the expected value. Path supports dot keys and numeric array indexes. */
+  z3.object({
+    kind: z3.literal("jsonPathEquals"),
+    file: z3.string().min(1),
+    path: z3.string().min(1),
+    value: GateJsonScalarSchema,
+    label: z3.string().min(1).optional()
+  }),
+  /** A CSV file has the expected header/row shape and optional picklist values. */
+  z3.object({
+    kind: z3.literal("csvShape"),
+    file: z3.string().min(1),
+    requiredColumns: z3.array(z3.string().min(1)).min(1).optional(),
+    exactColumns: z3.array(z3.string().min(1)).min(1).optional(),
+    minRows: z3.number().int().nonnegative().optional(),
+    consistentColumns: z3.boolean().optional(),
+    allowedValues: z3.record(z3.string(), z3.array(z3.string().min(1)).min(1)).optional()
+  }),
+  /** `file` matches `pattern` (regex), in the workspace or the artifacts drawer when `artifact`. */
+  z3.object({
+    kind: z3.literal("contains"),
+    file: z3.string().min(1),
+    pattern: z3.string().min(1),
+    flags: z3.string().optional(),
+    label: z3.string().min(1).optional(),
+    artifact: z3.boolean().optional()
+  }),
+  /** `file` must NOT match `pattern` (regex). E.g. exclude internal-only release noise. */
+  z3.object({
+    kind: z3.literal("notContains"),
+    file: z3.string().min(1),
+    pattern: z3.string().min(1),
+    flags: z3.string().optional(),
+    label: z3.string().min(1).optional()
+  }),
+  /**
+   * `file` may use high-risk claim wording only when the exact matched
+   * phrase appears in `sourceFiles`. This catches overclaim/tone drift in
+   * factual prose without requiring an LLM judge.
+   */
+  z3.object({
+    kind: z3.literal("unsupportedClaims"),
+    file: z3.string().min(1),
+    sourceFiles: z3.array(z3.string().min(1)).min(1),
+    patterns: z3.array(
+      z3.object({
+        pattern: z3.string().min(1),
+        label: z3.string().min(1).optional()
+      })
+    ).min(1),
+    flags: z3.string().optional()
+  }),
+  /**
+   * Every inline `<script>` body in `file` (default index.html) parses as
+   * JavaScript. The "ships broken JS" floor for the single-file-web class:
+   * a page whose inline script has a syntax error never runs in a browser,
+   * so the gate loops the builder back with the parse error. Files with no
+   * inline JS pass (nothing to judge); `type="module"` scripts are size-only
+   * (top-level import can't be function-parsed) and pass here.
+   */
+  z3.object({
+    kind: z3.literal("jsParses"),
+    file: z3.string().optional()
+  }),
+  /**
+   * An in-process, zero-spawn static gate for an HTML deliverable: the document
+   * shell closes, static DOM ids are unique, every inline classic/module
+   * script parses, and top-level function declarations do not silently
+   * replace one another. Unlike a live browser check, this runs in-process
+   * in locked-down modes and is safe to attach to every HTML deliverable.
+   */
+  z3.object({
+    kind: z3.literal("htmlLint"),
+    file: z3.string().min(1)
+  }),
+  /**
+   * Named `node:` imports in `file` resolve to real builtin exports, and a
+   * `.mjs` file doesn't call `require()`. The "ships broken module imports"
+   * floor for the code class: a name imported from the wrong builtin (e.g.
+   * `dirname` from `node:url`) or a `require()` in ESM throws at LOAD and
+   * nothing runs — and `jsParses` can't catch it (it skips `type="module"`
+   * and never sees a standalone `.mjs`/`.ts`). Files with no `node:` named
+   * imports pass.
+   */
+  z3.object({
+    kind: z3.literal("esmImports"),
+    file: z3.string().min(1)
+  }),
+  /**
+   * `file` parses as source code. For `.ts/.tsx/.js/.mjs/.cjs/.jsx` the
+   * service runs a syntax-only TypeScript transpile (milliseconds, zero
+   * spawns) and the failure message carries the first diagnostic with
+   * line:column; `.html` delegates to the inline-`jsParses` path. The
+   * code-class floor that catches truncated/unbalanced files a
+   * `minBytes`-only gate happily waves through.
+   */
+  z3.object({
+    kind: z3.literal("sourceParses"),
+    file: z3.string().min(1)
+  }),
+  /**
+   * The first Markdown table in `file` has the required header set and
+   * row floor. (CSV/JSON record data uses `csvShape`/`recordSchema`.)
+   */
+  z3.object({
+    kind: z3.literal("tableShape"),
+    file: z3.string().min(1),
+    requiredColumns: z3.array(z3.string().min(1)).min(1).optional(),
+    minRows: z3.number().int().nonnegative().optional(),
+    artifact: z3.boolean().optional()
+  }),
+  /**
+   * A JSON array (or CSV) of records in `file` conforms to a declared
+   * field schema — the ETL schema-conformance floor. Field `type` is a
+   * built-in cell type (`string`/`nonempty`/`number`/`integer`/`boolean`/
+   * `date`/`iso-date`/`email`) or a regex source.
+   */
+  z3.object({
+    kind: z3.literal("recordSchema"),
+    file: z3.string().min(1),
+    fields: z3.array(
+      z3.object({
+        name: z3.string().min(1),
+        type: z3.string().optional(),
+        required: z3.boolean().optional()
+      })
+    ).min(1),
+    minRows: z3.number().int().nonnegative().optional(),
+    uniqueBy: z3.string().optional(),
+    format: z3.enum(["json", "csv", "auto"]).optional(),
+    artifact: z3.boolean().optional()
+  }),
+  /**
+   * Execute `file` in the sandbox and require exit code 0. The ONE
+   * spawning check — evaluated service-side through an injected executor
+   * (absent executor = fail-closed reject) and gated behind the same
+   * `allowScriptExecution` security policy as user scripts. Only
+   * dependency-free files can run (node built-ins ok; the sandbox has no
+   * npm tree): a `node:test`/`assert` file exits nonzero on failure,
+   * which is exactly the contract.
+   */
+  z3.object({
+    kind: z3.literal("nodeRuns"),
+    file: z3.string().min(1),
+    /** Wall-clock budget. Default 20s, cap 60s. */
+    timeoutMs: z3.number().int().positive().max(6e4).optional()
+  }),
+  /**
+   * Every source `file` cites must exist — the anti-fabrication floor for
+   * research/review deliverables (a cited path that resolves is the
+   * difference between grounded work and an invented bibliography).
+   * File-path citations resolve against the workspace listing; URLs pass
+   * unless `corpus` is given, in which case cited paths AND URLs must be
+   * corpus members. Optional `minCitations` floors the citation count.
+   */
+  z3.object({
+    kind: z3.literal("citationsResolve"),
+    file: z3.string().min(1),
+    pattern: z3.string().min(1).optional(),
+    flags: z3.string().optional(),
+    minCitations: z3.number().int().nonnegative().optional(),
+    corpus: z3.array(z3.string().min(1)).min(1).optional(),
+    artifact: z3.boolean().optional()
+  }),
+  /**
+   * Require observable source acquisition during this activation. When
+   * `sourcePath` is non-empty, an exact successful `read_file` of that path
+   * qualifies; otherwise one of `tools` must have completed against an
+   * external source. The runtime supplies the live tool-call evidence.
+   */
+  z3.object({
+    kind: z3.literal("researchEvidence"),
+    sourcePath: z3.string().optional(),
+    tools: z3.array(z3.string().min(1)).min(1),
+    minSuccessful: z3.number().int().positive().optional()
+  }),
+  /**
+   * The H1 slide titles in `file` must match the numbered slide headings in
+   * `outlineFile`, one-for-one and in order. This makes a locked Markdown
+   * outline mechanically binding instead of relying on a reviewer to notice
+   * that slides were merged, dropped, or reordered.
+   */
+  z3.object({
+    kind: z3.literal("markdownHeadingsMatch"),
+    file: z3.string().min(1),
+    outlineFile: z3.string().min(1)
+  }),
+  /**
+   * Named facts in `file` must come from authorized sources: each fact
+   * requires one of its `required` patterns to appear, and its `forbidden`
+   * (decoy) patterns must not appear at all. The distractor-grounding
+   * floor for research/analysis deliverables, productized from the
+   * decoy-research grader.
+   */
+  z3.object({
+    kind: z3.literal("valueGrounding"),
+    file: z3.string().min(1),
+    facts: z3.array(
+      z3.object({
+        id: z3.string().min(1),
+        label: z3.string().min(1).optional(),
+        required: z3.array(z3.string().min(1)).min(1),
+        forbidden: z3.array(z3.string().min(1)).optional()
+      })
+    ).min(1),
+    /** Digit-group normalization ("1,234" ≈ "1234"); defaults on. */
+    normalizeDigits: z3.boolean().optional(),
+    artifact: z3.boolean().optional()
+  }),
+  /**
+   * Value-conservation floor for transform/ETL deliverables: every value
+   * in `file` matching `pattern` (one capture group) must appear verbatim
+   * in at least one `sourceFiles` member (entries may use `*`/`**` globs;
+   * the output file itself is always excluded from the sources). Catches
+   * renumbered/invented identifiers that pass every shape check — the
+   * failure mode that took out 7 of 8 local models on precision ETL in
+   * the core sweep.
+   */
+  z3.object({
+    kind: z3.literal("valuesSubsetOf"),
+    file: z3.string().min(1),
+    sourceFiles: z3.array(z3.string().min(1)).min(1),
+    pattern: z3.string().min(1),
+    flags: z3.string().optional(),
+    minMatches: z3.number().int().nonnegative().optional(),
+    artifact: z3.boolean().optional()
+  }),
+  /**
+   * LLM-judge check for unverifiable qualities (tone, faithfulness).
+   * FAIL-OPEN by design: when no judge is available (keurmeester
+   * unconfigured, timeout, unparseable verdict) the check approves
+   * with a "(fail-open)" note — the opposite polarity of `nodeRuns`.
+   * ADVISORY by default in v1: a would-reject never holds the step;
+   * the opinion rides the approve verdict + gate telemetry until
+   * false-reject data justifies flipping `advisory: false`.
+   */
+  z3.object({
+    kind: z3.literal("judge"),
+    file: z3.string().min(1),
+    /** Imperative rubric: the quality to judge, in one or two sentences. */
+    rubric: z3.string().min(1),
+    /** Context files quoted to the judge alongside the artifact (e.g. a voice guide). */
+    sourceFiles: z3.array(z3.string().min(1)).optional(),
+    /** A fail verdict must quote ≥1 verbatim excerpt from the artifact; default true. */
+    requireEvidence: z3.boolean().optional(),
+    /** Default true (v1). False = enforcing: a valid fail verdict rejects the step. */
+    advisory: z3.boolean().optional(),
+    /** Judge one-shot budget. Default 60s, capped at 120s. */
+    timeoutMs: z3.number().int().positive().max(12e4).optional(),
+    label: z3.string().min(1).optional(),
+    artifact: z3.boolean().optional()
+  }),
+  /**
+   * Structural plan validation on the first Markdown table in `file`:
+   * owners on-roster, dependencies resolve/acyclic/earlier-only,
+   * checkable done-states. The Planner role's mechanical floor.
+   */
+  z3.object({
+    kind: z3.literal("planStructure"),
+    file: z3.string().min(1),
+    minRows: z3.number().int().positive().optional(),
+    /** When given, every Owner cell must be one of these names. */
+    ownerRoster: z3.array(z3.string().min(1)).optional(),
+    /** Rows may only depend on EARLIER rows (default true). */
+    requireEarlierOnly: z3.boolean().optional(),
+    /** Minimum length of each Done-when cell (default 12 chars). */
+    doneWhenMinChars: z3.number().int().positive().optional(),
+    artifact: z3.boolean().optional()
+  })
+]);
+var JudgeVerdictSchema = z3.object({
+  verdict: z3.enum(["pass", "fail"]),
+  reasons: z3.array(z3.string().min(1)).max(5),
+  /** Verbatim quotes from the artifact backing the verdict. */
+  evidence: z3.array(z3.string()).default([]),
+  confidence: z3.enum(["low", "medium", "high"]).optional()
+});
+var GateSpecSchema = z3.object({
+  checks: z3.array(GateCheckSchema).min(1),
+  /** Step to activate when a check fails. Defaults to the entry/build step (loop back). */
+  onFail: z3.string().optional(),
+  /** Step to activate when all checks pass. Defaults to `next`. */
+  onPass: z3.string().optional(),
+  /** After this many failed loops, route to a terminal step instead of looping. Default 4. */
+  maxAttempts: z3.number().int().positive().optional(),
+  /** Role to hand to AFTER static checks pass — the dynamic (Playwright) reviewer layer. */
+  reviewer: z3.string().optional()
+});
+var GateScriptRefSchema = z3.object({
+  name: z3.string().min(1),
+  /** Where the script resolves from. Absent = 'project'. */
+  scope: ScriptScopeSchema.optional(),
+  inputs: z3.record(z3.string(), z3.unknown()).optional()
+});
+var GateScriptResultSchema = z3.object({
+  decision: z3.enum(["approve", "reject"]),
+  message: z3.string().optional(),
+  goto: z3.string().optional(),
+  handoff: z3.object({
+    message: z3.string(),
+    params: z3.record(z3.string(), z3.unknown()).optional()
+  }).optional()
+}).superRefine((v, ctx) => {
+  if (v.decision === "reject" && !v.message?.trim()) {
+    ctx.addIssue({
+      code: z3.ZodIssueCode.custom,
+      message: "a reject result must carry a message \u2014 it is the prescriptive guidance the working session uses to fix the step",
+      path: ["message"]
+    });
+  }
+});
+var StepGateSchema = z3.object({
+  at: z3.enum(["completion", "activation"]),
+  /** Cheap in-process floor; evaluated before any script spawns. */
+  checks: z3.array(GateCheckSchema).optional(),
+  /** Ordered gate scripts; first reject short-circuits. */
+  scripts: z3.array(GateScriptRefSchema).optional(),
+  /**
+   * Step to activate on reject. Absent = stay on this step (the
+   * rejection message re-prompts the working session). Set to the
+   * step's own id to force a fresh re-activation/handoff per reject —
+   * the loop shape that carries small models.
+   */
+  onReject: z3.string().optional(),
+  /** Step to activate on approve. Overrides `step.next`; a gate script's `goto` outranks it. */
+  onApprove: z3.string().optional(),
+  /** Rejections before the task pauses for help. Default 4. */
+  maxAttempts: z3.number().int().positive().optional(),
+  /** Legacy Layer-2 reviewer handoff (activation gates only). */
+  reviewer: z3.string().optional()
+}).superRefine((v, ctx) => {
+  if (!v.checks?.length && !v.scripts?.length) {
+    ctx.addIssue({
+      code: z3.ZodIssueCode.custom,
+      message: "a gate needs at least one check or one script"
+    });
+  }
+});
+var StepGateUnionSchema = z3.union([StepGateSchema, GateSpecSchema]);
+var GATE_DEFAULT_MAX_ATTEMPTS = 4;
+function isLegacyGateSpec(gate) {
+  return !("at" in gate);
+}
+function normalizeStepGate(gate) {
+  if (isLegacyGateSpec(gate)) {
+    return {
+      at: "activation",
+      checks: gate.checks,
+      scripts: [],
+      ...gate.onFail !== void 0 ? { onReject: gate.onFail } : {},
+      ...gate.onPass !== void 0 ? { onApprove: gate.onPass } : {},
+      maxAttempts: gate.maxAttempts ?? GATE_DEFAULT_MAX_ATTEMPTS,
+      ...gate.reviewer !== void 0 ? { reviewer: gate.reviewer } : {},
+      legacy: true
+    };
+  }
+  return {
+    at: gate.at,
+    checks: gate.checks ?? [],
+    scripts: gate.scripts ?? [],
+    ...gate.onReject !== void 0 ? { onReject: gate.onReject } : {},
+    ...gate.onApprove !== void 0 ? { onApprove: gate.onApprove } : {},
+    maxAttempts: gate.maxAttempts ?? GATE_DEFAULT_MAX_ATTEMPTS,
+    ...gate.reviewer !== void 0 ? { reviewer: gate.reviewer } : {},
+    legacy: false
+  };
+}
+function gateEdgeTargets(gate) {
+  const n = normalizeStepGate(gate);
+  return [n.onReject, n.onApprove].filter((t) => t !== void 0);
+}
+
+// src/schemas/hook.ts
+import { z as z4 } from "zod";
+var HookPhaseSchema = z4.enum(["PreToolUse", "PostToolUse"]);
+var HookDecisionSchema = z4.enum(["allow", "deny", "ask"]);
+var HookSpecSchema = z4.object({
+  phase: HookPhaseSchema,
+  matcher: z4.string().default(".*"),
+  script: ScriptRefSchema.optional(),
+  /** Static verdict — mutually exclusive with `script`. */
+  decision: HookDecisionSchema.optional(),
+  /**
+   * Optional human-readable label shown in the UI when this hook
+   * blocks/asks. Useful when one craftbook installs multiple hooks
+   * against the same matcher.
+   */
+  label: z4.string().optional()
+}).superRefine((spec, ctx) => {
+  const hasScript = spec.script !== void 0;
+  const hasDecision = spec.decision !== void 0;
+  if (hasScript === hasDecision) {
+    ctx.addIssue({
+      code: z4.ZodIssueCode.custom,
+      message: "a hook must set exactly one of `script` or `decision`",
+      path: [hasScript ? "decision" : "script"]
+    });
+  }
+});
+var HookResultSchema = z4.object({
+  decision: HookDecisionSchema.default("allow"),
+  message: z4.string().optional()
+});
+
+// src/schemas/craftbook.ts
+var CraftbookBranchSchema = z5.object({
+  when: ScriptOutputPredicateSchema,
+  goto: z5.string()
+});
+var AdvanceWhenSchema = z5.object({
+  /** Workspace-relative deliverable whose presence signals "this step is done". */
+  file: z5.string().min(1),
+  /** Liveness floor in bytes (guards against an empty/stub file). Default 1. */
+  minBytes: z5.number().int().positive().optional(),
+  /**
+   * Named content check the runtime runs before advancing. `html-complete`
+   * = a non-truncated HTML doc (balanced `<script>` tags + a closing
+   * `</body>`/`</html>`); `html-game` adds a render surface + substantial
+   * JS; `nonempty`/`json-valid` are generic. Absent = existence + minBytes
+   * only.
+   */
+  sniff: StepSniffSchema.optional(),
+  /**
+   * Edit-gate. When true, presence is NOT enough — the assignee must have
+   * *written to* `file` during the turn that triggers the advance. This is
+   * what makes `advanceWhen` usable on a step whose deliverable is an EDIT
+   * to a pre-existing source file (fix-a-bug, refactor): without it the
+   * gate would fire on the very first turn because the file already exists
+   * and clears `minBytes`, advancing past the step before any fix lands.
+   * With it, the step holds until the model actually edits the file (a
+   * successful `write_file`/`replace_in_file`/`append_to_file`/`apply_patch`/
+   * `insert_at_marker` targeting `file` this turn). The `sniff`/`minBytes`
+   * floor still applies on top. Absent → legacy "exists is enough".
+   */
+  requireChange: z5.boolean().optional(),
+  /**
+   * Resolve `file` against the project's ARTIFACTS drawer
+   * (`read_artifact` / `write_artifact`) instead of the shipped workspace.
+   * For deliverables that are review/analysis output — a threat model, an
+   * audit report — not product source the user ships. The runtime's
+   * observable-progress + gate readers honor this flag so an artifact
+   * deliverable is gated for size/shape exactly like a workspace one.
+   * Absent → workspace (the default).
+   */
+  artifact: z5.boolean().optional(),
+  /** Step to activate on the signal. Defaults to `next`; must resolve like `next`. */
+  goto: z5.string().optional()
+});
+var ModelTierSchema = z5.enum(MODEL_TIER_ORDER);
+var CraftbookStepSchema = z5.object({
+  id: z5.string().min(1),
+  name: z5.string().min(1),
+  description: z5.string().optional(),
+  /**
+   * Per-step prompt body. In bundled/local catalog form, this is loaded
+   * from the per-step `prompt.md` file (when the version manifest carries
+   * a separate file) and inlined at resolution time.
+   */
+  prompt: z5.string().optional(),
+  suggestedGezelId: z5.string().optional(),
+  /**
+   * Free-form role hint ("reviewer", "developer", "designer"). When set
+   * and `suggestedGezelId` / `assignee` are both absent at step
+   * activation, the TaskManager runs the role through `ensureGezel`
+   * (fuzzy roster match → gilde template → bespoke fallback) and
+   * persists the result onto the step's `suggestedGezelId`. Lets a
+   * craftbook step say "do this with a Reviewer" without baking in a
+   * specific gezel id. Override by setting `assignee` or
+   * `suggestedGezelId` at task create time.
+   */
+  suggestedRole: z5.string().optional(),
+  /**
+   * Minimum model tier to run this step unsupervised. Overrides the
+   * `suggestedRole`'s registry floor (roles/registry.ts) when set;
+   * absent → role floor → no routing. Consumed by per-step model
+   * routing at handoff dispatch: the cheapest installed local model
+   * that clears the floor runs the step.
+   */
+  capabilityFloor: ModelTierSchema.optional(),
+  assignee: TaskAssigneeSchema.optional(),
+  /** Setup scripts, run in order when the step activates. Single ref = legacy shape. */
+  onEnter: ScriptRefListSchema.optional(),
+  /**
+   * Cleanup scripts — the `finally` of the step. Run in order AFTER the
+   * gate (if any) approves; never on a gate reject. Branch predicates
+   * read the LAST ref's output (legacy routing; prefer gate routing).
+   */
+  onExit: ScriptRefListSchema.optional(),
+  /** See {@link AdvanceWhenSchema}. */
+  advanceWhen: AdvanceWhenSchema.optional(),
+  /** The end-of-step decision. See {@link StepGateSchema} (current) / {@link GateSpecSchema} (legacy). */
+  gate: StepGateUnionSchema.optional(),
+  next: z5.string().optional(),
+  branches: z5.array(CraftbookBranchSchema).optional(),
+  terminal: z5.boolean().optional(),
+  /**
+   * Marks the parent step that triggers a declarative per-item fanout
+   * (see {@link CraftbookSpawnSchema}). When this step activates on a
+   * spawn-host task, the runtime reads the craftbook's `spawn.overFile`
+   * workspace JSON array and spawns one child task per item — no model
+   * tool call. Inert unless the craftbook also declares `spawn`.
+   */
+  spawnFanout: z5.boolean().optional()
+});
+var CraftbookSpawnSchema = z5.object({
+  /** Workspace-relative JSON file the parent produces; its array drives the fanout. */
+  overFile: z5.string().min(1),
+  /** Dotted path to the array inside `overFile`. Absent → the file itself is the array. */
+  itemsPath: z5.string().optional(),
+  /** Entry step id of the child template. Defaults to the first `steps` entry. */
+  entryStepId: z5.string().optional(),
+  /** The per-child step template — same shape as a craftbook's own steps. */
+  steps: z5.array(CraftbookStepSchema).min(1)
+});
+function validateCraftbookGraph(cb) {
+  const problems = [];
+  const ids = /* @__PURE__ */ new Set();
+  for (const s of cb.steps) {
+    if (ids.has(s.id)) problems.push(`duplicate step id "${s.id}"`);
+    ids.add(s.id);
+    if (s.terminal && (s.next || s.branches && s.branches.length > 0)) {
+      problems.push(`step "${s.id}" is terminal but also has next/branches`);
+    }
+  }
+  if (!ids.has(cb.entryStepId)) {
+    problems.push(`entryStepId "${cb.entryStepId}" not in steps`);
+  }
+  for (const s of cb.steps) {
+    if (s.next && !ids.has(s.next)) {
+      problems.push(`step "${s.id}".next "${s.next}" missing from steps`);
+    }
+    for (const b of s.branches ?? []) {
+      if (!ids.has(b.goto)) {
+        problems.push(`step "${s.id}" branch goto "${b.goto}" missing from steps`);
+      }
+    }
+    if (s.advanceWhen) {
+      if (s.terminal) problems.push(`step "${s.id}" is terminal but also has advanceWhen`);
+      if (s.advanceWhen.goto && !ids.has(s.advanceWhen.goto)) {
+        problems.push(`step "${s.id}" advanceWhen.goto "${s.advanceWhen.goto}" missing from steps`);
+      }
+    }
+    if (s.gate) {
+      const gate = normalizeStepGate(s.gate);
+      if (s.terminal && gate.at === "activation") {
+        problems.push(`step "${s.id}" is terminal but also has an activation gate`);
+      }
+      for (const edge of gateEdgeTargets(s.gate)) {
+        if (!ids.has(edge)) {
+          problems.push(`step "${s.id}" gate route "${edge}" missing from steps`);
+        }
+      }
+    }
+  }
+  return problems;
+}
+function refineCraftbook(cb, ctx) {
+  for (const message of validateCraftbookGraph(cb)) {
+    ctx.addIssue({
+      code: z5.ZodIssueCode.custom,
+      message,
+      path: message.startsWith("entryStepId") ? ["entryStepId"] : ["steps"]
+    });
+  }
+  for (const message of validateCraftbookScriptRefs(cb)) {
+    ctx.addIssue({ code: z5.ZodIssueCode.custom, message, path: ["steps"] });
+  }
+}
+var CraftbookRequirementSchema = z5.discriminatedUnion("kind", [
+  /** The project is connected to a GitHub repository. */
+  z5.object({ kind: z5.literal("github") }),
+  /** The project's current git branch is not the main line (main/master). */
+  z5.object({ kind: z5.literal("non-main-branch") })
+]);
+var CraftbookRunModesSchema = z5.object({
+  scheduled: z5.enum(["supported", "recommended"]).optional(),
+  nightShift: z5.enum(["supported", "recommended"]).optional()
+});
+var CraftbookToolsetNeedSchema = z5.object({
+  /** Catalog toolset id, e.g. `github`, `usb-camera`. */
+  toolsetId: z5.string().min(1),
+  /** Catalog source provenance (bundled/community), when pinned. */
+  sourceId: z5.string().optional(),
+  /** Optional semver floor; presence is recorded but not yet enforced. */
+  minVersion: z5.string().optional(),
+  /**
+   * When true, the need is a suggestion only — surfaced as a hint, never
+   * blocks invocation. Default (absent/false) = required: the launcher
+   * offers install before the craftbook can run.
+   */
+  optional: z5.boolean().optional(),
+  /**
+   * When true, pre-authorize every tool this toolset exposes for the
+   * duration the craftbook is active — both via a synthesized PreToolUse
+   * allow-hook (in-process providers) and the Claude-CLI permission
+   * broker. Off by default; opt in for unattended/scheduled craftbooks.
+   */
+  autoAllow: z5.boolean().optional(),
+  /** Human-readable rationale shown in the launcher ("pull camera frames"). */
+  reason: z5.string().optional()
+});
+var CraftbookConnectorNeedSchema = z5.object({
+  /** Catalog connector-type id, e.g. `github-pulls`, `mail-gmail`. */
+  typeId: z5.string().min(1),
+  /** Catalog source provenance (bundled/community), when pinned. */
+  sourceId: z5.string().optional(),
+  /**
+   * When true, the craftbook still runs without the connector bound —
+   * the corpus is a bonus, not the substrate. Default (absent/false) =
+   * required: the launcher offers to bind it before the craftbook runs.
+   */
+  optional: z5.boolean().optional(),
+  /** Human-readable rationale shown in the launcher ("pull the PR diff"). */
+  reason: z5.string().optional()
+});
+var CRAFTBOOK_SCRIPT_MAX_BYTES = 64 * 1024;
+var CRAFTBOOK_SCRIPTS_TOTAL_MAX_BYTES = 256 * 1024;
+var CRAFTBOOK_SCRIPTS_MAX_COUNT = 24;
+var CraftbookScriptsSchema = z5.record(ScriptNameSchema, z5.string().min(1).max(CRAFTBOOK_SCRIPT_MAX_BYTES)).superRefine((scripts, ctx) => {
+  const names = Object.keys(scripts);
+  if (names.length > CRAFTBOOK_SCRIPTS_MAX_COUNT) {
+    ctx.addIssue({
+      code: z5.ZodIssueCode.custom,
+      message: `a craftbook carries at most ${CRAFTBOOK_SCRIPTS_MAX_COUNT} scripts (got ${names.length})`
+    });
+  }
+  let total = 0;
+  for (const name of names) total += scripts[name].length;
+  if (total > CRAFTBOOK_SCRIPTS_TOTAL_MAX_BYTES) {
+    ctx.addIssue({
+      code: z5.ZodIssueCode.custom,
+      message: `craftbook scripts total ${total} bytes \u2014 the ceiling is ${CRAFTBOOK_SCRIPTS_TOTAL_MAX_BYTES}`
+    });
+  }
+});
+var CraftbookBasedOnSchema = z5.object({
+  name: z5.string().min(1),
+  url: z5.string().url().regex(/^https?:\/\//i, "basedOn.url must use http or https")
+});
+function validateCraftbookScriptRefs(cb) {
+  if (!cb.scripts) return [];
+  const problems = [];
+  const names = new Set(Object.keys(cb.scripts));
+  const check = (stepId, where, refs) => {
+    for (const ref of refs) {
+      if ((ref.scope ?? "project") === "craftbook" && !names.has(ref.name)) {
+        problems.push(
+          `step "${stepId}" ${where} references craftbook script "${ref.name}" which is not in the scripts map${names.size > 0 ? ` (available: ${[...names].join(", ")})` : ""}`
+        );
+      }
+    }
+  };
+  for (const s of cb.steps) {
+    check(s.id, "onEnter", normalizeScriptRefs(s.onEnter));
+    check(s.id, "onExit", normalizeScriptRefs(s.onExit));
+    if (s.gate) check(s.id, "gate", normalizeStepGate(s.gate).scripts);
+  }
+  return problems;
+}
+var CraftbookSchema = z5.object({
+  /** Matches catalog folder name. For ad-hoc embedded craftbooks (inline-steps tasks), a generated id. */
+  id: z5.string().min(1),
+  name: z5.string().min(1),
+  description: z5.string().optional(),
+  /** Semver from the catalog version this craftbook was resolved from. Unset for ad-hoc embedded books. */
+  version: z5.string().optional(),
+  /** Optional credit + link to the upstream work this craftbook adapts. */
+  basedOn: CraftbookBasedOnSchema.optional(),
+  plan: z5.string().optional(),
+  defaultAssignee: TaskAssigneeSchema.optional(),
+  steps: z5.array(CraftbookStepSchema).min(1),
+  entryStepId: z5.string().min(1),
+  /**
+   * User-speech phrases that route to this craftbook. Matched
+   * case-insensitively as substrings against the user's chat input
+   * (or against a slash-command argument). Optional; absent =
+   * invocable only via explicit `invoke_craftbook` / Commands panel.
+   */
+  triggers: z5.array(z5.string()).optional(),
+  /**
+   * Pre/PostToolUse hooks installed for the duration the craftbook
+   * is active. The MCP bridge consults this list before forwarding
+   * a `tools/call`. See `hook.ts` for the decision contract.
+   */
+  hooks: z5.array(HookSpecSchema).optional(),
+  /**
+   * Optional squisq/JSON-Schema object describing the parameters this
+   * craftbook collects before it runs. Its top-level `properties` are
+   * the (scalar) params, in declaration order: the command launcher
+   * renders them into positional CLI tokens (`code-review <focus>
+   * <intensity>`) and squisq's `JsonEditor` renders them as a form.
+   * Stored permissively (an arbitrary squisq schema) and read
+   * structurally; typed as squisq's `SquisqAnnotatedSchema` at the UI
+   * boundary. Absent = parameterless (the command is injected directly).
+   */
+  paramSchema: z5.record(z5.string(), z5.unknown()).optional(),
+  /**
+   * CLI token the launcher stages into the terminal and that the
+   * terminal recognizes. Defaults to `id` when absent — e.g. the
+   * "Code Review" craftbook (id `review`) sets `command: "code-review"`.
+   */
+  command: z5.string().regex(/^[a-z][a-z0-9-]*$/).optional(),
+  /**
+   * Prerequisites a project must satisfy for this craftbook to be
+   * applicable. When unmet, the craftbook is hidden from the launcher
+   * and not recognized as a terminal command. Absent = always offered.
+   */
+  requirements: z5.array(CraftbookRequirementSchema).optional(),
+  /** Unattended launch modes this recipe is suitable for. */
+  runModes: CraftbookRunModesSchema.optional(),
+  /**
+   * Toolsets (MCP servers / CLIs / APIs) this craftbook depends on. Drives
+   * the launcher's install/config affordance and — for entries with
+   * `autoAllow` — pre-authorizes those toolsets' tools while the craftbook
+   * is active. See {@link CraftbookToolsetNeedSchema}. Unlike
+   * `requirements`, this is carried into the runtime craftbook and the task
+   * snapshot. Absent = no declared toolset dependencies.
+   */
+  toolsets: z5.array(CraftbookToolsetNeedSchema).optional(),
+  /**
+   * Connectors whose mirrored `artifacts/data/` corpus this craftbook reads. The
+   * launcher binds and syncs them before the first step runs. See
+   * {@link CraftbookConnectorNeedSchema}. Carried into the runtime
+   * craftbook and the task snapshot so a running task records what it
+   * was launched against. Absent = no connector dependencies.
+   */
+  connectors: z5.array(CraftbookConnectorNeedSchema).optional(),
+  /**
+   * Embedded script sources (name → TypeScript). See
+   * {@link CraftbookScriptsSchema}. Hydrated at resolution time for
+   * bundled/local/project books (their sources stay `scripts/*.ts`
+   * files on disk) and carried verbatim into the task snapshot, so a
+   * running task executes its gates from its own copy.
+   */
+  scripts: CraftbookScriptsSchema.optional(),
+  /**
+   * Declarative per-item fanout config. When present, the craftbook is a
+   * spawn host: its `spawnFanout` step fans out one child per item in
+   * `spawn.overFile`. See {@link CraftbookSpawnSchema}. Carried into the
+   * task snapshot so the runtime reads it at fanout time.
+   */
+  spawn: CraftbookSpawnSchema.optional(),
+  createdAt: z5.string(),
+  updatedAt: z5.string()
+}).superRefine(refineCraftbook);
+var DeliverableKindSchema = z5.enum([
+  "html-game",
+  "html-multiscreen-game",
+  "html-page",
+  "html-marketing-site",
+  "markdown-doc",
+  "markdown-report",
+  "markdown-notes",
+  "json",
+  "yaml-spec",
+  "code-module",
+  "code-with-tests",
+  "security-report",
+  "image-set",
+  "audio-file",
+  "slide-deck",
+  "data-file",
+  "generic-file"
+]);
+var StepDeliverableSchema = z5.object({
+  /** Workspace-relative file the step must produce. The only required field. */
+  path: z5.string().min(1),
+  /** Artifact class; inferred from the file extension when absent. */
+  kind: DeliverableKindSchema.optional(),
+  /** Override the class-default byte floor. */
+  minBytes: z5.number().int().positive().optional(),
+  /** Gate rejections before the task pauses for help. */
+  maxAttempts: z5.number().int().positive().optional(),
+  /** Gate the artifacts drawer instead of the workspace. */
+  artifact: z5.boolean().optional(),
+  /**
+   * The deliverable is an EDIT to a pre-existing file (fix/refactor):
+   * presence alone never advances the step — the assignee must have
+   * written to the file this turn. See {@link AdvanceWhenSchema}.
+   */
+  requireChange: z5.boolean().optional(),
+  /**
+   * For code deliverables: additionally execute the file in the sandbox
+   * and require exit 0 (a `node:test`/`assert` file exits nonzero on
+   * failure — exactly the contract). Opt-in.
+   */
+  execute: z5.boolean().optional(),
+  /** For data deliverables: required column names (adds a tableShape check). */
+  columns: z5.array(z5.string().min(1)).min(1).optional(),
+  /** For data deliverables: minimum row count (adds a tableShape check). */
+  minRows: z5.number().int().positive().optional()
+});
+var NewCraftbookStepSchema = z5.object({
+  id: z5.string().optional(),
+  name: z5.string().min(1),
+  description: z5.string().optional(),
+  prompt: z5.string().optional(),
+  suggestedGezelId: z5.string().optional(),
+  /** See {@link CraftbookStepSchema.shape.suggestedRole}. */
+  suggestedRole: z5.string().optional(),
+  /** See {@link CraftbookStepSchema.shape.capabilityFloor}. */
+  capabilityFloor: ModelTierSchema.optional(),
+  assignee: TaskAssigneeSchema.optional(),
+  onEnter: ScriptRefListSchema.optional(),
+  onExit: ScriptRefListSchema.optional(),
+  advanceWhen: AdvanceWhenSchema.optional(),
+  gate: StepGateUnionSchema.optional(),
+  /** See {@link StepDeliverableSchema} — one field attaches the enforced gate. */
+  deliverable: StepDeliverableSchema.optional(),
+  next: z5.string().optional(),
+  branches: z5.array(CraftbookBranchSchema).optional(),
+  terminal: z5.boolean().optional(),
+  /** See {@link CraftbookStepSchema.shape.spawnFanout}. */
+  spawnFanout: z5.boolean().optional()
+});
+var CreateCraftbookRequestSchema = z5.object({
+  id: z5.string().optional(),
+  name: z5.string().min(1),
+  description: z5.string().optional(),
+  basedOn: CraftbookBasedOnSchema.optional(),
+  plan: z5.string().optional(),
+  defaultAssignee: TaskAssigneeSchema.optional(),
+  steps: z5.array(NewCraftbookStepSchema).min(1),
+  entryStepId: z5.string().optional(),
+  paramSchema: z5.record(z5.string(), z5.unknown()).optional(),
+  command: z5.string().regex(/^[a-z][a-z0-9-]*$/).optional(),
+  requirements: z5.array(CraftbookRequirementSchema).optional(),
+  runModes: CraftbookRunModesSchema.optional(),
+  toolsets: z5.array(CraftbookToolsetNeedSchema).optional(),
+  scripts: CraftbookScriptsSchema.optional()
+});
+var UpdateCraftbookRequestSchema = z5.object({
+  name: z5.string().min(1).optional(),
+  description: z5.string().nullable().optional(),
+  basedOn: CraftbookBasedOnSchema.nullable().optional(),
+  plan: z5.string().nullable().optional(),
+  defaultAssignee: TaskAssigneeSchema.nullable().optional(),
+  steps: z5.array(NewCraftbookStepSchema).min(1).optional(),
+  entryStepId: z5.string().optional(),
+  paramSchema: z5.record(z5.string(), z5.unknown()).nullable().optional(),
+  command: z5.string().regex(/^[a-z][a-z0-9-]*$/).nullable().optional(),
+  requirements: z5.array(CraftbookRequirementSchema).nullable().optional(),
+  runModes: CraftbookRunModesSchema.nullable().optional(),
+  toolsets: z5.array(CraftbookToolsetNeedSchema).nullable().optional(),
+  /** Full-replace semantics: the map is the truth. `null` clears all scripts. */
+  scripts: CraftbookScriptsSchema.nullable().optional()
+});
+var CraftbookSummarySchema = z5.object({
+  id: z5.string(),
+  name: z5.string(),
+  description: z5.string().optional(),
+  version: z5.string().optional(),
+  basedOn: CraftbookBasedOnSchema.optional(),
+  /**
+   * Where the craftbook came from. `bundled` — shipped catalog;
+   * `local` — user-authored under `~/.gezel/craftbook-templates/`;
+   * `project` — project-local, defined in a workspace `.gezel/craftbooks/`
+   * folder (often auto-imported from a `.claude/skills` / `agents/skills`
+   * SKILL.md). Project craftbooks only surface inside their own project.
+   */
+  source: z5.enum(["bundled", "local", "project"]),
+  stepCount: z5.number().int().nonnegative()
+});
+var ListCraftbooksResponseSchema = z5.object({
+  craftbooks: z5.array(CraftbookSummarySchema)
+});
+var ProjectCraftbookProvenanceSchema = z5.object({
+  installedBy: z5.literal("project-type"),
+  typeId: z5.string(),
+  typeVersion: z5.string(),
+  bookVersion: z5.string(),
+  /** sha256 over the installed book's canonical recipe JSON. */
+  contentHash: z5.string(),
+  installedAt: z5.string()
+});
+var CraftbookSuggestionSchema = z5.object({
+  id: z5.string(),
+  name: z5.string(),
+  description: z5.string().optional(),
+  source: z5.enum(["bundled", "local", "project"]),
+  version: z5.string().optional(),
+  basedOn: CraftbookBasedOnSchema.optional(),
+  stepCount: z5.number().int().nonnegative(),
+  tags: z5.array(z5.string()).optional(),
+  triggers: z5.array(z5.string()).optional(),
+  score: z5.number(),
+  semantic: z5.number().optional(),
+  lexical: z5.number()
+});
+var SuggestCraftbooksResponseSchema = z5.object({
+  suggestions: z5.array(CraftbookSuggestionSchema)
+});
+var CraftbookResponseSchema = z5.object({
+  craftbook: CraftbookSchema
+});
+function slugifyStepId(input) {
+  return input.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 64) || "step";
+}
+var StepPositionSchema = z5.object({
+  /** Insert immediately after the step with this id. */
+  after: z5.string().optional(),
+  /** Insert immediately before the step with this id. */
+  before: z5.string().optional(),
+  /** Absolute insertion index (clamped to [0, length]). */
+  index: z5.number().int().nonnegative().optional()
+});
+
+// src/markdown/frontmatter.ts
+import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+function parseYamlFrontmatter(source) {
+  const opening = /^(?:\uFEFF)?---[ \t]*(?:\r?\n|$)/.exec(source);
+  if (!opening) return { data: {}, content: source };
+  const closing = /^(?:---|\.\.\.)[ \t]*(?:\r?\n|$)/gm;
+  closing.lastIndex = opening[0].length;
+  const end = closing.exec(source);
+  if (!end) throw new Error("YAML frontmatter is missing its closing delimiter");
+  const yamlText = source.slice(opening[0].length, end.index);
+  const value = parseYaml(yamlText, {
+    prettyErrors: false,
+    uniqueKeys: true
+  });
+  if (value === null || value === void 0) {
+    return { data: {}, content: source.slice(closing.lastIndex) };
+  }
+  if (typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("YAML frontmatter must contain a mapping");
+  }
+  return {
+    data: value,
+    content: source.slice(closing.lastIndex)
+  };
+}
+function stringifyYamlFrontmatter(content, data) {
+  const yaml = stringifyYaml(data, {
+    lineWidth: 0,
+    minContentWidth: 0
+  });
+  return `---
+${yaml}---
+${content || "\n"}`;
+}
+function parseYamlMapping(source) {
+  if (source.trim().length === 0) return {};
+  const value = parseYaml(source, {
+    prettyErrors: false,
+    uniqueKeys: true
+  });
+  if (value === null || value === void 0) return {};
+  if (typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("YAML block must contain a mapping");
+  }
+  return value;
+}
+function stringifyYamlMapping(data) {
+  return stringifyYaml(data, {
+    lineWidth: 0,
+    minContentWidth: 0
+  });
+}
+
+// src/markdown/md-structure.ts
+var FENCE = /^(```+|~~~+)(.*)$/;
+function splitSections(lines) {
+  const sections = [];
+  const preamble = [];
+  let current = null;
+  let openFence = null;
+  for (const line of lines) {
+    const fence = FENCE.exec(line.trim());
+    if (openFence !== null) {
+      if (fence && fence[1][0] === openFence[0] && fence[1].length >= openFence.length && fence[2].trim() === "") {
+        openFence = null;
+      }
+    } else if (fence) {
+      openFence = fence[1];
+    } else if (/^##\s+/.test(line)) {
+      if (current) sections.push({ heading: current.heading, body: current.body.join("\n") });
+      current = { heading: line.trim(), body: [] };
+      continue;
+    }
+    if (current) current.body.push(line);
+    else preamble.push(line);
+  }
+  if (current) sections.push({ heading: current.heading, body: current.body.join("\n") });
+  return { preamble: preamble.join("\n"), sections };
+}
+function findFirstH1(lines) {
+  let openFence = null;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const fence = FENCE.exec(line.trim());
+    if (openFence !== null) {
+      if (fence && fence[1][0] === openFence[0] && fence[1].length >= openFence.length && fence[2].trim() === "") {
+        openFence = null;
+      }
+      continue;
+    }
+    if (fence) {
+      openFence = fence[1];
+      continue;
+    }
+    const h1 = /^#\s+(.+?)\s*$/.exec(line);
+    if (h1) return { index: i, title: h1[1] };
+  }
+  return null;
+}
+function extractFirstFence(body) {
+  const lines = body.split("\n");
+  let inFence = false;
+  let fenceMarker = "";
+  let out = null;
+  for (const line of lines) {
+    const fence = FENCE.exec(line);
+    if (fence && !inFence) {
+      inFence = true;
+      fenceMarker = fence[1];
+      out = [];
+      continue;
+    }
+    if (inFence && isFenceClose(line, fenceMarker)) {
+      return out.join("\n");
+    }
+    if (inFence) out.push(line);
+  }
+  return void 0;
+}
+function extractAllFences(body) {
+  const lines = body.split("\n");
+  const fences = [];
+  let inFence = false;
+  let fenceMarker = "";
+  let lang = "";
+  let buf = [];
+  for (const line of lines) {
+    const fence = FENCE.exec(line);
+    if (fence && !inFence) {
+      inFence = true;
+      fenceMarker = fence[1];
+      lang = fence[2].trim().toLowerCase();
+      buf = [];
+      continue;
+    }
+    if (inFence && isFenceClose(line, fenceMarker)) {
+      inFence = false;
+      fences.push({ lang, code: buf.join("\n") });
+      continue;
+    }
+    if (inFence) buf.push(line);
+  }
+  return fences;
+}
+function isFenceClose(line, marker) {
+  const m = FENCE.exec(line.trim());
+  return m !== null && m[1][0] === marker[0] && m[1].length >= marker.length && m[2].trim() === "";
+}
+function parseYamlBlock(yamlText) {
+  return parseYamlMapping(yamlText);
+}
+function stringifyYamlBlock(fields) {
+  return stringifyYamlMapping(fields);
+}
+function pickFence(source) {
+  let longest = 2;
+  for (const m of source.matchAll(/`{3,}/g)) longest = Math.max(longest, m[0].length);
+  return "`".repeat(longest + 1);
+}
+
+// src/markdown/craftbook-md.ts
+var STEP_HEADING = /^##\s+step\s*:\s*(.+?)\s*$/i;
+var SCRIPT_HEADING = /^##\s+script\s*:\s*(.+?)\s*$/i;
+var FRONTMATTER_KEYS = [
+  "id",
+  "name",
+  "entry",
+  "basedOn",
+  "triggers",
+  "command",
+  "plan",
+  "defaultAssignee",
+  "requirements",
+  "runModes",
+  "toolsets",
+  "connectors",
+  "paramSchema",
+  "hooks",
+  "version",
+  "releasedAt"
+];
+var STEP_FENCE_KEYS = [
+  "id",
+  "description",
+  "suggestedGezelId",
+  "suggestedRole",
+  "capabilityFloor",
+  "assignee",
+  "deliverable",
+  "onEnter",
+  "onExit",
+  "advanceWhen",
+  "gate",
+  "next",
+  "branches",
+  "terminal"
+];
+function parseCraftbookMarkdown(text) {
+  const errors = [];
+  let fm;
+  let content;
+  try {
+    const parsed = parseYamlFrontmatter(text);
+    fm = parsed.data;
+    content = parsed.content;
+  } catch (err) {
+    return {
+      ok: false,
+      errors: [
+        {
+          where: "frontmatter",
+          message: `the YAML frontmatter does not parse: ${err instanceof Error ? err.message.split("\n")[0] : String(err)}`,
+          fix: "check indentation and quoting between the opening and closing --- lines"
+        }
+      ]
+    };
+  }
+  const lines = content.split(/\r?\n/);
+  const sections = splitSections(lines);
+  const doc = {};
+  for (const key of FRONTMATTER_KEYS) {
+    if (fm[key] !== void 0 && fm[key] !== null) {
+      doc[key === "entry" ? "entryStepId" : key] = fm[key];
+    }
+  }
+  for (const key of Object.keys(fm)) {
+    if (!FRONTMATTER_KEYS.includes(key)) {
+      errors.push({
+        where: "frontmatter",
+        message: `unknown key "${key}".`,
+        fix: `legal keys: ${FRONTMATTER_KEYS.join(", ")} \u2014 step fields go in the step's yaml block`
+      });
+    }
+  }
+  if (sections.preamble.trim().length > 0) doc.description = sections.preamble.trim();
+  const steps = [];
+  const scripts = {};
+  for (const section of sections.sections) {
+    const stepMatch = STEP_HEADING.exec(section.heading);
+    const scriptMatch = SCRIPT_HEADING.exec(section.heading);
+    if (stepMatch) {
+      const name = stepMatch[1];
+      const { fenced, prose, fenceError } = extractStepSection(section.body);
+      let fields = {};
+      if (fenceError) {
+        errors.push({
+          where: `section "## Step: ${name}"`,
+          message: fenceError,
+          fix: "put the step's structured fields in one ```yaml fence directly under the heading"
+        });
+      } else if (fenced !== void 0) {
+        try {
+          fields = parseYamlBlock(fenced);
+        } catch (err) {
+          errors.push({
+            where: `section "## Step: ${name}"`,
+            message: `the yaml step block does not parse: ${err instanceof Error ? err.message.split("\n")[0] : String(err)}`,
+            fix: "check indentation/quoting inside the ```yaml fence \u2014 flow-style JSON values are also legal"
+          });
+        }
+      }
+      const step = { ...fields, name };
+      if (prose.trim().length > 0) step.prompt = prose.trim();
+      steps.push(step);
+    } else if (scriptMatch) {
+      const name = scriptMatch[1];
+      const source = extractFirstFence(section.body);
+      if (source === void 0) {
+        errors.push({
+          where: `section "## Script: ${name}"`,
+          message: "no fenced code block found under this heading.",
+          fix: "put the script source in one ```ts fence directly under the heading"
+        });
+      } else {
+        scripts[name] = source;
+      }
+    } else {
+      errors.push({
+        where: `section "${section.heading}"`,
+        message: "unrecognized section heading.",
+        fix: "every `## ` heading must be `## Step: <name>` or `## Script: <name>`"
+      });
+    }
+  }
+  if (steps.length > 0) doc.steps = steps;
+  if (Object.keys(scripts).length > 0) doc.scripts = scripts;
+  if (steps.length === 0) {
+    errors.push({
+      where: "document",
+      message: "no steps found.",
+      fix: "add at least one `## Step: <name>` section"
+    });
+  }
+  return errors.length > 0 ? { ok: false, errors } : { ok: true, doc, errors: [] };
+}
+function serializeCraftbookMarkdown(doc) {
+  const fm = {};
+  for (const key of FRONTMATTER_KEYS) {
+    const docKey = key === "entry" ? "entryStepId" : key;
+    const value = doc[docKey];
+    if (value !== void 0) fm[key] = value;
+  }
+  const parts = [];
+  if (doc.description) parts.push(doc.description.trim());
+  for (const step of doc.steps) {
+    const fields = {};
+    for (const key of STEP_FENCE_KEYS) {
+      const value = step[key];
+      if (value !== void 0) fields[key] = value;
+    }
+    let section = `## Step: ${step.name}`;
+    if (Object.keys(fields).length > 0) {
+      section += `
+
+\`\`\`yaml
+${stringifyYamlBlock(fields)}\`\`\``;
+    }
+    if (step.prompt) section += `
+
+${step.prompt.trim()}`;
+    parts.push(section);
+  }
+  for (const [name, source] of Object.entries(doc.scripts ?? {})) {
+    const fence = pickFence(source);
+    parts.push(`## Script: ${name}
+
+${fence}ts
+${source.trimEnd()}
+${fence}`);
+  }
+  const body = `${parts.join("\n\n")}
+`;
+  return Object.keys(fm).length > 0 ? stringifyYamlFrontmatter(body, fm) : body;
+}
+function extractStepSection(body) {
+  const lines = body.split("\n");
+  const proseLines = [];
+  let fenced = null;
+  let inFence = false;
+  let fenceTag = "";
+  let taken = false;
+  let fenceMarker = "";
+  for (const line of lines) {
+    const fence = FENCE.exec(line);
+    if (fence && !inFence) {
+      inFence = true;
+      fenceMarker = fence[1];
+      fenceTag = fence[2].trim().toLowerCase();
+      if (!taken && (fenceTag === "yaml" || fenceTag === "yml" || fenceTag === "")) {
+        fenced = [];
+      } else {
+        proseLines.push(line);
+      }
+      continue;
+    }
+    if (inFence && isFenceClose(line, fenceMarker)) {
+      inFence = false;
+      if (fenced !== null && !taken) {
+        taken = true;
+      } else {
+        proseLines.push(line);
+      }
+      continue;
+    }
+    if (inFence && fenced !== null && !taken) {
+      fenced.push(line);
+      continue;
+    }
+    proseLines.push(line);
+  }
+  if (inFence) {
+    return { prose: proseLines.join("\n"), fenceError: "a code fence is never closed." };
+  }
+  return {
+    ...taken && fenced !== null ? { fenced: fenced.join("\n") } : {},
+    prose: proseLines.join("\n")
+  };
+}
+function defaultStepIdForName(name) {
+  return slugifyStepId(name);
+}
+
+// src/schemas/gezel.ts
+import { z as z14 } from "zod";
+
+// src/poppetje/schema.ts
+import { z as z6 } from "zod";
+
+// src/poppetje/catalogs.ts
+var BODY_ARCHETYPES = {
+  broad: {
+    baseW: 46,
+    hipW: 52,
+    waistW: 52,
+    chestW: 56,
+    shoulderW: 54,
+    label: "broad",
+    note: "Barrel torso, broad through the shoulders. Reads adult, sturdy."
+  },
+  tapered: {
+    baseW: 58,
+    hipW: 52,
+    waistW: 46,
+    chestW: 38,
+    shoulderW: 32,
+    label: "tapered",
+    note: "Classic peg-doll cone. Wide base, smooth taper to a narrow top."
+  },
+  curvy: {
+    baseW: 48,
+    hipW: 60,
+    waistW: 34,
+    chestW: 46,
+    shoulderW: 36,
+    label: "curvy",
+    note: "Hourglass \u2014 hip flare, pinched waist, narrower shoulders."
+  },
+  athletic: {
+    baseW: 38,
+    hipW: 40,
+    waistW: 42,
+    chestW: 54,
+    shoulderW: 56,
+    label: "athletic",
+    note: "V-shape. Wider chest and shoulders, narrower waist and hips."
+  },
+  slender: {
+    baseW: 46,
+    hipW: 42,
+    waistW: 34,
+    chestW: 36,
+    shoulderW: 32,
+    label: "slender",
+    note: "Narrow throughout. Reads tall and lean."
+  },
+  stout: {
+    baseW: 62,
+    hipW: 64,
+    waistW: 62,
+    chestW: 58,
+    shoulderW: 50,
+    label: "stout",
+    note: "Wide throughout. Reads grounded, generous."
+  }
+};
+var BODY_SHAPE_KEYS = Object.keys(BODY_ARCHETYPES);
+var FIGURE_SCALES = {
+  adult: { bodyScale: 1, headScale: 1, label: "adult", note: "Standard crew member." },
+  shorter: {
+    bodyScale: 0.88,
+    headScale: 0.98,
+    label: "shorter",
+    note: "Older or simply shorter adult."
+  },
+  child: {
+    bodyScale: 0.78,
+    headScale: 0.96,
+    label: "child",
+    note: "Short body, head reads proportionally larger."
+  },
+  toddler: { bodyScale: 0.76, headScale: 0.95, label: "toddler", note: "Smallest. Mostly head." }
+};
+var FIGURE_SCALE_KEYS = Object.keys(FIGURE_SCALES);
+var HAT_OPTIONS = ["cap", "beanie", "kerchief", "straw", "newsboy", "hood"];
+var DRESS_OPTIONS = ["scarf", "apron", "collar", "turtleneck"];
+var HAIR_SHAPES = ["halo", "short", "long", "bun", "braids", "shaved", "bald"];
+var ACCESSORY_OPTIONS = [
+  "glasses",
+  "sunglasses",
+  "cateye",
+  "readers",
+  "monocle",
+  "eyepatch",
+  "earrings",
+  "earring-left",
+  "earring-right",
+  "flower",
+  "hairclip",
+  "headband",
+  "bowtie",
+  "necklace",
+  "brooch",
+  "facemask",
+  "goggles",
+  "safety-glasses",
+  "pince-nez",
+  "headphones",
+  "hearing-aid",
+  "nose-ring",
+  "hoop-earrings",
+  "drop-earrings",
+  "pearl-earrings",
+  "bandage",
+  "feather",
+  "pencil",
+  "ribbon",
+  "necktie",
+  "cravat",
+  "bolo-tie",
+  "lanyard",
+  "medal",
+  "pocket-square",
+  "tool-pendant"
+];
+var FACIAL_HAIR_OPTIONS = ["beard", "mustache"];
+var MARK_OPTIONS = ["freckles", "mole"];
+var SHIRT_PATTERN_OPTIONS = [
+  "plain",
+  "buttons",
+  "stripes",
+  "sash",
+  "yoke",
+  "twotone"
+];
+var EXPRESSION_OPTIONS = ["smile", "wider", "neutral", "wink", "sleepy"];
+
+// src/poppetje/schema.ts
+function migrateLegacyAccessory(raw) {
+  if (!raw || typeof raw !== "object") return raw;
+  const r = { ...raw };
+  const acc = r.accessory;
+  if (acc === "beard" || acc === "mustache") {
+    if (r.facialHair == null) r.facialHair = acc;
+    r.accessory = null;
+  } else if (acc === "freckles" || acc === "mole") {
+    if (r.mark == null) r.mark = acc;
+    r.accessory = null;
+  } else if (acc === "earring") {
+    r.accessory = "earrings";
+  }
+  return r;
+}
+var PoppetjeSchema = z6.preprocess(
+  migrateLegacyAccessory,
+  z6.object({
+    /** Stable id; locks the wood-grain noise seed. Pin to the gezel id at creation. */
+    key: z6.string().min(1),
+    name: z6.string(),
+    bodyShape: z6.enum(BODY_SHAPE_KEYS),
+    figureScale: z6.enum(FIGURE_SCALE_KEYS),
+    /** Mid-tone of the head. Paired with skin2 for the lateral gradient. */
+    skin: z6.string(),
+    /** Darker edge tone. */
+    skin2: z6.string(),
+    hair: z6.string(),
+    hairShape: z6.enum(HAIR_SHAPES),
+    /** Replaces hair when set; 'hood' renders at body level. */
+    hat: z6.enum(HAT_OPTIONS).nullable().optional().default(null),
+    /** Body overlay; null for an unadorned shirt. */
+    dress: z6.enum(DRESS_OPTIONS).nullable().optional().default(null),
+    /** Wearable face accessory (glasses, earring, monocle). User-toggleable. */
+    accessory: z6.enum(ACCESSORY_OPTIONS).nullable().optional().default(null),
+    /** Facial hair (beard, mustache). Physical — reroll-only. */
+    facialHair: z6.enum(FACIAL_HAIR_OPTIONS).nullable().optional().default(null),
+    /** Small facial detail (freckles, mole). Physical — reroll-only. */
+    mark: z6.enum(MARK_OPTIONS).nullable().optional().default(null),
+    expression: z6.enum(EXPRESSION_OPTIONS).optional().default("smile"),
+    shirt: z6.string(),
+    shirtAccent: z6.string(),
+    /**
+     * Painted garment pattern over the shirt (buttons, stripes, sash, …).
+     * Files written before patterns existed parse as `plain` — the bare
+     * shirt those characters always had.
+     */
+    shirtPattern: z6.enum(SHIRT_PATTERN_OPTIONS).optional().default("plain")
+  })
+);
+
+// src/schemas/codex.ts
+import { z as z7 } from "zod";
+var CodexPermissionModeSchema = z7.enum(["plan", "edit", "reviewed", "full"]);
+var LegacyCodexPermissionModeSchema = z7.enum([
+  "default",
+  "acceptEdits",
+  "bypassPermissions"
+]);
+var CodexPermissionModeCompatSchema = z7.union([
+  CodexPermissionModeSchema,
+  LegacyCodexPermissionModeSchema
+]);
+
+// src/schemas/growth.ts
+import { z as z9 } from "zod";
+
+// src/schemas/tuning-profile-registry.ts
+import { z as z8 } from "zod";
+var TuningProfileIdSchema = z8.string().min(1).describe("Canonical tuning profile id.");
+
+// src/schemas/growth.ts
+var GrowthEvidenceSchema = z9.object({
+  /** Memory-file day (YYYY-MM-DD) — rewritten server-side from the matched entry. */
+  day: z9.string().regex(/^\d{4}-\d{2}-\d{2}$/),
+  kind: z9.enum(["fact", "decision", "pref", "status"]),
+  excerpt: z9.string().min(1).max(400)
+});
+var TraitProposalSchema = z9.object({
+  id: z9.string(),
+  kind: z9.literal("trait"),
+  title: z9.string().min(1).max(80),
+  /** One imperative second-person sentence destined for the prompt. */
+  traitText: z9.string().min(1).max(200),
+  evidence: z9.array(GrowthEvidenceSchema).min(1).max(3)
+});
+var TuningActionSchema = z9.discriminatedUnion("type", [
+  z9.object({ type: z9.literal("profile"), profile: TuningProfileIdSchema }),
+  /** Resolved + clamped at accept time against the then-current frontmatter. */
+  z9.object({ type: z9.literal("temperature"), delta: z9.union([z9.literal(0.1), z9.literal(-0.1)]) })
+]);
+var TuningProposalSchema = z9.object({
+  id: z9.string(),
+  kind: z9.literal("tuning"),
+  title: z9.string().max(80),
+  description: z9.string().max(300),
+  action: TuningActionSchema
+});
+var CosmeticProposalSchema = z9.object({
+  id: z9.string(),
+  kind: z9.literal("cosmetic"),
+  title: z9.string().max(80),
+  /** Key into GROWTH_COSMETICS, or a generic `level-N` milestone marker. */
+  cosmeticId: z9.string()
+});
+var GrowthProposalSchema = z9.discriminatedUnion("kind", [
+  TraitProposalSchema,
+  TuningProposalSchema,
+  CosmeticProposalSchema
+]);
+var PendingLevelUpSchema = z9.object({
+  toLevel: z9.number().int().min(2),
+  proposals: z9.array(GrowthProposalSchema).min(1).max(5),
+  createdAt: z9.string()
+});
+var GrowthSignalsSchema = z9.object({
+  memoryXp: z9.number().int().nonnegative().default(0),
+  lessonsXp: z9.number().int().nonnegative().default(0),
+  taskXp: z9.number().int().nonnegative().default(0),
+  consultXp: z9.number().int().nonnegative().default(0)
+});
+var AdoptedTraitRecordSchema = z9.object({
+  traitId: z9.string(),
+  text: z9.string(),
+  level: z9.number().int(),
+  adoptedAt: z9.string(),
+  evidence: z9.array(GrowthEvidenceSchema),
+  /** Set when the user later retires the trait — kept for the character sheet. */
+  removedAt: z9.string().optional()
+});
+var DeclinedProposalRecordSchema = z9.object({
+  kind: z9.enum(["trait", "tuning", "cosmetic"]),
+  title: z9.string(),
+  /** Used for never-re-offer matching on trait proposals. */
+  traitText: z9.string().optional(),
+  level: z9.number().int(),
+  declinedAt: z9.string()
+});
+var GezelGrowthStateSchema = z9.object({
+  version: z9.literal(1).default(1),
+  level: z9.number().int().min(1).default(1),
+  xp: z9.number().int().nonnegative().default(0),
+  signals: GrowthSignalsSchema.prefault({}),
+  lastComputedAt: z9.string().optional(),
+  pendingLevelUp: PendingLevelUpSchema.optional(),
+  adoptedTraits: z9.array(AdoptedTraitRecordSchema).default([]),
+  declinedProposals: z9.array(DeclinedProposalRecordSchema).default([]),
+  unlockedCosmetics: z9.array(z9.object({ id: z9.string(), at: z9.string() })).default([])
+});
+var GezelGrowthSummarySchema = z9.object({
+  level: z9.number().int().min(1),
+  /** True when a level-up is waiting for the user's choice. */
+  pending: z9.boolean().optional()
+});
+
+// src/schemas/model-tuning.ts
+import { z as z10 } from "zod";
+var DrySamplerSchema = z10.object({
+  multiplier: z10.number().min(0).max(5).describe("DRY penalty strength. 0 disables. 0.8 is a reasonable default."),
+  base: z10.number().min(0).max(5).optional().describe("Base of the exponential penalty for repeated tokens. Default 1.75."),
+  allowedLength: z10.number().int().min(0).max(64).optional().describe("Minimum n-gram length before DRY kicks in. Default 2.")
+}).describe("DRY anti-repetition sampler (llama.cpp only).");
+var XtcSamplerSchema = z10.object({
+  probability: z10.number().min(0).max(1).describe("Probability of triggering XTC on any given step."),
+  threshold: z10.number().min(0).max(1).describe("Minimum top-token probability for XTC to fire.")
+}).describe("XTC sampler (llama.cpp only).");
+var SamplingBlockSchema = z10.object({
+  temperature: z10.number().min(0).max(2).optional().describe("Sampling temperature. 0 = greedy. Most reasoning models want 0.6\u20131.0."),
+  topP: z10.number().min(0).max(1).optional().describe("Nucleus sampling. 0.95 is the common default for Qwen, Gemma, Nemotron."),
+  topK: z10.number().int().min(0).max(1e3).optional().describe("Top-k cutoff. 20 for Qwen think, 64 for Gemma, 1 for greedy-on-instruct."),
+  minP: z10.number().min(0).max(1).optional().describe("Min-p cutoff (llama.cpp / MLX / Ollama). Qwen recommends 0."),
+  maxTokens: z10.number().int().positive().optional().describe("Per-turn output token cap. Maps to num_predict / max_tokens / n_predict."),
+  seed: z10.number().int().optional().describe("RNG seed. Unset / negative = random. Best-effort determinism on cloud."),
+  repetitionPenalty: z10.number().min(0).max(3).optional().describe("Local engines (Ollama / llama.cpp / MLX): repeat_penalty. 1.0 = off, 1.1 = mild."),
+  repetitionContext: z10.number().int().positive().optional().describe("Local engines: window size for repetition penalty (`repeat_last_n`)."),
+  frequencyPenalty: z10.number().min(-2).max(2).optional().describe("Cloud (OpenAI) and Ollama / llama.cpp: penalize repeated tokens by frequency."),
+  presencePenalty: z10.number().min(-2).max(2).optional().describe("Cloud (OpenAI) and Ollama / llama.cpp: penalize any reused token."),
+  dry: DrySamplerSchema.optional(),
+  xtc: XtcSamplerSchema.optional()
+}).describe("Sampling parameters applied per-request.");
+var ReasoningBlockSchema = z10.object({
+  effort: z10.enum(["low", "medium", "high"]).optional().describe(
+    "Cloud reasoning effort. Maps to OpenAI `reasoning.effort` and Anthropic `thinking.budget_tokens` tiers."
+  ),
+  thinkingBudget: z10.number().int().positive().optional().describe(
+    "Explicit thinking-token budget (Anthropic `thinking.budget_tokens`, Nemotron `reasoning_budget`). Wins over `effort` when both set."
+  ),
+  enableThinking: z10.boolean().optional().describe(
+    "Chat-template toggle for dual-mode models (Qwen3+, Nemotron Nano/Super). Implicit on cloud thinking models."
+  ),
+  templateKwargs: z10.record(z10.string(), z10.union([z10.string(), z10.number(), z10.boolean()])).optional().describe(
+    "Chat-template variables that drive this model's reasoning depth, forwarded verbatim as `chat_template_kwargs` on local engines. The names are the model's own \u2014 GPT-OSS reads `reasoning_effort`, Muse Glimmer reads `reasoning_strength` (low|medium|high|xhigh) \u2014 so the manifest declares them rather than the runtime guessing. Lives under `reasoning` (not `engine`) because depth is a per-request choice a tuning profile overrides: `thinking-coding` can ask for xhigh while `instruct` asks for low. Cloud providers ignore it; use `reasoning.effort` there."
+  )
+}).describe("Reasoning controls.");
+var StructuredOutputSchema = z10.object({
+  responseFormat: z10.enum(["text", "json_object"]).optional().describe("Output mode. `text` = freeform (default). `json_object` = enforce JSON."),
+  jsonSchema: z10.unknown().optional().describe("Pin output to a JSON Schema (OpenAI strict mode, llama.cpp --json-schema)."),
+  grammar: z10.string().optional().describe("llama.cpp GBNF grammar. Last-resort structured-output knob.")
+}).describe("Structured-output controls.");
+var PromptTagsSchema = z10.object({
+  enableThinkingTag: z10.string().optional().describe("User-prompt tag that enables thinking for this turn (e.g. `/think`)."),
+  disableThinkingTag: z10.string().optional().describe("User-prompt tag that disables thinking for this turn (e.g. `/no_think`).")
+}).describe("Per-turn reasoning toggle tags.");
+var LlamaCppEngineConfigSchema = z10.object({
+  nGpuLayers: z10.number().int().min(-1).optional().describe("`--n-gpu-layers` override. -1 = all. Unset = b9843 `auto`/`--fit`."),
+  cpuMoe: z10.boolean().optional().describe("`--cpu-moe`: keep ALL MoE experts in system RAM (attention/dense on GPU)."),
+  nCpuMoe: z10.number().int().min(0).optional().describe("`--n-cpu-moe N`: keep the first N layers\u2019 MoE experts in RAM. Partial split."),
+  cacheReuse: z10.number().int().min(0).optional().describe(
+    "`--cache-reuse N` prefix-KV reuse chunk. 0 = disable. Unset inherits the global default."
+  ),
+  swaFull: z10.boolean().optional().describe("`--swa-full`: full-size SWA cache (Gemma family)."),
+  flashAttn: z10.enum(["on", "off", "auto"]).optional().describe("`--flash-attn` mode override for this model."),
+  ubatchSize: z10.number().int().positive().optional().describe("`--ubatch-size` (inner microbatch) override for this model."),
+  contextSize: z10.number().int().positive().optional().describe(
+    "Per-turn context ceiling (tokens) this model launches with. Capped by GGUF train ctx."
+  ),
+  chatTemplate: z10.string().min(1).optional().describe(
+    "`--chat-template` override for GGUFs whose embedded Jinja template is incompatible with llama.cpp tool parsing."
+  ),
+  threads: z10.number().int().positive().optional().describe("`--threads` override."),
+  batchSize: z10.number().int().positive().optional().describe("`--batch-size` override."),
+  spec: z10.object({
+    type: z10.enum([
+      "none",
+      "draft-mtp",
+      "draft-eagle3",
+      "draft-dflash",
+      "draft-simple",
+      "ngram-mod",
+      "ngram-simple",
+      "ngram-map-k",
+      "ngram-map-k4v",
+      "ngram-cache"
+    ]).optional().describe("`--spec-type` speculative-decoding mode for this model."),
+    mtp: z10.boolean().optional().describe(
+      "VERIFIED capability metadata: this model\u2019s target or companion GGUF carries MTP tensors. Does not enable `draft-mtp` by itself."
+    ),
+    draftModelId: z10.string().optional().describe("Catalog id / path of the draft model for `draft-simple`."),
+    nMax: z10.number().int().positive().optional().describe("`--spec-draft-n-max`: tokens drafted per step.")
+  }).optional().describe("Speculative-decoding config for this model.")
+}).describe("Per-model llama.cpp launch-flag defaults (engine-level, applied at model load).");
+var EngineConfigSchema = z10.object({
+  llamaCpp: LlamaCppEngineConfigSchema.optional()
+}).describe("Per-model engine launch-flag defaults, keyed by engine.");
+var ChatModelTuningBaseSchema = z10.object({
+  sampling: SamplingBlockSchema.optional(),
+  samplingWhenThinking: SamplingBlockSchema.optional().describe(
+    "Sparse override of `sampling` applied when the runtime determines reasoning is engaged. Used by Qwen3+ (different sampling for /think mode) and Nemotron Nano (different sampling for thinking vs instruct)."
+  ),
+  reasoning: ReasoningBlockSchema.optional(),
+  output: StructuredOutputSchema.optional(),
+  toolChoice: z10.enum(["auto", "required", "none"]).optional().describe(
+    "Tool selection mode (cloud + llama.cpp + MLX). `auto` lets the model decide; `required` forces a tool call this turn; `none` disables tools."
+  ),
+  promptTags: PromptTagsSchema.optional()
+}).describe("Per-model sampling, reasoning, and output defaults (without profiles).");
+var ChatModelTuningSchema = ChatModelTuningBaseSchema.extend({
+  engine: EngineConfigSchema.optional().describe(
+    "Per-model ENGINE launch-flag defaults (llama.cpp `--n-gpu-layers`, `--cpu-moe`, `--spec-type`, \u2026). Applied once at model load, not per request \u2014 so it lives on the top-level tuning object, not inside per-request `profiles`."
+  ),
+  profiles: z10.record(TuningProfileIdSchema, ChatModelTuningBaseSchema.partial()).optional().describe(
+    "Named tuning presets this model implements. Gezel frontmatter `tuningProfile` selects one; the resolver applies the profile as a layer between installDefault and catalog base. Missing requested profiles walk the canonical fallback chain."
+  )
+}).describe("Per-model sampling, reasoning, and output defaults.");
+
+// src/schemas/question.ts
+import { z as z11 } from "zod";
+var NpmInstallApprovalDecisionSchema = z11.object({
+  package: z11.string(),
+  version: z11.string(),
+  decision: z11.enum(["install", "always", "decline"])
+});
+var QuestionAnswerSchema = z11.object({
+  /** Indices into `choices` the user picked. Empty when only write-in. */
+  selectedChoices: z11.array(z11.number().int().min(0)).optional(),
+  /** Free-text the user typed. Empty when they only clicked choices. */
+  writeIn: z11.string().optional(),
+  /**
+   * Set when the user explicitly dismissed BUT wants the gezel to
+   * proceed anyway with sensible defaults. Triggers a synthetic
+   * follow-up turn with a `[The user wants you to proceed…]` seed
+   * so the gezel knows to make decisions on the user's behalf.
+   * UI label: "Just do whatever".
+   */
+  declined: z11.boolean().optional(),
+  /**
+   * Set when the user just wants the question to go away — no
+   * follow-up turn, no work done, nothing for the gezel to act on.
+   * The card collapses and the gezel's session is left as-is (its
+   * turn already ended when it called `ask_user_question`). Distinct
+   * from `declined` so the model never sees a "user wants defaults"
+   * signal that the user didn't intend. UI label: "Skip".
+   */
+  silentSkip: z11.boolean().optional(),
+  /**
+   * Per-package decisions for `npm-install-approval` questions. When
+   * set, the answer handler installs / always-allows / declines each
+   * package and emits a single follow-up summary into the session.
+   */
+  npmInstallDecisions: z11.array(NpmInstallApprovalDecisionSchema).optional(),
+  at: z11.string()
+});
+var NpmInstallApprovalPackageSchema = z11.object({
+  package: z11.string(),
+  version: z11.string()
+});
+var CommandApprovalScopeSchema = z11.enum(["script", "npx"]);
+var CommandApprovalIntentSchema = z11.object({
+  kind: z11.literal("command-approval"),
+  scope: CommandApprovalScopeSchema,
+  name: z11.string().min(1),
+  body: z11.string().optional(),
+  args: z11.array(z11.string()).optional()
+});
+var ToolPermissionIntentSchema = z11.object({
+  kind: z11.literal("tool-permission"),
+  toolName: z11.string(),
+  toolInput: z11.record(z11.string(), z11.unknown())
+});
+var ToolsetInstallApprovalIntentSchema = z11.object({
+  kind: z11.literal("toolset-install-approval"),
+  toolsetId: z11.string(),
+  sourceId: z11.string(),
+  version: z11.string(),
+  targetProjectId: z11.string(),
+  craftbookId: z11.string()
+});
+var ImageGenerationApprovalIntentSchema = z11.object({
+  kind: z11.literal("image-generation-approval"),
+  provider: z11.string(),
+  model: z11.string(),
+  /** Truncated prompt the model is about to send. Surfaced verbatim. */
+  promptPreview: z11.string(),
+  /** Resolved generation size, e.g. '2K 16:9' or '1024x1024'. Optional. */
+  estimatedSize: z11.string().optional()
+});
+var VideoGenerationApprovalIntentSchema = z11.object({
+  kind: z11.literal("video-generation-approval"),
+  provider: z11.string(),
+  model: z11.string(),
+  promptPreview: z11.string(),
+  /** Resolved clip shape, e.g. '704×480 · 97f · 24fps'. Optional. */
+  estimatedSize: z11.string().optional()
+});
+var ScheduleApprovalIntentSchema = z11.object({
+  kind: z11.literal("schedule-approval"),
+  typeId: z11.string(),
+  craftbookId: z11.string(),
+  /**
+   * Recurrence flavor. Absent → 'scheduled' (every question written
+   * before this field existed is a cron schedule). 'night-shift' hosts
+   * run inside the Night Shift window instead of on a user-visible cron;
+   * the card copy switches accordingly.
+   */
+  runMode: z11.enum(["scheduled", "night-shift"]).optional(),
+  /**
+   * 5-field cron expression (UTC). Surfaced verbatim on the card for
+   * 'scheduled' hosts; for 'night-shift' hosts it is the internal
+   * heartbeat and the card shows the window instead.
+   */
+  cron: z11.string(),
+  overlap: z11.enum(["skip", "queue", "concurrent"]).optional()
+});
+var NightShiftReviewIntentSchema = z11.object({
+  kind: z11.literal("night-shift-review"),
+  /** The window's day key (see `nightShiftWindowKey`). */
+  windowKey: z11.string(),
+  tasksCompleted: z11.number(),
+  reports: z11.array(
+    z11.object({
+      projectId: z11.string(),
+      path: z11.string(),
+      title: z11.string().optional(),
+      actionCount: z11.number()
+    })
+  )
+});
+var TaskPausedReasonSchema = z11.enum([
+  "gate_exhausted",
+  "gate_plateau",
+  "gate_unsatisfiable",
+  "gate_infrastructure",
+  "step_stalled",
+  "budget_exhausted"
+]);
+var TaskPausedIntentSchema = z11.object({
+  kind: z11.literal("task-paused"),
+  /** `projectId/num` of the paused task — the dedup key. */
+  taskRef: z11.string(),
+  stepId: z11.string().optional(),
+  reason: TaskPausedReasonSchema
+});
+var QuestionIntentSchema = z11.discriminatedUnion("kind", [
+  z11.object({
+    kind: z11.literal("npm-install-approval"),
+    /**
+     * Packages that need approval. Always at least one; multiple when
+     * the gezel batched an install call (encouraged) or when we merged
+     * a later request into the same pending question for dedup.
+     */
+    packages: z11.array(NpmInstallApprovalPackageSchema).min(1)
+  }),
+  CommandApprovalIntentSchema,
+  ToolPermissionIntentSchema,
+  ToolsetInstallApprovalIntentSchema,
+  ImageGenerationApprovalIntentSchema,
+  VideoGenerationApprovalIntentSchema,
+  ScheduleApprovalIntentSchema,
+  NightShiftReviewIntentSchema,
+  TaskPausedIntentSchema
+]);
+var QuestionSchema = z11.object({
+  id: z11.string(),
+  projectId: z11.string(),
+  gezelId: z11.string(),
+  sessionId: z11.string(),
+  /** Body of the question — supports markdown. */
+  prompt: z11.string().min(1),
+  /** Optional preset choices. Empty / omitted => write-in only. */
+  choices: z11.array(z11.string()).max(20).optional(),
+  /** Whether the user can also type a write-in alongside choices. Default true. */
+  allowWriteIn: z11.boolean().optional(),
+  /** Whether multiple choices may be selected. Default false. */
+  multiSelect: z11.boolean().optional(),
+  /**
+   * Approval-flow attachment: a task this question is *about*. Stored in
+   * `projectId/num` form so existing parsing helpers work. The UI shows
+   * the task title + status above the prompt and offers an "Open task"
+   * link.
+   */
+  taskRef: z11.string().optional(),
+  /**
+   * Approval-flow attachment: a document this question is *about*.
+   * Project-relative path when `projectId` is set, otherwise into the
+   * global `~/.gezel/documents/` library. The UI renders a collapsed
+   * preview + "Open document" link.
+   */
+  documentPath: z11.string().optional(),
+  /**
+   * Service-created specialized-question marker (see `QuestionIntent`
+   * for context). Absent for plain user-facing questions asked via
+   * the `ask_user_question` MCP tool.
+   */
+  intent: QuestionIntentSchema.optional(),
+  createdAt: z11.string(),
+  /** Set once the user has answered (or declined). */
+  answer: QuestionAnswerSchema.optional()
+});
+
+// src/schemas/recognition.ts
+import { z as z12 } from "zod";
+var ImageExifSchema = z12.object({
+  make: z12.string().optional(),
+  model: z12.string().optional(),
+  lensModel: z12.string().optional(),
+  dateTimeOriginal: z12.string().optional(),
+  orientation: z12.number().int().min(1).max(8).optional(),
+  software: z12.string().optional(),
+  imageDescription: z12.string().optional()
+});
+var ImageStaticMetaSchema = z12.object({
+  format: z12.enum(["png", "jpeg", "gif", "webp", "svg", "unknown"]),
+  width: z12.number().int().positive().optional(),
+  height: z12.number().int().positive().optional(),
+  byteLength: z12.number().int().nonnegative(),
+  sha256: z12.string().regex(/^[a-f0-9]{64}$/),
+  /**
+   * PNG `tEXt`/`iTXt`/`zTXt` keyword→value pairs. Generation provenance lives
+   * here (A1111 writes `parameters`, ComfyUI writes `prompt`/`workflow`) and
+   * screenshot tools stamp `Software`.
+   *
+   * Attacker-controlled: anyone can author a PNG whose `Description` chunk
+   * reads "Ignore previous instructions". Renderers MUST fence and cap this.
+   */
+  pngText: z12.record(z12.string(), z12.string()).optional(),
+  exif: ImageExifSchema.optional(),
+  /** Withheld from every prompt. See the schema doc above. */
+  gps: z12.object({ lat: z12.number(), lon: z12.number() }).optional(),
+  /** True when the file carried location data we deliberately dropped. */
+  gpsRedacted: z12.boolean().optional(),
+  /**
+   * Heuristic from dimensions, format, and metadata — drives `auto` mode
+   * selection without paying a classifier call.
+   */
+  likelyScreenshot: z12.boolean().optional()
+});
+var RecognitionModeSchema = z12.enum(["describe", "ocr", "ui", "extract"]);
+var RecognitionModeRequestSchema = z12.enum(["auto", "describe", "ocr", "ui", "extract"]);
+var ImageRecognitionSchema = z12.object({
+  schemaVersion: z12.literal(1),
+  sha256: z12.string().regex(/^[a-f0-9]{64}$/),
+  meta: ImageStaticMetaSchema,
+  modes: z12.array(RecognitionModeSchema).min(1),
+  description: z12.string().optional(),
+  ocrText: z12.string().optional(),
+  structured: z12.object({
+    templateId: z12.string().optional(),
+    data: z12.unknown()
+  }).optional(),
+  engine: z12.enum(["llama-cpp", "mlx", "mock", "none"]),
+  modelId: z12.string(),
+  status: z12.enum(["ok", "partial", "failed", "static-only"]),
+  failureReason: z12.string().optional(),
+  durationMs: z12.number().int().nonnegative(),
+  at: z12.string()
+});
+var MessageImageDigestSchema = z12.object({
+  /** The markdown ref exactly as it appears in the message body. */
+  ref: z12.string(),
+  sha256: z12.string().regex(/^[a-f0-9]{64}$/),
+  /** Pre-rendered, already capped and fenced-safe. */
+  digest: z12.string(),
+  modelId: z12.string(),
+  modes: z12.array(RecognitionModeSchema),
+  status: z12.enum(["ok", "partial", "failed", "static-only"]),
+  at: z12.string()
+});
+var RecognitionRequestSchema = z12.object({
+  /** Project-relative artifact path, e.g. `attachments/<uuid>.png`. */
+  artifactPath: z12.string().min(1).optional(),
+  data: z12.string().min(1).optional(),
+  mimeType: z12.string().optional(),
+  mode: RecognitionModeRequestSchema.default("auto"),
+  /** JSON Schema for `extract` mode — fed to llama-server `response_format`. */
+  schema: z12.unknown().optional(),
+  /** Overrides the configured recognition model for this call. */
+  model: z12.string().optional()
+});
+var RecognitionHealthSchema = z12.object({
+  state: z12.enum(["ok", "no-model", "not-configured", "error"]),
+  modelId: z12.string().optional(),
+  detail: z12.string().optional()
+});
+var RecognitionPullEventSchema = z12.union([
+  z12.object({
+    type: z12.literal("progress"),
+    bytesWritten: z12.number().int().nonnegative(),
+    totalBytes: z12.number().int().nonnegative().optional()
+  }),
+  z12.object({ type: z12.literal("error"), error: z12.string() }),
+  z12.object({ type: z12.literal("done"), id: z12.string() })
+]);
+var RecognitionCatalogEntrySchema = z12.object({
+  id: z12.string(),
+  name: z12.string(),
+  description: z12.string(),
+  license: z12.string(),
+  approxSizeBytes: z12.number().int().nonnegative(),
+  recoScore: z12.number()
+});
+var ListRecognitionCatalogResponseSchema = z12.object({
+  models: z12.array(RecognitionCatalogEntrySchema)
+});
+var InstalledRecognitionModelSchema = z12.object({
+  id: z12.string(),
+  name: z12.string(),
+  approxSizeBytes: z12.number().int().nonnegative(),
+  installedAt: z12.string(),
+  weightsPath: z12.string().optional(),
+  mmprojPath: z12.string().optional()
+});
+var ListInstalledRecognitionModelsResponseSchema = z12.object({
+  models: z12.array(InstalledRecognitionModelSchema)
+});
+
+// src/schemas/session-telemetry.ts
+import { z as z13 } from "zod";
+var SessionGpuTaskSchema = z13.enum([
+  "image_generation",
+  "video_generation",
+  "image_recognition"
+]);
+var SessionTurnTelemetrySchema = z13.object({
+  /** Epoch ms when the in-flight turn started. */
+  startedAt: z13.number(),
+  streamedContentChars: z13.number().int().nonnegative(),
+  toolCalls: z13.number().int().nonnegative(),
+  fileMutations: z13.number().int().nonnegative()
+});
+var SessionTelemetrySchema = z13.object({
+  sessionId: z13.string(),
+  gezelId: z13.string(),
+  projectId: z13.string(),
+  /** True while a send is currently running for this session. */
+  inflight: z13.boolean(),
+  turnsStarted: z13.number().int().nonnegative(),
+  deltaChunks: z13.number().int().nonnegative(),
+  streamedContentChars: z13.number().int().nonnegative(),
+  wirePulses: z13.number().int().nonnegative(),
+  heartbeats: z13.number().int().nonnegative(),
+  enginePhaseEvents: z13.number().int().nonnegative(),
+  /**
+   * `engine_phase === 'generating'` transitions — roughly one per completion
+   * request the engine served (the slot-launch granularity stall logic and
+   * the eval chatter threshold were calibrated against).
+   */
+  generationSpurts: z13.number().int().nonnegative(),
+  toolCalls: z13.number().int().nonnegative(),
+  toolArgChars: z13.number().int().nonnegative(),
+  fileMutations: z13.number().int().nonnegative(),
+  gpuEvents: z13.number().int().nonnegative(),
+  gpuTaskActive: SessionGpuTaskSchema.nullable(),
+  /** Epoch ms of the last streamed signal (delta / pulse / heartbeat / phase). */
+  lastStreamActivityAt: z13.number().nullable(),
+  lastToolActivityAt: z13.number().nullable(),
+  lastMutationAt: z13.number().nullable(),
+  lastGpuActivityAt: z13.number().nullable(),
+  /** Max of all activity timestamps — "when did ANY progress signal last fire". */
+  lastProgressAt: z13.number().nullable(),
+  /** Counters scoped to the currently-running turn; null between turns. */
+  currentTurn: SessionTurnTelemetrySchema.nullable()
+});
+var SessionTelemetryListResponseSchema = z13.object({
+  /** Bumped when counter semantics change; consumers gate on it. */
+  version: z13.literal(1),
+  capturedAt: z13.number(),
+  sessions: z13.array(SessionTelemetrySchema)
+});
+
+// src/schemas/gezel.ts
+var ProviderNameSchema = z14.enum([
+  "copilot",
+  "openai",
+  "anthropic",
+  "anthropic-cli",
+  "codex-cli",
+  "ollama",
+  "llama-cpp",
+  "mlx",
+  // DwarfStar/ds4 — antirez's DeepSeek-V4-specific engine. Like llama-cpp/mlx
+  // it serves an OpenAI-compatible HTTP API from a supervised native binary,
+  // but it only loads antirez's DeepSeek-V4 GGUFs and streams MoE experts from
+  // SSD so a 284B model fits a 64GB Mac. GPU-only (Metal/CUDA); see the ds4
+  // provider for the availability gating.
+  "ds4",
+  // Inference hosted on another paired gezel daemon ("remote models"). A
+  // single enum arm fronts a family of paired servers; the specific server is
+  // selected by the namespaced model id `remote:<remoteId>/<bLocalId>`. Like
+  // the cloud providers, the turn loop + tools run locally — only the model
+  // forward-pass is remoted — so `remote` is NOT a local provider.
+  "remote"
+]);
+var GezelGenderSchema = z14.enum(["male", "female", "non-binary"]);
+var FixedFunctionConfigSchema = z14.object({
+  /** MCP tool name to forward to (e.g. `'generate_image'`). */
+  tool: z14.string().min(1),
+  /** Argument key on the tool that receives the user's message text. */
+  promptKey: z14.string().min(1).default("prompt"),
+  /** Defaults merged into every call; user text on `promptKey` always wins. */
+  defaults: z14.record(z14.string(), z14.unknown()).optional()
+});
+var GezelTraitSchema = z14.object({
+  id: z14.string(),
+  /** One imperative second-person sentence, rendered as a prompt bullet. */
+  text: z14.string().min(1).max(200),
+  adoptedAt: z14.string(),
+  source: z14.enum(["levelup", "manual"]).optional()
+});
+var GezelFrontmatterSchema = z14.object({
+  id: z14.string().optional(),
+  name: z14.string(),
+  description: z14.string().optional(),
+  role: z14.string().optional(),
+  /**
+   * Kebab-case slug derived from `role` (or `gezel-N` when role is absent),
+   * globally unique across the install. Collisions get `-2`, `-3`, …
+   * suffixes. Backfilled at startup for legacy gezels. Used as a secondary
+   * identifier for @-mentions and as the sole rendered identifier when
+   * `config.roleBasedNameOnlyMode` is enabled.
+   */
+  roleBasedName: z14.string().optional(),
+  /**
+   * One of `male` / `female` / `non-binary`. Assigned at creation time
+   * from the matching gendered first-name pool (with a small chance of
+   * non-binary regardless of name). Drives pronouns in UI copy and in prompt
+   * references made by other gezels. It is not rendered into this gezel's
+   * own prompt. Absent on legacy gezels, where references omit pronouns.
+   */
+  gender: GezelGenderSchema.optional(),
+  model: z14.string().optional(),
+  provider: ProviderNameSchema.optional(),
+  reasoningEffort: z14.string().optional(),
+  /**
+   * Per-gezel sampling / reasoning / structured-output / tool-call overrides.
+   * Sparse — only set fields override the catalog's recommended defaults.
+   * Resolution order is gezel `tuning` > installDefault > selected
+   * `tuningProfile` > catalog identity `tuning` > provider fallback. See
+   * {@link ChatModelTuningSchema} for the full field list and dual-mode
+   * (`samplingWhenThinking`) semantics.
+   */
+  tuning: ChatModelTuningSchema.optional(),
+  /**
+   * Named tuning preset this gezel uses against the active model. Models
+   * declare which presets they implement under `tuning.profiles` in the
+   * catalog manifest (e.g. `thinking-coding`, `thinking-general`, `instruct`,
+   * `creative`). At request time the resolver applies the named profile as
+   * a layer between `installDefault` and the model's base tuning; the
+   * gezel's explicit `tuning` overrides still win per-leaf. Missing profiles
+   * walk a canonical fallback chain (`thinking-coding → thinking-general →
+   * instruct`). See `tuning-profile-registry.ts` for the canonical set.
+   */
+  tuningProfile: TuningProfileIdSchema.optional(),
+  /**
+   * Role/template-**suggested** tuning profile. Unlike `tuningProfile`
+   * (an explicit per-gezel user pick that overrides the install preset),
+   * this is a soft default a gilde template declares for its role. In the
+   * resolution stack it sits BELOW both the per-gezel pick and the
+   * install-wide preset, and ABOVE the app-wide fallback
+   * (`thinking-general`): a gezel uses its role's suggestion unless the
+   * user has explicitly chosen a profile (per-gezel or install preset).
+   * Lets coordinator roles (meester / voorman / planner) default to a
+   * low-temperature `thinking-precise` without locking the user out.
+   */
+  suggestedTuningProfile: TuningProfileIdSchema.optional(),
+  tools: z14.array(z14.string()).optional(),
+  tags: z14.array(z14.string()).optional(),
+  /**
+   * When set, switches this gezel into "fixed-function" mode: chat
+   * messages bypass the LLM and forward to the named MCP tool. See
+   * {@link FixedFunctionConfigSchema}. The LLM-config fields above
+   * (`model`, `provider`, etc.) are ignored for fixed-function gezels
+   * and `about.md` is not used / not written.
+   */
+  fixedFunction: FixedFunctionConfigSchema.optional(),
+  /** Ollama-only: override the context window (tokens) for this gezel. */
+  numCtx: z14.number().int().positive().optional(),
+  /** When false, suppresses auto-recall on session start for this gezel. */
+  autoRecall: z14.boolean().optional(),
+  /**
+   * Chat bubble font id (one of `GEZEL_CHAT_FONTS[*].id`). When unset or
+   * unrecognized, chat bubbles inherit the app default (Hanken Grotesk).
+   */
+  font: z14.string().optional(),
+  /**
+   * Kokoro TTS voice id (one of `KOKORO_VOICES[*].id`, e.g. `af_heart`,
+   * `bm_george`). Drives spoken audio rendering — `synthesize_speech`
+   * defaults to this voice for the gezel. Assigned at creation time
+   * from the gender-matched pool; users can override in the edit
+   * dialog. Absent on legacy gezels — synthesize falls back to the
+   * default voice (`af_heart`) when missing.
+   */
+  voice: z14.string().optional(),
+  /**
+   * Provenance: the id of the gilde catalog template this gezel was
+   * created from, if any. Written by exact-template or about-omitted
+   * `create_gezel`, `ensure_gezel`'s template path, and the catalog route.
+   * Absent on bespoke-generated or hand-authored gezels. The UI uses
+   * this to offer "reset to original template" on the about editor.
+   */
+  templateId: z14.string().optional(),
+  /**
+   * Provenance: the semver of the template version installed at create
+   * time. Paired with `templateId`. Absent on gezels created before this
+   * field existed — the "refresh template" UI treats absent as "unknown
+   * source version" and offers a refresh to current latest without
+   * comparing.
+   */
+  templateVersion: z14.string().optional(),
+  /**
+   * Copilot-only: when true, deny the Copilot CLI's built-in tools
+   * (bash, web_fetch, view, str_replace_editor, read_file, write_file,
+   * grep, etc.) and force the model to work through our MCP tools. When
+   * Unset inherits the install-level `GezelConfig.sandboxCopilot`, which
+   * itself defaults to the sandboxed MCP surface.
+   * Provider other than copilot: ignored.
+   */
+  sandboxCopilot: z14.boolean().optional(),
+  /**
+   * `anthropic-cli`-only: per-gezel override for the Claude CLI permission
+   * mode. Forwarded as `--permission-mode <value>` to each `claude` invocation.
+   *   - `default`: prompt-aware mode the CLI uses outside scripted contexts.
+   *   - `acceptEdits`: auto-approve file edits; Bash + other side-effecting
+   *     tools still gate. Sensible default for a chat-driven gezel.
+   *   - `plan`: read-only — useful for review-style gezels.
+   *   - `bypassPermissions`: yolo — every tool call auto-approved including
+   *     Bash. Reserve for builder gezels you trust to run shell commands.
+   * When unset, inherits `config.anthropicCli.defaultPermissionMode` (which
+   * itself defaults to `acceptEdits`). Other providers: ignored.
+   */
+  claudePermissionMode: z14.enum(["default", "acceptEdits", "plan", "bypassPermissions"]).optional(),
+  /**
+   * `codex-cli`-only execution posture. New writes use Plan / Edit /
+   * Reviewed / Full; legacy Codex values remain readable for compatibility.
+   * When unset, the project override and then install default apply.
+   */
+  codexPermissionMode: CodexPermissionModeCompatSchema.optional(),
+  /**
+   * When true and the gezel has a custom `icon.svg`, the UI renders that
+   * abstract sigil instead of the parametric poppetje. Default (absent /
+   * false) renders the poppetje everywhere. Toggled from Gezel Detail.
+   */
+  iconOverride: z14.boolean().optional(),
+  /**
+   * Standing behavior traits, adopted through the growth system (or
+   * hand-authored). Rendered as their own `### Traits` block in the
+   * stable system-prompt prefix right after the about body. Capped at 8
+   * visible slots; fully revertible (the user can retire any trait).
+   * The frontmatter list is AUTHORITATIVE for what's active — growth.json
+   * keeps the evidence-bearing adoption log.
+   */
+  traits: z14.array(GezelTraitSchema).max(8).optional(),
+  /**
+   * Overrides `config.recognition.mode` for this gezel. A gezel whose job is
+   * reading screenshots sets `always`; everyone else inherits.
+   *
+   * Deliberately a single enum rather than a mirror of the config object —
+   * frontmatter is user-edited YAML, and a nested policy struct there is a
+   * support burden. Native vision is a property of the model *install*, not of
+   * the gezel, so it has no frontmatter counterpart.
+   */
+  recognition: z14.enum(["auto", "always", "off"]).optional()
+});
+var GezelSectionSchema = z14.object({
+  heading: z14.string(),
+  template: z14.string().optional(),
+  params: z14.record(z14.string(), z14.string()).optional(),
+  body: z14.string()
+});
+var ParsedGezelSchema = z14.object({
+  frontmatter: GezelFrontmatterSchema,
+  sections: z14.array(GezelSectionSchema),
+  source: z14.string()
+});
+var GezelSummarySchema = z14.object({
+  id: z14.string(),
+  name: z14.string(),
+  description: z14.string().optional(),
+  role: z14.string().optional(),
+  /** Mirrors `GezelFrontmatter.roleBasedName`. */
+  roleBasedName: z14.string().optional(),
+  /** Mirrors `GezelFrontmatter.gender`. */
+  gender: GezelGenderSchema.optional(),
+  model: z14.string().optional(),
+  provider: ProviderNameSchema.optional(),
+  reasoningEffort: z14.string().optional(),
+  /** Mirrors `GezelFrontmatter.tuningProfile`. */
+  tuningProfile: TuningProfileIdSchema.optional(),
+  /** Mirrors `GezelFrontmatter.suggestedTuningProfile`. */
+  suggestedTuningProfile: TuningProfileIdSchema.optional(),
+  numCtx: z14.number().int().positive().optional(),
+  autoRecall: z14.boolean().optional(),
+  font: z14.string().optional(),
+  /** Mirrors `GezelFrontmatter.voice` — Kokoro TTS voice id. */
+  voice: z14.string().optional(),
+  /** Mirrors `GezelFrontmatter.templateId` when the gezel came from a gilde template. */
+  templateId: z14.string().optional(),
+  /** Mirrors `GezelFrontmatter.templateVersion`. */
+  templateVersion: z14.string().optional(),
+  /** Mirrors `GezelFrontmatter.sandboxCopilot`. */
+  sandboxCopilot: z14.boolean().optional(),
+  /** Mirrors `GezelFrontmatter.claudePermissionMode`. */
+  claudePermissionMode: z14.enum(["default", "acceptEdits", "plan", "bypassPermissions"]).optional(),
+  /** Mirrors `GezelFrontmatter.codexPermissionMode`. */
+  codexPermissionMode: CodexPermissionModeCompatSchema.optional(),
+  /**
+   * Mirrors `GezelFrontmatter.fixedFunction`. Present means this gezel
+   * skips the LLM and forwards messages to an MCP tool. The UI uses
+   * its presence to render a sidebar badge, hide LLM controls in the
+   * edit dialog, and replace the about pane with a "Forwards to: …"
+   * affordance.
+   */
+  fixedFunction: FixedFunctionConfigSchema.optional(),
+  icon: z14.string().optional(),
+  /**
+   * The resolved poppetje character data for this gezel. Inlined on
+   * every list/detail response so the UI can render the parametric SVG
+   * figure without a follow-up round-trip. Generated from the gezel id
+   * on first read; persisted thereafter (so re-rolling the catalog
+   * later doesn't drift existing characters).
+   */
+  poppetje: PoppetjeSchema.optional(),
+  /** Mirrors `GezelFrontmatter.iconOverride`. */
+  iconOverride: z14.boolean().optional(),
+  /** Mirrors `GezelFrontmatter.recognition`. */
+  recognition: z14.enum(["auto", "always", "off"]).optional(),
+  /**
+   * Where this gezel lives. `global` (the default when absent — back-compat
+   * with every gezel on disk before this field existed) is the install-wide
+   * roster under `~/.gezel/gezels/`. `project` is a project-local gezel
+   * defined in a workspace `.gezel/` folder — its id is the encoded
+   * `proj__<projectId>__<localId>` form (see `encodeProjectGezelId`). The UI
+   * badges project-scoped gezels and the roster only surfaces them inside
+   * their own project.
+   */
+  scope: z14.enum(["global", "project"]).optional(),
+  /**
+   * Filesystem ownership boundary, distinct from `scope` above. Shared gezel
+   * identity lives in the installer-managed machine root; chats, memories,
+   * growth, credentials, and installed toolsets remain in the user home.
+   */
+  storageScope: z14.enum(["user", "machine-shared"]).optional(),
+  /** Mirrors `GezelFrontmatter.traits`. */
+  traits: z14.array(GezelTraitSchema).optional(),
+  /**
+   * Lightweight growth summary (level + pending level-up flag),
+   * hydrated from growth.json and inlined on list/detail responses —
+   * like `poppetje` — so the roster badge and Growth-tab dot render
+   * without N+1 follow-up requests.
+   */
+  growth: GezelGrowthSummarySchema.optional(),
+  updatedAt: z14.string()
+});
+var GezelDetailSchema = GezelSummarySchema.extend({
+  parsed: ParsedGezelSchema,
+  about: z14.string(),
+  /**
+   * Optional contents of the per-gezel `tools.md` file. When present
+   * (non-null), fully replaces the auto-injected `## Tools available
+   * this turn` block in the system prompt. Power-user opt-in: the
+   * gezel's owner accepts responsibility for keeping the listing
+   * accurate as the install's registered tools evolve. `null` (the
+   * default) means no override file exists and the runtime renders
+   * the auto-block from the live MCP bridge.
+   */
+  toolsMd: z14.string().nullable().default(null)
+});
+var ToolCallImageSchema = z14.object({
+  /** Path relative to the project's artifacts/ root (e.g. `sessions/2026-04-19_143015_snake-test/tool-3-img-0.png`). */
+  path: z14.string(),
+  /** MIME type of the image, used by the UI to set the right `<img>` src URL. */
+  mimeType: z14.string()
+});
+var ToolCallAudioSchema = z14.object({
+  /** Path relative to the project's artifacts/ root. */
+  path: z14.string(),
+  /** MIME type, e.g. `audio/wav`. */
+  mimeType: z14.string(),
+  /** Duration in seconds when known — used by the UI to show length without preloading the blob. */
+  durationSeconds: z14.number().optional(),
+  /** Voice id used to produce this audio (TTS only). */
+  voice: z14.string().optional()
+});
+var ToolCallVideoSchema = z14.object({
+  /** Path relative to the project's artifacts/ root (e.g. `generated/video-123.mp4`). */
+  path: z14.string(),
+  /** MIME type, e.g. `video/mp4`. */
+  mimeType: z14.string(),
+  /** Optional poster-frame artifact path for the `<video poster>` attribute. */
+  posterPath: z14.string().optional()
+});
+var ChatMessageToolCallSchema = z14.object({
+  name: z14.string(),
+  durationMs: z14.number(),
+  success: z14.boolean(),
+  errorMessage: z14.string().optional(),
+  /** File path the tool touched, for the References pane. */
+  path: z14.string().optional(),
+  /** Ordered file paths touched by a batched filesystem tool. */
+  paths: z14.array(z14.string()).optional(),
+  /** Compact, human-readable one-liner ("→ Freja: update the game loop · file: workspace/index.html"). */
+  argsSummary: z14.string().optional(),
+  /**
+   * The tool call's FULL arguments, rendered as readable text (field by
+   * field, bulky values shown in full — not truncated like
+   * `argsSummary`). Surfaced in the UI behind an expand + copy so a user
+   * can verify exactly what a handoff/edit actually sent without digging
+   * through the debug log. Capped (~100 KB) server-side; longer blobs get
+   * a truncation marker. Same exposure stance as `argsSummary` — MCP tool
+   * arguments are not a secret vector in this codebase (secrets live in
+   * the toolset-config path), so this is not separately redacted.
+   */
+  argsFull: z14.string().optional(),
+  /** Short full response, or a bounded beginning/end summary for a long response. */
+  resultText: z14.string().optional(),
+  /** True when `resultText` is a bounded summary rather than the complete response. */
+  resultTruncated: z14.boolean().optional(),
+  /** Image artifacts the tool returned (e.g. browser_snapshot screenshots). */
+  images: z14.array(ToolCallImageSchema).optional(),
+  /** Audio artifacts the tool returned (e.g. synthesize_speech WAV). */
+  audios: z14.array(ToolCallAudioSchema).optional(),
+  /** Video artifacts the tool returned (e.g. generate_video mp4). */
+  videos: z14.array(ToolCallVideoSchema).optional(),
+  /**
+   * Unified diff describing the change a surgical-edit tool made
+   * (`replace_in_file`, `apply_patch`, `insert_at_marker`). Used by the UI
+   * to render an inline diff under the tool-call row. Capped at ~100KB
+   * server-side; larger diffs are truncated with a marker line.
+   */
+  diff: z14.string().optional(),
+  addedLines: z14.number().int().nonnegative().optional(),
+  removedLines: z14.number().int().nonnegative().optional()
+});
+var ChatMessageSchema = z14.object({
+  role: z14.enum(["user", "assistant"]),
+  content: z14.string(),
+  at: z14.string(),
+  from: z14.object({
+    gezelId: z14.string(),
+    gezelName: z14.string()
+  }).optional(),
+  /**
+   * Artifact paths (relative to the project's `artifacts/` directory)
+   * the assistant reply referenced in its body text. Populated on save
+   * by the server-side reference parser, and used by the chat UI to
+   * render a chip row under the bubble and to linkify inline code spans
+   * that match a real artifact. Back-stops Copilot's tool-call
+   * blindspot and any "AI wrote a file outside the MCP tools" paths.
+   */
+  referencedArtifacts: z14.array(z14.string()).optional(),
+  /**
+   * Task refs (`<projectId>/<num>`) the assistant reply mentioned. Same
+   * shape as `referencedArtifacts` — populated on save, gated on the
+   * ref actually existing in the task store, surfaced in the chat
+   * bubble as click-through chips. Catches the common "I created task
+   * gezel-ux-roadmap/2" mention so the user can jump to it without
+   * scrolling the body for the ref.
+   */
+  referencedTasks: z14.array(z14.string()).optional(),
+  /**
+   * Tool calls the assistant fired during this turn. Populated on the
+   * final assistant message; the UI renders them as a collapsible
+   * "thinking" expando above the reply body so the user can still see
+   * what ran even after the live stream has closed.
+   */
+  toolCalls: z14.array(ChatMessageToolCallSchema).optional(),
+  /**
+   * Phase announcements the model emitted via Copilot's `report_intent`
+   * tool during this turn. Each entry carries the intent label and an
+   * `afterChars` offset into `content` marking where (in the final
+   * reply) the intent fired. The UI splices them back in as horizontal
+   * dividers at those offsets so long multi-phase turns are visually
+   * segmented. `content` itself stays free of intent text — model
+   * replay and history export are unaffected. Copilot-only; other
+   * providers don't emit these.
+   */
+  intents: z14.array(
+    z14.object({
+      label: z14.string(),
+      afterChars: z14.number().int().min(0)
+    })
+  ).optional(),
+  /**
+   * Set when the assistant turn invoked `ask_user_question`. Lets the
+   * chat UI correlate the question card with the exact bubble that
+   * asked it, mirroring how `toolCalls` is captured. The Question
+   * itself lives in the per-project questions file; this id is just
+   * the foreign key.
+   */
+  pendingQuestionId: z14.string().optional(),
+  /**
+   * Marks the message as a system-generated synthesis rather than a real
+   * model turn.
+   *
+   * - `'compaction-summary'` — emitted by the in-flight compaction path
+   *   that replaces older messages with a single synthesized "[Earlier
+   *   in this conversation: …]" assistant message to keep the prompt
+   *   under Ollama's context window.
+   * - `'context-loop-halt'` — runtime ended a runaway tool-loop turn
+   *   gracefully and recorded a placeholder so the loop wouldn't keep
+   *   re-entering.
+   * - `'turn-aborted'` — provider threw mid-turn (repeat-tracker,
+   *   failure-tracker, or any other unhandled error). Without this
+   *   record the drained tool calls and the abort warning would only
+   *   live in the client-side streaming slot — refreshing or copying a
+   *   debug bundle would lose them. Content is whatever streamed
+   *   (often empty); the abort message lives in `warnings`.
+   * - `'growth-announcement'` — deterministic level-up announcement the
+   *   growth engine appends to the gezel's most recent session ("I just
+   *   reached level N…"). First-person and factually true, but not a
+   *   real model turn.
+   * - `'keurmeester-notice'` — the Keurmeester stepped in on a stalled
+   *   turn: one-line diagnosis + what was done, dropped into the thread
+   *   before the granted recovery continuation runs.
+   *
+   * UI renders these as muted bubbles; the model sees them as normal
+   * assistant turns (the role label is what matters to the API).
+   */
+  synthetic: z14.enum([
+    "compaction-summary",
+    "context-loop-halt",
+    "turn-aborted",
+    "growth-announcement",
+    "keurmeester-notice"
+  ]).optional(),
+  /**
+   * Display flag: the model sees this message as normal history, but the
+   * chat transcript UI never renders a bubble for it. Set on
+   * machine-authored facilitation seeds that would only be noise to the
+   * reader — e.g. a project-type page's `reaction` seed ("[Checkers page]:
+   * Your opponent played c3-d4. Board now: …") when the reaction opts in
+   * via `hideSeed`. Unlike `synthetic` (a muted-but-visible bubble), a
+   * `hidden` message is dropped entirely: `Store.listTimeline` filters it
+   * from loaded transcripts and the live-timeline handler skips its bubble
+   * while still opening the assistant's streaming slot.
+   */
+  hidden: z14.boolean().optional(),
+  /**
+   * This user message was delivered from the session's mid-turn queue
+   * as a nudge — typed while the previous turn was still streaming and
+   * held until it finished (contiguous nudges merge into one message).
+   * Display-only marker: the model sees a normal user turn; the UI
+   * renders a small "nudged" chip on the bubble.
+   */
+  nudge: z14.boolean().optional(),
+  /**
+   * Persistent warnings attached to this assistant turn — fabricated
+   * tool-use detection, degraded provider state, etc. The streaming
+   * `warning` events show during the live render but vanish when the
+   * slot is replaced by the persisted message; this field carries the
+   * same text into history so the bubble keeps showing the banner on
+   * reload. Populated by the chat manager just before `events.publish`
+   * fires the `complete` event.
+   */
+  warnings: z14.array(z14.string()).optional(),
+  /**
+   * Chain-of-thought captured during this turn. Local providers
+   * (ollama, llama-cpp, mlx, ds4) extract `<think>…</think>` /
+   * `<reasoning>…</reasoning>` tagged blocks during commit so they
+   * don't pollute the visible reply; Copilot captures its
+   * `assistant.reasoning_delta` stream; Anthropic captures
+   * `thinking_delta` events. All stash the text here so the chat
+   * bubble can render it behind a collapsed "Thinking" expander
+   * instead of dropping it when the live stream closes. OpenAI
+   * Responses hides reasoning server-side and leaves this unset.
+   * Empty / whitespace-only captures are dropped.
+   */
+  reasoning: z14.string().optional(),
+  /**
+   * Observed wall-clock span of the streamed private-reasoning trace,
+   * measured from the first `reasoning_delta` to the last. Optional
+   * because older messages and providers that only expose reasoning at
+   * commit time have no trustworthy phase timing.
+   */
+  reasoningDurationMs: z14.number().int().nonnegative().optional(),
+  /**
+   * Tool-call bodies the model emitted that the salvage layer
+   * couldn't parse — the literal text from `<|tool_call|>` markers
+   * (or prose-shaped `name(args)` attempts) that failed both the
+   * structured-call channel AND the repair pipeline. Surfaced here so
+   * a debug bundle for "model attempted a tool call but couldn't form
+   * it correctly" turns can show what the model actually produced.
+   * Without this the diagnostic disappears into provider logs.
+   *
+   * Populated by the MLX provider when retry budget exhausts. Other
+   * providers may add their own equivalents later. Truncated to a few
+   * hundred chars per body in the populator so a long fabricated body
+   * doesn't blow up the session file.
+   */
+  attemptedToolCalls: z14.array(
+    z14.object({
+      body: z14.string(),
+      reason: z14.string().optional()
+    })
+  ).optional(),
+  /**
+   * Text descriptions of images this message embedded, for models that can't
+   * see. `content` keeps the user's literal markdown (so the thumbnail still
+   * renders and the composer can round-trip it); the digest rides alongside and
+   * is spliced into the model-visible text at send time and again on every
+   * history replay.
+   *
+   * This has to be persisted rather than injected per-turn: `priorMessages` is
+   * rebuilt from the session record for every stateless provider, so an
+   * ephemeral digest would make a turn-1 screenshot vanish by turn 5 — after a
+   * daemon restart, a provider reset, or a context-pressure rebuild — leaving
+   * the model replaying a bare `![](attachments/9f3.png)`.
+   */
+  recognizedImages: z14.array(MessageImageDigestSchema).optional()
+});
+var ChatTurnErrorDetailSchema = z14.object({
+  code: z14.string().max(64).optional(),
+  /** Component that failed — a provider name (`llama-cpp`) or a subsystem. */
+  engine: z14.string().max(64).optional(),
+  /** Correlation key, also written into the engine's own incident log. */
+  incidentId: z14.string().max(64).optional(),
+  /** Native crash class from the exit snapshot, e.g. `cuda-out-of-memory`. */
+  panicKind: z14.string().max(64).optional(),
+  exitCode: z14.number().int().nullable().optional(),
+  signal: z14.string().max(32).nullable().optional(),
+  /**
+   * Request-independent launch facts copied from the crash snapshot, which
+   * is contractually free of prompts, tool arguments, and secrets. Bounded
+   * by the extractor. A machine profile cannot reconstruct which model at
+   * which context size with which KV type crashed; this can.
+   */
+  diagnostics: z14.record(z14.string(), z14.union([z14.string(), z14.number(), z14.boolean()])).optional()
+});
+var ChatEventSchema = z14.discriminatedUnion("type", [
+  z14.object({ type: z14.literal("delta"), content: z14.string() }),
+  /**
+   * Live private-reasoning tokens (ds4's think phase), streamed on their
+   * own channel so they never mix into the visible `delta` stream, the
+   * committed reply body, or the external API-compat forwarders. The UI
+   * renders them as a distinct "thinking" block that collapses into the
+   * committed message's reasoning expander once `complete` lands.
+   */
+  z14.object({ type: z14.literal("reasoning_delta"), content: z14.string() }),
+  z14.object({ type: z14.literal("complete"), message: ChatMessageSchema }),
+  /**
+   * Emitted right after the user's message is appended to the session
+   * record. The legacy session-scoped UI inserted user messages locally
+   * before POSTing, so it didn't need this — but the project + global
+   * envelope streams need it so the interleaved timeline can render the
+   * user's bubble immediately, before any assistant deltas.
+   */
+  z14.object({ type: z14.literal("user_message"), message: ChatMessageSchema }),
+  /**
+   * Emitted when the assistant invokes an MCP tool (OpenAI + Mock paths
+   * only — Copilot runs tools inside its subprocess, invisible to us).
+   * The UI surfaces these as "thinking" breadcrumbs.
+   */
+  z14.object({
+    type: z14.literal("tool"),
+    name: z14.string(),
+    durationMs: z14.number(),
+    success: z14.boolean(),
+    errorMessage: z14.string().optional(),
+    /**
+     * File path the tool touched (if any). Set for tools that take a `path`
+     * argument: readFile, writeFile, read_artifact, write_artifact,
+     * read_document, write_document. Lets the UI build a References panel
+     * without guessing.
+     */
+    path: z14.string().optional(),
+    /** Ordered file paths touched by a batched filesystem tool. */
+    paths: z14.array(z14.string()).optional(),
+    /**
+     * Compact human-readable preview of the non-bulky arguments. Example:
+     * `gezel: "Maya", message: "what's the status of..."`. Values are
+     * truncated and bulky fields like `content` are omitted. Used by the
+     * UI to render a useful in-progress tool line instead of just the
+     * tool name.
+     */
+    argsSummary: z14.string().optional(),
+    /** Full, readable args for the expand + copy affordance. See the persisted `ChatMessageToolCall.argsFull`. */
+    argsFull: z14.string().optional(),
+    /** Short full response, or a bounded beginning/end summary. */
+    resultText: z14.string().optional(),
+    /** True when `resultText` is a bounded summary rather than the complete response. */
+    resultTruncated: z14.boolean().optional(),
+    /**
+     * Image artifacts the tool returned (most commonly browser screenshots).
+     * Paths are relative to the project's artifacts/ root and resolved
+     * to URLs by the UI via the artifact-read endpoint.
+     */
+    images: z14.array(ToolCallImageSchema).optional(),
+    /**
+     * Audio artifacts the tool returned (synthesize_speech narrations,
+     * voice memos transcribed via transcribe_audio). Same artifact-path
+     * resolution as `images`.
+     */
+    audios: z14.array(ToolCallAudioSchema).optional(),
+    /**
+     * Video artifacts the tool returned (`generate_video`). Same
+     * artifact-path resolution as `images`; rendered as a `<video>`
+     * player in the chat row.
+     */
+    videos: z14.array(ToolCallVideoSchema).optional(),
+    /**
+     * Unified diff describing the change a surgical-edit tool made
+     * (`replace_in_file`, `apply_patch`, `insert_at_marker`). Streams to the
+     * UI mid-turn so the chat bubble can render an inline diff under
+     * the tool-call row even before the assistant message is finalized.
+     */
+    diff: z14.string().optional(),
+    addedLines: z14.number().int().nonnegative().optional(),
+    removedLines: z14.number().int().nonnegative().optional()
+  }),
+  z14.object({
+    type: z14.literal("error"),
+    error: z14.string(),
+    // Not `detail` — three sibling variants in this union already use that
+    // name for free-form progress prose, and one union with two meanings for
+    // one key is a trap.
+    errorDetail: ChatTurnErrorDetailSchema.optional()
+  }),
+  /**
+   * The running turn was intentionally stopped through the cancellation
+   * surface. This is terminal for the live UI, but is deliberately not an
+   * error: it must not poison the session or render failure recovery UI.
+   */
+  z14.object({ type: z14.literal("cancelled") }),
+  z14.object({ type: z14.literal("done") }),
+  /**
+   * Emitted when a turn ends up waiting in the provider queue for more
+   * than a brief grace period (~200ms). `aheadOf` is an approximate
+   * count of turns that will dispatch before this one. The UI replaces
+   * its "thinking" indicator with a numbered place-in-line diagram
+   * until the first `delta` or the wait clears. Sub-threshold waits don't
+   * emit this event — avoids flashing the indicator on the happy path
+   * where the queue is empty.
+   */
+  z14.object({ type: z14.literal("queued"), aheadOf: z14.number().int().min(0) }),
+  /**
+   * Ollama-only: emitted for each bare framing chunk that arrives
+   * on the wire without visible content / tool_calls — the
+   * housekeeping pings some Ollama versions stream between actual
+   * tokens. Lets the UI accumulate "···" dots in the streaming
+   * bubble so the user can see "Ollama is alive on the wire" even
+   * when the model isn't producing visible output. Reset on the
+   * next real `delta`, `tool`, or `complete`.
+   */
+  z14.object({ type: z14.literal("wire_pulse") }),
+  /**
+   * Live tool-argument stream. Fired while the model is generating a
+   * structured tool call — most visibly a multi-minute `write_file`
+   * whose argument tokens never appear as visible `delta`s, so without
+   * this channel the only signal is the accumulating wire-pulse count.
+   * `name` is the tool being called ('' until the name chunk arrives);
+   * `content` is the raw argument-text chunk (JSON fragments — file
+   * content mid-write). The UI accumulates these into a dimmed live
+   * "working" block (same pattern as `reasoning_delta`) and drops the
+   * block when the corresponding `tool` event lands.
+   */
+  z14.object({ type: z14.literal("tool_args_delta"), name: z14.string(), content: z14.string() }),
+  /**
+   * Emitted when a provider tells us it's still doing work — even though
+   * no visible text/tool event has arrived. Today this is wired from
+   * Copilot's `session.thinking_start` / `session.thinking_stop` events,
+   * which fire during server-side reasoning that otherwise looks like
+   * silence. The UI treats heartbeats as activity so the "silent for Xs"
+   * banner doesn't climb while the model is legitimately thinking.
+   * Optional `label` carries a short phase hint ('thinking', 'tool',
+   * etc.) that the streaming bubble can surface as a status line.
+   */
+  z14.object({ type: z14.literal("heartbeat"), label: z14.string().optional() }),
+  /**
+   * Provider-side warning surfaced mid-turn (e.g. Copilot rate-limit,
+   * context pressure, degraded mode). The UI renders these inline on
+   * the streaming bubble so the user sees them immediately instead of
+   * only finding out when the turn completes or times out.
+   */
+  z14.object({
+    type: z14.literal("warning"),
+    message: z14.string(),
+    /**
+     * Optional in-app destination for a warning's inline action. Kept
+     * deliberately narrow: warnings are still readable prose when an older
+     * client ignores this additive field.
+     */
+    action: z14.object({
+      kind: z14.literal("settings"),
+      section: z14.enum(["llamaCpp", "mlx", "ds4"])
+    }).optional()
+  }),
+  /**
+   * Copilot-only: the model announced a phase transition via its
+   * `report_intent` built-in tool (e.g. "Building cart checkout
+   * flow"). UI inserts a horizontal-rule divider with the label into
+   * the streaming bubble at the arrival position, then persists the
+   * offset on the final assistant message so completed bubbles render
+   * the same segmentation on reload.
+   */
+  z14.object({ type: z14.literal("intent"), label: z14.string() }),
+  /**
+   * Emitted when a new message is enqueued on the per-session queue
+   * because the session already has a turn in flight. The timeline
+   * renders a "ghost bubble" under the session's streaming bubble
+   * showing the queued text preview. Cleared via `queue_removed`.
+   */
+  z14.object({
+    type: z14.literal("queue_enqueued"),
+    queueId: z14.string(),
+    preview: z14.string(),
+    enqueuedAt: z14.string(),
+    /**
+     * The entry was queued as a mid-turn nudge — the ghost bubble labels
+     * it "nudge" and contiguous nudges merge into one turn on drain.
+     * Full text is deliberately NOT on the event (it re-publishes on
+     * every coalesce/edit); the edit affordance fetches it lazily via
+     * `GET /api/sessions/:id/queue`.
+     */
+    nudge: z14.boolean().optional()
+  }),
+  /**
+   * Emitted when a queued entry leaves the queue — either because
+   * it started running (`reason: 'started'`, the next `user_message`
+   * event follows for the same queueId / session) or because it was
+   * dropped without running (`reason: 'canceled'` via user action,
+   * `reason: 'rejected'` via session archive / delete / shutdown).
+   */
+  z14.object({
+    type: z14.literal("queue_removed"),
+    queueId: z14.string(),
+    reason: z14.enum(["started", "canceled", "rejected"])
+  }),
+  /**
+   * Local-provider context policy: emitted when accumulated conversation
+   * exceeds a safety fraction of the session's effective model context.
+   * The UI may suggest starting fresh because this event is never emitted
+   * for a first-turn standing system/tool prefix.
+   */
+  z14.object({
+    type: z14.literal("context_warning"),
+    estimatedTokens: z14.number(),
+    numCtx: z14.number(),
+    model: z14.string()
+  }),
+  /**
+   * Local-provider context policy: emitted right after in-flight compaction collapses
+   * older messages into a single synthesized "[Earlier in this
+   * conversation: …]" assistant bubble. The UI swaps the warning banner
+   * for a "compacted" variant and refreshes the visible timeline (older
+   * bubbles are now gone from disk).
+   */
+  z14.object({
+    type: z14.literal("context_compacted"),
+    removedCount: z14.number().int().nonnegative(),
+    model: z14.string()
+  }),
+  /**
+   * Emitted when the chat manager detects a self-chat / compaction loop —
+   * the same user-initiated send has already triggered N compactions, which
+   * means the model is regenerating the same prompt → context-pressure →
+   * compaction cycle without making progress. The pipeline halts the turn
+   * so the user can intervene; the UI surfaces a "looks stuck" banner.
+   */
+  z14.object({
+    type: z14.literal("context_loop"),
+    compactionsThisSend: z14.number().int().positive(),
+    reason: z14.string()
+  }),
+  /**
+   * Emitted when the Keurmeester (frontier quality inspector) steps in
+   * on a struggling session — diagnosis delivered, action applied. The
+   * UI renders a "stepped in" notice on the thread; the full case
+   * record lives under `~/.gezel/keurmeester/cases/` keyed by caseId.
+   */
+  z14.object({
+    type: z14.literal("keurmeester_intervention"),
+    caseId: z14.string(),
+    gezelId: z14.string(),
+    gezelName: z14.string(),
+    action: z14.string(),
+    summary: z14.string()
+  }),
+  /**
+   * Emitted once per session the first time auto-recall runs, so the UI
+   * can render a "pulled N memories from prior work" chip above the first
+   * assistant reply.
+   */
+  z14.object({
+    type: z14.literal("recall_applied"),
+    hitCount: z14.number(),
+    query: z14.string()
+  }),
+  /**
+   * Emitted when a gezel posts a structured question via the
+   * `ask_user_question` MCP tool. The UI re-fetches its pending
+   * questions on this event so the in-chat card, Home pane, and Home
+   * tab badge all light up together.
+   */
+  z14.object({ type: z14.literal("question_asked"), question: QuestionSchema }),
+  /**
+   * Emitted when the user submits (or declines) an answer. The UI
+   * uses the same fan-out as `question_asked` to refresh every
+   * surface; the chat bubble's pending card collapses to its
+   * answered state.
+   */
+  z14.object({ type: z14.literal("question_answered"), question: QuestionSchema }),
+  /**
+   * A durable task audit event, fanned onto the project's live stream after
+   * it has been appended to History. This keeps lightweight clients (most
+   * notably the CLI) current without polling task files or inventing a
+   * second task lifecycle bus. `task.tick` heartbeats are intentionally not
+   * published; this channel is for user-meaningful changes.
+   */
+  z14.object({
+    type: z14.literal("task_event"),
+    eventId: z14.string(),
+    kind: z14.string(),
+    summary: z14.string(),
+    at: z14.string(),
+    taskRef: z14.string().optional()
+  }),
+  /**
+   * Emitted when a gezel crosses a growth level threshold and a pending
+   * level-up is created. The UI refreshes growth badges/dots and raises
+   * a single calm OS notification when the window is hidden.
+   */
+  z14.object({
+    type: z14.literal("growth_level_up"),
+    gezelId: z14.string(),
+    gezelName: z14.string(),
+    toLevel: z14.number().int()
+  }),
+  /**
+   * llama-cpp-only: lifecycle phase of the supervised on-device engine
+   * for this turn. Fills the gap between "user sent a message" and
+   * "first token arrives" — long enough (up to 60-180s on a cold start)
+   * that a bare "thinking" spinner reads as hung.
+   *
+   * Phases:
+   *   - `starting`: supervisor spawned llama-server; waiting for `/health`.
+   *   - `loading_model`: llama-server is mapping GGUF weights into
+   *     memory / compiling Metal shaders. `progress` (0-1) is set when
+   *     the stdout parser can extract a percentage.
+   *   - `prefill`: request dispatched, waiting for first token.
+   *   - `generating`: first token arrived; streaming in progress.
+   *   - `ready`: engine is up and idle between turns. Used primarily
+   *     to clear stale status labels; not expected to render prominently.
+   *
+   * `detail` is free-form nerdy text (e.g. "loading layer 28/40",
+   * "Metal shader compile") — the UI can surface it verbatim under
+   * the phase label so users who want to know what's happening can
+   * see, without cluttering the happy-path status line.
+   */
+  z14.object({
+    type: z14.literal("engine_phase"),
+    provider: z14.enum(["llama-cpp", "mlx", "ds4"]),
+    phase: z14.enum(["starting", "loading_model", "prefill", "generating", "ready"]),
+    detail: z14.string().optional(),
+    progress: z14.number().min(0).max(1).optional(),
+    ttftMs: z14.number().int().nonnegative().optional()
+  }),
+  /**
+   * Per-turn telemetry for locally-hosted providers (llama-cpp +
+   * Ollama). Emitted once at turn end with the concrete token counts
+   * the UI needs for a speed readout — input tokens, output tokens,
+   * wall-clock duration, and tokens-per-second on the generation
+   * phase. UI accumulates these in a rolling window to show an
+   * average tok/s over the last N turns.
+   *
+   * Cloud providers (Copilot / OpenAI) don't emit this — their usage
+   * is tracked differently (`UsageSummary` via `/api/usage`); the
+   * local speed metric isn't meaningful when the latency is
+   * dominated by network round-trips.
+   */
+  z14.object({
+    type: z14.literal("turn_stats"),
+    provider: z14.enum(["llama-cpp", "ollama", "mlx", "ds4"]),
+    promptTokens: z14.number().int().nonnegative(),
+    completionTokens: z14.number().int().nonnegative(),
+    durationMs: z14.number().int().nonnegative(),
+    /** Generation speed in tokens/sec — completionTokens / generationSeconds. */
+    tokensPerSec: z14.number().nonnegative().optional()
+  }),
+  /**
+   * Static engine-level metrics that don't change during a session —
+   * total memory allocated for model weights + KV cache, reported
+   * after the supervised engine finishes loading. llama-cpp only
+   * today; Ollama doesn't expose this via its HTTP surface.
+   *
+   * Emitted once per engine lifecycle, fan-out identical to
+   * `engine_phase` (every session waiting on the same supervisor
+   * startup gets a copy).
+   */
+  z14.object({
+    type: z14.literal("engine_stats"),
+    provider: z14.enum(["llama-cpp", "mlx", "ds4"]),
+    /** Total bytes allocated across all GGUF buffers + KV cache. */
+    ramAllocBytes: z14.number().nonnegative()
+  }),
+  /**
+   * VRAM tenancy change — a non-LLM workload has taken (or released)
+   * the GPU. Fires for the local image generator (sd-cpp), the video
+   * generator, and the local image-recognition engine; in the future
+   * the same event will surface STT / TTS engines that share the pool.
+   *
+   * The user-visible point of these events: when the chat session
+   * has issued a `generate_image` tool call, the LLM is actually
+   * paused (and in `swap` policy, evicted from VRAM) while sd-server
+   * runs. Without this signal the bubble would just say "thinking"
+   * for 30+ seconds — actively wrong, and the silence-watchdog would
+   * fire a "still working — silent for X seconds" reassurance that
+   * doesn't apply.
+   *
+   * Lifecycle: a `started` event when the workload begins, optional
+   * `progress` events while the engine reports per-step advancement
+   * (sd-server emits `|==> | 3/20 - 18.20s/it` per sampling step), and
+   * a paired `ended` event when it finishes (or errors). The UI treats
+   * all three as activity signals, so the silence timer resets across
+   * the swap.
+   *
+   * `prompt` carries the user-facing narrative for the workload — for
+   * image_generation, the prompt the model passed to `generate_image`.
+   * It's set on `started` so the bubble can show "Designing: <prompt>"
+   * instead of just dots while sd-server runs. `progress` (0-1) and
+   * `step`/`totalSteps` drive a real progress bar; `secondsPerStep`
+   * lets the UI show an ETA.
+   */
+  z14.object({
+    type: z14.literal("gpu_swap"),
+    state: z14.enum(["started", "progress", "ended"]),
+    /**
+     * Shared with session telemetry so a new workload can't light up the
+     * bubble while staying invisible to stall detection.
+     *
+     * `image_recognition` carries no `progress` — llama-server emits no
+     * per-step ticks for a single vision decode, and a fabricated bar reads
+     * worse than a spinner. It still has to ride this event rather than a log
+     * line, because the silence watchdog treats `gpu_swap` as an activity
+     * signal; without it a 6s vision pass trips "still working — silent for X
+     * seconds", which reads as a bug.
+     */
+    task: SessionGpuTaskSchema,
+    detail: z14.string().optional(),
+    prompt: z14.string().optional(),
+    progress: z14.number().min(0).max(1).optional(),
+    step: z14.number().int().nonnegative().optional(),
+    totalSteps: z14.number().int().positive().optional(),
+    secondsPerStep: z14.number().nonnegative().optional()
+  }),
+  /**
+   * The turn is parked inside a synchronous `ask_gezel` /
+   * `ask_specialist` consultation — this gezel's model is idle, blocked
+   * on a reply from another gezel. Without this signal the asker's
+   * bubble keeps showing the last "Thinking it through" label and looks
+   * indistinguishable from the specialist that's actually doing the
+   * work, so the user can't tell where the ball is.
+   *
+   * Lifecycle mirrors `gpu_swap`: a `started` event when the ask is
+   * registered (before the question is even delivered), a paired
+   * `ended` when the reply arrives, times out, or errors. The UI treats
+   * both as activity (the silence watchdog shouldn't fire — the wait is
+   * expected, not a stall) and, while `started` is unpaired, dims the
+   * bubble and swaps the active "thinking" status for a passive
+   * "Waiting on <name>".
+   *
+   * `targetGezelName` is the already-display-formatted name of the
+   * gezel being consulted (role-based-name mode is resolved service-
+   * side, same as the `ask_gezel` tool result), so the UI can render
+   * it verbatim.
+   */
+  z14.object({
+    type: z14.literal("awaiting_gezel"),
+    state: z14.enum(["started", "ended"]),
+    targetGezelName: z14.string()
+  }),
+  /**
+   * A new project was created (via the New Project dialog, the
+   * `start_project` macro, or any other path through
+   * `POST /api/projects`). Emitted on the project + global streams so
+   * always-mounted surfaces — the left sidebar PROJECTS list in
+   * particular — can fold the project in immediately instead of waiting
+   * for the next manual refresh / tab-focus poll. Not a renderable
+   * timeline event (like `growth_level_up`); the chat surfaces ignore it.
+   */
+  z14.object({
+    type: z14.literal("project_created"),
+    projectId: z14.string(),
+    name: z14.string()
+  }),
+  /**
+   * A project was deleted (via the Project Actions menu, or an equivalent
+   * path through `DELETE /api/projects/:id`). Emitted on the project +
+   * global streams so always-mounted surfaces — the left sidebar PROJECTS
+   * list and the Projects view rail — drop the row immediately instead of
+   * waiting for the next manual refresh / tab-focus poll. Not a renderable
+   * timeline event; the chat surfaces ignore it.
+   */
+  z14.object({
+    type: z14.literal("project_deleted"),
+    projectId: z14.string(),
+    name: z14.string()
+  }),
+  /**
+   * A new shared gezel joined the global roster. Emitted on the global
+   * stream for every Store-backed creation path (including ensure_gezel),
+   * so always-mounted roster surfaces can refresh immediately. Project-local
+   * gezels deliberately do not emit this event because they do not belong in
+   * the global Gezellen list.
+   */
+  z14.object({
+    type: z14.literal("gezel_created"),
+    gezelId: z14.string(),
+    name: z14.string()
+  }),
+  /**
+   * Global (project-less) signal that Night Shift mode flipped ON/OFF.
+   * Emitted by `NightShiftManager` on every state transition so the UI
+   * menu pill reflects the live state. `source` is the active driver
+   * (scheduled window vs. a manual shift), null when inactive.
+   */
+  z14.object({
+    type: z14.literal("night_shift"),
+    active: z14.boolean(),
+    source: z14.enum(["scheduled", "manual"]).nullable()
+  }),
+  /**
+   * Global signal from the meester status generator. `started` fires
+   * when a run begins (manual runs show "Meester is writing…"),
+   * `ended` when a fresh report landed on disk, `failed` when the run
+   * produced nothing usable — the Home greeting refetches on the
+   * terminal states instead of polling.
+   */
+  z14.object({
+    type: z14.literal("meester_status"),
+    state: z14.enum(["started", "ended", "failed"]),
+    generatedAt: z14.string().optional()
+  }),
+  /**
+   * Global (history-free) heartbeat from the boekwachter indexing loops —
+   * workspace scans, AI enrichment batches, weekly digests. Drives the live
+   * indicator pill; complements (doesn't replace) the polled per-project
+   * index status. `pending` = files still awaiting AI enrichment when known.
+   */
+  z14.object({
+    type: z14.literal("index_progress"),
+    phase: z14.enum(["scan", "enrich", "review", "digest"]),
+    state: z14.enum(["started", "progress", "ended"]),
+    projectId: z14.string().optional(),
+    detail: z14.string().optional(),
+    pending: z14.number().int().nonnegative().optional(),
+    /** The concrete autonomous gezel doing this work, when the project has one. */
+    gezelId: z14.string().optional(),
+    /** Snapshot of their display name so transient progress remains human-readable. */
+    gezelName: z14.string().optional()
+  })
+]);
+var ChatEventEnvelopeSchema = z14.object({
+  sessionId: z14.string(),
+  gezelId: z14.string(),
+  projectId: z14.string(),
+  event: ChatEventSchema
+});
+
+// src/markdown/gezel-md.ts
+var HEADING_RE = /^(#{1,6})\s+(.+?)\s*$/;
+var TEMPLATE_RE = /\{\[\s*([a-zA-Z_][\w-]*)\s*([^\]]*)\]\}\s*$/;
+function parseGezelMarkdown(source) {
+  const parsed = parseYamlFrontmatter(source);
+  const frontmatter = GezelFrontmatterSchema.parse({
+    name: "Untitled agent",
+    ...parsed.data
+  });
+  const lines = parsed.content.split(/\r?\n/);
+  const headings = collectHeadings(lines);
+  if (headings.length === 0) {
+    return {
+      frontmatter,
+      sections: [
+        {
+          heading: "",
+          body: parsed.content.trim()
+        }
+      ],
+      source
+    };
+  }
+  const topLevel = Math.min(...headings.map((h) => h.level));
+  const sectionStarts = headings.filter((h) => h.level === topLevel);
+  const sections = [];
+  for (let i = 0; i < sectionStarts.length; i++) {
+    const start = sectionStarts[i];
+    const next = sectionStarts[i + 1];
+    const bodyLines = lines.slice(start.lineIndex + 1, next ? next.lineIndex : lines.length);
+    const body = bodyLines.join("\n").trim();
+    const { heading, template, params } = parseHeadingAnnotation(start.text);
+    sections.push({
+      heading,
+      body,
+      ...template ? { template } : {},
+      ...params && Object.keys(params).length > 0 ? { params } : {}
+    });
+  }
+  return { frontmatter, sections, source };
+}
+function collectHeadings(lines) {
+  const out = [];
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const m = HEADING_RE.exec(line);
+    if (m) out.push({ lineIndex: i, level: m[1].length, text: m[2] });
+  }
+  return out;
+}
+function parseHeadingAnnotation(raw) {
+  const m = TEMPLATE_RE.exec(raw);
+  if (!m) return { heading: raw.trim() };
+  const heading = raw.slice(0, m.index).trim();
+  const template = m[1];
+  const params = parseParams(m[2] ?? "");
+  return { heading, template, params };
+}
+function parseParams(src) {
+  const out = {};
+  const re = /([a-zA-Z_][\w-]*)=(?:"([^"]*)"|'([^']*)'|([^\s]+))/g;
+  let m;
+  while ((m = re.exec(src)) !== null) {
+    out[m[1]] = m[2] ?? m[3] ?? m[4] ?? "";
+  }
+  return out;
+}
+function serializeGezelMarkdown(parsed) {
+  const body = parsed.sections.map((section) => {
+    const annotation = section.template ? ` {[${section.template}${formatParams(section.params)}]}` : "";
+    const heading = section.heading ? `## ${section.heading}${annotation}
+
+` : "";
+    return `${heading}${section.body}`.trimEnd();
+  }).join("\n\n");
+  return stringifyYamlFrontmatter(`${body}
+`, parsed.frontmatter);
+}
+function formatParams(params) {
+  if (!params) return "";
+  const keys = Object.keys(params);
+  if (keys.length === 0) return "";
+  return ` ${keys.map((k) => `${k}=${quoteIfNeeded(params[k])}`).join(" ")}`;
+}
+function quoteIfNeeded(value) {
+  return /\s/.test(value) ? `"${value}"` : value;
+}
+
+// src/markdown/promote-channel-names.ts
+var KNOWN_CHANNEL_NAMES = ["thought", "analysis", "commentary", "final"];
+var MODE_INDICATORS = {
+  thought: "_Thinking\u2026_",
+  analysis: "_Analyzing\u2026_",
+  commentary: "_Reflecting\u2026_",
+  final: null
+};
+function splitInlineChannelLeaks(text) {
+  return text.replace(/^(thought|analysis|commentary|final)(?=[A-Z])/gm, "$1\n");
+}
+function promoteBareChannelNames(text) {
+  if (!text) return text;
+  const split = splitInlineChannelLeaks(text);
+  const lines = split.split("\n");
+  const out = [];
+  let lastIndicator = null;
+  for (const raw of lines) {
+    const trimmed = raw.trim().toLowerCase();
+    const match = KNOWN_CHANNEL_NAMES.includes(trimmed) ? trimmed : null;
+    if (match) {
+      const indicator = MODE_INDICATORS[match];
+      if (indicator === null) {
+        lastIndicator = null;
+        continue;
+      }
+      if (indicator !== lastIndicator) {
+        out.push(indicator);
+        lastIndicator = indicator;
+      }
+      continue;
+    }
+    if (raw.trim().length > 0) lastIndicator = null;
+    out.push(raw);
+  }
+  return out.join("\n");
+}
+
+// src/schemas/report-action.ts
+import { z as z15 } from "zod";
+var ReportActionKindSchema = z15.enum(["fire-craftbook", "create-task", "apply-edits"]);
+var commonFields = {
+  /**
+   * Author-supplied stable slug — keeps lifecycle state attached across
+   * nightly report regenerations. Optional: the parser falls back to a
+   * content hash (`a-<hash>`), which is stable only while the block's
+   * body is byte-identical.
+   */
+  id: z15.string().regex(/^[a-z0-9][a-z0-9_-]*$/i).optional(),
+  /** Short human label for the card ("Fix the unchecked null in parser.ts"). */
+  title: z15.string().min(1),
+  /** One-or-two-sentence rationale shown under the title. */
+  reason: z15.string().optional(),
+  /**
+   * Target project. Defaults to the report's own project. Cross-project
+   * targets are a primary case — the bundled oversight report lives in
+   * `default` but recommends work in specific projects.
+   */
+  projectId: z15.string().optional()
+};
+var FireCraftbookActionSchema = z15.object({
+  kind: z15.literal("fire-craftbook"),
+  ...commonFields,
+  craftbookId: z15.string().min(1),
+  /** Invocation params for the craftbook's paramSchema (stringified values). */
+  params: z15.record(z15.string(), z15.string()).optional()
+});
+var CreateTaskActionSchema = z15.object({
+  kind: z15.literal("create-task"),
+  ...commonFields,
+  /** Full work instruction for the bespoke task's single step. */
+  prompt: z15.string().min(1),
+  /** Role to recruit for the work (ensure_gezel jobTitle). Default: software developer. */
+  role: z15.string().optional()
+});
+var ApplyEditsActionSchema = z15.object({
+  kind: z15.literal("apply-edits"),
+  ...commonFields,
+  edits: z15.array(
+    z15.object({
+      /** Workspace-relative target file in the TARGET project. */
+      path: z15.string().min(1),
+      /** Artifacts-relative sidecar `.diff` path in the REPORT's project. */
+      diffArtifact: z15.string().min(1)
+    })
+  ).min(1)
+});
+var ReportActionSchema = z15.discriminatedUnion("kind", [
+  FireCraftbookActionSchema,
+  CreateTaskActionSchema,
+  ApplyEditsActionSchema
+]);
+var ReportActionStateSchema = z15.enum([
+  "suggested",
+  "fired",
+  "applied",
+  "failed",
+  "dismissed"
+]);
+var ReportActionRecordSchema = z15.object({
+  actionId: z15.string(),
+  /** Artifacts-relative path of the report the action came from. */
+  reportPath: z15.string(),
+  kind: ReportActionKindSchema,
+  contentHash: z15.string(),
+  firstSeenAt: z15.string(),
+  state: ReportActionStateSchema,
+  /** Task materialized by fire-craftbook / create-task. */
+  taskRef: z15.string().optional(),
+  firedAt: z15.string().optional(),
+  /** Stamped when the fired task settles. */
+  settledAt: z15.string().optional(),
+  outcome: z15.enum(["complete", "canceled"]).optional(),
+  /** apply-edits per-file results. */
+  results: z15.array(
+    z15.object({
+      path: z15.string(),
+      ok: z15.boolean(),
+      error: z15.string().optional()
+    })
+  ).optional()
+});
+var ReportActionParseIssueSchema = z15.object({
+  /** Zero-based index among the report's gezel-action fences. */
+  index: z15.number().int(),
+  message: z15.string(),
+  /** Raw fence body, for the "unreadable action block" card. */
+  raw: z15.string()
+});
+var ReportActionViewSchema = z15.object({
+  action: ReportActionSchema,
+  id: z15.string(),
+  contentHash: z15.string(),
+  state: ReportActionStateSchema,
+  taskRef: z15.string().optional(),
+  firedAt: z15.string().optional(),
+  settledAt: z15.string().optional(),
+  outcome: z15.enum(["complete", "canceled"]).optional(),
+  results: z15.array(z15.object({ path: z15.string(), ok: z15.boolean(), error: z15.string().optional() })).optional(),
+  /** The stored record predates a changed block body (report regenerated). */
+  contentChanged: z15.boolean().optional()
+});
+var ReportActionsResponseSchema = z15.object({
+  actions: z15.array(ReportActionViewSchema),
+  issues: z15.array(ReportActionParseIssueSchema),
+  /** Records whose action vanished from the regenerated report. */
+  stale: z15.array(ReportActionRecordSchema)
+});
+var FireReportActionRequestSchema = z15.object({
+  /** Artifacts-relative report path. */
+  path: z15.string().min(1),
+  actionId: z15.string().min(1),
+  /** apply-edits: none. fire-craftbook: overrides the block's params. */
+  params: z15.record(z15.string(), z15.string()).optional()
+});
+var FireReportActionResponseSchema = z15.object({
+  record: ReportActionRecordSchema,
+  /** Set for fire-craftbook / create-task. */
+  taskRef: z15.string().optional()
+});
+var DismissReportActionRequestSchema = z15.object({
+  path: z15.string().min(1),
+  actionId: z15.string().min(1)
+});
+
+// src/markdown/report-actions.ts
+var REPORT_ACTION_FENCE_LANG = "gezel-action";
+function reportActionContentHash(body) {
+  let hash = 2166136261;
+  const text = body.trim();
+  for (let i = 0; i < text.length; i++) {
+    hash ^= text.charCodeAt(i);
+    hash = Math.imul(hash, 16777619) >>> 0;
+  }
+  return hash.toString(16).padStart(8, "0");
+}
+var KIND_ALIASES = {
+  craftbook: "fire-craftbook",
+  "run-craftbook": "fire-craftbook",
+  task: "create-task",
+  "new-task": "create-task",
+  edits: "apply-edits",
+  "apply-diffs": "apply-edits",
+  diff: "apply-edits",
+  "diff-pack": "apply-edits"
+};
+var KNOWN_KEYS_BY_KIND = {
+  "fire-craftbook": ["kind", "id", "title", "reason", "projectId", "craftbookId", "params"],
+  "create-task": ["kind", "id", "title", "reason", "projectId", "prompt", "role"],
+  "apply-edits": ["kind", "id", "title", "reason", "projectId", "edits"]
+};
+var KEY_ALIASES = {
+  name: "title",
+  project: "projectId",
+  craftbook: "craftbookId",
+  why: "reason"
+};
+function normalizeRaw(raw) {
+  const out = {};
+  for (const [key, value] of Object.entries(raw)) {
+    out[KEY_ALIASES[key] ?? key] = value;
+  }
+  const kindRaw = typeof out.kind === "string" ? out.kind.trim().toLowerCase() : "";
+  const kind = KIND_ALIASES[kindRaw] ?? kindRaw;
+  out.kind = kind;
+  const known = KNOWN_KEYS_BY_KIND[kind];
+  const stripped = {};
+  for (const [key, value] of Object.entries(out)) {
+    if (!known || known.includes(key)) stripped[key] = value;
+  }
+  if (stripped.params && typeof stripped.params === "object" && !Array.isArray(stripped.params)) {
+    const params = {};
+    for (const [key, value] of Object.entries(stripped.params)) {
+      if (value === null || value === void 0) continue;
+      params[key] = typeof value === "string" ? value : String(value);
+    }
+    stripped.params = params;
+  }
+  if (Array.isArray(stripped.edits)) {
+    stripped.edits = stripped.edits.map((entry) => {
+      if (!entry || typeof entry !== "object") return entry;
+      const record = entry;
+      return {
+        ...record.path !== void 0 ? { path: String(record.path) } : {},
+        ...record.diffArtifact !== void 0 ? { diffArtifact: String(record.diffArtifact) } : record.diff !== void 0 ? { diffArtifact: String(record.diff) } : {}
+      };
+    }).filter((entry) => entry && typeof entry === "object");
+  }
+  return stripped;
+}
+function parseReportActionBlock(body, index) {
+  const contentHash = reportActionContentHash(body);
+  let raw;
+  try {
+    raw = parseYamlBlock(body);
+  } catch (err) {
+    return {
+      ok: false,
+      issue: {
+        index,
+        message: `not a YAML mapping: ${err instanceof Error ? err.message : String(err)}`,
+        raw: body
+      }
+    };
+  }
+  const normalized = normalizeRaw(raw);
+  const parsed = ReportActionSchema.safeParse(normalized);
+  if (!parsed.success) {
+    const first = parsed.error.issues[0];
+    return {
+      ok: false,
+      issue: {
+        index,
+        message: first ? `${first.path.join(".") || "block"}: ${first.message}` : "invalid action block",
+        raw: body
+      }
+    };
+  }
+  const id = parsed.data.id ?? `a-${contentHash}`;
+  return { ok: true, action: { ...parsed.data, id, contentHash } };
+}
+function parseReportActions(markdown) {
+  const actions = [];
+  const issues = [];
+  const seen = /* @__PURE__ */ new Map();
+  let index = 0;
+  for (const fence of extractAllFences(markdown)) {
+    const lang = fence.lang.split(/\s+/, 1)[0] ?? "";
+    if (lang !== REPORT_ACTION_FENCE_LANG) continue;
+    const fenceIndex = index++;
+    const result = parseReportActionBlock(fence.code, fenceIndex);
+    if (!result.ok) {
+      issues.push(result.issue);
+      continue;
+    }
+    const action = result.action;
+    const count = (seen.get(action.id) ?? 0) + 1;
+    seen.set(action.id, count);
+    if (count > 1) {
+      const suffixed = `${action.id}-${count}`;
+      issues.push({
+        index: fenceIndex,
+        message: `duplicate action id "${action.id}" \u2014 renamed to "${suffixed}"; give each block a unique id`,
+        raw: fence.code
+      });
+      actions.push({ ...action, id: suffixed });
+    } else {
+      actions.push(action);
+    }
+  }
+  return { actions, issues };
+}
+function hasReportActionFence(markdown) {
+  const lines = markdown.split("\n");
+  let openFence = null;
+  for (const line of lines) {
+    const fence = FENCE.exec(line.trim());
+    if (openFence !== null) {
+      if (fence && isFenceClose(line, openFence)) openFence = null;
+      continue;
+    }
+    if (fence) {
+      openFence = fence[1];
+      const lang = fence[2].trim().toLowerCase().split(/\s+/, 1)[0];
+      if (lang === REPORT_ACTION_FENCE_LANG) return true;
+    }
+  }
+  return false;
+}
+var REPORT_ACTION_AUTHORING_GUIDE = `When a recommendation is directly actionable, follow it with a \`\`\`gezel-action fenced YAML block so the user can fire it with one click in the morning. Three kinds, flat keys only, one block per action, each with a unique stable \`id\` slug:
+
+Run an existing craftbook:
+\`\`\`gezel-action
+kind: fire-craftbook
+id: nightly-a11y-sweep
+title: Run an accessibility audit
+reason: Three templates changed without alt text review.
+craftbookId: a11y-audit
+projectId: webshop
+\`\`\`
+
+Delegate a bespoke task:
+\`\`\`gezel-action
+kind: create-task
+id: fix-null-parse
+title: Fix the unchecked null in parser.ts
+reason: parseHeader returns null on empty input and callers dereference it.
+prompt: In src/parser.ts, parseHeader can return null (line ~88) and both callers dereference the result. Add the guard, mirror the fix in parseFooter, and extend parser.test.ts with the empty-input case.
+role: software developer
+projectId: webshop
+\`\`\`
+
+Propose file edits (diffs go in SIDECAR artifact files \u2014 never inline):
+\`\`\`gezel-action
+kind: apply-edits
+id: harden-csp-headers
+title: Add missing security headers
+reason: Responses lack X-Content-Type-Options and a CSP.
+projectId: webshop
+edits:
+  - path: src/server/headers.ts
+    diffArtifact: night-shift-report/edits/harden-csp-headers.diff
+\`\`\`
+
+For apply-edits: write each proposed change as ONE unified diff per target file with write_artifact (a single-file diff against the file's current content), and reference it via diffArtifact. Keep titles short, reasons to a sentence or two, and never invent craftbook ids \u2014 only reference books you confirmed exist.`;
+export {
+  FENCE,
+  REPORT_ACTION_AUTHORING_GUIDE,
+  REPORT_ACTION_FENCE_LANG,
+  defaultStepIdForName,
+  extractAllFences,
+  extractFirstFence,
+  findFirstH1,
+  hasReportActionFence,
+  isFenceClose,
+  parseCraftbookMarkdown,
+  parseGezelMarkdown,
+  parseReportActionBlock,
+  parseReportActions,
+  parseYamlBlock,
+  pickFence,
+  promoteBareChannelNames,
+  reportActionContentHash,
+  serializeCraftbookMarkdown,
+  serializeGezelMarkdown,
+  splitSections,
+  stringifyYamlBlock
+};