@ibalzam/codejitsu-core 0.10.0 → 0.11.1

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,151 @@
+# 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`. If
+missing, STOP with the same error message.
+
+Also read:
+- `src/content/blog/` — existing posts (find latest `pubDate`)
+- `src/content.config.ts` — confirm the schema shape
+
+## Step 1 — Decide cadence
+
+Default cadence is **`blogWriter.cadenceDays` from config** (kit default: 4).
+
+Cadence inference rules (in order):
+1. If `blogWriter.cadenceDays` is set in config → use it (don't infer).
+2. Else if `≥ 5` existing posts with future `pubDate` exist → measure gaps
+   between their consecutive dates. If the standard deviation of gaps is
+   `≤ 30%` of the median gap → use the median.
+3. Else (irregular spacing, e.g. WordPress import dates) → fall back to **4 days**.
+
+Starting date = `max(latest existing pubDate, today) + cadence`.
+
+If you fall back to default because of irregular existing dates, **mention it
+to the user** before continuing — they may want to override.
+
+## 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,231 @@
+# 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.
+
+**If `blogWriter` is missing or empty**, STOP and tell the user:
+
+> "The blogWriter config block isn't set up yet. Add this to your codejitsu.config.ts:
+>
+> ```ts
+> blogWriter: {
+>   tone: '<one-line voice description>',
+>   about: '<what the company does + who it serves>',
+>   audience: '<primary reader, e.g. BC homeowners planning HVAC>',
+>   services: ['Service A', 'Service B'],
+>   locations: ['City A', 'City B'],
+> },
+> ```
+>
+> The other fields (approvedTags, wordCount, imageStyle, pricing, seasonalRules,
+> bannedPhrases) have sensible kit defaults. See `modules/blog-writer/CLAUDE.md`
+> for the full shape."
+
+Do not proceed without the block. Don't invent values.
+
+Everything in there is **site-specific input** for what you're about to write:
+
+- `tone` — voice + register (REQUIRED)
+- `about` — what the company does, who it serves (REQUIRED)
+- `audience` — primary reader (REQUIRED)
+- `services` — names that map to `/services/<slug>/` (REQUIRED)
+- `locations` — names that map to `/service-areas/<slug>/` (REQUIRED)
+- `approvedTags` — exhaustive. If unset, derive from `blog.categories` in config OR ask the user once
+- `wordCount` — `{ min, max, default }`. Kit default `{ 1200, 2500, 1800 }`
+- `faqs` — `{ min, max }`. Kit default `{ 5, 8 }`
+- `internalLinks` — `{ min, max }` per post. Kit default `{ 3, 6 }`
+- `pricing` — `'brackets-only' | 'allowed' | 'never-mention'`. Kit default `'brackets-only'` for service businesses
+- `seasonalRules` — free text; current date should respect this. Default: none
+- `bannedPhrases` — refuse to write these. Kit default includes "In today's fast-paced world", "When it comes to", "Look no further", "In conclusion"
+- `authorDefault` — frontmatter `author`. Default: `site.defaultAuthor` or `site.name`
+- `cadenceDays` — for /blog-batch. Kit default `4`
+
+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. **Never invent.** If nothing in `approvedTags` fits the topic,
+    STOP and ask the user:
+    > "None of your approved tags fit '<topic>'. Options: pick the closest fit
+    > from <list>, OR add a new tag to `blogWriter.approvedTags` in
+    > codejitsu.config.ts. Which?"
+    Don't auto-add tags to the config.
+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
+
+After writing the file, **actively run these checks** by reading the file back
+and counting. Don't skip. If any fail, fix in place before reporting Step 5.
+
+- Word count is within `wordCount` target (count after stripping frontmatter)
+- FAQ count in frontmatter is within `faqs.min`-`faqs.max`
+- Internal links count: grep for `](/services/` and `](/service-areas/` in body
+- Tags are all from `approvedTags`
+- **No em dashes**: grep body for `—` and `–` — neither should appear
+- **No H1 in body**: first non-frontmatter line is NOT `# ...`
+- **No `bannedPhrases`**: grep body for each banned phrase
+- **Pricing policy**: if `'brackets-only'`, grep for standalone `$<digits>` not in a range
+- **Frontmatter shape**: matches existing posts in `src/content/blog/`
+- **At least one list**: body contains `- `, `1. `, OR `|` (markdown table)
+
+If any check fails, **fix the file then re-verify**. Surface unfixable issues
+to the user before reporting Step 5.
+
+## 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,146 @@
+# 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.
+
+## Conflict with existing site blog instructions
+
+Some Codejitsu sites already have `.claude/BLOG_INSTRUCTIONS.md` (pearl,
+workzen) — older bespoke instructions written before the kit existed.
+After running `blog:init`, the site has BOTH:
+- The kit's `/blog` command → reads BLOG_WRITING.md in the package
+- The site's `.claude/BLOG_INSTRUCTIONS.md` → may be referenced by Claude
+  ambiently when the site is open
+
+**Resolution when adopting the kit on such a site:**
+1. Read the existing `.claude/BLOG_INSTRUCTIONS.md`. Identify what's
+   genuinely site-specific (specific tone phrasings, special pricing
+   rules, internal link patterns).
+2. Move those site-specific bits into `codejitsu.config.ts.blogWriter`
+   (or `seasonalRules` / `bannedPhrases` fields).
+3. Delete or rename the old `.claude/BLOG_INSTRUCTIONS.md` to
+   `.claude/BLOG_INSTRUCTIONS.archived.md` so it doesn't get auto-loaded.
+4. Keep only the kit's slash command files in `.claude/commands/`.
+
+This avoids the "two contradicting instruction sources" problem.
+
+## 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,91 @@
+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/`. The templates are thin references
+ * to playbooks that live in the package; 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('');
+
+  // Detect whether blogWriter is already in the config.
+  const configCandidates = ['codejitsu.config.ts', 'codejitsu.config.mjs', 'codejitsu.config.json'];
+  let hasBlogWriter = false;
+  for (const name of configCandidates) {
+    const p = path.join(cwd, name);
+    if (fs.existsSync(p) && /blogWriter\s*:/.test(fs.readFileSync(p, 'utf8'))) {
+      hasBlogWriter = true;
+      break;
+    }
+  }
+
+  if (hasBlogWriter) {
+    console.log(c.green('✓') + ' `blogWriter` block detected in codejitsu.config — ready to use.');
+  } else {
+    console.log(c.yellow('!') + ' No `blogWriter` block in codejitsu.config yet.');
+    console.log('');
+    console.log(c.gray('Add this minimal block to your codejitsu.config.ts:'));
+    console.log('');
+    console.log(c.gray('  blogWriter: {'));
+    console.log(c.gray("    tone: 'professional, plain-spoken, confident not boastful',"));
+    console.log(c.gray("    about: '<what the company does + who it serves>',"));
+    console.log(c.gray("    audience: '<primary reader, e.g. BC homeowners ...>',"));
+    console.log(c.gray("    services: ['Service A', 'Service B'],"));
+    console.log(c.gray("    locations: ['City A', 'City B'],"));
+    console.log(c.gray('    // Optional with kit defaults: approvedTags, wordCount, faqs,'));
+    console.log(c.gray('    //   internalLinks, pricing, seasonalRules, bannedPhrases,'));
+    console.log(c.gray('    //   authorDefault, cadenceDays, imageStyle'));
+    console.log(c.gray('  },'));
+    console.log('');
+    console.log(c.gray('See node_modules/@ibalzam/codejitsu-core/modules/blog-writer/CLAUDE.md for the full shape.'));
+  }
+
+  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');
+  console.log('');
+}

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

@@ -16,6 +16,99 @@ export interface CodejitsuConfig {
     deploy?: DeployConfig | false;
     contact?: ContactConfig | false;
     audit?: AuditConfig;
+    blogWriter?: BlogWriterConfig | false;
+}
+/**
+ * The minimum to enable blog writing: tone, about, audience, services,
+ * locations. Everything else has kit defaults that suit most sites.
+ *
+ * @example minimal
+ * ```ts
+ * blogWriter: {
+ *   tone: 'professional, plain-spoken, confident not boastful',
+ *   about: 'Veteran is a BC HVAC contractor serving the Lower Mainland',
+ *   audience: 'BC homeowners planning HVAC upgrades',
+ *   services: ['Heat Pump Installation', 'Furnace Installation'],
+ *   locations: ['Vancouver', 'Burnaby', 'Surrey'],
+ * }
+ * ```
+ */
+export interface BlogWriterConfig {
+    enabled?: boolean;
+    /** REQUIRED. Voice + register, free text. e.g. "professional but friendly, confident not boastful". */
+    tone: string;
+    /** REQUIRED. What the company does + who it serves. Grounds the writer in context. */
+    about: string;
+    /** REQUIRED. Primary reader. e.g. "BC Lower Mainland homeowners planning HVAC upgrades". */
+    audience: string;
+    /** REQUIRED. Service names mapping to /services/<slug>/. Used for internal-link planning. */
+    services: string[];
+    /** REQUIRED. Location names mapping to /service-areas/<slug>/. */
+    locations: string[];
+    /** Exhaustive tag list. The writer refuses to invent new tags; if nothing fits it asks the user. Default: derives from `blog.categories` in config, or asks at first /blog use. */
+    approvedTags?: string[];
+    /** Default: { min: 1200, max: 2500, default: 1800 } (the "Long" tier). */
+    wordCount?: {
+        min: number;
+        max: number;
+        default: number;
+    };
+    /** Default: { min: 5, max: 8 }. */
+    faqs?: {
+        min: number;
+        max: number;
+    };
+    /** Default: { min: 3, max: 6 }. */
+    internalLinks?: {
+        min: number;
+        max: number;
+    };
+    /** Default: 'brackets-only' for service businesses; 'allowed' otherwise. */
+    pricing?: 'brackets-only' | 'allowed' | 'never-mention';
+    /** Free-text seasonal rules. e.g. "May-Sep: outdoor + AC; Oct-Nov: pre-winter prep". Default: none. */
+    seasonalRules?: string;
+    /** Phrases the writer must NOT produce. Default kit list includes "In today's fast-paced world", "When it comes to", "Look no further", "In conclusion". */
+    bannedPhrases?: string[];
+    /** Frontmatter `author` default. Default: `site.defaultAuthor` or `site.name`. */
+    authorDefault?: string;
+    /** Cadence for /blog-batch, in days. Default: 4. */
+    cadenceDays?: number;
+    /** Image generation config. Required only if you'll use /blog-images. */
+    imageStyle?: BlogImageStyle;
+}
+/**
+ * @example photorealistic-architecture
+ * ```ts
+ * imageStyle: {
+ *   description: 'Photorealistic real-estate / architectural photography of the actual space the post is about. Wide landscape framing, eye-level. Bright natural daylight, modern desert-contemporary palette. Clean composition, lightly staged, no clutter, no text overlays.',
+ *   branding: 'Logo small in bottom-right corner. No other brand marks.',
+ *   outputDir: 'public/assets/images/blog',
+ *   maxWords: 60,
+ *   realism: 'photorealistic',
+ * }
+ * ```
+ *
+ * @example sloth-mascot-cartoon
+ * ```ts
+ * imageStyle: {
+ *   description: 'Cartoon sloth-mascot character relevant to the post topic, flat friendly colors, with a white rounded text box at the bottom containing a SHORT version of the title.',
+ *   branding: 'No watermarks, just the in-image character',
+ *   outputDir: 'public/images/blog/posts',
+ *   maxWords: 50,
+ *   realism: 'cartoon',
+ * }
+ * ```
+ */
+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,91 @@ export interface CodejitsuConfig {
   deploy?: DeployConfig | false;
   contact?: ContactConfig | false;
   audit?: AuditConfig;
+  blogWriter?: BlogWriterConfig | false;
+}
+
+/**
+ * The minimum to enable blog writing: tone, about, audience, services,
+ * locations. Everything else has kit defaults that suit most sites.
+ *
+ * @example minimal
+ * ```ts
+ * blogWriter: {
+ *   tone: 'professional, plain-spoken, confident not boastful',
+ *   about: 'Veteran is a BC HVAC contractor serving the Lower Mainland',
+ *   audience: 'BC homeowners planning HVAC upgrades',
+ *   services: ['Heat Pump Installation', 'Furnace Installation'],
+ *   locations: ['Vancouver', 'Burnaby', 'Surrey'],
+ * }
+ * ```
+ */
+export interface BlogWriterConfig {
+  enabled?: boolean;
+  /** REQUIRED. Voice + register, free text. e.g. "professional but friendly, confident not boastful". */
+  tone: string;
+  /** REQUIRED. What the company does + who it serves. Grounds the writer in context. */
+  about: string;
+  /** REQUIRED. Primary reader. e.g. "BC Lower Mainland homeowners planning HVAC upgrades". */
+  audience: string;
+  /** REQUIRED. Service names mapping to /services/<slug>/. Used for internal-link planning. */
+  services: string[];
+  /** REQUIRED. Location names mapping to /service-areas/<slug>/. */
+  locations: string[];
+  /** Exhaustive tag list. The writer refuses to invent new tags; if nothing fits it asks the user. Default: derives from `blog.categories` in config, or asks at first /blog use. */
+  approvedTags?: string[];
+  /** Default: { min: 1200, max: 2500, default: 1800 } (the "Long" tier). */
+  wordCount?: { min: number; max: number; default: number };
+  /** Default: { min: 5, max: 8 }. */
+  faqs?: { min: number; max: number };
+  /** Default: { min: 3, max: 6 }. */
+  internalLinks?: { min: number; max: number };
+  /** Default: 'brackets-only' for service businesses; 'allowed' otherwise. */
+  pricing?: 'brackets-only' | 'allowed' | 'never-mention';
+  /** Free-text seasonal rules. e.g. "May-Sep: outdoor + AC; Oct-Nov: pre-winter prep". Default: none. */
+  seasonalRules?: string;
+  /** Phrases the writer must NOT produce. Default kit list includes "In today's fast-paced world", "When it comes to", "Look no further", "In conclusion". */
+  bannedPhrases?: string[];
+  /** Frontmatter `author` default. Default: `site.defaultAuthor` or `site.name`. */
+  authorDefault?: string;
+  /** Cadence for /blog-batch, in days. Default: 4. */
+  cadenceDays?: number;
+  /** Image generation config. Required only if you'll use /blog-images. */
+  imageStyle?: BlogImageStyle;
+}
+
+/**
+ * @example photorealistic-architecture
+ * ```ts
+ * imageStyle: {
+ *   description: 'Photorealistic real-estate / architectural photography of the actual space the post is about. Wide landscape framing, eye-level. Bright natural daylight, modern desert-contemporary palette. Clean composition, lightly staged, no clutter, no text overlays.',
+ *   branding: 'Logo small in bottom-right corner. No other brand marks.',
+ *   outputDir: 'public/assets/images/blog',
+ *   maxWords: 60,
+ *   realism: 'photorealistic',
+ * }
+ * ```
+ *
+ * @example sloth-mascot-cartoon
+ * ```ts
+ * imageStyle: {
+ *   description: 'Cartoon sloth-mascot character relevant to the post topic, flat friendly colors, with a white rounded text box at the bottom containing a SHORT version of the title.',
+ *   branding: 'No watermarks, just the in-image character',
+ *   outputDir: 'public/images/blog/posts',
+ *   maxWords: 50,
+ *   realism: 'cartoon',
+ * }
+ * ```
+ */
+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.1",
   "type": "module",
   "description": "Shared core for Codejitsu Astro sites — reusable code and Claude-facing instructions for blog, SEO, images, deploy, and llms.txt.",
   "keywords": [