Add mermaid diagrams to all lectures, PDF build pipeline, and README screenshots

- Add 1-2 mermaid diagrams per lecture (EN + ZH, 24 files total) illustrating
  core concepts: five-layer failure model, harness subsystems, knowledge visibility,
  instruction architecture, session continuity, initialization lifecycle, WIP=1
  workflow, feature state machine, termination checks, test pyramid, observability
  layers, and clean state dimensions
- Add PDF build pipeline: scripts/build-course-pdfs.ts and npm scripts
- Add README screenshot capture script and workflow
- Add GitHub Actions workflow for automated PDF releases
- Update README/README-CN with screenshots and PDF documentation

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: sanbuphy

.github/workflows/release-course-pdfs.yml

@@ -0,0 +1,71 @@
+name: Build course PDFs and publish release assets
+
+on:
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: Release tag to create or update
+        required: true
+        type: string
+      release_name:
+        description: Release title
+        required: true
+        type: string
+      prerelease:
+        description: Mark release as prerelease
+        required: false
+        default: false
+        type: boolean
+  release:
+    types:
+      - published
+
+permissions:
+  contents: write
+
+jobs:
+  build-pdfs:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+
+      - name: Setup Node
+        uses: actions/setup-node@v6
+        with:
+          node-version: 24
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Install Chromium for Playwright
+        run: npx playwright install --with-deps chromium
+
+      - name: Build course PDFs
+        run: npm run pdf:build
+
+      - name: Upload PDF artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: course-pdfs
+          path: artifacts/pdfs
+
+      - name: Publish PDFs to existing release
+        if: github.event_name == 'release'
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: ${{ github.event.release.tag_name }}
+          files: artifacts/pdfs/*.pdf
+
+      - name: Create or update release with PDFs
+        if: github.event_name == 'workflow_dispatch'
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: ${{ inputs.tag }}
+          name: ${{ inputs.release_name }}
+          prerelease: ${{ inputs.prerelease }}
+          generate_release_notes: true
+          files: artifacts/pdfs/*.pdf

.gitignore

@@ -26,3 +26,4 @@ pnpm-debug.log*
 docs/.vitepress/cache/
 docs/.vitepress/dist/
 *.tsbuildinfo
+artifacts/

README-CN.md

@@ -13,6 +13,35 @@ Learn Harness Engineering 是一门专注于 AI 编程智能体工程化落地
 
 ---
 
+## 页面截图
+
+### 中文
+
+<p>
+  <img src="./docs/public/screenshots/readme/zh-home.png" alt="中文首页预览" width="32%" />
+  <img src="./docs/public/screenshots/readme/zh-lecture-01.png" alt="中文讲义预览" width="32%" />
+  <img src="./docs/public/screenshots/readme/zh-resources.png" alt="中文资料库预览" width="32%" />
+</p>
+
+### English
+
+<p>
+  <img src="./docs/public/screenshots/readme/en-home.png" alt="English homepage preview" width="32%" />
+  <img src="./docs/public/screenshots/readme/en-lecture-01.png" alt="English lecture preview" width="32%" />
+  <img src="./docs/public/screenshots/readme/en-resources.png" alt="English resources preview" width="32%" />
+</p>
+
+## PDF 构建与 Release 流水线
+
+仓库里现在已经补上了课程 PDF 的构建链路。
+
+- 本地执行 `npm run pdf:build`，会生成中英文两份课程 PDF。
+- 输出目录是 `artifacts/pdfs/`。
+- 如果需要刷新 README 里的截图，执行 `npm run screenshots:readme`。
+- GitHub Actions 工作流 [`release-course-pdfs.yml`](./.github/workflows/release-course-pdfs.yml) 可以自动构建 PDF，并把产物上传到 GitHub Release。
+
+---
+
 ## 模型很强，但 Harness 让它靠谱
 
 有一个很多人交过学费才明白的事实：**世界上最强的模型，如果没有一个合适的工作环境，依然会在真实工程任务中翻车。**

README.md

@@ -13,6 +13,35 @@ Learn Harness Engineering is a course dedicated to the engineering of AI coding
 
 ---
 
+## Visual Preview
+
+### English
+
+<p>
+  <img src="./docs/public/screenshots/readme/en-home.png" alt="English homepage preview" width="32%" />
+  <img src="./docs/public/screenshots/readme/en-lecture-01.png" alt="English lecture preview" width="32%" />
+  <img src="./docs/public/screenshots/readme/en-resources.png" alt="English resources preview" width="32%" />
+</p>
+
+### 中文
+
+<p>
+  <img src="./docs/public/screenshots/readme/zh-home.png" alt="中文首页预览" width="32%" />
+  <img src="./docs/public/screenshots/readme/zh-lecture-01.png" alt="中文讲义预览" width="32%" />
+  <img src="./docs/public/screenshots/readme/zh-resources.png" alt="中文资料库预览" width="32%" />
+</p>
+
+## PDF Coursebooks
+
+The repository now includes a PDF build pipeline for the course content.
+
+- Run `npm run pdf:build` to generate English and Chinese PDFs locally.
+- Output files are written to `artifacts/pdfs/`.
+- Run `npm run screenshots:readme` if you want to refresh the README preview images.
+- GitHub Actions workflow [`release-course-pdfs.yml`](./.github/workflows/release-course-pdfs.yml) can build the PDFs and publish them to GitHub Releases.
+
+---
+
 ## The Model Is Smart, The Harness Makes It Reliable
 
 There's a hard truth most people learn the hard way: **the strongest model in the world will still fail on real engineering tasks if you don't build a proper environment around it.**

docs/en/lectures/lecture-01-why-capable-agents-still-fail/index.md

@@ -20,6 +20,31 @@ This isn't because the model isn't smart enough. It's because the working enviro
 - **Diagnostic Loop**: Execute → observe failure → attribute to a specific harness layer → fix that layer → re-execute. This is the core methodology of harness engineering.
 - **Definition of Done**: A set of machine-verifiable conditions — tests pass, lint is clean, type checks pass. Without an explicit definition of done, the agent will invent its own.
 
+## Failure Model Overview
+
+```mermaid
+graph LR
+    subgraph "Five Failure Layers"
+        direction TB
+        L1["① Task Specification"]
+        L2["② Context Provision"]
+        L3["③ Execution Environment"]
+        L4["④ Verification Feedback"]
+        L5["⑤ State Management"]
+    end
+
+    Agent -->|"encounters"| L1
+    L1 --> L2 --> L3 --> L4 --> L5
+    L5 -->|"signals defect"| Fix["Fix layer → Re-run"]
+    Fix -->|"diagnostic loop"| Agent
+```
+
+```mermaid
+graph LR
+    Bare["Bare Run<br/>20 min / $9<br/>Core features broken"] -->|"Add harness"| Full["Full Harness<br/>6 hr / $200<br/>Playable app"]
+    Bare -.->|"Same model"| Full
+```
+
 ## Why This Happens
 
 Let's start with data. As of late 2025, the strongest coding agents on SWE-bench Verified achieve roughly 50-60%. And that's on carefully selected tasks with clear issue descriptions and existing test cases. Move to a real daily development scenario — vague requirements, no existing tests, implicit business rules scattered everywhere — and that number only goes down.

docs/en/lectures/lecture-02-what-a-harness-actually-is/index.md

@@ -20,6 +20,21 @@ This lecture gives you a precise, actionable definition. Not an academic abstrac
 - **Feedback Latency**: The time between an agent's action and the feedback it receives. Compilation errors are second-level feedback, test suites are minute-level, "bug in production" is day-level. Faster feedback means faster correction.
 - **Isometric Model Control**: Keep the model fixed, systematically vary harness subsystems, measure each one's marginal contribution. This is the correct way to quantify a harness's value.
 
+## The Five-Tuple Harness Model
+
+```mermaid
+graph TB
+    Agent["AI Agent"] --> I["📋 Instructions<br/><i>AGENTS.md, CLAUDE.md</i>"]
+    Agent --> T["🔧 Tools<br/><i>Shell, file ops, tests</i>"]
+    Agent --> E["🖥️ Environment<br/><i>Dependencies, runtime</i>"]
+    Agent --> S["💾 State<br/><i>Progress files, git</i>"]
+    Agent --> F["✅ Feedback<br/><i>Test results, lint, build</i>"]
+
+    I ~~~ T ~~~ E ~~~ S ~~~ F
+
+    F -->|"highest ROI"| Star["⭐ Start here"]
+```
+
 ## Why This Happens
 
 Here's an analogy. Imagine you're a newly hired engineer dropped into a project with zero documentation. No README, no comments in the code, nobody tells you how to run tests, CI config is buried somewhere. Can you write good code? Maybe, but you'll spend enormous time on "figuring out what this project is about" rather than "solving the problem."

docs/en/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md

@@ -20,6 +20,39 @@ This lecture explains why you must put everything an agent needs to know into th
 - **Knowledge Decay Rate**: The proportion of knowledge entries that become stale per unit of time. Documentation going out of sync with code is the biggest enemy.
 - **ACID for Agent State**: Applying database transaction principles (Atomicity, Consistency, Isolation, Durability) to agent state management.
 
+## Knowledge Visibility
+
+```mermaid
+graph LR
+    subgraph "Visible to Agent"
+        Repo["Repository Files<br/>AGENTS.md, code, tests"]
+    end
+    subgraph "Invisible to Agent"
+        Slack["Slack History"]
+        Confluence["Confluence Docs"]
+        Heads["Senior Engineers' Heads"]
+        Jira["Jira Tickets"]
+    end
+
+    Repo -->|"accessible"| Agent["🤖 Agent"]
+    Slack -.->|"inaccessible"| Agent
+    Confluence -.->|"inaccessible"| Agent
+    Heads -.->|"inaccessible"| Agent
+    Jira -.->|"inaccessible"| Agent
+```
+
+```mermaid
+graph TB
+    subgraph "Cold-Start Test"
+        Q1["What is this system?"]
+        Q2["How is it organized?"]
+        Q3["How do I run it?"]
+        Q4["How do I verify it?"]
+        Q5["Where are we now?"]
+    end
+    Q1 & Q2 & Q3 & Q4 & Q5 -->|"all must be<br/>answerable from repo"| Pass["✅ Harness Ready"]
+```
+
 ## Why This Happens
 
 Think about what an agent's inputs actually are: system prompts and task descriptions, file contents from the repository, and tool execution output. That's it. Your Slack history, Jira tickets, Confluence pages, and that architecture decision you discussed with a colleague over coffee on Friday afternoon — the agent can't see any of it.

docs/en/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md

@@ -20,6 +20,31 @@ This is the "giant instruction file" trap. This lecture explains why "more infor
 - **Progressive Disclosure**: Give overview information first, detailed information when needed. Good harness design is like good UI design — don't dump all options on the user at once.
 - **Priority Ambiguity**: When all instructions appear in the same format and location, the agent can't distinguish non-negotiable hard constraints from suggestive soft guidelines.
 
+## Instruction Architecture
+
+```mermaid
+graph TB
+    subgraph "Three-Layer Structure"
+        L1["<b>Layer 1: Routing File</b><br/>AGENTS.md (50–200 lines)<br/>Overview + hard constraints + links"]
+        L2a["<b>Layer 2a</b><br/>api-patterns.md"]
+        L2b["<b>Layer 2b</b><br/>database-rules.md"]
+        L2c["<b>Layer 2c</b><br/>testing-standards.md"]
+        L3["<b>Layer 3: Inline</b><br/>Type defs, interface comments"]
+    end
+
+    L1 -->|"link"| L2a
+    L1 -->|"link"| L2b
+    L1 -->|"link"| L2c
+    L2a & L2b & L2c -->|"reference"| L3
+
+    style L1 fill:#D95C41,color:#fff
+```
+
+```mermaid
+graph LR
+    Top["Top of file<br/>✅ High recall"] --- Mid["Middle of file<br/>❌ Lost in the middle"] --- Bot["Bottom of file<br/>✅ High recall"]
+```
+
 ## Why This Happens
 
 The most common vicious cycle goes like this: the agent makes a mistake → you say "add a rule to prevent this" → add it to AGENTS.md → it works temporarily → agent makes a different mistake → add another rule → repeat → file bloats out of control.

docs/en/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md

@@ -20,6 +20,30 @@ This is one of the most painful problems with AI coding agents: cross-session co
 - **Compaction vs Reset**: Compaction summarizes context within the same session (keeps "what," may lose "why"); reset opens a new session rebuilding from persisted state (clean but depends on artifact completeness).
 - **Context Anxiety**: A phenomenon observed by Anthropic — agents exhibit premature convergence behavior when approaching perceived context limits, ending tasks early to avoid information loss. It's an irrational resource anxiety.
 
+## Session Continuity Flow
+
+```mermaid
+graph LR
+    subgraph "Session N"
+        Work1["Work on task"] --> Update1["Update PROGRESS.md<br/>Update DECISIONS.md"]
+        Update1 --> Commit1["Git commit checkpoint"]
+    end
+    subgraph "Session N+1"
+        Read1["Read PROGRESS.md<br/>Read DECISIONS.md"] --> Resume["Resume from<br/>Next Steps"]
+        Resume --> Work2["Continue work"]
+    end
+
+    Commit1 -->|"handoff"| Read1
+```
+
+```mermaid
+graph TB
+    subgraph "Information Loss"
+        Full["Full Context<br/>What + Why + How"] -->|"compaction"| Compact["Compacted<br/>What ✓ · Why ✗"]
+        Full -->|"new session"| Reset["Reset<br/>Rebuild from artifacts"]
+    end
+```
+
 ## Why This Happens
 
 Context windows are finite. This isn't solvable by model upgrades — even if window sizes grow to 1M tokens, complex tasks will still exhaust them. Because agents aren't just generating code; they're understanding codebases, tracking their own decision history, processing tool output, and maintaining conversation context. All this information grows faster than window expansion.

docs/en/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md

@@ -20,6 +20,29 @@ The better approach: before letting the agent start working, use a separate phas
 - **Time to First Verification**: The time from project start until the first feature point passes verification. This is the core metric for measuring initialization efficiency.
 - **Downstream Usability**: The best measure of initialization quality — the proportion of subsequent sessions that can successfully execute tasks without relying on implicit knowledge.
 
+## Initialization Lifecycle
+
+```mermaid
+graph LR
+    subgraph "Initialization Phase"
+        I1["Runnable environment<br/><i>deps installed</i>"] --> I2["Test framework<br/><i>example test passes</i>"]
+        I2 --> I3["Bootstrap contract<br/><i>start/test/verify docs</i>"]
+        I3 --> I4["Task breakdown<br/><i>ordered feature list</i>"]
+        I4 --> I5["Git checkpoint<br/><i>clean commit</i>"]
+    end
+    subgraph "Implementation Phase"
+        I5 --> P1["Session 2: Feature 1"]
+        P1 --> P2["Session 3: Feature 2"]
+        P2 --> P3["Session N: Feature N"]
+    end
+
+    style I1 fill:#D95C41,color:#fff
+    style I2 fill:#D95C41,color:#fff
+    style I3 fill:#D95C41,color:#fff
+    style I4 fill:#D95C41,color:#fff
+    style I5 fill:#D95C41,color:#fff
+```
+
 ## Why This Happens
 
 Initialization and implementation have fundamentally different optimization targets. The implementation phase optimizes for: maximizing the quantity and quality of verified features. The initialization phase optimizes for: maximizing the reliability and efficiency of all subsequent implementation.