@ibalzam/codejitsu-core 0.10.0 → 0.11.0

package/bin/codejitsu.mjs

@@ -3,6 +3,7 @@ import { parseArgs } from 'node:util';
 import { runBlog } from '../modules/cli/src/blog.mjs';
 import { runDeploySetup, runDeployTrigger } from '../modules/cli/src/deploy.mjs';
 import { runDoctor } from '../modules/cli/src/doctor.mjs';
+import { runBlogInit } from '../modules/cli/src/blog-init.mjs';
 import { runAudit } from '../modules/audit/src/run.mjs';
 
 const subcommand = process.argv[2];
@@ -11,6 +12,7 @@ const rest = process.argv.slice(3);
 const COMMANDS = {
   'blog:list': () => runBlog('blog:list'),
   'blog:drafts': () => runBlog('blog:drafts'),
+  'blog:init': () => runBlogInit(),
   'deploy:setup': () => runDeploySetup(),
   'deploy:run': () => runDeployTrigger(),
   doctor: () => runDoctor(),
@@ -56,6 +58,7 @@ function printHelp() {
   console.log(`Subcommands:`);
   console.log(`  blog:list           List every non-draft post with URL + image check`);
   console.log(`  blog:drafts         List future-dated (pending) posts only`);
+  console.log(`  blog:init           Install /blog, /blog-batch, /blog-images slash commands`);
   console.log(``);
   console.log(`  deploy:setup        Wire up daily Cloudflare deploy (prompts for hook URL)`);
   console.log(`  deploy:run          Trigger the Daily Deploy workflow once now`);

package/modules/blog-writer/BLOG_BATCH.md

@@ -0,0 +1,142 @@
+# Blog batch generation — Claude playbook
+
+> Triggered when the user runs `/blog-batch <N>` in a Codejitsu site
+> (default N = 20).
+>
+> Generates a **schedule + outline** for N future-dated posts. It does NOT
+> write the full body of every post — that's `/blog` per row. The goal here
+> is to produce a publishable roadmap that the user reviews + edits before
+> any prose is committed.
+
+## Step 0 — Read site config
+
+Same as `BLOG_WRITING.md` Step 0: load `codejitsu.config.ts.blogWriter`.
+
+Also read:
+- `src/content/blog/` — existing posts (find the latest `pubDate`)
+- `src/content.config.ts` — confirm the schema shape
+
+## Step 1 — Decide cadence
+
+Default cadence is **4 days between posts** (matches workzen / pearl /
+veteran). If existing posts have a different rhythm, infer from the last
+10 and match it.
+
+Starting date = max(`latest existing pubDate`, today) + cadence.
+
+## Step 2 — Generate N topics
+
+Brainstorm `N` topics, balancing across:
+
+- **Service × location** combinations — cycle through `services` and
+  `locations` from config so coverage is even
+- **Topic format** mix — roughly:
+  - 30% comparison / "X vs Y" posts
+  - 30% how-to / guides
+  - 20% troubleshooting
+  - 20% seasonal / news
+- **Season awareness** — apply `seasonalRules` from config. A post landing
+  in July shouldn't be about "winterize"; one in December shouldn't be
+  about "pre-summer".
+- **Unique titles** — no two posts in the batch should target the same slug
+  or near-duplicate keyword. Read all existing post titles before
+  brainstorming to avoid collisions.
+- **Approved tag balance** — distribute tags so no single tag is over 40% of
+  the batch.
+
+For each topic, derive:
+- `slug` — kebab-case, includes the city when applicable
+- `title` — natural, clickable, ≤70 chars
+- `pubDate` — assigned by cadence walk
+- `tags` — 2-3 from `approvedTags`, primary first
+- `service` + `city` — for internal-link planning
+
+## Step 3 — Produce the schedule table
+
+Write to `Blog/BLOG_SCHEDULE.md` (create the `Blog/` directory if needed).
+Append to it if it already exists — never overwrite without asking.
+
+Format:
+
+```markdown
+# <Site Name> — Blog Schedule (<start month> - <end month> <year>)
+
+Offline publishing calendar. N posts on a <cadence>-day cadence,
+<start date> through <end date>.
+
+## How to use
+
+1. Pick a row. Slug = filename → `src/content/blog/<slug>.md`.
+2. `pubDate: <date>` in frontmatter controls visibility.
+3. Run `/blog "<title>"` to flesh out the post body.
+4. Run `/blog-images` once a batch of posts is drafted.
+
+## Schedule
+
+| # | Date       | Category       | City      | Slug | Title |
+|---|------------|----------------|-----------|------|-------|
+| 1 | YYYY-MM-DD | <primary tag>  | <city>    | `<slug>` | <Title> |
+| 2 | ...        | ...            | ...       | ...      | ...     |
+```
+
+## Step 4 — Produce per-post outlines
+
+In the same file or a sibling `Blog/BLOG_OUTLINES.md`, expand each row into
+an outline:
+
+```markdown
+## <Slug>
+
+**pubDate**: YYYY-MM-DD
+**target words**: <from config.wordCount.default>
+**tags**: [primary, secondary]
+**service**: <slug>
+**city**: <slug or 'general'>
+
+**Angle / hook**: <one-sentence framing of the reader's pain>
+
+**Outline**:
+- Intro — 1-2 paragraphs hooking <hook>
+- ## <H2 #1>
+  - 2-3 paragraphs covering <points>
+- ## <H2 #2>
+  - Comparison table of <X vs Y>
+- ## <H2 #3>
+  - ...
+- Closing CTA + 5-8 FAQs
+
+**FAQ seeds**: list of 5-8 question stems
+```
+
+## Step 5 — Show + approve
+
+Present the full schedule + outline file to the user. Ask:
+
+> "Here's the schedule. Anything to adjust before we lock it in?
+>  Want me to flesh out the first N posts now, or stop here for review?"
+
+If the user says go: run `/blog` for each row (one post at a time). If they
+say stop: leave the file and exit. They can run `/blog` row by row whenever.
+
+## Hard rules
+
+- **Don't write the full prose for all N in one shot.** Too long, too
+  expensive, hard to review. Schedule + outlines first; prose per row on
+  demand.
+- **Don't push or commit.** The user reviews + commits.
+- **Respect existing posts.** If `Blog/BLOG_SCHEDULE.md` already has rows,
+  append the new batch and don't renumber.
+- **Don't invent services or locations.** Use only what's in
+  `blogWriter.services` and `blogWriter.locations`.
+- **Don't invent tags.** Only from `approvedTags`.
+- **Don't bunch up topic types.** Reject your own first draft if it has 5
+  comparison posts in a row.
+
+## Verify
+
+- [ ] N rows, all unique slugs
+- [ ] Dates respect cadence; no collisions with existing posts
+- [ ] Tags balanced across `approvedTags`
+- [ ] Service + city distribution covers most of the config lists
+- [ ] Season fits each `pubDate`'s month
+- [ ] No duplicate or near-duplicate topics

package/modules/blog-writer/BLOG_IMAGES.md

@@ -0,0 +1,127 @@
+# Blog image prompts — Claude playbook
+
+> Triggered when the user runs `/blog-images` (or `/blog-images <N>`) in a
+> Codejitsu site.
+>
+> Generates AI-image-generation prompts for blog posts that don't have their
+> images yet. Output goes to `Blog/IMAGE_PROMPTS.md` in the **5-dash separator
+> format**.
+
+## Step 0 — Read site config
+
+Open `codejitsu.config.ts` and locate `blogWriter.imageStyle`. Use:
+
+- `imageStyle.description` — the full prompt-style description of the visual
+  style (photorealistic / cartoon / illustration / etc., palette, framing)
+- `imageStyle.branding` — branding rule (e.g. "logo small in bottom-right")
+- `imageStyle.outputDir` — where the final .webp will live
+- `imageStyle.maxWords` — cap on prompt length (typical ≤60)
+- `imageStyle.realism` — `'photorealistic' | 'illustration' | 'cartoon' | 'mixed'`
+
+## Step 1 — Find the posts to prompt
+
+Default `N = 10` if not specified. Scan `src/content/blog/` and pick posts
+that:
+
+1. Have `pubDate > today` (pending / scheduled), OR
+2. Are missing an image file at `<imageStyle.outputDir>/<slug>.webp`
+
+Sort by `pubDate` ascending. Take up to N.
+
+If nothing matches → tell the user "no pending posts need images" and stop.
+
+## Step 2 — Generate prompts
+
+For each post, write a prompt ≤`maxWords` words that:
+
+- Captures the **specific topic** of the post (e.g. a comparison post should
+  show both materials, a city-anchored post should hint at the city's
+  setting)
+- Follows the style + branding from `imageStyle`
+- References any specific materials, fixtures, or settings mentioned in the
+  post title
+- **Doesn't** include text, captions, watermarks, or competitor brand names
+- **Doesn't** specify image dimensions (the image generator decides)
+
+If `imageStyle.realism === 'photorealistic'`, prompts emphasize architecture,
+lighting, real materials, magazine-quality framing.
+
+If `imageStyle.realism === 'cartoon'`, prompts emphasize character design,
+flat colors, friendly tone.
+
+## Step 3 — Output format
+
+Write to `Blog/IMAGE_PROMPTS.md` (create the `Blog/` directory if absent).
+Append if the file exists — never overwrite existing prompts.
+
+The format is **EXACTLY**:
+
+```
+**<Post Title>**
+<prompt text>
+
+-----
+
+**<Post Title>**
+<prompt text>
+
+-----
+
+**<Post Title>**
+<prompt text>
+```
+
+### Format rules — strict
+
+- Separator is **exactly 5 dashes** on their own line: `-----`. Not 3, not 7.
+  Markdown's `---` is wrong here; use `-----` literally.
+- Separator appears **between entries**, never after the last one.
+- Title goes on its own line in **bold** (with `**...**`).
+- Prompt goes directly below the title line, no blank line between them.
+- Blank line before each separator, blank line after.
+- No numbering.
+- No dimensions in the prompt text.
+- The output file goes to `imageStyle.outputDir/<slug>.webp` (note this
+  convention in a one-line header at the top of the file, not in each
+  prompt).
+
+## Step 4 — Header for the file
+
+Top of `Blog/IMAGE_PROMPTS.md`:
+
+```markdown
+# <Site Name> — Blog Image Prompts (Posts <range>)
+
+Generated against `modules/blog-writer/BLOG_IMAGES.md` from `<Site Name>`'s
+`codejitsu.config.ts.blogWriter.imageStyle`.
+
+Style: <one-line summary derived from imageStyle.description>.
+Output file convention: each image saves to `<outputDir>/<slug>.webp`.
+
+---
+```
+
+(That `---` IS markdown HR — it's the only 3-dash separator in the file,
+separating the header from the prompts. Everything between prompt entries is
+`-----`.)
+
+## Hard rules
+
+1. **Separator is `-----` (5 dashes).** Not 3.
+2. **No numbering** of entries.
+3. **No dimensions** in the prompt text.
+4. **No competitor brand names** in any prompt.
+5. **No text / captions / watermarks inside the image** unless the style
+   description explicitly allows it.
+6. **Append, don't overwrite.** If the user has a prior prompts file, add new
+   entries below; never delete or rewrite existing prompts.
+7. **One prompt per post.** Don't generate alternatives unless asked.
+
+## Verify
+
+- [ ] N prompts produced (or fewer if not enough pending posts)
+- [ ] Every separator is exactly 5 dashes
+- [ ] Last entry has NO trailing separator
+- [ ] No prompt exceeds `maxWords`
+- [ ] Each prompt references the post's specific topic + city if applicable
+- [ ] Output file path is `Blog/IMAGE_PROMPTS.md`

package/modules/blog-writer/BLOG_WRITING.md

@@ -0,0 +1,198 @@
+# Blog writing — Claude playbook
+
+> Triggered when the user runs `/blog` (or `/blog <topic>`) in a Codejitsu site
+> that has the kit's commands installed (`npx codejitsu blog:init`).
+>
+> The slash command file is a thin reference; this file is the actual playbook.
+
+## Step 0 — Read site config
+
+Open `codejitsu.config.ts` at the site root and locate the `blogWriter` block.
+Everything in there is **site-specific input** for what you're about to write:
+
+- `tone` — voice + register
+- `about` — what the company does, who it serves
+- `audience` — primary reader
+- `services` — names that map to `/services/<slug>/`
+- `locations` — names that map to `/service-areas/<slug>/`
+- `approvedTags` — exhaustive; never invent new ones
+- `wordCount` — `{ min, max, default }`
+- `faqs` — `{ min, max }` (kit default 5-8)
+- `internalLinks` — `{ min, max }` per post
+- `pricing` — `'brackets-only' | 'allowed' | 'never-mention'`
+- `seasonalRules` — free text; current date should respect this
+- `bannedPhrases` — refuse to write these
+- `authorDefault` — what to put in frontmatter `author`
+
+Also detect the blog's frontmatter shape by reading `src/content.config.ts` and
+ONE existing post in `src/content/blog/`. Use that exact shape for the new post.
+
+## Step 1 — Gather inputs (interactive)
+
+Use `AskUserQuestion` to gather these in order. If the user passed a topic as
+`$ARGUMENTS`, skip Question 1.
+
+### Question 1 — Topic & focus
+
+```
+header: "Topic"
+question: "What is this blog post about?"
+options:
+  - "Industry guide" — Educational content the audience would search for
+  - "How-to / tutorial" — Step-by-step instructions
+  - "Comparison / vs" — Compare 2+ options on multiple attributes
+  - "Troubleshooting" — Diagnose-and-fix walkthrough
+  - "Seasonal / news" — Time-sensitive (rebate change, season prep, etc.)
+```
+
+### Question 2 — Length
+
+```
+header: "Length"
+question: "How long?"
+options:
+  - "Short (400-600 words)" — Announcement, quick explainer
+  - "Medium (800-1200 words)" — Single-question explainer
+  - "Long (1500-2500 words)" — Default for SEO posts
+  - "XL (2500+ words)" — Definitive guide
+```
+
+Default = the `wordCount.default` from config.
+
+### Question 3 — Primary service + city focus
+
+```
+header: "Service + city"
+question: "Which service and city is this anchored to?"
+```
+
+Two follow-ups (separate questions):
+- Service options: derive from `blogWriter.services`
+- City options: derive from `blogWriter.locations` (plus an "any/general" option)
+
+These drive the internal-link choices later.
+
+### Question 4 — Publish date
+
+```
+header: "Publish date"
+question: "When should this go live?"
+options:
+  - "Today" — immediate publish
+  - "Next available slot" — read recent posts in src/content/blog/, find the
+    next open date in the existing cadence (e.g. 4-day gap), use that
+  - "Custom date" — user types YYYY-MM-DD
+```
+
+## Step 2 — Outline + approval
+
+Before writing prose, produce an outline:
+
+```
+TITLE: <working title>
+SLUG:  <kebab-case>
+DATE:  <YYYY-MM-DD>
+TAGS:  <2-3 from approvedTags, primary first>
+WORDS: <target word count>
+
+OUTLINE:
+  Intro (1-2 paragraphs)
+  ## <H2 #1>
+    2-3 paragraphs of [angle]
+  ## <H2 #2>
+    Includes a comparison table / bullet list of [items]
+  ## <H2 #3>
+    ...
+  Closing CTA (modal + phone)
+  FAQs (5-8): planned questions
+```
+
+Show the outline and **ask for approval before writing prose**. Adjust on
+feedback. Don't proceed without approval.
+
+## Step 3 — Write the post
+
+Write the full post to `src/content/blog/<slug>.md`. Match the existing
+frontmatter shape exactly (detected in Step 0).
+
+### HARD RULES — apply to every post
+
+1. **No em dashes anywhere.** Use ` - ` (regular dash with spaces around it).
+2. **No H1 in markdown body.** Frontmatter `title` becomes the H1. Body starts
+   with intro paragraph(s), then `## H2`.
+3. **No "one-line H2 sections."** Every `## H2` must have at least
+   **2-3 paragraphs**, not just a sentence + bullet list.
+4. **At least one list per post.** Either a bullet list (3+ parallel items) or
+   a numbered list (if order matters) or a markdown table (for comparisons).
+   No exceptions — a wall-of-prose 2,000-word post is wrong. But also no
+   slide-deck (every section ending in bullets).
+5. **FAQ block** in frontmatter — `faqs.min` to `faqs.max` entries from config
+   (default 5-8). Each FAQ = real question a reader would search; answer is
+   2-4 sentences, concise and complete.
+6. **Internal links** — `internalLinks.min` to `internalLinks.max` from config
+   (default 3-6). Link to `/services/<slug>/`, `/service-areas/<slug>/`, and
+   `/services/<slug>/<city>/` patterns. Don't link the same URL twice.
+7. **Banned phrases** — if `bannedPhrases` is set in config, refuse them.
+   Common offenders: "In today's fast-paced world…", "When it comes to…",
+   "Look no further…", "In conclusion…".
+8. **Pricing** — if `pricing: 'brackets-only'`, every price reference is a
+   range with context. Never a single dollar figure. If `pricing: 'never-mention'`,
+   omit pricing entirely.
+9. **CTA** — closing paragraph includes a call-to-action. Two patterns:
+   - Modal: `[text](#contact)` or trigger-class link
+   - Phone: `[text](tel:+1...)` — use the actual number from `site.business.telephone`
+   Best is one paragraph with both.
+10. **Approved tags only.** Pick 2-3 from `blogWriter.approvedTags`. Primary
+    tag first. Don't invent new tags. If nothing fits, ask the user.
+11. **Image placeholder.** Frontmatter `image` field points to where the image
+    WILL live: `<imageStyle.outputDir>/<slug>.webp`. The file doesn't exist
+    yet; that's fine. Run `/blog-images` to generate prompts later.
+12. **Seasonal awareness.** If `seasonalRules` is set, the topic + angle must
+    fit the post's publish month. No "winterize" posts in July.
+
+### Structure
+
+- **Intro** — 1-2 paragraphs that hook on a real audience pain. Tie to a
+  specific local concern when possible (the climate, regulation, market).
+- **3-6 H2 sections** — each 2-3 paragraphs minimum. Mix prose, lists, and
+  tables. Roughly:
+  - Prose carries narrative + explanation in most sections
+  - 1-3 bullet lists where content is genuinely parallel items
+  - A markdown table for 2+ option comparisons (when it's a vs/comparison post)
+  - Numbered list only when order matters
+- **H3 sub-sections** within H2s where useful.
+- **Closing paragraph** with CTA.
+- **FAQ block** in frontmatter.
+
+### Tone
+
+Read `blogWriter.tone` and `blogWriter.audience` from config. Match
+exactly. Examples:
+
+- "professional but friendly, confident not boastful" → don't oversell, don't joke
+- "BC HVAC pro, plain-spoken, technical when needed" → mix terms-of-art with plain explanations
+- "Zen calm, helpful, occasional humour" → workzen's signature
+
+## Step 4 — Verify after writing
+
+- [ ] Word count is within target range
+- [ ] FAQ count is within `faqs.min`-`faqs.max`
+- [ ] Internal links count is within `internalLinks.min`-`internalLinks.max`
+- [ ] Tags are from `approvedTags` only
+- [ ] No em dashes (`—` or `–`) anywhere
+- [ ] No H1 in body
+- [ ] No `bannedPhrases` present
+- [ ] Pricing follows `pricing` policy
+- [ ] Frontmatter shape matches existing posts
+- [ ] At least one list (bullet, numbered, or table)
+
+## Step 5 — Report back
+
+Tell the user:
+- Path to the new file
+- Word count
+- Tag selection + why
+- Whether image needs generating (point at `/blog-images`)
+- Whether the post is published immediately or scheduled (based on date)
+
+Don't push or commit unless explicitly asked.

package/modules/blog-writer/CLAUDE.md

@@ -0,0 +1,125 @@
+# Blog writer module — instructions for Claude
+
+When the user asks to **set up blog writing** or **add the codejitsu blog
+writer** to a site, do the following.
+
+## What this module provides
+
+A robust blog-writing workflow driven by per-site config + three slash
+commands in the user's `.claude/commands/`. The slash commands themselves
+are **thin references** to playbooks that live in the package — so updates
+flow through `npm update` without re-copying anything.
+
+**Files in this module:**
+
+- `BLOG_WRITING.md` — single-post playbook (driven by `/blog`)
+- `BLOG_BATCH.md` — schedule + outline N posts (driven by `/blog-batch <N>`)
+- `BLOG_IMAGES.md` — generate image prompts for pending posts (driven by `/blog-images`)
+- `templates/.claude/commands/*.md` — thin slash command files that the
+  site keeps in its repo (copied once via `codejitsu blog:init`)
+
+**Config block in `codejitsu.config.ts`:**
+
+```ts
+blogWriter: {
+  tone: 'professional, plain-spoken, confident not boastful',
+  about: 'Veteran Heating and Cooling is a Chilliwack HVAC contractor...',
+  audience: 'BC Lower Mainland homeowners planning HVAC upgrades',
+  services: ['Heat Pump Installation', 'Furnace Installation', ...],
+  locations: ['Vancouver', 'Burnaby', 'Surrey', ...],
+  approvedTags: ['rebates-savings', 'buying-guides', 'troubleshooting', 'seasonal-care', 'home-comfort'],
+  wordCount: { min: 1200, max: 2500, default: 1800 },
+  faqs: { min: 5, max: 8 },
+  internalLinks: { min: 3, max: 6 },
+  pricing: 'brackets-only',
+  seasonalRules: 'July-Sep: heat-wave + AC topics. Oct-Nov: pre-winter prep...',
+  bannedPhrases: ["In today's fast-paced world", "When it comes to", "Look no further"],
+  authorDefault: 'Veteran HVAC',
+  imageStyle: {
+    description: 'Photorealistic real-estate / architectural photography of HVAC equipment + BC home interiors. Bright natural daylight, modern Lower Mainland aesthetic, no people unless they wear branded uniform.',
+    branding: 'Logo small in bottom-right corner. No other brand marks.',
+    outputDir: 'public/assets/blog',
+    maxWords: 60,
+    realism: 'photorealistic',
+  },
+},
+```
+
+## Wiring it into a site
+
+### 1. Configure `blogWriter` in `codejitsu.config.ts`
+
+Fill in the block above. Take care with:
+- `approvedTags` — exhaustive list. The commands will refuse to invent new tags.
+- `imageStyle.description` — be specific. This is the seed for every image prompt.
+- `seasonalRules` — free text. The batch generator reads this to balance topics by month.
+- `bannedPhrases` — common AI tells.
+
+### 2. Run `codejitsu blog:init`
+
+```bash
+npx codejitsu blog:init
+```
+
+Copies the three slash command files into `.claude/commands/`:
+- `blog.md`
+- `blog-batch.md`
+- `blog-images.md`
+
+Each is a one-line reference pointing at the matching playbook in
+`node_modules/@ibalzam/codejitsu-core/modules/blog-writer/`. **Sites should
+not edit these files.** Updates to the playbooks ship via `npm update`.
+
+### 3. Use in Claude Code
+
+```
+/blog                          # single post, interactive
+/blog "tankless water heater"  # single post with topic seeded
+/blog-batch 20                 # schedule + outline 20 future posts
+/blog-images                   # image prompts for next 10 pending posts
+/blog-images 30                # for next 30
+```
+
+## How the slash commands work
+
+Each `.claude/commands/blog.md` looks like:
+
+```md
+---
+description: Codejitsu blog writer
+argument-hint: [optional topic]
+---
+
+Open `node_modules/@ibalzam/codejitsu-core/modules/blog-writer/BLOG_WRITING.md`
+and follow it top-down. The playbook reads site-specific tone, services,
+locations, and rules from `codejitsu.config.ts`.
+
+Topic provided: $ARGUMENTS
+```
+
+When the user runs `/blog`, Claude Code feeds this file's contents as the
+prompt. Claude reads BLOG_WRITING.md from the installed package and follows
+that playbook. **The actual writing rules live in the package**, not in the
+site's repo — that's the robust part.
+
+## What must NOT be done
+
+- **Don't copy the playbook contents into the site.** The slash command
+  should be a thin reference. If a site has hand-edited BLOG_WRITING.md
+  copy, it drifts from the package over time. Reference only.
+- **Don't write posts that invent tags.** Only `approvedTags` are valid.
+- **Don't break the 5-dash separator** for image prompts. Markdown's `---`
+  is the wrong separator — use `-----` literally.
+- **Don't run `/blog-batch` with N > 50.** Too many posts in one batch
+  bunches topics and degrades quality. Three batches of 20 is better.
+- **Don't generate prose for all N in `/blog-batch`.** Schedule + outlines
+  only. Prose per row via `/blog`.
+- **Don't push or commit blog posts without user permission.**
+
+## Verify after setup
+
+- [ ] `codejitsu.config.ts` has the full `blogWriter` block
+- [ ] `.claude/commands/blog.md`, `blog-batch.md`, `blog-images.md` exist
+- [ ] Each command is a one-line reference (don't edit)
+- [ ] `node_modules/@ibalzam/codejitsu-core/modules/blog-writer/BLOG_WRITING.md` exists
+- [ ] Running `/blog` in Claude Code opens the writer (test with a throwaway topic)

package/modules/blog-writer/templates/.claude/commands/blog-batch.md

@@ -0,0 +1,10 @@
+---
+description: Codejitsu blog batch — schedule + outline N future-dated posts
+argument-hint: [N — number of posts, default 20]
+---
+
+Open `node_modules/@ibalzam/codejitsu-core/modules/blog-writer/BLOG_BATCH.md` and follow it top-down.
+
+The playbook generates a schedule + outline (NOT full prose) for the next N posts, reading services, locations, tags, cadence rules, and seasonal awareness from `codejitsu.config.ts`. Prose per row is filled in via `/blog`.
+
+N provided: $ARGUMENTS

package/modules/blog-writer/templates/.claude/commands/blog-images.md

@@ -0,0 +1,12 @@
+---
+description: Codejitsu blog image prompts — generate AI-image prompts for pending posts
+argument-hint: [N — number of prompts, default 10]
+---
+
+Open `node_modules/@ibalzam/codejitsu-core/modules/blog-writer/BLOG_IMAGES.md` and follow it top-down.
+
+The playbook reads `blogWriter.imageStyle` from `codejitsu.config.ts` (style description, branding, output dir, max words, realism) and generates prompts in the **5-dash separator format** (not the markdown `---` HR — use `-----` literally).
+
+Output goes to `Blog/IMAGE_PROMPTS.md`. Appends to existing file — never overwrites.
+
+N provided: $ARGUMENTS

package/modules/blog-writer/templates/.claude/commands/blog.md

@@ -0,0 +1,10 @@
+---
+description: Codejitsu blog writer — interactive single-post creation
+argument-hint: [optional topic]
+---
+
+Open `node_modules/@ibalzam/codejitsu-core/modules/blog-writer/BLOG_WRITING.md` and follow it top-down.
+
+The playbook reads site-specific tone, services, locations, audience, approved tags, and writing rules from `codejitsu.config.ts` (the `blogWriter` block). Don't improvise from training-data memory — the config is the source of truth.
+
+Topic provided: $ARGUMENTS

package/modules/cli/src/blog-init.mjs

@@ -0,0 +1,59 @@
+import fs from 'fs';
+import path from 'path';
+import { c } from './format.mjs';
+
+const PACKAGE_ROOT = path.resolve(
+  path.dirname(new URL(import.meta.url).pathname),
+  '..', '..', '..'
+);
+
+/**
+ * `codejitsu blog:init` — copies the blog-writer slash command templates
+ * into the site's `.claude/commands/` directory. The templates are thin
+ * references to playbooks that live in the package, so site updates flow
+ * via `npm update` without re-running this command.
+ */
+export async function runBlogInit() {
+  const cwd = process.cwd();
+  const dest = path.join(cwd, '.claude/commands');
+  const src = path.join(
+    PACKAGE_ROOT,
+    'modules/blog-writer/templates/.claude/commands'
+  );
+
+  if (!fs.existsSync(src)) {
+    console.error(c.red(`✗ Source dir missing: ${src}`));
+    console.error('  Reinstall @ibalzam/codejitsu-core.');
+    process.exit(1);
+  }
+
+  fs.mkdirSync(dest, { recursive: true });
+
+  const files = fs.readdirSync(src).filter((n) => n.endsWith('.md'));
+  console.log(c.bold('\nCodejitsu blog:init\n'));
+
+  let written = 0;
+  let skipped = 0;
+  for (const name of files) {
+    const destPath = path.join(dest, name);
+    if (fs.existsSync(destPath)) {
+      console.log(c.gray('= ') + `${name} (already exists, skipping)`);
+      skipped++;
+      continue;
+    }
+    fs.copyFileSync(path.join(src, name), destPath);
+    console.log(c.green('+ ') + `.claude/commands/${name}`);
+    written++;
+  }
+
+  console.log('');
+  console.log(`${written} created, ${skipped} skipped.`);
+  console.log('');
+  console.log('Next: configure the `blogWriter` block in codejitsu.config.ts.');
+  console.log('See `node_modules/@ibalzam/codejitsu-core/modules/blog-writer/CLAUDE.md`.');
+  console.log('');
+  console.log('Then in Claude Code:');
+  console.log('  /blog              single post, interactive');
+  console.log('  /blog-batch 20     schedule + outline 20 future posts');
+  console.log('  /blog-images       image prompts for pending posts');
+}

package/modules/config/src/types.d.ts

@@ -16,6 +16,55 @@ export interface CodejitsuConfig {
     deploy?: DeployConfig | false;
     contact?: ContactConfig | false;
     audit?: AuditConfig;
+    blogWriter?: BlogWriterConfig | false;
+}
+export interface BlogWriterConfig {
+    enabled?: boolean;
+    /** Voice + register, free text. e.g. "professional but friendly, confident not boastful". */
+    tone: string;
+    /** What the company does + who it serves. Helps the writer ground posts in context. */
+    about: string;
+    /** Primary reader. e.g. "BC Lower Mainland homeowners planning HVAC upgrades". */
+    audience: string;
+    /** Service names that map to /services/<slug>/. Used for internal-link planning. */
+    services: string[];
+    /** Location names that map to /service-areas/<slug>/. */
+    locations: string[];
+    /** Exhaustive tag list. The writer refuses to invent new tags. */
+    approvedTags: string[];
+    wordCount: {
+        min: number;
+        max: number;
+        default: number;
+    };
+    faqs?: {
+        min: number;
+        max: number;
+    };
+    internalLinks?: {
+        min: number;
+        max: number;
+    };
+    /** Pricing policy. 'brackets-only' = always show as range with context. */
+    pricing?: 'brackets-only' | 'allowed' | 'never-mention';
+    /** Free-text seasonal rules. e.g. "May-Sep: outdoor + AC; Oct-Nov: pre-winter prep". */
+    seasonalRules?: string;
+    /** Phrases the writer must NOT produce. e.g. ["In today's fast-paced world", "Look no further"]. */
+    bannedPhrases?: string[];
+    /** Frontmatter `author` default if a post doesn't specify one. */
+    authorDefault?: string;
+    imageStyle: BlogImageStyle;
+}
+export interface BlogImageStyle {
+    /** Full prompt-style description of the visual style: palette, framing, materials, mood. */
+    description: string;
+    /** Branding rule. e.g. "logo small in bottom-right corner, no other brand marks". */
+    branding: string;
+    /** Where final .webp files live. e.g. "public/assets/images/blog". */
+    outputDir: string;
+    /** Max words per generated prompt. Typical ≤ 60. */
+    maxWords: number;
+    realism: 'photorealistic' | 'illustration' | 'cartoon' | 'mixed';
 }
 export interface ContactConfig {
     enabled?: boolean;

package/modules/config/src/types.ts

@@ -17,6 +17,47 @@ export interface CodejitsuConfig {
   deploy?: DeployConfig | false;
   contact?: ContactConfig | false;
   audit?: AuditConfig;
+  blogWriter?: BlogWriterConfig | false;
+}
+
+export interface BlogWriterConfig {
+  enabled?: boolean;
+  /** Voice + register, free text. e.g. "professional but friendly, confident not boastful". */
+  tone: string;
+  /** What the company does + who it serves. Helps the writer ground posts in context. */
+  about: string;
+  /** Primary reader. e.g. "BC Lower Mainland homeowners planning HVAC upgrades". */
+  audience: string;
+  /** Service names that map to /services/<slug>/. Used for internal-link planning. */
+  services: string[];
+  /** Location names that map to /service-areas/<slug>/. */
+  locations: string[];
+  /** Exhaustive tag list. The writer refuses to invent new tags. */
+  approvedTags: string[];
+  wordCount: { min: number; max: number; default: number };
+  faqs?: { min: number; max: number };
+  internalLinks?: { min: number; max: number };
+  /** Pricing policy. 'brackets-only' = always show as range with context. */
+  pricing?: 'brackets-only' | 'allowed' | 'never-mention';
+  /** Free-text seasonal rules. e.g. "May-Sep: outdoor + AC; Oct-Nov: pre-winter prep". */
+  seasonalRules?: string;
+  /** Phrases the writer must NOT produce. e.g. ["In today's fast-paced world", "Look no further"]. */
+  bannedPhrases?: string[];
+  /** Frontmatter `author` default if a post doesn't specify one. */
+  authorDefault?: string;
+  imageStyle: BlogImageStyle;
+}
+
+export interface BlogImageStyle {
+  /** Full prompt-style description of the visual style: palette, framing, materials, mood. */
+  description: string;
+  /** Branding rule. e.g. "logo small in bottom-right corner, no other brand marks". */
+  branding: string;
+  /** Where final .webp files live. e.g. "public/assets/images/blog". */
+  outputDir: string;
+  /** Max words per generated prompt. Typical ≤ 60. */
+  maxWords: number;
+  realism: 'photorealistic' | 'illustration' | 'cartoon' | 'mixed';
 }
 
 export interface ContactConfig {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ibalzam/codejitsu-core",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "type": "module",
   "description": "Shared core for Codejitsu Astro sites — reusable code and Claude-facing instructions for blog, SEO, images, deploy, and llms.txt.",
   "keywords": [