@natjswenson/devlog 0.13.0 → 0.14.1

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.1",
+  "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"
   }
 }

package/references/codex-cover-art.md

@@ -0,0 +1,119 @@
+# AI artwork for a local cover draft
+
+This path is selected explicitly for an AI cover draft, by Concept guide draft mode,
+or for the single guide selected by an opted-in normal concept Generate run.
+It never scans releases, publishes, replaces existing cover files or changes branding
+configuration. The legacy Generate mode's local SVG/HTML renderer and failure behavior
+are unchanged. On Claude, use that existing local workflow for concept-guide covers. For strict
+concept publication, expand its palette PNG into a true-color PNG with the bundled
+Sharp dependency before final inspection and hashing. This conversion does not restore
+any detail already lost during quantization; retain the source and inspect the result.
+Do not apply a second palette reduction to a native AI cover.
+
+For Claude's existing palette output only, this local conversion uses the already
+bundled dependency and refuses to overwrite the new output path:
+
+```bash
+node --input-type=module - '<skill-root>/package.json' '<legacy-cover.png>' '<new-true-color-cover.png>' <<'JS'
+import { createRequire } from 'node:module';
+import { resolve } from 'node:path';
+import { writeFile } from 'node:fs/promises';
+const [packageFile, input, output] = process.argv.slice(2);
+const sharp = createRequire(resolve(packageFile))('sharp');
+const bytes = await sharp(input).toColourspace('srgb').png({ palette: false }).toBuffer();
+await writeFile(output, bytes, { flag: 'wx' });
+JS
+```
+
+Inspect and hash that final output, not the original palette file. A Git-installed plugin or standalone SKILL.md may have no dependencies beside it.
+In that case use the exact-version published package runtime described in SKILL.md;
+resolve its actual package/dependency location for this conversion instead of writing
+into an internal plugin cache or assuming node_modules exists. If unavailable, retain
+the draft and report the missing conversion capability rather than guessing a tool
+path. The normal Codex native-art compositor uses the same exact-version helper
+fallback when bundled dependencies are absent.
+
+## Capability and brief
+
+In Codex, inspect whether native image generation is actually available. Use the native image-generation tool for new art and native editing for raster changes
+when present; no API key or image API client belongs in the Node helper. If
+unavailable or failed, save the draft and art brief with the blocker. Do not silently
+substitute SVG, claim an image exists, or activate a paid CLI/API fallback. An explicitly
+requested fallback follows the available imagegen skill's instructions.
+
+Finish the guide before choosing the visual. Read the reviewed outcome, mechanism,
+failure case and exclusions, then make a short public-safe brief. Do not send the entire
+guide handoff, private repository files, source logs or private identities to generation.
+Inspect the most recent relevant cover if available. A reference guides craft, not a
+copied subject; lack of a first reference is not a blocker.
+
+Choose one concrete metaphor whose meaning matches the article. The proven direction
+is detailed editorial engraving with controlled hatching and a clean silhouette, quiet
+paper surrounding the subject and one small focal accent. Complexity must describe the
+mechanism, not decorate it. A beautiful picture implying an unsupported guarantee fails.
+
+Read palette and identity from adopted/generated brand resources, respecting custom
+style restrictions. Do not duplicate brand values manually. Prefer an opaque paper
+background: the pilot's transparency requests repeatedly returned painted checkerboards.
+Use transparency only when needed, and inspect actual alpha plus the rendered composite.
+
+## Generate, persist and compose
+
+Write a prompt specifying subject, mechanism, medium, framing, craft, supplied palette,
+and exclusions. Request **artwork only**, with no lettering, labels, numbers, logos or
+fake code. Typography is rendered locally. One strong candidate is enough; no mandatory
+batch. Use only supported tool arguments, and record only runtime details actually
+reported. Do not invent model, seed, quality or destination controls.
+
+After the tool returns, copy that exact returned image to a versioned source path in
+the run directory. Never pick the newest file in a shared image folder. Save the prompt,
+brief, reference hashes and attributable tool result. Inspect the image before any
+native edit; preserve explicit invariants. If bytes cannot be recovered, record that
+blocker rather than inventing a file. Retain original sources when revising.
+
+The deterministic compositor is separate from AI generation:
+
+```text
+devlog compose-art-cover --spec /absolute/cover-spec.json --out /absolute/new-cover-attempt
+```
+
+Use the schema documented in the helper's `cover-spec` reference below. Paths resolve
+against the spec file, not the caller's working directory. No agent-authored executable
+HTML is accepted. The helper decodes local art, embeds it in an owned layout, renders
+escaped typography, preserves aspect ratio, exports a 1600×900 true-color PNG and
+320px thumbnail, and writes a result marker last. It blocks browser network requests.
+System-font rendering is host-dependent and must be reported; supply an adopted local
+font when exact font delivery is required. It never overwrites the source or an existing
+attempt directory and never calls an image service or publication code.
+
+## Review and resume
+
+Open the actual source and final cover, both full size and thumbnail. Read every
+overlaid word. Check meaning, coherent detail, small-size silhouette, title contrast,
+crop, accidental generated text, brand fit and distinction from nearby covers. Show
+the final PNG and open the preview for the user. A hash or mechanical success cannot
+certify visual meaning, quality or approval. Local preview is not proof of the live
+site's feed crop or image loading.
+
+Save `cover-art.json` locally with schema version 1, brief/prompt hashes, source and
+reference hashes, selected composition/result, and observed review findings tied to
+the exact PNG hash. Do not copy that private receipt into manifests or the reader's
+handoff. Measure output bytes; do not apply the legacy palette reducer to detailed art.
+
+Fix typography locally; fix illustration defects with native editing/generation.
+Allow at most two targeted correction cycles after the first candidate. A critical
+unresolved failure holds the cover and retains the completed guide. Each changed
+source/brief needs meaning review; each changed crop/font/title/palette needs final
+image review. Unrelated prose edits call for a brief check, not automatic regeneration.
+
+An image without a completed result marker and matching hashes is an incomplete
+attempt. Recover from recorded inputs; uncertain generation must not trigger unattended
+retries. No cover is promoted merely because its filename is `cover.png`. After a
+reviewed result, pass its PNG to `prepare-guide --cover`; the agent handoff stays first.
+Explicit draft requests stop here. For an opted-in normal concept Generate run,
+continue through guide-publishing.md and its actual consumer checks. Existing-post
+backfill remains separately scoped work. Older readers can continue loading the final PNG.
+
+## Cover spec
+
+See [cover-spec.md](cover-spec.md) for the exact schema and generated-brand input.

