@natjswenson/devlog 0.9.0 → 0.11.0

package/bin/devlog.js

@@ -2,7 +2,7 @@
 import { spawn, spawnSync, execSync } from 'node:child_process';
 import {
   existsSync, mkdirSync, readFileSync, writeFileSync, copyFileSync, realpathSync,
-  readdirSync, statSync, unlinkSync, rmSync, mkdtempSync,
+  readdirSync, statSync, rmSync, mkdtempSync,
 } from 'node:fs';
 import { dirname, join, resolve, basename } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -32,9 +32,10 @@ import {
   validateConfig,
   resolveDeepDive,
 } from '../lib/core.mjs';
-import { scanAll } from '../lib/scan.mjs';
+import { scanAll, summarizeScan } from '../lib/scan.mjs';
 import { lintPost, parseFrontmatter, splitSections } from '../lib/lint_post.mjs';
-import { publishEntry, addCoverToExistingEntry } from '../lib/publish_entry.mjs';
+import { publishEntry, addCoverToExistingEntry, tombstoneEntry, syncEntryFromFrontmatter } from '../lib/publish_entry.mjs';
+import { writeAssembledBlocks } from '../lib/assemble_post.mjs';
 import { addProject, removeProject, setField, SETTABLE_FIELDS } from '../lib/config_ops.mjs';
 import { loadStyleGuide, getRecentCovers, mergeManifestEntries } from '../lib/cover_gen.mjs';
 import { renderCoverImage } from '../lib/render_cover.mjs';
@@ -110,6 +111,18 @@ function emitJSON(obj, exitCode = 0) {
   process.exit(exitCode);
 }
 
