@aitne-sh/aitne 0.1.9 → 0.1.11

package/agent-assets/docs/troubleshooting/morning-routine-didnt-run.md

@@ -13,7 +13,7 @@ summary: |
   Causes are ordered by frequency: daemon was stopped at the trigger
   time, both backends failed, quota exhausted, the routine threw and is
   mid-retry, or it is a day-boundary subtlety. Most cases self-heal via
-  boot-time catch-up or the retry/stall watchdog.
+  boot/wake catch-up, the missed-fire self-heal, or the retry chain.
 section: morning-routine-didnt-run
 tags:
   - troubleshooting
@@ -28,7 +28,7 @@ ask_examples:
   - How do I regenerate today.md by hand?
 locale: en-US
 created: 2026-04-25
-updated: 2026-05-28
+updated: 2026-06-10
 keywords:
   - morning routine didn't run
   - morning routine skipped
@@ -37,7 +37,7 @@ keywords:
   - regenerate today
 related:
   - features/routines/morning-routine
-  - features/routines/hourly-check
+  - features/routines/activity-scan
   - concepts/agent-day
   - troubleshooting/auth-failed
   - troubleshooting/quota-exhausted
@@ -52,7 +52,7 @@ config_keys:
 context_files:
   - state/today.md
 ui_anchors:
-  - /settings/routines
+  - /agents/morning-routine
   - /activity
 ---
 
@@ -66,26 +66,42 @@ ui_anchors:
 
 ## Before You Worry: It Often Self-Heals
 
-The morning routine has two recovery paths that usually fix this
+The morning routine has several recovery paths that usually fix this
 without any action from you:
 
 - **Boot-time catch-up.** If the daemon was stopped during the trigger
   window, it fires the unrun morning routine the next time it starts.
   So a missed routine often resolves itself on the next `aitne start`
   or `aitne restart`.
+- **Sleep wake catch-up.** If the machine was asleep at the trigger
+  minute (laptop lid closed at 04:00), the cron fire is silently lost —
+  cron never replays missed ticks. The daemon detects the wall-clock
+  gap when the machine wakes and queues the morning routine itself,
+  along with any missed evening/weekly reviews.
+- **Missed-fire self-heal.** A periodic check (every 10 minutes)
+  notices when the day is more than ~15 minutes old with no morning
+  attempt and nothing queued, and queues the routine. This covers
+  sleeps too short for the wake detector and any other lost trigger.
 - **Retry on failure.** If the routine runs but fails to produce a
   fresh `state/today.md`, the daemon retries up to 3 times with an
   exponential back-off (5, then 10, then 15 minutes). After 3 failed
-  attempts it sends you a DM asking you to regenerate manually. If the
-  wake row sits unfinished for ~2 hours (the stall watchdog threshold),
-  you also get an owner DM so the silence never goes unnoticed.
+  attempts it sends you a DM asking you to regenerate manually.
+- **Hung-run recovery.** If a run starts and then wedges (typically a
+  sleep mid-run that kills the backend connection), the self-heal
+  check re-queues it once the run has been silent past the stall
+  threshold (~2 hours by default) — at most twice per day, after which
+  it alerts instead of re-running. Either way you get an owner DM so
+  the silence never goes unnoticed.
 
 Give it a few minutes, or restart the daemon, before digging deeper.
 
 ## Most Likely Causes (in probability order)
 
-1. **Daemon was stopped at the trigger time.** Check `aitne status`.
-   Boot-time catch-up should cover this once the daemon is back up.
+1. **Daemon was stopped — or the machine was asleep — at the trigger
+   time.** Check `aitne status`. Boot-time catch-up covers the stopped
+   case once the daemon is back up; sleep wake catch-up and the
+   missed-fire self-heal cover the asleep case within minutes of the
+   machine waking.
 2. **Both backends failed.** The routine tried the main backend, fell
    back, and the fallback failed too. Check `/activity` for an error
    outcome and `aitne logs` for the failure.
