narai-primitives 2.0.0-rc.1 → 2.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "narai-primitives",
-  "version": "2.0.0-rc.1",
+  "version": "2.0.0",
   "description": "Read-only connectors + planning hub + connector framework, in one package. Bundles what was @narai/connector-toolkit, @narai/connector-config, @narai/connector-hub, and the seven @narai/<svc>-agent-connector packages.",
   "type": "module",
   "main": "./dist/hub/index.js",

package/plugins/create-connector/.claude-plugin/plugin.json

@@ -0,0 +1,8 @@
+{
+  "name": "create-connector",
+  "version": "1.0.0",
+  "description": "Scaffold a custom connector for narai-primitives' gather() — wraps a SaaS API, REST/GraphQL endpoint, SDK, or CLI tool. Project- or user-scoped. No git init, no npm publish, no marketplace.",
+  "author": {
+    "name": "NarAI Labs"
+  }
+}

package/plugins/create-connector/README.md

@@ -0,0 +1,49 @@
+# create-connector
+
+A Claude Code skill that scaffolds custom connectors for `narai-primitives`'s `gather()`. Wraps any SaaS API, REST endpoint, GraphQL endpoint, SDK, or CLI tool into a minimal local connector.
+
+## Install
+
+Via the `narai` marketplace:
+
+```sh
+/plugin marketplace add narailabs/narai-claude-plugins
+/plugin install create-connector@narai
+```
+
+## Use
+
+In Claude Code, just describe what you want to wrap:
+
+> "I want to query Stripe from Claude"
+> "Wrap our internal orders API"
+> "Add Linear to our agents"
+> "Make me a Slack connector"
+
+The skill walks you through scope (project vs user), identity, auth, and action surface, then stamps out a minimal local connector at `<scope>/.connectors/connectors/<slug>/`. The `gather()` from `narai-primitives` picks it up immediately — no install, no publish, no restart.
+
+## What you get
+
+```
+<scope>/.connectors/connectors/<slug>/
+├── SKILL.md         describes actions; read by gather()'s planner
+├── index.mjs        uses createConnector from narai-primitives
+├── bin/<slug>       shell shim → exec node ../index.mjs
+└── (optional) tests/example.test.mjs
+```
+
+Plus one entry in `<scope>/.connectors/config.yaml`:
+
+```yaml
+connectors:
+  <slug>:
+    skill: <abs-path>
+    bin:   <abs-path>
+    enabled: true
+```
+
+## Differences from the legacy version
+
+The legacy create-connector flow scaffolded a full `@narai/<svc>-agent-connector` repo with `git init`, `npm install`, plugin manifest, tests/, README, LICENSE, marketplace entry. That flow is now used only for **builtin** connectors that get contributed to `narai-primitives` via PR — see [CONTRIBUTING.md](https://github.com/narailabs/narai-primitives/blob/main/CONTRIBUTING.md).
+
+This skill targets the much more common case: an **end user** who wants a quick local connector for their own work. No git, no publish, no plugin scaffold.

package/plugins/create-connector/skills/create-connector/SKILL.md

@@ -0,0 +1,252 @@
+---
+name: create-connector
+description: |
+  Use this skill when the user wants to add a custom connector to their project —
+  wrapping a SaaS API, REST endpoint, GraphQL endpoint, SDK, or CLI tool so
+  Claude can call it via `gather()` from `narai-primitives`. Trigger even when
+  the user doesn't say "connector" explicitly: phrases like "I want to query
+  Stripe from Claude", "add Slack to our agents", "wrap our internal orders
+  API", "connect Salesforce", "make a Linear agent" all warrant this skill.
+  Scaffolds a minimal local connector at `.connectors/connectors/<name>/`
+  (project scope, default) or `~/.connectors/connectors/<name>/` (user scope) —
+  no `git init`, no `npm publish`, no plugin manifest, no marketplace entry.
+  Do NOT use for: modifying an existing connector (just edit the file),
+  wrapping an MCP server (different abstraction), querying databases (the `db`
+  connector inside narai-primitives already covers postgres/mysql/sqlite/mssql/
+  mongodb/dynamodb/oracle), or contributing a new builtin connector (that's a
+  PR to https://github.com/narailabs/narai-primitives — see its CONTRIBUTING.md).
+---
+
+# create-connector
+
+Scaffold a custom connector that the user's local installation loads via `narai-primitives`'s `gather()`. The connector is **local-only**: it does not get published to npm, does not become a Claude Code plugin, and does not go in any marketplace. The user can later send a PR to `narailabs/narai-primitives` if their connector turns out to be broadly useful — that's a separate flow.
+
+## What gets created
+
+```
+<scope>/.connectors/connectors/<slug>/
+├── SKILL.md         # Describes actions; read by gather()'s planner
+├── index.mjs        # Uses createConnector from narai-primitives
+├── bin/<slug>       # Shell shim → exec node ../index.mjs
+└── (optional) tests/example.test.mjs
+```
+
+Plus one entry appended to `<scope>/.connectors/config.yaml`:
+
+```yaml
+connectors:
+  <slug>:
+    skill: <abs-path-to-connector-dir>      # path-style (config-loader supports it)
+    bin:   <abs-path-to-bin>
+    enabled: true
+```
+
+That's it — the connector is reachable via `gather()` immediately. No install, no publish, no restart.
+
+## When to invoke
+
+Use this skill when the user wants to **create a new custom connector** for local use.
+
+Classic phrasings:
+- "I want to wrap the Stripe API"
+- "Make me a Slack connector"
+- "We need a connector for our internal orders API"
+- "Add Linear to our agents"
+
+Near-miss phrasings (still trigger):
+- "I want to query Stripe from Claude"
+- "Connect Salesforce to Claude Code"
+- "Make a thing that lets me search Jira from Claude"
+
+**Do NOT use this skill for:**
+
+- **Modifying an existing connector.** Just edit the file directly.
+- **Wrapping an MCP server.** MCP servers and connectors are different abstractions in Claude Code. Point the user at the Claude Code MCP docs.
+- **Querying a database.** `narai-primitives/db` covers postgres, mysql, sqlite, mssql, mongodb, dynamodb, oracle. See `references/db-agent-pointer.md`. Only suggest a custom DB connector if it's a backend the bundled `db` connector doesn't support.
+- **Contributing a builtin connector to `narai-primitives`.** That's a different flow (PR to the bundle's repo, separate test suite, plugin marketplace entry). This skill is for end-user local connectors only.
+
+## Policy gate is automatic
+
+Every connector built on `createConnector` from `narai-primitives/toolkit` gets the policy gate **automatically**. Classification (`read` / `write` / `delete` / `admin` / `privilege`), approval-mode resolution (`auto` / `confirm_once` / `confirm_each` / `grant_required`), escalation, audit logging, and hardship recording all flow from the toolkit — you don't import any extra modules and don't write any approval logic yourself.
+
+What you **do** choose:
+
+- The **classification** of each action (defaults to `read`).
+- The **approval mode** for the connector (defaults to `auto` for read-only connectors).
+
+Both surface in the interview only when relevant.
+
+## Interview
+
+Conversational, not a fixed form. Capture the essentials in **5–7 quick exchanges**, then generate a draft and let the user react. People react faster than they author from scratch.
+
+### 1. Scope
+
+Ask: *"Should this connector be available only in this project, or for all your projects?"*
+
+| Choice | Where it lives | Default for |
+|---|---|---|
+| **Project (default)** | `./.connectors/connectors/<slug>/` | repo-specific stuff ("our internal orders API") |
+| **User** | `~/.connectors/connectors/<slug>/` | personal tools ("my company's Linear") |
+
+Pick a sensible default based on the user's phrasing. Confirm with them. The scope determines:
+- Where files get written
+- Which `config.yaml` gets the entry (`./.connectors/config.yaml` for project, `~/.connectors/config.yaml` for user)
+
+### 2. Identity
+
+Ask: *"What's the service slug?"*
+
+- **Slug**: lowercase, alphanumeric + hyphens (e.g., `stripe`, `slack`, `linear`, `acme`, `acme-orders`). Used everywhere — directory name, bin name, config key, envelope `name`.
+- **Description**: one sentence (e.g., "Read-only Stripe connector: customers, charges, invoices.")
+
+Record. Move on.
+
+### 3. Auth
+
+Ask: *"How does authentication work for this API?"*
+
+Map the answer to one of:
+
+- **`bearer-token-env-var`** (default) — single env var like `STRIPE_API_KEY`, used as `Authorization: Bearer …`.
+- **`api-key-header-env-var`** — single env var, used as a custom header like `X-API-Key`. Capture the header name.
+- **`multi-secret`** — multiple env vars (e.g., `GITHUB_TOKEN` + `GITHUB_OWNER`). Capture each pairing of `config-key → env-var`.
+- **`basic-auth`** — username + password env vars.
+- **`oauth-with-refresh`** — leave a `// TODO` placeholder in `loadCredentials`. Tell the user explicitly: *"You'll need to implement the OAuth flow before the connector will work."*
+- **`custom`** — anything else (mTLS, signed URLs, etc.). Same TODO treatment.
+
+See `references/auth-patterns.md` for per-scheme `loadCredentials` snippets.
+
+### 4. API basics
+
+Ask: *"What's the API base URL? Any rate limit or versioning header you know about?"*
+
+Defaults:
+- **Rate limit**: 60/min. Adjust if the user knows.
+- **Read timeout**: 30s.
+- **User-Agent**: `narai-custom-<slug>` (helps the upstream service identify the caller).
+
+### 5. Action surface
+
+Ask: *"What actions should this connector expose? Just describe them — name, what it does, what params, what it returns."*
+
+The user will say something like *"`get_customer` takes an id, returns the customer. `list_charges` takes optional `customer_id` and `limit` (default 25), returns a list."*
+
+You write the Zod schemas, pick HTTP methods/endpoints (ask if not obvious), and assign default classifications:
+
+- Names starting with `get_*`, `list_*`, `search_*`, `query_*`, `fetch_*` → `read`
+- Names starting with `create_*`, `post_*`, `send_*`, `update_*`, `patch_*` → `write`
+- Names starting with `delete_*`, `remove_*`, `archive_*` → `delete`
+- Names starting with `grant_*`, `revoke_*` → `privilege`
+
+Override on user signal — if they say *"this one mutates state"*, classify as `write` even if the name says otherwise.
+
+See `references/action-design.md` for Zod schema patterns and the full classification → approval-mode table.
+
+### 6. Approval mode (only if non-read actions exist)
+
+If any action is non-`read`, ask: *"For the write/delete actions, how should the user approve them — `auto` (no prompt), `confirm_once` (per session), `confirm_each` (every call), or `grant_required` (out-of-band)?"*
+
+Defaults:
+- `read` → `auto`
+- `write` → `confirm_once`
+- `delete` → `confirm_each`
+- `admin` / `privilege` → `grant_required`
+
+Skip entirely if all actions are read.
+
+### 7. Confirmation
+
+Show the user a summary:
+
+- File tree that will be created
+- Actions table with classifications
+- Auth scheme + env vars
+- Scope path (project or user)
+
+Ask: *"Anything to change before I scaffold?"* Wait for explicit OK.
+
+## Scaffold
+
+Templates live at `assets/templates/`. Three files plus an optional test:
+
+| Stamp | From template | Substitutions |
+|---|---|---|
+| `<scope>/.connectors/connectors/<slug>/index.mjs` | `assets/templates/index.mjs.tmpl` | slug, description, auth, action specs |
+| `<scope>/.connectors/connectors/<slug>/bin/<slug>` | `assets/templates/bin.tmpl` | slug |
+| `<scope>/.connectors/connectors/<slug>/SKILL.md` | `assets/templates/connector-SKILL.md.tmpl` | slug, description, action surface |
+| `<scope>/.connectors/connectors/<slug>/tests/example.test.mjs` (optional) | `assets/templates/tests-example.mjs.tmpl` | slug, first action |
+
+After stamping:
+
+1. `chmod +x <bin>` so the shim is executable.
+2. Open `<scope>/.connectors/config.yaml` (create it if missing — minimal valid file is `connectors: {}`) and append the entry under `connectors:`:
+   ```yaml
+   connectors:
+     <slug>:
+       skill: <abs-path-to-connector-dir>
+       bin:   <abs-path-to-bin>
+       enabled: true
+   ```
+3. Report what was created with absolute paths.
+
+### Placeholders
+
+| Placeholder | Example value |
+|---|---|
+| `{{SLUG}}` | `stripe` |
+| `{{ServicePascal}}` | `Stripe` (PascalCase, hyphens stripped) |
+| `{{DESCRIPTION}}` | `Read-only Stripe connector: customers, charges, invoices.` |
+| `{{API_BASE}}` | `https://api.stripe.com` |
+| `{{RATE_LIMIT_PER_MIN}}` | `60` |
+| `{{CREDENTIAL_ENV_VAR}}` | `STRIPE_API_KEY` |
+| `{{AUTH_HEADER_ENTRY}}` | `Authorization: \`Bearer ${creds.token}\`` (one line; for `X-API-Key` it's `"X-API-Key": creds.token,`) |
+| `{{ACTIONS_DICTIONARY}}` | the JS object literal of action handlers (filled in from interview) |
+| `{{ACTIONS_TABLE_MD}}` | markdown table of actions for the connector's SKILL.md |
+| `{{FIRST_ACTION}}` | first action name, used in the smoke-test invocation |
+
+## Verify
+
+After scaffolding:
+
+```sh
+# 1. Smoke-test the bin in isolation (env vars set, real API call optional).
+<scope>/.connectors/connectors/<slug>/bin/<slug> --action <first-action> --params '{}'
+```
+
+Expectation: a JSON envelope on stdout. Without credentials, expect `{"status":"error","error_code":"CONFIG_ERROR",…}` — that's the **right** shape; we're testing the dispatch plumbing, not connectivity.
+
+```sh
+# 2. End-to-end via the hub.
+node -e 'import("narai-primitives").then(({gather}) => gather({prompt:"call <slug> <first-action>"}).then(r => console.log(JSON.stringify(r, null, 2))))'
+```
+
+Expectation: `gather()` plans `{ connector: "<slug>", action: "<first-action>", … }`, dispatches, returns either a success envelope (with credentials) or the same `CONFIG_ERROR` (without). The dispatch path is what's being verified.
+
+If either fails, the most common causes are:
+- `bin` not executable (`chmod +x`)
+- `config.yaml` `skill:` and `bin:` paths not absolute (must be absolute, not `~/...`)
+- `index.mjs` import path wrong (must be `narai-primitives/toolkit`, not the legacy `@narai/connector-toolkit`)
+
+## Next steps (tell the user)
+
+After verification:
+
+1. **Set the credential**: `export <ENV_VAR>="…"` (or persist in their shell rc).
+2. **Run a real action**: `node <bin> --action <action> --params '<real-params>'`. Should return `{"status":"success","data":…}`.
+3. **(Optional) Add tests**: drop happy-path tests in `tests/` using vitest if installed locally, or skip — these are local connectors; tests are nice-to-have, not required.
+4. **(If broadly useful)** Send a PR to `narailabs/narai-primitives` to promote the connector to a builtin — see that repo's CONTRIBUTING.md for the contributor flow (different scaffolding, with a plugin layer, marketplace entry, etc.).
+
+If the auth scheme was `oauth-with-refresh` or `custom`, also flag: *"You'll need to implement the OAuth/custom flow in the `loadCredentials` block of `index.mjs` before the connector will work against the live API."*
+
+## Pointers
+
+- **Reference**: `references/connector-anatomy.md` — the createConnector contract, envelope shape, error codes.
+- **Auth patterns**: `references/auth-patterns.md` — auth scheme → `loadCredentials` template per scheme.
+- **Action design**: `references/action-design.md` — Zod schema patterns, classifications, handler shape.
+- **DB redirect**: `references/db-agent-pointer.md` — when to point the user at the bundled `db` connector instead.
+- **Builtin connectors** in `narai-primitives` (canonical examples to read for inspiration):
+  - GitHub: https://github.com/narailabs/narai-primitives/tree/main/src/connectors/github
+  - Notion: https://github.com/narailabs/narai-primitives/tree/main/src/connectors/notion
+  - DB (policy-gated, more complex): https://github.com/narailabs/narai-primitives/tree/main/src/connectors/db
+- **Legacy version of this skill** (when connectors used to scaffold as full `@narai/<svc>-agent-connector` repos with their own npm package + plugin layer): see `SKILL.legacy.md` in this directory.

package/plugins/create-connector/skills/create-connector/assets/templates/bin.tmpl

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+# {{SLUG}} connector bin shim — exec the index.mjs in this connector dir.
+# Forward all args + stdin verbatim.
+set -e
+HERE="$(cd "$(dirname "$0")/.." && pwd)"
+exec node "$HERE/index.mjs" "$@"

package/plugins/create-connector/skills/create-connector/assets/templates/connector-SKILL.md.tmpl

@@ -0,0 +1,49 @@
+---
+name: {{SLUG}}-connector
+description: {{DESCRIPTION}}
+---
+
+# {{ServicePascal}} connector
+
+{{DESCRIPTION}}
+
+Loaded by `gather()` from `narai-primitives` via the `connectors.{{SLUG}}` entry in your `.connectors/config.yaml`. Spawn-isolated: each invocation runs in its own Node subprocess.
+
+## Invocation
+
+```sh
+./bin/{{SLUG}} --action <action> --params '<json>'
+```
+
+The CLI prints a single JSON envelope on stdout:
+
+```json
+{ "status": "success", "action": "<name>", "data": { ... } }
+```
+
+Status can be `success`, `error`, `denied`, or `escalate`. Errors carry an `error_code` (`CONFIG_ERROR`, `AUTH_ERROR`, `UPSTREAM_ERROR`, …).
+
+## Actions
+
+{{ACTIONS_TABLE_MD}}
+
+## Credentials
+
+This connector reads `{{CREDENTIAL_ENV_VAR}}` from the environment.
+
+```sh
+export {{CREDENTIAL_ENV_VAR}}="…"
+```
+
+If unset, every action returns `{ "status": "error", "error_code": "CONFIG_ERROR", … }` without touching the API.
+
+## Hub usage
+
+The hub plans actions automatically based on the user's natural-language prompt:
+
+```ts
+import { gather } from "narai-primitives";
+const out = await gather({ prompt: "{{FIRST_ACTION_PROMPT_EXAMPLE}}" });
+```
+
+The planner reads this SKILL.md to decide when to call which action.

package/plugins/create-connector/skills/create-connector/assets/templates/index.mjs.tmpl

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+/**
+ * {{ServicePascal}} connector — {{DESCRIPTION}}
+ *
+ * Local custom connector loaded by `gather()` from `narai-primitives` via
+ * the `connectors.{{SLUG}}` entry in your `.connectors/config.yaml`.
+ *
+ * Run via the bin shim:  ./bin/{{SLUG}} --action <name> --params '<json>'
+ */
+import { createConnector } from "narai-primitives/toolkit";
+import { z } from "zod";
+
+const API_BASE = "{{API_BASE}}";
+const RATE_LIMIT_PER_MIN = {{RATE_LIMIT_PER_MIN}};
+
+// ── Credentials ──────────────────────────────────────────────────────
+//
+// `loadCredentials` runs once per spawn before any handler. Throwing here
+// produces a {status: "error", error_code: "CONFIG_ERROR", …} envelope
+// without touching the API.
+
+async function loadCredentials() {
+  const token = process.env["{{CREDENTIAL_ENV_VAR}}"];
+  if (!token) {
+    throw new Error(
+      `Missing {{CREDENTIAL_ENV_VAR}}. Export it before running this connector.`,
+    );
+  }
+  return { token };
+}
+
+// ── HTTP client ──────────────────────────────────────────────────────
+
+async function request(creds, method, path, body) {
+  const url = new URL(path, API_BASE);
+  const res = await fetch(url, {
+    method,
+    headers: {
+      {{AUTH_HEADER_ENTRY}}
+      "Content-Type": "application/json",
+      "User-Agent": "narai-custom-{{SLUG}}",
+    },
+    body: body ? JSON.stringify(body) : undefined,
+  });
+  if (!res.ok) {
+    const text = await res.text().catch(() => "");
+    throw Object.assign(new Error(`{{ServicePascal}} ${method} ${path} → ${res.status}: ${text.slice(0, 200)}`), {
+      code: res.status === 401 || res.status === 403 ? "AUTH_ERROR" : "UPSTREAM_ERROR",
+    });
+  }
+  return await res.json();
+}
+
+// ── Action surface ───────────────────────────────────────────────────
+//
+// Each entry is { description, params (Zod), classify, handler }.
+// `handler` receives validated params and the loaded credentials; the
+// envelope (success / error / denied / escalate) is wrapped by createConnector.
+
+const connector = createConnector({
+  name: "{{SLUG}}",
+  version: "0.1.0",
+  credentials: loadCredentials,
+
+  actions: {
+    {{ACTIONS_DICTIONARY}}
+  },
+
+  // Optional: if you need rate-limit wrapping, plug in a token-bucket here.
+  // The toolkit doesn't enforce limits by itself.
+  // rateLimit: { perMinute: RATE_LIMIT_PER_MIN },
+});
+
+connector.main(process.argv.slice(2)).then(
+  (code) => process.exit(code),
+  (err) => {
+    process.stderr.write(`Unhandled: ${err?.stack ?? err}\n`);
+    process.exit(1);
+  },
+);

package/plugins/create-connector/skills/create-connector/assets/templates/tests-example.mjs.tmpl

@@ -0,0 +1,45 @@
+/**
+ * Smoke test for the {{SLUG}} connector.
+ *
+ * Runs the bin in a subprocess with no credentials set — should produce a
+ * CONFIG_ERROR envelope (not a thrown exception). That confirms the
+ * dispatch plumbing is sound; live API behavior is out of scope here.
+ *
+ * Run with:  npx vitest run  (vitest must be installed somewhere)
+ *  -- or --  node --test tests/example.test.mjs  (Node's built-in runner)
+ */
+import { describe, it, expect } from "vitest";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const BIN = join(HERE, "..", "bin", "{{SLUG}}");
+
+function run(args, env = {}) {
+  // Strip the credential env var so we get the deterministic CONFIG_ERROR.
+  const cleanEnv = { ...process.env, ...env };
+  delete cleanEnv["{{CREDENTIAL_ENV_VAR}}"];
+  return spawnSync(BIN, args, { encoding: "utf-8", env: cleanEnv });
+}
+
+describe("{{SLUG}} connector", () => {
+  it("emits a JSON envelope on stdout for {{FIRST_ACTION}}", () => {
+    const r = run(["--action", "{{FIRST_ACTION}}", "--params", "{}"]);
+    expect(r.status).toBe(0);
+    const env = JSON.parse(r.stdout.trim());
+    expect(env.action).toBe("{{FIRST_ACTION}}");
+    // No creds → CONFIG_ERROR. Status is 'error' but the envelope is well-formed.
+    expect(env.status).toBe("error");
+    expect(env.error_code).toBe("CONFIG_ERROR");
+  });
+
+  it("rejects an unknown action with a structured error", () => {
+    const r = run(["--action", "nope_does_not_exist", "--params", "{}"]);
+    const env = JSON.parse(r.stdout.trim());
+    expect(env.status).toBe("error");
+    // The toolkit emits VALIDATION_ERROR or ACTION_NOT_FOUND depending on
+    // version — we only assert it's NOT a thrown exception.
+    expect(typeof env.error_code).toBe("string");
+  });
+});

package/plugins/create-connector/skills/create-connector/references/action-design.md

@@ -0,0 +1,133 @@
+# Action design
+
+How to design the action surface of a new connector — what to expose, how to validate, and what classifications to assign.
+
+## What an action is
+
+An action is a named operation the connector exposes. From the user's perspective, it's `--action <name> --params '<json>'`. From the toolkit's perspective, it's an entry in the `actions` dictionary with four fields:
+
+```ts
+get_customer: {
+  description: "Fetch a customer by ID",
+  params: z.object({ id: z.string().min(1) }),
+  classify: { kind: "read" },
+  handler: async (p, ctx) => { /* ... */ },
+}
+```
+
+## Naming conventions
+
+- **Snake case**, lowercase: `get_customer`, `list_charges`, `query_database`.
+- **Verb-first**: `get_*`, `list_*`, `search_*`, `query_*` for reads; `create_*`, `update_*`, `delete_*`, `post_*` for writes.
+- **Don't pluralize**: `list_customers` (plural noun) is fine; `gets_customer` is not.
+
+The naming itself is what the skill uses as a *signal* for default classification — anything starting with `create_`, `update_`, `delete_`, `post_`, `send_`, `revoke_` defaults to non-read.
+
+## Param schemas with Zod
+
+The params field is a Zod schema. The toolkit calls `params.parse(rawParams)` before your handler runs; failures become `VALIDATION_ERROR` envelopes automatically.
+
+Common patterns:
+
+```ts
+// String IDs
+const getCustomerParams = z.object({
+  id: z.string().min(1, "id is required"),
+});
+
+// Optional with default
+const listChargesParams = z.object({
+  customer_id: z.string().optional(),
+  limit: z.coerce.number().int().positive().max(100).default(25),
+});
+
+// UUID validation
+const UUID_RE = /^([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}|[0-9a-f]{32})$/;
+const getPageParams = z.object({
+  page_id: z.string().regex(UUID_RE, "Invalid page_id — expected UUID format"),
+});
+
+// Enum
+const searchParams = z.object({
+  query: z.string().min(1),
+  filter_type: z.enum(["page", "database"]).optional(),
+});
+
+// Free-form JSON
+const queryParams = z.object({
+  filter: z.record(z.unknown()).nullable().default(null),
+});
+```
+
+`z.coerce.number()` is useful because CLI params come in as strings; it converts them to numbers without the user having to quote them differently.
+
+## Classification
+
+Every action carries a `classify: { kind: ... }`. The toolkit's policy gate uses this to decide whether to run the handler, ask for approval, escalate, or deny.
+
+| `kind` | Examples | Default approval mode |
+|---|---|---|
+| `read` | `get_*`, `list_*`, `search_*`, `query_*` | `auto` (no prompt) |
+| `write` | `create_*`, `update_*`, `post_*`, `send_*` | `confirm_once` (per session) |
+| `delete` | `delete_*`, `remove_*`, `archive_*` | `confirm_each` (per call) |
+| `admin` | role/permission changes, user provisioning | `grant_required` (out-of-band) |
+| `privilege` | `grant_*`, `revoke_*` on access controls | `grant_required` |
+
+The defaults are sensible but not hard rules; the user can override per action during interview.
+
+## The handler signature
+
+```ts
+handler: async (params, ctx) => {
+  // params is fully validated (Zod has run)
+  // ctx has: sdk (your client), creds, name, action
+  const result = await ctx.sdk.getCustomer(params.id);
+  throwIfError(result);  // converts !ok results into a thrown ServiceError
+  return {
+    id: result.data.id,
+    email: result.data.email,
+    // shape what you return — this becomes envelope.data
+  };
+}
+```
+
+Don't return the raw API response — pick out the fields the user actually wants. The shape you return is the contract callers see.
+
+If you throw, the toolkit catches and runs `mapError(err)` to translate. If `mapError` returns `undefined`, the toolkit falls back to `CONNECTION_ERROR` with the error message.
+
+## Approval modes (when classification is non-read)
+
+The toolkit reads the connector's policy config (`~/.connectors/<slug>/config.yaml` or `.connectors/<slug>/config.yaml` in cwd) and resolves an approval mode per action:
+
+- `auto` — handler runs, no prompt.
+- `confirm_once` — first call in a session prompts the user; subsequent calls auto-allow.
+- `confirm_each` — every call prompts.
+- `grant_required` — refuses to run unless the user has issued a `--grant` token via the toolkit's grant CLI.
+
+When the user defines a write/delete action during interview, the skill asks which approval mode to default to. Most users want `confirm_once` for writes, `grant_required` for delete/admin/privilege.
+
+**Write-action happy-path tests need a permissive config in scope.** The toolkit's default policy escalates writes when no operator config is present. So for a connector that exposes any non-`read` action, the unit tests that assert `success` for the write action must set up a temp `HOME`/`cwd` with a permissive `.{name}-agent/config.yaml` (e.g., `policy: { write: success }, approval_mode: auto`) in `beforeAll`, and tear it down in `afterAll`. Read-only happy-path tests don't need this — `read` defaults to `allow`. The skill's `tests/integration/framework.test.ts.tmpl` already does this pattern for the escalate test; mirror it for write-action happy paths.
+
+## Non-HTTP shapes (CLI-wrap, RPC, anything not REST/GraphQL)
+
+The default `client.ts.tmpl` is HTTP-shaped: it bakes in `validateUrl`, `_throttle`, `_authHeaders`, `request<T>(method, relPath, ...)`, `Retry-After` parsing, and `fetchImpl` injection. For connectors that don't speak HTTP — e.g., wrapping a CLI binary via `child_process.execFile`, an RPC client, or anything else — write the client from scratch instead of trying to retrofit the HTTP frame. Preserve these load-bearing contracts so the rest of the toolkit fits:
+
+- The same `Result<T>` discriminated union: `{ ok: true; data: T; status: number } | { ok: false; code: string; message: string; retriable: boolean; status?: number }`. Many tests + the `index.ts` handlers depend on this shape.
+- An exported `load<Service>Credentials()` function (returns `{}` if the wrapped tool authenticates itself locally, or whatever object the client constructor expects).
+- The matching `<Service>Error` bridge class in `error.ts`.
+- The same `CODE_MAP` shape in `index.ts`.
+
+For test-time injection, mirror the `fetchImpl` pattern with a shape-appropriate analog (e.g., `execFileImpl` for CLI wraps, `clientImpl` for RPC). Tests then stub the analog instead of `fetchImpl`. The `cli.test.ts` and `client_extras.test.ts` template helpers will need adapting — that's expected for non-HTTP shapes.
+
+## What NOT to expose as actions
+
+- **Internal pagination cursors** — handle pagination inside the handler; expose a single `list_*` action that does the full pass (capped at a reasonable max).
+- **Auth flows** — credentials come from env/config; never let the user pass them as action params.
+- **Raw HTTP plumbing** — if the user could call your underlying client directly, they'd just use `curl`. The connector's value is the *shaped, validated, gated* surface.
+- **Secrets in responses** — the toolkit scrubs known secret patterns, but don't rely on it; redact in the handler.
+
+## Examples from existing connectors
+
+- `notion-agent-connector` — 7 actions: `search`, `get_page`, `get_database`, `query_database`, `list_attachments`, `get_attachment`, `get_comments`. All `read`.
+- `github-agent-connector` — multiple read actions over Octokit. All `read`.
+- `db-agent-connector` — single `query` action; classification is computed at runtime by parsing the SQL. (This is the one connector where the classification is dynamic.)

package/plugins/create-connector/skills/create-connector/references/auth-patterns.md

@@ -0,0 +1,122 @@
+# Auth patterns
+
+The skill supports the common auth schemes natively. For each, this doc shows what the scaffold produces and what the user has to provide.
+
+## Pattern 1: Bearer token via env var (default)
+
+The dominant case. Notion, Linear, Stripe, most public REST APIs.
+
+**Interview answer**: `bearer-token-env-var` + env var name (e.g., `STRIPE_API_KEY`).
+
+**Scaffold output**:
+
+- `src/cli.ts`:
+  ```ts
+  const STRIPE_ENV_MAPPING: Record<string, string> = {
+    token: "STRIPE_API_KEY",
+  };
+  ```
+- `src/lib/stripe_client.ts` `loadStripeCredentials()`:
+  ```ts
+  const token = (await resolveSecret("STRIPE_API_KEY")) ?? process.env["STRIPE_API_KEY"] ?? null;
+  if (!token) return null;
+  return { token };
+  ```
+- `_authHeaders()`:
+  ```ts
+  return {
+    Authorization: `Bearer ${this._token}`,
+    "User-Agent": USER_AGENT,
+    Accept: "application/json",
+  };
+  ```
+
+## Pattern 2: API-key header (X-API-Key etc.)
+
+For services that reject `Authorization: Bearer` and want a custom header. Think internal APIs, some partner integrations.
+
+**Interview answer**: `api-key-header-env-var` + env var name + header name (e.g., `X-API-Key`).
+
+**Scaffold differences from pattern 1**: `_authHeaders()` becomes:
+```ts
+return {
+  "X-API-Key": this._token,
+  "User-Agent": USER_AGENT,
+  Accept: "application/json",
+};
+```
+
+The `loadCredentials` and `cli.ts` env mapping are otherwise the same — only the header construction differs.
+
+## Pattern 3: Multi-secret (token + extra context)
+
+Like GitHub, where the token alone isn't sufficient — you also need an owner / org / workspace ID. The cli.ts env mapping has multiple entries:
+
+```ts
+const GITHUB_ENV_MAPPING: Record<string, string> = {
+  token: "GITHUB_TOKEN",
+  owner: "GITHUB_OWNER",
+};
+```
+
+**Scaffold differences**: 
+- `ServiceClientOptions` adds extra fields (`owner: string`, etc.).
+- `loadCredentials()` resolves all of them; missing required fields return `null`.
+- The client class stores the extras as private fields and uses them when constructing URLs (e.g., `${this._apiBase}/repos/${this._owner}/...`).
+
+## Pattern 4: Basic auth (username + password)
+
+Rare in modern APIs but still seen with internal tooling.
+
+**Interview answer**: `basic-auth` + env var names for user + pass.
+
+**Scaffold differences**: `_authHeaders()` becomes:
+```ts
+const credentials = Buffer.from(`${this._user}:${this._pass}`).toString("base64");
+return {
+  Authorization: `Basic ${credentials}`,
+  "User-Agent": USER_AGENT,
+  Accept: "application/json",
+};
+```
+
+## Pattern 5: OAuth with refresh tokens (NOT TEMPLATED)
+
+The skill does **not** scaffold OAuth flows. None of the existing connectors implement this; it's genuinely novel territory per service.
+
+**What the scaffold produces**: a placeholder `loadCredentials()` that throws `CONFIG_ERROR` with a TODO message:
+```ts
+export async function loadServiceCredentials(): Promise<{ access_token: string } | null> {
+  // TODO: implement OAuth flow.
+  // - Read a refresh token from `resolveSecret("SERVICE_REFRESH_TOKEN")`
+  // - Exchange it at the provider's token endpoint for an access token
+  // - Cache the access token (in-memory or via credential-providers) until expiry
+  // See https://oauth.net/2/grant-types/refresh-token/ for the canonical flow.
+  throw new Error("OAuth not implemented — see TODO in loadServiceCredentials");
+}
+```
+
+The user fills this in. The skill flags this clearly during interview and the post-scaffold next-steps.
+
+## Pattern 6: Custom (mTLS, signed URLs, anything else)
+
+For schemes that don't fit any of the above (mutual TLS, request signing, ephemeral session tokens). The skill scaffolds with a simplified `loadCredentials()` that returns an empty object and points the user at:
+
+- `notion-agent-connector/src/lib/notion_client.ts` for a Bearer reference
+- `aws-agent-connector` (in the workspace) for SDK-mediated credentials
+
+## Where credentials get resolved at runtime
+
+The `cli.ts` runs `loadConnectorEnvironment("<slug>", { envMapping })` from `@narai/connector-config`. This:
+
+1. Reads `~/.connectors/config.yaml` (or `NARAI_CONFIG_BLOB` if injected by `connector-hub`).
+2. Maps configured fields (`token`, `owner`, etc.) to env var names per `envMapping`.
+3. Sets `process.env.<NAME>` only if not already set — existing env wins.
+
+Inside the client, `resolveSecret(envName)` from `@narai/credential-providers` checks cloud-backed stores first, then falls back to `process.env`. This means a user can either:
+
+- Set `STRIPE_API_KEY` directly in their shell, OR
+- Configure it in `~/.connectors/config.yaml`, OR
+- Register a custom credential provider via `@narai/credential-providers`
+
+All three paths work without code changes.

package/plugins/create-connector/skills/create-connector/references/connector-anatomy.md

@@ -0,0 +1,116 @@
+# Connector anatomy
+
+The canonical shape of an action-dispatch connector built on `@narai/connector-toolkit@^3.x`. Read this when you need a fuller picture than what `SKILL.md` covers — typically when scaffolding something unusual or debugging why a generated file is shaped the way it is.
+
+## The two surfaces
+
+Every connector exposes two consumption modes from the same code:
+
+- **CLI** — `npx <pkg> --action <name> --params '<json>'` emits a JSON envelope on stdout. Implemented by `connector.main(argv)` from the toolkit. Stdout is JSON-only; diagnostics go to stderr.
+- **Library** — `import { fetch } from "@narai/<pkg>"; await fetch(action, params)` returns the same envelope as a JS object. Implemented by `connector.fetch(action, params)`.
+
+Both are returned by a single `createConnector<TSdk>` call. You don't write the dispatch logic — the toolkit does.
+
+## The factory call
+
+```ts
+return createConnector<MyClient>({
+  name: "myservice",                     // connector slug; used for audit, hardship, policy
+  version: "0.1.0",
+  scope: (ctx) => ctx.sdk.workspaceId,   // optional: returns a tenant id; null = global tier
+  credentials: async () => ({...}),       // resolved creds; passed to sdk if you call it manually
+  sdk: async () => new MyClient({...}),   // build the client; called once per main()/fetch()
+  actions: { /* action dictionary */ },
+  mapError: (err) => {/* ... */},        // optional: translate exceptions to canonical envelopes
+});
+```
+
+The toolkit owns:
+
+- Argument parsing (`parseAgentArgs` strict whitelist)
+- Zod validation of `params` per action
+- Policy-gate evaluation (classification + approval mode + rules)
+- Audit JSONL emission
+- Hardship JSONL recording
+- Envelope construction (success / denied / escalate / error)
+- The `--curate` flag
+
+You own:
+
+- Action definitions (Zod schema + classification + handler)
+- The HTTP/SDK client itself
+- Error mapping from your client's internal codes to toolkit's canonical taxonomy
+
+## The action dictionary
+
+```ts
+actions: {
+  get_customer: {
+    description: "Fetch a customer by ID",
+    params: z.object({ id: z.string().min(1) }),
+    classify: { kind: "read" },
+    handler: async (p, ctx) => {
+      const result = await ctx.sdk.getCustomer(p.id);
+      throwIfError(result);
+      return result.data;     // becomes envelope.data
+    },
+  },
+  // ...
+}
+```
+
+- `description` — surfaced by `--help` and the toolkit's introspection. Keep it tight.
+- `params` — a Zod schema. The toolkit validates inputs before calling the handler; validation failures become a `VALIDATION_ERROR` envelope with no handler invocation.
+- `classify` — `{ kind: "read" | "write" | "delete" | "admin" | "privilege" }`. Drives the policy gate and approval-mode resolution. Default to `read` unless the action genuinely mutates state.
+- `handler` — receives validated params + a context with `sdk` (your client), `creds`, `name`, `action`. Whatever you return becomes the envelope's `data` field. If you throw, `mapError` decides how to translate.
+
+## The Result-envelope client pattern
+
+Inside `src/lib/<svc>_client.ts`, methods return a discriminated union rather than throwing:
+
+```ts
+export type ServiceResult<T> =
+  | { ok: true; data: T; status: number }
+  | { ok: false; code: string; message: string; retriable: boolean; status?: number };
+```
+
+Why: it lets the client express *expected failures* (rate limit, auth error, network) declaratively, while the toolkit's handler-throws-an-Error contract takes over for the *unexpected* path. The bridge is `throwIfError(result)` in the handler:
+
+```ts
+function throwIfError<T>(r: ServiceResult<T>): asserts r is Extract<ServiceResult<T>, { ok: true }> {
+  if (!r.ok) throw new ServiceError(r.code, r.message, r.retriable, r.status);
+}
+```
+
+`ServiceError` carries the service-internal code; `mapError` translates it to a toolkit canonical code (`AUTH_ERROR`, `NOT_FOUND`, `RATE_LIMITED`, `TIMEOUT`, `VALIDATION_ERROR`, `CONFIG_ERROR`, `CONNECTION_ERROR`).
+
+## Required client features
+
+The frame in `client.ts.tmpl` covers all of these — don't reinvent:
+
+- **Sliding-window rate limit** (per-minute) with a configurable cap.
+- **Retry loop** (max 4 attempts) on retriable errors: 5xx, 429, network/timeout. Honors `Retry-After` header when present; falls back to exponential backoff (capped at 30s).
+- **HTTP method allowlist**: only `GET`, `POST`, `PUT`, `PATCH`, `DELETE` reach the wire. The default template covers all five so you don't need to extend.
+- **URL validation** via `validateUrl` from the toolkit (rejects non-http/https).
+- **Dependency injection**: `fetchImpl` and `sleepImpl` are constructor options so tests can mock without touching the global fetch.
+- **Configurable timeouts**: `connectTimeoutMs` (default 10s) + `readTimeoutMs` (default 30s); enforced by an `AbortController`.
+
+## Error code taxonomy
+
+| Toolkit code | When |
+|---|---|
+| `AUTH_ERROR` | 401, 403, missing/invalid credentials |
+| `NOT_FOUND` | 404 |
+| `RATE_LIMITED` | 429 |
+| `TIMEOUT` | Request aborted on timer |
+| `VALIDATION_ERROR` | 400, 422, Zod validation failure, invalid URL/method |
+| `CONFIG_ERROR` | Credentials not configured, connector misconfigured |
+| `CONNECTION_ERROR` | 5xx, network errors, anything else |
+
+Map your service's internal codes (e.g., Stripe's `card_declined`) to these via `CODE_MAP`.
+
+## What to read in the codebase for examples
+
+- `/Users/narayan/src/connectors/notion-agent-connector/src/index.ts` — full factory call with 7 actions
+- `/Users/narayan/src/connectors/notion-agent-connector/src/lib/notion_client.ts` — full Result-envelope client
+- `/Users/narayan/src/connectors/connector-toolkit/src/index.ts` — toolkit's public API surface (the contract you're consuming)

