@aitne-sh/aitne 0.1.0

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

@@ -0,0 +1,276 @@
+---
+name: roadmap
+description: Load when writing to roadmap.md — roadmap refresh, morning/evening routines, DMs with long-horizon intent, or scheduled tasks. Owns the section schema, entry taxonomy, Preparation Timeline rules, destination extraction, and the roadmap write lock.
+allowed-tools:
+  - Bash(curl *)
+  - Read
+---
+
+# roadmap.md Guide
+
+`roadmap.md` is the single source of truth for **long-horizon user
+intent** — everything that does not belong in `today.md`. It aggregates
+Calendar events, pending `agent_schedule` rows, DM-captured intent,
+mail-derived bookings, reading goals, and observations; Morning Routine
+consumes it to shape `today.md`.
+
+## Section schema
+
+```
+# Roadmap
+> Last synced: YYYY-MM-DD
+
+## Annual Goals          (user-authored — never rewrite autonomously)
+## Quarterly Focus       (user-authored — never rewrite autonomously)
+## Long-term Plans       (agent-writable, undated OK)
+## Agent Action Plan     (agent-writable, dated entries)
+## Recurring             (preserved verbatim)
+```
+
+- Preserve user-authored sections (`## Annual Goals`, `## Quarterly
+  Focus`, `## Recurring`) verbatim.
+- `## Agent Action Plan` is rebuilt by entry ID during refresh. Do not
+  regenerate it as anonymous text: preserve stable IDs and completed
+  Preparation Timeline rows.
+- `## Long-term Plans` is cumulative: append / per-entry edit; **never
+  clear it during refresh**.
+- The `> Last synced` header line carries the audit-timestamp role.
+  Always bump it on PUT, even on no-op runs.
+
+## Decision tree — where does this item go?
+
+```
+Is the item actionable and does it need agent-side preparation or awareness?
+├── No → don't write to roadmap
+│       (short-lived → today.md; preference → user-profile)
+└── Yes
+    ├── Is it an agent_schedule row?
+    │   ├── task_context.importance is "transient" or "low" → don't write to roadmap
+    │   ├── task_context.importance === "strategic"         → Agent Action Plan "Scheduled:" entry
+    │   ├── scheduled_for <= now + 7d                       → today.md Agent Plan only
+    │   └── normal/unspecified beyond 7d                    → Agent Action Plan "Scheduled:" entry
+    ├── Does it have a specific event date?
+    │   ├── Yes + within 48h                   → today.md only, not roadmap
+    │   ├── Yes + >48h away                    → Agent Action Plan event entry
+    │   │                                        with Preparation Timeline
+    │   └── No                                 → Long-term Plans (single line,
+    │                                             dateable later)
+```
+
+## Entry shapes
+
+### Event entry (calendar / travel-bookings / DM-dated)
+
+```
+### YYYY-MM-DD ~ MM-DD: <event title>  <!-- id: rm-YYYYMMDD-abcdef -->
+Source: <Google Calendar | Travel Bookings | DM>
+Destination: <resolved location or "unknown — pending check">
+
+**Preparation Timeline:**
+- YYYY-MM-DD [tag]: action description
+- ...
+
+**Agent Notes:**
+- supplementary info
+```
+
+### Scheduled-task entry (`agent_schedule` rows)
+
+```
+### Scheduled: <description>  (task #<id>)  <!-- id: rm-YYYYMMDD-abcdef -->
+Source: scheduled.task — wake-up YYYY-MM-DD HH:MM
+Status: ⏳ pending | ▶ running | ✓ completed | ✗ failed
+
+**Preparation Timeline:** (optional — only when the agent judges prep is useful)
+- ...
+```
+
+### Long-term plan line
+
+```
+- [<horizon-tag>] <intent> — Source: <dm|mail|observation|reading|dashboard|manual> <YYYY-MM-DD> — Review: <YYYY-MM-DD|[noreview]> — ReviewCount: <0-3>  <!-- id: rm-YYYYMMDD-abcdef -->
+```
+
+Horizon-tag grammar (validated by the context API):
+- `YYYY-MM` → month-granular
+- `YYYY-Qn` → calendar quarter
+- `YYYY spring|summer|autumn|winter`
+- `undated` → no horizon yet
+
+Examples:
+- `- [2026-05] LA trip candidate — Source: dm 2026-04-19 — Review: 2026-04-20 — ReviewCount: 0  <!-- id: rm-20260419-a3f1c2 -->`
+- `- [2026-Q3] US study prep — Source: dm 2026-04-19 — Review: 2026-05-17 — ReviewCount: 0  <!-- id: rm-20260419-b8e7d4 -->`
+- `- [undated] Eventually learn Spanish — Source: dm 2026-04-19 — Review: [noreview] — ReviewCount: 3  <!-- id: rm-20260419-0d4c9a -->`
+
+## Stable entry identity
+
+Every `## Agent Action Plan` entry and every `## Long-term Plans` line
+must carry a daemon-minted HTML comment ID:
+
+```
+<!-- id: rm-YYYYMMDD-abcdef -->
+```
+
+- Format: `rm-YYYYMMDD-<6 lowercase hex>`.
+- The `YYYYMMDD` segment is the entry creation date / Source date, not
+  the event date. Keep it stable when dates are refined.
+- Do not invent IDs in prose. Before adding a new roadmap entry, call
+  `POST /api/context/roadmap/id`:
+  ```bash
+  curl -s -X POST http://localhost:8321/api/context/roadmap/id \
+    -H 'Content-Type: application/json' \
+    -d '{"creationDate": "YYYY-MM-DD"}'
+  ```
+- If preserving or editing an existing entry, keep its ID byte-for-byte.
+- When promoting a Long-term Plan into Agent Action Plan, transfer the
+  same ID to the new `###` heading and remove the original line.
+- If a `roadmap_candidate` observation has
+  `payload.roadmap_entry_id`, treat that as the intended entry ID
+  before considering destination/date matching or minting a fresh ID.
+- If a PUT/PATCH fails with duplicate-ID validation, re-GET roadmap,
+  mint a fresh ID for only the colliding new entry, and retry once.
+
+## Long-term Plans review fields
+
+{{> ref:horizon-tags }}
+
+## Preparation Timeline taxonomy
+
+{{> ref:preparation-timeline }}
+
+## Destination extraction (travel-class entries)
+
+1. `calendar.location` is non-empty and parseable → use it.
+2. Else: title regex for a known city / country →
+   classify international vs. domestic.
+3. Else: description body regex.
+4. Else: destination = `"unknown — pending check"`, and add a
+   `[check] <event_date - 28d>: Confirm destination for <title>` line
+   to the Preparation Timeline.
+
+## travel_bookings cross-check
+
+Before generating a new entry or a `[check]` line for accommodation or
+flights:
+
+```
+curl -s 'http://localhost:8321/api/travel-bookings/upcoming?limit=50'
+```
+
+If a matching booking exists, mark the corresponding prep line with the
+completed-row grammar above and include the confirmation number in
+Agent Notes.
+
+## Long-horizon DM-intent detection
+
+Referenced from `message.received.dm` and `message.received.dm_first`.
+Identify user messages that describe a commitment or plan beyond the
+current day so the DM handler can route them into roadmap.
+
+**Signals (positive):**
+- Explicit forward-looking verb + horizon phrase:
+  *"going to X next month"*, *"planning to do Y this summer"*,
+  *"want to Z this quarter"*
+- Specific future date ≥ 48h out
+- Concrete object (destination, deliverable, learning target,
+  reservation)
+
+**Not signals:**
+- Speculative language (*"maybe"*, *"someday"*, *"might"*, *"perhaps"*,
+  *"thinking about"*) without a concrete anchor
+- Current-week commitments (those belong in `today.md`)
+- Opinions, preferences, taste statements
+  (those belong in `user/*.md` via the `user-profile` skill)
+
+**Routing after detection:**
+- Dated ≥ 48h out → Agent Action Plan event entry (Preparation
+  Timeline grows once destination / details resolve).
+- Undated horizon ("this summer", "this quarter") →
+  `## Long-term Plans` line with a horizon-tag.
+- Ambiguous → keep in `agent-journal.md` as a candidate line and
+  surface via the next morning routine for user confirmation
+  (dry-run mode).
+
+## Section auto-ensure PATCH recipe
+
+Legacy roadmaps created before the `## Long-term Plans` section was
+introduced may be missing it. Before the first PATCH to that section:
+
+1. `curl -s http://localhost:8321/api/context/roadmap` and inspect the
+   body for `## Long-term Plans`.
+2. If absent, insert it after `## Quarterly Focus`:
+   ```bash
+   curl -s -X PATCH http://localhost:8321/api/context/roadmap \
+     -H 'Content-Type: application/json' \
+     -d '{"section": "quarterly_focus", "mode": "append", "content": "\n## Long-term Plans\n"}'
+   ```
+3. Then PATCH `long_term_plans` normally.
+
+Full-file PUT writers (e.g. `routine.roadmap_refresh`) do not need this
+recipe — they always emit the full section schema.
+
+## Retention (RFC-D preview)
+
+- **Agent Action Plan event entries** — kept while the event's header
+  date is within `[today - 7d, today + 180d]`. Older ✓'d entries roll
+  off into `daily/` history.
+- **`Scheduled:` entries** — kept while the Wake-up date is within
+  `[today - 1d, today + 180d]`. On completion, Status flips to ✓ and
+  the entry persists one extra day for the journal.
+- **Long-term Plans** — entries without date movement for 90 days are
+  marked `[stale]` by Evening Review. 180 days without user
+  confirmation → DM; no reply in 7 days → remove.
+
+## Cross-request write lock
+
+Roadmap writes serialize via an optional exclusive lock so a
+mid-session refresh is not interleaved with a DM handler PATCH.
+
+- If `<roadmap_write_lock_id>` is in your context, include
+  `X-Lock-Id: <roadmap_write_lock_id>` on every PUT / PATCH to
+  `/api/context/roadmap`.
+- Dispatcher auto-acquires the lock for `routine.roadmap_refresh`.
+- Flows that need to write roadmap outside that routine (DM handler,
+  evening sweeper) can acquire via
+  `POST /api/context/lock/roadmap` and release via
+  `DELETE /api/context/lock/roadmap` with `{ "lockId": "..." }`.
+- If another session holds the lock, PUT / PATCH returns **409
+  `roadmap_write_lock_held`** — back off 30 s and retry up to 3 times.
+
+## roadmap.md API
+
+```bash
+# Read
+curl -s http://localhost:8321/api/context/roadmap
+
+# Mint a new stable entry id
+curl -s -X POST http://localhost:8321/api/context/roadmap/id \
+  -H 'Content-Type: application/json' \
+  -H 'X-Lock-Id: <roadmap_write_lock_id>' \
+  -d '{"creationDate": "YYYY-MM-DD"}'
+
+# Full replace (roadmap refresh — include X-Lock-Id if context provides one)
+curl -s -X PUT http://localhost:8321/api/context/roadmap \
+  -H 'Content-Type: application/json' \
+  -H 'X-Lock-Id: <roadmap_write_lock_id>' \
+  -d '{"content": "# Roadmap\n..."}'
+
+# Section PATCH
+curl -s -X PATCH http://localhost:8321/api/context/roadmap \
+  -H 'Content-Type: application/json' \
+  -H 'X-Lock-Id: <roadmap_write_lock_id>' \
+  -d '{"section": "long_term_plans", "mode": "append", "content": "- [2026-Q3] ...\n"}'
+```
+
+Snapshotting, mtime updates, and path validation are handled by the
+context API — see the `context` skill for the full endpoint reference.
+For roadmap writes, the API also validates ID uniqueness and runs a
+transition guard: if an entry ID survives from previous → next content,
+every previous `✓ completed ...` row for that ID must still exist
+byte-for-byte. If an entry ID disappears entirely, removal is accepted
+only when the retention window permits it or the operator bypass header
+is used.
+
+## Roadmap section schema (auto-curated)
+
+<!-- CURATION:knowledge_layout id="entry-types" -->

