@aitne-sh/aitne 0.1.7 → 0.1.9

package/agent-assets/skills/schedule/SKILL.md

@@ -1,7 +1,6 @@
 ---
 name: schedule
 description: Load when scheduling a future agent wake-up, pre-composed DM, recurring task, or de-duping against existing pending schedules.
-when_to_use: Owns `/api/schedule`, `/api/schedule/dm`, and `/api/recurring-schedules`. `external-services` defers here for all time-based work.
 allowed-tools:
   - Bash(curl *)
   - Read
@@ -32,50 +31,18 @@ user but compound into duplicate DMs/notifications at fire time.
    PATCH the existing item if it needs updating — never register a
    parallel second one).
 3. **Recurring check.** `GET /api/recurring-schedules?enabled=true` to
-   confirm no recurring rule already covers this cadence (e.g. a daily
-   09:00 inbox triage). If covered, skip — the recurring instance will
-   regenerate on its own.
+   confirm no recurring rule/Agent already covers this cadence (e.g. a
+   daily 09:00 inbox triage, or the morning briefing). If covered, skip.
+   (Recurring *work* is created as an Agent via the `agent-create` skill;
+   recurring *DMs* via `POST /api/recurring-schedules` `taskType:dm_session`.)
 4. **`confirm_dedup_key` check (mandatory for `confirm:` sub-flow rows
    only).** When scheduling a `dm_session` row with
-   `taskContext.sub_flow="confirm"`, additionally filter
-   `GET /api/schedule?status=pending,running` by
-   `taskContext.confirm_dedup_key`. Skip if any match exists —
-   regardless of `scheduledFor` distance or description match. The
-   confirm sub-flow's chained-fire model (see `scheduled.dm.md`
-   §"Confirmation follow-up" Step 3) and a hot-thread defer (Step 1
-   check 1) both inherit the same dedup_key, so a successor or defer
-   row legitimately occupies the queue with the same key — a second
-   gate firing for the same topic MUST yield to it rather than
-   double-asking.
-
-   ```bash
-   curl -s "http://localhost:8321/api/schedule?status=pending,running" \
-     | jq --arg k "<gate>:<stable-topic>" \
-         '[.items[] | select(.taskContext.confirm_dedup_key == $k)] | length'
-   ```
-
-   If the count is `≥ 1`, log to `## Agent Log` and proceed without
-   scheduling:
-   ```
-   - HH:MM [confirm] skipped <dedup_key>: row already pending
-   ```
-
-   **`confirm_dedup_key` shape contract.** The key is
-   `<gate>:<stable-topic>` — for example
-   `create_project:la-pm-masters`,
-   `roadmap_ambiguous:tokyo-trip-date`,
-   `managed_task_dedup:<existing-task-id>`. The gate scope ensures
-   two unrelated gates can't collide on the same topic name; the
-   topic component MUST be deterministic from the topic itself
-   (no timestamps, no message IDs, no random nonces) so re-fires of
-   the same gate produce the same key and this pre-flight catches
-   them.
-
-   This rule layers on top of bullets 1-3, which catch the common
-   recurring / Agent-Plan duplicates. Bullet 4 catches the case
-   where two confirms target the same topic at different scheduled
-   times (e.g. one queued for the morning briefing, another the
-   gate would queue for `+4h`).
+   `taskContext.sub_flow="confirm"`, run the dedup pre-check + shape
+   contract documented in
+   `task-flows/_partials/confirm-subflow.md` (also included verbatim
+   by `scheduled.dm.md` and `message.received.dm{,_first}.md`). The
+   single source covers the `dedup_key` filter, the
+   `<gate>:<stable-topic>` shape, and cross-path cancellation.
 
 Log the skip to `## Agent Log`:
 `- HH:MM [schedule] skipped <subject>: duplicate of <planId|row>`.
@@ -88,11 +55,14 @@ If the request expresses an **ongoing management practice** with a
 recorded reason — "every morning, run my finance app and log the
 balance to a finance dossier", "from now on whenever X happens, do
 Y" — switch to the `management-policy` skill instead. It creates a
-`rules/policies/<slug>.md` that captures the WHY alongside the cadence
-(via `routines/custom/<slug>.md`) so the rule survives a context
-reset. Plain recurring schedules via `/api/recurring-schedules` are
-still right when the cadence is all that matters and there is no need
-to record intent.
+`policies/management-captures/<slug>.md` that captures the WHY alongside the cadence
+(via `policies/routines/custom/<slug>.md`) so the rule survives a context
+reset. When the cadence is all that matters and there is no intent to
+record: recurring autonomous **work** → create a **recurring Agent** via
+the `agent-create` skill (`POST /api/agents`); recurring scheduled
+**DM / briefing** → `POST /api/recurring-schedules` with
+`taskType: "dm_session"`. (Creating a recurring `agent.task` row directly
+on `/api/recurring-schedules` is **410 Gone** — use an Agent.)
 
 ## DM vs Agent Task
 
