@natjswenson/devlog 0.13.0 → 0.14.1

package/SKILL.md

@@ -1,12 +1,29 @@
 ---
 name: devlog
-description: Turn each new version release (git tag) into a polished, researched how-to guide with real gotchas, written in your voice and published to GitHub. Also manages devlog configuration conversationally — add/remove tracked repos, change settings, show status.
+description: Turn releases into researched how-to posts, or explicitly draft one complete concept guide readers can implement with their own coding agent. Supports Codex AI cover drafts and conversational devlog configuration.
 user_invocable: true
 ---
 
+## Codex runtime
+
+When running in Codex, invoke this skill as `$devlog`. Resolve scripts, assets,
+and references from the directory containing this SKILL.md, regardless of the
+current working directory. Existing `~/.claude/` personal-data paths remain valid
+and are still used by the bundled scripts; they do not require Claude to run.
+Map `Read`/`Write`/`Edit`/`Bash` to the available file and shell tools, and
+`WebSearch`/`WebFetch` to available web tools. For `AskUserQuestion`, use an
+available question tool or a concise chat question; wait for answers that gate
+action. Use Codex's delegation tools for required subagents when available;
+otherwise disclose that independent execution is unavailable. Discover connected
+apps by capability rather than assuming Claude MCP tool names exist.
+
 # /devlog — Release How-To Generator
 
-You turn each **new version release** (a semver git tag) in the user's projects into a
+<!-- press:runtime -->
+In Claude Code, load `/press`; in Codex, load `$press`; then follow the shared PRESS terminal/UI contract from `brand/agent-ui.md`. Do not copy or override that contract here.
+<!-- press:runtime -->
+
+In the default Generate mode, you turn each **new version release** (a semver git tag) in the user's projects into a
 published blog post, written in **the user's own voice**, and pushed to the GitHub repo
 configured in `~/.claude/skills/devlog/config.json`.
 
@@ -21,6 +38,34 @@ Every agent-facing command prints JSON.
 
 ## Decide which mode you're in
 
+Explicit draft requests take precedence over the default Generate routing:
+
+- **Concept guide draft** — "draft one concept guide", "use the agent-friendly guide
+  method", or "consolidate these posts into one guide". Read
+  [references/concept-guides.md](references/concept-guides.md). Select at most one
+  transferable reader outcome and finish its implementation, handoff and independent
+  trial. This mode is draft-only; never fall through to Generate or publish-entry.
+- **AI cover draft** — "create an AI cover draft for this article". Read
+  [references/codex-cover-art.md](references/codex-cover-art.md). Work from the supplied
+  article, without scanning releases or publishing. Codex native image generation is
+  capability-checked; Claude retains its existing local renderer. No implicit API fallback.
+
+New helpers are `lint-guide`, `prepare-guide`, `compose-art-cover`, and `publish-guide`.
+Only `publish-guide` writes prepared content to a clone; it requires matching local
+execution, adaptation and review evidence. It does not push or deploy.
+The draft helpers do not change persistent configuration or the content repository.
+Use bundled `bin/devlog.js` relative to this loaded SKILL.md only when its runtime
+dependencies resolve: check `node <absolute-skill-root>/bin/devlog.js --version` first.
+A Git-installed plugin can contain the script without node_modules. If the script or
+dependencies are missing, use `npx -y @natjswenson/devlog@0.14.0 <helper>`; do not install
+dependencies into an internal plugin cache. A standalone SKILL.md installed by `init`
+uses that same exact-version fallback. For a missing Chromium binary, install the
+matching browser with `npx -y --package=@natjswenson/devlog@0.14.0 playwright install chromium`
+and retry the render; do not silently change dependency versions. References are bundled beside
+both host entrypoints and copied with standalone skill installation.
+
+Otherwise use the existing modes:
+
 1. **Configure** — the user wants to change what devlog tracks or how it behaves:
    "add this repo to devlog", "stop tracking X", "set min sources to 4", "show my
    devlog config". → **Configure mode**.
@@ -28,7 +73,15 @@ Every agent-facing command prints JSON.
    "any new releases?". → **Status mode**.
 3. **Generate** (default) — `/devlog` or `/devlog <project-key>`. → **Generate mode**.
 
