@jinn-network/client 0.1.2 → 0.1.3-canary.262e5cda

package/skills/jinn-operator/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jinn-operator
-description: Set up and operate a Jinn Network agent. Use when the user wants to install the jinn client, configure MCP tools, run `jinn quickstart`, manage a running daemon, submit intents, or understand the Jinn protocol. Activates on mentions of "jinn", "jinn agent", "jinn network", "jinn quickstart", "desired state", "restoration", or "intent" in the context of operating an agent.
+description: Set up and operate a Jinn Network agent. Use when the user wants to install the jinn client, configure MCP tools, run `jinn run`, manage a running daemon, submit intents, or understand the Jinn protocol. Activates on mentions of "jinn", "jinn agent", "jinn network", "jinn run", "desired state", "restoration", or "intent" in the context of operating an agent.
 allowed-tools: Bash, Read, Edit, Write, Glob, Grep
 ---
 
@@ -39,25 +39,55 @@ If not installed:
 npm install -g @jinn-network/client
 ```
 
-This gives you two binaries:
-- `jinn` — the operator CLI (17 verbs)
-- `jinn-mcp` — the MCP server for agent-to-agent operation
+This gives you the `jinn` operator CLI. The built-in MCP server is invoked via `jinn mcp` (see Phase 2).
 
 ### Prerequisites
 
 - **Node.js 22+** — `node --version` to check
 - **Claude Code CLI** — the daemon spawns Claude as a subprocess for restoration work. Must be installed and authenticated separately.
 
+### CLI verb reference
+
+<!-- skill:cli-table:start -->
+| Verb | What it does |
+|------|--------------|
+| `jinn version` | Print client version, protocol phase, and resolved token map |
+| `jinn doctor` | Preflight checks: answers "would jinn run work?" without running it |
+| `jinn init` | Generate the master wallet and write the encrypted keystore |
+| `jinn auth` | Check Claude authentication and persist how the operator runs the daemon |
+| `jinn bootstrap` | Advance the fleet state machine toward a running daemon |
+| `jinn fund-requirements` | List addresses that need funding before the next bootstrap step |
+| `jinn run` | Zero-to-running in one command: init, fund, bootstrap, then start the daemon in the foreground (stops on SIGINT/SIGTERM) |
+| `jinn stop` | Signal a running jinn daemon to shut down gracefully |
+| `jinn status` | Daemon liveness + roll-up (poll this for monitoring; pull detail separately) |
+| `jinn fleet` | Per-service fleet detail (wallets, staking, rewards, attention) |
+| `jinn balance` | Flat per-wallet balance map across master and service wallets |
+| `jinn history` | Recent protocol activity (intents, claims, deliveries, evaluations, rewards) |
+| `jinn rewards` | Earned vs claimed per service, per asset; next checkpoint time |
+| `jinn logs` | Structured event log (one JSON object per line) |
+| `jinn submit-intent` | Post a desired state (restoration job) to the protocol |
+| `jinn claim-rewards` | Pull pending protocol rewards to the fleet multisigs |
+| `jinn withdraw` | Sweep master / agents per withdraw flags |
+| `jinn keys` | Keystore management: backup, change-password |
+| `jinn plugin` | Configure AI tools to use Jinn MCP server and operator skill |
+| `jinn update` | Update the client package and refresh plugins in all configured AI tools |
+| `jinn intents` | List, enable, or disable restoration of specific intent kinds. |
+| `jinn mcp` | Run the operator MCP server over stdio |
+| `jinn migrate-agent-id` | Backfill ERC-8004 agent_id on legacy complete services (jinn-mono-jgp) |
+| `jinn conformance` | Run the envelope + trajectory conformance suite against a signed envelope CID |
+<!-- skill:cli-table:end -->
+
 ## Phase 2: MCP Configuration
 
 If the user wants their agent (Claude Code, Cursor, etc.) to operate jinn programmatically, configure the MCP server:
 
-**For Claude Code** — add to project or user MCP settings:
+**For Claude Code** — run `jinn plugin install` (installs automatically) or add to project/user MCP settings manually:
 ```json
 {
   "mcpServers": {
     "jinn": {
-      "command": "jinn-mcp"
+      "command": "jinn",
+      "args": ["mcp"]
     }
   }
 }