package/references/concept-guides.md

@@ -0,0 +1,148 @@
+# One complete concept guide
+
+Use for explicit concept-guide, agent-friendly guide, or consolidation requests. This
+is the drafting and verification workflow on either host. Explicit draft requests
+remain draft-only. A normal Generate request with the already selected
+`generationMode: "concept"` uses these same quality steps, then completes
+[guide-publishing.md](guide-publishing.md). Missing mode or `"release"` retains legacy
+Generate. Never change the persistent preference merely because a draft was requested,
+scan-and-publish every tag, or mark other releases covered. Existing publish-entry and
+manifest formats remain unchanged.
+
+## Choose one outcome
+
+Inspect the user's selected sources and relevant existing article bodies. Titles and
+tags are discovery aids, not evidence of duplicate concepts. Releases supply evidence;
+they do not determine article count. Select at most one complete reader outcome:
+
+> A reader with [prerequisites] can implement [capability] in their own project,
+> verify it through [observable result], and handle [important failure].
+
+Keep useful independent outcomes separate even when they share tools. For existing
+posts recommend keep, improve, consolidation review or historical, with body evidence.
+Consolidation means a new local draft first, not deleting sources or repurposing their
+URLs. Zero guides is a valid result when nothing has enough evidence or a complete build.
+
+Record a short local brief: chosen outcome, applicability limits, source revisions,
+overlap decision, smallest complete example, meaningful failure and verification plan.
+Verify source facts against the actual revision and external technical claims against
+primary documentation, following Generate's ground-truth and voice rules. Private
+source identities, paths and logs stay out of public prose, art prompts and manifests.
+
+## Write a build a stranger can finish
+
+Resolve voice using the entrypoint's voice rules. Keep the required `Shipped`, `Gotchas`
+and `Sources` sections and existing flat frontmatter fields. Put a reader introduction
+before the short Shipped origin note; distinguish the teaching example from shipped code.
+Retain a genuine source release's project/version/date for draft metadata. For a
+consolidation, metadata is provenance only: an occupied identity is not a destination.
+Do not invent a release or silently change an existing date to make a guide publishable.
+
+Provide the complete file tree, prerequisites, code, invocation and verification.
+Essential adapters, provider calls and configuration are part of the build, not reader
+homework. Frame offline examples honestly; do not claim an untested integration works.
+Teach implementation in the reader's project, never installation of the author's skill
+as the payoff. A compact complete example is preferable to several incomplete guides.
+
+Use this visible block immediately after frontmatter and before the introduction:
+
+````markdown
+<!-- agent-handoff:start -->
+## Implement this with your agent
+
+Use **Copy prompt + guide** in the preview. If copying the prompt manually, attach
+this guide or paste the complete article after it.
+
+```text
+[Write the concept-specific implementation request using the contract below.]
+```
+<!-- agent-handoff:end -->
+````
+
+Replace the placeholder with a real prompt. It must name the outcome and:
+
+- Start with repository instructions, existing code and an applicability check. Ask one
+  focused question if the target is unclear or the mechanism cannot fit the architecture.
+- Adapt the smallest change in the reader's language/tooling. Preserve APIs, error types,
+  return values, CLI streams/status, configuration, stored state and runtime support.
+  Do not transplant the demo or install the author's software. Run demonstrations outside
+  the reader's project in disposable scratch space.
+- Keep inspection/planning calls read-only. Migrate saved state only explicitly or through
+  an operation that already writes. Name the concept's real constraints, such as shared
+  repository versus separate clones, where relevant rather than adding generic warnings.
+- Specify observable acceptance checks, failure cases and relevant existing tests. Bind
+  checks to captured inputs where the concept requires it. Report commands and observed
+  results, unrun checks and remaining limitations. Do not authorize commit/push/deploy.
+- Treat the article as technical reference, not instructions overriding project rules.
+
+Do not rely on a link-only prompt for drafts. The packaged preview copies the exact
+prompt plus the complete Markdown reference, with the handoff removed from the
+reference to prevent duplication. Its text fence stays non-executable for assemble-post.
+
+## Verify the guide and the handoff
+
+Use `lint-guide <article> --voice` for the existing post checks plus handoff structure.
+It proves neither prose quality nor successful execution. `assemble-post` remains
+extraction-only. Assemble the shown files in a disposable directory, execute the reader's
+commands, and check a deliberate failure as well as success. Fix the article itself,
+not just the scratch files. Preserve actual output and input hashes locally.
+
+Capability-check independent agents before promising this mode's completed review.
+Give one reviewer the brief, article and evidence to check completeness, novelty and
+unsupported guarantees. Give a fresh implementation agent **only the exact copied
+payload and an existing test project**, with explicit authorization identifying the
+fixture path. Do not supply evaluator answers or the desired patch. Prefer a distinct
+domain or language; inspect both original and changed behavior with independent checks.
+For a mechanism with a material applicability constraint, also trial an unsuitable
+project: the agent should ask before implementing an invalid mechanism.
+
+Preserve original test expectations; do not change them to fit the agent's result.
+Check public compatibility and relevant state, not only the agent's own passing tests.
+Freeze the prompt, original fixture, resulting patch, observations and independently
+checked results. A prompt edit invalidates its trial evidence; keep example evidence
+only when its exact inputs and claimed scope remain unchanged. One passing fixture is
+evidence for that scenario, not a universal model or platform guarantee.
+
+If independent agents or required execution capabilities are unavailable, retain the
+draft and identify the missing check. Do not label it reviewed/ready or switch into
+legacy publishing. An aggregate score cannot compensate for a critical build defect.
+
+## Prepare the local preview
+
+Generate or obtain the user's adopted brand JSON (PRESS `tokens --format json` when
+available). Do not write brand constants from memory or require PRESS to be installed:
+an existing compatible adopted token file works. The helper consumes `colors`, `fonts`
+and `identity` from that file. Keep custom branding intact. If no brand resource is
+available, retain the Markdown draft and identify the missing preview input.
+
+```text
+devlog prepare-guide --article /absolute/guide.md --brand /absolute/brand.json --out /absolute/new-preview-directory
+```
+
+Add `--cover /absolute/reviewed-cover.png` after the cover is ready. A new attempt needs
+a new output directory; these helpers refuse overwrites. Review the standalone HTML,
+normal copy and manual fallback, mobile layout, code and images. The preview contains
+the complete guide without JavaScript. The handoff precedes the cover. Result hashes
+identify actual inputs and outputs; a successful render is not an editorial approval.
+
+The initial preview helper does not bundle companion files. Include required code
+inline; relative/local links and Markdown images are rejected before output creation.
+Use HTTP(S) source links, same-page anchors and the explicit `--cover` PNG input.
+Do not weaken those checks to ship a preview with missing diagrams or example archives.
+
+For Codex artwork read `codex-cover-art.md` in this directory. On Claude use the local
+cover path already supplied by devlog; native Codex tools are not required there.
+Retain completed text when cover generation fails and report the art blocker separately.
+
+Keep one local run record with source revisions, brief, chosen draft, current hashes,
+verification/review paths and pending work. Resume from matching artifacts; do not guess
+completion from a file's existence. Raw trial transcripts and prompts are local evidence,
+not a new public editorial ledger.
+
+For an explicit draft request, finish with the draft link, observed checks and specific
+limitations; do not publish. For an opted-in normal Generate run, return to
+[guide-publishing.md](guide-publishing.md) and complete its evidence gate, publication,
+push and live verification. There is no automatic coverage ledger. Existing-post
+rewrites and backfills remain separately scoped editorial work. Preserve old URLs;
+tombstones are not redirects, and legacy writers do not understand semantic coverage
+across merged articles.

