@aitne-sh/aitne 0.1.11 → 0.1.13

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>"
   }'
 ```
@@ -100,8 +103,22 @@ Fields:
   the standalone control that works). `process_key` defaults to `agent.task`;
   omit unless you know you need another. (Pinning a backend *engine* without a
   `model` is a known no-op — prefer `tier`.)
+- **`playbooks`** — optional array of operating-playbook slugs to inject into the
+  Agent's prompt at fire time: `research`, `markdown-note`, `monitoring`. Declaring
+  one makes the daemon inject that playbook's full methodology into every run — a
+  hard guarantee, and the only way the methodology reaches the Agent (there is no
+  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
 
@@ -110,48 +127,69 @@ Fields:
 > management rules). It does NOT remember this conversation or why you created
 > it. An under-specified prompt produces a vague, drifting Agent.
 
-Write the prompt as a self-contained brief covering all four:
+Author every Agent prompt with the **canonical frame** below, and resolve any
+missing required slot with the user *before* you `POST /api/agents` (clarify-back).
 
-| Element | What it must answer |
-|---|---|
-| **Requirements / preconditions** | What must be true / what inputs to read first (files, APIs, accounts). What to do if a precondition is missing. |
-| **Goal** | The single outcome this Agent exists to produce, stated concretely. |
-| **Process** | The ordered steps to run each firing — specific verbs, endpoints, filenames, decision rules. |
-| **Expected output** | What "done" looks like: which file/section is written, whether/when to DM the user, what NOT to do. |
+{{> ref:prompt-frame }}
 
-**Good prompt (excerpt):**
-```
-## Goal
-Each morning, surface inbox items that need the user's decision today.
-
-## Requirements
-- Read state/today.md for the day's agenda before triaging.
-- Mail access via the mail skill endpoints; if mail is unreachable, log the gap
-  to the Agent Log and exit without DMing.
-
-## Process
-1. GET unread mail from the last 24h.
-2. Classify: actionable-today / FYI / ignore (rules: …).
-3. Append a "## Inbox triage" section to state/today.md with the actionable set.
-4. DM the user ONLY if ≥1 item is time-sensitive today.
-
-## Output
-- today.md updated with the triage section.
-- At most one DM, sent only for time-sensitive items.
+### Declare the playbooks you reference
+
+Whenever the prompt's `# Important` names a playbook, ALSO list its slug in the
+top-level `playbooks` field so the daemon injects that methodology into every
+firing as a hard guarantee — not just a by-reference skill the Agent might skip:
+
+```json
+"playbooks": ["research", "markdown-note"]
 ```
 
-**Bad prompt:** `"Triage my inbox."` — no requirements, no steps, no output
-contract; the Agent will improvise differently every day.
+Valid slugs: `research`, `markdown-note`, `monitoring`. If you name a playbook in
+the prompt but forget to declare it, the create response returns a `warnings[]`
+entry (`playbook_referenced_not_declared`) — read it and add the missing slug.
+
+### Operational (state-mutating) Agents — extend the frame
+
+Most Agents are content / knowledge agents (research, monitoring, note) and the
+core frame above is the right shape. When the Agent instead **mutates code, files,
+or system state** — the general-purpose archetype — extend the frame with scope,
+a run-time autonomy boundary, and a verification receipt:
 
