@natjswenson/devlog 0.6.0 → 0.9.0

package/lib/publish_entry.mjs

@@ -2,11 +2,33 @@
 // 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, copyFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, writeFileSync, copyFileSync, statSync, openSync, readSync, closeSync } 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';
 
+const PNG_MAGIC = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+
+function isValidPng(path) {
+  let fd;
+  try {
+    fd = openSync(path, 'r');
+    const buf = Buffer.alloc(8);
+    const n = readSync(fd, buf, 0, 8, 0);
+    return n === 8 && buf.equals(PNG_MAGIC);
+  } catch {
+    return false;
+  } finally {
+    if (fd !== undefined) closeSync(fd);
+  }
+}
+
+function assertSafeSlug(slug) {
+  if (typeof slug !== 'string' || slug === '' || slug.includes('/') || slug.includes('..') || /[\x00-\x1f]/.test(slug)) {
+    throw new Error(`Invalid slug: ${JSON.stringify(slug)}`);
+  }
+}
+
 // Newest-first by date; same-date ties break by version, highest first.
 // Without the tiebreak, several releases cut on one day render oldest-on-top
 // in the feed (stable sort keeps insertion order), burying the newest post
@@ -33,7 +55,7 @@ function sortEntries(entries) {
     String(b.date).localeCompare(String(a.date)) || compareVersionsDesc(a, b));
 }
 
-export function publishEntry({ cloneDir, project, version, entryPath }) {
+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)}`);
   }
@@ -58,6 +80,17 @@ export function publishEntry({ cloneDir, project, version, entryPath }) {
   mkdirSync(projectDir, { recursive: true });
   copyFileSync(entryPath, destPath);
 
+  // Cover write happens between the .md write and the manifest mutation, matching the
+  // existing .md-then-manifest crash-recovery convention: a process death after this write
+  // but before the manifest mutation leaves an orphaned <version>.png with no matching
+  // `cover` field — harmless inert clutter (the manifest is the sole source of truth for
+  // "does this post have a cover"), not a correctness bug, and needs no cleanup logic.
+  let coverFile = null;
+  if (coverImageBuffer) {
+    coverFile = `${version}.png`;
+    writeFileSync(join(projectDir, coverFile), coverImageBuffer);
+  }
+
   const manifestPath = join(projectDir, 'manifest.json');
   let manifest = { entries: [] };
   if (existsSync(manifestPath)) {
@@ -79,11 +112,90 @@ export function publishEntry({ cloneDir, project, version, entryPath }) {
       title: String(data.title),
       summary: String(data.summary),
       version,
+      tags: Array.isArray(data.tags) ? data.tags : [],
+      ...(coverFile ? { cover: { file: coverFile, bytes: coverImageBuffer.length } } : {}),
     });
     manifest.entries = sortEntries(manifest.entries);
     atomicWriteJSON(manifestPath, manifest);
     manifestUpdated = true;
   }
 
-  return { written: destPath, manifestUpdated };
+  return { written: destPath, manifestUpdated, coverWritten: !!coverFile };
+}
+
+// Backfill path only: add a cover to an entry that was already published without one.
+// Never writes/reads <slug>.md, never pushes a new manifest row — its only mutation is the
+// `cover` field of an already-existing entry, keyed by that entry's version/file stem.
+//
+// Three-way branch, in order:
+//   1. force: true            -> ALWAYS overwrite the clone-destination PNG unconditionally,
+//                                 no magic-byte check, no adoption logic. This is what
+//                                 "force" means: --force is used precisely when a row
+//                                 already has `cover`, so an ungated adoption check would
+//                                 otherwise silently skip the write exactly when the caller
+//                                 most clearly intends to overwrite.
+//   2. !force, row has cover  -> throw/refuse before any write.
+//   3. !force, row lacks cover -> the only branch where magic-byte adopt-or-discard logic
+//                                 applies. Kept as cheap, harmless insurance for a resume
+//                                 scenario that is NOT reachable via commit-covers's actual
+//                                 call pattern (commit-covers always establishes a fresh
+//                                 clone and performs exactly one commit+push at the very
+//                                 end, so a crash mid-run never leaves this orphan
+//                                 discoverable by a later invocation) — not a claim that
+//                                 this state occurs in practice.
+export function addCoverToExistingEntry({ cloneDir, project, slug, coverImageBuffer, force = false }) {
+  if (!RE_PROJECT_KEY.test(project) || project.includes('..')) {
+    throw new Error(`Invalid project key: ${JSON.stringify(project)}`);
+  }
+  assertSafeSlug(slug);
+  if (!coverImageBuffer || !Buffer.isBuffer(coverImageBuffer)) {
+    throw new Error('coverImageBuffer is required and must be a Buffer');
+  }
+  if (!existsSync(cloneDir)) throw new Error(`Clone directory not found: ${cloneDir}`);
+
+  const projectDir = join(cloneDir, project);
+  const manifestPath = join(projectDir, 'manifest.json');
+  if (!existsSync(manifestPath)) {
+    throw new Error(`No manifest found for project "${project}" at ${manifestPath}`);
+  }
+  const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+  if (!manifest || !Array.isArray(manifest.entries)) {
+    throw new Error(`Malformed manifest at ${manifestPath}: expected { "entries": [...] }.`);
+  }
+
+  const idx = manifest.entries.findIndex(
+    (e) => e && (e.version === slug || (e.file && e.file.replace(/\.md$/, '') === slug))
+  );
+  if (idx === -1) {
+    throw new Error(`No manifest row for ${project}/${slug} — cannot add a cover to an entry that doesn't exist.`);
+  }
+  const entry = manifest.entries[idx];
+
+  if (entry.cover && !force) {
+    throw new Error(`${project}/${slug} already has a cover — pass force: true to overwrite.`);
+  }
+
+  const coverFile = `${slug}.png`;
+  const destPath = join(projectDir, coverFile);
+  mkdirSync(projectDir, { recursive: true });
+
+  let written;
+  if (force) {
+    writeFileSync(destPath, coverImageBuffer);
+    written = destPath;
+  } else if (existsSync(destPath) && isValidPng(destPath)) {
+    // Adopt the existing file as the completed result of a hypothetical interrupted prior
+    // write. coverImageBuffer (the staging-dir source the caller already read — a
+    // different file from this clone-destination path) is NOT rewritten over it.
+    written = destPath;
+  } else {
+    writeFileSync(destPath, coverImageBuffer);
+    written = destPath;
+  }
+
+  const bytes = statSync(written).size;
+  manifest.entries[idx] = { ...entry, cover: { file: coverFile, bytes } };
+  atomicWriteJSON(manifestPath, manifest);
+
+  return { written, manifestUpdated: true };
 }

