total-recall-brain 3.40.6 → 3.41.0

package/scaffold/.agent/skills/plugin/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: plugin
+description: Author, review or fix a Total Recall plugin (tr-plugin-*). A recipe of exact specifications an agent executes, so the plugin declares the surfaces its function needs, serves agents through its CLI, scaffolds its capability into other applications, and renders a bespoke card face.
+repo_scoped: false
+metadata:
+  version: "1.0.0"
+  source: total-recall-brain
+---
+
+# The plugin creator
+
+A recipe for agents: prompts with exact specifications, executed in order. Each prompt says what to produce and what "correct" means, and each has a runnable check.
+
+A plugin adds **one capability** to Total Recall. Core holds portable memory and generic loading; everything else is a plugin.
+
+**A plugin is not one shape.** It declares the surfaces its capability needs, and a capability can need almost any combination — memory, context, a CLI, skills, scheduled work, runtime behaviour, a face, deployment, distribution, composition. Some plugins are only a memory category. Some are only a generator. Some are a CLI. Some are several at once. What it is, is decided by what it does.
+
+```
+references/   every field, every rule, and the failure catalogue
+prompts/      the recipe, one prompt per step
+scripts/      the checks, runnable at any point
+subagents/    delegatable reviews and extractions
+evals/        proof that the recipe produces correct plugins
+```
+
+---
+
+## The invariants
+
+True of every plugin, whatever it turns out to be. Check every one before calling it done.
+
+1. **Everything is declared.** If the plugin can do it, the manifest says so. An undeclared operation does not exist to the host or to an agent.
+2. **Every executable operation declares an effect** — `read`, `write`, `destructive`, `send`. The host uses it to decide what may run read-only; an agent uses it to know what needs confirmation.
+3. **Machine-facing output is structured.** A command emits JSON under `--json` and exits non-zero on failure, so an agent acts on a result instead of scraping prose.
+4. **Credentials are declared, never held.** Resolved only through `total-recall auth secret`. Never a second store, never `argv`, never an ambient environment variable, never a log.
+5. **Real data only.** Every value traces to something that actually returned it. No seeded readings, no placeholders, no example defaults, no reassuring badges. A failure is reported as a failure, with the time of the last attempt.
+6. **No templates.** Not for the face, and not for the plugin's shape. A face that could be dropped onto a different plugin is a failed face.
+7. **Every plugin has a card face**, authored by hand from its own function.
+8. **Fail closed.** A missing credential, a failed provider or an unreachable peer is an explicit error, never a success state.
+9. **Copy.** No filler words, and no sentence ends with a preposition.
+
+---
+
+## The recipe
+
+| # | Prompt | Produce | Check |
+| --- | --- | --- | --- |
+| 1 | [Establish the function](prompts/01-function.md) | the users, the tasks, the dependencies | you can name them |
+| 2 | [Choose the surfaces](prompts/02-surfaces.md) | the manifest's surface set | each declared surface is used |
+| 3 | [Scaffold, then stop generating](prompts/03-scaffold.md) | repository skeleton | it exists, tests run |
+| 4 | [Write the CLI as an agent interface](prompts/04-cli.md) | operations, args, effects, JSON | `record.mjs` passes |
+| 5 | [Declare credentials and settings](prompts/05-credentials.md) | `secrets[]`, `configuration` | one credential path, auth |
+| 6 | [Design the card face by hand](prompts/06-card.md) | `ui/DESIGN.md`, `ui/card.js` | `record.mjs --card` passes |
+| 7 | [Extract the scaffold](prompts/07-scaffold.md) | the capability for another app | runs with Total Recall absent |
+| 8 | [Verify and report](prompts/08-verify.md) | a truthful report | `record.mjs` passes every check |
+
+Read [surfaces](references/surfaces.md) before Prompt 2, and [card](references/card.md) before Prompt 6.
+
+---
+
+## Scripts
+
+Run from the plugin repository.
+
+```
+node <skill>/scripts/record.mjs .              # every check
+node <skill>/scripts/record.mjs . --manifest   # manifest only
+node <skill>/scripts/record.mjs . --card       # face only
+node <skill>/scripts/record.mjs . --secrets    # credential safety only
+node <skill>/scripts/record.mjs . --scaffold   # standalone scaffold only
+node <skill>/scripts/record.mjs . --json       # machine-readable result
+```
+
+`record.mjs` exits non-zero on any failure and prints the real reason. It is the same battery Prompt 8 asks you to run, so there is nothing to remember.
+
+---
+
+## Subagents
+
+Delegate when the work is separable. Each is a prompt file, disposable and repeatable.
+
+| Subagent | Use when | Returns |
+| --- | --- | --- |
+| [plugin-reviewer](subagents/plugin-reviewer.md) | a plugin is claimed finished | violations against the invariants, with evidence, or "clean" |
+| [card-designer](subagents/card-designer.md) | the function is known and the face is not written | `ui/DESIGN.md` reasoning and a first `ui/card.js`, or the questions it cannot answer |
+| [scaffold-extractor](subagents/scaffold-extractor.md) | a plugin holds a capability another app could use | capability module design, or "not separable, because…" |
+
+The reviewer is adversarial by construction: it looks for fabricated values, host leaks, and a face that would suit any other plugin.
+
+---
+
+## Evals
+
+`evals/` proves the recipe works, using plugins whose correct outcome is already known — including the real defects found in this ecosystem.
+
+```
+node evals/run.mjs          # run every case
+node evals/run.mjs --case <name>
+```
+
+See [evals](evals/README.md).
+
+---
+
+## References
+
+- [Surfaces](references/surfaces.md) — every surface and its exact manifest fields.
+- [Card](references/card.md) — designing a bespoke face, and what it must never do.
+- [Scaffold](references/scaffold.md) — the capability for another application, and distribution.
+- [Anti-patterns](references/anti-patterns.md) — the failure catalogue, every entry observed in a real plugin.