-An entry corresponds to a **release**, not a day. Re-running Generate only produces
+For a normal Generate request, read validated config first. If the user explicitly
+selected `generationMode: "concept"`, follow
+[references/guide-publishing.md](references/guide-publishing.md): select at most one
+complete guide, finish its draft/trial/review, then publish after all checks. Missing
+`generationMode` or `"release"` retains the existing Generate workflow below. Explicit
+draft requests above always remain draft-only, even with this preference. Set the
+preference only when the user asks; an update must not silently opt existing users in.
+
+In Generate mode, an entry corresponds to a **release**, not a day. Re-running Generate only produces
 entries for tags that don't already have one — it is idempotent, and a published entry is
 **immutable: never overwrite it** (`publish-entry` refuses; don't work around it).
 
@@ -42,6 +95,7 @@ Map the user's request onto the CLI — never hand-edit `config.json`:
 | Add a project | `npx -y @natjswenson/devlog@latest add-project --yes --path <abs-path> [--key K] [--remote O/R] [--label L] [--tag-prefix P] [--path-filter F] [--private]` |
 | Remove a project | `npx -y @natjswenson/devlog@latest remove-project <key> --yes` |
 | Change a setting | `npx -y @natjswenson/devlog@latest set <field> <value>` (settable: `targetRepo`, `branch`, `targetDir`, `gitAuthor`, `githubUser`, `siteUrl`, `voicePath`, `deepDive.minSources`, `deepDive.topicDomains`) |
+| Adopt one-guide generation for future normal runs | `npx -y @natjswenson/devlog@latest set generationMode concept` (use `release` to restore legacy generation) |
 
 `targetDir` is the subdirectory of `targetRepo` that holds the devlog content tree
 (e.g. `content/devlog` when the target is the site repo itself); unset/empty means the
@@ -342,9 +396,12 @@ The `--clone` flag always points at the CONTENT ROOT: `<abs-tmp>/<repo-name>` wh
 `targetDir` is empty, `<abs-tmp>/<repo-name>/<targetDir>` when it's set. Git commands
 always run against the clone root `<abs-tmp>/<repo-name>` regardless.
 
-Each release also gets a cover image, composed inline in this same loop right before that
-release's own `publish-entry` call — a self-contained HTML/CSS (or inline SVG) document,
-rasterized locally, never sent to any external service:
+In this Generate path, each release also gets a cover image, created inline in this same loop right before that
+release's own `publish-entry` call. In Codex, the dominant artwork MUST come from the native
+image-generation tool as a persisted raster source; wireframes, hand-authored SVG, CSS drawings,
+and title-only placeholders are not covers. The deterministic compositor may add PRESS typography
+around that generated artwork, but it must never substitute for native image generation.
+The cover must carry a custom illustration or other meaningful visual material; a cover that just re-renders the title in large text is a failure.
 
 ```bash
 mktemp -d    # → record the absolute path, e.g. /var/folders/.../tmp.abc
@@ -365,24 +422,17 @@ Per release:
    returns the style guide, icon catalog, and up to 3 reference cover paths. **Read
    only the single most recent reference image** (image reads are the expensive part;
    open another only if you're genuinely unsure the new cover is distinct). On
-   `{"error": "style-guide-missing"}`: skip cover composition for this release entirely
-   and proceed straight to publish-entry with no `--cover` flag.
-   Never block publish on a missing style guide.
-2. **Compose** using ONLY this release's title/tags/summary/`## Shipped` text
-   (never the raw draft file, never `## Changelog`) plus the style guide and icon catalog. A
-   cover that just re-renders the title in large text is a failure — find the one
-   concrete mechanism this release is actually about (not the project name, not "a bug
-   fix") and draw ONE custom inline-SVG illustration of it as the dominant visual
-   element; title/kicker stay secondary; two releases should never produce visually
-   similar covers. Follow the style guide's hero-zone grid contract: the illustration
-   lives in a `#hero-zone` container at exactly `x:150 y:425 width:1300 height:400`
-   (render-cover mechanically enforces this), one of two slots (single centered hero,
-   or two-node before/after), interior points snapped to a 25px grid; catalog icons
-   never go inside `#hero-zone` (optional small accent glyph near the kicker only,
-   bottom edge above y:400). Write the document with the Write tool to
-   `'<abs-scratch>/<key>/<version>.html'` — full `<!DOCTYPE html>` document, sized
-   `html, body { margin:0; width:1600px; height:900px; }`, font referenced only as
-   `font-family: 'DevlogCoverFont', sans-serif`.
+   `{"error": "style-guide-missing"}`: stop this release and report that publication is
+   blocked. A release entry is not publishable without a cover and agent handoff.
+2. **Generate and compose.** Use ONLY this release's title/tags/summary/`## Shipped` text
+   (never the raw draft file, never `## Changelog`) plus the style guide and icon catalog to
+   brief the native image-generation tool. Request artwork only: one concrete mechanism,
+   no lettering, labels, numbers, logos, fake code, UI, wireframe, gradients, or watermark.
+   Persist and inspect the exact returned raster, then use `compose-art-cover` to add local
+   PRESS typography. Do not draw the dominant art as inline SVG or CSS. A cover that just
+   re-renders the title in large text is a failure. Match the established backfill look:
+   flat cream paper, monochrome technical engraving, black/gray ink, restrained crosshatching,
+   a quiet left field for the headline, and at most one small orange accent.
 3. **Rasterize.**
    `npx -y @natjswenson/devlog@latest render-cover '<abs-scratch>/<key>/<version>.html' --project '<key>' --slug '<version>' --out '<abs-scratch>'`
    The HTML is the source of truth and **survives the render**: to fix a visual

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];
@@ -1043,15 +1126,18 @@ async function cmdCommitCovers(rest) {
   // routinely runs well after the backfill/review session that produced the staging dir,
   // and reusing an hours-or-days-old clone would risk mutating a manifest that's since
   // moved on.
-  const cloneDir = mkdtempSync(join(tmpdir(), 'devlog-commit-covers-'));
+  const repoDir = mkdtempSync(join(tmpdir(), 'devlog-commit-covers-'));
   const branch = config.branch || 'main';
   const cloneUrl = `https://github.com/${config.targetRepo}.git`;
-  const cloneResult = spawnSync('git', ['clone', '--depth=1', '--branch', branch, cloneUrl, cloneDir], { encoding: 'utf8' });
+  const cloneResult = spawnSync('git', ['clone', '--depth=1', '--branch', branch, cloneUrl, repoDir], { encoding: 'utf8' });
   if (cloneResult.status !== 0) {
-    rmSync(cloneDir, { recursive: true, force: true });
+    rmSync(repoDir, { recursive: true, force: true });
     emitJSON({ error: 'clone-failed', message: cloneResult.stderr || 'git clone failed' }, 1);
     return;
   }
+  // Manifests live under the configured content root; git operations still run
+  // from the repository root.
+  const cloneDir = join(repoDir, config.targetDir || '');
 
   const summary = { written: [], skipped: [], failed: [], missingManifest: [] };
   let bulkForceOverwriteCount = 0;
@@ -1116,20 +1202,20 @@ async function cmdCommitCovers(rest) {
       ['commit', '-m', `chore(devlog): add ${summary.written.length} cover image(s)`],
     ];
     for (const args of steps) {
-      const r = spawnSync('git', ['-C', cloneDir, ...args], { encoding: 'utf8' });
+      const r = spawnSync('git', ['-C', repoDir, ...args], { encoding: 'utf8' });
       if (r.status !== 0) {
         emitJSON({ ok: false, ...summary, bulkForceOverwriteCount, error: 'git-commit-failed', message: r.stderr }, 1);
         return;
       }
     }
-    const push = spawnSync('git', ['-C', cloneDir, 'push', '--no-tags', 'origin', branch], { encoding: 'utf8' });
+    const push = spawnSync('git', ['-C', repoDir, 'push', '--no-tags', 'origin', branch], { encoding: 'utf8' });
     if (push.status !== 0) {
       emitJSON({ ok: false, ...summary, bulkForceOverwriteCount, error: 'git-push-failed', message: push.stderr }, 1);
       return;
     }
   }
 
-  rmSync(cloneDir, { recursive: true, force: true });
+  rmSync(repoDir, { recursive: true, force: true });
   emitJSON({ ok: summary.failed.length === 0, ...summary, bulkForceOverwriteCount });
 }
 
