npm - @natjswenson/devlog - Versions diffs - 0.8.1 → 0.10.0 - Mend

@natjswenson/devlog 0.8.1 → 0.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (13) hide show

package/SKILL.md +46 -18
package/bin/devlog.js +19 -6
package/image-style/icons.md +235 -0
package/image-style/style-guide.example.md +194 -26
package/lib/config_ops.mjs +1 -0
package/lib/core.mjs +12 -0
package/lib/cover_gen.mjs +20 -7
package/lib/migrate_entry_numbers.mjs +116 -0
package/lib/publish_entry.mjs +46 -2
package/lib/render_cover.mjs +99 -4
package/lib/scan.mjs +7 -3
package/package.json +1 -1
package/skill-invariants.json +10 -2

package/SKILL.md CHANGED Viewed

@@ -41,7 +41,11 @@ Map the user's request onto the CLI — never hand-edit `config.json`:
 | Show config | `npx -y @natjswenson/devlog config --json` |
 | Add a project | `npx -y @natjswenson/devlog 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 remove-project <key> --yes` |
-| Change a setting | `npx -y @natjswenson/devlog set <field> <value>` (settable: `targetRepo`, `branch`, `gitAuthor`, `githubUser`, `voicePath`, `deepDive.minSources`, `deepDive.topicDomains`) |
+| Change a setting | `npx -y @natjswenson/devlog set <field> <value>` (settable: `targetRepo`, `branch`, `targetDir`, `gitAuthor`, `githubUser`, `voicePath`, `deepDive.minSources`, `deepDive.topicDomains`) |
+`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 ''`.
 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
@@ -291,8 +295,13 @@ critique, not a rubber stamp.
 ### Step 5: Publish
-Clone once, publish each entry through the CLI, push once. `targetRepo` and `branch` come
-from validated config — still single-quote every interpolated value.
+Clone once, publish each entry through the CLI, push once. `targetRepo`, `branch`, and
+`targetDir` come from validated config (all echoed in the scan output) — still
+single-quote every interpolated value.
+The `--clone` flag always points at the CONTENT ROOT: `<abs-tmp>/<repo-name>` when
+`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,
@@ -301,30 +310,44 @@ rasterized locally, never sent to any external service:
 ```bash
 mktemp -d    # → record the absolute path, e.g. /var/folders/.../tmp.abc
 git -C '<abs-tmp>' clone --depth=1 'https://github.com/<targetRepo>.git'
+# <content-root> = '<abs-tmp>/<repo-name>/<targetDir>' if targetDir is set,
+#                  '<abs-tmp>/<repo-name>' otherwise.
 # Per release (refuses to overwrite an existing entry — on {"error": ...,
 # "message": "... immutable ..."} skip that release and note it):
 # 1. Style guide + up to 3 reference images of recently published covers.
 npx -y @natjswenson/devlog cover-context '<key>' '<version>' \
-  --clone '<abs-tmp>/<repo-name>'
+  --clone '<content-root>'
 # On {"error": "style-guide-missing", ...}: skip cover composition for this release
 # entirely — proceed straight to publish-entry with no --cover flag. Never block
 # publish on a missing style guide.
 # 2. Compose the cover using ONLY this release's title/tags/summary/`## Shipped` text
-#    (never the raw draft file, never `## Changelog`) plus the returned style guide and
-#    reference images. 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, sized as the
-#    dominant visual element of the canvas; title/kicker stay secondary. Two different
-#    releases should never produce visually similar covers — see the style guide's "one
-#    custom illustration per post" section before composing. Write the result with the
-#    Write tool to '<abs-scratch>/<key>/<version>.html' — a full document starting with
-#    `<!DOCTYPE html>`, sized `html, body { margin:0; width:1600px; height:900px; }`,
-#    referencing the bundled font only as `font-family: 'DevlogCoverFont', sans-serif`.
-# 3. Rasterize it. On failure (render timeout / Chromium not installed / font missing),
+#    (never the raw draft file, never `## Changelog`) plus the returned style guide,
+#    icon catalog, and reference images. 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, sized as the dominant visual element of the canvas; title/kicker stay
+#    secondary. Two different releases should never produce visually similar covers.
+#
+#    Draw the illustration inside a `#hero-zone` container at exactly
+#    `x:150 y:425 width:1300 height:400` (render-cover mechanically checks this box and
+#    refuses to render otherwise) — pick ONE of two composition slots per post: single
+#    centered hero (one freehand mechanism, nothing else), or two-node before/after (a
+#    left node, a right node, a connecting line, all freehand). Snap interior key points
+#    to a 25px coordinate grid. Catalog icons (image-style/icons.md) are never placed
+#    inside `#hero-zone` — they may only appear as an optional small accent glyph near
+#    the kicker/title area, entirely outside the hero zone, its bottom edge no lower than
+#    y:400. See the style guide's hero-zone grid contract section before composing.
+#    Write the result with the Write tool to '<abs-scratch>/<key>/<version>.html' — a
+#    full document starting with `<!DOCTYPE html>`, sized
+#    `html, body { margin:0; width:1600px; height:900px; }`, referencing the bundled
+#    font only as `font-family: 'DevlogCoverFont', sans-serif`.
+# 3. Rasterize it. On failure (render timeout / Chromium not installed / font missing /
+#    a #hero-zone problem — missing, duplicate, wrong position/size, or a catalog icon
+#    overlapping it),
 #    the .html is left in place for debugging — retry composing once with the error text
 #    fed back, or give up and proceed with no --cover flag.
 npx -y @natjswenson/devlog render-cover '<abs-scratch>/<key>/<version>.html' \
@@ -334,7 +357,7 @@ npx -y @natjswenson/devlog render-cover '<abs-scratch>/<key>/<version>.html' \
 # the prose.
 npx -y @natjswenson/devlog publish-entry \
