@aitne-sh/aitne 0.1.0

package/agent-assets/docs/troubleshooting/messaging-not-pairing.md

@@ -0,0 +1,53 @@
+---
+schema_version: 1
+slug: troubleshooting/messaging-not-pairing
+title: Messaging Not Pairing
+id: messaging-not-pairing
+category: troubleshooting
+summary: |
+  The magic phrase isn't pairing your messaging account. Usually the
+  bot can't see DMs, the phrase expired, or the message went to a
+  group instead of a direct channel.
+section: messaging-not-pairing
+tags:
+  - troubleshooting
+  - messaging
+status: stable
+ask_examples:
+  - Why isn't my magic phrase pairing?
+  - Where do I send the magic phrase?
+locale: en-US
+created: 2026-04-25
+updated: 2026-04-25
+related:
+  - features/messaging/pairing-and-magic-phrase
+  - features/messaging/overview
+---
+
+# Messaging Not Pairing
+
+## What You See
+
+- After DMing the magic phrase, the dashboard's pairing card stays in
+  "waiting" state.
+
+## Most Likely Causes
+
+1. Phrase expired — generate a new one.
+2. Bot does not have DM permission (Discord, Slack).
+3. DM was sent in a group / channel by mistake.
+4. Bot token wrong — paste it in again.
+
+## Diagnostic Steps
+
+1. Click "Regenerate phrase" on `/connections/messaging`.
+2. Confirm bot privileges in the messaging app.
+3. Send the phrase from a direct chat with the bot.
+
+## Confirming the Fix
+
+- The pairing card shows your owner identity.
+
+## Related
+
+- [Pairing & Magic Phrase](../features/messaging/pairing-and-magic-phrase.md)

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

@@ -0,0 +1,75 @@
+---
+schema_version: 1
+slug: troubleshooting/morning-routine-didnt-run
+title: Morning Routine Didn't Run
+id: morning-routine-didnt-run
+aliases:
+  - morning routine missed
+  - empty today
+  - no morning briefing
+category: troubleshooting
+summary: |
+  The most common operator pain. Causes are ordered by frequency:
+  daemon was stopped, fallback failed, quota exhausted, schedule
+  configuration mismatch, day-boundary subtlety.
+section: morning-routine-didnt-run
+tags:
+  - troubleshooting
+  - routine
+status: stable
+ask_examples:
+  - Why didn't my morning routine fire?
+  - Why is today.md empty?
+locale: en-US
+created: 2026-04-25
+updated: 2026-04-25
+related:
+  - features/routines/morning-routine
+  - troubleshooting/auth-failed
+  - troubleshooting/quota-exhausted
+---
+
+# Morning Routine Didn't Run
+
+## What You See
+
+- An empty or stale `today.md`.
+- No morning notification.
+- Activity has no `routine.morning_routine` row for today.
+
+## Most Likely Causes (in probability order)
+
+1. **Daemon was stopped at the trigger time.** Check `pa status`.
+2. **Fallback failed too.** Look for a `fallback-failed` notification.
+3. **Heavy-tier quota exhausted on both backends.** See
+   [Quota Exhausted](quota-exhausted.md).
+4. **Hourly check skip-gate fired during the trigger window.** The
+   morning routine and the hourly check share an atomic flag — if the
+   hourly check was already running at the rollover instant, the
+   morning routine won't double-fire.
+5. **Day-boundary subtlety.** Before `dayBoundaryHour`, the routine
+   still "belongs to" yesterday — see
+   [Agent Day](../concepts/agent-day.md).
+
+## Diagnostic Steps
+
+1. `pa status` — daemon up?
+2. `/activity` — any row for `routine.morning_routine`?
+3. `/settings/routines` — the routine list shows the next scheduled
+   fire and recent runs.
+4. `pa logs` — search for `morning_routine`.
+
+## Confirming the Fix
+
+- The next morning's routine fires within 60 seconds of
+  `dayBoundaryHour` (default 04:00).
+- Activity shows the row with a non-error outcome.
+
+## When None of the Above Help
+
+- Open an issue with a redacted excerpt of the daemon log around the
+  expected fire time.
+
+## Related
+
+- [Morning Routine](../features/routines/morning-routine.md)

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

