@natjswenson/devlog 0.10.0 → 0.11.1

package/README.md

@@ -0,0 +1,272 @@
+# devlog
+
+[![npm](https://img.shields.io/npm/v/@natjswenson/devlog?color=blue)](https://www.npmjs.com/package/@natjswenson/devlog)
+[![license](https://img.shields.io/npm/l/@natjswenson/devlog)](./LICENSE)
+[![security](https://img.shields.io/badge/security-audited-green)](./SECURITY.md)
+[![vulnerabilities](https://img.shields.io/badge/npm%20audit-0%20issues-brightgreen)](#security)
+
+A Claude Code skill that turns each version release (a git tag) into a published how-to guide, written in your own voice — and a React example for displaying it on your site.
+
+> **Build in public, by release.** Tag a release like you always do. Run `/devlog`. Each new version shows up on your site as a polished, end-to-end implementation guide — in your voice, with cited sources and the gotchas you actually hit — not raw commit messages.
+
+## Live example
+
+The skill is in production at [natejswenson.com/devlog](https://natejswenson.com/devlog), publishing to [github.com/natejswenson/daily-dev-log](https://github.com/natejswenson/daily-dev-log). What you see on that page is exactly what `npx @natjswenson/devlog preview` renders for you locally.
+
+## How it works
+
+1. **You ship a release** — tag it (e.g. `git tag v0.3.0`), like you already do.
+2. **Run `/devlog` in Claude Code.** The skill runs `devlog scan` to find tags that don't yet have an entry, researches the engineering topic behind each release, and writes a full setup → build → use → verify how-to guide (with a required `## Gotchas` section mined from your real fix commits, and 3+ cited sources). Every draft passes a deterministic lint (`devlog lint-post`) plus a quality self-review before it publishes. It's idempotent — re-running does nothing until you cut a new release, and a published entry is never overwritten (`devlog publish-entry` refuses).
+3. **Your site fetches it.** Static `manifest.json` + per-release markdown files served from `raw.githubusercontent.com` — no backend needed.
+
+You can also manage configuration conversationally in Claude Code: "add this repo to devlog", "stop tracking X", "set min sources to 4", or `/devlog status` to see what would be generated without writing anything.
+
+**In your voice.** Entries are written using a voice profile, resolved in this order: your `config.voicePath` → [ghostwriter](../ghostwriter)'s `voice/` dir if installed → a bundled default. devlog reads `voice-profile.md` (and `voice-notes.md` overrides) — never ghostwriter's `algorithm.md`, since LinkedIn reach tuning doesn't apply to a dev log.
+
+## Quick start
+
+```sh
+npx @natjswenson/devlog init
+```
+
+That command:
+- Creates `<your-username>/daily-dev-log` on GitHub (or uses an existing one)
+- Installs the skill at `~/.claude/skills/devlog/`
+- Writes `~/.claude/skills/devlog/config.json` with your answers
+- Lets you register one or more projects in a single run
+
+Then:
+
+```sh
+npx @natjswenson/devlog preview
+```
+
+to see your dev log rendered locally at `http://localhost:5173`.
+
+## Prerequisites
+
+- **Node 18+** — for the CLI and preview app
+- **GitHub CLI** (`gh`), authenticated with `gh auth login` — used to create your dev-log repo and push entries
+- **Claude Code** — to run the `/devlog` skill
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `npx @natjswenson/devlog init` | One-time setup: create dev-log repo, install skill, write config |
+| `npx @natjswenson/devlog add-project` | Register a project (interactive; `--yes --path <p>` for non-interactive/agent use) |
+| `npx @natjswenson/devlog remove-project <key> --yes` | Unregister a project (published entries stay) |
+| `npx @natjswenson/devlog set <field> <value>` | Update one config field (`targetRepo`, `branch`, `gitAuthor`, `githubUser`, `voicePath`, `deepDive.minSources`, `deepDive.topicDomains`) |
+| `npx @natjswenson/devlog config [--json]` | Show your current config with validation status |
+| `npx @natjswenson/devlog scan [--project <key>]` | JSON plan of new releases needing entries (used by the skill) |
+| `npx @natjswenson/devlog lint-post <file>` | Deterministic post-contract check (used by the skill) |
+| `npx @natjswenson/devlog publish-entry ...` | Copy a drafted entry into a clone + update the manifest; never overwrites (used by the skill) |
+| `npx @natjswenson/devlog preview` | Run a local preview at `http://localhost:5173` |
+| `npx @natjswenson/devlog --help` | Usage |
+| `npx @natjswenson/devlog --version` | Version |
+
+> **Tip:** run from any directory *outside* a clone of this repo. Running inside the repo causes a `package.json` name collision and `npx` fails with `command not found`.
+
+## What you end up with
+
+```
+~/.claude/skills/devlog/
+├── SKILL.md          # The /devlog slash-command instructions
+├── config.json       # Your settings (mode 0600)
+└── voice/            # Bundled fallback voice profile (last resort)
+    ├── voice-profile.md
+    └── voice-notes.md
+
+github.com/<you>/daily-dev-log/   # Created by init, populated by /devlog
+├── myproject/
+│   ├── manifest.json
+│   ├── v0.3.0.md
+│   ├── v0.2.0.md
+│   └── ...
+└── ...
+```
+
+## Manual setup (if you prefer)
+
+```sh
+gh repo create <you>/daily-dev-log --public --add-readme
+mkdir -p ~/.claude/skills/devlog/voice
+curl -o ~/.claude/skills/devlog/SKILL.md https://raw.githubusercontent.com/natejswenson/devlog/main/SKILL.md
+# Optional fallback voice profile (used when voicePath and ghostwriter are both absent):
+curl -o ~/.claude/skills/devlog/voice/voice-profile.md https://raw.githubusercontent.com/natejswenson/devlog/main/voice/voice-profile.example.md
+curl -o ~/.claude/skills/devlog/voice/voice-notes.md https://raw.githubusercontent.com/natejswenson/devlog/main/voice/voice-notes.example.md
+# Then copy config.example.json → ~/.claude/skills/devlog/config.json and fill it in
+```
+
+## Add to your site
+
+### React (drop-in)
+
+```sh
+cp -r examples/react/ your-site/src/devlog/
+```
+
+Edit `your-site/src/devlog/devlog-config.js` to point at your repo, then:
+
+```jsx
+import DevLogPage from './devlog/DevLogPage.jsx';
+
+<DevLogPage project="myproject" />
+```
+
+Full instructions: [`examples/react/README.md`](./examples/react/README.md).
+
+### No site yet?
+
+The `preview/` directory is a complete deployable Vite app. Set `VITE_DEVLOG_OWNER` / `VITE_DEVLOG_REPO` / `VITE_DEVLOG_PROJECTS` env vars on Vercel, Netlify, or Cloudflare Pages, build with `vite build`, deploy `dist/`. See [`preview/README.md`](./preview/README.md).
+
+### Other stacks (Next, Astro, plain HTML)
+
+It's static JSON and Markdown on GitHub. Build whatever UI you want — see the **Data contract** below.
+
+## Data contract
+
+The dev-log repo has this layout, all served as raw files from `https://raw.githubusercontent.com/<owner>/<repo>/<branch>/`:
+
+```
+<repo>/
+└── <project-key>/
+    ├── manifest.json          # Index of all entries (newest first)
+    ├── v0.3.0.md              # One entry per release (named by version)
+    ├── v0.2.0.md
+    └── ...
+```
+
+**`manifest.json`:**
+```json
+{
+  "entries": [
+    { "date": "2026-06-08", "file": "v0.2.0.md", "title": "...", "summary": "...", "version": "v0.2.0" }
+  ]
+}
+```
+
+Strict validation rules (entries that don't match are silently dropped by the React example):
+- `date` matches `YYYY-MM-DD` (the release/tag date)
+- `file` matches `^[a-zA-Z0-9._-]+\.md$`
+- `title` and `summary` are non-empty strings
+- `version` (optional) matches `^[a-zA-Z0-9._-]+$`
+
+**Entry markdown:**
+
+```markdown
+---
+title: "Essay-style title (never 'release vX.Y.Z')"
+date: 2026-06-08
+project: myproject
+version: v0.2.0
+tags: [reliability, python]
+summary: "1-2 sentence hook framing the how-to"
+---
+
+## Shipped
+What the release delivered, then the pivot to the topic the guide teaches.
+
+## <Setup / build / use-and-verify sections>
+An end-to-end implementation guide a reader can follow without your repo:
+complete, language-tagged code blocks; reader-side verification steps.
+
+## Gotchas
+Real traps from the release's history, each: trap → symptom → escape.
+
+## Sources
+- [Title](https://...) — what it supports  (3+ distinct URLs)
+
+## Changelog
+- commit message ([abc1234](https://github.com/.../commit/abc1234567...))
+```
+
+That's the entire contract — `npx @natjswenson/devlog lint-post <file>` checks the mechanical parts of it.
+
+## Configuration reference
+
+`~/.claude/skills/devlog/config.json`:
+
+| Field | Type | Description |
+|---|---|---|
+| `targetRepo` | `"<owner>/<repo>"` | Repo where dev log entries are published. Must match `^[a-z0-9][a-z0-9._-]*\/[a-z0-9][a-z0-9._-]*$`. |
+| `branch` | string (optional) | Branch in the dev-log repo. Defaults to `main`. Must not contain `..` or start with `-`. |
+| `gitAuthor` | string | Your name. Retained for backward compatibility; it is **not** currently rendered on entries (the author filter was removed, and release notes summarize all commits in a tag range). Still **required** by config validation — it must be present and non-empty (don't drop it). Whitespace OK; no shell metacharacters. |
+| `githubUser` | string | Your GitHub username. |
+| `voicePath` | string (optional) | Directory holding `voice-profile.md` (and optionally `voice-notes.md`) used to write entries in your voice. A leading `~` is expanded. If unset, devlog uses ghostwriter's `voice/` if installed, else the bundled default. Read only — never shell-interpolated. |
+| `projects` | array | One entry per project you want dev logs for. |
+| `projects[].key` | string | Subdirectory name in the dev-log repo. Strict token: `^[a-z0-9][a-z0-9._-]*$`, no `..`. |
+| `projects[].label` | string (optional) | Display name for the tab. Defaults to `key`. |
+| `projects[].path` | string | Local filesystem path to the project. Whitespace OK. |
+| `projects[].remote` | `"<owner>/<repo>"` | The project's GitHub remote. Used to mark public commits and link them. |
+| `projects[].pathFilter` | string (optional) | Repo-relative subdir scoping this project's commits in a monorepo (e.g. `skills/devlog`). |
+| `projects[].tagPrefix` | string (optional) | Prefix of the git tags that mark this project's releases (e.g. `devlog-v`). Defaults to `v`. Used in `git tag --list '<tagPrefix>*'`. |
+| `deepDive` | object (optional) | Controls the researched how-to. `topicDomains` (array, default `["AI", "DevOps/SRE", "software engineering"]`) steers topic selection; `minSources` (integer 1-10, default 3) is the floor of **distinct** cited source URLs per post. |
+
+See [`config.example.json`](./config.example.json) for a complete template, or run `npx @natjswenson/devlog config` to inspect your current config with validation.
+
+## Security
+
+The package is designed to be safe to install on a developer's machine and have ambient gh/git credentials. See [SECURITY.md](./SECURITY.md) for the full threat model and audit history.
+
+**At a glance:**
+- ✓ All shell calls in the CLI use `spawnSync` with argv arrays (no shell, no injection surface)
+- ✓ The skill validates every config field against an allowlist before interpolating into shell commands; instructs the LLM to single-quote interpolated values
+- ✓ Markdown rendering uses `react-markdown` with `skipHtml` and an allowlist `urlTransform` (only http(s)/mailto allowed; data:, javascript:, vbscript:, file:, blob: all neutralized)
+- ✓ Frontmatter parser uses `Object.create(null)` + key allowlist (no prototype pollution)
+- ✓ All external JSON is schema-validated before use (manifest, env-var projects array)
+- ✓ Vite dev server bound to `localhost`, CORS off
+- ✓ Demo-mode `window.fetch` override gated to dev builds only
+- ✓ `config.json` written atomically (tmp + rename), mode 0600
+- ✓ All dependencies pinned to exact versions
+- ✓ `npm audit`: 0 known vulnerabilities
+
+**To report a vulnerability:** open a [GitHub security advisory](https://github.com/natejswenson/devlog/security/advisories/new). Do not open a public issue.
+
+## Customization
+
+- **Tweak the entry template:** edit `~/.claude/skills/devlog/SKILL.md` (Generate mode, Step 3 — the how-to contract).
+- **Tweak your voice:** edit the `voice-profile.md` / `voice-notes.md` in your `voicePath` (or `~/.claude/skills/devlog/voice/`).
+- **Tune research depth:** `npx @natjswenson/devlog set deepDive.minSources 4`, or `set deepDive.topicDomains "security, platform engineering"`.
+- **Tweak the UI:** override the `--devlog-*` CSS variables in `examples/react/DevLogPage.css` to match your theme.
+- **Add or remove projects:** `npx @natjswenson/devlog add-project` / `remove-project <key> --yes` — or just tell Claude ("add this repo to devlog").
+
+## Testing & evals
+
+The deterministic core (`lib/`, the CLI) is covered by `npm test` (node:test; scan tests
+run against real throwaway git repos). The non-deterministic half — post quality — is
+covered by a cost-capped eval harness:
+
+```sh
+node evals/run_eval.mjs --mock    # $0, runs in CI; deterministic layer only
+node evals/run_eval.mjs --live    # LLM judge on golden fixtures; quotes spend, hard cap $0.50
+```
+
+The judge scores reproducibility, code completeness, gotcha quality, citations, voice,
+and scope honesty (pass ≥ 7/10). Without `ANTHROPIC_API_KEY` in the environment, mock
+mode is forced — CI can never spend money.
+
+## Troubleshooting
+
+**`sh: devlog: command not found` when running `npx`:** you're inside a checkout of this repo. The local `package.json` name collides with the published one. Run `npx` from somewhere else, e.g. `cd ~ && npx @natjswenson/devlog ...`.
+
+**Init prompts show `78` after placeholder text:** that's an artifact of how some output capture tools render `\x1b7`/`\x1b8` (cursor save/restore) escape sequences. In a real interactive terminal, you won't see it.
+
+**Preview is blank / no tabs / no entries:** check the browser console. If you see CJS interop errors related to `react-dom/client`, `style-to-js`, or `react-markdown`, you're on a pre-0.1.6 release — upgrade with `npm cache clean --force && rm -rf ~/.npm/_npx && npx --yes @natjswenson/devlog@latest preview`.
+
+**Init can't find `gh`:** install via [cli.github.com](https://cli.github.com/) and run `gh auth login`.
+
+**`Config validation failed: ...`** — the validator rejected something in your `config.json`. Run `npx @natjswenson/devlog config` for a detailed diagnosis. Common causes:
+- A field has shell metacharacters (`;` `&` `|` `` ` `` `$` etc) — see SKILL.md for the full list
+- A project key contains `..` or `/`
+- A path doesn't exist on disk
+
+**Preview shows "Setup required":** you deployed the preview app standalone but didn't set the env vars. Set `VITE_DEVLOG_OWNER`, `VITE_DEVLOG_REPO`, `VITE_DEVLOG_PROJECTS` (JSON-stringified array) in your hosting environment.
+
+## Versioning
+
+Releases are documented in [CHANGELOG.md](./CHANGELOG.md). The package follows semver — bug fixes/security patches in patch releases (0.1.x), behavior changes in minor (0.x.0).
+
+## License
+
+MIT

package/SKILL.md

@@ -16,7 +16,7 @@ actual work, backed by cited reputable sources, and including **gotchas earned f
 experience**. The release is the springboard; the teaching is the point.
 
 The deterministic work (release discovery, post linting, manifest updates, config edits)
-is done by the `@natjswenson/devlog` CLI — invoke it as `npx -y @natjswenson/devlog <cmd>`.
+is done by the `@natjswenson/devlog` CLI — invoke it as `npx -y @natjswenson/devlog@latest <cmd>`.
 Every agent-facing command prints JSON.
 
 ## Decide which mode you're in
@@ -38,10 +38,10 @@ Map the user's request onto the CLI — never hand-edit `config.json`:
 
 | Intent | Command |
 |---|---|
-| 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`, `targetDir`, `gitAuthor`, `githubUser`, `voicePath`, `deepDive.minSources`, `deepDive.topicDomains`) |
+| Show config | `npx -y @natjswenson/devlog@latest config --json` |
+| Add a project | `npx -y @natjswenson/devlog@latest add-project --yes --path <abs-path> [--key K] [--remote O/R] [--label L] [--tag-prefix P] [--path-filter F] [--private]` |
+| Remove a project | `npx -y @natjswenson/devlog@latest remove-project <key> --yes` |
+| Change a setting | `npx -y @natjswenson/devlog@latest set <field> <value>` (settable: `targetRepo`, `branch`, `targetDir`, `gitAuthor`, `githubUser`, `voicePath`, `deepDive.minSources`, `deepDive.topicDomains`) |
 
 `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
@@ -71,26 +71,32 @@ fix the named field via `set`.
 
 ## Status mode
 
-Run `npx -y @natjswenson/devlog scan --json` and render a compact table: project, new
-releases (version + date + commit count), and skipped tags worth mentioning (reason
-`prerelease`, `empty-range`, etc. — omit `entry-exists` noise unless asked). Note
-`tagFetch: "failed"` ("using local tags only") and `existenceCheck: "failed"` ("couldn't
-confirm which entries exist; publish will still refuse overwrites"). Write nothing.
+Run `npx -y @natjswenson/devlog@latest scan --json --summary` and render a compact table:
+project, new releases (version + date + `commitCount`), and skipped-tag counts worth
+mentioning (`prerelease`, `empty-range`, `entry-tombstoned`, etc. — omit `entry-exists`
+noise unless asked). Note `tagFetch: "failed"` ("using local tags only") and
+`existenceCheck: "failed"` ("couldn't confirm which entries exist; publish will still
+refuse overwrites"). Write nothing.
 
 ## Generate mode
 
 ### Step 1: Scan for new releases
 
 ```bash
-npx -y @natjswenson/devlog scan --json            # all projects
-npx -y @natjswenson/devlog scan --json --project '<key>'   # one project
+npx -y @natjswenson/devlog@latest scan --json --summary            # the plan table
+npx -y @natjswenson/devlog@latest scan --json --project '<key>'    # full detail, one project
 ```
 
-The JSON plan contains everything discovery used to require: per project, the
-`newReleases` array (`tag`, `version`, `date`, `prevTag`, `commits[{hash, subject, date,
-public}]`, `diffstat`) plus `skippedTags` with reasons, and the resolved `deepDive`
-settings (`minSources`, `topicDomains`). Handle the edges:
+Start with `--summary`: per project it gives `newReleases` (`tag`, `version`, `date`,
+`commitCount`), per-reason `skippedTags` counts, `publishedEntries` (every live entry's
+`version`/`title`/`tags` — the topic-dedup input for 3b), and the resolved `deepDive`
+settings (`minSources`, `topicDomains`). When you start writing a project's posts, run
+the full per-project scan for its `commits[{hash, subject, date, public}]` and
+`diffstat`. Handle the edges:
 
+- The output echoes `cliVersion` — the version npx actually ran. npx caches aggressively;
+  if it's older than the version this SKILL.md shipped with, say so and re-run (the
+  `@latest` pin usually prevents this).
 - `error: "unknown-project"` → list `availableKeys` and stop.
 - `totalNewReleases: 0` → tell the user nothing new was tagged (mention notable skipped
   tags) and stop. Do not create empty entries.
@@ -150,14 +156,28 @@ trivia or niche internals. If the obvious topic is repo-specific, step up one le
 the general pattern behind it — the test is "could a reader finish this how-to and have
 something working of their own?" When a release spans two candidate topics (or two
 releases in one run share one), don't write the same guide twice: give each post the
-most usable topic the run hasn't already covered. In a monorepo, one commit can appear
-in several projects' ranges — it belongs to the post whose release story it is; other
-posts leave it out of their narrative and `## Changelog` (check what sibling entries
-already cover, across all projects).
+most usable topic the run hasn't already covered. **The same rule applies against the
+whole catalog**: before settling on a topic, check every project's `publishedEntries`
+(titles + tags, in the scan output) — if an existing entry already teaches this topic,
+find the angle this release genuinely adds, or step to the next-most-usable topic.
+Never publish a near-duplicate of a guide the catalog already has. Vary the surface
+too: don't reuse the catalog's title shapes ("How to …" again and again) or repeat the
+same section-heading skeleton post after post.
+
+In a monorepo, one commit can appear in several projects' ranges — it belongs to the
+post whose release story it is; other posts leave it out of their narrative and
+`## Changelog` (`publish-entry` refuses a draft whose Changelog repeats a commit an
+existing entry already lists). **Never force a second angle the history doesn't
+support**: if the twin release has no story of its own beyond the shared commits, give
+it a proportionally small post — or fold it into the sibling's `## Shipped` — rather
+than inventing a premise to differentiate it.
 
 **3c. Research before writing.** Use web search/fetch to gather at least
 `deepDive.minSources` **distinct** reputable sources: official docs and release notes,
-standards bodies, primary research, well-regarded engineering writing. Avoid SEO farms.
+standards bodies, primary research, well-regarded engineering writing. A content farm
+or SEO-mill page never counts toward `minSources` — when a concept has a primary source
+(the original paper, the official docs, the pattern's canonical text), cite that, not a
+summary site that ranks for the keyword.
 Every specific external claim (a version, a behavior, a study, a definition) must be
 backed by a source you actually verified — if you can't source it, don't claim it. Don't
 lean on one URL for most claims. Keep a working `(claim, url)` list. Fetch tools can
@@ -277,16 +297,28 @@ Write each draft with the **Write tool** (never a bash heredoc) to a temp dir
 (`mktemp -d` once, reuse the absolute path — shell variables don't persist across bash
 calls). Name it `<version>.md`. Then:
 
-1. **Lint:** `npx -y @natjswenson/devlog lint-post '<abs-draft-path>'` — fix every
-   finding (missing sections, thin gotchas, too few distinct sources, sources listed
-   but never cited inline, untagged fences).
-2. **Assemble-and-run check:** when the post's code is runnable without external
-   services, copy its code blocks in order into a scratch dir and execute them exactly
-   as a reader would. Anything undefined, out of order, or missing an entrypoint fails
-   the stranger test mechanically — fix the post, not just the scratch copy.
-3. **Self-review against the how-to contract**, honestly, as a skeptical reader: walk
+1. **Ground-truth gate.** List every claim the draft makes about the user's own repo —
+   a tag exists or doesn't, a count ("seven tests went red"), a timeline, an outcome —
+   and verify each one with a git command run NOW, in this session (`git tag -l`,
+   `git show`, `git log`), the same way 3c keeps a `(claim, url)` list for external
+   claims. A claim you can't verify gets removed, not softened. A specific number is
+   publishable only if it appears in a commit, a diff, or a fetched source — otherwise
+   drop the precision ("several", not "seven"). And never label output as real ("that's
+   the real output", "from my actual run") unless the command that produced it ran in
+   this session — unrun output is always framed as expectation ("you should see…").
+2. **Lint:** `npx -y @natjswenson/devlog@latest lint-post '<abs-draft-path>' --voice` —
+   fix every finding (missing sections, thin gotchas, too few distinct sources, sources
+   listed but never cited inline, untagged fences, voice violations).
+3. **Assemble-and-run check:**
+   `npx -y @natjswenson/devlog@latest assemble-post '<abs-draft-path>' --out '<scratch>/assemble/<version>'`
+   extracts the draft's code blocks in order as numbered files (`text` fences are
+   expected output, listed but not written). When the code is runnable without external
+   services, execute the blocks exactly as a reader would. Anything undefined, out of
+   order, or missing an entrypoint (or an install step the post never shows) fails the
+   stranger test mechanically — fix the post, not just the scratch copy.
+4. **Self-review against the how-to contract**, honestly, as a skeptical reader: walk
    points 1-8 above plus voice adherence. Revise the draft for any point that fails.
-4. At most **two** revision passes; then proceed with the best version and carry any
+5. At most **two** revision passes; then proceed with the best version and carry any
    residual weakness into the final summary (e.g. "v0.5.0: only 2 gotchas had commit
    evidence").
 
@@ -312,57 +344,66 @@ 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 '<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,
-#    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' \
-  --project '<key>' --slug '<version>' --out '<abs-scratch>'
-# Show the rendered <abs-scratch>/<key>/<version>.png in this session before continuing —
-# this interactive review IS the quality gate for the cover, the same way Step 4 is for
-# the prose.
-
-npx -y @natjswenson/devlog publish-entry \
-  --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,
-# a render failure not worth a second attempt) — publish still proceeds normally.
+Right after the clone, **Write `<abs-tmp>/run-state.json`**: the clone path, the planned
+releases, and a per-release status you update as each one drafts/lints/publishes. If the
+session is compacted or interrupted mid-run, re-read it instead of re-deriving paths
+from `/var/folders` archaeology.
+
+Per release:
+
+1. **Cover context.**
+   `npx -y @natjswenson/devlog@latest cover-context '<key>' '<version>' --clone '<content-root>'`
+   returns the style guide, icon catalog, and up to 3 reference cover paths. **Read
+   only the single most recent reference image** (image reads are the expensive part;
+   open another only if you're genuinely unsure the new cover is distinct). On
+   `{"error": "style-guide-missing"}`: skip cover composition for this release entirely
+   and proceed straight to publish-entry with no `--cover` flag.
+   Never block publish on a missing style guide.
+2. **Compose** using ONLY this release's title/tags/summary/`## Shipped` text
+   (never the raw draft file, never `## Changelog`) plus the style guide and icon catalog. 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 as the dominant visual
+   element; title/kicker stay secondary; two releases should never produce visually
+   similar covers. Follow the style guide's hero-zone grid contract: the illustration
+   lives in a `#hero-zone` container at exactly `x:150 y:425 width:1300 height:400`
+   (render-cover mechanically enforces this), one of two slots (single centered hero,
+   or two-node before/after), interior points snapped to a 25px grid; catalog icons
+   never go inside `#hero-zone` (optional small accent glyph near the kicker only,
+   bottom edge above y:400). Write the document with the Write tool to
+   `'<abs-scratch>/<key>/<version>.html'` — full `<!DOCTYPE html>` document, sized
+   `html, body { margin:0; width:1600px; height:900px; }`, font referenced only as
+   `font-family: 'DevlogCoverFont', sans-serif`.
+3. **Rasterize.**
+   `npx -y @natjswenson/devlog@latest render-cover '<abs-scratch>/<key>/<version>.html' --project '<key>' --slug '<version>' --out '<abs-scratch>'`
+   The HTML is the source of truth and **survives the render**: to fix a visual
+   problem, edit (or re-Write — if an Edit fails, re-Write the whole file) the same
+   .html and re-run render-cover; it re-renders whenever the HTML is present,
+   overwriting the old PNG. On `render-failed` (timeout / Chromium missing / font
+   missing / a `#hero-zone` geometry violation), retry composing once with the error
+   text fed back, or give up and proceed with no `--cover` flag. **Show the rendered
+   `<abs-scratch>/<key>/<version>.png` in this session before continuing —
+   this interactive review IS the quality gate for the cover**, the same way Step 4
+   is for the prose.
+4. **Publish.**
+   ```bash
+   npx -y @natjswenson/devlog@latest publish-entry \
+     --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 (missing style guide, a render
+   failure not worth a second attempt) — publish still proceeds normally. publish-entry
+   refuses three things; none is retried by workaround: an existing entry (`immutable`
+   — skip the release, note it), a tombstoned version (`tombstoned` — skip; that
+   identity was editorially retired), and a Changelog commit another entry already
+   lists (drop the commit from this draft's `## Changelog` and re-publish).
+
+Then, once, after all releases:
 
+```bash
 git -C '<abs-tmp>/<repo-name>' add .
 git -C '<abs-tmp>/<repo-name>' commit -m 'devlog: add release entries'
 git -C '<abs-tmp>/<repo-name>' push --no-tags origin '<branch>'
@@ -415,5 +456,17 @@ rules:
   not an error.
 - **Entry already exists** (skipped as `entry-exists`, or `publish-entry` refuses): a cut
   release is immutable; never overwrite, never delete.
+- **`entry-tombstoned`:** the release's entry was editorially retired (moved,
+  consolidated, or deleted on purpose) — skip it silently, never regenerate it.
+- **The user moved/consolidated/deleted a published entry by hand:** tombstone the
+  identity it left behind so no later run resurrects it:
+  `npx -y @natjswenson/devlog@latest tombstone --clone '<content-root>' --project '<key>'
+  --version '<vX.Y.Z>' --reason '<where it went>'` (commit + push like a publish).
+- **The user edited a published entry's prose/frontmatter:** resync its manifest row
+  (title/summary/date/tags — what the site index and RSS read) with
+  `npx -y @natjswenson/devlog@latest sync-entry --clone '<content-root>' --project '<key>'
+  --slug '<version>'`. If the result reports `coverStale: true` and the title/topic
+  changed, offer to recompose the cover (Step 5 flow, `--cover` via publish is not
+  needed — use the backfill commands or recompose+`render-cover`+commit).
 - **Unknown project argument:** list the available keys from the scan error.
 - **Config missing/invalid:** point at `npx @natjswenson/devlog init` / `set` and stop.