@aitne-sh/aitne 0.1.8 → 0.1.9

package/agent-assets/skills/roadmap/references/api.md

@@ -22,7 +22,7 @@ context. Other flows (DM handler, evening sweeper) may acquire and
 release manually.
 
 Include `X-Lock-Id: <roadmap_write_lock_id>` on every PUT / PATCH to
-`/api/context/roadmap` when the tag is in your context. Other
+`/api/context/plans/roadmap` when the tag is in your context. Other
 sessions get `409 roadmap_write_lock_held` while the lock is held —
 back off 30 s and retry up to 3 times.
 
@@ -31,18 +31,18 @@ back off 30 s and retry up to 3 times.
 These return `404 {"error":"unknown_route", …}` with a hint pointing
 at the correct path:
 
-- `POST /api/context/roadmap/lock` — order reversed
-- `POST /api/context/roadmap/write-lock` — order reversed and wrong noun
+- `POST /api/context/plans/roadmap/lock` — order reversed
+- `POST /api/context/plans/roadmap/write-lock` — order reversed and wrong noun
 - `POST /api/context/lock/roadmap-write` — wrong noun
 
 A `401 {"error":"unauthorized"}` from a path you believe is correct
 means the path is still wrong (the lock endpoints are Autonomous-tier
 so no bearer token is required).
 
-## ID mint — `POST /api/context/roadmap/id`
+## ID mint — `POST /api/context/plans/roadmap/id`
 
 ```bash
-curl -s -X POST http://localhost:8321/api/context/roadmap/id \
+curl -s -X POST http://localhost:8321/api/context/plans/roadmap/id \
   -H 'Content-Type: application/json' \
   -H 'X-Lock-Id: <roadmap_write_lock_id>' \
   -d '{"creationDate":"YYYY-MM-DD"}'
@@ -64,7 +64,7 @@ The roadmap API validates two invariants on every PUT / PATCH:
    file. Duplicate ids return:
 
    ```json
-   {"error":"validation_error","message":"duplicate roadmap id rm-YYYYMMDD-abcdef","path":"roadmap.md"}
+   {"error":"validation_error","message":"duplicate roadmap id rm-YYYYMMDD-abcdef","path":"plans/roadmap.md"}
    ```
 
    Recovery: re-GET `roadmap`, mint a fresh id **for the colliding
@@ -78,7 +78,7 @@ The roadmap API validates two invariants on every PUT / PATCH:
    row returns:
 
    ```json
-   {"error":"validation_error","message":"transition_guard: completed row for rm-… changed","path":"roadmap.md"}
+   {"error":"validation_error","message":"transition_guard: completed row for rm-… changed","path":"plans/roadmap.md"}
    ```
 
    This is intentional: completed prep rows are the audit trail for

package/agent-assets/skills/roadmap/references/cross-check.md

@@ -25,14 +25,21 @@ Response shape (one row per booking):
 {
   "bookings": [
     {
-      "kind": "flight" | "hotel" | "rail" | "other",
-      "depart_at": "ISO8601 with tz",
-      "return_at": "ISO8601 with tz | null",
+      "id": "<int>",
+      "type": "flight" | "hotel" | "restaurant" | "train" | "bus" | "other",
+      "provider": "<string>",
       "destination": "city / airport / property name",
-      "confirmation_number": "<string>",
-      "source": "gmail" | "manual" | "ical"
+      "startDate": "ISO8601 | YYYY-MM-DD | null",
+      "endDate": "ISO8601 | YYYY-MM-DD | null",
+      "confirmationNumber": "<string | null>",
+      "amount": "<number | null>",
+      "currency": "<string | null>",
+      "status": "upcoming",
+      "providerMsgId": "<string | null>",
+      "createdAt": "ISO8601"
     }
-  ]
+  ],
+  "total": "<int>"
 }
 ```
 
@@ -43,7 +50,7 @@ A booking matches a roadmap event entry when **either**:
 - The booking's `destination` substring-matches the event entry's
   `Destination:` field (case-insensitive, after stripping common
   prefixes / suffixes — "Paris" matches "Paris, FR" and "Paris CDG").
