rewritable 0.1.0 → 0.5.0

package/src/commands.mjs

@@ -1,17 +1,24 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { spawn } from 'node:child_process';
 import crypto from 'node:crypto';
 
-import { loadSeed, applySeedSubs, replaceInlineDoc } from './seed.mjs';
+import { loadSeed, applySeedSubs, replaceInlineDoc, extractInlineDoc, kindOverrides, KNOWN_KINDS } from './seed.mjs';
+import { skinByName } from './skins.mjs';
+import { resolveBareWord } from './template.mjs';
 import { convert } from './import.mjs';
+import { convertPdfViaVision } from './import-vision.mjs';
+import { convertViaClaudeCli } from './import-claude.mjs';
 
 const here = path.dirname(fileURLToPath(import.meta.url));
 const packageRoot = path.dirname(here);
 
 // Look in the in-package copy first (published case), fall back to the
-// repo-canonical seed (dev case where cli/ sits next to seeds/).
-const SEED_CANDIDATES = [
+// repo-canonical seed (dev case where cli/ sits next to seeds/). Exported so
+// the `rwa edit` instruction path can extract SYSTEM_PROMPTS/TOOL_SCHEMAS
+// from the same seed `rwa new`/`rwa import` use — single source of truth.
+export const SEED_CANDIDATES = [
   path.join(packageRoot, 'seeds', 'rewritable.html'),
   path.join(packageRoot, '..', 'seeds', 'rewritable.html'),
 ];
@@ -53,22 +60,180 @@ function rel(p) {
   return r || p;
 }
 
-export async function newCmd({ outPath, force }) {
-  const out = path.resolve(outPath || './rewritable.html');
+// Parse a single var out of a .env-style file. Minimal — handles KEY=value,
+// surrounding whitespace, optional matched single/double quotes, leading `export`.
+// Skips blank/comment lines. No interpolation, no multiline values.
+async function readEnvKey(name) {
+  if (process.env[name]) return process.env[name];
+  let text;
+  try {
+    text = await fs.readFile(path.join(process.cwd(), '.env'), 'utf8');
+  } catch (_) { return null; }
+  for (const line of text.split('\n')) {
+    const m = line.match(/^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*?)\s*$/);
+    if (!m || m[1] !== name) continue;
+    let v = m[2];
+    if ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'"))) {
+      v = v.slice(1, -1);
+    }
+    return v || null;
+  }
+  return null;
+}
+
+// Validate-and-return a backend name. Returns null for invalid input rather
+// than throwing — pre-fill is best-effort; an unknown value just means the
+// user sees the default backend (openrouter) on first paint.
+function validBackend(v) {
+  return ['openrouter', 'ollama', 'lmstudio', 'bridge'].includes(v) ? v : null;
+}
+
+// Collect URL-param pre-fills from env / ./.env. Returns an object whose keys
+// match the URL params the bootstrap lifts (key, backend, model). Missing or
+// invalid values are omitted; the bootstrap falls back to its defaults.
+async function collectPrefill() {
+  const out = {};
+  const key     = await readEnvKey('OPENROUTER_API_KEY');
+  const backend = validBackend(await readEnvKey('RWA_BACKEND'));
+  const model   = await readEnvKey('RWA_MODEL');
+  if (key)     out.key = key;
+  if (backend) out.backend = backend;
+  if (model)   out.model = model;
+  return out;
+}
+
+function openFile(target, prefill) {
+  // When any prefill is present we open via a file:// URL with the params so
+  // the bootstrap can lift them into sessionStorage on first paint and scrub
+  // the URL bar via history.replaceState. Without any prefill we use the bare
+  // path so the open command is byte-identical to before.
+  let arg;
+  const params = prefill || {};
+  const hasAny = params.key || params.backend || params.model;
+  if (hasAny) {
+    const u = pathToFileURL(target);
+    if (params.key) u.searchParams.set('key', params.key);
+    if (params.backend) u.searchParams.set('backend', params.backend);
+    if (params.model) u.searchParams.set('model', params.model);
+    arg = u.toString();
+  } else {
+    arg = target;
+  }
+  let cmd, args;
+  if (process.platform === 'darwin') {
+    cmd = 'open'; args = [arg];
+  } else if (process.platform === 'win32') {
+    cmd = 'cmd'; args = ['/c', 'start', '""', arg];
+  } else {
+    cmd = 'xdg-open'; args = [arg];
+  }
+  const child = spawn(cmd, args, { detached: true, stdio: 'ignore' });
+  child.on('error', err => {
+    console.error(`note: could not open file (${err.code || err.message})`);
+  });
+  child.unref();
+}
+
+// Open a freshly-written container, lifting env / .env prefills into the
+// file:// URL (key/backend/model) exactly as the new/import open paths do.
+// Exported so `rwa create` can honor --open without duplicating openFile +
+// collectPrefill. (newCmd/importCmd keep their inline blocks unchanged.)
+export async function openWithPrefill(out) {
+  const prefill = await collectPrefill();
+  if (prefill.key) console.error('note: passing OPENROUTER_API_KEY via ?key= URL parameter');
+  if (prefill.backend) console.error(`note: passing RWA_BACKEND=${prefill.backend} via ?backend= URL parameter`);
+  if (prefill.model) console.error(`note: passing RWA_MODEL=${prefill.model} via ?model= URL parameter`);
+  openFile(out, prefill);
+}
+
+export async function newCmd({ outPath, force, open, kind, templateName, skin }) {
+  // Two body sources funnel through one seed-subs path. Default: a built-in
+  // starter (kindOverrides). `templateName` set: clone a data-rwa-template-labeled
+  // file from cwd — pristine seed + the template's INLINE_DOC (label stripped),
+  // fresh UUID. A cloned instance is a document with the template's body (the
+  // template `kind` is a discovery label, not a PRODUCT_KIND).
+  let out, bodyOverride, fromMsg = '';
+  let resolvedKind = kind || 'document';
+  if (templateName) {
+    // Template-first, kind-fallback (design 2026-05-31 §3.2), via the ONE resolver
+    // shared with `rwa create`: a bare word is first a cwd template label to clone;
+    // on a miss, if it names a built-in kind, emit that kind; otherwise error naming
+    // both misses. A user's labeled file thus overrides the built-in starter, and
+    // `rwa new presentation` makes the deck.
+    const frame = await resolveBareWord(templateName, process.cwd());
+    const dated = `./${templateName}-${new Date().toISOString().slice(0, 10)}.html`;
+    if (frame && frame.source === 'template') {
+      if (frame.ambiguous) console.error(`note: multiple "${templateName}" templates in ./; using ${rel(frame.templatePath)} (most recent)`);
+      out = path.resolve(outPath || dated);
+      bodyOverride = frame.body;        // already label-stripped by the resolver
+      resolvedKind = 'document';
+      fromMsg = ` (from template ${rel(frame.templatePath)})`;
+    } else if (frame && frame.source === 'kind') {
+      resolvedKind = frame.kind;
+      out = path.resolve(outPath || dated);
+      // bodyOverride stays unset → kindOverrides(resolvedKind) supplies the body.
+    } else {
+      const e = new Error(`no rwa file in ./ is labeled "${templateName}", and "${templateName}" is not a known kind (${KNOWN_KINDS.join(', ')}). Add data-rwa-template="${templateName}" to a doc's root element to make it a template, or use a known kind.`);
+      e.exitCode = 2;
+      throw e;
+    }
+  } else {
+    out = path.resolve(outPath || './rewritable.html');
+  }
   await ensureWritable(out, force);
   const seed = await loadSeed(SEED_CANDIDATES);
   const fileMeta = path.basename(out);
   const title = titleFromBasename(path.basename(out, path.extname(out)));
-  const result = applySeedSubs(seed, {
+  // R9-minimal: kind defaults to 'document' (current behavior — no overrides
+  // applied, byte-identical to pre-flag emit). For other kinds, kindOverrides
+  // supplies the INLINE_DOC body and lens placeholder; SYSTEM_PROMPT is
+  // intentionally left alone (audit R1).
+  const overrides = kindOverrides(resolvedKind);
+  let result = applySeedSubs(seed, {
     uuid: crypto.randomUUID(),
     title,
     fileMeta,
+    lensPlaceholder:    overrides.lensPlaceholder,
+    palPlaceholder:     overrides.palPlaceholder,
+    productHeader:      overrides.productHeader,
+    productKind:        resolvedKind,                    // audit R1
+    lensClickToAnchor:  overrides.lensClickToAnchor,     // audit R3 scoped
   });
+  let body = bodyOverride != null ? bodyOverride : overrides.body;
+  // --skin: prepend the preset's <style data-rwa-skin> block as the leading child
+  // of INLINE_DOC. Skin is orthogonal to kind (a skinned document/presentation),
+  // and the inject runs AFTER applySeedSubs (the `rwa import` ordering lesson) so
+  // the skin CSS can't false-match a substitution regex. Deterministic, offline,
+  // model-free — the L1 restyle is a later phase. skinByName throws exit-2 on an
+  // unknown name (caught by the bin's outer handler).
+  if (skin) {
+    const { theme } = skinByName(skin);
+    const base = body != null ? body : extractInlineDoc(result);
+    body = theme + '\n' + base;
+  }
+  if (body != null) result = replaceInlineDoc(result, body);
   await fs.writeFile(out, result, 'utf8');
-  console.log(`wrote ${rel(out)}`);
+  // Annotate with the resolved kind (covers both `--kind presentation` and the
+  // bare-word `rwa new presentation` fallback); a template clone reports its source.
+  const kindMsg = resolvedKind !== 'document' ? ` (kind: ${resolvedKind})` : '';
+  console.log(`wrote ${rel(out)}${fromMsg || kindMsg}`);
+  if (open) {
+    const prefill = await collectPrefill();
+    if (prefill.key) console.error('note: passing OPENROUTER_API_KEY via ?key= URL parameter');
+    if (prefill.backend) console.error(`note: passing RWA_BACKEND=${prefill.backend} via ?backend= URL parameter`);
+    if (prefill.model) console.error(`note: passing RWA_MODEL=${prefill.model} via ?model= URL parameter`);
+    openFile(out, prefill);
+  }
 }
 
-export async function importCmd({ inputPath, outPath, force }) {
+export { KNOWN_KINDS };
+
+export async function importCmd({ inputPath, outPath, force, open, vision, claude, trustInput, model, timeoutSec }) {
+  if (vision && claude) {
+    const e = new Error('--vision and --claude are mutually exclusive');
+    e.exitCode = 2;
+    throw e;
+  }
   const input = path.resolve(inputPath);
   const inputDir = path.dirname(input);
   const inputBasename = path.basename(input, path.extname(input));
@@ -76,8 +241,32 @@ export async function importCmd({ inputPath, outPath, force }) {
   await ensureWritable(out, force);
 
   const ext = path.extname(input).toLowerCase().replace(/^\./, '');
-  const contents = await fs.readFile(input, 'utf8');
-  const { html, warnings } = await convert(ext, contents);
+  let html, warnings;
+  if (vision) {
+    if (ext !== 'pdf') {
+      const e = new Error(`--vision is currently only supported for .pdf (got .${ext})`);
+      e.exitCode = 2;
+      throw e;
+    }
+    console.error('note: vision: posting to openrouter…');
+    // Buffer for HTTP base64 encoding.
+    const contents = await fs.readFile(input);
+    ({ html, warnings } = await convertPdfViaVision(contents, { model }));
+  } else if (claude) {
+    if (trustInput) {
+      console.error(`note: claude: --trust-input set — running the agent with bypassPermissions on ${path.basename(input)}. Only safe for files you trust.`);
+    }
+    // Pass the path; the skill reads the file itself via its own tools.
+    // trustInput gates the bypassPermissions agent (see import-claude.mjs); the
+    // consent gate there throws with exitCode 2 when it is absent.
+    const claudeOpts = { trustInput, ...(timeoutSec ? { timeoutMs: timeoutSec * 1000 } : {}) };
+    ({ html, warnings } = await convertViaClaudeCli(input, ext, claudeOpts));
+  } else {
+    // 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));
+  }
   for (const w of warnings) console.error(`note: ${w}`);
 
   const seed = await loadSeed(SEED_CANDIDATES);
@@ -97,4 +286,11 @@ export async function importCmd({ inputPath, outPath, force }) {
   const result = replaceInlineDoc(subbed, html);
   await fs.writeFile(out, result, 'utf8');
   console.log(`wrote ${rel(out)}`);
+  if (open) {
+    const prefill = await collectPrefill();
+    if (prefill.key) console.error('note: passing OPENROUTER_API_KEY via ?key= URL parameter');
+    if (prefill.backend) console.error(`note: passing RWA_BACKEND=${prefill.backend} via ?backend= URL parameter`);
+    if (prefill.model) console.error(`note: passing RWA_MODEL=${prefill.model} via ?model= URL parameter`);
+    openFile(out, prefill);
+  }
 }

package/src/create.mjs

@@ -0,0 +1,256 @@
+// `rwa create <task…>` (and the `draft` alias) — scaffold + agent-fill into a
+// SELF-CONTAINED rewritable in one shot (design 2026-05-31 §4). The task is a CLI
+// INPUT, never a file capability: the CLI bakes the generated content (and any
+// --data) into the INLINE_DOC snapshot, and the emitted file is thereafter an
+// ordinary, dependency-free rewritable. Recurrence = re-run the CLI.
+//
+// Pipeline (§4.6): scaffold in memory → runAgentLoop (authoring) → apply the
+// envelope to a temp file → assertSelfContained → write ONCE atomically. Nothing
+// is written to the destination unless the whole pipeline succeeds, so a failed
+// run never leaves a half-baked file on disk.
+
+import crypto from 'node:crypto';
+import path from 'node:path';
+import { readFile, rm, stat } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { loadSeed, applySeedSubs, replaceInlineDoc, extractInlineDoc, kindOverrides, KNOWN_KINDS } from './seed.mjs';
+import { resolveBareWord } from './template.mjs';
+import { extractFromSeed } from './seed-extract.mjs';
+import { runAgentLoop } from './agent-loop.mjs';
+import { applyPlan, CliError } from './edit.mjs';
+import { assertSelfContained } from './self-contained.mjs';
+import { findFrozenZones } from './apply-edits.mjs';
+import { resolveApiKey, envBaseUrl } from './backend.mjs';
+import { atomicWrite } from './atomic-write.mjs';
+
+// Hard cap on --data baked into the snapshot. The dataset lands inside INLINE_DOC
+// of a single self-contained file the user will ship; an unbounded paste would
+// bloat the artifact and the model context. Over the cap → fail loud (§4.3).
+const DATA_CAP = 200_000;
+
+const VALUE_FLAGS = new Set([
+  '--kind', '--from', '--data', '--out',
+  '--backend', '--model', '--base-url', '--api-key',
+]);
+
+/**
+ * Parse `rwa create` argv into flags + the positional task words. Pure: no IO,
+ * no kind resolution (that is resolveBareWord's job, §4.2 Stage 1). A value
+ * flag's argument is never collected as a task word.
+ *
+ * @param {string[]} argv — args after the `create`/`draft` verb
+ * @returns {{kind:string|null, from:string|null, data:string|null, out:string|null,
+ *            force:boolean, open:boolean,
+ *            backend:{name:string|null, model:string|null, baseUrl:string|null, apiKey:string|null},
+ *            words:string[]}}
+ */
+export function parseCreateArgs(argv) {
+  const get = (name) => {
+    const i = argv.indexOf(name);
+    return i >= 0 ? (argv[i + 1] ?? null) : null;
+  };
+  const words = argv.filter((a, i) => {
+    if (a.startsWith('-')) return false;            // a flag itself
+    if (VALUE_FLAGS.has(argv[i - 1])) return false; // a value-flag's argument
+    return true;
+  });
+  return {
+    kind: get('--kind'),
+    from: get('--from'),
+    data: get('--data'),
+    out:  get('--out'),
+    force: argv.includes('--force') || argv.includes('-f'),
+    open:  argv.includes('--open')  || argv.includes('-o'),
+    backend: {
+      name:    get('--backend'),
+      model:   get('--model'),
+      baseUrl: get('--base-url'),
+      apiKey:  get('--api-key'),
+    },
+    words,
+  };
+}
+
+// The create-only generation contract (design §4.5): output must run with ZERO
+// external runtime dependencies. Appended to whichever per-kind system prompt the
+// resolved frame selects — this is CLI-exclusive framing, never shipped in the
+// seed bytes. assertSelfContained (below) is the code-level tripwire behind it.
+const SELF_CONTAINMENT_DIRECTIVE = `
+
+CRITICAL — the document you produce MUST be fully self-contained and run with NO external runtime dependencies:
+- Do NOT reference any external URL: no <script src=...> to a CDN, no <link href=...> stylesheet, no remote <img>, no @import or url() pointing off-document. Everything is inlined.
+- For any chart/graph/visualization, hand-roll it with inline <svg> or <canvas> + plain JavaScript. Do NOT use D3, Chart.js, or any library.
+- Embed every piece of data directly in the document (e.g. a <script type="application/json"> island or a JS const). Never fetch data at runtime.
+- Produce the COMPLETE document for the request — this is authoring from a starter, so a wholesale replace_document is appropriate.`;
+
+// Mirror of commands.mjs titleFromBasename (kept local — create.mjs is a peer of
+// commands.mjs, not a dependent). Filename → Title Case, with a safe fallback.
+function titleFromBasename(basename) {
+  return basename
+    .replace(/[-_]+/g, ' ')
+    .split(' ')
+    .filter(Boolean)
+    .map(w => w[0].toUpperCase() + w.slice(1))
+    .join(' ') || 'Untitled';
+}
+
+function rel(p, cwd) {
+  const r = path.relative(cwd, p);
+  return r || p;
+}
+
+// Resolve the creation FRAME — kind + scaffold body + the brief words — from the
+// parsed args (design §4.2). --kind wins and disables leading-word detection; an
+// explicit kind keeps the full word list as the brief. Otherwise the leading word
+// is matched template-first via resolveBareWord (the SAME resolver `rwa new` uses,
+// so the two surfaces never diverge), and that word is consumed from the brief.
+// A silent frame (no kind, no template match) defaults to document with the whole
+// word list as the brief — Stage 2 model inference is deferred to v2 (§9.2).
+async function resolveFrame(parsed, cwd) {
+  if (parsed.kind) {
+    if (!KNOWN_KINDS.includes(parsed.kind)) {
+      throw new CliError(1, 'unknown_kind', { kind: parsed.kind, known: KNOWN_KINDS });
+    }
+    return { kind: parsed.kind, scaffoldBody: kindOverrides(parsed.kind).body, briefWords: parsed.words, fromMsg: '' };
+  }
+  const lead = parsed.words[0];
+  const frame = lead ? await resolveBareWord(lead, cwd) : null;
+  if (frame && frame.source === 'template') {
+    return {
+      kind: 'document',                 // a cloned instance is a document
+      scaffoldBody: frame.body,         // already label-stripped by resolveBareWord
+      briefWords: parsed.words.slice(1),
+      fromMsg: ` (from template ${rel(frame.templatePath, cwd)})`,
+    };
+  }
+  if (frame && frame.source === 'kind') {
+    return { kind: frame.kind, scaffoldBody: kindOverrides(frame.kind).body, briefWords: parsed.words.slice(1), fromMsg: '' };
+  }
+  return { kind: 'document', scaffoldBody: null, briefWords: parsed.words, fromMsg: '' };
+}
+
+/**
+ * `rwa create` / `rwa draft`: scaffold a fresh container, drive the agent loop to
+ * author it, validate self-containment, and write ONCE — atomically. The emitted
+ * file is an ordinary self-contained rewritable; the task left no capability in it.
+ *
+ * @param {object} parsed — parseCreateArgs output
+ * @param {object} opts
+ * @param {string[]} opts.seedCandidates — seed search paths (loadSeed order)
+ * @param {string}   [opts.cwd] — base dir for relative paths + template scan
+ * @param {string}   [opts.stdinData] — content for `--data -` (caller drains stdin)
+ * @returns {Promise<{out:string, kind:string, fromMsg:string}>}
+ * @throws {CliError} exit 1 usage / 2 file / 3 envelope / 4 agent
+ */
+export async function createCmd(parsed, { seedCandidates, cwd = process.cwd(), stdinData } = {}) {
+  let { kind, scaffoldBody, briefWords, fromMsg } = await resolveFrame(parsed, cwd);
+
+  // --from: base the artifact on an existing rewritable's editable body. Reuses
+  // the same exit-2 surface (not_found / not_a_rewritable) as the rest of the CLI.
+  if (parsed.from) {
+    const fromPath = path.resolve(cwd, parsed.from);
+    let fromText;
+    try {
+      fromText = await readFile(fromPath, 'utf8');
+    } catch (e) {
+      if (e && e.code === 'ENOENT') throw new CliError(2, 'not_found', { path: fromPath });
+      throw new CliError(2, 'read_error', { path: fromPath, errno: e && e.code, message: e && e.message });
+    }
+    try {
+      scaffoldBody = extractInlineDoc(fromText);
+    } catch {
+      throw new CliError(2, 'not_a_rewritable', { path: fromPath });
+    }
+    fromMsg = ` (from ${rel(fromPath, cwd)})`;
+  }
+
+  // --data: read the dataset to bake into the brief. `-` reads stdin (drained by
+  // the caller). Never fetched at runtime; embedded inline by the agent (§4.3).
+  let dataContent = null;
+  if (parsed.data === '-') {
+    dataContent = stdinData == null ? '' : stdinData;
+  } else if (parsed.data) {
+    const dataPath = path.resolve(cwd, parsed.data);
+    try {
+      dataContent = await readFile(dataPath, 'utf8');
+    } catch (e) {
+      if (e && e.code === 'ENOENT') throw new CliError(2, 'not_found', { path: dataPath });
+      throw new CliError(2, 'read_error', { path: dataPath, errno: e && e.code, message: e && e.message });
+    }
+  }
+  if (dataContent != null && dataContent.length > DATA_CAP) {
+    throw new CliError(1, 'data_too_large', { bytes: dataContent.length, cap: DATA_CAP });
+  }
+
+  // Output path + clobber guard (matches new/import's --force semantics).
+  const dated = `./${kind}-${new Date().toISOString().slice(0, 10)}.html`;
+  const out = path.resolve(cwd, parsed.out || dated);
+  try {
+    await stat(out);
+    if (!parsed.force) throw new CliError(2, 'dest_exists', { path: out });
+  } catch (e) {
+    if (e instanceof CliError) throw e;
+    // ENOENT is the happy path (file doesn't exist yet); anything else is a real
+    // stat error worth surfacing.
+    if (!(e && e.code === 'ENOENT')) throw new CliError(2, 'read_error', { path: out, errno: e && e.code });
+  }
+
+  // Build the scaffold in memory — identical subs flow to newCmd.
+  const seed = await loadSeed(seedCandidates);
+  const overrides = kindOverrides(kind);
+  let scaffold = applySeedSubs(seed, {
+    uuid: crypto.randomUUID(),
+    title: titleFromBasename(path.basename(out, path.extname(out))),
+    fileMeta: path.basename(out),
+    lensPlaceholder:   overrides.lensPlaceholder,
+    palPlaceholder:    overrides.palPlaceholder,
+    productHeader:     overrides.productHeader,
+    productKind:       kind,
+    lensClickToAnchor: overrides.lensClickToAnchor,
+  });
+  const body = scaffoldBody != null ? scaffoldBody : overrides.body;
+  if (body != null) scaffold = replaceInlineDoc(scaffold, body);
+  const scaffoldDoc = extractInlineDoc(scaffold);
+
+  // Backend: flag → env → default. The key is used ONLY for the model call here;
+  // it is never written into the artifact (the file carries content, not creds).
+  const backendName = parsed.backend.name || process.env.RWA_BACKEND || 'openrouter';
+  const backend = {
+    baseUrl: parsed.backend.baseUrl || envBaseUrl(backendName),
+    model:   parsed.backend.model   || process.env.RWA_MODEL || 'google/gemini-3.5-flash',
+    apiKey:  resolveApiKey(backendName, parsed.backend.apiKey),
+  };
+
+  // Per-kind system prompt + the create-only self-containment directive; the brief
+  // carries any --data inline so the agent embeds it (never fetches).
+  const { SYSTEM_PROMPTS, TOOL_SCHEMAS } = extractFromSeed(seed);
+  const systemPrompt = (SYSTEM_PROMPTS[kind] || SYSTEM_PROMPTS.document) + SELF_CONTAINMENT_DIRECTIVE;
+  const frozenZoneNames = findFrozenZones(scaffoldDoc).map(z => z.name);
+  let instruction = briefWords.join(' ').trim() || `Author a complete ${kind} for this document.`;
+  if (dataContent != null) {
+    instruction += `\n\nUse this data — embed it inline in the document, do NOT fetch it at runtime:\n${dataContent}`;
+  }
+
+  let result;
+  try {
+    result = await runAgentLoop({ systemPrompt, toolSchemas: TOOL_SCHEMAS, currentDoc: scaffoldDoc, instruction, frozenZoneNames, backend });
+  } catch (e) {
+    throw new CliError(4, e.subcode || 'agent_error', e.details || { message: e && e.message });
+  }
+
+  // Atomicity (§4.6): apply + validate against a TEMP file, never the destination.
+  // The destination is written exactly once, only after self-containment passes —
+  // so any failure (envelope, frozen-zone, external-ref) leaves --out untouched.
+  const tmp = path.join(tmpdir(), `rwa-create-${crypto.randomUUID()}.html`);
+  try {
+    await atomicWrite(tmp, scaffold);
+    await applyPlan(tmp, result.envelope);                 // throws CliError on envelope/frozen issues
+    const filled = await readFile(tmp, 'utf8');
+    assertSelfContained(extractInlineDoc(filled));         // throws CliError(4) → out untouched
+    await atomicWrite(out, filled);
+  } finally {
+    await rm(tmp, { force: true });
+  }
+
+  return { out, kind, fromMsg };
+}

package/src/doc.mjs

@@ -0,0 +1,69 @@
+// Read-path entry for `rwa doc` — the counterpart to `rwa edit`'s applyPlan.
+// Where applyPlan WRITES the editable body of a rewritable, inspectDoc READS
+// it: it returns the exact LF-canonical text the rwa-edit contract operates
+// on, plus the metadata an agent needs to edit safely (uuid, product kind,
+// frozen-zone names).
+//
+// Error surface mirrors edit.mjs so callers dedupe file-error handling across
+// read and write:
+//   exitCode 2 / subcode: 'not_found', 'read_error', 'not_a_rewritable'
+
+import { readFile } from 'node:fs/promises';
+import { extractInlineDoc } from './seed.mjs';
+import { findFrozenZones } from './apply-edits.mjs';
+import { resolveSelfDescription } from './identity.mjs';
+import { CliError } from './edit.mjs';
+
+// The bootstrap bakes both consts at emit time (cli/src/seed.mjs applySeedSubs).
+// Reading them back is how we recover identity (uuid) and editing framing
+// (kind) without a full HTML parse. Patterns mirror seed.mjs UUID_RE /
+// PRODUCT_KIND_RE and rwa.mjs detectProductKind — keep them in step.
+const UUID_RE = /const DOC_UUID = '([0-9a-f-]{36})';/;
+const PRODUCT_KIND_RE = /const PRODUCT_KIND = '([^']*)';/;
+
+/**
+ * Read a rewritable's editable document body, contract metadata, and the
+ * `self-description/1` projection (the "what is this?" surface, computed from the
+ * bytes — kind/affordances/title/blocks/baseline). The projection applies the
+ * v1.1 precedence (declared > static): a trustworthy embedded #rwa-affordances
+ * declaration (edit-unreachable) wins over the kind-template guess
+ * (`source:"declared"`); otherwise the static kind-derived projection
+ * (`source:"static"`). No `live` block (the CLI executes no JS). See
+ * ./identity.mjs and docs/specs/rwa-self-description-spec.md §3.1.
+ *
+ * @param {string} filePath — path to the target .html
+ * @returns {Promise<{doc: string, uuid: string|null, kind: string, frozenZones: string[], self: object}>}
+ * @throws {CliError} exitCode 2 on file / non-rewritable errors
+ */
+export async function inspectDoc(filePath) {
+  let fileText;
+  try {
+    fileText = await readFile(filePath, 'utf8');
+  } catch (e) {
+    if (e && e.code === 'ENOENT') throw new CliError(2, 'not_found', { path: filePath });
+    throw new CliError(2, 'read_error', { path: filePath, errno: e && e.code, message: e && e.message });
+  }
+
+  // A plain-text or non-rewritable target throws here — the same gate `rwa
+  // edit` uses. Surfacing it as not_a_rewritable gives agents a deterministic
+  // "is this a rewritable?" probe (clean non-zero exit, empty stdout).
+  let doc;
+  try {
+    doc = extractInlineDoc(fileText);
+  } catch (_e) {
+    throw new CliError(2, 'not_a_rewritable', { path: filePath });
+  }
+
+  const uuid = (fileText.match(UUID_RE) || [])[1] || null;
+  // Pre-PRODUCT_KIND containers (and any unknown kind) default to 'document',
+  // matching how the runtime and `rwa edit` resolve SYSTEM_PROMPTS.
+  const kind = (fileText.match(PRODUCT_KIND_RE) || [])[1] || 'document';
+  const frozenZones = findFrozenZones(doc).map(z => z.name);
+  // The self-description/1 projection — "what is this, what can be done with it".
+  // resolveSelfDescription applies the v1.1 precedence (declared > static): a
+  // trustworthy embedded #rwa-affordances declaration (edit-unreachable) wins over
+  // the kind-template guess; otherwise the static kind-derived projection.
+  const self = resolveSelfDescription({ fileText, doc, uuid, kind, frozenZones });
+
+  return { doc, uuid, kind, frozenZones, self };
+}