package/scaffold/.agent/skills/plugin/evals/README.md

@@ -0,0 +1,53 @@
+# Evals
+
+Proof that the recipe and its checks work.
+
+Each case is a synthetic plugin whose correct outcome is already known. Five are **real defects observed in this ecosystem**; one is a plugin that follows the recipe and must be **accepted**. A checker that only ever rejects, or only ever accepts, proves nothing.
+
+```
+node evals/run.mjs                 # every case
+node evals/run.mjs --case <name>
+node evals/run.mjs --json
+node evals/run.mjs --keep          # keep the temp fixture for inspection
+```
+
+Exit code is non-zero unless every case behaves as expected.
+
+## How a case is judged
+
+A case declares the failures it expects. It passes when `scripts/record.mjs` reports **exactly** those and nothing else:
+
+- A defect case passes only if the checker **catches** it. A checker that looks at nothing fails here.
+- The correct-plugin case passes only if there are **no** failures. An over-eager checker fails here.
+- A case whose expectation is empty treats any failure as unexpected.
+
+## The cases
+
+| Case | Defect it encodes | Expected |
+| --- | --- | --- |
+| [`fabricated-seed`](cases/01-fabricated-seed.mjs) | a card seeding a telemetry reading — a literal hostname, uptime, load average and `usedPercent: 99.1` before any command ran, commented "Retain fallback telemetry" | `no seeded values` |
+| [`reassuring-default`](cases/02-reassuring-default.mjs) | a card reading three fields its command never returns and defaulting to "Up to date", so a repository with three unpushed commits rendered clean | `no reassuring default` |
+| [`declared-template`](cases/03-declared-template.mjs) | a manifest declaring `card_layout` with a template name and region list — the vocabulary that made 24 of 34 plugins identical | `no template` |
+| [`card-collects-credential`](cases/04-card-collects-credential.mjs) | a card collecting an API key in a password field and dispatching the raw value — generated by the old scaffolder | `never collects a credential`, `never transmits a credential` |
+| [`host-leak-in-scaffold`](cases/05-host-leak-in-scaffold.mjs) | a capability calling the `total-recall` binary for credentials and shipping `https://example.com/checkout/success` | `no Total Recall dependency`, `no placeholder values` |
+| [`correct-plugin`](cases/06-correct-plugin.mjs) | a plugin that follows the recipe: one bespoke face, real data only, credentials resolved through auth in the CLI, and a host-free capability | no failures |
+
+## Adding a case
+
+A case is a module exporting `{ name, why, files, expect }`:
+
+```js
+export default {
+  name: 'kebab-case-name',
+  why: 'the failure mode this encodes, and what it costs',
+  files: { 'plugin.json': '…', 'cli.mjs': '…', 'ui/card.js': '…' },
+  expect: { fail: ['the check name record.mjs must report'] },
+}
+```
+
+Rules:
+
+- `why` states the **cost** of the defect, not just its shape.
+- `expect.fail` lists check names as `record.mjs` prints them. Empty means "must be accepted".
+- Prefer a case grounded in something that actually happened. An invented defect tests the checker against your imagination; a real one tests it against the ecosystem.
+- If a new case cannot be made to fail, the check behind it is decorative — fix the check, not the case.

