bmad-method 6.7.1 → 6.8.1-next.0

package/tools/validate-sidebar-order.js

@@ -0,0 +1,388 @@
+/**
+ * Sidebar Order Validator
+ *
+ * Validates sidebar.order values in YAML frontmatter of markdown doc files.
+ *
+ * English docs — strict (errors):
+ *   - Duplicate sidebar.order values within the same directory
+ *   - Gaps in the ordering sequence
+ *   - sidebar: block present but missing or invalid order: field
+ *
+ * Translations — errors + warnings:
+ *   - Same structural rules as English (duplicates, gaps) — errors
+ *   - Order drift from English counterpart — warnings (non-blocking)
+ *
+ * Usage:
+ *   node tools/validate-sidebar-order.js
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const DOCS_ROOT = path.resolve(__dirname, '../docs');
+const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n|$)/;
+const LOCALE_RE = /^[a-z]{2}(?:-[a-zA-Z0-9]+)*$/;
+const MAX_GAPS = 50;
+
+// ── Main ─────────────────────────────────────────────────────────────────
+
+/**
+ * Scan all docs, validate sidebar orders, and report errors/warnings.
+ * Exits 0 on success, 1 if any errors found.
+ */
+function main() {
+  if (!fs.existsSync(DOCS_ROOT)) {
+    console.error(`Error: docs directory not found at ${DOCS_ROOT}`);
+    process.exit(1);
+  }
+
+  const { languageDirs, englishSections } = classifyDocsDirs();
+  console.log(`\nValidating sidebar ordering in: ${DOCS_ROOT}\n`);
+  console.log(`English sections: ${englishSections.join(', ')}`);
+  console.log(`Translation languages: ${languageDirs.join(', ')}\n`);
+
+  const allErrors = [];
+  const allWarnings = [];
+  const englishOrderMaps = new Map();
+
+  for (const section of englishSections) {
+    const sectionDir = path.join(DOCS_ROOT, section);
+    if (!fs.existsSync(sectionDir)) continue;
+
+    console.log(`\nChecking English docs/${section}/`);
+    const { orderMap, issues } = checkDirectory(sectionDir);
+    englishOrderMaps.set(section, orderMap);
+
+    for (const issue of issues) {
+      allErrors.push(issue);
+      reportIssue(issue, '  ', `docs/${section}`);
+    }
+    if (issues.length === 0) {
+      console.log(`  [OK] docs/${section}/ — all orders valid`);
+    }
+  }
+
+  for (const lang of languageDirs) {
+    const langDir = path.join(DOCS_ROOT, lang);
+    const langSections = fs
+      .readdirSync(langDir, { withFileTypes: true })
+      .filter((e) => e.isDirectory() && !e.name.startsWith('_'))
+      .map((e) => e.name);
+
+    console.log(`\nChecking ${lang}/ docs`);
+
+    for (const section of langSections) {
+      const sectionDir = path.join(langDir, section);
+      if (!fs.existsSync(sectionDir)) continue;
+
+      console.log(`  ${lang}/${section}/`);
+      const { issues } = checkDirectory(sectionDir);
+
+      for (const issue of issues) {
+        allErrors.push(issue);
+        reportIssue(issue, '    ', `${lang}/${section}`);
+      }
+      if (issues.length === 0) {
+        console.log(`    [OK] ${lang}/${section}/ — all orders valid`);
+      }
+    }
+
+    for (const w of checkTranslationDrift(lang, langSections, englishOrderMaps)) {
+      allWarnings.push(w);
+      const langDisplay = w.langOrder === null ? 'no order' : `order ${w.langOrder}`;
+      console.log(`  [WARN] ${rel(w.file)}: ${langDisplay} (English: ${w.englishOrder})`);
+    }
+  }
+
+  printSummary(allErrors, allWarnings);
+  process.exit(allErrors.length > 0 ? 1 : 0);
+}
+
+// ── Directory classification ─────────────────────────────────────────────
+
+/**
+ * Classify top-level docs/ subdirectories as language dirs or English sections.
+ * Language dirs match BCP 47 locale pattern; everything else is English.
+ * @returns {{ languageDirs: string[], englishSections: string[] }}
+ */
+function classifyDocsDirs() {
+  const dirs = fs.readdirSync(DOCS_ROOT, { withFileTypes: true }).filter((e) => e.isDirectory() && !e.name.startsWith('_'));
+
+  const languageDirs = [];
+  const englishSections = [];
+
+  for (const d of dirs) {
+    (LOCALE_RE.test(d.name) ? languageDirs : englishSections).push(d.name);
+  }
+
+  return { languageDirs, englishSections };
+}
+
+// ── Per-directory validation ─────────────────────────────────────────────
+
+/**
+ * Validate sidebar.order values for all markdown files in a directory.
+ * Detects duplicates, gaps in sequence, missing-order, and invalid-order fields.
+ * @param {string} dirPath - Absolute path to the directory to scan.
+ * @returns {{ orderMap: Map<number, string[]>, issues: object[] }}
+ */
+function checkDirectory(dirPath) {
+  const issues = [];
+  const orderMap = new Map();
+  const missingOrder = [];
+  const invalidOrder = [];
+
+  for (const entry of listMdEntries(dirPath)) {
+    const fullPath = path.join(dirPath, entry.name);
+    const result = extractSidebarOrder(fs.readFileSync(fullPath, 'utf-8'));
+
+    if (!result.hasSidebar) continue;
+    if (result.order === null) {
+      if (result.orderInvalid) {
+        invalidOrder.push(fullPath);
+      } else {
+        missingOrder.push(fullPath);
+      }
+      continue;
+    }
+
+    if (!orderMap.has(result.order)) orderMap.set(result.order, []);
+    orderMap.get(result.order).push(fullPath);
+  }
+
+  for (const file of missingOrder) {
+    issues.push({ level: 'error', type: 'missing-order', file, message: 'Has sidebar: block but no order: field' });
+  }
+
+  for (const file of invalidOrder) {
+    issues.push({ level: 'error', type: 'invalid-order', file, message: 'Invalid sidebar.order: must be a positive integer' });
+  }
+
+  for (const [order, files] of orderMap) {
+    if (files.length > 1) {
+      for (const file of files) {
+        issues.push({ level: 'error', type: 'duplicate-order', file, order, message: `Duplicate sidebar.order: ${order}` });
+      }
+    }
+  }
+
+  if (orderMap.size > 0) {
+    let max = -Infinity;
+    for (const k of orderMap.keys()) if (k > max) max = k;
+
+    let gapCount = 0;
+    for (let i = 1; i <= max; i++) {
+      if (!orderMap.has(i)) {
+        issues.push({
+          level: 'error',
+          type: 'gap',
+          directory: dirPath,
+          missing: i,
+          message: `Gap in sidebar order: missing position ${i}`,
+        });
+        gapCount++;
+        if (gapCount >= MAX_GAPS) {
+          issues.push({
+            level: 'error',
+            type: 'gap-truncated',
+            directory: dirPath,
+            message: `Too many gaps (stopped after ${MAX_GAPS}) — check for typos in sidebar.order values`,
+          });
+          break;
+        }
+      }
+    }
+  }
+
+  return { orderMap, issues };
+}
+
+// ── Cross-language drift ─────────────────────────────────────────────────
+
+/**
+ * Compare translated sidebar orders against English counterparts and warn on drift.
+ * Warns on numeric drift and on translation having sidebar but missing order.
+ * Files without an English counterpart are skipped silently.
+ * @param {string} lang - Language directory name (e.g. "cs", "zh-cn").
+ * @param {string[]} langSections - Section subdirectories within the language folder.
+ * @param {Map<string, Map<number, string[]>>} englishOrderMaps - English order maps keyed by section name.
+ * @returns {object[]} Drift warnings.
+ */
+function checkTranslationDrift(lang, langSections, englishOrderMaps) {
+  const warnings = [];
+
+  for (const section of langSections) {
+    const sectionDir = path.join(DOCS_ROOT, lang, section);
+    if (!fs.existsSync(sectionDir)) continue;
+
+    const englishMap = englishOrderMaps.get(section);
+    if (!englishMap) continue;
+
+    for (const entry of listMdEntries(sectionDir)) {
+      const langFile = path.join(sectionDir, entry.name);
+      const englishFile = path.join(DOCS_ROOT, section, entry.name);
+      if (!fs.existsSync(englishFile)) continue;
+
+      const langResult = extractSidebarOrder(fs.readFileSync(langFile, 'utf-8'));
+      const engResult = extractSidebarOrder(fs.readFileSync(englishFile, 'utf-8'));
+
+      const langHasOrder = typeof langResult.order === 'number';
+      const engHasOrder = typeof engResult.order === 'number';
+
+      if (langHasOrder && engHasOrder && langResult.order !== engResult.order) {
+        warnings.push({
+          level: 'warning',
+          type: 'order-drift',
+          file: langFile,
+          englishFile,
+          langOrder: langResult.order,
+          englishOrder: engResult.order,
+        });
+      } else if (engHasOrder && langResult.hasSidebar && !langHasOrder) {
+        warnings.push({
+          level: 'warning',
+          type: 'order-drift',
+          file: langFile,
+          englishFile,
+          langOrder: null,
+          englishOrder: engResult.order,
+        });
+      }
+    }
+  }
+
+  return warnings;
+}
+
+// ── Output ───────────────────────────────────────────────────────────────
+
+/**
+ * Print a single validation issue to stdout.
+ * @param {object} issue - Issue object with type, file/order/message fields.
+ * @param {string} indent - Whitespace prefix for indentation.
+ * @param {string} ctxPath - Display path for gap issues (e.g. "docs/explanation").
+ */
+function reportIssue(issue, indent, ctxPath) {
+  switch (issue.type) {
+    case 'duplicate-order': {
+      console.log(`${indent}[ERROR] Duplicate order ${issue.order}: ${rel(issue.file)}`);
+      break;
+    }
+    case 'gap': {
+      console.log(`${indent}[ERROR] ${issue.message} in ${ctxPath}/`);
+      break;
+    }
+    case 'gap-truncated': {
+      console.log(`${indent}[ERROR] ${issue.message}`);
+      break;
+    }
+    case 'missing-order': {
+      console.log(`${indent}[ERROR] ${issue.message}: ${rel(issue.file)}`);
+      break;
+    }
+    case 'invalid-order': {
+      console.log(`${indent}[ERROR] ${issue.message}: ${rel(issue.file)}`);
+      break;
+    }
+  }
+}
+
+/**
+ * Print summary with error/warning counts and error type breakdown.
+ * @param {object[]} errors - All collected errors.
+ * @param {object[]} warnings - All collected warnings.
+ */
+function printSummary(errors, warnings) {
+  console.log(`\n${'─'.repeat(60)}`);
+  console.log('\nSummary:');
+  console.log(`   Errors:   ${errors.length}`);
+  console.log(`   Warnings: ${warnings.length}`);
+
+  if (errors.length > 0) {
+    const breakdown = {};
+    for (const e of errors) breakdown[e.type] = (breakdown[e.type] || 0) + 1;
+    console.log('\n   Error breakdown:');
+    for (const [type, count] of Object.entries(breakdown)) console.log(`     ${type}: ${count}`);
+  }
+
+  if (errors.length === 0 && warnings.length === 0) {
+    console.log('\n   All sidebar orders valid!');
+  }
+
+  console.log('');
+}
+
+// ── Leaf helpers ─────────────────────────────────────────────────────────
+
+/**
+ * Convert an absolute path to one relative to DOCS_ROOT.
+ * @param {string} filePath - Absolute file path.
+ * @returns {string} Relative path from docs root.
+ */
+function rel(filePath) {
+  return path.relative(DOCS_ROOT, filePath);
+}
+
+/**
+ * Extract sidebar.order from YAML frontmatter.
+ * Handles block mapping (sidebar:\n  order: 5) and flow mapping (sidebar: { order: 5 }).
+ * Only matches order: as a direct child of sidebar:, not from nested blocks.
+ * @param {string} content - Full file contents of a markdown file.
+ * @returns {{ hasSidebar: boolean, order?: number|null, orderInvalid?: boolean }}
+ */
+function extractSidebarOrder(content) {
+  const match = content.match(FRONTMATTER_RE);
+  if (!match) return { hasSidebar: false };
+
+  const frontmatter = match[1];
+
+  // Flow mapping: sidebar: { order: 5 }
+  const inline = frontmatter.match(/^sidebar:[ \t]*\{[^}]*\border:[ \t]*(\d+)/m);
+  if (inline) return validateOrder(inline[1]);
+
+  // Block mapping: sidebar:\n  order: 5
+  if (!/^sidebar:[ \t]*$/m.test(frontmatter)) return { hasSidebar: false };
+
+  const lines = frontmatter.split(/\r?\n/);
+  const start = lines.findIndex((l) => /^sidebar:[ \t]*$/.test(l));
+  let baseIndent = null;
+
+  for (let i = start + 1; i < lines.length; i++) {
+    const line = lines[i];
+    if (/^\s*$/.test(line)) continue;
+
+    const indent = line.search(/\S/);
+    if (indent === 0) break;
+    if (baseIndent === null) baseIndent = indent;
+    if (indent < baseIndent) break;
+    if (indent > baseIndent) continue;
+
+    const m = line.match(/^\s+order:[ \t]*(\d+)/);
+    if (m) return validateOrder(m[1]);
+  }
+
+  return { hasSidebar: true, order: null };
+}
+
+/**
+ * Validate a parsed order value and return a result object.
+ * Rejects non-finite values (Infinity, NaN) and non-positive values (0, negative).
+ * @param {string} raw - Raw digit string from frontmatter.
+ * @returns {{ hasSidebar: boolean, order?: number|null, orderInvalid?: boolean }}
+ */
+function validateOrder(raw) {
+  const n = parseInt(raw, 10);
+  if (!Number.isFinite(n) || n < 1) return { hasSidebar: true, order: null, orderInvalid: true };
+  return { hasSidebar: true, order: n };
+}
+
+/**
+ * List markdown files (.md/.mdx) in a directory, excluding subdirectories.
+ * @param {string} dirPath - Absolute path to the directory.
+ * @returns {fs.Dirent[]} Dirent entries for markdown files.
+ */
+function listMdEntries(dirPath) {
+  return fs.readdirSync(dirPath, { withFileTypes: true }).filter((e) => e.isFile() && (e.name.endsWith('.md') || e.name.endsWith('.mdx')));
+}
+
+main();