-- The booking's `depart_at` date falls within the event entry's
+- The booking's `startDate` date falls within the event entry's
   `YYYY-MM-DD ~ MM-DD` header range (inclusive on both ends).
 
 When a match is found:
@@ -54,7 +61,7 @@ When a match is found:
    <YYYY-MM-DD> confirmation #<conf>`), preserving the original
    `[tag]` and date.
 3. Append a line to the entry's `**Agent Notes:**` block:
-   `- Booking confirmed (<kind>) — #<confirmation_number>`.
+   `- Booking confirmed (<type>) — #<confirmationNumber>`.
 
 ## When no match exists
 

package/agent-assets/skills/roadmap/references/migration.md

@@ -4,7 +4,7 @@ name: migration
 description: Section auto-ensure recipe for legacy roadmaps missing ## Long-term Plans. PATCH-driven; full-file PUT writers (refresh routine) do not need this.
 ---
 
-# Section auto-ensure — legacy `roadmap.md` files
+# Section auto-ensure — legacy `plans/roadmap.md` files
 
 Roadmaps created before the `## Long-term Plans` section was
 introduced may be missing that header. A direct
@@ -24,19 +24,19 @@ they never trigger `section_not_found` and never need this recipe.
 
 ```bash
 # 1. Read the file
-curl -s http://localhost:8321/api/context/roadmap
+curl -s http://localhost:8321/api/context/plans/roadmap
 
 # 2. Inspect the body for "## Long-term Plans". If present, skip the
 #    insert and go straight to the normal PATCH below.
 
 # 3. Absent → insert it after "## Quarterly Focus":
-curl -s -X PATCH http://localhost:8321/api/context/roadmap \
+curl -s -X PATCH http://localhost:8321/api/context/plans/roadmap \
   -H 'Content-Type: application/json' \
   -H 'X-Lock-Id: <roadmap_write_lock_id>' \
   -d '{"section": "quarterly_focus", "mode": "append", "content": "\n## Long-term Plans\n"}'
 
 # 4. Then PATCH long_term_plans normally
-curl -s -X PATCH http://localhost:8321/api/context/roadmap \
+curl -s -X PATCH http://localhost:8321/api/context/plans/roadmap \
   -H 'Content-Type: application/json' \
   -H 'X-Lock-Id: <roadmap_write_lock_id>' \
   -d '{"section": "long_term_plans", "mode": "append", "content": "- [undated] …"}'

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

@@ -2,7 +2,7 @@
   "kind": "knowledge_layout",
   "files": [
     {
-      "path": "roadmap.md",
+      "path": "plans/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" },

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

@@ -31,9 +31,10 @@ 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"`, run the dedup pre-check + shape
@@ -54,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
 
@@ -71,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 |
 |---|---|
@@ -89,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 |
 |---|---|---|
@@ -149,16 +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":"Hourly docker health check: run `docker ps --format` and DM if any container is in restart loop.","tier":"lite","taskContext":{"scheduledBy":"docker_monitor"}}'
+  -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. |
+| `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-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`. |
+| `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`.
@@ -169,7 +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), `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.
+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
@@ -210,24 +214,28 @@ model, batch) are in the errors reference below.
 
 ---
 
-## Recurring Schedules
+## Recurring: work → Agent; DM → dm_session
 
-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.
+`/schedule` registers **one-shot** wake-ups and DMs. For repeating tasks:
 
-{{> ref:recurring }}
+- **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.
 
-### recurrenceRule grammar — engine vs consumer
+`GET /api/recurring-schedules` stays read-only for the dedup pre-check.
 
-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.
+### 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

@@ -31,7 +31,7 @@ curl -s -X POST http://localhost:8321/api/schedule/batch \
         "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"],
+          "references": ["plans/projects/q2-roadmap.md#open-risks", "calendar:event:standup-2026-05-15"],
           "tone": "concise"
         }
       }
@@ -57,7 +57,7 @@ curl -s -X POST http://localhost:8321/api/schedule/batch \
 | `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. |