@@ -69,7 +99,7 @@ If the user wants their agent (Claude Code, Cursor, etc.) to operate jinn progra
   "mcpServers": {
     "jinn": {
       "command": "npx",
-      "args": ["-y", "-p", "@jinn-network/client", "jinn-mcp"]
+      "args": ["-y", "-p", "@jinn-network/client", "jinn", "mcp"]
     }
   }
 }
@@ -77,30 +107,47 @@ If the user wants their agent (Claude Code, Cursor, etc.) to operate jinn progra
 
 Once configured, these MCP tools become available:
 
+<!-- skill:mcp-table:start -->
 | Tool | What it does |
-|------|-------------|
-| `jinn_init` | Create master wallet (idempotent) |
-| `jinn_doctor` | Preflight checks |
-| `jinn_status` | Daemon health + fleet roll-up |
-| `jinn_fleet` | Per-service detail |
-| `jinn_balance` | Wallet balances |
-| `jinn_history` | Recent protocol activity |
-| `jinn_rewards` | Earned vs claimed rewards |
-| `jinn_bootstrap` | Advance fleet state machine |
-| `jinn_submit_intent` | Post a desired state on-chain |
-| `jinn_start_daemon` | Start daemon in background |
-| `jinn_stop_daemon` | Stop running daemon |
-
-## Phase 3: Quickstart (Zero to Running)
-
-The fastest path from nothing to a running agent:
+|------|--------------|
+| `jinn_auth` | Read-only: check Claude authentication status and the resolved runtime mode (bare/docker-compose/container). Does NOT attempt login — it only probes and reports. Use this as the first call to verify the agent path is ready. Returns authenticated:true + context + email on success; returns an error envelope if not authenticated. Fast (<1s). |
+| `jinn_doctor` | Preflight checks: node version, claude binary, keystore, deployment config. Read-only. Fast (<5s). |
+| `jinn_fund_requirements` | Read-only: list addresses and amounts that need funding before bootstrap can advance. Note: the underlying command may hydrate wallet state as a side effect of checking funding. Returns an array of funding gaps; empty array means all funded. |
+| `jinn_status` | Daemon liveness and fleet health roll-up. Read-only. Poll this to monitor progress. Fast (<2s). |
+| `jinn_fleet` | Per-service fleet detail: wallets, staking status, activity counts. Read-only. Fast (<5s). |
+| `jinn_balance` | Flat per-wallet balance map across master and service wallets. Read-only. Requires RPC. Fast (<5s). |
+| `jinn_history` | Recent protocol activity: intents, claims, deliveries, evaluations, rewards. Read-only from local DB. Fast (<2s). |
+| `jinn_logs` | Recent activity event log from the local SQLite store. Read-only. Fast (<2s). Returns events with ts, level, component, msg fields. Call with limit=100 for monitoring; increase for deeper history. |
+| `jinn_rewards` | Pending and claimed reward balances per staked service. Read-only. Requires RPC access. Fast (<5s). Returns per-service pending/claimed amounts and next checkpoint time. |
+| `jinn_intents_list` | List all registered intent kinds with their enabled/ready state. Read-only. Fast (<2s). |
+| `jinn_intents_status` | Detailed status for one intent kind: impl, enabled, ready, nextStep. Read-only. Fast (<2s). |
+| `jinn_intents_enable` | MUTATING: Opt in to restoring a specific intent kind. Idempotent. Calls impl.onEnable which may write config. Fast unless impl requires external action. Pass extra_args as space-separated "--key=value" pairs for impl-specific options (e.g. "--hl-master=0x..."). |
+| `jinn_intents_disable` | MUTATING: Opt out of restoring a specific intent kind. Writes config. Idempotent. Fast (<1s). |
+| `jinn_init` | MUTATING. Create the master wallet and write the encrypted keystore. Idempotent: re-runs return the existing master address. Requires confirm: true; default is preview (no filesystem write). |
+| `jinn_run` | MUTATING: Zero-to-running in one call: resolve/generate password, init wallet, bootstrap fleet, start daemon. Idempotent — safe to call repeatedly; resumes from last completed step. Long-running: can take up to 30 minutes if funding is required. Returns a progress stream via --json-progress; poll jinn_status to monitor after this returns. Use no_daemon=true to skip starting the daemon (useful for CI or when the daemon is managed separately). |
+| `jinn_bootstrap` | MUTATING. Advance the fleet state machine. Idempotent. May take several minutes; can post on-chain transactions and request testnet faucet funds. Returns funding_required if a wallet needs ETH. Requires confirm: true; default is preview (no chain or filesystem mutation). |
+| `jinn_submit_intent` | MUTATING. Post a desired state (restoration job) to the protocol. Idempotent by id. Sends an on-chain transaction and pays gas when confirmed. Requires confirm: true; default is preview (uses CLI --dry-run, no on-chain action). |
+| `jinn_claim_rewards` | MUTATING. Pull pending protocol rewards to the fleet multisigs. Idempotent: zero-delta exits 0. Requires confirm: true; default is preview (uses CLI --dry-run, no on-chain action). |
+| `jinn_update` | MUTATING: Update the client package and refresh installed plugins. Step 1: npm update -g @jinn-network/client Step 2: jinn plugin install (refreshes skills in all configured AI tools). May take 1-2 minutes. Use skip_npm=true to only refresh plugins with the current version. |
+| `jinn_start_daemon` | MUTATING. Start the jinn daemon as a detached background process. Spawns a long-lived child process and writes a pidfile. Requires confirm: true; default is preview (does not spawn a process). |
+| `jinn_stop_daemon` | MUTATING. Stop the running jinn daemon. Idempotent: returns success even if already stopped. Requires confirm: true; default is preview (does not signal any process). |
+<!-- skill:mcp-table:end -->
+
+## Phase 3: Zero to Running
+
+The canonical first-run path — run these two commands in order:
 
 ```bash
-jinn quickstart
+# Step 1 — one-time: pick runtime mode and authenticate Claude Code (interactive TTY required).
+jinn auth
+
+# Step 2 — zero-to-running: auto-generates a keystore password, then init → fund → bootstrap → run.
+jinn run
 ```
 
