total-recall-brain 3.40.6 → 3.41.0

package/scaffold/.agent/skills/plugin/references/surfaces.md

@@ -0,0 +1,206 @@
+# Surfaces
+
+Every surface a plugin can declare, with the exact fields for each.
+
+**Declare only what the capability needs.** An unused surface is noise; a missing one hides the capability. Identity is required; everything else is optional and independent.
+
+---
+
+## Identity — always required
+
+```json
+{
+  "id": "host-telemetry",
+  "name": "Host Telemetry",
+  "version": "1.0.0",
+  "description": "One concrete sentence saying what this adds.",
+  "author": "Greg",
+  "license": "MIT",
+  "use_cases": ["operations", "self-hosting"]
+}
+```
+
+| Field | Rule |
+| --- | --- |
+| `id` | lowercase kebab-case, matching the repository `tr-plugin-<id>` |
+| `name` | plain and descriptive; never an invented brand for a wrapper of someone else's service |
+| `version` | semver |
+| `description` | at least five characters, one sentence, no filler |
+| `author`, `license` | authorship and license, as shipped |
+| `use_cases` | free-form tags used to filter discovery |
+
+---
+
+## CLI
+
+```json
+"cli": {
+  "command": "host-telemetry",
+  "handler": "./cli.mjs",
+  "subcommands": [
+    { "name": "sample", "description": "One telemetry reading from this machine",
+      "effect": "read", "output": "json",
+      "args": [ { "name": "json", "flag": "--json", "label": "JSON output", "type": "boolean" } ] },
+    { "name": "charge", "description": "Create a payment", "effect": "send", "output": "json", "timeout_ms": 30000,
+      "args": [
+        { "name": "amount", "flag": "--amount", "label": "Amount", "type": "number", "required": true },
+        { "name": "currency", "flag": "--currency", "label": "Currency", "type": "choice", "options": ["usd", "eur"] },
+        { "name": "secretKey", "label": "Secret key", "type": "string", "secret": true }
+      ] }
+  ]
+}
+```
+
+| Field | Required | Rule |
+| --- | --- | --- |
+| `name` | yes | kebab-case, unique, declared once |
+| `description` | yes | what the operation does |
+| `effect` | yes | `read`, `write`, `destructive`, `send` |
+| `args[].name` | yes | camelCase |
+| `args[].label` | yes | human label |
+| `args[].type` | yes | `string`, `number`, `boolean`, `choice` |
+| `args[].flag` | for non-secret | `--flag-name` |
+| `args[].positional` | alternative to flag | `true` |
+| `args[].required` | no | `true` when the operation cannot run without it |
+| `args[].options` | for `choice` | non-empty array |
+| `args[].secret` | for credentials | `true`; the value travels over **stdin**, never `argv`. Exactly one secret argument per command, a string, with no flag |
+| `output` | no | `json` (default) or `text` |
+| `timeout_ms` | no | 1–600000, for slow operations |
+
+The handler must emit JSON under `--json` on **every** subcommand, exit non-zero on failure with the real error on stderr, and answer `--help` without resolving credentials.
+
+## Memory
+
+```json
+"ssss_schemas": { "categories": [ { "name": "host-readings", "description": "…", "node_type": "memory" } ] }
+```
+
+Adds a category to the vault. Use when the capability contributes a new kind of knowledge.
+
+## Context
+
+```json
+"compile": { "generator": "./generate.mjs", "watch": ["data"] }
+```
+
+`generator` is a safe relative path; `watch` lists plugin-owned directories the compiler re-reads. Use when the capability must change what agents read at the start of a task.
+
+## Skills
+
+```json
+"skills": [ { "id": "host-telemetry", "path": "./skills/host-telemetry/SKILL.md" } ]
+```
+
+Instruction an agent loads on demand.
+
+## Tasks
+
+```json
+"tasks": [ { "intent": "Sample every node", "schedule": "*/15 * * * *", "command": "fleet", "placement": "selected-node" } ]
+```
+
+Five-field cron. `command` must be a declared subcommand.
+
+## Runtime
+
+```json
+"runtime": { "modules": { "sampler": "./runtime/sampler.mjs" }, "routers": ["./routes/readings.mjs"] }
+```
+
+Live behaviour rather than a command. Module keys are lowercase kebab-case.
+
+## UI — the card face
+
+```json
+"ui": {
+  "design_tokens": "ui/DESIGN.md",
+  "elements": [
+    { "id": "card", "kind": "card", "tag": "tr-host-telemetry-card", "module": "ui/card.js",
+      "description": "Fleet telemetry board" }
+  ]
+}
+```
+
+**Every plugin has a card**: exactly one element of kind `card`, and **no `card_layout`** — a declared template is an error, not a fallback. `description` says what the element is. See [card](card.md).
+
+## Deploy
+
+```json
+"deploy": { "targets": ["ssss-app", "nextjs"], "required_ssss_version": ">=0.9.3",
+  "access_grants": ["ssss:vault:read"], "resources": { "db": "sqlite" } }
+```
+
+Use when the capability is deployed into other applications.
+
+## Distribution and monetization
+
+```json
+"distribution": { "tier": "official", "license": "open" },
+"monetization": { "model": "metered", "price_cents": 2, "currency": "usd", "period": "per-use",
+  "license_key_secret": "SERVICE_LICENSE_KEY", "checkout_url": "https://…" }
+```
+
+`tier`: `core`, `official`, `personal`, `community`. `license`: `open` or `closed`. A closed plugin is an operated service behind a thin client; never rely on a local license check.
+
+## Composition
+
+```json
+"requires": [ { "id": "auth", "range": "^1.0.0" } ]
+```
+
+Builds on other bricks instead of starting from zero.
+
+## Credentials
+
+```json
+"secrets": [ { "key": "SERVICE_API_KEY", "description": "Reads and creates charges", "required": true } ]
+```
+
+Uppercase key. Resolved only through `total-recall auth secret`. No store of the plugin's own, and no ambient environment variable.
+
+## Settings
+
+```json
+"configuration": { "fields": [ { "key": "region", "label": "Region", "type": "string", "default": "us-east" } ] }
+```
+
+Keys are camelCase and may not contain `password`, `secret`, `apiKey` or `token` — those belong in `secrets`.
+
+## Status
+
+```json
+"status": { "command": "status", "refresh_seconds": 30 }
+```
+
+`command` must be a declared `read` subcommand. `refresh_seconds` is 5–86400.
+
+## Branding
+
+```json
+"branding": {
+  "name": "Host Telemetry", "color": "#059669", "accent": "#10b981",
+  "font": "jetbrains-mono", "density": "compact", "radius": "sm", "header": "ledger-rule",
+  "badge": "Telemetry", "logo": "ui/logo.svg",
+  "provider": { "name": "Stripe", "url": "https://stripe.com" }
+}
+```
+
+| Field | Values |
+| --- | --- |
+| `color`, `accent` | `#rrggbb` |
+| `font` | `system`, `inter`, `ibm-plex`, `space-grotesk`, `jetbrains-mono`, `dm-sans`, `outfit`, `fraunces`, `newsreader`, `chivo-mono` |
+| `density` | `compact`, `comfortable`, `spacious` |
+| `radius` | `none`, `sm`, `md`, `lg`, `pill` |
+| `header` | `plain`, `ledger-rule`, `band`, `tab-strip`, `badge-left` |
+| `logo` | relative `.svg` or `.png` inside the plugin; a real mark, never an emoji or generic icon |
+| `provider` | for a wrapper of someone else's API: set it and keep that provider's name and brand rather than inventing your own |
+
+---
+
+## Validating
+
+```
+total-recall plugin info <id>
+```
+
+No errors and no warnings before the plugin is done. `scripts/record.mjs` runs the same validation plus the checks the validator cannot make.