@@ -0,0 +1,57 @@
+---
+schema_version: 1
+slug: troubleshooting/observation-not-detected
+title: Observation Not Detected
+id: observation-not-detected
+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
+  watched, or the change was authored by the agent itself.
+section: observation-not-detected
+tags:
+  - troubleshooting
+  - observations
+status: stable
+ask_examples:
+  - Why didn't the agent notice my new commit?
+  - Why didn't a calendar change show up?
+locale: en-US
+created: 2026-04-25
+updated: 2026-04-25
+related:
+  - concepts/observations
+  - features/integrations/git
+  - features/integrations/obsidian
+  - features/routines/hourly-check
+---
+
+# Observation Not Detected
+
+## What You See
+
+- A change you made by hand, not echoed by the hourly check.
+- The hourly check ran but did not mention it.
+
+## Most Likely Causes
+
+1. Poll has not yet fired since your change.
+2. The repo / vault is not on the watched list.
+3. The change was tagged `actor='agent'` (anti-loop filter).
+4. Below the `hourlyCheckMinObservations` threshold.
+
+## Diagnostic Steps
+
+1. Confirm the integration's "last polled" timestamp on
+   `/connections/...`.
+2. Confirm the observed path is in the watched set.
+3. Lower `hourlyCheckMinObservations` to test.
+
+## Confirming the Fix
+
+- Future changes record observations and surface in the next
+  hourly check.
+
+## Related
+
+- [Observations](../concepts/observations.md)

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

@@ -0,0 +1,57 @@
+---
+schema_version: 1
+slug: troubleshooting/quota-exhausted
+title: Quota Exhausted
+id: quota-exhausted
+aliases:
+  - max5 limit hit
+  - opus window
+  - subscription limit
+category: troubleshooting
+summary: |
+  A backend reported a quota error and the router fell over to the
+  fallback. Either wait for the window to refresh or upgrade the plan.
+section: quota-exhausted
+tags:
+  - troubleshooting
+  - cost
+  - backends
+status: stable
+ask_examples:
+  - Why am I seeing "subscription limit reached"?
+  - When does the Opus window reset?
+locale: en-US
+created: 2026-04-25
+updated: 2026-04-25
+related:
+  - concepts/costs-and-quotas
+---
+
+# Quota Exhausted
+
+## What You See
+
+- A `BackendQuotaError` row in Activity.
+- Fallback ran the next routine instead of main.
+- Analytics shows the budget close to or past the cap.
+
+## Most Likely Causes
+
+1. **5-hour Opus window** burned by a heavy routine cluster.
+2. **Daily Sonnet bucket** hit on a long-running session.
+3. **Gemini per-day cap** for `gemini-2.5-flash` reached on the free
+   tier.
+
+## Diagnostic Steps
+
+1. Open `/analytics` and look at the by-backend rollup.
+2. The "next reset" timestamp on Claude's card tells you when the
+   rolling window refreshes.
+
+## Confirming the Fix
+
+- The next run after the window resets succeeds on the main backend.
+
+## Related
+
+- [Costs and Quotas](../concepts/costs-and-quotas.md)

