feat(course): full v2 migration - all modules to micro-lesson format, 18 reference deep-dives, reuse/voice/render audits

.gitignore

@@ -26,6 +26,7 @@ hugo.linux
 # Other
 .DS_Store
 .*
+!.okf
 !.claude
 .claude/**/*.json
 .claude/**/*.sh
@@ -123,3 +124,5 @@ docs/projects/**/sprint-*-verification-report.md
 docs/projects/**/*-coordinator-report.md
 docs/projects/**/*-verification-report.md
 .grepai/
+*.rvf
+*.rvf.lock

.okf/build/hugo-build.md

@@ -0,0 +1,31 @@
+---
+type: Build Pipeline
+title: Hugo build (bin/hugo-build)
+description: Canonical build + validation entry point; runs Hugo plus the course validators including the banned-strings ratchet.
+resource: bin/hugo-build
+tags: [build, hugo, validation]
+timestamp: 2026-07-13T00:00:00Z
+---
+
+`bin/hugo-build` builds the site into `_dest/public-dev/` (repo-root
+`public/` is a stale artifact - never review it) and runs the validation
+suite. Zero build breaks is a hard rule - all content changes must pass it
+before commit.
+
+# Key facts
+
+- Course pages get extra validators, including the banned-strings ratchet
+  driven by [data/course_banned_strings.yaml](/content/banned-strings-ratchet.md).
+- The ratchet scans course chapter SOURCE markdown (`index.md` bodies,
+  case-sensitive substring match) - not rendered HTML, and never SVG artwork
+  or mermaid diagram labels. Defects inside artwork need the
+  [visual scroll gate](/workflows/render-verification.md).
+- Build twice as a control before blaming an edit for output flicker:
+  Hugo stats/PurgeCSS interactions can produce nondeterministic diffs
+  (term-casing races, header partialCached race).
+
+# Examples
+
+```bash
+bin/hugo-build            # build + validate
+```

.okf/build/index.md

@@ -0,0 +1,5 @@
+# Build & Test
+
+* [Hugo build pipeline](hugo-build.md) - bin/hugo-build with the 8 course validators
+* [Test gates](test-gates.md) - the three suites and when each is a commit blocker
+* [Template PDFs](pdf-templates.md) - regenerating the downloadable course PDFs

.okf/build/pdf-templates.md

@@ -0,0 +1,20 @@
+---
+type: Build Pipeline
+title: Course template PDFs
+description: bin/generate-template-pdfs regenerates the downloadable course PDFs from built pages; run it after editing any template chapter.
+resource: bin/generate-template-pdfs
+tags: [build, pdf, course]
+timestamp: 2026-07-13T00:00:00Z
+---
+
+The course offers downloadable PDF versions of its template chapters
+(worksheet, ownership checklist, and siblings). They are generated FROM the
+built HTML pages, so any content change to a template chapter silently
+stales its PDF.
+
+# Steps
+
+1. Edit the template chapter markdown.
+2. `bin/hugo-build`
+3. `bin/generate-template-pdfs`
+4. Commit the regenerated PDFs together with the content change.

.okf/build/test-gates.md

