@natjswenson/devlog 0.3.1 → 0.4.1

package/SKILL.md

@@ -1,14 +1,20 @@
 ---
 name: devlog
-description: Generate a dev log entry for each new version release from git tags, written in your own voice, and publish to GitHub
+description: Generate a researched, cited blog post for each new version release from git tags, written in your own voice, and publish to GitHub
 user_invocable: true
 ---
 
-# /devlog — Release Dev Log Generator
+# /devlog — Release Blog-Post Generator
 
-You are generating a dev log entry **for each new version release** (a semver git tag) in
-the user's projects, writing each entry **in the user's own voice**, and publishing them to
-a GitHub repo configured in `~/.claude/skills/devlog/config.json`.
+You are generating a **blog post for each new version release** (a semver git tag) in the
+user's projects, writing each in **the user's own voice**, and publishing them to a GitHub
+repo configured in `~/.claude/skills/devlog/config.json`.
+
+Each post is more than a changelog: a short "what shipped" hook, then a **deeply researched,
+end-to-end implementation guide** for the engineering topic(s) the work touched — how to build
+and use the technique, grounded in BOTH the user's actual work AND reputable, cited outside
+sources, with multiple copy-paste-reusable code blocks that form a complete, runnable whole
+(see Step 6).
 
 Usage: `/devlog` (all configured projects) or `/devlog <project-key>` (single project)
 
@@ -55,6 +61,11 @@ Optional fields:
   (e.g. `devlog-v` for tags like `devlog-v0.2.0`). Defaults to `v` (matching tags like
   `v1.4.0`). In a monorepo, each project sets its own prefix so its releases are detected
   independently.
+- `deepDive` — optional object controlling the researched deep-dive (Step 6). Repo-agnostic;
+  all values have sensible defaults:
+  - `topicDomains` — array of domains the deep dive may explore. Default
+    `["AI", "DevOps/SRE", "software engineering"]`.
+  - `minSources` — minimum reputable external sources to cite per post. Default `2`.
 
 ## Step 0: Load and validate config
 
@@ -266,42 +277,131 @@ git -C '<project.path>' branch --contains '<hash>' -r 2>/dev/null | grep -q 'ori
 - If the remote URL matches `<project.remote>` (i.e. `github.com/<project.remote>` or the SSH equivalent) and the commit is on the published branch, it's a public commit — link it using `https://github.com/<project.remote>/commit/<hash>`.
 - Otherwise, describe the change without linking.
 
