@oneie/claude 0.6.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

@@ -9,7 +9,7 @@ This skill is the **middle layer** of three. It does not write prose (that's the
 
 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) → check `.claude/product-marketing.md` (voice).
+**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.
 
@@ -119,9 +119,9 @@ A dense, token-lean briefing for an AI agent that must *act*: the signal chain,
 ## 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** — `cp text/template-<type>.md text/<slug>-<suffix>.md`. The template is the shape; never write a doc-spine artifact from scratch.
+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 `do-reconcile.sh dictionary` on the file before committing (no dead names, no new synonyms).
+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.
 
 ---
 
@@ -150,4 +150,4 @@ A dense, token-lean briefing for an AI agent that must *act*: the signal chain,
 
 ---
 
-*Taxonomy: [`text/docs.md`](../../../text/docs.md). Templates: [`text/templates.md`](../../../text/templates.md). Craft: `writer` skill. Voice: [`.claude/product-marketing.md`](../../product-marketing.md).*
+*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

@@ -1,242 +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. They're scaffolded, typed, and auto-discovered.
+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              # MCP server entrypoint
-│   ├── tools/                # tool implementations
-│   │   ├── index.ts          # tool registry + re-exports
-│   │   ├── chat/             # chat-related tools
-│   │   │   ├── index.ts
-│   │   │   └── memory.ts
-│   │   └── {domain}/
-│   │       ├── index.ts
-│   │       └── {action}.ts
-│   └── schema.ts             # Zod schemas for tool inputs
+│   ├── 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
 
-### 1. Define the schema (input + output types)
+**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.
 
-```typescript
-// packages/mcp/src/schema.ts
-import { z } from 'zod';
+### 1. Define the input schema (raw JSON Schema, not Zod)
 
-export const memoryToolSchema = z.object({
-  groupId: z.string().describe('Group ID'),
-  content: z.string().describe('Memory content to store'),
-});
+`McpTool.inputSchema` is `Record<string, unknown>` and is handed to the MCP
+client verbatim. Zod is an SDK dependency, not an MCP one.
 
-export type MemoryToolInput = z.infer<typeof memoryToolSchema>;
+```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/chat/memory.ts
-import { SubstrateClient } from '@oneie/sdk';
-import { memoryToolSchema, MemoryToolInput } from '../schema';
-
-export async function memoryTool(input: MemoryToolInput): Promise<string> {
-  const client = new SubstrateClient();
-  const memory = await client.memory(input.groupId);
-  
-  if (!memory) {
-    return 'No memory found for this group.';
-  }
-  
-  return JSON.stringify(memory);
+// 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 const MEMORY_TOOL = {
-  name: 'memory',
-  description: 'Read or write group memory',
-  inputSchema: memoryToolSchema,
-  execute: memoryTool,
-};
+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:**
-- Schema first (using Zod)
-- Function receives typed input
-- Function returns string (MCP protocol requirement)
-- Tool object has name, description, inputSchema, execute
-- Tool calls SDK methods, never direct HTTP/DB
-
-### 3. Register the tool
+- 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/tools/chat/index.ts
-export { MEMORY_TOOL } from './memory';
-export * as chatTools from './index';
-
-// packages/mcp/src/tools/index.ts
-import * as chatTools from './chat';
-export const TOOLS = [
-  chatTools.MEMORY_TOOL,
-  // other tools
-] as const;
-
 // packages/mcp/src/index.ts
-import { TOOLS } from './tools';
+export function createOneRouter() {
+  const router = createRouter();
+  for (const tool of [...substrateTools(), ...broadcastTools(), /* … */]) {
+    router.register(tool);
+  }
+  return router;
+}
 