@@ -1257,6 +1343,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 +1417,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

@@ -11,8 +11,9 @@ are how a from-scratch visual language stays consistent from post to post.
 
 ## What you're composing
 
-A single self-contained HTML document (inline `<style>`, inline SVG for any artwork) that
-renders, at exactly 1600×900px, as a cover image for one dev log entry. Compose from these
+A single PRESS editorial cover that renders, at exactly 1600×900px, as a cover image for
+one dev log entry. In Codex, the dominant image is a native generated raster illustration;
+the local compositor adds the typography and layout. Compose from these
 fields only — never open the post's raw markdown file, never reference any section other
 than `## Shipped` (no `## Changelog`, no gotchas, no sources):
 - `title`
@@ -34,11 +35,11 @@ Before writing any HTML, do this thinking step explicitly:
    key that doesn't fit, a git tag being distrusted like any other user input, one broken
    link in a chain, a filter separating signal from noise, a clock catching a stale
    timestamp, two paths diverging and one being cut off.
-3. Design ONE illustration — built from inline SVG shapes (lines, arcs, polygons,
-   simple geometric forms) — that depicts that concept. Not a photo, not a stock icon,
-   not a screenshot: a small original line-art scene, **editorial line art in ink with
-   sparing orange**, in the spirit of a newspaper diagram or a technical schematic, using
-   only the palette below.
+3. Design ONE native raster illustration that depicts that concept. Not a photo, stock
+   icon, screenshot, UI, wireframe, or geometric placeholder: a detailed original
+   **monochrome technical engraving in black and warm gray ink on flat cream paper**, in
+   the spirit of a historical engineering plate or newspaper field illustration, with at
+   most one small vermilion/orange focal accent. The art must look printed, not painterly.
 4. That illustration is the dominant visual element of the cover — roughly half the
    canvas, not a thumbnail in the corner. Title, kicker, and summary text support it;
    they do not replace it.