@@ -99,9 +115,9 @@ Give it a few minutes, or restart the daemon, before digging deeper.
    the routine still "belongs to" yesterday — see
    [Agent Day](../concepts/agent-day.md).
 
-Note: the morning routine takes priority over the hourly check, not the
-other way around. The hourly check skips itself while the morning
-routine is active, so a running hourly check never blocks the morning
+Note: the morning routine takes priority over the activity scan, not the
+other way around. The activity scan skips itself while the morning
+routine is active, so a running activity scan never blocks the morning
 routine.
 
 ## Diagnostic Steps
@@ -109,8 +125,8 @@ routine.
 1. `aitne status` — is the daemon up?
 2. `/activity` — is there a row for `routine.morning_routine`? An error
    outcome points to a backend failure (cause 2 or 3).
-3. `/settings/routines` — the routine list shows the next scheduled
-   fire and recent runs.
+3. `/agents` — the morning-routine card shows its schedule, status,
+   and last run; open `/agents/morning-routine` for recent executions.
 4. `aitne logs` — search for `morning_routine` to see the trigger,
    any fallback, and retry scheduling.
 
@@ -136,5 +152,5 @@ synthesis immediately.
 ## Related
 
 - [Morning Routine](../features/routines/morning-routine.md)
-- [Hourly Check](../features/routines/hourly-check.md)
+- [Activity Scan](../features/routines/activity-scan.md)
 - [Agent Day](../concepts/agent-day.md)

package/agent-assets/docs/troubleshooting/observation-not-detected.md

@@ -7,47 +7,47 @@ aliases:
   - observation missing
   - no observations
   - polling broken
-  - hourly check empty
+  - activity scan empty
 category: troubleshooting
 summary: |
   An expected change (commit, note, calendar move) didn't surface in
-  the hourly check. Most often a polling delay, a vault/repo not
+  the activity scan. Most often a polling delay, a vault/repo not
   watched, or a change the agent authored itself (filtered out).
 section: troubleshooting
 tags:
   - troubleshooting
   - observations
   - polling
-  - hourly-check
+  - activity-scan
 status: stable
 ask_examples:
   - Why didn't the agent notice my new commit?
   - Why didn't a calendar change show up?
-  - Why is the hourly check empty?
+  - Why is the activity scan empty?
 locale: en-US
 created: 2026-04-25
-updated: 2026-05-28
+updated: 2026-06-10
 keywords:
   - observation
   - polling
   - observer
   - AgentWriteTracker
-  - hourly check
+  - activity scan
 related:
   - concepts/observations
-  - features/routines/hourly-check
+  - features/routines/activity-scan
   - features/integrations/git
   - features/integrations/obsidian
 config_keys:
-  - hourlyCheckMinObservations
-  - hourlyCheckEnabled
-  - hourlyCheckIntervalMinutes
+  - activityScanMinObservations
+  - activityScanEnabled
+  - activityScanIntervalMinutes
 process_keys:
-  - routine.hourly_check
+  - routine.activity_scan
 ui_anchors:
   - /connections/repositories
   - /connections/calendar
-  - /settings/schedule
+  - /agents/activity-scan
 context_files:
   - state/today.md
 ---
@@ -55,24 +55,24 @@ context_files:
 # Observation Not Detected
 
 You made a change by hand — a commit, an Obsidian note, a calendar move — and
-expected the agent to notice it on the next hourly check. It didn't.
+expected the agent to notice it on the next activity scan. It didn't.
 
 This is almost always one of four things: the poller hasn't run yet, the
 source isn't being watched, the agent itself made the change (so it was
-filtered out), or there weren't enough observations to clear the hourly-check
+filtered out), or there weren't enough observations to clear the activity-scan
 gate. Work through them in that order.
 
 ## How detection actually works
 
 Observers (Obsidian, Git, Notion, Calendar) do **not** fire an event per
 change. They poll on a cadence and call `recordObservation(...)`, which