-The Expected-output decision feeds one schedule field: if the output contract
+{{> ref:prompt-frame-extended }}
+
+The `# 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.
 
+## 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.
+  schedule is paired and it will fire on the next matching tick. The response may
+  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
@@ -163,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/agent-create/references/prompt-frame-extended.md

@@ -0,0 +1,132 @@
+---
+kind: reference
+name: prompt-frame-extended
+description: The extended prompt frame for operational / state-mutating agents (code, files, system state) — adds Goal / Context / Inputs / Scope / Execution Mode / Requirements / Constraints / Verification and a structured Output receipt on top of the core frame, plus the operational clarify-back slot.
+---
+
+### When to reach for the extended frame
+
+Use it when the agent **mutates code, files, or system state**, or runs a
+multi-step engineering-flavored task (the *general-purpose* agents). Content /
+knowledge agents (research, monitoring, note) stay on the **core** frame — their
+verification and output shape come from the playbooks, so they never carry the
+sections below. Forcing this scaffolding onto a content agent is empty boilerplate
+that dilutes the real instruction and eats the 8000-char cap.
+
+Add these on top of the core `# Role` / `# Important` / `# Instruction`:
+
+```markdown
+# Goal              # the outcome this agent exists to produce (fold into # Role if one line)
+# Context           # background, why it matters, the spec / state to read first
+# Inputs            # concrete artifacts: files, paths, URLs, repos, prior-run note, error logs
+# Role
+Act as a careful <engineer / researcher / reviewer / editor>.
+Prioritize <correctness / minimal change / source-backed claims / maintainability>.
+# Scope             # WHERE it may act
+Do:     - <in-scope actions / the editable surface>
+Do not: - <areas, files, or data it must not touch>
+# Execution Mode    # WHEN to act vs escalate
+Proceed autonomously after reading the relevant context.
+Escalate instead of acting when an action is outward-facing or irreversible
+(send / publish / pay / delete), a data / schema migration, a broad refactor, or
+the requirements are materially contradictory.
+On escalation: if the user is reachable, DM a concise approval request and defer the
+action; if running unattended, record the proposed action + reason and skip it.
+# Requirements      # success conditions
+- <condition 1> ...
+# Constraints       # behavioral prohibitions not already in Scope / Execution Mode
+- No speculative changes; preserve behavior outside the requested scope; no new
+  dependencies unless clearly necessary; do not remove existing tests / validation.
+# Verification
+- Run the checks relevant to what changed: code → tests / typecheck / lint;
+  research → cross-check each claim against ≥ 2 sources.
+- Don't claim verification unless the checks passed; if they can't be run, say why.
+# Output            # structured receipt for the user to review
+1. Summary of what was done
+2. Files changed / sources used
+3. Checks run + results
+4. Assumptions made
+5. Remaining risks / follow-ups
+```
+
+Three rules keep the extended frame from sprawling (over-specification — the same
+prohibition restated three times — is its main failure mode):
+
+- **One prohibition, one section** — spatial → `# Scope`, risk / timing →
+  `# Execution Mode`, behavioral → `# Constraints`. Never restate "don't touch
+  unrelated files" in all three.
+- **Fold short sections up** — an empty `# Goal` / `# Context` / `# Constraints` is
+  omitted, not left as a stub (`# Goal` folds into `# Role` when it's one line).
+- **Content archetypes stay on the core frame** — never give a research / note
+  agent `# Verification` or receipt scaffolding.
+
+#### `# Execution Mode` — the run-time autonomy boundary
+
+Clarify-back (below, and in the core frame) resolves ambiguity at **authoring**
+time, with the user present. `# Execution Mode` governs the **deployed** agent at
+**run** time, usually with no user present — the gap where an agent that hits a risk
+boundary mid-run has no instruction. Encode the product's posture: act on the safe,
+reversible majority; on the risky minority **defer + flag** (DM an approval request,
+hold the action) when the user is reachable, or **record + skip** when unattended.
+Never guess, never block waiting.
+
+### Clarify-back — the operational slot
+
+On top of the content-archetype slots in the core frame, an operational agent has
+its own required slots:
+
+| Archetype | Required slots (ask only if unknown) | Sensible default |
+|---|---|---|
+| **General / operational** (code, files, system state) | editable surface / scope; what "done" means (success criteria); may it act autonomously or propose-then-confirm; which checks to run | propose-then-confirm for irreversible / outward actions; run the repo's standard checks; deliver as a branch / PR or draft, not a direct commit / send |
+
+### Worked example — an operational agent
+
+A recurring "keep the repo green" agent, extended frame end-to-end:
+
+```markdown
+# Goal
+Keep <repo> free of lint and type errors introduced during the day.
+
+# Context
+CI runs lint + typecheck on every PR; errors on `develop` block everyone. You run
+nightly to catch and fix what slipped in.
+
+# Inputs
+- Repo: <org/repo>, branch `develop`.
+- Commands: `pnpm lint`, `pnpm typecheck` (project root).
+
+# Role
+Act as a careful engineer. Prioritize minimal, behavior-preserving changes.
+
+# Scope
+Do:     fix lint / type errors in app source under `packages/`.
+Do not: touch test fixtures, generated files, or `*.config.*`; change runtime behavior.
+
+# Execution Mode
+Proceed autonomously for mechanical fixes. Escalate (open a draft PR + DM, do not
+merge) if a fix needs a behavior change, touches a public API, or the error count is
+> 30 (likely a systemic cause to confirm first). Running unattended: never merge —
+always deliver as a PR for review.
+
+# Requirements
+- `pnpm lint` and `pnpm typecheck` both pass after your changes.
+- One PR titled `nightly: lint+type sweep <YYYY-MM-DD>`.
+
+# Constraints
+- No new dependencies; no disabling of rules to silence errors; do not remove tests.
+
+# Verification
+- Run `pnpm lint` and `pnpm typecheck`; include the final output in the receipt.
+- If either still fails, leave those errors unfixed and list them — don't claim green.
+
+# Output
+1. Summary of what was fixed.
+2. Files changed (+ the PR link).
+3. `pnpm lint` / `pnpm typecheck` results.
+4. Assumptions made.
+5. Remaining errors / follow-ups.
+```
+
+**Bad:** `"Keep the repo green nightly."` — no scope (which files?), no autonomy
+boundary (merge or PR?), no verification contract. An agent with write access and
+no `# Scope` / `# Execution Mode` is how unattended automation does damage.

package/agent-assets/skills/agent-create/references/prompt-frame.md

@@ -0,0 +1,125 @@
+---
+kind: reference
+name: prompt-frame
+description: The canonical core prompt frame (# Role / # Important / # Instruction / # Output), the operating-playbook references, and the clarify-back gate the DM agent uses to author a deployed agent's prompt. Shared byte-identical between agent-create and schedule.
+---
+
+### The core frame
+
+Author the deployed agent's prompt as this Markdown skeleton. It is classic,
+model-agnostic structure and reads identically under every backend. Keep it well
+under the 8000-char cap — durable methodology lives in the playbooks (below), not
+inlined here.
+
+```markdown
+# Role
+You are <agent identity>. Every <cadence> you <the single outcome this agent exists for>.
+
+# Important
+- <hard constraints & rules to uphold>
+- Preconditions: read <inputs> first; if <precondition> is missing, <fallback> and do not guess.
+- Do NOT <the things that would make the output wrong or unsafe>.
+- <playbook reference — name the methodology you'll follow, e.g. "Follow the research playbook.">
+
+# Instruction
+1. <ordered, concrete step — specific verb + endpoint / filename / decision rule>
+2. <step — include a worked EXAMPLE wherever a step is non-obvious>
+   e.g. "Classify each item actionable-today / FYI / ignore — 'PR review requested' → actionable-today; a newsletter → ignore."
+3. ...
+
+# Output
+- <format & destination: which file / section, frontmatter, append-vs-new-file, when/whether to DM>
+- <if writing a note, say "follow the markdown-note playbook for structure">
+- (Omit this section only when the task produces no durable artifact and no DM.)
+```
+
+Rules that make the difference between a sharp agent and a drifting one:
+
+- **`# Instruction` steps must include concrete examples.** A step the agent could
+  read two ways needs a worked example pinning the intended one. Vague steps are
+  the #1 cause of a drifting agent.
+- **`# Important` is the guardrail section** — preconditions, fallbacks, the
+  explicit "do NOT" list, and the playbook reference all live here. Don't scatter
+  guardrails across the other sections.
+- **The deployed agent has no memory of this conversation.** Everything it needs is
+  in the prompt or in a playbook it is told to follow — nothing else carries over.
+
+Migrating from the old four-element skeleton:
+
+| Old element | New home |
+|---|---|
+| Goal | `# Role` (identity + the single outcome) |
+| Requirements / preconditions | `# Important` (preconditions + fallbacks) |
+| Process | `# Instruction` (ordered steps, **with examples**) |
+| Expected output | `# Output` |
+| guardrails / "what NOT to do" | `# Important` |
+
+### Operating playbooks (never inline the full text)
+
+Durable methodology lives in the operating playbooks, kept central so a single
+update reaches every agent. Do NOT paste a playbook's full content into the prompt
+— that copy would silently go stale. How the methodology reaches the run depends
+on the path:
+
+- **Recurring Agent** (agent definition): name the playbook in `# Important` AND
+  declare its slug in the top-level `playbooks:` field. The daemon then injects the
+  full methodology into every run — the single, guaranteed copy in the prompt.
+- **One-off task** (`/schedule`): there is no `playbooks:` field and no injection.
+  Fold the handful of steps you actually need straight into `# Instruction`; a
+  run-once task has no staleness concern, so inlining is the right call here.
+
+| If the agent's job is… | Name this playbook in `# Important` | Also |
+|---|---|---|
+| Research a topic and report | "Follow the **research** playbook." | + markdown-note if it writes a note |
+| Watch something and report changes | "Follow the **monitoring** playbook." | + markdown-note for the rolling note |
+| Produce / update a free-form topic note | "Follow the **markdown-note** playbook." | — |
+
+The markdown-note playbook governs *free-form topic notes only* — never the
+structured context-vault files (today.md, journal, roadmap), which keep their own
+schemas.
+
+### Clarify-back before you deploy
+
+If a required slot for the agent's archetype is unknown from the conversation, ask
+the user **one consolidated question** before creating the agent — never guess. (The
+runtime drops an ambiguous task rather than salvaging it, so ambiguity has to be
+resolved now.) Batch all missing slots into a single message and pair each with a
+sensible **default** the user can accept in one tap. Ask only *missing, required*
+slots — don't interrogate.
+
+| Archetype | Required slots (ask only if unknown) | Sensible default |
+|---|---|---|
+| **Research** | topic/scope; what you mainly want (a decision? situational awareness? specific sub-questions?); depth (how many angles/sources); output destination (Obsidian note? DM? both); cadence + time | medium depth (3–5 angles); Obsidian note + short DM digest |
+| **Monitoring / digest** | what to watch; what counts as a noteworthy change; where to record; notify threshold (always vs only-on-change) | notify only on material change; record to a rolling note |
+| **Any task writing a note** | destination path; title pattern; append-to-existing vs new-file-per-run | new dated file under the topic folder |
+
+### Worked example — a content agent
+
+**Good** (research → note; core frame + playbook references):
+
+```markdown
+# Role
+You are the user's AI-news researcher. Every morning you produce a verified digest
+of the most important AI developments from the last 24h.
+
+# Important
+- Read context/research/ai-news.md for what you already reported; don't repeat it.
+- Follow the **research** playbook for method + source verification, and the
+  **markdown-note** playbook for the note's shape.
+- Do NOT include a claim backed by a single source without marking it "(single source)".
+
+# Instruction
+1. Pick 3–5 distinct angles not already covered in the existing note.
+2. For each angle, find 2–4 authoritative sources with WebSearch; open the top 1–2
+   in full if the agent has page-fetch access (a standard scheduled agent does not).
+   e.g. for "model releases" prefer the lab's own post over a news aggregator.
+3. Cross-check every material claim against ≥ 2 sources before including it.
+
+# Output
+- Write context/research/ai-news/<YYYY-MM-DD>-digest.md per the markdown-note playbook.
+- DM the user the 2–4 sentence "what matters" summary + the note path.
+```
+
+**Bad:** `"Research the latest AI news every morning and send me a summary."` — no
+preconditions, no method, no source bar, no output contract; the agent improvises
+differently (and shallowly) every day.

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,14 +84,14 @@ 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.
 
 ## Hard rules
 
-1. **Localhost only.** `http://127.0.0.1:8321/api/background-task/*`.
+1. **Localhost only.** `http://localhost:8321/api/background-task/*`.
 2. **POST, ack, end the turn. NEVER poll for completion.** After a
    successful POST, reply once and stop. Do NOT GET `/:id` in a loop or
    "wait and check". Ending your turn has zero effect on the detached
@@ -110,7 +111,7 @@ Clarifications are answered with the **`background-task-reply`** skill.
 ```bash
 curl --silent --fail -X POST -H 'Content-Type: application/json' \
   -d '{"brief":"Audit these repos for a red main-branch CI build: aitne/daemon, aitne/web. \"Failing\" = the latest default-branch run concluded failure. Summary in English. Only notify if at least one repo is red. Output: one line per failing repo with the job.","title":"CI audit","notificationPolicy":"if_significant"}' \
-  http://127.0.0.1:8321/api/background-task
+  http://localhost:8321/api/background-task
 ```
 
 Body:
@@ -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).
@@ -149,12 +152,14 @@ detail it didn't include ("what exactly did it find on repo X?", "show me
 the numbers"), do a **single** read and answer from the verbatim `report`:
 
 ```bash
-curl --silent --fail http://127.0.0.1:8321/api/background-task/<taskId>
+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
 
@@ -162,7 +167,7 @@ A `silent` / unmet-`if_significant` result is filed (`notify=false`), not
 pushed. When the user asks whether a backgrounded task ran:
 
 ```bash
-curl --silent --fail "http://127.0.0.1:8321/api/background-task?state=completed&notify=false&sinceHours=168"
+curl --silent --fail "http://localhost:8321/api/background-task?state=completed&notify=false&sinceHours=168"
 ```
 
 Each row carries `title`, `significance`, and `report`. Summarize

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

@@ -65,7 +65,7 @@ user-visible text** (token hygiene). The GET is the authoritative source.
 ```bash
 curl --silent --fail -X POST -H 'Content-Type: application/json' \
   -d '{"clarificationId":"<uuid>","answer":"api first"}' \
-  http://127.0.0.1:8321/api/background-task/<taskId>/clarify
+  http://localhost:8321/api/background-task/<taskId>/clarify
 ```
 
 - `answer` (1..8192) — the owner's reply, verbatim and faithful. Do not
@@ -96,5 +96,5 @@ Status codes — handle each, don't retry blindly:
 
 ## Localhost only
 
-`http://127.0.0.1:8321/api/background-task/*`. JSON body in single quotes
+`http://localhost:8321/api/background-task/*`. JSON body in single quotes
 (project convention) so the daemon hooks classify the payload as data.

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

@@ -0,0 +1,92 @@
+---
+name: board
+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
+---
+
+# Task Board — see everything in motion
+
+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, 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.
+
+The board is **read-only and computed on demand** — it stores nothing and
+mirrors nothing. It does **not** replace the proactive reminder surface: pending
+one-off reminders are already injected into your DM context every turn, so use
+the board when the user *asks* to look, not as a standing checklist.
+
+## When to use
+
+- The user asks what's scheduled / running / set up ("show me my agents",
+  "what's running", "do I still have that Zoom sweep?").
+- Before a delete/modify, to tell the user the impact ("if I stop the digest,
+  what goes with it?").
+- To resolve a vague reference ("turn off the morning thing") to a concrete
+  `ref` you can then act on with the `task` skill.
+
+## Inventory — `GET /api/tasks`
+
+```bash
+curl --silent --fail http://localhost:8321/api/tasks
+```
+
+Returns `{ items, total, generatedAt }`. Each item:
+
+| Field | Meaning |
+|---|---|
+| `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` / `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` |
+| `lastResult`, `lastRunAt`, `nextRunAt` | at-a-glance health, when the owner tracks them |
+
+Summarise naturally; don't read the JSON back verbatim. The `kind` / `status`
+/ `cadence` labels are a fixed English vocabulary; `title` is passed through
+verbatim from the owning row.
+
+## Blast radius — `GET /api/tasks/impact?ref=<ref>`
+
+```bash
+curl --silent --fail "http://localhost:8321/api/tasks/impact?ref=mt_3"
+```
+
+Returns `{ ref, found, summary, nodes }`. Each node is a row a delete/modify
+would touch, with its real cascade semantics:
+
+- `is_a_cascade` — a 1:1 wrapper deleted **with** the target (a managed task and
+  its recurring schedule die together).
+- `set_null_satellite` — an Agent or automation trigger that **references** the
+  schedule and **survives** its deletion.
+- `owner_paired_schedule` — an Agent's **own** recurring schedule (shown when the
+  target is `agent:<slug>`): disabled with the Agent, removed only on hard-delete.
+- `no_action_unlinked` — pending fires that are unlinked/skipped, not deleted.
+- `self` — the target row itself.
+
+`found:false` (still `200`) means the ref resolves to no live row. Lead with the
+`summary`, then list what survives vs what's removed so the user can decide.
+
+## Writes go through the `task` skill
+
+This skill never creates, edits, or deletes. When the user wants to act on a
+board item, hand the resolved `ref` (or a `kind` for a new item) to the **`task`**
+skill, which routes the write to the hardened owner endpoint. Detailed authoring
+(a full recurring Agent, an app-fetch with dedup) still belongs to the
+specialised skills (`agent-create`, `managed-tasks`, `schedule`,
+`background-task`) — `task` is the single front door to them.
+
+## Hard rules
+
+1. **Localhost only.** `http://localhost:8321/api/tasks*`.
+2. **Read-only.** This skill issues only GETs. Never mutate from here.
+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-history/SKILL.md

