@natjswenson/devlog 0.11.2 → 0.13.0

package/CHANGELOG.md

@@ -2,21 +2,89 @@
 
 All notable changes to `@natjswenson/devlog` are documented here.
 
-## 0.11.2 (2026-07-28) — actually render the README on npmjs.com
-
-- **Fixed: the npm page still showed "No README data found" after 0.11.1.** That
-  release put README.md, LICENSE and CHANGELOG.md into the tarball (verified by
-  downloading it), which fixed what `npm install` delivers — but not the website.
-  npm reads README.md to populate the registry manifest's `readme` field when it
-  builds the publish manifest, which happens BEFORE the package's own `prepack`
-  hook runs. So the tarball had the file and the registry record did not.
-  Worse than merely empty: the stored value was the literal string
-  `ERROR: No README data found!`, and npmjs.com falls back to reading the
-  tarball only when that field is *absent* (compare `zod`, which renders fine
-  with no packument readme at all), so the error string kept winning.
-  The release workflow now stages the three files into the package directory
-  before `npm publish` is invoked at all, rather than relying on `prepack`.
-  Code unchanged.
+## 0.13.0 (2026-07-29) — a publish run now proves the entry is live
+
+Publishing reported success on a post that was never reachable. The content, cover
+and manifest all landed correctly, the push succeeded, every command returned `ok`,
+and the entry 404'd for an hour because the site's own project registry had never
+been told the project existed. A push is not a route, and this release stops the
+skill treating the two as the same thing.
+
+- **Added: `publish-entry` returns `firstEntryForProject`.** True when the call
+  created a project's first live entry, which is exactly when a rendering site needs
+  a new registry row. A project holding only tombstones still counts as first, since
+  a retired entry never implied a route. Previously nothing distinguished a project's
+  first publish from its fiftieth, so the one moment registration is required looked
+  identical to every run where it isn't.
+- **Added: `siteUrl` config field** (settable, optional, trailing slash stripped,
+  http(s) only) plus `siteUrl` in the scan output. The repo name is not the site name
+  — a repo named `example.io` is commonly served at `example.com` — so a publish run
+  had no way to reach the page it had just published.
+- **Added: SKILL.md Generate step 5b (register a project the site has never
+  rendered).** Find the site's registry, add the project, and *build the clone to
+  confirm the route exists* before pushing. Also warns that registry position can
+  decide feed order: a site sorting by date alone falls back to load order for
+  same-date entries, so a project appended last can render its newest entry last.
+- **Added: SKILL.md Generate step 6 (verify the entry is live).** Poll the published
+  URL until it returns 200 before reporting success; on a persistent 404, check the
+  registry first, then the host's build log, and report it as **not live**. With no
+  `siteUrl` configured, the run must say the entry is pushed but unverified rather
+  than call it published.
+- **Changed: the confirmation block leads with the verified live URL**, with the repo
+  blob URL demoted to secondary, and prints the failure on the `Live:` line rather
+  than a URL that may 404.
+
+## 0.12.0 (2026-07-28) — five composition slots; stop defaulting to before/after
+
+Minor rather than patch: this adds three new named composition slots, so covers
+generated after it will legitimately look different from covers generated before.
+Style-guide prose only — no code changed.
+
+- **Added: three composition slots**, taking the set from two to five. *Axis /
+  timeline* for posts about ordering, timing or a race; *nested / containment*
+  for scope, sandboxing, or a thing living inside a thing; *field / distribution*
+  for many items, sampling, coverage, or one anomaly among many.
+- **Fixed: compositional monoculture across a run.** Two-node before/after fits
+  almost any post *badly*, because nearly anything can be framed as a
+  transformation — so it was the slot the model kept reaching for. Fifty covers
+  that are each individually fine but all split-scene-with-a-connecting-line read
+  as one template with the labels swapped. That is the anti-similarity failure at
+  the level of the whole publication rather than the individual cover, which
+  nothing was checking for. The guide now requires identifying which slot each
+  reference cover from `cover-context` used, and picking a different one if two or
+  more already share the intended slot.
+- **Added: no rounded incidental shapes.** The no-rounded-corners rule now names
+  the shapes reached for without thinking — speech bubbles, callout balloons, pill
+  badges, tooltips, rounded terminal chrome — and says to check every `rx`/`ry`
+  and `border-radius` before rendering. One rounded bubble in an otherwise square
+  composition collapses the cover into web-app chrome.
+- **Added: never print a number the post did not state.** A figure that looks like
+  a measurement ("0 edits left", "3x faster", "~40ms") must appear literally in the
+  `## Shipped` text or the summary; fair entailment is not enough, because set in
+  mono on a cover it reads as something measured, and a reader who goes looking
+  for it will not find it. When the point is zero, draw the absence rather than
+  asserting a count.
+
+## 0.11.2 (2026-07-28) — attempted npm-page fix; did NOT work
+
+- **Attempted and failed: making npmjs.com render the README.** 0.11.1 put
+  README.md, LICENSE and CHANGELOG.md into the tarball (verified by downloading
+  the published artifact), which fixed what `npm install` delivers. This release
+  additionally staged those files into the package directory before
+  `npm publish` was invoked, on the theory that npm populates the registry
+  manifest's `readme` field from disk at that point. **It did not work.** After
+  publishing, `npm view <pkg> readme` still returns the literal string
+  `ERROR: No README data found!` for both packages.
+  That field appears to be sticky: it was set once by an early release that had
+  no README, and republishing with one present does not overwrite it. Since
+  npmjs.com only falls back to reading the tarball when the field is *absent*
+  (compare `zod`, which renders fine with none at all), the stale error string
+  keeps winning.
+  The ineffective staging step was reverted in the release workflow; the
+  `prepack` hook stays, because the tarball fix is real and verified. **The npm
+  web page for both packages is still blank** — an open issue, likely needing
+  npm support to clear the cached field.
+  Code unchanged in both skills.
 
 ## 0.11.1 (2026-07-28) — publish the README, LICENSE and CHANGELOG to npm
 