package/scaffold/.agent/skills/plugin/scripts/record.mjs

@@ -0,0 +1,360 @@
+#!/usr/bin/env node
+/**
+ * record.mjs — the plugin creator's verification battery.
+ *
+ * Runs the checks the recipe asks for, against a plugin repository. Exits
+ * non-zero on any failure and prints the real reason. Nothing here trusts a
+ * declaration: every check reads the actual files or runs the actual command.
+ *
+ *   node record.mjs <pluginDir> [--manifest|--card|--secrets|--scaffold|--json]
+ *
+ * Checks are marked PASS, FAIL or WARN. A WARN is a judgement call the agent
+ * must resolve; a FAIL is a rejection.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { pathToFileURL } from 'node:url';
+
+const args = process.argv.slice(2);
+const json = args.includes('--json');
+const only = ['--manifest', '--card', '--secrets', '--scaffold'].filter((f) => args.includes(f));
+const root = path.resolve(args.find((a) => !a.startsWith('-')) || '.');
+const want = (section) => only.length === 0 || only.includes(section);
+
+const results = [];
+const record = (section, level, check, detail) => results.push({ section, level, check, detail });
+
+/* ── helpers ─────────────────────────────────────────────────────────────── */
+
+const read = (rel) => {
+  try { return fs.readFileSync(path.join(root, rel), 'utf8'); } catch { return ''; }
+};
+const exists = (rel) => fs.existsSync(path.join(root, rel));
+
+/** Files the plugin owns, excluding dependencies and the brain. */
+function walk(dir, out = [], base = root) {
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (entry.name.startsWith('.') || ['node_modules', 'bricks'].includes(entry.name)) continue;
+    const abs = path.join(dir, entry.name);
+    if (entry.isSymbolicLink()) continue;
+    if (entry.isDirectory()) walk(abs, out, base);
+    else out.push(path.relative(base, abs));
+  }
+  return out;
+}
+
+/* ── manifest ────────────────────────────────────────────────────────────── */
+
+let manifest = null;
+if (want('--manifest')) {
+  const file = path.join(root, 'plugin.json');
+  if (!fs.existsSync(file)) {
+    record('manifest', 'FAIL', 'plugin.json exists', 'no plugin.json in ' + root);
+  } else {
+    try {
+      manifest = JSON.parse(fs.readFileSync(file, 'utf8'));
+      record('manifest', 'PASS', 'plugin.json parses', `${manifest.id} v${manifest.version}`);
+    } catch (err) {
+      record('manifest', 'FAIL', 'plugin.json parses', err.message);
+    }
+  }
+}
+
+// Validate with the real contract when this skill is inside a Total Recall checkout.
+if (manifest) {
+  const loaderPath = path.resolve(import.meta.dirname, '../../../../src/core/plugin-loader.mjs');
+  if (fs.existsSync(loaderPath)) {
+    try {
+      const { validatePluginManifest } = await import(pathToFileURL(loaderPath).href);
+      const v = validatePluginManifest(manifest);
+      for (const e of v.errors || []) record('manifest', 'FAIL', 'contract', e);
+      for (const w of v.warnings || []) record('manifest', 'WARN', 'contract', w);
+      if (!(v.errors || []).length && !(v.warnings || []).length) {
+        record('manifest', 'PASS', 'contract', 'no errors, no warnings');
+      }
+    } catch (err) {
+      record('manifest', 'WARN', 'contract', `validator unavailable: ${err.message}`);
+    }
+  } else {
+    record('manifest', 'WARN', 'contract', 'validator not found; structural checks only');
+  }
+
+  // Card declaration
+  const elements = manifest.ui?.elements || [];
+  const faces = elements.filter((e) => e && (e.kind === 'card' || e.kind === 'panel'));
+  if (manifest.card_layout !== undefined) {
+    record('manifest', 'FAIL', 'no template', "'card_layout' is declared; a face is bespoke owner code");
+  } else {
+    record('manifest', 'PASS', 'no template', 'no card_layout');
+  }
+  if (faces.length === 0) {
+    record('manifest', 'FAIL', 'card declared', 'every plugin has a card; ui.elements declares none');
+  } else if (faces.length > 1) {
+    record('manifest', 'FAIL', 'card declared', `${faces.length} faces declared; exactly one is allowed`);
+  } else {
+    const face = faces[0];
+    record('manifest', 'PASS', 'card declared', `<${face.tag}> → ${face.module}`);
+    if (!exists(face.module)) record('manifest', 'FAIL', 'card module resolves', `${face.module} does not exist`);
+    else record('manifest', 'PASS', 'card module resolves', face.module);
+  }
+
+  // Declared effects and typed arguments on the CLI surface.
+  for (const sub of manifest.cli?.subcommands || []) {
+    if (!['read', 'write', 'destructive', 'send'].includes(sub.effect)) {
+      record('manifest', 'FAIL', 'effect declared', `'${sub.name}' has no valid effect`);
+    }
+    for (const arg of sub.args || []) {
+      if (arg.secret === true && arg.flag !== undefined) {
+        record('manifest', 'FAIL', 'secret over stdin', `'${sub.name}.${arg.name}' is secret but carries a flag`);
+      }
+    }
+  }
+
+  // Status must bind to a real read command.
+  const status = manifest.status;
+  if (status?.command) {
+    const sub = (manifest.cli?.subcommands || []).find((s) => s.name === status.command);
+    if (!sub) record('manifest', 'FAIL', 'status binds', `status.command '${status.command}' is not declared`);
+    else if (sub.effect && sub.effect !== 'read') record('manifest', 'FAIL', 'status binds', `status.command '${status.command}' is not a read`);
+    else record('manifest', 'PASS', 'status binds', status.command);
+  }
+}
+
+/* ── card ────────────────────────────────────────────────────────────────── */
+
+if (want('--card') && manifest) {
+  const face = (manifest.ui?.elements || []).find((e) => e && e.kind === 'card');
+  const src = face ? read(face.module) : '';
+  if (!src) {
+    record('card', 'FAIL', 'card source readable', 'no card module to read');
+  } else {
+    const lines = src.split('\n');
+
+    // A credential must never be collectable from the face.
+    if (/type\s*=\s*["']password["']/.test(src) || /input\.type\s*=\s*["']password["']/.test(src)) {
+      record('card', 'FAIL', 'never collects a credential', 'a password input exists in the card');
+    } else {
+      record('card', 'PASS', 'never collects a credential', 'no password input');
+    }
+    if (/save-token|dispatchEvent\(\s*new CustomEvent\(\s*["']save-/.test(src)) {
+      record('card', 'FAIL', 'never transmits a credential', 'the card dispatches a credential event');
+    } else {
+      record('card', 'PASS', 'never transmits a credential', 'no credential event');
+    }
+
+    // Seeded values: a literal that looks like a reading, not a read of one.
+    // Each pattern requires an actual literal (a digit or a quoted string), so
+    // a ternary such as `? h.loadAvg : []` is not mistaken for a seed.
+    const seedPatterns = [
+      [/\bthis\.(sample|reading|status|telemetry|gateway|data)\s*=\s*\{[^}]*\b(hostname|loadAvg|usedPercent|uptimeSeconds)\b/s, 'a seeded reading object'],
+      [/hostname\s*:\s*["'][^"']+["']/, 'a literal hostname'],
+      [/usedPercent\s*:\s*\d/, 'a literal usedPercent'],
+      [/loadAvg\s*:\s*\[\s*\d/, 'a literal load average'],
+      [/\bvalue\s*=\s*["']\d+(\.\d+)?["']/, 'a seeded input value'],
+    ];
+    let seeded = [];
+    for (const [re, what] of seedPatterns) if (re.test(src)) seeded.push(what);
+    if (seeded.length) record('card', 'FAIL', 'no seeded values', seeded.join('; '));
+    else record('card', 'PASS', 'no seeded values', 'no literal reading found');
+
+    // A reassuring default is a *fallback* for an unknown — `x || 'Up to date'`
+    // or `x ?? 'Synced'`. The same word chosen by a ternary between two honest
+    // labels (`ok ? 'Connected' : 'Unconfigured'`) is not a default, so only a
+    // fallback position is flagged.
+    const reassuringWords = ['Up to date', 'Synced', 'Repository Active', 'ONLINE', 'Healthy', 'Connected', 'All good', 'OK'];
+    const reassuranceFallbacks = [];
+    for (const word of reassuringWords) {
+      for (const quote of ["'", '"']) {
+        const literal = `${quote}${word}${quote}`;
+        const index = src.indexOf(literal);
+        if (index === -1) continue;
+        // Look back for the operator that makes it a default.
+        const before = src.slice(Math.max(0, index - 40), index);
+        if (/\|\||\?\?\s*$/.test(before) || /\?\?\s*$/.test(src.slice(Math.max(0, index - 6), index))) {
+          reassuranceFallbacks.push(word);
+          break;
+        }
+        // A default inside a catch branch is a fallback too.
+        const sinceCatch = src.slice(src.lastIndexOf('catch', index) === -1 ? 0 : src.lastIndexOf('catch', index), index);
+        if (src.lastIndexOf('catch', index) !== -1 && sinceCatch.length < 200 && !/}\s*(else|finally)/.test(sinceCatch)) {
+          reassuranceFallbacks.push(`${word} (in a catch)`);
+          break;
+        }
+      }
+    }
+    if (reassuranceFallbacks.length) record('card', 'FAIL', 'no reassuring default', reassuranceFallbacks.join(', '));
+    else record('card', 'PASS', 'no reassuring default', 'none found');
+
+    // Randomness is how fabricated ids appear.
+    if (/Math\.random\(/.test(src)) record('card', 'FAIL', 'no invented identifiers', 'Math.random in the card');
+    else record('card', 'PASS', 'no invented identifiers', 'no Math.random');
+
+    // Every read must go through the host, and failures must be states.
+    if (!/host\.run|this\.host/.test(src)) {
+      record('card', 'WARN', 'reads through the host', 'no host.run reference; does it render real data?');
+    } else {
+      record('card', 'PASS', 'reads through the host', 'host.run is used');
+    }
+    if (!/catch/.test(src)) record('card', 'WARN', 'failures are states', 'no catch; can the card show a failed read?');
+    else record('card', 'PASS', 'failures are states', 'a catch exists');
+
+    // A timer left running after disconnect.
+    if (/setInterval/.test(src) && !/disconnectedCallback/.test(src)) {
+      record('card', 'FAIL', 'timers cleared', 'setInterval without disconnectedCallback');
+    } else {
+      record('card', 'PASS', 'timers cleared', 'no leaked interval');
+    }
+
+    // Raw hex outside a token block suggests a hard-coded palette.
+    const hex = [...src.matchAll(/#[0-9a-fA-F]{6}\b/g)];
+    const tokenBlockHex = (src.match(/--face-[a-z-]+:\s*#[0-9a-fA-F]{3,8}/g) || []).length;
+    if (hex.length - tokenBlockHex > 6) {
+      record('card', 'WARN', 'tokens only', `${hex.length - tokenBlockHex} raw hex values outside token declarations`);
+    } else {
+      record('card', 'PASS', 'tokens only', 'colour is declared as tokens');
+    }
+
+    // The host's tokens must actually be used.
+    for (const token of ['--text-primary', '--border']) {
+      if (!src.includes(token)) record('card', 'WARN', 'host tokens used', `${token} is not referenced; the face may not adapt to the dashboard`);
+    }
+
+    // Accessibility floor.
+    if (!/min-height:\s*(4[4-9]|[5-9]\d)px/.test(src)) {
+      record('card', 'WARN', 'touch targets', 'no control declares a >=44px minimum height');
+    } else {
+      record('card', 'PASS', 'touch targets', 'controls reach 44px');
+    }
+    if (!/prefers-reduced-motion/.test(src)) {
+      record('card', 'WARN', 'reduced motion', 'prefers-reduced-motion is not respected');
+    } else {
+      record('card', 'PASS', 'reduced motion', 'respected');
+    }
+  }
+}
+
+/* ── secrets ─────────────────────────────────────────────────────────────── */
+
+if (want('--secrets') && manifest) {
+  const files = walk(root).filter((f) => /\.(mjs|js)$/.test(f));
+
+  // A declared credential must not be read from the ambient environment.
+  for (const secret of manifest.secrets || []) {
+    const key = secret.key;
+    let envRead = null;
+    for (const f of files) {
+      if (f.startsWith('test/')) continue;
+      const src = read(f);
+      if (new RegExp(`process\\.env(\\.${key}|\\[\\s*["']${key}["']\\s*\\])`).test(src)) { envRead = f; break; }
+    }
+    if (envRead) record('secrets', 'FAIL', 'declared secret is not ambient', `${key} read from process.env in ${envRead}`);
+    else record('secrets', 'PASS', 'declared secret is not ambient', key);
+  }
+
+  // The card may name a credential's identifier — it must, so the operator
+  // knows which key to set. What it must never do is receive or render the
+  // value. The only channel a value could travel on is stdin, so that is the
+  // thing to forbid.
+  const faceSrc = read(manifest.ui?.elements?.find?.((e) => e.kind === 'card')?.module || '');
+  if (/stdin\s*:/.test(faceSrc)) {
+    record('secrets', 'FAIL', 'card never receives a credential', 'the card passes stdin to host.run');
+  } else {
+    record('secrets', 'PASS', 'card never receives a credential', 'no stdin channel from the face');
+  }
+  const names = (manifest.secrets || []).filter((s) => faceSrc.includes(s.key));
+  if (names.length) {
+    record('secrets', 'PASS', 'card names the identifier only', `${names.map((s) => s.key).join(', ')} — so the operator can fix it`);
+  }
+
+  // Credential access must go through auth.
+  const authUse = files.some((f) => /auth['"],\s*['"]secret|auth secret/.test(read(f)));
+  if ((manifest.secrets || []).length && !authUse) {
+    record('secrets', 'FAIL', 'credentials resolve through auth', 'no auth secret call found');
+  } else if ((manifest.secrets || []).length) {
+    record('secrets', 'PASS', 'credentials resolve through auth', 'auth secret is used');
+  }
+}
+
+/* ── scaffold ────────────────────────────────────────────────────────────── */
+
+if (want('--scaffold')) {
+  const capDir = path.join(root, 'capability');
+  if (!fs.existsSync(capDir)) {
+    record('scaffold', 'WARN', 'scaffold present', 'no capability/ — fine if another app would not want this capability');
+  } else {
+    const capEntry = manifest?.capability?.entry || 'capability/index.mjs';
+    const capSrc = read(capEntry);
+    if (!capSrc) {
+      record('scaffold', 'FAIL', 'entry resolves', `${capEntry} does not exist`);
+    } else {
+      record('scaffold', 'PASS', 'entry resolves', capEntry);
+
+      const hostRefs = capSrc.match(/total-recall|TOTAL_RECALL_BIN|auth secret/g) || [];
+      if (hostRefs.length) record('scaffold', 'FAIL', 'no Total Recall dependency', hostRefs.join(', '));
+      else record('scaffold', 'PASS', 'no Total Recall dependency', 'none reachable from the capability');
+
+      const placeholders = capSrc.match(/example\.com|example\.org|localhost:\d+/g) || [];
+      if (placeholders.length) record('scaffold', 'FAIL', 'no placeholder values', placeholders.join(', '));
+      else record('scaffold', 'PASS', 'no placeholder values', 'none');
+
+      if (!/export\s+(async\s+)?function|export\s+const/.test(capSrc)) {
+        record('scaffold', 'FAIL', 'exports the capability', 'no exported function; a builder cannot import it');
+      } else {
+        record('scaffold', 'PASS', 'exports the capability', 'exported functions present');
+      }
+
+      if (/process\.argv|process\.exitCode/.test(capSrc)) {
+        record('scaffold', 'FAIL', 'no CLI concerns', 'argv or exitCode inside the capability');
+      } else {
+        record('scaffold', 'PASS', 'no CLI concerns', 'no argv or exitCode');
+      }
+
+      if (fs.existsSync(path.join(capDir, 'ui'))) {
+        record('scaffold', 'FAIL', 'no UI in the scaffold', 'capability/ui exists');
+      } else {
+        record('scaffold', 'PASS', 'no UI in the scaffold', 'no ui under capability/');
+      }
+    }
+
+    // Prove standalone operation: import it with Total Recall unavailable.
+    try {
+      const env = { ...process.env };
+      delete env.TOTAL_RECALL_BIN;
+      env.PATH = '/nonexistent';
+      execFileSync(process.execPath, ['--input-type=module', '-e',
+        `await import(${JSON.stringify(pathToFileURL(path.join(root, capEntry)).href)})`],
+        { env, stdio: 'pipe', timeout: 15000 });
+      record('scaffold', 'PASS', 'loads with Total Recall absent', 'imported successfully');
+    } catch (err) {
+      record('scaffold', 'FAIL', 'loads with Total Recall absent', String(err.stderr || err.message).trim().split('\n').slice(-2).join(' '));
+    }
+  }
+}
+
+/* ── report ──────────────────────────────────────────────────────────────── */
+
+const fails = results.filter((r) => r.level === 'FAIL');
+const warns = results.filter((r) => r.level === 'WARN');
+
+if (json) {
+  process.stdout.write(JSON.stringify({
+    plugin: manifest?.id || path.basename(root),
+    root,
+    pass: results.filter((r) => r.level === 'PASS').length,
+    fail: fails.length,
+    warn: warns.length,
+    results,
+  }, null, 2) + '\n');
+} else {
+  const tag = { PASS: '  ok  ', FAIL: ' FAIL ', WARN: ' warn ' };
+  let section = '';
+  for (const r of results) {
+    if (r.section !== section) { section = r.section; console.log(`\n${section.toUpperCase()}`); }
+    console.log(`[${tag[r.level]}] ${r.check} — ${r.detail}`);
+  }
+  console.log(`\n${results.filter((r) => r.level === 'PASS').length} passed, ${fails.length} failed, ${warns.length} warnings`);
+  if (warns.length) console.log('\nA warning is a judgement call to resolve, not a pass.');
+}
+
+process.exitCode = fails.length ? 1 : 0;

package/scaffold/.agent/skills/plugin/subagents/card-designer.md

@@ -0,0 +1,60 @@
+---
+name: card-designer
+inputs: a capability brief — users, tasks, what must be visible without a click, dependencies, brand
+returns: ui/DESIGN.md reasoning and a first ui/card.js, or the questions that cannot be answered yet
+---
+
+# Subagent — card designer
+
+Design one plugin's card face. You are **not** filling in a layout: you are designing the interface for this capability, and it must not resemble any other plugin's.
+
+Read [card](../references/card.md) first. It is the specification.
+
+## Ask before you draw
+
+Given the brief, you must be able to answer:
+
+1. Who uses it, and what are they in the middle of doing?
+2. What must be visible without a single click?
+3. What is the one primary action, and what is destructive?
+4. What is the domain's own vocabulary?
+5. What is the worst thing that happens if the operator misreads this screen?
+
+**If you cannot answer 1, 2 or 4 from the brief, stop and return the questions.** A face designed around a guessed function is a template, which is the failure this exists to prevent. Do not invent users or tasks to proceed.
+
+## Design
+
+1. Write `ui/DESIGN.md`: who uses it, the tasks, what is visible without a click, the vocabulary, the chosen arrangement and why it fits this plugin in its own terms, the `tokens:` block, and the state list.
+2. Author `ui/card.js`: one Web Component, the single element of kind `card`, screens the plugin defines and orders by task frequency, wide not a column.
+
+## Hard rules
+
+- **No template, no `card_layout`, no region or widget vocabulary.**
+- **Every value comes from `host.run`.** Before the first read, frames show em dashes. Never a seed, never a placeholder, never an example default.
+- **A failed read clears the figures** rather than retaining a previous one as current.
+- **Unknown is an em dash with its reason.** `0` and `unknown` are different facts.
+- **Name the driver of a combined severity**, or a red tile beside a green figure reads as a contradiction.
+- **The host's tokens, tuned for a dark surface.** The dashboard is dark; verify on its real values, not on white.
+- **Severity never by colour alone.**
+- **44 px controls, keyboard reachable, visible focus, `prefers-reduced-motion`.**
+- **Never render a secret, never collect one.**
+- **Name each screen for the task it serves**, not for a command.
+
+## Before returning
+
+- Render at 360, 768 and 1280 px on the dark tokens. No horizontal overflow.
+- Render every state: present, missing, unreachable, rejected, empty, stale.
+- Put it beside another plugin's face. If the two are interchangeable, redesign.
+
+## Return
+
+```
+DESIGN.md: <the file, or the blocking questions>
+card.js: <the file>
+screens: <each screen and the task it serves>
+states rendered: <which you exercised and what you saw>
+distinguishable from: <which plugin you compared against, and how they differ>
+unverified: <what you could not check>
+```
+
+Never return a face you have not rendered and looked at.