-This single command:
-1. Generates a random keystore password (saved to `~/.jinn-client/keystore-password`)
+`jinn auth` persists the runtime-mode choice so all subsequent commands agree on how to spawn Claude.
+`jinn run` then:
+1. Generates a random keystore password (saved to `~/.jinn-client/keystore-password`, mode 0600)
 2. Creates the master wallet
 3. Funds via Coinbase CDP faucet (automatic on testnet)
 4. Bootstraps the fleet (Safe wallet, service registration, staking, mech deployment)
@@ -108,23 +155,25 @@ This single command:
 
 When it finishes: **open `http://localhost:7331`** for the operator dashboard.
 
-### If the user already has JINN_PASSWORD set:
+### Advanced / CI: explicit password
+
+If you want to manage the password yourself (recommended for production or CI pipelines), set `JINN_PASSWORD` before calling `jinn run`. No file will be written to disk:
 
 ```bash
-JINN_PASSWORD=their-password jinn quickstart
+JINN_PASSWORD=their-password jinn run
 ```
 
-The command respects an existing password and won't generate a new one.
+For CI, prefer reading the password from a file descriptor: `--password-fd N`.
 
-### If quickstart stops at "funding required":
+### If `jinn run` stops at "funding required":
 
 The automatic faucet may have rate-limited (1 claim per 24 hours per address). Options:
-- Wait 24 hours and re-run `jinn quickstart`
+- Wait 24 hours and re-run `jinn run`
 - Fund manually: go to https://portal.cdp.coinbase.com/products/faucet, send testnet ETH to the printed master address, then re-run
 
 ## Phase 3.5: Opting In to Intent Kinds
 
-After quickstart, the daemon participates in `legacy` (health-check) and `prediction.v0` intents by default. Other intent kinds are **off by default** because they require operator-specific credentials (exchange authorizations, API keys, etc.).
+After `jinn run` brings the fleet up, the daemon participates in `legacy` (health-check) and `prediction.v0` intents by default. Other intent kinds are **off by default** because they require operator-specific credentials (exchange authorizations, API keys, etc.).
 
 ### Generic flow (applies to every intent kind with external deps)
 