package/scaffold/.agent/skills/plugin/evals/cases/01-fabricated-seed.mjs

@@ -0,0 +1,42 @@
+/**
+ * A card that seeds a telemetry reading in its constructor.
+ *
+ * Observed: system-monitor held a literal hostname, uptime, load average and
+ * `usedPercent: 99.1` before any command ran, with the comment
+ * "// Retain fallback telemetry".
+ */
+const CARD = `
+export class SeededCard extends HTMLElement {
+  constructor() {
+    super();
+    this.sample = {
+      hostname: 'Gregorys-Mac-mini.local',
+      platform: 'darwin',
+      uptimeSeconds: 566924,
+      loadAvg: [3.34, 3.76, 5.00],
+      memory: { total: 17179869184, free: 159334400, usedPercent: 99.1 }
+    };
+  }
+  connectedCallback() { this.attachShadow({ mode: 'open' }) }
+}
+customElements.define('tr-seeded-card', SeededCard)
+`;
+
+export default {
+  name: 'fabricated-seed',
+  why: 'a fabricated reading on the face is the most consequential kind of lie',
+  files: {
+    'plugin.json': JSON.stringify({
+      id: 'seeded', name: 'Seeded', version: '1.0.0', description: 'A plugin that fabricates a reading.',
+      cli: { command: 'seeded', handler: './cli.mjs', subcommands: [{ name: 'sample', effect: 'read' }] },
+      status: { command: 'sample', refresh_seconds: 30 },
+      branding: { color: '#059669' },
+      ui: { elements: [{ id: 'card', kind: 'card', tag: 'tr-seeded-card', module: 'ui/card.js' }] },
+    }, null, 2),
+    'cli.mjs': 'export default async function run() {}\n',
+    'ui/card.js': CARD,
+  },
+  expect: {
+    fail: ['no seeded values'],
+  },
+};

package/scaffold/.agent/skills/plugin/evals/cases/02-reassuring-default.mjs

@@ -0,0 +1,39 @@
+/**
+ * A card that reads fields its command does not return, and defaults to a
+ * reassurance.
+ *
+ * Observed: a git card read `data.worktree.unstaged`, `data.synced` and
+ * `data.upstream.status`, none of which the command returns, and defaulted to
+ * "Up to date" — so a repository with three unpushed commits rendered clean.
+ */
+const CARD = `
+export class ReassuringCard extends HTMLElement {
+  async read() {
+    const data = await this.host.run('audit', ['--json'])
+    const isClean = data.worktree?.clean ?? (data.clean ?? false)
+    const upstream = data.upstream?.status || (data.synced ? 'Synced' : 'Up to date')
+    this.shadowRoot.querySelector('.state').textContent = isClean ? 'Clean' : upstream
+  }
+  connectedCallback() { this.attachShadow({ mode: 'open' }); this.read() }
+}
+customElements.define('tr-reassuring-card', ReassuringCard)
+`;
+
+export default {
+  name: 'reassuring-default',
+  why: 'an unverified reassurance is worse than no value, because it is believed',
+  files: {
+    'plugin.json': JSON.stringify({
+      id: 'reassuring', name: 'Reassuring', version: '1.0.0', description: 'A plugin that reassures without checking.',
+      cli: { command: 'reassuring', handler: './cli.mjs', subcommands: [{ name: 'audit', effect: 'read' }] },
+      status: { command: 'audit', refresh_seconds: 30 },
+      branding: { color: '#b45309' },
+      ui: { elements: [{ id: 'card', kind: 'card', tag: 'tr-reassuring-card', module: 'ui/card.js' }] },
+    }, null, 2),
+    'cli.mjs': 'export default async function run() {}\n',
+    'ui/card.js': CARD,
+  },
+  expect: {
+    fail: ['no reassuring default'],
+  },
+};

