@oneie/claude 0.5.0 → 0.7.0

package/skills/directory-autofill/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: directory-autofill
+description: Fill directory-submission forms in the operator's own Chrome via claude-in-chrome, one queued row at a time, with the human approving every submit. Use whenever an operator says "file with agent", "file these directories", "run the directory autofill", or opens the File-with-agent door on the /u/[slug]/directories board. Never clicks submit, never solves a challenge, always stamps filedBy — see HARD RULES.
+---
+
+# directory-autofill — the browser hand for directory submissions
+
+**Purpose:** Turn a run's queued directory rows into filled, human-approved submissions inside the operator's own logged-in Chrome, using the `claude-in-chrome` MCP tools — `tabs_create_mcp` / `navigate` to open the submit page, `read_page` + `find` to locate inputs, `form_input` to fill them, `computer` for a screenshot (there is no `screenshot` tool; screenshots are a `computer` action). Design + data model: `text/directory-submission-plan.md` § The browser hand. The one page this drives: `/u/[slug]/directories`.
+
+## HARD RULES
+
+- **The human owns the submit.** This skill fills a form and stops. It never clicks the directory's submit button, never confirms a modal that finalizes a listing, and never creates an account on the operator's behalf. The operator reviews the filled form and approves the submit themselves.
+- **Never solves a challenge.** Captcha, email verification, phone verification, or any anti-bot step hands control straight back to the human — this skill does not attempt to defeat them. Resume the loop on the next queued row once the human clears it (or skip and move on).
+- **Provenance always.** Every `POST /api/directories/update` call this skill makes carries `filedBy: "agent"`. If a human takes over mid-fill and finishes the submit themselves, the row is recorded `filedBy: "human"` instead — never claim agent credit for a human-finished row.
+- **One generic matcher, zero per-site scripts.** The `DirectoryField` key set is closed — seven shared templates in `registry.ts` (`F_LOCAL`, `F_REVIEW`, `F_B2B`, `F_STARTUP`, `F_AITOOL`, `F_EMAIL`, `F_VERTICAL`) supply every key, and no directory declares fields inline — and packs are deterministic; the only judgment this skill exercises is "which input on this page is *phone*", via label/placeholder/autocomplete-attribute matching. All 306 directories share this one code path. A site that defeats matching gets filed by hand instead — never write a bespoke per-site scraper.
+- **No stored credentials.** Auth to `/api/directories/*` rides the operator's own session, the same way other operator-side skills call the ONE API (`cc-connect`/do-signal pattern). This skill holds no secrets of its own and never asks for or stores a directory's login.
+- **Watched, paced batches.** Work 10–20 queued rows per sitting, not the whole run unattended — the desktop session is the throttle. Directory sites are exactly the sites with captchas and bot detection; a human present in their own browser dissolves both without evading anything.
+
+## The loop
+
+```
+GET /api/directories/run?slug=<slug>&runId=<runId>
+        │  read the frozen packs for queued rows (batch 10–20)
+        ▼
+open directory.submitUrl in a new Chrome tab
+        ▼
+read the page, match each pack.fields[key] onto the
+  closest form input by label / placeholder / autocomplete
+        ▼
+human checkpoint — the operator reviews the filled
+  form and clicks/approves the actual submit
+        ▼
+capture evidence: confirmation text, listing URL if
+  shown, a screenshot
+        ▼
+POST /api/directories/update
+  { slug, id, status: "submitted", filedBy: "agent" }
+  (and, once the listing appears, a later
+   { status: "live", listingUrl } call — evidence, not
+   assertion, per the status walk)
+        ▼
+next queued row · challenge encountered → hand to the
+  human, resume the loop once cleared (or move on)
+```
+
+## Steps
+
+1. **Get the run.** Ask the operator (or read from the board context) which workspace `slug` and `runId` to work. `GET /api/directories/run?slug=<slug>&runId=<runId>` returns `{ submissions: [{ id, directorySlug, status, pack, listingUrl }] }`, where `pack` is the frozen `{ fields, missing }`. Keep each row's `id` — it is the handle every `update` call needs. Only act on rows with `status: "queued"`.
+2. **Look up the directory.** Cross-reference `directorySlug` against `one.ie/web/src/lib/directories/registry.ts`'s `DIRECTORIES` for the `submitUrl`, `method`, and `fields` list — the pack's `fields` map already carries the values, keyed the same as the registry's `DirectoryField.key`s.
+3. **Open and fill.** Navigate to `submitUrl` in the operator's Chrome. For a `method: 'form'` directory, read the page and match each `pack.fields` entry onto the input whose label/placeholder/autocomplete most plausibly matches that key. The twelve keys the templates can emit: `name`, `company`, `address`, `city`, `phone`, `email`, `website`, `url`, `category`, `tagline`, `description`, `pricing`. For a `method: 'email'` directory, draft the email in the operator's mail client instead of a web form, still stopping before send.
+4. **Stop at the human checkpoint.** Once every matchable field is filled, stop and tell the operator plainly: "Form filled for {directory.name} — review and submit when ready." Do not proceed until the operator confirms they submitted it (or tells you to skip).
+5. **Record the evidence.** After the operator confirms, `POST /api/directories/update` with `{ slug, id, status: "submitted", filedBy: "agent" }`. If the directory's confirmation page shows a live listing URL immediately, follow up once confirmed live with `{ status: "live", listingUrl }` — `listingUrl` is required to mark live, and the route 400s without it. If a listing takes longer to appear, leave the row `submitted` — the operator marks it live later from the board.
+6. **Handle challenges and mismatches.** A captcha, email/phone verification loop, or a form the matcher can't confidently map → stop, tell the operator this row needs a by-hand fill from the pack drawer, and move to the next queued row. Never guess a field mapping you're not confident about — an empty field the operator notices beats a wrong value they don't.
+7. **Repeat, paced.** Work through the batch (10–20 rows), then stop and summarize: how many submitted, how many handed to the human, how many skipped and why.
+
+## Failure modes (designed in, not edge cases)
+
+- **No Chrome session / extension not available** — refuse at startup with a plain message; tell the operator the pack drawer's by-hand path (copy fields, open submit page, mark submitted) is always the fallback.
+- **Field mapping fails** — leave the row `queued`, note which fields couldn't be matched, move on. Never invent a value for a field the pack doesn't supply.
+- **Directory site redesigned / submitUrl dead** — stop and leave the row `queued` with a note saying why. The status walk (`ALLOWED_TRANSITIONS` in `update.ts`) only allows `queued → submitted` and `submitted → live | rejected`, so a queued row **cannot** be marked `rejected` — that call 400s with `invalid_transition`. `rejected` is the verdict on a submission the directory turned down, not on a directory that can't be reached. A note on the stuck row is the signal that routes the registry fix and future runs away from this directory.
+
+## See also
+
+- `text/directory-submission.md` — the promise
+- `text/directory-submission-plan.md` — data model, API shapes, § The browser hand
+- `text/directory-submission-ui.md` — the File-with-agent door on the board
+- `one.ie/web/src/lib/directories/registry.ts` — `DIRECTORIES`, `Directory`, `DirectoryField`
+- `one.ie/web/src/pages/api/directories/run.ts` · `update.ts` — the two guarded routes this skill calls

