total-recall-brain 3.31.2 → 3.32.1

package/bin/total-recall.mjs

@@ -88,6 +88,11 @@ const COMMANDS = {
   brain:    'brain.mjs',
   config:   'config.mjs',
   skill:    'skill.mjs',
+  'project-id': 'project-id.mjs',
+  api:      'api.mjs',
+  brief:    'brief.mjs',
+  group:    'group.mjs',
+  groups:   'group.mjs',
   secret:   'secret.mjs',
   secrets:  'secret.mjs',
   help:     'help.mjs',
@@ -167,6 +172,19 @@ async function main() {
 
   const handlerFile = COMMANDS[command];
   if (!handlerFile) {
+    // Any HTTP API route group without a dedicated verb: `total-recall <group> <action> …`
+    try {
+      const { loadApiRoutes } = await import('../src/core/api-routes.mjs');
+      if ((await loadApiRoutes()).some((r) => r.group === command)) {
+        const { default: apiCli } = await import('../src/cli/api.mjs');
+        await apiCli(args);
+        process.exit(process.exitCode ?? 0);
+      }
+    } catch (err) {
+      console.error(`Error: ${err.message}`);
+      process.exit(1);
+    }
+
     // Check if it is a dynamic integration command configured in the VFS
     try {
       const { agentDir, resolveBrainLayer } = await import('../src/core/config.mjs');
@@ -188,7 +206,7 @@ async function main() {
           } else {
             await handler.default(process.argv.slice(3));
           }
-          process.exit(0);
+          return;
         }
       }
 
@@ -208,7 +226,7 @@ async function main() {
           } else {
             await handler.default(process.argv.slice(3));
           }
-          process.exit(0);
+          return;
         }
       }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "total-recall-brain",
