@ibalzam/codejitsu-core 0.11.0 → 0.12.0

package/bin/codejitsu.mjs

@@ -4,6 +4,7 @@ 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 { runBlogSelftest } from '../modules/cli/src/blog-selftest.mjs';
 import { runAudit } from '../modules/audit/src/run.mjs';
 
 const subcommand = process.argv[2];
@@ -13,6 +14,17 @@ const COMMANDS = {
   'blog:list': () => runBlog('blog:list'),
   'blog:drafts': () => runBlog('blog:drafts'),
   'blog:init': () => runBlogInit(),
+  'blog:selftest': () => {
+    const { values } = parseArgs({
+      args: rest,
+      options: {
+        topic: { type: 'string' },
+        model: { type: 'string' },
+      },
+      allowPositionals: true,
+    });
+    return runBlogSelftest({ topic: values.topic, model: values.model });
+  },
   'deploy:setup': () => runDeploySetup(),
   'deploy:run': () => runDeployTrigger(),
   doctor: () => runDoctor(),
@@ -59,6 +71,7 @@ function printHelp() {
   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(`  blog:selftest       Cold-Claude write a throwaway post + grade it. Flags: --topic, --model`);
   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/audit/src/groups/blog-quality.mjs

@@ -31,10 +31,17 @@ export async function runBlogQuality(ctx) {
   const staleCutoff = new Date(today);
   staleCutoff.setUTCMonth(staleCutoff.getUTCMonth() - staleMonths);
 
+  // Tag governance: approvedTags is the controlled vocabulary (cap 12).
+  const blogWriter = config.blogWriter && typeof config.blogWriter === 'object' ? config.blogWriter : null;
+  const approvedTags = blogWriter?.approvedTags ?? null;
+  const approvedSet = approvedTags ? new Set(approvedTags) : null;
+
   const stalePosts = [];
   const missingDescription = [];
   const missingImage = [];
   const shortBody = [];
+  const htmlBodyPosts = [];
+  const unapprovedTagPosts = [];
   const dupTitle = new Map();
   const dupDesc = new Map();
 
@@ -44,6 +51,22 @@ export async function runBlogQuality(ctx) {
     if (draftField && data[draftField]) continue;
 
     const slug = fileName.replace(/\.md$/, '');
+
+    // Tag governance: collect category + tags, flag any not in approvedTags.
+    if (approvedSet) {
+      const postTags = [];
+      if (typeof data.category === 'string') postTags.push(data.category);
+      if (Array.isArray(data.tags)) postTags.push(...data.tags);
+      const bad = postTags.filter((t) => !approvedSet.has(t));
+      if (bad.length > 0) {
+        unapprovedTagPosts.push(`${slug}: ${[...new Set(bad)].join(', ')}`);
+      }
+    }
+
+    // Body format: flag posts whose body is raw HTML (legacy WordPress imports).
+    if (/^\s*<(p|h[1-6]|div|ul|ol|table)[\s>]/i.test(content.trimStart())) {
+      htmlBodyPosts.push(slug);
+    }
     const dateVal = data[dateField];
     const postDate = dateVal instanceof Date ? dateVal : (typeof dateVal === 'string' ? new Date(dateVal) : null);
 
@@ -69,6 +92,30 @@ export async function runBlogQuality(ctx) {
   }
 
   results.push(info(`${files.length} blog posts indexed`));
+
+  // Tag governance results.
+  if (!approvedTags) {
+    results.push(info('No blogWriter.approvedTags configured — tag governance not enforced'));
+  } else {
+    results.push(
+      approvedTags.length <= 12
+        ? pass(`approvedTags within cap (${approvedTags.length}/12)`)
+        : fail(`approvedTags exceeds cap (${approvedTags.length}/12)`,
+            'Trim to 12 or fewer. The cap keeps the taxonomy tight.')
+    );
+    results.push(summarize(
+      'All post tags + categories are in approvedTags',
+      unapprovedTagPosts,
+      'fail'
+    ));
+  }
+
+  results.push(summarize(
+    'Post bodies are markdown (not legacy HTML)',
+    htmlBodyPosts,
+    'warn'
+  ));
+
   results.push(summarize(
     `No posts older than ${staleMonths} months`,
     stalePosts,

package/modules/blog-writer/BLOG_BATCH.md

@@ -10,19 +10,28 @@
 
 ## Step 0 — Read site config
 
-Same as `BLOG_WRITING.md` Step 0: load `codejitsu.config.ts.blogWriter`.
+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 the latest `pubDate`)
+- `src/content/blog/` — existing posts (find 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.
+Default cadence is **`blogWriter.cadenceDays` from config** (kit default: 4).
 
-Starting date = max(`latest existing pubDate`, today) + cadence.
+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
 
@@ -134,9 +143,22 @@ say stop: leave the file and exit. They can run `/blog` row by row whenever.
 
 ## 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
+After generating the schedule, **actively count** these distributions and
+rebalance the draft if any fail. Don't just eyeball.
+
+- N rows, all unique slugs (grep the slug column for duplicates)
+- Dates respect cadence; no collisions with existing post `pubDate`s
+- **Tag distribution**: no single primary tag exceeds 40% of the batch.
+  (For N=20, no tag appears as primary more than 8 times.)
+- **Topic-format distribution**: count comparison / how-to / troubleshooting /
+  seasonal across the batch. No single format exceeds ~40%. Roughly
+  30/30/20/20 is the target.
+- **City coverage**: cover most of `blogWriter.locations` before any city
+  repeats. For N ≤ locations.length, every city should be distinct.
+- **Service coverage**: spread across `blogWriter.services`; don't anchor half
+  the batch to one service.
+- Season fits each `pubDate`'s month per `seasonalRules`
+- No duplicate or near-duplicate topics (compare titles for keyword overlap)
+
+If any distribution check fails, **revise the batch before writing the file** —
+swap the over-represented topics for under-covered service/city/format combos.

package/modules/blog-writer/BLOG_WRITING.md

@@ -8,24 +8,70 @@
 ## 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
-- `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`
+- `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` — **REQUIRED for writing; the single controlled vocabulary**
+  (hard cap: 12 per site). Governs BOTH `category` and `tags` fields. If unset,
+  STOP and ask the user to define up to 12 (or derive from the `category` enum
+  in `src/content.config.ts`). Never write a post with a tag outside this list.
+- `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.
+ONE existing post in `src/content/blog/`. **Match the frontmatter field SHAPE
+(which fields exist), but NOT the body format and NOT the field VALUES.**
+
+**Body format: always write clean markdown.** Use `## H2`, `- bullets`,
+`1. numbered`, `| markdown | tables |`, `**bold**`. Do this EVEN IF existing
+posts have HTML in the body. Some sites (veteran) were WordPress-imported with
+raw HTML bodies inside their `.md` files. That is legacy, not the target.
+Astro renders markdown and inline-HTML identically, so a new markdown post sits
+fine alongside old HTML ones. Never copy `<p>`, `<h2>`, `<table>` from an
+existing post — write markdown.
+
+Critical distinction for taxonomy fields (`category`, `tags`):
+- A schema may have `category` (an enum — constrained) AND/OR `tags` (a free
+  array). Both are taxonomy.
+- `blogWriter.approvedTags` governs **every taxonomy field**. Put approved
+  values in `category` AND in `tags`.
+- **Do NOT copy free-form tag values from existing posts.** Many sites were
+  WordPress-imported with proliferated tags (every city, every appliance as a
+  tag). That sprawl is exactly what `approvedTags` exists to stop. Match the
+  field structure of old posts, ignore their messy values.
+- If `category` is an enum, pick the one approved value that fits. If `tags`
+  is a free array, fill it from `approvedTags` only — not invented descriptors.
 
 ## Step 1 — Gather inputs (interactive)
 
@@ -57,7 +103,38 @@ options:
   - "XL (2500+ words)" — Definitive guide
 ```
 
-Default = the `wordCount.default` from config.
+**Match the tier to the topic's natural scope — don't rubber-stamp the config
+default.** A focused 2-option comparison or a single-question explainer is
+usually Medium. A multi-angle definitive guide is Long or XL. Defaulting every
+post to "Long" produces either thin Long posts or padded ones.
+
+Rough mapping:
+- Comparison / "X vs Y" (2-3 options) → Medium (800-1200), occasionally Long
+- Single troubleshooting walkthrough → Medium (800-1200)
+- How-to / multi-step guide → Long (1500-2500)
+- Industry/buying guide covering many sub-topics → Long (1500-2500)
+- Definitive "everything about X" → XL (2500+)
+
+**The real quality bar is structural density + depth, NOT raw word count.**
+A post passes if every H2 has 2-3 real paragraphs, there's at least one
+list/table, and nothing reads thin. Never pad to hit a number — efficient,
+complete writing at 1200 words beats 1800 words of filler every time.
+
+**To make Long / XL posts genuinely long, add DEPTH, not words:**
+- At least one worked example or named scenario ("a Surrey homeowner switching
+  from a 15-year-old gas furnace stacked CleanBC + BC Hydro to land at roughly
+  X after rebates") — concrete, not abstract.
+- Real specifics: model families, actual process steps, real numbers inside
+  narratives, real local detail.
+- Granular sub-sections (H3s) where a topic has genuine sub-parts.
+- Show the concept applied, don't just define it.
+
+If a Long post comes in short, the fix is "what concrete example or applied
+detail is missing?" — never "add more adjectives." If after adding genuine
+depth the post is still ~1200 words and complete, it was a Medium topic;
+relabel it and move on. Do not pad.
+
+`wordCount` in config is a loose sanity band, not a target to chase.
 
 ### Question 3 — Primary service + city focus
 
@@ -130,20 +207,47 @@ frontmatter shape exactly (detected in Step 0).
    (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.
+   (default 3-6). **Target the MIDDLE of the range, not the floor.** For a
+   3-6 range, aim for 4-5. Link the FIRST mention of each distinct city and
+   service in the body. A post that names a city six times but links it once
+   is under-linked — link the first occurrence. Don't link the same URL twice;
+   don't stuff. Patterns: `/services/<slug>/`, `/service-areas/<slug>/`,
+   `/services/<slug>/<city>/`.
 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.
+8. **Pricing** — applies only to `pricing: 'brackets-only'`:
+   - **Service-cost CLAIMS must be bracket ranges with context.** What a
+     job/install/repair/service costs is always a range:
+     "a furnace replacement typically runs $6,500 - $10,000 depending on
+     venting and efficiency." Never a single figure for a cost claim.
+   - **Narrative examples may be specific.** A hypothetical scenario, a
+     story about one homeowner's invoice, or a comparison walkthrough can use
+     a specific number because it references a *scenario*, not a price claim:
+     "the technician quoted $1,400 for the control board" is fine inside a
+     decision-making narrative. When in doubt, bracket it.
+   - If `pricing: 'never-mention'`, omit all pricing.
 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.
+10. **Approved tags only — for ALL taxonomy fields, hard cap 12.** `approvedTags`
+    is the single controlled vocabulary, max 12 per site. It governs both
+    `category` (if the schema has an enum) and `tags` (if the schema has a free
+    array). Put `approvedTags` values in both. Pick 2-3, primary first.
+    **Never invent, even if existing posts use free-form tags.** WordPress
+    imports often have proliferated tags (cities, appliance types) — that
+    sprawl is exactly what `approvedTags` prevents. Match the field *shape* of
+    old posts, not their values.
+
+    **If nothing in `approvedTags` fits the topic**, STOP and ask:
+    > "None of your approved tags fit '<topic>'. Either: (a) pick the closest
+    > from <list>, or (b) add a new approved tag. You currently have <N>/12.
+    > [If N < 12:] I can add '<proposed>' to blogWriter.approvedTags. [If N = 12:]
+    > You're at the 12-tag cap — to add one, tell me which existing tag to remove."
+
+    Only add a tag to the config with explicit user approval, and never exceed
+    12. Don't auto-add.
 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.
@@ -175,16 +279,38 @@ exactly. Examples:
 
 ## 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)
+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.
+
+- **Structural density (the real bar):** every H2 has 2-3 paragraphs; at least
+  one list or table; no section reads thin. This matters more than word count.
+- Word count is a SOFT signal, not a gate. Do not pad to hit it. If a post
+  intended as Long lands short, ask "what concrete example / applied detail
+  is missing?" and add depth — OR accept it was a Medium topic and relabel.
+  Never add filler to chase a number. A dense, complete 1200-word post passes.
+- FAQ count in frontmatter is within `faqs.min`-`faqs.max`.
+- **Internal links — mechanical check, do this explicitly:**
+  1. List every distinct service AND city you named in the body.
+  2. You should have linked the FIRST mention of each (up to `internalLinks.max`).
+  3. Count your actual `](/services/` + `](/service-areas/` links.
+  4. If the count is below the range midpoint AND you have named-but-unlinked
+     services/cities, add those links now. Don't ship at the floor when you
+     mentioned linkable things and skipped them.
+  Example failure: post discusses heat pumps, furnaces, AND air conditioning
+  but only links two of them — link the third.
+- **Every taxonomy field uses `approvedTags`**: check BOTH `category` and
+  `tags` in the frontmatter. If `tags` contains any value not in
+  `approvedTags` (e.g. a city name or appliance copied from old posts),
+  that's a fail — replace with approved values.
+- **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
 

package/modules/blog-writer/CLAUDE.md

@@ -102,6 +102,27 @@ 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

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

@@ -9,9 +9,9 @@ const PACKAGE_ROOT = path.resolve(
 
 /**
  * `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.
+ * 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();
@@ -49,11 +49,43 @@ export async function runBlogInit() {
   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`.');
+
+  // 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/cli/src/blog-selftest.mjs

@@ -0,0 +1,231 @@
+import fs from 'fs';
+import path from 'path';
+import { spawn } from 'child_process';
+import matter from 'gray-matter';
+import { loadConfig, isModuleEnabled } from '../../config/src/load.mjs';
+import { c } from './format.mjs';
+
+const PACKAGE_PLAYBOOK = '@ibalzam/codejitsu-core/modules/blog-writer/BLOG_WRITING.md';
+
+/**
+ * `codejitsu blog:selftest [--topic "..."] [--model sonnet]`
+ *
+ * Spawns a COLD `claude -p` session (no memory of the kit's design), points
+ * it at the blog-writer playbook, has it write a throwaway post, then grades
+ * the output against the playbook's own rules. Reports pass/fail and deletes
+ * the test post. Report-only: exits 1 on failure (CI-friendly) but blocks
+ * nothing by default.
+ *
+ * This is the antidote to self-test bias — a fresh session reveals whether
+ * the playbook actually drives behaviour, not whether the author follows
+ * rules they already know.
+ */
+export async function runBlogSelftest({ topic, model = 'sonnet' } = {}) {
+  const cwd = process.cwd();
+
+  let config;
+  try { config = await loadConfig(cwd); }
+  catch (err) {
+    console.error(c.red(`✗ ${err.message}`));
+    process.exit(1);
+  }
+
+  if (!isModuleEnabled(config, 'blogWriter')) {
+    console.error(c.red('✗ blogWriter not configured in codejitsu.config.'));
+    console.error('  Run `codejitsu blog:init` and add the blogWriter block first.');
+    process.exit(1);
+  }
+  const bw = config.blogWriter;
+
+  if (!(await commandExists('claude'))) {
+    console.error(c.red('✗ `claude` CLI not in PATH. Install Claude Code to run selftest.'));
+    process.exit(1);
+  }
+
+  // Default topic: weave service[0] + location[0] so internal links are possible.
+  const svc = bw.services?.[0] ?? 'your main service';
+  const loc = bw.locations?.[0] ?? 'your main city';
+  const testTopic = topic ?? `${svc} considerations for ${loc} homeowners this season`;
+
+  const slug = `__selftest-${Date.now()}`;
+  const contentDir = path.resolve(cwd, (typeof config.blog === 'object' && config.blog.contentDir) || 'src/content/blog');
+  const postPath = path.join(contentDir, `${slug}.md`);
+
+  console.log(c.bold(`\nCodejitsu blog:selftest\n`));
+  console.log(`Model:  ${model}`);
+  console.log(`Topic:  ${testTopic}`);
+  console.log(`Output: ${path.relative(cwd, postPath)} (deleted after grading)`);
+  console.log(c.gray('\nSpawning a cold claude -p session… (~$0.80 on sonnet, 2-6 minutes)\n'));
+
+  const prompt = buildPrompt({ testTopic, slug });
+
+  let envelope;
+  try {
+    const out = await runCmd('claude', [
+      '-p', prompt,
+      '--allowedTools', 'Read Glob Grep Write Edit Bash',
+      '--model', model,
+      '--output-format', 'json',
+    ], 600_000);
+    if (out.code !== 0) {
+      console.error(c.red(`✗ claude exited ${out.code}`));
+      console.error(out.stderr.slice(0, 400));
+      cleanup(postPath);
+      process.exit(1);
+    }
+    envelope = JSON.parse(out.stdout);
+  } catch (err) {
+    console.error(c.red(`✗ Could not run claude: ${err.message}`));
+    cleanup(postPath);
+    process.exit(1);
+  }
+
+  if (envelope.total_cost_usd) {
+    console.log(c.gray(`Cost: ~$${Number(envelope.total_cost_usd).toFixed(3)}\n`));
+  }
+
+  if (!fs.existsSync(postPath)) {
+    console.error(c.red(`✗ Cold Claude did not write the expected file: ${path.relative(cwd, postPath)}`));
+    console.error(c.gray('Its response was:'));
+    console.error(c.gray((envelope.result ?? '').slice(0, 500)));
+    process.exit(1);
+  }
+
+  const results = gradePost(postPath, bw);
+  printGrade(results);
+  cleanup(postPath);
+
+  const fails = results.filter((r) => r.status === 'fail').length;
+  console.log('');
+  console.log(fails === 0
+    ? c.green('Selftest passed — the playbook drove a clean post from a cold session.')
+    : c.red(`Selftest found ${fails} failure(s) — tighten the playbook and re-run.`));
+  process.exit(fails > 0 ? 1 : 0);
+}
+
+function buildPrompt({ testTopic, slug }) {
+  return `You are running the /blog command for this Codejitsu site. Open ${PACKAGE_PLAYBOOK} (in node_modules) and follow it top-down to write ONE blog post.
+
+This is a NON-INTERACTIVE selftest run. SKIP the AskUserQuestion step and use:
+- Topic: ${testTopic}
+- Pick the post type + length tier that genuinely fit the topic
+- Use the next sensible future publish date
+- IMPORTANT: write the file to exactly this slug so it can be graded + cleaned up:
+  src/content/blog/${slug}.md
+
+Read codejitsu.config.ts for tone, services, locations, approvedTags, and all rules. Read src/content.config.ts for the taxonomy fields. Read ONE existing post to match the frontmatter SHAPE (but write the body in clean markdown, and use only approvedTags for category + tags). Run the playbook's Step 4 verify checks and fix any failures before finishing.`;
+}
+
+function gradePost(postPath, bw) {
+  const raw = fs.readFileSync(postPath, 'utf8');
+  let data, body;
+  try {
+    const parsed = matter(raw);
+    data = parsed.data;
+    body = parsed.content;
+  } catch (err) {
+    return [{ status: 'fail', label: 'Frontmatter parses', detail: err.message }];
+  }
+
+  const results = [];
+  const add = (ok, label, detail) =>
+    results.push({ status: ok ? 'pass' : 'fail', label, detail: ok ? undefined : detail });
+  const addWarn = (ok, label, detail) =>
+    results.push({ status: ok ? 'pass' : 'warn', label, detail: ok ? undefined : detail });
+
+  // Em dashes
+  const emDashes = (body.match(/[—–]/g) ?? []).length;
+  add(emDashes === 0, 'No em dashes', `found ${emDashes}`);
+
+  // No H1 in body
+  const firstLine = body.split('\n').find((l) => l.trim().length > 0) ?? '';
+  add(!/^#\s/.test(firstLine.trim()), 'No H1 in body', `body starts with: ${firstLine.slice(0, 50)}`);
+
+  // Markdown body, not HTML
+  add(!/^\s*<(p|h[1-6]|div|ul|ol|table)[\s>]/i.test(body.trimStart()),
+    'Body is markdown (not HTML)', 'body starts with an HTML block tag');
+
+  // FAQ count
+  const faqMin = bw.faqs?.min ?? 5;
+  const faqMax = bw.faqs?.max ?? 8;
+  const faqCount = Array.isArray(data.faqs) ? data.faqs.length : 0;
+  add(faqCount >= faqMin && faqCount <= faqMax,
+    `FAQ count in ${faqMin}-${faqMax}`, `got ${faqCount}`);
+
+  // Tags governance
+  const approved = new Set(bw.approvedTags ?? []);
+  if (approved.size > 0) {
+    const used = [];
+    if (typeof data.category === 'string') used.push(data.category);
+    if (Array.isArray(data.tags)) used.push(...data.tags);
+    const bad = [...new Set(used.filter((t) => !approved.has(t)))];
+    add(bad.length === 0, 'All tags/category in approvedTags',
+      `not approved: ${bad.join(', ')}`);
+  } else {
+    results.push({ status: 'warn', label: 'approvedTags configured', detail: 'none set' });
+  }
+
+  // Internal links
+  const linkMin = bw.internalLinks?.min ?? 3;
+  const links = (body.match(/\]\(\/(services|service-areas)\/[^)]+\)/g) ?? []).length;
+  addWarn(links >= linkMin, `Internal links ≥ ${linkMin}`, `got ${links}`);
+
+  // Banned phrases
+  const banned = bw.bannedPhrases ?? ["In today's fast-paced world", 'When it comes to', 'Look no further', 'In conclusion'];
+  const hit = banned.filter((p) => body.toLowerCase().includes(p.toLowerCase()));
+  add(hit.length === 0, 'No banned phrases', `found: ${hit.join('; ')}`);
+
+  // At least one list or table
+  const hasList = /^[-*]\s/m.test(body) || /^\d+\.\s/m.test(body) || /^\|.+\|/m.test(body);
+  add(hasList, 'At least one list or table', 'none found');
+
+  // Word count sane (not absurdly thin)
+  const words = body.split(/\s+/).filter(Boolean).length;
+  addWarn(words >= 700, 'Body ≥ 700 words (not thin)', `got ${words}`);
+  results.push({ status: 'info', label: `Body word count: ${words}` });
+
+  // Pricing brackets (only if brackets-only)
+  if (bw.pricing === 'brackets-only') {
+    // Heuristic: flag standalone $N that is NOT part of a "$N - $N" range or a narrative.
+    // We only hard-check the count; narrative examples are allowed, so this is a warn.
+    const standalone = (body.match(/\$[0-9][0-9,]*(?!\s*-\s*\$)/g) ?? []).length;
+    results.push({ status: 'info', label: `Standalone $ figures: ${standalone} (narrative examples allowed; service-cost claims should be ranges)` });
+  }
+
+  return results;
+}
+
+function printGrade(results) {
+  console.log(c.bold('Grade:'));
+  for (const r of results) {
+    const icon = r.status === 'pass' ? c.green('✓')
+      : r.status === 'warn' ? c.yellow('!')
+      : r.status === 'info' ? c.gray('i')
+      : c.red('✗');
+    console.log(`  ${icon} ${r.label}${r.detail ? c.gray('  — ' + r.detail) : ''}`);
+  }
+}
+
+function cleanup(postPath) {
+  try { if (fs.existsSync(postPath)) fs.unlinkSync(postPath); } catch {}
+}
+
+function commandExists(cmd) {
+  return new Promise((resolve) => {
+    const p = spawn('which', [cmd], { stdio: 'ignore' });
+    p.on('close', (code) => resolve(code === 0));
+    p.on('error', () => resolve(false));
+  });
+}
+
+function runCmd(cmd, args, timeoutMs) {
+  return new Promise((resolve, reject) => {
+    const proc = spawn(cmd, args, { stdio: ['ignore', 'pipe', 'pipe'] });
+    let stdout = '', stderr = '';
+    proc.stdout.on('data', (d) => { stdout += d; });
+    proc.stderr.on('data', (d) => { stderr += d; });
+    const t = setTimeout(() => { proc.kill(); reject(new Error('timed out')); }, timeoutMs);
+    proc.on('error', (e) => { clearTimeout(t); reject(e); });
+    proc.on('close', (code) => { clearTimeout(t); resolve({ code, stdout, stderr }); });
+  });
+}

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

@@ -18,43 +18,87 @@ export interface CodejitsuConfig {
     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;
-    /** Voice + register, free text. e.g. "professional but friendly, confident not boastful". */
+    /** REQUIRED. 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. */
+    /** REQUIRED. What the company does + who it serves. Grounds the writer in context. */
     about: string;
-    /** Primary reader. e.g. "BC Lower Mainland homeowners planning HVAC upgrades". */
+    /** REQUIRED. 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. */
+    /** REQUIRED. Service names mapping to /services/<slug>/. Used for internal-link planning. */
     services: string[];
-    /** Location names that map to /service-areas/<slug>/. */
+    /** REQUIRED. Location names mapping to /service-areas/<slug>/. */
     locations: string[];
-    /** Exhaustive tag list. The writer refuses to invent new tags. */
-    approvedTags: string[];
-    wordCount: {
+    /** 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;
     };
-    /** Pricing policy. 'brackets-only' = always show as range with context. */
+    /** 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". */
+    /** 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. e.g. ["In today's fast-paced world", "Look no further"]. */
+    /** 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 if a post doesn't specify one. */
+    /** Frontmatter `author` default. Default: `site.defaultAuthor` or `site.name`. */
     authorDefault?: string;
-    imageStyle: BlogImageStyle;
+    /** 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;

package/modules/config/src/types.ts

@@ -20,34 +20,78 @@ export interface CodejitsuConfig {
   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;
-  /** Voice + register, free text. e.g. "professional but friendly, confident not boastful". */
+  /** REQUIRED. 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. */
+  /** REQUIRED. What the company does + who it serves. Grounds the writer in context. */
   about: string;
-  /** Primary reader. e.g. "BC Lower Mainland homeowners planning HVAC upgrades". */
+  /** REQUIRED. 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. */
+  /** REQUIRED. Service names mapping to /services/<slug>/. Used for internal-link planning. */
   services: string[];
-  /** Location names that map to /service-areas/<slug>/. */
+  /** REQUIRED. Location names mapping 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 };
+  /** 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 };
-  /** Pricing policy. 'brackets-only' = always show as range with context. */
+  /** 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". */
+  /** 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. e.g. ["In today's fast-paced world", "Look no further"]. */
+  /** 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 if a post doesn't specify one. */
+  /** Frontmatter `author` default. Default: `site.defaultAuthor` or `site.name`. */
   authorDefault?: string;
-  imageStyle: BlogImageStyle;
+  /** 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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ibalzam/codejitsu-core",
-  "version": "0.11.0",
+  "version": "0.12.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": [