-  --clone '<abs-tmp>/<repo-name>' --project '<key>' \
+  --clone '<content-root>' --project '<key>' \
   --version '<version>' --entry '<abs-draft-path>' \
   --cover '<abs-scratch>/<key>/<version>.png'
 # Omit --cover entirely if no cover was produced for this release (missing style guide,
@@ -356,9 +379,14 @@ Release dev log entries published
   Project: <key>
   Releases: <version>, ...
   Judged weaknesses: <residuals from Step 4, or "none">
-  URL: https://github.com/<targetRepo>/blob/<branch>/<key>/<version>.md
+  URL: 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.
 ## Security rules
 The CLI validates all config fields and excludes unsafe tag names before they reach you,

package/bin/devlog.js CHANGED Viewed

@@ -423,6 +423,12 @@ async function cmdInit() {
     copyFileSync(fontSrc, fontDest);
     log.ok(`Installed image-style/font.ttf → ${fontDest}`);
   }
+  const iconsSrc = join(IMAGE_STYLE_SRC_DIR, 'icons.md');
+  const iconsDest = join(IMAGE_STYLE_DEST_DIR, 'icons.md');
+  if (existsSync(iconsSrc) && (await confirmOverwrite('image-style/icons.md', iconsDest))) {
+    copyFileSync(iconsSrc, iconsDest);
+    log.ok(`Installed image-style/icons.md → ${iconsDest}`);
+  }
   // Cover-generation reachability checks. Informational only — neither failure blocks
   // setup, since a missing Chromium/font only affects cover generation, not the rest of