@@ -151,10 +152,10 @@ For the two-node slot specifically: the accent icon's presence must not be read
   `DevlogCoverFont` finishes loading. That's resolving a name the browser already has, not
   embedding or fetching a file — no different in kind from the fallback this rule already
   requires.
-- No external resources of any kind — no `<link>`, no `@import`, no remote `<img src>`,
-  no web fonts, no raster images. All artwork is inline SVG built from basic shapes
-  (`<path>`, `<circle>`, `<rect>`, `<line>`, `<polygon>`, `<polyline>`) — everything must
-  be inline HTML/CSS/SVG, hand-composed, not fetched or embedded from anywhere.
+- The final cover must be self-contained and offline-renderable. Native raster artwork is
+  persisted locally and embedded by `compose-art-cover`; no remote images or web fonts.
+  Typography is rendered locally and the generated artwork is never replaced by inline
+  SVG, CSS shapes, a wireframe, or a title-only placeholder.
 
 ## Visual direction
 
@@ -165,20 +166,21 @@ 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.
-
-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
-visibly under that compression while flat fills don't.
+<!-- >>> press:palette v0.10.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. Native
+art should be predominantly cream paper plus black/gray engraving lines, with no broad
+color wash, no saturated palette, and no painterly digital lighting. The only bright color
+is the single small orange accent permitted by the accent law below.
 
 ### The accent law, carried to covers
 
@@ -304,7 +306,8 @@ summary as on-image text.
   cursor, no bare `_` suffix, no stray `$` prompt as decoration. The dark palette now
   belongs to exactly one place, the `.term` panel, and only when it's real code.
 - Don't embed a photograph, stock image, or anything requiring an external fetch — the
-  illustration is drawn from inline SVG primitives, not sourced from anywhere.
+  illustration is native-generated raster artwork persisted locally and embedded by the
+  compositor, never a hand-authored SVG substitute.
 - Don't reference any font file other than the bundled `'DevlogCoverFont'` — the serif
   and display voices lean on this rendering host's own system fonts, never a file you
   fetch or embed yourself.

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');