package/SKILL.md

@@ -41,12 +41,19 @@ Map the user's request onto the CLI — never hand-edit `config.json`:
 | 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`) |
+| Change a setting | `npx -y @natjswenson/devlog@latest set <field> <value>` (settable: `targetRepo`, `branch`, `targetDir`, `gitAuthor`, `githubUser`, `siteUrl`, `voicePath`, `deepDive.minSources`, `deepDive.topicDomains`) |
 
 `targetDir` is the subdirectory of `targetRepo` that holds the devlog content tree
 (e.g. `content/devlog` when the target is the site repo itself); unset/empty means the
 repo root. Set it with `set targetDir content/devlog`, clear it with `set targetDir ''`.
 
+`siteUrl` is the public base URL that repo is *served* at, with no trailing slash — used
+to verify a published entry actually renders (Generate step 6). **The repo name is not the
+site name**: a repo called `example.io` is commonly served at `example.com`, so take this
+from a working page, not from the repo. Without it a run can push but cannot confirm
+anything went live. Set with `set siteUrl 'https://example.com'`, clear with
+`set siteUrl ''`.
+
 For **add-project**: resolve the path first (the repo the user named, or the cwd), then
 detect what the CLI will use — key = directory basename, remote = `git -C '<path>' remote
 get-url origin`. In a monorepo, suggest a `--path-filter` (the project's subdir) and a
@@ -412,7 +419,65 @@ rm -rf '<abs-tmp>'
 
 If the push fails, report the error and stop — do not retry automatically.
 
-### Step 6: Confirm
+### Step 5b: Register a project the site has never rendered before
+
+`publish-entry` returns **`firstEntryForProject: true`** when the call created that
+project's first live entry. **A push is not a route.** A site that renders the devlog
+almost always keeps its own registry deciding *which* content directories become pages;
+content on disk that the registry doesn't list is built right past, and the entry 404s
+while every command in this skill reports success. Publishing a project's first entry is
+therefore a two-part job, and the CLI can only do the first part.
+
+When `firstEntryForProject` is true, **before the push**:
+
+1. Find the registry in the clone. It is a source file, not content — grep the site's
+   `src/` for the existing project keys (`grep -rn '<a-known-project-key>' <clone>/src`).
+   In an Astro/Next-style site it is typically a `PROJECTS` array the entry loader maps
+   over.
+2. Add the new project, matching the shape of the neighbouring rows exactly.
+3. **Build the site in the clone and confirm the route exists** (`npm ci && npx astro
+   build`, then check the output directory contains the new `<project>/<version>` path).
+   A registry edit that doesn't produce a route is not done.
+4. Run the site's own test suite if it has one, and commit the registry change together
+   with the content in the same push.
+
+If you cannot find a registry, say so plainly rather than assuming there isn't one; the
+verification in Step 6 is what actually settles it.
+
+**Registry position can decide feed order, not just visibility.** If the site sorts
+entries by date alone, same-date entries fall back to their load order, which is registry
+order — so a project appended to the end can render its newest entry last. After the build
+in step 3, check that the new entry appears where its date and publish numeral say it
+should, and report it if not.
+
+### Step 6: Verify the entry is actually live
+
+**Do not report a publish as successful until the published URL returns 200.** The push
+succeeding, the manifest updating, and the site serving the post are three different
+things, and this skill has previously reported success on all of the first two while the
+post 404'd.
+
+When `siteUrl` is set in config (it is echoed in the scan output):
+
+```bash
+curl -s -o /dev/null -w '%{http_code}' -L '<siteUrl>/devlog/<project>/<version>/'
+```
+
+Poll every ~45s for up to ~5 minutes; deploys are not instant. Then:
+
+- **200** → done, report the live URL as the primary link.
+- **Still 404 after the window** → the deploy failed or the entry is not routed. Check
+  `firstEntryForProject`/the registry from Step 5b first, since that is the most common
+  cause, then the host's build log. Report it as **not live**, with what you checked.
+- **`siteUrl` unset** → say the entry is pushed but unverified, give the repo URL, and
+  offer to set it: `npx -y @natjswenson/devlog@latest set siteUrl 'https://example.com'`.
+  Never describe an unverified push as published.
+
+The `/devlog/<project>/<version>/` path is this skill's default convention. If the site
+routes differently, take the pattern from a URL of an already-published entry rather than
+assuming this one.
+
+### Step 7: Confirm
 
 ```
 Release dev log entries published