@@ -675,7 +681,7 @@ function cmdPublishEntry(rest) {
 function cmdBackfillCovers(rest) {
   const sub = rest[0];
   if (sub !== 'list') {
-    emitJSON({ error: 'unknown-subcommand', message: 'Usage: devlog backfill-covers list --clone <cloneDir> [--project <key>] [--out <staging-dir>]' }, 2);
+    emitJSON({ error: 'unknown-subcommand', message: 'Usage: devlog backfill-covers list --clone <cloneDir> [--project <key>] [--out <staging-dir>] [--all]' }, 2);
     return;
   }
   const { values } = parseArgs({
@@ -684,6 +690,7 @@ function cmdBackfillCovers(rest) {
       clone: { type: 'string' },
       project: { type: 'string' },
       out: { type: 'string' },
+      all: { type: 'boolean', default: false },
     },
     allowPositionals: false,
   });
@@ -699,8 +706,11 @@ function cmdBackfillCovers(rest) {
     return;
   }
+  // Default (no --all): missing-cover-only, this command's original purpose. With --all,
+  // every manifest entry qualifies regardless of cover status — what a cover-quality
+  // backfill needs, since every real entry already has cover: true from a prior batch.
   let candidates = merged
-    .filter((e) => e && !e.cover)
+    .filter((e) => e && (values.all || !e.cover))
     .map((e) => ({ ...e, _slug: slugFromFile(e.file) }));
   if (values.project) {
@@ -767,9 +777,12 @@ function cmdCoverContext(rest) {
   const config = readValidConfigOrExit({ json: true });
-  let styleGuide;
+  // `let`, declared outside both try blocks below — NOT `const` inside the first one.
+  // Both blocks' emitJSON calls need text/iconCatalog, and a `const` destructure scoped to
+  // the first try alone would leave them unreachable (a ReferenceError) inside the second.
+  let text, iconCatalog;
   try {
-    styleGuide = loadStyleGuide();
+    ({ text, iconCatalog } = loadStyleGuide());
   } catch (e) {
     emitJSON({ error: 'style-guide-missing', message: e.message }, 1);
     return;
@@ -782,12 +795,12 @@ function cmdCoverContext(rest) {
       stagingDir: values.staging ? expandHome(values.staging) : null,
       n: 3,
     });
-    emitJSON({ styleGuide, references });
+    emitJSON({ styleGuide: text, references, iconCatalog });
   } catch (e) {
     // A configured project's manifest.json missing/unparseable: distinct, named error
     // field — never collapsed into an empty references: [] array — but still does not
     // block the rest of publish for the caller.
-    emitJSON({ styleGuide, references: [], error: 'reference-lookup-failed', message: e.message });
+    emitJSON({ styleGuide: text, references: [], error: 'reference-lookup-failed', message: e.message, iconCatalog });
   }
 }

package/image-style/icons.md ADDED Viewed

@@ -0,0 +1,235 @@
+# Cover icon catalog
+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: #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.
+**These are for the kicker-area accent glyph only** (see `style-guide.md`'s hero-zone
+grid contract) — never for the hero illustration's own mechanism/nodes, which are always
+freehand SVG the agent draws itself. Look up a concept below instead of re-deriving an
+icon from scratch; if a post's concept doesn't map cleanly to any of these 20, that's a
+signal the post doesn't need an accent icon at all (a terminal-glyph accent or no accent
+is always a valid choice — see `style-guide.md`).
+## Topic → icon cheat sheet
+| Topic / keywords in title or summary | Icon |
+|---|---|
+| agent, LLM, Claude, subagent, prompt | `agents` |
+| test, testing, assert, spec, coverage | `testing` |
+| CI, CD, pipeline, workflow, build | `ci-cd` |
+| git, commit, branch, merge, tag | `git` |
+| a11y, accessibility, aria, screen reader | `accessibility` |
+| debug, bug, fix, root cause, trace | `debugging` |
+| CLI, command, terminal, flag, argv | `cli` |
+| config, settings, options, flags | `config` |
+| deploy, release, ship, publish, rollout | `deploy` |
+| database, manifest, schema, storage | `database` |
+| API, endpoint, request, response | `api` |
+| search, filter, query, lookup | `search` |
+| auth, login, token, credential, permission | `auth` |
+| monitor, metric, telemetry, dashboard | `monitoring` |
+| cover, image, render, screenshot, thumbnail | `cover-image` |
+| performance, speed, latency, throughput | `performance` |
+| parse, parser, tokenize, frontmatter | `parsing` |
+| cache, staging, memoize, invalidate | `caching` |
+| UI, layout, component, page, nav | `ui` |
+| network, remote, fetch, clone, push/pull | `networking` |
+## Icons
+### `agents`
+```svg
+<svg viewBox="0 0 24 24" stroke="currentColor" fill="none" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round">
+  <rect x="5" y="8" width="14" height="11" rx="2"/>
+  <line x1="12" y1="8" x2="12" y2="4"/>
+  <circle cx="12" cy="3" r="1"/>
+  <circle cx="9" cy="13" r="1.2"/>
+  <circle cx="15" cy="13" r="1.2"/>
+  <line x1="9" y1="17" x2="15" y2="17"/>
+</svg>
+```
+### `testing`
+```svg
+<svg viewBox="0 0 24 24" stroke="currentColor" fill="none" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round">
+  <rect x="4" y="4" width="16" height="16" rx="2"/>
+  <polyline points="8,12.5 11,15.5 16,9"/>
+</svg>
+```
+### `ci-cd`
+```svg
+<svg viewBox="0 0 24 24" stroke="currentColor" fill="none" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round">
+  <circle cx="4.5" cy="12" r="2"/>
+  <circle cx="12" cy="12" r="2"/>
+  <circle cx="19.5" cy="12" r="2"/>
+  <line x1="6.5" y1="12" x2="10" y2="12"/>
+  <line x1="14" y1="12" x2="17.5" y2="12"/>
+  <polyline points="15.5,10 17.5,12 15.5,14"/>
+</svg>
+```
+### `git`
+```svg
+<svg viewBox="0 0 24 24" stroke="currentColor" fill="none" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round">
+  <circle cx="6" cy="6" r="2"/>
+  <circle cx="6" cy="18" r="2"/>
+  <circle cx="18" cy="10" r="2"/>
+  <line x1="6" y1="8" x2="6" y2="16"/>
+  <path d="M6 8 C6 10, 8 10, 12 10 S18 10, 18 12"/>
+</svg>
+```
+### `accessibility`
+```svg
+<svg viewBox="0 0 24 24" stroke="currentColor" fill="none" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round">
+  <circle cx="12" cy="12" r="9"/>
+  <circle cx="12" cy="7.5" r="1.4"/>
+  <line x1="7" y1="11" x2="17" y2="11"/>
+  <line x1="12" y1="11" x2="12" y2="15"/>
+  <line x1="12" y1="15" x2="9" y2="18.5"/>
+  <line x1="12" y1="15" x2="15" y2="18.5"/>
+</svg>
+```
+### `debugging`
+```svg
+<svg viewBox="0 0 24 24" stroke="currentColor" fill="none" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round">
+  <rect x="8" y="8" width="8" height="10" rx="4"/>
+  <line x1="12" y1="4" x2="12" y2="8"/>
+  <line x1="6" y1="10" x2="8" y2="11"/>
+  <line x1="6" y1="14" x2="8" y2="14"/>
+  <line x1="6" y1="18" x2="8" y2="17"/>
+  <line x1="18" y1="10" x2="16" y2="11"/>
+  <line x1="18" y1="14" x2="16" y2="14"/>
+  <line x1="18" y1="18" x2="16" y2="17"/>
+</svg>
+```
+### `cli`
+```svg
+<svg viewBox="0 0 24 24" stroke="currentColor" fill="none" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round">
+  <rect x="3" y="4" width="18" height="16" rx="2"/>
+  <polyline points="7,10 10,12.5 7,15"/>
+  <line x1="12" y1="15" x2="16" y2="15"/>
+</svg>
+```
+### `config`
+```svg
+<svg viewBox="0 0 24 24" stroke="currentColor" fill="none" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round">
+  <circle cx="12" cy="12" r="3"/>
+  <path d="M12 3v2.2M12 18.8V21M3 12h2.2M18.8 12H21M5.6 5.6l1.5 1.5M16.9 16.9l1.5 1.5M18.4 5.6l-1.5 1.5M7.1 16.9l-1.5 1.5"/>
+</svg>
+```
+### `deploy`
+```svg
+<svg viewBox="0 0 24 24" stroke="currentColor" fill="none" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round">
+  <line x1="12" y1="19" x2="12" y2="6"/>
+  <polyline points="6,12 12,6 18,12"/>
+  <line x1="5" y1="20" x2="19" y2="20"/>
+</svg>
+```
+### `database`
+```svg
+<svg viewBox="0 0 24 24" stroke="currentColor" fill="none" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round">
+  <ellipse cx="12" cy="6" rx="7" ry="2.5"/>
+  <path d="M5 6v12c0 1.4 3.1 2.5 7 2.5s7-1.1 7-2.5V6"/>
+  <path d="M5 12c0 1.4 3.1 2.5 7 2.5s7-1.1 7-2.5"/>
+</svg>
+```
+### `api`
+```svg
+<svg viewBox="0 0 24 24" stroke="currentColor" fill="none" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round">
+  <polyline points="9,5 3,12 9,19"/>
+  <polyline points="15,5 21,12 15,19"/>
+</svg>
+```
+### `search`
+```svg
+<svg viewBox="0 0 24 24" stroke="currentColor" fill="none" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round">
+  <circle cx="10.5" cy="10.5" r="6"/>
+  <line x1="15" y1="15" x2="20" y2="20"/>
+</svg>
+```
+### `auth`
+```svg
+<svg viewBox="0 0 24 24" stroke="currentColor" fill="none" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round">
+  <rect x="5" y="11" width="14" height="9" rx="2"/>
+  <path d="M8 11V7a4 4 0 0 1 8 0v4"/>
+  <circle cx="12" cy="15" r="1.3"/>
+</svg>
+```
+### `monitoring`
+```svg
+<svg viewBox="0 0 24 24" stroke="currentColor" fill="none" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round">
+  <polyline points="3,14 8,14 10,8 14,18 16,14 21,14"/>
+</svg>
+```
+### `cover-image`
+```svg
+<svg viewBox="0 0 24 24" stroke="currentColor" fill="none" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round">
+  <rect x="3" y="5" width="18" height="14" rx="2"/>
+  <circle cx="8.5" cy="10" r="1.5"/>
+  <polyline points="4,17 9,12 13,16 16,13 20,17"/>
+</svg>
+```
+### `performance`
+```svg
+<svg viewBox="0 0 24 24" stroke="currentColor" fill="none" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round">
+  <path d="M4 16a8 8 0 0 1 16 0"/>
+  <line x1="12" y1="16" x2="16" y2="10.5"/>
+  <circle cx="12" cy="16" r="1"/>
+</svg>
+```
+### `parsing`
+```svg
+<svg viewBox="0 0 24 24" stroke="currentColor" fill="none" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round">
+  <path d="M9 4c-2 0-3 1-3 3v3c0 1-1 2-2 2 1 0 2 1 2 2v3c0 2 1 3 3 3"/>
+  <path d="M15 4c2 0 3 1 3 3v3c0 1 1 2 2 2-1 0-2 1-2 2v3c0 2-1 3-3 3"/>
+</svg>
+```
+### `caching`
+```svg
+<svg viewBox="0 0 24 24" stroke="currentColor" fill="none" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round">
+  <rect x="5" y="4" width="14" height="4.5" rx="1"/>
+  <rect x="5" y="9.75" width="14" height="4.5" rx="1"/>
+  <rect x="5" y="15.5" width="14" height="4.5" rx="1"/>
+</svg>
+```
+### `ui`
+```svg
+<svg viewBox="0 0 24 24" stroke="currentColor" fill="none" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round">
+  <rect x="3" y="4" width="18" height="16" rx="2"/>
+  <line x1="3" y1="8.5" x2="21" y2="8.5"/>
+  <line x1="8" y1="4" x2="8" y2="8.5"/>
+</svg>
+```
+### `networking`
+```svg
+<svg viewBox="0 0 24 24" stroke="currentColor" fill="none" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round">
+  <circle cx="12" cy="5" r="2"/>
+  <circle cx="5" cy="18" r="2"/>
+  <circle cx="19" cy="18" r="2"/>
+  <line x1="12" y1="7" x2="5" y2="16"/>
+  <line x1="12" y1="7" x2="19" y2="16"/>
+  <line x1="7" y1="18" x2="17" y2="18"/>
+</svg>
+```

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

@@ -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.
@@ -48,6 +49,67 @@ that's a sign to go back to step 2 and find the more specific concept — a post
 retrying a flaky network call and a post about deduplicating bank transactions should not
 end up with the same shape family.
+## Hero-zone grid contract
+The hero illustration renders inside a fixed bounding box: `x:150 y:425 width:1300 height:400` on the 1600×900 canvas (below the kicker/title area). Draw a container
+element with `id="hero-zone"` at exactly this position and size — `render-cover`
+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. 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
+  three freehand shapes (never catalog icons) — for a post about a transformation or a
+  fix.
+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 — 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.
+For the two-node slot specifically: the accent icon's presence must not be read as belonging to either node; it sits in the kicker/title area purely as a page-level decoration, unrelated to the two-node layout below it.
 ## Technical requirements (non-negotiable)
 - Start the document with a literal `<!DOCTYPE html>` declaration, always.
@@ -56,8 +118,15 @@ end up with the same shape family.
   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
@@ -65,25 +134,98 @@ end up with the same shape family.
 ## 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
@@ -100,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.

package/lib/config_ops.mjs CHANGED Viewed

@@ -31,6 +31,7 @@ export function removeProject(config, key) {
 const SETTERS = {
   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 }),
   voicePath: (c, v) => (v === '' ? omit(c, 'voicePath') : { ...c, voicePath: expandHome(v) }),

package/lib/core.mjs CHANGED Viewed

@@ -113,6 +113,18 @@ export function validateConfig(config) {
       throw new Error(`branch must be a valid git branch name (no leading dash, no '..'): got ${JSON.stringify(config.branch)}`);
     }
   }