package/plugins/create-connector/skills/create-connector/references/db-agent-pointer.md

@@ -0,0 +1,84 @@
+# Pointer: when to use db-agent-connector instead
+
+If the user wants to query a database from Claude, the answer is almost always **install and configure the existing `db-agent-connector`**, not scaffold a new connector. This doc explains why and how to redirect.
+
+## What db-agent-connector already does
+
+Lives at `/Users/narayan/src/connectors/db-agent-connector/`. Single CLI surface, single library API, single Claude Code plugin — but speaks to **seven** database systems through a pluggable driver registry:
+
+- PostgreSQL (`pg`)
+- MySQL / MariaDB (`mysql2`)
+- SQLite (`better-sqlite3`)
+- Microsoft SQL Server (`mssql`)
+- MongoDB (`mongodb`)
+- Amazon DynamoDB (`@aws-sdk/client-dynamodb`)
+- Oracle (`oracledb`)
+
+Drivers are `optionalDependencies`, lazy-loaded on first use. A user querying only SQLite doesn't carry the weight of `pg` or `mssql`.
+
+## Why a fresh action-dispatch connector is the wrong shape
+
+- **Multi-state envelope**: db-agent emits `ok` / `present_only` / `denied` / `escalate` / `error`. The `present_only` state is unique to db-agent — it returns formatted SQL for the user to review without executing. Action-dispatch connectors don't have this state, and adding it ad-hoc would mean reimplementing db-agent's policy engine.
+- **Operator-configurable safety**: db-agent reads policy rules from `~/.connectors/config.yaml` (V2.0 layout) under the `connectors.db.policy` slice: classifications `read` / `write` / `delete` / `admin` / `privilege` map to actions `allow` / `present` / `escalate` / `deny`. Plus `unbounded_select` (escalate SELECTs without WHERE/LIMIT) and a safety floor that rejects `admin: allow` and `privilege: allow`. Operator-tunable per server via the optional per-server `policy` block.
+- **SQL keyword classification**: db-agent classifies queries by parsing the SQL keyword (`SELECT` → read, `INSERT/UPDATE/DELETE` → write, `CREATE/ALTER/DROP` → delete, `GRANT/REVOKE` → privilege). The toolkit's static `classify` field can't do this because the action shape is just "run this query".
+- **Stateful connection pooling** with per-server config (driver, host, db, credentials, approval mode).
+
+If a new connector tried to replicate this, it would be a ~2000-line lift duplicating work db-agent already shipped.
+
+## How to redirect the user
+
+When the interview triages to `database`:
+
+1. **Identify the backend**: ask which DB engine. If it's one of the seven listed above, use db-agent. If it's something else (Snowflake, BigQuery, ClickHouse, Redis), see "Genuinely novel backends" below.
+
+2. **Confirm db-agent is installed**: check whether `/Users/narayan/src/connectors/db-agent-connector/` has `node_modules/`. If not, `cd` there and run `npm install`.
+
+3. **Walk through `~/.connectors/config.yaml`** (V2.0 layout — single shared config file with a `connectors.db.*` slice). Tell the user to read `db-agent-connector/CLAUDE.md` for the authoritative format. A minimal example:
+
+   ```yaml
+   connectors:
+     db:
+       policy:
+         read: allow
+         write: present
+         delete: present
+         admin: deny       # safety floor — `allow` is rejected by validation
+         privilege: deny   # safety floor — `allow` is rejected by validation
+         unbounded_select: escalate   # SELECTs lacking WHERE/LIMIT/OFFSET get escalated
+
+       servers:
+         prod:
+           driver: postgres
+           host: db.acme.com
+           database: app
+           user: readonly
+           password: env:PROD_PG_PASSWORD   # provider:key form — see below
+           approval_mode: confirm_each
+
+       audit:
+         enabled: true
+         path: ~/.connectors/db-agent/audit.jsonl
+   ```
+
+   Repo-level overlay: `./.connectors/config.yaml` wins on per-key conflicts with the user-level file.
+
+   Credential references inside the slice use a `provider:key` form: `env:VAR_NAME`, `keychain:NAME`, `file:path.json:dotted.key`, `cloud:alias`. Plain strings without a recognized prefix pass through as literals. Set the env var in your shell as usual.
+
+4. **Smoke test**: `npx db-agent-connector --action query --params '{"server":"prod","sql":"SELECT 1"}'`.
+
+The skill should produce this redirect without scaffolding any new files.
+
+## Genuinely novel backends
+
+If the user wants to query a backend db-agent doesn't yet support (Snowflake, BigQuery, ClickHouse, Redis, etc.):
+
+- **Suggest extending db-agent's driver registry**, not building a fresh connector. The driver interface lives at `db-agent-connector/src/lib/drivers/`. Adding a new driver gets the user the policy gate, audit, escalation, and approval modes for free.
+- If the user *insists* on a fresh action-dispatch connector for a non-SQL store (e.g., a key-value lookup that doesn't need policy gating), the skill can scaffold it — but warn that they're duplicating infrastructure db-agent already provides.
+
+## Critical files for the user to read
+
+- `/Users/narayan/src/connectors/db-agent-connector/CLAUDE.md` — authoritative documentation for db-agent.
+- `/Users/narayan/src/connectors/db-agent-connector/src/connector.ts` — the policy-gate orchestration.
+- `/Users/narayan/src/connectors/db-agent-connector/src/lib/policy.ts` — the SQL keyword classifier.
+- `/Users/narayan/src/connectors/db-agent-connector/src/lib/plugin_config.ts` — config schema.
+- `/Users/narayan/src/connectors/db-agent-connector/src/lib/drivers/` — driver registry pattern (for extension).

package/plugins/create-connector/skills/create-connector/references/plugin-layer.md

@@ -0,0 +1,115 @@
+# The Claude Code plugin layer
+
+Every connector ships a `plugin/` subdirectory that lets Claude Code install and invoke it without any manual setup. Read this when scaffolding the plugin layer or debugging why the SessionStart hook isn't picking up changes.
+
+## What lives in plugin/
+
+```
+plugin/
+├── .claude-plugin/
+│   └── plugin.json              # Manifest (name, version, description, author)
+├── hooks/
+│   ├── hooks.json               # SessionStart, PostToolUse, SessionEnd hooks
+│   └── reminder.mjs             # Best-effort SessionStart curation banner
+├── bin/
+│   └── <svc>-agent              # Bash shim that execs the published CLI
+├── skills/
+│   └── <svc>-agent/
+│       └── SKILL.md             # Tells Claude how/when to invoke the bin
+└── commands/
+    └── <svc>-agent.md           # Slash command (/<svc>-agent <action> <params>)
+```
+
+The whole `plugin/` tree is excluded from the npm tarball via `.npmignore`. Claude Code installs from the source repo, not from npm.
+
+## The SessionStart hook (hooks.json)
+
+Three commands run at session start, in order:
+
+1. **Idempotent npm install**
+   ```
+   diff -q "${CLAUDE_PLUGIN_ROOT}/package.json" "${CLAUDE_PLUGIN_DATA}/package.json" \
+     || (mkdir -p "${CLAUDE_PLUGIN_DATA}" && cp "${CLAUDE_PLUGIN_ROOT}/package.json" "${CLAUDE_PLUGIN_DATA}/" \
+         && cd "${CLAUDE_PLUGIN_DATA}" && npm install --no-audit --no-fund) \
+     || rm -f "${CLAUDE_PLUGIN_DATA}/package.json"
+   ```
+
+   Diffs the plugin's `package.json` against the cached copy in `${CLAUDE_PLUGIN_DATA}`. If different (or missing), copies + runs `npm install`. On failure, removes the partial copy so the next session retries cleanly. This is what makes `node_modules/@narai/<pkg>/dist/cli.js` available to the bash shim.
+
+2. **Service-specific reminder** (`reminder.mjs`) — best-effort import of the toolkit's nudge module to print a banner if the user has enabled curation. Never blocks startup.
+
+3. **Toolkit stale-summarize hook** — invokes `connector-toolkit/plugin-hooks/stale-summarize.mjs` to surface session activity. Tagged with `USAGE_CONNECTOR_NAME` for cross-connector aggregation.
+
+## PostToolUse + SessionEnd hooks
+
+- **PostToolUse** with matcher `Bash` — invokes `usage-record.mjs` after every Bash call to capture connector usage events. Tagged with `USAGE_CONNECTOR_NAME` and `USAGE_BIN_HINT` for telemetry.
+- **SessionEnd** — invokes `session-summary.mjs` to write an end-of-session summary. Same tagging.
+
+All four hook commands swallow errors (`|| true`) — no plugin should ever wedge a session.
+
+## The bash shim (bin/<svc>-agent)
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+
+if [ -z "${CLAUDE_PLUGIN_DATA:-}" ]; then
+  echo "<svc>-agent: CLAUDE_PLUGIN_DATA is not set (run from inside Claude Code)" >&2
+  exit 2
+fi
+
+CLI="${CLAUDE_PLUGIN_DATA}/node_modules/@narai/<svc>-agent-connector/dist/cli.js"
+
+if [ ! -f "$CLI" ]; then
+  echo "<svc>-agent: connector CLI not found at $CLI" >&2
+  echo "Restart your Claude Code session to re-run the SessionStart install hook." >&2
+  exit 2
+fi
+
+exec node "$CLI" "$@"
+```
+
+`CLAUDE_PLUGIN_DATA` is set by the runtime to a session-specific cache directory. The shim hands off to `node` with `exec` so the Node process *replaces* the bash process — no fork overhead, signals propagate correctly.
+
+If the CLI is missing, the shim tells the user to restart the session (which re-runs the SessionStart install hook). It does NOT try to install from inside the shim, because that would block on first invocation.
+
+## The plugin SKILL.md (skills/<svc>-agent/SKILL.md)
+
+This is what Claude actually reads to decide when to invoke the connector. Keep it tight:
+
+- **Frontmatter**: `name`, `description`, `context: fork`. The description triggers the skill — make it specific to the service ("read-only Notion content"), not generic.
+- **Body**: invocation syntax (`<svc>-agent --action <name> --params '<json>'`), supported actions table, credentials note, safety statement.
+
+The `context: fork` directive matters: it tells Claude Code to load this skill into a subagent context rather than the main one, keeping conversation context clean.
+
+## The slash command (commands/<svc>-agent.md)
+
+A 7-line markdown file with frontmatter + a one-line body:
+
+```markdown
+---
+description: Run a <svc> action via the <svc>-agent connector
+argument-hint: "<action> <params-json>"
+---
+
+Invoke the `<svc>-agent` skill with the user's $ARGUMENTS as the action name and params JSON. Return the connector's JSON envelope verbatim.
+```
+
+This adds `/<svc>-agent <action> <params-json>` as a typed shortcut for the skill.
+
+## The .npmignore at repo root
+
+Excludes everything that's not the published library:
+
+```
+src/
+tests/
+plugin/
+evals/
+vitest.config.ts
+tsconfig.json
+.gitignore
+.git/
+```
+
+Result: the published npm tarball contains only `dist/`, `README.md`, and `LICENSE`. The plugin lives in the source repo.

package/plugins/create-connector/skills/create-connector/references/template-sync.md

@@ -0,0 +1,71 @@
+# Template sync strategy
+
+Templates in `assets/templates/connector/` are snapshots of `notion-agent-connector` files (the canonical reference) at a specific point in time. They will drift as the canonical pattern evolves — toolkit upgrades, new hook types, version pin bumps, etc. This doc tells you how to detect and apply that drift.
+
+## Last synced
+
+- **Date**: 2026-04-26
+- **Source connector**: `/Users/narayan/src/connectors/notion-agent-connector/`
+- **Toolkit version pinned**: `@narai/connector-toolkit ^3.1.0` (workspace published `3.4.0`)
+- **Sibling pins**: `@narai/credential-providers ^0.2.1`, `@narai/connector-config ^1.1.0`, `zod ^3.23.0`
+
+## Source-of-truth file mapping
+
+| Template | Canonical source | Substitutions applied |
+|---|---|---|
+| `package.json.tmpl` | `notion-agent-connector/package.json` | `notion` → `{{SERVICE_SLUG}}`, version reset to `0.1.0` |
+| `tsconfig.json` | `notion-agent-connector/tsconfig.json` | none (literal copy) |
+| `vitest.config.ts.tmpl` | `notion-agent-connector/vitest.config.ts` | `TEST_LIVE_NOTION` → `TEST_LIVE_{{SERVICE_SLUG_UPPER}}` |
+| `LICENSE` | `notion-agent-connector/LICENSE` | none |
+| `.npmignore` | `notion-agent-connector/.npmignore` | comment line slug |
+| `README.md.tmpl` | `notion-agent-connector/README.md` | name, action table, env var name |
+| `src/cli.ts.tmpl` | `notion-agent-connector/src/cli.ts` | `NOTION` → slug, env mapping body |
+| `src/lib/error.ts.tmpl` | `notion-agent-connector/src/lib/notion_error.ts` | `Notion` → `{{ServicePascal}}` |
+| `src/lib/client.ts.tmpl` | `notion-agent-connector/src/lib/notion_client.ts` (frame only) | full reshape (auth header, methods, types removed) |
+| `src/index.ts.tmpl` | `notion-agent-connector/src/index.ts` (skeleton only) | full reshape (param schemas, actions removed) |
+| `tests/unit/cli.test.ts.tmpl` | `notion-agent-connector/tests/unit/cli.test.ts` (helpers only) | service-name swap |
+| `tests/unit/client_extras.test.ts.tmpl` | per-method test pattern from notion's tests | starter slot |
+| `tests/integration/framework.test.ts.tmpl` | `notion-agent-connector/tests/integration/framework.test.ts` (one happy-path) | service-name swap |
+| `plugin/.claude-plugin/plugin.json.tmpl` | `notion-agent-connector/plugin/.claude-plugin/plugin.json` | name + description |
+| `plugin/hooks/hooks.json.tmpl` | `notion-agent-connector/plugin/hooks/hooks.json` | `notion` → slug |
+| `plugin/hooks/reminder.mjs.tmpl` | `notion-agent-connector/plugin/hooks/reminder.mjs` | `notion` → slug |
+| `plugin/bin/service-agent.tmpl` | `notion-agent-connector/plugin/bin/notion-agent` | `notion` → slug, package name |
+| `plugin/skills/service-agent/SKILL.md.tmpl` | `notion-agent-connector/plugin/skills/notion-agent/SKILL.md` | full reshape |
+| `plugin/commands/service-agent.md.tmpl` | `notion-agent-connector/plugin/commands/notion-agent.md` | `notion` → slug |
+
+## Re-sync procedure
+
+When notion-agent-connector changes in a way that should propagate to new scaffolds:
+
+1. **Identify the changed file(s)** in notion-agent. If it's a content change to a templated file, the template needs updating. If it's notion-specific behavior (e.g., a new Notion API endpoint), don't propagate.
+
+2. **Diff the canonical against the template** (treating placeholders as free variables):
+   ```bash
+   diff -u \
+     <(sed 's/notion/{{SERVICE_SLUG}}/g; s/Notion/{{ServicePascal}}/g; s/NOTION/{{SERVICE_SLUG_UPPER}}/g' /Users/narayan/src/connectors/notion-agent-connector/<file>) \
+     /Users/narayan/.claude/skills/create-connector/assets/templates/connector/<file>.tmpl
+   ```
+
+3. **Apply non-substitution diffs** to the template. Test by scaffolding a fresh connector and running `npm install && npm run build && npm run typecheck && npm test`.
+
+4. **Update this doc**: bump the "Last synced" date and any version pins that changed.
+
+## Major bump checklist
+
+When `@narai/connector-toolkit` ships a major version (e.g., `^3.x` → `^4.0.0`):
+
+1. Read the toolkit's CHANGELOG for breaking changes.
+2. Update the version pin in `package.json.tmpl`.
+3. Re-run all eval test cases in `evals/evals.json` against the new toolkit. Confirm scaffolds still build clean.
+4. Update template internals if APIs shifted (e.g., `createConnector` signature, error code taxonomy, `mapError` semantics).
+5. Update `references/connector-anatomy.md` with any contract changes.
+
+## Detecting drift in the wild
+
+The skill's verification step (`npm install && npm run build && npm run typecheck && npm test` on a fresh scaffold) catches drift the moment a new connector fails to build. If a user reports "scaffold doesn't typecheck against latest toolkit", that's the trigger to re-sync.
+
+Soft signals to watch for:
+
+- A new connector PR in the workspace adds a file the templates don't have.
+- The toolkit publishes a new helper that materially simplifies client code.
+- A new plugin hook type appears in another connector's `hooks.json`.

package/plugins/create-connector/skills/create-connector/references/verification.md

@@ -0,0 +1,103 @@
+# Verification
+
+Step-by-step smoke test for a freshly scaffolded connector. Run this before declaring the scaffold "done".
+
+## Prerequisites
+
+- The new connector lives at `<workspace>/<svc>-agent-connector/` (default: `/Users/narayan/src/connectors/<svc>-agent-connector/`).
+- Node 20+ is available (`node --version`).
+- The npm scope `@narai` is reachable (the connector depends on `@narai/connector-toolkit`, `@narai/credential-providers`, `@narai/connector-config`).
+
+## Steps
+
+### 1. Install dependencies
+
+```bash
+cd <new-connector-dir>
+npm install
+```
+
+Expect: clean install, no warnings about missing peers (carets resolve).
+
+If `npm install` fails on `@narai/*` packages, the user may not have access to the private npm scope. The skill should flag this.
+
+### 2. Build
+
+```bash
+npm run build
+```
+
+Expect: `dist/` directory populated with compiled JS + `.d.ts`. No TS errors.
+
+If errors mention "Cannot find module '@narai/connector-toolkit'", install failed silently — re-run step 1 with `--verbose`.
+
+If errors mention strict TS settings (`exactOptionalPropertyTypes`, `noUnusedParameters`), the generated code has issues. Read the error, fix, re-run.
+
+### 3. Typecheck
+
+```bash
+npm run typecheck
+```
+
+Expect: silent success.
+
+This is mostly redundant with `build`, but it's faster (no emit) and catches anything `tsc` would warn about. Useful in CI.
+
+### 4. Test
+
+```bash
+npm test
+```
+
+Expect: vitest reports all tests passing.
+
+Common failures:
+- **Mock fetch returns wrong shape**: the test's `jsonResponse({...})` body doesn't match what the client method expects. Check the action's response shape contract.
+- **Rate limiter sleeps in test**: `sleepImpl` should be `async () => {}` (no-op) in tests.
+- **Hardship logger writes to real `~/.claude/`**: integration tests should set `process.env.HOME` to a tmpdir; check `beforeEach`.
+
+### 5. Smoke envelope
+
+```bash
+node dist/cli.js --action <first-action> --params '{}'
+```
+
+Expect: a JSON object on stdout. Without credentials configured, you'll see something like:
+
+```json
+{
+  "status": "error",
+  "action": "<first-action>",
+  "error_code": "CONFIG_ERROR",
+  "message": "<service> credentials not configured. Set <SVC>_TOKEN or register a credential provider via @narai/credential-providers.",
+  "retriable": false
+}
+```
+
+That's the **right** shape — the CLI plumbing works end-to-end. We're testing the envelope structure, not connectivity.
+
+If the output is **not** valid JSON (e.g., a stack trace, "command not found", or shell noise), something is broken upstream. Common causes:
+
+- `dist/cli.js` doesn't exist → step 2 (build) failed.
+- The shebang `#!/usr/bin/env node` is missing or the file isn't executable → re-check the cli.ts template.
+- An import error → check `package.json` "type": "module" and `tsconfig.json` "module": "NodeNext".
+
+### 6. (Optional) Live connectivity test
+
+Only if the user has real credentials and asks for it:
+
+```bash
+export <SVC>_TOKEN="..."
+node dist/cli.js --action <first-action> --params '<real-params>'
+```
+
+Expect: `status: "success"` with shaped data. If you get `AUTH_ERROR`, the token is wrong; if `NOT_FOUND`, the resource id doesn't exist; if `CONNECTION_ERROR`, the API is unreachable.
+
+## Verification of the skill itself (not a scaffold)
+
+Separate from per-scaffold verification, the skill itself should be sanity-checked periodically:
+
+1. Open `SKILL.md`, confirm < 500 lines and frontmatter is well-formed.
+2. Spot-check that all referenced files in `references/*.md` exist.
+3. Run the eval set in `evals/evals.json` through skill-creator's eval loop (see `~/.claude/plugins/cache/claude-plugins-official/skill-creator/`).
+4. After a major scaffold change, manually run test case 1 (Stripe) and `diff` the resulting tree against `notion-agent-connector/` (ignoring service-name substitutions).