@@ -105,11 +75,11 @@ to record intent.
 
 **Default to DM** when possible. Every agent wake-up costs money and context.
 
-## Writing a Good Description (for agent tasks)
+## Writing a Good Prompt (for agent tasks)
 
-> **The wake-up agent has NO memory of why it was scheduled.** It receives only: `today.md`, a fresh 1-day calendar, `user/profile.md` + `rules/management.md`, and the `description` + `taskContext` fields you provide. Nothing else.
+> **The wake-up agent has NO memory of why it was scheduled.** It receives only: `state/today.md`, a fresh 1-day calendar, `identity/profile.md` + `policies/management.md`, and the `prompt` + `taskContext` fields you provide. Nothing else. (`description` is just an optional list label — never the agent body.)
 
-Include all four elements:
+Include all four elements in the `prompt`:
 
 | Element | What it answers |
 |---|---|
@@ -123,13 +93,13 @@ Include all four elements:
 **Bad:** `"Meeting prep"` — which meeting? when? what to prepare?
 
 ## Using `taskContext`
-Structured metadata for IDs, URLs, and correlation. Put long identifiers here so `description` stays under ~2 sentences:
+Structured metadata for IDs, URLs, and correlation. Put long identifiers here so the `prompt` stays focused:
 ```json
 { "scheduledBy": "morning_routine", "prUrl": "https://github.com/user/repo/pull/42" }
 ```
 
 **`importance` convention.** This controls whether `agent_schedule`
-rows become `roadmap.md` `Scheduled:` entries:
+rows become `plans/roadmap.md` `Scheduled:` entries:
 
 | Tier | Roadmap behavior | Use |
 |---|---|---|
@@ -144,9 +114,11 @@ month about ESTA for the LA trip"), either write/promote the roadmap
 item via the roadmap skill and let AAP schedule the reminder, or call
 `/api/schedule/dm` with `"importance":"strategic"`.
 
-## Model selection
-- **`sonnet`** (default) — reminders, notifications, single-step tasks
-- **`opus`** — multi-file analysis, cross-repo reasoning, decisions affecting user commitments
+## Tier / Model selection
+
+Pick `tier` (`lite` / `medium` / `high`) by default — backend-neutral cost knob. Pin `model` (registered id, alias, or `<backendId>/<modelId>`) only when the row must outlive a `/settings/models` re-route. Mutually exclusive — both set returns `schedule.tier_and_model_conflict`. Omit both to use the dispatcher's process-key default. Discovery, PATCH swap form, alias rewrite, and `/api/schedule/options` payload are in the reference below.
+
+{{> ref:model-selection }}
 
 ## Time discipline
 - **Absolute time required** — resolve relative expressions via `<current_time>` into ISO 8601 with offset. E.g. "in 1 hour" at 15:30 EDT → `2026-04-06T16:30:00-04:00`.
@@ -181,15 +153,16 @@ Response: `{ "status":"scheduled", "scheduleId":"123", "scheduledFor":"..." }`.
 ```bash
 curl -s -X POST http://localhost:8321/api/schedule \
   -H 'Content-Type: application/json' \
-  -d '{"time":"2026-04-06T16:00:00-04:00","taskType":"wake","description":"Check PR #42 status and notify user.","model":"sonnet","taskContext":{"scheduledBy":"dm_conversation"}}'
+  -d '{"time":"2026-04-06T16:00:00-04:00","taskType":"wake","prompt":"Hourly docker health check: run `docker ps --format` and DM if any container is in restart loop.","description":"Docker health check","tier":"lite","taskContext":{"scheduledBy":"docker_monitor"}}'
 ```
 | Field | Required | Description |
 |---|---|---|
 | `time` | Yes | ISO 8601 with timezone offset |
-| `taskType` | Yes | `wake` for scheduled tasks |
-| `description` | Yes | Self-contained (min 20 chars). See format above. Doubles as the agent body unless `prompt` overrides it. |
-| `prompt` | No | Optional override for the agent body (min 20 chars when set). When set, the dispatcher injects this — not `description` — into the task-flow template. Use when you want a short list-friendly `description` plus a longer, separate instruction for the agent. |
-| `model` | No | `sonnet` (default) or `opus` |
+| `taskType` | Yes | Free-form provenance label for the row (no allowlist on the single endpoint). Use `wake` for an agent wake-up — the convention this skill follows. The closed set `wake`/`dm_session`/`check`/`dm` is enforced only on `/api/schedule/batch`; e.g. the dashboard's manual "+ New task" sends `custom`. The label does not change firing — the scheduler runs every non-`dm`/`dm_session`/`browser_task` row as a generic `scheduled.task`. |
+| `prompt` | Yes | The agent's instruction at fire time — its ONLY context (the session has no memory). Self-contained: what + why + who + expected output. See format above. Max 8000 chars (~2000 tokens); move bulk reference material into a file the agent reads at fire time rather than inlining it. |
+| `description` | No | Optional short label shown in the schedule list (max 200 chars). NOT the agent body — that is `prompt`. Omit it and the list shows a `prompt` excerpt. |
+| `tier` | No | `lite` / `medium` / `high`. Omit to use the dispatcher's process-key default (medium for `scheduled.task`). See "Tier / Model selection" above. Mutually exclusive with `model`. |
+| `model` | No | Registered model id (`claude-opus-4-8`, `gpt-5.4`, …), legacy alias (`sonnet` / `opus`, auto-rewritten to `tier`), or composite `<backendId>/<modelId>`. See "Tier / Model selection" above. Mutually exclusive with `tier`. |
 | `taskContext` | No | Structured metadata object |
 
 Response: `{ "status":"scheduled", "scheduleId":"123", "scheduledFor":"YYYY-MM-DD HH:MM:SS" }`. `scheduledFor` is the normalized UTC SQLite timestamp the daemon actually stored — log this verbatim instead of re-formatting the input `time`. Rejects times in the past (> 1 min ago), same as `/api/schedule/dm`.
