@ibalzam/codejitsu-core 0.11.0 → 0.11.1

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
 

package/modules/blog-writer/BLOG_WRITING.md

@@ -8,21 +8,43 @@
 ## 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` — 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.
@@ -143,7 +165,12 @@ frontmatter shape exactly (detected in Step 0).
    - 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.
+    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.
@@ -175,16 +202,22 @@ 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.
+
+- 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
 

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/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.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": [