@aitne-sh/aitne 0.1.9 → 0.1.10

package/agent-assets/skills/managed-tasks/SKILL.md

@@ -123,35 +123,18 @@ a paraphrase. The user is the one who can fix auth / quota / install.
 
 ### Step 4a — Decide `output_path` (LLM judgment)
 
-From the probe sample, infer the primary L2 directory the recurring
-fetch will write into. Bias toward existing matches:
-
-1. If the entity-mirror already holds entities with `sources.<app>.*`
-   under one `<domain>/<type-plural>/`, reuse that path:
-   ```bash
-   curl -s "http://localhost:8321/api/entities?source=<app>&limit=5" | jq .
-   ```
-   Each item's `path` (`<domain>/<type-plural>/<slug>.md`) reveals
-   where that source already lives. If 1+ rows agree on
-   `<domain>/<type>`, that path wins.
-2. Otherwise, pick the `(domain, type)` pair whose semantic prior
-   best fits the data shape:
-
-   | Probe sample shape | Likely `<domain>/<type-plural>/` |
-   |---|---|
-   | Recording with attendees + duration | `work/meetings/` |
-   | PDF / image with monetary amount | `finance/receipts/` |
-   | Travel itinerary / booking | `travel/trips/` |
-   | Long-form note / article | `<domain>/notes/` (pick by content topic) |
-   | Book metadata / progress | `learning/books/` |
-
-3. If the data shape is genuinely ambiguous (zero rows), set
-   `output_path: null` — the first scheduled run will populate it
-   from real data.
-
-The full `output_path` grammar (allowed domain / type values,
-trailing-slash rule, `..` rejection, 422 envelope) is in the
-reference below.
+Infer the primary L2 directory the recurring fetch will write into:
+
+1. Reuse an existing path if the source already lives somewhere —
+   `curl -s "http://localhost:8321/api/entities?source=<app>&limit=5" | jq -r '.items[].path'`;
+   if 1+ rows agree on `<domain>/<type-plural>`, that path wins.
+2. Else pick by the probe sample's data shape (mapping table in the
+   reference below).
+3. Else omit the field (`output_path: null`) — the first scheduled run
+   back-fills it.
+
+The full grammar (allowed domain / type values, trailing-slash rule,
+`..` rejection, 400 rejection shape, data-shape mapping) is below.
 
 {{> ref:output-path }}
 
@@ -206,15 +189,10 @@ cadence)` collides at the uniqueness check and returns `409
 duplicate` with the existing `mt_id` — DM the user pointing at it
 instead of registering twice.
 
-**Server-side transaction (atomic)**: the daemon allocates the next
-`mt_<n>` from `managed_task_seq`, INSERTs `recurring_schedules` and
-`managed_tasks` linked by FK, and writes one `agent_actions` row
-(`action_type='management_task.created'`). On any DB failure the
-transaction rolls back and you get a 5xx — surface the body verbatim.
-
-**File render**: post-transaction the daemon re-renders
-`policies/management.md` from DB (locked, snapshotted into
-`md_file_snapshots`). You do NOT touch the file.
+**Server-side**: the daemon runs the atomic tx (allocate `mt_<n>`,
+INSERT the FK-linked `recurring_schedules` + `managed_tasks`, audit),
+re-renders `policies/management.md`, and snapshots it — you do not
+touch the file. On a DB failure you get a 5xx; surface the body.
 
 ### Step 7 — Confirm to user
 
@@ -305,10 +283,8 @@ rename has its own dedicated route
 disambiguator already routes app-change requests to "stop + re-register"
 for safety.
 
-Server-side transaction: UPDATE `recurring_schedules` (if
-`recurrenceRule` changed) → UPDATE `managed_tasks` → re-render
-`policies/management.md` → INSERT one `agent_actions` row
-(`action_type='management_task.modified', detail={changed, from, to}`).
+**Server-side**: the daemon runs the atomic tx + re-renders the file
++ audits — you do not touch the file.
 
 `mt_id`, `last_run_at`, `last_result`, and `consecutive_failures`
 are preserved across PATCH — history is continuous. A cadence change
@@ -374,16 +350,13 @@ so they can make an informed call.
 curl -sS -X DELETE http://localhost:8321/api/managed-tasks/mt_42
 ```
 