@@ -200,8 +173,7 @@ curl -s -X PATCH http://localhost:8321/api/schedule/42 \
   -H 'Content-Type: application/json' \
   -d '{"time":"2026-04-06T17:00:00-04:00"}'
 ```
-Fields: `time` (ISO 8601), `description` (min 20 chars, non-dm only), `prompt` (min 20 chars OR `null` to clear; non-dm only), `message` (dm only), `model`, `taskContext`. At least one required. Only `pending` items editable. `description`/`message` mutually exclusive; `prompt`/`message` mutually exclusive.
-Response: `{ "status":"updated", "id":42 }` / 404 / 409 (not pending).
+Fields: `time` (ISO 8601), `prompt` (the agent instruction, ≤8000 chars, non-dm only, OR `null` to clear on a legacy row), `description` (optional label ≤200 chars, non-dm only), `message` (dm only), `tier` (`lite`/`medium`/`high` OR `null` to clear), `model` (registered id / alias / composite OR `null` to clear), `taskContext`. At least one required. Only `pending` items editable. `description`/`message` mutually exclusive; `prompt`/`message` mutually exclusive. Tier ↔ model swap form is in the model-selection reference above. Response: `{ "status":"updated", "id":42, "warnings":[] }` / 404 / 409 — surface `warnings[]` (e.g. `schedule.model_deprecated`) to the next turn.
 
 ### GET /api/schedule — List scheduled items
 ```bash
@@ -211,7 +183,7 @@ Param `status` (default `pending,running`): comma-separated `pending`, `running`
 Param `roadmapEligible=true`: return only rows that may become
 roadmap `Scheduled:` entries (`transient` / `low` excluded, `normal`
 only beyond 7 days, `strategic` included).
-Response: `{ "items":[{ "id","scheduledFor","taskType","description","prompt","status","model","taskContext","createdAt" }] }` — `prompt` is `null` when no override is set. `taskContext` is the parsed JSON object (or `null` when none was stored); use it for sub-flow-aware filtering, e.g. `jq '.items[] | select(.taskContext.confirm_dedup_key == "create_project:la-pm-masters")'`.
+Response: `{ "items":[{ "id","scheduledFor","taskType","description","prompt","status","model","backendId","tier","taskContext","createdAt" }] }`. `prompt` / `tier` / `model` / `backendId` are `null` when no override is set. `model` is a registered id verbatim and travels with `backendId` when set — the row carries either the `(model, backendId)` pin or `tier`, never both. Legacy alias inputs (`sonnet` / `opus`) are normalized to `tier` at write time. `taskContext` is the parsed JSON (or `null`); filter with `jq` e.g. `'.items[] | select(.taskContext.confirm_dedup_key == "create_project:la-pm-masters")'`.
 
 ### DELETE /api/schedule/:id — Cancel a pending item
 ```bash
@@ -219,51 +191,51 @@ curl -s -X DELETE http://localhost:8321/api/schedule/42
 ```
 Only cancels `pending` items. Response: `{ "status":"cancelled", "id":42 }` / 404 / 409.
 
+### POST /api/schedule/batch — Bulk register rich-context schedules
+
+Morning-routine Stage A only. Single-row callers use `POST /api/schedule`
+above. The required `taskContext.background` + `expected_output`
+fields, the 50-row cap, the atomic / per-row commit modes, and the
+success payload are in the batch reference below.
+
+{{> ref:batch }}
+
 ---
 
-## Recurring Schedules
-For tasks that repeat on a fixed pattern. Auto-regenerates the next occurrence after each execution.
+## Errors
 
