total-recall-brain 3.40.7 → 3.41.0

package/scaffold/.agent/skills/plugin/prompts/03-scaffold.md

@@ -0,0 +1,31 @@
+# Prompt 3 — Scaffold, then stop generating
+
+## The prompt
+
+```
+total-recall plugin create <id> --name "<plain descriptive name>" --description "<one concrete sentence>"
+```
+
+You receive a manifest, a CLI handler and a test.
+
+**No UI is generated, deliberately.** A card face is a design act: it requires knowing the users, their tasks and the domain's vocabulary, which is Prompt 1's work. A generated stub is precisely what produced an ecosystem of identical cards, so the scaffold refuses to write one.
+
+**The scaffold is not yet a valid plugin.** It has no card, and `plugin info` will say so. Do not treat a successful scaffold as finished work, and do not declare a card you have not designed.
+
+## Correct means
+
+- The repository exists at `tr-plugin-<id>` with a manifest carrying identity only.
+- Its tests run.
+- You know the face is outstanding, and that Prompts 4–6 are how it gets written.
+
+## Then
+
+Set the surfaces you chose in Prompt 2: add `cli.subcommands`, `secrets`, `configuration`, `status`, `branding`, and finally `ui.elements` when the face exists.
+
+## Check
+
+```
+node <skill>/scripts/record.mjs . --manifest
+```
+
+Reports the surfaces present and the surfaces outstanding. A plugin with no `ui.elements` fails — correctly — until Prompt 6 is done.

package/scaffold/.agent/skills/plugin/prompts/04-cli.md

@@ -0,0 +1,49 @@
+# Prompt 4 — Write the CLI as an agent interface
+
+The CLI is used by two audiences: an operator at a terminal, and **an agent** that discovers the plugin, calls it, and parses the result. Write for both.
+
+## The prompt
+
+In `plugin.json`, for every operation:
+
+- a **name** in lowercase kebab-case, unique
+- a **description** of what it does
+- an **effect**: `read`, `write`, `destructive` or `send`
+- **typed arguments**, each with a label — `string`, `number`, `boolean`, `choice` with options. Mark positionals, mark requireds.
+- a **secret argument** is marked `secret = true`, and its value travels over stdin, never `argv`. One per command, a string, no flag.
+- `output: "json"` unless the result is genuinely prose
+- `timeout_ms` for anything slow
+
+In `cli.mjs`:
+
+- `--json` emits structured output on **every** subcommand, including those that default to text
+- a failure prints the real error to **stderr** and exits **non-zero**
+- `--help` answers **without resolving credentials**, so it works before setup
+- no secret value reaches `argv`, stdout, stderr or a log
+
+## Correct means
+
+An agent can:
+
+1. run `total-recall plugin library --json` and see this plugin's operations, their arguments and their effects;
+2. choose an operation without reading prose;
+3. call `total-recall <id> <op> <args> --json`;
+4. parse the JSON;
+5. tell success from failure from the exit code.
+
+## Common wrong answers
+
+- `--json` that only some subcommands honour.
+- Resolving a credential at the top of `run()` so `--help` fails without a key.
+- Printing a success message on a failed HTTP call.
+- Taking an API key as `--key <value>`, which puts it in `argv`, in shell history and in the process list.
+- Declaring an effect of `read` for an operation that mutates.
+
+## Check
+
+```
+node <skill>/scripts/record.mjs . --manifest
+node <skill>/scripts/record.mjs . --secrets
+```
+
+Then run `--help` and one `--json` call by hand and read the real output.

package/scaffold/.agent/skills/plugin/prompts/05-credentials.md