package/lib/render_cover.mjs

@@ -0,0 +1,251 @@
+// Rasterize a Claude-composed HTML/CSS cover into a fixed-size PNG.
+//
+// This is the one genuinely deterministic, testable function in the cover-generation
+// path — composing the HTML itself is agent behavior, not a library call (see SKILL.md
+// Step 5 / devlog cover-context). Uses headless Chromium (the `playwright` package,
+// never `playwright-core` — the CLI needs the full package so
+// `npx playwright install chromium` works).
+import { chromium } from 'playwright';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import sharp from 'sharp';
+
+export const COVER_FONT_FAMILY = 'DevlogCoverFont';
+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
+// than Claude directly viewing reference cover images.
+function readFontBase64(fontPath) {
+  if (!existsSync(fontPath)) {
+    throw new Error(`Cover font not found at ${fontPath} — run \`devlog init\` to install it.`);
+  }
+  let bytes;
+  try {
+    bytes = readFileSync(fontPath);
+  } catch (e) {
+    throw new Error(`Cover font at ${fontPath} could not be read: ${e.message}`);
+  }
+  if (bytes.length === 0) {
+    throw new Error(`Cover font at ${fontPath} is empty (0 bytes) — reinstall it with \`devlog init\`.`);
+  }
+  return bytes.toString('base64');
+}
+
+// Lossy palette quantization toward a ~300-500KB target. Best-effort: never throws for
+// size reasons, just returns the smallest of the attempts tried. Quantization affects
+// color depth/file size only, never pixel dimensions.
+async function quantize(pngBuffer) {
+  const attempts = [
+    { palette: true, quality: 90, effort: 8 },
+    { palette: true, quality: 70, colors: 128, effort: 8 },
+    { palette: true, quality: 50, colors: 64, effort: 8 },
+  ];
+  let best = pngBuffer;
+  for (const opts of attempts) {
+    let out;
+    try {
+      out = await sharp(pngBuffer).png(opts).toBuffer();
+    } catch {
+      continue; // this attempt's options weren't accepted; fall through to the next
+    }
+    if (out.length < best.length) best = out;
+    if (out.length <= QUANTIZE_TARGET_BYTES) return out;
+  }
+  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 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 {
+    width,
+    height,
+    timeoutMs = DEFAULT_RENDER_TIMEOUT_MS,
+    fontPath = FONT_PATH,
+    executablePath,
+    // Test-only seam, not part of the documented contract: lets tests inject a fake
+    // launch() to spy on page.setContent/addStyleTag/evaluate/screenshot call order
+    // without spinning up real Chromium. Defaults to the real playwright launcher.
+    launch = executablePath ? (o) => chromium.launch({ ...o, executablePath }) : (o) => chromium.launch(o),
+  } = opts;
+
+  if (typeof html !== 'string' || html.trim() === '') {
+    throw new Error('renderCoverImage: html must be a non-empty string');
+  }
+  if (!Number.isInteger(width) || !Number.isInteger(height) || width <= 0 || height <= 0) {
+    throw new Error('renderCoverImage: width/height must be positive integers');
+  }
+
+  // Read + validate the font BEFORE ever launching Chromium — a missing/corrupt font is a
+  // plain, cheap filesystem check and shouldn't cost a browser launch to detect.
+  const fontBase64 = readFontBase64(fontPath);
+
+  let browser;
+  try {
+    browser = await launch(undefined);
+  } catch (e) {
+    throw new Error(
+      `Chromium is not installed (or failed to launch) — run \`npx playwright install chromium\`. (${e.message})`
+    );
+  }
+
+  try {
+    const page = await browser.newPage({ viewport: { width, height } });
+
+    // Parse Claude's document exactly as authored first, in standards mode — never a raw
+    // string prepend of the font-face rule, which would force quirks mode (per the HTML5
+    // tree-construction algorithm, any non-whitespace content before the DOCTYPE token
+    // does) and risks a same-specificity shadow from Claude's own CSS.
+    await page.setContent(html, { waitUntil: 'load', timeout: timeoutMs });
+
+    // Inject the real font into the already-parsed document via the DOM API. Landing here
+    // — added after the page's own stylesheets are already parsed — also means this rule
+    // wins any cascade tie against markup referencing the same family, by document order.
+    const fontFaceCss =
+      `@font-face { font-family: '${COVER_FONT_FAMILY}'; ` +
+      `src: url(data:font/ttf;base64,${fontBase64}) format('truetype'); }`;
+    await page.addStyleTag({ content: fontFaceCss });
+
+    // Merely declaring @font-face does not synchronously start the load — Chromium only
+    // triggers the fetch/decode once a style-recalc discovers text resolving to that
+    // family, and that recalc isn't guaranteed to have run yet. document.fonts.load()
+    // explicitly kicks off the load so the immediately-following document.fonts.ready
+    // check is guaranteed to cover it, closing a real race where the ready-promise could
+    // otherwise resolve before the embedded font has actually finished decoding.
+    const fontsReady = (async () => {
+      await page.evaluate((family) => document.fonts.load(`1em '${family}'`), COVER_FONT_FAMILY);
+      await page.evaluate(() => document.fonts.ready);
+    })();
+    // Attach a no-op handler immediately so a late rejection (e.g. the timeout branch below
+    // wins the race, then this promise itself rejects after the page is torn down) never
+    // surfaces as an unhandled rejection — the race below is still driven by this same
+    // promise reference.
+    fontsReady.catch(() => {});
+    await Promise.race([
+      fontsReady,
+      new Promise((_, reject) =>
+        setTimeout(
+          () => reject(new Error(`renderCoverImage: timed out after ${timeoutMs}ms waiting on font load`)),
+          timeoutMs
+        )
+      ),
+    ]);
+
+    // 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}
+    // regardless of whether the composed HTML's content overflows it.
+    const png = await page.screenshot({ type: 'png', timeout: timeoutMs });
+    return await quantize(png);
+  } finally {
+    await browser.close();
+  }
+}