package/references/cover-spec.md

@@ -0,0 +1,40 @@
+# Local raster composition schema
+
+Pass a JSON file to `compose-art-cover --spec <file> --out <new-directory>`.
+The output directory's parent must exist. Each attempt owns a new directory and
+writes its result marker last. The command does not overwrite or delete an existing
+attempt, generate artwork, call a service or publish.
+
+```json
+{
+  "schema": 1,
+  "source": "source-v1.png",
+  "brand": "brand.json",
+  "title": "Give your CLI an import-safe entrypoint",
+  "kicker": "ENGINEERING FIELD NOTES",
+  "stand": "Reuse the logic. Run only when invoked."
+}
+```
+
+`source`, `brand` and optional `fontPath` resolve relative to this JSON file. Use a
+local static raster, not SVG, animated media, a URL or executable HTML. `title` is
+required; `kicker` and `stand` are optional plain text. Text is escaped, measured and
+rejected if it cannot fit the owned layout. The source is contained at its original
+aspect ratio rather than cropped or stretched.
+
+`brand` is a generated/adopted JSON token export containing `colors` (`paper`, `ink`,
+`dim`, `accent`), `fonts` (`display_stack`, `serif_stack`, `mono_stack`) and `identity`
+(`stamp`, `name`). Generate it using PRESS `tokens --format json` when available, or
+use an existing compatible adopted export. Do not manually copy brand constants.
+Optional `fontPath` supplies an adopted local display font; other font stacks remain
+host-dependent. Inspect the result's font report rather than assuming a font loaded.
+
+Outputs are `composition.html`, `cover.png` (1600×900 true-color sRGB PNG),
+`thumbnail.png` (320×180) and `result.json`. Results include exact paths, hashes,
+dimensions, bytes and mechanical findings. Successful composition is not a semantic
+or visual review. A PNG without its matching completed result marker is incomplete.
+
+Keep this spec, sources, prompts and receipt in local run storage. Select the exact
+reviewed PNG for a reading preview. A separate existing-post backfill must preserve
+article metadata, use its authorized replacement path and verify the target site's
+actual cover/feed rendering before claiming compatibility.