-Server-side transaction (atomic): snapshot the row's full state into
-`agent_actions.detail` → DELETE `managed_tasks` (cascades to
-`recurring_schedules` via FK) → cancel pending `agent_schedule`
-rows → re-render `policies/management.md` → INSERT one `agent_actions`
-row (`action_type='management_task.deleted'`).
+**Server-side**: the daemon runs the atomic tx (snapshot the row,
+DELETE `managed_tasks` cascading to `recurring_schedules`, cancel
+pending fires, audit) + re-renders the file — you do not touch it.
 
-The pre-delete row snapshot in `agent_actions`
-(`detail.original_row`) plus the file snapshot in
-`md_file_snapshots` is the recovery surface — surface it in
-audit / debug contexts only, never in the user-facing DM.
+The pre-delete row snapshot (`agent_actions.detail.original_row`)
+plus the `md_file_snapshots` row is the recovery surface — for
+audit / debug only, never the user-facing DM.
 
 ### Step 4 — Confirm to user
 
@@ -407,11 +380,11 @@ modifying the schedule:
 curl -sS -X POST http://localhost:8321/api/managed-tasks/mt_42/run-now
 ```
 
-The route is implemented at `packages/daemon/src/api/routes/managed-tasks.ts:875`.
-The dispatcher enqueues a one-shot fire that runs the same task-flow
-as a scheduled fire would; the next regular firing is unaffected.
-`409 already_running` means a previous fire is still in flight — do
-not loop.
+Success is `202 {status:"queued", mt_id, scheduled_row_id}` — the
+route enqueues a one-shot `agent_schedule` row that runs the same
+task-flow as a scheduled fire; the next regular firing is unaffected.
+There is no in-flight guard, so the fire always enqueues — do not
+fire it in a loop yourself.
 
 Confirm to user with one DM after the fire enqueues:
 
@@ -422,10 +395,10 @@ Confirm to user with one DM after the fire enqueues:
 
 ## Error envelope
 
-The standard daemon error shape applies to every `/api/managed-tasks`
-call. Verbs (POST / PATCH / DELETE / run-now), codes
-(`validation_error`, `duplicate`, `cap_reached`, `invalid_id`,
-`not_found`, `already_running`, `internal_error`), and the
+Every error is the daemon envelope
+(`{ok:false, summary, errors:[…], retryable, error?}`). Verbs (POST /
+PATCH / DELETE / run-now), codes (`validation_error`, `duplicate`,
+`cap_reached`, `invalid_id`, `not_found`, `internal_error`), and the
 Idempotency-Key contract are in the errors reference below.
 
 {{> ref:errors }}
@@ -434,26 +407,20 @@ Idempotency-Key contract are in the errors reference below.
 
 ## What this skill does NOT do
 
-- Does NOT hardcode connector tool names — all tool selection is
-  LLM-judged.
-- Does NOT PUT `policies/management.md` directly — the daemon owns the
-  write. The only legal write is the `/api/managed-tasks` chokepoint.
-- Does NOT INSERT `recurring_schedules` directly. POST
-  `/api/managed-tasks` keeps the FK pair consistent.
-- Does NOT pause / disable a task — there is no soft-pause; stop +
-  re-register if the user wants a hiatus.
-- Does NOT mutate `app` through PATCH — that is a different
-  commitment, stop + re-register.
-- Does NOT touch §A (SoT bindings) — use `PUT /api/sot-bindings`.
-  Does NOT touch §C (Active Policies) — owned by `management-policy`.
+- Does NOT PUT `policies/management.md` (or INSERT `recurring_schedules`)
+  directly — the only legal write is the `/api/managed-tasks` chokepoint;
+  the daemon owns the file write and the FK pair.
+- Does NOT mutate `app` through PATCH — a different connector is a
+  different commitment; stop + re-register.
 - Does NOT silently re-register on retry — use `Idempotency-Key`
   per-DM; conflicts surface the existing `mt_id`.
-- Does NOT register a task that has no probe-passing connector.
-  Probe failure is a hard stop.
-- Does NOT delete entity files produced by past runs on stop.
-- Does NOT regenerate `state/activity/<source>.md`. The reconciler does.
+- Does NOT register a task with no probe-passing connector — probe
+  failure is a hard stop.
+- Does NOT delete entity files produced by past runs on stop — those
+  stay where written; the DELETE only removes the row + its recurring
+  schedule.
 - Does NOT bulk-stop without per-row confirmation. "Stop all gmail
-  tasks" is a series of DM round-trips, one per row.
+  tasks" is one DM round-trip per row.
 
 ## API surface
 

package/agent-assets/skills/managed-tasks/references/errors.md

@@ -1,24 +1,32 @@
 ---
 kind: reference
 name: errors
-description: /api/managed-tasks error envelope — POST / PATCH / DELETE codes (validation_error, duplicate, cap_reached, invalid_id, not_found, internal_error).
+description: /api/managed-tasks error envelope — {ok:false, summary, errors[], retryable} plus POST / PATCH / DELETE codes (validation_error, duplicate, cap_reached, invalid_id, not_found, internal_error).
 ---
 
 # /api/managed-tasks error envelope
 
-Every endpoint returns the standard daemon error shape:
+Every error response is the standard daemon envelope:
 
 ```jsonc
 {
-  "error":   "<machine code>",
-  "message": "<human text — surface verbatim to the user>",
-  "details": [ /* Zod issue list when error === "validation_error" */ ],
-  "item":    { /* present on 409 duplicate — the existing row */ }
+  "ok":        false,
+  "summary":   "<one-line human text — surface verbatim>",
+  "errors":    [ { "code": "managed_tasks.validation_error", "field": "body", "hint": "..." } ],
+  "retryable": false,
+  "error":     "<legacy machine-code alias — present on single-issue envelopes>"
 }
 ```
 
-`body.message` is intended for the user — preserve it verbatim. The
-daemon does NOT emit `cron_too_tight`. Note: the recurrence schema
+`summary`, `errors[]`, and `retryable` are ALWAYS present. Each
+`errors[]` issue carries `code` / `field` / `hint`. The top-level
+`error` is a legacy alias for the single issue's code. Legacy aliases
+appear only on specific codes: `item` (the existing row) on `409
+duplicate`, `message` on duplicate / cap, and `details` (the raw
+ZodError) on `validation_error`. Per-verb tables below name the issue
+`code`; surface `body.summary` or the issue `hint`, not a paraphrase.
+
+The daemon does NOT emit `cron_too_tight`. Note: the recurrence schema
 DOES accept `hourly` (the engine supports `hourly`/`daily`/`weekly`/
 `monthly`), so a sub-daily POST is NOT rejected server-side — it
 succeeds (201). The daily-or-coarser floor for managed tasks is a
@@ -32,7 +40,7 @@ structured field, so there is no partial-cadence shape to reject).
 
 | HTTP | `error` | When | What to do |
 |---|---|---|---|
-| 400 | `validation_error` | Body fails Zod (frequency unknown, time malformed, etc.) | Pick the offending field from `details[].path` and ask the user to clarify. |
+| 400 | `validation_error` | Body fails Zod (frequency unknown, time malformed, etc.) | Pick the offending field from `body.summary` / the issue `hint` (`details` is a serialized ZodError object, not an array) and ask the user to clarify. |
 | 409 | `duplicate` | An existing row has the same `(app_normalized, cadence)` | DM `Already managed as <body.item.id>` and stop. The body's `item` is the existing row. |
 | 409 | `cap_reached` | §B already at the active-task cap (default 100) | Surface `body.message` (carries the cap value); user must stop something first. |
 | 5xx | `internal_error` | DB / cascade failure | DM "Couldn't register; daemon error. Try again, or check `aitne logs`." |
@@ -42,9 +50,9 @@ structured field, so there is no partial-cadence shape to reject).
 | HTTP | `error` | When | What to do |
 |---|---|---|---|
 | 400 | `invalid_id` | `:id` didn't match `^mt_[1-9]\d*$` | User typed the id wrong — ask them to repeat. |
-| 400 | `validation_error` | Body fails Zod (empty body, recurrenceRule.daysOfWeek on a `daily`, etc.) | Pin the failing path from `details[].path` and ask for a fix. |
+| 400 | `validation_error` | Body fails Zod (empty body, recurrenceRule.daysOfWeek on a `daily`, etc.) | Pin the failing field from `body.summary` / the issue `hint` (`details` is a serialized ZodError object, not an array) and ask for a fix. |
 | 404 | `not_found` | No row for `:id` | DM "I don't have an `mt_<id>` to modify"; offer to register one. |
-| 5xx | `internal_error` | DB / cascade failure | Surface `body.message`; advise `aitne logs`. |
+| 5xx | `internal_error` | DB / cascade failure | Surface `body.summary`; advise `aitne logs`. |
 
 ## DELETE /api/managed-tasks/:id
 
@@ -52,16 +60,19 @@ structured field, so there is no partial-cadence shape to reject).
 |---|---|---|---|
 | 400 | `invalid_id` | `:id` didn't match `^mt_[1-9]\d*$` | Ask the user to repeat. |
 | 404 | `not_found` | No row for `:id` | DM "No managed task with that id"; if you used a fuzzy match, re-list candidates. |
-| 5xx | `internal_error` | DB / cascade failure | Surface `body.message`; advise `aitne logs`. |
+| 5xx | `internal_error` | DB / cascade failure | Surface `body.summary`; advise `aitne logs`. |
 
 ## POST /api/managed-tasks/:id/run-now
 
+Success is `202 {status:"queued", mt_id, scheduled_row_id}` — the
+route has no concurrency guard, so a fire enqueues unconditionally
+(there is no `already_running` code). Errors:
+
 | HTTP | `error` | When | What to do |
 |---|---|---|---|
 | 400 | `invalid_id` | `:id` didn't match `^mt_[1-9]\d*$` | Ask the user to repeat. |
 | 404 | `not_found` | No row for `:id` | Cannot run a stopped task. |
-| 409 | `already_running` | A previous fire is still in flight | Tell the user; do NOT loop. |
-| 5xx | `internal_error` | Dispatcher / cascade failure | Surface `body.message`. |
+| 5xx | `internal_error` | Dispatcher / cascade failure | Surface the issue `hint`. |
 
 ## Idempotency on POST
 

package/agent-assets/skills/managed-tasks/references/output-path.md

@@ -8,8 +8,10 @@ description: output_path grammar — `<domain>/<type-plural>/` only, trailing sl
 
 The `output_path` field on `/api/managed-tasks` is the L2 directory
 under the primary context vault where the recurring fetch will write
-entity files. The daemon enforces the format with a CHECK constraint
-at INSERT / UPDATE time.
+entity files. The full grammar (domain/type enum, two segments, no
+`..`) is enforced by a Zod `.refine` PRE-insert, so a bad value is
+rejected with **HTTP 400**. The SQL CHECK constraint only guarantees
+the trailing slash (`output_path LIKE '%/'`).
 
 ## Format
 
@@ -28,9 +30,24 @@ at INSERT / UPDATE time.
 | `<type-plural>` | `meetings`, `trips`, `receipts`, `projects`, `books`, `notes` |
 
 Not every domain × type combination is meaningful in practice — pick
-the pair whose semantic prior best fits the fetch's data shape (see
-the §"Decide output path" table in the Register section of the skill
-body for the typical mapping).
+the pair whose semantic prior best fits the fetch's data shape.
+
+## Data shape → path mapping
+
+When no existing entity path is found for the source (see Register
+Step 4a), pick the `(domain, type)` pair whose semantic prior best
+fits the probe sample:
+
+| Probe sample shape | Likely `<domain>/<type-plural>/` |
+|---|---|
+| Recording with attendees + duration | `work/meetings/` |
+| PDF / image with monetary amount | `finance/receipts/` |
+| Travel itinerary / booking | `travel/trips/` |
+| Long-form note / article | `<domain>/notes/` (pick by content topic) |
+| Book metadata / progress | `learning/books/` |
+
+If the data shape is genuinely ambiguous (zero rows), omit the field
+(`output_path: null`) — the first scheduled run populates it.
 
 ## Examples
 
@@ -61,15 +78,14 @@ re-register.
 To clear an existing `output_path` back to "first run decides", send
 `{"output_path": null}` in the PATCH.
 
-## 422 envelope on rejection
-
-```json
-{
-  "error": "validation_error",
-  "message": "output_path 'work/meetings' is missing the trailing slash",
-  "field": "output_path"
-}
-```
-
-Surface the daemon's `message` verbatim — it names the exact rule
-that failed. Do not retry the same value.
+## Rejection
+
+A bad `output_path` fails Zod and the route returns **HTTP 400** with
+the generic `managed_tasks.validation_error` issue — there is no
+top-level `field` and no per-`output_path` `message`. The raw
+ZodError lives under `legacyFields.details`, but it is a serialized
+ZodError object (`{name:"ZodError", message:"<stringified issues>"}`),
+NOT an array — there is no `details[].path` to read. The offending
+field (`output_path`) is named in `body.summary` and the issue `hint`;
+the raw issues are inside the stringified `details.message`. Surface
+`body.summary` or the issue `hint`. Do not retry the same value.

package/agent-assets/skills/managed-tasks/references/recurrence-rule.md

@@ -8,10 +8,12 @@ description: recurrenceRule grammar — hourly / daily / weekly / monthly. Engin
 
 The daemon's recurrence engine accepts four frequencies: `hourly`,
 `daily`, `weekly`, `monthly`. Each frequency requires its own set of
-fields and rejects fields that don't apply — the daemon's Zod
-refinements return a `schedule.frequency_field_mismatch` issue (with
-the offending field path) when the shape disagrees with the chosen
-frequency. Pre-validate to save a round-trip.
+fields and rejects fields that don't apply — the daemon rejects a
+mismatched shape with an HTTP 400 validation error naming the
+frequency/field conflict. The recurring-schedules endpoint (the
+`schedule` skill) surfaces it as a `schedule.frequency_field_mismatch`
+issue with a field path; the managed-tasks endpoint surfaces it as a
+`managed_tasks.validation_error`. Pre-validate to save a round-trip.
 
 Times are `HH:MM` 24-hour local; `timezone` is IANA (auto-fills from
 daemon config when omitted, but explicit is safer so a roaming laptop

package/agent-assets/skills/management-policy/SKILL.md

@@ -69,8 +69,8 @@ curl -s "http://localhost:8321/api/context/list/policies"
 ```
 
 If the listing and `_index.md` rows disagree, **prefer the listing**
