@aitne-sh/aitne 0.1.12 → 0.1.13

package/agent-assets/docs/troubleshooting/wiki-ingest-full-blocked.md

@@ -16,7 +16,6 @@ summary: |
   This entry tells you how to clear each branch.
 section: troubleshooting
 tags:
-  - troubleshooting
   - wiki
   - cost
   - git
@@ -29,7 +28,7 @@ ask_examples:
   - What does "Sent for approval" mean after !compile full?
 locale: en-US
 created: 2026-05-12
-updated: 2026-05-28
+updated: 2026-07-01
 keywords:
   - wiki compile blocked
   - compile cost gate
@@ -57,8 +56,8 @@ ui_anchors:
 
 ## What You See
 
-You ran `!compile full` and the bang reply was one of these. Jump to the
-matching section:
+You ran `!compile full` and it stopped before doing anything, with one of
+these replies. Jump to the section that matches what you saw:
 
 - **"the external vault has uncommitted changes"** — the git pre-compile
   gate. See [Uncommitted Changes](#uncommitted-changes).
@@ -74,20 +73,20 @@ The full reply is:
 > Cannot run `!compile full` — the external vault has uncommitted
 > changes. Please commit or stash first. Dirty paths: …
 
-This is the **git pre-compile gate** firing. Before a full rebuild,
-Aitne wants to take a clean pre-compile snapshot commit so you can revert
-the whole compile in one step. It refuses to start on an external
-git-tracked vault whose working tree is dirty, because that snapshot
-would no longer be a clean baseline.
+This is the **git pre-compile gate**. Before a full rebuild, Aitne makes a
+clean snapshot commit of your vault, so you can undo the whole compile in
+one step later. It will not start when a git-tracked external vault still
+has uncommitted changes (a "dirty" working tree), because that snapshot
+would no longer be a clean baseline to revert to.
 
 To proceed:
 
 1. `git -C <vault> status` — review the dirty paths Aitne listed.
 2. Commit or stash them: `git add -A && git commit -m "wip"` or
    `git stash -u`.
-3. Re-run `!compile full`. On a clean tree Aitne commits the snapshot
-   itself (`aitne wiki: pre-compile snapshot <ts>`) before the compile
-   starts, and the reply echoes the short SHA.
+3. Re-run `!compile full`. On a clean tree Aitne makes the snapshot commit
+   for you (`aitne wiki: pre-compile snapshot <ts>`) before the compile
+   starts, and the reply shows its short SHA.
 
 If you don't want the auto-commit, turn off **Auto-commit before
 `!compile full`** on `/settings/wiki` (the toggle only appears for
@@ -105,9 +104,10 @@ The full reply ends with:
 > Sent for approval. Open `/settings/wiki` → Approvals to confirm and the
 > compile will start.
 
-This is the **cost gate**. Before running, Aitne estimates the compile
-cost (pure on-disk arithmetic — no agent session is spent). The estimate
-DM looks like this:
+This is the **cost gate**. Before running, Aitne estimates what the compile
+will cost. This estimate is just arithmetic over the files on disk — it
+does not spend an agent session to work it out. The estimate DM looks like
+this:
 
 ```
 Full compile estimate for `my-wiki`:
@@ -117,13 +117,13 @@ Full compile estimate for `my-wiki`:
 - approval threshold: $2.00
 ```
 
-If the **pessimistic** bound (`2× expected`) exceeds the per-workspace
-approval threshold (default **$2.00**), the compile is queued for
-approval instead of running.
+If the **pessimistic** figure (`2× expected`) is above the per-workspace
+approval threshold (default **$2.00**), the compile waits for your approval
+instead of running right away.
 
 ### Approve or Deny
 
-The queued request shows up as a **pending approval** on the dashboard.
+The waiting request shows up as a **pending approval** on the dashboard.
 Open the dashboard overview (the home page `/`, also reached via the
 `/approvals` shortcut) and use the **pending approvals** card:
 
@@ -140,21 +140,22 @@ request.
 You have three levers, all on `/settings/wiki`:
 
 - **Raise the threshold.** The **Approval threshold for `!compile full`**
-  field controls when a compile queues for approval. Bump it if routine
-  recompiles keep stalling on a confirmation you'd always grant.
+  field decides when a compile has to wait for approval. Raise it if
+  routine recompiles keep stalling on a confirmation you would always say
+  yes to.
 - **Use a cheaper model.** In the **Commands & models** section, point
   `wiki.compile` at a lite-tier model. It defaults to the medium tier
-  (Claude Sonnet 5), whose per-token cost is the dominant variable in
-  the estimate.
+  (Claude Sonnet 5), and the model's per-token price is the biggest factor
+  in the estimate.
 - **Trim the raw layer.** The estimate scans `10_raw/` and approximates
-  tokens per file from on-disk content, so the cost tracks the actual
-  size of what you're compiling. Compiling fewer or shorter raw notes
-  lowers the bound directly.
+  the tokens in each file from its on-disk content, so the cost tracks the
+  actual size of what you are compiling. Fewer or shorter raw notes lower
+  the estimate directly.
 
-> The estimate is a heuristic (≈4 chars per token for prose, denser for
-> CJK), bracketed `0.5×`–`2×`. It is intentionally cheap rather than
-> exact — close enough to gate spend without burning a session to
-> measure it.
+> The estimate is a rough rule of thumb (≈4 characters per token for
+> prose, denser for CJK), bracketed `0.5×`–`2×`. It is deliberately cheap
+> rather than exact — close enough to gate spending without burning a
+> session just to measure it.
 
 ## Not Enabled
 
@@ -163,11 +164,11 @@ If the reply is:
 > Wiki is not enabled. Open `/settings/wiki` and enable the internal
 > wiki workspace first.
 
-you have no active workspace row. On `/settings/wiki`, either click
+you have no active workspace yet. On `/settings/wiki`, either click
 **Enable internal wiki** to create the built-in workspace, or point Aitne
-at an existing folder with **Use this folder** (after the path probe
+at an existing folder with **Use this folder** (once the path check
 passes). Then re-run `!compile full`.
 
 If the workspace exists but is archived, the page shows a **This wiki is
-archived** card — click **Re-activate wiki** there before any `!compile`
-command will run.
+archived** card — click **Re-activate wiki** there first. No `!compile`
+command will run until you do.

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

@@ -14,9 +14,7 @@ summary: |
   filesystem permission vs. the Obsidian CLI fallback path.
 section: wiki-write-failed
 tags:
-  - troubleshooting
   - wiki
-  - obsidian
   - integrations
 status: stable
 ask_examples:
@@ -25,7 +23,7 @@ ask_examples:
   - How do I retry the write-strategy probe?
 locale: en-US
 created: 2026-05-12
-updated: 2026-06-11
+updated: 2026-07-01
 keywords:
   - wiki write failed
   - wiki API failure
@@ -46,31 +44,30 @@ related:
 
 ## What You See
 
-A wiki bang command (`!ingest`, `!compile`) reports a write failure in
-the daemon log, or the `GET /api/wiki/:workspace/health` endpoint
-(surfaced behind the dashboard's write-strategy badge) reports a
-non-`fs` strategy with `cliAvailable: false`.
+A wiki bang command (`!ingest` or `!compile`) reports a write failure in
+the daemon log. Or the wiki health check — `GET /api/wiki/:workspace/health`,
+shown behind the dashboard's write-strategy badge — reports a strategy other
+than `fs`, with `cliAvailable: false`.
 
 ## Quick Checklist
 
-1. **Internal mode?** Internal workspaces always write via the local
-   filesystem. If you see EPERM there, the underlying issue is
-   `dataDir` permissions — fix those rather than thinking the wiki
-   is the problem.
+1. **Internal mode?** Internal workspaces always write to the local
+   filesystem. If you see EPERM there, the real problem is `dataDir`
+   permissions — fix those, not the wiki.
 2. **External mode + `write_strategy=fs`?** The filesystem rejected
    the write. Common causes:
-   - iCloud sandbox (most frequent on macOS).
-   - Read-only volume / snapshot mount.
-   - Filesystem ACL on the parent directory.
-3. **External mode + `write_strategy=cli`?** The probe already fell
-   back to the Obsidian CLI but the CLI is unavailable. See the CLI
-   checklist below.
+   - iCloud sandbox (the most frequent one on macOS).
+   - A read-only volume or snapshot mount.
+   - A filesystem ACL (access-control list) on the parent directory.
+3. **External mode + `write_strategy=cli`?** The write probe already
+   fell back to the Obsidian CLI, but the CLI is unavailable. See the
+   CLI checklist below.
 
 ## The CLI Fallback Path
 
-When direct fs writes fail with `EPERM` / `EACCES` / `EROFS` /
-`EBUSY`, Aitne falls back to the official Obsidian CLI (1.12+).
-Requirements:
+When a direct filesystem write fails with `EPERM` / `EACCES` / `EROFS` /
+`EBUSY`, Aitne falls back to the official Obsidian CLI (1.12 or later).
+For that fallback to work, you need:
 
 - Obsidian installed (1.12 or later).
 - **Settings → General → Command line interface** enabled inside
@@ -89,10 +86,10 @@ If any of these is missing, the daemon surfaces a structured error:
 
 ## Force a Re-Probe
 
-The resolved strategy (`fs` or `cli`) is cached on the workspace row so
-later writes skip the probe. If you've fixed the underlying issue
-(granted iCloud permission, mounted the disk read-write) but the cached
-strategy is still `cli`, force a fresh probe:
+Once a strategy (`fs` or `cli`) is resolved, Aitne caches it on the
+workspace row so later writes can skip the probe. If you've fixed the
+underlying problem (granted iCloud permission, remounted the disk
+read-write) but the cached strategy is still `cli`, force a fresh probe:
 
 1. Open **Settings → Wiki** (`/settings/wiki`) and edit the external
    workspace.

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

@@ -52,6 +52,9 @@ curl -s -X POST http://localhost:8321/api/agents \
       "timezone": "Asia/Tokyo"
     },
     "backend": { "tier": "medium" },
+    "success_criteria": [
+      { "id": "triage-note", "kind": "file_exists", "target": "notes/inbox-triage-{date}.md" }
+    ],
     "prompt": "<the detailed agent definition — see below>"
   }'
 ```
@@ -107,8 +110,15 @@ Fields:
   separate skill copy). **Declare every playbook you name in the prompt's
   `# Important`** — a bare mention is not injected on its own. An unknown slug is
   rejected as `invalid_definition` on field `playbooks`.
+- **`success_criteria`** — optional array of deterministic post-run checks; their
+  hit rate is the Agent's dashboard quality metric. **Derive 1–3 from the prompt's
+  `# Output` contract** (see "Success criteria" below); omitting them when the
+  prompt has an `# Output` section returns a `no_success_criteria` warning.
 - **`prompt`** — the Agent's instructions (the Markdown body). **This is the most
-  important field. Write it in detail.**
+  important field. Write it in detail.** An empty or stub body (`"placeholder"`,
+  `"TODO"`, …) is rejected as `invalid_definition` on field `prompt` — the Agent
+  would skip every run as ambiguous. Never create now to fill the prompt in
+  later; clarify the task with the user first.
 
 ## Writing the `prompt` — the Agent has NO memory of why it exists
 
@@ -150,13 +160,36 @@ 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.
 
+## Success criteria — derive them from `# Output`
+
+`success_criteria` are deterministic checks the daemon evaluates after every
+firing; their hit rate is the Agent's dashboard quality metric — without them
+the Agent has **no quality signal**. Derive 1–3 mechanically from the `# Output`
+contract at creation time:
+
+- Writes a dated note → `{ "id": "note-exists", "kind": "file_exists",
+  "target": "notes/<name>-{date}.md" }`. Targets are vault-relative; `{date}`
+  (the agent-day, resolved at eval time) is the only placeholder.
+- Populates a note with N sections → `{ "id": "sections-filled",
+  "kind": "file_section_count", "target": "…", "heading_level": 2, "min": N }` —
+  counts headings of exactly `heading_level`.
+- DMs the user → `{ "id": "dm-delivered", "kind": "notification_log",
+  "notification_type": "agent", "delivered_within_minutes": M }` — size `M` to
+  the run (30–60 typical). Caveat: matching is install-wide within the window
+  (ANY delivered `"agent"` notification counts, not just this Agent's), so
+  prefer the file-based kinds whenever the output also lands in a file.
+
+`id` values must be unique within the Agent (duplicates are rejected as
+`invalid_definition` on `success_criteria[i].id`).
+
 ## Responses & errors
 
 - `201 { "status": "created", "slug": "…" }` — the Agent is live; its recurring
   schedule is paired and it will fire on the next matching tick. The response may
-  also carry `warnings[]` (non-blocking authoring lint — e.g. an empty prompt, a
-  missing `# Instruction` section, or a playbook you named but didn't declare);
-  the Agent is still created, but fix the flagged issues and re-save its `agent.md`.
+  also carry `warnings[]` (non-blocking authoring lint — e.g. a missing
+  `# Instruction` section, a playbook you named but didn't declare, or an
+  `# Output` contract with no `success_criteria`); the Agent is still created,
+  but fix the flagged issues and re-save its `agent.md`.
 - `400 one_shot_not_supported` — the schedule was not `cron`/`recurring`. Use the
   `schedule` skill for one-time tasks.
 - `400 invalid_recurrence` — a `kind:"recurring"` schedule carried a malformed
@@ -168,7 +201,8 @@ message that would be held anyway.
   `issues[]` (each `{ field, message }`); the post-write cross-check (loader
   rejects the freshly written file) returns `slug` + a single `detail` string
   (or `null`). Read `issues[]` if present, else fall back to `detail`, fix the
-  reported field(s), and resubmit.
+  reported field(s), and resubmit. An empty/placeholder `prompt` also lands
+  here — get the real task from the user, never retry with another stub.
 
 Read `Read`-only files you reference in the prompt to confirm they exist before
 creating the Agent.

package/agent-assets/skills/background-task/SKILL.md

@@ -54,8 +54,9 @@ Resolve ambiguity with the user now, then encode all of:
   reads right if it's sent directly.
 - **Notification policy + criteria** — see below; for `if_significant` the
   criteria MUST be written into the brief in concrete terms.
-- **Expected output** — what a good `result` contains (a per-repo table, a
-  ranked list, a one-paragraph verdict).
+- **Expected output** — 1–5 concretely verifiable requirements (a per-repo
+  table, a ranked list, a one-paragraph verdict). The worker verifies its
+  result against these line-by-line before finishing.
 
 The worker can read owner memory itself to fill in preferences, so you need
 only supply the *task-specific* inputs above. **Promoting an inline task?**
@@ -83,7 +84,7 @@ in the daily digest and the user can pull it (see "Filed results" below).
 |---|---|---|
 | POST | `/api/background-task` | Create + dispatch, or schedule (`scheduleAt`). |
 | GET | `/api/background-task?state=...` | List (also `notify`, `sinceHours` for the filed pull). |
-| GET | `/api/background-task/:id` | The artifact — verbatim `report`, `draft`, `notify`, clarifications. |
+| GET | `/api/background-task/:id` | The artifact — verbatim `report`, `draft`, `notify`, `verification`, clarifications. |
 | POST | `/api/background-task/:id/cancel` | Force-stop. |
 
 Clarifications are answered with the **`background-task-reply`** skill.
@@ -130,6 +131,8 @@ Body:
   The eventual *result delivery* is what respects quiet hours, not the run.
   `202` with `{ taskId, status:"scheduled", scheduledFor, scheduleRowId }`.
   A time more than 60s in the past is rejected `400`.
+- `origin` — Task Board provenance: `"user"` when the user asked for this
+  work, `"agent"` (default) for your own initiative.
 
 Immediate response carries `taskId` and `status`. Then ack once and stop
 (Hard rule 2).
@@ -154,7 +157,9 @@ curl --silent --fail http://localhost:8321/api/background-task/<taskId>
 
 `report` is the full, unparaphrased result. Quote from it; don't invent
 detail. If you lack the `taskId`, list `state=completed` and match by
-`title`.
+`title`. The worker's `verification` checklist rides along — on
+`outcomeDetail` `completed_with_gaps` it shows which requirements fell
+short.
 
 ## Filed results — the "did that monitor ever run?" pull
 

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

@@ -1,6 +1,6 @@
 ---
 name: board
-description: Read-only Task Board — list everything in motion (recurring DMs, Agents, app-fetch, reminders, background/browser/research) via GET /api/tasks, and preview a delete's blast radius via GET /api/tasks/impact. For writes use the `task` skill.
+description: Read-only Task Board — list everything in motion (recurring DMs, Agents, app-fetch, automation triggers, reminders, background/browser work) via GET /api/tasks, and preview a delete's blast radius via GET /api/tasks/impact. For writes use the `task` skill.
 allowed-tools:
   - Bash(curl *)
   - Read
@@ -11,8 +11,9 @@ allowed-tools:
 One place to answer two questions the user actually asks:
 
 1. **"What do I have running / set up?"** — a single inventory across every
-   creation path (recurring DMs, Agents, app-fetch managed tasks, pending
-   one-off reminders, and in-flight background / browser / research work).
+   creation path (recurring DMs, Agents, app-fetch managed tasks, automation
+   triggers, pending one-off reminders, and in-flight background / browser
+   work).
 2. **"What breaks if I delete / change X?"** — the blast radius, with each
    affected row labelled by its real cascade.
 
@@ -40,10 +41,10 @@ Returns `{ items, total, generatedAt }`. Each item:
 
 | Field | Meaning |
 |---|---|
-| `ref` | typed handle — `rs:<id>` (recurring DM), `mt_<n>` (app-fetch), `agent:<slug>`, `as:<id>` (one-off reminder), `bt:<id>` (background), `bx:<id>` (browser), `cluster:<slug>` (research) |
+| `ref` | typed handle — `rs:<id>` (recurring DM), `mt_<n>` (app-fetch), `agent:<slug>`, `trigger:<id>` (automation trigger), `as:<id>` (one-off reminder), `bt:<id>` (background), `bx:<id>` (browser) |
 | `title` | human label — passed through verbatim from the owning row |
-| `kind` | `dm` / `agent` / `app_fetch` / `reminder` / `background` / `browser` / `research` |
-| `status` | `active` / `paused` / `pending` / a fulfiller state (`running`, `awaiting_user`, …) |
+| `kind` | `dm` / `agent` / `app_fetch` / `trigger` / `reminder` / `background` / `browser` |
+| `status` | `active` / `paused` / `pending` / `running` (incl. an Agent with a turn in flight) / a fulfiller state (`awaiting_user`, …) |
 | `cadence` | human schedule label, or null for one-shot work |
 | `fulfilledBy` | typed ref of the row that actually executes (for `app_fetch`, its `rs:` schedule) |
 | `origin` | `system` / `user` / `agent` |
@@ -87,7 +88,5 @@ specialised skills (`agent-create`, `managed-tasks`, `schedule`,
 
 1. **Localhost only.** `http://localhost:8321/api/tasks*`.
 2. **Read-only.** This skill issues only GETs. Never mutate from here.
-3. **Never reactivate a muted/concluded research cluster** by listing it — the
-   board only surfaces active/dormant clusters and `impact` never changes status.
-4. **Never read or relay a browser-task final-confirm token.** The board surfaces
+3. **Never read or relay a browser-task final-confirm token.** The board surfaces
    only safe fields (`status`/`ref`); a pending `!~xxxxxxxx` token is never shown.

package/agent-assets/skills/browser-task/SKILL.md

@@ -81,6 +81,8 @@ Body:
   pre-generated id you use for status GETs).
 - `requireFinalConfirm` (default `true`) — keep `true` unless the user
   explicitly asks to skip the gate for a reversible flow.
+- `origin` — Task Board provenance: `"user"` when the user asked for this
+  work, `"agent"` (default) for your own initiative.
 
 Immediate response carries `taskId`, `status`, and `queueState`; then ack
 once and stop (Hard rule 2). If `queueState.waitingForSlot === true`, the

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

@@ -8,6 +8,7 @@
     { "path": "journal/monthly/*.md", "purpose": "monthly review snapshots (YYYY-MM)", "sections": [{ "heading": "## Theme", "contains": "the month's overall theme" }] },
     { "path": "policies/*.md", "purpose": "user-controlled policy files", "sections": [{ "heading": "## Why", "contains": "rationale for the rule" }, { "heading": "## How", "contains": "concrete rule shape" }] },
     { "path": "identity/*.md", "purpose": "user identity and preferences dictionary", "sections": [{ "heading": "## Identity", "contains": "name role tz" }] },
-    { "path": "journal/agent.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" }] },
+    { "path": "knowledge/sources/*/*.md", "purpose": "source-document cards: summaries of user-sent files (PDF/PPTX/docs) stored in the source library; write via the sources skill", "sections": [{ "heading": "# <Title>", "contains": "summary + source_id frontmatter + project link" }] }
   ]
 }

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