@@ -0,0 +1,41 @@
+# Prompt 5 — Declare credentials and settings
+
+There is exactly **one** credential path in the whole system, and it belongs to the auth plugin.
+
+## The prompt
+
+**Credentials.** Every key the plugin reads goes in `secrets[]`:
+
+```json
+"secrets": [ { "key": "SERVICE_API_KEY", "description": "Reads and creates charges", "required": true } ]
+```
+
+Resolve it only through `total-recall auth secret`. The plugin has no store of its own, reads no ambient environment variable as a fallback, and accepts no key on `argv`.
+
+**Settings.** Every setting goes in `configuration.fields` with its type and default. Field keys are camelCase and may not contain `password`, `secret`, `apiKey` or `token` — those belong in `secrets`.
+
+**The card** reports a credential as *present* or *missing*. It never renders a value, and never renders an input that accepts one. To set a key, the card hands over the command:
+
+```
+total-recall auth secret set SERVICE_API_KEY --stdin
+```
+
+## Correct means
+
+- Exactly one credential path exists, and it is auth.
+- The card has no code path that can receive a key value, so it cannot leak one.
+- A setting a user must change is declared, so it is visible rather than buried in code.
+
+## Why the card must not collect keys
+
+The rule is not bureaucracy: one store means one rotation path and one audit trail. A per-plugin key screen violates it even when it writes to the same store, because it makes the plugin the place an operator thinks of when a key must change. It also creates a receive path for the secret inside plugin code, which is a leak surface that would otherwise not exist.
+
+Evidence: a scaffolded panel rendered `<input type="password">` and dispatched the raw value to the host; a real card built three such screens.
+
+## Check
+
+```
+node <skill>/scripts/record.mjs . --secrets
+```
+
+Fails if a secret is reachable in `argv`, in stdout, in a log, or in the rendered card.

package/scaffold/.agent/skills/plugin/prompts/06-card.md

@@ -0,0 +1,46 @@
+# Prompt 6 — Design the card face by hand
+
+Every plugin has a card face. It is bespoke owner code, written for this plugin and no other.
+
+Full specification: [card](../references/card.md).
+
+## The prompt
+
+Work in this order. Write the reasoning into `ui/DESIGN.md` **before** writing component code.
+
+1. Who uses it, and what are they in the middle of doing? Name the real tasks.
+2. What must be visible without a single click? That decides the hierarchy.
+3. What is the one primary action, and what is destructive?
+4. What is the domain's own vocabulary? Use it. Never render a domain as "a list of commands".
+5. Then choose the arrangement, and justify it in the plugin's own terms.
+
+Then author `ui/card.js`:
+
+- **One bespoke Web Component**, declared as the single element of kind `card` in `ui.elements`. No `card_layout`, no template name, no region or widget vocabulary.
+- **Screens the plugin defines**, ordered by the plugin's own tasks, most-used first. Never one screen per subcommand.
+- **Wide, not a column.**
+- **Real data only.** Every value from `host.run(subcommand, args)`. Anything not returned renders an em dash with its reason.
+- **Failures are states**, each rendered explicitly with the time of the last attempt.
+- **Name a value's driver** when severity combines several measures, or a red tile beside a green figure reads as a contradiction.
+- **The host's tokens.** The dashboard is dark: use the injected `--text-*`, `--bg-*`, `--border`, `--accent` and your brand tokens. Declare state colours once in a `:host` block and keep them legible on dark.
+- **Accessible**: 44 px controls, keyboard reachable, visible focus, contrast-checked states, `prefers-reduced-motion` respected.
+- **Severity never by colour alone** — pair every colour with a word.
+- **The card consumes credentials, never collects them.**
+
+## Correct means
+
+1. Render at **360, 768 and 1280 px** — no horizontal overflow anywhere.
+2. Render on the **real dashboard tokens** (dark), not on a white page.
+3. Exercise every state: credential present, missing, provider unreachable, call rejected, empty, stale.
+4. Put it beside another plugin's face. If you cannot tell which is which from the layout alone, it is not finished.
+5. No secret value can reach the DOM in any state.
+
+**Then look at it.** Every defect in the anti-patterns catalogue that begins "only looking reveals" was invisible to a schema check.
+
+## Check
+
+```
+node <skill>/scripts/record.mjs . --card
+```
+
+Then render and inspect it yourself. A passing check is not a design.

package/scaffold/.agent/skills/plugin/prompts/07-scaffold.md