@@ -420,13 +485,13 @@ Release dev log entries published
   Project: <key>
   Releases: <version>, ...
   Judged weaknesses: <residuals from Step 4, or "none">
-  URL: https://github.com/<targetRepo>/blob/<branch>/<targetDir-prefix><key>/<version>.md
+  Live: <siteUrl>/devlog/<key>/<version>/  (verified 200)
+  Source: https://github.com/<targetRepo>/blob/<branch>/<targetDir-prefix><key>/<version>.md
 ```
 
-(`<targetDir-prefix>` is `<targetDir>/` when set, empty otherwise.) When the target is
-a site repo that auto-deploys on push (e.g. Cloudflare Pages watching `main`), the
-publish push itself triggers the rebuild — mention that the entry goes live with the
-next deploy.
+(`<targetDir-prefix>` is `<targetDir>/` when set, empty otherwise.) Report the **verified
+live URL** as the primary link; the repo blob URL is the secondary one. If Step 6 could
+not verify, say so on the `Live:` line instead of printing a URL that may 404.
 
 ## Security rules
 

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

@@ -82,15 +82,39 @@ Never leave the band empty under a one-line headline. Whitespace is part of the
 only when it's *between* composed elements — a gap with nothing on either side of it is
 just a hole.
 
-**Two named composition slots** — pick one per post:
+**Five 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.
+- **Axis / timeline** — one horizontal (or vertical) run with marks, labels, and events
+  positioned along it. For anything about *ordering*, *timing*, or *a race*: what fired
+  when, what arrived late, what overlapped. The marks carry the meaning, not boxes.
+- **Nested / containment** — one shape inside another, or a stack of layers, showing
+  what wraps what, what's isolated from what, or where a boundary sits. For posts about
+  scope, sandboxing, encapsulation, or a thing living inside a thing.
+- **Field / distribution** — many small marks whose *arrangement* is the point: a
+  scatter, a cluster with an outlier, a grid with holes, a shape emerging from noise.
+  For posts about many items, sampling, coverage, or one anomaly among many.
 
 These are placement/proportion guidance, not literal templates — the actual shapes
 inside each slot are still freehand per post.
 
+**Do not default to two-node.** It is the easiest slot to reach for and it fits almost
+any post *badly*, because nearly everything can be framed as before/after. That framing
+is the single biggest threat to this set: fifty covers that are each individually fine
+but all split-scene-with-a-connecting-line read as one template with the labels swapped,
+which is the anti-similarity failure at the level of the whole publication rather than
+the individual cover.
+
+So, before you commit to a slot: **look at the reference covers `cover-context` handed
+you and identify which slot each one used.** If two or more of them used the slot you
+were about to pick, pick a different one — and only override that if the post's mechanism
+genuinely cannot be drawn any other way, which is rarer than it feels. Reach for
+single-centered-hero more often than instinct suggests; one well-drawn mechanism with
+nothing beside it is usually stronger than a comparison, and it is the slot most likely
+to be under-used across a long run.
+
 **A third option, when the post is genuinely about code or a terminal session:** the
 `.term` panel treatment (see Palette below) may fill some or all of `#hero-zone` instead
 of a freehand mechanism — a real, believable command/output snippet drawn from the