package/agent-assets/skills/roadmap/curation.json

@@ -0,0 +1,13 @@
+{
+  "version": 1,
+  "sections": [
+    {
+      "id": "entry-types",
+      "kind": "knowledge_layout",
+      "anchor": "<!-- CURATION:knowledge_layout id=\"entry-types\" -->",
+      "human_label": "Roadmap section schema",
+      "description": "Required sections in roadmap.md and what each holds",
+      "scope_paths": ["roadmap.md"]
+    }
+  ]
+}

package/agent-assets/skills/roadmap/references/horizon-tags.md

@@ -0,0 +1,40 @@
+---
+kind: reference
+parent_skill: roadmap
+---
+
+`Review:` is the date when Evening Review should re-evaluate whether the
+line is ready to become an Agent Action Plan entry. Date math uses the
+configured user timezone, not UTC midnight.
+
+| Horizon tag | Anchor (earliest plausible start) | Default `Review:` |
+|---|---:|---:|
+| `YYYY-MM` | first day of that month | anchor - 28 days |
+| `YYYY-Qn` | first day of the quarter's first month | anchor - 45 days |
+| `YYYY spring` | `YYYY-03-01` | anchor - 60 days |
+| `YYYY summer` | `YYYY-06-01` | anchor - 60 days |
+| `YYYY autumn` | `YYYY-09-01` | anchor - 60 days |
+| `YYYY winter` | `YYYY-12-01` | anchor - 60 days |
+| `undated` | none | Source date + 90 days |
+| explicit `Review: [noreview]` | none | never fires |
+
+Northern-hemisphere season anchors are intentional. When a derived
+review date is already in the past at write time, clamp it to
+`Source date + 1 day` so newly captured plans do not fire in the same
+turn.
+
+`ReviewCount:` starts at `0`. For undated entries that fail to promote,
+Evening Review moves `Review:` forward by 90 days and increments
+`ReviewCount:`. When an undated entry reaches `ReviewCount: 3` with no
+movement, rewrite `Review:` to `[noreview]` silently; do not DM the
+user. Dated entries that fail to promote move `Review:` forward by 30
+days.
+
+User edits are normalized narrowly. If a Dashboard/API write adds a
+parseable bullet with a horizon tag and intent but omits `Source:`,
+`Review:`, or `ReviewCount:`, the context API fills
+`Source: dashboard <today>`, derives `Review:` from the table above,
+and sets `ReviewCount: 0`. Direct filesystem edits bypass the API, so
+the next roadmap refresh or evening review must preserve the line by
+rewriting it into the same canonical shape. Unparseable bullets are
+validation errors with line numbers; do not guess.

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