-appends a row to the `observations` table. The hourly check later reads those
+appends a row to the `observations` table. The activity scan later reads those
 rows in a single batch. So a "missing" observation is usually a row that was
 never written, or one that was written but filtered.
 
 `AgentWriteTracker` tags every change as `actor='agent'` or `actor='user'`.
 Changes the agent itself wrote are tagged `actor='agent'` and skipped by the
-hourly check — this is the deliberate anti-loop filter that stops the agent
+activity scan — this is the deliberate anti-loop filter that stops the agent
 from observing its own output.
 
 ## Most likely causes
@@ -84,9 +84,10 @@ from observing its own output.
    was never connected, nothing polls it.
 3. **The change was tagged `actor='agent'`.** If the agent (not you) authored
    the commit or note, the anti-loop filter drops it.
-4. **It was below the gate threshold.** The hourly check only runs its full
-   pass when at least `hourlyCheckMinObservations` (default `1`) pending
-   observations exist. A single low-signal change can be held back.
+4. **It was below the gate threshold.** The activity scan only runs its full
+   pass when at least the activity-scan agent's **min observations**
+   threshold (default `1`; legacy key `activityScanMinObservations`) of
+   pending observations exists. A single low-signal change can be held back.
 
 ## Diagnostic steps
 
@@ -101,21 +102,22 @@ from observing its own output.
 3. **Rule out the agent-authored filter.** If the commit or note was written
    by the agent, that's expected — it's filtered by design. Look for a change
    *you* made by hand to test detection.
-4. **Lower the gate threshold to test.** Temporarily set
-   `hourlyCheckMinObservations` to `1` (its default) on `/settings/schedule`
+4. **Lower the gate threshold to test.** Temporarily set **Min
+   observations** to `1` (its default) on the activity-scan agent's page
+   (`/agents/activity-scan`, Definition tab → Cadence card)
    so even a single observation triggers the check, then make a manual change
-   and wait for the next hourly run.
+   and wait for the next activity-scan run.
 
 ## Confirming the fix
 
 After the next poll runs, a manual change you made should record an
-observation and surface in the next hourly check. You can cross-check recent
+observation and surface in the next activity scan. You can cross-check recent
 agent activity from the CLI with `aitne audit`, which reads the `agent_actions`
 log read-only.
 
 ## Related
 
 - [Observations](../concepts/observations.md) — what gets recorded and why
-- [Hourly Check](../features/routines/hourly-check.md) — the gate and its thresholds
+- [Activity Scan](../features/routines/activity-scan.md) — the gate and its thresholds
 - [Git integration](../features/integrations/git.md)
 - [Obsidian integration](../features/integrations/obsidian.md)

package/agent-assets/docs/troubleshooting/quota-exhausted.md

@@ -26,7 +26,7 @@ ask_examples:
   - Why did an autonomous run get skipped for the cost cap?
 locale: en-US
 created: 2026-04-25
-updated: 2026-05-28
+updated: 2026-06-07
 keywords:
   - quota
   - BackendQuotaError
@@ -54,8 +54,9 @@ related:
 - Fallback ran the next routine instead of main.
 - Or: an autonomous run was skipped with reason
   `autonomous_cost_cap_exceeded` — this is a *separate* safety net
-  (`autonomousDailyCostCapUsd` / `autonomousMonthlyCostCapUsd`,
-  default off) that skips only autonomous work, never reactive DMs.
+  (`autonomousDailyCostCapUsd`, default off) that skips only autonomous
+  work, never reactive DMs. (`autonomousMonthlyCostCapUsd`, also default
+  off, is notifications-only — it never skips a run, just alerts.)
   It is not a provider quota error; raise the cap on `/settings/models`
   or wait for the next agent day.
 