package/scaffold/.agent/skills/plugin/evals/cases/03-declared-template.mjs

@@ -0,0 +1,32 @@
+/**
+ * A manifest that declares a shared layout template.
+ *
+ * Observed: core enforced a closed allowlist of seven layouts, and 24 of 34
+ * plugins shared a byte-identical card signature.
+ */
+const CARD = `
+export class TemplatedCard extends HTMLElement {
+  connectedCallback() { this.attachShadow({ mode: 'open' }) }
+}
+customElements.define('tr-templated-card', TemplatedCard)
+`;
+
+export default {
+  name: 'declared-template',
+  why: 'a shared layout vocabulary is the mechanism that made unrelated plugins look alike',
+  files: {
+    'plugin.json': JSON.stringify({
+      id: 'templated', name: 'Templated', version: '1.0.0', description: 'A plugin that declares a layout template.',
+      cli: { command: 'templated', handler: './cli.mjs', subcommands: [{ name: 'status', effect: 'read' }] },
+      status: { command: 'status', refresh_seconds: 30 },
+      branding: { color: '#475569' },
+      card_layout: { template: 'ledger', regions: [{ widget: 'status' }, { widget: 'table', source: { command: 'status' } }] },
+      ui: { elements: [{ id: 'card', kind: 'card', tag: 'tr-templated-card', module: 'ui/card.js' }] },
+    }, null, 2),
+    'cli.mjs': 'export default async function run() {}\n',
+    'ui/card.js': CARD,
+  },
+  expect: {
+    fail: ['no template', 'card_layout'],
+  },
+};

package/scaffold/.agent/skills/plugin/evals/cases/04-card-collects-credential.mjs

@@ -0,0 +1,46 @@
+/**
+ * A card that collects an API key in a password field.
+ *
+ * Observed: the scaffolder generated exactly this, dispatching the raw value
+ * as a `save-token` event — a second credential store and a leak surface.
+ */
+const CARD = `
+export class CollectingCard extends HTMLElement {
+  connectedCallback() {
+    const root = this.attachShadow({ mode: 'open' })
+    const input = document.createElement('input')
+    input.type = 'password'
+    input.setAttribute('aria-label', 'API key')
+    const button = document.createElement('button')
+    button.textContent = 'Save'
+    button.addEventListener('click', () => {
+      this.dispatchEvent(new CustomEvent('save-token', { detail: { token: input.value }, bubbles: true }))
+    })
+    root.append(input, button)
+  }
+}
+customElements.define('tr-collecting-card', CollectingCard)
+`;
+
+export default {
+  name: 'card-collects-credential',
+  why: 'one credential path exists in the system, and it is the auth plugin',
+  files: {
+    'plugin.json': JSON.stringify({
+      id: 'collecting', name: 'Collecting', version: '1.0.0', description: 'A plugin whose card collects a key.',
+      cli: { command: 'collecting', handler: './cli.mjs', subcommands: [
+        { name: 'status', effect: 'read' },
+        { name: 'token', effect: 'write', args: [{ name: 'key', label: 'Key', type: 'string', secret: true }] },
+      ] },
+      secrets: [{ key: 'COLLECTING_API_KEY', description: 'Service key', required: true }],
+      status: { command: 'status', refresh_seconds: 30 },
+      branding: { color: '#6366f1' },
+      ui: { elements: [{ id: 'card', kind: 'card', tag: 'tr-collecting-card', module: 'ui/card.js' }] },
+    }, null, 2),
+    'cli.mjs': "import { spawnSync } from 'node:child_process'\nspawnSync('total-recall', ['auth', 'secret', 'get', 'COLLECTING_API_KEY'])\nexport default async function run() {}\n",
+    'ui/card.js': CARD,
+  },
+  expect: {
+    fail: ['never collects a credential', 'never transmits a credential'],
+  },
+};