-  "version": "3.31.2",
+  "version": "3.32.1",
   "description": "Personal AI system — database-free, SSSS-powered intelligence engine deployable to any POSIX host.",
   "type": "module",
   "workspaces": [
@@ -64,7 +64,7 @@
   "homepage": "https://github.com/gregiteen/total-recall#readme",
   "dependencies": {
     "@simplewebauthn/server": "^13.3.2",
-    "@ssss/cli": "github:gregiteen/ssss#main",
+    "@ssss/cli": "github:gregiteen/ssss#v0.10.1",
     "bcrypt": "^6.0.0",
     "better-sqlite3": "^12.11.1",
     "cookie-parser": "^1.4.7",

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

@@ -39,6 +39,11 @@ An ID is lowercase kebab case, starts with a letter, and is 2–64 characters. `
 - **Agent context:** add `compile: { "generator": "./generator.mjs", "auto": true }` and export `generateContext()` from that file. Only include information useful to the agent; avoid secrets and noisy telemetry.
 - **Memory category:** declare it under `ssss_schemas.categories` using the current manifest schema. Preserve SSSS Markdown and operation-contract writes; do not write vault documents directly.
 
+- **Repo-customized skill:** a layered skill (plugin-owned `core/`, repo-owned files beside it) declares its repo config contract as `core/config.schema.json`, a JSON Schema whose root is an object. Annotate an array with `"x-collection": "<noun>"` (and optionally `"x-key"`, default `name`) to get `<noun> list|add|remove`. An optional `core/detect.mjs` exports `detect({ repoRoot, skillDir })` and returns a proposed config. Users customize the repo layer with `total-recall skill config <id> config set …`, `detect --apply`, or `init`, or with a repo command generated by `total-recall command create <name> --config-for-skill <id>`. Every write validates the whole config and commits a `skill_config` record to the repo's project vault; `config.json` is rebuilt from it. Never tell users to edit `config.json` by hand: `config validate` reports hand edits as drift, and `config import` adopts a pre-existing file. Mark gate-command string fields `"x-command": true`; `skill config <id> check`, `skill status <id>`, and `app verify` confirm each one resolves without running it.
+
+- **App-runtime CLI:** declare `app_cli` in `plugin.json`: `name`, `api: { base_url_env, default_base_url }` (loopback only; operators override it with the env var or `--base-url`), optional `auth: { type: "bearer", token_env }`, and `commands: [{ name, method, path, args }]`. Args are typed (`string|integer|number|boolean`, `choices`, `default`, `required`, `positional`); `{name}` in `path` must be a required arg, other args go to the query (GET/DELETE) or JSON body. `total-recall app cli <plugin> --lang node|python` (or `--adapter flask|nextjs|react|ssss-app`) prints a self-contained file; `--out <file>` writes it. The file runs without Total Recall: exit 0 ok, 1 the app returned an error, 2 usage, 3 unreachable; `--json` prints `{ ok, status, data | error }`. Regenerate after changing the spec; never hand-edit the output.
+- **UI elements:** author each element once as a self-contained custom element: an ES module under the plugin (e.g. `ui/<id>.js`) that imports nothing, calls `customElements.define('<tag>', …)` exactly once, and styles itself only with design-token variables (`var(--color-…)`, `--spacing-…`, `--radius-…`, `--typography-<style>-…`, `--font-family-…`; `--_name` for private ones). No literal colors, not even as `var()` fallbacks. Declare it in `plugin.json` `ui.elements[]`: `id`, `kind` (`panel|form|list|detail|settings|widget`), `tag`, `module`, optional `slot`, typed `props` (set as DOM properties), `events`, the `tokens` it requires and `optional_tokens` it uses with a token fallback; `ui.design_tokens` may point at a neutral default `DESIGN.md`. `total-recall app ui <plugin> --ui web-components|react` (or `--adapter flask|ssss-app|nextjs|react`) with `--tokens <app DESIGN.md>` checks the required tokens and generates `tokens.css`, `elements/<id>.js`, `index.js`, React wrappers (`--typescript` for `.tsx` plus `.d.ts`), and `ui-manifest.json`; `--out <dir>` writes `<dir>/<plugin-id>/`. An app restyles elements by editing its `DESIGN.md` and regenerating; the element files do not change.
+
 ## Validate the actual job
 
 1. Validate `plugin.json` against the installed schema and `total-recall plugin info <id>`.

package/scaffold/.agent/skills/total-recall/SKILL.md

@@ -28,7 +28,7 @@ You MUST actively reference and apply this skill under the following specific ru
 
 ### 1. When the user establishes a rule, preference, or correction
 *   **Trigger**: Whenever the user corrects your behavior, shares a coding style, defines an architectural pattern, or establishes a preference you must remember.
-*   **Action**: Autonomously create a new SSSS v2 memory node under `.agent/memory-vault/` and compile the vault.
+*   **Action**: Save the new rule with `npx total-recall remember` in the appropriate category and scope. The CLI validates the node and compiles the vault.
 
 ### 2. When referencing invariants, preferences, and corrections (Intrinsically Known Rules)
 *   **⚠️ MANDATORY**: The compiled instruction files (like `INSTRUCTIONS.md`, `GEMINI.md`, `AGENTS.md`, etc.) contain the **entirety** of active invariants, preferences, and behavior corrections (rules/directives).
@@ -36,7 +36,7 @@ You MUST actively reference and apply this skill under the following specific ru
 
 ### 3. When searching for complex domain knowledge or general facts
 *   **Trigger**: When you need to retrieve deep factual information (e.g. from the `facts/` category) or conceptual domain structures (e.g. from `concepts/`) that are not present in your active instruction files.
-*   **Action**: Use the semantic/lexical hybrid search engine (via the local `recall` command, or `/api/memory/search/semantic` endpoint) along with regular text search (e.g., grep):
+*   **Action**: Use `npx total-recall recall "<query>"` to search memory. Do not read or grep memory-vault files directly.
      *   **Hybrid Search**: Blends cosine-similarity vector search and lexical density TF-IDF keyword matching using Reciprocal Rank Fusion (RRF). This blends intent-based semantic matching with exact keyword accuracy.
      *   **Hierarchical Parent-Child Search**: Memory node bodies are chunked and indexed as children. The vector store searches both the parent node and child chunks, returning matches based on maximum similarity.
      *   **Regular Text Search**: Use grep to locate exact configurations, literal keys, or symbols.
@@ -58,7 +58,7 @@ You MUST actively reference and apply this skill under the following specific ru
 
 ### 5. When you modify, add, or delete files in the memory vault
 *   **Trigger**: Immediately after performing any memory node writes.
-*   **Action**: Rebuild the instruction shims. If using CLI commands (`npx total-recall remember` / `forget`), recompilation runs automatically in the background (asynchronously via detached subprocesses) to minimize latency. If editing vault files directly, trigger manual compilation by sending a POST request to `/api/vault/compile` or running `npx total-recall compile`.
+*   **Action**: The `remember` and `forget` CLI commands compile the instruction shims automatically. Use `npx total-recall compile` only when a manual rebuild is needed; never edit vault files directly.
 
 ### 5b. When handling ANY credential, API key, or password
 Never invent a new place to keep it. It goes in the encrypted secrets store —
@@ -74,6 +74,24 @@ See **TESTS**. The full suite and the quality gates run only on the Mac Mini —
 never on a laptop or the cloud droplet. A single spec file may run on any mesh node. Builds and installs are fine on any machine; build large apps
 on the Mac Mini.
 
+### 5e. When operating any third-party provider (DNS, registrar, hosting, mail, payments, telephony)
+The user's providers are already integrated: their API keys live in the secrets
+store. "Use the API" for a provider means exactly that.
+1. `npx total-recall secret catalog` — find the provider's key(s) by provider tag.
+2. Call the provider's REST API or CLI with the value read inside your process
+   (never echoed, never in argv). Check the provider's current API docs first.
+3. **Do not** fall back to browser automation when an API exists, and **do not**
+   ask the user for a key the catalog already has. Browser only for flows with
+   no API (e.g. a portal-only compliance form).
+4. Prefer targeted writes over bulk ones: edit one DNS record by id, never
+   replace a whole zone by default; read the current state first and verify after.
+5. If a key is missing, find the service that already uses it (its deployed
+   env), import it with `secret set <key> --stdin`, and record where it lives
+   with `remember fact`.
+6. If the agent host's own permission mode blocks an action category (e.g. DNS
+   changes), say so in one line with the exact setting that allows it. Do not
+   argue repeatedly and do not route around it through another tool.
+
 ### 6. When troubleshooting connections, port blocks, or sync errors
 *   **Trigger**: If the REST server is unreachable, ports are blocked, or the upstream sync tool encounters errors.
 *   **Action**: Refer to the active diagnostics manual within this skill to heal the local runtime.
@@ -338,6 +356,18 @@ curl -H "Authorization: Bearer <YOUR_PAT_TOKEN>" \
 
 ## 🧩 SKILLS MANAGEMENT (`skill` subcommand)
 
+### Initializing a new repository
+
+After initializing a project brain, initialize that repository's own
+`.agent/skills/repo-expert/` from its current code, manifests, tests, and
+runtime configuration. `skill generate-expert --repo <repo>` is a starting
+point; review and trim generated output before use, especially directory trees
+that include runtime data. The local expert must declare `repo_scoped: true`
+and pass an identity check against the current repository. Register it in the
+project brain. The global `repo-expert` remains a repository-agnostic discovery
+method; never deploy another project's expert or synchronize local experts
+across repositories.
+
 Two distinct layers. Confusing them is the usual cause of "my edit disappeared".
 
 | Layer | What it is | Commands |

package/src/cli/api.mjs

@@ -0,0 +1,133 @@
+/**
+ * total-recall api — every HTTP API route as a CLI verb.
+ *
+ *   total-recall api list [group] [--json]
+ *   total-recall api <group> <action> [positional params…] [--data '<json>'] [--query k=v]… [--json]
+ *   total-recall api call <METHOD> </api/path> [--data '<json>'] [--query k=v]…
+ *
+ * Also reachable as `total-recall <group> <action>` for any group that has no
+ * dedicated verb. Talks to the brain server named in config/brain.json.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { loadApiRoutes } from '../core/api-routes.mjs';
+import { detectProjectBrain, getGlobalBrainDir } from './agent-dir.mjs';
+
+function brainConnection() {
+  const dirs = [detectProjectBrain(process.cwd())?.brainDir, getGlobalBrainDir()].filter(Boolean);
+  for (const d of dirs) {
+    try {
+      const c = JSON.parse(fs.readFileSync(path.join(d, 'config', 'brain.json'), 'utf8'));
+      if (c.url) return { url: process.env.TR_BRAIN || c.url, token: process.env.TR_PAT || c.token };
+    } catch {
+      /* try next */
+    }
+  }
+  return { url: process.env.TR_BRAIN || 'http://localhost:3000', token: process.env.TR_PAT };
+}
+
+function parse(argv) {
+  const out = { pos: [], query: {}, data: undefined, json: false, help: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--json') out.json = true;
+    else if (a === '--help' || a === '-h') out.help = true;
+    else if (a === '--data') out.data = argv[++i];
+    else if (a === '--query') {
+      const [k, ...v] = String(argv[++i] ?? '').split('=');
+      if (k) out.query[k] = v.join('=');
+    } else out.pos.push(a);
+  }
+  return out;
+}
+
+async function call(method, routePath, { query, data }) {
+  const { url, token } = brainConnection();
+  const qs = new URLSearchParams(query).toString();
+  const res = await fetch(`${url.replace(/\/$/, '')}${routePath}${qs ? `?${qs}` : ''}`, {
+    method,
+    headers: {
+      ...(token ? { Authorization: `Bearer ${token}` } : {}),
+      ...(data !== undefined ? { 'Content-Type': 'application/json' } : {}),
+    },
+    body: data !== undefined ? data : undefined,
+  });
+  const text = await res.text();
+  let body;
+  try {
+    body = JSON.parse(text);
+  } catch {
+    body = text;
+  }
+  return { status: res.status, ok: res.ok, body };
+}
+
+function printRoutes(routes) {
+  const width = Math.max(...routes.map((r) => `${r.group} ${r.action}`.length), 10);
+  for (const r of routes) {
+    const params = r.params.map((p) => ` <${p}>`).join('');
+    console.log(`  ${`${r.group} ${r.action}${params}`.padEnd(width + 12)} ${r.method.padEnd(6)} ${r.path}`);
+  }
+}
+
+export default async function apiCli(argv = []) {
+  const opts = parse(argv[0] === 'api' ? argv.slice(1) : argv);
+  const routes = await loadApiRoutes();
+  const [first, second, ...rest] = opts.pos;
+
+  if (opts.help || !first || first === 'list') {
+    const group = first === 'list' ? second : null;
+    const shown = group ? routes.filter((r) => r.group === group) : routes;
+    if (opts.json) return console.log(JSON.stringify(shown, null, 2));
+    if (!group && !opts.help && first !== 'list') {
+      console.log('Usage: total-recall api list [group] | api <group> <action> [params] [--data json] [--query k=v] | api call <METHOD> <path>\n');
+    }
+    if (!shown.length) return console.log(`  No routes for group "${group}".`);
+    if (!group) {
+      const groups = [...new Set(routes.map((r) => r.group))];
+      console.log(`  ${routes.length} routes in ${groups.length} groups: ${groups.join(', ')}\n`);
+      if (!opts.help && first !== 'list') return;
+    }
+    return printRoutes(shown);
+  }
+
+  if (first === 'call') {
+    const [method, routePath] = [String(second || '').toUpperCase(), rest[0]];
+    if (!method || !routePath) {
+      console.error('Usage: total-recall api call <METHOD> </api/path> [--data json] [--query k=v]');
+      process.exit(1);
+    }
+    return finish(await call(method, routePath, opts), opts);
+  }
+
+  const group = first;
+  const groupRoutes = routes.filter((r) => r.group === group);
+  if (!groupRoutes.length) {
+    console.error(`Unknown API group "${group}". Run: total-recall api list`);
+    process.exit(1);
+  }
+  if (!second) return printRoutes(groupRoutes);
+  const route = groupRoutes.find((r) => r.action === second);
+  if (!route) {
+    console.error(`No "${second}" action in ${group}. Actions:`);
+    printRoutes(groupRoutes);
+    process.exit(1);
+  }
+  if (rest.length < route.params.length) {
+    console.error(`Missing parameter(s): ${route.params.slice(rest.length).map((p) => `<${p}>`).join(' ')}`);
+    process.exit(1);
+  }
+  let p = route.path;
+  route.params.forEach((name, i) => {
+    p = p.replace(`:${name}`, encodeURIComponent(rest[i]));
+  });
+  return finish(await call(route.method, p, opts), opts);
+}
+
+function finish(r, opts) {
+  console.log(typeof r.body === 'string' ? r.body : JSON.stringify(r.body, null, opts.json ? 0 : 2));
+  if (!r.ok) {
+    console.error(`HTTP ${r.status}`);
+    process.exitCode = 1;
+  }
+}

package/src/cli/app/index.mjs

@@ -8,6 +8,8 @@
  *   app create <dir> --plugin <source> [--adapter <id>] [--name <name>] [--force] [--json]
  *   app upgrade <id> --to <source> [--target <dir>] [--adapter <id>] [--dry-run] [--json]
  *   app verify [--target <dir>] [--json]
+ *   app cli <source> [--lang node|python | --adapter <id>] [--out <file>] [--force] [--json]
+ *   app ui <source> [--ui web-components|react | --adapter <id>] [--tokens <DESIGN.md>] [--typescript] [--out <dir>] [--force] [--json]
  */
 
 import path from 'node:path';
@@ -26,6 +28,10 @@ import {
   AppCreateError
 } from '../../core/app-deploy/standalone.mjs';
 import { verifyApplication } from '../../core/app-deploy/verify.mjs';
+import { resolveCapabilitySource } from '../../core/app-deploy/source.mjs';
+import { generateAppCli, languageForAdapter, APP_CLI_LANGUAGES } from '../../core/app-deploy/runtime-cli.mjs';
+import { generateUiElements, writeUiElements, uiTargetForAdapter, UI_TARGETS } from '../../core/app-deploy/ui-elements.mjs';
+import fs from 'node:fs';
 import {
   IncompatibleAdapterError,
   IncompatibleSsssVersionError,
@@ -73,6 +79,23 @@ Commands:
                             --target <dir>     Target application directory (default: cwd)
                             --json             Output verification report as JSON
 
+  cli <source>              Generate the app's own runtime CLI from the plugin's app_cli spec.
+                            The file needs no Total Recall install at run time.
+                            --lang <lang>      node (ESM script) or python (argparse module)
+                            --adapter <id>     Pick the language from the adapter (flask: python; else node)
+                            --out <file>       Write the file (mode 755) instead of printing it
+                            --force            Replace an existing --out file
+                            --json             Output { language, path, sha256, out } as JSON
+
+  ui <source>               Generate the plugin's UI elements for the app, styled by its DESIGN.md.
+                            --ui <target>      web-components (Flask/Jinja, any HTML) or react (React/Next)
+                            --adapter <id>     Pick the target from the adapter (flask, ssss-app: web-components)
+                            --tokens <file>    The app's DESIGN.md (default: the plugin's own default tokens)
+                            --typescript       React wrappers as .tsx
+                            --out <dir>        Write <dir>/<plugin-id>/ (replaced whole) instead of listing files
+                            --force            Replace a previously generated <dir>/<plugin-id>/
+                            --json             Output { target, files, elements, tokens, warnings, out } as JSON
+
 Exit Codes:
   0   Success
   1   User/argument error or internal failure
@@ -418,7 +441,164 @@ export async function run(argv = []) {
     process.exit(0);
   }
 
-  // 5. APP VERIFY
+  // 5. APP CLI
+  else if (sub === 'cli') {
+    let source = null;
+    let language = null;
+    let adapter = null;
+    let out = null;
+    let force = false;
+    let isJson = false;
+    for (let i = 0; i < rest.length; i++) {
+      const arg = rest[i];
+      if (arg === '--json') isJson = true;
+      else if (arg === '--force') force = true;
+      else if (arg === '--lang' && rest[i + 1]) language = rest[++i];
+      else if (arg === '--adapter' && rest[i + 1]) adapter = rest[++i];
+      else if (arg === '--out' && rest[i + 1]) out = rest[++i];
+      else if (!arg.startsWith('--') && !source) source = arg;
+      else {
+        console.error(`\n❌ Unknown or incomplete option: ${arg}\n`);
+        process.exit(1);
+      }
+    }
+    const report = (message, code) => {
+      if (isJson) console.error(JSON.stringify({ error: message }));
+      else console.error(`\n❌ ${message}\n`);
+      process.exit(code);
+    };
+    if (!source) report('Missing capability source. Usage: total-recall app cli <source> --lang node|python [--out <file>]', 1);
+    if (language && adapter) report('Pass --lang or --adapter, not both', 1);
+    if (!language && !adapter) report(`Pass --lang (${APP_CLI_LANGUAGES.join('|')}) or --adapter <id>`, 1);
+    if (adapter) {
+      try {
+        language = languageForAdapter(adapter);
+      } catch (err) {
+        report(err.message, 3);
+      }
+    }
+
+    let generated;
+    let resolved;
+    try {
+      resolved = await resolveCapabilitySource(source);
+      if (!resolved.manifest.app_cli) throw new Error(`Plugin '${resolved.id}' declares no app_cli`);
+      generated = generateAppCli(resolved.manifest.app_cli, { language, source: { id: resolved.id, version: resolved.version } });
+    } catch (err) {
+      if (err?.message?.startsWith('process.exit(')) throw err;
+      report(err.message, 1);
+    } finally {
+      resolved?.cleanup?.();
+    }
+
+    let written = null;
+    if (out) {
+      written = path.resolve(out);
+      if (fs.existsSync(written) && !force) report(`${written} exists; pass --force to replace it`, 1);
+      try {
+        fs.mkdirSync(path.dirname(written), { recursive: true });
+        const tmp = `${written}.${process.pid}.tmp`;
+        fs.writeFileSync(tmp, generated.content, { mode: generated.mode });
+        fs.chmodSync(tmp, generated.mode);
+        fs.renameSync(tmp, written);
+      } catch (err) {
+        report(`Could not write ${written}: ${err.message}`, 1);
+      }
+    }
+
+    if (isJson) {
+      console.log(JSON.stringify({ language: generated.language, path: generated.path, sha256: generated.sha256, out: written }));
+    } else if (written) {
+      console.log(`✔ Wrote ${generated.language} app CLI '${generated.spec.name}' to ${written} (suggested path: ${generated.path})`);
+    } else {
+      process.stdout.write(generated.content);
+    }
+    process.exit(0);
+  }
+
+  // 6. APP UI
+  else if (sub === 'ui') {
+    let source = null;
+    let target = null;
+    let adapter = null;
+    let tokens = null;
+    let out = null;
+    let typescript = false;
+    let force = false;
+    let isJson = false;
+    for (let i = 0; i < rest.length; i++) {
+      const arg = rest[i];
+      if (arg === '--json') isJson = true;
+      else if (arg === '--force') force = true;
+      else if (arg === '--typescript') typescript = true;
+      else if (arg === '--ui' && rest[i + 1]) target = rest[++i];
+      else if (arg === '--adapter' && rest[i + 1]) adapter = rest[++i];
+      else if (arg === '--tokens' && rest[i + 1]) tokens = rest[++i];
+      else if (arg === '--out' && rest[i + 1]) out = rest[++i];
+      else if (!arg.startsWith('--') && !source) source = arg;
+      else {
+        console.error(`\n❌ Unknown or incomplete option: ${arg}\n`);
+        process.exit(1);
+      }
+    }
+    const report = (message, code) => {
+      if (isJson) console.error(JSON.stringify({ error: message }));
+      else console.error(`\n❌ ${message}\n`);
+      process.exit(code);
+    };
+    if (!source) report('Missing capability source. Usage: total-recall app ui <source> --ui web-components|react [--tokens DESIGN.md] [--out <dir>]', 1);
+    if (target && adapter) report('Pass --ui or --adapter, not both', 1);
+    if (!target && !adapter) report(`Pass --ui (${UI_TARGETS.join('|')}) or --adapter <id>`, 1);
+    if (adapter) {
+      try {
+        target = uiTargetForAdapter(adapter);
+      } catch (err) {
+        report(err.message, 3);
+      }
+    }
+    if (!UI_TARGETS.includes(target)) report(`Unknown --ui '${target}' (known: ${UI_TARGETS.join(', ')})`, 1);
+    if (typescript && target !== 'react') report('--typescript applies to --ui react only', 1);
+    if (tokens && !fs.existsSync(tokens)) report(`Design tokens file not found: ${tokens}`, 1);
+
+    let generated;
+    let resolved;
+    let written = null;
+    try {
+      resolved = await resolveCapabilitySource(source);
+      generated = generateUiElements(resolved.manifest, { pluginDir: resolved.stagedDir, target, tokens, typescript });
+      if (out) written = writeUiElements(generated, out, { force });
+    } catch (err) {
+      if (err?.message?.startsWith('process.exit(')) throw err;
+      report(err.message, 1);
+    } finally {
+      resolved?.cleanup?.();
+    }
+
+    if (isJson) {
+      console.log(JSON.stringify({
+        target: generated.target,
+        plugin: generated.pluginId,
+        files: generated.files.map(({ path: p, sha256 }) => ({ path: p, sha256 })),
+        elements: generated.elements,
+        tokens: generated.tokens,
+        warnings: generated.warnings,
+        out: written
+      }));
+    } else {
+      console.log(written
+        ? `✔ Wrote ${generated.files.length} ${generated.target} file(s) for '${generated.pluginId}' to ${written}`
+        : `${generated.target} files for '${generated.pluginId}' (pass --out <dir> to write them):`);
+      for (const f of generated.files) console.log(`  ${f.path}  ${f.sha256.slice(0, 12)}`);
+      console.log(generated.tokens.source
+        ? `  tokens: ${generated.tokens.source === 'app' ? "the app's DESIGN.md" : "the plugin's default DESIGN.md"}`
+        : '  tokens: none — pass --tokens <DESIGN.md> to check required tokens and emit tokens.css');
+      for (const w of generated.warnings) console.log(`  ⚠ ${w}`);
+      console.log(`\nUse it:\n${generated.usage.replace(/^/gm, '  ')}`);
+    }
+    process.exit(0);
+  }
+
+  // 7. APP VERIFY
   else if (sub === 'verify') {
     let target = process.cwd();
     let isJson = false;