@ibalzam/codejitsu-core 0.11.1 → 0.13.0

package/SETUP.md

@@ -393,7 +393,11 @@ npx codejitsu deploy:setup
 Interactive wizard:
 - Copies `.github/workflows/daily-deploy.yml` + `wrangler.toml` from
   package templates if missing.
-- Prompts for the Cloudflare deploy hook URL.
+- Prompts for the Cloudflare deploy hook URL(s). For a multi-site monorepo
+  (one repo → several Pages projects), enter every project's hook URL
+  comma-separated; they're stored in `CLOUDFLARE_DEPLOY_HOOK_URLS` and the
+  workflow pings each. A single site uses `CLOUDFLARE_DEPLOY_HOOK_URL`.
+  See `modules/deploy/CLAUDE.md` → "Multi-site monorepos".
 - Stores it as a GH Actions secret via `gh secret set`.
 - Optionally triggers a test run.
 

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/checklist/core.md

@@ -9,7 +9,7 @@ The runner covers the easy stuff (file presence, meta tags, canonical, schema sc
 - [ ] `npm run build` exits 0 with no warnings about missing pages, unresolved imports, or broken links.
 - [ ] `dist/` contains static HTML for every expected route. No `.html` route is missing.
 - [ ] `wrangler.toml` is present and points to `dist`.
-- [ ] `.github/workflows/daily-deploy.yml` exists; the `CLOUDFLARE_DEPLOY_HOOK_URL` secret is set in the repo (skip if site has no scheduled content).
+- [ ] `.github/workflows/daily-deploy.yml` exists; the deploy-hook secret is set in the repo — `CLOUDFLARE_DEPLOY_HOOK_URL` (single site) or `CLOUDFLARE_DEPLOY_HOOK_URLS` (comma-separated, one Deploy Hook per Pages project, for a multi-site monorepo). Skip if the site has no scheduled content.
 
 ## URLs + routing
 

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

@@ -143,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

@@ -36,7 +36,10 @@ Everything in there is **site-specific input** for what you're about to write:
 - `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
+- `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 }`
@@ -47,7 +50,28 @@ Everything in there is **site-specific input** for what you're about to write:
 - `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)
 
@@ -79,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
 