-and trust the next reconcile pass to refresh the index. Do **not**
-hand-PATCH `_index.md` to fix the drift — that just creates more churn.
+and trust the next reconcile pass to refresh the index (`_index.md` is
+reconciler-owned — see body intro).
 
 ### Step 2 — Detect similarity
 
@@ -156,9 +156,8 @@ the active policies first and ask.
    frontmatter `enabled: false`, PUT back. The reload hook flips the
    cron job off automatically.
 
-The policy-index reconciler picks the change up on the FS event and
-re-renders both `_index.md` and the management.md section within
-~10 s. Do not PATCH them manually.
+The policy-index reconciler re-renders both `_index.md` and the
+management.md section within ~10 s (reconciler-owned — see body intro).
 
 If step 2 fails after step 1 succeeded, **attempt to roll back step 1**
 (`status` back to `active`). If the rollback itself fails, report the
@@ -190,8 +189,6 @@ is intentionally not whitelisted (see MANAGEMENT-POLICY-CAPTURE-PLAN
 - Does NOT create rows in the `recurring_schedules` DB table — defer to
   `policies/routines/custom/` for cron, which gives the user a visible MD file
   to edit.
-- Does NOT migrate existing custom routines into policy files
-  retroactively. Migration is a separate one-time operation.
 
 ## Cross-skill pointers
 
@@ -223,11 +220,13 @@ skill targets these paths:
 - `DELETE /api/context/policies/routines/custom/<slug>` (remove only)
 
 `policies/management-captures/_index.md` and the `## Active Policies` section in
-`policies/management.md` are written by the daemon's policy-index
-reconciler — they are NOT in the agent's write surface for this skill.
+`policies/management.md` are reconciler-owned (see body intro) — NOT in
+the agent's write surface for this skill.
 
-Frontmatter validation enforces `kind: policy`, `owner: agent`, and
-the slug rules in Step 4. Malformed writes return 422 with the failing
+Frontmatter validation enforces `type: rule`, `kind: policy`,
+`owner: agent`, `status`, `created_at` (YYYY-MM-DD), `origin`,
+`updated` (ISO), an H1, and the slug rules in Step 4 — see 5.3 for the
+full required set. Malformed writes return 422 with the failing
 field — surface that text to the user verbatim rather than retrying
 blindly.
 

package/agent-assets/skills/management-policy/references/policy-workflow.md

@@ -76,11 +76,10 @@ reconciler can resolve them.
 
 ## 5.4 _(no manual step required)_
 
-`policies/management-captures/_index.md` is auto-maintained by the daemon's
-policy-index reconciler — it re-renders within ~10 s of step 5.3's
-write. Same for the `## Active Policies` section in
-`policies/management.md`. **Do not PATCH or PUT either path manually**;
-doing so just races the reconciler and creates snapshot churn.
+Both `policies/management-captures/_index.md` and the `## Active Policies`
+section in `policies/management.md` are reconciler-owned and re-render
+within ~10 s of step 5.3's write (see SKILL.md body intro — no manual
+PATCH/PUT).
 
 If you need to confirm the index is up to date before replying to the
 user, GET `policies/management-captures/_index` after a short wait. The

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