@@ -258,13 +282,24 @@ summary as on-image text.
   edges, fold lines, or any texture overlay — the paper is a flat hex, not a vintage
   poster prop.
 - Don't round any corner or drop any shadow, on the illustration or anywhere else on the
-  cover — PRESS structure comes from rules and whitespace, never rounded chrome.
+  cover — PRESS structure comes from rules and whitespace, never rounded chrome. This
+  includes *incidental* shapes you reach for without thinking: speech bubbles, callout
+  balloons, pill badges, tooltips, rounded terminal chrome. A speech bubble is a
+  rectangle with a triangular tail, not a lozenge. Check every `rx`/`ry` on an SVG rect
+  and every `border-radius` before you render — a single rounded bubble in an otherwise
+  square composition is the tell that collapses the whole cover into web-app chrome.
 - Don't let orange spread across the cover — one signature moment (see The accent law),
   never orange as a fill color for multiple shapes, never a background wash.
 - Don't set the headline, eyebrow, or numerals in the serif voice — that voice is for
   commentary only; structure is always the display face.
 - Don't invent editorial props that aren't backed by real data: no fabricated issue
   numbers, no barcodes, no pull-quotes that aren't an actual quote from the post.
+- Don't print a number the post didn't state. A figure that *looks* like a measurement
+  ("0 edits left", "3x faster", "~40ms") must appear literally in the `## Shipped` text
+  or the summary. A fair entailment is not enough: once it's set in mono on the cover it
+  reads as something that was measured, and a reader who goes looking for it in the post
+  won't find it. If the point is "none" or "zero," draw the absence — an empty frame, a
+  severed line, a gap where marks used to be — rather than asserting a count.
 - Don't leave old terminal furniture lying around outside a `.term` panel — no blinking
   cursor, no bare `_` suffix, no stray `$` prompt as decoration. The dark palette now
   belongs to exactly one place, the `.term` panel, and only when it's real code.

package/lib/config_ops.mjs