-export const mcpServer = {
-  tools: TOOLS,
-  // other MCP config
+export const MCP_TOOLS = {
+  broadcast: ["broadcast_create", "broadcast_list", "broadcast_get",
+              "broadcast_send", /* … */] as const,
 };
 ```
 
-### 4. Test the tool
+`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`.
 
-```typescript
-// packages/mcp/test/chat.memory.test.ts
-describe('Memory tool', () => {
-  it('returns memory for a group', async () => {
-    const result = await memoryTool({ groupId: 'group-123', content: 'test' });
-    expect(result).toContain('memory');
-  });
+### 4. Check and test
 
-  it('returns error message when no memory', async () => {
-    const result = await memoryTool({ groupId: 'nonexistent', content: 'test' });
-    expect(result).toContain('No memory');
-  });
+```bash
+cd packages/mcp && bun run check:tools
+# builds, then reports "MCP_TOOLS matches the router" or exits 1 with the diff
+```
 
-  it('validates input schema', () => {
-    expect(() => {
-      memoryToolSchema.parse({ groupId: 'g1' });  // missing content
-    }).toThrow();
-  });
-});
+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:** kebab-case, verb-noun
-- ✓ `read-memory`, `create-task`, `list-actors`
-- ✗ `Memory`, `CREATE_TASK`, `list_actors` (inconsistent)
+**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
-- ✓ "Read or write group memory" (what agent can do)
-- ✗ "Calls the memory API" (implementation detail)
+**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:** snake_case, self-documenting
-- ✓ `groupId`, `taskTitle`, `memberEmails`
-- ✗ `gid`, `t`, `e` (unclear)
+**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 |
 |----------|---------|---------|
-| **Read** | Fetch data without side effects | `read-memory`, `list-tasks` |
-| **Create** | Add new entity | `create-task`, `create-group` |
-| **Update** | Modify existing entity | `update-memory`, `complete-task` |
-| **Delete** | Remove entity (rare) | `delete-task` |
-| **Execute** | Run an action with side effects | `send-message`, `approve-request` |
+| **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
 
-❌ **Tool with no schema**
+**A new tool for a new product action**
 ```typescript
-// WRONG
-export const memoryTool = async (input: any) => { ... };
+// 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:** Define Zod schema, use typed input.
+**Fix:** Write the JSON Schema object literal, or derive it from the receiver
+with `ask("meta:schema", { receiver })`.
 
-❌ **Tool calls HTTP directly**
+**Returning a hand-serialised string**
 ```typescript
 // WRONG
-async function memoryTool(input: MemoryToolInput) {
-  const res = await fetch('/api/memory', { body: JSON.stringify(input) });
-  return res.text();
-}
+handler: async (args, env) => JSON.stringify(await ask(env, "broadcast:get", args))
 ```
-**Fix:** Use SDK client: `const client = new SubstrateClient(); client.memory(...)`
+**Fix:** Return the value. `handler` is `Promise<unknown>`; double-encoding
+gives the agent a string it has to re-parse.
 
-❌ **Tool without description**
+**Tool builds its own fetch**
 ```typescript
 // WRONG
-const MEMORY_TOOL = {
-  name: 'memory',
-  inputSchema: memoryToolSchema,
-  execute: memoryTool,
-};
+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 description for agent context.
+**Fix:** Add the name to its `MCP_TOOLS` group in the same edit.
 
-❌ **Tool that modifies global state**
+**Tool that modifies global state**
 ```typescript
 // WRONG
-let cachedMemory: any;
-export async function memoryTool(input: MemoryToolInput) {
-  cachedMemory = await client.memory(input.groupId);  // cache is a bug
-  return JSON.stringify(cachedMemory);
-}
+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 composes SDK methods:**
+**New tool wraps an existing receiver:**
 ```typescript
-// GOOD — reuses existing SDK
-async function createTaskTool(input: CreateTaskInput) {
-  const client = new SubstrateClient();
-  const task = await client.createTask(input);  // SDK handles DB, validation
-  return JSON.stringify(task);
+// 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 creates novel capability:**
+**New tool is generated from a catalog:**
 ```typescript
-// GOOD — when no SDK method exists yet
-async function analyzeMemoryTool(input: AnalyzeMemoryInput) {
-  const client = new SubstrateClient();
-  const memory = await client.memory(input.groupId);
-  // Analysis logic (not in SDK, because it's agent-specific)
-  const analysis = analyzeForSentiment(memory.content);
-  return JSON.stringify(analysis);
-}
+// 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
-export async function memoryTool(input: MemoryToolInput): Promise<string> {
-  try {
-    const client = new SubstrateClient();
-    const memory = await client.memory(input.groupId);
-    
-    if (!memory) {
-      return 'No memory found for this group. Create one first.';
-    }
-    
-    return JSON.stringify(memory);
-  } catch (error) {
-    if (error instanceof ValidationError) {
-      return `Invalid input: ${error.message}`;
-    }
-    if (error instanceof AuthenticationError) {
-      return 'You do not have permission to access this memory.';
-    }
-    throw error;  // Let parent handle unexpected errors
+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:**
-- Validate input (Zod does this for you)
-- Return user-facing error messages (not stack traces)
-- Don't catch unexpected errors (let them propagate)
-- Never expose sensitive data (API keys, DB queries) in error messages
+- 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` — MCP development guide
-- `packages/sdk/src/receivers.ts` — receiver registry (every tool calls a receiver)
-- `text/receiver-names-shipped-vs-spec.md` — which receivers exist
+- `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/promise-make/SKILL.md

@@ -50,7 +50,7 @@ What the resolver does (so you don't re-do it): inserts the D1 `promises` row (s
 ## 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.
+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).
@@ -90,4 +90,4 @@ Counter-example (must refuse): *"Promise we'll make the client happy."* → No o
 - 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)
+- 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.