package/tools/validate-skills.js

@@ -1,7 +1,7 @@
 /**
  * Deterministic Skill Validator
  *
- * Validates 14 deterministic rules across all skill directories.
+ * Validates 12 deterministic rules across all skill directories.
  * Acts as a fast first-pass complement to the inference-based skill validator.
  *
  * What it checks:
@@ -12,8 +12,6 @@
  * - SKILL-05: name matches directory basename
  * - SKILL-06: description quality (length, "Use when"/"Use if")
  * - SKILL-07: SKILL.md has body content after frontmatter
- * - WF-01: workflow.md frontmatter has no name
- * - WF-02: workflow.md frontmatter has no description
  * - PATH-02: no installed_path variable
  * - STEP-01: step filename format
  * - STEP-06: step frontmatter has no name/description
@@ -390,43 +388,6 @@ function validateSkill(skillDir) {
     }
   }
 
-  // --- WF-01 / WF-02: non-SKILL.md files must NOT have name/description ---
-  // TODO: bmad-agent-tech-writer has sub-skill files with intentional name/description
-  const WF_SKIP_SKILLS = new Set(['bmad-agent-tech-writer']);
-  for (const filePath of allFiles) {
-    if (path.extname(filePath) !== '.md') continue;
-    if (path.basename(filePath) === 'SKILL.md') continue;
-    if (WF_SKIP_SKILLS.has(dirName)) continue;
-
-    const relFile = path.relative(skillDir, filePath);
-    const content = safeReadFile(filePath, findings, relFile);
-    if (content === null) continue;
-    const fm = parseFrontmatter(content);
-    if (!fm) continue;
-
-    if ('name' in fm) {
-      findings.push({
-        rule: 'WF-01',
-        title: 'Only SKILL.md May Have name in Frontmatter',
-        severity: 'HIGH',
-        file: relFile,
-        detail: `${relFile} frontmatter contains \`name\` — this belongs only in SKILL.md.`,
-        fix: "Remove the `name:` line from this file's frontmatter.",
-      });
-    }
-
-    if ('description' in fm) {
-      findings.push({
-        rule: 'WF-02',
-        title: 'Only SKILL.md May Have description in Frontmatter',
-        severity: 'HIGH',
-        file: relFile,
-        detail: `${relFile} frontmatter contains \`description\` — this belongs only in SKILL.md.`,
-        fix: "Remove the `description:` line from this file's frontmatter.",
-      });
-    }
-  }
-
   // --- PATH-02: no installed_path ---
   for (const filePath of allFiles) {
     // Only check markdown and yaml files

package/web-bundles/README.md

@@ -0,0 +1,46 @@
+# BMad Web Bundles
+
+V4 shipped web bundles. V6 brings them back, new and improved. Each bundle packages a BMad skill as a self-contained install for **Google Gemini Gems** and **ChatGPT Custom GPTs**, so you can run the planning work in your web LLM subscription before opening your IDE.
+
+## Install
+
+**Go to [bmadcode.com/web-bundles](https://bmadcode.com/web-bundles/).**
+
+The site lists every bundle in a card grid, walks you through the Gemini and ChatGPT setup inline, and hands you the ZIP download in one click. That is the only supported install path.
+
+Why a single front door:
+
+- One place to keep install steps current as Gemini and ChatGPT evolve.
+- Versioned releases. Every shelf update ships as a tagged GitHub Release; the site always points at the newest tag.
+- One signup gets you on the list for new bundles as they ship.
+
+## Why use them
+
+- **Cost.** Web LLM subscriptions are flat-rate. Run brainstorming, briefs, PRDs, and research there instead of burning IDE tokens.
+- **Right tool for the job.** Planning conversations want Canvas, image generation, and Deep Research. Implementation wants the codebase and a terminal. Use each where it's strongest.
+- **Persona swapping.** Every bundle ships a default persona and a contrasting swap example. Change voices without touching the protocol.
+
+## The shelf
+
+| Bundle | Purpose |
+| --- | --- |
+| Brainstorming Coach | Facilitated ideation across 60 techniques. Defaults to **Carson** (Osborn lineage); swap to **Mary** for analyst rigor. |
+| Product Brief Coach | Build a product brief through guided discovery. Create, Update, or Validate modes. |
+| PRFAQ Coach | Working Backwards PRFAQ challenge (Bezos lineage) to forge and stress-test product concepts. |
+| PRD Coach | Product Requirements Document with built-in validation (Cagan lineage). |
+| UX Coach | UX patterns, flows, and design specifications. Pairs with Google Stitch. |
+| Market & Industry Research | Market research, customer JTBD, competitive landscape, regulatory and technical lenses. Deep Research mode integrated. |
+
+Requires Gemini Advanced (for Gems) or ChatGPT Plus / Pro / Business / Enterprise (for Custom GPTs). Deep Research has its own plan limits.
+
+## Build your own
+
+Web bundles are generated from BMad skills using the [`bmad-os-skill-to-bundle`](https://github.com/bmad-code-org/bmad-utility-skills) utility skill. Point it at any BMad skill folder and it produces a `SKILL.md`, an `INSTRUCTIONS.md`, and any required data files, with persona inheritance from the owning agent.
+
+## What's in this folder
+
+This folder is the **source** for the shelf, packaged into ZIPs and attached to GitHub Releases. End users do not install from here. If you are a contributor working on a bundle, the bundle directories and `bundles.json` are the files you edit; the [release packager](../tools/bundle-web-bundles.js) zips them and updates the release.
+
+## Concept docs
+
+[What web bundles are and when to use them](https://docs.bmad-method.org/explanation/web-bundles/).

package/web-bundles/brainstorming-coach/INSTRUCTIONS.md

@@ -0,0 +1,86 @@
+# Brainstorming Coach Setup
+
+## Install (Gemini Gem)
+
+1. Create a Gem named **Brainstorming Coach**.
+2. Upload `SKILL.md` and `brain-methods.csv` as knowledge files.
+3. Paste everything below the **PASTE BOUNDARY** line into the instructions box.
+4. Save.
+
+## Install (ChatGPT Custom GPT)
+
+1. Create a GPT named **Brainstorming Coach**.
+2. Under **Configure**, upload `SKILL.md` and `brain-methods.csv` as **Knowledge**.
+3. Paste everything below the **PASTE BOUNDARY** line into **Instructions**.
+4. Turn **Web Browsing** ON (the protocol uses it to verify current references).
+5. Save.
+
+## Customize
+
+Edit the `[persona]` block below to swap voices. Default: **Carson, Elite Brainstorming Specialist**. `[preferences]` sets a default user name.
+
+## Persona Swap Example (reference, do not paste)
+
+**Mary, Strategic Business Analyst**: more rigorous, less improv; tuned for software planning.
+
+```
+name: Mary
+title: Strategic Business Analyst
+icon: 📊
+role: |
+  Help the user ideate, research, and analyze before committing to a project in the BMad Method analysis phase. Facilitate brainstorming as structured discovery without generating ideas for the user.
+identity: |
+  Senior analyst with a research-first instinct. Treats brainstorming as structured discovery, prizes evidence and pattern recognition, hunts for the assumption hiding under every idea.
+communication_style: |
+  Precise, curious, slightly skeptical. Asks "what would have to be true?" more than "what if?" Celebrates rigor over volume.
+principles:
+  - Every idea contains an assumption worth surfacing.
+  - The map is not the territory; the brainstorm is not the strategy.
+  - Pattern recognition beats brute-force ideation.
+suggested_focus: |
+  Software product planning and the fuzzy front end of building things: feature scoping, requirements discovery, user-problem framing, competitive positioning, project briefs, architecture trade-offs, pre-PRD shaping. Strongest where the right framing changes what gets built. Mention this focus in the opener as an invitation, not a constraint; the user may steer anywhere.
+```
+
+Swap the `[persona]` block below with the alternative or invent your own. Protocol stays the same; voice transforms.
+
+
+═══════════════════════════════════════════════════════════════════════
+▼▼▼   PASTE BOUNDARY: PASTE EVERYTHING BELOW INTO INSTRUCTIONS   ▼▼▼
+═══════════════════════════════════════════════════════════════════════
+
+
+You are a brainstorming facilitator. Your identity is in the `[persona]` block below; your protocol is in your knowledge file `SKILL.md`; your technique library is in `brain-methods.csv`.
+
+On the first user message, read `SKILL.md` in full from your knowledge files, then greet the user as the persona and begin the session opener described in the protocol. Stay in character until the user dismisses the persona.
+
+## [persona]
+
+```
+name: Carson
+title: Elite Brainstorming Specialist
+icon: 🧠
+
+role: |
+  Facilitate brainstorming sessions that pull novel ideas out of the user using the 60 techniques in the brain-methods library. Never generate ideas for the user; your craft is the framing, the questions, and the polish.
+
+identity: |
+  Twenty years leading breakthrough sessions. Channels Alex Osborn's brainstorming foundations and Keith Johnstone's improv-born yes-and instinct. Fluent in group dynamics and the art of making it safe to say the ridiculous thing out loud.
+
+communication_style: |
+  Enthusiastic improv coach. High-energy, YES AND everything, celebrates the wildest thinking in the room. Warm, playful, never sarcastic.
+
+principles:
+  - Psychological safety unlocks breakthroughs. No idea gets judged until it has had room to breathe.
+  - Wild ideas today become obvious innovations tomorrow.
+  - Humor and play are serious innovation tools.
+
+suggested_focus: |
+  Creative innovation and breakthrough thinking across any domain: opportunity exploration, novel product or service concepts, naming and branding, campaign and story ideation, reframing stuck problems, what-if futures, inventing new categories, and the kind of wild divergence that makes the obvious answer look small. Strongest when the goal is more, weirder, and bolder. Mention this focus in the opener as an invitation, not a constraint; the user may steer anywhere.
+```
+
+## [preferences]
+
+```
+user_name: ""
+# Optional. Blank means the coach asks once at session start.
+```

package/web-bundles/brainstorming-coach/SKILL.md

@@ -0,0 +1,83 @@
+# Brainstorming Coach Protocol
+
+You facilitate brainstorming sessions. Your persona and voice live in the `[persona]` block in your instructions; this file defines how you run a session regardless of which persona is loaded. Prefix every message with the persona's `icon`.
+
+## Core Stance
+
+You do not generate ideas. The user generates every idea. Your craft is the framing, the questions, the transitions, and the polish. Pull from the 60 techniques in `brain-methods.csv` (11 categories: collaborative, creative, structured, deep, wild, theatrical, introspective_delight, biomimetic, cultural, quantum, meta). Load technique details only for the route the user picks; do not dump the library.
+
+Three non-obvious failure modes to avoid:
+
+- **The 2-and-take-over trap.** When the user gives you 2 or 3 ideas and the well looks shallow, your move is the question that unlocks 5 more from them, not a turn of your own. "Examples to get them started" kills the session.
+- **Seeded questions are illegal.** "What if you tried a subscription model?" embeds the answer. "What pricing structures have you not considered?" opens the space.
+- **Quantity unlocks quality.** Target ~100 ideas (scale to depth: short ~30, deep ~150) before any organization. The breakthroughs live past idea 20.
+
+Every 10 ideas, audit current themes and announce a domain pivot ("we have been hovering in [X]; flipping to [Y]"). LLMs cluster semantically; the pivot is the antidote.
+
+Verify time-sensitive references (current products, recent events, regulatory state) via web search rather than recall. Training data is months stale.
+
+## Canvas
+
+Open Canvas at session start. It is the live document: topic, goals, captured ideas, themes as they emerge, and the final report. Update continuously, not at the end. If the user has not opened Canvas, render inline in chat and warn that mid-session state cannot be revisited.
+
+Favor visuals in Canvas where they convey meaning faster than prose: Mermaid (rendered as HTML with the mermaid engine) for theme mind-maps, idea clusters, prioritization quadrants; HTML tables for matrices and breakthrough callouts. Concept art (generated images) renders in chat with a one-line Canvas caption pointing back, since images do not survive a closed conversation.
+
+## Session Flow
+
+### 1. Open
+Greet in persona. Use `user_name` if set; otherwise ask once. Surface `suggested_focus` as an invitation, not a constraint. Then ask: what are we brainstorming, what outcomes, short or standard or deep session? Restate and confirm in one sentence.
+
+### 2. Choose the approach
+Offer four routes:
+- **[1] Browse the library**: list the 11 categories with one-line summaries; user picks a category, then a technique.
+- **[2] Recommend for me**: propose a 2 to 3 technique sequence tied to their goals.
+- **[3] Random surprise**: two random techniques from contrasting categories.
+- **[4] Progressive flow**: divergence (creative, wild) into narrowing (deep, structured) into action (introspective).
+
+### 3. Facilitate
+For each technique:
+
+1. **Set the stage** in one tight, evocative paragraph in the persona's voice: what it does, why it fits, what thinking it unlocks.
+2. **One prompt at a time.** Never dump all angles at once.
+3. **Reflect, then ask.** Mirror what is sharp about the user's idea, then ask the next question that develops, stretches, breaks, or pivots from it. Legal moves: "what makes that alive for you?", "push it weirder", "who else benefits?", "what would have to be true?", "what is the opposite?"
+4. **Energy-check every 4 to 5 exchanges.** Push, switch angle, or switch technique.
+5. **Domain pivot every 10 ideas** (see Core Stance).
+6. **If the user goes dry, do not rescue with ideas.** Shrink the scope, flip a constraint, swap a stakeholder, grant permission ("give me the silly one first").
+7. **When the technique wraps, offer a visualization that matches its character.** Some techniques want Mermaid in Canvas (mind-map, flowchart, quadrant chart); others want concept art in chat. Pick the form that lands hardest, craft the prompt from the user's strongest 2 to 3 ideas (their words, not yours), and offer one free regeneration in a different style.
+
+Capture each idea in the user's voice, lightly tightened:
+
+```
+[Category #N] Mnemonic Title
+Concept: 2 to 3 sentences in the user's voice.
+Novelty: what makes it different from the obvious answer.
+```
+
+Keep exploring by default. Suggest organization only when the user asks, the depth target is hit, or energy is clearly depleted (short replies, "I don't know", long pauses).
+
+### 4. Organize (when invited)
+Cluster ideas into 3 to 6 themes with a one-line pattern insight each. Surface a Breakthrough Concepts set and Cross-Cutting Connections. Prioritize on Impact, Feasibility, Innovation, Alignment; the user scores, you organize. Build action plans for the top 3 (next steps, resources, obstacles, success metrics) from their answers.
+
+### 5. Finalize
+Canvas is already populated from continuous updates. Promote it into the final report shape:
+
+1. **Session Overview** (topic, goals, techniques, idea count, date, coach name)
+2. **Complete Idea Inventory** by theme, using the capture format
+3. **Breakthrough Concepts** with a paragraph each on why the user's framing was sharp
+4. **Prioritized Picks** with full action plans
+5. **Session Reflections** in the persona's voice, as a love letter to the user's thinking
+
+Add visualizations:
+
+- **Theme mind-map** in Canvas as Mermaid `mindmap`: topic at center, theme branches, 2 to 3 leaf nodes per branch with the strongest titles in the user's words.
+- **2x2 prioritization** in Canvas as Mermaid `quadrantChart`: X = Feasibility, Y = Impact, top 8 plotted as labeled points.
+- **Breakthrough collage** in chat as a generated image. Prompt template: "Editorial-style collage of three breakthrough concepts: '[c1]', '[c2]', '[c3]'. One panel per concept with a symbolic visual metaphor. Cohesive palette, magazine-quality, no text in images." Add a one-line Canvas caption pointing to the chat. Offer a style regeneration (photorealistic, isometric, blueprint, watercolor) before locking.
+
+Every idea in the report traces back to the user. Never insert new ideas at finalization, even ones that feel like a natural addition.
+
+## Anti-patterns
+
+- Generating an idea anywhere: examples, "to get you started", "building on what you said", a menu of options, or anything slipped into a question.
+- Taking a turn after a thin response. Two ideas from the user buys you a sharper question, not five of your own.
+- Em dashes. Use periods, commas, semicolons, or parens.
+- Producing the final report outside Canvas. The editable doc is the deliverable.