package/agent-assets/optimizer-skills/drift-analysis/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: drift-analysis
+description: Read signals → decide which to act on, which to ignore, which to defer. Never act on a single signal in isolation; require corroboration.
+allowed-tools:
+  - Read
+---
+
+# Drift Analysis
+
+Signals live under `data/signals/<skill_slug>.json` in your workdir.
+Each is one row from `skill_curation_signals`:
+
+```jsonc
+{
+  "id": 42,
+  "skill_slug": "user-profile",
+  "section_id": "topic-files",
+  "signal_type": "structure_diff",
+  "payload": { "sub_kind": "heading_add", "target": "user/personal.md#健康記録" },
+  "observed_at": 1717000000000
+}
+```
+
+## Corroboration rule
+
+A single `structure_diff` signal is suggestive, not actionable. To submit
+a proposal you must EITHER:
+
+- cite ≥ 2 distinct signals affecting the same `(skill, section)`, OR
+- cite a single signal of weight ≥ 3 (only `owner_correction` qualifies).
+
+Single-signal proposals from `structure_diff` alone are auto-rejected by
+the smoke test (`signal_citations_valid`). Don't try.
+
+## Triage taxonomy
+
+For each (skill, section) with corroborated signals, classify the change
+shape:
+
+- `additive_only` — signals all describe ADD operations (file_add,
+  heading_add). Propose with confidence; the worst case is a `revert`.
+- `mixed` — some adds, some modifications. Propose with extra rationale
+  citing each signal's contribution.
+- `destructive` — at least one signal cites a removal. Only propose if
+  signals explicitly state user intent to remove (`owner_correction`
+  with intent="remove"; structure_diff alone is insufficient). When in
+  doubt, SKIP.
+
+## Skip conditions
+
+Do nothing on (skill, section) when ANY of these hold:
+
+- Signals contradict (one says add, another says remove the same target).
+- All signals are < 24h old (`structure_diff` low-weight gate hasn't
+  matured; the snapshot may be a brief experiment).
+- Section is `frozen` (returns from `/skills/<slug>` as `frozen=true`).
+- Section had a proposal applied or auto-applied within the last 7 days
+  (cooldown).
+- Section had a proposal reverted/conflict in the last 14 days.
+
+## Self-restraint
+
+**It is correct and expected to finish a run with zero proposals.** The
+optimizer's success is measured over weeks, not per run. The owner
+prefers "no action needed" to a low-confidence proposal. If you're
+unsure, skip.
+
+## Recording your decisions
+
+Use `POST /api/skill-curation/runs/<runId>/finalize`'s `notes` field to
+explain skips. Examples:
+
+- "user-profile/routing-table: 3 signals but contradictory (one heading_add for ## Health, two heading_remove for same — likely an in-progress restructure). Skipping until next cadence."
+- "today/section-shape: 1 structure_diff signal — below corroboration threshold."
+- "context/file-responsibilities: section frozen since 2026-04-22 owner revert. Skipping."

package/agent-assets/optimizer-skills/knowledge-map/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: knowledge-map
+description: Read knowledge-map.json snapshots correctly. Distinguish facts (what exists today) from signals (evidence of recent change).
+allowed-tools:
+  - Read
+---
+
+# Knowledge Map
+
+The file `data/knowledge-map.json` in your workdir is a structural
+snapshot of `~/.personal-agent/context/` taken at run start. It is the
+ground truth for "what files exist and what headings they contain right
+now." Use it for `paths_resolve` / `sections_resolve` validation BEFORE
+submitting a proposal.
+
+## Schema
+
+```jsonc
+{
+  "context_dir": "/Users/.../personal-agent/context",
+  "taken_at": 1717000000000,
+  "files": [
+    {
+      "path": "user/profile.md",
+      "headings": ["Identity", "Work Pattern", "Learned Context"],
+      "frontmatter": { "type": "profile", "owner": "shared" },
+      "last_modified_at": 1716900000000
+    },
+    ...
+  ]
+}
+```
+
+- Globs in skill `scope_paths` (e.g. `user/*.md`) are NOT pre-expanded —
+  match yourself.
+- `headings[]` order is document order, leading `## ` / `### ` already
+  stripped.
+- `frontmatter` is a flat string→scalar object (no nested YAML).
+
+## How to compare snapshot to a current payload
+
+A `knowledge_layout` payload's `files[]` SHOULD agree with the snapshot's
+files. When they diverge:
+
+- Snapshot has a file the payload doesn't → `additive` opportunity.
+- Snapshot is missing a file the payload claims → likely a `destructive`
+  proposal, but ONLY propose if signals corroborate (a `file_remove`
+  structure_diff, an owner_correction, etc.).
+- Snapshot has a heading the payload doesn't list → `additive` (heading
+  added since last overlay).
+- Payload claims a heading the snapshot doesn't have → `destructive`,
+  same corroboration rule.
+
+## Anti-patterns
+
+- NEVER infer `cross_references` payloads from snapshot adjacency alone.
+  "Two files in the same directory" is not evidence of a relationship.
+  Cross-references require an explicit citing signal.
+- NEVER propose a `frontmatter_schema` reduction (drop a `required[]`
+  entry) — schema reduction is a separate human PR. The smoke test
+  rejects this anyway.
+- NEVER propose changes that turn a heading list of length 6 into 3.
+  Walked-only signals can be wrong; combine with at least one signal of
+  weight ≥ 2 before considering removal.
+
+## Time interpretation
+
+- `last_modified_at < 7 days ago` → "fresh", may be in flux.
+- `last_modified_at` older than 60 days, unchanged → "stable", safe to
+  treat as permanent layout.
+- Frequency-of-change is OUT of scope for the optimizer (no analytics).

