@natjswenson/devlog 0.5.2 → 0.8.1

package/SKILL.md

@@ -39,7 +39,7 @@ 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]` |
+| 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`) |
 
@@ -51,6 +51,16 @@ get-url origin`. In a monorepo, suggest a `--path-filter` (the project's subdir)
 and show the resulting project list. For **remove-project**, confirm once before running;
 tell the user published entries are not deleted.
 
+**Private repos.** If the user says the repo is private (or a source repo happens to be
+private on GitHub even though it's configured normally), pass `--private`. A private
+project's commits are never marked public in the scan (see Generate mode), so no post ever
+links a commit for it, `## Changelog` is always omitted, and `--remote` is optional — the
+tool has no reason to know or use the repo's GitHub location. This is a declared project
+*type*, not something auto-detected from the GitHub API: `remoteMatches` + "on the
+published branch" alone doesn't imply the repo is public, so a project with a real, correctly
+configured remote that happens to sit in a private repo needs this flag or its commits would
+otherwise scan as public.
+
 If any command prints `{"error": "config-missing", ...}`, tell the user to run
 `npx @natjswenson/devlog init` first. On `config-invalid`, show the message and offer to
 fix the named field via `set`.
@@ -109,30 +119,55 @@ For each new release, in order:
 
 **3a. Understand what actually shipped.** The scan gives you commit subjects and a
 diffstat. When you need more, read the real changes — validate every hash matches
-`^[0-9a-f]{7,40}$` first, then:
+`^[0-9a-f]{7,40}$` first, then (when a commit message and its diff disagree on a
+specific fact — a count, a filename, a behavior — the diff wins):
 
 ```bash
 git -C '<project.path>' show --stat '<hash>'
 git -C '<project.path>' show '<hash>' -- '<project.pathFilter>'
 ```
 
+Teach the code **as it existed at this tag**, not as it looks today — the repo may have
+moved on since the release. When you need a file's state rather than a diff, use
+`git -C '<project.path>' show '<tag>:<file>'` instead of reading the working tree.
+This anchors the **facts** (what shipped, what it did); the teaching implementation may
+still be a cleaner generalization per the how-to contract — anchor claims at the tag,
+generalize the code.
+
 **3b. Derive the topic.** Identify the **one** substantive engineering topic the work
 touched (occasionally more, only when the work genuinely spans them) within
 `deepDive.topicDomains`. The topic is the general concept *behind* what shipped (e.g.
 shipping a `feature→dev→main` flow → branching strategy and release engineering). Never
 pad with topics the work didn't touch.
 
+Between candidate topics, pick the one the reader can most plausibly **use**: a
+transferable technique they could apply to their own project this week beats project
+trivia or niche internals. If the obvious topic is repo-specific, step up one level to
+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).
+
 **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.
 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.
+lean on one URL for most claims. Keep a working `(claim, url)` list. Fetch tools can
+summarize a page into quote-shaped text that isn't on it: before putting anything in
+quotation marks, re-fetch asking for the verbatim wording and drop the quotes (paraphrase
+instead) if it can't be confirmed.
 
 **3d. Mine the gotchas.** Gotchas are the post's signature — **real traps from the
 user's own experience**, never invented. Look for them in: fix commits that follow the
 feature commits in the range, revert commits, `CHANGELOG` "Fixed" entries for this
-version, and corrections visible in the diffs (an approach that changed mid-range). Each
+version, and corrections visible in the diffs (an approach that changed mid-range).
+Also follow the code this release introduced **forward** in history (`git log '<tag>..'
+-- <files it touched>`): a later fix to that same code is prime gotcha material, as long
+as the post says plainly when it was discovered ("this bit us a few weeks later"). Each
 gotcha is written as **trap → symptom → escape**, concretely. If the history genuinely
 shows none, the `## Gotchas` section instead covers the sourced failure modes a reader
 will hit first, clearly framed as "what to watch for" rather than as personal war stories.