package/lib/scan.mjs

@@ -74,6 +74,7 @@ export function scanProject(project, { branch = 'main', fetch = true, existingFi
     key: project.key,
     label: project.label || project.key,
     remote: project.remote,
+    private: !!project.private,
     path: project.path,
     pathFilter: project.pathFilter || null,
     tagPrefix: project.tagPrefix || 'v',
@@ -107,6 +108,11 @@ export function scanProject(project, { branch = 'main', fetch = true, existingFi
   const hasPublishedRef = git(project.path, ['rev-parse', '--verify', '--quiet', publishedRef]) !== null;
 
   const isPublic = (rev) => {
+    // A private project has no safe commit surface, full stop — this bypasses
+    // remoteMatches/hasPublishedRef entirely rather than relying on them to
+    // happen to be false, since a private repo can still have origin configured
+    // correctly (remoteMatches true) and a normally-pushed branch.
+    if (project.private) return false;
     if (!remoteMatches || !hasPublishedRef) return false;
     return spawnArgs('git', ['-C', project.path, 'merge-base', '--is-ancestor', rev, publishedRef]).status === 0;
   };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@natjswenson/devlog",
-  "version": "0.6.0",
+  "version": "0.9.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",
@@ -33,6 +33,7 @@
     "preview/",
     "examples/",
     "voice/",
+    "image-style/",
     "SKILL.md",
     "SECURITY.md",
     "CHANGELOG.md",
@@ -50,11 +51,13 @@
   "dependencies": {
     "@vitejs/plugin-react": "6.0.1",
     "kleur": "4.1.5",
+    "playwright": "1.61.1",
     "prompts": "2.4.2",
     "react": "18.3.1",
     "react-dom": "18.3.1",
     "react-markdown": "9.1.0",
     "remark-gfm": "4.0.1",
+    "sharp": "0.35.3",
     "vite": "8.0.16"
   }
 }

package/skill-invariants.json

@@ -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",
@@ -60,7 +60,40 @@
       "id": "no-push-retry",
       "pattern": "do not retry automatically",
       "rationale": "A failed push is surfaced to the user, not retried blind."
+    },
+    {
+      "id": "private-project-no-links",
+      "pattern": "no post ever[\\s\\S]{0,10}links a commit for it",
+      "rationale": "A private project's commits must never scan as public just because remoteMatches + branch-contains happen to hold — losing this line reopens the dead-link-to-a-private-repo path."
+    },
+    {
+      "id": "cover-composition-scope",
+      "pattern": "never the raw draft file, never[\\s\\S]{0,10}## Changelog",
+      "rationale": "Cover composition must draw only from title/tags/summary/## Shipped — never the raw draft or Changelog — losing this line reopens off-scope content leaking into an auto-composed image."
+    },
+    {
+      "id": "cover-never-blocks-publish",
+      "pattern": "[Nn]ever block[\\s\\S]{0,10}publish on a missing style guide",
+      "rationale": "A missing/uninstalled style guide must degrade gracefully (no cover this run), never abort the whole publish."
+    },
+    {
+      "id": "cover-review-gate",
+      "pattern": "this interactive review IS the quality gate for the cover",
+      "rationale": "The rendered cover must be shown to the user before push, the same way Step 4 gates the prose — losing this line reopens publishing an unreviewed cover."
+    },
+    {
+      "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. 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"]
+  "cli_commands_referenced": ["scan", "lint-post", "publish-entry", "add-project", "remove-project", "set", "config", "init", "cover-context", "render-cover"]
 }