@@ -0,0 +1,52 @@
+# Prompt 7 — Extract the scaffold, if another application wants the capability
+
+Only when Prompt 1 answered yes. Full specification: [scaffold](../references/scaffold.md).
+
+## The prompt
+
+A **scaffold** is the capability extracted so a builder can put it into their own application. It is **not a copy of the plugin**. The plugin is the reference implementation.
+
+Structure the repository as one source with two artifacts:
+
+```
+tr-plugin-<id>/
+  capability/     ← the scaffold payload: exported functions, no host
+    index.mjs
+  cli.mjs         ← the Total Recall entry: parse argv, resolve credentials, call capability/
+  ui/             ← the face; Total Recall only
+  test/
+```
+
+Declare it:
+
+```json
+"capability": { "entry": "capability/index.mjs", "exports": ["…"] }
+```
+
+Move the domain logic — request construction, signature verification, payload building, response mapping — out of the CLI handler and into `capability/`. `cli.mjs` becomes a thin adapter.
+
+The capability must be:
+
+- **explicitly parameterised** — no `argv`, no `process.env`, no module-level singleton
+- **free of environment defaults** — a missing `successUrl` is the caller's error, never a silent `example.com`
+- **transport-injected**, so the app uses its own HTTP client and tests run offline
+- **returning data**, not printing text
+- **throwing errors**, not setting `process.exitCode`
+- **free of Total Recall** — no `total-recall`, no `TOTAL_RECALL_BIN`, no auth store
+- **free of UI** — no card, no `DESIGN.md`, no logo
+
+Write `BRICK.md`: what to import, what to pass, where credentials come from, what comes back.
+
+## Correct means
+
+A builder can lay the capability into their application and use it **without rewriting it**, with no Total Recall present, every environment value supplied by them.
+
+The test is not "does it run". It is **"can a builder use this as it stands?"** Evidence: 19 of 34 plugins currently export only `run`, so a builder must extract the logic by hand — exactly the work a scaffold exists to remove.
+
+## Check
+
+```
+node <skill>/scripts/record.mjs . --scaffold
+```
+
+Asserts the capability loads with `TOTAL_RECALL_BIN` unset and no auth store, that no Total Recall string is reachable from it, that no placeholder value ships, and that its tests fail if it spawns a process.

package/scaffold/.agent/skills/plugin/prompts/08-verify.md

@@ -0,0 +1,43 @@
+# Prompt 8 — Verify, then report
+
+Run every check and report the **real** result. A passing health probe is not a test result.
+
+## The prompt
+
+```
+node <skill>/scripts/record.mjs . --json
+```
+
+Then work the list, and record the actual outcome of each. Do not tick a box you did not test.
+
+- [ ] `total-recall plugin info <id>` reports no errors and no warnings.
+- [ ] Every surface the function needs is declared, and nothing unused.
+- [ ] Every operation has typed arguments and an effect.
+- [ ] `--json` works on every subcommand; failures exit non-zero; `--help` works without credentials.
+- [ ] No secret value appears in `argv`, stdout, stderr, a log or the card state.
+- [ ] The card declares exactly one element of kind `card`, and no `card_layout`.
+- [ ] Every value on the card came from a command; failures render as failures; unknown values render an em dash.
+- [ ] The card renders on the real dark dashboard at 360, 768 and 1280 px with no horizontal overflow.
+- [ ] Every state renders: credential present, missing, provider unreachable, rejected call, empty, stale.
+- [ ] The suite passes — per-subcommand unit tests including failure paths, a manifest test, a secrets test.
+- [ ] No seeded value, placeholder or example default survives anywhere in the plugin.
+- [ ] If a scaffold exists: it runs with `TOTAL_RECALL_BIN` unset, and its tests fail if it spawns a process.
+
+## Then, honestly
+
+Bring `README.md` to describe the plugin **as it actually is**:
+
+- what it does, in its own words
+- the real commands
+- where credentials come from
+- **anything still outstanding**, stated plainly
+
+No claim of a capability the plugin does not have. A stale warning about a fixed bug is itself a defect: one plugin's README described two reporting bugs as unfixed long after both were repaired and verified.
+
+## Correct means
+
+Every claim in the report is backed by a command you ran, and anything you could not verify is named as unverified rather than omitted.
+
+## Check
+
+A second reader can reproduce every claim from the report alone.

package/scaffold/.agent/skills/plugin/references/anti-patterns.md