@@ -0,0 +1,35 @@
+---
+type: Playbook
+title: Test gates and when they block commits
+description: bin/rake test:critical always; bin/test AND bin/dtest are both mandatory for any themes/, layouts/, or CSS change.
+tags: [testing, visual-regression, gates]
+timestamp: 2026-07-13T00:00:00Z
+---
+
+# The three suites
+
+| Command | What it is | When required |
+|---|---|---|
+| `bin/rake test:critical` | Critical Minitest suite (46 runs / 84 screenshots) | After every change, before every commit |
+| `bin/test` | Visual regression on macOS host (baselines in `test/fixtures/screenshots/macos/`) | Any edit to `themes/`, `layouts/`, `*.css`, or post body HTML |
+| `bin/dtest` | Same suite in Linux/Docker (baselines in `linux/`) - CI runs Linux | Same trigger as bin/test; skipping it ships green-locally / red-in-CI |
+
+# Hard-won caveats
+
+- The snapshot tool REWRITES baselines when a run passes. Never edit CSS
+  while a suite is running - a raced run once saved a corrupt baseline
+  missing its hero image. Catch with pixel-compare, restore via `git checkout`.
+- Visual failures are commit blockers, not warnings. Either fix the
+  regression or update BOTH baseline dirs (macos/ and linux/) in the same
+  commit with the intentional change.
+- Content-only + standalone-SVG waves need
+  [bin/hugo-build](/build/hugo-build.md) + `test:critical` + the
+  [visual scroll gate](/workflows/render-verification.md) on edited pages -
+  the command matrix above is not the complete gate on its own.
+- Changes to `lib/` (validators, helpers) additionally require
+  `bundle exec rake test:unit` - CI runs the unit suite and `test:critical`
+  does NOT include it (2026-07-17: a validator change shipped green locally,
+  red in CI, because its unit fixture was never run).
+- Docker runs via Colima; fresh worktrees need `bun install` first.
+- Tests must assert behavior shape (`q=\d+`, has `<picture>`), never tunable
+  config values (exact quality/width numbers).

.okf/content/banned-strings-ratchet.md

@@ -0,0 +1,27 @@
+---
+type: Validator
+title: Banned-strings ratchet
+description: data/course_banned_strings.yaml pins every fixed prose defect so it cannot silently regress; entries can be scoped to a single page.
+resource: data/course_banned_strings.yaml
+tags: [validation, course, regression]
+timestamp: 2026-07-13T00:00:00Z
+---
+
+When a review sprint fixes a prose defect (a wrong tool name, a banned
+phrase, a stale threshold), the exact defective string is added to
+`data/course_banned_strings.yaml`. [bin/hugo-build](/build/hugo-build.md)
+fails if it reappears in any course chapter's SOURCE markdown body
+(case-sensitive substring match against `index.md`).
+
+# Rules
+
+- Entries support per-page scoping via an optional `scope` regex matched
+  against the bundle directory name (e.g. ban "Airtable" only on the
+  operating-kit page). There is NO exemption mechanism - if a string must
+  stay legal on some page, scope the entry AWAY from that page instead.
+- The ratchet reads source markdown only - it is blind to text inside SVG
+  artwork and mermaid labels. Artwork defects are caught by the
+  [render-verification playbook](/workflows/render-verification.md) instead.
+- After fixing any prose defect, grep your own replacement text for the
+  exact pattern you just removed - re-introducing the defect being fixed is
+  a blocking failure.

.okf/content/course-canon.md