-## Step 6: Generate the entry (in the user's voice)
+## Step 6: Research and write the blog post (in the user's voice)
+
+Each entry is a **proper blog post**, not a changelog: a short "what shipped" hook, then a
+**researched deep dive** into the engineering topic(s) the work touched. The release is the
+springboard; the teaching is the point. Every post must be grounded in BOTH the user's actual
+work AND **reputable outside sources, cited**.
+
+### Step 6a: Derive the deep-dive topic(s)
+
+From the release's real changes (Step 4), identify the **one** substantive topic the work
+touched (occasionally several, only when the work genuinely spans them) in the configured
+`deepDive.topicDomains` (default: AI, DevOps/SRE, and software engineering). 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.
+
+### Step 6b: Research — deeply, from reputable sources
+
+For each topic, **research before writing**. Use web search/fetch to gather authoritative
+sources and concrete, citable facts. Requirements:
+- **Prefer primary/authoritative sources:** official docs and release notes, standards bodies
+  (e.g. semver.org), primary research (e.g. DORA / *Accelerate*), and well-regarded
+  engineering writing (e.g. Martin Fowler / Thoughtworks, Atlassian, the project's own docs).
+  Avoid SEO content farms and low-signal blog spam.
+- **At least `deepDive.minSources` reputable sources** (default 2; aim for 3+ on a meaty topic).
+- **Every specific external claim must be backed by a source** — version numbers, behaviors,
+  research findings, definitions, statistics. If you can't source a specific claim, don't make
+  it. Verify facts against the source rather than recalling them.
+- Keep a working list of `(claim, url)` pairs to cite in the post.
+
+### Step 6c: Write the post
 
-For each new release, generate a markdown entry with this structure, writing the prose to
-match the voice profile resolved in Step 2 (its openers, rhythm, vocabulary, never-do):
+Structure (write the prose to match the voice profile resolved in Step 2 — openers, rhythm,
+vocabulary, never-do):
 
 ```markdown
 ---
-title: "<concise title for this release>"
+title: "<essay-style title; NOT 'release vX.Y.Z'>"
 date: YYYY-MM-DD
 project: <project.key>
 version: <version label, e.g. v0.2.0>
-summary: "<1-2 sentence summary of what shipped>"
+tags: [<2-5 lowercase topic tags, e.g. git, ci-cd, release-engineering>]
+summary: "<1-2 sentence hook that frames the deep dive, not just what shipped>"
 ---
 
-## What Shipped
+## Shipped
+
+<2-4 sentences: what this release actually delivered, plainly. End by pivoting to the topic
+the rest of the post explores. This is the only purely-changelog part.>
+
+## <Descriptive section heading for the deep dive / walkthrough>
+
+<The deep dive is an END-TO-END IMPLEMENTATION GUIDE, not a single illustrative snippet. A
+developer should be able to read this post and actually BUILD and USE the thing it's about.
+Weave together THREE threads throughout: (1) what the user actually did (grounded, first-person,
+no fabrication), (2) the general concept backed by the researched sources, cited inline as
+markdown links, and (3) the user's earned take/lesson.
+
+Cover the full path, in order, using descriptive section headings (split across multiple `##`
+sections — do not cram the whole build into one):
+
+- **Setup / prerequisites** — what's needed before the core code: dependencies, config, the
+  relevant data model, types, or interfaces. Include a code block whenever it has real content
+  (install command, schema, config file).
+- **Build it, step by step** — the core implementation broken into ordered steps, EACH with its
+  own language-tagged code block, that together form a COMPLETE, coherent, runnable whole, not
+  one isolated centerpiece function. Show the wiring between the pieces (how they call each
+  other), not just the most interesting line.
+- **Use it** — how to actually invoke or run the result, with a code block showing the call site
+  and a realistic example of its output or effect.
+- **Verify it / edge cases** — how to confirm it works (a test, an assertion, or what to check),
+  plus the one or two real failure modes worth calling out.
+
+This is a blog for DEVELOPERS: every code block must be real, correct, idiomatic, language-tagged,
+and copy-paste-reusable, and the blocks must be collectively complete enough to reproduce the
+LOAD-BEARING path of the feature. Aim for the essential blocks (roughly 3-6 for a substantive
+feature, fewer for a small change) — show the pieces that carry the idea and the wiring between
+them, not every helper, import, or obvious glue line. Favor one clear block per step over many
+tiny ones or one giant dump; if a block isn't teaching something, cut it. A clean, general
+version of the concept is the goal; it need not be the user's exact source. Use inline `code`
+for identifiers.>
+
+## <Next build/use section — continue the walkthrough>
 
-<Narrative paragraphs about what this version delivers. Focus on WHAT changed and WHY it
-matters to someone using or following the project, not raw commit messages. Group related
-commits into the handful of changes that actually matter. Write in the user's voice per the
-resolved voice profile.>
+<...>
 
-## What's Next
+## Sources
 
-<Brief 1-2 sentence forward-looking note based on the trajectory of the work.>
+- [<source title>](<url>) — <one phrase on what it supports>
+- [<source title>](<url>) — <...>
 
