@aitne-sh/aitne 0.1.7 → 0.1.9

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

@@ -0,0 +1,232 @@
+---
+kind: reference
+name: api
+description: Canonical /api/context/* surface — read / write / list / lock / archive / restore / health / repair / action-log. Organised by operation.
+---
+
+# /api/context/* — Operation reference
+
+Body submission follows `_safety.md` "Daemon-API body submission":
+small section PATCHes use inline `-d '{...}'`; full-file PUT uses the
+stdin heredoc `-d @- <<'JSON'` shape because the body runs multi-KB.
+
+Add `X-Lock-Id: <today_write_lock_id>` (for `state/today.md`) or
+`X-Lock-Id: <roadmap_write_lock_id>` (for `plans/roadmap.md`) on every
+PUT / PATCH when the matching lock-id tag is in your context — the
+daemon emits the tag only while the corresponding lock is held by
+this session.
+
+## Read
+
+### GET /api/context/:path
+
+```bash
+curl -s http://localhost:8321/api/context/plans/roadmap
+```
+
+Response: `{ "content": "...", "lastModified": "ISO8601" }` or `404`.
+Returns the **entire file** — no section-level GET. Path traversal is
+rejected; the trailing `.md` is implicit (do not include it in the
+URL).
+
+### GET /api/context/list/:dir
+
+```bash
+curl -s http://localhost:8321/api/context/list/projects
+```
+
+Response: `{ "files": [{ "name", "lastModified" }, …] }`. Use this to
+enumerate `projects/`, `weekly/`, `monthly/`, `user/`, `rules/`,
+`routines/`, `inbox/` before deciding a write target.
+
+### GET /api/context/today/reconciliation
+
+Returns the Morning Routine's reconciliation report for `state/today.md`
+(which mail/calendar/Notion sources contributed what to User Tasks /
+Agent Plan). Read-only diagnostic surface; not the place to write
+changes.
+
+### GET /api/context/health
+
+Returns a file-by-file health report — missing frontmatter, stale
+`updated`, validator failures. Read-only.
+
+## Write
+
+### PUT /api/context/:path — Full replace
+
+Fields:
+
+| Field | Type | Description |
+|---|---|---|
+| `content` | string (required) | Full file body, including frontmatter and H1 where the file's validator requires them. |
+| `expectedMtime` | string (optional) | ISO 8601. When present the daemon returns `409` if the current mtime differs — race protection for read-modify-write loops. |
+
+Add `X-Lock-Id: <lock-id>` when writing a locked file (`state/today.md`,
+`plans/roadmap.md`). Snapshots the prior content for restore.
+
+Common rejections:
+
+- `400 {error:"validation_error", message, path}` — file-specific
+  validator failed (e.g. `state/today.md` line-1 date regex, `plans/roadmap.md`
+  transition guard, required frontmatter missing on `user/*.md` /
+  `rules/*.md` / `projects/*.md` / `daily/*.md` / `weekly/*.md` /
+  `monthly/*.md`).
+- `409 {error:"morning_routine_lock_held"}` — the Morning Routine holds
+  the `state/today.md` write lock; `409 {error:"roadmap_write_lock_held"}`
+  — another session holds the `plans/roadmap.md` lock. Retry with
+  backoff (30s × 3).
+- `400 {error:"validation_error", message, path}` — also covers the
+  `state/today.md` line-1 agent-day mismatch (the message echoes both the
+  supplied date and the daemon's current agent-day). The `422` status is
+  reserved for *frontmatter* validation on globbed files (`user/*.md`,
+  `rules/*.md`, `projects/*.md`, `daily/*.md`, `weekly/*.md`,
+  `monthly/*.md`), not for today.md line-1.
+
+`policies/management.md` is user-controlled policy: modify only when the
+user explicitly asks, and preserve every unrelated section.
+
+### PATCH /api/context/:path — Section operation
+
+```bash
+curl -s -X PATCH http://localhost:8321/api/context/state/today \
+  -H 'Content-Type: application/json' \
+  -d '{"section": "agent_log", "mode": "append", "content": "- 09:35 Processed meeting summary"}'
+```
+
+| Field | Type | Description |
+|---|---|---|
+| `section` | string | snake_case of the heading (e.g. `learned_context`, `agent_log`, `log`). **Omit for `append_to_file` and `frontmatterMerge`**; required for every other mode. |
+| `mode` | `append` \| `replace` \| `clear` \| `clear_before` \| `append_to_file` \| `frontmatterMerge` | Default `append`. |
+| `content` | string | Ignored for `clear` / `clear_before` / `frontmatterMerge`. |
+| `cutoff` | string | **Required when `mode: "clear_before"`.** SQLite format `YYYY-MM-DD HH:MM:SS` (zero-padded). Removes bullet rows whose `- [YYYY-MM-DD HH:MM:SS]` timestamp is ≤ cutoff. |
+| `maxEntries` | number | Optional for `mode: "append"`. After appending, trim oldest bullet entries from the top of the section body so at most `maxEntries` bullets remain. Non-bullet lines are preserved. SignalDetector uses cap = 20. |
+| `frontmatter` | object | **Required when `mode: "frontmatterMerge"`** (and only valid then). Non-empty partial frontmatter object, deep-merged into the file's YAML frontmatter. |
+
+Mode semantics:
+
+- `append` — add `content` to the end of the section body. Preserves siblings byte-for-byte.
+- `replace` — replace the entire section body with `content`. **Read-before-write is mandatory** — `replace` does not merge; sending just one bullet erases every sibling. The skill body's "Worked example" shows the GET-merge-PATCH pattern.
+- `clear` — drop the section body, keep the heading.
+- `clear_before` — rolling-log trim, drops bullets with timestamps ≤ `cutoff`. Non-bullet lines preserved. Race-safe consumption shape for `Raw Signals` and similar logs.
+- `append_to_file` — omit `section`, append `content` to the end of the file. The intended first-write path when a section header does not exist yet: include the header inside `content` (`"\n## Section\n- bullet\n"`). Also the only write shape for files with no canonical section schema (`journal/agent.md`).
+- `frontmatterMerge` — omit `section`; deep-merge the `frontmatter` object into the file's existing YAML frontmatter (nested objects merge key-by-key; scalars/arrays replace), preserving the body verbatim. The chokepoint-safe way to link entity `sources.<app>.<id>` + set `last_synced_at` without a read-modify-write of the whole file (design 21 §10.4).
+
+Common rejections (informational responses worth knowing):
+
+- `400 {error:"section_not_found", section, availableSections:[…]}` — the section name did not match. `availableSections` lists every snake_cased heading the file actually has; pick the closest match and retry. Do NOT retry the same `section` value.
+- `400 {error:"validation_error", message, path}` — content failed the file-specific validator.
+- `400 {error:"cutoff_required", message}` — `clear_before` was called without a valid `cutoff`.
+- `409 {error:"morning_routine_lock_held"}` (PATCH/PUT on `state/today`) or
+  `409 {error:"roadmap_write_lock_held"}` (PATCH/PUT on `plans/roadmap`) —
+  the file's write lock is held by another session. (The generic
+  `lock_held` code is only emitted by `POST /api/context/lock/morning-routine`
+  on contended acquisition, never by a PATCH/PUT.)
+
+### DELETE /api/context/:path
+
+Removes the file (snapshot first). The daemon only allows DELETE on a
+small set of paths — notably `policies/routines/custom/<slug>` (after the user
+asks to retire a custom routine). Most files are NOT delete-eligible
+(e.g. `state/today.md`, `plans/roadmap.md`, `identity/profile.md`); the daemon returns
+`403 {error:"forbidden"}` (with `errors[0].code: "context.write_forbidden"`)
+for those.
+
+## Lifecycle
+
+### POST /api/context/archive-today
+
+Rotates `state/today.md` → `state/yesterday.md` (synthesized `daily/YYYY-MM-DD.md`
+is now written by the Morning Routine, not this endpoint). Called by
+the Morning Routine during day rotation; other sessions should NOT
+invoke this directly.
+
+### POST /api/context/restore-snapshot/:id
+
+Restores the file from snapshot `id` (the daemon snapshots every PUT /
+PATCH / DELETE). Diagnostic / recovery surface; never part of a normal
+write path. The snapshot listing endpoint is `GET /api/context/health`
+adjacent and is dashboard-only — agents should not rely on it in flows.
+
+### POST /api/context/repair/stub
+
+Auto-repairs a stubbed file (e.g. a file that exists but has only the
+H1) by re-running its template seed. Recovery surface; called only
+when `GET /api/context/health` reports the file as stubbed.
+
+## Locks
+
+`state/today.md` and `plans/roadmap.md` are locked files: `PUT` / `PATCH` requires
+the lock to be held by the calling session, and the daemon emits an
+`X-Lock-Id` header value that must be echoed on each request via the
+`X-Lock-Id:` header.
+
+### Morning-routine lock (today.md)
+
+| Action | Verb | Path |
+|---|---|---|
+| Acquire | `POST` | `/api/context/lock/morning-routine` |
+| Release | `DELETE` | `/api/context/lock/morning-routine` (body `{"lockId":"…"}`) |
+
+The dispatcher auto-acquires this lock for `routine.morning_routine`
+and surfaces the id via `<today_write_lock_id>` in the prompt context.
+Other sessions get `409 morning_routine_lock_held` on PUT / PATCH while
+the lock is held — back off 30 s and retry up to 3 times.
+
+### Roadmap lock
+
+| Action | Verb | Path |
+|---|---|---|
+| Acquire | `POST` | `/api/context/lock/roadmap` |
+| Release | `DELETE` | `/api/context/lock/roadmap` (body `{"lockId":"…"}`) |
+
+The dispatcher auto-acquires for `routine.roadmap_refresh`. Other
+flows (DM handler, evening sweeper) can acquire / release manually.
+PUT / PATCH returns `409 roadmap_write_lock_held` while held by
+another session — same 30 s × 3 retry pattern.
+
+**Path-name gotchas** (these return `404 {"error":"unknown_route", …}`
+with a hint pointing at the correct path):
+
+- `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).
+
+## Roadmap-specific writes
+
+### POST /api/context/plans/roadmap/id
+
+Mints a new stable entry id (`rm-YYYYMMDD-<hash>`) for a roadmap row.
+Requires `X-Lock-Id: <roadmap_write_lock_id>`.
+
+```bash
+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"}'
+```
+
+The roadmap API also validates ID uniqueness on PUT / PATCH 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.
+
+## Action log
+
+### POST /api/action/log
+
+```bash
+curl -s -X POST http://localhost:8321/api/action/log \
+  -H 'Content-Type: application/json' \
+  -d '{"actionType": "observation", "detail": "reviewed 6 pending changes, added 2 tasks", "result": "success"}'
+```
+
+Records an entry in `agent_actions` for the dashboard's audit feed.
+Not the same as `state/today.md ## Agent Log` (that's a markdown surface;
+this is a SQLite row). Risk tier: Autonomous.

package/agent-assets/skills/context/references/required-frontmatter.md

@@ -0,0 +1,73 @@
+---
+kind: reference
+name: required-frontmatter
+description: YAML frontmatter required by /api/context/* validators on full-file PUT — per-glob type/owner/updated values, H1 requirement.
+---
+
+# Required frontmatter — guarded files
+
+Full-file `PUT /api/context/<path>` for the following globs is rejected
+(`400 validation_error`) unless the body opens with the matching YAML
+frontmatter followed by at least one H1 heading.
+
+Use today's date (the value from `<current_agent_day date="…" />`) for
+`updated`. The daemon does not auto-fill `updated`; an outdated value
+trips the Evening Review's stale-file detector.
+
+## Per-glob frontmatter
+
+| File glob | `type` | `owner` | Required H1 |
+|---|---|---|---|
+| `projects/*.md` | `project` | `shared` | Yes |
+| `daily/*.md` | `daily` | `agent` | Yes |
+| `weekly/*.md` | `weekly` | `agent` | Yes |
+| `monthly/*.md` | `monthly` | `agent` | Yes |
+| `rules/*.md` | `rule` | `shared` | Yes |
+| `user/*.md` | `user` | `shared` | Yes |
+
+Every glob also requires `updated: YYYY-MM-DD`.
+
+## Skeleton
+
+```yaml
+---
+type: <from table>
+owner: <from table>
+updated: YYYY-MM-DD
+---
+
+# <Title>
+
+…body…
+```
+
+## Section-level PATCH
+
+`PATCH /api/context/<path>` (`section` + `mode`) **preserves existing
+frontmatter** byte-for-byte. You do not need to re-supply the
+frontmatter on PATCH. The validator only re-runs the frontmatter check
+on `PUT` (full replace).
+
+## Files outside the table
+
+`state/today.md`, `plans/roadmap.md`, `journal/agent.md`, and `policies/management-captures/*.md`
+have their own validators (date-line regex, transition guard, append-
+only mode, policy schema). The frontmatter rules in this reference do
+not apply to them — see each owning skill for the specifics.
+
+## Common 400 envelope
+
+```json
+{
+  "error": "validation_error",
+  "message": "identity/people.md is missing required frontmatter field: updated",
+  "path": "identity/people.md"
+}
+```
+
+The `message` field names the offending field. Re-PUT with the
+corrected frontmatter; the daemon does not partially repair the body.
+
+`POST /api/context/repair/stub` is the recovery path for a file that
+exists but has only the H1 — it re-runs the template seed. Do not use
+it to bypass a frontmatter validation failure on your own PUT body.

package/agent-assets/skills/context/references/snapshot-files.md

@@ -0,0 +1,103 @@
+---
+kind: reference
+name: snapshot-files
+description: Weekly / monthly review snapshots, rules / routines files — who writes, when, with what cadence and frontmatter.
+---
+
+# Snapshot files — weekly / monthly / rules / routines
+
+These files live in the primary management vault under
+`weekly/`, `monthly/`, `rules/`, and `routines/`. They are not part
+of the day-to-day context churn (`state/today.md`, `plans/roadmap.md`,
+`projects/*.md`); they accumulate slowly and are written by routines
+or by explicit user request.
+
+## weekly/*.md, monthly/*.md
+
+| File | Path | Cadence | Writer | Verb |
+|---|---|---|---|---|
+| Weekly review | `weekly/YYYY-Www.md` | Friday Weekly Review only | `routine.weekly_review` | `PUT` (full body) |
+| Monthly review | `monthly/YYYY-MM.md` | Month-end Monthly Review only | `routine.monthly_review` | `PUT` (full body) |
+
+Notes:
+
+- Monthly files are **user-facing only** — agent-side metrics (cost,
+  retry counts, self-critique) go to `journal/agent.md`, not here.
+- Weekly file name uses ISO week (`YYYY-Www` — `2026-W19`, not
+  `2026-W5`); pad the week to two digits.
+- Never write `weekly/*.md` or `monthly/*.md` on any other day. The
+  Morning Routine, Hourly Check, Evening Review, and DM handlers do
+  not produce these files; if you are not the matching review
+  routine, do not PUT this path.
+- `PATCH` is technically accepted but unusual. The normal write is a
+  single full-body `PUT` at the end of the review session.
+- **Weekly leverage contract.** `weekly/YYYY-Www.md` carries three
+  load-bearing H2 sections — `## Carry Over to Next Week`,
+  `## Next Week Focus`, `## Lessons for Next Week` — that the
+  morning_routine lifts mechanically via the `<previous_week>` context
+  block every morning of the next ISO week. Headings must match
+  verbatim (digest extractor is header-regex bound); caps are 5 / 3 /
+  3 bullets respectively; empty sections render as `(none recorded)`
+  downstream. Full design: `docs/design/appendices/weekly-next-week-leverage.md`.
+
+## agent/journal.md
+
+| Field | Value |
+|---|---|
+| Owner | agent |
+| User-facing | No — never read in DMs / briefings / notifications |
+| Write verb | `PATCH mode: "append_to_file"` (no `section` needed) |
+
+Weekly sections: `## Weekly YYYY-Www` (What worked / slipped /
+improvements / Metrics). Monthly: `## Monthly YYYY-MM` (follow-up /
+self-critique / gap / adjustments / Metrics). The Evening Review,
+Weekly Review, and Monthly Review each append their own block.
+
+**Nothing from this file should appear in notifications.** The journal
+is the agent's private metrics surface, not user-readable content.
+
+## rules/*.md, routines/*.md
+
+User-controlled policy and routine files. Only modify when the user
+explicitly asks to change the policy or routine itself.
+
+### `rules/*.md`
+
+- Preserve unrelated sections verbatim. PATCH the one section the
+  user is changing; do not full-body PUT.
+- `policies/management.md` is the durable management policy file —
+  modify only when the user explicitly asks.
+
+### `policies/management-captures/<slug>.md` and `policies/management-captures/_index.md`
+
+Route to the `management-policy` skill. It owns the read-before-write,
+similarity-detection, and pause/resume fan-out for durable policies.
+**Do not hand-edit from this skill.** A direct PATCH here bypasses the
+similarity check and the dossier / routine fan-out.
+
+### `routines/<cadence>.md` (built-in cadences)
+
+- Cadences: `morning`, `evening`, `weekly`, `monthly`, `hourly`.
+- Keep the existing frontmatter. Keep a `## Checks` section.
+- Append or edit `### <label>` blocks under `## Checks`; each block
+  is one user-authored rule the cadence runs.
+
+### `policies/routines/custom/<slug>.md`
+
+Full-file `PUT` is usually safest. Required frontmatter:
+
+```yaml
+type: rule
+slug: <kebab-name>
+cron: '<cron expression>'
+process_key: <ProcessKey from packages/shared/src/process-key.ts>
+enabled: true
+backend_tier: lite | medium | high
+max_budget_usd: <number>
+```
+
+The file body must also contain a `## Checks` section.
+
+Deleting a custom routine uses `DELETE /api/context/policies/routines/custom/<slug>`
+**only** after the user asks to retire it. The daemon snapshots the
+prior content for restore.

package/agent-assets/skills/context/seeds/file-responsibilities.seed.json

@@ -1,13 +1,13 @@
 {
   "kind": "knowledge_layout",
   "files": [
-    { "path": "today.md", "purpose": "today's schedule, tasks, agent log, handoff", "sections": [{ "heading": "## Schedule", "contains": "today's events" }, { "heading": "## Tasks", "contains": "open tasks" }, { "heading": "## Agent Notes", "contains": "agent observations" }] },
-    { "path": "roadmap.md", "purpose": "long-horizon agent action plan + Long-term Plans", "sections": [{ "heading": "## Annual Goals", "contains": "year-scope outcomes" }, { "heading": "## Quarterly Milestones", "contains": "quarter-scope deliverables" }, { "heading": "## Focus Areas", "contains": "current themes of work" }] },
+    { "path": "state/today.md", "purpose": "today's schedule, tasks, agent log, handoff", "sections": [{ "heading": "## Schedule", "contains": "today's events" }, { "heading": "## Tasks", "contains": "open tasks" }, { "heading": "## Agent Notes", "contains": "agent observations" }] },
+    { "path": "plans/roadmap.md", "purpose": "long-horizon agent action plan + Long-term Plans", "sections": [{ "heading": "## Annual Goals", "contains": "year-scope outcomes" }, { "heading": "## Quarterly Milestones", "contains": "quarter-scope deliverables" }, { "heading": "## Focus Areas", "contains": "current themes of work" }] },
     { "path": "projects/*.md", "purpose": "per-project state summaries (slug-named)", "sections": [{ "heading": "## Overview", "contains": "what the project is about" }, { "heading": "## Lifecycle Phases", "contains": "phase ladder for the project" }] },
-    { "path": "weekly/*.md", "purpose": "weekly review snapshots (YYYY-Www)", "sections": [{ "heading": "## Highlights", "contains": "wins and lessons of the week" }] },
+    { "path": "weekly/*.md", "purpose": "weekly review snapshots (YYYY-Www); Carry Over / Next Week Focus / Lessons are lifted into next week's morning_routine via <previous_week>", "sections": [{ "heading": "## Highlights", "contains": "wins of the week" }, { "heading": "## Open Loops", "contains": "tasks/commitments still pending" }, { "heading": "## Carry Over to Next Week", "contains": "open loops to carry over (max 5) with one-line reason" }, { "heading": "## Next Week Focus", "contains": "top priorities for next week (max 3)" }, { "heading": "## Lessons for Next Week", "contains": "behavioral observation → action (max 3)" }] },
     { "path": "monthly/*.md", "purpose": "monthly review snapshots (YYYY-MM)", "sections": [{ "heading": "## Theme", "contains": "the month's overall theme" }] },
     { "path": "rules/*.md", "purpose": "user-controlled policy files", "sections": [{ "heading": "## Why", "contains": "rationale for the rule" }, { "heading": "## How", "contains": "concrete rule shape" }] },
     { "path": "user/*.md", "purpose": "user identity and preferences dictionary", "sections": [{ "heading": "## Identity", "contains": "name role tz" }] },
-    { "path": "agent/journal.md", "purpose": "agent-owned weekly + monthly self-critique", "sections": [{ "heading": "## Weekly", "contains": "what worked, what slipped, improvements" }] }
+    { "path": "journal/agent.md", "purpose": "agent-owned weekly + monthly self-critique", "sections": [{ "heading": "## Weekly", "contains": "what worked, what slipped, improvements" }] }
   ]
 }

package/agent-assets/skills/docs-search/SKILL.md

@@ -16,7 +16,7 @@ other endpoint is in the allow-list.
 **Daemon URL is not optional.** Every call must go to
 `http://localhost:8321/api/docs/...`. The session's `curl` wrapper
 rejects any other host/port silently (stdout stays empty), so a request
-to `localhost:3000` or a path with no host returns nothing and reads as
+to `localhost:8322` or a path with no host returns nothing and reads as
 "0 results" — exactly the failure mode that masquerades as "the docs
 don't cover this".
 
@@ -31,22 +31,22 @@ the FTS query in three steps:
    | Input | Topic |
    |---|---|
    | "what is delegated mode?" | `delegated mode` |
-   | "delegatedモードとは何？" | `delegatedモード` |
+   | "什么是 delegated 模式？" | `delegated模式` |
    | "tell me about ProcessKey" | `ProcessKey` |
-   | "ProcessKeyについて教えて" | `ProcessKey` |
+   | "ProcessKey 是什么？" | `ProcessKey` |
    | "how does the morning routine work?" | `morning routine` |
-   | "朝のルーチンの動きは？" | `朝のルーチン` |
+   | "早晨例行公事是怎么运作的？" | `早晨例行公事` |
 
 2. **Split at script boundaries.** If the topic mixes Latin and CJK
    without spaces, insert a space at every Latin↔CJK boundary. FTS5
    quotes each whitespace-separated token as a phrase before
-   AND-joining; an unsplit `delegatedモード` becomes one unmatchable
+   AND-joining; an unsplit `delegated模式` becomes one unmatchable
    trigram phrase.
 
    | Input | Split |
    |---|---|
-   | `delegatedモード` | `delegated モード` |
-   | `ProcessKey一覧` | `ProcessKey 一覧` |
+   | `delegated模式` | `delegated 模式` |
+   | `ProcessKey列表` | `ProcessKey 列表` |
 
 3. **Latin wins.** If the split topic contains both Latin and CJK
    tokens, drop the CJK tokens. The corpus is English; CJK is the
@@ -56,9 +56,9 @@ the FTS query in three steps:
 
    | Input | Final query |
    |---|---|
-   | `delegated モード` | `delegated` |
-   | `ProcessKey 一覧` | `ProcessKey` |
-   | `朝のルーチン` | `朝のルーチン` (passes through; may miss) |
+   | `delegated 模式` | `delegated` |
+   | `ProcessKey 列表` | `ProcessKey` |
+   | `早晨例行公事` | `早晨例行公事` (passes through; may miss) |
 
 ## Endpoints
 
@@ -74,8 +74,9 @@ wrapper.
 | `curl -s "http://localhost:8321/api/docs"` | Tree listing. Use only when the operator asks "what docs are there?" |
 
 The slug in `by-slug/<slug>` is path-style (e.g.
-`features/routines/morning-routine`), exactly as it appears in the
-search response and inside `[doc:...]` citations.
+`features/routines/morning-routine`, a docs slug — not a vault path), <!-- drift-allow -->
+exactly as it appears in the search response and inside `[doc:...]`
+citations.
 
 ## Search-call budget — at most 3 per turn
 
@@ -113,14 +114,14 @@ Optional filters supported by both `term-search` and `search`:
 ## Worked example
 
 ```
-Operator: "delegatedモードとは何？"
+Operator: "什么是 delegated 模式？"
 
 Step 1 — extract topic:
-  Strip "とは何？" → "delegatedモード"
+  Strip "什么是 / ？" → "delegated模式"
 Step 2 — split scripts:
-  "delegatedモード" → "delegated モード"
+  "delegated模式" → "delegated 模式"
 Step 3 — Latin wins:
-  "delegated モード" → "delegated"
+  "delegated 模式" → "delegated"
 Step 4 — call:
   curl -s "http://localhost:8321/api/docs/term-search?q=delegated&limit=5"
 Top hit:

package/agent-assets/skills/external-services/SKILL.delegated.claude.md

@@ -1,9 +1,8 @@
 ---
 name: external-services
-description: Load when the task involves Google Calendar, the user's external Obsidian vault, GitHub, or Skills management AND Google Calendar is in cross-backend delegated mode (DM session on Claude Code, Calendar delegated to a different backend's connector). Calendar calls flow through `POST /api/integrations/google_calendar/exec`; the rest of the surface (Obsidian, GitHub, recurring schedules, one-shot scheduling, skills CRUD) is unchanged from the direct-mode body.
+description: Load when the task touches Google Calendar, Obsidian, GitHub, or Skills CRUD AND Google Calendar is cross-backend delegated from a Claude DM session. Calendar calls route through `POST /api/integrations/google_calendar/exec`; other surfaces keep their direct routes.
 allowed-tools:
   - Bash(curl *)
-  - Bash(jq *)
   - Read
 ---
 
@@ -22,8 +21,7 @@ Claude in this session).
 
 The rest of this skill — Obsidian, GitHub, recurring schedules, one-shot
 scheduling, skills CRUD — works identically to the direct-mode body.
-Refer to that body for those services; **only the Calendar section
-below changes** under cross-backend delegation.
+Refer to that body for those services; **only the Calendar section below changes** under cross-backend delegation.
 
 To check which backend currently owns the Calendar connector, read
 `~/.personal-agent/integrations.md`. The `/exec` body below is
@@ -214,7 +212,7 @@ carries the connector's own language.
 **Scope**: this skill targets a **separate** Obsidian vault the user
 maintains alongside this app — e.g. a personal knowledge base. It is
 **not** the agent's own primary management store. The agent's primary
-files (`today.md`, `roadmap.md`, `projects/`, `rules/`, `routines/`,
+files (`state/today.md`, `plans/roadmap.md`, `projects/`, `rules/`, `routines/`,
 `user/`, `agent/`, …) live in the primary vault and are reached via
 `/api/context/*` (see the `context` skill). **Never** use this skill to
 read or write the primary vault.
@@ -259,10 +257,10 @@ skill and the `/api/context/*` endpoints instead.
 
 ```bash
 curl -s http://localhost:8321/api/github/repos                              # list watched repos
-curl -s "http://localhost:8321/api/github/pulls?state=open"                  # list PRs
+curl -s "http://localhost:8321/api/github/pulls?owner=user&repo=repo&state=open" # list PRs
 curl -s -X POST http://localhost:8321/api/github/pulls/comment \
   -H 'Content-Type: application/json' \
-  -d '{"owner": "user", "repo": "repo", "pullNumber": 42, "body": "LGTM"}' # comment — Autonomous
+  -d '{"owner": "user", "repo": "repo", "pull_number": 42, "comment": "LGTM"}' # comment — Autonomous
 ```
 <!-- /service:github -->
 
@@ -278,23 +276,13 @@ update, archive).
 
 ---
 
-## Recurring Schedules
+## Recurring tasks
 
-CRUD for repeating agent tasks. Timezone auto-filled from daemon config.
-
-```bash
-curl -s -X POST http://localhost:8321/api/recurring-schedules \
-  -H 'Content-Type: application/json' \
-  -d '{"taskType": "wake", "description": "Morning inbox triage.", "recurrenceRule": {"frequency": "daily", "time": "09:00"}}'
-curl -s "http://localhost:8321/api/recurring-schedules?enabled=true"         # list
-curl -s -X PATCH http://localhost:8321/api/recurring-schedules/1 \
-  -H 'Content-Type: application/json' \
-  -d '{"recurrenceRule": {"frequency": "weekly", "time": "10:00", "daysOfWeek": [1,3,5]}}'
-curl -s -X PATCH http://localhost:8321/api/recurring-schedules/1 \
-  -H 'Content-Type: application/json' -d '{"enabled": false}'              # disable
-curl -s -X DELETE http://localhost:8321/api/recurring-schedules/1           # delete
-```
-`recurrenceRule`: `frequency` (daily/weekly/monthly), `time` (HH:MM), `daysOfWeek` (0=Sun..6=Sat, weekly), `daysOfMonth` (1-31, monthly). → Full guide: load `schedule` skill.
+Recurring autonomous **work** (fetch / check / act on a cadence) is an **Agent** —
+create one with the `agent-create` skill (`POST /api/agents`), managed on `/agents`.
+Recurring scheduled **DMs / briefings** stay on `POST /api/recurring-schedules`
+with `taskType: "dm_session"`. `GET /api/recurring-schedules?enabled=true` lists
+existing rows (dedup). → Full guide: load the `agent-create` or `schedule` skill.
 
 ---
 
@@ -332,9 +320,9 @@ curl -s -X POST http://localhost:8321/api/schedule/dm \
 ```bash
 curl -s -X POST http://localhost:8321/api/schedule \
   -H 'Content-Type: application/json' \
-  -d '{"time": "2026-04-06T16:00:00-04:00", "taskType": "wake", "description": "Check PR #42 status and notify user.", "model": "sonnet", "taskContext": {"scheduledBy": "dm_conversation"}}'
+  -d '{"time": "2026-04-06T16:00:00-04:00", "taskType": "wake", "prompt": "Check PR #42 status and notify user.", "description": "PR #42 status check", "tier": "medium", "taskContext": {"scheduledBy": "dm_conversation"}}'
 ```
-Fields: `time` (required), `taskType` (`wake`), `description` (required, min 20 chars), `model` (optional), `taskContext` (optional metadata).
+Fields: `time` (required), `taskType` (`wake`), `prompt` (required — the agent instruction, ≤8000 chars), `description` (optional label, ≤200 chars), `tier` (`lite`/`medium`/`high`) **or** `model` (registered id like `claude-opus-4-8`, legacy alias `sonnet`/`opus`, or composite `<backendId>/<modelId>`) — mutually exclusive, `taskContext` (optional metadata). See the `schedule` skill body for the full surface and `/api/schedule/options` for the live model list.
 
 ### Manage pending items
 ```bash
@@ -343,7 +331,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"}'   # edit
 curl -s -X DELETE http://localhost:8321/api/schedule/42                              # cancel
 ```
-Editable: `time`, `description`, `message` (dm only), `model`, `taskContext`. Only `pending` items.
+Editable: `time`, `description`, `message` (dm only), `tier` (or `model`, mutually exclusive — pass `null` to clear), `taskContext`. Only `pending` items.
 
 ### Time discipline
 - Absolute ISO 8601 with offset required — no relative times.