-### POST /api/recurring-schedules — Create
-```bash
-# Daily at 09:00
-curl -s -X POST http://localhost:8321/api/recurring-schedules \
-  -H 'Content-Type: application/json' \
-  -d '{"taskType":"wake","description":"Morning inbox triage — check pending observations and update today.md.","recurrenceRule":{"frequency":"daily","time":"09:00"}}'
-# Weekly Mon/Wed/Fri at 10:00
-curl -s -X POST http://localhost:8321/api/recurring-schedules \
-  -H 'Content-Type: application/json' \
-  -d '{"taskType":"wake","description":"Standup prep — review PRs, calendar, and blockers.","recurrenceRule":{"frequency":"weekly","time":"10:00","daysOfWeek":[1,3,5]}}'
-```
-| Field | Required | Description |
-|---|---|---|
-| `taskType` | Yes | Task type for dispatch (e.g. `wake`) |
-| `description` | Yes | Self-contained (min 20 chars). Same rules as one-shot. Doubles as the agent body unless `prompt` overrides it. |
-| `prompt` | No | Optional override for the agent body (min 20 chars when set). Each materialized one-shot row inherits this from the recurring parent. |
-| `recurrenceRule` | Yes | `{ frequency, time, timezone?, daysOfWeek?, daysOfMonth? }` |
-| `model` | No | `sonnet` (default) or `opus` |
-| `taskContext` | No | Structured metadata object |
+Every endpoint in this skill emits errors in the **agent-consumable
+envelope** — read `errors[].hint`, fix the value at `errors[].field`,
+and resubmit the same body. The full envelope shape and every
+`schedule.*` code (request-shape, time-bound, row-content, taskContext,
+model, batch) are in the errors reference below.
 
-**Recurrence rule:** `frequency`: `daily`/`weekly`/`monthly`. `time`: `HH:MM` local. `timezone`: IANA (auto-filled from daemon config). `daysOfWeek` (weekly): 0=Sun..6=Sat. `daysOfMonth` (monthly): 1-31 (31 clamps to month end).
+{{> ref:errors }}
 
-Response: `{ "status":"created", "item":{ "id","recurrenceLabel","nextRunAt",... } }`
+---
 
-### GET /api/recurring-schedules — List
-```bash
-curl -s "http://localhost:8321/api/recurring-schedules?enabled=true"
-```
-Response: `{ "items":[{ "id","taskType","description","recurrenceRule","enabled","nextRunAt","recurrenceLabel" }] }`
+## Recurring: work → Agent; DM → dm_session
 
-### PATCH /api/recurring-schedules/:id — Update
-```bash
-curl -s -X PATCH http://localhost:8321/api/recurring-schedules/1 \
-  -H 'Content-Type: application/json' \
-  -d '{"recurrenceRule":{"frequency":"daily","time":"10:00"}}'
-```
-Updatable: `recurrenceRule`, `description`, `prompt` (string sets an override, `null` clears), `model`, `taskContext`, `enabled`. Changing `recurrenceRule`/`enabled` auto-reschedules. Set `{"enabled":false}` to pause.
+`/schedule` registers **one-shot** wake-ups and DMs. For repeating tasks:
 
-### DELETE /api/recurring-schedules/:id — Delete
-```bash
-curl -s -X DELETE http://localhost:8321/api/recurring-schedules/1
-```
-Deletes schedule and cancels pending instances. Response: `{ "status":"deleted", "id":1 }`
+- **Recurring autonomous work** (daily inbox triage, weekly review, hourly
+  health check) is a **recurring Agent** — a durable, named identity with
+  metrics on `/agents`. Create it with the **`agent-create` skill**
+  (`POST /api/agents`). Creating a recurring `agent.task` row directly on
+  `POST /api/recurring-schedules` is **410 Gone** — use an Agent.
+- **Recurring scheduled DM / briefing** ("DM me a summary every morning")
+  stays on `POST /api/recurring-schedules` with `taskType: "dm_session"`
+  (its fire time can track quiet-hours; PATCH/DELETE edit it). The morning
+  briefing is one of these.
+
+`GET /api/recurring-schedules` stays read-only for the dedup pre-check.
+
+### recurrenceRule grammar — the shared recurrence engine
+
+The recurrence engine grammar (mapping table, frequency-vs-field matrix,
+cadence-string discipline) is shared with the `managed-tasks` skill and
+the `dm_session` recurring rule above. The reference is byte-identical
+across both skills —
+pinned by `skills-manifest.test.ts` so they cannot drift.
+
+{{> ref:recurrence-rule }}

package/agent-assets/skills/schedule/references/batch.md