package/scaffold/.agent/skills/plugin/evals/cases/05-host-leak-in-scaffold.mjs

@@ -0,0 +1,55 @@
+/**
+ * A capability that depends on Total Recall and ships a placeholder.
+ *
+ * Observed: a vendored brick called the `total-recall` binary for every
+ * credential read — failing with `Auth credential read failed` once it was
+ * absent — and carried `https://example.com/checkout/success`.
+ */
+const CARD = `
+export class LeakyCard extends HTMLElement {
+  connectedCallback() { this.attachShadow({ mode: 'open' }) }
+}
+customElements.define('tr-leaky-card', LeakyCard)
+`;
+
+const CAPABILITY = `
+import { spawnSync } from 'node:child_process'
+
+function secret() {
+  const binary = process.env.TOTAL_RECALL_BIN || 'total-recall'
+  const out = spawnSync(binary, ['auth', 'secret', 'get', 'LEAKY_API_KEY', '--json'])
+  return JSON.parse(out.stdout).value
+}
+
+export async function createCheckout({ amount }) {
+  const successUrl = 'https://example.com/checkout/success'
+  const res = await fetch('https://api.example.com/v1/sessions', {
+    method: 'POST',
+    headers: { Authorization: 'Bearer ' + secret() },
+    body: JSON.stringify({ amount, success_url: successUrl }),
+  })
+  return res.json()
+}
+`;
+
+export default {
+  name: 'host-leak-in-scaffold',
+  why: 'a scaffold is laid into an application that has no Total Recall, and no placeholders',
+  files: {
+    'plugin.json': JSON.stringify({
+      id: 'leaky', name: 'Leaky', version: '1.0.0', description: 'A plugin whose capability depends on the host.',
+      cli: { command: 'leaky', handler: './cli.mjs', subcommands: [{ name: 'status', effect: 'read' }] },
+      capability: { entry: 'capability/index.mjs', exports: ['createCheckout'] },
+      secrets: [{ key: 'LEAKY_API_KEY', description: 'Service key', required: true }],
+      status: { command: 'status', refresh_seconds: 30 },
+      branding: { color: '#b45309' },
+      ui: { elements: [{ id: 'card', kind: 'card', tag: 'tr-leaky-card', module: 'ui/card.js' }] },
+    }, null, 2),
+    'cli.mjs': 'export default async function run() {}\n',
+    'ui/card.js': CARD,
+    'capability/index.mjs': CAPABILITY,
+  },
+  expect: {
+    fail: ['no Total Recall dependency', 'no placeholder values'],
+  },
+};

package/scaffold/.agent/skills/plugin/evals/cases/06-correct-plugin.mjs