@@ -0,0 +1,123 @@
+# Anti-patterns
+
+Every entry below was observed in a real plugin in this ecosystem, with the evidence. They are the failure modes this recipe exists to prevent. Each is a rejection, not a preference.
+
+---
+
+## Fabrication
+
+**Seeded readings.** A card constructor held a literal hostname, uptime, load average and `usedPercent: 99.1`, with the comment `// Retain fallback telemetry`. A host at 99.1% memory is in distress; this was a false alarm, and one machine's hostname shipped to every node.
+
+**Invented API results.** A card's fallback branch fabricated `cs_live_…` session ids, `pi_…` intent ids, a payment URL and a latency of "42ms" when `host.run` was unavailable. That branch was not a degraded mode; it was a mock payment terminal.
+
+**Hard-coded claims.** A header rendered `Stripe API (Live Secret)` and `HMAC-SHA256 Verified` with no command behind either. A merchant with no key and no webhook secret saw an identical card.
+
+**Fixed text where a command belongs.** `card_face.metrics` held literal strings such as `ONLINE`. The validator warns on it; the card must never carry it.
+
+> **Rule.** A value appears only if a command or the host returned it. If a source fails, show the failure and when it was last attempted.
+
+## Reassuring defaults
+
+The single most damaging pattern found.
+
+- A card read `data.worktree.unstaged`, `data.synced` and `data.upstream.status` — **none of which the command returns**. Every value fell through to its default.
+- The defaults were `'Up to date'` and `'Synced'`.
+- Therefore a repository with **three unpushed commits rendered as "Up to date."**
+
+Related: a missing upstream comparison becoming `unpushedCommits: 0` instead of unknown.
+
+> **Rule.** Unknown renders an em dash with its reason. `0` and `unknown` are different facts, and a reassurance the plugin has not verified is a lie.
+
+## Credential violations
+
+- A scaffolded panel rendered `<input type="password">` for an API key and dispatched `save-token` with the raw value — a second credential store, and a path the key could leak from.
+- A card built three separate key-entry screens.
+- A plugin's error text told the *application's* users to run a Total Recall command.
+
+> **Rule.** One credential path exists in the whole plugin, and it is `total-recall auth secret`. The card reports present or missing, never renders a value, and never collects one.
+
+## Templates
+
+- Core enforced a closed allowlist of seven layouts, so a bespoke arrangement could not be declared even in principle.
+- One engine rendered every card through a shared widget vocabulary. **24 of 34 plugins shared a byte-identical card signature**; Stripe, Domains and Tickets — three unrelated domains — were the same layout.
+- 30 plugins shipped a real bespoke `card.js` that the card face never mounted.
+- The scaffolder generated a stub panel and an empty `DESIGN.md`, which is the mechanism that produced the uniformity.
+
+> **Rule.** No layout vocabulary anywhere. A face that could be dropped onto another plugin is a failed face.
+
+## Invented brands
+
+| Plugin | Invented wordmark | Real identity |
+| --- | --- | --- |
+| Stripe wrapper | `PAYFORGE` | Stripe's own |
+| git-sentinel | `[BLAME//GAME]` | plain descriptive name |
+| system-monitor | `[PULSE//CHECK]` | plain descriptive name |
+
+Two of the three also carried colour values contradicting their own manifest.
+
+> **Rule.** A wrapper of someone else's API keeps that provider's name and brand. A first-party plugin uses a plain descriptive name and its own mark. Never an emoji, never a generic icon.
+
+## Values that break the capability elsewhere
+
+- `const successUrl = "https://example.com/checkout/success"` shipped inside a vendorable plugin. An app scaffolding it would send paying customers to a placeholder domain.
+- Defaults of `2000`, `"General Admission Ticket"` and `"usd"` — the author's examples — travelling into every copy.
+- A domain default of `clean[1] || 'example.com'`.
+
+> **Rule.** Every environment value is the caller's to supply. No placeholder, no author default, no example value in anything a builder might take.
+
+## Host leaks into a scaffold
+
+- A vendored brick shelled out to the `total-recall` binary for every credential read: with `TOTAL_RECALL_BIN=/nonexistent` it failed with `Auth credential read failed`.
+- It shipped `ui/card.js`, whose only data channel is `host.run` — a host that application does not have.
+- **19 of 34 plugins** carry this runtime dependency, and every one of them is vendorable.
+
+> **Rule.** A scaffold runs with Total Recall absent. Its tests must fail if it spawns a process.
+
+## Presentation defects only looking reveals
+
+- `.figure[data-tone]` CSS was defined but the tone was never set on the wrapper, so all four accent borders rendered grey. Dead CSS, invisible to a schema check.
+- A fleet tile showed a **red border beside a green load figure**: severity combined load and memory, but the tile only displayed load, so a memory-driven critical read as a contradiction.
+- A selection outline collided with the severity border, so a critical tile appeared to have a green edge.
+- Bars collapsed to slivers after a layout change, because a three-column grid left no room for the track.
+- **"USD" appeared twice** — as a suffix in the amount field and on the currency button immediately beside it.
+- A long payment URL ran into its copy button at narrow widths.
+
+> **Rule.** Render it, look at it, measure it. A passing schema check is not a design.
+
+## Dark-surface blindness
+
+The dashboard is **dark-only** (`--text-primary: #f1f5f9`, zero `prefers-color-scheme` rules), but cards were authored and verified against a white test page. Light-theme state colours were therefore unreadable in production, including the verdict line.
+
+> **Rule.** Design and verify on the tokens the host actually injects.
+
+## Colour-only severity
+
+Severity conveyed by hue alone, with no word and no value. Indistinguishable under colour blindness and in a screenshot without a legend.
+
+> **Rule.** Every colour is paired with a word.
+
+## Host-derived screens
+
+The host built one screen per CLI subcommand, so every plugin's screens were its command list. That is the template failure at a higher level.
+
+> **Rule.** The plugin defines its screens, ordered by its own tasks, most-used first.
+
+## Stale documentation
+
+A plugin's README described two reporting bugs as unfixed and pointed at a correction tracker. **Both had already been fixed and were verified against hostile input** — a file named `" leading-space.txt"` parses correctly, and a missing upstream yields `null`, not `0`. The stale warning misrepresented a working plugin and sent readers to a dead end.
+
+> **Rule.** Documentation describes the plugin as it is now. A warning that no longer applies is a defect.
+
+## Environments that return confidently wrong data
+
+`cat /proc/meminfo 2>/dev/null | head -4 || vm_stat` **never fell through on macOS**, because `cat missing | head` exits 0. The macOS memory branch was dead code, and the plugin reported a false `100%` where the truth was `58.3%`.
+
+> **Rule.** Test the condition, not the exit status. Verify a computed figure against an independent calculation before trusting it.
+
+## Two definitions of one thing
+
+- **30 of 30 plugin repositories** carried a stale copied `auth` plugin declaring a `yaml` dependency with no `node_modules`, so every secrets and mesh call from a plugin repository crashed.
+- The scaffold held real directory copies of the nine default plugins rather than links, so each drifted independently.
+- Two skills, `plugin` and `plugins`, described the same thing.
+
+> **Rule.** One definition, referenced everywhere. A second copy is a second source of truth, and it will diverge.

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

