@natjswenson/devlog 0.12.0 → 0.14.0

package/SKILL.md

@@ -1,12 +1,25 @@
 ---
 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
+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 +34,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 +69,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).
 
@@ -41,12 +90,20 @@ Map the user's request onto the CLI — never hand-edit `config.json`:
 | Show config | `npx -y @natjswenson/devlog@latest 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`, `voicePath`, `deepDive.minSources`, `deepDive.topicDomains`) |
+| 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
 repo root. Set it with `set targetDir content/devlog`, clear it with `set targetDir ''`.
 
+`siteUrl` is the public base URL that repo is *served* at, with no trailing slash — used
+to verify a published entry actually renders (Generate step 6). **The repo name is not the
+site name**: a repo called `example.io` is commonly served at `example.com`, so take this
+from a working page, not from the repo. Without it a run can push but cannot confirm
+anything went live. Set with `set siteUrl 'https://example.com'`, clear with
+`set siteUrl ''`.
+
 For **add-project**: resolve the path first (the repo the user named, or the cwd), then
 detect what the CLI will use — key = directory basename, remote = `git -C '<path>' remote
 get-url origin`. In a monorepo, suggest a `--path-filter` (the project's subdir) and a
@@ -335,7 +392,7 @@ 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
+In this legacy Generate path, 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:
 
@@ -412,7 +469,65 @@ rm -rf '<abs-tmp>'
 
 If the push fails, report the error and stop — do not retry automatically.
 
-### Step 6: Confirm
+### Step 5b: Register a project the site has never rendered before
+
+`publish-entry` returns **`firstEntryForProject: true`** when the call created that
+project's first live entry. **A push is not a route.** A site that renders the devlog
+almost always keeps its own registry deciding *which* content directories become pages;
+content on disk that the registry doesn't list is built right past, and the entry 404s
+while every command in this skill reports success. Publishing a project's first entry is
+therefore a two-part job, and the CLI can only do the first part.
+
+When `firstEntryForProject` is true, **before the push**:
+
+1. Find the registry in the clone. It is a source file, not content — grep the site's
+   `src/` for the existing project keys (`grep -rn '<a-known-project-key>' <clone>/src`).
+   In an Astro/Next-style site it is typically a `PROJECTS` array the entry loader maps
+   over.
+2. Add the new project, matching the shape of the neighbouring rows exactly.
+3. **Build the site in the clone and confirm the route exists** (`npm ci && npx astro
+   build`, then check the output directory contains the new `<project>/<version>` path).
+   A registry edit that doesn't produce a route is not done.
+4. Run the site's own test suite if it has one, and commit the registry change together
+   with the content in the same push.
+
+If you cannot find a registry, say so plainly rather than assuming there isn't one; the
+verification in Step 6 is what actually settles it.
+
+**Registry position can decide feed order, not just visibility.** If the site sorts
+entries by date alone, same-date entries fall back to their load order, which is registry
+order — so a project appended to the end can render its newest entry last. After the build
+in step 3, check that the new entry appears where its date and publish numeral say it
+should, and report it if not.
+
+### Step 6: Verify the entry is actually live
+
+**Do not report a publish as successful until the published URL returns 200.** The push
+succeeding, the manifest updating, and the site serving the post are three different
+things, and this skill has previously reported success on all of the first two while the
+post 404'd.
+
+When `siteUrl` is set in config (it is echoed in the scan output):
+
+```bash
+curl -s -o /dev/null -w '%{http_code}' -L '<siteUrl>/devlog/<project>/<version>/'
+```
+
+Poll every ~45s for up to ~5 minutes; deploys are not instant. Then:
+
+- **200** → done, report the live URL as the primary link.
+- **Still 404 after the window** → the deploy failed or the entry is not routed. Check
+  `firstEntryForProject`/the registry from Step 5b first, since that is the most common
+  cause, then the host's build log. Report it as **not live**, with what you checked.
+- **`siteUrl` unset** → say the entry is pushed but unverified, give the repo URL, and
+  offer to set it: `npx -y @natjswenson/devlog@latest set siteUrl 'https://example.com'`.
+  Never describe an unverified push as published.
+
+The `/devlog/<project>/<version>/` path is this skill's default convention. If the site
+routes differently, take the pattern from a URL of an already-published entry rather than
+assuming this one.
+
+### Step 7: Confirm
 
 ```
 Release dev log entries published
@@ -420,13 +535,13 @@ Release dev log entries published
   Project: <key>
   Releases: <version>, ...
   Judged weaknesses: <residuals from Step 4, or "none">
-  URL: https://github.com/<targetRepo>/blob/<branch>/<targetDir-prefix><key>/<version>.md
+  Live: <siteUrl>/devlog/<key>/<version>/  (verified 200)
+  Source: https://github.com/<targetRepo>/blob/<branch>/<targetDir-prefix><key>/<version>.md
 ```
 
-(`<targetDir-prefix>` is `<targetDir>/` when set, empty otherwise.) When the target is
-a site repo that auto-deploys on push (e.g. Cloudflare Pages watching `main`), the
-publish push itself triggers the rebuild — mention that the entry goes live with the
-next deploy.
+(`<targetDir-prefix>` is `<targetDir>/` when set, empty otherwise.) Report the **verified
+live URL** as the primary link; the repo blob URL is the secondary one. If Step 6 could
+not verify, say so on the `Live:` line instead of printing a URL that may 404.
 
 ## Security rules
 

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,11 +29,13 @@ 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 }),
   gitAuthor: (c, v) => ({ ...c, gitAuthor: v }),
   githubUser: (c, v) => ({ ...c, githubUser: v }),
+  siteUrl: (c, v) => (v === '' ? omit(c, 'siteUrl') : { ...c, siteUrl: v.replace(/\/+$/, '') }),
   voicePath: (c, v) => (v === '' ? omit(c, 'voicePath') : { ...c, voicePath: expandHome(v) }),
   'deepDive.minSources': (c, v) => {
     const n = Number(v);

package/lib/core.mjs

@@ -125,6 +125,19 @@ export function validateConfig(config) {
       throw new Error(`targetDir must be a relative path like "content/devlog" (no leading/trailing slash, no '..'): got ${JSON.stringify(config.targetDir)}`);
     }
   }
+  if ('siteUrl' in config) {
+    // Optional: the public base URL the target repo is served at, used only to
+    // confirm a published entry actually renders. The repo name is not the site
+    // name (a repo called `example.io` can be served at `example.com`), and
+    // pushing content is not the same as the site serving it, so this is the
+    // only way a publish run can verify itself rather than assume.
+    // Interpolated into a shell curl, hence the tight charset.
+    if (typeof config.siteUrl !== 'string'
+      || !/^https?:\/\/[A-Za-z0-9.-]+(:\d+)?(\/[A-Za-z0-9._~/-]*)?$/.test(config.siteUrl)
+      || config.siteUrl.endsWith('/')) {
+      throw new Error(`siteUrl must be an http(s) URL with no trailing slash, e.g. "https://example.com": got ${JSON.stringify(config.siteUrl)}`);
+    }
+  }
   if ('voicePath' in config) {
     // Optional: directory holding the voice profile used to write entries. Read by
     // the skill with the Read tool only — never shell-interpolated — so the only
@@ -137,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');