@@ -15,7 +15,7 @@ their own destination policy — see the cluster-update flow below.
 ## Hard rules
 
 1. **Localhost only.** Every request goes to
-   `http://127.0.0.1:8321/api/browser-history/*` (or `localhost`).
+   `http://localhost:8321/api/browser-history/*`.
    A curl to any other host is a contract violation and the daemon's
    absolute-block layer will reject it.
 2. **No raw SQLite.** Never invoke `sqlite3`, never `Read` a path under
@@ -75,7 +75,7 @@ so do NOT add an auth header to it.)
 
 ```bash
 curl --silent --show-error \
-  http://127.0.0.1:8321/api/browser-history/research-clusters
+  http://localhost:8321/api/browser-history/research-clusters
 ```
 
 Use `--silent --show-error` (not `--fail`): the agent's `curl` runs
@@ -94,7 +94,7 @@ curl --silent --show-error \
   -X POST \
   -H 'Content-Type: application/json' \
   -d '{"kind":"research_assist"}' \
-  http://127.0.0.1:8321/api/browser-history/offers/quantum-mechanics/accept
+  http://localhost:8321/api/browser-history/offers/quantum-mechanics/accept
 ```
 
 ## Flow: routine.research_cluster_update

package/agent-assets/skills/browser-history-respond/SKILL.md

@@ -87,15 +87,15 @@ pre-summarise.
 
 ```bash
 curl --silent --fail \