@@ -0,0 +1,93 @@
+---
+kind: reference
+name: batch
+description: POST /api/schedule/batch — bulk register up to 50 rich-context schedules in one atomic transaction. Morning-routine Stage A is the primary caller.
+---
+
+# POST /api/schedule/batch — Bulk register rich-context schedules
+
+Used by the morning-routine Stage A to register every same-day
+schedule in one atomic transaction. Each row's `taskContext` MUST
+carry the context a future `scheduled.task` / `scheduled.dm` session
+needs to produce high-quality output hours later — the daemon cannot
+reconstruct this from the user-facing description.
+
+If you are not the morning routine, you almost certainly want
+`POST /api/schedule` (single-row) instead — batch's required
+`taskContext.background` + `expected_output` fields are overkill for
+one-off DM-handler reminders.
+
+## Example
+
+```bash
+curl -s -X POST http://localhost:8321/api/schedule/batch \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "rows": [
+      {
+        "scheduledFor": "2026-05-15T14:30:00-04:00",
+        "taskType": "wake",
+        "taskDescription": "Pre-brief the 15:00 standup with the two open Q2 risks.",
+        "taskContext": {
+          "background": "User flagged Q2 roadmap risks in yesterdays DM; standup needs the two open items front-loaded so the team aligns before 15:30.",
+          "expected_output": "DM with two bullet items + one suggested mitigation each, sent 30min before standup.",
+          "references": ["plans/projects/q2-roadmap.md#open-risks", "calendar:event:standup-2026-05-15"],
+          "tone": "concise"
+        }
+      }
+    ],
+    "atomic": true
+  }'
+```
+
+## Fields
+
+| Field | Required | Description |
+|---|---|---|
+| `rows` | Yes | Array of row objects (max 50 per batch). Empty array is a documented no-op. |
+| `rows[].scheduledFor` | Yes | ISO 8601 with timezone offset. Must be >= 1 minute in the future. |
+| `rows[].taskType` | Yes | `wake` / `dm_session` / `check` / `dm`. |
+| `rows[].taskDescription` | Yes | Self-contained (min 20 chars). Doubles as the agent body unless `taskPrompt` overrides. |
+| `rows[].taskContext.background` | Yes | Why this task is being scheduled (min 30 chars). Anchor for the future session. |
+| `rows[].taskContext.expected_output` | Yes | What the future session should produce (min 20 chars). |
+| `rows[].taskContext.references` | No | Stable handles the future session can look up (project paths, calendar event ids). |
+| `rows[].taskContext.tone` | No | Free-form tone hint for DM-shaped output. |
+| `rows[].taskContext.tier_override` | No | `lite` / `medium` / `high` / `null`. **Legacy slot — prefer `rows[].tier` (top-level)**. When `tier` is omitted, this value is lifted into the row's `tier_override` column at insert time. |
+| `rows[].tier` | No | `lite` / `medium` / `high`. Abstract cost knob — primary path. Wins over `taskContext.tier_override` when both are set. Mutually exclusive with `rows[].model` on the same row. |
+| `rows[].taskContext.sub_flow` | No | Branches the task-flow rendering when the dispatcher needs a specialised sub-flow. |
+| `rows[].taskPrompt` | No | Override for the agent body (min 20 chars when set). |
+| `rows[].correlationId` | No | Defaults to the morning routine's correlation id when omitted. |
+| `rows[].model` | No | Registered model id (`claude-opus-4-8`, `claude-sonnet-4-6`, `gpt-5.4`, `gemini-3.1-pro-preview`, …), legacy alias (`sonnet` / `opus` — auto-rewritten to `tier`), composite `<backendId>/<modelId>`, or `null`. Mutually exclusive with `rows[].tier`. Omit both to let `process_backend_config` decide. |
+| `atomic` | No | `true` (default) wraps inserts in one transaction — any row error rolls back all. `false` commits successful rows individually. |
+
+## Success
+
+201:
+
+```json
+{ "ok": true, "rowsAttempted": 1, "rowsCommitted": 1, "ids": [101], "warnings": [] }
+```
+
+`warnings[]` carries non-blocking advisories (per-row issues like
+`schedule.model_deprecated` keep the rowIndex so the agent can map
+warnings back to the offending row). Rows are still committed —
+surface the warnings to the next turn so the LLM can refine without
+re-POSTing.
+
+## Errors
+
+Returns the standard agent-consumable envelope — see
+`references/errors.md`. `rowsCommitted` tells you how much of the
+batch landed; with `atomic:true` any error means `rowsCommitted === 0`.
+Per-row `model_unknown` / `model_ambiguous` / `tier_and_model_conflict`
+all reach this envelope with `rowIndex` set — fix the offending rows
+and resubmit the same body.
+
+## When NOT to use batch
+
+- One-off DM-handler reminders → use `POST /api/schedule` (single
+  row, no required `taskContext.background`).
+- DM-tone scheduled messages → use `POST /api/schedule/dm` (no agent
+  invoked at fire time).
+- More than 50 rows in a single horizon → chunk into multiple
+  `atomic:true` batches; do not raise the cap.

package/agent-assets/skills/schedule/references/errors.md