@@ -92,9 +93,9 @@ related:
    account's spending / rate-limit settings. For cloud providers,
    open the matching console (AWS / GCP / Azure) and check the
    per-region / per-model quota.
-4. If on the subscription fallback, the backend card shows the
-   "next reset" timestamp for the rolling window. Consider
-   registering an API key — see
+4. If on the subscription fallback, the `BackendQuotaError` message in
+   Activity carries the "next reset" timestamp for the rolling window
+   (when the provider reports one). Consider registering an API key — see
    [Costs and Quotas](../concepts/costs-and-quotas.md).
 
 ## Confirming the Fix

package/agent-assets/docs/troubleshooting/wiki-write-failed.md

@@ -25,7 +25,7 @@ ask_examples:
   - How do I retry the write-strategy probe?
 locale: en-US
 created: 2026-05-12
-updated: 2026-05-28
+updated: 2026-06-11
 keywords:
   - wiki write failed
   - wiki API failure
@@ -36,7 +36,7 @@ api_endpoints:
   - /api/wiki/:workspace/health
 ui_anchors:
   - /settings/wiki
-  - /connections/knowledge
+  - /connections/notes
 related:
   - features/wiki/overview
   - guides/use-an-existing-obsidian-vault
@@ -84,7 +84,7 @@ If any of these is missing, the daemon surfaces a structured error:
 
 | Error code | Meaning | Fix |
 |---|---|---|
-| `EWIKI_CLI_UNAVAILABLE` | Aitne's `ObsidianService` is not configured (the `obsidian` binary is not resolvable on `PATH`). | Open **Connections → Knowledge** and connect Obsidian via the Obsidian card, then confirm Obsidian 1.12+ is installed with the CLI enabled. |
+| `EWIKI_CLI_UNAVAILABLE` | Aitne's `ObsidianService` is not configured (the `obsidian` binary is not resolvable on `PATH`). | Open **Connections → Notes** and connect Obsidian via the Obsidian card, then confirm Obsidian 1.12+ is installed with the CLI enabled. |
 | `EWIKI_CLI_NOT_RUNNING` | The CLI is configured but the Obsidian app is not running, so it cannot reach the sandboxed vault. | Launch the Obsidian app and retry. |
 
 ## Force a Re-Probe

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

@@ -1,6 +1,6 @@
 ---
 name: agent-actions
-description: Load when the running session needs to write structured metadata into its own `agent_actions` row so daemon-side consumers (morning-routine AgentJournalAppender, anomaly surfacing, audit log) read structured data instead of parsing prose.
+description: Load near the end of a morning-routine / dispatcher session to record dayType, anomalies, inbox stats, and files-touched into your own `agent_actions` row, so daemon-side consumers (morning-routine journal appender, audit log) read structured data instead of parsing prose.
 allowed-tools:
   - Bash(curl *)
   - Read
@@ -41,7 +41,8 @@ header attachment for you — you do not type them. The endpoint returns
 if no in-flight row matches your session — typically because the row
 has already settled to a terminal `result`, or because the dispatcher
 spawned the session without the pre-insert step that the morning
-routine's pipeline orchestrator owns. Surface as anomaly and continue.
+routine's pipeline orchestrator owns. Record it in this endpoint's
+`anomalies` field (when accessible) or DM the operator, then continue.
 
 ## Metadata shape
 
@@ -51,12 +52,12 @@ The morning-routine Stage A is the primary caller. Its expected shape:
 
 | Field | Type | Purpose |
 |---|---|---|
