@natjswenson/devlog 0.13.0 → 0.14.0

package/bin/devlog.js

@@ -393,6 +393,16 @@ async function cmdInit() {
   }
 
   if (await confirmOverwrite('SKILL.md', SKILL_DEST)) {
+    // These are versioned instructions, not personal config/voice/style files.
+    // Install references with the entrypoint so standalone hosts can resolve them.
+    const references = join(PACKAGE_ROOT, 'references');
+    const referenceDest = join(CONFIG_DIR, 'references');
+    mkdirSync(referenceDest, { recursive: true, mode: 0o700 });
+    for (const name of readdirSync(references)) {
+      if (name.endsWith('.md') && statSync(join(references, name)).isFile()) {
+        copyFileSync(join(references, name), join(referenceDest, name));
+      }
+    }
     copyFileSync(SKILL_SRC, SKILL_DEST);
     log.ok(`Installed SKILL.md → ${SKILL_DEST}`);
   } else {
@@ -789,6 +799,79 @@ function cmdAssemblePost(rest) {
   }
 }
 
+// Additive local draft helpers. No config reads, generation, or content writes.
+async function cmdLintGuide(rest) {
+  const { values, positionals } = safeParseArgs({
+    args: rest, options: { voice: { type: 'boolean', default: false } }, allowPositionals: true,
+  });
+  if (positionals.length !== 1) emitJSON({ error: 'missing-arg', message: 'Usage: devlog lint-guide <article> [--voice]' }, 2);
+  try {
+    const { lintGuide } = await import('../lib/guide_draft.mjs');
+    const result = lintGuide(readFileSync(expandHome(positionals[0]), 'utf8'), { voice: values.voice });
+    emitJSON(result, result.ok ? 0 : 1);
+  } catch (e) {
+    emitJSON({ error: e.code || 'guide-lint-failed', message: e.message }, 1);
+  }
+}
+
+async function cmdPrepareGuide(rest) {
+  const { values } = safeParseArgs({
+    args: rest,
+    options: { article: { type: 'string' }, brand: { type: 'string' }, out: { type: 'string' }, cover: { type: 'string' } },
+    allowPositionals: false,
+  });
+  for (const flag of ['article', 'brand', 'out']) {
+    if (!values[flag]) emitJSON({ error: 'missing-flag', message: `prepare-guide requires --${flag}` }, 2);
+  }
+  try {
+    const { prepareGuidePreview } = await import('../lib/guide_draft.mjs');
+    const result = await prepareGuidePreview({
+      articlePath: expandHome(values.article), brandPath: expandHome(values.brand),
+      outDir: expandHome(values.out), coverPath: values.cover ? expandHome(values.cover) : undefined,
+    });
+    emitJSON({ ok: true, ...result });
+  } catch (e) {
+    emitJSON({ error: e.code || 'guide-preview-failed', message: e.message, ...(e.findings ? { findings: e.findings } : {}) }, 1);
+  }
+}
+
+async function cmdComposeArtCover(rest) {
+  const { values } = safeParseArgs({
+    args: rest, options: { spec: { type: 'string' }, out: { type: 'string' } }, allowPositionals: false,
+  });
+  for (const flag of ['spec', 'out']) {
+    if (!values[flag]) emitJSON({ error: 'missing-flag', message: `compose-art-cover requires --${flag}` }, 2);
+  }
+  try {
+    const { composeArtCover } = await import('../lib/compose_art_cover.mjs');
+    const result = await composeArtCover(expandHome(values.spec), expandHome(values.out));
+    emitJSON({ ok: true, ...result });
+  } catch (e) {
+    emitJSON({ error: e.code || 'art-compose-failed', message: e.message }, 1);
+  }
+}
+
+async function cmdPublishGuide(rest) {
+  const { values } = safeParseArgs({
+    args: rest,
+    options: { clone: { type: 'string' }, article: { type: 'string' }, evidence: { type: 'string' }, cover: { type: 'string' } },
+    allowPositionals: false,
+  });
+  for (const flag of ['clone', 'article', 'evidence']) {
+    if (!values[flag]) emitJSON({ error: 'missing-flag', message: `publish-guide requires --${flag}` }, 2);
+  }
+  try {
+    const { publishGuide } = await import('../lib/publish_guide.mjs');
+    const result = await publishGuide({
+      cloneDir: expandHome(values.clone), articlePath: expandHome(values.article),
+      evidencePath: expandHome(values.evidence), coverPath: values.cover ? expandHome(values.cover) : undefined,
+    });
+    emitJSON(result);
+  } catch (e) {
+    emitJSON({ error: e.code || 'guide-publish-failed', message: e.message, ...(e.findings ? { findings: e.findings } : {}) }, 1);
+  }
+}
+
 // ─── backfill-covers list ─────────────────────────────────────────────────────
 function cmdBackfillCovers(rest) {
   const sub = rest[0];
@@ -1257,6 +1340,10 @@ Used by the /devlog skill:
   ${kleur.cyan('npx @natjswenson/devlog scan [--project <key>] [--summary]')}   JSON plan of new releases needing entries
   ${kleur.cyan('npx @natjswenson/devlog lint-post <file> [--voice]')}  Deterministic post-contract check (+ voice rules)
   ${kleur.cyan('npx @natjswenson/devlog assemble-post <draft> --out <dir>')}  Extract the draft's code blocks for the run-it check
+  ${kleur.cyan('devlog lint-guide <article> [--voice]')}  Check a concept draft and its top-of-post handoff
+  ${kleur.cyan('devlog prepare-guide --article <md> --brand <json> --out <new-dir> [--cover <png>]')}  Local reading preview with complete agent payload
+  ${kleur.cyan('devlog compose-art-cover --spec <json> --out <new-dir>')}  Compose local raster art and typography; no AI call or publishing
+  ${kleur.cyan('devlog publish-guide --clone <content-root> --article <md> --evidence <json> [--cover <png>]')}  Validate evidence and publish into clone; no push
   ${kleur.cyan('npx @natjswenson/devlog publish-entry ...')}        Copy a drafted entry into the clone + update manifest (never overwrites)
   ${kleur.cyan('npx @natjswenson/devlog cover-context <project> <slug> --clone <dir>')}  Style guide + reference-image paths for cover composition
   ${kleur.cyan('npx @natjswenson/devlog render-cover <html> --project <key> --slug <s> --out <dir>')}  Rasterize a composed cover to PNG
@@ -1327,6 +1414,18 @@ if (isMain) {
     case 'assemble-post':
       cmdAssemblePost(rest);
       break;
+    case 'lint-guide':
+      cmdLintGuide(rest);
+      break;
+    case 'prepare-guide':
+      cmdPrepareGuide(rest);
+      break;
+    case 'publish-guide':
+      await cmdPublishGuide(rest);
+      break;
+    case 'compose-art-cover':
+      cmdComposeArtCover(rest);
+      break;
     case 'backfill-covers':
       cmdBackfillCovers(rest);
       break;

package/config.example.json

@@ -1,6 +1,7 @@
 {
   "targetRepo": "yourusername/daily-dev-log",
   "branch": "main",
+  "generationMode": "release",
   "gitAuthor": "Your Name",
   "githubUser": "yourusername",
   "voicePath": "~/.claude/ghostwriter/voice",

package/image-style/style-guide.example.md

@@ -165,16 +165,16 @@ site, not a marketing graphic and not a repeated template.
 
 ### Palette
 
-- **Paper** `#F5F0E6` — the canvas background. Flat. No gradient, no vignette, no texture.
-- **Ink** `#181510` — headline, structural rules, the stamp's frame when not orange, most
-  line art.
-- **Dim** `#6E675C` — secondary text: date/meta, captions, dim linework.
-- **Tertiary** `#8A8272` — decorative use only inside the illustration (a faint
-  background element), never body text, never the headline.
-- **Signature** `#E8501F` (orange) — the ONE loud accent. See The accent law below.
-- **Term panel** (only inside a `.term` hero, see above) — background `#141A26`, text
-  `#EFE9DC`, dim text `#8A8478`, hot/verdict line `#FF8A5C`. This quartet never appears
-  outside a `.term` panel.
+<!-- >>> press:palette v0.9.0 sha256:5904c52d4168 GENERATED by @natjswenson/press, do not edit -->
+- **Paper** `#F5F0E6` — Warm cream. Flat — never gradiented, never textured.
+- **Ink** `#181510` — Near-black. Text, headlines, and every structural rule.
+- **Dim** `#6E675C` — Muted secondary text; the serif commentary voice's color.
+- **Accent** `#E8501F` — THE one loud color. Spent once or twice per document, never as decoration.
+- **Ink Mid** `#4A423A` — Mid ink step: a second series, a stacked-bar segment, a bar track.
+- **Ink Faint** `#8A8272` — Decorative only — a faint element inside an illustration. Never body text, never a headline.
+- **Terminal panel** (bg, text, dim, hot, prompt) `#141A26`, `#EFE9DC`, `#8A8478`, `#FF8A5C`, `#1E2738` — the one place the dark palette
+  survives, and only inside a terminal element. Never on paper.
+<!-- <<< press:palette -->
 
 Prefer flat, limited color and solid/line fills over gradients or smooth shading — the
 render is compressed with lossy PNG palette quantization afterward, and gradients band

package/lib/compose_art_cover.mjs

@@ -0,0 +1,144 @@
+// Additive, offline raster-art compositor. Success records rendering, never visual approval.
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import sharp from 'sharp';
+import { chromium } from 'playwright';
+
+const hash = bytes => createHash('sha256').update(bytes).digest('hex');
+const escape = value => value.replace(/[&<>"']/g, c => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]));
+const fail = (code, message) => Object.assign(new Error(message), { code });
+function string(value, field, max, optional = false) {
+  if (optional && value === undefined) return '';
+  if (typeof value !== 'string' || !value.trim() || value.length > max || /[\u0000-\u001f]/.test(value)) {
+    throw fail('ART_SPEC_INVALID', `${field} must be nonempty text of at most ${max} characters without control characters`);
+  }
+  return value;
+}
+function local(value, field, base) {
+  string(value, field, 4096);
+  if (!path.isAbsolute(value) && /^[a-z][a-z0-9+.-]*:/i.test(value)) throw fail('ART_SPEC_INVALID', `${field} must be a local filesystem path`);
+  return path.resolve(base, value);
+}
+async function json(file, field) {
+  const bytes = await readFile(file);
+  try { return { bytes, value: JSON.parse(bytes.toString('utf8')) }; }
+  catch { throw fail('ART_SPEC_INVALID', `${field} must contain valid JSON`); }
+}
+
+/** Schema 1: {schema:1, source, brand, title, kicker?, stand?, fontPath?}.
+ * Paths in the spec resolve against its directory; outDir resolves against cwd.
+ * Output directory must not exist. On failure it may contain partial artifacts,
+ * but never result.json; the compositor never deletes any directory.
+ */
+export async function composeArtCover(specPath, outDir) {
+  try { return await compose(specPath, outDir); }
+  catch (error) {
+    if (error.code?.startsWith('ART_')) throw error;
+    throw fail('ART_COMPOSE_FAILED', `Art cover failed: ${error.message}`);
+  }
+}
+async function compose(specPath, outDir) {
+  const resolvedSpec = path.resolve(string(specPath, 'specPath', 4096));
+  const destination = path.resolve(string(outDir, 'outDir', 4096));
+  const base = path.dirname(resolvedSpec);
+  const { bytes: specBytes, value: spec } = await json(resolvedSpec, 'spec');
+  if (!spec || spec.schema !== 1 || Array.isArray(spec)) throw fail('ART_SPEC_INVALID', 'spec.schema must be 1');
+  const known = new Set(['schema', 'source', 'brand', 'title', 'kicker', 'stand', 'fontPath']);
+  if (Object.keys(spec).some(key => !known.has(key))) throw fail('ART_SPEC_INVALID', 'Unknown spec field; HTML/CSS input is not supported');
+  const title = string(spec.title, 'title', 300);
+  const kicker = string(spec.kicker, 'kicker', 80, true) || 'ENGINEERING FIELD NOTES';
+  const stand = string(spec.stand, 'stand', 180, true);
+  const sourcePath = local(spec.source, 'source', base);
+  const brandPath = local(spec.brand, 'brand', base);
+  const { bytes: brandBytes, value: brand } = await json(brandPath, 'brand');
+  for (const key of ['paper', 'ink', 'dim', 'accent']) {
+    if (!/^#[\da-f]{6}$/i.test(brand?.colors?.[key] ?? '')) throw fail('ART_BRAND_INVALID', `brand.colors.${key} must be a six-digit hex color`);
+  }
+  for (const key of ['display_stack', 'serif_stack', 'mono_stack']) {
+    const value = brand?.fonts?.[key];
+    if (typeof value !== 'string' || !/^[a-z\d ,"'_-]{1,500}$/i.test(value)) throw fail('ART_BRAND_INVALID', `brand.fonts.${key} must be a safe local font stack`);
+  }
+  const stamp = string(brand?.identity?.stamp, 'brand.identity.stamp', 12);
+  const name = string(brand?.identity?.name, 'brand.identity.name', 80);
+  const sourceBytes = await readFile(sourcePath);
+  let metadata, raster;
+  try {
+    metadata = await sharp(sourceBytes, { animated: true, limitInputPixels: 40_000_000 }).metadata();
+    if (!['png', 'jpeg', 'webp'].includes(metadata.format) || (metadata.pages ?? 1) !== 1) throw Error('Only single-frame PNG, JPEG, or WebP artwork is supported');
+    raster = await sharp(sourceBytes, { failOn: 'warning', limitInputPixels: 40_000_000 }).rotate().toColourspace('srgb').png({ palette: false }).toBuffer();
+  } catch (e) { throw fail('ART_SOURCE_INVALID', `Cannot decode source artwork: ${e.message}`); }
+  let fontCss = '', fontInfo = { mode: 'system-stacks', hostDependent: true, stacks: brand.fonts };
+  let display = brand.fonts.display_stack;
+  if (spec.fontPath !== undefined) {
+    const fontPath = local(spec.fontPath, 'fontPath', base);
+    const fontBytes = await readFile(fontPath);
+    if (!fontBytes.length || fontBytes.length > 10_000_000) throw fail('ART_FONT_INVALID', 'Local font must contain 1 to 10000000 bytes');
+    fontCss = `@font-face{font-family:ArtCoverDisplay;src:url(data:font/ttf;base64,${fontBytes.toString('base64')})}`;
+    display = `'ArtCoverDisplay', ${display}`;
+    fontInfo = { mode: 'embedded-display', path: fontPath, sha256: hash(fontBytes), hostDependent: true, fallback: 'Display glyph fallback and serif/mono stacks remain host dependent', stacks: brand.fonts };
+  }
+  const c = brand.colors;
+  const html = `<!DOCTYPE html><html><head><meta charset="utf-8"><meta http-equiv="Content-Security-Policy" content="default-src 'none'; img-src data:; font-src data:; style-src 'unsafe-inline'"><title>${escape(title)}</title><style>
+${fontCss}
+*{box-sizing:border-box}html,body{margin:0;width:1600px;height:900px;background:${c.paper};color:${c.ink}}
+main{position:relative;width:1600px;height:900px;padding:54px 64px;overflow:hidden}
+header{border-top:8px solid ${c.ink};display:flex;align-items:center;gap:20px;padding-top:18px}
+.stamp{font:900 25px ${display};border:3px solid ${c.accent};padding:8px;transform:rotate(-4deg)}
+.kicker,.name,footer{font:16px ${brand.fonts.mono_stack}}.name{margin-left:auto;color:${c.dim}}.kicker{max-width:820px}
+h1{position:absolute;left:64px;top:203px;width:495px;margin:0;font:900 70px/1.02 ${display};letter-spacing:-.03em;overflow-wrap:anywhere}
+.art{position:absolute;left:580px;top:196px;width:970px;height:610px;object-fit:contain}
+.stand{position:absolute;left:66px;top:675px;width:465px;max-height:128px;margin:0;font:italic 26px/1.3 ${brand.fonts.serif_stack};color:${c.dim}}
+footer{position:absolute;left:64px;right:64px;bottom:35px;border-top:2px solid ${c.ink};padding-top:16px;color:${c.dim}}
+</style></head><body><main><header><div class="stamp">${escape(stamp)}</div><div class="kicker">${escape(kicker)}</div><div class="name">${escape(name)}</div></header><h1>${escape(title)}</h1><img class="art" alt="" src="data:image/png;base64,${raster.toString('base64')}"><p class="stand">${escape(stand)}</p><footer>IMPLEMENT IT IN YOUR PROJECT</footer></main></body></html>`;
+  // Exclusive mkdir establishes ownership; no recursive mkdir and no deletion on errors.
+  try { await mkdir(destination); }
+  catch (e) { throw fail(e.code === 'EEXIST' ? 'ART_OUTPUT_EXISTS' : 'ART_OUTPUT_INVALID', `Output must be a new directory with an existing parent: ${destination} (${e.message})`); }
+  let browser, imageBytes, geometry;
+  try {
+    browser = await chromium.launch({ headless: true, timeout: 15000 });
+    const page = await browser.newPage({ viewport: { width: 1600, height: 900 }, deviceScaleFactor: 1, serviceWorkers: 'block' });
+    await page.route('**/*', route => route.abort());
+    await page.setContent(html, { waitUntil: 'load', timeout: 15000 });
+    geometry = await page.evaluate(async hasFont => {
+      await Promise.race([
+        (async () => {
+          if (hasFont) {
+            try { if (!(await document.fonts.load('70px ArtCoverDisplay')).length) throw Error('No matching face'); }
+            catch { throw Error('Embedded display font failed to load'); }
+          }
+          await document.fonts.ready;
+          await Promise.all([...document.images].map(image => image.decode()));
+        })(),
+        new Promise((_, reject) => setTimeout(() => reject(Error('Font/image readiness timed out')), 10000)),
+      ]);
+      if (document.querySelector('header').getBoundingClientRect().bottom > 176) throw Error('Header overflows into the title/art area; shorten the kicker or identity');
+      const heading = document.querySelector('h1');
+      let size = 70;
+      while (heading.getBoundingClientRect().bottom > 645 && size > 54) { size -= 2; heading.style.fontSize = `${size}px`; }
+      if (heading.getBoundingClientRect().bottom > 645) throw Error('Title overflows at minimum 54px; shorten it');
+      const bounds = {};
+      for (const selector of ['h1', '.art', '.stand', '.stamp', '.kicker', '.name', 'footer']) {
+        const el = document.querySelector(selector), r = el.getBoundingClientRect();
+        if (r.left < 0 || r.top < 0 || r.right > 1600 || r.bottom > 900 || el.scrollWidth > el.clientWidth + 1 || (selector === '.stand' && el.scrollHeight > el.clientHeight + 1)) throw Error(`Text or art overflows: ${selector}`);
+        bounds[selector] = { x: r.x, y: r.y, width: r.width, height: r.height };
+      }
+      return { titleFontSize: size, bounds };
+    }, Boolean(spec.fontPath));
+    imageBytes = await page.screenshot({ type: 'png', timeout: 15000 });
+  } catch (e) { throw fail('ART_RENDER_FAILED', `Offline cover render failed: ${e.message}`); }
+  finally { if (browser) await browser.close(); }
+  const cover = await sharp(imageBytes).removeAlpha().toColourspace('srgb').png({ palette: false, compressionLevel: 9 }).toBuffer();
+  const thumbnail = await sharp(cover).resize(320, 180).png({ palette: false }).toBuffer();
+  const artifacts = { 'composition.html': Buffer.from(html), 'cover.png': cover, 'thumbnail.png': thumbnail };
+  for (const [file, bytes] of Object.entries(artifacts)) await writeFile(path.join(destination, file), bytes, { flag: 'wx' });
+  const result = {
+    schema: 1, renderer: 'offline-raster-art-v1', visualReview: 'pending', outputDir: destination,
+    inputs: { spec: { path: resolvedSpec, sha256: hash(specBytes) }, source: { path: sourcePath, sha256: hash(sourceBytes), format: metadata.format, width: metadata.width, height: metadata.height }, brand: { path: brandPath, sha256: hash(brandBytes) }, font: fontInfo },
+    title, geometry, width: 1600, height: 900, palette: false,
+    outputs: Object.fromEntries(Object.entries(artifacts).map(([file, bytes]) => [file, { sha256: hash(bytes), bytes: bytes.length }])),
+  };
+  // Commit marker written last. Absence means this attempt did not complete.
+  await writeFile(path.join(destination, 'result.json'), JSON.stringify(result, null, 2) + '\n', { flag: 'wx' });
+  return result;
+}

package/lib/config_ops.mjs

@@ -29,6 +29,7 @@ export function removeProject(config, key) {
 // Fields settable via `devlog set <field> <value>`. Everything funnels through
 // validateConfig, so a bad value can never be persisted.
 const SETTERS = {
+  generationMode: (c, v) => ({ ...c, generationMode: v }),
   targetRepo: (c, v) => ({ ...c, targetRepo: v }),
   branch: (c, v) => ({ ...c, branch: v }),
   targetDir: (c, v) => (v === '' ? omit(c, 'targetDir') : { ...c, targetDir: v }),

package/lib/core.mjs

@@ -150,6 +150,9 @@ export function validateConfig(config) {
       throw new Error(`voicePath must be a path with no shell metacharacters and no leading dash: got ${JSON.stringify(config.voicePath)}`);
     }
   }
+  if ('generationMode' in config && !['release', 'concept'].includes(config.generationMode)) {
+    throw new Error('generationMode must be release or concept');
+  }
   if ('deepDive' in config) {
     const d = config.deepDive;
     if (!d || typeof d !== 'object' || Array.isArray(d)) throw new Error('deepDive must be an object');

package/lib/guide_draft.mjs

@@ -0,0 +1,134 @@
+// Additive, local-only guide preparation. Never executes article code or publishes.
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import React from 'react';
+import { renderToStaticMarkup } from 'react-dom/server';
+import ReactMarkdown from 'react-markdown';
+import remarkGfm from 'remark-gfm';
+import sharp from 'sharp';
+import { lintPost, parseFrontmatter } from './lint_post.mjs';
+
+const START = '<!-- agent-handoff:start -->';
+const END = '<!-- agent-handoff:end -->';
+const hash = value => createHash('sha256').update(value).digest('hex');
+const escape = value => String(value).replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;').replaceAll('"', '&quot;');
+const fail = (code, message, findings) => Object.assign(new Error(message), { code, ...(findings ? { findings } : {}) });
+
+function handoff(markdown) {
+  const findings = [];
+  const add = (rule, message) => findings.push({ rule, message });
+  if (markdown.split(START).length !== 2 || markdown.split(END).length !== 2) {
+    add('guide-handoff-markers', 'Use exactly one agent-handoff:start and one agent-handoff:end marker.');
+    return { findings, reference: markdown };
+  }
+  const start = markdown.indexOf(START);
+  const end = markdown.indexOf(END);
+  if (end <= start) {
+    add('guide-handoff-order', 'The handoff end marker must follow its start marker.');
+    return { findings, reference: markdown };
+  }
+  const { body } = parseFrontmatter(markdown);
+  if (!body.trimStart().startsWith(START)) add('guide-handoff-position', 'The handoff must be the first body content, before the introduction and Shipped.');
+  const block = markdown.slice(start + START.length, end);
+  const fences = [...block.replaceAll('\r\n', '\n').matchAll(/^```([^\n]*)$/gm)];
+  const match = /^```text\r?\n([\s\S]*?)\r?\n```\s*$/m.exec(block);
+  if (fences.length !== 2 || fences[0]?.[1] !== 'text' || fences[1]?.[1] !== '' || !match || !match[1].trim()) {
+    add('guide-handoff-prompt', 'The handoff must contain exactly one nonempty fenced text prompt.');
+  }
+  return { findings, prompt: match?.[1], reference: markdown.slice(0, start) + markdown.slice(end + END.length) };
+}
+
+// Same result shape as lintPost. Structural checks do not prove semantic quality or review.
+export function lintGuide(markdown, { voice = false } = {}) {
+  const parsed = handoff(markdown);
+  const findings = [...lintPost(parsed.reference.replaceAll('\r\n', '\n'), { voice }).findings, ...parsed.findings];
+  return { ok: findings.length === 0, findings };
+}
+
+function brandCss(tokens) {
+  const fields = { paper: tokens.colors?.paper, ink: tokens.colors?.ink, dim: tokens.colors?.dim, accent: tokens.colors?.accent, hair: tokens.derived?.hair ?? tokens.colors?.ink };
+  for (const [name, value] of Object.entries(fields)) {
+    if (typeof value !== 'string' || !/^(#[a-f\d]{6}|rgba\(\s*\d{1,3},\s*\d{1,3},\s*\d{1,3},\s*(?:0|1|0?\.\d+)\s*\))$/i.test(value)) throw fail('GUIDE_BRAND_INVALID', `Invalid PRESS color: ${name}`);
+  }
+  for (const name of ['display', 'mono', 'serif']) {
+    const value = tokens.fonts?.[`${name}_stack`];
+    if (typeof value !== 'string' || !value.trim() || !/^[a-z\d\s,'"-]+$/i.test(value)) throw fail('GUIDE_BRAND_INVALID', `Invalid PRESS font stack: ${name}`);
+    fields[`font-${name}`] = value;
+  }
+  for (const name of ['stamp', 'name']) if (typeof tokens.identity?.[name] !== 'string' || !tokens.identity[name].trim()) throw fail('GUIDE_BRAND_INVALID', `Missing PRESS identity: ${name}`);
+  return `:root{${Object.entries(fields).map(([key, value]) => `--${key}:${value}`).join(';')}}`;
+}
+
+export async function prepareGuidePreview({ articlePath, outDir, brandPath, coverPath } = {}) {
+  for (const [name, value] of Object.entries({ articlePath, outDir, brandPath })) if (typeof value !== 'string' || !value.trim()) throw fail('GUIDE_ARGUMENT', `${name} is required.`);
+  const markdown = await fs.readFile(articlePath, 'utf8');
+  const lint = lintGuide(markdown);
+  if (!lint.ok) throw fail('GUIDE_LINT', 'Guide failed structural lint.', lint.findings);
+  const { prompt, reference } = handoff(markdown);
+  const payload = `${prompt}\n\n<reference-guide>\n${reference.trim()}\n</reference-guide>\n`;
+  const { data } = parseFrontmatter(markdown.replaceAll('\r\n', '\n'));
+  const { body } = parseFrontmatter(reference);
+  const brandRaw = await fs.readFile(brandPath, 'utf8');
+  let tokens;
+  try { tokens = JSON.parse(brandRaw); } catch { throw fail('GUIDE_BRAND_INVALID', 'PRESS brand file must contain JSON.'); }
+  if (!tokens || typeof tokens !== 'object') throw fail('GUIDE_BRAND_INVALID', 'PRESS brand file must contain an object.');
+  const css = brandCss(tokens);
+  let cover;
+  if (coverPath) {
+    cover = await fs.readFile(coverPath);
+    try {
+      const decoder = sharp(cover, { limitInputPixels: 40_000_000 });
+      const meta = await decoder.metadata();
+      if (meta.format !== 'png' || meta.width !== 1600 || meta.height !== 900 || (meta.pages || 1) !== 1) throw new Error('Expected one 1600 × 900 PNG.');
+      await decoder.raw().toBuffer();
+    } catch (error) { throw fail('GUIDE_COVER_INVALID', `Cover must be a decodable, single-frame 1600 × 900 PNG: ${error.message}`); }
+  }
+  const styles = await fs.readFile(new URL('./guide_preview.css', import.meta.url), 'utf8');
+  const rendered = renderToStaticMarkup(React.createElement(ReactMarkdown, {
+    remarkPlugins: [remarkGfm], skipHtml: true,
+    components: {
+      // Validate resolved Markdown nodes, including reference-style links. This
+      // draft helper copies one article, not an arbitrary companion directory.
+      a({ node: _node, href, children, ...props }) {
+        if (typeof href !== 'string' || !/^(https?:\/\/|#)/i.test(href)) throw fail('GUIDE_ASSET_UNSUPPORTED', 'Guide links must use public HTTP(S) URLs or same-page anchors. Relative companion files are not bundled; include required code inline.');
+        return React.createElement('a', { ...props, href }, children);
+      },
+      img() { throw fail('GUIDE_ASSET_UNSUPPORTED', 'Embedded Markdown images are not bundled. Supply a local PNG with coverPath, or retain the draft until companion-asset support is available.'); },
+    },
+  }, body));
+  const html = `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>${escape(data.title)}</title><style>${css}\n${styles}</style></head><body><main>
+<header class="masthead"><div class="stamp">${escape(tokens.identity.stamp)}</div><div class="eyebrow">CONCEPT GUIDE · LOCAL DRAFT</div><div class="byline">${escape(tokens.identity.name)}</div></header>
+<h1>${escape(data.title)}</h1><section class="agent-handoff" aria-labelledby="agent-heading"><h2 id="agent-heading">Implement this with your agent</h2><p>Copy the implementation prompt and complete guide, then paste into your coding agent in your project.</p><button type="button" id="copy-agent">Copy prompt + guide</button><p id="copy-status" role="status" aria-live="polite"></p><textarea id="copy-fallback" readonly hidden aria-label="Prompt and complete guide for manual copying"></textarea><details><summary>Read the prompt</summary><pre>${escape(prompt)}</pre></details><p><a href="agent-prompt.txt" download>Download prompt + complete guide</a></p><noscript><p>JavaScript is disabled. Open the <a href="agent-prompt.txt">complete plain-text handoff</a> and copy it into your agent.</p></noscript></section>
+${cover ? `<figure><a href="cover.png"><img src="cover.png" width="1600" height="900" alt="Cover for ${escape(data.title)}"></a></figure>` : ''}
+<p class="notice">Draft for review · <a href="article.md">Markdown guide</a> · Structural lint passed; implementation and independent review are separate checks.</p>${rendered}<footer class="colophon">Local draft. This helper does not publish.</footer></main>
+<script type="application/json" id="agent-payload">${JSON.stringify(payload).replaceAll('<', '\\u003c')}</script>
+<script>
+const payload = JSON.parse(document.getElementById('agent-payload').textContent);
+const button = document.getElementById('copy-agent');
+const status = document.getElementById('copy-status');
+const fallback = document.getElementById('copy-fallback');
+button.addEventListener('click', async () => {
+  status.textContent = '';
+  try {
+    if (!navigator.clipboard?.writeText) throw new Error('Clipboard unavailable');
+    await navigator.clipboard.writeText(payload);
+    fallback.hidden = true;
+    status.textContent = 'Copied prompt and complete guide. Paste into your agent.';
+  } catch {
+    fallback.hidden = false; fallback.value = payload; fallback.focus(); fallback.select();
+    status.textContent = 'Automatic copy is unavailable. The full text is selected below; press Cmd+C or Ctrl+C.';
+  }
+});
+</script></body></html>`;
+  const result = { schemaVersion: 1, status: 'local-draft', article: 'article.md', preview: 'index.html', agentPrompt: 'agent-prompt.txt', cover: cover ? 'cover.png' : null, articleSha256: hash(markdown), previewSha256: hash(html), stylesheetSha256: hash(styles), agentPromptSha256: hash(payload), brandSha256: hash(brandRaw), ...(cover ? { coverSha256: hash(cover) } : {}), lint, verification: { implementation: 'not-run', independentReview: 'not-run' } };
+  // mkdir without recursive is the exclusive claim. Existing directories/symlinks fail;
+  // a failed partial write retains no result.json completion marker and is never reused.
+  await fs.mkdir(outDir);
+  await fs.writeFile(path.join(outDir, 'article.md'), markdown, { flag: 'wx' });
+  await fs.writeFile(path.join(outDir, 'index.html'), html, { flag: 'wx' });
+  await fs.writeFile(path.join(outDir, 'agent-prompt.txt'), payload, { flag: 'wx' });
+  if (cover) await fs.writeFile(path.join(outDir, 'cover.png'), cover, { flag: 'wx' });
+  await fs.writeFile(path.join(outDir, 'result.json'), `${JSON.stringify(result, null, 2)}\n`, { flag: 'wx' });
+  return result;
+}

package/lib/guide_preview.css

@@ -0,0 +1,3 @@
+*{box-sizing:border-box}body{margin:0;background:var(--paper);color:var(--ink);font-family:var(--font-display);font-size:17px;line-height:1.65}main{max-width:1000px;margin:auto;padding:44px 40px 72px}header.masthead{border-top:8px solid var(--ink);padding-top:18px;display:flex;gap:20px;align-items:center;margin-bottom:42px}.stamp{font-family:var(--font-display);font-weight:900;font-size:22px;border:3px solid var(--accent);color:var(--accent);padding:7px;transform:rotate(-4deg)}.eyebrow,.byline,.colophon{font-family:var(--font-mono);font-size:12px;letter-spacing:.04em}.byline{margin-left:auto;color:var(--dim)}h1{font-size:clamp(38px,6vw,64px);line-height:1.05;letter-spacing:-.03em;font-weight:900;margin:0 0 32px;max-width:850px}h2{font-size:27px;line-height:1.2;border-top:2px solid var(--ink);padding-top:24px;margin-top:48px;letter-spacing:-.02em}p{max-width:780px}a{color:inherit;text-underline-offset:3px}pre{font-family:var(--font-mono);font-size:13px;line-height:1.6;overflow-x:auto;padding:20px 0;border-block:1px solid var(--hair)}code{font-family:var(--font-mono);font-size:.88em}pre code{font-size:inherit}img{display:block;max-width:100%;height:auto;margin:24px auto}table{border-collapse:collapse;width:100%;font-size:14px}td,th{border-bottom:1px solid var(--hair);padding:12px 16px 12px 0;text-align:left;vertical-align:top}th{border-bottom:2px solid var(--ink)}.notice{font-family:var(--font-mono);font-size:13px;color:var(--dim);padding-bottom:22px;border-bottom:1px solid var(--hair);margin-bottom:32px}.colophon{border-top:2px solid var(--ink);margin-top:48px;padding-top:18px;color:var(--dim)}@media(max-width:600px){main{padding:24px 20px}.byline{display:none}table{font-size:12px}}@media print{main{padding:0;max-width:none}pre{white-space:pre-wrap}h2{break-after:avoid}img{break-inside:avoid}}
+.agent-handoff{border-block:2px solid var(--ink);padding:22px 0;margin:0 0 32px}.agent-handoff h2{border:0;margin:0;padding:0}.agent-handoff pre{white-space:pre-wrap;overflow-wrap:anywhere}button{font:700 14px var(--font-display);background:var(--ink);color:var(--paper);border:2px solid var(--ink);padding:12px 18px;cursor:pointer}button:focus-visible,summary:focus-visible{outline:2px solid var(--accent);outline-offset:3px}summary{cursor:pointer;font-weight:700;margin-top:16px}#copy-status{font-family:var(--font-mono);font-size:12px;min-height:1.5em}#copy-fallback{width:100%;height:240px;margin-top:12px;background:var(--paper);color:var(--ink);font:13px var(--font-mono);border:1px solid var(--ink);padding:12px}figure{margin:32px 0}td,th{overflow-wrap:anywhere}@media print{button,#copy-status,#copy-fallback{display:none}}
+main{overflow-wrap:anywhere;min-width:0}table{display:block;overflow-x:auto}header.masthead{flex-wrap:wrap}

package/lib/publish_guide.mjs

@@ -0,0 +1,124 @@
+// Strict, additive guide publication. Receipts establish local consistency, not
+// independent proof that commands ran or that an author reviewed the result.
+import { readFileSync, existsSync, mkdtempSync, writeFileSync, rmSync, lstatSync } from 'node:fs';
+import { resolve, dirname, join, isAbsolute } from 'node:path';
+import { tmpdir } from 'node:os';
+import { createHash } from 'node:crypto';
+import sharp from 'sharp';
+import { lintGuide } from './guide_draft.mjs';
+import { parseFrontmatter } from './lint_post.mjs';
+import { publishEntry } from './publish_entry.mjs';
+import { RE_PROJECT_KEY, RE_FINAL_RELEASE } from './core.mjs';
+
+const digest = bytes => createHash('sha256').update(bytes).digest('hex');
+const fail = message => Object.assign(new Error(message), { code: 'GUIDE_EVIDENCE_INVALID' });
+function requireThat(condition, message) { if (!condition) throw fail(message); }
+function text(value) { return typeof value === 'string' && value.trim().length > 0; }
+function local(base, value) {
+  requireThat(text(value) && (isAbsolute(value) || !/^[a-z][a-z\d+.-]*:/i.test(value)), 'Evidence paths must be local filesystem paths');
+  return resolve(base, value);
+}
+function parse(bytes, label) {
+  try { const data = JSON.parse(bytes.toString('utf8')); requireThat(data && typeof data === 'object' && !Array.isArray(data), `${label} must be a JSON object`); return data; }
+  catch (error) { if (error.code === 'GUIDE_EVIDENCE_INVALID') throw error; throw fail(`${label} must contain valid JSON`); }
+}
+function checkedFile(base, ref, label) {
+  requireThat(ref && /^[a-f\d]{64}$/.test(ref.sha256 ?? ''), `${label} requires a SHA-256`);
+  const path = local(base, ref.path);
+  const bytes = readFileSync(path);
+  requireThat(digest(bytes) === ref.sha256, `${label} hash is stale`);
+  return { path, bytes };
+}
+function report(base, ref, label, articleSha256, agentPromptSha256) {
+  const file = checkedFile(base, ref, label);
+  const value = parse(file.bytes, label);
+  requireThat(value.status === 'passed' && text(value.summary), `${label} must pass with observed summary`);
+  requireThat(value.articleSha256 === articleSha256 && value.agentPromptSha256 === agentPromptSha256, `${label} is bound to different article or agent payload bytes`);
+  return { value, base: dirname(file.path) };
+}
+function present(file) {
+  try { lstatSync(file); return true; } catch (error) { if (error.code === 'ENOENT') return false; throw error; }
+}
+function assertVacant(cloneDir, project, version) {
+  requireThat(existsSync(cloneDir), 'Clone directory does not exist');
+  const projectDir = join(cloneDir, project);
+  if (present(projectDir)) requireThat(lstatSync(projectDir).isDirectory() && !lstatSync(projectDir).isSymbolicLink(), 'Project directory must be an ordinary directory');
+  for (const suffix of ['md', 'png']) {
+    requireThat(!present(join(projectDir, `${version}.${suffix}`)), `Guide identity ${project}/${version} is occupied (${suffix}); explicit editorial rewrite is separate`);
+  }
+  const manifestPath = join(projectDir, 'manifest.json');
+  if (existsSync(manifestPath)) {
+    const manifest = parse(readFileSync(manifestPath), 'Manifest');
+    requireThat(Array.isArray(manifest.entries), 'Manifest must contain entries');
+    requireThat(!manifest.entries.some(entry => entry && (entry.version === version || entry.file === `${version}.md`)), `Guide identity ${project}/${version} is occupied or tombstoned in the manifest`);
+  }
+}
+
+/** Local preflight followed by existing publishEntry; never commits or pushes.
+ * All evidence paths resolve relative to evidencePath; output-log paths resolve
+ * relative to their execution report. Missing config mode does not call this API.
+ */
+export async function publishGuide({ cloneDir, articlePath, evidencePath, coverPath } = {}) {
+  try {
+    requireThat(text(cloneDir) && text(articlePath) && text(evidencePath), 'cloneDir, articlePath and evidencePath are required');
+    const articleBytes = readFileSync(articlePath);
+    const markdown = articleBytes.toString('utf8');
+    const lint = lintGuide(markdown);
+    requireThat(lint.ok, `Guide lint failed: ${lint.findings.map(item => item.rule).join(', ')}`);
+    const evidence = parse(readFileSync(evidencePath), 'Evidence');
+    const base = dirname(resolve(evidencePath));
+    requireThat(evidence.schema === 1, 'Evidence schema must be 1');
+    const articleSha256 = digest(articleBytes);
+    requireThat(evidence.articleSha256 === articleSha256, 'Article hash is stale');
+    const { data } = parseFrontmatter(markdown.replaceAll('\r\n', '\n'));
+    const anchor = evidence.anchor;
+    requireThat(anchor && typeof anchor.project === 'string' && RE_PROJECT_KEY.test(anchor.project) && !anchor.project.includes('..'), 'Anchor project is invalid');
+    requireThat(typeof anchor.version === 'string' && RE_FINAL_RELEASE.test(anchor.version), 'Anchor must identify a final release version');
+    requireThat(typeof anchor.date === 'string' && /^\d{4}-\d{2}-\d{2}$/.test(anchor.date) && new Date(anchor.date).toISOString().slice(0, 10) === anchor.date, 'Anchor date must be a valid ISO date');
+    requireThat(data.project === anchor.project && data.version === anchor.version && String(data.date) === anchor.date, 'Article project/version/date must match the selected anchor');
+    const start = '<!-- agent-handoff:start -->', end = '<!-- agent-handoff:end -->';
+    const startIndex = markdown.indexOf(start), endIndex = markdown.indexOf(end);
+    const block = markdown.slice(startIndex + start.length, endIndex);
+    const prompt = /^```text\r?\n([\s\S]*?)\r?\n```\s*$/m.exec(block)[1];
+    const reference = markdown.slice(0, startIndex) + markdown.slice(endIndex + end.length);
+    const payload = `${prompt}\n\n<reference-guide>\n${reference.trim()}\n</reference-guide>\n`;
+    const payloadFile = checkedFile(base, evidence.agentPrompt, 'Agent prompt');
+    requireThat(payloadFile.bytes.equals(Buffer.from(payload)), 'Agent prompt does not match the exact handoff/reference payload');
+    const agentPromptSha256 = digest(payloadFile.bytes);
+    const execution = report(base, evidence.execution, 'Execution report', articleSha256, agentPromptSha256);
+    requireThat(Array.isArray(execution.value.commands) && execution.value.commands.length > 0, 'Execution report needs command observations');
+    for (const command of execution.value.commands) {
+      requireThat(command && text(command.command) && command.exitCode === 0, 'Every execution command must record successful observed completion');
+      const output = checkedFile(execution.base, command.output, 'Execution output');
+      requireThat(output.bytes.length > 0, 'Execution output cannot be empty');
+    }
+    const adaptation = report(base, evidence.adaptation, 'Adaptation report', articleSha256, agentPromptSha256).value;
+    requireThat(text(adaptation.fixture?.original) && text(adaptation.fixture?.result), 'Adaptation report must identify original and resulting fixtures');
+    requireThat(Array.isArray(adaptation.independentChecks) && adaptation.independentChecks.length > 0 && adaptation.independentChecks.every(check => check && text(check.check) && text(check.observation) && check.passed === true), 'Adaptation report needs passing independent checks with observations');
+    const review = report(base, evidence.review, 'Review report', articleSha256, agentPromptSha256).value;
+    requireThat(text(review.reviewer) && Array.isArray(review.blockingFindings) && review.blockingFindings.length === 0, 'Review report needs a reviewer and no unresolved blocking findings');
+    let coverImageBuffer;
+    if (coverPath !== undefined) {
+      requireThat(text(coverPath), 'coverPath must be a local file');
+      coverImageBuffer = readFileSync(coverPath);
+      const coverSha256 = digest(coverImageBuffer);
+      requireThat(evidence.coverSha256 === coverSha256 && review.coverSha256 === coverSha256 && text(review.coverReview), 'Cover bytes require matching evidence/review hashes and visual observations');
+      const image = sharp(coverImageBuffer, { animated: true, limitInputPixels: 40_000_000 });
+      const metadata = await image.metadata();
+      requireThat(metadata.format === 'png' && metadata.width === 1600 && metadata.height === 900 && (metadata.pages ?? 1) === 1 && !metadata.isPalette, 'Cover must be a single-frame true-color 1600x900 PNG');
+      await image.raw().toBuffer();
+    } else requireThat(evidence.coverSha256 === undefined && review.coverSha256 === undefined, 'Evidence references a cover but no coverPath was provided');
+    // Final check after async decoding, before any content write. A frozen local
+    // snapshot prevents article edits between evidence validation and copyFile.
+    assertVacant(cloneDir, anchor.project, anchor.version);
+    const staging = mkdtempSync(join(tmpdir(), 'devlog-validated-guide-'));
+    try {
+      const entryPath = join(staging, 'article.md');
+      writeFileSync(entryPath, articleBytes, { flag: 'wx' });
+      return { ...publishEntry({ cloneDir, project: anchor.project, version: anchor.version, entryPath, coverImageBuffer }), evidenceValidated: true, articleSha256, agentPromptSha256 };
+    } finally { rmSync(staging, { recursive: true, force: true }); }
+  } catch (error) {
+    if (error.code === 'GUIDE_EVIDENCE_INVALID') throw error;
+    throw fail(`Guide publication failed: ${error.message}`);
+  }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@natjswenson/devlog",
-  "version": "0.13.0",
-  "description": "Release dev log generator \u2014 Claude Code skill + preview app for publishing version-release dev logs, written in your voice, to your site",
+  "version": "0.14.0",
+  "description": "Release dev log generator — Claude Code skill + preview app for publishing version-release dev logs, written in your voice, to your site",
   "license": "MIT",
   "author": "Nate Swenson",
   "homepage": "https://github.com/natejswenson/devlog",
@@ -34,6 +34,7 @@
     "examples/",
     "voice/",
     "image-style/",
+    "references/",
     "SKILL.md",
     "SECURITY.md",
     "CHANGELOG.md",
@@ -59,7 +60,7 @@
     "react-dom": "18.3.1",
     "react-markdown": "9.1.0",
     "remark-gfm": "4.0.1",
-    "sharp": "0.35.3",
+    "sharp": "0.35.4",
     "vite": "8.0.16"
   }
 }