rewritable 0.14.0 → 0.16.0

package/README.md

@@ -79,6 +79,8 @@ Embeds the input file's content as the document's initial state. Supported forma
 
 Output defaults to `<input-basename>.html` in the input's directory. Conversion is deterministic and offline — no API key, no network.
 
+**Import fidelity loop (PDF).** After a PDF import, `rwa` runs an offline **structural fidelity check** (text-coverage + extraction-quality). If it's low *and* a model is reachable (`RWA_OPENROUTER_KEY` set), it **auto-escalates** to `--vision` and keeps the higher-fidelity result — announced on stderr. **Offline-first is preserved:** with no key, a low-fidelity import stays offline, succeeds, and just warns (suggesting `--vision`/`--claude`). Controls: `--no-escalate` (disable the loop), `--target-fidelity <0..1>` (set the bar, default 0.85). *(The deterministic geometry import is unchanged; the loop only measures and, when authorized, escalates. The full picture-level visual judge is a browser-side follow-up.)*
+
 ### `rwa clone <url> [path]`
 
 Clone a public webpage into a self-contained rewritable: fetch the page, extract its main article and title, and bake the content into a fresh container. First-class for **WordPress / ikangai posts** — a blog post becomes an editable, shareable single-file `.html` you can rewrite with `⌘K`.
@@ -261,6 +263,19 @@ rwa host notes.html --url https://host.example --json   # {"id":"…","token":"
 
 This command is **network-bearing** (like `rwa clone` / `rwa publish-site`), so the offline-first rule does not apply to it.
 