-| `dayType` | `"weekday" \| "weekend" \| "focus" \| "off"` | The day-type Stage A derived. ⑥ AgentJournalAppender writes this into agent/journal.md's header line. |
-| `anomalies` | `string[]` | Free-form anomalies you encountered (e.g. "AgentPlan cardinality mismatch: today.md has 6 rows, batch had 5"). ⑥ surfaces these in agent/journal.md and `pnpm audit` filters on them. |
-| `filesTouched` | `string[]` | Paths your turn wrote to (e.g. `context/today.md`, `context/roadmap.md`). |
+| `dayType` | `"weekday" \| "weekend" \| "focus" \| "off"` | The day-type Stage A derived. ⑥ AgentJournalAppender writes this into journal/agent.md's header line. |
+| `anomalies` | `string[]` | Free-form anomalies you encountered (e.g. "AgentPlan cardinality mismatch: today.md has 6 rows, batch had 5"). ⑥ surfaces these in journal/agent.md. |
+| `filesTouched` | `string[]` | Paths your turn wrote to (e.g. `state/today.md`, `plans/roadmap.md`). |
 | `inboxStats` | `{triaged, movedToScratch, dmConfirmsSent, secretsSkipped}` | Inbox triage counts from Step 4. All keys integers >= 0. `secretsSkipped` is collected but NOT rendered by ⑥; surface secret-skip events through `anomalies` as well so they reach the audit trail. |
 | `morningChecks` | `string[]` | Short labels for every Step 8 `policies/routines/morning.md` extension check executed (e.g. `"water bottle filled"`). ⑥ joins these with `, ` into the `Checks from routines/morning.md:` bullet. Empty array → renders as `(none)`. |
-| `scheduleBatchSize` | `number` | Cardinality you observed when posting to `/api/schedule/batch`. Mirrors what was POSTed so ⑥ can detect cardinality mismatches against today.md. |
+| `scheduleBatchSize` | `number` | Cardinality you observed when posting to `/api/schedule/batch`. Informational metadata mirroring what was POSTed. |
 
 The endpoint accepts any well-formed JSON object — these are the keys
 the morning-routine pipeline consumes. Skills can extend the shape