@@ -34,6 +34,7 @@ const SETTERS = {
   targetDir: (c, v) => (v === '' ? omit(c, 'targetDir') : { ...c, targetDir: v }),
   gitAuthor: (c, v) => ({ ...c, gitAuthor: v }),
   githubUser: (c, v) => ({ ...c, githubUser: v }),
+  siteUrl: (c, v) => (v === '' ? omit(c, 'siteUrl') : { ...c, siteUrl: v.replace(/\/+$/, '') }),
   voicePath: (c, v) => (v === '' ? omit(c, 'voicePath') : { ...c, voicePath: expandHome(v) }),
   'deepDive.minSources': (c, v) => {
     const n = Number(v);

package/lib/core.mjs

@@ -125,6 +125,19 @@ export function validateConfig(config) {
       throw new Error(`targetDir must be a relative path like "content/devlog" (no leading/trailing slash, no '..'): got ${JSON.stringify(config.targetDir)}`);
     }
   }
+  if ('siteUrl' in config) {
+    // Optional: the public base URL the target repo is served at, used only to
+    // confirm a published entry actually renders. The repo name is not the site
+    // name (a repo called `example.io` can be served at `example.com`), and
+    // pushing content is not the same as the site serving it, so this is the
+    // only way a publish run can verify itself rather than assume.
+    // Interpolated into a shell curl, hence the tight charset.
+    if (typeof config.siteUrl !== 'string'
+      || !/^https?:\/\/[A-Za-z0-9.-]+(:\d+)?(\/[A-Za-z0-9._~/-]*)?$/.test(config.siteUrl)
+      || config.siteUrl.endsWith('/')) {
+      throw new Error(`siteUrl must be an http(s) URL with no trailing slash, e.g. "https://example.com": got ${JSON.stringify(config.siteUrl)}`);
+    }
+  }
   if ('voicePath' in config) {
     // Optional: directory holding the voice profile used to write entries. Read by
     // the skill with the Read tool only — never shell-interpolated — so the only

package/lib/publish_entry.mjs

@@ -221,6 +221,14 @@ export function publishEntry({ cloneDir, project, version, entryPath, coverImage
   }
 
   const file = `${version}.md`;
+  // Whether this project had any live entry before this call. A site that
+  // renders the devlog typically keeps its own registry of which projects to
+  // render (content on disk is not the same as a route), and that registry is
+  // the thing a first-ever publish silently misses: the entry lands, the build
+  // walks past it, and the post 404s while every check reports success.
+  // Reported back so the caller can require registration exactly once per
+  // project, instead of relying on whoever is publishing to remember.
+  const hadLiveEntries = manifest.entries.some((e) => e && !e.removed);
   // Idempotent: legacy manifests may already reference this file/version even
   // when the .md was missing — never duplicate an index row.
   const already = manifest.entries.some((e) => e && (e.file === file || e.version === version));
@@ -247,7 +255,13 @@ export function publishEntry({ cloneDir, project, version, entryPath, coverImage
     manifestUpdated = true;
   }
 
-  return { written: destPath, manifestUpdated, coverWritten: !!coverFile, no };
+  return {
+    written: destPath,
+    manifestUpdated,
+    coverWritten: !!coverFile,
+    no,
+    firstEntryForProject: manifestUpdated && !hadLiveEntries,
+  };
 }
 
 // Editorially retire a release: after an entry is manually moved, consolidated,

package/lib/scan.mjs

@@ -288,6 +288,11 @@ export function scanAll(config, { projectKey = null, fetch = true, getExisting =
     // skill appends it to the publish clone path (`--clone <clone>/<targetDir>`).
     targetDir: config.targetDir || '',
     branch,
+    // Public base URL the target repo is served at, when configured — the skill
+    // uses it to confirm a published entry actually renders. null means the run
+    // can push but cannot verify, which the skill has to say out loud rather
+    // than report an unverified publish as a success.
+    siteUrl: config.siteUrl || null,
     deepDive: resolveDeepDive(config),
     voicePath: config.voicePath || null,
     projects: results,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@natjswenson/devlog",
-  "version": "0.11.2",
+  "version": "0.13.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",