@@ -0,0 +1,47 @@
+---
+kind: reference
+parent_skill: roadmap
+---
+
+Action line formats:
+
+```
+- 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`.
+
+Tags: `[notify]`, `[today]`, `[check]`, `[schedule]`.
+
+### Travel (domestic / international)
+
+- International: visa/ESTA application `[notify]` 3–4 weeks before
+- Flight tickets `[notify]` 2–3 weeks before (prices rise closer to date)
+- Accommodation confirmation `[check]` 1–2 weeks before
+- Packing list `[today]` 2 days before
+- Transit plan, weather check `[today]` 1 day before
+- Final checklist `[notify]` day before departure
+
+### Deadlines / Submissions
+
+- Data gathering / research `[today]` 2 weeks before
+- Draft creation `[today]` 1 week before
+- Final review reminder `[notify]` 2 days before
+- Due date reminder `[notify]` 1 day before
+
+### Conferences / Presentations
+
+- Slide preparation `[today]` 2 weeks before
+- Rehearsal `[today]` 3 days before
+- Travel prep if applicable (see Travel above)
+
+### Recurring milestones
+
+- Progress review `[today]` 3 weeks before
+- Remaining tasks audit `[notify]` 2 weeks before
+- Final confirmation `[today]` 3 days before

package/agent-assets/skills/roadmap/seeds/entry-types.seed.json

