@natjswenson/devlog 0.6.0 → 0.9.0

package/config.example.json

@@ -23,6 +23,12 @@
       "remote": "yourusername/your-monorepo",
       "pathFilter": "skills/devlog",
       "tagPrefix": "devlog-v"
+    },
+    {
+      "key": "personal",
+      "label": "Personal",
+      "path": "/Users/yourusername/code/private-project",
+      "private": true
     }
   ]
 }

package/evals/fixtures/good-post.md

@@ -3,7 +3,7 @@ title: "Retries that don't stampede: exponential backoff with jitter in 40 lines
 date: 2026-07-10
 project: fixture
 version: v1.3.0
-tags: [reliability, python, distributed-systems]
+tags: [reliability, python, distributed-systems, backoff, jitter]
 summary: "This release moved our flaky HTTP calls behind a retry wrapper. Here's how to build one with full jitter, and the two traps that bit me."
 ---
 

package/evals/fixtures/irreproducible-post.md

@@ -3,7 +3,7 @@ title: "How our pipeline learned to validate itself end-to-end"
 date: 2026-07-10
 project: fixture
 version: v2.1.0
-tags: [testing, data-pipelines, python]
+tags: [testing, data-pipelines, python, etl, validation]
 summary: "v2.1.0 added self-validating pipeline stages. A look at how the validation layer came together."
 ---
 

package/image-style/icons.md

@@ -0,0 +1,234 @@
+# 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: #ededed` or `color: #fff503` (the accent yellow) —
+never `fill`. 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

@@ -0,0 +1,138 @@
+# Cover image style guide
+
+This is the fallback style guide devlog uses when composing a post's cover image. It is
+generic. Replace it with your own — the more specific the visual direction, the more
+consistent your covers will look across ~50+ posts.
+
+devlog reads this file, plus (when available) the `n` most recently published covers as
+reference images, before composing a new cover. **Actually look at the reference images
+before composing** — the style guide alone under-specifies layout/spacing; the references
+are how a from-scratch visual language stays consistent from post to post.
+
+## What you're composing
+
+A single self-contained HTML document (inline `<style>`, inline SVG for any artwork) that
+renders, at exactly 1600×900px, as a cover image for one dev log entry. Compose from these
+fields only — never open the post's raw markdown file, never reference any section other
+than `## Shipped` (no `## Changelog`, no gotchas, no sources):
+- `title`
+- `tags`
+- `summary`
+- the `## Shipped` section's text
+
+## The point of this cover: one custom illustration, not a repeated headline
+
+**A cover that just re-renders the title in large text is a failure, no matter how clean
+the typography is.** The title is already the `<h1>` on the post page one scroll down —
+the cover's job is to give the reader something to *look at*, a specific visual idea that
+came from *this* post's content and would look wrong on any other post.
+
+Before writing any HTML, do this thinking step explicitly:
+1. Read the title, summary, and `## Shipped` text.
+2. Identify the one concrete technical concept or moment the post is actually about —
+   not the project name, not "a bug fix," but the specific mechanism: a lock rejecting a
+   key that doesn't fit, a git tag being distrusted like any other user input, one broken
+   link in a chain, a filter separating signal from noise, a clock catching a stale
+   timestamp, two paths diverging and one being cut off.
+3. Design ONE illustration — built from inline SVG shapes (lines, arcs, polygons,
+   simple geometric forms) — that depicts that concept. Not a photo, not a stock icon,
+   not a screenshot: a small original line-art scene, in the spirit of an editorial
+   illustration or a technical diagram, 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.
+
+**Two different posts should never produce visually similar covers.** If your instinct is
+to reach for a generic circle/square/checkmark because you're not sure what else to draw,
+that's a sign to go back to step 2 and find the more specific concept — a post about
+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.
+
+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.
+
+**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.
+
+**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.
+
+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.
+- `html, body { margin: 0; width: 1600px; height: 900px; }` — the render is a
+  viewport-clipped screenshot at exactly this size; content that overflows this box is
+  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.
+- No external resources of any kind — no `<link>`, no `@import`, no remote `<img src>`,
+  no web fonts, no raster images. All artwork is inline SVG built from basic shapes
+  (`<path>`, `<circle>`, `<rect>`, `<line>`, `<polygon>`, `<polyline>`) — everything must
+  be inline HTML/CSS/SVG, hand-composed, not fetched or embedded from anywhere.
+
+## 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.
+- **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
+  concept, not decorate around it.
+
+## Never do
+
+- Don't make the title the largest, most prominent element on the cover — the
+  illustration is.
+- Don't restate the version number as the headline ("v0.6.0" as the big text) — use the
+  post's actual title, and keep it secondary to the artwork.
+- Don't reuse the same illustration, shape family, or visual metaphor across different
+  posts — go back to the post's actual content and find what's specific to it.
+- 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 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).

package/lib/config_ops.mjs