@@ -141,11 +176,13 @@ will hit first, clearly framed as "what to watch for" rather than as personal wa
 
 ```markdown
 ---
-title: "<essay-style title; NOT 'release vX.Y.Z'>"
+title: "<essay-style title in sentence case (capitalize only the first word and proper nouns); NOT 'release vX.Y.Z'>"
 date: <release date from scan>
 project: <project key>
 version: <version from scan>
-tags: [<2-5 lowercase topic tags>]
+tags: [<5-10 specific, lowercase tags — tools, techniques, and concepts actually
+  present in the post, not just broad topic labels, e.g. git, ci-cd,
+  release-engineering, github-actions, semver, changelog-automation>]
 summary: "<1-2 sentence hook that frames the how-to, not just what shipped>"
 ---
 
@@ -154,6 +191,11 @@ summary: "<1-2 sentence hook that frames the how-to, not just what shipped>"
 <2-4 sentences: what this release delivered, plainly, then pivot to the topic the guide
 teaches. The only purely-changelog part.>
 
+<!-- Between Shipped and Gotchas, the headings below are the default shape, not a
+requirement — only Shipped, Gotchas, and Sources are mandatory. Merge or reorder the
+middle sections when the walkthrough flows better that way. Fence command OUTPUT
+blocks as `text`. -->
+
 ## <Descriptive heading: setup / prerequisites>
 
 <What a reader needs before the core build: dependencies, config, data model. Code block
@@ -189,11 +231,17 @@ the wiring between pieces, not just the interesting line.>
 2. **Complete code.** Every symbol a code block references is defined in an earlier
    block or explicitly stubbed with a one-line note ("`load_fixtures()` returns your test
    DB handle"). The blocks compose into a runnable whole — no phantom fixtures or elided
-   helpers. Aim for the essential blocks (roughly 3-6 for a substantive feature); a clean,
+   helpers, and if a later block revises an earlier function, show the complete new
+   function, never a fragment calling helpers no block defines. Aim for the essential blocks (roughly 3-6 for a substantive feature); a clean,
    general version of the concept is the goal, and never claim illustrative code is
    verbatim production source.
 3. **Reader-side verification.** The verify step gives commands the READER runs against
    THEIR implementation, with expected output — not proof that the author's repo works.
+   When the blocks are cheap to execute (scratch dir, no external services), actually
+   run them and paste the real output. Never present output as observed if you didn't
+   run the command; if you can't run it, frame the expectation ("you should see…").
+   Verbose real output (tracebacks, long logs) may be trimmed to the signal lines or
+   whitespace-normalized when the post says so.
 4. **Real gotchas** per 3d.
 5. **Source diversity** per 3c, cited inline as markdown links AND in `## Sources`.
 6. **Honest scope.** A single test file is not "end-to-end". Size the title, summary, and
@@ -202,12 +250,21 @@ the wiring between pieces, not just the interesting line.>
    teaser.
 7. **No leaked repo-specific artifacts.** Genericize or explain anything a stranger
    would trip on (`.example` suffixes, monorepo nesting, internal tool names).
+8. **Fun to follow.** The guide reads like a generous colleague walking the reader
+   through a build they'll actually finish: give an early runnable win, keep momentum
+   between steps, and make the payoff visible at each stage (show real output, not just
+   code). Fun comes from quick wins and concrete results — never forced jokes, hype, or
+   exclamation points.
 
 **Separate fact from concept.** What the user *did* comes only from commits/diffs —
 never invent metrics, motivations, or outcomes. What the topic *is* comes from the cited
 sources. Keep the two distinguishable. Match the voice profile + `voice-notes.md`
-(authenticity, anti-AI-tell, and punctuation rules), but NOT any length/reach rules —
-target ~900-1600 words for a substantive feature, shorter for a small change. Only link
+(authenticity, anti-AI-tell, and punctuation rules — these govern the PROSE; the em dash
+in the `## Sources` template line is fixed template punctuation, and verbatim quoted
+data such as commit subjects in `## Changelog` keeps its original punctuation),
+but NOT any length/reach rules —
+target ~900-1600 words of prose (code blocks don't count) for a substantive feature,
+shorter for a small change. Only link
 commits where `public: true` in the scan; omit `## Changelog` if none are.
 
 ### Step 4: Self-check before publishing
@@ -217,10 +274,15 @@ Write each draft with the **Write tool** (never a bash heredoc) to a temp dir
 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, untagged fences).
-2. **Self-review against the how-to contract**, honestly, as a skeptical reader: walk
-   points 1-7 above plus voice adherence. Revise the draft for any point that fails.
-3. At most **two** revision passes; then proceed with the best version and carry any
+   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
+   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
    residual weakness into the final summary (e.g. "v0.5.0: only 2 gotchas had commit
    evidence").
 
@@ -232,15 +294,51 @@ critique, not a rubber stamp.
 Clone once, publish each entry through the CLI, push once. `targetRepo` and `branch` come
 from validated config — still single-quote every interpolated value.
 
+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,
+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'
 
 # 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>'
+# 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),
+#    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 '<abs-tmp>/<repo-name>' --project '<key>' \
-  --version '<version>' --entry '<abs-draft-path>'
+  --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.
 
 git -C '<abs-tmp>/<repo-name>' add .
 git -C '<abs-tmp>/<repo-name>' commit -m 'devlog: add release entries'