@@ -30,10 +30,9 @@ user but compound into duplicate DMs/notifications at fire time.
    the conversation made moot. Else `GET
    /api/schedule?status=pending,running` for one within ±15 min with a
    matching `description`; if found, skip or PATCH.
-3. **Recurring check.** `GET /api/recurring-schedules?enabled=true` to
-   confirm no recurring rule/Agent already covers this cadence (e.g. a
-   daily 09:00 inbox triage, or the morning briefing). If covered, skip.
-   (How recurring work/DMs are created — see "Recurring" below.)
+3. **Recurring check.** `GET /api/recurring-schedules?enabled=true&includeClaimed=true`
+   — confirm no recurring rule/Agent covers this cadence (a `claimedByAgentSlug`
+   row is Agent-owned and counts). If covered, skip (see "Recurring" below).
 4. **`confirm_dedup_key` check (mandatory for `confirm:` sub-flow rows
    only).** When scheduling a `dm_session` row with
    `taskContext.sub_flow="confirm"`, run the dedup pre-check + shape
@@ -222,7 +221,9 @@ model, batch) are in the errors reference below.
   (its fire time can track quiet-hours; PATCH/DELETE edit it). The morning
   briefing is one of these.
 
-`GET /api/recurring-schedules` stays read-only for the dedup pre-check.
+`GET /api/recurring-schedules` stays read-only for the dedup pre-check; `includeClaimed=true`
+keeps Agent-claimed (`claimedByAgentSlug`) + trigger-owned (`claimedByTriggerId`) rows visible.
+Writes on claimed rows: **409** → `/api/agents/<slug>`; trigger-owned → `/api/triggers/<id>`.
 
 ### recurrenceRule grammar — the shared recurrence engine
 

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