@@ -0,0 +1,16 @@
+{
+  "kind": "knowledge_layout",
+  "files": [
+    {
+      "path": "roadmap.md",
+      "purpose": "Long-horizon user intent: goals, focus, plans, scheduled tasks, and recurring entries",
+      "sections": [
+        { "heading": "## Annual Goals", "contains": "user-authored yearly goals preserved verbatim" },
+        { "heading": "## Quarterly Focus", "contains": "user-authored quarterly focus areas preserved verbatim" },
+        { "heading": "## Long-term Plans", "contains": "agent-writable cumulative plan lines tagged with horizon" },
+        { "heading": "## Agent Action Plan", "contains": "agent-writable dated entries with stable IDs and Preparation Timeline" },
+        { "heading": "## Recurring", "contains": "recurring schedule entries preserved verbatim across refreshes" }
+      ]
+    }
+  ]
+}

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

@@ -0,0 +1,228 @@
+---
+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
+---
+
+# Schedule Wake-Up Decision Guide
+
+## When to Schedule
+Register a wake-up when **all three** are true:
+1. There is follow-up work that must happen at a specific time
+2. The current session is ending before that time
+3. No other session will reliably pick it up (a peer routine, an SSE poll, etc.)
+
+Common triggers: morning routine end, calendar event prep (15 min before), deadline/reminder requests, in-flight work needing follow-up (e.g. PR review).
+
+## Before creating — dedup pre-check (mandatory)
+
+Every `POST /api/schedule` / `POST /api/schedule/dm` call MUST be
+preceded by a dedup scan. Duplicate schedules are invisible to the
+user but compound into duplicate DMs/notifications at fire time.
+
+1. **Agent Plan check.** Scan `<today>` `## Agent Plan` for a row with
+   HH:MM within ±15 min of your target AND an overlapping subject. If
+   present, the plan is already in place — do NOT add a second one.
+2. **Pending schedule check.** `GET /api/schedule?status=pending,running`
+   and look for an item whose `scheduledFor` is within ±15 min of your
+   target with a matching `description` subject. If found, skip (or
+   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.
+
+Log the skip to `## Agent Log`:
+`- HH:MM [schedule] skipped <subject>: duplicate of <planId|row>`.
+
+Only after all three clear do you create the new schedule.
+
+## When the user wants a durable rule, not a wake-up
+
+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.
+
+## DM vs Agent Task
+
+| Criterion | `/api/schedule/dm` (free) | `/api/schedule` (~$0.03) |
+|---|---|---|
+| Message text knowable now? | Yes | No — needs lookup/decision at execution |
+| Needs calendar/API data at execution? | No | Yes |
+| Multi-step action at execution? | No | Yes |
+| Conditional on state that may change? | No | Yes |
+
+**Default to DM** when possible. Every agent wake-up costs money and context.
+
+## Writing a Good Description (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.
+
+Include all four elements:
+
+| Element | What it answers |
+|---|---|
+| **What** | Specific verb + object (notify, check, update, prepare) |
+| **Why** | The trigger or reason (meeting approaching, deadline, user request) |
+| **Who/What** | Concrete names, IDs, URLs, filenames |
+| **Expected output** | What "success" looks like (notification sent, file updated) |
+
+**Good:** `"15-minute reminder for the 14:00 design review. Attendees: Sarah, Mike. Agenda: API v2 breaking changes. Prepare the meeting-note template and notify the user via Slack."`
+
+**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:
+```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:
+
+| Tier | Roadmap behavior | Use |
+|---|---|---|
+| `transient` | Never in roadmap; surfaces in today.md only on the day it fires | Default for `/api/schedule/dm`; short pings like "call mom next Tuesday" |
+| `normal` | In roadmap only when scheduled more than 7 days out | Default for `/api/schedule`; ordinary user-facing follow-ups |
+| `strategic` | In roadmap regardless of horizon | Long-prep commitments such as ESTA / travel / deadline reminders |
+| `low` | Never in roadmap | Internal ticks already visible elsewhere, e.g. Agent Plan rows, recurring-schedule instances, morning retries |
+
+For direct DMs, omit `importance` for ordinary one-off pings. If the
+reminder is clearly tied to a long-prep commitment ("remind me in a
+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
+
+## 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`.
+- **No quiet hours (default 22:00-08:00, configurable)** unless `critical` priority.
+- **Check today.md Schedule** before creating wakes to avoid piling onto a busy hour.
+
+## Budget
+- **Max 5 wake-ups per execution.** Consolidate into a single briefing task if more.
+- **Morning Routine batches all day's wake-ups at once.** Other events schedule only immediate needs.
+
+---
+
+## API Reference
+
+### POST /api/schedule/dm — Schedule a direct DM
+Sends a pre-composed message at the specified time. No AI agent invoked.
+```bash
+curl -s -X POST http://localhost:8321/api/schedule/dm \
+  -H 'Content-Type: application/json' \
+  -d '{"time":"2026-04-06T16:00:00-04:00","message":"Reminder: Design review in 30 min.","platform":"slack"}'
+```
+| Field | Required | Description |
+|---|---|---|
+| `time` | Yes | ISO 8601 with timezone offset |
+| `message` | Yes | Complete message text — sent as-is |
+| `platform` | No | Target platform (defaults to primary) |
+| `importance` | No | `transient` (default), `normal`, or `strategic`. Use `strategic` only for roadmap-shaped long-prep reminders. |
+
+Response: `{ "status":"scheduled", "scheduleId":"123", "scheduledFor":"..." }`. Rejects times in the past (> 1 min ago).
+
+### POST /api/schedule — Schedule an agent task
+```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"}}'
+```
+| 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` |
+| `taskContext` | No | Structured metadata object |
+
+Rejects times in the past (> 1 min ago), same as `/api/schedule/dm`.
+
+### PATCH /api/schedule/:id — Edit a pending item
+```bash
+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).
+
+### GET /api/schedule — List scheduled items
+```bash
+curl -s "http://localhost:8321/api/schedule?status=pending"
+```
+Param `status` (default `pending,running`): comma-separated `pending`, `running`, `completed`, `failed`.
+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","createdAt" }] }` — `prompt` is `null` when no override is set.
+
+### DELETE /api/schedule/:id — Cancel a pending item
+```bash
+curl -s -X DELETE http://localhost:8321/api/schedule/42
+```
+Only cancels `pending` items. Response: `{ "status":"cancelled", "id":42 }` / 404 / 409.
+
+---
+
+## Recurring Schedules
+For tasks that repeat on a fixed pattern. Auto-regenerates the next occurrence after each execution.
+
+### 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 |
+
+**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).
+
+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" }] }`
+
+### 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.
+
+### 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 }`