-  http://127.0.0.1:8321/api/browser-history/offers/pending
+  http://localhost:8321/api/browser-history/offers/pending
 
 curl --silent --fail -X POST \
   -H 'Content-Type: application/json' \
   -d '{"kind":"research_assist"}' \
-  http://127.0.0.1:8321/api/browser-history/offers/<slug>/accept
+  http://localhost:8321/api/browser-history/offers/<slug>/accept
 
 curl --silent --fail -X POST \
-  http://127.0.0.1:8321/api/browser-history/offers/<slug>/decline
+  http://localhost:8321/api/browser-history/offers/<slug>/decline
 ```
 
 JSON body in single quotes (project convention) so the daemon hooks

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

@@ -21,7 +21,7 @@ B-4 purchase tokens, or workflow approvals — those live under
 
 ## Hard rules
 
-1. **Localhost only.** `http://127.0.0.1:8321/api/browser-task/*`.
+1. **Localhost only.** `http://localhost:8321/api/browser-task/*`.
 2. **POST, ack, end the turn. NEVER poll for completion.** After a
    successful POST, reply once ("Started — I'll report back when it's
    done.") and stop. Do not GET `/:id` in a loop, "wait and check", or
@@ -64,7 +64,7 @@ B-4 purchase tokens, or workflow approvals — those live under
 ```bash
 curl --silent --fail -X POST -H 'Content-Type: application/json' \
   -d '{"description":"Post \"Hello world\" to twitter.com"}' \
-  http://127.0.0.1:8321/api/browser-task
+  http://localhost:8321/api/browser-task
 ```
 
 Body:
@@ -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