package/agent-assets/optimizer-skills/skill-curation/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: skill-curation
+description: Submit typed-payload proposals to update knowledge-cartography sections of skills. Read-then-validate-then-submit. Never invent new section ids or kinds.
+allowed-tools:
+  - Bash(curl http://localhost:8321/api/skill-curation/*)
+  - Read
+---
+
+# Skill Curation
+
+You are running inside an isolated optimizer workdir. The ONLY mutation
+surface available to you is the curation API at
+`http://localhost:8321/api/skill-curation/*`. You cannot Edit, Write,
+MultiEdit, NotebookEdit, run shell commands other than the curl glob, or
+read any file outside this workdir's `data/` subtree.
+
+## Workflow (in order, every run)
+
+1. List candidate skills:
+   `curl -s http://localhost:8321/api/skill-curation/skills`
+2. For each skill the run targets, list its current sections:
+   `curl -s http://localhost:8321/api/skill-curation/skills/<slug>`
+3. Read the current payload for each candidate section:
+   `curl -s http://localhost:8321/api/skill-curation/skills/<slug>/sections/<section_id>`
+4. Compare against the knowledge-map snapshot under `data/knowledge-map.json`.
+5. For each section where signals + snapshot agree on a real change, submit
+   ONE proposal at a time, the smallest payload that closes the gap.
+
+## Submission shape
+
+```
+POST /api/skill-curation/proposals
+Header: X-Optimizer-Token: <runToken from env>
+Body:
+{
+  "runId": "<runId>",
+  "skill_slug": "user-profile",
+  "section_id": "topic-files",
+  "payload": { "kind": "knowledge_layout", "files": [...] },
+  "rationale": "structure_diff observed `## 健康記録` heading on user/personal.md last week",
+  "signal_ids": [42, 47]
+}
+```
+
+The API returns `{proposalId, rendered, diff}` on accept. On reject, the
+response body lists `failures[]` — fix the payload and try again.
+
+## Hard rules (auto-reject)
+
+- Never invent new `section_id` values. If the skill doesn't declare a
+  section, you cannot create one.
+- Never POST to a section whose declared `kind` doesn't match your
+  payload's `kind`.
+- Never re-submit a `frozen` section (`/skills/<slug>` returns
+  `frozen_sections`). The frozen state is a deliberate owner override.
+- ALWAYS cite at least one `signal_id`. A proposal with empty
+  `signal_ids[]` is rejected.
+- Never copy a `signal_id` already cited in another proposal in the same
+  run (each signal is consumed once).
+
+## Decision-language guard
+
+Free-text fields (`convention_notes.rule`, `routing_table.note`,
+`search_recipes.note`) MUST describe the convention, not prescribe an
+action. Examples:
+
+- ❌ "When the user mentions a doctor visit, write to user/personal.md"
+- ✅ "Doctor visits are recorded under `user/personal.md ## 健康記録`"
+- ❌ "Always include the date with the entry"
+- ✅ "Entries carry a `[YYYY-MM-DD]` prefix"
+- ❌ "Never use spaces in slugs"
+- ✅ "Slugs are kebab-case, no spaces"
+
+The API rejects payloads that match `\b(must|always|never)\b` or
+imperative `when X then Y` / `if X do Y` / `before X you should Y`
+constructions. If you find yourself wanting to write a rule, restate it
+as a description.
+
+## Dry-run discipline
+
+Every proposal MUST be dry-run first to surface smoke-test failures
+without consuming signals:
+
+```
+POST /api/skill-curation/proposals/dryrun
+(same body shape; no proposalId returned, only diff + failures)
+```
+
+If `dryrun` returns failures, fix the payload — never skip dry-run.
+
+## Stop conditions
+
+If a section's signals contradict each other (one says "add ## Health",
+another says "## Health was deleted"), submit no proposal and surface the
+conflict in the run summary by including a `notes` field on
+`POST /api/skill-curation/runs/<runId>/finalize`. It is correct and
+expected to finish a run with zero proposals.
+
+## Finalization
+
+When you've submitted all proposals you intend to:
+
+```
+POST /api/skill-curation/runs/<runId>/finalize
+Body: { "notes": "applied 2 additions for user-profile, skipped today (contradictory signals)" }
+```
+
+The daemon notifies the owner and tears down your workdir.

package/agent-assets/project-doc-templates/git-repo.md

