feat(course): Tech for Non-Technical Founders 2026 — full 10-module course (32 chapters, 47 covers, site nav)

.claude/agents/semble-search.md

@@ -0,0 +1,28 @@
+---
+name: semble-search
+description: Code search agent for exploring any codebase. Use for finding code by intent, locating implementations, understanding how something works, or discovering related code. Prefer over Grep/Glob/Read for any semantic or exploratory question.
+tools: mcp__semble__search, mcp__semble__find_related, Read
+---
+
+Use the semble MCP tools only — do **not** invoke the `semble` CLI via Bash.
+
+## Tools
+
+- `mcp__semble__search(query, repo, top_k?, mode?)` — natural-language or symbol query against a codebase. `repo` is a local path or `https://` git URL; the index is cached for the session.
+- `mcp__semble__find_related(file_path, line, repo, top_k?)` — nearest-neighbor expansion from a known hit. Pass `file_path` and `line` exactly as returned by a prior `search`.
+- `Read` — open returned files when the chunk lacks enough context.
+
+`mode` defaults to `hybrid` (best for most queries). Use `semantic` for pure intent search; `bm25` for keyword/symbol-heavy queries.
+
+## Workflow
+
+1. Call `mcp__semble__search` with a natural-language description of intent ("save model to disk", "authentication flow") or a symbol name. Always pass `repo` — the absolute path of the project root, or a git URL.
+2. Read full files only when the returned chunk is insufficient.
+3. Optionally call `mcp__semble__find_related` with a promising hit's `file_path` and `line` to discover related implementations and callers.
+4. If `mcp__semble__search` returns no relevant hits after 2-3 query variations, return the empty result rather than substituting another search tool - the agent has only the semble + Read tools by design.
+
+## Rules
+
+- MCP only. The `semble` CLI is off-limits in this agent.
+- Always pass `repo` explicitly; do not rely on a default index.
+- Report results as `file_path:line` so the caller can navigate.

.github/actions/setup-hugo/action.yml

@@ -60,6 +60,17 @@ runs:
           ${{ runner.os }}-hugo-${{ inputs.environment }}-
           ${{ runner.os }}-hugo-
 
+    # Runs after cache restore so stale-cache clearance isn't reverted.
+    - name: Check Node runtime for PostCSS compatibility
+      shell: bash
+      run: |
+        bin/check-node-runtime
+        case $? in
+          0) echo "✓ Node runtime OK — continuing with cache restore" ;;
+          1) echo "⚠️  bun detected — asset cache cleared, PATH adjusted" ;;
+          2) echo "❌ bun detected but real Node.js not found — build may fail" ;;
+        esac
+
     - name: Build Hugo site
       run: PATH="./node_modules/.bin:$PATH" bin/hugo-build
       shell: bash

.github/workflows/_hugo.yml

@@ -73,6 +73,19 @@ jobs:
           restore-keys: |
             ${{ runner.os }}-hugo-assets-
 
+      # Verify node runtime and clear stale cache if bun→node symlink is active.
+      # Runs after cache restore so the stale-cache clearance isn't reverted.
+      # Prevents PostCSS failures when production plugins (PurgeCSS, cssnano)
+      # encounter bun, which can also corrupt the asset cache with broken output.
+      - name: Check Node runtime for PostCSS compatibility
+        run: |
+          bin/check-node-runtime
+          case $? in
+            0) echo "✓ Node runtime OK — continuing with cache restore" ;;
+            1) echo "⚠️  bun detected — asset cache cleared, PATH adjusted" ;;
+            2) echo "❌ bun detected but real Node.js not found — build may fail" ;;
+          esac
+
       - name: Build with Hugo
         run: |
           PATH="./node_modules/.bin:app/bin:$PATH" hugo \

.gitignore

@@ -112,3 +112,4 @@ docs/projects/**/sprint-*-coordinator-report.md
 docs/projects/**/sprint-*-verification-report.md
 docs/projects/**/*-coordinator-report.md
 docs/projects/**/*-verification-report.md
+.grepai/