@@ -0,0 +1,61 @@
+---
+type: Reference
+title: Course canon numbers
+description: The single source of truth for every recurring number in the course; any chapter that contradicts these is defective.
+tags: [course, canon, consistency]
+timestamp: 2026-07-13T00:00:00Z
+---
+
+# Canonical values
+
+| Fact | Canon |
+|---|---|
+| Founding Hypothesis score | ≥14/20 across four lenses |
+| Smoke test traffic | 300 cold visitors |
+| Interviews | 10 (from a 30-name list, expanded if replies run thin) |
+| Build / pivot / kill gate | 7+ strong signals build · 4-6 pivot · under 4 kill |
+| Prototype test subjects | 5 interview subjects |
+| Sean Ellis must-have test | 40% - directional at ≥10 respondents, useful at 20+, sliceable at 30+ |
+| Cold reply bands | 3-8% realistic; <5% stop and diagnose · 5-10% continue · >10% accelerate |
+| Paid pilot deposit | $500+ refundable, via Stripe |
+| Tracking tool | Google Sheet - never Airtable |
+| AI token pass-through | disciplined $80-$120/dev/mo · undisciplined $300-$500; industry range $80-$300 |
+| Slopsquatting source | Lasso Security research March 2025; "slopsquatting" coined by Infosecurity Magazine April 2025 |
+
+# Recurring cast (keep consistent across chapters)
+
+- **Mia** - the walkthrough protagonist (TutorMatch).
+- **Marcos** (author) and **Priya** (reviewer) - the PR-review example pair.
+  Spelling is "Marcos", never "Marcus". PR #847 = the refund-branch review
+  story; the weekly-report admin-search example uses PR #843.
+
+Structural home: [course structure](/content/course-structure.md).
+Enforcement: [banned-strings ratchet](/content/banned-strings-ratchet.md).
+
+# External sources for cited claims
+
+- Sean Ellis 40% test: [Lenny's Podcast interview](https://www.lennysnewsletter.com/p/the-original-growth-hacker-sean-ellis) (cutoff + wording).
+- Slopsquatting: [Lasso Security research](https://www.lasso.security/blog/ai-package-hallucinations) + [Infosecurity Magazine, April 2025](https://www.infosecurity-magazine.com/news/ai-hallucinations-slopsquatting/) (coined the term).
+- First-10-customers network finding: [Lenny Rachitsky's B2B first-customers research](https://www.lennysnewsletter.com/p/how-todays-fastest-growing-b2b-businesses).
+- Interview method: Teresa Torres, [Customer Interviews](https://www.producttalk.org/customer-interviews/) and [Learning to Interview Continuously](https://www.producttalk.org/learning-to-interview-continuously/) (Product Talk).
+- Reply bands, deposit bands, token pass-through ranges: internal editorial
+  canon (JT practice numbers) - no external citation; do not invent one.
+
+# Progressive elaboration rule (expand, never restart)
+
+Later lessons MAY deepen an earlier artifact; they MUST NOT re-derive it
+from a blank page. Mechanically: any lesson touching an earlier artifact
+opens WITH it - "open your [artifact] from Lesson N.N, paste it here" -
+and adds a named delta. Every prompt slot names its source artifact.
+Good: 2.3's three sentences ("your 1.1 blanks, unpacked - copy the
+sentence in"). Bad: a persona prompt asking Sam to describe the customer
+fresh when the ICP map already exists. Owner rule 2026-07-17: "it's ok to
+expand previous results; but if we start over to do the same it's
+confusing."
+
+# Terminology
+
+Numbered core units are **Lessons** ("Lesson N.N", never "Chapter N.N" or
+"Ch N.N" - enforced by the lesson-number validator; decided in the 30.03
+format spec). "Chapters" remains only for the non-numbered long-form set
+(Going Further, continuation, supplementary references).

.okf/content/course-structure.md

@@ -0,0 +1,43 @@
+---
+type: Content Architecture
+title: Course structure (From Idea to First Paying Customer)
+description: 5-module linear spine defined in data/course_sequence.yaml, plus a non-linear Going Further set, per-module Mia walkthroughs, and template chapters.
+resource: content/course/tech-for-non-technical-founders-2026/
+tags: [course, structure, hugo]
+timestamp: 2026-07-17T00:00:00Z
+---
+
+# The spine
+
+The reading order lives in `data/course_sequence.yaml` - the Overview
+(how-this-course-works) then Modules 1-5 (hypothesis → smoke test →
+interviews → brief/build → first paying customer). The prev/next strip,
+branch-aware forks, and the `course-stat` shortcode all derive from that
+file. Never hardcode exact chapter counts in prose; use near numbers
+("20+ lessons").
+
+# Outside the spine
+
+- **Going Further set** (linked from the 5.7 closing callout): continuation
+  chapters (churn triage, pivot-or-persevere), the hire-track reference,
+  demoted management chapters (engineering org chart, friday demo rule,
+  three questions standup, weekly dev report), and the AI-in-production trio
+  (agency AI questions → AI token bill → slopsquatting, badged Step 1-3 of 3).
+- **Mia walkthroughs**: one per module (`module-N-walkthrough-mia`).
+- **Templates**: worksheet/checklist/script chapters with
+  [generated PDFs](/build/pdf-templates.md).
+- **Reference deep-dives** under `reference/` - every module now has them
+  (M1: hypothesis-sprint-full, smoke-test-channel-guide,
+  stripe-price-test-full; M2: mom-test-full, persona-rehearsal-full,
+  find-10-people-full (shared by 2.3+2.4), prototype-build-full;
+  M3: product-brief-full, outcomes-not-features-full; M4: hire-decision-full,
+  ownership-full, stack-tools-full, mvp-build-phases-full,
+  ceiling-signals-full; M5: must-have-survey-full, channel-selection-full,
+  paid-pilot-full, outbound-full). Lessons point at them via a
+  `Deeper reference:` footer line; the module landing cards link them as
+  "Optional reference". As of 2026-07-17 ALL five modules are migrated to
+  the v2 micro-lesson format - no v1 long-form lessons remain.
+- **Floating glossary**: five-tech-words-stop-nodding-at, reachable from every
+  chapter, not in the linear order.
+
+All chapter facts must agree with the [course canon](/content/course-canon.md).

.okf/content/index.md

@@ -0,0 +1,6 @@
+# Content
+
+* [Course structure](course-structure.md) - the 5-module spine, Going Further set, and course_sequence.yaml
+* [Course canon](course-canon.md) - the numbers every chapter must agree on
+* [Voice rules](voice-rules.md) - Sam voice, banned patterns, and the em-dash rule
+* [Banned-strings ratchet](banned-strings-ratchet.md) - how fixed prose defects stay fixed

.okf/content/voice-rules.md

@@ -0,0 +1,42 @@
+---
+type: Style Guide
+title: Course voice rules (write for Sam)
+description: The reader is Sam, an idea-stage non-technical first-time founder; plain-words glossing, dash style, and the banned structural patterns.
+tags: [voice, style, course]
+timestamp: 2026-07-13T00:00:00Z
+---
+
+Full guides: `docs/90-99-content-strategy/strategy-analysis/90.11-voice-guide.md`
+and the course-specific rules in `CLAUDE.md`. This concept records the
+rules that recur in review sprints.
+
+# Core rules
+
+- **Write for Sam, not Paul.** Sam is an idea-stage non-technical founder.
+  Course bodies never use rescue/trauma framing (that ICP is the website's
+  "Alex", not the course's Sam); the Going Further rescue chapters are the
+  exemption.
+- **Gloss at first mention** - every acronym/tool/term gets a plain-words
+  parenthetical the first time it appears in the reading order (SOW, MSA,
+  SLA, FTE, PLG, ARPU, MAU, RAG-status, 0day...).
+- **Dashes**: always "-", never "—" - in prose AND inside SVG/mermaid artwork.
+- **Progressive disclosure**: orientation blocks orient; thresholds and
+  mechanics belong where the reader acts on them.
+- **Callout rhythm**: no two adjacent same-form callouts.
+
+# Banned structural patterns (reject on sight)
+
+Slogany reveal-twist flips ("X wasn't Y - it was Z"), cinematic time-cut
+narration, anonymous-founder-vignette openers repeated 3+ chapters in a row,
+aphoristic flourish closers, fabricated cohort stats without a source,
+`## Why this matters` headings, "Founders who / Most founders / Founders we
+worked with", dual-source statistical openers, sustained staccato.
+
+Sentence-level slop scoring is necessary but NOT sufficient - shape-tell
+review (essay arc, pivot sentences, cloned scaffolding) runs alongside it.
+
+Regression sweep before any handback:
+
+```bash
+grep -rn "## Why this matters\|Founders who\|Most founders\|Founders we worked with" content/course/
+```

.okf/design/course-typography.md

@@ -0,0 +1,34 @@
+---
+type: Design System
+title: Course reading typography
+description: Course pages read at 20px/1.65 body scale (blog keeps 22.4px); overrides must mirror the full single-post.css selector chain or they silently lose.
+resource: themes/beaver/assets/css/style.css
+tags: [css, typography, course]
+timestamp: 2026-07-13T00:00:00Z
+---
+
+# The scale (course pages only)
+
+| Element | Value |
+|---|---|
+| Body p / li | 20px / 1.65 |
+| li margin | 12px |
+| Blockquote/callout p | 19px / 1.6 |
+| Worksheet card p, ws-checks li | 17px / 1.55 |
+| ws-route p | 16.5px |
+
+The blog keeps its thoughtbot-anchored 22.4px scale - the course override is
+scoped with a `.section-course` prefix.
+
+# The specificity trap
+
+`single-post.css` sets body type via
+`.blog article.single-content .fl-rich-text p` (specificity 0,3,2). Any
+course override weaker than that silently loses - a plain
+`.section-course .blog p` (0,2,1) does nothing. Mirror the FULL chain:
+`.section-course .blog article.single-content .fl-rich-text p`.
+
+Also: broad element rules (e.g. the 20px li rule) can invert component
+hierarchies - the worksheet-card checklist items got bumped to 20px and had
+to be re-pinned to 17px. After any type change, run both visual suites per
+[test gates](/build/test-gates.md).

.okf/design/cover-pipeline.md

@@ -0,0 +1,29 @@
+---
+type: Playbook
+title: Course cover rebuild pipeline
+description: Covers are rebuilt as full HTML per .stitch/design.md rendered headless at 2400x1260; chip-composite for single-fact edits.
+resource: .stitch/design.md
+tags: [covers, design, stitch]
+timestamp: 2026-07-13T00:00:00Z
+---
+
+Original covers were Stitch-made and their downloads are auth-gated, so the
+working rebuild path is: author a full HTML page implementing the spec and
+screenshot it headless at 2400x1260.
+
+# Spec essentials (.stitch/design.md)
+
+- Titles: Space Grotesk 800, letter-spacing -0.03em
+- Chip labels: Inter 600, 22px, letter-spacing 0.14em
+- Chip values: Space Grotesk 700
+- Status line: JetBrains Mono
+- Palette: JetVelocity - obsidian dark, Ruby red #cc342d, neon purple #a855f7
+
+# Techniques
+
+- Full rebuild: HTML file in scratchpad → headless Chrome screenshot →
+  `cover.png` (update the `cover_image_alt` frontmatter to match).
+- Single-fact edit (one chip's wording): chip-composite - render just the
+  corrected chip and composite it over the existing PNG with magick.
+- Watch sub-glyph grazes on chips ("%", trailing "E"); fix with explicit
+  `<br/>` splits and `&nbsp;` slack, verify with zoomed re-renders.

.okf/design/house-visual-spec.md

@@ -0,0 +1,32 @@
+---
+type: Design System
+title: House in-post visual spec
+description: Hand-drawn SVG house style - paper tones, 2-2.5px strokes, semantic colors (green = money only), labels inside shapes.
+resource: .stitch/prompts/course-inpost-visual-prompt.md
+tags: [svg, design, course]
+timestamp: 2026-07-13T00:00:00Z
+---
+
+# The spec in one table
+
+| Element | Rule |
+|---|---|
+| Backgrounds | Paper tones: #fff5f5 (red-tint), #faf7f2 (cream), #f0f9f0 (green), #fbe9ff (purple) |
+| Strokes | 2-2.5px, hand-drawn feel |
+| Red | Action / anti-pattern |
+| Purple | Alternate path |
+| Green | ONLY money/success outcomes |
+| Amber | Warnings |
+| Typography | Caveat / Patrick Hand / Comic Sans MS cursive stack |
+| Labels | INSIDE shapes (Sweller split-attention rule); never bare diamonds |
+| Dashes | "-" only, including inside artwork |
+
+# Exemplars
+
+`invoice-loop.svg` (ai-token-bill) and `network-buckets.svg` are the
+canonical compact hand-drawn exemplars - numbered step cards, outcome cards,
+dashed loop, header + italic subtitle, ~960x470.
+
+Diagrams taller than 2x viewport read as a wall, not a hook - replace with a
+compact SVG or table. Verify every new visual with the
+[render-verification playbook](/workflows/render-verification.md).

.okf/design/index.md

@@ -0,0 +1,6 @@
+# Design
+
+* [Mermaid theme](mermaid-theme.md) - the Caveat webfont root-cause fix and the theming gotchas
+* [House visual spec](house-visual-spec.md) - paper tones, semantic colors, hand-drawn identity
+* [Cover pipeline](cover-pipeline.md) - rebuilding course covers from the design spec
+* [Course typography](course-typography.md) - the course-scoped reading scale and the specificity trap