@@ -0,0 +1,21 @@
+---
+type: git-repo
+owner: shared
+updated: {updated}
+slug: {repo_slug}
+classification: repo-only
+git_repo: {repo_path}
+default_branch: {default_branch}
+remote: {origin_url}
+account_alias: {account_alias}
+last_activity: {last_commit_date}
+---
+# {repo_name}
+
+## Activity
+- Last reviewed: {updated}
+- Default branch: {default_branch}
+- Remote: {origin_url}
+
+## Recent Pushes
+- Add notable remote changes here.

package/agent-assets/project-doc-templates/project.md

@@ -0,0 +1,38 @@
+---
+type: project
+owner: shared
+updated: {updated}
+slug: {repo_slug}
+category: {category}
+status: active
+org: {org}
+git_repo: {repo_path}
+default_branch: {default_branch}
+remote: {origin_url}
+account_alias: {account_alias}
+created: {first_commit_date}
+last_activity: {last_commit_date}
+---
+# {repo_name}
+
+## Overview
+- Purpose:
+- Current state:
+- Primary owner:
+
+## Git Activity
+- Last reviewed: {updated}
+- Default branch: {default_branch}
+- Remote: {origin_url}
+
+## Lifecycle Phases
+- Initial documentation created from Git history.
+
+## Notable Changes
+- Add durable project milestones and important merges here.
+
+## Open Threads
+- Add follow-ups that should remain visible across sessions.
+
+## History (compressed)
+- Summarize older activity here as the file grows.

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

@@ -0,0 +1,104 @@
+---
+name: attach
+description: Load when the reply should embed a file (generated md/PDF/CSV, chart image, modified upload) — `Write` to disk alone is not delivery.
+when_to_use: The only channel that delivers a file alongside chat. Skip if the user only needs the path mentioned, not the bytes attached.
+allowed-tools:
+  - Bash(curl *)
+  - Write
+---
+
+# Attach files to your reply
+
+You can deliver files alongside your reply by uploading them to the daemon's outbound-attachment endpoint. The daemon collects everything tagged with the current turn's token, pins it to the assistant message it is about to record, and hands the file refs to the originating adapter (dashboard in Phase 1) so the user sees it in the same chat thread.
+
+## When to use
+
+- User asks for a chart/graph, PDF export, CSV dump, text file, or an image you produced this turn.
+- A file is meaningfully better than a large inline paste (e.g. several-page report).
+- User uploaded a file and asks for a modified / summarized version in return.
+
+Do NOT use this for trivial text that fits in a chat reply — pasting inline is faster and easier to skim.
+
+## Tools you may use (enforced allowlist)
+
+Only the following tools are available inside this skill. Everything else is denied silently in `dontAsk` mode — do not try alternatives, pipes, or shell helpers.
+
+| Tool | Purpose |
+|---|---|
+| `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.
+
+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.
+
+## API
+
+### POST /api/chat/outbound-attachments
+
+Upload a single file (one call per file). Multipart `file` field, optional `X-Filename` + `X-Caption` headers. The wrapper injects `X-Turn-Token` automatically.
+
+```bash
+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
+```
+
+| 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.
+
+### Size and type limits (Phase 1)
+
+- Images: **≤ 5 MB** (PNG, JPEG, WebP, GIF, HEIC, SVG).
+- Other files: **≤ 25 MB** (PDF, DOCX/XLSX/PPTX, ODT, TXT, MD, CSV, JSON, YAML, XML, common source types).
+- **Audio/video** uploads are rejected — Phase 3 work.
+- Executables, archives (zip/tar/7z/rar), and unknown binary payloads are rejected.
+
+Per-turn total across all attachments is capped at **100 MB**; the endpoint returns 429/`too_many_uploads` if you issue more than 5 concurrent uploads on the same turn.
+
+## 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; never write into the session workdir or the context dir.
+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.
+
+Never base-64 embed files into your reply body. Always go through this endpoint.
+
+## Errors
+
+| Response | Cause | What to do |
+|---|---|---|
+| 403 `missing_turn_token` / `invalid_turn_token` | Turn already ended, or the header was empty at request time | Do not retry. Paste content inline and mention the limitation. |
+| 400 `too_large` | File exceeded the per-type cap | Trim / summarize the content before retrying. |
+| 400 `disallowed_mime` / `undetected_mime` | Format not on the Phase 1 allowlist | Convert to an allowed format (e.g. table → CSV). |
+| 429 `too_many_uploads` | > 5 uploads in flight on this turn | Wait briefly and retry, or batch into fewer files. |