+  if ('targetDir' in config) {
+    // Optional: subdirectory of targetRepo holding the devlog content tree — e.g.
+    // `content/devlog` when the target is a site repo that renders the entries
+    // itself. Relative, slash-separated, no traversal, no leading/trailing slash.
+    // Interpolated into shell commands (the publish clone path) and the gh api
+    // contents path, so the charset is deliberately tight.
+    if (typeof config.targetDir !== 'string'
+      || !/^[A-Za-z0-9._-]+(\/[A-Za-z0-9._-]+)*$/.test(config.targetDir)
+      || config.targetDir.split('/').some((s) => s === '.' || s === '..')) {
+      throw new Error(`targetDir must be a relative path like "content/devlog" (no leading/trailing slash, no '..'): got ${JSON.stringify(config.targetDir)}`);
+    }
+  }
   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

package/lib/cover_gen.mjs CHANGED Viewed

@@ -7,19 +7,32 @@ import { CONFIG_DIR } from './core.mjs';
 const IMAGE_STYLE_DIR = join(CONFIG_DIR, 'image-style');
 const STYLE_GUIDE_PATH = join(IMAGE_STYLE_DIR, 'style-guide.md');
+const ICON_CATALOG_PATH = join(IMAGE_STYLE_DIR, 'icons.md');
 function slugFromFile(file) {
   return String(file || '').replace(/\.md$/, '');
 }