@@ -0,0 +1,92 @@
+/**
+ * A plugin that satisfies the recipe: one bespoke face, real data only,
+ * credentials through auth, values the caller supplies.
+ *
+ * This is the positive case. It must produce no failures.
+ */
+const CARD = `
+const DASH = '\\u2014'
+
+export class ExampleCard extends HTMLElement {
+  constructor() {
+    super()
+    this.state = 'idle'
+    this.reading = null
+    this.lastError = null
+    this.lastAttempt = null
+    this.screen = 'status'
+  }
+  get screens() { return [{ id: 'status', label: 'Status' }] }
+  connectedCallback() {
+    if (!this.shadowRoot) this.attachShadow({ mode: 'open' })
+    this.render()
+    void this.read()
+  }
+  async read() {
+    this.lastAttempt = new Date()
+    try {
+      const payload = await this.host.run('status', ['--json'])
+      this.reading = payload && typeof payload === 'object' ? payload : null
+      if (!this.reading) throw new Error('The status command returned nothing readable')
+      this.lastError = null
+      this.state = 'ready'
+    } catch (err) {
+      this.reading = null
+      this.lastError = err && err.message ? err.message : String(err)
+      this.state = 'error'
+    } finally {
+      this.paint()
+    }
+  }
+  paint() {
+    const value = this.shadowRoot.querySelector('#value')
+    const note = this.shadowRoot.querySelector('#note')
+    if (value) value.textContent = this.reading ? String(this.reading.usedPercent ?? DASH) : DASH
+    if (note) note.textContent = this.lastError ? this.lastError + ' at ' + this.lastAttempt.toLocaleTimeString() : ''
+  }
+  render() {
+    this.shadowRoot.innerHTML = '<style>:host{display:block;color:var(--text-primary);border:1px solid var(--border);padding:14px}' +
+      'button{min-height:44px}</style>' +
+      '<h2>Example</h2><span id="value">' + DASH + '</span><p id="note"></p><button type="button">Read</button>'
+  }
+}
+customElements.define('tr-example-card', ExampleCard)
+`;
+
+const CAPABILITY = `
+export async function readStatus({ endpoint, apiKey, fetchImpl = fetch }) {
+  if (!endpoint) throw new Error('endpoint is required')
+  const res = await fetchImpl(endpoint + '/status', { headers: apiKey ? { Authorization: 'Bearer ' + apiKey } : {} })
+  if (!res.ok) throw new Error('status request failed: ' + res.status)
+  return res.json()
+}
+`;
+
+export default {
+  name: 'correct-plugin',
+  why: 'the recipe must accept a plugin that follows it, or it is not a recipe',
+  files: {
+    'plugin.json': JSON.stringify({
+      id: 'example', name: 'Example', version: '1.0.0', description: 'A plugin that follows the recipe exactly.',
+      cli: { command: 'example', handler: './cli.mjs', subcommands: [
+        { name: 'status', description: 'Read current status', effect: 'read', output: 'json' },
+        { name: 'set-key', description: 'Store the service key', effect: 'write',
+          args: [{ name: 'apiKey', label: 'API key', type: 'string', secret: true }] },
+      ] },
+      capability: { entry: 'capability/index.mjs', exports: ['readStatus'] },
+      secrets: [{ key: 'EXAMPLE_API_KEY', description: 'Reads the service', required: true }],
+      status: { command: 'status', refresh_seconds: 30 },
+      distribution: { tier: 'official', license: 'open' },
+      branding: { name: 'Example', color: '#047857', accent: '#10b981', font: 'inter', density: 'comfortable', radius: 'sm', header: 'plain' },
+      ui: { design_tokens: 'ui/DESIGN.md', elements: [{ id: 'card', kind: 'card', tag: 'tr-example-card', module: 'ui/card.js' }] },
+    }, null, 2),
+    'cli.mjs': "import { readAuthSecret } from './auth-client.mjs'\nimport { readStatus } from './capability/index.mjs'\nexport default async function run() {\n  return readStatus({ endpoint: process.env.EXAMPLE_ENDPOINT, apiKey: readAuthSecret('EXAMPLE_API_KEY') })\n}\n",
+    'auth-client.mjs': "/** Auth-only transport: the plugin holds no credential of its own. */\nimport { spawnSync } from 'node:child_process'\nexport function readAuthSecret(key) {\n  const out = spawnSync('total-recall', ['auth', 'secret', 'get', key, '--json'], { encoding: 'utf8' })\n  const parsed = JSON.parse(out.stdout)\n  return parsed.found ? parsed.value : ''\n}\n",
+    'ui/DESIGN.md': '# DESIGN.md — Example\n\n```yaml\ntokens:\n  brand-name: "Example"\n  color-primary: "#047857"\n```\n\nOne screen: the status reading.\n',
+    'ui/card.js': CARD,
+    'capability/index.mjs': CAPABILITY,
+  },
+  expect: {
+    fail: [],
+  },
+};

