total-recall-brain 3.44.0 → 3.46.0

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

@@ -12,7 +12,7 @@ Measured against the current ecosystem, vendoring a plugin copies its whole tree
 
 | 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 |
+| the native Home | 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 |
@@ -44,7 +44,7 @@ The rules the shape enforces:
 - **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.
+- **Keep dashboard presentation assets in the plugin.** There is no dashboard to render them.
 
 **Plus a builder entry point** — `BRICK.md`, short and concrete:
 
@@ -68,8 +68,8 @@ It states what to import, what to pass, where credentials come from, and what co
 
 ## 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
+- the native Home, `DESIGN.md`, a logo
+- the plugin manifest — a manifest of Total Recall commands, secrets and dashboard UI 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
@@ -103,7 +103,7 @@ The CLI becomes a **thin adapter**: parse arguments, resolve credentials through
 - [ ] 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.
+- [ ] Keep `ui/` and the manifest in the plugin package.
 - [ ] 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.
 

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

@@ -109,19 +109,20 @@ Five-field cron. `command` must be a declared subcommand.
 
 Live behaviour rather than a command. Module keys are lowercase kebab-case.
 
-## UI — the card face
+## UI — native Home
 
 ```json
 "ui": {
-  "design_tokens": "ui/DESIGN.md",
+  "home": "fleet",
+  "design_tokens": "DESIGN.md",
   "elements": [
-    { "id": "card", "kind": "card", "tag": "tr-host-telemetry-card", "module": "ui/card.js",
+    { "id": "fleet", "kind": "panel", "tag": "tr-host-telemetry-home", "module": "ui/home.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).
+Package the owner design and [SSSS page blocks](generative-home.md) alongside the native Home. Additional panels are available by their declared IDs.
 
 ## Deploy
 
@@ -184,6 +185,14 @@ Keys are camelCase and may not contain `password`, `secret`, `apiKey` or `token`
 
 `command` must be a declared `read` subcommand. `refresh_seconds` is 5–86400.
 
+## Startup check — what a session should see when it starts
+
+```json
+"startup_check": { "command": "unmerged", "args": ["--json"], "timeout_ms": 20000 }
+```
+
+Optional. `command` must be a declared `read` subcommand; `args` are at most 8 plain arguments; `timeout_ms` is 1000–30000 (default 15000). `total-recall startup check` and `brief` run it in the session's directory and show its `summary` when `outstanding` is above zero. The command prints one JSON object `{ "ok": true, "outstanding": 0, "summary": "one line: what and where" }`. A failure, a timeout or any other shape is shown as unavailable, never as clean. Declare it only for something that needs attention at the start of work, and keep it fast.
+
 ## Gate — how work reaches your plugin
 
 Every plugin declares this, even one with nothing to claim. Write it by hand from what your plugin actually does.

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

@@ -6,7 +6,7 @@
  * 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|--reuse|--json]
+ *   node record.mjs <pluginDir> [--manifest|--home|--secrets|--scaffold|--reuse|--json]
  *
  * Checks are marked PASS, FAIL or WARN. A WARN is a judgement call the agent
  * must resolve; a FAIL is a rejection.
@@ -17,8 +17,12 @@ import { execFileSync } from 'node:child_process';
 import { pathToFileURL } from 'node:url';
 
 const args = process.argv.slice(2);
+if (args.includes('--card')) {
+  console.error('Legacy plugin cards are retired. Verify the native Home with --home.');
+  process.exit(2);
+}
 const json = args.includes('--json');
-const only = ['--manifest', '--card', '--secrets', '--scaffold', '--reuse'].filter((f) => args.includes(f));
+const only = ['--manifest', '--home', '--secrets', '--scaffold', '--reuse'].filter((f) => args.includes(f));
 const root = path.resolve(args.find((a) => !a.startsWith('-')) || '.');
 const want = (section) => only.length === 0 || only.includes(section);
 
@@ -30,7 +34,6 @@ const record = (section, level, check, detail) => results.push({ section, level,
 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) {
@@ -63,10 +66,18 @@ let manifest = null;
   }
 }
 
-// Validate with the real contract when this skill is inside a Total Recall checkout.
-if (manifest && want('--manifest')) {
-  const loaderPath = path.resolve(import.meta.dirname, '../../../../src/core/plugin-loader.mjs');
-  if (fs.existsSync(loaderPath)) {
+// Use the host that runs block validation when it is given by path.
+if (manifest && (want('--manifest') || want('--home'))) {
+  const binary = process.env.TOTAL_RECALL_BIN;
+  const explicit = binary && path.isAbsolute(binary) && fs.existsSync(binary)
+    ? path.resolve(path.dirname(fs.realpathSync(binary)), '../src/core/plugin-loader.mjs')
+    : null;
+  const loaderPath = [
+    explicit,
+    path.resolve(import.meta.dirname, '../../../../src/core/plugin-loader.mjs'),
+    path.resolve(import.meta.dirname, '../../../../../src/core/plugin-loader.mjs'),
+  ].find(file => file && fs.existsSync(file));
+  if (loaderPath) {
     try {
       const { validatePluginManifest } = await import(pathToFileURL(loaderPath).href);
       const v = validatePluginManifest(manifest);
@@ -81,27 +92,21 @@ if (manifest && want('--manifest')) {
   } else {
     record('manifest', 'WARN', 'contract', 'validator not found; structural checks only');
   }
+}
 
-  // Card declaration
-  const elements = manifest.ui?.elements || [];
-  // One face (kind 'card') plus any number of screens (kind 'panel'); a panel is never the face.
-  const faces = elements.filter((e) => e && e.kind === 'card');
-  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);
+if (manifest && (want('--manifest') || want('--home'))) {
+  const elements = Array.isArray(manifest.ui?.elements) ? manifest.ui.elements : [];
+  const obsolete = ['card', 'card_face', 'card_layout'].filter(field => Object.hasOwn(manifest, field));
+  if (elements.some(element => ['card', 'card-face'].includes(element?.kind))) obsolete.push('ui.elements');
+  for (const file of walk(root).filter(file => /^ui\/(card|card-face)\.(m?js|css)$/.test(file))) obsolete.push(file);
+  record('manifest', obsolete.length ? 'FAIL' : 'PASS', 'native presentation only',
+    obsolete.length ? `Remove legacy declarations or assets: ${obsolete.join(', ')}` : 'No legacy declarations or assets');
+  if (!manifest.ui?.home && manifest.brick !== true && manifest.scaffold !== true) {
+    record('manifest', 'FAIL', 'UI declared', 'Declare a native ui.home.');
   }
+}
 
+if (manifest && want('--manifest')) {
   // Declared effects and typed arguments on the CLI surface.
   for (const sub of manifest.cli?.subcommands || []) {
     if (!['read', 'write', 'destructive', 'send'].includes(sub.effect)) {
@@ -124,6 +129,51 @@ if (manifest && want('--manifest')) {
   }
 }
 
+if (want('--home') && manifest && (manifest.ui?.home || only.includes('--home'))) {
+  const hasAuth = manifest.auth?.plugin === 'auth' && manifest.auth.session_verification === true;
+  record('home', hasAuth ? 'PASS' : 'FAIL', 'Bundled Auth', hasAuth ? 'Host session verification' : 'Declare auth.plugin and auth.session_verification.');
+  const home = manifest.ui?.elements?.find(element => element.id === manifest.ui.home);
+  const files = walk(root);
+  const validHome = home && ['panel', 'form', 'list', 'detail', 'widget'].includes(home.kind) && files.includes(home.module);
+  record('home', validHome ? 'PASS' : 'FAIL', 'Home element', validHome ? home.id : 'Declare a valid native ui.home.');
+  if (validHome) {
+    const source = read(home.module);
+    const seeded = /\b(?:hostname|loadAvg|usedPercent|uptimeSeconds)\s*:\s*(?:["'][^"']+["']|\[\s*\d|\d)/;
+    if (seeded.test(source)) record('home', 'FAIL', 'no seeded values', 'A live reading is initialized with a literal.');
+    const reassurance = /(?:\|\||\?\?)\s*['"](?:Up to date|Synced|Repository Active|ONLINE|Healthy|Connected|All good|OK)['"]/;
+    if (reassurance.test(source)) record('home', 'FAIL', 'no reassuring default', 'An unverified reading defaults to a successful state.');
+    const credentialPanel = home.events?.includes('save-token') && home.props?.view && manifest.secrets?.length === 1;
+    const ownsCredentialStore = manifest.id === 'auth' && hasAuth &&
+      home.events?.includes('auth-inventory') && home.events?.includes('auth-credential-mutate');
+    if (!credentialPanel && !ownsCredentialStore && /type\s*=\s*["']password["']|input\.type\s*=\s*["']password["']/.test(source)) {
+      record('home', 'FAIL', 'credential interface', 'Use shared Auth or a declared host credential panel.');
+    }
+  }
+  const hasDesign = manifest.ui?.design_tokens === 'DESIGN.md' && !!read('DESIGN.md').trim();
+  record('home', hasDesign ? 'PASS' : 'FAIL', 'Owner design', hasDesign ? 'DESIGN.md' : 'Package and declare root DESIGN.md.');
+  const covered = new Set();
+  let pageBlocks = 0;
+  for (const file of files.filter(file => /^ui\/chunks\/[^/]+\.md$/.test(file))) {
+    try {
+      const output = execFileSync(process.env.TOTAL_RECALL_BIN || 'total-recall',
+        ['plugin', 'chunks', 'validate', path.join(root, file), '--plugin-dir', root, '--json'],
+        { cwd: root, encoding: 'utf8', timeout: 15000, stdio: ['ignore', 'pipe', 'pipe'] });
+      const { chunk } = JSON.parse(output);
+      if (chunk.surfaces.includes('page')) {
+        pageBlocks++;
+        for (const operation of chunk.operations || []) covered.add(operation);
+      }
+      record('home', 'PASS', 'SSSS block', chunk.key);
+    } catch (error) {
+      record('home', 'FAIL', 'SSSS block', `${file}: ${String(error.stdout || error.message).trim().slice(0, 500)}`);
+    }
+  }
+  if (!pageBlocks) record('home', 'FAIL', 'Page blocks', 'Home has no validated page blocks.');
+  const missing = (manifest.cli?.subcommands || []).map(operation => operation.name).filter(name => !covered.has(name));
+  if (missing.length) record('home', 'FAIL', 'Operation coverage', missing.join(', '));
+  else if (pageBlocks) record('home', 'PASS', 'Operation coverage', 'All declared operations have page blocks.');
+}
+
 /* ── reuse ───────────────────────────────────────────────────────────────── */
 
 function pluginInventory(command) {
@@ -181,119 +231,6 @@ if (want('--reuse') && manifest) {
   }
 }
 
-/* ── 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) {
@@ -312,21 +249,6 @@ if (want('--secrets') && manifest) {
     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) {

package/scaffold/.agent/skills/plugin/subagents/plugin-reviewer.md

@@ -14,13 +14,13 @@ Do not fix anything. Report only. A report with no violations must say why it is
 
 Work from the [anti-patterns](../references/anti-patterns.md) catalogue. It is the record of every failure actually found in this ecosystem, so it is the highest-yield place to look.
 
-**Fabrication.** Seeded readings, invented API results, hard-coded status claims, fixed text where a command belongs. Grep the card and the CLI for literals that could be a fabricated value: a hostname, a percentage, a latency, a status word, a session id.
+**Fabrication.** Seeded readings, invented API results, hard-coded status claims, fixed text where a command belongs. Grep the Home and the CLI for literals that could be a fabricated value: a hostname, a percentage, a latency, a status word, a session id.
 
-**Reassuring defaults.** A default that reports success, health or cleanliness the plugin has not verified. This is the most damaging pattern found: a card read three fields the command never returns and defaulted to `"Up to date"`, so a repository with three unpushed commits rendered as clean. For every value on the card, trace it to the command field it came from — and prove the field exists in the command's real output.
+**Reassuring defaults.** A default that reports success, health or cleanliness the plugin has not verified. This is the most damaging pattern found: a card read three fields the command never returns and defaulted to `"Up to date"`, so a repository with three unpushed commits rendered as clean. For every value on the Home, trace it to the command field it came from — and prove the field exists in the command's real output.
 
 **Credential violations.** A second store; a secret in `argv`; a secret in a log or stdout; an input that accepts a key; error text telling the user to install another product.
 
-**Templates.** A `card_layout`; a region or widget list; a face that would suit a different plugin; screens derived from the command list rather than the plugin's tasks.
+**Templates.** A shared template or a Home that would suit a different plugin; screens derived from the command list rather than the plugin's tasks.
 
 **Host leaks in a scaffold.** Any `total-recall` reference, `TOTAL_RECALL_BIN`, or auth-store read reachable from `capability/`. Any `ui/` file in the scaffold payload.
 
@@ -34,7 +34,7 @@ Work from the [anti-patterns](../references/anti-patterns.md) catalogue. It is t
 
 1. Run `node ../scripts/record.mjs <path> --json` and read every failure.
 2. `total-recall plugin info <id>` — read the errors and warnings.
-3. For each value the card shows, find the command field behind it. If you cannot, that is a violation.
+3. For each value the Home shows, find the command field behind it. If you cannot, that is a violation.
 4. Read the CLI for `--help` without credentials, `--json` on every subcommand, non-zero exit on failure.
 5. Render the face and look at it. Do not review a face you have not seen.
 6. Read the tests. A test that injects a fake credential path proves logic, not the contract.

package/scaffold/.agent/skills/total-recall/plugins/auth/DESIGN.md

@@ -0,0 +1,76 @@
+---
+version: "1.0"
+name: Auth & Secrets
+description: A pine-green operator console for credentials, registered brains, and Mesh machines.
+colors:
+  primary: "#64e3a4"
+  background: "#101e19"
+  surface: "#192d24"
+  text: "#f2f8f3"
+  muted: "#b1c9ba"
+  outline: "#3f6350"
+  warning: "#f4d18c"
+  danger: "#ffbbb1"
+typography:
+  body:
+    fontFamily: "Outfit, system-ui, sans-serif"
+    fontSize: 1rem
+    lineHeight: 1.5
+  heading:
+    fontFamily: "Outfit, system-ui, sans-serif"
+    fontSize: 1.4rem
+    fontWeight: 700
+  label:
+    fontFamily: "JetBrains Mono, ui-monospace, monospace"
+    fontSize: 0.75rem
+    letterSpacing: 0.05em
+spacing:
+  sm: 0.65rem
+  md: 1rem
+  lg: 1.5rem
+rounded:
+  panel: 0.65rem
+  control: 0.4rem
+components:
+  access-overview:
+    backgroundColor: "{colors.surface}"
+    borderColor: "{colors.outline}"
+    borderWidth: 1px
+    borderStyle: solid
+    rounded: "{rounded.panel}"
+    padding: "{spacing.md}"
+---
+
+# Auth & Secrets
+
+## Overview
+
+Auth Home is an operator inventory. Start with credential names, providers, repository bindings, storage and rotation. Give registered brains, Mesh machines, and sign-in checks their own views.
+
+## Colors
+
+Use deep pine for the workspace and a lighter pine for inset surfaces. Mint identifies a present configuration or a completed audit. Amber flags setup or a finding. Coral marks unavailable checks and failed requests. Accompany every status color with readable text.
+
+## Typography
+
+Use Outfit for headings and body text. Use JetBrains Mono for workflow labels and command syntax. Fall back to the system families on a device without either font.
+
+## Layout
+
+Use a compact heading and section navigation above a searchable table. Keep table headings visible during scrolling. Let the table scroll horizontally at narrow widths. Keep credential values inside the owner’s secure workflows.
+
+## Elevation & Depth
+
+Separate the console with a single outline and inset dividers. Use flat color so a warning keeps its prominence.
+
+## Shapes
+
+Use modestly rounded corners for the console and controls. Keep state labels as plain text.
+
+## Components
+
+Access overview introduces the local configuration and links its block to the native panel. The panel uses the authenticated bridge to refresh state and run a baseline audit. Workflow blocks use headings, short steps and exact local command names. Named component tokens apply to the access overview.
+
+## Do's and Don'ts
+
+Use visible focus, status announcements and touch targets of at least 44 pixels. Keep the interface still. Report a failed or unavailable check in text. Keep sign-in ceremonies and credential entry in the owner workflows.

package/scaffold/.agent/skills/total-recall/plugins/auth/README.md

@@ -18,7 +18,9 @@ Dashboard/step-up/collaboration tokens use HS256 with issuer, purpose-specific a
 
 Before uninstall, auth verifies and preserves encrypted ciphertext outside the brain. Locked, corrupt, plaintext, conflicting or unmigrated legacy credentials abort teardown. No live credential migration is performed by source changes.
 
-The card displays requested results only. The panel performs browser credential creation plus server verification before reporting registration success. Hardware attestation, provider availability and rotation schedules are never fabricated.
+## Auth Home
+
+Open **Auth & Secrets** from the dashboard's Plugins folder to check sign-in setup and run the host baseline. Customize its colors, typography and layout in `DESIGN.md`. The independent SSSS blocks in `ui/chunks/` bind to the owner CLI and can be composed into pages and drawers. Credential entry and one-time outputs stay in the native Auth flows. The account panel uses browser credential creation and server verification to enroll a passkey.
 
 Integration and whole-ecosystem migration remain in progress. Fixture tests do not prove a physical passkey, OAuth provider login or fleet deployment.
 

package/scaffold/.agent/skills/total-recall/plugins/auth/cli.mjs

@@ -294,24 +294,29 @@ async function handleAudit(subArgs, json) {
     return;
   }
   const brain = resolveBrainDir();
-  const webauthnPath = path.join(brain, 'config', 'webauthn.json');
   const findings = [];
 
-  // Check 1: WebAuthn file permissions
-  if (fs.existsSync(webauthnPath)) {
-    try {
-      const stats = fs.statSync(webauthnPath);
-      const mode = (stats.mode & 0o777).toString(8);
-      if (mode !== '600' && mode !== '400') {
-        findings.push({
-          target: 'webauthn.json',
-          severity: 'HIGH',
-          message: `Permissions mode is ${mode}, expected 0600 (owner read/write only)`,
-        });
-      }
-    } catch {
-      // stat check fallback
+  // Check 1: The same canonical passkey state the owner reads and writes.
+  try {
+    const { resolveWebAuthnPath } = await import('./src/webauthn-store.mjs');
+    const { authState } = await import('./src/metadata-state.mjs');
+    await listStoredPasskeys();
+    const { documentPath } = authState(resolveWebAuthnPath(brain));
+    const stats = fs.lstatSync(documentPath, { throwIfNoEntry: false });
+    const mode = stats && (stats.mode & 0o777);
+    if (stats && mode !== 0o600 && mode !== 0o400) {
+      findings.push({
+        target: 'webauthn.json',
+        severity: 'HIGH',
+        message: `Passkey state permissions are ${mode.toString(8)}, expected 0600 or 0400`,
+      });
     }
+  } catch {
+    findings.push({
+      target: 'webauthn.json',
+      severity: 'HIGH',
+      message: 'Could not read or validate the Auth passkey state',
+    });
   }
 
   // Check 2: Session secret entropy

package/scaffold/.agent/skills/total-recall/plugins/auth/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "tr-plugin-auth",
-  "version": "1.2.9",
+  "version": "1.3.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "tr-plugin-auth",
-      "version": "1.2.9",
+      "version": "1.3.0",
       "license": "MIT",
       "dependencies": {
         "@gregiteen/ssss-cli": "0.14.5",
@@ -19,7 +19,7 @@
       },
       "devDependencies": {
         "supertest": "^7.3.1",
-        "total-recall-brain": "3.43.3",
+        "total-recall-brain": "3.45.0",
         "vitest": "^4.1.12"
       }
     },
@@ -6704,9 +6704,9 @@
       }
     },
     "node_modules/total-recall-brain": {
-      "version": "3.43.3",
-      "resolved": "https://registry.npmjs.org/total-recall-brain/-/total-recall-brain-3.43.3.tgz",
-      "integrity": "sha512-yjfPN/BQxEEa+iodyFXQov/6fRt1pZg/7RcmgsbpALwBt6Ki3JJjT3tzArBC7NxHQmXgGYyKnCYId6xe/W2rPg==",
+      "version": "3.45.0",
+      "resolved": "https://registry.npmjs.org/total-recall-brain/-/total-recall-brain-3.45.0.tgz",
+      "integrity": "sha512-HDYfROazZbsLHQsFPnlBcSpe1HL1QEi7JG8x/eNRUI06RxVQsZWl8LwBo2lTWjWRDrKmCy7BUmSXQDuWF3lrEw==",
       "dev": true,
       "license": "MIT",
       "workspaces": [
@@ -6714,7 +6714,7 @@
       ],
       "dependencies": {
         "@simplewebauthn/server": "^13.3.2",
-        "@ssss/cli": "npm:@gregiteen/ssss-cli@0.14.4",
+        "@ssss/cli": "npm:@gregiteen/ssss-cli@0.14.5",
         "bcrypt": "^6.0.0",
         "better-sqlite3": "^12.11.1",
         "cookie-parser": "^1.4.7",

package/scaffold/.agent/skills/total-recall/plugins/auth/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tr-plugin-auth",
-  "version": "1.2.9",
+  "version": "1.3.0",
   "description": "White-label Total Recall auth plugin: Passkey biometric FIDO2 and Google OAuth2 authentication.",
   "type": "module",
   "main": "cli.mjs",
@@ -29,6 +29,7 @@
     "cli.mjs",
     "plugin.json",
     "README.md",
+    "DESIGN.md",
     "src/",
     "scripts/",
     "!src/**/*.spec.mjs",