@@ -71,7 +72,7 @@ curl -s -X PATCH http://localhost:8321/api/agent-actions/self \
     "metadata": {
       "dayType": "weekday",
       "anomalies": [],
-      "filesTouched": ["context/today.md", "context/roadmap.md"],
+      "filesTouched": ["state/today.md", "plans/roadmap.md"],
       "inboxStats": { "triaged": 4, "movedToScratch": 4, "dmConfirmsSent": 1, "secretsSkipped": 0 },
       "morningChecks": ["water bottle filled", "calendar synced"],
       "scheduleBatchSize": 5
@@ -86,37 +87,20 @@ Success (200):
 
 ## Errors
 
-Every error response uses the **agent-consumable envelope**:
-
-```jsonc
-{
-  "ok": false,
-  "summary": "Request rejected: agent_actions.session_identity_missing on headers.x-pa-event-correlation-id.",
-  "errors": [
-    {
-      "rowIndex": null,
-      "code": "agent_actions.session_identity_missing",
-      "field": "headers.x-pa-event-correlation-id",
-      "received": "<missing>",
-      "expected": "x-pa-event-correlation-id and x-process-key headers identifying the running session",
-      "hint": "The pa-api shim auto-injects these from PA_EVENT_CORRELATION_ID and PA_PROCESS_KEY when running inside a dispatcher-spawned session.",
-      "skillAnchor": "agent-actions#self-write-auth",
-      "severity": "error"
-    }
-  ],
-  "retryable": false
-}
-```
+Failures return an agent-consumable envelope (`ok:false`) carrying a
+`code`, a `hint`, and a `skillAnchor` back into this skill. The two
+session-state codes below are `retryable:false` — do NOT re-fire; record
+the failure in this endpoint's `anomalies` field (when accessible) or DM
+the operator, then continue. A malformed-body code is retryable — fix the
+body and resend.
 
-### Codes the endpoint can emit
+Two codes reflect session state you must reason about:
 
-| Code | When | Fix |
-|---|---|---|
-| `agent_actions.session_identity_missing` | `x-pa-event-correlation-id` or `x-process-key` header is absent / empty. | Running inside a dispatcher-spawned session the pa-api shim attaches both headers from env. If you see this, the session is misconfigured — surface it as an anomaly via `<safety_violation>` and stop. Not retryable in the same turn. |
-| `agent_actions.session_row_not_found` | No in-flight `agent_actions` row matches `(event_id, action_type)`. | Either the row has already settled to a terminal result (success/failed/partial) and your PATCH arrived late, or the dispatcher spawned this session without the orchestrator-side pre-insert that the morning-routine pipeline relies on. Either way, the PATCH cannot land — surface as anomaly and continue. Not retryable. |
-| `agent_actions.body_not_object` | Request body is not a JSON object. | POST `{"metadata":{…}}`. |
-| `agent_actions.metadata_field_invalid` | `metadata` slot is missing, not an object, an array, or carries non-JSON-serialisable values (functions, Symbols, BigInts). | Pass a plain JSON object literal. Arrays go inside named keys (e.g. `anomalies:[…]`). |
-
-`retryable:false` means the agent should NOT retry the same call; it
-should surface the failure as a structured anomaly (via this endpoint's
-`anomalies` field when accessible) or DM the operator.
+| Code | When |
+|---|---|
+| `agent_actions.session_identity_missing` | `x-pa-event-correlation-id` or `x-process-key` header is absent / empty — the session is misconfigured. The shim normally attaches both from env. |
+| `agent_actions.session_row_not_found` | No in-flight row matches `(event_id, action_type)` — either the row already settled to a terminal result and your PATCH arrived late, or the dispatcher spawned the session without the orchestrator-side pre-insert. |
+
+A malformed body fails with `agent_actions.body_not_object` (send
+PATCH `{"metadata":{…}}`) or `agent_actions.metadata_field_invalid`
+(pass a plain JSON object; arrays go inside named keys).

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

@@ -28,7 +28,10 @@ recurring DM with no autonomous work, use `dm_session` (above), not an Agent.
 ## Before creating — dedup (mandatory)
 
 1. `GET /api/agents` — does an enabled Agent already do this on this cadence? If
-   so, do not create a duplicate (edit it via the dashboard / `PATCH /api/agents/:slug`).
+   so, do not create a duplicate. To edit one: `PATCH /api/agents/:slug` only
+   toggles `enabled` (field edits return `400 user_agent_edit_via_file`); to
+   change a user Agent's prompt/schedule/backend, edit its `agent.md`
+   (`PATCH /api/context/policies/agents/<slug>/agent.md`) or the dashboard editor.
 2. `GET /api/recurring-schedules?enabled=true` — confirm no existing recurring
    row already covers the cadence.
 
@@ -54,8 +57,12 @@ curl -s -X POST http://localhost:8321/api/agents \
 ```
 
 Fields:
-- **`slug`** — kebab-case, unique, immutable after creation (the `/agents/<slug>` URL).
-- **`name`**, **`description`** — human labels shown in the dashboard.
+- **`slug`** — kebab-case, must start with a lowercase letter (`^[a-z][a-z0-9-]*`),
+  unique, immutable after creation (the `/agents/<slug>` URL). A leading digit or
+  hyphen is rejected as `invalid_definition` on field `slug`.
+- **`name`**, **`description`** — required human labels shown in the dashboard; an
+  empty/omitted `description` is rejected as `invalid_definition` on field
+  `description`.
 - **`schedule.kind`** — `"recurring"` (structured, preferred) or `"cron"` (raw
   expression). A `one_shot`/`event` schedule is rejected with
   `one_shot_not_supported` (use `/schedule` for one-time work). Note:
@@ -77,10 +84,18 @@ Fields:
   in the resolved timezone (`min hour day-of-month month day-of-week`). Examples:
   `0 9 * * *` (daily 09:00), `0 8 * * 1` (Mondays 08:00), `0 * * * *` (hourly at
   :00), `0 */2 * * *` (every 2 hours), `0 18 1 * *` (1st of each month 18:00).
-  Only cron shapes that map to a recurrence are accepted: minute a single value;
-  hour a single value or `*` / `*/N`. Sub-hourly steps (`*/30`) and hour
-  ranges/lists are NOT representable — pick one explicit cadence.
+  A syntactically-valid cron is accepted at create (`201`, valid row) even if it
+  cannot be mapped to a recurrence — but a non-mappable shape (sub-hourly steps
+  like `*/30`, hour ranges/lists like `9-17`) is never paired and silently never
+  fires. Only shapes that map are actually run: minute a single value; hour a
+  single value or `*` / `*/N`. Pick one explicit, mappable cadence.
 - **`schedule.timezone`** — IANA zone; omit to inherit the daemon default.
+- **`schedule.defer_in_quiet_hours`** — boolean, default `false`. When `true`, a
+  firing that lands inside the user's quiet hours is pushed to the window's end
+  instead of running — the whole run moves, so the data is fresh at delivery
+  time. Mechanical rule: **set `true` whenever the Expected output includes
+  DMing the user**; leave it `false` for silent file-writing work deliberately
+  scheduled overnight.
 - **`backend`** — optional. `tier` is `lite`/`medium`/`high` (cost/capability knob;
   the standalone control that works). `process_key` defaults to `agent.task`;
   omit unless you know you need another. (Pinning a backend *engine* without a
@@ -128,6 +143,11 @@ Each morning, surface inbox items that need the user's decision today.
 **Bad prompt:** `"Triage my inbox."` — no requirements, no steps, no output
 contract; the Agent will improvise differently every day.
 
+The Expected-output decision feeds one schedule field: if the output contract
+includes DMing the user, also set `schedule.defer_in_quiet_hours: true` so a
+firing inside quiet hours waits for the window's end instead of producing a
+message that would be held anyway.
+
 ## Responses & errors
 
 - `201 { "status": "created", "slug": "…" }` — the Agent is live; its recurring

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

@@ -27,21 +27,7 @@ Only the following tools are available inside this skill. Everything else is den
 | `Write` | Create the file to upload (text, markdown, CSV, JSON, YAML). |
 | `Bash(curl *)` | Issue exactly one POST to the daemon per file. |
 
-### Commands that WILL be denied — do not attempt
-
-The Claude Code permission classifier blocks these patterns under `dontAsk`. Attempting them wastes a turn and confuses the user.
-
-- **Any shell expansion of an environment variable**: `$PA_TURN_TOKEN`, `$HOME`, `$(date +%Y)`, `` `whoami` `` — all auto-denied. This is why the turn token is injected by the daemon's curl wrapper instead of being passed inline (see below).
-- `ls /tmp/...` / `ls <absolute-path>` — absolute-path listings are auto-denied.
-- `cat <file>`, `head`, `tail`, `stat`, `file`, `test -f`, `echo <anything>` — none are on the allowlist.
-- Chained commands via `&&`, `||`, `;`, `|` — each segment is evaluated separately; any segment outside the allowlist fails the whole line.
-- `python3 ...`, `pandoc`, `node <script>`, `sh -c`, etc. — not on the allowlist. Binary/PDF/chart generation is out of scope for Phase 1; stick to text formats you can `Write`.
-
-If you *think* you need one of the above, the answer is to pre-compute the value in your reasoning, write it as a literal, and invoke curl once with no substitutions.
-
-## Per-turn capability token
-
-The daemon issues a per-turn token and makes the session's curl wrapper (`.pa/bin/curl`) attach it automatically to requests to `/api/chat/outbound-attachments`. **Do not pass `X-Turn-Token` yourself** — inline `$PA_TURN_TOKEN` expansion is blocked by the permission classifier, and the wrapper already handles this for you.
+- **curl with literal strings only.** No `$VAR` / `$(...)` / backticks / pipes / chained commands (`&&`, `||`, `;`, `|`) — the `dontAsk` classifier silently denies them. Pre-compute any value in your reasoning and write it as a literal. The session's curl wrapper (`.pa/bin/curl`) injects `X-Turn-Token` from `PA_TURN_TOKEN` for you — never pass it yourself, and binary/PDF/chart generation (`python3`, `pandoc`, `node`) is out of scope for Phase 1; stick to text formats you can `Write`.
 
 If the turn has already ended (or no token was issued), the daemon returns HTTP 403 `missing_turn_token`. Treat that as a terminal signal, not something to retry.
 
@@ -56,21 +42,19 @@ curl -s -X POST http://localhost:8321/api/chat/outbound-attachments \
   -H "X-Filename: weekly-summary.md" \
   -H "X-Caption: Weekly summary" \
   -F "file=@/tmp/weekly-summary.md"
-# → {"id":"<uuid>"}                      on success
-# → {"error":"missing_turn_token"}       HTTP 403
-# → {"error":"invalid_turn_token"}       HTTP 403
-# → {"error":"too_large"}                HTTP 400
-# → {"error":"disallowed_mime"}          HTTP 400
-# → {"error":"too_many_uploads"}         HTTP 429
+# → {"id":"<uuid>"}                      HTTP 200 — success
+# → 403 — turn token missing/invalid; do not retry (see Errors table)
 ```
 
+Errors return the standard agent-error envelope `{ok:false,summary,errors:[{code,field,hint}],retryable,error:<code>}`. Branch on the flat `error` field (a legacy alias for the single issue code); the codes in the Errors table are accurate.
+
 | Header / field | Purpose |
 |---|---|
 | `file` (form field, binary) | The bytes to deliver. Stream from a file you just created with `Write`. |
 | `X-Filename` | Optional. Overrides the filename shown to the user. Literal string — no substitutions. Default: the multipart `filename` parameter. |
 | `X-Caption` | Optional. ≤ 1024 chars. Literal string — no `$(...)` / backticks. |
 
-> The wrapper silently adds `X-Turn-Token` from `PA_TURN_TOKEN`. Do not add it yourself. If you *do* pass `X-Turn-Token` explicitly (e.g. during local debugging), the wrapper will respect your value and not overwrite it.
+> If you *do* pass `X-Turn-Token` explicitly (e.g. during local debugging), the wrapper respects your value and does not overwrite it.
 
 ### Size and type limits (Phase 1)
 
@@ -84,12 +68,9 @@ Per-turn total across all attachments is capped at **100 MB**; the endpoint retu
 ## Workflow
 
 1. Decide the filename and caption up front (literal strings — no shell interpolation).
-2. Generate the content and write it with the `Write` tool. Use `/tmp/<name>` as the path only — every other path (`~/`, session workdir, context dir, `/var/`, `/Users/...`) is denied by the absolute-block layer (`packages/daemon/src/safety/always-disallowed.ts`). Never write into the session workdir or the context dir.
+2. Generate the content and write it with the `Write` tool. Write scratch files under `/tmp/<name>` — the session workdir is re-materialized between turns and the context dir is daemon-owned, so `/tmp` avoids collisions.
 3. Issue the single curl POST shown above. One file per call.
-4. Branch on the response:
-   - Success (`{"id": "..."}`) — mention the attachment in your reply, e.g. `"Attached: weekly-summary.md"`. You may discard the id; the daemon links it to your message automatically.
-   - HTTP 403 (`missing_turn_token` / `invalid_turn_token`) — the turn has already been released or the skill was invoked outside a turn. Do not retry. Fall back to inline paste and tell the user the attachment could not be sent.
-   - Other errors — follow the table below.
+4. On success (`{"id": "..."}`) mention the attachment in your reply, e.g. `"Attached: weekly-summary.md"` — you may discard the id; the daemon links it automatically. On any error, follow the Errors table below.
 
 Never base-64 embed files into your reply body. Always go through this endpoint.