@@ -0,0 +1,217 @@
+---
+kind: reference
+name: errors
+description: Agent-consumable error envelope shape + every `schedule.*` code emitted by /api/schedule and /api/schedule/batch.
+---
+
+# Schedule error envelope + codes
+
+Every endpoint in this skill emits errors in the
+**agent-consumable envelope** so you can self-correct in the same
+turn instead of retrying blindly:
+
+```jsonc
+{
+  "ok": false,
+  "summary": "1 validation error. Fix the listed errors and retry.",
+  "errors": [
+    {
+      "rowIndex": 2,                                  // null when not a batch row
+      "code": "schedule.task_context_field_missing",  // stable machine code
+      "field": "rows[2].taskContext.background",      // JSON-pointer-ish path
+      "received": "<missing>",
+      "expected": "string with >= 30 characters explaining why this task is being scheduled",
+      "constraint": { "type": "string", "minLength": 30, "required": true },
+      "validValues": null,                             // runtime-derived set, when applicable (see "validValues vs constraint.enum")
+      "hint": "Stage A must populate taskContext.background so the future session can produce high-quality output without re-deriving context. Example: ...",
+      "skillAnchor": "schedule#taskContext-required-fields",
+      "docsUrl": "agent-assets/skills/schedule/references/errors.md#task_context_field_missing",
+      "severity": "error"
+    }
+  ],
+  "warnings": [],                                      // non-blocking advisories — see "Warnings channel"
+  "retryable": true,
+  "retryHint": "Fix the listed rows and POST the same body again. atomic=true (the default) means no rows were committed."
+}
+```
+
+When you see an error: read `errors[].hint`, fix the value at
+`errors[].field`, and resubmit the same body. The morning-routine
+task-flow gates batch retries on `rowsCommitted === rows.length`; do
+not retry a row-level fix on a different field path.
+
+## Issue fields
+
+| Field | Use |
+|---|---|
+| `code` | Stable namespaced identifier. Switch on this in skill prose, not on `expected` or `hint`. |
+| `field` | JSON-pointer-ish path to the offending input (`rows[2].taskContext.background`). |
+| `received` | Exact value the daemon saw. `'<missing>'` sentinel when the field was omitted. |
+| `expected` | One-sentence summary of what would have been accepted. |
+| `constraint` | Static, schema-level shape (`{type, minLength, enum: [...]}`). Fixed across deploys. |
+| `validValues` | Runtime-derived list of acceptable values — populated when the answer is data the operator can change (model registry, IANA timezones, an integration's supported modes). Distinct from `constraint.enum`: never both on the same code. |
+| `hint` | Concrete remediation guidance with an example. |
+| `skillAnchor` | `<skill>#<slug>` reference for fuller context — `Read agent-assets/skills/<skill>/SKILL.md#<slug>`. |
+| `docsUrl` | Repo-relative path to deeper "what to do" prose, including a fragment that lands on the code's heading in this file. |
+| `severity` | `error` blocks the commit; `warning` is advisory only (also surfaced via `warnings[]` — see below). |
+
+### validValues vs constraint.enum
+
+These two fields look alike but answer different questions:
+
+- **`constraint.enum`** — schema-level static list (`["lite","medium","high"]`, `["hourly","daily","weekly","monthly"]`). Same on every deploy.
+- **`validValues`** — runtime-derived list (the model registry snapshot, which evolves as new models are registered; the IANA timezone set; an integration's `supportedModes`). Filled by the route at error-time.
+
+Use `validValues` when present — it reflects what the daemon will accept on this run, including any newly added entries. `constraint.enum` is the
+specification-time guarantee. The two never appear together on the same code.
+
+## Warnings channel
+
+Some inputs are syntactically valid but suspicious enough to flag —
+deprecated model on a long-lived recurring rule, `daysOfMonth:[31]`
+with the default `lastDayOfMonth` policy, etc. The daemon does **not**
+reject these; the row is persisted and the response returns 200/201
+with a `warnings: []` array using the same issue shape as `errors[]`:
+
+```jsonc
+{
+  "status": "created",
+  "item": { "id": 42, "recurrenceRule": { ... }, "nextRunAt": "2026-05-31T12:00:00Z" },
+  "warnings": [
+    {
+      "rowIndex": null,
+      "code": "schedule.on_missing_day_unused",
+      "field": "recurrenceRule.onMissingDay",
+      "received": "lastDayOfMonth",
+      "expected": "onMissingDay only matters when daysOfMonth contains 29, 30, or 31",
+      "hint": "Drop onMissingDay or add 29/30/31 to daysOfMonth.",
+      "skillAnchor": "schedule#monthly-missing-day",
+      "severity": "warning"
+    }
+  ]
+}
+```
+
+Surface warnings to the next agent turn (e.g. include them in the
+DM that confirms the schedule was created) so the LLM can refine on
+the next call if the warning matters. **Don't treat warnings as
+failures** — they are advisory, not blocking. `retryable` is computed
+from `errors[]` only and ignores `warnings[]`.
+
+When the same envelope contains both `errors` and `warnings`, the
+errors path runs first: fix every entry in `errors[]`, then inspect
+`warnings[]` on the retried response.
+
+## Codes the schedule endpoints can emit
+
+### Request-shape codes
+
+Apply to `POST /api/schedule` and `POST /api/schedule/batch`.
+
+<a id="request-shape"></a>
+
+| Code | When | Fix |
+|---|---|---|
+| <a id="body_not_object"></a> `schedule.body_not_object` | Body is not a JSON object. | POST `{"rows":[…]}` for batch, or the row fields directly for single-row. |
+| <a id="rows_field_missing"></a> `schedule.rows_field_missing` | Batch body is missing the `rows` array. | Wrap your row objects in a `rows` array. |
+| <a id="rows_too_many"></a> `schedule.rows_too_many` | Batch contains > 50 rows. | Split into chunks of at most 50 rows. |
+| <a id="batch_atomic_invalid"></a> `schedule.batch_atomic_invalid` | `atomic` is not a boolean. | Pass `true` / `false`, or omit (defaults to `true`). |
+
+### Time-bound codes
+
+<a id="scheduledFor-bounds"></a>
+
+| Code | When | Fix |
+|---|---|---|
+| <a id="scheduled_for_invalid"></a> `schedule.scheduled_for_invalid` | `scheduledFor` / `time` is not parseable by `Date()`. | Use ISO 8601 with timezone offset. Resolve relative times via `<current_time>`. |
+| <a id="scheduled_for_in_past"></a> `schedule.scheduled_for_in_past` | `scheduledFor` is earlier than now (with a 1-minute grace). | Pick a future time. Inspect `<current_time>` and pick now+1min minimum. |
+
+### Row-content codes
+
+<a id="taskType"></a>
+<a id="description-shape"></a>
+
+| Code | When | Fix |
+|---|---|---|
+| <a id="task_type_unknown"></a> `schedule.task_type_unknown` | **Batch only** (`/api/schedule/batch` rows): `taskType` is not one of the closed set `wake` / `dm_session` / `check` / `dm`. On the single `POST /api/schedule`, `taskType` is a free-form provenance label (no allowlist) — this code fires there only when `taskType` is missing or not a string. | Batch: pick one of the four. Single endpoint: send any non-empty string (`wake` is the convention for agent wake-ups). Use `/api/schedule/dm` for the precomposed-DM variant. |
+| <a id="prompt_required"></a> `schedule.prompt_required` | `POST /api/schedule` (or a PATCH that sets it) with `prompt` missing or empty. | `prompt` is the wake-up agent's only instruction — write the full instruction there. `description` is just the optional list label, no longer the agent body. |
+| <a id="prompt_too_long"></a> `schedule.prompt_too_long` | `prompt` / `taskPrompt` > 8000 chars. | Tighten the instruction (goal + key context + expected output); move bulk reference material into a file the agent reads at fire time instead of inlining it. |
+| <a id="description_too_long"></a> `schedule.description_too_long` | `description` > 200 chars. | The description is the short list label — keep it under 200 chars and put the full instruction in `prompt`. |
+| <a id="description_too_short"></a> `schedule.description_too_short` | `taskDescription` (batch) / recurring `description` < 20 chars. | Expand the body so the wake-up agent has enough context to act. (Does not apply to the single `/api/schedule` row, where `description` is an optional label.) |
+| <a id="prompt_too_short"></a> `schedule.prompt_too_short` | Batch `taskPrompt` / recurring `prompt` is set but < 20 chars. | Either remove it (the description body is used) or expand it. (The single `/api/schedule` row requires `prompt`; see `schedule.prompt_required`.) |
+
+### taskContext required fields
+
+<a id="taskContext-required-fields"></a>
+
+For `POST /api/schedule/batch`, every row's `taskContext` must carry
+`background` (>=30 chars) and `expected_output` (>=20 chars). The
+future session firing at the scheduled time inherits these verbatim
+— its output quality is bounded by the richness of what you write
+here.
+
+| Code | When | Fix |
+|---|---|---|
+| <a id="task_context_field_missing"></a> `schedule.task_context_field_missing` | `taskContext.background` or `taskContext.expected_output` is absent. | Populate both. `background` explains *why* this row exists; `expected_output` defines what "done" looks like. |
+| <a id="task_context_field_too_short"></a> `schedule.task_context_field_too_short` | One of the required taskContext fields is below its min length. | Expand the string. Trivial values like "follow up" don't survive a 4-hour gap. |
+| <a id="task_context_field_wrong_type"></a> `schedule.task_context_field_wrong_type` | A typed taskContext slot received the wrong type (e.g. `references` is a string instead of `string[]`). | Match the schema: references is `string[]`, tier_override is `null|"lite"|"medium"|"high"`, tone is a free string. |
+
+### Model selection
+
+<a id="model-selection"></a>
+<a id="tier-selection"></a>
+<a id="tier-vs-model"></a>
+
+`model` accepts a free-form token after SCHEDULE_API_REDESIGN_PLAN
+§4.3: legacy aliases (`sonnet` / `opus` — rewritten to `tier` at
+the route), full registered model ids (e.g. `claude-opus-4-8`,
+`gpt-5.4`), or the composite `<backendId>/<modelId>` form when an
+id appears under multiple backends. `tier` (`lite` | `medium` |
+`high`) is the abstract cost knob and is mutually exclusive with
+`model`. Prefer `tier` for new schedules — the dispatcher picks the
+latest non-deprecated model per resolved process key automatically.
+
+| Code | When | Fix |
+|---|---|---|
+| <a id="model_unknown"></a> `schedule.model_unknown` | `model` is not a registered alias / model id. | Inspect `validValues.aliases` and `validValues.models` on the response — these list every value the daemon will accept right now. Omit `model` to let `process_backend_config` decide. |
+| <a id="model_ambiguous"></a> `schedule.model_ambiguous` | `model` matches more than one backend in the registry. | Resubmit using the composite `<backendId>/<modelId>` form (see `validValues.matches`). |
+| <a id="model_deprecated"></a> `schedule.model_deprecated` (warning) | `model` is registered but flagged deprecated. | The row was still created. Switch to a non-deprecated id from `validValues.availableModels`, or use `tier` instead. |
+| <a id="backend_id_unknown"></a> `schedule.backend_id_unknown` | Backend portion of the composite token is not `claude` / `codex` / `gemini` / `opencode`. | Use one of the four BackendId values. |
+| <a id="tier_unknown"></a> `schedule.tier_unknown` | `tier` is not `lite` / `medium` / `high`. | Pick one of the three tiers or omit entirely. |
+| <a id="tier_and_model_conflict"></a> `schedule.tier_and_model_conflict` | Both `tier` AND `model` set on the same row. | Pick exactly one: `tier` (recommended) OR `model`. On PATCH you can clear one and set the other in the same request (pass `null` to clear). |
+
+### Batch-shape codes
+
+<a id="batch-shape"></a>
+
+See the table under "Request-shape codes" above. `rowsAttempted` /
+`rowsCommitted` in the envelope tell you how much of the batch
+committed; with `atomic:true` (the default) every error means
+`rowsCommitted === 0`.
+
+### Recurring-schedules (`/api/recurring-schedules`)
+
+<a id="recurring-shape"></a>
+
+POST and PATCH `/api/recurring-schedules` route every Zod validation
+failure through `translateZodError` so each offending field surfaces
+as its own code instead of collapsing onto one
+`recurring_schedules.validation_error` issue. The codes below mirror
+the per-frequency rules in `recurrence-rule.md`.
+
+| Code | When | Fix |
+|---|---|---|
+| <a id="frequency_unknown"></a> `schedule.frequency_unknown` | `recurrenceRule.frequency` not in the enum. | Pick `hourly` / `daily` / `weekly` / `monthly`. |
+| <a id="frequency_field_mismatch"></a> `schedule.frequency_field_mismatch` | Wrong fields for the chosen frequency (e.g. `time` on `hourly`, `daysOfWeek` on `daily`). | See `validValues.requiredFor` / `forbiddenFor` for the exact matrix. |
+| <a id="interval_hours_out_of_range"></a> `schedule.interval_hours_out_of_range` | `intervalHours` outside `[1, 23]`. | Use 1..23; for daily switch frequency. |
+| <a id="minute_of_hour_out_of_range"></a> `schedule.minute_of_hour_out_of_range` | `minuteOfHour` outside `[0, 59]`. | Pick 0..59 (default 0). |
+| <a id="time_format_invalid"></a> `schedule.time_format_invalid` | `time` not `HH:MM` 24h. | Use the exact form `09:00` / `21:30`. |
+| <a id="days_of_week_invalid"></a> `schedule.days_of_week_invalid` | `daysOfWeek` empty, duplicate, or out of `[0, 6]`. | 0=Sun..6=Sat, distinct entries only. |
+| <a id="days_of_month_invalid"></a> `schedule.days_of_month_invalid` | `daysOfMonth` empty, duplicate, or out of `[1, 31]`. | 1..31, distinct entries only — use `onMissingDay` to control 29-31 behavior. |
+| <a id="on_missing_day_unknown"></a> `schedule.on_missing_day_unknown` | `onMissingDay` not `skip` / `lastDayOfMonth`. | Pick one (default `lastDayOfMonth`). |
+| <a id="on_missing_day_unused"></a> `schedule.on_missing_day_unused` (warning) | `onMissingDay` set but `daysOfMonth` has no entry in `[29, 30, 31]`. | Advisory — row is created. Either drop `onMissingDay` (no effect on a 1..28 set) or extend `daysOfMonth` to include 29/30/31 if you meant a month-end rule. |
+| <a id="timezone_unknown"></a> `schedule.timezone_unknown` | `timezone` is not a valid IANA zone. | Use a real zone (`Asia/Tokyo`, `America/New_York`, `UTC`). |
+| <a id="recurrence_rule_invalid"></a> `schedule.recurrence_rule_invalid` | `recurrenceRule` is structurally invalid in a way the traversal could not localise. | Inspect the response `field` path and resubmit a well-formed object. |
+| <a id="recurring_id_invalid"></a> `schedule.recurring_id_invalid` | id segment not a positive integer. | Use the `item.id` returned by POST. |
+| <a id="recurring_not_found"></a> `schedule.recurring_not_found` | No row with this id. | List `/api/recurring-schedules` to see current rows. |
+| <a id="recurring_no_changes"></a> `schedule.recurring_no_changes` | PATCH body is empty. | Supply at least one of `description` / `prompt` / `recurrenceRule` / `model` / `tier` / `taskContext` / `enabled`. |