@aitne-sh/aitne 0.1.7 → 0.1.8

package/agent-assets/skills/roadmap/references/preparation-timeline.md

@@ -7,14 +7,14 @@ Action line formats:
 
 ```
 - YYYY-MM-DD [tag]: description
-- ✓ completed YYYY-MM-DD: YYYY-MM-DD [tag]: description
+- completed YYYY-MM-DD: YYYY-MM-DD [tag]: description
 ```
 
 The completed prefix date is the completion date; the second date is
 the original planned date. Preserve completed rows byte-for-byte across
 refreshes. Morning Routine marks an open row complete by rewriting:
 `- YYYY-MM-DD [tag]: foo` →
-`- ✓ completed <today>: YYYY-MM-DD [tag]: foo`.
+`- completed <today>: YYYY-MM-DD [tag]: foo`.
 
 Tags: `[notify]`, `[today]`, `[check]`, `[schedule]`.
 

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
@@ -37,45 +36,12 @@ user but compound into duplicate DMs/notifications at fire time.
    regenerate on its own.
 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>`.
@@ -144,9 +110,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,7 +149,7 @@ 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","description":"Hourly docker health check: run `docker ps --format` and DM if any container is in restart loop.","tier":"lite","taskContext":{"scheduledBy":"docker_monitor"}}'
 ```
 | Field | Required | Description |
 |---|---|---|
@@ -189,7 +157,8 @@ curl -s -X POST http://localhost:8321/api/schedule \
 | `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` |