@@ -0,0 +1,90 @@
+# The card face
+
+Every plugin has a card face. It is the plugin's interface in the Total Recall dashboard, and it is **bespoke owner code**: written by hand, for that one plugin, from that plugin's own function and brand.
+
+There is no template, no layout vocabulary, no widget set, no region list. Core rejects `card_layout` outright. A face that could be dropped onto a different plugin is a failed face.
+
+---
+
+## What the host provides, and nothing more
+
+- a **sandboxed frame** — opaque origin, `default-src 'none'`, `connect-src 'none'`, no dashboard DOM and no storage
+- a frozen **`host`** object whose `run(subcommand, args, options)` is the only channel out
+- the **design tokens** it injects into the frame
+- the **drawer**, which carries settings and credentials so the face stays focused
+
+Everything else — structure, vocabulary, hierarchy, controls, visual language — is yours to design for this plugin and no other.
+
+## The design process
+
+Work in this order, and write the reasoning into `ui/DESIGN.md` **before** writing component code.
+
+1. **Who uses it, and what are they in the middle of doing?** Name the two or three real tasks. A payments operator reconciling a payout is not the same as one hunting a suspicious charge.
+2. **What must be visible without a single click?** That decides the hierarchy. A DNS plugin shows the zone and its records; a telephony plugin shows line state and the active call; a telemetry plugin shows which machine is struggling.
+3. **What is the one primary action, and what is destructive?** A destructive action gets confirmation, and never the visual weight of the obvious next step.
+4. **What is the domain's own vocabulary?** Use it. Amounts, dates and states in the arrangement an accountant expects; peers, routes and reachability for a mesh. Never render a domain as "a list of commands".
+5. **Then choose the arrangement**, and justify it in the plugin's own terms.
+
+`ui/DESIGN.md` carries a real `tokens:` block matching the manifest, and the reasoning above. See the surfaces reference for the token fields.
+
+## Screens
+
+A plugin with several jobs carries them across **screens the operator flips through**. The plugin defines them.
+
+- Order them by the plugin's own tasks, **most-used first**.
+- The first screen answers what the operator opened the card to do.
+- **Never one screen per subcommand.** That is the host's command list wearing a costume, and it is what makes unrelated plugins look alike.
+- Never a screen set the host derives or imposes.
+
+## Rules that make a face real
+
+- **Real data only.** A value appears only if a command or the host returned it. Never a seeded reading, a placeholder, an example default or an `ONLINE` badge. If a source fails, show the failure and when it was last attempted.
+- **Unknown is an em dash with a reason**, never a zero and never a reassuring word. `0 unpushed commits` and `unknown, no upstream configured` are different facts.
+- **Failures are states**, first-class and rendered like any other. Missing credential, unreachable provider, rejected call, stale reading.
+- **A value's driver is named.** If severity combines several measures, say which one drove it, or a red tile beside a green figure reads as a contradiction.
+- **Every declared operation is reachable**, and its effect is visible — a `read` must not look like a `send`.
+- **Destructive actions state their target and require confirmation.**
+- **The card consumes credentials, never collects them.** Report present or missing; never render a value; never render an input that accepts one. Hand over the auth command to run instead.
+- **Tokens only.** No hard-coded hex outside the single `:host` token block. The dashboard is **dark**, so the injected `--text-*`, `--bg-*`, `--border` and `--accent` values are light-on-dark; tune your state colours for that surface and keep them legible.
+- **Wide, not a column.** A narrow column forces vertical stacking, which is what makes different plugins look alike.
+- **Severity never by colour alone** — pair every colour with a word.
+- **Accessible.** Controls at least 44 px, keyboard reachable, visible focus, contrast-checked state colours, `prefers-reduced-motion` respected.
+- **No decoration.** No ambient animation, no emoji as icons, no hardware-skin imitation, no fake equaliser on a plugin that has no audio. Motion only when it reports a state change.
+- **Copy.** No filler words, and no sentence ends with a preposition.
+
+## Shape of the component
+
+```js
+export class ExampleCard extends HTMLElement {
+  get screens() { return [ { id: 'charge', label: 'Charge' }, /* … most-used first */ ] }
+  connectedCallback() { /* attach shadow, render frames with em dashes, then read */ }
+  disconnectedCallback() { /* clear timers; never leave one running */ }
+  async read() { /* host.run(...) → paint; a rejection clears figures and shows the error */ }
+}
+if (!customElements.get('tr-example-card')) customElements.define('tr-example-card', ExampleCard)
+```
+
+- Values are painted **after** a command returns. Before the first read, the frames show em dashes.
+- A failed read **clears** every figure rather than retaining the previous one as though current.
+- Timers are cleared on disconnect.
+
+## Verifying a face
+
+Run `scripts/record.mjs --card` for the mechanical checks, then look at it:
+
+1. Render at **360, 768 and 1280 px**. No horizontal overflow at any width.
+2. Render on the **real dashboard tokens** (dark), not on a white test page. A face that only reads on white is broken in production.
+3. Exercise every state: credential present, credential missing, provider unreachable, call rejected, empty, stale.
+4. Put it beside another plugin's face. If you cannot tell which is which from the layout alone, it is not finished.
+5. Confirm no secret value can reach the DOM in any state.
+
+## What a face must never do
+
+- Never seed a value, a hostname, a reading or a status word.
+- Never show a reassuring default in place of an unknown.
+- Never render a secret, in any state, for any reason.
+- Never collect a credential.
+- Never present a command name as the primary structure.
+- Never derive its screens from the command list.
+- Never style a destructive action as the obvious next step.
+- Never render as a narrow column when width is available.

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

