@aitne/daemon 0.1.8 → 0.1.10

package/dist/api/helpers/agent-errors-registry.d.ts

@@ -0,0 +1,2290 @@
+/**
+ * Authoritative registry of every agent-consumable error code. Adding a new
+ * code requires a registry entry; the helper logs a warning and emits a
+ * placeholder hint when an unregistered code is passed (so a typo doesn't
+ * silently ship a useless error).
+ *
+ * Codes are namespaced by resource:
+ * - `schedule.*`        — POST /api/schedule + POST /api/schedule/batch
+ * - `agent_actions.*`   — PATCH /api/agent-actions/self
+ *
+ * The codes here must be reachable via a crafted bad request — every test
+ * file for these endpoints carries a coverage assertion against the registry
+ * (see schedule-batch.test.ts / agent-actions.test.ts).
+ */
+export declare const AGENT_ERROR_REGISTRY: {
+    readonly "schedule.body_not_object": {
+        readonly expected: "JSON object";
+        readonly hint: "Request body must be a JSON object. For /api/schedule/batch wrap rows in '{\"rows\":[…]}'. For /api/schedule supply the row fields directly at the top level.";
+        readonly skillAnchor: "schedule#request-shape";
+        readonly docsUrl: "agent-assets/skills/schedule/references/errors.md#body_not_object";
+        readonly constraint: {
+            readonly type: "object";
+            readonly required: true;
+        };
+    };
+    readonly "schedule.rows_field_missing": {
+        readonly expected: "array of row objects under 'rows'";
+        readonly hint: "Wrap your row objects in a 'rows' array: POST {\"rows\":[{…},{…}]}. An empty array is accepted as a documented no-op.";
+        readonly skillAnchor: "schedule#batch-shape";
+        readonly docsUrl: "agent-assets/skills/schedule/references/errors.md#rows_field_missing";
+        readonly constraint: {
+            readonly type: "array";
+            readonly required: true;
+        };
+    };
+    readonly "schedule.rows_too_many": {
+        readonly expected: "at most 50 rows per batch";
+        readonly hint: "Split the batch into chunks of at most 50 rows. The morning routine's typical batch size is 4-8 rows; 50 is a generous cap.";
+        readonly skillAnchor: "schedule#batch-shape";
+        readonly docsUrl: "agent-assets/skills/schedule/references/errors.md#rows_too_many";
+        readonly constraint: {
+            readonly type: "array";
+            readonly maximum: 50;
+        };
+    };
+    readonly "schedule.scheduled_for_invalid": {
+        readonly expected: "ISO8601 timestamp parseable by Date()";
+        readonly hint: "Use an ISO 8601 string with timezone offset, e.g. '2026-05-15T14:30:00-04:00'. Convert relative expressions via <current_time> in your context.";
+        readonly skillAnchor: "schedule#scheduledFor-bounds";
+        readonly docsUrl: "agent-assets/skills/schedule/references/errors.md#scheduled_for_invalid";
+        readonly constraint: {
+            readonly type: "iso8601";
+            readonly required: true;
+        };
+    };
+    readonly "schedule.scheduled_for_in_past": {
+        readonly expected: "ISO8601 timestamp >= now";
+        readonly hint: "scheduledFor must be at least 1 minute in the future. Pick a time later today or tomorrow, then resubmit.";
+        readonly skillAnchor: "schedule#scheduledFor-bounds";
+        readonly docsUrl: "agent-assets/skills/schedule/references/errors.md#scheduled_for_in_past";
+        readonly constraint: {
+            readonly type: "iso8601";
+        };
+    };
+    readonly "schedule.task_type_unknown": {
+        readonly expected: "one of 'wake' | 'dm_session' | 'check' | 'dm'";
+        readonly hint: "taskType is the dispatcher's switch. Pick: 'wake' = future agent session that decides+acts at fire time (most common); 'dm_session' = agent session that composes ONE DM and exits (notifications with model judgment); 'dm' = precomposed DM with no LLM call at fire time (use this on POST /api/schedule/dm, NOT POST /api/schedule); 'check' = non-LLM probe (rare — internal). When in doubt for routines, use 'wake'.";
+        readonly skillAnchor: "schedule#taskType";
+        readonly docsUrl: "agent-assets/skills/schedule/references/errors.md#task_type_unknown";
+        readonly constraint: {
+            readonly type: "enum";
+            readonly enum: readonly ["wake", "dm_session", "check", "dm"];
+            readonly required: true;
+        };
+    };
+    readonly "schedule.description_too_short": {
+        readonly expected: "string with >= 20 characters";
+        readonly hint: "The wake-up agent has NO memory — description is its only context. Include what + why + who + expected output. Bad: 'Meeting prep'. Good: '15-min reminder for the 14:00 design review. Attendees: Sarah, Mike. Notify the user via Slack.'";
+        readonly skillAnchor: "schedule#description-shape";
+        readonly docsUrl: "agent-assets/skills/schedule/references/errors.md#description_too_short";
+        readonly constraint: {
+            readonly type: "string";
+            readonly minLength: 20;
+            readonly required: true;
+        };
+    };
+    readonly "schedule.prompt_too_short": {
+        readonly expected: "string with >= 20 characters when set";
+        readonly hint: "On /api/schedule/batch and recurring schedules a `prompt`/`taskPrompt` override must be >= 20 chars when set, or omit it so the row uses its description body. (On the single /api/schedule row `prompt` is the required instruction and only `schedule.prompt_required` applies.)";
+        readonly skillAnchor: "schedule#description-shape";
+        readonly docsUrl: "agent-assets/skills/schedule/references/errors.md#prompt_too_short";
+        readonly constraint: {
+            readonly type: "string";
+            readonly minLength: 20;
+        };
+    };
+    readonly "schedule.prompt_required": {
+        readonly expected: "non-empty string (the agent's instruction)";
+        readonly hint: "prompt is the wake-up agent's ONLY instruction at fire time — it is required. Write the full instruction here (what to do + why + the expected output). The separate `description` is just the optional short label shown in the schedule list; it is no longer used as the agent body.";
+        readonly skillAnchor: "schedule#description-shape";
+        readonly docsUrl: "agent-assets/skills/schedule/references/errors.md#prompt_required";
+        readonly constraint: {
+            readonly type: "string";
+            readonly minLength: 1;
+            readonly required: true;
+        };
+    };
+    readonly "schedule.prompt_too_long": {
+        readonly expected: "string with <= 8000 characters";
+        readonly hint: "prompt exceeds the 8000-character cap (~2000 tokens) — the bound is a cost/context guardrail, not a model limit. Tighten the instruction to the goal, the key context, and the expected output. Move bulk reference material into a file the agent reads at fire time (e.g. a context/plans path) instead of inlining it.";
+        readonly skillAnchor: "schedule#description-shape";
+        readonly docsUrl: "agent-assets/skills/schedule/references/errors.md#prompt_too_long";
+        readonly constraint: {
+            readonly type: "string";
+            readonly maxLength: 8000;
+        };
+    };
+    readonly "schedule.description_too_long": {
+        readonly expected: "string with <= 200 characters";
+        readonly hint: "description is the short label shown in the schedule list — keep it under 200 characters. It is NOT the agent body; put the full instruction in `prompt`. (Omit `description` entirely and the list falls back to a prompt excerpt.)";
+        readonly skillAnchor: "schedule#description-shape";
+        readonly docsUrl: "agent-assets/skills/schedule/references/errors.md#description_too_long";
+        readonly constraint: {
+            readonly type: "string";
+            readonly maxLength: 200;
+        };
+    };
+    readonly "schedule.task_context_field_missing": {
+        readonly expected: "string with >= 30 characters explaining why this task is being scheduled";
+        readonly hint: "Stage A must populate taskContext.background and taskContext.expected_output so the future session can produce high-quality output without re-deriving context. Example background: 'User flagged Q2 roadmap risks in yesterday's DM; pre-brief should surface the two open items before the 15:00 standup.'";
+        readonly skillAnchor: "schedule#taskContext-required-fields";
+        readonly docsUrl: "agent-assets/skills/schedule/references/errors.md#task_context_field_missing";
+        readonly constraint: {
+            readonly type: "string";
+            readonly minLength: 30;
+            readonly required: true;
+        };
+    };
+    readonly "schedule.task_context_field_too_short": {
+        readonly expected: "non-trivial string content";
+        readonly hint: "Required taskContext fields must carry real content. background needs >=30 chars, expected_output needs >=20 chars. Omitting them is not an option — they're how the future session reconstructs context.";
+        readonly skillAnchor: "schedule#taskContext-required-fields";
+        readonly docsUrl: "agent-assets/skills/schedule/references/errors.md#task_context_field_too_short";
+        readonly constraint: {
+            readonly type: "string";
+        };
+    };
+    readonly "schedule.task_context_field_wrong_type": {
+        readonly expected: "matching type per the schema";
+        readonly hint: "taskContext fields have typed slots: background = string (>=30 chars); expected_output = string (>=20 chars); references = string[] (paths or URLs the future session should read); tier_override = null | 'lite' | 'medium' | 'high'; tone = free string ('terse', 'celebratory', etc.); deadline = ISO8601 string or null. The response's `received` shows the actual JS type the daemon saw — coerce to the expected one and resubmit.";
+        readonly skillAnchor: "schedule#taskContext-required-fields";
+        readonly docsUrl: "agent-assets/skills/schedule/references/errors.md#task_context_field_wrong_type";
+    };
+    readonly "schedule.model_unknown": {
+        readonly expected: "'sonnet' | 'opus' | a registered model id | omitted";
+        readonly hint: "Pass one of: a legacy alias ('sonnet'/'opus' — rewritten to tier 'medium'/'high'); a full registered model id (e.g. 'claude-opus-4-8', 'gpt-5.4'); the composite form '<backendId>/<modelId>' when an id collides across backends; or omit `model` and use `tier` (recommended). The response's validValues lists every alias + every currently-registered model per backend — pick from that list and resubmit.";
+        readonly skillAnchor: "schedule#model-selection";
+        readonly docsUrl: "agent-assets/skills/schedule/references/errors.md#model_unknown";
+        readonly constraint: {
+            readonly type: "string";
+            readonly maxLength: 120;
+        };
+    };
+    readonly "schedule.model_ambiguous": {
+        readonly expected: "an unambiguous model token (use '<backendId>/<modelId>')";
+        readonly hint: "The model id you supplied is registered under more than one backend. Resubmit using the composite '<backendId>/<modelId>' form (e.g. 'claude/claude-opus-4-8') so the daemon doesn't have to guess which backend you meant. The response's validValues.matches lists the colliding entries.";
+        readonly skillAnchor: "schedule#model-selection";
+        readonly docsUrl: "agent-assets/skills/schedule/references/errors.md#model_ambiguous";
+        readonly constraint: {
+            readonly type: "string";
+        };
+    };
+    readonly "schedule.model_deprecated": {
+        readonly expected: "a non-deprecated model id (or omit and use `tier`)";
+        readonly hint: "The model id you supplied is registered but flagged deprecated — the registry may remove it on a future release. The row was still persisted. Consider switching to a non-deprecated id from the response's validValues.availableModels list, or use `tier` instead so the dispatcher picks the latest non-deprecated model for the resolved process key.";
+        readonly skillAnchor: "schedule#model-selection";
+        readonly docsUrl: "agent-assets/skills/schedule/references/errors.md#model_deprecated";
+        readonly severity: "warning";
+        readonly constraint: {
+            readonly type: "string";
+        };
+    };
+    readonly "schedule.backend_id_unknown": {
+        readonly expected: "'claude' | 'codex' | 'gemini' | 'opencode'";
+        readonly hint: "The backend id portion of the composite-form token did not match a registered backend. Use one of the four BackendId values listed in validValues — the daemon does not dispatch to any others.";
+        readonly skillAnchor: "schedule#model-selection";
+        readonly docsUrl: "agent-assets/skills/schedule/references/errors.md#backend_id_unknown";
+        readonly constraint: {
+            readonly type: "enum";
+            readonly enum: readonly ["claude", "codex", "gemini", "opencode"];
+        };
+    };
+    readonly "schedule.tier_unknown": {
+        readonly expected: "'lite' | 'medium' | 'high' | omitted";
+        readonly hint: "tier is the abstract cost knob — prefer this over `model` for new schedules. Omit to use the dispatcher's process-key default (medium). Use 'lite' for hourly polling/health checks (Haiku-class) and 'high' for one-off generative work (Opus-class).";
+        readonly skillAnchor: "schedule#tier-selection";
+        readonly docsUrl: "agent-assets/skills/schedule/references/errors.md#tier_unknown";
+        readonly constraint: {
+            readonly type: "enum";
+            readonly enum: readonly ["lite", "medium", "high"];
+        };
+    };
+    readonly "schedule.tier_and_model_conflict": {
+        readonly expected: "exactly one of `tier` OR `model` (not both)";
+        readonly hint: "You supplied BOTH `tier` and `model`. Pick one: use `tier` ('lite' | 'medium' | 'high') as the abstract cost knob — this is the recommended path because the dispatcher picks the latest non-deprecated model per backend automatically. Use `model` only when you must pin a specific id (e.g. reproducing a past run on a deprecated id). On PATCH, you can clear one and set the other in the same request (pass `null` to clear).";
+        readonly skillAnchor: "schedule#tier-vs-model";
+        readonly docsUrl: "agent-assets/skills/schedule/references/errors.md#tier_and_model_conflict";
+    };
+    readonly "schedule.batch_atomic_invalid": {
+        readonly expected: "boolean (default true)";
+        readonly hint: "atomic controls rollback. true (default) wraps all rows in one transaction; any row error rolls back all inserts. false commits successful rows individually. Use true for morning routine to retry the whole batch as one unit.";
+        readonly skillAnchor: "schedule#batch-shape";
+        readonly docsUrl: "agent-assets/skills/schedule/references/errors.md#batch_atomic_invalid";
+        readonly constraint: {
+            readonly type: "boolean";
+        };
+    };
+    readonly "schedule.frequency_unknown": {
+        readonly expected: "'hourly' | 'daily' | 'weekly' | 'monthly'";
+        readonly hint: "recurrenceRule.frequency must be one of: 'hourly' (every N hours at :MM), 'daily' (one fire per day at HH:MM), 'weekly' (HH:MM on the listed daysOfWeek), 'monthly' (HH:MM on the listed daysOfMonth). See validValues for the exact enum.";
+        readonly skillAnchor: "recurring#frequency";
+        readonly docsUrl: "agent-assets/skills/schedule/references/errors.md#frequency_unknown";
+        readonly constraint: {
+            readonly type: "enum";
+            readonly enum: readonly ["hourly", "daily", "weekly", "monthly"];
+        };
+    };
+    readonly "schedule.frequency_field_mismatch": {
+        readonly expected: "field set that matches the chosen frequency";
+        readonly hint: "Each frequency requires a specific combination of fields. hourly: no `time`, no day-of-* fields, no `onMissingDay` — use `intervalHours` (1..23, default 1) + `minuteOfHour` (0..59, default 0). daily: `time` only (HH:MM). weekly: `time` + `daysOfWeek` (0=Sun..6=Sat). monthly: `time` + `daysOfMonth` (1..31), `onMissingDay` optional ('skip' | 'lastDayOfMonth', default 'lastDayOfMonth'). See validValues.requiredFor / forbiddenFor for the exact matrix.";
+        readonly skillAnchor: "recurring#frequency-fields";
+        readonly docsUrl: "agent-assets/skills/schedule/references/errors.md#frequency_field_mismatch";
+    };
+    readonly "schedule.interval_hours_out_of_range": {
+        readonly expected: "integer in [1, 23]";
+        readonly hint: "intervalHours sets the hourly cadence — N=1 fires every hour, N=2 every two hours anchored at midnight in the rule's timezone. The cap is 23 because N=24 collapses to a daily fire; if you want daily, switch frequency to 'daily' and set `time`. Sub-hour intervals are not supported.";
+        readonly skillAnchor: "recurring#hourly";
+        readonly docsUrl: "agent-assets/skills/schedule/references/errors.md#interval_hours_out_of_range";
+        readonly constraint: {
+            readonly type: "integer";
+            readonly minimum: 1;
+            readonly maximum: 23;
+        };
+    };
+    readonly "schedule.minute_of_hour_out_of_range": {
+        readonly expected: "integer in [0, 59]";
+        readonly hint: "minuteOfHour pins which minute the hourly cadence lands on. Default 0 (fires at :00). Example: minuteOfHour=15 with intervalHours=2 fires at 00:15, 02:15, 04:15, …";
+        readonly skillAnchor: "recurring#hourly";
+        readonly docsUrl: "agent-assets/skills/schedule/references/errors.md#minute_of_hour_out_of_range";
+        readonly constraint: {
+            readonly type: "integer";
+            readonly minimum: 0;
+            readonly maximum: 59;
+        };
+    };
+    readonly "schedule.time_format_invalid": {
+        readonly expected: "string matching ^\\d{2}:\\d{2}$ (24h)";
+        readonly hint: "recurrenceRule.time is 24-hour HH:MM local to the rule's timezone — e.g. '09:00', '21:30'. No seconds, no AM/PM, no offset.";
+        readonly skillAnchor: "recurring#time";
+        readonly docsUrl: "agent-assets/skills/schedule/references/errors.md#time_format_invalid";
+        readonly constraint: {
+            readonly type: "string";
+            readonly pattern: "^\\d{2}:\\d{2}$";
+        };
+    };
+    readonly "schedule.days_of_week_invalid": {
+        readonly expected: "non-empty array of distinct integers in [0, 6]";
+        readonly hint: "daysOfWeek is required for frequency='weekly' and forbidden otherwise. Integers 0..6 map to Sun..Sat (see validValues.labels). Duplicates are rejected at the schema layer — a duplicate is always a caller bug, never intent. Example: [1,3,5] = Mon/Wed/Fri.";
+        readonly skillAnchor: "recurring#weekly";
+        readonly docsUrl: "agent-assets/skills/schedule/references/errors.md#days_of_week_invalid";
+        readonly constraint: {
+            readonly type: "array";
+            readonly minimum: 1;
+            readonly maximum: 7;
+        };
+    };
+    readonly "schedule.days_of_month_invalid": {
+        readonly expected: "non-empty array of distinct integers in [1, 31]";
+        readonly hint: "daysOfMonth is required for frequency='monthly' and forbidden otherwise. Integers 1..31. Duplicates are rejected. Days 29-31 may fall outside short months — control the behavior via `onMissingDay` ('skip' to drop those months, 'lastDayOfMonth' to fire on the actual last day instead).";
+        readonly skillAnchor: "recurring#monthly";
+        readonly docsUrl: "agent-assets/skills/schedule/references/errors.md#days_of_month_invalid";
+        readonly constraint: {
+            readonly type: "array";
+            readonly minimum: 1;
+            readonly maximum: 31;
+        };
+    };
+    readonly "schedule.on_missing_day_unknown": {
+        readonly expected: "'skip' | 'lastDayOfMonth' (or omit; defaults to 'lastDayOfMonth')";
+        readonly hint: "onMissingDay only applies to frequency='monthly'. 'skip' drops months that don't contain the requested day (e.g. [31] skips Feb/Apr/Jun/Sep/Nov). 'lastDayOfMonth' fires on the actual last day of those months instead (the bit-compatible default — preserves the pre-redesign clamp behavior).";
+        readonly skillAnchor: "recurring#on-missing-day";
+        readonly docsUrl: "agent-assets/skills/schedule/references/errors.md#on_missing_day_unknown";
+        readonly constraint: {
+            readonly type: "enum";
+            readonly enum: readonly ["skip", "lastDayOfMonth"];
+        };
+    };
+    readonly "schedule.on_missing_day_unused": {
+        readonly expected: "onMissingDay omitted, OR daysOfMonth contains 29, 30, or 31";
+        readonly hint: "You set `onMissingDay` but `daysOfMonth` has no entry in [29, 30, 31] — the field has no effect because every month already contains the requested day. Either drop `onMissingDay` to keep the row clean, or extend `daysOfMonth` (e.g. add 31 if this is meant to be a month-end rule).";
+        readonly skillAnchor: "recurring#on-missing-day";
+        readonly docsUrl: "agent-assets/skills/schedule/references/errors.md#on_missing_day_unused";
+        readonly severity: "warning";
+    };
+    readonly "schedule.timezone_unknown": {
+        readonly expected: "valid IANA timezone string";
+        readonly hint: "recurrenceRule.timezone must parse via Intl.DateTimeFormat with a real IANA zone (e.g. 'Asia/Tokyo', 'America/New_York', 'UTC'). When omitted, the daemon falls back to the configured primary timezone, then the system zone.";
+        readonly skillAnchor: "recurring#timezone";
+        readonly docsUrl: "agent-assets/skills/schedule/references/errors.md#timezone_unknown";
+        readonly constraint: {
+            readonly type: "string";
+        };
+    };
+    readonly "schedule.recurrence_rule_invalid": {
+        readonly expected: "well-formed RecurrenceRule object";
+        readonly hint: "recurrenceRule must be an object with `frequency` plus the per-frequency fields. The route emits more specific codes (schedule.frequency_unknown / schedule.frequency_field_mismatch / schedule.time_format_invalid / …) when it can identify the offending field; this fallback fires on structurally-invalid bodies the Zod traversal could not localise.";
+        readonly skillAnchor: "recurring#shape";
+        readonly docsUrl: "agent-assets/skills/schedule/references/errors.md#recurrence_rule_invalid";
+    };
+    readonly "schedule.recurring_id_invalid": {
+        readonly expected: "positive integer id";
+        readonly hint: "The id path segment must parse as a positive integer. Use the value returned by POST /api/recurring-schedules (item.id), not a slug or 0.";
+        readonly skillAnchor: "recurring#identifiers";
+        readonly docsUrl: "agent-assets/skills/schedule/references/errors.md#recurring_id_invalid";
+        readonly legacyErrorCode: "invalid_id";
+        readonly constraint: {
+            readonly type: "integer";
+            readonly minimum: 1;
+        };
+    };
+    readonly "schedule.recurring_not_found": {
+        readonly expected: "recurring schedule id that exists";
+        readonly hint: "No recurring schedule exists with this id. List /api/recurring-schedules to see the current rows, or POST a new one. Deleted rows are gone permanently — the table does not soft-delete.";
+        readonly skillAnchor: "recurring#identifiers";
+        readonly docsUrl: "agent-assets/skills/schedule/references/errors.md#recurring_not_found";
+        readonly legacyErrorCode: "not_found";
+    };
+    readonly "schedule.recurring_no_changes": {
+        readonly expected: "at least one field set on the PATCH body";
+        readonly hint: "An empty PATCH body is rejected — supply at least one of `description`, `prompt`, `recurrenceRule`, `model`, `tier`, `taskContext`, `enabled`. PATCH does not re-materialize the already-pending agent_schedule row unless you change `recurrenceRule` or `enabled`.";
+        readonly skillAnchor: "recurring#patch-semantics";
+        readonly docsUrl: "agent-assets/skills/schedule/references/errors.md#recurring_no_changes";
+    };
+    readonly "agent_actions.session_identity_missing": {
+        readonly expected: "x-pa-event-correlation-id and x-process-key headers identifying the running session";
+        readonly hint: "The pa-api shim auto-injects these from PA_EVENT_CORRELATION_ID and PA_PROCESS_KEY when running inside a dispatcher-spawned session. If you are calling this endpoint directly from the dashboard or a test, supply both headers explicitly.";
+        readonly skillAnchor: "agent-actions#self-write-auth";
+        readonly retryable: false;
+    };
+    readonly "agent_actions.session_row_not_found": {
+        readonly expected: "an in-flight agent_actions row matching (event_id, action_type)";
+        readonly hint: "No row was found for the running session's correlation id + process key. Either the dispatcher has not yet inserted the row, or the row's result column is already terminal (success/failed). Verify the dispatcher writes an in_progress row before launching the session.";
+        readonly skillAnchor: "agent-actions#self-write-auth";
+        readonly retryable: false;
+    };
+    readonly "agent_actions.metadata_field_invalid": {
+        readonly expected: "object with optional dayType/anomalies/filesTouched/inboxStats/scheduleBatchSize";
+        readonly hint: "The metadata body slot is shallow-merged into the row's metadata column. Pass an object literal; arrays go inside named keys (e.g. anomalies:[...]). Non-JSON-serialisable values (functions, Symbols) are rejected.";
+        readonly skillAnchor: "agent-actions#metadata-shape";
+        readonly constraint: {
+            readonly type: "object";
+            readonly required: true;
+        };
+    };
+    readonly "agent_actions.body_not_object": {
+        readonly expected: "JSON object";
+        readonly hint: "Body must be {\"metadata\":{…}}. The metadata key is required; other top-level keys are ignored.";
+        readonly skillAnchor: "agent-actions#metadata-shape";
+        readonly constraint: {
+            readonly type: "object";
+            readonly required: true;
+        };
+    };
+    readonly "context.path_invalid": {
+        readonly expected: "context-relative path within the allowed write whitelist";
+        readonly hint: "The path failed safePath(): it escaped getContextDir() or pointed outside the allowed file set. Use a path like 'state/today', 'plans/roadmap', 'plans/projects/<slug>', 'identity/profile' — no '..', no absolute paths. Read GET /api/context/list/plans/projects to discover live slugs.";
+        readonly skillAnchor: "context#allowed-paths";
+        readonly legacyErrorCode: "invalid_path";
+        readonly constraint: {
+            readonly type: "string";
+        };
+    };
+    readonly "context.path_required": {
+        readonly expected: "non-empty 'path' query / route parameter";
+        readonly hint: "The endpoint needs a context path (e.g. 'state/today', 'plans/projects/launch-prep'). For wildcard read/write routes the path is the URL tail after /api/context/; for snapshot restore the path is captured from the snapshot row.";
+        readonly skillAnchor: "context#allowed-paths";
+        readonly legacyErrorCode: "path_required";
+        readonly constraint: {
+            readonly type: "string";
+            readonly required: true;
+        };
+    };
+    readonly "context.path_not_found": {
+        readonly expected: "an existing context MD file at the resolved path";
+        readonly hint: "GET / PATCH / DELETE on a path that does not exist on disk. Use GET /api/context/list/plans/projects (or .../list/policies) to discover available paths, or PUT first to create the file.";
+        readonly skillAnchor: "context#allowed-paths";
+        readonly legacyErrorCode: "not_found";
+        readonly retryable: false;
+    };
+    readonly "context.write_forbidden": {
+        readonly expected: "path inside the daemon's write whitelist";
+        readonly hint: "This file is read-only from the agent side. The whitelist covers state/today, plans/roadmap, plans/projects/*, policies/management-captures/*, identity/*, journal/agent, state/profile-questions, journal/weekly/*, journal/monthly/*, knowledge/dossiers/*, knowledge/entities/<domain>/<type-plural>/* (e.g. knowledge/entities/work/meetings/<slug>), research/* (browser-history cluster journals), state/inbox/*, state/scratch/*, and policies/routines/custom/*. Legacy paths (today.md, roadmap.md, user/*, rules/*, agent/journal) are server-side aliased for one minor release but the canonical names above are the future contract. Files outside this set are owned by the daemon or operator — GET /api/context/list/plans/projects to find a writable parent, or NOTIFY the user.";
+        readonly skillAnchor: "context#write-whitelist";
+        readonly legacyErrorCode: "forbidden";
+        readonly retryable: false;
+    };
+    readonly "context.lock_held": {
+        readonly expected: "morning-routine lock not held by another holder";
+        readonly hint: "Another session is currently running the morning routine. Wait for it to finish (the holder block in the response carries the lockId and acquiredAt). Acquire-lock requests on a held lock return 409.";
+        readonly skillAnchor: "context#locks";
+        readonly legacyErrorCode: "lock_held";
+        readonly retryable: true;
+    };
+    readonly "context.lock_not_held": {
+        readonly expected: "valid lockId held by this caller";
+        readonly hint: "Release was rejected — the lockId in the body did not match the current holder. The release contract is single-shot: each acquire returns exactly one lockId; releasing twice or releasing without the id returns 400. If the dispatcher did not capture the id, re-acquire and immediately release.";
+        readonly skillAnchor: "context#locks";
+        readonly legacyErrorCode: "lock_not_held";
+        readonly retryable: false;
+    };
+    readonly "context.morning_routine_lock_held": {
+        readonly expected: "morning_routine lock released OR X-Lock-Id matching the holder";
+        readonly hint: "today.md write rejected because the morning routine is in progress. If you are the routine, pass X-Lock-Id: <id> with the lockId from POST /context/lock/morning-routine. If you are not the routine, wait for it to finish (typically <2 minutes) and retry.";
+        readonly skillAnchor: "context#locks";
+        readonly legacyErrorCode: "morning_routine_lock_held";
+        readonly retryable: true;
+    };
+    readonly "context.roadmap_write_lock_held": {
+        readonly expected: "roadmap write lock released OR X-Lock-Id matching the holder";
+        readonly hint: "roadmap.md write rejected because another flow is currently rewriting roadmap. Pass X-Lock-Id: <id> from POST /context/lock/roadmap if you acquired it, or wait for the holder (typically routine.roadmap_refresh) to finish.";
+        readonly skillAnchor: "context#locks";
+        readonly legacyErrorCode: "roadmap_write_lock_held";
+        readonly retryable: true;
+    };
+    readonly "context.body_not_object": {
+        readonly expected: "JSON object body";
+        readonly hint: "PUT / PATCH / lock-release / archive-today bodies must be a JSON object. Wrap your payload in '{}'. An empty body is rejected by PUT (content required) but accepted by lock-release as a no-op.";
+        readonly skillAnchor: "context#request-shape";
+        readonly legacyErrorCode: "validation_error";
+        readonly constraint: {
+            readonly type: "object";
+            readonly required: true;
+        };
+    };
+    readonly "context.invalid_body_field": {
+        readonly expected: "field value matching the route schema";
+        readonly hint: "One or more body fields failed schema validation. Inspect the per-issue `field` (Zod path) and `received` (the value you sent) plus `validValues` for enum fields. For PATCH /api/context/<path> the shape is {section, mode: 'append'|'replace'|'clear'|'clear_before'|'append_to_file', content?, cutoff?, maxEntries?}; for PUT it is {content}. For append-only files like journal/agent.md prefer mode='append_to_file' (section optional).";
+        readonly skillAnchor: "context#request-shape";
+        readonly legacyErrorCode: "validation_error";
+    };
+    readonly "context.invalid_json_body": {
+        readonly expected: "syntactically valid JSON";
+        readonly hint: "Body failed JSON.parse(). Check for trailing commas, single quotes, or unescaped newlines in string content. Use jq -nc for compact valid JSON before piping into curl --data-binary.";
+        readonly skillAnchor: "context#request-shape";
+        readonly legacyErrorCode: "invalid_json_body";
+    };
+    readonly "context.snapshot_id_invalid": {
+        readonly expected: "positive safe integer matching md_file_snapshots.id";
+        readonly hint: "Snapshot id must be a positive integer (no decimals, no scientific notation). GET /api/context/snapshots/:path to list available snapshot ids.";
+        readonly skillAnchor: "context#snapshots";
+        readonly legacyErrorCode: "invalid_id";
+        readonly constraint: {
+            readonly type: "integer";
+            readonly minimum: 1;
+        };
+    };
+    readonly "context.snapshot_not_found": {
+        readonly expected: "an existing row in md_file_snapshots";
+        readonly hint: "No snapshot exists with that id. Snapshots are pruned over time — verify the id from a fresh GET /api/context/snapshots/:path before restoring.";
+        readonly skillAnchor: "context#snapshots";
+        readonly legacyErrorCode: "not_found";
+        readonly retryable: false;
+    };
+    readonly "context.roadmap_id_generation_failed": {
+        readonly expected: "successful id generation after collision retries";
+        readonly hint: "The daemon exhausted retries trying to mint a non-colliding 4-char suffix for the roadmap id. This indicates an unusually full roadmap day or a corrupt randomBytes injection. Retry once; if it fails again, file an issue — DO NOT manually mint an id, the IDs must be daemon-issued so audit hooks fire.";
+        readonly skillAnchor: "context#roadmap-ids";
+        readonly legacyErrorCode: "roadmap_id_generation_failed";
+        readonly retryable: true;
+    };
+    readonly "context.creation_date_invalid": {
+        readonly expected: "YYYY-MM-DD calendar date string";
+        readonly hint: "Roadmap-id creationDate must be a calendar date in YYYY-MM-DD form (no time component). Use localDateStr(now, <timezone>) shape; omit the field entirely to let the daemon stamp it from config.timezone.";
+        readonly skillAnchor: "context#roadmap-ids";
+        readonly legacyErrorCode: "validation_error";
+        readonly constraint: {
+            readonly type: "string";
+            readonly pattern: "^\\d{4}-\\d{2}-\\d{2}$";
+        };
+    };
+    readonly "context.directory_invalid": {
+        readonly expected: "directory listed in the allowed-directory set";
+        readonly hint: "Directory listings are restricted to the curated allow-list returned in the 400 response's `allowed` field (e.g. 'plans/projects', 'policies/management-captures', 'identity', 'knowledge/dossiers'). Pick from that list — wildcards and absolute paths are rejected.";
+        readonly skillAnchor: "context#allowed-paths";
+        readonly legacyErrorCode: "invalid_directory";
+    };
+    readonly "context.content_validation_failed": {
+        readonly expected: "content matching the file's schema (today/roadmap/projects/...)";
+        readonly hint: "The body content failed validateContextContent(). The response's `message` field carries the specific reason: today.md H1 date mismatch, frontmatter shape, roadmap row schema, project doc skeleton, etc. Read the message verbatim and adjust the offending section — do NOT retry without changing the content.";
+        readonly skillAnchor: "context#content-validation";
+        readonly legacyErrorCode: "validation_error";
+    };
+    readonly "context.daily_skeleton_field_drift": {
+        readonly expected: "skeleton-owned frontmatter field present and well-typed";
+        readonly hint: "A required skeleton-owned frontmatter field is missing or malformed on the daily/<date>.md write. The errors array carries one entry per offending field with the exact `received` value and the `expected` shape. Re-emit the file with the missing fields restored from the `<journal_skeleton>` you were given — the skeleton's frontmatter is preserved byte-for-byte; do not paraphrase it. Body authoring is yours per rules/journal-format.md.";
+        readonly skillAnchor: "context#daily-skeleton-fields";
+        readonly legacyErrorCode: "daily_skeleton_drift";
+        readonly retryable: true;
+    };
+    readonly "context.vault_unreachable": {
+        readonly expected: "primary vault filesystem reachable";
+        readonly hint: "The vault path resolved by config.primaryVault is currently unreachable (mount lost, drive not present, etc.). Reads work; writes are blocked until the path returns. Surface the situation to the operator — do NOT retry blindly. See `state.reason` and `state.path` in the response for details.";
+        readonly skillAnchor: "context#vault-degraded";
+        readonly legacyErrorCode: "primary_vault_unreachable";
+        readonly retryable: false;
+    };
+    readonly "context.migration_in_progress": {
+        readonly expected: "no /api/setup/migrate-context run in flight";
+        readonly hint: "Context writes are temporarily globally blocked because the setup migration is moving the data directory. Wait until the migration completes (typically <10s for normal installs; up to a minute for large vaults) and retry. Reads remain available.";
+        readonly skillAnchor: "context#migration-gate";
+        readonly legacyErrorCode: "migration_in_progress";
+        readonly retryable: true;
+    };
+    readonly "context.stub_target_unsupported": {
+        readonly expected: "one of the REPAIRABLE_STUB_TARGETS paths";
+        readonly hint: "POST /api/context/repair-stub only accepts a curated allow-list of paths (e.g. 'policies/management-captures/_index', 'identity/_index'). The response's expected list (if surfaced) or the REPAIRABLE_STUB_TARGETS constant in context-health.ts is authoritative. For any other file, PUT the content directly via /api/context/<path>.";
+        readonly skillAnchor: "context#stub-repair";
+        readonly legacyErrorCode: "unsupported_stub_target";
+        readonly retryable: false;
+    };
+    readonly "context.template_unavailable": {
+        readonly expected: "agent-assets/templates directory resolvable";
+        readonly hint: "Skeleton template root unresolved on this install — typically a setup-time misconfiguration (agent-assets/ not bundled, or PA_DATA_DIR points at a wrong tree). The agent has no recovery path here: skip the stub-repair step, continue the routine with the unrepaired stub, and surface ONE notification to the user suggesting `aitne doctor`. Do NOT loop on this code.";
+        readonly skillAnchor: "context#stub-repair";
+        readonly legacyErrorCode: "templates_unavailable";
+        readonly retryable: false;
+    };
+    readonly "context.template_not_found": {
+        readonly expected: "matching template file under agent-assets/templates/";
+        readonly hint: "No skeleton template exists for the requested stub path. Either the path you passed is wrong, or this particular stub doesn't have a template (and should be authored directly). Check REPAIRABLE_STUB_TARGETS for the supported set.";
+        readonly skillAnchor: "context#stub-repair";
+        readonly legacyErrorCode: "template_not_found";
+        readonly retryable: false;
+    };
+    readonly "context.append_only_violation": {
+        readonly expected: "section header retained — only body content may change";
+        readonly hint: "This file is append-only (e.g. agent/journal.md uses mode='append_to_file' or mode='append'). PATCH replace/clear modes are rejected. Use mode='append' or mode='append_to_file' to add content; never overwrite past entries.";
+        readonly skillAnchor: "context#patch-modes";
+        readonly legacyErrorCode: "append_only";
+        readonly retryable: false;
+    };
+    readonly "context.write_conflict": {
+        readonly expected: "If-Match / parent revision matching current on-disk state";
+        readonly hint: "PATCH rejected — the file changed since you fetched it. Recovery in 3 steps: (1) GET /api/context/<path> again and capture the new `ETag` response header; (2) re-derive your patch against the fresh content (section may have moved, bullets may have been added); (3) re-PATCH with `If-Match: <new ETag>`. Bare curl without the If-Match header always 409s on tracked files (today.md, roadmap.md, projects/*). If the conflict repeats twice on the same field, another writer is racing — wait 10s before the third attempt, or fall back to mode='append_to_file' to dodge the section-level conflict entirely.";
+        readonly skillAnchor: "context#write-conflict";
+        readonly legacyErrorCode: "conflict";
+        readonly retryable: true;
+    };
+    readonly "context.unsupported_operation": {
+        readonly expected: "endpoint capable of handling this file extension";
+        readonly hint: "PATCH is unsupported for .base files — they are full-replace only. Use PUT /api/context/<path>.base with the complete new content instead. Other operation/file combinations carry their own message in the response.";
+        readonly skillAnchor: "context#file-extensions";
+        readonly legacyErrorCode: "unsupported_operation";
+        readonly retryable: false;
+    };
+    readonly "context.section_not_found": {
+        readonly expected: "matching ## heading in the file";
+        readonly hint: "PATCH targeted a section heading that does not exist in the file. Section matching rules: case-sensitive, exact literal '## <name>' (the leading `## ` and a single space are mandatory; '##  X' with two spaces, '### X' deeper, or '##X' tight all miss). Recovery in order: (1) GET the file and read the current ## headings — pick the actual one verbatim; (2) if the section truly belongs in a new heading, use mode='append_to_file' with the heading included in `content` (e.g. `\\n## New Section\\n<body>`); (3) for structural rewrites, PUT the full file body. Do not approximate the heading — title-cased / pluralised guesses keep missing.";
+        readonly skillAnchor: "context#patch-modes";
+        readonly legacyErrorCode: "section_not_found";
+        readonly retryable: false;
+    };
+    readonly "context.cutoff_required": {
+        readonly expected: "ISO date string under 'cutoff' when mode='clear_before'";
+        readonly hint: "mode='clear_before' requires a cutoff date so the daemon knows which dated bullets to drop. Use YYYY-MM-DD (or a full ISO timestamp); rows with a stamp older than cutoff are removed.";
+        readonly skillAnchor: "context#patch-modes";
+        readonly legacyErrorCode: "cutoff_required";
+        readonly constraint: {
+            readonly type: "iso8601";
+            readonly required: true;
+        };
+    };
+    readonly "obsidian.not_configured": {
+        readonly expected: "external Obsidian vault configured in setup";
+        readonly hint: "No external Obsidian vault is configured for this install — `externalObsidianVaultPath`/`externalObsidianVaultName` are unset. Stop calling /api/obsidian/* in this session; either route the work to /api/wiki/* (internal vault), /api/context/* (management store), or notify the user that Obsidian is not configured. GET /api/health → integrationStatuses.obsidian for the live state.";
+        readonly skillAnchor: "obsidian-vault-rules#external-vault-setup";
+        readonly legacyErrorCode: "obsidian_not_configured";
+        readonly retryable: false;
+    };
+    readonly "obsidian.not_running": {
+        readonly expected: "Obsidian.app process running on the host";
+        readonly hint: "The Obsidian CLI requires the Obsidian desktop app to be running (Catalyst feature). Notify the user that Obsidian is not running and ask them to launch it, then retry after they confirm. Do NOT silently retry — there is no automatic recovery path.";
+        readonly skillAnchor: "obsidian-vault-rules#obsidian-must-be-running";
+        readonly legacyErrorCode: "obsidian_not_running";
+        readonly retryable: false;
+    };
+    readonly "obsidian.invalid_path": {
+        readonly expected: "vault-relative path: word chars / spaces / hyphens / dots / forward slashes, no '..', no leading '/'";
+        readonly hint: "Vault paths reject `..`, absolute paths, and characters outside `[a-z0-9 _\\-./CJK]`. Use 'folder/subfolder/My Note' shape (no leading slash, no .md extension required for the CLI). Search via GET /api/obsidian/search?q=… to discover a real path before writing.";
+        readonly skillAnchor: "obsidian-vault-rules#path-rules";
+        readonly legacyErrorCode: "invalid file path";
+        readonly constraint: {
+            readonly type: "string";
+            readonly maxLength: 500;
+        };
+    };
+    readonly "obsidian.invalid_note_name": {
+        readonly expected: "vault-relative note name: same rules as path";
+        readonly hint: "Note names for create take the same shape as paths: no '..', no leading '/', characters limited to `[a-z0-9 _\\-./CJK]`. Use 'Daily/2026-05-15' or 'My Note' — the CLI appends .md automatically.";
+        readonly skillAnchor: "obsidian-vault-rules#path-rules";
+        readonly legacyErrorCode: "invalid note name";
+        readonly constraint: {
+            readonly type: "string";
+            readonly maxLength: 500;
+        };
+    };
+    readonly "obsidian.name_and_content_required": {
+        readonly expected: "both 'name' (string) and 'content' (string) in the JSON body";
+        readonly hint: "POST /api/obsidian/notes requires `{ name: '<vault-path>', content: '<markdown>' }`. Both fields are mandatory and must be non-empty strings. To create an empty note, pass content: '' (empty string), not omit the field.";
+        readonly skillAnchor: "obsidian-vault-rules#create-note";
+        readonly legacyErrorCode: "name and content are required";
+        readonly constraint: {
+            readonly type: "object";
+            readonly required: true;
+        };
+    };
+    readonly "obsidian.content_required": {
+        readonly expected: "'content' string in the JSON body";
+        readonly hint: "PUT / PATCH /api/obsidian/notes endpoints require `{ content: '<markdown>' }`. Pass an empty string to clear content; omitting the field is a different error. PATCH /obsidian/notes also needs `file`; PATCH /obsidian/daily only needs `content`.";
+        readonly skillAnchor: "obsidian-vault-rules#update-note";
+        readonly legacyErrorCode: "content is required";
+        readonly constraint: {
+            readonly type: "string";
+            readonly required: true;
+        };
+    };
+    readonly "obsidian.file_and_content_required": {
+        readonly expected: "both 'file' (vault path) and 'content' (string) in the JSON body";
+        readonly hint: "PATCH /api/obsidian/notes (append) requires `{ file: '<vault-path>', content: '<markdown to append>' }`. Use PATCH /api/obsidian/daily (no `file`) to append to today's daily note instead.";
+        readonly skillAnchor: "obsidian-vault-rules#append-note";
+        readonly legacyErrorCode: "file and content are required";
+        readonly constraint: {
+            readonly type: "object";
+            readonly required: true;
+        };
+    };
+    readonly "obsidian.query_required": {
+        readonly expected: "non-empty 'q' query parameter";
+        readonly hint: "GET /api/obsidian/search?q=<term> needs a non-empty query string. The Obsidian CLI search is FTS-style — pass a phrase, tag like `#project`, or path fragment. Empty string is rejected; use the notes endpoint for path-only enumeration.";
+        readonly skillAnchor: "obsidian-vault-rules#search";
+        readonly legacyErrorCode: "query parameter 'q' is required";
+        readonly constraint: {
+            readonly type: "string";
+            readonly required: true;
+            readonly minLength: 1;
+        };
+    };
+    readonly "obsidian.not_found": {
+        readonly expected: "an existing note at the resolved vault path";
+        readonly hint: "The note does not exist. The Obsidian CLI collapses 'no such note' and 'read failure' into one error — GET /api/obsidian/search?q=<word-from-title> to discover the correct path, then retry. Do NOT keep retrying the same path.";
+        readonly skillAnchor: "obsidian-vault-rules#read-note";
+        readonly legacyErrorCode: "not_found";
+        readonly retryable: false;
+    };
+    readonly "obsidian.upstream_error": {
+        readonly expected: "successful Obsidian CLI invocation";
+        readonly hint: "Obsidian CLI returned a non-zero error. `message` is the raw CLI stderr — read it before retrying. Branches: 'note locked' / 'vault busy' → another writer is mid-flight, wait 5s and retry ONCE; 'note has unsaved changes' → the note is open in the Obsidian UI with edits the CLI refuses to overwrite, notify the user with 'Please save or close <path> in Obsidian, then retry' and skip this write; 'unauthorized' / 'token expired' → CLI auth lost, notify with 'Re-link Obsidian CLI: open Obsidian → Settings → Catalyst → CLI → regenerate token' and stop calling /api/obsidian/* this turn; 'plugin not running' → user closed Obsidian, see obsidian.not_running. Do NOT loop without changing call shape.";
+        readonly skillAnchor: "obsidian-vault-rules#errors";
+        readonly legacyErrorCode: "obsidian_error";
+        readonly retryable: true;
+    };
+    readonly "calendar.not_configured": {
+        readonly expected: "Google Calendar configured (direct mode) on this install";
+        readonly hint: "Google Calendar is not configured for direct access — either OAuth is not set up, the service is disabled, or the integration is in delegated/native mode (in which case the route is already 410-gated). Notify the user that calendar is unavailable and skip the calendar branch of the routine. GET /api/health.integrationStatuses.google.services.calendar shows the live state.";
+        readonly skillAnchor: "calendar#configuration";
+        readonly legacyErrorCode: "calendar_not_configured";
+        readonly retryable: false;
+    };
+    readonly "calendar.invalid_date_format": {
+        readonly expected: "'today' or YYYY-MM-DD date string";
+        readonly hint: "The `date` query parameter must be the literal 'today' or a calendar date like '2026-05-15'. Other shapes (ISO timestamps, '5/15/26', RFC-3339) are rejected. Use localDateStr(now, <timezone>) shape.";
+        readonly skillAnchor: "calendar#list-events";
+        readonly legacyErrorCode: "invalid date format — expected YYYY-MM-DD or 'today'";
+        readonly constraint: {
+            readonly type: "string";
+            readonly pattern: "^(today|\\d{4}-\\d{2}-\\d{2})$";
+            readonly required: true;
+        };
+    };
+    readonly "calendar.invalid_send_updates": {
+        readonly expected: "one of 'all' | 'externalOnly' | 'none'";
+        readonly hint: "The `sendUpdates` query parameter controls invite emails. Pass 'none' (silent — typical for batch agent edits), 'externalOnly' (notify external attendees but not internal), or 'all' (notify everyone). Omit the param to default to 'none'.";
+        readonly skillAnchor: "calendar#sendUpdates";
+        readonly legacyErrorCode: "invalid sendUpdates — must be 'all', 'externalOnly', or 'none'";
+        readonly constraint: {
+            readonly type: "enum";
+            readonly enum: readonly ["all", "externalOnly", "none"];
+        };
+    };
+    readonly "calendar.not_found": {
+        readonly expected: "an existing event at the supplied calendarId + eventId";
+        readonly hint: "Google returned 404 for this event. The event may have been deleted by another client, or the eventId is wrong. Re-list with GET /api/calendar/events?date=<day> to find the current id, or skip if the event no longer exists.";
+        readonly skillAnchor: "calendar#event-id";
+        readonly legacyErrorCode: "not_found";
+        readonly retryable: false;
+    };
+    readonly "calendar.upstream_error": {
+        readonly expected: "successful Google Calendar API call";
+        readonly hint: "Google Calendar returned an error. `message` is Google's verbatim text. Branches: 429 / 'rateLimitExceeded' / 'userRateLimitExceeded' → backoff 60s and retry ONCE, then skip calendar for this turn. 412 / 'preconditionFailed' → another client edited the event between your GET and PATCH; GET the event again to refresh the etag and replay the same change ONCE. 401 / 'authError' → OAuth refresh token revoked or expired; notify the user to re-link Google in /settings/integrations and skip — agent cannot refresh interactively. 403 / 'insufficientPermissions' → the integration scope was downgraded; same fix as 401. 404 → event was deleted between your last list and this call; drop it and continue. Cap retries at one per code per turn.";
+        readonly skillAnchor: "calendar#errors";
+        readonly legacyErrorCode: "calendar_error";
+        readonly retryable: true;
+    };
+    readonly "calendar.validation_error": {
+        readonly expected: "request body matching the calendar event schema";
+        readonly hint: "Body failed Zod validation. The response's `details` array carries per-field issues — read each `path` + `message` and fix. Common issues: start/end must be `{ dateTime: ISO, timeZone: 'IANA/Name' }` OR `{ date: 'YYYY-MM-DD' }` (all-day), not both; attendees must be array of `{ email }` objects.";
+        readonly skillAnchor: "calendar#event-shape";
+        readonly legacyErrorCode: "validation_error";
+    };
+    readonly "calendar.outlook_not_configured": {
+        readonly expected: "an active Outlook mail account (calendar reuses its MSAL token)";
+        readonly hint: "Outlook Calendar piggybacks on the first active Outlook mail account's MSAL token. Either no Outlook account is set up, or the cached token can't acquire Calendars.ReadWrite. Notify the user to add an Outlook account in /settings/mail and confirm calendar scopes were granted.";
+        readonly skillAnchor: "calendar#outlook-setup";
+        readonly legacyErrorCode: "outlook_not_configured";
+        readonly retryable: false;
+    };
+    readonly "calendar.outlook_disabled": {
+        readonly expected: "outlook_calendar integration mode != 'disabled'";
+        readonly hint: "Outlook Calendar is set to 'disabled' in /settings/integrations. Skip the calendar branch for Outlook routines. Don't re-enable from the agent side — the user controls integration modes via the dashboard.";
+        readonly skillAnchor: "calendar#outlook-mode";
+        readonly legacyErrorCode: "outlook_calendar_disabled";
+        readonly retryable: false;
+    };
+    readonly "calendar.outlook_delegated": {
+        readonly expected: "outlook_calendar integration mode = 'direct' for this route";
+        readonly hint: "Outlook Calendar is in 'delegated' mode — direct reads are blocked. Route cross-backend work through POST /api/integrations/outlook_calendar/exec (task-mode chokepoint; the legacy /invoke RPC was retired) or wait for the delegated sync worker's next cadence to land observations.";
+        readonly skillAnchor: "calendar#outlook-mode";
+        readonly legacyErrorCode: "outlook_calendar_delegated";
+        readonly retryable: false;
+    };
+    readonly "wiki.not_enabled": {
+        readonly expected: "an active wiki_workspaces row matching the URL workspace name";
+        readonly hint: "The wiki is opt-in; either no workspace named `<workspace>` exists, or it has `active=0`. Use GET /api/wiki/workspaces to list available workspaces. To enable, open /settings/wiki in the dashboard and click 'Enable Wiki' — the agent cannot enable it.";
+        readonly skillAnchor: "wiki-vault-rules#enable";
+        readonly legacyErrorCode: "wiki_not_enabled";
+        readonly retryable: false;
+    };
+    readonly "wiki.workspace_not_found": {
+        readonly expected: "an existing workspace row, including archived ones for DELETE/PATCH";
+        readonly hint: "No workspace named `<workspace>` exists at all (not even archived). GET /api/wiki/workspaces to list ids and names. To create the default workspace, POST /api/wiki/workspaces with an empty body.";
+        readonly skillAnchor: "wiki-vault-rules#workspace-crud";
+        readonly legacyErrorCode: "not_found";
+        readonly retryable: false;
+    };
+    readonly "wiki.invalid_body": {
+        readonly expected: "request body matching the workspace/file/bridge zod schema";
+        readonly hint: "Body failed Zod validation. The response's `issues` array carries per-field paths — read each `path`/`message` and fix that field exactly. Common shapes by endpoint: (a) POST /wiki/workspaces external — `{ kind: 'external', rootPath: '<abs>', language?, name? }`; (b) POST /wiki/<ws>/files — `{ path: '<layer>/<slug>.md', content: '<markdown>', frontmatter? }`; (c) PATCH /wiki/<ws>/files/<path> — `{ content: '<markdown>' }`; (d) bridge proposals — `{ rawPath, wikiPath, confidence: 0-1, evidence: string }`. Do NOT retry without changing the listed fields.";
+        readonly skillAnchor: "wiki-vault-rules#schemas";
+        readonly legacyErrorCode: "invalid_body";
+    };
+    readonly "wiki.invalid_root_path": {
+        readonly expected: "writable directory outside primary vault / external obsidian / dataDir / other wiki";
+        readonly hint: "Wiki root path validation rejects paths that overlap with the management vault, the external Obsidian vault, the daemon's data dir, or another active wiki workspace. POST /api/fs/probe?path=<absolute> first to see which collision applies, then pick a sibling path.";
+        readonly skillAnchor: "wiki-vault-rules#root-path";
+        readonly legacyErrorCode: "invalid_root_path";
+        readonly retryable: false;
+    };
+    readonly "wiki.invalid_json": {
+        readonly expected: "syntactically valid JSON body or empty body";
+        readonly hint: "POST /api/wiki/workspaces accepts either no body (default-workspace quick path) or a JSON object — anything else fails JSON.parse(). Check for trailing commas, single quotes, or unescaped newlines.";
+        readonly skillAnchor: "wiki-vault-rules#workspace-crud";
+        readonly legacyErrorCode: "invalid_json";
+    };
+    readonly "wiki.append_only_raw": {
+        readonly expected: "POST to a new path in 10_raw/ (never overwrite)";
+        readonly hint: "Files in 10_raw/ are create-only (the source-of-truth layer). POSTing to an existing 10_raw/<slug>.md file is rejected. If you need to add to an existing source, append a new dated note under 30_outputs/ or create a 20_wiki/ article that links to it.";
+        readonly skillAnchor: "wiki-vault-rules#layer-rules";
+        readonly legacyErrorCode: "append_only";
+        readonly retryable: false;
+    };
+    readonly "wiki.append_only_log": {
+        readonly expected: "PATCH to log.md (POST overwrite is rejected)";
+        readonly hint: "log.md grows append-only via PATCH. POST overwrites are rejected once log.md exists. Use PATCH /api/wiki/<workspace>/files/log.md with `{ content: '<new line>' }` to add entries.";
+        readonly skillAnchor: "wiki-vault-rules#log";
+        readonly legacyErrorCode: "append_only";
+        readonly retryable: false;
+    };
+    readonly "wiki.raw_patch_forbidden": {
+        readonly expected: "POST (create) rather than PATCH for 10_raw/ files";
+        readonly hint: "10_raw/ files cannot be patched after creation — they are immutable sources. Use POST to create a new sibling note instead of mutating an existing one.";
+        readonly skillAnchor: "wiki-vault-rules#layer-rules";
+        readonly legacyErrorCode: "append_only";
+        readonly retryable: false;
+    };
+    readonly "wiki.invalid_path": {
+        readonly expected: "vault-relative path inside a known layer (00_inbox/10_raw/20_wiki/30_outputs/90_meta or log.md)";
+        readonly hint: "Wiki paths must live inside the four-layer schema. The classifier rejects unknown roots, paths containing '..' or '\\', and shapes that don't match the per-layer regex (e.g. 30_outputs/ requires `<YYYY-MM-DD>-<kind>-<slug>.md`). See wiki-vault-rules for the layer table.";
+        readonly skillAnchor: "wiki-vault-rules#path-shapes";
+        readonly legacyErrorCode: "invalid_path";
+    };
+    readonly "wiki.invalid_layer": {
+        readonly expected: "path classifying into a known layer";
+        readonly hint: "Path is well-formed but the leading directory doesn't match any of `00_inbox/`, `10_raw/`, `20_wiki/`, `30_outputs/`, `90_meta/`, or the bare `log.md`. Move the file under the right layer for its kind (raw source → 10_raw, article → 20_wiki, etc.).";
+        readonly skillAnchor: "wiki-vault-rules#layer-rules";
+        readonly legacyErrorCode: "invalid_layer";
+    };
+    readonly "wiki.file_not_found": {
+        readonly expected: "an existing file under the workspace root";
+        readonly hint: "GET on a wiki path that does not exist on disk. Use GET /api/wiki/<workspace>/index to list files, or GET /api/wiki/<workspace>/search?q=… to find it by title. POST first to create it if you intended a write.";
+        readonly skillAnchor: "wiki-vault-rules#read-file";
+        readonly legacyErrorCode: "not_found";
+        readonly retryable: false;
+    };
+    readonly "wiki.not_file": {
+        readonly expected: "the resolved path is a regular file";
+        readonly hint: "GET hit a directory rather than a file. Append the file name (e.g. `20_wiki/<slug>.md`) instead of the directory path.";
+        readonly skillAnchor: "wiki-vault-rules#read-file";
+        readonly legacyErrorCode: "not_file";
+        readonly retryable: false;
+    };
+    readonly "wiki.forbidden_missing_process_key": {
+        readonly expected: "x-process-key header on every wiki call";
+        readonly hint: "Wiki endpoints gate on `x-process-key` for layer-aware auth. The pa-api shim auto-injects this from `PA_PROCESS_KEY`; if you are calling outside a dispatcher session, supply the header explicitly (e.g. `x-process-key: wiki.compile` for compile, `wiki.ingest_url` for raw ingest, `message.dm` for bridge proposals).";
+        readonly skillAnchor: "wiki-vault-rules#process-keys";
+        readonly legacyErrorCode: "forbidden";
+        readonly retryable: false;
+    };
+    readonly "wiki.forbidden_read": {
+        readonly expected: "x-process-key with a `wiki.*` or DM-read prefix";
+        readonly hint: "GET on wiki files requires either a wiki-tier process key (`wiki.compile`, `wiki.ask`, …) or a DM-read process key (`message.dm`, `message.mention`, `dashboard.chat`). The agent's current process key did not match either set.";
+        readonly skillAnchor: "wiki-vault-rules#process-keys";
+        readonly legacyErrorCode: "forbidden";
+        readonly retryable: false;
+    };
+    readonly "wiki.forbidden_write": {
+        readonly expected: "process key authorized to write to this layer";
+        readonly hint: "Writes are layer-gated: `wiki.ingest_url` → 10_raw/; `wiki.compile` → 20_wiki/ + 90_meta/; `wiki.ask`/`wiki.trace`/`wiki.connect` → 30_outputs/; `wiki.lint` → 90_meta/health/. DM-tier callers can ONLY write bridge files in 10_raw/ AND only when both `bridge_enabled` and `dm_agent_write_enabled` are on. The `code` field disambiguates which gate failed.";
+        readonly skillAnchor: "wiki-vault-rules#process-keys";
+        readonly legacyErrorCode: "forbidden";
+        readonly retryable: false;
+    };
+    readonly "wiki.import_conflict": {
+        readonly expected: "no destination-side filename collisions in the existing vault";
+        readonly hint: "Import-migrate aborted because flattened filenames collide with existing files in 20_wiki/. The response's `conflicts` array lists each collision. Re-run with `?allowConflicts=true` to overwrite, or pre-rename the conflicting files in the source vault first.";
+        readonly skillAnchor: "wiki-vault-rules#import";
+        readonly legacyErrorCode: "import_conflict";
+        readonly retryable: true;
+    };
+    readonly "wiki.import_split_unsupported": {
+        readonly expected: "decision = 'adopt' or 'migrate'";
+        readonly hint: "The 'split' import decision is reserved for the multi-workspace phase and not yet implemented. Re-POST with `decision: 'adopt'` (keep source layout) or `decision: 'migrate'` (flatten to the standard schema).";
+        readonly skillAnchor: "wiki-vault-rules#import";
+        readonly legacyErrorCode: "import_split_unsupported";
+        readonly retryable: false;
+    };
+    readonly "fs.missing_path": {
+        readonly expected: "non-empty 'path' query parameter";
+        readonly hint: "GET /api/fs/probe?path=<absolute-path>. The path must be absolute (no `..`, no `~`) and is checked against the wiki/primary-vault collision matrix. POST /api/system/pick-directory is the OS-native picker — use it first to get a valid absolute path.";
+        readonly skillAnchor: "wiki-vault-rules#root-path-picker";
+        readonly legacyErrorCode: "missing_path";
+        readonly constraint: {
+            readonly type: "string";
+            readonly required: true;
+        };
+    };
+    readonly "fs.invalid_path": {
+        readonly expected: "absolute path that is not on the system blocklist";
+        readonly hint: "The path failed `normalizeRequestedPath()`: it was relative, contained `..` traversal, started with a system prefix (`/etc`, `/var`, `/System`, …), or matched a known secret-file pattern. Pick a path inside the user's home directory or an external mount; the response's `error`/`message` carries the specific reason.";
+        readonly skillAnchor: "wiki-vault-rules#root-path-picker";
+        readonly retryable: false;
+    };
+    readonly "attachments.too_many_uploads": {
+        readonly expected: "fewer than 5 concurrent uploads per principal";
+        readonly hint: "Throttled — there are already 5 in-flight uploads on this auth key. Wait for one to complete (200/4xx response) before starting another. Multipart parses count from the first byte until the response is sent.";
+        readonly skillAnchor: "attachments#upload";
+        readonly legacyErrorCode: "too_many_uploads";
+        readonly retryable: true;
+    };
+    readonly "attachments.invalid_content_type": {
+        readonly expected: "Content-Type: multipart/form-data; boundary=…";
+        readonly hint: "Attachment uploads must be multipart/form-data with a single `file` field. application/json, x-www-form-urlencoded, and raw binary are rejected. Use `curl -F 'file=@<path>' -F 'caption=<text>'` for shell uploads.";
+        readonly skillAnchor: "attachments#upload";
+        readonly legacyErrorCode: "invalid_request";
+        readonly retryable: false;
+    };
+    readonly "attachments.invalid_multipart": {
+        readonly expected: "well-formed multipart body with at least one 'file' field";
+        readonly hint: "Busboy failed to parse the request — the multipart boundary is malformed, the body was empty before the file field, or the stream closed early. Re-send with a clean -F flag; do not concatenate two -F uploads in one request.";
+        readonly skillAnchor: "attachments#upload";
+        readonly legacyErrorCode: "invalid_multipart";
+        readonly retryable: true;
+    };
+    readonly "attachments.missing_turn_token": {
+        readonly expected: "X-Turn-Token header from the currently-running session";
+        readonly hint: "Outbound (agent→user) attachment uploads require X-Turn-Token. The dispatcher mints one per session and the pa-api shim auto-injects `PA_TURN_TOKEN`. If you're calling outside a session, this endpoint is the wrong one — use POST /api/chat/attachments (inbound) instead.";
+        readonly skillAnchor: "attachments#outbound";
+        readonly legacyErrorCode: "missing_turn_token";
+        readonly retryable: false;
+    };
+    readonly "attachments.invalid_turn_token": {
+        readonly expected: "X-Turn-Token bound to an active session";
+        readonly hint: "The supplied token doesn't correspond to a currently-running turn. The dispatcher rotates tokens per turn; an attachment from a previous turn is rejected. Re-fetch the token from the current session env (`PA_TURN_TOKEN`) and retry.";
+        readonly skillAnchor: "attachments#outbound";
+        readonly legacyErrorCode: "invalid_turn_token";
+        readonly retryable: false;
+    };
+    readonly "attachments.ingest_rejected": {
+        readonly expected: "file matching the accepted MIME / size constraints";
+        readonly hint: "The attachment store rejected the file. The `error` field carries the IngestRejectedError reason (disallowed_mime, too_large, mime_mismatch, magic_bytes_mismatch, …); the `message` is verbatim. Common cases: images > 5 MB, non-image > 25 MB, declared application/pdf but magic bytes say PNG.";
+        readonly skillAnchor: "attachments#limits";
+        readonly retryable: false;
+    };
+    readonly "attachments.ingest_failed": {
+        readonly expected: "successful blob write";
+        readonly hint: "Internal error storing the attachment. Check daemon logs for the stack; not retryable from the agent side. Notify the user and skip the attach step rather than looping.";
+        readonly skillAnchor: "attachments#errors";
+        readonly legacyErrorCode: "ingest_failed";
+        readonly retryable: false;
+    };
+    readonly "attachments.not_found": {
+        readonly expected: "an existing attachment id from the recent upload response";
+        readonly hint: "GET / DELETE /chat/attachments/:id for an unknown id. Attachment ids are returned from POST /chat/attachments — store the id immediately and quote it verbatim. Attachments may also have been pruned (TTL).";
+        readonly skillAnchor: "attachments#crud";
+        readonly legacyErrorCode: "not_found";
+        readonly retryable: false;
+    };
+    readonly "attachments.already_bound": {
+        readonly expected: "attachment not yet bound to a message";
+        readonly hint: "DELETE on an attachment that's already attached to a sent message is rejected — deletion would break the message thread. Detach via the chat history flow instead, or leave it in place.";
+        readonly skillAnchor: "attachments#crud";
+        readonly legacyErrorCode: "already_bound";
+        readonly retryable: false;
+    };
+    readonly "github.rate_limited": {
+        readonly expected: "fewer than 60 requests per minute per peer (300 global)";
+        readonly hint: "Webhook receiver rate limit hit (per-peer 60 req/min, global 300 req/min). GitHub auto-retries webhook deliveries with backoff, so this is harmless for real deliveries. If the agent itself is calling here (replay/testing), do NOT tight-loop — drop the GitHub branch of this routine and continue with the rest. Retry the same call only after >=60s have elapsed.";
+        readonly skillAnchor: "github#webhook";
+        readonly legacyErrorCode: "rate_limited";
+        readonly retryable: true;
+    };
+    readonly "github.webhook_not_configured": {
+        readonly expected: "PA_GITHUB_WEBHOOK_SECRET set in the keychain";
+        readonly hint: "The webhook secret is unset, so signature verification cannot run. The user must set it in /settings/integrations → GitHub. Skip webhook-related work until the secret is configured.";
+        readonly skillAnchor: "github#webhook-setup";
+        readonly legacyErrorCode: "webhook_not_configured";
+        readonly retryable: false;
+    };
+    readonly "github.invalid_signature": {
+        readonly expected: "X-Hub-Signature-256 matching HMAC-SHA256(body, secret)";
+        readonly hint: "Signature mismatch — either the wrong secret was configured or the request was tampered with. Verify the GitHub webhook secret in /settings/integrations matches the one configured on github.com side.";
+        readonly skillAnchor: "github#webhook-auth";
+        readonly legacyErrorCode: "invalid_signature";
+        readonly retryable: false;
+    };
+    readonly "github.missing_event_type": {
+        readonly expected: "X-GitHub-Event header set";
+        readonly hint: "Webhook payload received without the X-GitHub-Event header. Real GitHub deliveries always set it; if you are replaying for testing, add it to the request.";
+        readonly skillAnchor: "github#webhook";
+        readonly legacyErrorCode: "missing_event_type";
+        readonly retryable: false;
+    };
+    readonly "github.invalid_json": {
+        readonly expected: "syntactically valid JSON webhook body";
+        readonly hint: "The webhook body failed JSON.parse(). Genuine GitHub webhooks are always valid JSON; if you are replaying, check the body wasn't double-encoded or truncated.";
+        readonly skillAnchor: "github#webhook";
+        readonly legacyErrorCode: "invalid_json";
+        readonly retryable: false;
+    };
+    readonly "github.not_configured": {
+        readonly expected: "GitHub token in the OS keychain";
+        readonly hint: "No GitHub token is stored. The user must add one in /settings/integrations → GitHub → 'Add token'. Until then, /api/github/* proxy routes 503 — skip the GitHub branch of any routine.";
+        readonly skillAnchor: "github#token";
+        readonly legacyErrorCode: "github_not_configured";
+        readonly retryable: false;
+    };
+    readonly "github.repository_not_found": {
+        readonly expected: "repository id or slug registered in the unified repositories table";
+        readonly hint: "The supplied `repo=`/`repositoryId=` does not match any row. Use GET /api/repositories to list registered repos; the value can be a row id, a local absolute path, or `github:owner/repo`. To register a new repo, POST /api/repositories.";
+        readonly skillAnchor: "repositories#identifiers";
+        readonly legacyErrorCode: "repository_not_found";
+        readonly retryable: false;
+    };
+    readonly "github.repository_not_registered": {
+        readonly expected: "(owner, repo) pair registered in the unified repositories table";
+        readonly hint: "The combination of owner/repo does not match a registered repository. Register the repo first via POST /api/repositories, then retry. Owner+repo must be the canonical GitHub slug — branches and forks need their own rows.";
+        readonly skillAnchor: "repositories#github-side";
+        readonly legacyErrorCode: "repository_not_registered";
+        readonly retryable: false;
+    };
+    readonly "github.side_required": {
+        readonly expected: "repository row with non-null githubOwner + githubRepo";
+        readonly hint: "The repository is registered locally but has no GitHub side (it's a `local:*` row). GitHub API calls only work on rows with a GitHub slug; either register the GitHub side via PATCH /api/repositories/:id or pick a different repo.";
+        readonly skillAnchor: "repositories#dual-sided";
+        readonly legacyErrorCode: "github_side_required";
+        readonly retryable: false;
+    };
+    readonly "github.validation_error": {
+        readonly expected: "owner+repo or repositoryId in the request";
+        readonly hint: "Specify the target repo either as `?owner=<owner>&repo=<repo>` or `?repositoryId=<id-or-slug>`. The dual form exists for legacy callers; new code should pass `repositoryId` only.";
+        readonly skillAnchor: "repositories#identifiers";
+        readonly legacyErrorCode: "validation_error";
+        readonly retryable: false;
+    };
+    readonly "github.pull_number_and_comment_required": {
+        readonly expected: "'pull_number' (number) and 'comment' (string) in the JSON body";
+        readonly hint: "POST /api/github/pulls/comment requires `{ owner, repo, pull_number, comment }` (or `repositoryId` instead of owner+repo). pull_number is the PR number (not the global issue id). comment is the markdown body of the new comment.";
+        readonly skillAnchor: "github#pull-comment";
+        readonly legacyErrorCode: "pull_number and comment are required";
+        readonly constraint: {
+            readonly type: "object";
+            readonly required: true;
+        };
+    };
+    readonly "github.api_error": {
+        readonly expected: "successful Octokit response";
+        readonly hint: "GitHub API returned an error. Inspect `message` (Octokit's verbatim error text) AND `status` (the HTTP code) to disambiguate. Common cases: 401 (token expired — notify the user to refresh in /settings/integrations → GitHub, then skip; the agent cannot self-recover); 403 (secondary rate limit — wait 60s and retry once, then skip if it persists); 404 (repo/PR deleted or token lost visibility — verify the slug, do NOT loop); 422 (validation — `message` names the offending field; typical causes: closing an already-closed PR, commenting on a locked PR, merge with conflicts; do NOT retry the same body); 5xx (GitHub maintenance — retry once after 60s, then skip).";
+        readonly skillAnchor: "github#errors";
+        readonly legacyErrorCode: "github_api_error";
+        readonly retryable: true;
+    };
+    readonly "git.invalid_repo": {
+        readonly expected: "repo identifier resolving to a clone in the unified repositories table";
+        readonly hint: "?repo= must be either an absolute local path matching a row's `local_path`, or a repository id (e.g. `github:acme/widgets`, `local:abc123…`). GitHub-only rows without a clone 404 here. The response's `allowed` array (on /git/log) lists currently-registered local paths.";
+        readonly skillAnchor: "repositories#local-path";
+        readonly legacyErrorCode: "invalid or missing repo";
+        readonly retryable: false;
+    };
+    readonly "git.invalid_ref": {
+        readonly expected: "ref free of shell metachars; not starting with '-'";
+        readonly hint: "The `?ref=` query parameter is sanitized — it cannot contain `;&|`$` or start with `-` (which would be interpreted as a git flag). Use plain refs like `HEAD~1..HEAD`, `main..feature`, or a 40-char sha range.";
+        readonly skillAnchor: "git#diff";
+        readonly legacyErrorCode: "invalid ref format";
+        readonly retryable: false;
+    };
+    readonly "git.invalid_hash": {
+        readonly expected: "hash free of shell metachars; not starting with '-'";
+        readonly hint: "The `?hash=` query parameter is sanitized — same rules as ref. Use a 7-40 char hex sha, or `HEAD`/`HEAD~N`. No flag-style strings.";
+        readonly skillAnchor: "git#show";
+        readonly legacyErrorCode: "invalid hash format";
+        readonly retryable: false;
+    };
+    readonly "git.exec_failed": {
+        readonly expected: "successful git invocation on the resolved clone";
+        readonly hint: "git exited non-zero. `message` is git's verbatim stderr — read it first. Branches: 'unknown revision' / 'bad revision' → the ref doesn't exist locally; cannot retry, instead either narrow to a known sha range (HEAD~10..HEAD) or skip this repo for the turn. 'fatal: not a git repository' → the localPath is no longer a clone (deleted or moved); update the row via PATCH /api/repositories/:id. 'fatal: bad object' / 'object file is empty' → repository corruption; surface to the user with 'Run `git fsck` in <localPath>' and skip. 'unable to read tree' on porcelain queries → uncommitted state; either stash or skip the file-tree query. Do NOT auto-retry — git failures are deterministic given the inputs.";
+        readonly skillAnchor: "git#errors";
+        readonly retryable: false;
+    };
+    readonly "notion.not_configured": {
+        readonly expected: "Notion integration token in the OS keychain";
+        readonly hint: "Notion is not configured. The user must add an integration token in /settings/integrations → Notion and share at least one database with the integration. Until then, /api/notion/* 503s — skip Notion work.";
+        readonly skillAnchor: "notion#configuration";
+        readonly legacyErrorCode: "notion_not_configured";
+        readonly retryable: false;
+    };
+    readonly "notion.database_not_found": {
+        readonly expected: "database label registered in notion_databases config";
+        readonly hint: "The `?database=<label>` query did not match a registered alias. The 404 response's `available` array lists configured labels (e.g. 'tasks', 'projects'). To register a new database, edit notion_databases in /settings/integrations → Notion.";
+        readonly skillAnchor: "notion#database-labels";
+        readonly legacyErrorCode: "database_not_found";
+        readonly retryable: false;
+    };
+    readonly "notion.invalid_json_parameter": {
+        readonly expected: "URL-encoded JSON in the 'filter' or 'sorts' query parameters";
+        readonly hint: "GET /api/notion/query accepts `?filter=<json>` and `?sorts=<json>`. The JSON must be URL-encoded — use `encodeURIComponent(JSON.stringify(filterObj))`. Notion filter shape: `{ property: '<name>', <type>: { <op>: <value> } }`. Empty filter: omit the param.";
+        readonly skillAnchor: "notion#query";
+        readonly legacyErrorCode: "invalid_json_parameter";
+        readonly retryable: false;
+    };
+    readonly "notion.invalid_type": {
+        readonly expected: "type query parameter = 'page' | 'data_source'";
+        readonly hint: "Notion search supports two filter types. Omit the parameter to search both, or pass `type=page` (titles) / `type=data_source` (databases). Anything else is rejected.";
+        readonly skillAnchor: "notion#search";
+        readonly legacyErrorCode: "invalid_type";
+        readonly constraint: {
+            readonly type: "enum";
+            readonly enum: readonly ["page", "data_source"];
+        };
+    };
+    readonly "notion.invalid_page_id": {
+        readonly expected: "32-hex UUID or 8-4-4-4-12 hyphenated UUID";
+        readonly hint: "Notion page ids are UUIDs — either 32 hex chars without hyphens or canonical 8-4-4-4-12 form. URL-style ids ('My-Page-abc123…') must be stripped of the title prefix; copy the id from the page's Share menu → Copy link → trailing 32-hex string.";
+        readonly skillAnchor: "notion#page-id";
+        readonly legacyErrorCode: "invalid_page_id";
+        readonly constraint: {
+            readonly type: "string";
+            readonly pattern: "^([0-9a-f]{32}|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$";
+        };
+    };
+    readonly "notion.not_found": {
+        readonly expected: "an existing Notion page accessible to the configured integration";
+        readonly hint: "Notion returned 404 / object_not_found. Either the id is wrong, the page is in trash, or the integration token doesn't have access to it. Share the parent page/database with the integration from the Notion UI, then retry.";
+        readonly skillAnchor: "notion#permissions";
+        readonly legacyErrorCode: "not_found";
+        readonly retryable: false;
+    };
+    readonly "notion.invalid_parent": {
+        readonly expected: "parent as database label, { database: '<label>' }, { data_source_id: '<uuid>' }, or { page_id: '<uuid>' }";
+        readonly hint: "Page create needs an explicit parent. Three accepted shapes: string database label ('tasks'), `{ database: 'tasks' }`, `{ data_source_id: '<uuid>' }`, or `{ page_id: '<uuid>' }`. Database labels must be pre-registered (404 above) before using them here.";
+        readonly skillAnchor: "notion#create-page";
+        readonly legacyErrorCode: "invalid_parent";
+        readonly constraint: {
+            readonly required: true;
+        };
+    };
+    readonly "notion.empty_body": {
+        readonly expected: "at least one field to update in the PATCH body";
+        readonly hint: "PATCH /api/notion/pages/:id rejects empty bodies — supply at least one of properties / icon / cover / in_trash. To rename a page, send `{ properties: { title: [{ text: { content: '<new title>' } }] } }`.";
+        readonly skillAnchor: "notion#update-page";
+        readonly legacyErrorCode: "empty_body";
+        readonly retryable: false;
+    };
+    readonly "notion.content_required": {
+        readonly expected: "'content' string in the PATCH body for append/replace_all/replace_range modes";
+        readonly hint: "PATCH /api/notion/pages/:id/content modes 'append', 'replace_all', 'replace_range' all need `content: '<markdown>'`. 'update' mode uses `updates: [{ oldStr, newStr }]` instead. Pass an empty string for content to clear; do not omit the field.";
+        readonly skillAnchor: "notion#content-modes";
+        readonly constraint: {
+            readonly type: "string";
+            readonly required: true;
+        };
+    };
+    readonly "notion.content_range_required": {
+        readonly expected: "'content' AND 'contentRange' strings in 'replace_range' mode";
+        readonly hint: "`mode: 'replace_range'` also needs `contentRange` — the substring of the current page content to replace with `content`. Use 'update' mode if you have many small edits; replace_range is for one contiguous swap.";
+        readonly skillAnchor: "notion#content-modes";
+        readonly constraint: {
+            readonly type: "object";
+            readonly required: true;
+        };
+    };
+    readonly "notion.updates_required": {
+        readonly expected: "non-empty 'updates' array in 'update' mode";
+        readonly hint: "`mode: 'update'` needs `updates: [{ oldStr: '<find>', newStr: '<replace>', replaceAll?: false }, …]` with at least one entry. Use this for multi-spot find-and-replace; for a single large edit use 'replace_range' or 'replace_all'.";
+        readonly skillAnchor: "notion#content-modes";
+        readonly constraint: {
+            readonly type: "array";
+            readonly required: true;
+            readonly minimum: 1;
+        };
+    };
+    readonly "notion.updates_element_invalid": {
+        readonly expected: "every updates element has non-empty 'oldStr' (string) and 'newStr' (string)";
+        readonly hint: "Each entry of `updates[]` must carry both fields. oldStr cannot be empty — that would match everywhere. The response's `message` carries the offending index.";
+        readonly skillAnchor: "notion#content-modes";
+        readonly constraint: {
+            readonly type: "object";
+        };
+    };
+    readonly "notion.invalid_mode": {
+        readonly expected: "mode = 'append' | 'replace_all' | 'replace_range' | 'update'";
+        readonly hint: "PATCH content has exactly four modes. Pick: 'append' (add to end), 'replace_all' (rewrite), 'replace_range' (swap one contiguous chunk), 'update' (multi-spot find-replace). Anything else is rejected.";
+        readonly skillAnchor: "notion#content-modes";
+        readonly legacyErrorCode: "invalid_mode";
+        readonly constraint: {
+            readonly type: "enum";
+            readonly enum: readonly ["append", "replace_all", "replace_range", "update"];
+        };
+    };
+    readonly "notion.upstream_error": {
+        readonly expected: "successful Notion API response";
+        readonly hint: "Notion API call failed. The `error` field tells you which operation tripped (query/search/get/create/update/archive/content_update); the `message` is Notion's verbatim API response. Common cases: 401 (token revoked or rotated — notify the user to re-add in /settings/integrations → Notion, then skip Notion work this turn); 403 (page not shared with the integration — guide the user to open the page in Notion → ··· menu → Add connections → pick the integration, then retry once); 404 (page in trash or id wrong — verify with a search call before retrying); 409 (conflict_error on concurrent edits — re-fetch the page and replay the edit once); 429 (rate limit — Notion caps at 3 req/sec/integration; back off 60s then retry once). Do NOT loop without changing the call shape.";
+        readonly skillAnchor: "notion#errors";
+        readonly retryable: true;
+    };
+    readonly "mail.not_configured": {
+        readonly expected: "at least one active mail account in the account registry";
+        readonly hint: "No mail accounts are set up. The user must add one in /settings/mail (Gmail OAuth, Outlook MSAL, IMAP credentials, etc.). Until then, /api/mail/* 503s — skip the mail branch.";
+        readonly skillAnchor: "mail#accounts";
+        readonly legacyErrorCode: "mail_not_configured";
+        readonly retryable: false;
+    };
+    readonly "mail.blob_store_unavailable": {
+        readonly expected: "encrypted blob store wired into the daemon";
+        readonly hint: "Internal config error — the per-account secrets store is missing. The user must run `aitne doctor` to diagnose; agent cannot recover. Skip mail work this turn.";
+        readonly skillAnchor: "mail#secrets";
+        readonly legacyErrorCode: "blob_store_unavailable";
+        readonly retryable: false;
+    };
+    readonly "mail.unsupported_kind": {
+        readonly expected: "kind = 'gmail' | 'outlook' | 'yahoo' | 'icloud' | 'imap'";
+        readonly hint: "Mail account creation needs an explicit provider kind. Pick from the supported list — the request body's `kind` is the dispatch switch. Use 'imap' for any custom IMAP server (Fastmail, ProtonMail bridge, etc.).";
+        readonly skillAnchor: "mail#account-create";
+        readonly legacyErrorCode: "unsupported_kind";
+        readonly constraint: {
+            readonly type: "enum";
+            readonly enum: readonly ["gmail", "outlook", "yahoo", "icloud", "imap"];
+        };
+    };
+    readonly "mail.outlook_client_config_missing": {
+        readonly expected: "OUTLOOK_CLIENT_ID env var or pre-registered tenant config";
+        readonly hint: "Outlook MSAL needs a registered app's client_id. The user must register an app in Azure AD and set OUTLOOK_CLIENT_ID before /api/mail/accounts can create Outlook rows. Skip Outlook setup; notify the user.";
+        readonly skillAnchor: "mail#outlook-setup";
+        readonly legacyErrorCode: "outlook_client_config_missing";
+        readonly retryable: false;
+    };
+    readonly "mail.account_not_found": {
+        readonly expected: "account id from POST /api/mail/accounts";
+        readonly hint: "No mail account row matches this id. GET /api/mail/accounts to list current ids. Note that DELETE returns 204 + the row drops; reusing the same id afterward will 404.";
+        readonly skillAnchor: "mail#account-crud";
+        readonly legacyErrorCode: "not_found";
+        readonly retryable: false;
+    };
+    readonly "mail.oauth_timeout": {
+        readonly expected: "user completes the OAuth consent flow within the timeout";
+        readonly hint: "OAuth pairing timed out waiting for the user to grant consent in the browser. Notify the user that they need to finish the consent flow (open the link the dashboard surfaced) and retry the pair step.";
+        readonly skillAnchor: "mail#oauth";
+        readonly legacyErrorCode: "oauth_timeout";
+        readonly retryable: true;
+    };
+    readonly "mail.invalid_body": {
+        readonly expected: "JSON body matching the per-endpoint shape";
+        readonly hint: "Mail endpoint body missing or malformed — `message` names the specific offender (e.g. 'clientId required', 'read: boolean required', 'add/remove labels required'). Common shapes by endpoint: POST /mail/accounts — `{ kind, displayName?, ... }` (provider-specific extras); PATCH /mail/messages/:id/read — `{ read: boolean }`; PATCH /mail/messages/:id/labels — `{ add?: string[], remove?: string[] }` (at least one); POST /mail/send — see mail.validation_failed for the send contract. Read `message` verbatim, supply the missing field, and resubmit; do NOT retry the same body.";
+        readonly skillAnchor: "mail#request-shapes";
+        readonly legacyErrorCode: "invalid_body";
+        readonly constraint: {
+            readonly type: "object";
+            readonly required: true;
+        };
+    };
+    readonly "mail.not_implemented": {
+        readonly expected: "operation supported by the resolved provider";
+        readonly hint: "This operation is not available on the resolved provider. `message` names the gap (e.g. 'untrash not supported on imap', 'listDrafts not supported on imap'). Known gaps: IMAP cannot manage drafts (no DRAFTS folder semantics — compose via SMTP send instead); IMAP cannot untrash once a message hits `\\Deleted` + EXPUNGE; Yahoo/iCloud have no thread API (use search by subject as a fallback); only Gmail exposes label semantics, others use folder moves. If the agent's intent requires this provider's data, skip the operation and surface to the user — do NOT retry the same call.";
+        readonly skillAnchor: "mail#provider-matrix";
+        readonly legacyErrorCode: "not_implemented";
+        readonly retryable: false;
+    };
+    readonly "mail.provider_auth_error": {
+        readonly expected: "valid OAuth/IMAP credentials for the resolved account";
+        readonly hint: "Provider returned 401/403 — credentials are revoked, expired, or insufficient. Notify the user to re-link the account in /settings/mail; the agent cannot refresh OAuth interactively. Skip mail operations until the user confirms.";
+        readonly skillAnchor: "mail#errors";
+        readonly legacyErrorCode: "provider_auth_error";
+        readonly retryable: false;
+    };
+    readonly "mail.validation_failed": {
+        readonly expected: "send body matching the validateSendInput contract";
+        readonly hint: "Send-mail body failed validation. The `errors` array carries per-field issues; fix every listed entry before retrying. Required fields: `to` (non-empty array of string emails or `{ email, name? }` objects), at least one of `subject`/`body`/`draftId`. Optional: `cc`/`bcc` (same shape as `to`), `replyTo` (single recipient), `inReplyTo` (RFC 822 message-id of the parent for thread continuation), `attachments` (array of `{ filename, mimeType, contentBase64 }` — all three are required per attachment). Address fields reject bare names without `@`; encode display names via the `{ email, name }` form, not RFC-2822 `Name <addr>` strings.";
+        readonly skillAnchor: "mail#send";
+        readonly legacyErrorCode: "validation_failed";
+    };
+    readonly "mail.upstream_error": {
+        readonly expected: "successful provider API response";
+        readonly hint: "Mail provider returned an unexpected error. `error` is the per-route tag (`mail_list_failed`, `mail_send_failed`, …); `message` is the provider's verbatim text. Transient = 5xx, ECONNRESET, ETIMEDOUT, IMAP NO/BAD with text mentioning 'temporary' — retry ONCE after 30s, then skip. Permanent = 4xx, IMAP NO with mailbox/permission text, SMTP 5xx — do NOT retry; notify the user with the verbatim `message` and skip the mail branch. After two consecutive retries on the same account, treat as permanent regardless of code.";
+        readonly skillAnchor: "mail#errors";
+        readonly retryable: true;
+    };
+    readonly "knowledge.event_bus_unavailable": {
+        readonly expected: "EventBus wired into the API server";
+        readonly hint: "The event bus is not constructed — daemon is starting up or in degraded mode. Wait ~5s and retry; if it persists, the agent should skip and notify the user. Do not loop tight.";
+        readonly skillAnchor: "knowledge#bus";
+        readonly legacyErrorCode: "event_bus_unavailable";
+        readonly retryable: true;
+    };
+    readonly "knowledge.empty_file": {
+        readonly expected: "non-empty file payload";
+        readonly hint: "The uploaded file was 0 bytes after multipart parse — likely a curl typo (`-F 'file=@'` with empty path) or a download race. Re-fetch the source and resubmit.";
+        readonly skillAnchor: "knowledge#upload";
+        readonly legacyErrorCode: "empty_file";
+        readonly constraint: {
+            readonly type: "string";
+            readonly minLength: 1;
+        };
+    };
+    readonly "observations.invalid_actor": {
+        readonly expected: "actor = 'user' | 'agent' | 'system'";
+        readonly hint: "The `?actor=` filter accepts only `user`, `agent`, or `system`. `user` is the hourly-check default (excludes agent's own writes). Omit to get all observations.";
+        readonly skillAnchor: "observations#actor-filter";
+        readonly legacyErrorCode: "invalid_actor";
+        readonly constraint: {
+            readonly type: "enum";
+            readonly enum: readonly ["user", "agent", "system"];
+        };
+    };
+    readonly "observations.invalid_json_body": {
+        readonly expected: "syntactically valid JSON consume body";
+        readonly hint: "POST /api/observations/consume body failed JSON parse. The body shape is `{ ids: number[], cursor?: string }`. Verify quoting and array shape before re-sending.";
+        readonly skillAnchor: "observations#consume";
+        readonly legacyErrorCode: "invalid_json_body";
+        readonly retryable: false;
+    };
+    readonly "recurring_schedules.invalid_id": {
+        readonly expected: "positive integer id from GET /api/recurring-schedules";
+        readonly hint: "The `:id` route param must be a positive integer. GET /api/recurring-schedules to list ids. URL-encoded ids and decimal ids are rejected.";
+        readonly skillAnchor: "recurring-schedules#crud";
+        readonly legacyErrorCode: "invalid_id";
+        readonly constraint: {
+            readonly type: "integer";
+            readonly minimum: 1;
+        };
+    };
+    readonly "recurring_schedules.not_found": {
+        readonly expected: "an existing recurring_schedules row";
+        readonly hint: "PATCH/DELETE on an id that doesn't exist. GET /api/recurring-schedules to discover current ids; rows are pruned when the user disables them via the dashboard.";
+        readonly skillAnchor: "recurring-schedules#crud";
+        readonly legacyErrorCode: "not_found";
+        readonly retryable: false;
+    };
+    readonly "recurring_schedules.validation_error": {
+        readonly expected: "body matching recurringScheduleSchema (cron-like + payload)";
+        readonly hint: "Zod validation failed. The `details` field lists per-field issues. Required shape: `{ cron: '<cron expr>', taskType: 'wake'|'dm_session'|…, description: '<20+ chars>', taskContext: {...} }`. Use a cron expression validator (e.g. crontab.guru) before submitting.";
+        readonly skillAnchor: "recurring-schedules#schema";
+        readonly legacyErrorCode: "validation_error";
+    };
+    readonly "travel_bookings.invalid_type": {
+        readonly expected: "one of 'flight' | 'hotel' | 'restaurant' | 'train' | 'bus' | 'other'";
+        readonly hint: "The `?type=` filter must be a registered travel kind. The 400 response carries the `validTypes` array verbatim — pick from it or omit the filter to get all kinds. Spelling matters: 'plane' / 'flights' are rejected; use 'flight'.";
+        readonly skillAnchor: "gmail-lifestyle#travel-bookings-filters";
+        readonly legacyErrorCode: "invalid_type";
+        readonly constraint: {
+            readonly type: "enum";
+            readonly enum: readonly ["flight", "hotel", "restaurant", "train", "bus", "other"];
+        };
+    };
+    readonly "travel_bookings.invalid_status": {
+        readonly expected: "one of 'upcoming' | 'completed' | 'cancelled' | 'all' (filter) or 'upcoming' | 'completed' | 'cancelled' (PATCH)";
+        readonly hint: "Status values are constrained. Filter (?status=) accepts 'all' as the no-op; PATCH body { status } does NOT — pick one of the three concrete states. The 400 response's `validStatuses` / `valid` array carries the live list.";
+        readonly skillAnchor: "gmail-lifestyle#travel-bookings-status";
+        readonly legacyErrorCode: "invalid_status";
+    };
+    readonly "travel_bookings.invalid_id": {
+        readonly expected: "positive integer id from GET /api/travel-bookings";
+        readonly hint: "PATCH /api/travel-bookings/:id needs a numeric row id. GET /api/travel-bookings to discover live ids; the response items carry `.id`. URL-encoded and decimal ids are rejected.";
+        readonly skillAnchor: "gmail-lifestyle#travel-bookings-crud";
+        readonly legacyErrorCode: "invalid_id";
+        readonly constraint: {
+            readonly type: "integer";
+            readonly minimum: 1;
+        };
+    };
+    readonly "travel_bookings.invalid_json": {
+        readonly expected: "syntactically valid JSON body";
+        readonly hint: "PATCH body failed JSON.parse(). Check for trailing commas, single quotes, or unescaped newlines. Use jq -nc to validate before piping into curl --data-binary.";
+        readonly skillAnchor: "gmail-lifestyle#travel-bookings-request-shape";
+        readonly legacyErrorCode: "invalid_json";
+        readonly retryable: false;
+    };
+    readonly "travel_bookings.no_updates": {
+        readonly expected: "PATCH body containing at least one of { status, destination }";
+        readonly hint: "PATCH /api/travel-bookings/:id rejects empty bodies. Supply at least one mutable field — currently `status` ('upcoming'|'completed'|'cancelled') or `destination` (string). Other columns are immutable; re-ingest from mail to change them.";
+        readonly skillAnchor: "gmail-lifestyle#travel-bookings-patch";
+        readonly legacyErrorCode: "no_updates";
+        readonly retryable: false;
+    };
+    readonly "travel_bookings.not_found": {
+        readonly expected: "an existing travel_bookings row matching :id";
+        readonly hint: "PATCH targeted a row id that does not exist. GET /api/travel-bookings to discover current ids; rows can be pruned when a cancellation mail is reconciled. Do not retry the same id.";
+        readonly skillAnchor: "gmail-lifestyle#travel-bookings-crud";
+        readonly legacyErrorCode: "not_found";
+        readonly retryable: false;
+    };
+    readonly "receipts.invalid_id": {
+        readonly expected: "positive integer id from GET /api/receipts";
+        readonly hint: "The `:id` route param must be a positive integer. GET /api/receipts to list current ids; receipts are pruned when the source mail is deleted. URL-encoded and decimal ids are rejected.";
+        readonly skillAnchor: "gmail-lifestyle#receipts-crud";
+        readonly legacyErrorCode: "invalid_id";
+        readonly constraint: {
+            readonly type: "integer";
+            readonly minimum: 1;
+        };
+    };
+    readonly "receipts.not_found": {
+        readonly expected: "an existing receipts row matching :id";
+        readonly hint: "No receipt row exists with that id. Re-list with GET /api/receipts (filters: ?category=, ?saved=true|false) to find the right id. Rows are removed when the source mail message is purged by IMAP reconciliation.";
+        readonly skillAnchor: "gmail-lifestyle#receipts-crud";
+        readonly legacyErrorCode: "not_found";
+        readonly retryable: false;
+    };
+    readonly "receipts.no_updates": {
+        readonly expected: "PATCH body containing at least one of { obsidianPath, category }";
+        readonly hint: "PATCH /api/receipts/:id needs at least one mutable field. Currently `obsidianPath` (sets saved_at to now) or `category` ('document'|'travel'). Pass both to file a receipt under Obsidian and re-tag in one shot.";
+        readonly skillAnchor: "gmail-lifestyle#receipts-patch";
+        readonly legacyErrorCode: "no_updates";
+        readonly retryable: false;
+    };
+    readonly "receipts.attachment_too_large": {
+        readonly expected: "receipt attachment <= 100 MB";
+        readonly hint: "Download blocked by the 100 MB ceiling to avoid OOM. The `maxBytes` field carries the limit. For attachments above this, ask the user to download via the mail provider's web UI instead. Do not retry — the size won't shrink.";
+        readonly skillAnchor: "gmail-lifestyle#receipts-download-limits";
+        readonly legacyErrorCode: "attachment_too_large";
+        readonly retryable: false;
+    };
+    readonly "receipts.mail_not_configured": {
+        readonly expected: "mail registry available with at least one active account";
+        readonly hint: "Receipt download proxies through the originating mail account. The mail registry is not wired in — either no accounts are configured yet, or the daemon is in degraded mode. Notify the user; skip receipt downloads this turn.";
+        readonly skillAnchor: "gmail-lifestyle#receipts-download";
+        readonly legacyErrorCode: "mail_not_configured";
+        readonly retryable: false;
+    };
+    readonly "receipts.orphaned_receipt": {
+        readonly expected: "receipt row with a non-null account_id linked to an active mail account";
+        readonly hint: "The receipt has account_id=NULL, so the daemon can't pick a provider to fetch the attachment. This typically means the originating mail account was deleted. Either re-ingest the receipt from the new account, or skip the download — there is no recovery from this state without re-ingest.";
+        readonly skillAnchor: "gmail-lifestyle#receipts-account-link";
+        readonly legacyErrorCode: "orphaned_receipt";
+        readonly retryable: false;
+    };
+    readonly "receipts.account_not_found": {
+        readonly expected: "account_id matching an active row in the mail account registry";
+        readonly hint: "The receipt's account_id does not resolve to any registered mail account. The account was likely removed in /settings/mail. Either re-add it (the user must re-link) or skip the download.";
+        readonly skillAnchor: "gmail-lifestyle#receipts-account-link";
+        readonly legacyErrorCode: "account_not_found";
+        readonly retryable: false;
+    };
+    readonly "receipts.attachment_download_not_supported": {
+        readonly expected: "originating provider supports per-attachment download";
+        readonly hint: "This provider (e.g. an IMAP server without UID FETCH attachment selectors) cannot download individual attachments. The `provider` field names the kind. Ask the user to fetch the attachment via the provider's native UI; do not retry.";
+        readonly skillAnchor: "gmail-lifestyle#receipts-download";
+        readonly legacyErrorCode: "attachment_download_not_supported";
+        readonly retryable: false;
+    };
+    readonly "receipts.attachment_not_found": {
+        readonly expected: "provider returns a non-null attachment payload for the recorded (msg, attachment) pair";
+        readonly hint: "The mail provider returned null when asked for the attachment — typically the source message was deleted or moved out of the All Mail label. Skip the download and offer to remove the orphan row by PATCHing category='deleted' or by user action.";
+        readonly skillAnchor: "gmail-lifestyle#receipts-download";
+        readonly legacyErrorCode: "attachment_not_found";
+        readonly retryable: false;
+    };
+    readonly "books.invalid_id": {
+        readonly expected: "positive integer id from GET /api/books";
+        readonly hint: "Book id must be a positive integer. GET /api/books?limit=200 to list current ids; URL-encoded and decimal ids are rejected.";
+        readonly skillAnchor: "books#crud";
+        readonly legacyErrorCode: "invalid_id";
+        readonly constraint: {
+            readonly type: "integer";
+            readonly minimum: 1;
+        };
+    };
+    readonly "books.not_found": {
+        readonly expected: "an existing books row matching :id";
+        readonly hint: "No book row exists with that id. GET /api/books to discover current ids, or POST /api/books/import-clippings / import-notebook-html to create rows from Kindle exports.";
+        readonly skillAnchor: "books#crud";
+        readonly legacyErrorCode: "not_found";
+        readonly retryable: false;
+    };
+    readonly "books.invalid_json": {
+        readonly expected: "syntactically valid JSON body";
+        readonly hint: "Body failed JSON.parse(). Check for trailing commas, single quotes, or unescaped newlines in the clipping/HTML text. Use jq -nc to validate before piping into curl --data-binary.";
+        readonly skillAnchor: "books#request-shape";
+        readonly legacyErrorCode: "invalid_json";
+        readonly retryable: false;
+    };
+    readonly "books.invalid_status": {
+        readonly expected: "one of 'reading' | 'completed' | 'abandoned'";
+        readonly hint: "Book status whitelist. The 400 response carries the `valid` array verbatim. To delete a book, use 'abandoned' (no DELETE endpoint by design — keeps the highlights linkable).";
+        readonly skillAnchor: "books#status";
+        readonly legacyErrorCode: "invalid_status";
+        readonly constraint: {
+            readonly type: "enum";
+            readonly enum: readonly ["reading", "completed", "abandoned"];
+        };
+    };
+    readonly "books.rating_must_be_1_to_5": {
+        readonly expected: "integer between 1 and 5 (inclusive) for the `rating` field";
+        readonly hint: "Rating uses a 5-star scale. Pass an integer 1–5; decimals and out-of-range values are rejected. Omit the field if you don't want to rate the book.";
+        readonly skillAnchor: "books#rating";
+        readonly legacyErrorCode: "rating_must_be_1_to_5";
+        readonly constraint: {
+            readonly type: "integer";
+            readonly minimum: 1;
+            readonly maximum: 5;
+        };
+    };
+    readonly "books.no_updates": {
+        readonly expected: "PATCH body containing at least one of { status, rating, notes }";
+        readonly hint: "PATCH /api/books/:id needs at least one mutable field. Currently `status` ('reading'|'completed'|'abandoned'), `rating` (1–5), or `notes` (free string). Setting status='completed' also stamps completed_at automatically.";
+        readonly skillAnchor: "books#patch";
+        readonly legacyErrorCode: "no_updates";
+        readonly retryable: false;
+    };
+    readonly "books.payload_too_large": {
+        readonly expected: "request body <= 10 MB";
+        readonly hint: "Clipping/notebook-HTML imports cap at 10 MB. Typical Kindle My Clippings.txt is under 5 MB; a 10 MB+ payload suggests duplicate concatenation or stray binary data. Split the file or ask the user to re-export.";
+        readonly skillAnchor: "books#import-limits";
+        readonly legacyErrorCode: "payload_too_large";
+        readonly retryable: false;
+    };
+    readonly "books.data_required": {
+        readonly expected: "non-empty 'data' string in the import-clippings body";
+        readonly hint: "POST /api/books/import-clippings requires `{ data: '<clippings.txt content>' }`. Pass the raw text content (the parser handles ==== separators and the standard Kindle header lines).";
+        readonly skillAnchor: "books#import-clippings";
+        readonly legacyErrorCode: "data_required";
+        readonly constraint: {
+            readonly type: "string";
+            readonly required: true;
+            readonly minLength: 1;
+        };
+    };
+    readonly "books.html_required": {
+        readonly expected: "non-empty 'html' string in the import-notebook-html body";
+        readonly hint: "POST /api/books/import-notebook-html requires `{ html: '<email HTML>', subject?, date? }`. Pass the raw HTML payload from the Kindle 'Export Notebook' email; subject/date are used as fallbacks when the HTML lacks an explicit title or timestamp.";
+        readonly skillAnchor: "books#import-notebook-html";
+        readonly legacyErrorCode: "html_required";
+        readonly constraint: {
+            readonly type: "string";
+            readonly required: true;
+            readonly minLength: 1;
+        };
+    };
+    readonly "books.unrecognized_format": {
+        readonly expected: "Kindle notebook HTML matching the parser's known shapes";
+        readonly hint: "HTML didn't match any known Kindle notebook export shape. Three likely causes: (a) Amazon changed the export template — the agent cannot adapt, surface to the user and ask for a re-export; (b) the HTML was already converted to plain text before upload (e.g. via a 'Save as PDF'/'Print to plain text' detour) — request the original .html attachment from the Kindle 'Export Notebook' email; (c) wrong source (Goodreads, Apple Books, etc.) — only Kindle is supported here. Recovery for the user: open https://read.amazon.com → pick the book → Notebook (right rail) → Export → 'Send as email' → forward the .html attachment without modification. Do NOT retry without a different payload.";
+        readonly skillAnchor: "books#import-notebook-html";
+        readonly legacyErrorCode: "unrecognized_format";
+        readonly retryable: false;
+    };
+    readonly "repositories.not_found": {
+        readonly expected: "an existing repositories row matching :id, slug, or `github:owner/repo`";
+        readonly hint: "GET /api/repositories to list current rows. The `:id` route param accepts the row id, the `localPath` absolute path, or a `github:<owner>/<repo>` slug. Rows are removed via DELETE — the agent cannot recreate one without explicit user intent.";
+        readonly skillAnchor: "repositories#crud";
+        readonly legacyErrorCode: "not_found";
+        readonly retryable: false;
+    };
+    readonly "repositories.event_bus_unavailable": {
+        readonly expected: "EventBus wired into the API server";
+        readonly hint: "The daemon is starting up or in degraded mode — the EventBus that schedules repository runs is not yet available. Wait ~5s and retry once; if it persists, skip the repository run and notify the user.";
+        readonly skillAnchor: "repositories#run";
+        readonly legacyErrorCode: "event_bus_unavailable";
+        readonly retryable: true;
+    };
+    readonly "repositories.validation_error": {
+        readonly expected: "request body fields satisfying the run/trigger contract";
+        readonly hint: "A required field is missing or has the wrong shape — `message` names the offender (e.g. 'name is required', 'backend must be claude/codex/gemini', 'prompt is required'). Read the message verbatim and supply the field. Most repository POST bodies need at minimum `{ backend, model, workdirMode, prompt }` (run) or `{ name, eventType, backend, model, workdirMode, prompt }` (trigger).";
+        readonly skillAnchor: "repositories#schemas";
+        readonly legacyErrorCode: "validation_error";
+    };
+    readonly "repositories.model_invalid": {
+        readonly expected: "model registered for the chosen backend in process_backend_config";
+        readonly hint: "The (backend, model) pair is rejected because the model isn't listed in the backend's model registry. GET /api/backends/models?backend=<backend> to list valid models for that backend. Common: passing 'sonnet' alias to codex/gemini — they need full ids like 'claude-sonnet-4-6' or 'gemini-2.5-pro'.";
+        readonly skillAnchor: "repositories#run";
+        readonly legacyErrorCode: "model_invalid";
+        readonly retryable: false;
+    };
+    readonly "repositories.local_clone_required": {
+        readonly expected: "repositories row with a non-null localPath";
+        readonly hint: "The operation needs a local git clone — management init/scan/refresh-architecture and `workdirMode='local-clone'` runs all require it. Either POST /api/repositories/:id/link-local first with a clone path, or pick `workdirMode='temp'` for run-in-temp.";
+        readonly skillAnchor: "repositories#dual-sided";
+        readonly legacyErrorCode: "local_clone_required";
+        readonly retryable: false;
+    };
+    readonly "repositories.instruction_required": {
+        readonly expected: "`instructionMd` string when workdirMode='temp'";
+        readonly hint: "run-in-temp needs an explicit instruction markdown — the temp clone has no project context to ground the agent. Either provide `instructionMd` (markdown the agent will read first) or switch to `workdirMode='local-clone'` if a clone is registered.";
+        readonly skillAnchor: "repositories#run";
+        readonly legacyErrorCode: "instruction_required";
+        readonly retryable: false;
+    };
+    readonly "repositories.already_in_flight": {
+        readonly expected: "no in-flight git.project.refresh_architecture row for this repo";
+        readonly hint: "An architecture refresh is already pending or running. Two concurrent runs would race on the overview.md chokepoint write and burn model quota. Poll GET /api/repositories/:id/management → architectureRefresh.status until it leaves 'pending'/'running', or just wait for the next dashboard refresh.";
+        readonly skillAnchor: "repositories#refresh-architecture";
+        readonly legacyErrorCode: "already_in_flight";
+        readonly retryable: true;
+    };
+    readonly "repositories.no_overview": {
+        readonly expected: "overview.md exists for this repository";
+        readonly hint: "PUT /architecture-section can only replace the Architecture block of an existing overview.md. Run POST /api/repositories/:id/management/init first to create the skeleton, then retry the PUT.";
+        readonly skillAnchor: "repositories#architecture-section";
+        readonly legacyErrorCode: "no_overview";
+        readonly retryable: false;
+    };
+    readonly "repositories.payload_too_large": {
+        readonly expected: "architecture-section markdown body within the size limit";
+        readonly hint: "The markdown body exceeds the per-section byte cap. Shorten the section — focus on stable architecture (modules, dataflow, key invariants), not change history. Split overlapping content out into other overview sections via init/scan instead.";
+        readonly skillAnchor: "repositories#architecture-section";
+        readonly legacyErrorCode: "payload_too_large";
+        readonly retryable: false;
+    };
+    readonly "repositories.management_init_failed": {
+        readonly expected: "successful init of git/<slug>/overview.md";
+        readonly hint: "Init failed mid-pipeline (skeleton write OR architecture-refresh enqueue). `message` carries the underlying error verbatim. Diagnose by branch: 'ENOENT' / 'EACCES' on the localPath → user must remount the clone or fix permissions; 'fatal:' from git → the clone is corrupt (suggest `git fsck`); 'UNIQUE constraint failed' → an in-flight init/refresh already exists, wait for it to terminal then re-call; any other text → schema drift, do not loop. Skip the repository for this turn and surface ONE notification with the verbatim `message`.";
+        readonly skillAnchor: "repositories#management-init";
+        readonly legacyErrorCode: "management_init_failed";
+        readonly retryable: false;
+    };
+    readonly "repositories.architecture_refresh_enqueue_failed": {
+        readonly expected: "successful insert of a git.project.refresh_architecture schedule row";
+        readonly hint: "Could not enqueue the architecture-refresh agent run. The underlying error is in `message`. Don't auto-retry — typically a schema/migration drift or an EventBus shutdown. Surface to the user.";
+        readonly skillAnchor: "repositories#refresh-architecture";
+        readonly legacyErrorCode: "architecture_refresh_enqueue_failed";
+        readonly retryable: false;
+    };
+    readonly "repositories.architecture_section_write_failed": {
+        readonly expected: "successful in-process write of overview.md's Architecture block";
+        readonly hint: "The Architecture section write to overview.md failed. `message` carries the underlying file/IO error. Inspect `git/<slug>/overview.md` manually if writable; otherwise surface to the user.";
+        readonly skillAnchor: "repositories#architecture-section";
+        readonly legacyErrorCode: "architecture_section_write_failed";
+        readonly retryable: false;
+    };
+    readonly "repositories.management_scan_failed": {
+        readonly expected: "successful management scan run";
+        readonly hint: "Daily management scan failed mid-run. `message` carries the underlying error. Common causes and the right next step: 'git fetch failed' / network text → clone is offline; skip until network returns, do not retry this turn. 'journal write failed' (EACCES/ENOSPC) → vault is read-only or full; surface to the user with the verbatim path and stop scanning. GitHub rate-limited → the secondary limit hit (see github.rate_limited); next cron tick (1h+) will succeed naturally. The scan row is marked 'failed' for audit even though the row itself is unrecoverable — do NOT enqueue a manual retry, let the daily cron fire.";
+        readonly skillAnchor: "repositories#management-scan";
+        readonly legacyErrorCode: "management_scan_failed";
+        readonly retryable: false;
+    };
+    readonly "repositories.internal_error": {
+        readonly expected: "no unexpected exception inside the store";
+        readonly hint: "RepositoryStore threw an unrecognised error. `message` carries the verbatim exception. This is typically a schema/migration drift; do not retry without operator action.";
+        readonly skillAnchor: "repositories#errors";
+        readonly legacyErrorCode: "internal_error";
+        readonly retryable: false;
+    };
+    readonly "mcp.not_found": {
+        readonly expected: "an existing mcp_servers row matching :id";
+        readonly hint: "GET /api/mcp/servers to list current ids. MCP server rows are added via POST /api/mcp/servers; the agent cannot create them — surface to the user if a referenced server is missing.";
+        readonly skillAnchor: "mcp#crud";
+        readonly legacyErrorCode: "not_found";
+        readonly retryable: false;
+    };
+    readonly "mcp.invalid_input": {
+        readonly expected: "request body matching the MCP server / patch / secret schema";
+        readonly hint: "Body failed Zod validation. The `issues` array carries per-field paths — fix each one and resubmit. Common: transport must be 'stdio'|'sse'|'http'|'docker'; backends must be a non-empty array of registered backend ids; envKeys/headerKeys must be non-empty strings.";
+        readonly skillAnchor: "mcp#schemas";
+        readonly legacyErrorCode: "invalid_input";
+    };
+    readonly "mcp.duplicate": {
+        readonly expected: "no existing mcp_servers row with the same id";
+        readonly hint: "An MCP server with this id already exists. Either PATCH /api/mcp/servers/:id to update the existing row, or pick a different id (ids are user-visible — e.g. 'my-notion', 'acme-mcp/coda').";
+        readonly skillAnchor: "mcp#duplicate";
+        readonly legacyErrorCode: "duplicate";
+        readonly retryable: false;
+    };
+    readonly "mcp.internal_error": {
+        readonly expected: "no unexpected exception inside the MCP registry";
+        readonly hint: "Internal error during MCP CRUD. Inspect daemon logs for the stack; the route does not surface implementation detail to the agent. Do not retry — typically a schema/migration drift or a corrupted secrets blob.";
+        readonly skillAnchor: "mcp#errors";
+        readonly legacyErrorCode: "internal_error";
+        readonly retryable: false;
+    };
+    readonly "mcp.server_disabled": {
+        readonly expected: "MCP server row with enabled=1";
+        readonly hint: "Probe is rejected because the server is currently disabled. Enable via POST /api/mcp/servers/:id/enable (Approve tier — the dashboard owns this), or notify the user to enable it before retrying.";
+        readonly skillAnchor: "mcp#probe";
+        readonly legacyErrorCode: "server_disabled";
+        readonly retryable: false;
+    };
+    readonly "mcp.probe_failed": {
+        readonly expected: "MCP probe completes without throwing at the transport layer";
+        readonly hint: "The probe transport threw an unexpected error (not a normal `{ ok: false }` probe result, which is persisted normally). `message` carries the verbatim failure. Common: the configured command/binary is missing, the URL is unreachable, or an env-key secret is unset.";
+        readonly skillAnchor: "mcp#probe";
+        readonly legacyErrorCode: "probe_failed";
+        readonly retryable: true;
+    };
+    readonly "mcp.unknown_key": {
+        readonly expected: "keyName declared in the server's envKeys or headerKeys";
+        readonly hint: "Secret keyName must match one of the strings configured on the server. PATCH /api/mcp/servers/:id with the new key in envKeys (for stdio servers) or headerKeys (for HTTP/SSE) before writing the secret value.";
+        readonly skillAnchor: "mcp#secrets";
+        readonly legacyErrorCode: "unknown_key";
+        readonly retryable: false;
+    };
+    readonly "mcp.gemini_cli_not_found": {
+        readonly expected: "`gemini` CLI binary resolvable on the daemon's PATH";
+        readonly hint: "POST /api/mcp/gemini-install needs the Gemini CLI installed and on PATH. Notify the user to install it from https://github.com/google-gemini/gemini-cli and re-run `aitne doctor` to confirm resolution.";
+        readonly skillAnchor: "mcp#gemini-install";
+        readonly legacyErrorCode: "gemini_cli_not_found";
+        readonly retryable: false;
+    };
+    readonly "mcp.install_failed": {
+        readonly expected: "successful `gemini extensions install` / `gemini mcp add` invocation";
+        readonly hint: "Gemini CLI exited non-zero. `stdout`/`stderr` on the response are verbatim — read both. Common branches: 'not authenticated' / 'login required' → user must run `gemini auth login` first, the agent cannot complete OAuth interactively; 'ECONNREFUSED' / 'ENOTFOUND' → npm registry/network blocked, surface and skip; 'already installed' at a different version → DELETE /api/mcp/servers/:id then re-POST with the desired version, OR install via the dashboard's /settings/integrations → MCP card which handles version pinning. Idempotent re-runs short-circuit with `alreadyInstalled: true`, so reaching this code means a real failure — do NOT retry the same call.";
+        readonly skillAnchor: "mcp#gemini-install";
+        readonly legacyErrorCode: "install_failed";
+        readonly retryable: false;
+    };
+    readonly "skills.invalid_form": {
+        readonly expected: "multipart/form-data body with at least a `file` field";
+        readonly hint: "Skill upload requires multipart/form-data. application/json and x-www-form-urlencoded are rejected. Use `curl -F 'file=@SKILL.md' -F 'name=<slug>'` for shell uploads.";
+        readonly skillAnchor: "skills#upload";
+        readonly legacyErrorCode: "invalid_form";
+        readonly retryable: false;
+    };
+    readonly "skills.file_field_required": {
+        readonly expected: "multipart 'file' part containing the SKILL.md content";
+        readonly hint: "The multipart parsed but did not include a `file` field. Add `-F 'file=@<path>'` (or the equivalent in your client) — the file part is required.";
+        readonly skillAnchor: "skills#upload";
+        readonly legacyErrorCode: "file field required";
+        readonly retryable: false;
+    };
+    readonly "skills.builtin_protected": {
+        readonly expected: "skill name not matching a built-in slug";
+        readonly hint: "Built-in skills are read-only — they ship with the daemon and are owned by `agent-assets/skills/`. Pick a different slug for user skills (e.g. add a prefix like `user-` or `<your-handle>-`). GET /skills/sources to see built-in slugs.";
+        readonly skillAnchor: "skills#builtin-protection";
+        readonly legacyErrorCode: "builtin_protected";
+        readonly retryable: false;
+    };
+    readonly "skills.file_too_large": {
+        readonly expected: "uploaded SKILL.md file <= 256 KB";
+        readonly hint: "SKILL.md uploads cap at 256 KB. A larger file usually means embedded binary content or accidentally-included generated output. Trim the file and re-upload; consider linking out to longer prose rather than inlining.";
+        readonly skillAnchor: "skills#upload-limits";
+        readonly legacyErrorCode: "file_too_large";
+        readonly retryable: false;
+    };
+    readonly "skills.invalid_encoding": {
+        readonly expected: "valid UTF-8 file content";
+        readonly hint: "The uploaded file is not valid UTF-8 — likely a binary file renamed to .md. Re-export as plain UTF-8 text. macOS Notes / Pages exports particularly often include BOMs and surrogate pairs that trip the validator.";
+        readonly skillAnchor: "skills#upload";
+        readonly legacyErrorCode: "invalid_encoding";
+        readonly retryable: false;
+    };
+    readonly "skills.empty_content": {
+        readonly expected: "non-empty SKILL.md body after parsing the frontmatter";
+        readonly hint: "The skill file parsed successfully but has no body content after the YAML frontmatter. Add at least one prose paragraph after the `---` block; that's the actual skill instructions the agent will read.";
+        readonly skillAnchor: "skills#shape";
+        readonly legacyErrorCode: "empty_content";
+        readonly retryable: false;
+    };
+    readonly "skills.invalid_name": {
+        readonly expected: "skill name matching `[a-z0-9][a-z0-9-]*` (kebab-case)";
+        readonly hint: "Skill slugs are restricted to lowercase letters, digits, and hyphens (no underscores, dots, or uppercase). The first character must not be a hyphen. Pick a kebab-case slug such as `my-skill` or `obsidian-graduate-v2`.";
+        readonly skillAnchor: "skills#naming";
+        readonly legacyErrorCode: "invalid_name";
+        readonly retryable: false;
+    };
+    readonly "skills.invalid_description": {
+        readonly expected: "single-line description field (no \\r or \\n)";
+        readonly hint: "Frontmatter description must be one line. Embedded newlines break the regex-based parser the daemon uses to update skills. Re-write the description as a single sentence; long prose goes in the body.";
+        readonly skillAnchor: "skills#frontmatter";
+        readonly legacyErrorCode: "invalid_description";
+        readonly retryable: false;
+    };
+    readonly "skills.validation_error": {
+        readonly expected: "JSON body matching skillCreateSchema / skillUpdateSchema";
+        readonly hint: "Zod validation failed. The `details` array carries per-field paths — fix and resubmit. POST /skills needs `{ name, description, content, allowedTools? }`; PUT /skills/:name accepts a partial { description?, content?, allowedTools? }.";
+        readonly skillAnchor: "skills#schemas";
+        readonly legacyErrorCode: "validation_error";
+    };
+    readonly "skills.not_found": {
+        readonly expected: "an existing skill at agent-assets/skills/<slug>/SKILL.md (built-in) or user-skills/<slug>/SKILL.md";
+        readonly hint: "GET /skills to list current slugs. Built-ins are read-only; user skills can be created via POST /skills or POST /skills/upload. Do not retry the same slug — verify spelling first.";
+        readonly skillAnchor: "skills#crud";
+        readonly legacyErrorCode: "not_found";
+        readonly retryable: false;
+    };
+    readonly "skills.already_exists": {
+        readonly expected: "skill slug not yet present in user-skills/";
+        readonly hint: "A user skill with this slug already exists. Either PUT /skills/:name to update it, or DELETE /skills/:name first if you want a fresh create. POST /skills/upload overwrites by default.";
+        readonly skillAnchor: "skills#crud";
+        readonly legacyErrorCode: "already_exists";
+        readonly retryable: false;
+    };
+    readonly "skills.write_failed": {
+        readonly expected: "successful disk write to the user-skills directory";
+        readonly hint: "Internal write error — the user-skills directory may be on a read-only mount or out of space. `message` carries the verbatim cause. Do not auto-retry; surface to the user.";
+        readonly skillAnchor: "skills#errors";
+        readonly legacyErrorCode: "write_failed";
+        readonly retryable: false;
+    };
+    readonly "skills.delete_failed": {
+        readonly expected: "successful rmSync on the user-skills/<slug>/ directory";
+        readonly hint: "Internal delete error — `message` carries the verbatim cause. Common: file locked by an editor, permission denied. Do not auto-retry; surface to the user.";
+        readonly skillAnchor: "skills#errors";
+        readonly legacyErrorCode: "delete_failed";
+        readonly retryable: false;
+    };
+    readonly "managed_tasks.invalid_id": {
+        readonly expected: "managed-task id matching `mt_<n>` (alphanumeric)";
+        readonly hint: "Managed-task ids are `mt_<n>` (e.g. `mt_1`, `mt_42`). GET /api/managed-tasks to list current ids. Pass the id verbatim — do NOT URL-encode the underscore.";
+        readonly skillAnchor: "managed-tasks#id-format";
+        readonly legacyErrorCode: "invalid_id";
+        readonly retryable: false;
+    };
+    readonly "managed_tasks.not_found": {
+        readonly expected: "an existing managed_tasks row matching :id";
+        readonly hint: "Either the id is wrong or the row was already deleted (DELETE /api/managed-tasks/:id). GET /api/managed-tasks to list current rows. Stopped rows are pruned — `mt_<n>` is not reused; pick a different id rather than re-creating with the same one.";
+        readonly skillAnchor: "managed-tasks#crud";
+        readonly legacyErrorCode: "not_found";
+        readonly retryable: false;
+    };
+    readonly "managed_tasks.validation_error": {
+        readonly expected: "JSON body matching managedTaskCreate/Patch/RunResult schema";
+        readonly hint: "Zod validation failed. `details` carries per-field issues. Common: cadence must match `daily|weekly|monthly|<RRULE>`; intent must be a non-empty string; recurrenceRule must include freq + interval. Read each `path`/`message` and resubmit.";
+        readonly skillAnchor: "managed-tasks#schemas";
+        readonly legacyErrorCode: "validation_error";
+    };
+    readonly "managed_tasks.invalid_limit": {
+        readonly expected: "positive integer <= 200 in the `limit` query parameter";
+        readonly hint: "`?limit=` accepts an integer between 1 and 200. Pass `?limit=50` for the default page size; values above 200 are rejected to keep `agent_actions` scans bounded. URL-encoded or decimal values are rejected.";
+        readonly skillAnchor: "managed-tasks#pagination";
+        readonly legacyErrorCode: "invalid_limit";
+        readonly constraint: {
+            readonly type: "integer";
+            readonly minimum: 1;
+            readonly maximum: 200;
+        };
+    };
+    readonly "managed_tasks.invalid_cursor": {
+        readonly expected: "positive integer in the `before_id` query parameter";
+        readonly hint: "Pagination cursor is the smallest id in the previous page (returned as `nextCursor`). Pass it verbatim — URL-encoded and decimal values are rejected. Omit the parameter for the first page.";
+        readonly skillAnchor: "managed-tasks#pagination";
+        readonly legacyErrorCode: "invalid_cursor";
+        readonly constraint: {
+            readonly type: "integer";
+            readonly minimum: 1;
+        };
+    };
+    readonly "managed_tasks.cap_reached": {
+        readonly expected: "active managed-tasks count below the configured cap";
+        readonly hint: "The active-tasks cap (default 20; configured via `managedTasksMaxActive` in /settings) is hit. Either DELETE one before registering a new task, or raise the cap via /settings → Management. Surface to the user; the cap is intentional.";
+        readonly skillAnchor: "managed-tasks#capacity";
+        readonly legacyErrorCode: "cap_reached";
+        readonly retryable: false;
+    };
+    readonly "managed_tasks.duplicate": {
+        readonly expected: "no managed_tasks row with the same (app_normalized, cadence) pair";
+        readonly hint: "A managed task already covers this (app, cadence) — the response's `item` carries the existing row. To replace it, DELETE the existing id first. To extend it (e.g. change cadence), PATCH /api/managed-tasks/:id on the existing row.";
+        readonly skillAnchor: "managed-tasks#duplicate-handling";
+        readonly legacyErrorCode: "duplicate";
+        readonly retryable: false;
+    };
+    readonly "managed_tasks.internal_error": {
+        readonly expected: "no unexpected exception inside the transaction";
+        readonly hint: "Internal error inside a managed-tasks CRUD/run-now/rename-app/run-result transaction. The error is logged server-side; the route does not surface implementation detail. Do not auto-retry — typically a schema/migration drift.";
+        readonly skillAnchor: "managed-tasks#errors";
+        readonly legacyErrorCode: "internal_error";
+        readonly retryable: false;
+    };
+    readonly "apple_calendar.not_configured": {
+        readonly expected: "Apple Calendar credentials saved + service initialised";
+        readonly hint: "Apple Calendar is unavailable — either no credentials are saved (POST /apple-calendar/credentials with `{ email, appPassword }`) or the cached service rejected the iCloud handshake. Notify the user to add an app-specific password from https://appleid.apple.com → App-Specific Passwords. Skip Apple Calendar branches of routines until reconfigured.";
+        readonly skillAnchor: "apple-calendar#configuration";
+        readonly legacyErrorCode: "apple_calendar_not_configured";
+        readonly retryable: false;
+    };
+    readonly "apple_calendar.auth_failed": {
+        readonly expected: "iCloud CalDAV accepts the Apple ID + app-specific password";
+        readonly hint: "Apple ID auth failed. Common causes: regular password used instead of an app-specific one; password was revoked from appleid.apple.com; account requires reauth after iCloud security update. Re-issue an app-specific password and POST /apple-calendar/credentials again — there's no silent recovery.";
+        readonly skillAnchor: "apple-calendar#auth";
+        readonly legacyErrorCode: "auth_failed";
+        readonly retryable: false;
+    };
+    readonly "apple_calendar.validation_error": {
+        readonly expected: "request body matching the Apple Calendar schema";
+        readonly hint: "Zod validation failed (`.strict()`) — Apple Calendar deliberately rejects Google-shaped extras like `attendees`, `reminders`, `recurrence`, `visibility`. Drop those fields. The `details` array carries per-field paths. iCloud event create body: `{ summary, start, end, description?, location? }`.";
+        readonly skillAnchor: "apple-calendar#event-shape";
+        readonly legacyErrorCode: "validation_error";
+    };
+    readonly "apple_calendar.invalid_date": {
+        readonly expected: "'today' or YYYY-MM-DD `date` query parameter";
+        readonly hint: "The `?date=` query rejects shapes other than the literal 'today' or a calendar date like '2026-05-15'. Use localDateStr(now, <timezone>) shape — RFC-3339 timestamps are rejected.";
+        readonly skillAnchor: "apple-calendar#list-events";
+        readonly constraint: {
+            readonly type: "string";
+            readonly pattern: "^(today|\\d{4}-\\d{2}-\\d{2})$";
+        };
+    };
+    readonly "apple_calendar.not_found": {
+        readonly expected: "an existing iCloud event matching :id";
+        readonly hint: "The event id does not resolve to any iCloud event. Recurring-instance ids cannot be modified directly (use the master event id). Re-list with GET /apple-calendar/events?date=<day> to find the master id.";
+        readonly skillAnchor: "apple-calendar#event-id";
+        readonly legacyErrorCode: "not_found";
+        readonly retryable: false;
+    };
+    readonly "apple_calendar.recurring_instance_unsupported": {
+        readonly expected: "master event id (not a per-instance recurrence override)";
+        readonly hint: "iCloud CalDAV cannot mutate single instances of a recurring event in this build. Either edit the master (changes apply to the whole series) or skip the modification and notify the user. The `message` field carries the offending instance id verbatim.";
+        readonly skillAnchor: "apple-calendar#recurring";
+        readonly legacyErrorCode: "recurring_instance_unsupported";
+        readonly retryable: false;
+    };
+    readonly "apple_calendar.upstream_error": {
+        readonly expected: "successful iCloud CalDAV round-trip";
+        readonly hint: "iCloud CalDAV returned an error (surfaced as 502 to the agent). `message` is iCloud's verbatim text. Branches: 5xx → Apple maintenance window or transient; retry once after 60s, then skip. 401 → app-specific password revoked or expired; notify the user with this exact prompt: 'Apple Calendar access expired — please go to https://appleid.apple.com → App-Specific Passwords, issue a new password, and paste it into /settings/integrations → Apple Calendar.' Then skip. 412 → etag mismatch from concurrent edit; GET the event again to refresh the etag and replay the change ONCE. Do NOT chain more than one retry per error code in a single turn.";
+        readonly skillAnchor: "apple-calendar#errors";
+        readonly legacyErrorCode: "apple_calendar_error";
+        readonly retryable: true;
+    };
+    readonly "agent.daemon_starting": {
+        readonly expected: "daemon startup complete";
+        readonly hint: "Daemon still initialising (typical window: 1-3 s after process spawn). Wait ~3s and retry ONCE; if the second attempt also returns daemon_starting, abandon this turn — startup that takes >30s indicates a stuck migration or a port conflict the agent cannot resolve. Surface ONE notification suggesting `aitne status` / `aitne doctor`, then exit. Never tight-loop on this code.";
+        readonly skillAnchor: "agent#startup-gate";
+        readonly legacyErrorCode: "daemon_starting";
+        readonly retryable: true;
+    };
+    readonly "agent.hourly_check_unavailable": {
+        readonly expected: "triggerHourlyCheck wired into the API server";
+        readonly hint: "POST /agent/run-now/hourly was called before the hourly-check engine was wired (typically only the first ~1s of boot). Wait ~3s and retry.";
+        readonly skillAnchor: "agent#run-now";
+        readonly legacyErrorCode: "hourly_check_unavailable";
+        readonly retryable: true;
+    };
+    readonly "agent.roadmap_maintenance_unavailable": {
+        readonly expected: "triggerRoadmapMaintenance wired into the API server";
+        readonly hint: "Roadmap maintenance dispatcher not yet wired. Wait ~3s and retry; this fires only during boot.";
+        readonly skillAnchor: "agent#roadmap-maintenance";
+        readonly legacyErrorCode: "roadmap_maintenance_unavailable";
+        readonly retryable: true;
+    };
+    readonly "agent.roadmap_maintenance_failed": {
+        readonly expected: "successful roadmap maintenance pass";
+        readonly hint: "Maintenance threw mid-pass; `message` carries the underlying error. Common: roadmap.md lock contention, schema drift, or malformed roadmap row. Do not auto-retry — inspect daemon logs.";
+        readonly skillAnchor: "agent#roadmap-maintenance";
+        readonly legacyErrorCode: "roadmap_maintenance_failed";
+        readonly retryable: false;
+    };
+    readonly "agent.invalid_requested_model": {
+        readonly expected: "'sonnet' | 'opus' | omitted";
+        readonly hint: "`requestedModel` accepts the alias 'sonnet' or 'opus'. Omit to let process_backend_config decide; pin 'opus' for high-complexity multi-file analysis.";
+        readonly skillAnchor: "agent#requestedModel";
+        readonly legacyErrorCode: "invalid_requestedModel";
+        readonly constraint: {
+            readonly type: "enum";
+            readonly enum: readonly ["sonnet", "opus"];
+        };
+    };
+    readonly "agent.notify_validation_error": {
+        readonly expected: "request body matching notifyRequestSchema";
+        readonly hint: "Body failed Zod validation. `details` carries per-field paths. Required: `message` (string). Optional: `platform`/`platforms`, `priority` ('critical'|'high'|'normal'|'low').";
+        readonly skillAnchor: "agent#notify";
+        readonly legacyErrorCode: "validation_error";
+    };
+    readonly "agent.schedule_dm_validation_error": {
+        readonly expected: "request body matching scheduleDmRequestSchema";
+        readonly hint: "POST /schedule/dm body shape: `{ time: ISO8601, message: string, platform?, platforms?, importance? }`. `details` lists per-field paths. Use POST /api/schedule (batch) for LLM runs — /schedule/dm is the no-LLM precomposed-DM path.";
+        readonly skillAnchor: "schedule#dm-shape";
+        readonly legacyErrorCode: "validation_error";
+    };
+    readonly "agent.invalid_time": {
+        readonly expected: "ISO8601 string parseable by Date() and >= now - 60s";
+        readonly hint: "`time` failed Date.parse() or was more than 1 minute in the past. `details` disambiguates which check failed. Use `2026-05-15T14:30:00-04:00` shape with explicit timezone offset.";
+        readonly skillAnchor: "schedule#scheduledFor-bounds";
+        readonly legacyErrorCode: "invalid_time";
+        readonly constraint: {
+            readonly type: "iso8601";
+            readonly required: true;
+        };
+    };
+    readonly "agent.invalid_status": {
+        readonly expected: "comma-separated subset of 'pending,running,completed,failed,skipped'";
+        readonly hint: "GET /schedule `?status=` accepts a CSV of the five statuses. `details` names the offending token. Default is 'pending,running'; pass 'completed,failed,skipped' to see history.";
+        readonly skillAnchor: "schedule#status-filter";
+        readonly legacyErrorCode: "invalid_status";
+    };
+    readonly "agent.invalid_id": {
+        readonly expected: "positive integer id from GET /schedule";
+        readonly hint: "`:id` must be a positive integer. GET /schedule for current pending ids. URL-encoded and decimal ids are rejected.";
+        readonly skillAnchor: "schedule#crud";
+        readonly legacyErrorCode: "invalid_id";
+        readonly constraint: {
+            readonly type: "integer";
+            readonly minimum: 1;
+        };
+    };
+    readonly "agent.not_found": {
+        readonly expected: "an existing agent_schedule row matching :id";
+        readonly hint: "PATCH/DELETE on a schedule id that doesn't exist. The row may have been picked up by the scheduler (status moved to running) or already cancelled. GET /schedule for current ids.";
+        readonly skillAnchor: "schedule#crud";
+        readonly legacyErrorCode: "not_found";
+        readonly retryable: false;
+    };
+    readonly "agent.schedule_conflict": {
+        readonly expected: "row in 'pending' status (running/completed/failed are immutable)";
+        readonly hint: "Edits and cancels only work on `pending` schedules. `details` carries the row's current status. Per-state recovery: 'running' → the scheduler has already picked the row up; cannot cancel mid-flight (the running session must finish). If you want a different action, POST /api/schedule with a NEW row scheduled for a later time. 'completed' / 'failed' / 'skipped' → terminal, the row is archive-only; do not retry — its outcome is final. If the conflict was for a cancel intent the user really needs to honour, send them a notification with the schedule id and current status rather than looping.";
+        readonly skillAnchor: "schedule#crud";
+        readonly legacyErrorCode: "conflict";
+        readonly retryable: false;
+    };
+    readonly "agent.invalid_field": {
+        readonly expected: "field set respecting the task_type contract";
+        readonly hint: "PATCH /schedule/:id field/task_type mismatch — `details` names the offending field. Matrix: task_type='wake' or 'dm_session' or 'check' → set `description` and optionally `prompt`, NOT `message`. task_type='dm' (precomposed) → set `message`, NOT `description` and NOT `prompt` (dm rows do not run a model, so prompt would be ignored and is rejected). `time` and `taskContext` are accepted on all types; `model` is accepted on 'wake'/'dm_session'/'check' but ignored on 'dm'. To switch a row's shape, DELETE and re-create rather than PATCH across the dm boundary.";
+        readonly skillAnchor: "schedule#field-by-type";
+        readonly legacyErrorCode: "invalid_field";
+        readonly retryable: false;
+    };
+    readonly "agent.no_changes": {
+        readonly expected: "PATCH body containing at least one mutable field";
+        readonly hint: "PATCH /schedule/:id needs at least one of { time, description, message, prompt, model, taskContext }. Omitting all is rejected.";
+        readonly skillAnchor: "schedule#crud";
+        readonly legacyErrorCode: "no_changes";
+        readonly retryable: false;
+    };
+    readonly "agent.invalid_target": {
+        readonly expected: "target = 'today' | 'roadmap'";
+        readonly hint: "POST /agent/regenerate body needs `{ target: 'today' | 'roadmap' }`. Other values rejected. 'today' refreshes today.md via routine.today_refresh; 'roadmap' refreshes roadmap.md.";
+        readonly skillAnchor: "agent#regenerate";
+        readonly constraint: {
+            readonly type: "enum";
+            readonly enum: readonly ["today", "roadmap"];
+        };
+    };
+    readonly "agent.roadmap_refresh_unavailable": {
+        readonly expected: "triggerRoadmapRefresh wired into the API server";
+        readonly hint: "Roadmap refresh dispatcher not currently wired (boot-time only). Wait ~3s and retry; if persistent, surface to user — daemon is in degraded mode.";
+        readonly skillAnchor: "agent#regenerate";
+        readonly retryable: true;
+    };
+    readonly "agent.event_bus_unavailable": {
+        readonly expected: "EventBus wired into the API server";
+        readonly hint: "EventBus unavailable, so today.md regeneration cannot be dispatched. Wait ~3s and retry; if persistent, run `aitne status`.";
+        readonly skillAnchor: "agent#regenerate";
+        readonly retryable: true;
+    };
+    readonly "agent.action_log_validation_error": {
+        readonly expected: "request body matching actionLogRequestSchema";
+        readonly hint: "Body failed Zod validation. `details` carries per-field paths. Required: `actionType` (string), `result` (string). Use `<resource>.<verb>` shape for actionType (e.g. `mail.archive`).";
+        readonly skillAnchor: "agent#action-log";
+        readonly legacyErrorCode: "validation_error";
+    };
+    readonly "agent.outbound_purchase_template_refused": {
+        readonly expected: "an outbound message free of reserved purchase-confirmation markers";
+        readonly hint: "Refused: this message carries a reserved purchase-confirmation marker (\"🔐 Aitne purchase confirmation\", \"[purchase-verify:\", or \"Approved on …\"). Those markers are emitted exclusively by the daemon's unforgeable purchase-system-message-sender (MANAGED_CHROMIUM_IMPLEMENTATION_PLAN.md §17.7); an agent-originated message claiming to be a purchase confirmation is structurally blocked as a spoof. Remove the reserved marker text from `message` and resend a normal notification — do not compose purchase confirmations yourself.";
+        readonly skillAnchor: "agent#notify";
+        readonly legacyErrorCode: "outbound_purchase_template_refused";
+        readonly retryable: false;
+    };
+    readonly "profile_questions.path_required": {
+        readonly expected: "non-empty 'path' query parameter (context-relative)";
+        readonly hint: "GET /api/profile-questions/slot-filled needs `?path=<relative>` — e.g. `?path=identity/profile`. Trailing `.md` is optional; `.base` files are rejected (use a prose markdown file). Add `&section=<heading>` to scope to one heading and `&anchor=<bullet-key>` to scope to one bullet.";
+        readonly skillAnchor: "profile-questions#slot-filled";
+        readonly legacyErrorCode: "missing_path";
+        readonly constraint: {
+            readonly type: "string";
+            readonly required: true;
+        };
+    };
+    readonly "profile_questions.path_invalid": {
+        readonly expected: "context-relative path inside the vault (no '..', no absolute)";
+        readonly hint: "The path failed traversal validation. Use forward-slash, vault-relative paths only — e.g. `identity/profile`, `identity/people/colleague-jane`. Reject `..` segments, absolute paths, and `.base` files (those are Obsidian view configs, not prose).";
+        readonly skillAnchor: "profile-questions#slot-filled";
+        readonly legacyErrorCode: "invalid_path";
+        readonly constraint: {
+            readonly type: "string";
+        };
+        readonly retryable: true;
+    };
+    readonly "profile_questions.read_failed": {
+        readonly expected: "readable file at the resolved path";
+        readonly hint: "Filesystem read failed mid-probe (EACCES / EIO). The file exists but the daemon couldn't open it. Likely cause: vault was moved or permissions changed while the daemon was running. Re-check the externalObsidianVaultPath config and retry; if persistent, surface to user — daemon needs vault access.";
+        readonly skillAnchor: "profile-questions#slot-filled";
+        readonly legacyErrorCode: "read_failed";
+        readonly retryable: false;
+    };
+    readonly "entities.missing_query": {
+        readonly expected: "either tier-1 (source[, external_id]) or tier-2 (domain, type, date) query parameters";
+        readonly hint: "GET /api/entities needs a query shape. Tier-1 exact: `?source=<app>&external_id=<eid>`. Tier-1 bias: `?source=<app>` alone (list all entities for the source so you can pick a dominant domain/type). Tier-2: `?domain=<domain>&type=<singular>&date=YYYY-MM-DD`. Don't mix tiers in one call.";
+        readonly skillAnchor: "entities#query-shape";
+        readonly legacyErrorCode: "missing_query";
+        readonly retryable: true;
+    };
+    readonly "entities.ambiguous_query": {
+        readonly expected: "exactly one tier — not both at the same time";
+        readonly hint: "The request mixed tier-1 (source/external_id) and tier-2 (domain/type/date) parameters. Drop one set: tier-1 is for known external ids (e.g. gmail thread id), tier-2 is for discovery by category. Pick the side that matches your input.";
+        readonly skillAnchor: "entities#query-shape";
+        readonly legacyErrorCode: "ambiguous_query";
+        readonly retryable: true;
+    };
+    readonly "entities.validation_error": {
+        readonly expected: "well-formed query per the tier rules";
+        readonly hint: "A field violated its constraint. Common causes: `external_id` set without `source` (tier-1 needs both for exact match); tier-2 missing one of domain/type/date; `date` not ISO YYYY-MM-DD; `limit` not a positive integer; unknown `domain` / `type` enum value. The `message` field carries the specific violation — read it verbatim and fix that field only.";
+        readonly skillAnchor: "entities#query-shape";
+        readonly legacyErrorCode: "validation_error";
+        readonly retryable: true;
+    };
+    readonly "entities.not_found": {
+        readonly expected: "an entity row matching the supplied path";
+        readonly hint: "GET /api/entities/by-path?path=<...> returned no row. The path is a vault-relative markdown path (e.g. `work/meetings/2026-05-15-launch-review.md`). Check the slug spelling, or use GET /api/entities?source=<app> to discover the canonical path the registrar wrote.";
+        readonly skillAnchor: "entities#by-path";
+        readonly legacyErrorCode: "not_found";
+        readonly retryable: false;
+    };
+    readonly "sot_bindings.invalid_category": {
+        readonly expected: "non-empty category slug in the URL";
+        readonly hint: "GET /api/sot-bindings/:category needs a trimmed category like `email`, `calendar`, `task`. Empty strings (e.g. `/sot-bindings/%20`) are rejected. List all categories first via GET /api/sot-bindings.";
+        readonly skillAnchor: "sot-bindings#categories";
+        readonly legacyErrorCode: "invalid_category";
+        readonly retryable: true;
+    };
+    readonly "sot_bindings.not_found": {
+        readonly expected: "an existing binding row for the supplied category";
+        readonly hint: "The category has no binding registered yet. Use GET /api/sot-bindings to enumerate the live rows, or PUT /api/sot-bindings to install a new binding (body shape: an array or `{items: [...]}`).";
+        readonly skillAnchor: "sot-bindings#categories";
+        readonly legacyErrorCode: "not_found";
+        readonly retryable: false;
+    };
+    readonly "sot_bindings.validation_error": {
+        readonly expected: "array of binding rows, or `{items: [...]}`";
+        readonly hint: "PUT body must be a JSON array or `{items: [{category, source, ...}]}`. Each row needs `category` (string) and at least one source descriptor. Duplicates by category are rejected as defense-in-depth — the file render is keyed on category position and silent overwrites would corrupt the user's mental model. Read `details`/`message` for the exact field that failed.";
+        readonly skillAnchor: "sot-bindings#put-shape";
+        readonly legacyErrorCode: "validation_error";
+        readonly constraint: {
+            readonly type: "array";
+            readonly required: true;
+        };
+        readonly retryable: true;
+    };
+    readonly "sot_bindings.duplicate_category": {
+        readonly expected: "at most one row per category in the PUT body";
+        readonly hint: "Two or more rows shared the same `category` value. De-dupe in the caller — pick the row you want (most specific) and drop the rest. The duplicate's category value is carried on the response as `category` for log triage.";
+        readonly skillAnchor: "sot-bindings#put-shape";
+        readonly legacyErrorCode: "duplicate_category";
+        readonly retryable: true;
+    };
+    readonly "sot_bindings.internal_error": {
+        readonly expected: "successful DB write";
+        readonly hint: "The SoT-bindings table write failed at the SQLite layer (disk full, lock contention, or corruption). Retry once; if persistent, run `aitne doctor` to verify the DB and surface to user.";
+        readonly skillAnchor: "sot-bindings#put-shape";
+        readonly legacyErrorCode: "internal_error";
+        readonly retryable: true;
+    };
+    readonly "docs.doc_not_found": {
+        readonly expected: "an existing doc with the supplied slug in fts_docs";
+        readonly hint: "No doc indexed under `slug`. Slugs come from doc frontmatter and look like `appendices/voice-transcription` or `design/02-event-pipeline`. Search first via GET /api/docs/search?q=<term> to find the canonical slug, or GET /api/docs to list everything.";
+        readonly skillAnchor: "docs#by-slug";
+        readonly legacyErrorCode: "doc_not_found";
+        readonly retryable: false;
+    };
+    readonly "docs.qa_adapter_unavailable": {
+        readonly expected: "DocsQAAdapter wired into the API server";
+        readonly hint: "The docs-QA bus is not initialized in this daemon instance. Most likely an in-test boot or a degraded startup; the dashboard's QA panel cannot operate. Wait a few seconds and retry; if persistent, run `aitne status` and re-launch the daemon.";
+        readonly skillAnchor: "docs#qa-bus";
+        readonly legacyErrorCode: "qa_adapter_unavailable";
+        readonly retryable: true;
+    };
+    readonly "docs.channel_not_connected": {
+        readonly expected: "channelId minted by GET /docs/qa/stream and still open";
+        readonly hint: "POST /docs/qa/messages was called with a channelId the adapter does not recognise. The channel must be minted by the SSE stream's first event (D5 SSE-first contract). Open GET /docs/qa/stream first, capture the channelId, then POST messages against it. The channel auto-closes when the SSE EventSource disconnects.";
+        readonly skillAnchor: "docs#qa-channel";
+        readonly legacyErrorCode: "channel_not_connected";
+        readonly retryable: false;
+    };
+    readonly "docs.validation_error": {
+        readonly expected: "request body matching qaMessageSchema (channelId, content, scope, …)";
+        readonly hint: "QA message body failed Zod validation. Required fields: `channelId` (UUID from the SSE stream), `content` (non-empty string). Optional: `scope`, `context`, `modelId`. Read `details` for the per-field path.";
+        readonly skillAnchor: "docs#qa-message-shape";
+        readonly legacyErrorCode: "validation_error";
+        readonly constraint: {
+            readonly type: "object";
+            readonly required: true;
+        };
+        readonly retryable: true;
+    };
+    readonly "docs.model_not_registered": {
+        readonly expected: "modelId registered for the active QA backend";
+        readonly hint: "The picker-supplied `modelId` is not in the registered list for the resolved QA backend. Drop the `modelId` field (the daemon picks the canonical medium-tier model), or pick a registered id from GET /api/docs/qa/config.";
+        readonly skillAnchor: "docs#qa-model-pick";
+        readonly legacyErrorCode: "model_not_registered";
+        readonly retryable: true;
+    };
+    readonly "docs.model_tier_locked": {
+        readonly expected: "modelId at the medium tier (not lite, not high)";
+        readonly hint: "The QA path is hard-wired to the medium tier to avoid silently draining Opus quota. The supplied `modelId` is registered but at the wrong tier. Pick a medium-tier model from GET /api/docs/qa/config or drop the field entirely.";
+        readonly skillAnchor: "docs#qa-model-pick";
+        readonly legacyErrorCode: "model_tier_locked";
+        readonly retryable: true;
+    };
+    readonly "git_templates.invalid_kind": {
+        readonly expected: "'project' or 'git-repo' in the :kind URL segment";
+        readonly hint: "The `:kind` segment must be exactly `project` (full project doc template) or `git-repo` (repo-only doc template). Other values (e.g. `repo`, `Git-Repo`) are rejected — these are the only two on-disk templates the daemon ships.";
+        readonly skillAnchor: "git-templates#kinds";
+        readonly legacyErrorCode: "invalid_kind";
+        readonly constraint: {
+            readonly type: "enum";
+            readonly enum: readonly ["project", "git-repo"];
+            readonly required: true;
+        };
+        readonly retryable: true;
+    };
+    readonly "git_templates.content_required": {
+        readonly expected: "string body at `content` (the template markdown source)";
+        readonly hint: "PUT /api/git/templates/:kind needs `{ \"content\": \"# Template…\\n…\" }`. The value must be a string — sending a number, array, or omitting the key returns 400. Read the active body first via GET /api/git/templates/:kind to seed your edit.";
+        readonly skillAnchor: "git-templates#editor";
+        readonly legacyErrorCode: "content_required";
+        readonly constraint: {
+            readonly type: "string";
+            readonly required: true;
+        };
+        readonly retryable: true;
+    };
+    readonly "git_templates.read_failed": {
+        readonly expected: "readable template file (or absent override = bundled fallback)";
+        readonly hint: "Filesystem read of the template override failed (EACCES / EIO). The bundled template is still usable — drop the override file or PUT a fresh body. `message` carries the underlying fs error verbatim.";
+        readonly skillAnchor: "git-templates#editor";
+        readonly legacyErrorCode: "read_failed";
+        readonly retryable: true;
+    };
+    readonly "git_templates.write_failed": {
+        readonly expected: "successful write to the override path";
+        readonly hint: "Failed to write the template override (disk full, permissions, or path collision). Verify dataDir is writable (`aitne doctor`), then retry. `message` carries the underlying fs error.";
+        readonly skillAnchor: "git-templates#editor";
+        readonly legacyErrorCode: "write_failed";
+        readonly retryable: true;
+    };
+    readonly "git_templates.body_too_large": {
+        readonly expected: "template body ≤ 64 KB";
+        readonly hint: "Template payload exceeded the 64 KB cap. Trim boilerplate, or split into two template kinds. Skill / agent-profile prose belongs in agent-assets/ — only the rendered project doc template lives here.";
+        readonly skillAnchor: "git-templates#editor";
+        readonly legacyErrorCode: "body_too_large";
+        readonly retryable: false;
+    };
+    readonly "git_templates.in_progress": {
+        readonly expected: "no in-flight retemplate run";
+        readonly hint: "A retemplate run is already scheduled / executing (409). Wait for the existing run to finish, or check status via GET /api/git/templates/retemplate/status. The response carries `scheduleId` and `correlationId` for the in-flight run so the dashboard can render 'already running' state.";
+        readonly skillAnchor: "git-templates#apply";
+        readonly legacyErrorCode: "in_progress";
+        readonly retryable: true;
+    };
+    readonly "git_templates.missing_template": {
+        readonly expected: "template file present for the supplied kind";
+        readonly hint: "The retemplate apply call cannot proceed because the template file isn't readable yet (no override AND the bundled fallback is missing — possibly a corrupt install). Run `aitne doctor` or reinstall. The `kind` field on the response identifies which template was missing.";
+        readonly skillAnchor: "git-templates#apply";
+        readonly legacyErrorCode: "missing_template";
+        readonly retryable: false;
+    };
+    readonly "git_templates.no_targets": {
+        readonly expected: "at least one watched git repository for the apply call";
+        readonly hint: "No git repositories are registered for the retemplate scope (422). Add a watched repo via POST /api/repositories first, or pick a different kind. GET /api/repositories?filter=git lists the live set.";
+        readonly skillAnchor: "git-templates#apply";
+        readonly legacyErrorCode: "no_targets";
+        readonly retryable: false;
+    };
+    readonly "git_templates.invalid_slug": {
+        readonly expected: "lowercase kebab-case slug ([a-z0-9]([a-z0-9-]*[a-z0-9])?)";
+        readonly hint: "POST /api/git/templates/retemplate/file body needs `slug` matching `^[a-z0-9][a-z0-9-]*[a-z0-9]$` (or a single `[a-z0-9]` char). Underscores, uppercase, and leading/trailing hyphens are rejected. Slugs come from the apply call's `targets[].slug` — echo that value verbatim.";
+        readonly skillAnchor: "git-templates#per-file-report";
+        readonly legacyErrorCode: "invalid_slug";
+        readonly constraint: {
+            readonly type: "string";
+            readonly pattern: "^[a-z0-9][a-z0-9-]*[a-z0-9]$";
+            readonly required: true;
+        };
+        readonly retryable: true;
+    };
+    readonly "git_templates.invalid_status": {
+        readonly expected: "one of 'started' | 'completed' | 'skipped' | 'failed'";
+        readonly hint: "Per-file `status` must be exactly one of the four lifecycle values. `started` is a work-begin marker (no audit row). `completed`/`skipped`/`failed` are terminal — each emits one `agent_actions` row tagged `git.project.retemplate`. Don't invent intermediate states.";
+        readonly skillAnchor: "git-templates#per-file-report";
+        readonly legacyErrorCode: "invalid_status";
+        readonly constraint: {
+            readonly type: "enum";
+            readonly enum: readonly ["started", "completed", "skipped", "failed"];
+            readonly required: true;
+        };
+        readonly retryable: true;
+    };
+    readonly "git_templates.no_active_run": {
+        readonly expected: "an active retemplate run before posting per-file status";
+        readonly hint: "No retemplate run is in flight; per-file reports are only accepted while the parent run holds its slot in `runtime_state` (409). The apply call (POST /api/git/templates/:kind/apply) must succeed first and seed the status grid.";
+        readonly skillAnchor: "git-templates#per-file-report";
+        readonly legacyErrorCode: "no_active_run";
+        readonly retryable: false;
+    };
+    readonly "git_templates.correlation_mismatch": {
+        readonly expected: "correlationId matching the in-flight retemplate run";
+        readonly hint: "The supplied `correlationId` does not match the active run's id (409). Another retemplate run started between your apply and this report. Re-read GET /api/git/templates/retemplate/status to confirm the live run's id, then echo that value in subsequent reports.";
+        readonly skillAnchor: "git-templates#per-file-report";
+        readonly legacyErrorCode: "correlation_mismatch";
+        readonly retryable: false;
+    };
+    readonly "git_templates.slug_not_in_run": {
+        readonly expected: "slug present in the active run's target list";
+        readonly hint: "The supplied `slug` is not one of the active run's targets (404). Slugs are pinned at apply time — adding a new target mid-run is not supported. Re-check the slug spelling against the apply response's `targets[].slug` array.";
+        readonly skillAnchor: "git-templates#per-file-report";
+        readonly legacyErrorCode: "slug_not_in_run";
+        readonly retryable: false;
+    };
+    readonly "integrations.unknown_integration": {
+        readonly expected: "integration key registered in the daemon (e.g. gmail, google_calendar, notion)";
+        readonly hint: "The `:key` URL segment is not a registered integration. Get the live list from GET /api/integrations (returns every key the daemon knows about, with mode + backend). Keys are case-sensitive snake_case: `gmail`, `google_calendar`, `outlook_mail`, `outlook_calendar`, `notion` — not `Gmail` / `outlook-mail`.";
+        readonly skillAnchor: "integrations#keys";
+        readonly legacyErrorCode: "unknown_integration";
+        readonly retryable: false;
+    };
+    readonly "integrations.invalid_json_body": {
+        readonly expected: "valid JSON object body (parse-able)";
+        readonly hint: "POST /api/integrations/:key/probe expects either `null`/empty (= cached read), or `{ backend?, tools?, liveProbe? }`. Parse-level failure means the body wasn't valid JSON at all — check Content-Type: application/json and that no trailing commas / unquoted keys snuck in.";
+        readonly skillAnchor: "integrations#probe";
+        readonly legacyErrorCode: "invalid_json_body";
+        readonly constraint: {
+            readonly type: "json";
+            readonly required: true;
+        };
+        readonly retryable: true;
+    };
+    readonly "integrations.invalid_limit": {
+        readonly expected: "positive integer (default 50, max 200)";
+        readonly hint: "`?limit=` must parse as an integer ≥ 1. Anything else falls back to 50, but a non-numeric value returns 400. The hard cap is 200 — larger values are silently clamped, smaller positive ints honoured.";
+        readonly skillAnchor: "integrations#recent-proxy-calls";
+        readonly legacyErrorCode: "invalid_limit";
+        readonly constraint: {
+            readonly type: "integer";
+            readonly minimum: 1;
+            readonly maximum: 200;
+        };
+        readonly retryable: true;
+    };
+    readonly "integrations.internal_error": {
+        readonly expected: "successful integration state update / probe persistence";
+        readonly hint: "Server-side failure during integration mode change or probe persistence. Typical causes: a `runtime_state.integration_flip_lock:<key>` left by a crashed flip blocks the next change (resolves after the lock TTL expires, ~60s); descriptor vs DB-row drift (an integration was removed from `packages/shared/src/integrations.ts` but a `direct` row still exists); SQLite write contention during a long-running migration. Retry ONCE after 5s. If still failing, do not loop — stop touching this integration's mode/probe this turn, surface ONE notification quoting the response's `message`, and proceed with other work. The flip lock alone does not block read endpoints, so observation consumption can continue.";
+        readonly skillAnchor: "integrations#internal-errors";
+        readonly legacyErrorCode: "internal_error";
+        readonly retryable: true;
+    };
+};
+export type AgentErrorCode = keyof typeof AGENT_ERROR_REGISTRY;