@@ -0,0 +1,68 @@
+---
+name: sources
+description: Load to manage the durable source library (user-sent PDFs/PPTX/docs) — list unfiled sources, file them as knowledge/sources/ cards, promote images, or send a stored source back. SKIP for delivering files you generated this turn (attach) or general vault edits (context).
+allowed-tools:
+  - Bash(curl *)
+  - Bash(unzip *)
+  - Read
+  - Write
+---
+
+# Source library
+
+Document attachments the user sends (PDF, PPTX, DOCX, XLSX, ODT) are captured automatically into a durable library the moment they arrive — they survive chat pruning. Each source is a ledger row (`src_…` id) plus the original bytes. Your job is the *organization* layer: write a markdown **card** for each source under `knowledge/sources/<collection>/`, link it to projects, and keep the collections tidy.
+
+- **Bash is limited to `curl` and `unzip`, literal arguments only.** No `$VAR` / `$(...)` / pipes / chained commands — anything else is silently denied. Pre-compute values and write literals.
+- Cards are written via the `context` API (this skill shows the calls); the library API below only records metadata and bindings.
+
+## API (all on `http://localhost:8321`)
+
+| Verb | Purpose |
+|---|---|
+| `GET /api/sources?status=unfiled` | List sources awaiting filing (also `filed`, `archived`; `limit`/`offset`). |
+| `GET /api/sources/<id>` | One source's metadata (filename, mime, size, caption, provenance, cardPath). |
+| `GET /api/sources/<id>/file` | The original bytes. Save to the workdir: `curl -s -o ./src-deck.pdf http://localhost:8321/api/sources/<id>/file` |
+| `POST /api/sources/promote` | Capture a chat attachment the auto-capture skipped (images, audio): `{"attachmentId":"<uuid>","caption":"…"}`. Returns the `src_…` id (`deduped:true` if already stored). |
+| `PATCH /api/sources/<id>` | Record the filing: `{"cardPath":"knowledge/sources/<collection>/<slug>.md"}` (implies `status:"filed"`). Also `{"status":"archived"}` for junk, `{"caption":"…"}`. |
+| `POST /api/sources/<id>/export` | Copy the original binary into the user's external Obsidian vault: `{"target":"obsidian"}`. Lands at `sources/<file>` with a companion note embedding it (`{"note":false}` to skip). 409 if no external vault is configured. For **Notion**, there is no binary path — create a page from the card markdown via `POST /api/notion/pages` instead. |
+
+Errors use the standard agent-error envelope; `404 sources.not_found` means a stale id — re-list. Never DELETE a source; archive instead (deletion is owner-only).
+
+## Filing a source (the core loop)
+
+1. `GET /api/sources?status=unfiled` — pick a source.
+2. Understand it. PDFs: fetch the bytes to the workdir and `Read` the file directly. PPTX/DOCX are zip archives of XML — best-effort text peek with `unzip -p ./src-deck.pptx ppt/slides/slide1.xml` (one file per call, no pipes; read the text between the XML tags in the output). If `unzip` is unavailable on this platform, fall back to filename + caption — they often suffice.
+3. Choose a collection per the taxonomy below (create a new one only when nothing fits).
+4. Write the card:
+
+```bash
+curl -s -X PUT http://localhost:8321/api/context/knowledge/sources/acme-launch/pitch-deck.md \
+  -H "Content-Type: application/json" \
+  -d '{"content":"---\ntype: source\nowner: agent\nupdated: 2026-07-01\nsource_id: src_1234\nmime: application/pdf\nreceived: 2026-07-01\nprovenance: user_telegram\n---\n# Acme launch pitch deck\n\nOne-paragraph summary of what the document contains and why the user sent it.\n\nProject: [[acme-launch]]\n"}'
+```
+
+5. Bind it: `curl -s -X PATCH http://localhost:8321/api/sources/src_1234 -H "Content-Type: application/json" -d '{"cardPath":"knowledge/sources/acme-launch/pitch-deck.md"}'`
+6. If the source belongs to a project, add a `- [[knowledge/sources/acme-launch/pitch-deck|Pitch deck]]` line under a `## Sources` heading in `plans/projects/<slug>.md` (PATCH, append mode).
+7. Keep `knowledge/sources/_index.md` current: one line per collection with a one-phrase scope.
+
+## Reorganizing
+
+Move a card = PUT the card at the new path, DELETE the old path (`curl -X DELETE http://localhost:8321/api/context/knowledge/sources/old/card.md`), then PATCH the source's `cardPath`. Deletes are snapshotted — recoverable. Merge singleton collections into broader ones; split collections past ~15 cards.
+
+## Sending a source back to the user
+
+Fetch the bytes to the workdir, then deliver through the outbound endpoint (see the `attach` skill for limits):
+
+```bash
+curl -s -o ./src-deck.pdf http://localhost:8321/api/sources/src_1234/file
+curl -s -X POST http://localhost:8321/api/chat/outbound-attachments \
+  -H "X-Filename: pitch-deck.pdf" -F "file=@./src-deck.pdf"
+```
+
+## Collection taxonomy (auto-curated)
+
+<!-- CURATION:knowledge_layout id="source-collections" -->
+
+## Filing conventions (auto-curated)
+
+<!-- CURATION:convention_notes id="filing-rules" -->

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