+| `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

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

@@ -133,9 +133,12 @@ Apply to `POST /api/schedule` and `POST /api/schedule/batch`.
 
 | 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. |
+| <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
 
@@ -161,7 +164,7 @@ here.
 
 `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`,
+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

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

@@ -25,7 +25,7 @@ even after `/settings/models` re-routes the process key). The two are
   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`,
+  four backends. Examples: `claude-opus-4-8`, `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.
@@ -33,7 +33,7 @@ even after `/settings/models` re-routes the process key). The two are
   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
+  `anthropic/claude-opus-4-8` are NOT composites and fall through to
   the cross-backend scan.
 
 Unknown / ambiguous / deprecated model tokens surface through the
@@ -76,7 +76,7 @@ Response shape:
   "tiers": ["lite", "medium", "high"],
   "modelAliases": { "sonnet": "medium", "opus": "high" },
   "models": {
-    "claude":   [{ "id": "claude-opus-4-7", "tier": "high", "deprecated": false }, ...],
+    "claude":   [{ "id": "claude-opus-4-8", "tier": "high", "deprecated": false }, ...],
     "codex":    [...],
     "gemini":   [...],
     "opencode": [...]

package/agent-assets/skills/schedule/references/recurrence-rule.md

@@ -76,7 +76,7 @@ Same template applies to "every 5 minutes", "every 30 minutes",
 ## Cadence string vs structured rule
 
 Always send both `cadence` (human-readable, rendered in
-`rules/management.md` §B) and `recurrenceRule` (structured, what the
+`policies/management.md` §B) and `recurrenceRule` (structured, what the
 scheduler executes). They must agree — if they drift, the rendered
 file misleads the user about what the scheduler will actually do.
 

package/agent-assets/skills/scheduled-managed-task/SKILL.md

@@ -175,39 +175,49 @@ runs. The (`section`, `mode`, `content`, `cutoff`, `maxEntries`)
 shape is the contract today — see `contextPatchSchema` in
 `packages/shared/src/schemas.ts`.
 
-**Source-id capture (write the `external_id` into the body lines):**
-the entity-mirror watcher (P5) reparses the file's frontmatter on
-change, so the dedup contract in §7.6 hinges on the upstream id
-landing in **frontmatter**, not just the body. Until the entity-mirror
-reconciler ships AND the context API gains a `frontmatter*` patch
-mode for `<domain>/<type-plural>/*` files, do this:
-
-1. Always include `- external_id: <id>` on its own line in the
-   appended `## <App> Notes` body so a future reconciler-rebuild can
-   recover the binding from prose.
-2. Track the binding in the §B "Recently changed" path — the
-   `agent_actions.management_task.run_recorded` row's `detail` is
-   structured and survives even when the file body doesn't reflect
-   the binding cleanly.
-
-> **Implementation gap to flag** (Phase 5 / extended Phase 3): the
-> context PATCH route does not currently:
->   - allow writes under `<domain>/<type-plural>/*` (no entry in
->     `CONTEXT_WRITE_PERMISSIONS`), so this PATCH returns `403
->     forbidden` until the whitelist is widened, and
->   - expose a `frontmatterMerge` mode for deep-merging
->     `frontmatter.sources.<app>`.
-> Both are required by design 21 §10.4 step 4b and must land before
-> this Step 5a goes from "designed" to "operational". Until then,
-> Step 5b's audit row is the durable trace of the run — surface that
-> in the activity-view rather than relying on the entity body.
-
-If the entity file does not previously exist, today's API requires a
-PUT with full content (the `<domain>/<type-plural>/*` write path is
-gated by the same whitelist note above). When the gap closes, the
-first PATCH must include a complete frontmatter block — `type`,
-`domain`, `slug`, `title`, `created`, `sources` — or the daemon
-returns 422 against `EntitySchema`.
+**Source-id capture — deep-merge into frontmatter (`mode:"frontmatterMerge"`):**
+the §7.6 dedup contract hinges on the upstream id landing in **frontmatter**
+(`sources.<app>.external_id`) — the canonical signal the entity-mirror watcher
+reparses and `GET /api/entities?source=…&external_id=…` queries — not just the
+body. The context PATCH route exposes `mode:"frontmatterMerge"` for exactly this
+(design 21 §10.4 step 4b): it deep-merges a partial frontmatter object into the
+file's existing YAML (nested objects merge key-by-key; scalars/arrays replace),
+so a new `<app>` source is linked without clobbering other apps' ids, other
+frontmatter keys, or the body:
+
+```bash
+curl -sS -X PATCH "http://localhost:8321/api/context/work/meetings/2026-12-04-foo-1on1" \
+  -H 'Content-Type: application/json' \
+  -d @- <<'JSON'
+{
+  "mode": "frontmatterMerge",
+  "frontmatter": {
+    "sources": { "zoom": { "external_id": "zm_xyz789" } },
+    "last_synced_at": "2026-12-04T09:00:00Z"
+  }
+}
+JSON
+```
+
+`frontmatterMerge` requires a non-empty `frontmatter` object and takes no
+`section` (it never touches the body). Append the human-readable
+`## <App> Notes` section in a separate `mode:"append"` / `"append_to_file"`
+PATCH. Also keep Step 5b's audit row as the durable structured trace of the run.
+
+> **Write path:** the bare `<domain>/<type-plural>/<slug>` path is alias-rewritten
+> to `knowledge/entities/<domain>/<type-plural>/<slug>` by `context-vault-aliases.ts`,
+> which **is** whitelisted in `CONTEXT_WRITE_PERMISSIONS` for `PUT`/`PATCH`
+> (autonomous tier), so both the frontmatterMerge and the body-append PATCH
+> succeed on an existing entity file. (Recognised domains: `work`, `travel`,
+> `finance`, `personal`, `health`, `learning`.)
+
+If the entity file does not previously exist, PATCH returns
+`404 context.path_not_found` — today's API requires a PUT with full
+content to create it first (the `<domain>/<type-plural>/*` write path
+is whitelisted for both PUT and PATCH; only the file-existence rule
+forces the PUT-first ordering). The creating PUT must include a
+complete frontmatter block — `type`, `domain`, `slug`, `title`,
+`created`, `sources` — or the daemon returns 422 against `EntitySchema`.
 
 ### Step 5b — Update the row
 
@@ -296,7 +306,7 @@ agent keeps trying, but doesn't disappear silently.
 `scheduled.task` flow's "Output contract — your final text becomes a
 DM" applies (`scheduled.task.md`). For managed-task runs the default
 is **empty final text**: bookkeeping is invisible by design. The user
-sees the change reflected in `_activity/<source>.md` (auto-built) and
+sees the change reflected in `state/activity/<source>.md` (auto-built) and
 `<domain>/_index.md`, not in a chat ping per fire.
 
 Exceptions:
@@ -343,7 +353,7 @@ appended `## <App> Notes` body, not as a separate DM.
 | HTTP | `error` | What to do |
 |---|---|---|
 | 400 (`/api/managed-tasks/:id/run-result`) | `invalid_id` / `validation_error` | Body shape drift — re-check field names exactly match `last_run_at` / `last_result` / `consecutive_failures` |
-| 403 (`/api/context/<domain>/<type-plural>/...`) | `forbidden` | Entity-domain write paths are not yet whitelisted (Phase 5 gap, §Step 5a). Skip the entity merge for this run, still record run-result, and surface a one-line warning in `last_result`. |
+| 404 (`/api/context/<domain>/<type-plural>/...`) | `context.path_not_found` | The entity file does not exist yet — PATCH cannot create it. Create it first with a PUT carrying full content + complete frontmatter (§Step 5a), then the merge succeeds. (Entity-domain write paths ARE whitelisted for PUT/PATCH; the prior 403 claim is obsolete.) |
 | 404 (`/api/managed-tasks/:id`) | `not_found` | Row was stopped mid-run. End the session quietly. |
 | 422 (`/api/context/...`) | `validation_error` | Frontmatter incomplete or malformed; populate all required fields and retry once |
 | 422 (`/api/managed-tasks/:id`) | `validation_error` | Path / body shape rejected; drop the offending field (typically `output_path`) and retry once with the rest |
@@ -379,7 +389,7 @@ appended `## <App> Notes` body, not as a separate DM.
 | `GET /api/entities?source=` | Step 4 bias hint (list-by-source-key) |
 | `GET /api/entities?domain=&type=&date=&q=` | Step 4.2 (tier-2 fuzzy) |
 | `GET /api/entities/by-path?path=` | Step 4 (verify before merging) |
-| `PATCH /api/context/<domain>/<type-plural>/<slug>` | Step 5a (gated by entity-domain write whitelist — Phase 5 gap) |
+| `PATCH /api/context/<domain>/<type-plural>/<slug>` | Step 5a (whitelisted PUT/PATCH; PATCH requires the file to exist — PUT-create first if 404) |
 | `PATCH /api/managed-tasks/:id/run-result` | Step 5b (internal — last_run_at / last_result / consecutive_failures) |
 | `PATCH /api/managed-tasks/:id` | Step 5b output-path back-fill only |
 | `POST /api/notify` | Step 6 (only on the 3-failures-in-a-row crossing edge) |

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

@@ -23,7 +23,7 @@ Output language: today.md is Policy B — see `<output_language_policy>`. The sk
    `## Agent Plan`, `## Agent Notes`, `## Agent Log`, `## Handoff` —
    in this order.
 
-A `PUT /api/context/today` whose line 1 or line 2 fails the exact regex
+A `PUT /api/context/state/today` whose line 1 or line 2 fails the exact regex
 is rejected with 400 and the daemon does NOT write the file. Translating
 any keyword on line 2 (the field labels, the `Weekday`/`Weekend` value,
 or `on`/`off`) into the user's primary language is the most common
@@ -63,9 +63,9 @@ line 1 is exactly `# 2026-04-28 (Tuesday)`. Do **not** advance the date
 because the routine is "preparing tomorrow"; the morning routine always
 prepares the agent-day in progress, not the next one.
 
-`PUT /api/context/today` returns 422 if line 1 disagrees with the
-daemon's current agent-day; the error message echoes both values so a
-mistake is recoverable in the same session.
+`PUT /api/context/state/today` returns 400 (`error:"validation_error"`) if
+line 1 disagrees with the daemon's current agent-day; the error message
+echoes both values so a mistake is recoverable in the same session.
 
 today.md has **no YAML frontmatter** — the H1 must be the first byte of
 the file.
@@ -80,7 +80,7 @@ Line 2 encodes today's filter policy (field order is fixed — downstream parser
 
 Derivation (Morning Routine at 04:00):
 1. Day-of-week from `<current_time>`. Weekday = Mon–Fri, Weekend = Sat–Sun (unless user/profile.md overrides).
-2. Read `user/profile.md` → ## Notification Preferences. Apply matching policy.
+2. Read `identity/profile.md` → ## Notification Preferences. Apply matching policy.
 3. No explicit policy → default: weekday = all on, weekend = work off, study on, personal on.
 
 Category → focus-dimension mapping:
@@ -143,7 +143,7 @@ Violations: row without schedule → silently never fires. Schedule without row
 `scheduled.task` and `scheduled.dm` (and any other event that flips an
 Agent Plan row) follow the close-the-loop lifecycle in the reference
 below: execute, append Agent Log entry, read-then-flip the row to
-`[x]` with annotation, retry on `today.md` lock, surface missing-row
+`[x]` with annotation, retry on `state/today.md` lock, surface missing-row
 state.
 
 DM handlers and hourly checks do not flip Agent Plan rows — read the
@@ -195,14 +195,14 @@ The generic GET / PUT / PATCH / DELETE surface — modes, fields, error
 envelopes, body-submission shape — is documented in the **context**
 skill `references/api.md`. today.md-specific rules layered on top:
 
-- **Lock.** `today.md` is locked by the Morning Routine. Include
+- **Lock.** `state/today.md` is locked by the Morning Routine. Include
   `X-Lock-Id: <today_write_lock_id>` on every PUT / PATCH when the
   tag is in your context; other sessions get `409
-  today_write_lock_held` while the lock is held.
+  morning_routine_lock_held` while the lock is held.
 - **Skeleton validators.** PUT is rejected (400) if line 1 fails the
   H1 date regex or line 2 fails the day-type quote regex (see §"Line 1
   — which date?" and §"Header line — day-type filter" above). PUT is
-  rejected (422) if line 1's date disagrees with the daemon's current
+  also rejected (400) if line 1's date disagrees with the daemon's current
   agent-day — the error echoes both values.
 
 ## Knowledge map — section shape (auto-curated)

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

@@ -5,9 +5,9 @@
       "id": "section-shape",
       "kind": "knowledge_layout",
       "anchor": "<!-- CURATION:knowledge_layout id=\"section-shape\" -->",
-      "human_label": "today.md section shape",
+      "human_label": "state/today.md section shape",
       "description": "Required sections in today.md and what each holds",
-      "scope_paths": ["today.md"]
+      "scope_paths": ["state/today.md"]
     },
     {
       "id": "agent-notes-flavors",
@@ -15,7 +15,7 @@
       "anchor": "<!-- CURATION:convention_notes id=\"agent-notes-flavors\" -->",
       "human_label": "Agent Notes flavors",
       "description": "Sub-shapes the agent uses inside ## Agent Notes (look-ahead, day-time observation, latent profile question)",
-      "scope_paths": ["today.md"]
+      "scope_paths": ["state/today.md"]
     }
   ]
 }

package/agent-assets/skills/today/references/agent-plan-lifecycle.md

@@ -49,10 +49,10 @@ the action it represents, before the session exits.
    + action text), and flip `[ ]` → `[x]`:
 
    ```bash
-   curl -s http://localhost:8321/api/context/today
+   curl -s http://localhost:8321/api/context/state/today
    # Find the agent_plan section. Edit the matching row's checkbox.
    # Then PATCH the full updated section body:
-   curl -s -X PATCH http://localhost:8321/api/context/today \
+   curl -s -X PATCH http://localhost:8321/api/context/state/today \
      -H 'Content-Type: application/json' \
      -H 'X-Lock-Id: <today_write_lock_id>' \
      -d '{"section": "agent_plan", "mode": "replace", "content": "<full merged section>"}'
@@ -86,10 +86,11 @@ triggers self-recovery and inflates the agent-actions audit.
 
 ## Lock retry rules
 
-The Morning Routine holds the `today.md` write lock. Other sessions
-get `409 today_write_lock_held` on PUT / PATCH while the lock is held.
+The Morning Routine holds the `state/today.md` write lock. Other sessions
+get `409 morning_routine_lock_held` on PUT / PATCH while the lock is held.
 
-- Detect by the response body `{"error":"lock_held"}` or by the
+- Detect by the response body `{"error":"morning_routine_lock_held"}`
+  (with `errors[0].code: "context.morning_routine_lock_held"`) or by the
   status code 409 alone.
 - Retry policy: 30 s back-off, max 3 attempts. If the third attempt
   also returns 409, log `loop-closeout deferred (lock_held)` to Agent

package/agent-assets/skills/today/seeds/section-shape.seed.json

@@ -2,7 +2,7 @@
   "kind": "knowledge_layout",
   "files": [
     {
-      "path": "today.md",
+      "path": "state/today.md",
       "purpose": "today's plan, schedule, agent log, and handoff to tomorrow",
       "sections": [
         { "heading": "## Plan", "contains": "the day's intent in plain prose" },