@@ -152,25 +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. **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.
+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.
@@ -205,10 +282,26 @@ exactly. Examples:
 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`
+- **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

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/deploy/CLAUDE.md

@@ -5,7 +5,7 @@ When the user asks to **set up codejitsu/core/deploy** (or "wire up the Cloudfla
 ## What this module provides
 
 - `templates/wrangler.toml` — minimal Cloudflare Pages config.
-- `templates/daily-deploy.yml` — GitHub Action that pings a Cloudflare deploy hook every morning so scheduled blog posts (or any time-gated content) graduate from hidden to public on their publish date.
+- `templates/daily-deploy.yml` — GitHub Action that pings one or more Cloudflare deploy hooks every morning so scheduled blog posts (or any time-gated content) graduate from hidden to public on their publish date. Handles both single-site repos and multi-site monorepos (see below).
 
 ## Wiring it into a site
 
@@ -30,11 +30,34 @@ gh secret set CLOUDFLARE_DEPLOY_HOOK_URL --body "<paste URL>"
 
 Or via the GitHub UI: Settings → Secrets and variables → Actions → New repository secret, named `CLOUDFLARE_DEPLOY_HOOK_URL`.
 
+> Multi-site monorepo? Skip this step and follow **Multi-site monorepos** below instead.
+
 ### 4. Verify
 
 - Trigger the workflow manually: `gh workflow run "Daily Deploy"` (or via the GH UI).
 - A Cloudflare Pages deployment should kick off within seconds.
 
+## Multi-site monorepos
+
+A single repo can host several sites (e.g. `sites/www`, `sites/kamloops`, `sites/kelowna`), each deployed as its **own Cloudflare Pages project**. There is still only **one** `.github/workflows/daily-deploy.yml` for the repo, but it must rebuild **every** project — otherwise only one site graduates its scheduled content each morning and the rest stay stale.
+
+The template already handles this. To wire it up:
+
+1. **Create one deploy hook per Pages project** (Cloudflare dashboard → each project → Settings → Builds & deployments → Deploy hooks, branch `main`). For garagedoorpros that's three: `garagedoorpros-ca`, `gdp-kamloops`, `gdp-kelowna`.
+2. **Store all the URLs in a single plural secret, comma-separated** (one line — easiest to set and paste; Cloudflare hook URLs never contain commas):
+
+   ```bash
+   gh secret set CLOUDFLARE_DEPLOY_HOOK_URLS \
+     --body "https://api.cloudflare.com/.../www-hook,https://api.cloudflare.com/.../kamloops-hook,https://api.cloudflare.com/.../kelowna-hook"
+   ```
+
+   (Newline- or space-separated values also work — the workflow splits on commas, newlines, and spaces — but commas keep it a single line, which avoids the multi-line `--body` / paste pitfalls.)
+3. The workflow prefers `CLOUDFLARE_DEPLOY_HOOK_URLS` when present, splits it, and pings each URL. It only falls back to the singular `CLOUDFLARE_DEPLOY_HOOK_URL` when the plural secret is absent — so single-site repos need no change.
+
+**Adding a site later:** create its deploy hook, append `,<new-url>` to `CLOUDFLARE_DEPLOY_HOOK_URLS`, done. No workflow edit needed.
+
+**Verify:** `gh workflow run "Daily Deploy"` then confirm a deployment kicks off in *every* Pages project, not just one.
+
 ## Build command (for Cloudflare Pages git integration)
 
 If using Cloudflare's git integration (preferred for push-driven deploys):
@@ -45,7 +68,8 @@ If using Cloudflare's git integration (preferred for push-driven deploys):
 
 ## What must NOT be done
 
-- **Don't commit the deploy hook URL.** It belongs in `CLOUDFLARE_DEPLOY_HOOK_URL` secret only.
+- **Don't commit the deploy hook URL(s).** They belong in the `CLOUDFLARE_DEPLOY_HOOK_URL` / `CLOUDFLARE_DEPLOY_HOOK_URLS` secret only.
+- **Don't add a second daily-deploy workflow for a monorepo's extra sites.** One workflow pings all hooks via `CLOUDFLARE_DEPLOY_HOOK_URLS` — see **Multi-site monorepos**. Duplicate workflows mean duplicate crons and drift.
 - **Don't change the cron without reason.** 13:00 UTC is intentional — early-morning Pacific so posts are live by the time users wake up. If a site is on a different timezone, change it explicitly and note why in a comment in the workflow file.
 - **Don't add a `wrangler deploy` step to the cron workflow.** The workflow only *pings* the deploy hook; Cloudflare does the actual build via git integration. Doing the build twice causes drift.
 - **Don't skip the daily-deploy workflow even if the site has no scheduled content yet.** It's the safety net for when the user adds a scheduled post six months later.
@@ -54,5 +78,5 @@ If using Cloudflare's git integration (preferred for push-driven deploys):
 
 - [ ] `wrangler.toml` present at site root with correct `name`.
 - [ ] `.github/workflows/daily-deploy.yml` present.
-- [ ] `CLOUDFLARE_DEPLOY_HOOK_URL` secret set in the repo (check with `gh secret list`).
-- [ ] Cloudflare Pages project exists and is connected to the git repo.
+- [ ] Deploy-hook secret set (check with `gh secret list`): `CLOUDFLARE_DEPLOY_HOOK_URL` for a single site, or `CLOUDFLARE_DEPLOY_HOOK_URLS` (one URL per line) for a multi-site monorepo.
+- [ ] A Cloudflare Pages project exists for **each** site and is connected to the git repo, and every project has a hook in the secret.

package/modules/deploy/checklist.md

@@ -3,7 +3,7 @@
 - [ ] `wrangler.toml` exists at site root with the correct Cloudflare Pages project `name`.
 - [ ] `pages_build_output_dir = "dist"` in `wrangler.toml`.
 - [ ] `.github/workflows/daily-deploy.yml` exists and is unmodified from the template (or modifications are documented in a comment).
-- [ ] `CLOUDFLARE_DEPLOY_HOOK_URL` secret is set in the repo (`gh secret list`).
-- [ ] Cloudflare Pages project exists and is connected to the GitHub repo (git integration).
-- [ ] Pages build command is `npm run build`, output dir is `dist`, Node version is 20.
-- [ ] Manual run of `gh workflow run "Daily Deploy"` triggers a Cloudflare deployment within seconds.
+- [ ] Deploy-hook secret is set in the repo (`gh secret list`): `CLOUDFLARE_DEPLOY_HOOK_URL` (single site) or `CLOUDFLARE_DEPLOY_HOOK_URLS` (multi-site monorepo, one URL per line).
+- [ ] A Cloudflare Pages project exists for **each** site and is connected to the GitHub repo (git integration); every project's hook is in the secret.
+- [ ] Each Pages project's build command is `npm run build` (for its own site/workspace), output dir is `dist`, Node version is 20.
+- [ ] Manual run of `gh workflow run "Daily Deploy"` triggers a Cloudflare deployment in **every** Pages project within seconds.

package/modules/deploy/templates/daily-deploy.yml

@@ -3,9 +3,14 @@ name: Daily Deploy
 # Triggers a Cloudflare Pages rebuild each morning so any scheduled content
 # whose publish date has arrived graduates from hidden to public.
 #
-# Requires a repository secret named CLOUDFLARE_DEPLOY_HOOK_URL holding
-# the Deploy Hook URL from Cloudflare Pages (Project settings -> Builds &
+# Single-site repo: set the secret CLOUDFLARE_DEPLOY_HOOK_URL to the one
+# Deploy Hook URL from Cloudflare Pages (Project settings -> Builds &
 # deployments -> Deploy hooks).
+#
+# Multi-site monorepo (one repo -> several Pages projects): set the secret
+# CLOUDFLARE_DEPLOY_HOOK_URLS to ALL the projects' Deploy Hook URLs, separated
+# by commas (newlines also work). The job pings every URL so each site
+# rebuilds. If both secrets are set, the plural one wins.
 
 on:
   schedule:
@@ -18,12 +23,23 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: 5
     steps:
-      - name: Ping Cloudflare deploy hook
+      - name: Ping Cloudflare deploy hook(s)
         env:
+          HOOKS: ${{ secrets.CLOUDFLARE_DEPLOY_HOOK_URLS }}
           HOOK: ${{ secrets.CLOUDFLARE_DEPLOY_HOOK_URL }}
         run: |
-          if [ -z "$HOOK" ]; then
-            echo "CLOUDFLARE_DEPLOY_HOOK_URL secret is not set"
+          # Prefer the plural (multi-URL) secret; fall back to the singular one.
+          urls="$HOOKS"
+          [ -z "$urls" ] && urls="$HOOK"
+          if [ -z "$urls" ]; then
+            echo "Neither CLOUDFLARE_DEPLOY_HOOK_URLS nor CLOUDFLARE_DEPLOY_HOOK_URL is set"
             exit 1
           fi
-          curl --fail-with-body -X POST "$HOOK"
+          # Accept commas, newlines, or spaces as separators between URLs.
+          failed=0
+          for url in $(echo "$urls" | tr ',\n' '  '); do
+            [ -z "$url" ] && continue
+            echo "Pinging deploy hook: ${url%%\?*}"
+            curl --fail-with-body -X POST "$url" || failed=1
+          done
+          exit $failed

package/package.json

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