package/skills/docs/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: docs
+description: Pick the right documentation type and write it with the right discipline. Use whenever creating or editing any file in text/ that documents a feature — a marketing promise (.md), feature spec (-features.md), UI spec (-ui.md), architecture (-plan.md), explanation (-docs.md), tutorial (-tutorial.md), how-to (-how-to.md), reference (-reference.md), or agent briefing (-agents-docs.md). Invoke this BEFORE writing to choose the type and load its rules; it works on top of the `writer` skill (craft) and the templates (shape). Triggers — "write the docs for X", "document this feature", "write a tutorial/how-to/reference/explanation", "what doc type is this", "split this doc", "this doc mixes concerns".
+---
+
+# docs — the documentation discipline
+
+This skill is the **middle layer** of three. It does not write prose (that's the `writer` skill) and it does not hold the section skeleton (that's the `template-*.md` files). It does one thing the other two can't: **it knows the ONE doc taxonomy, picks the right type for the reader, and enforces the one rule that type lives or dies by.**
+
+A generic writing skill can make any paragraph clearer. It cannot tell you that the paragraph doesn't belong in a `-reference.md` at all. That judgment is this skill.
+
+**The order:** invoke `docs` (pick type + rules) → copy the matching `template-*.md` (shape) → invoke `writer` (craft the prose) → invoke `voice` (pick + apply the register) → check `.claude/product-marketing.md` (product context).
+
+The full taxonomy lives in [`text/docs.md`](../../../text/docs.md); the template map in [`text/templates.md`](../../../text/templates.md). This skill is how you *apply* them.
+
+---
+
+## First: which type?
+
+Every doc answers **one reader's one question at one moment.** Find the reader and the question; the type falls out.
+
+| The reader's question | Type | File |
+|---|---|---|
+| "Why would I want this?" | promise | `<slug>.md` |
+| "What does it do?" | features | `<slug>-features.md` |
+| "What does it look like?" | ui | `<slug>-ui.md` |
+| "How is it built?" | plan | `<slug>-plan.md` |
+| "How does it work, and why?" | explanation | `<slug>-docs.md` |
+| "How do I succeed the first time?" | tutorial | `<slug>-tutorial.md` |
+| "How do I do X?" | how-to | `<slug>-how-to.md` |
+| "What's the exact spec?" | reference | `<slug>-reference.md` |
+| "What does an agent need to operate it?" | agent briefing | `<slug>-agents-docs.md` |
+
+If a single file is trying to answer two of these, **it's the wrong file** — split it. A doc that mixes "how do I" steps with "why it works" theory serves neither reader.
+
+**Don't over-create.** Most features need only `.md` + `-plan.md` + `-docs.md`. Reach for tutorial / how-to / reference only when the feature outgrows one explanation file.
+
+---
+
+## The four user docs are a grid
+
+The user-facing types aren't a list — they're the four cells of [Diátaxis](https://diataxis.fr/), split by what the reader is *doing* (practical vs. theoretical) and where they *are* (learning vs. working):
+
+```
+                  PRACTICAL (doing)        THEORETICAL (knowing)
+              ┌─────────────────────────┬─────────────────────────┐
+ LEARNING     │  tutorial               │  explanation (-docs)    │
+ (studying)   │  succeed first time     │  understand how & why   │
+              ├─────────────────────────┼─────────────────────────┤
+ WORKING      │  how-to                 │  reference              │
+ (applying)   │  get this task done     │  look up the exact spec │
+              └─────────────────────────┴─────────────────────────┘
+```
+
+The most common failure is mixing two cells in one doc. The grid is the cure: when a section feels off, name its cell. If it's a different cell than the doc, move it.
+
+---
+
+## The discipline per type
+
+Each type has **one cardinal rule** — the thing it must never do. Break it and the type collapses into another.
+
+### explanation (`-docs.md`) — understanding-oriented
+Background, the mental model, the why. The page that makes every other page click.
+- **Cardinal rule: no steps.** The moment you write "first… then…" you've drifted to tutorial/how-to.
+- Tell: "therefore", "because", "the reason is", "this fits the system by…"
+- Default for most features: this is the one doc you write. (Template `template-teach.md` makes it a complete guide — model + first win + runbook — when no split is needed.)
+
+### tutorial (`-tutorial.md`) — learning-oriented
+One complete story, beginning to a guaranteed success. The reader follows; the doc leads.
+- **Cardinal rule: never fork on reader state.** No "if you have X, do Y." One path. If the reader's setup varies, that's a how-to, not a tutorial.
+- Every command exact and verified. Show the expected output after each step. End on the win.
+- It's about *learning by doing*, not about the task — the result can be a toy; the point is the reader's confidence.
+
+### how-to (`-how-to.md`) — task-oriented
+A practitioner who already knows the concept needs the steps for one real task.
+- **Cardinal rule: no concept-explaining.** No teaching what a campaign is — link to `-docs.md`. Straight to the recipe.
+- Title is a task: "How to…", "Running a…". Assumes competence. Numbered steps + a verify.
+
+### reference (`-reference.md`) — information-oriented
+Complete, precise, neutral. Field types, signal names, limits, defaults, error codes.
+- **Cardinal rule: no opinions, no prose explanation.** If you're tempted to explain *why*, link to `-docs.md`. Reference states *what*.
+- Structure mirrors the code's structure (a table per surface). Exhaustive over readable.
+
+---
+
+## The ONE-specific types
+
+Not Diátaxis — but they obey the same "one reader, one question" law.
+
+### promise (`<slug>.md`) — the buyer, pre-purchase + the genesis contract
+Marketing copy on the surface; a contract underneath. The **first file** — everything else derives from it and reconciles **upward** to it.
+- **Cardinal rule: persuade, don't specify.** Lead with what the persona gets (hire, sell, ship, earn). Drop internal words — `mark`/`warn`/`substrate`/`pheromone` belong nowhere near it (see `.claude/product-marketing.md`).
+- This is the spec the `/do` PROVE stage checks shipped behavior against. Every claim must be true.
+- **Frontmatter is the contract — four machine-read manifests, read like an agency SOW:** `deliverables:` (the exhaustive schedule of work — every item the client receives, each with its own `accept:` bash check; not listed = not promised, listed = ships or the promise settles broken, acceptance indivisible; `assumes:` alongside lists client-side dependencies, green at the making) + `proof:` (the acceptance test — **derived, not authored**: the `&&`-join of every `accept:`, verbatim; it becomes the todo `outcome:`, the TEST assertion, and the PROVE oracle) + `derives:` (the manifest of which files to spawn) + `world:` (the runtime the kept promise puts into the substrate — lifecycle moves + recording signals, workflow steps, agents + `subscribes:` tags, skills, task tags, tracking marks/warns, routing paths). The schedule ⇄ proof law is linted by `.claude/scripts/do-promise-lint.sh <slug>` — the PROMISE gate. Body must carry **"The deliverables (the schedule of work)"** (the SOW table + completeness clause) and **"Out of scope (excluded, in writing)"** (enumerated exclusions). **`derives:` is authoritative** for which conditional docs exist — this skill *confirms/refines* that choice, it does not override it. `/do` presence-checks every `world:` entry like an artifact: missing agent → a `template-agent.md` cycle (+ `subscriptions:register` for its tags) · missing skill → `/skill-creator` · missing workflow/lifecycle stage → a todo cycle · present → skip. Design: `text/promise-plan.md`.
+- **Contract-backed form:** a promise uncomments the `contract:` block in `text/template-feature.md` and mints a generated Move Promise at PROMISE; `do-promise-settle.sh` settles it at close from the proof exit code. Worked example: `text/playbook.md`.
+- Craft is `writer` + `copywriting`, not this skill — but `docs` keeps it from absorbing feature-spec detail (that's `-features.md`).
+
+### features (`<slug>-features.md`) — the builder/PM
+WHAT the feature does: capabilities, scope, use cases, and **non-goals**.
+- **Cardinal rule: no implementation.** What it does, not how it's built (that's `-plan.md`).
+- Non-goals are load-bearing — they're how scope stops creeping.
+
+### ui (`<slug>-ui.md`) — the builder/designer
+WHAT it looks like: screens, component states (empty · loading · error · success · edit), user flows.
+- **Cardinal rule: no backend wiring.** Pair with the `frontend-design` skill for layout quality.
+
+### plan (`<slug>-plan.md`) — the builder
+HOW it's built: signals, TypeDB schema, the authority walk, the reuse verdict.
+- **Cardinal rule: no selling and no user-facing "what it does"** — that's `.md` and `-features.md`.
+
+### agent briefing (`<slug>-agents-docs.md`) — the agent
+A dense, token-lean briefing for an AI agent that must *act*: the signal chain, schema types and their fields, receivers, authority (role → can), compact task recipes, and error → recovery-signal.
+- **Cardinal rule: briefing, not background.** No essays, no motivation, no journey. Tables and signal chains. Optimized for tokens, not warmth.
+- Verify every signal name, receiver, and field against the code (`packages/sdk/src/receivers.ts`, `schema/*.tql`) — invoke `sdk`/`typedb` for accuracy. A wrong signal name here breaks a real agent.
+
+---
+
+## How it composes with the other layers
+
+1. **Pick the type** (this skill) — reader + question → type. If the content spans two types, split before writing.
+2. **Copy the template** — the type → template map is the table in [`text/templates.md`](../../../text/templates.md); most types are `template-<type>.md`, with two exceptions worth knowing before you `cp` the wrong file: the **promise** copies `template-feature.md` (`template-promise.md` is a FOLDED stub — do not copy it) and the **explanation** copies `template-teach.md` (there is no `template-docs.md`). The template is the shape; never write a doc-spine artifact from scratch.
+3. **Write with `writer`** — apply the craft loop (cut, show-don't-tell, structure, sentence polish). This skill says *what goes where*; `writer` makes each sentence land.
+4. **Check voice** — `.claude/product-marketing.md`: ONE's audience (CEOs + engineers), simple English, banned words. Run `bash .claude/scripts/do-reconcile.sh dictionary text/<file>.md` before committing (no dead names, no new synonyms) — the scripts are not on PATH.
+
+---
+
+## Self-check before shipping any doc
+
+- [ ] **One reader, one question.** Name them. If you name two, split the file.
+- [ ] **Cardinal rule held.** The type's one forbidden thing is absent (no steps in explanation, no fork in tutorial, no opinion in reference, no essay in agent briefing).
+- [ ] **Right file name.** The suffix matches the type (`-docs` vs `-reference` vs `-how-to`).
+- [ ] **No duplication across files.** If two docs say the same thing, one should link to the other.
+- [ ] **Links resolve.** Cross-references to sibling docs and `file:line` anchors are real.
+- [ ] **Facts verified.** For reference/agent-briefing, every name/signal/field checked against code.
+- [ ] **Voice clean.** No banned words; dictionary reconcile passes.
+
+---
+
+## Common fixes
+
+| Symptom | Fix |
+|---|---|
+| `-docs.md` has numbered steps | Move them to `-how-to.md` (a task) or `-tutorial.md` (a first run); keep only the why |
+| `-tutorial.md` says "if you have X…" | It forks — either pick one path, or it's actually a how-to |
+| `-reference.md` opens with a paragraph of context | Move the prose to `-docs.md`; reference is facts only |
+| `.md` reads like a spec | Move the spec to `-features.md`; the `.md` sells |
+| `-agents-docs.md` reads like a guide | Cut the narration to tables + signal chains |
+| One doc serves both a beginner and an expert | Split: tutorial for the beginner, reference for the expert |
+
+---
+
+*Taxonomy: [`text/docs.md`](../../../text/docs.md). Templates: [`text/templates.md`](../../../text/templates.md). Craft: `writer` skill. Register: `voice` skill → [`text/voice-and-tone.md`](../../../text/voice-and-tone.md) (senior) + [`text/writing-style-guide.md`](../../../text/writing-style-guide.md). Product context: [`.claude/product-marketing.md`](../../product-marketing.md).*

package/skills/mcp/SKILL.md

@@ -0,0 +1,272 @@
+---
+name: mcp
+description: Add or change a tool in @oneie/mcp — the MCP server exposing ONE to Claude Desktop, Cursor, and any MCP client. Use when adding an MCP tool, editing anything under packages/mcp/src/tools/, writing a tool inputSchema, fixing MCP_TOOLS manifest drift when `bun run check:tools` fails, or deciding whether a new capability needs a tool at all (usually it does not — signal/ask already reach every receiver). Triggers — "add an MCP tool", "new tool for the MCP server", "check:tools is failing", "MCP_TOOLS drift", "expose X to Claude Desktop", "wire the oneie MCP server".
+---
+
+# MCP tools — Model Context Protocol for agents
+
+MCP tools give agents programmatic access to ONE capabilities. Each tool is a
+plain object registered on a router; the router is served over stdio.
+
+## Structure
+
+```
+packages/mcp/
+├── src/
+│   ├── index.ts    # createOneRouter() + MCP_TOOLS + bin
+│   ├── serve.ts    # McpTool, McpRouter, apiCall(), serve()
+│   ├── env.ts      # readEnv() → { baseUrl, apiKey }
+│   ├── telemetry.ts
+│   └── tools/      # one file per group: <group>Tools()
+│       ├── substrate.ts     # 6 verbs + dims (locked)
+│       ├── lifecycle.ts     # agents, skills, pay
+│       ├── observability.ts # stats, health, export
+│       ├── discovery · social · video · broadcast
+│       ├── messaging · seo · views · workflow · tasks
+│       └── fn.ts            # generated per allowlisted fn
+```
+
+There is no `src/schema.ts` and no per-domain subdirectory — a tool group is one
+flat file exporting one `<group>Tools(): McpTool[]` function.
+
+## Pattern: Adding an MCP tool
+
+**First ask whether you need one.** `signal` and `ask` address any receiver by
+name — the registry declares 273 of them today. (The registry is the capability
+*catalog*; a receiver is only reachable once a handler is bound in
+`world-receivers.ts` or a channels tool module. A declared-but-unbound name
+type-checks and 404s.) A new product action needs a receiver, not a tool.
+The documented exceptions (`views.ts`, `workflow.ts`, `tasks.ts`) exist because
+those are first-class product objects other clients address by name — and even
+they add no new receiver, they route through the `/api/ask` door.
+
+### 1. Define the input schema (raw JSON Schema, not Zod)
+
+`McpTool.inputSchema` is `Record<string, unknown>` and is handed to the MCP
+client verbatim. Zod is an SDK dependency, not an MCP one.
+
+```typescript
+// inside packages/mcp/src/tools/broadcast.ts
+const inputSchema = {
+  type: "object",
+  properties: {
+    broadcastId: { type: "string" },
+  },
+  required: ["broadcastId"],
+};
+```
+
+### 2. Implement the tool
+
+```typescript
+// packages/mcp/src/tools/broadcast.ts
+import { apiCall, type McpTool } from "../serve.js";
+
+function ask(env: { baseUrl: string; apiKey?: string }, receiver: string, data: unknown) {
+  return apiCall(env.baseUrl, env.apiKey, `/api/ask/${encodeURIComponent(receiver)}`, {
+    method: "POST",
+    body: JSON.stringify({ data }),
+  });
+}
+
+export function broadcastTools(): McpTool[] {
+  return [
+    {
+      name: "broadcast_send",
+      description: "Send a broadcast now (inline drain, suppression-checked).",
+      inputSchema: {
+        type: "object",
+        properties: { broadcastId: { type: "string" } },
+        required: ["broadcastId"],
+      },
+      handler: async (args, env) => ask(env, "broadcast:send", args),
+    },
+  ];
+}
+```
+
+**Rules:**
+- The tool shape is exactly `{ name, description, inputSchema, handler }` —
+  the field is `handler`, not `execute`
+- `handler(args, env)` receives `Record<string, unknown>` and the `readEnv()`
+  result; it returns `Promise<unknown>` — **not** a string. Return the parsed
+  JSON body; the transport serialises it
+- Tools call `apiCall(env.baseUrl, env.apiKey, path, init)` from `serve.ts`.
+  They do **not** construct a `SubstrateClient` — the SDK import in this package
+  is for the `RECIPES` contract catalog, not for transport
+- Every receiver a tool wraps must be a real key in `@oneie/sdk/receivers`
+- `apiCall` throws with the response body on a non-2xx, so the API's structured
+  error (`{error, field, expected, got, hint}`) reaches the agent. Let it throw
+
+### 3. Register the tool — in two places
+
+```typescript
+// packages/mcp/src/index.ts
+export function createOneRouter() {
+  const router = createRouter();
+  for (const tool of [...substrateTools(), ...broadcastTools(), /* … */]) {
+    router.register(tool);
+  }
+  return router;
+}
+
+export const MCP_TOOLS = {
+  broadcast: ["broadcast_create", "broadcast_list", "broadcast_get",
+              "broadcast_send", /* … */] as const,
+};
+```
+
+`MCP_TOOLS` is hand-maintained and drifts. `toolManifestDrift()` diffs the
+manifest against the live router; `fn_*` is excluded by design because those are
+generated at runtime from `FN_MAP`.
+
+### 4. Check and test
+
+```bash
+cd packages/mcp && bun run check:tools
+# builds, then reports "MCP_TOOLS matches the router" or exits 1 with the diff
+```
+
+There is no vitest suite in `packages/mcp` — `check:tools` and `bun run
+typecheck` are the gates. Exercise a tool end-to-end through a live client:
+
+```bash
+claude mcp add oneie -e ONEIE_API_KEY=one-<key> -- npx -y @oneie/mcp
+```
+
+## Naming conventions
+
+**Tool names:** snake_case, `group_verb`
+- Correct: `broadcast_send`, `tasks_list`, `chat_send`, `workflow_run`
+- Wrong: `send-broadcast`, `Memory`, `CREATE_TASK` (nothing shipped uses kebab or caps)
+- The universal verbs are the bare exception — `signal`, `ask`, `mark`, `warn`,
+  `fade`, `follow` keep the locked verb name with no prefix
+
+**Tool descriptions:** one sentence, agent-perspective, and say what comes back
+- Correct: "Send a broadcast now (inline drain, suppression-checked)."
+- Correct: "Get one broadcast by id. Returns { broadcast }."
+- Wrong: "Calls the broadcast API" (implementation detail, no return shape)
+
+**Input fields:** match the receiver's zod request field-for-field
+- The handler forwards `args` straight through, so a renamed field is a silent
+  400. `broadcast:send` takes `broadcastId`; the tool takes `broadcastId`
+
+## Tool categories
+
+| Category | Purpose | Example |
+|----------|---------|---------|
+| **Universal** | Reach any receiver by name | `signal`, `ask` |
+| **Read** | Fetch data without side effects | `broadcast_list`, `tasks_list`, `stats` |
+| **Create** | Add new entity | `broadcast_create`, `tasks_create`, `create_view` |
+| **Update** | Modify existing entity | `newsletter_update`, `tasks_status` |
+| **Delete** | Remove entity (rare) | `delete_room`, `unpublish_agent` |
+| **Execute** | Run an action with side effects | `broadcast_send`, `chat_send`, `workflow_run` |
+
+## Anti-patterns
+
+**A new tool for a new product action**
+```typescript
+// WRONG — a receiver already reaches this
+{ name: "commend_agent", handler: (a, e) => ask(e, "agents:commend", a) }
+```
+**Fix:** Let the agent call `signal` with `receiver: "agents:commend"`. Only add
+a tool for a first-class object clients address by name, and document why.
+
+**Zod in inputSchema**
+```typescript
+// WRONG — inputSchema is raw JSON Schema
+inputSchema: z.object({ broadcastId: z.string() })
+```
+**Fix:** Write the JSON Schema object literal, or derive it from the receiver
+with `ask("meta:schema", { receiver })`.
+
+**Returning a hand-serialised string**
+```typescript
+// WRONG
+handler: async (args, env) => JSON.stringify(await ask(env, "broadcast:get", args))
+```
+**Fix:** Return the value. `handler` is `Promise<unknown>`; double-encoding
+gives the agent a string it has to re-parse.
+
+**Tool builds its own fetch**
+```typescript
+// WRONG
+const res = await fetch(`${base}/api/ask/broadcast:send`, { … });
+return res.json();
+```
+**Fix:** Use `apiCall()` — it sets Accept/Content-Type/Authorization, handles
+204, and surfaces the structured error body on failure.
+
+**Registered in the router but not in MCP_TOOLS**
+```typescript
+// WRONG — check:tools exits 1 with "missing: [ 'broadcast_send' ]"
+router.register(broadcastSendTool);  // and nothing added to the manifest
+```
+**Fix:** Add the name to its `MCP_TOOLS` group in the same edit.
+
+**Tool that modifies global state**
+```typescript
+// WRONG
+let cached: unknown;
+handler: async (args, env) => (cached ??= await ask(env, "broadcast:list", args))
+```
+**Fix:** No caching in tools. Each invocation is independent.
+
+## Composability rules
+
+**New tool wraps an existing receiver:**
+```typescript
+// GOOD — the receiver owns validation, authority, and persistence
+{
+  name: "segment_preview",
+  description:
+    "Preview an audience segment definition — live count + up to 10 sample " +
+    "addresses (read-only). Pass a SegmentDef ({all,any?}), not an id.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      definition: { type: "object", description: "SegmentDef {all: SegmentRule[], any?: SegmentRule[]}" },
+      channel: { type: "string", enum: ["email", "sms", "whatsapp"] },
+    },
+    required: ["definition"],
+  },
+  handler: async (args, env) => ask(env, "segment:preview", args),
+}
+```
+
+**New tool is generated from a catalog:**
+```typescript
+// GOOD — fn.ts builds one tool per FN_ALLOWLIST entry (20 today) from
+// @oneie/sdk/generated/fn-map, all routing through ask("fn:run"). Extending the
+// surface means allowlisting the fun in @oneie/sdk/fn-allowlist — one edit
+// reaches web, MCP, CLI, and channels. Never hand-write an fn_* tool.
+```
+
+## Error handling
+
+```typescript
+handler: async (args, env) => {
+  const res = await ask(env, "broadcast:get", args) as { broadcast?: unknown };
+  if (!res.broadcast) {
+    return { ok: false, error: "not_found", hint: "Call broadcast_list for valid ids." };
+  }
+  return res;
+}
+```
+
+**Rules:**
+- Let `apiCall` throw on a non-2xx — its message already carries the API's
+  structured detail, which is what an agent self-corrects from
+- Return an error *shape* (`{ ok: false, error, hint }`) for domain-empty cases
+  the API considers a legitimate 200
+- Never expose the API key, raw TypeQL, or a stack trace in a returned value
+- Don't validate what the receiver already validates — the zod contract runs
+  server-side before dispatch
+
+## See also
+
+- `packages/mcp/CLAUDE.md` — the tool-file map, wiring, and the base-URL trap
+- `packages/mcp/src/serve.ts` — `McpTool`, `McpRouter`, `apiCall`
+- `packages/sdk/src/receivers.ts` — receiver registry (every tool wraps a receiver)
+- `text/signals-catalog.md` — the generated namespace map
+- `@modelcontextprotocol/sdk` — MCP protocol docs

package/skills/oneie/SKILL.md

@@ -31,7 +31,7 @@ packages/templates/       — @oneie/templates (16 C-suite + marketing + service
 
 ## When to use
 
-- User asks about `oneie <verb>` — see `text/cli-reference-plan.md`
+- User asks about `oneie <verb>` — see `text/cli-reference.md`
 - User touches `packages/{sdk,mcp,templates}/` — see the per-package README
 - User wants to mint a token for an agent — route to `oneie launch <uid> --dry-run`, then handoff docs
 - User asks why buy/sell isn't in ONE — [launch-handoff.md](../../docs/launch-handoff.md) is the "why"
@@ -44,7 +44,7 @@ packages/templates/       — @oneie/templates (16 C-suite + marketing + service
 
 ## See Also
 
-- [cli-reference.md](../../text/cli-reference-plan.md)
+- [cli-reference.md](../../text/cli-reference.md)
 - [sdk-reference.md](../../text/sdk-reference-plan.md)
 - [mcp-tools.md](../../text/mcp-tools-plan.md)
 - [launch-handoff.md](../../docs/launch-handoff.md)

package/skills/promise-make/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: promise-make
+description: State terms + exactly one checkable proof — make a promise as a signal any actor can send. Use whenever an operator or agent commits to an outcome that should be held, watched, and settled — "promise that X", "commit to Y", "make a promise", "I'll deliver Z by the time the proof passes". Refuses a promise with no observable. Emits signal("promise:make", { slug, terms, proof }) and closes the loop with a receipt.
+---
+
+# promise-make — state terms + exactly one checkable proof
+
+**Purpose:** Turn a commitment into a promise Thing the world holds: frozen terms + ONE proof observable. One signal in, one `promised` state out, announced to everyone staked on the `promise` tag. The run-time face of what `/do`'s PROMISE stage does at build time.
+
+Source of truth: `one.ie/web/src/lib/resolvers/promises.ts` (receiver `promise:make`) · briefing: `text/promise-signals-agents-docs.md` · contract: `text/promise-signals.md`.
+
+---
+
+## HARD RULES
+
+- **Refuse a promise with no observable.** Empty or vague `proof` → do NOT emit the signal. The resolver rejects it anyway (`{ok:false, error:'a promise needs one observable'}`), but the refusal happens here first: ask for the one checkable thing, or dissolve the request with a stated reason. Never a silent return.
+- **Exactly ONE proof.** If the terms need two *independent* observables, that's two promises — split them into two slugs. But a **multi-part delivery is one promise with a schedule** (covenant clause 1, `text/promises.md`): enumerate the deliverables in `terms` like an agency SOW — every item the receiver gets, each with its own acceptance check in words — and make the ONE `proof` the observable that is true only when *every* line shipped (acceptance indivisible, no partial credit). Not enumerated = not promised. If no single observable can cover the whole schedule, the schedule is two promises.
+- **Terms freeze at the making.** The resolver inserts with `ON CONFLICT(slug) DO NOTHING` — a re-make of an existing slug changes nothing. Never "update" a promise's terms; make a new slug.
+- **Know which rail the proof settles on.** A shell-shaped proof (`test -f`, `grep`, `&&`, `;`, `$()`, backticks) is a BUILD-time observable — it settles at PROVE via `do-promise-settle.sh`, and `promise:settle` will refuse it. A runtime observable (a D1 row, a fetch, a signal receipt, a maker-attested verdict) settles via `promise:settle`. State which rail at make-time so the maker isn't surprised at settle-time.
+- **Identity is the session, never the body.** `maker` becomes `ctx.ownerSlug` server-side. Never pass an `actorId` in the payload expecting it to matter — it doesn't, by design (IDOR-safe).
+- **Closed loop.** Emit → read the response → `mark` mentally on `{ok:true}`, surface the error verbatim on `{ok:false}`. No silent returns.
+
+## When to use
+
+- An operator says "promise that…", "commit to…", "hold me to…"
+- An agent takes on work whose completion should route future work (reputation via `promise:<slug>→proof`)
+- A `/do` promise file's `world.skills` fan-out names a commitment that must exist as a run-time object
+- A deal needs an unpriced spine before money attaches (a priced promise rides the deal rail on top of this)
+
+**Not for:** settling (that's `promise-settle`), reading (`promise:get`, public, no skill needed), or build-time promise files in `text/` (that's the `docs` skill + `template-feature.md`).
+
+## The signal (exact shape)
+
+```ts
+signal("promise:make", {
+  slug:  "ship-weekly-digest",         // ^[a-zA-Z0-9_:/-]{1,128}$ — the promise's name, forever
+  terms: "A digest email goes to every subscriber each week.",  // frozen prose, hashed sha256
+  proof: "promise:get shows a broadcast_sends row for the current week"  // ONE observable
+})
+```
+
+Response on success:
+
+```json
+{ "ok": true, "slug": "ship-weekly-digest", "state": "promised", "terms_hash": "<sha256 of terms>" }
+```
+
+What the resolver does (so you don't re-do it): inserts the D1 `promises` row (state `promised`, strength 0, resistance 0), fire-and-forgets a TypeDB `thing` with `thing-type "promise"`, and fire-and-forgets `world:announce` with tags `["promise", "made", slug]` — every subscriber staked on those tags gets it in their inbox Space.
+
+## Process
+
+1. **Extract the terms.** One sentence of what will be true. If the ask is fuzzy, tighten it with the maker before emitting — frozen fuzz is worse than no promise.
+2. **Extract the ONE proof.** Ask: "what single check settles this?" If the answer is "well, A and B" → two promises. If the answer is "you'll know it when you see it" → refuse, with the reason stated. The check should be *false right now* (covenant clause 3, red before green) — a proof that already passes means the thing is already built, or the proof is too weak to gate anything. The resolver does not enforce this; you do.
+3. **Classify the proof rail.** Shell-shaped → tell the maker it settles at PROVE via CLI, not via `promise:settle`. Runtime-checkable → `promise:settle` works.
+4. **Pick the slug.** Kebab, stable, matches `^[a-zA-Z0-9_:/-]{1,128}$`. It becomes the path endpoint `promise:<slug>→proof` — choose like it's permanent, because it is.
+5. **Emit** `signal("promise:make", { slug, terms, proof })` — authenticated (the session's `ctx.ownerSlug` becomes the maker who alone may settle).
+6. **Close the loop.** `{ok:true, state:"promised"}` → report slug + terms_hash back to the maker. `{ok:false}` → surface the error verbatim (`slug + terms required` · `invalid slug` · `a promise needs one observable` · `forbidden: authentication required`) and fix the input. If the slug already existed, `promise:get` it and tell the maker the prior terms stand — nothing was overwritten.
+
+## Worked example
+
+Operator: *"Promise the client their movers landing page will be live."*
+
+1. Terms: "The elitemoversca landing page is live at its production URL."
+2. Proof (one, runtime-checkable): "GET https://elitemoversca.com returns 200 with the hero headline present."
+3. Rail: runtime observable → settles via `promise:settle`. Good.
+4. Slug: `elitemoversca-landing-live`.
+5. Emit:
+   ```ts
+   signal("promise:make", {
+     slug:  "elitemoversca-landing-live",
+     terms: "The elitemoversca landing page is live at its production URL.",
+     proof: "GET https://elitemoversca.com returns 200 with the hero headline present"
+   })
+   ```
+6. Response `{ ok: true, slug: "elitemoversca-landing-live", state: "promised", terms_hash: "9f2c…" }` → report: "Promised. Terms frozen (hash 9f2c…). Settles kept when the page answers 200 — run `promise-settle` when it's live. Everyone staked on the `promise` tag was announced."
+
+Counter-example (must refuse): *"Promise we'll make the client happy."* → No observable. Reply: "A promise needs one checkable proof — what single thing, when true, means this is kept? (e.g. a signed renewal, a ≥ 4-star review row)." Do not emit.
+
+## Quality checks
+
+- [ ] Exactly one proof observable, stated in the payload
+- [ ] Proof rail classified (shell → PROVE/CLI · runtime → `promise:settle`) and told to the maker
+- [ ] Slug matches the regex and won't need renaming
+- [ ] Response read and reported — `ok:true` receipt or verbatim error, never silence
+- [ ] No body-field identity games — session auth only
+
+## Cross-references
+
+- Settle side: `.claude/skills/promise-settle/SKILL.md`
+- Receiver source: `one.ie/web/src/lib/resolvers/promises.ts` (`make`, lines 36–67)
+- Agent briefing (payloads, errors, recovery): `text/promise-signals-agents-docs.md`
+- The contract this skill serves: `text/promise-signals.md` (`world.skills` names this skill)
+- Build-time twin: `/do` PROMISE stage + `text/template-feature.md` (contract: block). "Never update the terms" is this rail's rule — a D1 row inert after `ON CONFLICT DO NOTHING`. The build-time rail differs: a *kept* `text/<slug>.md` promise grows, appending a follow-on deliverable whose `accept:` is already green and extending the `proof:` join (`.claude/rules/documentation.md` § "Promises grow with delivery"). Green-only and additive there; frozen here.