+| `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-7`, `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 +169,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), `description` (min 20 chars, non-dm only), `prompt` (min 20 chars OR `null` to clear; 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 +179,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 +187,47 @@ 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 Schedules
 
-### 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.
+For tasks that repeat on a fixed pattern. The daemon auto-regenerates
+the next one-shot occurrence after each execution. **Hourly / daily /
+weekly / monthly** cadences are supported; the recurring reference
+below documents the full shape, the hourly + monthly missing-day
+recipes, pause-vs-delete trade-off, and PATCH / GET / DELETE surface.
 
-### 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 }`
+{{> ref:recurring }}
+
+### recurrenceRule grammar — engine vs consumer
+
+The full engine grammar (mapping table, frequency-vs-field matrix,
+cadence-string-must-match-recurrenceRule discipline) is shared with
+the `managed-tasks` skill. The reference is byte-identical across
+both skills — pinned by `skills-manifest.test.ts` so they cannot
+drift. Schedule callers may use any of the four frequencies the
+engine accepts; the `managed-tasks` consumer chooses to refuse
+sub-daily for app-fetch correctness and that constraint lives there.
+
+{{> 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": ["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-7`, `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,214 @@
+---
+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` | `taskType` is not `wake` / `dm_session` / `check` / `dm`. | Pick the matching type. Use `/api/schedule/dm` for the precomposed-DM variant. |
+| <a id="description_too_short"></a> `schedule.description_too_short` | `description` / `taskDescription` < 20 chars. | Expand the description so the wake-up agent has enough context to act. |
+| <a id="prompt_too_short"></a> `schedule.prompt_too_short` | `prompt` / `taskPrompt` is set but < 20 chars. | Either remove it (description doubles as the body) or expand it. |
+
+### 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-7`,
+`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`. |

package/agent-assets/skills/schedule/references/model-selection.md

@@ -0,0 +1,96 @@
+---
+kind: reference
+name: model-selection
+description: Tier vs model selection for schedule rows + `GET /api/schedule/options` discovery endpoint. Mutual-exclusion rules, legacy alias rewrite, composite-form disambiguator.
+---
+
+# Tier / Model selection
+
+`tier` is the backend-neutral cost knob — **prefer it**. `model` pins
+a specific registered model id when the row must run against a
+particular backend (e.g. a routine that depends on Opus reasoning
+even after `/settings/models` re-routes the process key). The two are
+**mutually exclusive on a single row** — passing both returns
+`schedule.tier_and_model_conflict` (no "tier wins" precedence).
+
+| `tier` | Class | When |
+|---|---|---|
+| `"lite"` | Haiku | hourly polling / health checks (e.g. docker `ps` summary) |
+| `"medium"` | Sonnet | lock against future `/settings/models` re-routes |
+| `"high"` | Opus | one-off generative work driving user-visible output |
+
+`model` accepts:
+
+- **Legacy aliases** — `"sonnet"` / `"opus"`. Auto-rewritten at the
+  route to `tier:"medium"` / `tier:"high"`; the alias is not stored
+  verbatim.
+- **Registered model ids** — any id from `MODEL_REGISTRY` across the
+  four backends. Examples: `claude-opus-4-7`, `claude-sonnet-4-6`,
+  `claude-haiku-4-5-20251001`, `gpt-5.4`, `gemini-3.1-pro-preview`.
+  The row persists `(model, backend_id)` together so the dispatcher
+  honors the pin at fire time.
+- **Composite `<backendId>/<modelId>`** — disambiguator for a future
+  registry that has the same model id under multiple backends (today
+  unreachable but accepted). The prefix MUST be one of `claude` /
+  `codex` / `gemini` / `opencode`; opencode model ids like
+  `anthropic/claude-opus-4-7` are NOT composites and fall through to
+  the cross-backend scan.
+
+Unknown / ambiguous / deprecated model tokens surface through the
+error envelope's `validValues` field — read it instead of guessing.
+The full code list lives in `references/errors.md`.
+
+## PATCH semantics — tier ↔ model swap
+
+A row carries at most one pin at rest. On PATCH:
+
+- Pass `null` to clear one and a concrete value to set the other in
+  the same request — that is the documented form for swapping a
+  tier-pinned row to a model-pinned row (and vice versa).
+- Setting a registered `model` token also clears any prior
+  `tier_override` automatically; setting `tier` does not auto-clear
+  `model` — pair the change with `"model": null` when the intent is
+  to swap.
+- Setting a legacy alias (`sonnet` / `opus`) on PATCH is rewritten to
+  `tier:"medium"` / `tier:"high"`; the alias is never stored verbatim.
+
+## Discovery — `GET /api/schedule/options`
+
+Read-only one-stop endpoint that returns every value the daemon will
+accept right now: registered models per backend, model aliases,
+allowed tiers, recurrence frequencies, `daysOfWeek` map, hourly /
+monthly bounds (`intervalHours` 1..23, `minuteOfHour` 0..59,
+`onMissingDay` default), and the operator's configured timezone.
+Fetch once per cold session before composing tricky schedules; the
+error envelope also cites this endpoint via `docsUrl` so you can
+recover after a 400.
+
+```bash
+curl -s http://localhost:8321/api/schedule/options
+```
+
+Response shape:
+
+```jsonc
+{
+  "tiers": ["lite", "medium", "high"],
+  "modelAliases": { "sonnet": "medium", "opus": "high" },
+  "models": {
+    "claude":   [{ "id": "claude-opus-4-7", "tier": "high", "deprecated": false }, ...],
+    "codex":    [...],
+    "gemini":   [...],
+    "opencode": [...]
+  },
+  "frequencies": ["hourly", "daily", "weekly", "monthly"],
+  "daysOfWeek":  { "0": "Sun", "1": "Mon", ..., "6": "Sat" },
+  "recurrence": {
+    "intervalHours": { "min": 1, "max": 23 },
+    "minuteOfHour":  { "min": 0, "max": 59 },
+    "daysOfMonth":   { "min": 1, "max": 31 },
+    "onMissingDay":  { "values": ["skip", "lastDayOfMonth"], "default": "lastDayOfMonth" }
+  },
+  "timeFormat":      "HH:MM (24h)",
+  "timezoneExample": "Asia/Tokyo",
+  "defaults":        { "timezone": "<operator's configured primary timezone>" }
+}
+```