+### `rwa intelligence new <role>`
+
+Mint a **droppable intelligence** — a signed `rwa-agent/1` role packaged as a *carrier* rewritable you can drop onto another rewritable to retune its ⌘K editor (intelligence/0.2). It generates a fresh Ed25519 keypair, signs the role, and scaffolds a self-describing `skill-host` carrier. The **private key** is written to a sibling `<name>.key.json`, kept out of the carrier — keep it to publish updates under the same author identity.
+
+```
+rwa intelligence new concise \
+  --prompt "Tighten prose: shorter sentences, fewer hedges, meaning preserved." \
+  --model anthropic/claude-sonnet-4-6 --backend openrouter \
+  --affinity document,presentation
+```
+
+Flags: `--prompt` (required — the role's system prompt), `--description`, `--model` / `--backend` (a *recommended* model offered on activation behind consent — never auto-applied, never carries your key), `--affinity` (comma-separated document kinds; advisory — a mismatch only warns), `--vault` (comma-separated namespaces the role may reach), `--out <path>`, `--force`. Offline; the carrier holds only the public key + signature.
+
 ### `rwa skin <path> <name>`
 
 Pick a **named look** for a rewritable instead of hand-styling it from the blank lens. A skin is one self-contained `<style data-rwa-skin="NAME">` block — system fonts only, no web fonts or remote assets — that the command splices into the **document body**. So it commits with the document, ships inside the exported `.html`, survives sharing, and one in-browser undo (`⌘Z`) reverts it. Five presets ship today: `notion-clean`, `linear-dark`, `editorial-serif`, `stripe-docs`, `terminal-mono` (clean · dark · editorial · docs · terminal).

package/bin/rwa.mjs

@@ -728,6 +728,36 @@ function detectProductKind(fileText) {
     // `rwa skill publish <file.rwa-skill.json> [--url base] [--json]` — publish a SIGNED skill
     // envelope to the marketplace index (POST /skills/publish, I6 §11). The envelope is already
     // signed (no key needed). Online by design; exit 4 labeled `publish_error` (like `publish`).
+    // `rwa intelligence new <role> --prompt "..." [--description ..] [--model id] [--backend name]
+    //  [--affinity kind,kind] [--vault ns,ns] [--out file] [--force]` — I-C (intelligence/0.2 §6):
+    // mint a signed rwa-agent/1 role and scaffold a carrier rewritable (private key → sibling file).
+    if (verb === 'intelligence') {
+      const sub = rest[0];
+      if (sub !== 'new') {
+        process.stderr.write("rwa intelligence: unknown subcommand '" + (sub || '') + "' (try: rwa intelligence new <role> --prompt \"...\")\n");
+        process.exitCode = 1;
+        return;
+      }
+      const subRest = rest.slice(1);
+      const valFlags = ['--prompt', '--description', '--model', '--backend', '--affinity', '--vault', '--out'];
+      const role = subRest.find((a, i) => !a.startsWith('-') && !valFlags.includes(subRest[i - 1]));
+      const g = (n) => getFlag(n, subRest).value;
+      const list = (n) => { const v = g(n); return v ? v.split(',').map(s => s.trim()).filter(Boolean) : []; };
+      try {
+        const { intelligenceNewCmd } = await import('../src/intelligence.mjs');
+        await intelligenceNewCmd({
+          role, prompt: g('--prompt'), description: g('--description'),
+          model: g('--model'), backend: g('--backend'),
+          affinity: list('--affinity'), vault: list('--vault'),
+          outPath: g('--out'), force: subRest.includes('--force') || subRest.includes('-f'),
+        });
+      } catch (e) {
+        process.stderr.write('rwa intelligence: ' + ((e && e.message) || e) + '\n');
+        process.exitCode = (e && e.exitCode) || 1;
+      }
+      return;
+    }
+
     if (verb === 'skill') {
       const sub = rest[0];
       const subRest = rest.slice(1);
@@ -1187,6 +1217,16 @@ function detectProductKind(fileText) {
     const vision = rest.includes('--vision');
     const claude = rest.includes('--claude');
     const trustInput = rest.includes('--trust-input');
+    // Import fidelity loop (PDF): measure the deterministic import + auto-escalate to --vision when
+    // low AND a model is reachable. --no-escalate opts out; --target-fidelity <0..1> sets the bar.
+    const escalate = !rest.includes('--no-escalate');
+    const tfIdx = rest.indexOf('--target-fidelity');
+    const targetFidelity = tfIdx >= 0 ? Number(rest[tfIdx + 1]) : undefined;
+    if (tfIdx >= 0 && (!Number.isFinite(targetFidelity) || targetFidelity < 0 || targetFidelity > 1)) {
+      console.error('rwa import: --target-fidelity must be a number between 0 and 1');
+      process.exitCode = 2;
+      return;
+    }
     // --model and --timeout take a value: find the index, then take the next arg.
     const modelIdx = rest.indexOf('--model');
     const model = modelIdx >= 0 ? rest[modelIdx + 1] : undefined;
@@ -1219,7 +1259,7 @@ function detectProductKind(fileText) {
       process.exitCode = 2;
       return;
     }
-    const positional = rest.filter((a, i) => !a.startsWith('-') && rest[i - 1] !== '--model' && rest[i - 1] !== '--timeout' && rest[i - 1] !== '--kind' && rest[i - 1] !== '--skin');
+    const positional = rest.filter((a, i) => !a.startsWith('-') && rest[i - 1] !== '--model' && rest[i - 1] !== '--timeout' && rest[i - 1] !== '--kind' && rest[i - 1] !== '--skin' && rest[i - 1] !== '--target-fidelity');
     if (verb === 'new') {
       // `rwa new --kind <starter>` selects a built-in starter. Otherwise a bare-word
       // first positional is a TEMPLATE name (clone a data-rwa-template-labeled file
@@ -1238,7 +1278,7 @@ function detectProductKind(fileText) {
         process.exitCode = 2;
         return;
       }
-      await importCmd({ inputPath: positional[0], outPath: positional[1], force, open, vision, claude, trustInput, model, timeoutSec });
+      await importCmd({ inputPath: positional[0], outPath: positional[1], force, open, vision, claude, trustInput, model, timeoutSec, escalate, targetFidelity });
     } else {
       console.error(`rwa: unknown verb "${verb}". Try --help.`);
       process.exitCode = 2;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rewritable",
-  "version": "0.14.0",
+  "version": "0.16.0",
   "description": "CLI for re-writeable: emit and import single-file rwa documents.",
   "type": "module",
   "bin": {

package/seeds/rewritable.html

@@ -2332,7 +2332,8 @@ async function renderActionsModePanel(panel) {
     const isActive = a.role === activeRole;
     const isAdvisor = advisorSet.indexOf(a.role) >= 0;
     const state = isActive ? 'primary' : (isAdvisor ? 'advisor' : '');
-    const meta = (a.verified ? 'verified' : 'unverified') + (state ? ' · ' + state : '');
+    const aff = (a.affinity && a.affinity.length) ? ' · for ' + a.affinity.join('/') : '';
+    const meta = (a.verified ? 'verified' : 'unverified') + (state ? ' · ' + state : '') + aff;
     let btns = '';
     if (a.verified) {
       const r = escRuntimeHtml(a.role);
@@ -2375,14 +2376,16 @@ async function renderActionsModePanel(panel) {
     btn.addEventListener('click', () => runtimeSetMode('skills'));
   });
   panel.querySelectorAll('[data-agent-on]').forEach(btn => btn.addEventListener('click', () => {
-    try { runtimeActivateAgent(btn.getAttribute('data-agent-on')); } // setActive + offer recommended model
+    const role = btn.getAttribute('data-agent-on');
+    try { runtimeActivateAgent(role); const aw = affinityWarning(role); if (aw && typeof setStatus === 'function') setStatus('', aw); } // setActive + offer model; advisory affinity warn (I-D)
     catch (e) { if (typeof setStatus === 'function') setStatus('err', '✗ ' + (e && (e.code || e.message))); }
     renderActionsModePanel(panel);
   }));
   const agentOff = panel.querySelector('[data-agent-off]');
   if (agentOff) agentOff.addEventListener('click', () => { runtimeSetActiveAgent(null); renderActionsModePanel(panel); });
   panel.querySelectorAll('[data-agent-advon]').forEach(btn => btn.addEventListener('click', () => {
-    try { runtimeAddAdvisor(btn.getAttribute('data-agent-advon')); } // I-E: layer an advisory lens
+    const role = btn.getAttribute('data-agent-advon');
+    try { runtimeAddAdvisor(role); const aw = affinityWarning(role); if (aw && typeof setStatus === 'function') setStatus('', aw); } // I-E: layer an advisory lens; I-D affinity warn
     catch (e) { if (typeof setStatus === 'function') setStatus('err', '✗ ' + (e && (e.code || e.message))); }
     renderActionsModePanel(panel);
   }));
@@ -7844,7 +7847,7 @@ function _agAgentsRegion() {
   };
 }
 function runtimeListAgents() {
-  return Array.from(installedAgents.values()).map(a => ({ role: a.role, author_pubkey: a.manifest && a.manifest.author_pubkey, verified: a.verified }));
+  return Array.from(installedAgents.values()).map(a => ({ role: a.role, author_pubkey: a.manifest && a.manifest.author_pubkey, verified: a.verified, affinity: getAffinity(a.envelope) }));
 }
 function runtimeAgentActive() {
   if (!activeAgentRole) return null;
@@ -8166,6 +8169,24 @@ function getRecommendation(envelope) {
   if (typeof e.recommended_backend === 'string' && REC_BACKENDS.includes(e.recommended_backend.trim())) out.backend = e.recommended_backend.trim();
   return (out.model || out.backend) ? out : null;
 }
+// I-D (intelligence/0.2 §6) — advisory kind-affinity. A role may declare an UNSIGNED `affinity`
+// envelope field (the document kinds it is tuned for). Activating/advising it on a mismatched
+// PRODUCT_KIND only WARNS — never blocks (spec §4: affinity is a soft note). Advisory by design.
+function getAffinity(envelope) {
+  const a = envelope && envelope.affinity;
+  if (Array.isArray(a)) return a.filter(x => typeof x === 'string' && x);
+  if (typeof a === 'string' && a) return [a];
+  return [];
+}
+function affinityWarning(role) {
+  const rec = Array.from(installedAgents.values()).find(x => x.role === role);
+  if (!rec) return null;
+  const aff = getAffinity(rec.envelope);
+  if (!aff.length || aff.indexOf(PRODUCT_KIND) >= 0) return null;
+  return '⚠ “' + role + '” is tuned for ' + aff.join('/') + ' documents, but this is a ' + PRODUCT_KIND + ' — applied anyway.';
+}
+window.__rwaGetAffinity = getAffinity;
+window.__rwaAffinityWarning = affinityWarning;
 function applyRecommendation(rec) {
   const r = rec || {};
   const applied = {};

package/src/commands.mjs

@@ -228,7 +228,7 @@ export async function newCmd({ outPath, force, open, kind, templateName, skin })
 
 export { KNOWN_KINDS };
 
-export async function importCmd({ inputPath, outPath, force, open, vision, claude, trustInput, model, timeoutSec }) {
+export async function importCmd({ inputPath, outPath, force, open, vision, claude, trustInput, model, timeoutSec, escalate, targetFidelity }) {
   if (vision && claude) {
     const e = new Error('--vision and --claude are mutually exclusive');
     e.exitCode = 2;
@@ -265,7 +265,31 @@ export async function importCmd({ inputPath, outPath, force, open, vision, claud
     // Buffer (not utf8 string) — docx and pdf are binary, and text formats
     // decode internally inside convert().
     const contents = await fs.readFile(input);
-    ({ html, warnings } = await convert(ext, contents));
+    const conv = await convert(ext, contents);
+    ({ html, warnings } = conv);
+    // Import fidelity loop (PDF) — measure the deterministic import; on a low structural score,
+    // auto-escalate to --vision, but ONLY when a model is reachable (offline-first: a keyless
+    // import stays offline and warns). `--no-escalate` opts out. Design: docs/plans/2026-06-30-…
+    if (ext === 'pdf' && conv.fidelityInput && escalate !== false) {
+      const { measureAndEscalate } = await import('./import-fidelity.mjs');
+      // Resolve the OpenRouter key ONCE so the reachability probe and the actual escalation target
+      // agree (both honor RWA_OPENROUTER_KEY, the project-preferred var, AND OPENROUTER_API_KEY).
+      // convertPdfViaVision otherwise only reads OPENROUTER_API_KEY, so a probe that said "reachable"
+      // on RWA_OPENROUTER_KEY alone would escalate into a guaranteed "key required" throw.
+      const orKey = process.env.RWA_OPENROUTER_KEY || process.env.OPENROUTER_API_KEY;
+      const r = await measureAndEscalate(
+        { structuralInput: conv.fidelityInput, importResult: conv },
+        {
+          threshold: targetFidelity,
+          escalate: escalate !== false,
+          modelReachable: () => !!orKey,
+          visionImport: async () => { console.error('note: import fidelity low — escalating to --vision (openrouter)…'); return convertPdfViaVision(contents, { model, apiKey: orKey }); },
+        },
+      );
+      if (r.note) console.error('note: ' + r.note);
+      html = r.result.html;
+      warnings = r.result.warnings || warnings;
+    }
   }
   for (const w of warnings) console.error(`note: ${w}`);
 

package/src/import-fidelity.mjs

@@ -0,0 +1,131 @@
+// Import fidelity loop — increment 1 (docs/plans/2026-06-30-import-fidelity-loop-design.md).
+// An OFFLINE structural check on a PDF import + auto-escalate UP the ladder (default → --vision)
+// when fidelity is low — gated on offline-first: escalation fires only when a model is reachable;
+// a keyless low-fidelity import stays offline and warns, never touching the network.
+//
+// Increment 1 measures two false-positive-free signals:
+//   - coverage: fraction of source word-tokens present in the imported text (transform fidelity —
+//               catches dropped/mangled content; ~1 for a faithful geometry import).
+//   - garble:   1 − share of replacement (U+FFFD) / control chars in the source (extraction
+//               quality — a PDF with broken font encoding extracts to garbage; the geometry import
+//               is then unfaithful and should escalate to --vision, which reads the rendered glyphs).
+// The graphics/visual signal ("this page is a chart/scan the text import can't reproduce") needs a
+// renderer; it is the browser-side VISUAL JUDGE, a later increment. `density` is returned for
+// callers/future use but deliberately NOT scored here (char-count alone false-positives on short
+// docs) and is not yet surfaced in CLI output.
+//
+// Sensitivity, stated honestly: this is a FLOOR, biased to never over-escalate a good import.
+// coverage uses substring `includes`, so reordered/duplicated text scores ~1.0; garble only counts
+// U+FFFD + control chars, so wrong-encoding glyphs that aren't U+FFFD score ~1.0. The offline
+// trigger therefore reliably fires only on DROPPED text or replacement-char garble — visual/glyph
+// faithfulness is the VLM judge's job, not this metric's.
+
+const DEFAULT_THRESHOLD = 0.85;
+const MIN_CHARS_PER_PAGE = 200; // informational density floor only (not part of the score in inc. 1)
+
+const norm = (s) => String(s == null ? '' : s).replace(/\s+/g, ' ').trim().toLowerCase();
+const stripTags = (h) => String(h == null ? '' : h).replace(/<[^>]*>/g, ' ');
+
+// Count replacement (U+FFFD) + control chars (excluding tab/LF/CR) without embedding literal
+// control bytes in source — a char-code scan, so the file stays clean ASCII.
+function badChars(src) {
+  let bad = 0;
+  for (let i = 0; i < src.length; i++) {
+    const c = src.charCodeAt(i);
+    if (c === 0xFFFD || (c < 0x20 && c !== 9 && c !== 10 && c !== 13)) bad++;
+  }
+  return bad;
+}
+
+/** Pure offline structural score in [0,1] = min(coverage, garble). Returns the components + reasons. */
+export function structuralScore({ sourceText, pages } = {}, importedHtml) {
+  const src = String(sourceText == null ? '' : sourceText);
+  const importText = norm(stripTags(importedHtml));
+
+  // coverage — unique source word-tokens (len>1) present in the imported text
+  const tokens = [...new Set(norm(src).split(' ').filter(t => t.length > 1))];
+  let coverage = 1;
+  if (tokens.length) {
+    let hit = 0;
+    for (const t of tokens) if (importText.includes(t)) hit++;
+    coverage = hit / tokens.length;
+  }
+
+  // garble — replacement + control char share of the source
+  const garble = src.length ? Math.max(0, 1 - badChars(src) / src.length) : 1;
+
+  // density — reported only (graphics-heaviness detection is the deferred visual judge)
+  const pageN = Math.max(1, pages | 0);
+  const density = Math.min(1, src.replace(/\s+/g, '').length / (pageN * MIN_CHARS_PER_PAGE));
+
+  const score = Math.min(coverage, garble);
+  const reasons = [];
+  if (coverage < 0.9) reasons.push('low-coverage');
+  if (garble < 0.9) reasons.push('garbled-text');
+  return { score, coverage, garble, density, reasons };
+}
+
+/**
+ * Per-page structural fidelity for a multipage import. `perPage`: [{ sourceText, html }], where
+ * imported page i aligns 1:1 with source page i (the geometry import preserves page order). Returns
+ * { pages:[{page, score, coverage, garble, reasons}], overall (mean), worst (the lowest page) }.
+ * The per-page strip is what the browser visual judge surfaces so you jump to the bad pages.
+ */
+export function structuralScoreByPage(perPage = []) {
+  const pages = perPage.map((p, i) => ({ page: i + 1, ...structuralScore({ sourceText: p.sourceText, pages: 1 }, p.html) }));
+  const overall = pages.length ? pages.reduce((a, p) => a + p.score, 0) / pages.length : 1;
+  const worst = pages.length ? pages.reduce((w, p) => (p.score < w.score ? p : w)) : null;
+  return { pages, overall, worst };
+}
+
+// The escalate-trigger fidelity: the WORST page when per-page data is present (so one bad page in an
+// otherwise-good doc still escalates — averaging would hide it), else the whole-doc score.
+function measureStructural(structuralInput, importHtml) {
+  if (structuralInput && Array.isArray(structuralInput.perPage) && structuralInput.perPage.length) {
+    const bp = structuralScoreByPage(structuralInput.perPage);
+    return { score: bp.worst.score, coverage: bp.worst.coverage, garble: bp.worst.garble, reasons: bp.worst.reasons, overall: bp.overall, worst: bp.worst, pages: bp.pages };
+  }
+  return structuralScore(structuralInput, importHtml);
+}
+
+/**
+ * Measure the geometry import; if its score is below `threshold` AND escalation is enabled AND a
+ * model is reachable, re-import via the injected `visionImport` and keep the higher-rung result.
+ * Offline-first: with no reachable model, never call the network — keep the deterministic import and
+ * surface a warning `note`. A failed escalation falls back to the deterministic import (loud).
+ *
+ * deps: { threshold=0.85, escalate=true, modelReachable():boolean, visionImport():Promise<importResult> }
+ */
+export async function measureAndEscalate({ structuralInput, importResult }, deps = {}) {
+  const threshold = deps.threshold == null ? DEFAULT_THRESHOLD : deps.threshold;
+  const escalate = deps.escalate !== false; // default on
+  const fidelity = measureStructural(structuralInput, importResult.html);
+
+  if (fidelity.score >= threshold || !escalate) {
+    return { result: importResult, fidelity, escalated: false };
+  }
+
+  const reachable = typeof deps.modelReachable === 'function' ? deps.modelReachable() : false;
+  if (!reachable) {
+    return {
+      result: importResult, fidelity, escalated: false,
+      note: 'low import fidelity (' + fidelity.score.toFixed(2) + (fidelity.reasons.length ? ': ' + fidelity.reasons.join(', ') : '') +
+        ') — set RWA_OPENROUTER_KEY or use --vision/--claude for a higher-fidelity import',
+    };
+  }
+
+  try {
+    const vResult = await deps.visionImport();
+    // Escalation succeeded: keep the higher rung. We do NOT re-score with the same text-only metric
+    // — its blind spot (graphics/garbled glyphs) is exactly why we escalated; the model addresses it.
+    return {
+      result: vResult, escalated: true, baselineFidelity: fidelity,
+      note: 'import fidelity ' + fidelity.score.toFixed(2) + ' — escalated to --vision',
+    };
+  } catch (e) {
+    return {
+      result: importResult, fidelity, escalated: false,
+      note: 'low import fidelity (' + fidelity.score.toFixed(2) + ') — escalation to --vision failed: ' + ((e && e.message) || e),
+    };
+  }
+}

package/src/import.mjs

@@ -264,13 +264,18 @@ async function convertPdf(bytes) {
     throw e;
   }
   const pages = [];
+  const perPage = [];
   let totalText = 0;
+  let sourceText = '';
   for (let p = 1; p <= doc.numPages; p++) {
     const page = await doc.getPage(p);
     const rendered = await renderPdfPage(page, pdfjs.Util, pdfjs.OPS);
     pages.push(rendered.html);
     totalText += rendered.textCount;
+    sourceText += (rendered.text || '') + '\n';
+    perPage.push({ sourceText: rendered.text || '', html: rendered.html }); // for per-page fidelity
   }
+  const pageCount = doc.numPages;
   await doc.destroy().catch(() => {});
 
   if (totalText === 0) {
@@ -281,6 +286,7 @@ async function convertPdf(bytes) {
   return {
     html: `<article class="rwa-pdf">\n${PDF_PAGE_STYLE}\n<div class="rwa-pdf-doc">\n${pages.join('\n')}\n</div>\n</article>`,
     warnings: ['pdf: imported as a geometry-faithful reconstruction (positioned text + rules) — text stays editable but is absolutely positioned'],
+    fidelityInput: { sourceText, pages: pageCount, perPage }, // for the import fidelity loop (import-fidelity.mjs); perPage drives per-page/worst-page scoring
   };
 }
 
@@ -489,5 +495,7 @@ async function renderPdfPage(page, Util, OPS) {
   }
 
   const html = `<div class="rwa-pdf-page" style="width:${pdfNum(vp.width)}px;height:${pdfNum(vp.height)}px">\n${parts.join('\n')}\n</div>`;
-  return { html, textCount };
+  // text: the raw pdf.js-extracted source text (for the import fidelity check — coverage + garble).
+  const text = tc.items.map(i => i.str || '').join(' ');
+  return { html, textCount, text };
 }

package/src/intelligence.mjs

@@ -0,0 +1,79 @@
+// I-C (intelligence/0.2 §6) — `rwa intelligence new <role>`: mint a signed rwa-agent/1 role and
+// scaffold a CARRIER rewritable (a skill-host holding the record + a self-describing card). The
+// carrier ships only the PUBLIC key + signature; the PRIVATE key is written to a sibling .key.json
+// (keep it to publish updates under the same author identity). Offline; reuses the agent canon
+// (skill-manifest) and the seed bootstrap (seed.mjs) — no new wire-type, no canon fork.
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { webcrypto, randomUUID } from 'node:crypto';
+import { SEED_CANDIDATES } from './commands.mjs';
+import { loadSeed, applySeedSubs, kindOverrides, replaceInlineDoc } from './seed.mjs';
+import { agentSigningMessage } from './skill-manifest.mjs';
+
+const ROLE_RE = /^[a-z0-9][a-z0-9_-]{0,63}$/;
+const REC_MODEL_RE = /^[A-Za-z0-9._:\/-]{1,200}$/;
+const REC_BACKENDS = ['openrouter', 'ollama', 'lmstudio', 'atomic', 'bridge', 'bridge-session'];
+const b64 = (u8) => Buffer.from(u8).toString('base64');
+const rel = (p) => path.relative(process.cwd(), p) || p;
+const esc = (s) => String(s == null ? '' : s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+const fail = (msg, code = 2) => { const e = new Error(msg); e.exitCode = code; throw e; };
+
+export async function intelligenceNewCmd(opts = {}) {
+  const role = opts.role, prompt = opts.prompt;
+  if (!role || !ROLE_RE.test(role)) fail('intelligence: <role> must be lowercase a-z0-9_- (≤64, leading alphanumeric)');
+  if (!prompt || typeof prompt !== 'string') fail('intelligence: --prompt "<system prompt>" is required');
+  if (prompt.includes('`') || prompt.includes('${') || /<\/?DOC>/i.test(prompt)) fail('intelligence: --prompt must not contain ` ${ or <DOC>');
+  if (opts.model != null && !REC_MODEL_RE.test(String(opts.model))) fail('intelligence: --model is not a valid model id');
+  if (opts.backend != null && !REC_BACKENDS.includes(String(opts.backend))) fail('intelligence: --backend must be one of ' + REC_BACKENDS.join('/'));
+  const vault = (opts.vault || []).map(v => /^vault:/.test(v) ? v : 'vault:' + v);
+  const affinity = (opts.affinity || []).filter(Boolean);
+
+  // Mint + sign the rwa-agent/1 record. The signature is over `agent` (the canon); the
+  // recommendation/affinity ride OUTSIDE it (unsigned envelope fields, per I-A/I-D).
+  const kp = await webcrypto.subtle.generateKey({ name: 'Ed25519' }, true, ['sign', 'verify']);
+  const author_pubkey = b64(new Uint8Array(await webcrypto.subtle.exportKey('raw', kp.publicKey)));
+  const agent = { author_pubkey, description: opts.description || ('The ' + role + ' role.'), role, system_prompt: prompt, vault_namespace_set: vault, version: 'rwa-agent/1' };
+  const signature = b64(new Uint8Array(await webcrypto.subtle.sign({ name: 'Ed25519' }, kp.privateKey, agentSigningMessage(agent))));
+  const envelope = { agent, signature };
+  if (opts.model) envelope.recommended_model = String(opts.model);
+  if (opts.backend) envelope.recommended_backend = String(opts.backend);
+  if (affinity.length) envelope.affinity = affinity;
+
+  // Scaffold the carrier — a skill-host bootstrap + card + frozen #rwa-agents zone.
+  const out = path.resolve(opts.outPath || ('./' + role + '.intelligence.html'));
+  if (!opts.force) { let exists = false; try { await fs.access(out); exists = true; } catch (_) {} if (exists) fail('intelligence: ' + rel(out) + ' exists (use --force)'); }
+  const seed = await loadSeed(SEED_CANDIDATES);
+  const ov = kindOverrides('skill-host');
+  let result = applySeedSubs(seed, { uuid: randomUUID(), title: 'Intelligence — ' + role, fileMeta: path.basename(out), productKind: 'skill-host', lensPlaceholder: ov.lensPlaceholder, palPlaceholder: ov.palPlaceholder, productHeader: ov.productHeader, lensClickToAnchor: ov.lensClickToAnchor });
+  const zone = '<div data-rwa-frozen id="rwa-agents"><script type="application/rwa-agent+json">' + b64(Buffer.from(JSON.stringify(envelope))) + '</script></div>';
+  result = replaceInlineDoc(result, buildCard({ role, prompt, model: opts.model, backend: opts.backend, affinity, vault }) + '\n' + zone);
+  await fs.writeFile(out, result, 'utf8');
+
+  // The private key — needed to re-sign updates under the same author identity. Sibling file, loud.
+  const fingerprint = Buffer.from(await webcrypto.subtle.digest('SHA-256', Buffer.from(author_pubkey, 'base64'))).toString('hex').slice(0, 16);
+  const keyOut = out.replace(/\.html?$/i, '') + '.key.json';
+  // 0600: the file holds the PRIVATE key — owner read/write only, never world-readable.
+  await fs.writeFile(keyOut, JSON.stringify({
+    role, author_pubkey, fingerprint,
+    private_key_pkcs8_b64: b64(new Uint8Array(await webcrypto.subtle.exportKey('pkcs8', kp.privateKey))),
+    warning: 'SECRET. Keep this to publish updates to this intelligence under the same author identity. Never commit or share it. The carrier .html holds only the public key.',
+  }, null, 2) + '\n', { mode: 0o600 });
+  try { await fs.chmod(keyOut, 0o600); } catch (_) {} // guarantee owner-only even if the file pre-existed (writeFile mode applies only on create; best-effort on non-POSIX)
+
+  console.log('wrote ' + rel(out) + ' (intelligence "' + role + '")');
+  console.log('author ' + fingerprint + ' — private key saved to ' + rel(keyOut) + ' (keep secret; needed to update this intelligence)');
+  return { out, keyOut, fingerprint, envelope };
+}
+
+function buildCard({ role, prompt, model, backend, affinity, vault }) {
+  const recLine = model ? '\n<li><strong>Recommended model:</strong> <code>' + esc(model) + '</code>' + (backend ? ' on <code>' + esc(backend) + '</code>' : '') + ' — offered on activation, behind consent (your session only; key untouched).</li>' : '';
+  const affLine = affinity.length ? '\n<li><strong>Affinity:</strong> ' + esc(affinity.join(', ')) + ' (advisory — a mismatch only warns).</li>' : '';
+  const vaultLine = '\n<li><strong>Vault namespaces:</strong> ' + (vault.length ? esc(vault.join(', ')) : 'none') + '.</li>';
+  return '<article>\n' +
+    '<h1>Intelligence — &ldquo;' + esc(role) + '&rdquo;</h1>\n' +
+    '<p class="lede">A droppable <strong>intelligence</strong> (intelligence/0.2): a signed <code>rwa-agent/1</code> role you can drop onto another rewritable to retune its &#8984;K editor. This file is the carrier — open it, read it, drop it.</p>\n' +
+    '<h2>What it does</h2>\n<p>' + esc(prompt) + '</p>\n' +
+    '<h2>What it carries</h2>\n<ul>\n<li><strong>Role:</strong> <code>' + esc(role) + '</code></li>' + recLine + affLine + vaultLine + '\n</ul>\n' +
+    '<h2>How to use it</h2>\n<p>Drop this file onto another rewritable to install the role (behind the consent dialog), then activate it from the Activity panel&rsquo;s <em>Intelligences</em> section. This carrier is itself a skill-host, so the role is already installed here — try it directly.</p>\n' +
+    '</article>';
+}