+// parseArgs is strict by default, so an unknown flag (`render-cover --force`)
+// used to die with a raw ERR_PARSE_ARGS_UNKNOWN_OPTION stack trace instead of
+// the JSON error shape every agent-facing command promises. Same contract as
+// commit-covers' hand-rolled parser: unknown/malformed flags → bad-flag JSON.
+function safeParseArgs(spec) {
+  try {
+    return parseArgs(spec);
+  } catch (e) {
+    emitJSON({ error: 'bad-flag', message: e.message }, 2);
+  }
+}
+
 function readValidConfigOrExit({ json = false } = {}) {
   if (!existsSync(CONFIG_PATH)) {
     if (json) emitJSON({ error: 'config-missing', path: CONFIG_PATH, hint: 'Run `npx @natjswenson/devlog init` first.' }, 1);
@@ -462,7 +475,7 @@ async function cmdInit() {
 
 // ─── add-project ─────────────────────────────────────────────────────────────
 async function cmdAddProject(rest) {
-  const { values } = parseArgs({
+  const { values } = safeParseArgs({
     args: rest,
     options: {
       path: { type: 'string' },
@@ -541,7 +554,7 @@ async function cmdAddProject(rest) {
 
 // ─── remove-project ──────────────────────────────────────────────────────────
 async function cmdRemoveProject(rest) {
-  const { values, positionals } = parseArgs({
+  const { values, positionals } = safeParseArgs({
     args: rest,
     options: { yes: { type: 'boolean', default: false } },
     allowPositionals: true,
@@ -571,7 +584,7 @@ async function cmdRemoveProject(rest) {
 
 // ─── set ─────────────────────────────────────────────────────────────────────
 function cmdSet(rest) {
-  const { positionals } = parseArgs({ args: rest, options: {}, allowPositionals: true });
+  const { positionals } = safeParseArgs({ args: rest, options: {}, allowPositionals: true });
   const [field, value] = positionals;
   const config = readValidConfigOrExit({ json: true });
   if (!field || value === undefined) {
@@ -588,11 +601,14 @@ function cmdSet(rest) {
 
 // ─── scan ────────────────────────────────────────────────────────────────────
 function cmdScan(rest) {
-  const { values } = parseArgs({
+  const { values } = safeParseArgs({
     args: rest,
     options: {
       project: { type: 'string' },
       'no-fetch': { type: 'boolean', default: false },
+      // Plan-table view: per release, commitCount instead of the commit list
+      // and diffstat; skippedTags collapsed to per-reason counts.
+      summary: { type: 'boolean', default: false },
       // scan always emits JSON; the flag is accepted so `scan --json` (as
       // SKILL.md spells it) is never a crash.
       json: { type: 'boolean', default: true },
@@ -600,19 +616,29 @@ function cmdScan(rest) {
     allowPositionals: false,
   });
   const config = readValidConfigOrExit({ json: true });
-  const result = scanAll(config, { projectKey: values.project || null, fetch: !values['no-fetch'] });
+  let result = scanAll(config, { projectKey: values.project || null, fetch: !values['no-fetch'] });
+  if (values.summary) result = summarizeScan(result);
+  // Which CLI actually ran: npx caches aggressively, and a stale install has
+  // silently missed shipped fixes before — the skill compares this against the
+  // version its own instructions shipped with.
+  if (!result.error) result.cliVersion = readPackageVersion();
   emitJSON(result, result.error ? 1 : 0);
 }
 
 // ─── lint-post ───────────────────────────────────────────────────────────────
 function cmdLintPost(rest) {
-  const { values, positionals } = parseArgs({
+  const { values, positionals } = safeParseArgs({
     args: rest,
-    options: { 'min-sources': { type: 'string' } },
+    options: {
+      'min-sources': { type: 'string' },
+      // Deterministic voice-contract rules (em dashes, banned phrases) —
+      // opt-in so non-voice callers and the eval harness keep their behavior.
+      voice: { type: 'boolean', default: false },
+    },
     allowPositionals: true,
   });
   const file = positionals[0];
-  if (!file) emitJSON({ error: 'missing-arg', message: 'Usage: devlog lint-post <file> [--min-sources N]' }, 2);
+  if (!file) emitJSON({ error: 'missing-arg', message: 'Usage: devlog lint-post <file> [--min-sources N] [--voice]' }, 2);
 
   let minSources;
   if (values['min-sources'] !== undefined) {
@@ -633,13 +659,13 @@ function cmdLintPost(rest) {
   } catch (e) {
     emitJSON({ error: 'unreadable', message: e.message }, 2);
   }
-  const result = lintPost(content, { minSources, filename: file });
+  const result = lintPost(content, { minSources, filename: file, voice: values.voice });
   emitJSON({ ...result, minSources }, result.ok ? 0 : 1);
 }
 
 // ─── publish-entry ───────────────────────────────────────────────────────────
 function cmdPublishEntry(rest) {
-  const { values } = parseArgs({
+  const { values } = safeParseArgs({
     args: rest,
     options: {
       clone: { type: 'string' },
@@ -677,6 +703,92 @@ function cmdPublishEntry(rest) {
   }
 }
 
+// ─── tombstone ───────────────────────────────────────────────────────────────
+// Editorially retire a (project, version) identity after its entry was moved,
+// consolidated, or deleted by hand — scan then reports `entry-tombstoned` and
+// publish-entry refuses it forever.
+function cmdTombstone(rest) {
+  const { values } = safeParseArgs({
+    args: rest,
+    options: {
+      clone: { type: 'string' },
+      project: { type: 'string' },
+      version: { type: 'string' },
+      reason: { type: 'string' },
+    },
+    allowPositionals: false,
+  });
+  for (const flag of ['clone', 'project', 'version', 'reason']) {
+    if (!values[flag]) emitJSON({ error: 'missing-flag', message: `tombstone requires --${flag}` }, 1);
+  }
+  try {
+    const result = tombstoneEntry({
+      cloneDir: expandHome(values.clone),
+      project: values.project,
+      version: values.version,
+      reason: values.reason,
+    });
+    emitJSON({ ok: true, ...result });
+  } catch (e) {
+    emitJSON({ error: 'tombstone-failed', message: e.message }, 1);
+  }
+}
+
+// ─── sync-entry ──────────────────────────────────────────────────────────────
+// Resync a published entry's manifest row (title/summary/date/tags) from its
+// .md frontmatter after a deliberate post-publish edit.
+function cmdSyncEntry(rest) {
+  const { values } = safeParseArgs({
+    args: rest,
+    options: {
+      clone: { type: 'string' },
+      project: { type: 'string' },
+      slug: { type: 'string' },
+    },
+    allowPositionals: false,
+  });
+  for (const flag of ['clone', 'project', 'slug']) {
+    if (!values[flag]) emitJSON({ error: 'missing-flag', message: `sync-entry requires --${flag}` }, 1);
+  }
+  try {
+    const result = syncEntryFromFrontmatter({
+      cloneDir: expandHome(values.clone),
+      project: values.project,
+      slug: values.slug,
+    });
+    emitJSON({ ok: true, ...result });
+  } catch (e) {
+    emitJSON({ error: 'sync-failed', message: e.message }, 1);
+  }
+}
+
+// ─── assemble-post ───────────────────────────────────────────────────────────
+// Extract a draft's fenced code blocks, in order, into numbered files so the
+// Step 4 assemble-and-run check is mechanical instead of hand-copied.
+function cmdAssemblePost(rest) {
+  const { values, positionals } = safeParseArgs({
+    args: rest,
+    options: { out: { type: 'string' } },
+    allowPositionals: true,
+  });
+  const file = positionals[0];
+  if (!file) emitJSON({ error: 'missing-arg', message: 'Usage: devlog assemble-post <draft> --out <dir>' }, 2);
+  if (!values.out) emitJSON({ error: 'missing-flag', message: 'assemble-post requires --out' }, 1);
+
+  let content;
+  try {
+    content = readFileSync(expandHome(file), 'utf8');
+  } catch (e) {
+    emitJSON({ error: 'unreadable', message: e.message }, 2);
+  }
+  try {
+    const result = writeAssembledBlocks(content, expandHome(values.out));
+    emitJSON({ ok: true, ...result });
+  } catch (e) {
+    emitJSON({ error: 'assemble-failed', message: e.message }, 1);
+  }
+}
+
 // ─── backfill-covers list ─────────────────────────────────────────────────────
 function cmdBackfillCovers(rest) {
   const sub = rest[0];
@@ -684,7 +796,7 @@ function cmdBackfillCovers(rest) {
     emitJSON({ error: 'unknown-subcommand', message: 'Usage: devlog backfill-covers list --clone <cloneDir> [--project <key>] [--out <staging-dir>] [--all]' }, 2);
     return;
   }
-  const { values } = parseArgs({
+  const { values } = safeParseArgs({
     args: rest.slice(1),
     options: {
       clone: { type: 'string' },
@@ -761,7 +873,7 @@ function cmdBackfillCovers(rest) {
 
 // ─── cover-context ─────────────────────────────────────────────────────────────
 function cmdCoverContext(rest) {
-  const { positionals, values } = parseArgs({
+  const { positionals, values } = safeParseArgs({
     args: rest,
     options: {
       clone: { type: 'string' },
@@ -826,7 +938,7 @@ function regenerateContactSheet(outDir) {
 }
 
 async function cmdRenderCover(rest) {
-  const { positionals, values } = parseArgs({
+  const { positionals, values } = safeParseArgs({
     args: rest,
     options: {
       project: { type: 'string' },
@@ -852,17 +964,21 @@ async function cmdRenderCover(rest) {
   mkdirSync(projectDir, { recursive: true });
   const pngPath = join(projectDir, `${values.slug}.png`);
 
-  // Idempotent re-run: an existing, valid PNG is left untouched — no re-render.
-  if (existsSync(pngPath) && isValidPngFile(pngPath)) {
-    regenerateContactSheet(outDir);
-    emitJSON({ ok: true, written: pngPath, rendered: false });
-    return;
-  }
-
+  // The HTML file is the source of truth: whenever it's present, render it —
+  // overwriting any stale PNG from a previous attempt. (The old
+  // PNG-exists short-circuit silently ignored freshly edited HTML, which cost
+  // every real retry loop an ls/mtime/md5 debugging dance and a guessed-at
+  // `--force` flag that didn't exist.) Only when the HTML is gone does an
+  // existing valid PNG mean "already rendered, nothing to do".
   let html;
   try {
     html = readFileSync(expandHome(htmlFile), 'utf8');
   } catch (e) {
+    if (existsSync(pngPath) && isValidPngFile(pngPath)) {
+      regenerateContactSheet(outDir);
+      emitJSON({ ok: true, written: pngPath, rendered: false });
+      return;
+    }
     emitJSON({ error: 'html-unreadable', message: e.message }, 1);
     return;
   }
@@ -878,9 +994,10 @@ async function cmdRenderCover(rest) {
   }
   writeFileSync(pngPath, png);
 
-  // Transient source document — deleted immediately after a successful render only.
-  try { unlinkSync(expandHome(htmlFile)); } catch { /* best-effort cleanup */ }
-
+  // The HTML source deliberately stays on disk (it lives in the run's scratch
+  // dir and dies with it): keeping it is what makes "tweak the HTML, re-run
+  // render-cover" work at all — deleting it on success broke every
+  // post-render Edit attempt in real runs.
   regenerateContactSheet(outDir);
   emitJSON({ ok: true, written: pngPath, rendered: true });
 }
@@ -1018,7 +1135,7 @@ async function cmdCommitCovers(rest) {
 
 // ─── config (view) ───────────────────────────────────────────────────────────
 async function cmdConfig(rest) {
-  const { values } = parseArgs({
+  const { values } = safeParseArgs({
     args: rest,
     options: { json: { type: 'boolean', default: false } },
     allowPositionals: false,
@@ -1137,12 +1254,17 @@ Setup & config:
   ${kleur.cyan('npx @natjswenson/devlog config [--json]')}          Show current config (with validation)
 
 Used by the /devlog skill:
-  ${kleur.cyan('npx @natjswenson/devlog scan [--project <key>]')}   JSON plan of new releases needing entries
-  ${kleur.cyan('npx @natjswenson/devlog lint-post <file>')}         Deterministic post-contract check
+  ${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('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
 
+Editorial maintenance:
+  ${kleur.cyan('npx @natjswenson/devlog tombstone --clone <dir> --project <key> --version <v> --reason <why>')}  Retire a moved/consolidated entry's identity
+  ${kleur.cyan('npx @natjswenson/devlog sync-entry --clone <dir> --project <key> --slug <v>')}  Resync a manifest row from an edited entry's frontmatter
+
 Backfilling covers onto existing posts:
   ${kleur.cyan('npx @natjswenson/devlog backfill-covers list --clone <dir> [--out <staging-dir>]')}  List posts missing a cover
   ${kleur.cyan('npx @natjswenson/devlog commit-covers <staging-dir> [--force [slug]]')}  Publish staged covers to already-published entries
@@ -1196,6 +1318,15 @@ if (isMain) {
     case 'publish-entry':
       cmdPublishEntry(rest);
       break;
+    case 'tombstone':
+      cmdTombstone(rest);
+      break;
+    case 'sync-entry':
+      cmdSyncEntry(rest);
+      break;
+    case 'assemble-post':
+      cmdAssemblePost(rest);
+      break;
     case 'backfill-covers':
       cmdBackfillCovers(rest);
       break;

package/examples/react/useDevLogEntries.js

@@ -34,6 +34,8 @@ function validateManifest(data) {
   const entries = [];
   for (const e of data.entries) {
     if (!e || typeof e !== 'object') continue;
+    // Tombstoned rows (removed: true) are editorial retirements, not entries.
+    if (e.removed) continue;
     const { date, file, title, summary, version } = e;
     if (typeof date !== 'string' || !/^\d{4}-\d{2}-\d{2}$/.test(date)) continue;
     if (typeof file !== 'string' || !/^[a-zA-Z0-9._-]+\.md$/.test(file)) continue;

package/image-style/icons.md

@@ -2,8 +2,9 @@
 
 Twenty small, secondary/accent icons — **never the hero illustration itself**. Each is a
 real inline SVG, 24×24 viewBox, stroke-only (`stroke="currentColor" fill="none"`), so it
-recolors for free via CSS `color: #ededed` or `color: #fff503` (the accent yellow) —
-never `fill`. Wrap every usage in a container carrying `data-catalog-icon="<name>"`
+recolors for free via CSS `color: #181510` (ink) or `color: #6E675C` (dim) — never
+`fill`, and never the signature orange: per the style guide, the accent icon is
+structure, not the cover's one loud moment. Wrap every usage in a container carrying `data-catalog-icon="<name>"`
 (the exact `<name>` from the table below) — `render-cover`'s geometry guard reads this
 attribute to confirm no catalog icon has drifted into the hero zone.
 

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

@@ -36,8 +36,9 @@ Before writing any HTML, do this thinking step explicitly:
    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, in the spirit of an editorial
-   illustration or a technical diagram, using only the palette below.
+   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.
 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.
@@ -55,10 +56,32 @@ element with `id="hero-zone"` at exactly this position and size — `render-cove
 mechanically checks the rendered `#hero-zone` rect against these numbers (within a 2px
 tolerance for subpixel rounding) and refuses to render if it doesn't match, or if
 `#hero-zone` is missing or duplicated. This is a hard requirement, not a suggestion —
-every post's hero renders inside the identical box so covers stay comparable.
+every post's hero renders inside the identical box so covers stay comparable. It is also a
+convenient coincidence worth using: the box's 150px left/right insets are the same
+outer margin the masthead and headline above it should sit inside, so the hero zone, the
+eyebrow row, and the headline all line up on one shared left edge.
 
 Every key point of the hero shape you draw *inside* `#hero-zone` should snap to a 25px coordinate grid (this is prose guidance, not mechanically checked — the guard verifies the outer box only) — pick coordinates as multiples of 25px from `#hero-zone`'s own top-left corner. This fixes near-misses and uneven spacing; it does not mean the shapes themselves must be simple, only that their key points land on a consistent rhythm.
 
+**Fill the zone — this is not optional.** `render-cover` only checks the outer `#hero-zone` box; nothing mechanically stops you from drawing something small inside a mostly-empty rectangle, so this rule is on you, checkable by eye. The illustration's own ink — the actual bounding box of the shapes you draw, not the container — must cover at least 70% of the zone's 1300px width and at least 60% of its 400px height. A thin horizontal band of marks sitting low in the zone, with a large empty margin above it, is a specific and common failure: it reads as top-heavy — headline, then a dead void, then a sliver of drawing — rather than as one composed image. Distribute the drawing's mass across the zone's full height, not just its width: let elements reach toward both y:0 and y:400 of the zone's own coordinate space (labels, connecting lines, secondary marks all count), not cluster near one edge.
+
+**Bridge a short headline — the band above the zone is yours to fill.** The hero zone
+starts at a fixed `y:425` no matter how tall the headline is. A two-line headline ends
+near `y:270` and leaves a comfortable ~155px of paper; a **one-line headline ends near
+`y:215` and leaves ~210px of dead air** that no amount of good drawing inside the zone
+can close — the cover reads as a headline, a void, then an unrelated diagram. When your
+headline renders on one line, you must bridge that band. In order of preference:
+- a **standfirst** — one serif-italic line behind a 5px orange left rule, restating the
+  mechanism in plain words (this is the PRESS `.stand`, and it is the best answer);
+- a **ledger strip** — two or three mono `label · value` pairs on one row, over a 2px ink
+  rule, carrying real numbers from `## Shipped`;
+- letting the illustration's own **labels or axis titles** rise into the band, so the
+  drawing visually begins before the zone does.
+
+Never leave the band empty under a one-line headline. Whitespace is part of the brand
+only when it's *between* composed elements — a gap with nothing on either side of it is
+just a hole.
+
 **Two named composition slots** — pick one per post:
 - **Single centered hero** — one freehand mechanism, nothing else, inside the hero zone.
 - **Two-node before/after** — a left node, a right node, and a connecting line, all
@@ -68,12 +91,20 @@ Every key point of the hero shape you draw *inside* `#hero-zone` should snap to
 These are placement/proportion guidance, not literal templates — the actual shapes
 inside each slot are still freehand per post.
 
+**A third option, when the post is genuinely about code or a terminal session:** the
+`.term` panel treatment (see Palette below) may fill some or all of `#hero-zone` instead
+of a freehand mechanism — a real, believable command/output snippet drawn from the
+`## Shipped` text, not invented. This is the one place the old dark palette survives, and
+only here: never let the dark panel bleed to the canvas edges — keep at least the same
+25px-grid margin of paper visible around it inside the hero zone so it reads as an object
+floating on the page, not a background.
+
 **Catalog icons are never placed inside `#hero-zone`, in either slot.** The mechanism
 and both two-node shapes are always freehand SVG you draw yourself. A catalog icon
 (`image-style/icons.md`) may only appear as a small accent glyph in the kicker/title
 area, entirely outside the hero zone.
 
-**Optional kicker-area accent icon.** Independent of which of the two slots you picked, you may add one small accent glyph near the kicker/title area — either a catalog icon (`image-style/icons.md`) or a terminal/code aesthetic glyph (`$`, `>`, `//`, brackets). Never combine the catalog-icon accent and the terminal-glyph accent in the same cover.
+**Optional kicker-area accent icon — anchored, never floating.** Independent of which of the two slots you picked, you may add one small accent glyph near the kicker/title area — either a catalog icon (`image-style/icons.md`) or a terminal/code aesthetic glyph (`$`, `>`, `//`, brackets). It needs a defined home: sit it directly against the eyebrow row, baseline-aligned, immediately before or after the eyebrow text, so it reads as part of that line rather than a shape adrift in empty space. If there's nowhere for it to attach this cleanly, leave it out — an omitted accent icon is a better cover than a floating one, which is exactly why this element is optional. Never combine the catalog-icon accent and the terminal-glyph accent in the same cover. Color it ink or dim (`#181510` / `#6E675C`), never the signature orange — the accent icon is a small piece of structure, not the cover's one loud moment.
 
 If you use a catalog-icon accent, it must be positioned with its bottom edge no lower than y:400 — a 25px buffer above the hero zone's y:425 top edge — so it can never clip into the hero zone and trip the geometry guard.
 
@@ -87,8 +118,15 @@ For the two-node slot specifically: the accent icon's presence must not be read
   simply never captured, so keep everything inside it.
 - Reference the bundled font only by its fixed name, with a fallback:
   `font-family: 'DevlogCoverFont', sans-serif;` — never embed font bytes yourself, never
-  reference any other font file. The renderer injects the real font after your markup is
-  parsed.
+  reference any other font file. The renderer injects the real font (a monospace face)
+  after your markup is parsed. **This is the only font whose bytes are ever loaded** — but
+  it is not the only font-family value you're allowed to write. The Typography section
+  below asks for a serif voice and a display voice as well; get those from this rendering
+  host's own built-in system fonts (`Georgia`, `ui-serif`, `-apple-system`, generic
+  `serif`/`sans-serif`), the same way the `sans-serif` fallback above already works before
+  `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
@@ -96,25 +134,98 @@ For the two-node slot specifically: the accent icon's presence must not be read
 
 ## Visual direction
 
-The site (natejswenson.com) is a minimalist, monospace, terminal-styled dev log. Covers
-should feel like they belong to the same publication as the site itself — technical
-editorial illustrations, not marketing graphics and not a repeated template:
-
-- **Palette:** background `#0a0a0b` (near-black), foreground/line-art color `#ededed`,
-  secondary/dim `#8a8a8a`, one accent color `#fff503` (yellow) for the single most
-  important element of the illustration — the thing being emphasized, not a decoration.
-  Prefer 2-3 colors on a page (black, white, one accent), not a rainbow. Prefer flat,
-  limited color and solid/line fills over large smooth gradients — the render is
-  compressed with lossy PNG palette quantization afterward, and gradients band visibly
-  under that compression while flat fills don't.
-- **Typography:** `'DevlogCoverFont'` (a monospace face) for any on-image text — kicker,
-  title, date. Keep the title modest in size (it is not the main event); a short kicker
-  (project + date) is enough context. Terminal/code aesthetic glyphs (`$`, `>`, `//`,
-  brackets) are fair game as small accents, not as the illustration itself.
-- **Composition:** the illustration occupies the dominant visual weight of the canvas —
-  centered or offset to one side, large enough to read at a glance, with the
-  title/kicker in the remaining negative space (not overlapping the artwork). Plenty of
-  breathing room around the illustration; don't crowd it with text or decoration.
+The site (natejswenson.com) runs on **PRESS** — a warm-paper editorial-poster brand:
+huge black type, a serif standfirst voice, one loud signature accent, heavy ink rules, and
+a personal monogram stamp. Covers should read as an issue of the same publication as the
+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.
+
+### The accent law, carried to covers
+
+Orange is a signature, not a color scheme. On one cover it may appear as:
+- the **stamp** (border + `NS` letters) — always, every cover.
+- **at most one pivot phrase** inside the headline (`<span>` colored orange) — optional,
+  use it when one word or short phrase is genuinely the point. **Cap it at two words.** A
+  three-or-more-word orange run stops reading as a pivot and starts reading as a second
+  headline, and it eats the budget the illustration needs. If the point can't be made in
+  two words, leave the headline entirely ink and let the drawing carry the signature.
+- **at most one orange element in the illustration, and only one of these two kinds:**
+  either a *fill* (one payoff bar, one win-state shape) or *thin marks* (a cap line, a
+  pivot tick, a labelled dot) — never both, and never a fill larger than the payoff itself.
+  Count the headline pivot against this too: a cover with an orange pivot phrase AND a
+  large orange fill is over budget. One loud thing per cover, plus the stamp.
+- **a numeral, only if it's real.** If the `## Shipped` text hands you an actual number
+  worth calling out (a count, a duration, a percentage), it may run in orange, large. Never
+  invent a sequential "No. 042"-style issue number to fill an eyebrow — devlog doesn't
+  pass covers a real published-count field the way the site's own pages do, and a
+  fabricated one is exactly the ornamental-prop failure mode in Never do, below.
+- **thin marks or rules inside the illustration** — sparing use, one or two strokes, never
+  a fill.
+- **`.hot` lines inside a `.term` panel** — panel-internal, doesn't count against the
+  budget above.
+
+Everything else is ink, or dim for secondary weight. If you're not sure whether something
+should be orange, it should be ink — when orange shows up as the fill of three different
+shapes, the badge, and the border all on one cover, it stops being a signature and starts
+being a rainbow.
+
+### Typography — three voices
+
+Match the site's own split: **display** = structure (headline, eyebrow, numerals, labels),
+**serif italic** = commentary (a short standfirst/caption, if you use one), **mono** =
+data (dates, tags, terminal text, inline code).
+
+| Role | Font stack | Notes |
+|---|---|---|
+| Headline, eyebrow, numerals, labels, stamp letters | `-apple-system, BlinkMacSystemFont, 'Segoe UI', Arial, sans-serif` | weight 800–900, tight tracking (`-0.02em` to `-0.03em` on the headline) |
+| Standfirst / caption (optional, ≤1 short line) | `Georgia, 'Times New Roman', ui-serif, serif`, italic | secondary ink or dim |
+| Dates, tags, terminal/code text | `'DevlogCoverFont', ui-monospace, 'SF Mono', Menlo, monospace` | the injected font is a monospace face, so this voice is where it actually renders as intended; everything else falls back to a system font gracefully |
+
+Keep the title modest — it is not the main event, the illustration is. A short kicker
+(project name, plus a date if you know it) is enough context; don't restate the whole
+summary as on-image text.
+
+### Composition
+
+- The illustration occupies the dominant visual weight of the canvas — inside `#hero-zone`,
+  large enough to read at a glance, with the masthead/headline in the negative space above
+  it (never overlapping the artwork).
+- Masthead row near the top: a small stamp (a square, ~2.5–3px orange border, `NS`
+  in orange, `transform: rotate(-4deg)`) plus an eyebrow — the project name in tracked
+  caps, ink. A heavy ink rule (6–8px) above this row, matching the site's own page-frame
+  weight, reads as the cover's top edge.
+- Headline below the masthead, ink, up to two lines, sized to leave real air above
+  `#hero-zone` — don't let it crowd down into the illustration's territory.
+- Optional thin ink rule (2px) at the very bottom of the canvas, under `#hero-zone`, is a
+  fine way to close the composition the way the site's own colophon closes a page — skip
+  it if the illustration already reads as complete without one; it's a finishing touch,
+  not a required element.
+- **A caption, if you use one, anchors to the drawing, not to the canvas margin.** Center
+  it under the illustration's own visual mass, or align it flush to one edge of the
+  drawing's actual bounding box — never park it at the hero zone's left inset independent
+  of where the artwork itself sits. A caption is a caption *for* the drawing; its position
+  should say so, and it exists to reinforce a concept the drawing already communicates on
+  its own, not to explain a drawing that doesn't communicate anything by itself.
+- Breathing room belongs between the composed image and the canvas edges, and between the
+  image and the masthead/headline above it — not inside the hero zone as empty space
+  around an undersized drawing. Don't crowd the composition with unrelated text or
+  decoration; do fill the zone the drawing is given (see the fill requirement above).
 - **Restraint in execution, not in ambition:** the illustration should be a real, specific
   scene (multiple shapes composed together to depict one concept), not a single
   primitive. But avoid clutter — every shape in the illustration should serve the one
@@ -131,8 +242,34 @@ editorial illustrations, not marketing graphics and not a repeated template:
 - Don't fall back to a generic circle/square/checkmark/arrow when stuck — that's the
   exact failure mode this guide exists to prevent. Spend the extra step finding the
   concrete mechanism the post describes.
-- Don't use a gradient as a full-bleed background.
+- Don't draw a row of repeated, near-identical marks along one baseline — a tick row, a
+  barcode, evenly spaced dashes — as the whole illustration. It reads as a barcode, not a
+  concept. A reader must be able to infer the concept from the shapes and their
+  arrangement alone, before reading any caption; if the caption is doing the work of
+  explaining what the drawing is, the drawing failed, and adding a caption to compensate
+  doesn't fix it.
+- Don't leave the hero zone mostly empty around a small drawing. `render-cover` only
+  checks the outer `#hero-zone` box, not what's inside it, so a thin band of marks in an
+  otherwise bare 1300×400 area passes the mechanical check and still fails this guide —
+  see the fill requirement in Hero-zone grid contract.
+- Don't let the kicker-area accent icon float in empty space with nothing beside it —
+  anchor it to the eyebrow line, or leave it out entirely.
+- Don't use a gradient as a full-bleed background, and don't add grain, noise, torn
+  edges, fold lines, or any texture overlay — the paper is a flat hex, not a vintage
+  poster prop.
+- Don't round any corner or drop any shadow, on the illustration or anywhere else on the
+  cover — PRESS structure comes from rules and whitespace, never rounded chrome.
+- Don't let orange spread across the cover — one signature moment (see The accent law),
+  never orange as a fill color for multiple shapes, never a background wash.
+- Don't set the headline, eyebrow, or numerals in the serif voice — that voice is for
+  commentary only; structure is always the display face.
+- Don't invent editorial props that aren't backed by real data: no fabricated issue
+  numbers, no barcodes, no pull-quotes that aren't an actual quote from the post.
+- Don't leave old terminal furniture lying around outside a `.term` panel — no blinking
+  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.
-- Don't reference any font other than `'DevlogCoverFont'` (with its `sans-serif`
-  fallback).
+- 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.