@@ -224,7 +273,7 @@ To post a desired state for the network to work on:
 jinn submit-intent --id my-intent --description "The service publishes a daily summary" --yes
 ```
 
-Or via MCP: call `jinn_submit_intent` with `id` and `description` parameters.
+Or via MCP: call `jinn_submit_intent` with `id` and `description`. Mutating MCP tools default to a preview envelope; pass `confirm: true` to actually post on-chain. Other mutating tools (`jinn_init`, `jinn_bootstrap`, `jinn_start_daemon`, `jinn_stop_daemon`) follow the same `confirm: true` rule.
 
 ### Checking Rewards
 
@@ -236,7 +285,7 @@ Shows pending vs claimed rewards per service.
 
 ### Changing the Auto-Generated Password
 
-If the user started with `jinn quickstart` and wants to set their own password:
+If the user started with `jinn run` and wants to set their own password:
 
 ```bash
 JINN_NEW_PASSWORD=their-new-password jinn keys change-password
@@ -280,7 +329,7 @@ Bootstrap may need multiple runs if it hit a funding gate partway through. Re-ru
 
 When operating jinn tools, keep this mental model:
 
-- **`jinn quickstart`** is the one-shot setup. After this, the daemon is running.
+- **`jinn run`** is the one-shot setup. After this, the daemon is running.
 - **`jinn status`** is your health check. Poll it to know if things are working.
 - **`jinn submit-intent`** is the main action verb. This is how you create work on the network.
 - **`jinn fleet`** tells you about your staked services and their state.

package/templates/plug-in/hook/README.md.tmpl

@@ -0,0 +1,24 @@
+# {{packageName}}
+
+Path 1 Jinn plug-in. Runs a custom hook at the `{{event}}` event of
+each claude-code-learner session.
+
+## Install (operator)
+
+```bash
+yarn add {{packageName}}
+jinn plug-ins add {{packageName}} --entry $(node -p "require.resolve('{{packageName}}/package.json').replace(/\/package\.json$/, '')")
+```
+
+## Develop
+
+```bash
+yarn install
+yarn test
+```
+
+Edit `hooks/{{event}}.sh` to add your hook behaviour.
+
+## Spec
+
+`spec/2026-04-30-plug-in-surface.md` §4. Slot type: `hook`.

package/templates/plug-in/hook/gitignore.tmpl

@@ -0,0 +1,3 @@
+node_modules/
+*.log
+.DS_Store

package/templates/plug-in/hook/hooks/event.sh.tmpl

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+# {{packageName}} — {{event}} hook.
+#
+# Inputs (from environment, set by the coordinator skill):
+#   JINN_INTENT_ID, JINN_INTENT_KIND
+#   JINN_PHASE          — set for pre-phase / post-phase events
+#   JINN_WORKING_DIR    — session ephemeral dir
+#   JINN_IMPL_STATE_DIR — operator-private durable dir
+#
+# Failures here log a warning to JINN_WORKING_DIR/.errors/hooks.log but
+# do not abort the session.
+
+set -euo pipefail
+
+echo "{{packageName}} {{event}}: intent=${JINN_INTENT_ID:-unknown} phase=${JINN_PHASE:-n/a}"

package/templates/plug-in/hook/jinn-plugin.json.tmpl

@@ -0,0 +1,16 @@
+{
+  "schemaVersion": "1.0.0",
+  "name": "{{packageName}}",
+  "version": "0.1.0",
+  "description": "Hook plug-in for the {{event}} event.",
+  "compatibility": {
+    "claudeCodeLearner": ">=0.1.0"
+  },
+  "slots": [
+    {
+      "type": "hook",
+      "event": "{{event}}",
+      "entry": "hooks/{{event}}.sh"
+    }
+  ]
+}

package/templates/plug-in/hook/package.json.tmpl