@@ -0,0 +1,21 @@
+{
+  "version": 1,
+  "sections": [
+    {
+      "id": "source-collections",
+      "kind": "knowledge_layout",
+      "anchor": "<!-- CURATION:knowledge_layout id=\"source-collections\" -->",
+      "human_label": "Source collection taxonomy",
+      "description": "Current collections under knowledge/sources/ and what belongs in each",
+      "scope_paths": ["knowledge/sources/**"]
+    },
+    {
+      "id": "filing-rules",
+      "kind": "convention_notes",
+      "anchor": "<!-- CURATION:convention_notes id=\"filing-rules\" -->",
+      "human_label": "Source filing conventions",
+      "description": "Card slug grammar, card body shape, and project cross-linking rules",
+      "scope_paths": ["knowledge/sources/**"]
+    }
+  ]
+}

package/agent-assets/skills/sources/seeds/filing-rules.seed.json

@@ -0,0 +1,25 @@
+{
+  "kind": "convention_notes",
+  "notes": [
+    {
+      "topic": "Card slug",
+      "rule": "Lowercase [a-z0-9._-], descriptive of the document content, not the filename (strip dates/version noise unless meaningful).",
+      "example": "knowledge/sources/acme-launch/pitch-deck.md for 'Acme_Pitch_FINAL_v3 (2).pdf'"
+    },
+    {
+      "topic": "One card per source",
+      "rule": "Exactly one card per src_ id; on dedup (same file re-sent) update the existing card's `updated:` instead of writing a second card.",
+      "example": "receive_count > 1 on GET /api/sources/<id> means the user re-sent the same bytes"
+    },
+    {
+      "topic": "Collection choice",
+      "rule": "Prefer a collection matching an active project slug; use a topical collection for project-less documents; reserve `inbox` for the genuinely unclassifiable.",
+      "example": "a tax PDF with no project goes to knowledge/sources/finance/, not inbox"
+    },
+    {
+      "topic": "Project cross-link",
+      "rule": "When a source supports a project, the project file gets a `## Sources` bullet linking the card — the card alone is not discoverable from the project side.",
+      "example": "plans/projects/acme-launch.md gains: - [[knowledge/sources/acme-launch/pitch-deck|Pitch deck]]"
+    }
+  ]
+}