-// Pure. Reads the installed style guide. There is no graceful degradation here — Claude
-// has nothing to compose from without it; callers (devlog cover-context) catch the throw
-// and surface it as a distinct error, never blocking the rest of publish.
-export function loadStyleGuide() {
-  if (!existsSync(STYLE_GUIDE_PATH)) {
-    throw new Error(`Cover style guide not found at ${STYLE_GUIDE_PATH} — run \`devlog init\` to install it.`);
+// Pure, given explicit paths — exported separately so tests can exercise the
+// missing-icons.md degradation deterministically against a temp directory, without
+// touching this machine's real installed state at CONFIG_DIR.
+export function resolveStyleGuideAndCatalog(styleGuidePath, iconCatalogPath) {
+  if (!existsSync(styleGuidePath)) {
+    throw new Error(`Cover style guide not found at ${styleGuidePath} — run \`devlog init\` to install it.`);
   }
-  return readFileSync(STYLE_GUIDE_PATH, 'utf8');
+  const text = readFileSync(styleGuidePath, 'utf8');
+  const iconCatalog = existsSync(iconCatalogPath) ? readFileSync(iconCatalogPath, 'utf8') : null;
+  return { text, iconCatalog };
+}
+// Reads the installed style guide (no graceful degradation — Claude has nothing to
+// compose from without it; callers (devlog cover-context) catch the throw and surface it
+// as a distinct error, never blocking the rest of publish) plus the installed icon catalog
+// (graceful degradation here: iconCatalog: null when icons.md isn't installed, mirroring
+// the missing-style-guide handling pattern, just one level down — composition proceeds
+// without a catalog rather than blocking).
+export function loadStyleGuide() {
+  return resolveStyleGuideAndCatalog(STYLE_GUIDE_PATH, ICON_CATALOG_PATH);
 }
 // Read one project's manifest.json out of an already-established clone.

package/lib/migrate_entry_numbers.mjs ADDED Viewed

@@ -0,0 +1,116 @@
+// One-time (but idempotent, safely re-runnable) migration that backfills the
+// frozen `no` field onto every pre-existing manifest row that lacks one. Run
+// once against the published corpus after `publishEntry` started emitting
+// `no` for new entries (see publish_entry.mjs) — everything published before
+// that point needs a number assigned retroactively.
+//
+// `no` is a single global sequence across ALL projects (issue numbers of one
+// publication), so this walks every project directory under corpusDir
+// together rather than numbering each project's manifest independently.
+//
+// Tiebreak for entries sharing a date (common in this corpus — multiple
+// projects, and multiple releases of one project, often ship the same day):
+// date ascending, then project name ascending, then filename ascending. Both
+// of those are stable fields already on the row, so the order is
+// deterministic and reproducible from the data alone, with no external
+// input (e.g. "whichever I published first today") required to redo it.
+//
+// Mutates ONLY the `no` field. Never touches `.md` files. Never touches
+// `cover`. Preserves every other field's value and the manifest's existing
+// key order — `no` is inserted immediately before `cover` (matching where
+// publishEntry places it on a fresh row) or appended at the end when the row
+// has no cover, so old and newly-migrated rows end up shaped the same way.
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { atomicWriteJSON } from './core.mjs';
+function compareRows(a, b) {
+  return String(a.date).localeCompare(String(b.date))
+    || a.project.localeCompare(b.project)
+    || String(a.file).localeCompare(String(b.file));
+}
+function insertNo(entry, no) {
+  const out = {};
+  let inserted = false;
+  for (const [key, value] of Object.entries(entry)) {
+    if (key === 'cover' && !inserted) {
+      out.no = no;
+      inserted = true;
+    }
+    out[key] = value;
+  }
+  if (!inserted) out.no = no;
+  return out;
+}
+// dryRun: compute and return the assignment without writing anything —
+// useful to preview before committing to a run.
+export function migrateEntryNumbers(corpusDir, { dryRun = false } = {}) {
+  if (!existsSync(corpusDir)) throw new Error(`Corpus directory not found: ${corpusDir}`);
+  const projects = readdirSync(corpusDir, { withFileTypes: true })
+    .filter((d) => d.isDirectory())
+    .map((d) => d.name)
+    .sort();
+  const manifestsByProject = new Map();
+  let maxNo = 0;
+  const unnumbered = [];
+  for (const project of projects) {
+    const manifestPath = join(corpusDir, project, 'manifest.json');
+    if (!existsSync(manifestPath)) continue;
+    const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+    if (!manifest || !Array.isArray(manifest.entries)) {
+      throw new Error(`Malformed manifest at ${manifestPath}: expected { "entries": [...] }.`);
+    }
+    manifestsByProject.set(project, manifest);
+    manifest.entries.forEach((entry, index) => {
+      if (!entry) return;
+      if (Number.isInteger(entry.no)) {
+        if (entry.no > maxNo) maxNo = entry.no;
+      } else {
+        unnumbered.push({ project, index, date: String(entry.date), file: String(entry.file) });
+      }
+    });
+  }
+  unnumbered.sort(compareRows);
+  const assigned = [];
+  let next = maxNo + 1;
+  for (const row of unnumbered) {
+    const manifest = manifestsByProject.get(row.project);
+    manifest.entries[row.index] = insertNo(manifest.entries[row.index], next);
+    assigned.push({ project: row.project, file: row.file, date: row.date, no: next });
+    next += 1;
+  }
+  const touchedProjects = [...new Set(unnumbered.map((r) => r.project))].sort();
+  if (!dryRun) {
+    for (const project of touchedProjects) {
+      atomicWriteJSON(join(corpusDir, project, 'manifest.json'), manifestsByProject.get(project));
+    }
+  }
+  return { assigned, touchedProjects, startingNo: maxNo + 1, endingNo: next - 1 };
+}
+// CLI entry point: `node migrate_entry_numbers.mjs <corpusDir> [--dry-run]`
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const corpusDir = process.argv[2];
+  const dryRun = process.argv.includes('--dry-run');
+  if (!corpusDir) {
+    console.error('Usage: node migrate_entry_numbers.mjs <corpusDir> [--dry-run]');
+    process.exit(2);
+  }
+  const result = migrateEntryNumbers(corpusDir, { dryRun });
+  console.log(JSON.stringify(result, null, 2));
+  if (result.assigned.length === 0) {
+    console.error('Nothing to do — every entry already has `no`.');
+  } else {
+    console.error(`${dryRun ? '[dry run] would assign' : 'Assigned'} ${result.assigned.length} numbers (${result.startingNo}..${result.endingNo}).`);
+  }
+}

package/lib/publish_entry.mjs CHANGED Viewed

@@ -2,7 +2,7 @@
 // manifest. This is the code-enforced immutability guard: a cut release's
 // entry is never overwritten, and manifest mutation is no longer done by
 // hand-editing JSON in the agent loop.
-import { existsSync, mkdirSync, readFileSync, writeFileSync, copyFileSync, statSync, openSync, readSync, closeSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, writeFileSync, copyFileSync, statSync, openSync, readSync, closeSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
 import { RE_PROJECT_KEY, RE_FINAL_RELEASE, atomicWriteJSON } from './core.mjs';
 import { parseFrontmatter } from './lint_post.mjs';
@@ -55,6 +55,43 @@ function sortEntries(entries) {
     String(b.date).localeCompare(String(a.date)) || compareVersionsDesc(a, b));
 }
+// `no` is a single sequence across ALL projects (issue numbers of one
+// publication, not per-project counters), but manifests are stored one per
+// project — so "next" means "scan every project's manifest under cloneDir and
+// take the highest `no` seen, plus one." Pre-migration rows with no `no` field
+// are simply skipped, not treated as 0; a manifest a sibling agent is mid-write
+// on is skipped rather than thrown on, since a transient parse failure on
+// ANOTHER project must never block publishing to THIS one.
+// NOT safe against two publishEntry calls racing in separate processes at the
+// same instant (read-then-write with no lock) — acceptable for this single-
+// operator CLI; a real lock is not worth the complexity until that changes.
+function nextEntryNumber(cloneDir) {
+  let dirents;
+  try {
+    dirents = readdirSync(cloneDir, { withFileTypes: true });
+  } catch {
+    return 1;
+  }
+  let max = 0;
+  for (const dirent of dirents) {
+    if (!dirent.isDirectory()) continue;
+    const manifestPath = join(cloneDir, dirent.name, 'manifest.json');
+    if (!existsSync(manifestPath)) continue;
+    let manifest;
+    try {
+      manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+    } catch {
+      continue;
+    }
+    if (!manifest || !Array.isArray(manifest.entries)) continue;
+    for (const entry of manifest.entries) {
+      if (entry && Number.isInteger(entry.no) && entry.no > max) max = entry.no;
+    }
+  }
+  return max + 1;
+}
 export function publishEntry({ cloneDir, project, version, entryPath, coverImageBuffer }) {
   if (!RE_PROJECT_KEY.test(project) || project.includes('..')) {
     throw new Error(`Invalid project key: ${JSON.stringify(project)}`);
@@ -105,7 +142,13 @@ export function publishEntry({ cloneDir, project, version, entryPath, coverImage
   // when the .md was missing — never duplicate an index row.
   const already = manifest.entries.some((e) => e && (e.file === file || e.version === version));
   let manifestUpdated = false;
+  // Frozen at publish, never recomputed: a backdated entry published later must
+  // never shift a number already baked into a live published social image.
+  // Computed only on the write path — a repeat/idempotent call that hits
+  // `already` above must not burn a number on a publish that's a no-op.
+  let no = null;
   if (!already) {
+    no = nextEntryNumber(cloneDir);
     manifest.entries.push({
       date: String(data.date),
       file,
@@ -113,6 +156,7 @@ export function publishEntry({ cloneDir, project, version, entryPath, coverImage
       summary: String(data.summary),
       version,
       tags: Array.isArray(data.tags) ? data.tags : [],
+      no,
       ...(coverFile ? { cover: { file: coverFile, bytes: coverImageBuffer.length } } : {}),
     });
     manifest.entries = sortEntries(manifest.entries);
@@ -120,7 +164,7 @@ export function publishEntry({ cloneDir, project, version, entryPath, coverImage
     manifestUpdated = true;
   }
-  return { written: destPath, manifestUpdated, coverWritten: !!coverFile };
+  return { written: destPath, manifestUpdated, coverWritten: !!coverFile, no };
 }
 // Backfill path only: add a cover to an entry that was already published without one.

package/lib/render_cover.mjs CHANGED Viewed

@@ -16,6 +16,17 @@ export const DEFAULT_RENDER_TIMEOUT_MS = 15000;
 const FONT_PATH = join(homedir(), '.claude', 'skills', 'devlog', 'image-style', 'font.ttf');
 const QUANTIZE_TARGET_BYTES = 500 * 1024;
+// Fixed hero-zone bounding box on the 1600x900 canvas — the single source of truth this
+// design's prose (image-style/style-guide.example.md) must state identically, checked by
+// tests/skill_contract.test.mjs's COVER-Q-2 invariant rather than trusted to manual review.
+export const HERO_ZONE = { x: 150, y: 425, width: 1300, height: 400 };
+export const HERO_GRID_UNIT = 25;
+// getBoundingClientRect() subpixel/rounding tolerance — not a meaningful size/position
+// allowance. Exact-match (within this tolerance), never containment: a containment check
+// would let an agent draw a tiny #hero-zone in a corner and trivially clear the
+// catalog-overlap check below, since a tiny box is still "contained" in the larger one.
+const HERO_ZONE_TOLERANCE_PX = 2;
 // Deterministic Node code, never agent-authored text: reads the installed font file and
 // builds a base64 data URI. The font's bytes never pass through Claude's own text
 // generation — a qualitatively different (and much less reliable, at this size) operation
@@ -59,15 +70,88 @@ async function quantize(pngBuffer) {
   return best;
 }
+// Two rects overlap only on positive-area intersection — rects that merely touch along an
+// edge (zero-area overlap) do NOT count as intersecting.
+function rectsOverlap(a, b) {
+  const left = Math.max(a.x, b.x);
+  const right = Math.min(a.x + a.width, b.x + b.width);
+  const top = Math.max(a.y, b.y);
+  const bottom = Math.min(a.y + a.height, b.y + b.height);
+  return right > left && bottom > top;
+}
+function withinTolerance(rect, fixed, toleranceExclusivePx) {
+  return (
+    Math.abs(rect.x - fixed.x) <= toleranceExclusivePx &&
+    Math.abs(rect.y - fixed.y) <= toleranceExclusivePx &&
+    Math.abs(rect.width - fixed.width) <= toleranceExclusivePx &&
+    Math.abs(rect.height - fixed.height) <= toleranceExclusivePx
+  );
+}
+/**
+ * @param {import('playwright').Page} page
+ * @returns {Promise<{overlaps: boolean, offendingIcons: string[]}>}
+ *
+ * #hero-zone is structurally mandatory, not an opt-in marker: throws if querySelectorAll
+ * finds zero elements (missing) or more than one (duplicate) — rather than silently
+ * skipping the check or resolving to the first DOM match. Once exactly one #hero-zone is
+ * confirmed, its rect is compared against the fixed HERO_ZONE constant (exact-match within
+ * HERO_ZONE_TOLERANCE_PX, not containment — see the constant's own comment) and throws a
+ * distinct geometry-mismatch error if it's outside tolerance, BEFORE computing catalog-icon
+ * overlap. Only past both of those checks does this function resolve normally to
+ * { overlaps, offendingIcons } — overlap-found and overlap-not-found are both successful
+ * resolutions of the check; it is the caller (renderCoverImage) that decides whether
+ * overlaps: true itself becomes a thrown error.
+ */
+export async function checkHeroZoneOverlap(page) {
+  const heroZoneRects = await page.evaluate(() =>
+    [...document.querySelectorAll('#hero-zone')].map((el) => {
+      const r = el.getBoundingClientRect();
+      return { x: r.x, y: r.y, width: r.width, height: r.height };
+    })
+  );
+  if (heroZoneRects.length === 0) {
+    throw new Error('renderCoverImage: composed HTML has no #hero-zone element — a hero zone marker is required, not optional.');
+  }
+  if (heroZoneRects.length > 1) {
+    throw new Error(`renderCoverImage: composed HTML has ${heroZoneRects.length} elements sharing the #hero-zone id — exactly one is required.`);
+  }
+  const heroZoneRect = heroZoneRects[0];
+  if (!withinTolerance(heroZoneRect, HERO_ZONE, HERO_ZONE_TOLERANCE_PX)) {
+    throw new Error(
+      `renderCoverImage: #hero-zone rect (x:${heroZoneRect.x} y:${heroZoneRect.y} width:${heroZoneRect.width} height:${heroZoneRect.height}) ` +
+      `does not match the fixed HERO_ZONE box (x:${HERO_ZONE.x} y:${HERO_ZONE.y} width:${HERO_ZONE.width} height:${HERO_ZONE.height}) ` +
+      `within ${HERO_ZONE_TOLERANCE_PX}px tolerance.`
+    );
+  }
+  const iconRects = await page.evaluate(() =>
+    [...document.querySelectorAll('[data-catalog-icon]')].map((el) => {
+      const r = el.getBoundingClientRect();
+      return { name: el.getAttribute('data-catalog-icon'), x: r.x, y: r.y, width: r.width, height: r.height };
+    })
+  );
+  const offendingIcons = iconRects.filter((icon) => rectsOverlap(icon, heroZoneRect)).map((icon) => icon.name);
+  return { overlaps: offendingIcons.length > 0, offendingIcons };
+}
 /**
  * @param {string} html full, self-contained HTML document (must start with <!DOCTYPE html>)
  * @param {{width:number, height:number, timeoutMs?:number, fontPath?:string, executablePath?:string}} opts
  * @returns {Promise<Buffer>} PNG bytes, exactly {width}x{height} pixels
  *
- * Throws on exactly three realistic failure modes: a render timeout; Chromium not being
- * installed; a missing/unreadable installed font file. Does NOT throw on malformed HTML —
- * Chromium's HTML5 parser is deliberately fault-tolerant and recovers into some DOM
- * regardless of input; a poorly composed document renders wrong, it doesn't fail to render.
+ * Throws on exactly four realistic failure modes: a render timeout; Chromium not being
+ * installed; a missing/unreadable installed font file; and (a deliberate widening of this
+ * already-documented throw contract) a #hero-zone structural/geometry problem — missing
+ * #hero-zone, duplicate #hero-zone, the #hero-zone rect not matching the fixed HERO_ZONE
+ * bounding box within tolerance, or a catalog icon overlapping the hero zone. Does NOT
+ * throw on malformed HTML — Chromium's HTML5 parser is deliberately fault-tolerant and
+ * recovers into some DOM regardless of input; a poorly composed document renders wrong, it
+ * doesn't fail to render.
  */
 export async function renderCoverImage(html, opts = {}) {
   const {
@@ -144,6 +228,17 @@ export async function renderCoverImage(html, opts = {}) {
       ),
     ]);
+    // Geometry-enforced hero-zone guard, immediately before the screenshot: throws on a
+    // missing/duplicate #hero-zone, a #hero-zone rect that doesn't match the fixed
+    // HERO_ZONE box, or (below) a catalog icon whose rect overlaps the hero zone.
+    const { overlaps, offendingIcons } = await checkHeroZoneOverlap(page);
+    if (overlaps) {
+      throw new Error(
+        `renderCoverImage: catalog icon(s) [${offendingIcons.join(', ')}] overlaps hero zone — ` +
+        'catalog icons may only appear as an accent glyph outside #hero-zone, never inside it.'
+      );
+    }
     // Viewport-clipped screenshot (fullPage omitted/false, Playwright's default) — never
     // fullPage: true, which would capture the whole scrollable page rather than just the
     // viewport. This is what guarantees the output is always exactly {width, height}

package/lib/scan.mjs CHANGED Viewed

@@ -191,8 +191,9 @@ function splitLogLine(line) {
 // project has no entries yet; any other failure is surfaced so the caller
 // knows the entry-exists filter may be incomplete (publish-entry still refuses
 // overwrites against the fresh clone, so a stale scan cannot clobber anything).
-export function fetchExistingEntries(targetRepo, branch, projectKey) {
-  const r = spawnArgs('gh', ['api', `repos/${targetRepo}/contents/${projectKey}?ref=${branch}`, '--jq', '.[].name']);
+export function fetchExistingEntries(targetRepo, branch, projectKey, targetDir = '') {
+  const contentPath = targetDir ? `${targetDir}/${projectKey}` : projectKey;
+  const r = spawnArgs('gh', ['api', `repos/${targetRepo}/contents/${contentPath}?ref=${branch}`, '--jq', '.[].name']);
   if (r.status === 0) {
     return { files: new Set(r.stdout.split('\n').filter(Boolean)), status: 'ok' };
   }
@@ -218,7 +219,7 @@ export function scanAll(config, { projectKey = null, fetch = true, getExisting =
   }
   const results = projects.map((project) => {
-    const existing = getExisting(config.targetRepo, branch, project.key);
+    const existing = getExisting(config.targetRepo, branch, project.key, config.targetDir || '');
     const scanned = scanProject(project, { branch, fetch, existingFiles: existing.files });
     scanned.existenceCheck = existing.status;
     return scanned;
@@ -226,6 +227,9 @@ export function scanAll(config, { projectKey = null, fetch = true, getExisting =
   return {
     targetRepo: config.targetRepo,
+    // Subdirectory of targetRepo holding the content tree ('' = repo root) — the
+    // skill appends it to the publish clone path (`--clone <clone>/<targetDir>`).
+    targetDir: config.targetDir || '',
     branch,
     deepDive: resolveDeepDive(config),
     voicePath: config.voicePath || null,

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@natjswenson/devlog",
-  "version": "0.8.1",
+  "version": "0.10.0",
   "description": "Release dev log generator \u2014 Claude Code skill + preview app for publishing version-release dev logs, written in your voice, to your site",
   "license": "MIT",
   "author": "Nate Swenson",

package/skill-invariants.json CHANGED Viewed

@@ -1,5 +1,5 @@
 {
-  "comment": "Prose guardrails in SKILL.md that must survive edits. Each pattern is a case-insensitive regex tested against the full SKILL.md text by tests/skill_contract.test.mjs. If you intentionally change one, update it here in the same commit and say why in the PR.",
+  "comment": "Prose guardrails in SKILL.md that must survive edits (the `prose` array — each pattern is a case-insensitive regex tested against the full SKILL.md text) and code-level guards elsewhere in this skill's source (the `code` array — each pattern is tested against the file named by its own `file` field, not SKILL.md). Both are checked by tests/skill_contract.test.mjs. If you intentionally change one, update it here in the same commit and say why in the PR.",
   "prose": [
     {
       "id": "immutable-entries",
@@ -84,7 +84,15 @@
     {
       "id": "cover-custom-illustration",
       "pattern": "cover that just re-renders the title in large text is a failure",
-      "rationale": "First shipped version of this feature produced a shared text-heavy template with a rotating stock shape — rejected as bland/repetitive. Losing this line reopens that regression."
+      "rationale": "First shipped version of this feature produced a shared text-heavy template with a rotating stock shape — rejected as bland/repetitive. Losing this line reopens that regression. Independent of, not superseded by, the v0.9.0 geometry guard (cover-catalog-hero-overlap-guard, below): that guard is a mechanical check on an agent's rendered composition each time a cover is rendered; this line is a prose guardrail against a future SKILL.md/style-guide edit silently reintroducing the bland-template regression at the instruction level. Two different regression surfaces, both still worth guarding."
+    }
+  ],
+  "code": [
+    {
+      "id": "cover-catalog-hero-overlap-guard",
+      "file": "lib/render_cover.mjs",
+      "pattern": "(?:getBoundingClientRect[\\s\\S]{0,400}hero-zone|hero-zone[\\s\\S]{0,400}getBoundingClientRect)",
+      "rationale": "The catalog-icon/hero-zone overlap check must stay wired into renderCoverImage() — losing it silently reopens the gap where a catalog icon (or two, connected by a line) can stand in for the required bespoke hero illustration."
     }
   ],
   "cli_commands_referenced": ["scan", "lint-post", "publish-entry", "add-project", "remove-project", "set", "config", "init", "cover-context", "render-cover"]