@@ -3,11 +3,14 @@
 // reading/writing ~/.claude/skills/devlog/config.json atomically.
 import { validateConfig, expandHome } from './core.mjs';
 
-export function addProject(config, { key, path, remote, label, tagPrefix, pathFilter }) {
+export function addProject(config, { key, path, remote, label, tagPrefix, pathFilter, private: isPrivate }) {
   if (config.projects.some((p) => p.key === key)) {
     throw new Error(`Project key "${key}" is already registered.`);
   }
-  const project = { key, path: expandHome(path), remote };
+  const project = { key, path: expandHome(path) };
+  // remote is required unless the project is private (see core.mjs validateConfig).
+  if (remote) project.remote = remote;
+  if (isPrivate) project.private = true;
   if (label) project.label = label;
   // Only persist tagPrefix when it differs from the default `v` (keeps configs clean).
   if (tagPrefix && tagPrefix !== 'v') project.tagPrefix = tagPrefix;

package/lib/core.mjs

@@ -154,7 +154,18 @@ export function validateConfig(config) {
     if (typeof p.path !== 'string' || SHELL_QUOTE_BREAK.test(p.path)) {
       throw new Error(`project.path invalid (must contain no shell metacharacters): ${JSON.stringify(p.path)}`);
     }
-    if (!RE_OWNER_REPO.test(p.remote)) {
+    if ('private' in p && typeof p.private !== 'boolean') {
+      throw new Error(`project.private must be a boolean if present: ${JSON.stringify(p.private)}`);
+    }
+    // A private project has no safe public commit surface, so `remote` is
+    // optional (it's never used to build a commit link — see scan.mjs's
+    // isPublic). If supplied anyway, for the maintainer's own reference, it
+    // must still be well-formed.
+    if (p.private) {
+      if ('remote' in p && p.remote !== undefined && !RE_OWNER_REPO.test(p.remote)) {
+        throw new Error(`project.remote must match <owner>/<repo>: ${JSON.stringify(p.remote)}`);
+      }
+    } else if (!RE_OWNER_REPO.test(p.remote)) {
       throw new Error(`project.remote must match <owner>/<repo>: ${JSON.stringify(p.remote)}`);
     }
     if ('pathFilter' in p) {

package/lib/cover_gen.mjs

@@ -0,0 +1,137 @@
+// Style guide + reference-image lookup for cover-image composition. Deterministic,
+// no LLM/agent involvement — the agent calls `devlog cover-context` (bin/devlog.js),
+// which wraps these two functions.
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+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, 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.`);
+  }
+  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.
+// Two distinct missing-manifest cases (mirrors fetchExistingEntries()'s empty/failed split
+// in lib/scan.mjs): a project directory that doesn't exist at all (never published a
+// release yet) is zero entries, not an error. A project directory that DOES exist but
+// whose manifest.json is missing or fails to parse is a genuine anomaly — surfaced via
+// status: 'failed' so the caller can throw a clear, named error rather than silently
+// dropping that project's entries from a merged result.
+function readProjectManifest(cloneDir, projectKey) {
+  const projectDir = join(cloneDir, projectKey);
+  if (!existsSync(projectDir)) {
+    return { entries: [], status: 'empty' };
+  }
+  const manifestPath = join(projectDir, 'manifest.json');
+  if (!existsSync(manifestPath)) {
+    return { entries: [], status: 'failed', reason: `manifest.json missing for project "${projectKey}" (expected at ${manifestPath})` };
+  }
+  let manifest;
+  try {
+    manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+  } catch (e) {
+    return { entries: [], status: 'failed', reason: `manifest.json for project "${projectKey}" failed to parse: ${e.message}` };
+  }
+  if (!manifest || !Array.isArray(manifest.entries)) {
+    return { entries: [], status: 'failed', reason: `manifest.json for project "${projectKey}" is malformed (expected { "entries": [...] })` };
+  }
+  return { entries: manifest.entries, status: 'ok' };
+}
+
+// Cross-project manifest enumeration/merge — the one mechanism shared by
+// getRecentCovers() (below) and `devlog backfill-covers list` (bin/devlog.js). There is no
+// merged/aggregated manifest file anywhere in daily-dev-log (confirmed: exactly one
+// manifest.json per project directory) — every project's own manifest.json is read
+// individually and tagged with `project` as it's read, mirroring getAllEntries() in
+// natejswenson.io/src/lib/devlog.js (the site's own equivalent per-project-manifest merge;
+// its own empty-vs-corrupt handling is indirect/local-overlay-based, not the same
+// mechanism as this direct directory check, though it reaches the same outcome for the
+// directory-absent case).
+export function mergeManifestEntries(cloneDir, config) {
+  const merged = [];
+  for (const p of (config.projects || [])) {
+    const { entries, status, reason } = readProjectManifest(cloneDir, p.key);
+    if (status === 'failed') throw new Error(reason);
+    for (const e of entries) merged.push({ ...e, project: p.key });
+  }
+  return merged;
+}
+
+// Staged-but-uncommitted covers from earlier in the same backfill session, freshest first
+// by file mtime. Resolved under stagingDir's per-project subdirectory
+// (<stagingDir>/<project>/<slug>.png) — never a flat <stagingDir>/<slug>.png, since slugs
+// are not globally unique across projects.
+function listStagedCovers(stagingDir) {
+  if (!stagingDir || !existsSync(stagingDir)) return [];
+  const out = [];
+  for (const d of readdirSync(stagingDir, { withFileTypes: true })) {
+    if (!d.isDirectory()) continue; // skips the top-level index.html contact sheet
+    const projectDir = join(stagingDir, d.name);
+    for (const f of readdirSync(projectDir)) {
+      if (!f.endsWith('.png')) continue;
+      const full = join(projectDir, f);
+      out.push({ project: d.name, slug: f.replace(/\.png$/, ''), path: full, mtimeMs: statSync(full).mtimeMs });
+    }
+  }
+  out.sort((a, b) => b.mtimeMs - a.mtimeMs);
+  return out.map(({ project, slug, path }) => ({ project, slug, path }));
+}
+
+// Pure given its inputs. Returns the N most recently published covers across every
+// configured project (newest by manifest `date`), as local paths inside the already-
+// established clone. When stagingDir is given and fewer than n published covers exist,
+// tops up the result with covers already staged this session (freshest-first) — what lets
+// a from-scratch backfill session bootstrap its own visual consistency instead of every
+// candidate composing from the style guide alone. Returns [] when neither source has
+// anything yet (the true first-cover case) — never throws for that, never pads.
+export function getRecentCovers({ cloneDir, config, stagingDir = null, n = 3 }) {
+  const merged = mergeManifestEntries(cloneDir, config);
+  const covered = merged
+    .filter((e) => e && e.cover && e.file)
+    .map((e) => ({ project: e.project, slug: slugFromFile(e.file), date: e.date }))
+    .sort((a, b) => (a.date < b.date ? 1 : a.date > b.date ? -1 : 0));
+
+  const result = covered.slice(0, n).map(({ project, slug }) => ({
+    project,
+    slug,
+    path: join(cloneDir, project, `${slug}.png`),
+  }));
+
+  if (result.length < n) {
+    const seen = new Set(result.map((r) => `${r.project}/${r.slug}`));
+    for (const staged of listStagedCovers(stagingDir)) {
+      if (result.length >= n) break;
+      const key = `${staged.project}/${staged.slug}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      result.push(staged);
+    }
+  }
+
+  return result;
+}

package/lib/lint_post.mjs

@@ -10,6 +10,23 @@ export const REQUIRED_SECTIONS = ['Shipped', 'Gotchas', 'Sources'];
 
 const RE_DATE = /^\d{4}-\d{2}-\d{2}$/;
 
+export const TAG_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
+
+// First-occurrence wins: keeps the first casing seen, drops later
+// case-insensitive duplicates. A same-case repeat is the reachable case in
+// practice — TAG_PATTERN already forbids the case-differing variant outright.
+export function dedupeCaseInsensitive(tags) {
+  const seen = new Set();
+  const out = [];
+  for (const t of tags) {
+    const key = t.toLowerCase();
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push(t);
+  }
+  return out;
+}
+
 // Minimal frontmatter parser: `--- ... ---` fence, `key: value` lines, flow
 // arrays for tags. Prototype-free target object; unknown keys are kept (the
 // contract does not forbid extras) but only allowlisted keys are checked.
@@ -121,8 +138,18 @@ export function lintPost(content, { minSources = 3, filename = null } = {}) {
       add('title-style', 'Title must be essay-style, not a "release vX.Y.Z" label.');
     }
   }
-  if (Array.isArray(data.tags) && (data.tags.length < 2 || data.tags.length > 5)) {
-    add('tags-count', `Expected 2-5 topic tags, got ${data.tags.length}.`);
+  if (Array.isArray(data.tags) && (data.tags.length < 5 || data.tags.length > 10)) {
+    add('tags-count', `Expected 5-10 topic tags, got ${data.tags.length}.`);
+  }
+  if (Array.isArray(data.tags)) {
+    for (const t of data.tags) {
+      if (typeof t === 'string' && !TAG_PATTERN.test(t)) {
+        add('tags-character-pattern', `Tag "${t}" must be lowercase alphanumeric/hyphens only (^[a-z0-9][a-z0-9-]*$).`);
+      }
+    }
+    if (dedupeCaseInsensitive(data.tags).length !== data.tags.length) {
+      add('tags-duplicate', 'Tags contain a case-insensitive duplicate.');
+    }
   }
   if (filename && typeof data.version === 'string' && data.version) {
     const expected = `${data.version}.md`;