@@ -0,0 +1,14 @@
+{
+  "name": "{{packageName}}",
+  "version": "0.1.0",
+  "description": "Jinn Path 1 plug-in: hook for the {{event}} event.",
+  "type": "module",
+  "files": ["hooks/", "jinn-plugin.json", "README.md"],
+  "scripts": {
+    "test": "vitest run"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.0",
+    "vitest": "^2.1.9"
+  }
+}

package/templates/plug-in/hook/test/manifest.test.ts.tmpl

@@ -0,0 +1,21 @@
+import { describe, it, expect } from 'vitest';
+import { readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+describe('{{packageName}} hook plug-in', () => {
+  it('declares a hook slot for {{event}}', () => {
+    const manifest = JSON.parse(
+      readFileSync(join(__dirname, '..', 'jinn-plugin.json'), 'utf8'),
+    );
+    expect(manifest.name).toBe('{{packageName}}');
+    expect(manifest.slots[0].type).toBe('hook');
+    expect(manifest.slots[0].event).toBe('{{event}}');
+  });
+
+  it('hook entry exists', () => {
+    const manifest = JSON.parse(
+      readFileSync(join(__dirname, '..', 'jinn-plugin.json'), 'utf8'),
+    );
+    expect(existsSync(join(__dirname, '..', manifest.slots[0].entry))).toBe(true);
+  });
+});

package/templates/plug-in/mcp-tool/README.md.tmpl

@@ -0,0 +1,26 @@
+# {{packageName}}
+
+Path 1 Jinn plug-in. Surfaces an MCP server to phase agents.
+
+## Install (operator)
+
+```bash
+yarn add {{packageName}}
+jinn plug-ins add {{packageName}} --entry $(node -p "require.resolve('{{packageName}}/package.json').replace(/\/package\.json$/, '')")
+```
+
+The harness spawns this server at session-start; tools surface under
+namespace `{{packageName}}` (or `slot.namespace` if you set one).
+
+## Develop
+
+```bash
+yarn install
+yarn test
+```
+
+Implement the MCP server in `src/server.ts`.
+
+## Spec
+
+`spec/2026-04-30-plug-in-surface.md` §4. Slot type: `mcp-tool`.

package/templates/plug-in/mcp-tool/gitignore.tmpl

@@ -0,0 +1,4 @@
+node_modules/
+dist/
+*.log
+.DS_Store

package/templates/plug-in/mcp-tool/jinn-plugin.json.tmpl

@@ -0,0 +1,16 @@
+{
+  "schemaVersion": "1.0.0",
+  "name": "{{packageName}}",
+  "version": "0.1.0",
+  "description": "MCP tool server for {{packageName}}.",
+  "compatibility": {
+    "claudeCodeLearner": ">=0.1.0"
+  },
+  "slots": [
+    {
+      "type": "mcp-tool",
+      "command": "node",
+      "args": ["src/server.js"]
+    }
+  ]
+}

package/templates/plug-in/mcp-tool/package.json.tmpl

@@ -0,0 +1,19 @@
+{
+  "name": "{{packageName}}",
+  "version": "0.1.0",
+  "description": "Jinn Path 1 plug-in: MCP tool server.",
+  "type": "module",
+  "main": "./src/server.js",
+  "files": ["src/", "jinn-plugin.json", "README.md"],
+  "scripts": {
+    "test": "vitest run",
+    "start": "node src/server.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.0",
+    "vitest": "^2.1.9"
+  }
+}

package/templates/plug-in/mcp-tool/src/server.ts.tmpl

@@ -0,0 +1,17 @@
+/**
+ * Minimal MCP server stub for {{packageName}}. Replace with real tool
+ * implementations. The server is spawned by the harness when this
+ * plug-in is installed; tools surface to phase agents under the
+ * plug-in's name (or `slot.namespace` if declared).
+ */
+
+// Replace with actual @modelcontextprotocol/sdk imports when implementing.
+console.error('{{packageName}}: MCP server starting (stub)');
+
+process.stdin.on('data', (chunk: Buffer) => {
+  // Echo loop — replace with proper JSON-RPC handling.
+  process.stdout.write(chunk);
+});
+
+process.on('SIGTERM', () => process.exit(0));
+process.on('SIGINT', () => process.exit(0));

package/templates/plug-in/mcp-tool/test/server.test.ts.tmpl

@@ -0,0 +1,18 @@
+import { describe, it, expect } from 'vitest';
+import { readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+describe('{{packageName}} MCP-tool plug-in', () => {
+  it('declares an mcp-tool slot', () => {
+    const manifest = JSON.parse(
+      readFileSync(join(__dirname, '..', 'jinn-plugin.json'), 'utf8'),
+    );
+    expect(manifest.name).toBe('{{packageName}}');
+    expect(manifest.slots[0].type).toBe('mcp-tool');
+    expect(manifest.slots[0].command).toBe('node');
+  });
+
+  it('server entry exists', () => {
+    expect(existsSync(join(__dirname, '..', 'src', 'server.ts'))).toBe(true);
+  });
+});

package/templates/plug-in/memory-backend/README.md.tmpl

@@ -0,0 +1,33 @@
+# {{packageName}}
+
+Path 1 Jinn plug-in. Surfaces a memory backend (vector store) to the
+memory-consolidation phase via MCP under the namespace
+`memory-{{packageName}}`.
+
+## Install (operator)
+
+```bash
+yarn add {{packageName}}
+jinn plug-ins add {{packageName}} --entry $(node -p "require.resolve('{{packageName}}/package.json').replace(/\/package\.json$/, '')")
+```
+
+Then point a kind at this backend by editing
+`implStateDir/policy.json`:
+
+```json
+{ "memoryBackend": { "perKind": { "prediction.v0": "{{packageName}}" } } }
+```
+
+## Develop
+
+```bash
+yarn install
+yarn test
+```
+
+Implement the three MCP tools (`embed`, `query`, `prune`) in
+`src/server.ts`.
+
+## Spec
+
+`spec/2026-04-30-plug-in-surface.md` §4. Slot type: `memory-backend`.

package/templates/plug-in/memory-backend/gitignore.tmpl

@@ -0,0 +1,4 @@
+node_modules/
+dist/
+*.log
+.DS_Store

package/templates/plug-in/memory-backend/jinn-plugin.json.tmpl

@@ -0,0 +1,16 @@
+{
+  "schemaVersion": "1.0.0",
+  "name": "{{packageName}}",
+  "version": "0.1.0",
+  "description": "Memory backend: vector embed/query/prune over MCP.",
+  "compatibility": {
+    "claudeCodeLearner": ">=0.1.0"
+  },
+  "slots": [
+    {
+      "type": "memory-backend",
+      "command": "node",
+      "args": ["src/server.js"]
+    }
+  ]
+}

package/templates/plug-in/memory-backend/package.json.tmpl

@@ -0,0 +1,19 @@
+{
+  "name": "{{packageName}}",
+  "version": "0.1.0",
+  "description": "Jinn Path 1 plug-in: memory backend (MCP server with embed/query/prune).",
+  "type": "module",
+  "main": "./src/server.js",
+  "files": ["src/", "jinn-plugin.json", "README.md"],
+  "scripts": {
+    "test": "vitest run",
+    "start": "node src/server.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.0",
+    "vitest": "^2.1.9"
+  }
+}

package/templates/plug-in/memory-backend/src/server.ts.tmpl

@@ -0,0 +1,23 @@
+/**
+ * Minimal memory-backend MCP server stub for {{packageName}}. The
+ * memory-consolidation skill expects three tools under namespace
+ * `memory-{{packageName}}`:
+ *
+ *   - embed(text: string): Float32Array
+ *   - query(vector: Float32Array, k: number): Array<{ id, score, text }>
+ *   - prune(maxAgeDays: number): { pruned: number }
+ *
+ * Replace the stubs below with your real backend (LanceDB, pgvector,
+ * Pinecone, etc.). Keep the tool names and shapes — the skill routes
+ * by exact name.
+ */
+
+console.error('{{packageName}}: memory-backend MCP server starting (stub)');
+
+// Replace with actual @modelcontextprotocol/sdk wiring.
+process.stdin.on('data', (chunk: Buffer) => {
+  process.stdout.write(chunk);
+});
+
+process.on('SIGTERM', () => process.exit(0));
+process.on('SIGINT', () => process.exit(0));

package/templates/plug-in/memory-backend/test/server.test.ts.tmpl

@@ -0,0 +1,17 @@
+import { describe, it, expect } from 'vitest';
+import { readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+describe('{{packageName}} memory-backend plug-in', () => {
+  it('declares a memory-backend slot', () => {
+    const manifest = JSON.parse(
+      readFileSync(join(__dirname, '..', 'jinn-plugin.json'), 'utf8'),
+    );
+    expect(manifest.name).toBe('{{packageName}}');
+    expect(manifest.slots[0].type).toBe('memory-backend');
+  });
+
+  it('server entry exists', () => {
+    expect(existsSync(join(__dirname, '..', 'src', 'server.ts'))).toBe(true);
+  });
+});

package/templates/plug-in/phase-agent-override/README.md.tmpl

@@ -0,0 +1,30 @@
+# {{packageName}}
+
+Path 1 Jinn plug-in. Overrides the bundled claude-code-learner
+`{{agent}}` agent during the `{{phase}}` phase.
+
+## Install (operator)
+
+```bash
+yarn add {{packageName}}
+jinn plug-ins add {{packageName}} --entry $(node -p "require.resolve('{{packageName}}/package.json').replace(/\/package\.json$/, '')")
+```
+
+The daemon picks the override up at the next session-start: if the
+intent kind is in scope, the `{{phase}}` skill spawns this agent
+instead of the bundled `{{agent}}`.
+
+## Develop
+
+```bash
+yarn install
+yarn test
+```
+
+Edit `agents/{{phaseAgentName}}.md` — the override receives the same inputs as the
+bundled agent.
+
+## Spec
+
+`spec/2026-04-30-plug-in-surface.md` §4. Slot type:
+`phase-agent-override`.

package/templates/plug-in/phase-agent-override/agents/agent.md.tmpl

@@ -0,0 +1,26 @@
+---
+name: {{phaseAgentName}}
+description: Override for the bundled claude-code-learner {{agent}} agent in the {{phase}} phase.
+---
+
+# {{phaseAgentName}}
+
+This is a stub override agent. Replace the body below with your custom
+{{phase}}/{{agent}} logic. The override receives the same inputs as the
+bundled agent — see the bundled
+`client/plugins/claude-code-learner/agents/{{agent}}.md` for the contract.
+
+## Inputs
+
+(Document what your override expects here.)
+
+## Outputs
+
+(Document what your override produces here.)
+
+## Notes
+
+- Inherits trust from the harness — no per-plug-in capability allow-list.
+- Phase skills route to this override only when `intent.spec.kind` matches
+  the `scope.matchKinds` declared in `jinn-plugin.json` (or unconditionally
+  when `scope` is absent).

package/templates/plug-in/phase-agent-override/gitignore.tmpl

@@ -0,0 +1,3 @@
+node_modules/
+*.log
+.DS_Store

package/templates/plug-in/phase-agent-override/jinn-plugin.json.tmpl

@@ -0,0 +1,17 @@
+{
+  "schemaVersion": "1.0.0",
+  "name": "{{packageName}}",
+  "version": "0.1.0",
+  "description": "Phase-agent override for {{phase}}/{{agent}}.",
+  "compatibility": {
+    "claudeCodeLearner": ">=0.1.0"
+  },
+  "slots": [
+    {
+      "type": "phase-agent-override",
+      "phase": "{{phase}}",
+      "agent": "{{agent}}",
+      "entry": "agents/{{phaseAgentName}}.md"
+    }
+  ]
+}

package/templates/plug-in/phase-agent-override/package.json.tmpl

@@ -0,0 +1,14 @@
+{
+  "name": "{{packageName}}",
+  "version": "0.1.0",
+  "description": "Jinn Path 1 plug-in: phase-agent override for {{phase}}/{{agent}}.",
+  "type": "module",
+  "files": ["agents/", "jinn-plugin.json", "README.md"],
+  "scripts": {
+    "test": "vitest run"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.0",
+    "vitest": "^2.1.9"
+  }
+}