package/scaffold/.agent/skills/plugin/evals/run.mjs

@@ -0,0 +1,118 @@
+#!/usr/bin/env node
+/**
+ * evals/run.mjs — proof that the recipe and its checks work.
+ *
+ * Each case is a synthetic plugin whose correct outcome is already known. Most
+ * are defects observed in the real ecosystem; one is a plugin that follows the
+ * recipe and must be accepted. Every case is materialised into a temp
+ * directory, run through scripts/record.mjs, and asserted.
+ *
+ *   node evals/run.mjs [--case <name>] [--json] [--keep]
+ *
+ * A case passes when record.mjs reports exactly the failures the case expects:
+ * an eval that passes because the checker looks at nothing is not evidence.
+ */
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { execFileSync } from 'node:child_process'
+import { pathToFileURL } from 'node:url'
+
+const HERE = import.meta.dirname
+const RECORD = path.join(HERE, '..', 'scripts', 'record.mjs')
+const args = process.argv.slice(2)
+const asJson = args.includes('--json')
+const keep = args.includes('--keep')
+const onlyCase = args.includes('--case') ? args[args.indexOf('--case') + 1] : null
+
+if (!fs.existsSync(RECORD)) {
+  console.error(`record.mjs not found at ${RECORD}`)
+  process.exit(2)
+}
+
+/* Load every case. */
+const caseFiles = fs.readdirSync(path.join(HERE, 'cases'))
+  .filter((f) => f.endsWith('.mjs'))
+  .sort()
+const cases = []
+for (const file of caseFiles) {
+  const mod = await import(pathToFileURL(path.join(HERE, 'cases', file)).href)
+  if (mod.default) cases.push({ ...mod.default, file })
+}
+
+/* Materialise and check one case. */
+function materialise(spec, dir) {
+  for (const [rel, content] of Object.entries(spec.files)) {
+    const abs = path.join(dir, rel)
+    fs.mkdirSync(path.dirname(abs), { recursive: true })
+    fs.writeFileSync(abs, content)
+  }
+}
+
+function runRecord(dir) {
+  try {
+    const out = execFileSync(process.execPath, [RECORD, dir, '--json'], { encoding: 'utf8', timeout: 60000 })
+    return { code: 0, report: JSON.parse(out) }
+  } catch (err) {
+    // record.mjs exits non-zero when it finds failures; the JSON is still valid.
+    const out = String(err.stdout || '')
+    try { return { code: err.status ?? 1, report: JSON.parse(out) } }
+    catch { return { code: err.status ?? 1, report: null, raw: out + String(err.stderr || '') } }
+  }
+}
+
+const results = []
+for (const spec of cases) {
+  if (onlyCase && spec.name !== onlyCase) continue
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), `plugin-eval-${spec.name}-`))
+  try {
+    materialise(spec, dir)
+    const { report } = runRecord(dir)
+
+    if (!report) {
+      results.push({ name: spec.name, ok: false, reason: 'record.mjs produced no JSON' })
+      continue
+    }
+
+    const failures = report.results.filter((r) => r.level === 'FAIL')
+    const failureText = failures.map((f) => `${f.check}: ${f.detail}`).join(' | ')
+    const expected = spec.expect.fail || []
+
+    const missing = expected.filter((want) => !failureText.includes(want.split(':')[0].trim()))
+    const unexpected = expected.length === 0
+      ? failures.map((f) => `${f.check}: ${f.detail}`)
+      : []
+
+    const ok = missing.length === 0 && unexpected.length === 0
+    results.push({
+      name: spec.name,
+      ok,
+      why: spec.why,
+      expected,
+      found: failures.map((f) => `${f.check} — ${f.detail}`),
+      reason: ok ? null
+        : missing.length ? `checker missed: ${missing.join(', ')}`
+          : `unexpected failures: ${unexpected.join(' | ')}`,
+    })
+  } finally {
+    if (!keep) fs.rmSync(dir, { recursive: true, force: true })
+    else console.log(`kept: ${dir}`)
+  }
+}
+
+/* Report. */
+if (asJson) {
+  process.stdout.write(JSON.stringify({ cases: results, passed: results.filter((r) => r.ok).length, total: results.length }, null, 2) + '\n')
+} else {
+  for (const r of results) {
+    console.log(`${r.ok ? '  ok  ' : ' FAIL '} ${r.name}`)
+    if (r.why) console.log(`         why: ${r.why}`)
+    if (r.expected.length) console.log(`         expects: ${r.expected.join(', ')}`)
+    if (r.found.length) console.log(`         found:   ${r.found.join(' | ')}`)
+    if (r.reason) console.log(`         ${r.reason}`)
+  }
+  const passed = results.filter((r) => r.ok).length
+  console.log(`\n${passed}/${results.length} eval cases passed`)
+}
+
+process.exitCode = results.every((r) => r.ok) ? 0 : 1