@@ -0,0 +1,120 @@
+# The scaffold
+
+A plugin's capability may be wanted inside a **different application** — someone else's app, which owns the code and ships without Total Recall. The **scaffold** is that capability, extracted so a builder can put it into their application and use it.
+
+The plugin is the reference implementation. The scaffold is what a builder takes so nobody starts from zero.
+
+---
+
+## A scaffold is not a copy of the plugin
+
+Measured against the current ecosystem, vendoring a plugin copies its whole tree, and the result is unusable in an app:
+
+| What a builder receives | Why it fails |
+| --- | --- |
+| the card face | its only data channel is `host.run`, a Total Recall host the app does not have |
+| an auth client that shells out to `total-recall` | the app breaks the moment Total Recall is absent — `Auth credential read failed` |
+| request logic inlined in `argv`-parsing handlers | there is nothing to import; 19 of 34 plugins export only `run` |
+| `https://example.com/checkout/success`, a default amount of `2000` | a real app would send paying customers to a placeholder domain |
+
+The test is not "does it run". It is **"can a builder lay this in without rewriting it?"**
+
+## What a scaffold contains
+
+**The capability, as code the application imports:**
+
+```js
+// capability/index.mjs — exported, importable, host-free
+export async function createCheckoutSession({
+  secretKey,                    // supplied by the caller; never read from a store
+  amount, currency,
+  successUrl, cancelUrl,        // the caller's URLs; never a placeholder
+  productName,
+  fetchImpl = fetch,            // injectable: the app uses its own client, tests run offline
+}) { /* … returns data … */ }
+
+export function verifyWebhookSignature({ payload, signatureHeader, secret }) { /* … */ }
+```
+
+The rules the shape enforces:
+
+- **Explicit parameters.** No `argv`, no `process.env`, no module-level singleton, no ambient credential.
+- **No defaults for environment values.** A missing `successUrl` is the caller's error to fix, never a silent `example.com`.
+- **Injected transport.** The app supplies its own HTTP client; a test needs no network.
+- **Returned data, not printed text.** Printing is the CLI's job.
+- **Thrown errors, never `process.exitCode`.** The application decides how to fail.
+- **No Total Recall.** The capability does not know it exists.
+- **No card, no design tokens, no logo.** There is no dashboard to render them.
+
+**Plus a builder entry point** — `BRICK.md`, short and concrete:
+
+```
+# Checkout capability
+
+Copy `capability/` into your app.
+
+  import { createCheckoutSession } from './capability/index.mjs'
+
+  await createCheckoutSession({
+    secretKey: process.env.STRIPE_SECRET_KEY,   // your own configuration, never ours
+    amount: 2500, currency: 'usd',
+    successUrl: `${origin}/checkout/success`,
+    cancelUrl:  `${origin}/checkout/cancel`,
+    productName: 'General admission',
+  })
+```
+
+It states what to import, what to pass, where credentials come from, and what comes back. Not a description of a CLI.
+
+## What a scaffold never contains
+
+- the card face, `ui/DESIGN.md`, a logo
+- the plugin manifest — a manifest of Total Recall commands, secrets and a card means nothing in an app
+- any call to `total-recall`, `TOTAL_RECALL_BIN`, or an auth store
+- `argv` parsing or `console.log` as its output
+- a placeholder URL, an example default, or the author's own values
+- a message telling the app's users to install another product
+
+## How the plugin presents it
+
+One source, two artifacts, separated by directory and declared in the manifest:
+
+```
+tr-plugin-<id>/
+  capability/        ← the scaffold payload
+    index.mjs
+  cli.mjs            ← the Total Recall entry; parses argv, resolves credentials, calls capability/
+  ui/                ← the face; Total Recall only
+  test/
+```
+
+```json
+"capability": { "entry": "capability/index.mjs", "exports": ["createCheckoutSession", "verifyWebhookSignature"] }
+```
+
+- `capability` present → the plugin is vendorable as a scaffold.
+- `capability` absent → vendoring reports that this plugin has no separable capability, instead of copying a program into the app.
+
+The CLI becomes a **thin adapter**: parse arguments, resolve credentials through auth, call the capability, format the output. The domain logic lives in `capability/` and is exercised by both.
+
+## Verifying a scaffold
+
+- [ ] It runs with `TOTAL_RECALL_BIN` unset and no auth store present.
+- [ ] Every exported function is callable with caller-supplied arguments and an injected transport.
+- [ ] No `total-recall` string is reachable from the payload.
+- [ ] No `example.com`, no author default, no placeholder value.
+- [ ] No `ui/`, no `card.js`, no manifest.
+- [ ] The suite fails if the capability spawns a process — proving standalone operation rather than assuming it.
+- [ ] Vendored into a clean app, its suite passes there.
+
+## Distribution
+
+```json
+"distribution": { "tier": "official", "license": "open" }
+```
+
+`tier`: `core`, `official`, `personal`, `community`. `license`: `open` (vendorable and shareable) or `closed` (an operated service behind a thin client).
+
+Monetized plugins state their model in `monetization` — `model`, `price_cents` or `take_rate_basis_points`, `period`, `license_key_secret`, `checkout_url`. **Never rely on a local license check for protection**: a closed plugin's value lives on the server, not in the client.
+
+A third party publishes with the same manifest and the same conformance checks. A store lists signed, immutable versions and never runs plugin code.