.skills/course-lesson-review-sam/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: course-lesson-review-sam
+description: Run a Sam-perspective customer-research review on a draft course lesson. Use this skill whenever the user asks to review a lesson from Sam's perspective, check a lesson for ICP fit, validate that a lesson works for non-technical founders, or mentions `/course-lesson-review-sam`. Triggers on phrases like "Sam review", "review this lesson", "check this for Sam", "ICP review", "customer lens review", or any request to validate a course lesson against the target audience.
+---
+
+# Course Lesson Sam-Review
+
+Run a Sam-perspective customer-research review on a draft lesson. Channels Sam beat-by-beat with verbatim reactions, friction points, glossing gaps.
+
+## Pre-loaded context
+
+### Project docs (what we're reviewing against)
+
+1. **PRD** — `.agent/prd/PRD.md` — formal product requirements: 5-module architecture, 15 quality gates, artifact chain, Sam ICP. Every lesson must advance Sam toward the course promise.
+2. **5-Sam Validation Pilot** — Planned but NOT YET EXECUTED. The current simulation learnings (40.11) are imputed, not field-validated. Real Sams may stall where the simulation didn't predict. Be aware that all simulation findings are provisional — do not treat them as proven.
+
+### Canonical spec (what the lesson SHOULD match)
+
+1. **30.03 §2 — 8-part template** — `docs/projects/2605-tech-for-non-technical-founders/30-39-architecture-design/30.03-course-format-requirements-for-creators.md` §2 (the non-negotiable 8-part template: Hook → Outcome → Concept → Visual → Do-Now → Error → Reflection → Bridge)
+2. **30.03 §1 — design principles** — §1.1-1.6 (single outcome, time cap, microlearning structure, self-paced, mobile-friendly, word count bands)
+3. **30.03 §5 — content spec** — §5.1-5.3 (course-level elements, per-lesson elements, micro-copy constraints, NN/g F-pattern rules)
+4. **30.03 §4 — engagement** — §4.1-4.8 (immediate win, attention cycle, B=MAP, Zeigarnik, progress visibility, language, navigation)
+
+### Sam profile (who we're reviewing FOR)
+
+5. **Sam profile (course ICP)** — `docs/projects/2605-tech-for-non-technical-founders/40-49-review/40.06-sam-customer-journey-report-2026-06.md` (first-time non-technical founder, no PM background, no burn history, 2-4 hr/week, ~$20K savings, reads on phone, intimidation + first-timer enthusiasm)
+6. **Sam simulation learnings** — `docs/projects/2605-tech-for-non-technical-founders/40-49-review/40.11-sam-simulation-pilot-lessons-2026-06.md` (5 themes from beat-by-beat simulation: "I don't have to write code" trust gate, catalogue-my-mistake pattern, measurable success criterion, UI-cue gap, decision-aid-in-one-sentence)
+7. **Voice guide** — `docs/90-99-content-strategy/strategy-analysis/90.11-voice-guide.md` (banned words, anti-AI structural patterns, the "who"/"show"/"coffee" tests)
+
+### Canonical v2 examples (what a passing lesson looks like)
+
+8. **Pilot Lesson 1.2a** — `content/course/tech-for-non-technical-founders-2026/smoke-test-build-page/index.md` (~870w, agnostic-tool framing, Mixo as worked example)
+9. **Pilot Lesson 1.2b** — `content/course/tech-for-non-technical-founders-2026/smoke-test-wire-tracking/index.md` (~640w, heavy gloss pass)
+
+**DO NOT reference v1 long-form chapters as style examples.** v1 chapters are 2,000-4,500 words and do NOT follow the 8-part template. Only the 2 pilot lessons are canonical v2 examples.
+
+### Sam's profile card (quick reference)
+
+| Attribute | Detail |
+|---|---|
+| **Role** | Founder & CEO, B2B SaaS |
+| **Age** | 38 |
+| **Tech literacy** | Can read a Stripe invoice, cannot read a GitHub commit |
+| **Burn history** | NONE — this is Sam's FIRST venture. No prior devshop experience. |
+| **PM background** | NONE — never worked in product management |
+| **Current state** | Has runway, has an idea, has NOT validated anything yet |
+| **Emotional load** | Intimidation ("everyone seems to know things I don't"), first-timer enthusiasm ("this course will finally make it clear"), fear ("what if I pick wrong?") |
+| **Reading mode** | Skim-first, time-poor. Reads H2 headings on phone during commute before committing. Wants specific numbers, not vague promises. |
+| **Trust trigger** | "This person knows I'm coming in cold and doesn't judge me for it." |
+| **Trust killer** | Jargon without explanation. Too many choices. Being told to "figure it out." |
+
+## The 6 tests
+
+Run all 6 tests on the draft lesson. For each test, produce:
+- A verdict (PASS / PARTIAL / FAIL)
+- The specific line or section that triggered the verdict
+- A Sam-character verbatim reaction (how Sam would actually react in his head)
+- A priority fix (HIGH / MEDIUM / LOW)
+
+### Test 1: 3-second hook test
+
+Can Sam tell what this lesson does and why he should care within the first 2 sentences?
+
+- Read the hook (first 1-3 sentences after the course-frame callout)
+- If the hook is a narrative vignette longer than 3 sentences, it FAILS
+- If the hook uses "we" language without naming Sam's pain, it FAILS
+- If Sam can't picture what tangible thing he'll walk away with after reading the hook, it FAILS
+
+Sam's likely reaction to a bad hook: opens lesson, scrolls past 4 paragraphs, thinks "I don't know what this is for," closes tab.
+
+### Test 2: Glossing audit
+
+Every term Sam doesn't know — decoded at first mention?
+
+Scan the entire lesson body. Flag every technical term and check:
+- Is it glossed at first mention with a one-sentence plain-English definition?
+- Is the gloss in parentheses right next to the term, not in a footnote or sidebar?
+- Filter for: MVP, PMF, ICP, CTA, DPA, ARR, MRR, SOC2, HIPAA, API, RLS, JWT, OAuth, SDK, CI/CD, CMS, DNS, SSL, JSON, CSV, HTML, CSS, JS, SQL, CRUD, REST, GraphQL, webhook, endpoint, deploy, staging, production, migration, ORM, framework, runtime, SDK, hero section, incognito mode, headless CMS, CDN, reverse proxy
+
+For each unglossed term, Sam's reaction: "I keep nodding but I don't know what half of these mean."
+
+### Test 3: Progressive disclosure
+
+First 30% orients Sam; thresholds/metrics arrive only when Sam acts on them.
+
+- Does the first 30% of the lesson body (after the course-frame callout, before the "Do this now") ONLY orient Sam?
+- Do thresholds, decision numbers, scoring rubrics appear only in or after the action section?
+- If a scoring table or decision threshold appears in the first 30%, it FAILS
+
+Sam's reaction to bad progressive disclosure: "There's a 40% threshold and a 7/10 score and a $300 budget and I haven't even been told what I'm building yet."
+
+### Test 4: Tool-paralysis check
+
+Single golden path or named alternatives?
+
+- Does the lesson recommend ONE primary tool with exactly ONE named fallback?
+- If there's a comparison table with 4+ options, it FAILS
+- If Sam has to make a tool choice before the action steps, it FAILS
+
+Sam's reaction to tool paralysis: "Mixo vs Carrd vs Lovable vs Framer — which one? What if I pick wrong? I'll come back to this later." (Never comes back.)
+
+### Test 5: Confidence-to-act check
+
+Sam knows what to do next with no remaining ambiguity?
+
+- After reading the entire lesson, can Sam name the next step without re-reading?
+- Is there an observable success check?
+- Is there a concrete "If blocked" escape valve?
+- If any of these three is missing or vague, it FAILS
+
+Sam's reaction to ambiguity: "OK... I think I'm supposed to build something? With what? How do I know if it worked?"
+
+### Test 6: Off-ICP drift check
+
+Any sentence that reads as written for a developer, PM, or scarred founder?
+
+Scan every sentence and ask:
+- Would a first-time founder who's never hired a devshop understand this?
+- Would someone with zero PM background follow this?
+- Does any sentence assume the reader has been burned before?
+- Does any sentence use "your devshop" or "your last agency" or "the team you fired"?
+
+For each sentence that fails, Sam's reaction: "This is written for someone who's been through this before. I haven't."
+
+## Output format
+
+Always produce this exact output structure:
+
+```
+## Sam Review — [Lesson Slug]
+
+### Overall: [PASS / PARTIAL / FAIL] ([N]/6 tests passed)
+
+### Beat-by-beat
+
+| # | Test | Verdict | What triggered it | Sam's reaction | Fix priority |
+|---|---|---|---|---|---|
+| 1 | 3-second hook | PASS/FAIL | "exact quote from lesson" | "Sam's verbatim reaction" | HIGH/MED/LOW |
+| ... | ... | ... | ... | ... | ... |
+
+### Priority fix list
+
+1. **[HIGH/MED/LOW]** [specific fix instruction]
+2. ...
+
+### Verbatim Sam quotes
+
+- "[what Sam would actually say to a friend about this lesson if it were a draft]"
+```
+
+## What NOT to do
+
+- Do NOT critique the lesson as a technical reviewer — ONLY channel Sam
+- Do NOT suggest structural rewrites that serve SEO or "best practices" — Sam doesn't care about those
+- Do NOT use "the learner would benefit from" language — say "Sam wouldn't understand this"
+- Do NOT grade on word count alone — a 700-word lesson that passes all 6 tests is fine for Sam