package/scaffold/.agent/skills/plugin/prompts/01-function.md

@@ -0,0 +1,29 @@
+# Prompt 1 — Establish the function
+
+**Do this before any code.** A plugin designed before its function is understood becomes a template.
+
+## The prompt
+
+Answer all five, concretely:
+
+1. **What capability does this add?** One sentence. If it needs "and" to hold together, it is two plugins.
+2. **Who uses it, and what two or three things do they actually do with it?** Name the tasks, not the features.
+3. **What must be visible without a single click?** This decides the hierarchy later.
+4. **What does it depend on outside itself?** A provider's API, a local service, other machines on the mesh, another plugin, or nothing.
+5. **Could another application want this capability?** If yes, part of this plugin is the capability and part is Total Recall presentation, and they must be separable from the first line of code.
+
+## Correct means
+
+- You can name the users and their tasks in plain words.
+- You know whether a scaffold is in scope (Prompt 7), because that changes where the domain logic lives.
+- The capability is one thing, not a bundle.
+
+If you cannot answer 1 and 2, you are not ready to write code. Stop and find out.
+
+## Record it
+
+Write the answers into `ui/DESIGN.md` when you reach Prompt 6 — they are the basis of the face. Keep the scaffold answer for Prompt 7.
+
+## Check
+
+None mechanical. The check is that you can state the answers without hedging.

package/scaffold/.agent/skills/plugin/prompts/02-surfaces.md

@@ -0,0 +1,43 @@
+# Prompt 2 — Choose the surfaces
+
+A plugin declares the surfaces its capability needs. **It is not one shape.**
+
+## The prompt
+
+Read [surfaces](../references/surfaces.md) and select only what this function needs.
+
+| Surface | Use when the capability… |
+| --- | --- |
+| Memory | adds a new kind of knowledge to the vault |
+| Context | must change what agents read at the start of a task |
+| CLI | offers operations an operator or an agent invokes |
+| Skills | ships instruction an agent loads on demand |
+| Tasks | must run on a schedule without being asked |
+| Runtime | provides live behaviour rather than a command |
+| UI | always — every plugin has a face |
+| Deploy | is deployed into other applications |
+| Distribution | is shared, sold, or operated as a service |
+| Composition | builds on other bricks rather than starting from zero |
+
+A plugin might be only a memory category. Only a generator. Only a router. Only a skill pack. A CLI with no UI beyond its card. Several at once.
+
+## Correct means
+
+- Every declared surface is **used**. An unused surface is noise and a maintenance cost.
+- Every surface the function needs is **declared**. A missing one makes the capability invisible to the host and to agents.
+- The set is justified by Prompt 1's answers, not by what other plugins do.
+
+## Common wrong answers
+
+- Declaring a CLI out of habit for a capability that is purely a memory contribution.
+- Skipping `status` for a plugin whose state a user must be able to check at a glance.
+- Declaring `tasks` when nothing needs to run unasked.
+- Declaring `requires` to pull in a brick that is not actually needed.
+
+## Check
+
+```
+node <skill>/scripts/record.mjs . --manifest
+```
+
+Reports each declared surface and whether a stated function supports it.