@natjswenson/devlog 0.1.9 → 0.4.0

package/bin/devlog.js

@@ -19,13 +19,19 @@ import kleur from 'kleur';
 //
 // For strict-token fields (project keys, repo names, branch names), separate
 // allowlist regexes apply additional structural constraints.
-const SHELL_QUOTE_BREAK = /[;&|`$()<>{}[\]*?!#~"'\\\n\r]/;
-const RE_GH_USER = /^[a-z0-9][a-z0-9-]*$/i;
-const RE_REPO_NAME = /^[a-z0-9][a-z0-9._-]*$/i;
-const RE_OWNER_REPO = /^[a-z0-9][a-z0-9._-]*\/[a-z0-9][a-z0-9._-]*$/i;
-const RE_PROJECT_KEY = /^[a-z0-9][a-z0-9._-]*$/i;
-const RE_BRANCH = /^[a-z0-9][a-z0-9._/-]*$/i;
-const FORBIDDEN_BRANCH_PARTS = /(^|\/)\.\.($|\/)/; // reject `..` as a path component
+export const SHELL_QUOTE_BREAK = /[;&|`$()<>{}[\]*?!#~"'\\\n\r]/;
+export const RE_GH_USER = /^[a-z0-9][a-z0-9-]*$/i;
+export const RE_REPO_NAME = /^[a-z0-9][a-z0-9._-]*$/i;
+export const RE_OWNER_REPO = /^[a-z0-9][a-z0-9._-]*\/[a-z0-9][a-z0-9._-]*$/i;
+export const RE_PROJECT_KEY = /^[a-z0-9][a-z0-9._-]*$/i;
+export const RE_BRANCH = /^[a-z0-9][a-z0-9._/-]*$/i;
+// Repo-relative subdir used to scope `git log` to one skill in a monorepo.
+// Same shape as a branch: no leading dash/slash, no shell metacharacters.
+export const RE_PATH_FILTER = /^[a-z0-9][a-z0-9._/-]*$/i;
+// Git tag prefix that marks a project's releases (e.g. `v` or `devlog-v`).
+// Interpolated into `git tag --list '<tagPrefix>*'`; same safety as a path filter.
+export const RE_TAG_PREFIX = /^[a-z0-9][a-z0-9._/-]*$/i;
+export const FORBIDDEN_BRANCH_PARTS = /(^|\/)\.\.($|\/)/; // reject `..` as a path component
 
 const require = createRequire(import.meta.url);
 const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
@@ -34,6 +40,9 @@ const CONFIG_DIR = join(homedir(), '.claude', 'skills', 'devlog');
 const CONFIG_PATH = join(CONFIG_DIR, 'config.json');
 const SKILL_DEST = join(CONFIG_DIR, 'SKILL.md');
 const PREVIEW_DIR = join(PACKAGE_ROOT, 'preview');
+const VOICE_SRC_DIR = join(PACKAGE_ROOT, 'voice');
+const VOICE_DEST_DIR = join(CONFIG_DIR, 'voice');
+const GHOSTWRITER_VOICE_DIR = join(homedir(), '.claude', 'skills', 'ghostwriter', 'voice');
 
 const log = {
   info: (msg) => console.log(msg),
@@ -69,7 +78,7 @@ function tryExecArgs(cmd, args) {
   }
 }
 
-function expandHome(p) {
+export function expandHome(p) {
   if (!p) return p;
   if (p === '~') return homedir();
   if (p.startsWith('~/')) return join(homedir(), p.slice(2));
@@ -93,7 +102,7 @@ function atomicWriteJSON(path, data) {
 }
 
 // Validate a config object before writing. Throws with a user-facing message on failure.
-function validateConfig(config) {
+export function validateConfig(config) {
   if (!config || typeof config !== 'object') throw new Error('Config must be an object');
   const required = ['targetRepo', 'gitAuthor', 'githubUser', 'projects'];
   for (const k of required) {
@@ -113,6 +122,18 @@ function validateConfig(config) {
       throw new Error(`branch must be a valid git branch name (no leading dash, no '..'): got ${JSON.stringify(config.branch)}`);
     }
   }
+  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
+    // hard requirement is no shell metacharacters and no leading dash. A leading `~`
+    // is allowed (the skill expands it); we test the expanded form so an absolute
+    // path has no `~` left to trip the shell-quote-break check. Existence is checked
+    // at prompt time (and at runtime, with a fallback chain), not here.
+    const expanded = typeof config.voicePath === 'string' ? expandHome(config.voicePath) : config.voicePath;
+    if (typeof config.voicePath !== 'string' || SHELL_QUOTE_BREAK.test(expanded) || expanded.trim().startsWith('-')) {
+      throw new Error(`voicePath must be a path with no shell metacharacters and no leading dash: got ${JSON.stringify(config.voicePath)}`);
+    }
+  }
   if (!Array.isArray(config.projects)) {
     throw new Error('projects must be an array');
   }
@@ -130,6 +151,22 @@ function validateConfig(config) {
     if (!RE_OWNER_REPO.test(p.remote)) {
       throw new Error(`project.remote must match <owner>/<repo>: ${JSON.stringify(p.remote)}`);
     }
+    if ('pathFilter' in p) {
+      // Optional: scope this project's commits to a repo subdirectory (e.g. a
+      // single skill in a monorepo). Interpolated into `git log -- <pathFilter>`,
+      // so enforce the same no-metacharacter / no-`..` safety as branch names.
+      if (typeof p.pathFilter !== 'string' || !RE_PATH_FILTER.test(p.pathFilter) || FORBIDDEN_BRANCH_PARTS.test(p.pathFilter)) {
+        throw new Error(`project.pathFilter must be a repo-relative subdir (no leading dash/slash, no '..', no shell metacharacters): ${JSON.stringify(p.pathFilter)}`);
+      }
+    }
+    if ('tagPrefix' in p) {
+      // Optional: the prefix of the git tags that mark this project's releases
+      // (e.g. `devlog-v`). Interpolated into `git tag --list '<tagPrefix>*'`, so
+      // enforce the same no-metacharacter / no-`..` safety as path filters.
+      if (typeof p.tagPrefix !== 'string' || !RE_TAG_PREFIX.test(p.tagPrefix) || FORBIDDEN_BRANCH_PARTS.test(p.tagPrefix)) {
+        throw new Error(`project.tagPrefix must be a tag prefix (no leading dash/slash, no '..', no shell metacharacters): ${JSON.stringify(p.tagPrefix)}`);
+      }
+    }
     if ('label' in p) {
       // Label is rendered as React text content only — never shell-interpolated,
       // never used in URLs, never used as a filesystem path. React escapes all
@@ -197,7 +234,7 @@ async function confirmOverwrite(label, path) {
 }
 
 // ─── prompt validators (reused across init and add-project) ──────────────────
-const VALIDATORS = {
+export const VALIDATORS = {
   gitAuthor: (v) => {
     if (v.trim().length === 0) return 'Required';
     if (SHELL_QUOTE_BREAK.test(v)) return 'Invalid characters (no quotes, backticks, dollar signs, semicolons, parens, or shell metacharacters)';
@@ -217,6 +254,20 @@ const VALIDATORS = {
     return true;
   },
   ownerRepo: (v) => RE_OWNER_REPO.test(v.trim()) || 'Expected <owner>/<repo>, no leading dash, alphanumeric + ._- only',
+  voicePath: (v) => {
+    // Optional. Blank means "use ghostwriter's voice dir if present, else the bundled default".
+    if (!v || v.trim() === '') return true;
+    if (SHELL_QUOTE_BREAK.test(v)) return 'Invalid characters (no quotes, backticks, dollar signs, semicolons, parens, or shell metacharacters)';
+    if (v.trim().startsWith('-')) return 'Path cannot start with a dash';
+    return existsSync(expandHome(v.trim())) || 'Path does not exist';
+  },
+  tagPrefix: (v) => {
+    // Optional. Blank/`v` is the default. Used in `git tag --list '<prefix>*'`.
+    const t = (v || '').trim();
+    if (t === '') return true;
+    if (!RE_TAG_PREFIX.test(t) || FORBIDDEN_BRANCH_PARTS.test(t)) return 'Invalid prefix (no leading dash/slash, no "..", no shell metacharacters)';
+    return true;
+  },
   label: (v) => {
     // Label is React text content only — apostrophes and most punctuation are fine.
     // Reject only control chars and overlong values.
@@ -262,6 +313,13 @@ async function promptForProject(defaults = {}) {
       initial: (_p, values) => detectProjectRemote(expandHome(values.path)) || initialRemote,
       validate: VALIDATORS.ownerRepo,
     },
+    {
+      type: 'text',
+      name: 'tagPrefix',
+      message: 'Release tag prefix (optional, e.g. "v" or "myproject-v"):',
+      initial: defaults.tagPrefix || 'v',
+      validate: VALIDATORS.tagPrefix,
+    },
   ], { onCancel: () => process.exit(1) });
 
   const out = {
@@ -270,6 +328,9 @@ async function promptForProject(defaults = {}) {
     remote: answers.remote.trim(),
   };
   if (answers.label && answers.label.trim()) out.label = answers.label.trim();
+  // Only persist tagPrefix when it differs from the default `v` (keeps configs clean).
+  const tagPrefix = (answers.tagPrefix || '').trim();
+  if (tagPrefix && tagPrefix !== 'v') out.tagPrefix = tagPrefix;
   return out;
 }
 
@@ -282,12 +343,16 @@ async function cmdInit() {
     gitAuthor: detectGitName() || '',
     githubUser: detectGhUser() || '',
     targetRepoName: 'daily-dev-log',
+    // Pre-fill the voice path with ghostwriter's voice dir if it's installed — that's
+    // the most likely place a user already keeps their voice profile.
+    voicePath: existsSync(GHOSTWRITER_VOICE_DIR) ? GHOSTWRITER_VOICE_DIR : '',
   };
 
   const answers = await prompts([
-    { type: 'text', name: 'gitAuthor', message: 'Your name (used to filter `git log --author`):', initial: defaults.gitAuthor, validate: VALIDATORS.gitAuthor },
+    { type: 'text', name: 'gitAuthor', message: 'Your name (retained for backward compatibility; not currently rendered on entries):', initial: defaults.gitAuthor, validate: VALIDATORS.gitAuthor },
     { type: 'text', name: 'githubUser', message: 'Your GitHub username:', initial: defaults.githubUser, validate: VALIDATORS.githubUser },
     { type: 'text', name: 'targetRepoName', message: 'Name of the repo where dev logs will be published:', initial: defaults.targetRepoName, validate: VALIDATORS.targetRepoName },
+    { type: 'text', name: 'voicePath', message: 'Voice profile directory (optional — blank uses ghostwriter\'s if present, else the bundled default):', initial: defaults.voicePath, validate: VALIDATORS.voicePath },
   ], { onCancel: () => process.exit(1) });
 
   // Optionally register projects in a loop. First time defaults to "yes".
@@ -313,11 +378,16 @@ async function cmdInit() {
   }
 
   const targetRepo = `${answers.githubUser}/${answers.targetRepoName}`;
+  // Store the expanded absolute path (consistent with project.path) so the persisted
+  // config never carries a `~` that would later trip the shell-quote-break check.
+  const rawVoicePath = (answers.voicePath || '').trim();
+  const voicePath = rawVoicePath ? expandHome(rawVoicePath) : '';
   const config = validateConfig({
     targetRepo,
     branch: 'main',
     gitAuthor: answers.gitAuthor,
     githubUser: answers.githubUser,
+    ...(voicePath ? { voicePath } : {}),
     projects,
   });
 
@@ -334,6 +404,7 @@ async function cmdInit() {
   log.info(`  Git author:     ${config.gitAuthor}`);
   log.info(`  GitHub user:    ${config.githubUser}`);
   log.info(`  Branch:         ${config.branch}`);
+  log.info(`  Voice profile:  ${config.voicePath || '(ghostwriter if present, else bundled default)'}`);
   log.info(`  Projects:       ${config.projects.length === 0 ? '(none — add later with `devlog add-project`)' : config.projects.map((p) => p.key).join(', ')}`);
   log.info(`  Skill location: ${CONFIG_DIR}`);
 
@@ -347,7 +418,7 @@ async function cmdInit() {
     log.warn(`Repo github.com/${targetRepo} already exists. Will use it as-is.`);
   } else {
     log.step(`Creating github.com/${targetRepo}...`);
-    const r = spawnSync('gh', ['repo', 'create', targetRepo, '--public', '--description', 'Daily dev log', '--add-readme'], { stdio: 'inherit' });
+    const r = spawnSync('gh', ['repo', 'create', targetRepo, '--public', '--description', 'Release dev log', '--add-readme'], { stdio: 'inherit' });
     if (r.status !== 0) {
       log.err('Failed to create repo. Check `gh` permissions.');
       process.exit(1);
@@ -374,16 +445,33 @@ async function cmdInit() {
     log.warn('Skipped config.json');
   }
 
+  // Install the bundled voice template as the fallback voice profile. The skill
+  // resolves voice in this order: config.voicePath → ghostwriter's voice dir →
+  // this bundled copy. Installing it guarantees the last fallback always exists.
+  if (!existsSync(VOICE_DEST_DIR)) {
+    mkdirSync(VOICE_DEST_DIR, { recursive: true, mode: 0o700 });
+  }
+  for (const [src, dest] of [['voice-profile.example.md', 'voice-profile.md'], ['voice-notes.example.md', 'voice-notes.md']]) {
+    const s = join(VOICE_SRC_DIR, src);
+    const d = join(VOICE_DEST_DIR, dest);
+    if (existsSync(s) && (await confirmOverwrite(`voice/${dest}`, d))) {
+      copyFileSync(s, d);
+      log.ok(`Installed voice/${dest} → ${d}`);
+    }
+  }
+
   log.info('\n' + kleur.bold().green('Setup complete.') + '\n');
   log.info('Next steps:');
   if (config.projects.length === 0) {
     log.info(`  1. Add a project: ${kleur.cyan('npx @natjswenson/devlog add-project')}`);
-    log.info('  2. Make some commits in the project');
+    log.info('  2. Tag a release in the project (e.g. `git tag v0.1.0`)');
+    log.info(`  3. In Claude Code, run: ${kleur.cyan('/devlog')}`);
+    log.info(`  4. Preview locally: ${kleur.cyan('npx @natjswenson/devlog preview')}`);
   } else {
-    log.info('  1. Make some commits in a registered project');
+    log.info('  1. Tag a release in a registered project (e.g. `git tag v0.1.0`)');
+    log.info(`  2. In Claude Code, run: ${kleur.cyan('/devlog')}`);
+    log.info(`  3. Preview locally: ${kleur.cyan('npx @natjswenson/devlog preview')}`);
   }
-  log.info(`  2. In Claude Code, run: ${kleur.cyan('/devlog')}`);
-  log.info(`  3. Preview locally: ${kleur.cyan('npx @natjswenson/devlog preview')}`);
   log.info('');
 }
 
@@ -458,11 +546,14 @@ async function cmdConfig() {
   log.info(`Branch:        ${config.branch || 'main'}`);
   log.info(`Git author:    ${config.gitAuthor || '?'}`);
   log.info(`GitHub user:   ${config.githubUser || '?'}`);
+  log.info(`Voice path:    ${config.voicePath || kleur.dim('(ghostwriter if present, else bundled default)')}`);
   log.info(`Projects (${(config.projects || []).length}):`);
   for (const p of config.projects || []) {
     log.info(`  ${kleur.cyan(p.key)}${p.label ? `  (${p.label})` : ''}`);
     log.info(kleur.dim(`    path:   ${p.path}`));
     log.info(kleur.dim(`    remote: github.com/${p.remote}`));
+    if (p.pathFilter) log.info(kleur.dim(`    scope:  ${p.pathFilter}/`));
+    log.info(kleur.dim(`    tags:   ${p.tagPrefix || 'v'}*`));
   }
   log.info('');
 }
@@ -526,7 +617,7 @@ async function cmdPreview() {
 // ─── help ────────────────────────────────────────────────────────────────────
 function printHelp() {
   console.log(`
-${kleur.bold('@natjswenson/devlog')} v${readPackageVersion()} — daily dev log generator
+${kleur.bold('@natjswenson/devlog')} v${readPackageVersion()} — release dev log generator
 
 Usage:
   ${kleur.cyan('npx @natjswenson/devlog init')}           One-time setup: create your dev-log repo, install the skill, write config
@@ -542,31 +633,36 @@ Issues:  https://github.com/natejswenson/devlog/issues
 }
 
 // ─── dispatch ────────────────────────────────────────────────────────────────
-const arg = process.argv[2];
-switch (arg) {
-  case 'init':
-    cmdInit();
-    break;
-  case 'add-project':
-    cmdAddProject();
-    break;
-  case 'config':
-    cmdConfig();
-    break;
-  case 'preview':
-    cmdPreview();
-    break;
-  case '-v':
-  case '--version':
-    console.log(readPackageVersion());
-    break;
-  case undefined:
-  case '-h':
-  case '--help':
-    printHelp();
-    break;
-  default:
-    log.err(`Unknown command: ${arg}`);
-    printHelp();
-    process.exit(1);
+// Only run the CLI dispatch when this file is executed directly, not when it is
+// imported (e.g. by the test suite). Importing the module must have no side effects.
+const isMain = process.argv[1] === fileURLToPath(import.meta.url);
+if (isMain) {
+  const arg = process.argv[2];
+  switch (arg) {
+    case 'init':
+      cmdInit();
+      break;
+    case 'add-project':
+      cmdAddProject();
+      break;
+    case 'config':
+      cmdConfig();
+      break;
+    case 'preview':
+      cmdPreview();
+      break;
+    case '-v':
+    case '--version':
+      console.log(readPackageVersion());
+      break;
+    case undefined:
+    case '-h':
+    case '--help':
+      printHelp();
+      break;
+    default:
+      log.err(`Unknown command: ${arg}`);
+      printHelp();
+      process.exit(1);
+  }
 }

package/config.example.json

@@ -3,17 +3,22 @@
   "branch": "main",
   "gitAuthor": "Your Name",
   "githubUser": "yourusername",
+  "voicePath": "~/.claude/skills/ghostwriter/voice",
   "projects": [
     {
       "key": "midnight-side-quest",
       "label": "Midnight Side Quest",
       "path": "/Users/yourusername/code/midnight-side-quest",
-      "remote": "yourusername/midnight-side-quest"
+      "remote": "yourusername/midnight-side-quest",
+      "tagPrefix": "v"
     },
     {
-      "key": "todays-existential-crisis",
-      "path": "/Users/yourusername/code/todays-existential-crisis",
-      "remote": "yourusername/todays-existential-crisis"
+      "key": "devlog",
+      "label": "Devlog",
+      "path": "/Users/yourusername/code/your-monorepo",
+      "remote": "yourusername/your-monorepo",
+      "pathFilter": "skills/devlog",
+      "tagPrefix": "devlog-v"
     }
   ]
 }

package/examples/react/README.md

@@ -1,6 +1,6 @@
 # React example — devlog
 
-Drop-in React components for rendering your daily dev log on any React-based site.
+Drop-in React components for rendering your release dev log on any React-based site.
 
 ## What's here
 

package/examples/react/useDevLogEntries.js

@@ -3,11 +3,12 @@ import { DEVLOG_CONFIG as DEFAULT_CONFIG } from './devlog-config.js';
 
 // Allowlist of frontmatter keys we recognize. Anything else is ignored —
 // prevents prototype-pollution via crafted keys like `__proto__`.
-const FRONTMATTER_KEYS = new Set(['title', 'date', 'project', 'summary']);
+// `version` is the release tag this entry corresponds to (e.g. "v0.2.0").
+const FRONTMATTER_KEYS = new Set(['title', 'date', 'project', 'summary', 'version']);
 
 /**
  * Parse YAML-ish frontmatter from a markdown string.
- * Returns { metadata: { title, date, project, summary }, body: string }
+ * Returns { metadata: { title, date, project, summary, version }, body: string }
  */
 function parseFrontmatter(raw) {
   const match = raw.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
@@ -24,19 +25,22 @@ function parseFrontmatter(raw) {
 }
 
 // Schema validation for fetched manifest. Reject anything that isn't shaped
-// like { entries: [{ date, file, title, summary }, ...] } so a hostile commit
-// to the dev-log repo can't crash the page.
+// like { entries: [{ date, file, title, summary, version? }, ...] } so a hostile
+// commit to the dev-log repo can't crash the page. `version` is optional and
+// only kept when it's a clean tag-ish string.
 function validateManifest(data) {
   if (!data || typeof data !== 'object') return null;
   if (!Array.isArray(data.entries)) return null;
   const entries = [];
   for (const e of data.entries) {
     if (!e || typeof e !== 'object') continue;
-    const { date, file, title, summary } = e;
+    const { date, file, title, summary, version } = e;
     if (typeof date !== 'string' || !/^\d{4}-\d{2}-\d{2}$/.test(date)) continue;
     if (typeof file !== 'string' || !/^[a-zA-Z0-9._-]+\.md$/.test(file)) continue;
     if (typeof title !== 'string' || typeof summary !== 'string') continue;
-    entries.push({ date, file, title, summary });
+    const entry = { date, file, title, summary };
+    if (typeof version === 'string' && /^[a-zA-Z0-9._-]+$/.test(version)) entry.version = version;
+    entries.push(entry);
   }
   return { entries };
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@natjswenson/devlog",
-  "version": "0.1.9",
-  "description": "Daily dev log generator — Claude Code skill + preview app for publishing git-based dev logs to your site",
+  "version": "0.4.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",
   "homepage": "https://github.com/natejswenson/devlog",
@@ -18,6 +18,7 @@
     "claude-skill",
     "build-in-public",
     "git",
+    "release-notes",
     "blog"
   ],
   "type": "module",
@@ -28,6 +29,7 @@
     "bin/",
     "preview/",
     "examples/",
+    "voice/",
     "SKILL.md",
     "SECURITY.md",
     "CHANGELOG.md",
@@ -39,6 +41,7 @@
     "node": ">=18"
   },
   "scripts": {
+    "test": "node --test \"tests/**/*.test.mjs\"",
     "audit": "npm audit --audit-level=moderate"
   },
   "dependencies": {
@@ -49,6 +52,6 @@
     "react-dom": "18.3.1",
     "react-markdown": "9.1.0",
     "remark-gfm": "4.0.1",
-    "vite": "8.0.10"
+    "vite": "8.0.16"
   }
 }

package/preview/demo.js

@@ -25,31 +25,33 @@ function offsetDate(daysAgo) {
 
 const ENTRIES = [
   {
+    version: 'v0.4.0',
     date: offsetDate(0),
     title: 'You are looking at fake data',
-    summary: "Hi. These aren't your entries. Your entries are 30 seconds away.",
-    body: `## What I Built
+    summary: "Hi. These aren't your releases. Your releases are 30 seconds away.",
+    body: `## What Shipped
 
 Nothing. I'm a placeholder. A handsome one, but still a placeholder.
 
 You're seeing this screen because the preview app couldn't find env vars
 pointing at your dev-log repo. Once that's fixed, this entire feed gets
 replaced with real entries, generated by the \`/devlog\` skill from your
-actual git commits.
+actual version releases — written in your voice.
 
 ## What's Next
 
 You. Setting things up. Probably while half-watching a YouTube tutorial
 about something unrelated. We believe in you.
 
-## Public Commits
+## Commits
 
-- [demo] make placeholder more passive-aggressive ([abcd123](#))
-- [demo] add a tiny bit of charm ([def4567](#))
+- make placeholder more passive-aggressive ([abcd123](#))
+- add a tiny bit of charm ([def4567](#))
 `,
   },
   {
-    date: offsetDate(1),
+    version: 'v0.3.0',
+    date: offsetDate(2),
     title: 'How to make this screen go away',
     summary: 'Two paths: the lazy one (recommended) and the manual one (also fine).',
     body: `## The lazy path
@@ -58,7 +60,7 @@ about something unrelated. We believe in you.
 npx @natjswenson/devlog init
 \`\`\`
 
-Answer four prompts. The CLI creates your dev-log repo on GitHub, installs
+Answer a few prompts. The CLI creates your dev-log repo on GitHub, installs
 the Claude Code skill, and writes your config. Run \`npx @natjswenson/devlog preview\`
 again. This entry vanishes. You feel powerful.
 
@@ -75,18 +77,20 @@ VITE_DEVLOG_PROJECTS=[{"key":"myproject","label":"My Project"}]
 
 ## What's Next
 
-The real preview, with your real entries. Try it.
+The real preview, with your real releases. Try it.
 `,
   },
   {
-    date: offsetDate(3),
+    version: 'v0.2.0',
+    date: offsetDate(5),
     title: "Why you'd actually want this",
-    summary: 'Build in public, but with style. And without remembering to write blog posts.',
-    body: `## What I Built
+    summary: 'Build in public, by release — with style, and without remembering to write blog posts.',
+    body: `## What Shipped
 
-The whole point: you commit code as usual. You run \`/devlog\` in Claude Code.
-The skill reads today's commits and writes a *narrative* entry — not "fix typo,
-fix typo again, ok actually fix it" but real prose about what you built and why.
+The whole point: you tag a release as usual. You run \`/devlog\` in Claude Code.
+The skill finds tags that don't have an entry yet and writes a *narrative*
+release note — not "fix typo, fix typo again, ok actually fix it" but real
+prose about what shipped and why, in your voice.
 
 That entry gets pushed to your dev-log repo. Your site (or this preview app,
 deployed to Vercel/Netlify/Cloudflare) renders it.
@@ -95,29 +99,30 @@ The result: you ship in public without ever opening a blog post editor.
 
 ## What's Next
 
-You'll set this up. You'll ship something on day one. You'll feel slightly
+You'll set this up. You'll tag a release on day one. You'll feel slightly
 smug about it on the train tomorrow. We're rooting for you.
 
-## Public Commits
+## Commits
 
-- [demo] write hopeful pep talk ([eeee101](#))
+- write hopeful pep talk ([eeee101](#))
 `,
   },
   {
-    date: offsetDate(7),
+    version: 'v0.1.0',
+    date: offsetDate(9),
     title: "Things this is not",
     summary: 'A short list, for the avoidance of disappointment.',
     body: `## Not features
 
 - A blog CMS. There are sixty of those. Use one if you want one.
 - A social network. Please don't.
-- An AI ghostwriter for marketing copy. The narratives come from *your*
-  commits. Garbage in, garbage out.
+- A marketing-copy generator. The narratives come from *your* releases, in
+  *your* voice. Garbage in, garbage out.
 - A way to make your past coding choices look better in retrospect. Sorry.
 
 ## Is features
 
-- A way to ship dev log entries without context-switching out of Claude Code.
+- A way to ship release notes without context-switching out of Claude Code.
 - A static, no-backend pipeline (manifest.json + markdown on GitHub).
 - Components you can drop into your own React site, or the preview app you
   can deploy as a standalone dev log.
@@ -132,9 +137,10 @@ Replace this fake entry with a real one. It's right there. Just go.
 const MANIFEST = {
   entries: ENTRIES.map((e) => ({
     date: e.date,
-    file: `${e.date}.md`,
+    file: `${e.version}.md`,
     title: e.title,
     summary: e.summary,
+    version: e.version,
   })),
 };
 
@@ -143,6 +149,7 @@ function entryMarkdown(entry) {
 title: "${entry.title.replace(/"/g, '\\"')}"
 date: ${entry.date}
 project: ${DEMO_PROJECT_KEY}
+version: ${entry.version}
 summary: "${entry.summary.replace(/"/g, '\\"')}"
 ---
 
@@ -156,9 +163,9 @@ function demoResponse(url) {
       headers: { 'content-type': 'application/json' },
     });
   }
-  const m = url.match(/(\d{4}-\d{2}-\d{2})\.md$/);
+  const m = url.match(/\/([a-zA-Z0-9._-]+)\.md$/);
   if (m) {
-    const entry = ENTRIES.find((e) => e.date === m[1]);
+    const entry = ENTRIES.find((e) => e.version === m[1]);
     if (entry) {
       return new Response(entryMarkdown(entry), {
         status: 200,

package/voice/voice-notes.example.md

@@ -0,0 +1,16 @@
+# Voice notes — recent corrections
+
+This file overrides `voice-profile.md` wherever they conflict. Put your most recent,
+explicit corrections here — the things you keep having to fix in generated entries. Keep
+it short and specific; it is read every time an entry is generated.
+
+## Defaults (safe to keep)
+- Write for the reader, not as a diary. Lead with the change and its impact, not "I".
+- No em dashes; use a comma or semicolon.
+- No tacked-on punchy filler lines and no rhetorical fragment lists for rhythm.
+- Never invent metrics, motivations, or outcomes the commits don't support.
+- A release entry is a release note, not a changelog dump — group commits into the
+  handful of changes that actually matter and explain why.
+
+## Your corrections
+(Append your own as they come up.)

package/voice/voice-profile.example.md

@@ -0,0 +1,37 @@
+# Voice profile — (your name)
+
+This is the fallback voice profile devlog uses when no other profile is found. It is
+generic. Replace it with your own — or, better, point `voicePath` in `config.json` at a
+richer profile you already maintain (e.g. ghostwriter's `voice/`). **`voice-notes.md` in
+the same directory overrides this file wherever they conflict.**
+
+devlog reads only `voice-profile.md` and `voice-notes.md`. It never reads `algorithm.md`
+(LinkedIn reach tuning) — a dev log is not a LinkedIn feed, so reach rules do not apply.
+
+## Voice & tone
+Warm, practical, honest. A builder writing release notes for people who follow along — no
+hype, no doom, no marketing gloss. Explain what shipped and why it matters in plain terms.
+
+## Sentence rhythm & structure
+- Short sentences, generous white space, one idea per line or per tiny paragraph.
+- Lead with the change, then the reason. Build to a crisp takeaway.
+- A short bullet list is fine to enumerate "what changed."
+
+## Openers (how to start a release entry)
+- A sharp statement of what shipped: "v0.3.0 makes the log release-driven."
+- A short framing of the problem the release solves.
+
+## Closers
+- A reframe or a genuine forward-looking line about what's next. Not a forced question.
+
+## Vocabulary & tics
+- Plain, modern, conversational; contractions; no corporate jargon or buzzwords.
+- Name real things: features, files, versions. Specifics over abstractions.
+
+## Emoji & hashtags
+- Emoji: sparing or none. Hashtags: none.
+
+## Never do
+- No hype words ("game-changer", "revolutionary"), no doom, no cynicism.
+- No corporate jargon, no fake humility, no fabricated metrics or motivations.
+- Don't pad. If a line isn't carrying weight, cut it.