package/agent-assets/skills/sources/seeds/source-collections.seed.json

@@ -0,0 +1,20 @@
+{
+  "kind": "knowledge_layout",
+  "files": [
+    {
+      "path": "knowledge/sources/_index.md",
+      "purpose": "Directory of collections — one line per collection with its one-phrase scope",
+      "sections": [
+        { "heading": "## Collections", "contains": "bullet list: - [[<collection>]] — what belongs there" }
+      ]
+    },
+    {
+      "path": "knowledge/sources/*/*.md",
+      "purpose": "One card per stored source document; collections usually mirror an active project slug from plans/projects/",
+      "sections": [
+        { "heading": "# <Title>", "contains": "H1 naming the document in plain words" },
+        { "heading": "(body)", "contains": "one-paragraph summary, why the user sent it, and a Project: [[<slug>]] link when one applies" }
+      ]
+    }
+  ]
+}

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

@@ -44,8 +44,11 @@ the front door; the specialised skills are the manual.
 ## Edit / delete — `PATCH` / `DELETE /api/tasks/<ref>`
 
 Address the row by its typed `ref` from the board (`rs:<id>`, `mt_<n>`,
-`agent:<slug>`, `as:<id>`). PATCH forwards your patch body to the owning edit
-endpoint; DELETE forwards to the owning delete (cascade preserved).
+`agent:<slug>`, `as:<id>`, `trigger:<id>`). PATCH forwards your patch body to
+the owning edit endpoint; DELETE forwards to the owning delete (cascade
+preserved). A `trigger:` write routes to `/api/triggers/<id>` (Approve tier;
+`401` = needs the dashboard's authorization; no facade create kind) and its
+delete removes the paired recurring schedule too.
 
 ```bash
 curl --silent --fail -X PATCH -H 'Content-Type: application/json' \

package/agent-assets/task-flows/background_task.md

@@ -44,8 +44,8 @@ notification policy. Read it carefully and satisfy it end to end.
 
 ## Finishing — the artifact (read this carefully)
 
-`finish(result, draft, notify, significance?)` is the only thing the
-owner ever sees the effect of. Each field has a distinct job:
+`finish(result, draft, notify, verification, significance?)` is the only
+thing the owner ever sees the effect of. Each field has a distinct job:
 
 - **`result`** — the FULL, verbatim outcome: every finding, number, URL,
   id, quote. This is persisted unchanged and is what a precise follow-up
@@ -67,15 +67,41 @@ owner ever sees the effect of. Each field has a distinct job:
     the brief. If the criteria are not met, `notify = false`.
   - `silent` → `notify = false`.
   - When you are on `always` and unsure, prefer `true`.
+- **`verification`** *(required)* — your self-verification checklist: 1–10
+  `{requirement, met, evidence}` items (see "Self-verification before
+  finish" below). Any `met=false` automatically appends a gap disclosure
+  to your `draft` and records the completion as `completed_with_gaps` —
+  you do not need to (and cannot) hide a gap.
 - **`significance`** *(optional)* — one line on why notify is true/false
   ("2 repos red" / "no criteria met"). Used for the audit + the
   filed-results digest.
 
+## Self-verification before finish
+
+Before calling `finish`, verify your own result against the brief:
+
+1. **Derive a checklist** from the brief's **Expected output** section
+   (fallback: the Objective) — 1–10 concrete requirements, each stated in
+   ≤300 chars.
+2. **Verify each item against your ACTUAL result**, not your intent.
+   `evidence` must point at something real in `result` ("table has one
+   row per repo, all 6 listed"), never a restatement of the requirement.
+3. **If a requirement is unmet and you have turn budget left, attempt the
+   repair FIRST** — go back, gather what is missing, then re-verify.
+4. Finish with `met=false` only when you genuinely cannot fix it (source
+   unavailable, out of scope, budget exhausted). Say what is missing and
+   why in `evidence`.
+
+Never claim `met=true` your evidence does not support: any unmet item is
+disclosed to the owner automatically, but a false "met" is a silent lie
+the owner will act on.
+
 ## Typical loop
 
 ```
 1. (optional) read_memory(...)            # pull owner context you need
 2. WebSearch / WebFetch / reason          # do the actual work
 3. (only if blocked) ask_user(...)        # then STOP this turn
-4. finish(result=<full>, draft=<summary>, notify=<policy eval>, significance=<one line>)
+4. self-verify vs the brief's Expected output; repair gaps if budget remains
+5. finish(result=<full>, draft=<summary>, notify=<policy eval>, verification=<checklist>, significance=<one line>)
 ```