-## Commits
+## Changelog
 
 - <commit message> ([short-hash](https://github.com/<project.remote>/commit/full-hash))
 ```
 
 **Important rules for content generation:**
-- "What Shipped" is a NARRATIVE release note, not a commit list. Describe the changes that matter, grouped, with their impact.
-- Match the **voice profile** for tone and phrasing; let `voice-notes.md` override it. Do NOT apply any LinkedIn reach rules — this is a dev log.
-- Only include the "Commits" section's links for commits on the published branch of a public repo.
-- "What's Next" should be a reasonable inference from the release's trajectory — never a fabricated roadmap.
-- **Never invent** metrics, motivations, or outcomes the commits don't support.
+- **Separate fact from concept.** What the user *did* comes only from the commits/diff — never
+  invent metrics, motivations, decisions, or outcomes the work doesn't support. What the topic
+  *is* comes from the cited sources. Keep the two clearly distinguishable to the reader.
+- **No unsourced external claims.** Any specific fact about the wider world (a version, a
+  behavior, a study, a definition) needs a `## Sources` citation. General reasoning and the
+  user's own opinions don't need a citation, but must be clearly the user's view.
+- **Match the voice profile + `voice-notes.md`** for tone and phrasing. Apply the voice's
+  authenticity, anti-AI-tell, and punctuation rules (e.g. no em dashes if the profile bans
+  them; no rhetorical fragment-lists; no clever-symmetry "payoff" closer; end on the last real
+  point). Do **NOT** apply the profile's LinkedIn length/reach rules — a blog implementation
+  guide needs room (target ~900–1600 words for a substantive feature; shorter for a genuinely
+  small change; as long as a complete, honest walkthrough requires, never padded).
+- **Accessible but substantive:** a curious non-expert can follow the entry, an experienced
+  engineer still learns something non-obvious.
+- **Write it as an END-TO-END implementation guide, not a snippet showcase.** The post must
+  teach a developer how to BUILD and USE the technique, not just glimpse it. Walk the full path:
+  setup/prerequisites → the implementation built up step by step across MULTIPLE code blocks
+  that form a complete, runnable whole → how to invoke/use it → how to verify it (and the key
+  failure modes). A reader should be able to reproduce the feature from the post alone. Every
+  code block is real, correct, idiomatic, language-tagged, and copy-paste-reusable; show the
+  load-bearing pieces and how they wire together, but keep it lean (roughly 3-6 blocks for a
+  substantive feature) — don't block every helper, import, or obvious glue line, and cut any
+  block that isn't teaching something. The code need NOT be the user's exact source (a clean, general version
+  of the concept is fine), but never claim illustrative code is verbatim production source and
+  never put fabricated metrics/results in it. **Right-size honestly:** a genuinely small change
+  gets a proportionally shorter guide that still shows the full build-and-use path; never pad a
+  thin change to look bigger, and never shrink a real feature to a single teaser block.
+- Only include the `## Changelog` links for commits on the published branch of a public repo
+  (per Step 5); omit the section if there are none.
 
 ## Step 7: Push to GitHub
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@natjswenson/devlog",
-  "version": "0.3.1",
-  "description": "Release dev log generator — Claude Code skill + preview app for publishing version-release dev logs, written in your voice, to your site",
+  "version": "0.4.1",
+  "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",
   "homepage": "https://github.com/natejswenson/devlog",

package/CHANGELOG.md

@@ -1,145 +0,0 @@
-# Changelog
-
-All notable changes to `@natjswenson/devlog` are documented here.
-
-## 0.3.1 (2026-06-20) — fetch tags before discovering releases
-
-**Fixed**
-- `/devlog` now runs a best-effort `git fetch --tags --quiet` per project at the
-  start of release discovery (Step 3), before listing tags. Releases are
-  commonly cut by CI on the remote (a version-driven GitHub Release on green
-  `main`/`master`), so the tag is born on the remote; a local clone that hadn't
-  fetched would list only stale local tags and silently report "no new release"
-  for a release that was already live. The fetch is best-effort: on failure
-  (offline, no remote, auth prompt) it notes the failure and proceeds on local
-  tags rather than aborting. `--tags` takes no untrusted input and `project.path`
-  is validated + single-quoted per Step 0.5.
-
-## 0.3.0 (2026-06-18) — release-focused entries, written in your voice
-
-**Changed (behavior)**
-- `/devlog` now generates one entry **per version release** (a semver git tag) instead of
-  one entry per day. An entry summarizes the commits in a release's tag range
-  (`<prevTag>..<thisTag>`), scoped by `pathFilter` when present. The run is **idempotent**:
-  a release's entry is written once and never overwritten, and re-running produces nothing
-  until a new tag is cut. The per-day "Update — HH:MM" append mode is removed.
-- Entries are keyed by version: `<project-key>/<version>.md` (e.g. `v0.2.0.md`), with a
-  `version` field added to the frontmatter and to each `manifest.json` entry. Entry sections
-  are now **What Shipped / What's Next / Commits**. The entry `date` is the tag's commit date.
-
-**Added**
-- **Voice-driven publishing.** Entries are written in the user's voice using a voice profile
-  resolved in this order: `config.voicePath` → `~/.claude/skills/ghostwriter/voice` (if
-  installed) → a bundled fallback at `~/.claude/skills/devlog/voice/`. devlog reads
-  `voice-profile.md` and `voice-notes.md` (overrides) — and never `algorithm.md`, since
-  LinkedIn reach tuning does not apply to a dev log.
-- `voicePath` (top-level, optional) and `projects[].tagPrefix` (optional, default `v`) config
-  fields, with security validation in both `bin/devlog.js` and SKILL.md. `tagPrefix` lets each
-  project in a monorepo detect its own releases (e.g. `devlog-v`, `ghostwriter-v`).
-- `init` prompts for the voice directory and release tag prefix, and installs the bundled
-  voice template. `config` shows the voice path and each project's tag pattern.
-- The React example carries the optional `version` field through frontmatter parsing and
-  manifest validation.
-
-**Migration note:** existing per-day `YYYY-MM-DD.md` entries are left untouched; new entries
-are per-release. To detect a monorepo project's releases, set its `tagPrefix`.
-
-## 0.2.0 (2026-06-08) — monorepo subdirectory filtering
-
-**Added**
-- `projects[].pathFilter` config field: scope a project's commits to a repo-relative
-  subdirectory (e.g. `skills/devlog`). Lets several logical projects share one monorepo
-  `path`/`remote` while each collects only its own subtree's commits. `git log` gains a
-  `-- <pathFilter>` pathspec; commit links still resolve to `<remote>/commit/<hash>`.
-- SKILL.md documents the field, its security validation (no leading `-`/`/`, no `..`,
-  single-quoted), and the multi-skill monorepo workflow.
-- `bin/devlog.js` validates `pathFilter` and shows it as `scope:` in `devlog config`.
-
-## 0.1.9 (2026-06-05) — accessibility fix
-
-**Accessibility**
-- The drop-in React component (`examples/react/DevLogPage.jsx`) now exposes the expand/collapse entries as a proper disclosure control. Previously they were mouse-only — a bare `onClick` on `<article>` with no `role`, `tabIndex`, `aria-expanded`, or keyboard handler, so keyboard and screen-reader users could not operate the feed.
-  - The header carries `role="button"`, `tabIndex={0}`, `aria-expanded`, and `aria-controls` for screen-reader toggle semantics.
-  - `Enter`/`Space` toggle the focused entry (`preventDefault` on Space stops page scroll).
-  - `:focus-visible` outline makes keyboard focus visible.
-  - The toggle moved from the whole card to the header, so links inside an expanded entry are no longer nested in an interactive ancestor and text selection in the body works normally.
-- Visuals are unchanged: padding/hover/cursor moved from `.devlog-entry` to `.devlog-header`, with the redundant content padding zeroed so spacing matches.
-
-## 0.1.8 (2026-05-01) — final hardening pass
-
-Closes the four Low-Hardening findings from the second adversarial verification:
-
-- **L-1:** `validateConfig` now bounds `projects[].label` length (≤200 chars) and rejects control characters. Label apostrophes/quotes/etc are intentionally allowed since label is React text content only — never shell-interpolated. The validator includes an explicit invariant comment to keep this guarantee load-bearing.
-- **L-2:** `atomicWriteJSON` uses `wx` (exclusive create) flag, preventing symlink-attack scenarios on shared filesystems where another local user could pre-create the tmp file.
-- **L-3:** `atomicWriteJSON` tmp filename now also includes `Date.now()` for additional uniqueness across rapid sequential calls.
-- **L-4:** SKILL.md Step 5 explicitly instructs the LLM to treat fetched dev-log content as data, not instructions — defense against indirect prompt injection from hostile dev-log markdown.
-
-Verification: a second 6-perspective adversarial agent against HEAD reports zero Critical/High/Medium-Active vulnerabilities remain.
-
-## 0.1.7 (2026-05-01) — security hardening + UX improvements
-
-**Security**
-- Tightened `SHELL_METACHARS` to additionally reject whitespace, single-quote, square brackets, equals, and percent
-- Project paths now cannot start with `-` (would be parsed as flag)
-- Added strict validation of the `branch` field (no leading dash, no `..` as a path component)
-- Atomic `config.json` writes (write-to-tmp + rename)
-- CLI no longer forwards arbitrary `VITE_*` env vars to the spawned vite — only `VITE_DEVLOG_*` plus `PATH`/`HOME`/etc.
-- Added `Content-Security-Policy` meta tag to the preview app
-- Explicit `urlTransform` in `react-markdown` rejects `data:`, `blob:`, `javascript:`, `vbscript:`, `file:`, and any non-http(s)/mailto scheme
-- `react-markdown` invoked with `skipHtml` for explicit defense-in-depth
-- `SKILL.md` instructs the LLM to single-quote every interpolated config value (defense-in-depth on top of validation)
-- Production preview builds without env vars show a clear "Setup required" screen instead of attempting demo fetches that would 404
-- `config.json` written with mode `0600`, `~/.claude/skills/devlog/` created with mode `0700`
-- Pinned all dependencies to exact versions (no `^` ranges) to eliminate resolution drift
-
-**UX**
-- `init` now loops to register multiple projects in a single setup
-- New `add-project` subcommand: `npx @natjswenson/devlog add-project` — register a project without editing config.json by hand
-- New `config` subcommand: `npx @natjswenson/devlog config` — view current config with validation status
-- Init detects when `gh` is authenticated as a different user than `githubUser` and warns
-- Better next-step messaging after init (color, concrete commands)
-- All error messages now include actionable hints (`log.hint`)
-
-**Docs**
-- New `SECURITY.md` — threat model, audit history, ruled-out attack scenarios, vulnerability reporting flow
-- New `CHANGELOG.md` (this file)
-- README updated with new subcommands and security guarantees section
-
-## 0.1.6 (2026-05-01) — initial security audit fixes
-
-Addressed 1 Critical + 3 High findings from the first round of the 6-agent siege:
-- SKILL.md now requires runtime allowlist validation of every config value before shell interpolation
-- CLI switched from `execSync` with template strings to `spawnSync` with argv arrays for any user-input-bearing call
-- `gh repo create` regex hardened against leading-dash flag injection
-- `gitAuthor` validator now rejects shell metachars
-- Schema validation added for `manifest.json`, `VITE_DEVLOG_PROJECTS`, frontmatter (allowlist + `Object.create(null)`)
-- `optimizeDeps` includes for vite to fix react-markdown / react-dom CJS interop in npx layouts
-- Preview vite server bound to localhost only, CORS disabled
-
-## 0.1.5 (2026-05-01)
-
-- Corrected live-site URL in README (`natejswenson.com` not `.io`)
-
-## 0.1.4 (2026-05-01)
-
-- README troubleshooting section, npm + license badges
-- SKILL.md uses `<config.branch || 'main'>` consistently in push/URL output
-
-## 0.1.3 (2026-05-01)
-
-- Expanded `optimizeDeps.include` to cover react/react-dom for npx-installed layouts
-
-## 0.1.2 (2026-05-01)
-
-- First `optimizeDeps` fix for `style-to-js` CJS/ESM interop (react-markdown rendering)
-
-## 0.1.1 (2026-05-01)
-
-- `projects[].label` and `branch` config fields (optional, with safe defaults)
-
-## 0.1.0 (2026-05-01)
-
-- Initial release
-- CLI: `init`, `preview`
-- React drop-in components: `DevLogPage`, `useDevLogEntries`
-- Standalone deployable Vite preview app with snarky demo mode

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2026 Nate Swenson
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.

package/README.md

@@ -1,240 +0,0 @@
-# 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 dev log entry, 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 narrative entry — in your voice — 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 finds tags that don't yet have an entry, summarizes each release's changes into a narrative markdown entry written in your voice, and pushes it to your dev-log GitHub repo. It's idempotent — re-running does nothing until you cut a new release.
-3. **Your site fetches it.** Static `manifest.json` + per-release markdown files served from `raw.githubusercontent.com` — no backend needed.
-
-**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 an additional project without editing config.json by hand |
-| `npx @natjswenson/devlog config` | Show your current config with validation status |
-| `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: "Concise release summary"
-date: 2026-06-08
-project: myproject
-version: v0.2.0
-summary: "1-2 sentence summary"
----
-
-## What Shipped
-Narrative paragraphs, written in your voice.
-
-## What's Next
-Forward-looking note.
-
-## Commits
-- commit message ([abc1234](https://github.com/.../commit/abc1234567...))
-```
-
-That's the entire contract.
-
-## 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>*'`. |
-
-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` (Step 6 — generate the entry).
-- **Tweak your voice:** edit the `voice-profile.md` / `voice-notes.md` in your `voicePath` (or `~/.claude/skills/devlog/voice/`).
-- **Tweak the UI:** override the `--devlog-*` CSS variables in `examples/react/DevLogPage.css` to match your theme.
-- **Add more projects:** `npx @natjswenson/devlog add-project` (no manual JSON editing required).
-
-## 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