@@ -41,10 +41,9 @@ language-agnostic** — it applies whatever language the agent uses
 with the user.
 
 Anti-examples (non-exhaustive — the positive rule above is
-load-bearing, not this list): "Good morning!", "Evening check-in —",
-"Morning briefing —", "Summary:", "Done.", "Sent.", "OK.", "Here's
-your day:", "Heads-up —", "FYI:", "Quick update:". Near-synonyms of
-these in any language also fail the positive rule.
+load-bearing, not this list): "Good morning!", "Summary:", "Done.",
+"Heads-up —". Near-synonyms of these in any language also fail the
+positive rule.
 
 ### No internal mechanism names
 
@@ -56,9 +55,8 @@ user-visible text. Those go in Agent Log only.
 
 ### No filler timing commentary
 
-Forbidden — "Just a heads-up", "Still about N hours to go", "About N
-hours left", "FYI". If timing matters, the deadline / event time
-itself carries it.
+Forbidden — "Just a heads-up", "About N hours left", "FYI". If timing
+matters, the deadline / event time itself carries it.
 
 ### No table-of-contents readback
 
@@ -96,16 +94,16 @@ Notify when **all three** are true: (1) **actionable** or requires awareness, (2
 - **A pending Agent Plan row / scheduled DM is already set to fire
   for this item within the next 2 hours** — let the planned channel
   deliver; don't pre-empt it.
-- **Quiet hours (default 22:00-08:00, configurable)** unless `critical` — schedule for after instead
-- **Over the rate-limit caps (3/hour, 12/day; `critical` bypasses both)** — do NOT spam-retry. The endpoint does NOT signal this: `/api/notify` returns `200 {status:"sent"}` even when quiet-hours or the rate-limit silently drops the message, so a `"sent"` response is not proof of delivery. Self-throttle by checking `<today>` `## Agent Log` before firing; if you suspect suppression, log the skip rather than re-posting. If time-critical, upgrade priority at next opportunity
+- **Already delivered this item** — `/api/notify` sends immediately and a `200 {status:"sent"}` is proof of delivery, so do NOT re-post on a 200. Self-throttle via `<today>` `## Agent Log` before firing and log the skip rather than re-posting. (No endpoint quiet-hours or rate cap gates this for you — noise control is your job.)
 - **Routine file changes** or **agent internal state** — use Agent Log instead
 - **When in doubt — prefer silence**
 
 ## Priority
 
 **Default to `normal`.** Reserve `high` for 8h-delay-matters. Reserve
-`critical` for 3am-matters. Full per-level table, examples, and
-rate-limit caps are in the priority reference below.
+`critical` for 3am-matters. `priority` is metadata recorded in the
+notification log — it does not gate delivery on this endpoint. Full
+per-level table and examples are in the priority reference below.
 
 {{> ref:priority }}
 
@@ -120,5 +118,5 @@ curl -s -X POST http://localhost:8321/api/notify \
   -H 'Content-Type: application/json' \
   -d '{"message": "Design review starts in 15 minutes.", "priority": "normal"}'
 ```
-Fields: `message` (required, markdown), `priority` (optional: critical/high/normal/low), `platform` (optional, override target).
-Response: `{ "status": "sent", "notificationId": "..." }`. Risk tier: `Autonomous` — the agent decides when to notify; recorded in `notification_log` for the on-demand retrospective.
+Fields: `message` (required, markdown), `priority` (optional: critical/high/normal/low), `platform` (optional, override target) OR `platforms` (optional, array of targets) — mutually exclusive, not both.
+Response: `200 { "status": "sent", "notificationId": "...", "dispatchId": "..." }` = delivered to ≥1 channel; a total delivery failure returns HTTP 500 (not a silent 200-drop). Risk tier: `Autonomous` — the agent decides when to notify; recorded in `notification_log` for the on-demand retrospective.

package/agent-assets/skills/notify/references/priority.md

@@ -1,20 +1,24 @@
 ---
 kind: reference
 name: priority
-description: Notification priority levels — critical / high / normal / low — with quiet-hours behavior and per-level examples.
+description: Notification priority levels — critical / high / normal / low — as metadata you set, with per-level usage examples.
 ---
 
 # Notification priority levels
 
-Pick the lowest priority that still preserves the user-visible
-behavior the message needs. **Default to `normal`.**
+`priority` is a metadata field you set on the `/api/notify` call. It
+travels into `notification_log` and helps the user (and the
+retrospective) gauge how urgent each message was. It does NOT gate
+delivery on this endpoint — `/api/notify` sends immediately regardless
+of level. Pick the lowest priority that still honestly describes the
+message. **Default to `normal`.**
 
-| Priority | Quiet-hours | Use for |
-|---|---|---|
-| `critical` | Bypasses | Security alerts (credential leak, account lockout), data-loss risk (about to overwrite without backup, irreversible deletion in flight), system errors blocking the user from working. Wakes the user. |
-| `high` | Bypasses | Hard deadlines firing in the next 8 hours, urgent inbound messages from people the user has flagged as priority, "meeting starting now". User wants to see this even during quiet hours but not at 3 am. |
-| `normal` | Respects (dropped during quiet hours) | Regular reminders (`15 min until standup`), digest-style summaries, single-recipient FYIs the user opted into. **Default.** |
-| `low` | Respects (dropped during quiet hours) | Background updates, observational FYIs the user did not explicitly ask for, optional context. Often better as an Agent Log entry instead of a notification at all. |
+| Priority | Use for |
+|---|---|
+| `critical` | Security alerts (credential leak, account lockout), data-loss risk (about to overwrite without backup, irreversible deletion in flight), system errors blocking the user from working. The "wake the user at 3 am" tier. |
+| `high` | Hard deadlines firing in the next 8 hours, urgent inbound messages from people the user has flagged as priority, "meeting starting now". Important but not 3 am. |
+| `normal` | Regular reminders (`15 min until standup`), digest-style summaries, single-recipient FYIs the user opted into. **Default.** |
+| `low` | Background updates, observational FYIs the user did not explicitly ask for, optional context. Often better as an Agent Log entry instead of a notification at all. |
 
 ## Examples by level
 
@@ -47,19 +51,18 @@ If the next morning would still be soon enough, it is not `high`.
 If the user did not opt in to receiving this category of update, do not
 send `low`. Drop it to an Agent Log entry instead.
 
-## Rate-limit defaults
-
-3/hour, 12/day across all priorities (`critical` bypasses both caps).
-The agent CANNOT query `notification_log` directly (Approve-tier). Use
-`<today>` `## Agent Log` as the authoritative dedup source (look for
-`notify sent` / `DM sent` lines).
-
-`/api/notify` does NOT report rate-limit or quiet-hours suppression
-back to you — it returns `200 {status:"sent"}` even when the message is
-silently dropped inside the delivery layer. A `"sent"` response is
-therefore not proof the user saw it. Do NOT re-post the same item
-hoping for delivery; self-throttle by scanning `<today>` `## Agent Log`
-first and log `notify skipped (rate_limited)` when you choose to hold.
-If the message is time-critical and the next opportunity arises,
-upgrade to `high` (or `critical` if the situation has escalated)
-rather than re-sending at the same level.
+## Delivery semantics
+
+`/api/notify` delivers immediately — there is no quiet-hours gate, no
+per-priority suppression, and no rate cap on this endpoint. A `200
+{status:"sent"}` means the message was delivered to at least one
+channel; a total delivery failure THROWS and surfaces as HTTP 500 (not
+a silent 200-drop). So `"sent"` IS proof of delivery — do NOT re-post
+the same item on a 200.
+
+Noise control is YOUR job, not the endpoint's. The agent CANNOT query
+`notification_log` directly (Approve-tier), so use `<today>` `## Agent
+Log` as the authoritative dedup source (look for `notify sent` / `DM
+sent` lines) and self-throttle before firing. Don't re-send the same
+item at the same level; if the situation has genuinely escalated, raise
+the priority metadata to reflect that.

