pr-docent 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 꼬리찾은도마뱀
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,176 @@
-# Temporary Holding Version
+# PR Docent
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+GitHub 풀 리퀘스트의 **Files changed** 화면 위에서 동작하는 리뷰 투어 Chrome 확장입니다. 수천 줄짜리 PR을 챕터로 나누고, **읽을 순서대로** 해당 파일과 줄로 이동하며 하이라이트하고, 설명을 보여 주거나 음성으로 읽어 줍니다.
+
+> 상태: 1단계 프로토타입. 투어는 미리 만든 JSON을 불러와 재생합니다. 투어 자동 생성(2단계)은 아직 없습니다.
+
+## 기능
+
+- 챕터 목록, 진행률, 이전·재생·다음, **집중 단계만 골라 건너뛰기**, 단축키
+- 단계마다 파일과 줄 범위로 스크롤하고 하이라이트. 나머지 코드는 흐리게 처리합니다.
+- 음성이 읽는 문장에 맞춰 해당 줄을 진하게 가리킵니다(`note`를 문장별 배열로 쓴 경우).
+- 중요도 표시: **집중**(꼼꼼히 볼 곳), **훑기**, **생략 가능**
+- 브라우저 내장 음성 합성으로 설명 읽기(속도 조절). 네트워크 요청이나 비용이 없습니다.
+- **투어가 다루지 않은 파일** 목록: 투어만 믿고 놓치는 파일이 없게 합니다.
+- 접힌 대용량 diff("Load Diff")는 자동으로 펼칩니다.
+- 패널이 열려 있는 동안 diff가 패널에 가리지 않도록 페이지 폭을 줄입니다.
+- PR마다 마지막 위치를 기억합니다.
+- 화면 언어는 영어(기본)와 한국어를 지원합니다. 툴바의 PR Docent 아이콘을 눌러 자동(브라우저 언어), English, 한국어 중에서 고릅니다. 로컬에서 만드는 투어도 고른 언어로 작성되고, 음성은 투어 문장의 언어에 맞춰 읽습니다.
+
+## 단축키
+
+GitHub의 diff 화면은 화살표 키와 한 글자 단축키를 이미 쓰므로, PR Docent는 Alt(Mac은 Option) 조합만 씁니다. 코멘트를 입력하는 중에는 동작하지 않습니다.
+
+| 단축키 | 동작 |
+|---|---|
+| `Alt` + `→` / `←` | 다음 / 이전 단계 |
+| `Alt` + `↓` / `↑` | 다음 / 이전 **집중** 단계로 건너뛰기 |
+| `Alt` + `P` | 재생 / 일시정지 |
+
+## 설치 (개발용)
+
+1. `chrome://extensions`에서 **개발자 모드**를 켭니다.
+2. **압축해제된 확장 프로그램을 로드합니다**를 누르고 이 폴더를 선택합니다.
+3. PR의 Files changed 탭을 열면 오른쪽 아래에 **▶ PR Docent** 버튼이 나타납니다.
+
+## 투어 자동 생성 (GitHub Actions)
+
+PR이 열리거나 커밋이 추가될 때마다 Claude Code가 diff를 읽고 투어를 만들어 PR 코멘트로 올립니다. 확장은 Files changed 탭에서 그 코멘트를 찾아 투어를 자동으로 불러옵니다. 비공개 저장소에서도 로그인한 사용자 권한으로 읽으므로 별도 토큰이 필요 없습니다.
+
+1. Claude 구독 계정으로 OAuth 토큰을 만듭니다. 생성에는 그 구독의 사용량이 쓰입니다.
+   ```bash
+   claude setup-token
+   ```
+2. 투어를 만들 저장소에 secret으로 등록합니다.
+   ```bash
+   gh secret set CLAUDE_CODE_OAUTH_TOKEN -R <owner>/<repo>
+   ```
+3. 그 저장소에 `.github/workflows/pr-docent.yml`을 추가합니다.
+   ```yaml
+   name: PR Docent tour
+   on:
+     pull_request:
+       types: [opened, synchronize, reopened, ready_for_review]
+   concurrency:
+     group: pr-docent-tour-${{ github.event.pull_request.number }}
+     cancel-in-progress: true
+   jobs:
+     tour:
+       if: github.event.pull_request.draft == false && github.event.pull_request.head.repo.full_name == github.repository
+       uses: thomas783/pr-docent/.github/workflows/generate-tour.yml@main
+       secrets:
+         CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+       permissions:
+         contents: read
+         pull-requests: write
+   ```
+
+동작 방식
+- Claude는 투어 파일 하나만 쓸 수 있고, 저장소의 다른 파일은 읽기만 합니다.
+- `scripts/check-tour.mjs`가 투어를 검사합니다. 형식, 모든 줄 번호가 실제 diff 화면에 보이는지, 문장별 줄이 단계 범위 안에 있는지, 바뀐 파일을 모두 다루거나 건너뛴 이유를 적었는지 확인합니다. Claude는 검사를 통과할 때까지 고치고, 통과하지 못하면 코멘트를 올리지 않습니다.
+- 코멘트는 PR마다 하나이며, 새 커밋이 올라오면 같은 코멘트를 갱신합니다.
+- 입력값 `model`(기본 `claude-opus-5-5`)과 `language`(기본 `한국어`)로 모델과 언어를 바꿀 수 있습니다.
+- 포크에서 온 PR에는 secret이 전달되지 않으므로 실행하지 않습니다.
+
+## 투어 로컬 생성 (본인 Claude Code)
+
+저장소 설정 없이, 패널의 **로컬 Claude Code로 투어 생성** 버튼으로 지금 보고 있는 PR의 투어를 만듭니다. 본인 컴퓨터의 Claude Code와 구독을 쓰므로 API 키나 추가 비용이 없고, 설정 권한이 없는 저장소의 PR에서도 됩니다.
+
+준비 (컴퓨터마다 한 번, macOS와 Linux)
+1. [Claude Code](https://claude.com/claude-code)를 설치하고 로그인합니다.
+2. 로컬 도우미를 Chrome에 등록합니다. Node.js 18 이상이 필요합니다.
+   ```bash
+   npx pr-docent install
+   ```
+   `~/.pr-docent/`에 도우미 파일과 실행 스크립트를 복사하고, Chrome의 `NativeMessagingHosts` 폴더에 `dev.prdocent.host.json`을 만듭니다. 이 확장(ID `hleefogoiedjahnmjgmmgonckaeicppc`)만 연결할 수 있으며, 다른 ID는 `--extension-id <ID>`로 추가합니다. 이 저장소에서는 `npm run install-host`도 같습니다.
+3. `chrome://extensions`에서 확장을 새로고침합니다.
+
+동작 방식
+- 확장이 로그인 세션으로 PR의 diff와 바뀐 파일을 가져와 로컬 도우미(`host/pr-docent-host.mjs`)에 넘깁니다.
+- 도우미가 임시 폴더에서 `claude -p`를 실행합니다. GitHub Actions와 같은 프롬프트와 검사기를 쓰고, Claude는 투어 파일 하나만 쓸 수 있습니다.
+- 검사를 통과한 투어를 이 PR에 저장하고 바로 재생합니다. 생성에는 보통 2~3분이 걸립니다.
+- 제거: `npx pr-docent uninstall`
+
+## 투어 생성 규칙 바꾸기 (`.github/pr-docent.md`)
+
+Actions 생성과 로컬 생성 모두 기본적으로 짧은 투어를 만듭니다. 단계 수는 바뀐 줄 25줄당 1개에 3을 더한 값까지(최대 20)이고, 단계마다 문장 3개, 문장마다 80자까지입니다. 주석만 바뀐 곳, 임포트, 문서처럼 사소한 변경은 단계 대신 "건너뛴 파일"에 넣습니다. 검사기가 이 기준을 확인하고, 넘으면 Claude가 다시 줄입니다.
+
+저장소에 `.github/pr-docent.md`를 두면 그 저장소의 규칙을 더할 수 있습니다. 앞부분 `---` 블록은 숫자 기준을 바꾸고, 본문은 생성 지시문 뒤에 붙어 기본 규칙보다 우선합니다.
+
+```markdown
+---
+maxSteps: 6            # 단계 수 상한 (기본: 3 + 바뀐 줄 25줄당 1, 최대 20)
+sentencesPerStep: 2    # 단계당 문장 수 (기본 3)
+sentenceChars: 100     # 문장 길이 (기본 80자)
+pointChars: 120        # 리뷰 포인트 길이 (기본 120자)
+summaryChars: 200      # PR 요약 길이 (기본 200자)
+chapterSummaryChars: 60
+---
+- 도메인 용어는 원장, 안분, 파생 라인으로 씁니다.
+- Flyway 마이그레이션 파일은 항상 집중 단계로 다룹니다.
+```
+
+PR의 head 커밋에 있는 파일을 읽으므로, 규칙을 바꾸는 PR에서는 바뀐 규칙으로 생성됩니다.
+
+## 투어 불러오기
+
+- PR 코멘트에 자동 생성된 투어가 있으면 그 투어를 불러옵니다. 직접 불러온 투어가 있으면 그쪽이 우선합니다.
+- `tours/<owner>--<repo>--<number>.json` 파일이 있으면 해당 PR에서 자동으로 불러옵니다.
+- 예제: [`tours/thomas783--pr-docent--1.json`](tours/thomas783--pr-docent--1.json) — 이 레포의 [PR #1](https://github.com/thomas783/pr-docent/pull/1/changes)(단축키와 집중 단계 건너뛰기)을 리뷰하는 투어입니다. 확장을 설치한 뒤 이 PR을 열면, PR Docent로 PR Docent 자신의 변경을 리뷰해 볼 수 있습니다.
+- 직접 만든 투어는 같은 폴더에 두면 자동으로 불러오고, 커밋되지 않습니다(`.gitignore` 참고). 공개 예제만 커밋합니다.
+- 그 밖의 PR은 패널의 **투어 JSON 불러오기**로 파일을 선택합니다. 불러온 투어는 그 PR에 저장됩니다.
+
+## 투어 형식 (version 1)
+
+```json
+{
+  "version": 1,
+  "pr": { "owner": "your-org", "repo": "your-repo", "number": 42 },
+  "title": "투어 제목",
+  "summary": "PR 요약",
+  "chapters": [
+    {
+      "title": "1. 도메인 모델",
+      "summary": "챕터 설명",
+      "steps": [
+        { "file": "src/Foo.kt", "lines": [10, 24], "side": "right", "level": "focus", "note": "이 단계에서 볼 것" }
+      ]
+    }
+  ],
+  "skipped": [{ "file": "gradlew", "reason": "생성된 파일" }]
+}
+```
+
+| 필드 | 설명 |
+|---|---|
+| `lines` | `[시작, 끝]` 줄 번호. 생략하면 파일 전체로 이동합니다. |
+| `side` | `right`(변경 후, 기본값) 또는 `left`(변경 전, 삭제된 줄) |
+| `level` | `focus`, `skim`(기본값), `skip` |
+| `note` | 설명 문자열. 또는 `[{ "text": "...", "lines": [시작, 끝] }, ...]` 배열로 쓰면 음성이 각 문장을 읽는 동안 그 줄을 진하게 가리킵니다. |
+| `point` | 리뷰어가 확인할 점(선택). 패널에 강조 상자로 보이고, 설명 다음에 따로 읽어 줍니다. |
+| `skipped` | 일부러 건너뛴 파일과 이유. "다루지 않은 파일" 목록에서 빠집니다. |
+
+## GitHub 화면 연동 방식
+
+GitHub의 2026년 Files changed 화면 기준입니다. 화면 구조가 바뀌면 `src/github.js`만 고치면 됩니다.
+
+- 파일 요소 ID: `diff-` + 파일 경로의 SHA-256
+- 줄 셀: `data-line-anchor="diff-<해시>R<줄>"`(삭제 쪽은 `L`)
+- URL 해시를 바꿔도 스크롤되지 않으므로 직접 스크롤합니다.
+- 하이라이트는 요소에 클래스를 붙이지 않고 줄 앵커를 가리키는 CSS 규칙으로 적용합니다. GitHub(React)가 요소를 다시 그려도 유지됩니다.
+- 화면 밖 파일과 접힌 파일은 그 파일로 스크롤한 뒤 내용이 그려질 때까지 기다리고, 필요하면 "Load Diff"를 누릅니다.
+
+## 개발
+
+- 빌드 단계가 없습니다. 콘텐츠 스크립트(`src/loader.js`)가 ES 모듈(`src/main.js`)을 불러옵니다.
+- 테스트: `npm test` (Node 내장 테스트 러너). 투어 검증, diff 대조, 재생 상태, 단축키, PR 주소 해석, GitHub 파일 ID 해시, 줄 선택자를 다룹니다.
+- npm 게시: `package.json`의 버전을 올려 머지한 뒤 `git tag npm-v<버전> && git push origin npm-v<버전>`. GitHub Actions(`publish.yml`)가 trusted publishing으로 게시하므로 npm 토큰이나 2FA 입력이 필요 없습니다.
+- 투어 검사: `node scripts/check-tour.mjs <tour.json> <pr.diff> [owner/repo#number]` (`gh pr diff <number> > pr.diff`)
+
+## 라이선스
+
+MIT
+
+## 다음 단계
+
+1. **다듬기:** 구조 변화 다이어그램, 테스트 커버리지 표시, 비공개 레포 처리

package/bin/pr-docent.mjs

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+// PR Docent's local generator setup.
+//
+//   npx pr-docent install [--extension-id <id>]...   register with Chrome (once per computer)
+//   npx pr-docent uninstall                           remove the registration and files
+//
+// Install copies the generator into ~/.pr-docent/app, so it keeps working after npx clears its
+// cache, and writes a wrapper that pins PATH, Node and Claude Code: Chrome starts native hosts
+// with a bare environment.
+
+import { execFileSync } from "node:child_process";
+import { chmodSync, cpSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { homedir, platform } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { EXTENSION_IDS, HOST_NAME } from "../host/native.mjs";
+
+const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+// What the host needs at run time; everything else in the package is for the extension or tests.
+const RUNTIME_FILES = ["host/native.mjs", "host/pr-docent-host.mjs", "src/diff.js", "src/guidelines.js", "src/tour.js", "scripts/check-tour.mjs", "scripts/tour-prompt.md"];
+const HOSTS_DIRS = {
+  darwin: join(homedir(), "Library", "Application Support", "Google", "Chrome", "NativeMessagingHosts"),
+  linux: join(homedir(), ".config", "google-chrome", "NativeMessagingHosts"),
+};
+const CONFIG_DIR = join(homedir(), ".pr-docent");
+
+const [command = "help", ...args] = process.argv.slice(2);
+const hostsDir = HOSTS_DIRS[platform()];
+const hostManifest = hostsDir && join(hostsDir, `${HOST_NAME}.json`);
+
+if (command === "install") install(args);
+else if (command === "uninstall") uninstall();
+else {
+  console.log("usage: pr-docent install [--extension-id <id>]... | pr-docent uninstall");
+  process.exit(command === "help" ? 0 : 2);
+}
+
+function install(args) {
+  if (!hostsDir) fail(`Not supported on ${platform()} yet (macOS and Linux only).`);
+  let claude;
+  try {
+    claude = execFileSync("which", ["claude"], { encoding: "utf8" }).trim();
+  } catch {
+    fail("Claude Code (claude) was not found on PATH. Install it and log in first: https://claude.com/claude-code");
+  }
+  const extraIds = args.flatMap((arg, i) => (arg === "--extension-id" && args[i + 1] ? [args[i + 1]] : []));
+  const extensionIds = [...new Set([...EXTENSION_IDS, ...extraIds])];
+
+  const app = join(CONFIG_DIR, "app");
+  rmSync(app, { recursive: true, force: true });
+  for (const file of RUNTIME_FILES) {
+    mkdirSync(dirname(join(app, file)), { recursive: true });
+    cpSync(join(PACKAGE_ROOT, file), join(app, file));
+  }
+  writeFileSync(join(app, "package.json"), `${JSON.stringify({ type: "module" })}\n`); // src/*.js are ES modules
+  writeFileSync(join(CONFIG_DIR, "config.json"), `${JSON.stringify({ claude }, null, 2)}\n`);
+
+  const quote = (value) => `'${value.replace(/'/g, `'\\''`)}'`;
+  const wrapper = join(CONFIG_DIR, "host.sh");
+  writeFileSync(wrapper, `#!/bin/sh\nexport PATH=${quote(process.env.PATH)}\nexec ${quote(process.execPath)} ${quote(join(app, "host", "pr-docent-host.mjs"))}\n`);
+  chmodSync(wrapper, 0o755);
+
+  mkdirSync(hostsDir, { recursive: true });
+  const manifest = {
+    name: HOST_NAME,
+    description: "PR Docent local tour generator",
+    path: wrapper,
+    type: "stdio",
+    allowed_origins: extensionIds.map((id) => `chrome-extension://${id}/`),
+  };
+  writeFileSync(hostManifest, `${JSON.stringify(manifest, null, 2)}\n`);
+
+  console.log(`Installed the PR Docent local generator.
+  Chrome host manifest: ${hostManifest}
+  Generator:            ${app}
+  Allowed extensions:   ${extensionIds.join(", ")}
+  Claude Code:          ${claude}
+Reload the extension in chrome://extensions, then click "Create a tour with local Claude Code"
+in the panel ("로컬 Claude Code로 투어 생성" in Korean).`);
+}
+
+function uninstall() {
+  rmSync(CONFIG_DIR, { recursive: true, force: true });
+  if (hostManifest) rmSync(hostManifest, { force: true });
+  console.log(`Removed ${CONFIG_DIR}${hostManifest ? ` and ${hostManifest}` : ""}.`);
+}
+
+function fail(message) {
+  console.error(message);
+  process.exit(1);
+}

package/host/native.mjs

@@ -0,0 +1,35 @@
+// Pieces of the local generator that don't touch the process or the file system.
+
+import { createHash } from "node:crypto";
+
+export const HOST_NAME = "dev.prdocent.host";
+// Extensions the host accepts by default: the unpacked install, whose ID manifest.json's key fixes.
+export const EXTENSION_IDS = ["hleefogoiedjahnmjgmmgonckaeicppc"];
+
+/** Chrome native messaging frames each message as a 32-bit little-endian length plus UTF-8 JSON. */
+export function encodeMessage(value) {
+  const json = Buffer.from(JSON.stringify(value), "utf8");
+  const header = Buffer.alloc(4);
+  header.writeUInt32LE(json.length, 0);
+  return Buffer.concat([header, json]);
+}
+
+/** Returns a stdin "data" handler that calls [onMessage] for every complete frame. */
+export function createDecoder(onMessage) {
+  let pending = Buffer.alloc(0);
+  return (chunk) => {
+    pending = Buffer.concat([pending, chunk]);
+    while (pending.length >= 4) {
+      const length = pending.readUInt32LE(0);
+      if (pending.length < 4 + length) break;
+      onMessage(JSON.parse(pending.subarray(4, 4 + length).toString("utf8")));
+      pending = pending.subarray(4 + length);
+    }
+  };
+}
+
+/** The ID Chrome gives an extension whose manifest carries this public [key]. */
+export function extensionIdFromKey(key) {
+  const hex = createHash("sha256").update(Buffer.from(key, "base64")).digest("hex").slice(0, 32);
+  return [...hex].map((c) => String.fromCharCode(97 + parseInt(c, 16))).join("");
+}

package/host/pr-docent-host.mjs

@@ -0,0 +1,119 @@
+// Local generator: Chrome starts this through native messaging when the panel asks for a tour.
+// It writes the PR's diff and changed files to a temporary folder, runs the user's own Claude
+// Code (their subscription, no API key) with the same prompt and checker as the GitHub Actions
+// workflow, and sends the checked tour back. Installed by `pr-docent install` (bin/pr-docent.mjs).
+
+import { spawn } from "node:child_process";
+import { mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { dirname, join, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import { changedLineCount, checkTour, visibleLines } from "../src/diff.js";
+import { buildPrompt, checkBrevity, parseGuidelines } from "../src/guidelines.js";
+import { parseTour } from "../src/tour.js";
+import { createDecoder, encodeMessage } from "./native.mjs";
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const CONFIG = readConfig();
+const TIMEOUT_MS = 15 * 60 * 1000;
+
+let child = null;
+const send = (message) => process.stdout.write(encodeMessage(message));
+
+process.stdin.on(
+  "data",
+  createDecoder((message) => {
+    if (message.type !== "generate") return;
+    generate(message)
+      .then((tour) => send({ type: "done", tour }))
+      .catch((error) => send({ type: "error", message: error.message }))
+      .finally(() => process.exit(0));
+  }),
+);
+// Chrome closes stdin when the extension disconnects (panel closed, tab gone): stop Claude too.
+process.stdin.on("end", () => {
+  child?.kill();
+  process.exit(0);
+});
+
+async function generate({ pr, title, body, headSha, diff, files, guidelines = "", model, language }) {
+  // Real path: on macOS the temp folder is a symlink, and the write rule must match exactly.
+  const work = realpathSync(mkdtempSync(join(tmpdir(), "pr-docent-")));
+  try {
+    const repo = join(work, "repo");
+    const out = join(work, "out");
+    mkdirSync(repo);
+    mkdirSync(out);
+    for (const [path, content] of Object.entries(files)) {
+      const target = resolve(repo, path);
+      if (!target.startsWith(repo + sep)) continue; // never write outside the folder
+      mkdirSync(dirname(target), { recursive: true });
+      writeFileSync(target, content);
+    }
+    writeFileSync(join(out, "pr.diff"), diff);
+    writeFileSync(join(out, "pr.json"), JSON.stringify({ title, body, headRefOid: headSha }, null, 2));
+    if (guidelines) writeFileSync(join(out, "guidelines.md"), guidelines);
+    const { limits, errors: guidelineErrors } = parseGuidelines(guidelines);
+    if (guidelineErrors.length) throw new Error(`.github/pr-docent.md: ${guidelineErrors.join(" / ")}`);
+    const changedLines = changedLineCount(diff);
+
+    const prRef = `${pr.owner}/${pr.repo}#${pr.number}`;
+    const prompt = buildPrompt(readFileSync(join(ROOT, "scripts", "tour-prompt.md"), "utf8"), {
+      pr: prRef,
+      out,
+      tools: ROOT,
+      language: language || "한국어",
+      changedLines,
+      guidelinesText: guidelines,
+    });
+    await runClaude(prompt, repo, [
+      "--model", model || "claude-opus-5-5",
+      "--permission-mode", "dontAsk",
+      "--allowedTools", `Read,Glob,Grep,Edit(/${out}/tour.json),Bash(node ${ROOT}/scripts/check-tour.mjs:*)`,
+    ]);
+
+    let raw;
+    try {
+      raw = JSON.parse(readFileSync(join(out, "tour.json"), "utf8"));
+    } catch {
+      throw new Error("Claude did not write a tour file.");
+    }
+    const { tour, errors } = parseTour(raw);
+    const problems = errors.length
+      ? errors
+      : [...checkTour(tour, visibleLines(diff)), ...checkBrevity(tour, { changedLines, limits })];
+    if (problems.length) throw new Error(`The tour did not pass the checks: ${problems.slice(0, 3).join(" / ")}`);
+    return raw;
+  } finally {
+    rmSync(work, { recursive: true, force: true });
+  }
+}
+
+/** Written by the installer; without it, use whatever claude is on PATH. */
+function readConfig() {
+  try {
+    return JSON.parse(readFileSync(join(homedir(), ".pr-docent", "config.json"), "utf8"));
+  } catch {
+    return { claude: "claude" };
+  }
+}
+
+function runClaude(prompt, cwd, args) {
+  return new Promise((resolvePromise, reject) => {
+    const started = Date.now();
+    let output = "";
+    child = spawn(CONFIG.claude, ["-p", prompt, ...args], { cwd, stdio: ["ignore", "pipe", "pipe"] });
+    const keep = (chunk) => (output = (output + chunk).slice(-2000));
+    child.stdout.on("data", keep);
+    child.stderr.on("data", keep);
+    const progress = setInterval(() => send({ type: "progress", seconds: Math.round((Date.now() - started) / 1000) }), 5000);
+    const timeout = setTimeout(() => child.kill(), TIMEOUT_MS);
+    child.on("error", (error) => reject(new Error(`Could not start Claude Code (${CONFIG.claude}): ${error.message}`)));
+    child.on("close", (code) => {
+      clearInterval(progress);
+      clearTimeout(timeout);
+      if (code === 0) resolvePromise();
+      else reject(new Error(`Claude Code exited with code ${code}. ${output.trim().slice(-300)}`));
+    });
+  });
+}

package/package.json

@@ -1,6 +1,38 @@
 {
   "name": "pr-docent",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "type": "module",
+  "description": "Guided, narrated review tours on top of GitHub pull request diffs. This package installs the local tour generator for the PR Docent Chrome extension.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/thomas783/pr-docent.git"
+  },
+  "homepage": "https://github.com/thomas783/pr-docent#readme",
+  "keywords": [
+    "github",
+    "pull-request",
+    "code-review",
+    "chrome-extension",
+    "claude"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "bin": {
+    "pr-docent": "bin/pr-docent.mjs"
+  },
+  "files": [
+    "bin/",
+    "host/",
+    "src/diff.js",
+    "src/guidelines.js",
+    "src/tour.js",
+    "scripts/check-tour.mjs",
+    "scripts/tour-prompt.md"
+  ],
+  "scripts": {
+    "test": "node --test tests/*.test.mjs",
+    "install-host": "node bin/pr-docent.mjs install"
+  }
+}

package/scripts/check-tour.mjs

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+// Validates a tour against a pull request diff.
+//
+//   node scripts/check-tour.mjs <tour.json> <pr.diff> [owner/repo#number] [--guidelines <file>]
+//
+// Prints every problem and exits 1, or prints a one-line summary and exits 0.
+// The diff must use 3 lines of context (`gh pr diff` or `git diff -U3`), as GitHub does.
+// --guidelines points at a copy of the repository's .github/pr-docent.md; a missing file means
+// the default limits.
+
+import { existsSync, readFileSync } from "node:fs";
+import { changedLineCount, checkTour, visibleLines } from "../src/diff.js";
+import { checkBrevity, parseGuidelines } from "../src/guidelines.js";
+import { flattenSteps, parseTour } from "../src/tour.js";
+
+const args = process.argv.slice(2);
+const flag = args.indexOf("--guidelines");
+const guidelinesPath = flag >= 0 ? args.splice(flag, 2)[1] : null;
+const [tourPath, diffPath, expectedPr] = args;
+if (!tourPath || !diffPath) {
+  console.error("usage: node scripts/check-tour.mjs <tour.json> <pr.diff> [owner/repo#number] [--guidelines <file>]");
+  process.exit(2);
+}
+
+const fail = (errors) => {
+  console.error(`Tour has ${errors.length} problem(s):`);
+  for (const error of errors) console.error(`- ${error}`);
+  process.exit(1);
+};
+
+let raw;
+try {
+  raw = JSON.parse(readFileSync(tourPath, "utf8"));
+} catch (error) {
+  fail([`${tourPath} is not valid JSON: ${error.message}`]);
+}
+
+const { tour, errors } = parseTour(raw);
+if (errors.length) fail(errors);
+
+if (expectedPr) {
+  const actual = `${tour.pr.owner}/${tour.pr.repo}#${tour.pr.number}`;
+  if (actual !== expectedPr) fail([`pr is ${actual}, expected ${expectedPr}`]);
+}
+
+const diff = readFileSync(diffPath, "utf8");
+const guidelines = parseGuidelines(guidelinesPath && existsSync(guidelinesPath) ? readFileSync(guidelinesPath, "utf8") : "");
+if (guidelines.errors.length) fail(guidelines.errors.map((error) => `.github/pr-docent.md: ${error}`));
+const problems = [
+  ...checkTour(tour, visibleLines(diff)),
+  ...checkBrevity(tour, { changedLines: changedLineCount(diff), limits: guidelines.limits }),
+];
+if (problems.length) fail(problems);
+
+console.log(`OK: ${tour.chapters.length} chapters, ${flattenSteps(tour).length} steps, ${tour.skipped.length} skipped files`);

package/scripts/tour-prompt.md

@@ -0,0 +1,98 @@
+You are writing a PR Docent review tour for pull request {{PR}}.
+
+A tour guides a human reviewer through the diff on GitHub's Files changed page: a browser
+extension scrolls to each step, highlights its lines and reads the note aloud with a speech
+synthesizer, pointing at the lines each sentence talks about. Reviewers keep their eyes on the
+code while they listen, so the tour must say what to look at and why, in reading order.
+
+## Inputs
+
+- `{{OUT}}/pr.json`: the PR's title, body and head commit.
+- `{{OUT}}/pr.diff`: the diff exactly as GitHub shows it (3 lines of context).
+- The current directory: the repository at the head commit (when generated locally, only the
+  files this PR changes). Use the Read tool to see line numbers.
+
+## Output
+
+Write the tour to `{{OUT}}/tour.json`, then run
+
+    node {{TOOLS}}/scripts/check-tour.mjs {{OUT}}/tour.json {{OUT}}/pr.diff {{PR}} --guidelines {{OUT}}/guidelines.md
+
+and fix every problem it reports until it prints `OK`. Then stop. Do not post comments or
+change any other file. Use these absolute paths as written and do not change directory:
+`{{OUT}}/tour.json` is the only file you are allowed to write.
+
+## Format
+
+```json
+{
+  "version": 1,
+  "pr": { "owner": "...", "repo": "...", "number": 0 },
+  "title": "한 줄 제목",
+  "summary": "PR이 무엇을 왜 바꾸는지 2~4문장",
+  "chapters": [
+    {
+      "title": "1. 챕터 제목",
+      "summary": "한 문장",
+      "steps": [
+        {
+          "file": "path/from/repo/root.kt",
+          "lines": [40, 58],
+          "side": "right",
+          "level": "focus",
+          "note": [
+            { "text": "이 문장이 설명하는 줄을 가리킵니다.", "lines": [41, 45] },
+            { "text": "다음 문장은 다른 줄을 가리킵니다.", "lines": [50, 58] }
+          ],
+          "point": "리뷰어가 확인할 구체적인 질문"
+        }
+      ]
+    }
+  ],
+  "skipped": [{ "file": "package-lock.json", "reason": "의존성 잠금 파일" }]
+}
+```
+
+## Rules
+
+Be brief. Reviewers listen while they look at the code, so every sentence must earn its place.
+The checker enforces these limits for this diff ({{CHANGED_LINES}} changed lines):
+- At most {{MAX_STEPS}} steps in total.
+- At most {{SENTENCES_PER_STEP}} sentences per step, each at most {{SENTENCE_CHARS}} characters.
+- `point`: one question, at most {{POINT_CHARS}} characters.
+- `summary`: at most {{SUMMARY_CHARS}} characters; each chapter `summary`: at most
+  {{CHAPTER_SUMMARY_CHARS}}.
+
+Coverage and order
+- Every changed file must be visited by a step or listed in `skipped` with a short reason.
+- Make steps only for changes a reviewer must think about. Put trivial changes in `skipped`
+  instead of steps: comment or doc-comment edits, imports, docs, test fixtures that pass values
+  through, lock files, generated code, renames, binaries. A file can have a step for its real
+  change and nothing for its trivial ones.
+- Merge neighbouring changes that make one point into one step; never repeat a step.
+- Order chapters the way a person should read the change, not by file path: what changes and
+  why, then the core logic, then how it is wired in, then tests.
+
+Lines
+- `lines` are line numbers in the new file (`"side": "right"`, the default). Use
+  `"side": "left"` with old-file numbers only for code that was deleted.
+- Every line in a step's range must be shown in the diff: inside a hunk, not in the
+  unchanged code GitHub folds away. The checker lists what each file shows.
+- Each note sentence's `lines` must sit inside its step's `lines` and point exactly at what
+  that sentence talks about, usually 1-8 lines. Leave `lines` out for a sentence about the
+  step as a whole.
+
+Notes are spoken aloud
+- Write in {{LANGUAGE}}. One sentence per note entry, one idea per sentence.
+- Say why the change matters: intent, risk, or how it connects to other code. Do not restate
+  what the code plainly shows ("adds a parameter", "imports X", "updates the comment").
+- Avoid symbols, brackets and long lists that sound bad in speech. Name identifiers as written.
+
+Levels and review points
+- `focus`: where a bug would hurt or a design decision is made; at most about a third of the
+  steps. `skim`: worth a look.
+- `point` is one concrete question for the reviewer, grounded in the code you read: an edge
+  case, a failure mode, a contract another caller relies on. Leave it out when there is nothing
+  real to check. Never invent problems.
+
+{{GUIDELINES}}

package/src/diff.js

@@ -0,0 +1,114 @@
+// Checks a tour against the pull request's diff. Pure functions — no DOM, no chrome.*.
+//
+// GitHub's Files changed page shows each hunk of a unified diff with 3 lines of context,
+// so a tour can only point at lines that appear in `git diff -U3`. Generated tours get
+// line numbers wrong easily; this catches that before the tour is published.
+
+/**
+ * Lines visible on the Files changed page, per file: { right: Set, left: Set } where right
+ * holds new-file line numbers (context and additions) and left old-file ones (context and
+ * deletions). Keyed by the new path (the old path for deleted files).
+ */
+export function visibleLines(diffText) {
+  const files = new Map();
+  let current = null;
+  let inHunk = false;
+  let oldLine = 0;
+  let newLine = 0;
+  for (const line of String(diffText).split("\n")) {
+    if (line.startsWith("diff --git ")) {
+      // Every file has this header, including binaries and pure renames that have no hunks.
+      current = { right: new Set(), left: new Set() };
+      files.set(line.slice(line.lastIndexOf(" b/") + 3), current);
+      inHunk = false;
+    } else if (!current) {
+      continue;
+    } else if (line.startsWith("@@")) {
+      const match = line.match(/^@@ -(\d+)(?:,\d+)? \+(\d+)(?:,\d+)? @@/);
+      if (match) [oldLine, newLine] = [Number(match[1]), Number(match[2])];
+      inHunk = Boolean(match);
+    } else if (!inHunk) {
+      continue; // index, mode, rename, ---/+++ headers
+    } else if (line.startsWith("+")) {
+      current.right.add(newLine++);
+    } else if (line.startsWith("-")) {
+      current.left.add(oldLine++);
+    } else if (line.startsWith(" ")) {
+      current.right.add(newLine++);
+      current.left.add(oldLine++);
+    }
+  }
+  return files;
+}
+
+/**
+ * Problems that would make the tour point at the wrong place or skip part of the PR:
+ * files outside the diff, lines not shown on the page, beats outside their step, repeated
+ * steps, and changed files the tour neither visits nor skips.
+ */
+export function checkTour(tour, files) {
+  const errors = [];
+  const visited = new Set();
+  const seen = new Set();
+  tour.chapters.forEach((chapter, c) =>
+    chapter.steps.forEach((step, s) => {
+      const where = `chapters[${c}].steps[${s}] (${step.file})`;
+      visited.add(step.file);
+      const key = `${step.file}|${step.side}|${step.lines}`;
+      if (seen.has(key)) errors.push(`${where}: repeats an earlier step on the same lines`);
+      seen.add(key);
+      const file = files.get(step.file);
+      if (!file) return errors.push(`${where}: file is not changed in this pull request`);
+      const shown = file[step.side];
+      const check = (lines, label) => {
+        const missing = range(lines).filter((n) => !shown.has(n));
+        if (missing.length) {
+          errors.push(`${label}: lines ${formatRanges(missing)} are not shown in the diff (${step.side} side shows ${formatRanges([...shown])})`);
+        }
+      };
+      if (step.lines) check(step.lines, where);
+      step.beats.forEach((beat, b) => {
+        if (!beat.lines) return;
+        if (!step.lines || beat.lines[0] < step.lines[0] || beat.lines[1] > step.lines[1]) {
+          errors.push(`${where} note[${b}]: lines ${formatRanges(range(beat.lines))} must be inside the step's lines`);
+        } else {
+          check(beat.lines, `${where} note[${b}]`);
+        }
+      });
+    }),
+  );
+  for (const skipped of tour.skipped) visited.add(skipped.file);
+  for (const path of files.keys()) {
+    if (!visited.has(path)) errors.push(`${path}: changed but neither visited by a step nor listed in "skipped"`);
+  }
+  return errors;
+}
+
+/** Added plus removed lines, which sets how long a tour of the diff may be. */
+export function changedLineCount(diffText) {
+  let count = 0;
+  let inHunk = false;
+  for (const line of String(diffText).split("\n")) {
+    if (line.startsWith("diff --git ")) inHunk = false;
+    else if (line.startsWith("@@")) inHunk = true;
+    else if (inHunk && (line.startsWith("+") || line.startsWith("-"))) count++;
+  }
+  return count;
+}
+
+function range([start, end]) {
+  return Array.from({ length: end - start + 1 }, (_, i) => start + i);
+}
+
+/** [1, 2, 3, 7, 9, 10] → "1-3, 7, 9-10" */
+export function formatRanges(numbers) {
+  const sorted = [...numbers].sort((a, b) => a - b);
+  const parts = [];
+  for (let i = 0; i < sorted.length; ) {
+    let j = i;
+    while (j + 1 < sorted.length && sorted[j + 1] === sorted[j] + 1) j++;
+    parts.push(i === j ? `${sorted[i]}` : `${sorted[i]}-${sorted[j]}`);
+    i = j + 1;
+  }
+  return parts.join(", ") || "none";
+}

package/src/guidelines.js

@@ -0,0 +1,102 @@
+// How long a generated tour may be, and a repository's own instructions for it.
+// Pure functions — no DOM, no chrome.*, no file system.
+//
+// A repository can add .github/pr-docent.md. Its optional front matter overrides the limits,
+// and the rest is appended to the generator's instructions:
+//
+//   ---
+//   maxSteps: 5
+//   sentenceChars: 100
+//   ---
+//   Use the domain terms 원장, 안분 and 파생 라인. Always mark migrations as focus.
+
+import { flattenSteps, splitSentences } from "./tour.js";
+
+export const GUIDELINES_PATH = ".github/pr-docent.md";
+
+export const DEFAULT_LIMITS = {
+  maxSteps: null, // null: 3 + 1 per 25 changed lines, at most 20
+  sentencesPerStep: 3,
+  sentenceChars: 80,
+  pointChars: 120,
+  summaryChars: 200,
+  chapterSummaryChars: 60,
+};
+
+/** { limits, instructions, errors } from the text of .github/pr-docent.md (or "" when absent). */
+export function parseGuidelines(text) {
+  const limits = { ...DEFAULT_LIMITS };
+  const errors = [];
+  const match = String(text ?? "").match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?/);
+  for (const line of match ? match[1].split(/\r?\n/) : []) {
+    if (!line.trim() || line.trim().startsWith("#")) continue;
+    const [, key, value] = line.replace(/\s+#.*$/, "").match(/^\s*(\w+)\s*:\s*(.*?)\s*$/) ?? [];
+    if (!key || !(key in DEFAULT_LIMITS)) errors.push(`Unknown setting: ${line.trim()}`);
+    else if (!/^\d+$/.test(value) || Number(value) < 1) errors.push(`${key} must be a positive whole number`);
+    else limits[key] = Number(value);
+  }
+  const instructions = String(text ?? "").slice(match ? match[0].length : 0).trim();
+  return { limits, instructions, errors };
+}
+
+/** How many steps a tour of a diff with [changedLines] added or removed lines may have. */
+export function stepBudget(changedLines, limits = DEFAULT_LIMITS) {
+  return limits.maxSteps ?? Math.min(20, 3 + Math.ceil(changedLines / 25));
+}
+
+/** Problems that make a tour wordier than the limits allow. */
+export function checkBrevity(tour, { changedLines, limits = DEFAULT_LIMITS }) {
+  const errors = [];
+  const steps = flattenSteps(tour);
+  const budget = stepBudget(changedLines, limits);
+  if (steps.length > budget) {
+    errors.push(`${steps.length} steps for ${changedLines} changed lines; at most ${budget}. Merge related steps and list trivial changes (comments, imports, docs, pass-through code) in "skipped".`);
+  }
+  if (tour.summary.length > limits.summaryChars) errors.push(`summary is ${tour.summary.length} characters; at most ${limits.summaryChars}`);
+  tour.chapters.forEach((chapter, c) => {
+    if (chapter.summary.length > limits.chapterSummaryChars) {
+      errors.push(`chapters[${c}].summary is ${chapter.summary.length} characters; at most ${limits.chapterSummaryChars}`);
+    }
+    chapter.steps.forEach((step, s) => {
+      const where = `chapters[${c}].steps[${s}] (${step.file})`;
+      const sentences = step.beats.flatMap((beat) => splitSentences(beat.text).map((x) => x.text));
+      if (sentences.length > limits.sentencesPerStep) {
+        errors.push(`${where}: ${sentences.length} sentences; at most ${limits.sentencesPerStep}. Keep only what the code doesn't already say.`);
+      }
+      for (const sentence of sentences) {
+        if (sentence.length > limits.sentenceChars) {
+          errors.push(`${where}: a sentence is ${sentence.length} characters; at most ${limits.sentenceChars}: "${sentence.slice(0, 30)}…"`);
+        }
+      }
+      if (step.point.length > limits.pointChars) {
+        errors.push(`${where}: point is ${step.point.length} characters; at most ${limits.pointChars}. Ask one question.`);
+      }
+    });
+  });
+  return errors;
+}
+
+/**
+ * The generator's instructions: [template] (scripts/tour-prompt.md) with the paths, the limits
+ * for this diff and the repository's own instructions filled in.
+ */
+export function buildPrompt(template, { pr, out, tools, language, changedLines, guidelinesText = "" }) {
+  const { limits, instructions } = parseGuidelines(guidelinesText);
+  const vars = {
+    PR: pr,
+    OUT: out,
+    TOOLS: tools,
+    LANGUAGE: language,
+    CHANGED_LINES: changedLines,
+    MAX_STEPS: stepBudget(changedLines, limits),
+    SENTENCES_PER_STEP: limits.sentencesPerStep,
+    SENTENCE_CHARS: limits.sentenceChars,
+    POINT_CHARS: limits.pointChars,
+    SUMMARY_CHARS: limits.summaryChars,
+    CHAPTER_SUMMARY_CHARS: limits.chapterSummaryChars,
+    GUIDELINES: instructions
+      ? `## Repository guidelines (${GUIDELINES_PATH})\n\nThese come from the repository and take precedence over the rules above.\n\n${instructions}\n`
+      : "",
+  };
+  return template.replace(/{{(\w+)}}/g, (match, name) => (name in vars ? String(vars[name]) : match));
+}

package/src/tour.js

@@ -0,0 +1,172 @@
+// Tour model: validation, flattening and coverage. Pure functions — no DOM, no chrome.*.
+//
+// A tour (version 1):
+// {
+//   "version": 1,
+//   "pr": { "owner": "your-org", "repo": "your-repo", "number": 42 },
+//   "title": "...", "summary": "...",
+//   "chapters": [{ "title": "...", "summary": "...", "steps": [
+//     { "file": "path/in/repo.kt", "lines": [10, 24], "side": "right", "level": "focus", "note": "...", "point": "..." }
+//   ]}],
+//   "skipped": [{ "file": "server/gradlew", "reason": "generated wrapper" }]
+// }
+// lines and side are optional (without lines the step points at the whole file);
+// level is focus | skim | skip; point (optional) is what the reviewer should check.
+// note is a string, or a list of beats that each point at the lines they talk about:
+//   "note": [{ "text": "findFocus finds ...", "lines": [58, 63] }, { "text": "..." }]
+
+export const LEVELS = ["focus", "skim", "skip"];
+
+/** Validates and normalizes raw JSON. Returns { tour, errors }; tour is null when there are errors. */
+export function parseTour(raw) {
+  const errors = [];
+  const fail = (msg) => errors.push(msg);
+  if (!raw || typeof raw !== "object") return { tour: null, errors: ["Tour must be a JSON object"] };
+  if (raw.version !== 1) fail(`Unsupported tour version: ${raw.version}`);
+
+  const pr = raw.pr || {};
+  if (!pr.owner || !pr.repo || !Number.isInteger(pr.number)) fail("pr.owner, pr.repo and pr.number are required");
+  if (!Array.isArray(raw.chapters) || raw.chapters.length === 0) fail("At least one chapter is required");
+
+  const chapters = (raw.chapters || []).map((chapter, c) => {
+    if (!chapter.title) fail(`chapters[${c}].title is required`);
+    if (!Array.isArray(chapter.steps) || chapter.steps.length === 0) fail(`chapters[${c}] needs at least one step`);
+    const steps = (chapter.steps || []).map((step, s) => {
+      const where = `chapters[${c}].steps[${s}]`;
+      if (typeof step.file !== "string" || !step.file) fail(`${where}.file is required`);
+      const lines = parseLines(step.lines, where, fail);
+      const side = step.side ?? "right";
+      if (side !== "left" && side !== "right") fail(`${where}.side must be "left" or "right"`);
+      const level = step.level ?? "skim";
+      if (!LEVELS.includes(level)) fail(`${where}.level must be one of ${LEVELS.join(", ")}`);
+      if (step.point !== undefined && typeof step.point !== "string") fail(`${where}.point must be a string`);
+      const beats = parseBeats(step.note, where, fail);
+      const note = beats.map((beat) => beat.text).join(" ");
+      return { file: step.file, lines, side, level, note, beats, point: step.point ?? "" };
+    });
+    return { title: String(chapter.title ?? ""), summary: String(chapter.summary ?? ""), steps };
+  });
+
+  const skipped = (raw.skipped || []).map((s) => ({ file: String(s.file ?? ""), reason: String(s.reason ?? "") }));
+  if (errors.length) return { tour: null, errors };
+  return {
+    tour: {
+      version: 1,
+      pr: { owner: pr.owner, repo: pr.repo, number: pr.number },
+      title: String(raw.title ?? ""),
+      summary: String(raw.summary ?? ""),
+      chapters,
+      skipped,
+    },
+    errors: [],
+  };
+}
+
+/** [start, end] line range, or null when absent; reports a malformed one through [fail]. */
+function parseLines(value, where, fail) {
+  if (value === undefined) return null;
+  const [start, end] = Array.isArray(value) ? value : [];
+  if (!Number.isInteger(start) || !Number.isInteger(end) || start < 1 || end < start) {
+    fail(`${where}.lines must be [start, end] with 1 <= start <= end`);
+    return null;
+  }
+  return [start, end];
+}
+
+/** A note as beats: a plain string is one beat that points at no particular lines. */
+function parseBeats(note, where, fail) {
+  if (!Array.isArray(note)) return note ? [{ text: String(note), lines: null }] : [];
+  return note.map((beat, b) => {
+    const at = `${where}.note[${b}]`;
+    if (typeof beat?.text !== "string" || !beat.text) fail(`${at}.text is required`);
+    return { text: String(beat?.text ?? ""), lines: parseLines(beat?.lines, at, fail) };
+  });
+}
+
+/** Every step in order, with its chapter index and its position inside the chapter. */
+export function flattenSteps(tour) {
+  return tour.chapters.flatMap((chapter, chapterIndex) =>
+    chapter.steps.map((step, stepIndex) => ({ ...step, chapterIndex, stepIndex, chapterTitle: chapter.title })),
+  );
+}
+
+/** PR files the tour neither visits nor explicitly skips — the reviewer must look at these alone. */
+export function uncoveredFiles(tour, prFiles) {
+  const covered = new Set([
+    ...tour.chapters.flatMap((c) => c.steps.map((s) => s.file)),
+    ...tour.skipped.map((s) => s.file),
+  ]);
+  return prFiles.filter((file) => !covered.has(file));
+}
+
+/** Seconds a step stays on screen when narration is off: roughly reading speed, at least 4s. */
+export function readingSeconds(text) {
+  return Math.max(4, Math.round(String(text).length / 12));
+}
+
+/**
+ * Splits narration into sentences, each with its offset in [text], so it can be read (and
+ * resumed) a sentence at a time. A period after a digit ("2. 집중 단계") is a list number,
+ * not a sentence end.
+ */
+export function splitSentences(text) {
+  const sentences = [];
+  const pattern = /[^\d\s][.!?](?=\s)/g;
+  let start = 0;
+  for (let match; (match = pattern.exec(text)); ) {
+    const end = match.index + match[0].length;
+    pushSentence(sentences, text, start, end);
+    start = end;
+  }
+  pushSentence(sentences, text, start, text.length);
+  return sentences;
+}
+
+function pushSentence(sentences, text, start, end) {
+  const raw = text.slice(start, end);
+  const trimmed = raw.trim();
+  if (trimmed) sentences.push({ start: start + raw.indexOf(trimmed), text: trimmed });
+}
+
+/**
+ * What to say for a step, one sentence per unit, each with the lines to point at while it
+ * is read (null: just the step's own range). Opens with the chapter title when given and
+ * ends with the review point.
+ */
+export function narrationUnits(step, { chapterTitle = "", pointLabel = "" } = {}) {
+  const units = [];
+  const add = (text, lines) => splitSentences(text).forEach((s) => units.push({ text: s.text, lines }));
+  if (chapterTitle) add(`${chapterTitle}.`, null);
+  for (const beat of step.beats) add(beat.text, beat.lines);
+  if (step.point) add(`${pointLabel}: ${step.point}`, null);
+  return units;
+}
+
+/**
+ * The tour for [pr] among code blocks of the PR's comments (the generator posts it as a
+ * JSON block): the last block that parses as a version 1 tour of this PR, or null.
+ */
+export function findTourInBlocks(blocks, { owner, repo, number }) {
+  let found = null;
+  for (const text of blocks) {
+    let raw;
+    try {
+      raw = JSON.parse(text);
+    } catch {
+      continue;
+    }
+    if (raw?.version === 1 && raw.pr?.owner === owner && raw.pr?.repo === repo && raw.pr?.number === number) found = raw;
+  }
+  return found;
+}
+
+/** "ko" when the tour's text has Hangul, otherwise "en": the language to narrate it in. */
+export function tourLanguage(tour) {
+  const text = [tour.title, tour.summary, ...flattenSteps(tour).flatMap((s) => [s.note, s.point])].join(" ");
+  return /[가-힣]/.test(text) ? "ko" : "en";
+}
+
+/** The bundled tour file name for a PR, e.g. "your-org--your-repo--42.json". */
+export function tourFileName({ owner, repo, number }) {
+  return `${owner}--${repo}--${number}.json`;
+}