package/agent-assets/skills/notion/SKILL.delegated.claude.md

@@ -29,7 +29,7 @@ delegated mode:
 
 ```bash
 curl -s http://localhost:8321/api/notion/databases
-# → { databases: { "<label>": { "id": "<uuid>", "title": "..." }, ... } }
+# → { databases: [ { "label": "<label>", "id": "<uuid>" }, ... ] }
 ```
 
 Resolve label → UUID here BEFORE the `/exec` call so your `task`

package/agent-assets/skills/notion/SKILL.delegated.codex.md

@@ -26,7 +26,7 @@ delegated mode:
 
 ```bash
 curl -sS http://localhost:8321/api/notion/databases
-# → { databases: { "<label>": { "id": "<uuid>", "title": "..." }, ... } }
+# → { databases: [ { "label": "<label>", "id": "<uuid>" }, ... ] }
 ```
 
 Resolve label → UUID here BEFORE the `/exec` call so your `task`

package/agent-assets/skills/notion/SKILL.delegated.gemini.md

@@ -26,7 +26,7 @@ delegated mode:
 
 ```bash
 curl -sS http://localhost:8321/api/notion/databases
-# → { databases: { "<label>": { "id": "<uuid>", "title": "..." }, ... } }
+# → { databases: [ { "label": "<label>", "id": "<uuid>" }, ... ] }
 ```
 
 Resolve label → UUID here BEFORE the `/exec` call so your `task`