newpr 0.3.0 → 0.5.0

package/README.md

@@ -1,78 +1,86 @@
 # newpr
 
-AI-powered PR review tool for understanding large pull requests with 1000+ lines of changes.
+AI-powered PR review tool that turns large pull requests into readable, navigable stories.
 
-newpr fetches a GitHub PR, optionally clones the repo for deep codebase exploration using an agentic coding tool, then uses an LLM to produce a structured analysis: file summaries, logical groupings, an overall summary, and a narrative walkthrough with clickable cross-references.
+## Quick Install
 
-## Features
-
-- **Narrative walkthrough** — reads like an article, with `[[group:...]]` and `[[file:...]]` cross-references
-- **Logical grouping** — clusters changed files by purpose (feature, refactor, bugfix, etc.)
-- **Codebase exploration** — uses Claude Code / OpenCode / Codex to analyze the actual repository, not just the diff
-- **Interactive TUI** — Ink-based terminal UI with tabbed panels, slash commands, ASCII logo
-- **Web UI** — browser-based interface with sidebar, resizable panels, markdown rendering, dark/light mode
-- **Streaming progress** — real-time SSE streaming of analysis steps
-- **Session history** — saves past analyses for instant recall
-- **Multi-language** — output in any language (auto-detected or configured)
+```bash
+bunx newpr --web
+```
 
-## Quick Start
+Or install globally:
 
 ```bash
-bun install
+bun add -g newpr
+newpr --web
 ```
 
-### Option A: OpenRouter API key
+The web UI opens automatically at `http://localhost:3000`. Paste any GitHub PR URL to start.
+
+### Prerequisites
+
+- [Bun](https://bun.sh) — `curl -fsSL https://bun.sh/install | bash`
+- [GitHub CLI](https://cli.github.com) — `brew install gh && gh auth login`
+- One of:
+  - `OPENROUTER_API_KEY` — for model selection (Claude, GPT-4, Gemini, etc.)
+  - [Claude Code](https://docs.anthropic.com/en/docs/claude-code) — zero-config fallback
 
 ```bash
+# Option A: OpenRouter
 export OPENROUTER_API_KEY=sk-or-...
-newpr https://github.com/owner/repo/pull/123
+newpr --web
+
+# Option B: Claude Code (no API key needed)
+newpr --web
 ```
 
-### Option B: Claude Code (no API key needed)
+## What it Does
 
-If you have [Claude Code](https://docs.anthropic.com/en/docs/claude-code) installed, newpr uses it as a fallback when no OpenRouter API key is set — for both LLM analysis and codebase exploration.
+newpr fetches a GitHub PR, clones the repo for deep codebase exploration using an agentic coding tool (Claude Code / OpenCode / Codex), then produces:
 
-```bash
-newpr https://github.com/owner/repo/pull/123
-```
+- **Narrative walkthrough** — prose-first story with clickable code references that open diffs at the exact line
+- **Logical grouping** — clusters files by purpose (feature, refactor, bugfix) with key changes, risk assessment, and dependency mapping
+- **Interactive chat** — ask follow-up questions with agentic tool execution (file diffs, GitHub API, web search)
+- **Inline diff comments** — create/edit/delete review comments synced to GitHub
+- **PR actions** — approve, request changes, or comment directly from the UI
+- **React Doctor** — auto-runs [react-doctor](https://github.com/millionco/react-doctor) on React projects for code quality scoring
 
-### Web UI
+### Anchors & Navigation
 
-```bash
-newpr --web --port 3000
-```
+Every analysis is densely linked. The narrative contains three types of clickable references:
 
-Opens a browser-based UI at `http://localhost:3000` with:
-- Left sidebar with session history
-- Resizable detail panel on the right
-- Clickable group/file anchors in the narrative
-- Settings modal for model, agent, language configuration
-- GitHub profile integration
+| Anchor | Appearance | Action |
+|--------|------------|--------|
+| `[[group:Name]]` | Blue chip | Opens group detail in sidebar |
+| `[[file:path]]` | Blue chip | Opens file diff in sidebar |
+| `[[line:path#L-L]](text)` | Subtle underline | Opens diff scrolled to line, highlights range |
 
 ## Usage
 
-```
-newpr                                # launch interactive shell
-newpr <pr-url>                       # shell with PR pre-loaded
-newpr --web [--port 3000]            # launch web UI
-newpr review <pr-url> --json         # non-interactive JSON output
-newpr history                        # list past review sessions
-newpr auth [--key <api-key>]         # configure API key
+```bash
+newpr                                 # interactive shell (TUI)
+newpr <pr-url>                        # shell with PR pre-loaded
+newpr --web [--port 3000]             # web UI (default)
+newpr --web --cartoon                 # web UI with comic strip generation
+newpr review <pr-url> --json          # non-interactive JSON output
+newpr history                         # list past sessions
+newpr auth [--key <api-key>]          # configure API key
 ```
 
-### Review mode options
+### Options
 
 ```
---repo <owner/repo>   Repository (when using PR number only)
---model <model>       Override LLM model (default: anthropic/claude-sonnet-4.5)
+--model <model>       LLM model (default: anthropic/claude-sonnet-4.6)
 --agent <tool>        Preferred agent: claude | opencode | codex (default: auto)
---no-clone            Skip git clone, diff-only analysis (faster, less context)
+--port <port>         Web UI port (default: 3000)
+--cartoon             Enable comic strip generation
+--no-clone            Skip git clone, diff-only analysis
 --json                Output raw JSON
---stream-json         Stream progress as NDJSON, then emit result
+--stream-json         Stream progress as NDJSON
 --verbose             Show progress on stderr
 ```
 
-### PR input formats
+### PR Input Formats
 
 ```bash
 newpr https://github.com/owner/repo/pull/123
@@ -80,66 +88,71 @@ newpr owner/repo#123
 newpr review 123 --repo owner/repo
 ```
 
-## Architecture
+## Web UI
 
-```
-src/
-├── cli/          # CLI entry, arg parsing, auth, history commands
-├── config/       # Config loading (~/.newpr/config.json)
-├── github/       # GitHub API (fetch PR data, diff, parse URL)
-├── diff/         # Unified diff parser + chunker
-├── llm/          # LLM clients (OpenRouter + Claude Code fallback), prompts, response parser
-├── analyzer/     # Pipeline orchestrator + progress events
-├── workspace/    # Agent system (claude/opencode/codex), git operations, codebase exploration
-├── types/        # Shared TypeScript types
-├── history/      # Session persistence (~/.newpr/history/)
-├── tui/          # Ink TUI (shell, panels, theme, slash commands)
-└── web/          # Web UI
-    ├── server.ts           # Bun.serve() with Tailwind CSS build
-    ├── server/             # REST API + SSE endpoints, session manager
-    ├── client/             # React frontend
-    │   ├── components/     # AppShell, ResultsScreen, Markdown, DetailPane, etc.
-    │   ├── panels/         # Story, Summary, Groups, Files, Narrative
-    │   └── hooks/          # useAnalysis, useSessions, useTheme, useGithubUser
-    └── styles/             # Tailwind v4 + Pretendard font
-```
+The web interface provides:
 
-## Analysis Pipeline
+- **Sidebar** — sessions grouped by repository, background analysis tracking
+- **Story tab** — narrative with inline line anchors + chat input at bottom
+- **Discussion tab** — PR description + GitHub comments
+- **Groups tab** — collapsible change groups with key changes and risk
+- **Files tab** — tree/group/changes view modes with inline summaries
+- **Comic tab** — AI-generated 4-panel comic strip (with `--cartoon`)
+- **Right sidebar** — file diffs with syntax highlighting, inline comments, line highlighting
+- **TipTap editor** — `@` to reference files/groups, `/` for commands
+- **KaTeX** — LaTeX math rendering in chat and narrative
+- **Review modal** — approve, request changes, or comment via GitHub API
+- **Settings** — model, agent, language, API keys
+- **Preflight checks** — system health (gh, agents, API key) on startup
 
-1. **Fetch** — PR metadata, commits, and diff from GitHub API
-2. **Parse** — unified diff into per-file chunks
-3. **Clone** — bare repo clone with worktree checkout (cached)
-4. **Explore** — 3-phase codebase exploration via agentic tool (structure → related code → issues)
-5. **Analyze** — LLM summarizes each file chunk in parallel batches
-6. **Group** — LLM clusters files into logical groups with types
-7. **Summarize** — LLM generates purpose, scope, impact, risk level
-8. **Narrate** — LLM writes a walkthrough article with cross-references
+## Chat
 
-## LLM Backend
+The chat in the Story tab supports agentic tool execution:
 
-newpr supports two LLM backends:
+| Tool | Description |
+|------|-------------|
+| `get_file_diff` | Fetch unified diff for a specific file |
+| `list_files` | List all changed files with summaries |
+| `get_pr_comments` | Fetch PR discussion comments |
+| `get_review_comments` | Fetch inline review comments |
+| `get_pr_details` | PR metadata, labels, reviewers |
+| `web_search` | Search the web (delegated to agent) |
+| `web_fetch` | Fetch URL content (delegated to agent) |
+| `run_react_doctor` | Run react-doctor analysis |
 
-| Backend | Setup | Use case |
-|---------|-------|----------|
-| **OpenRouter** | Set `OPENROUTER_API_KEY` | Full model selection (Claude, GPT-4, Gemini, etc.) |
-| **Claude Code** | Install `claude` CLI | Zero-config fallback, uses your existing Claude subscription |
+Type `/undo` to remove the last exchange.
 
-When no OpenRouter API key is configured, newpr automatically falls back to Claude Code for all LLM calls.
+## Analysis Pipeline
 
-## Codebase Exploration Agents
+1. **Fetch** — PR metadata, commits, diff, and discussion from GitHub API
+2. **Parse** — unified diff into per-file chunks
+3. **Clone** — bare repo with worktree checkout (cached in `~/.newpr/repos/`)
+4. **Explore** — 3-4 phase codebase exploration via agent:
+   - Structure — project type, architecture
+   - Related code — imports, usages, tests
+   - Issues — breaking changes, inconsistencies
+   - React Doctor — code quality score (React projects only)
+5. **Analyze** — LLM summarizes each file in parallel batches
+6. **Group** — LLM clusters files with key changes, risk, dependencies
+7. **Summarize** — purpose, scope, impact, risk level
+8. **Narrate** — prose walkthrough with line-level code references
+
+## LLM Backends
+
+| Backend | Setup | Use case |
+|---------|-------|----------|
+| **OpenRouter** | `OPENROUTER_API_KEY` | Full model selection |
+| **Claude Code** | `claude` CLI installed | Zero-config fallback |
 
-For deep analysis beyond the diff, newpr uses an agentic coding tool to explore the actual repository:
+## Exploration Agents
 
-| Agent | Command | Detection |
+| Agent | Install | Detection |
 |-------|---------|-----------|
-| Claude Code | `claude` | `which claude` |
-| OpenCode | `opencode` | `which opencode` |
-| Codex | `codex` | `which codex` |
+| Claude Code | `npm i -g @anthropic-ai/claude-code` | `which claude` |
+| OpenCode | `npm i -g opencode` | `which opencode` |
+| Codex | `npm i -g @openai/codex` | `which codex` |
 
-The agent runs 3 exploration phases:
-1. **Structure** — project type, key directories, architecture pattern
-2. **Related code** — imports, usages, test coverage for changed files
-3. **Issues** — breaking changes, missing error handling, inconsistencies
+Agents run with read-only tools (Read, Glob, Grep, Bash, WebSearch, WebFetch). No write operations.
 
 ## Environment Variables
 
@@ -147,19 +160,19 @@ The agent runs 3 exploration phases:
 |----------|----------|-------------|
 | `OPENROUTER_API_KEY` | No* | OpenRouter API key (*falls back to Claude Code) |
 | `GITHUB_TOKEN` | No | GitHub token (falls back to `gh` CLI) |
-| `NEWPR_MODEL` | No | Default model (default: `anthropic/claude-sonnet-4.5`) |
+| `NEWPR_MODEL` | No | Default model (default: `anthropic/claude-sonnet-4.6`) |
 | `NEWPR_MAX_FILES` | No | Max files to analyze (default: 100) |
 | `NEWPR_TIMEOUT` | No | Timeout per LLM call in seconds (default: 120) |
 | `NEWPR_CONCURRENCY` | No | Parallel LLM calls (default: 5) |
 
-## Config File
+## Config
 
-Persistent settings are stored in `~/.newpr/config.json`:
+Persistent settings in `~/.newpr/config.json`:
 
 ```json
 {
   "openrouter_api_key": "sk-or-...",
-  "model": "anthropic/claude-sonnet-4.5",
+  "model": "anthropic/claude-sonnet-4.6",
   "language": "auto",
   "agent": "claude",
   "max_files": 100,
@@ -171,19 +184,38 @@ Persistent settings are stored in `~/.newpr/config.json`:
 ## Development
 
 ```bash
+git clone https://github.com/jiwonMe/newpr
+cd newpr
 bun install
-bun test              # run tests (91 tests)
+bun test              # 91 tests
 bun run typecheck     # tsc --noEmit
-bun run lint          # biome check
 bun run start         # launch CLI
 ```
 
-## Requirements
+## Architecture
 
-- [Bun](https://bun.sh) ≥ 1.3
-- GitHub CLI (`gh`) for authentication, or `GITHUB_TOKEN`
-- One of: `OPENROUTER_API_KEY` or Claude Code (`claude` CLI)
+```
+src/
+├── cli/          # CLI entry, args, auth, preflight, update-check
+├── config/       # Config loading (~/.newpr/config.json)
+├── github/       # GitHub API (PR data, diff, comments)
+├── diff/         # Unified diff parser + chunker
+├── llm/          # LLM clients (OpenRouter + Claude Code), prompts, parser
+├── analyzer/     # Pipeline orchestrator + progress events
+├── workspace/    # Agent system, git operations, codebase exploration
+├── types/        # Shared TypeScript types
+├── history/      # Session persistence + sidecar files
+├── tui/          # Ink TUI (shell, panels, theme)
+└── web/          # Web UI
+    ├── server.ts           # Bun.serve()
+    ├── server/             # REST/SSE API, session manager
+    ├── client/             # React frontend
+    │   ├── components/     # AppShell, ChatSection, Markdown, TipTapEditor, etc.
+    │   ├── panels/         # Story, Discussion, Groups, Files, Cartoon
+    │   └── hooks/          # useAnalysis, useBackgroundAnalyses, useChatState, etc.
+    └── styles/             # Tailwind v4 + Pretendard + Tab0 Mono K
+```
 
 ## License
 
-Private
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "newpr",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "AI-powered large PR review tool - understand PRs with 1000+ lines of changes",
   "module": "src/cli/index.ts",
   "type": "module",
@@ -53,7 +53,7 @@
     "@types/react-dom": "^19.2.3"
   },
   "peerDependencies": {
-    "typescript": "^5"
+    "typescript": "^5.9.3"
   },
   "dependencies": {
     "@radix-ui/react-dropdown-menu": "^2.1.16",

package/src/analyzer/pipeline.ts

@@ -85,18 +85,14 @@ async function runExploration(
 ): Promise<ExplorationResult> {
 	const agent = await requireAgent(preferredAgent);
 
-	onProgress?.({ stage: "cloning", message: `Cloning ${pr.owner}/${pr.repo}...` });
 	const bareRepoPath = await ensureRepo(pr.owner, pr.repo, token, (msg) => {
 		onProgress?.({ stage: "cloning", message: `📦 ${msg}` });
 	});
-	onProgress?.({ stage: "cloning", message: `📦 ${pr.owner}/${pr.repo} cached` });
 
-	onProgress?.({ stage: "checkout", message: `🌿 Preparing worktrees: ${baseBranch} ← PR #${pr.number}` });
 	const worktrees = await createWorktrees(
 		bareRepoPath, baseBranch, pr.number, pr.owner, pr.repo,
 		(msg) => onProgress?.({ stage: "checkout", message: `🌿 ${msg}` }),
 	);
-	onProgress?.({ stage: "checkout", message: `🌿 Worktrees ready: ${baseBranch} ← PR #${pr.number}` });
 
 	onProgress?.({ stage: "exploring", message: `🤖 ${agent.name}: exploring ${changedFiles.length} changed files...` });
 	const exploration = await exploreCodebase(
@@ -302,6 +298,7 @@ export async function analyzePr(options: PipelineOptions): Promise<NewprOutput>
 			pr_body: prData.body || undefined,
 			pr_url: prData.url,
 			pr_state: prData.state,
+			pr_updated_at: prData.updated_at,
 			base_branch: prData.base_branch,
 			head_branch: prData.head_branch,
 			author: prData.author,

package/src/cli/args.ts

@@ -46,7 +46,7 @@ Options:
 
 Options (review mode):
   --repo <owner/repo>   Repository (required when using PR number only)
-  --model <model>       Override LLM model (default: anthropic/claude-sonnet-4.5)
+  --model <model>       Override LLM model (default: anthropic/claude-sonnet-4.6)
   --agent <tool>        Preferred agent: claude | opencode | codex (default: auto)
   --no-clone            Skip git clone, diff-only analysis (faster, less context)
   --json                Output raw JSON (for piping/scripting)

package/src/cli/index.ts

@@ -11,8 +11,9 @@ import { createStderrProgress, createSilentProgress, createStreamJsonProgress }
 import { renderLoading, renderShell } from "../tui/render.tsx";
 import { checkForUpdate, printUpdateNotice } from "./update-check.ts";
 import { runPreflight, printPreflight } from "./preflight.ts";
+import { getVersion } from "../version.ts";
 
-const VERSION = "0.3.0";
+const VERSION = getVersion();
 
 async function main(): Promise<void> {
 	const args = parseArgs(process.argv);

package/src/github/fetch-pr.ts

@@ -20,6 +20,7 @@ export function mapPrResponse(json: Record<string, unknown>): Omit<GithubPrData,
 		body: (json.body as string) ?? "",
 		url: json.html_url as string,
 		state,
+		updated_at: (json.updated_at as string) ?? new Date().toISOString(),
 		base_branch: (base?.ref as string) ?? "unknown",
 		head_branch: (head?.ref as string) ?? "unknown",
 		author: (user?.login as string) ?? "unknown",

package/src/history/store.ts

@@ -2,7 +2,7 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 import { mkdirSync, rmSync, existsSync } from "node:fs";
 import { randomBytes } from "node:crypto";
-import type { NewprOutput, DiffComment, ChatMessage, CartoonImage } from "../types/output.ts";
+import type { NewprOutput, DiffComment, ChatMessage, CartoonImage, SlideDeck } from "../types/output.ts";
 import type { SessionRecord } from "./types.ts";
 
 const HISTORY_DIR = join(homedir(), ".newpr", "history");
@@ -197,6 +197,30 @@ export async function loadCartoonSidecar(
 	}
 }
 
+export async function saveSlidesSidecar(
+	id: string,
+	deck: SlideDeck,
+): Promise<void> {
+	ensureDirs();
+	await Bun.write(
+		join(SESSIONS_DIR, `${id}.slides.json`),
+		JSON.stringify(deck),
+	);
+}
+
+export async function loadSlidesSidecar(
+	id: string,
+): Promise<SlideDeck | null> {
+	try {
+		const filePath = join(SESSIONS_DIR, `${id}.slides.json`);
+		const file = Bun.file(filePath);
+		if (!(await file.exists())) return null;
+		return JSON.parse(await file.text()) as SlideDeck;
+	} catch {
+		return null;
+	}
+}
+
 export function getHistoryPath(): string {
 	return HISTORY_DIR;
 }

package/src/llm/prompts.ts

@@ -155,30 +155,83 @@ export function buildNarrativePrompt(
 
 	return {
 		system: `You are an expert code reviewer writing a review walkthrough for other developers.
-Write a clear, concise narrative that tells the "story" of this PR — what changes were made and in what logical order.
-Use the commit history and PR discussion to understand the development progression: which changes came first, how the PR evolved, and the intent behind each step. The PR description often explains the author's motivation and approach.
-Use markdown formatting. Write 2-5 paragraphs. Do NOT use JSON. Write natural prose.
-${lang ? `CRITICAL: Write the ENTIRE narrative in ${lang}. Every sentence must be in ${lang}. Do NOT use English except for code identifiers, file paths, and [[group:...]]/[[file:...]] tokens.` : "If the PR title is in a non-English language, write the narrative in that same language."}
-
-IMPORTANT: Use these anchor formats — they become clickable links in the UI:
-
-1. Group: [[group:Group Name]] — renders as a clickable chip.
-2. File: [[file:path/to/file.ts]] — renders as a clickable chip.
-3. Line reference: [[line:path/to/file.ts#L42-L50]](descriptive text here) — the "descriptive text" becomes an underlined clickable link that opens the diff at that line. The line info itself is NOT shown to the user — only the descriptive text is visible.
-
-RULES:
-- Use EXACT group names and file paths from the context above.
-- Every group MUST be referenced at least once with [[group:...]].
-- For line references, ALWAYS use the form [[line:path#Lstart-Lend]](text). NEVER use bare [[line:...]] without (text).
-- The (text) should be a natural description of what the code does, NOT the file name or line numbers. The reader should not see any line numbers — they just see underlined text they can click.
-- Do NOT place [[file:...]] and [[line:...]] next to each other for the same file. Use [[line:...]] with descriptive text instead — it already opens the file.
-- Aim for most sentences about code to have at least one [[line:...]](...) reference.
-
-GOOD example:
-"The [[group:Auth Flow]] group introduces session management. [[line:src/auth/session.ts#L15-L30]](The new validateToken function) handles JWT parsing, and [[line:src/auth/middleware.ts#L8-L12]](the auth middleware) invokes it on every request."
-
-BAD example (DO NOT do this):
-"The new validateToken function [[line:src/auth/session.ts#L15-L30]] in [[file:src/auth/session.ts]] handles JWT parsing."`,
+
+## Goal
+Write a narrative that tells the "story" of this PR — what was changed, why, and how the pieces connect. The reader should finish with a clear mental model of the PR.
+
+## Writing Style
+- Write in flowing prose paragraphs. This is a narrative, not a changelog.
+- Do NOT use horizontal rules (---), dividers, or excessive headers. Let the prose flow naturally.
+- Use ### headers ONLY for major conceptual sections (2-4 max for the whole narrative). Prefer topic sentences over headers.
+- Default to prose. Use bullet lists only for 3+ parallel items that are genuinely list-like (e.g., list of API endpoints, config options). Never list things that would read better as a sentence.
+- Use tables only when comparing structured data (e.g., before/after schemas, flag mappings).
+- Keep paragraphs short (3-5 sentences). Human working memory holds ~4 chunks — each paragraph should be one coherent idea.
+- Lead each paragraph with a topic sentence that states the key point. Supporting details follow.
+- Use transition phrases to connect paragraphs naturally. If writing in a non-English language, use idiomatic transitions in THAT language — never insert English phrases like "Building on this" into non-English text.
+- Use commit history and PR discussion to understand the development progression.
+
+## Anchor Syntax (CRITICAL — this is how readers navigate from your text to the actual code)
+
+There are THREE anchor types. You MUST use ALL of them.
+
+### Group Anchors (MANDATORY)
+- Format: [[group:Exact Group Name]]
+- Renders as a clickable blue chip.
+- You MUST reference EVERY group from the Change Groups list at least once. No exceptions.
+- Use group anchors when introducing a topic area or explaining what a set of changes accomplishes together.
+- Example: "The [[group:Auth Flow]] group introduces session management."
+
+### File Anchors
+- Format: [[file:exact/path/to/file.ts]]
+- Renders as a clickable blue chip that opens the file diff.
+- Use when referencing a file generally (not a specific line), or when you don't have exact line numbers.
+- Use EXACT file paths from the Change Groups context.
+- Example: "Configuration is defined in [[file:src/config/auth.ts]]."
+
+### Line Anchors
+- Format: [[line:path/to/file.ts#L42-L50]](descriptive text)
+- The "descriptive text" becomes a subtle underlined link. Line numbers are NOT visible.
+- Use for specific code changes — functions, types, config fields, imports.
+
+### Usage Rules:
+- ALWAYS use [[line:path#Lstart-Lend]](text) with BOTH start and end lines. Single lines: [[line:path#L42-L42]](text).
+- The (text) must describe WHAT the code does, not WHERE it is. Bad: "lines 42-50". Good: "the new rate limiter middleware".
+- Wrap EVERY specific code mention in a line anchor. If you mention a function, class, type, constant, config change, or import — anchor it.
+- Interleave anchors naturally within sentences. They should feel like hyperlinks in a wiki article.
+- Do NOT pair [[file:...]] with [[line:...]] for the same file. The line anchor already opens the file.
+- Use the diff context provided to find accurate line numbers. If unsure of exact lines, use [[file:...]] instead.
+
+### Anchor Density — TWO levels:
+When describing a function or class, use anchors at TWO granularity levels:
+
+**Level 1 — Declaration**: Anchor the function/class name itself to its full definition range.
+**Level 2 — Implementation details**: When explaining what the code does, anchor EACH distinct piece of logic to its specific lines within the function.
+
+Example with two levels:
+"[[line:src/auth/session.ts#L15-L50]](The validateToken function) handles the full JWT lifecycle. It [[line:src/auth/session.ts#L18-L22]](extracts the token from the Authorization header), [[line:src/auth/session.ts#L24-L30]](verifies the signature against the configured secret), and [[line:src/auth/session.ts#L32-L40]](checks the expiration timestamp). If validation fails, [[line:src/auth/session.ts#L42-L48]](it throws a typed AuthError with a specific error code)."
+
+Key principles:
+- The first anchor covers the entire function (L15-L50). Subsequent anchors zoom into specific parts within it.
+- Each sub-anchor should cover 2-10 lines — one logical step.
+- Descriptive text for sub-anchors should explain the step, not name the function again.
+
+### Line Anchor Granularity:
+- Anchor individual functions, not entire files: [[line:auth.ts#L15-L30]](validateToken) not [[line:auth.ts#L1-L200]](auth module)
+- Anchor key type definitions: [[line:types.ts#L5-L12]](the new UserSession interface)
+- Anchor config/schema changes: [[line:schema.ts#L42-L45]](the added rate_limit field)
+- Anchor imports and exports that wire things together: [[line:index.ts#L3-L3]](re-exported from the barrel file)
+- For multi-part changes, anchor each part separately
+
+GOOD example (uses all 3 anchor types + two-level density):
+"The [[group:Auth Flow]] group introduces session management. [[line:src/auth/session.ts#L15-L50]](The new validateToken function) handles JWT parsing: [[line:src/auth/session.ts#L18-L22]](it extracts the token from the header), then [[line:src/auth/session.ts#L24-L35]](verifies the signature and checks expiration). [[line:src/auth/middleware.ts#L8-L20]](The auth middleware) invokes it on every request, [[line:src/auth/middleware.ts#L15-L18]](rejecting invalid tokens with a 401). Supporting configuration lives in [[file:src/auth/constants.ts]]."
+
+BAD examples:
+- No group anchors: "The auth changes introduce session management." (MUST use [[group:Auth Flow]])
+- No anchors in implementation details: "The validateToken function extracts the token, verifies the signature, and checks expiration." (MUST anchor each step separately)
+- One big anchor for everything: "[[line:session.ts#L15-L50]](The function extracts tokens, verifies signatures, and checks expiration)" (MUST split into sub-anchors)
+- Bare line anchor: "[[line:src/auth/session.ts#L15-L30]]" (MUST have (text) after it)
+
+${lang ? `CRITICAL: Write the ENTIRE narrative in ${lang}. Every sentence must be in ${lang}. Do NOT use English except for code identifiers, file paths, and anchor tokens.` : "If the PR title is in a non-English language, write the narrative in that same language."}`,
 		user: `PR Title: ${prTitle}\n\nSummary:\n- Purpose: ${summary.purpose}\n- Scope: ${summary.scope}\n- Impact: ${summary.impact}\n- Risk: ${summary.risk_level}\n\nChange Groups:\n${groupDetails}${commitCtx}${discussionCtx}${diffContext}`,
 	};
 }
@@ -194,6 +247,9 @@ function formatCodebaseContext(exploration: ExplorationResult): string {
 	if (exploration.potential_issues) {
 		sections.push(`=== Potential Issues (from codebase analysis) ===\n${exploration.potential_issues}`);
 	}
+	if (exploration.react_doctor) {
+		sections.push(`=== React Doctor Analysis (react-doctor) ===\n${exploration.react_doctor}`);
+	}
 	return sections.join("\n\n");
 }
 
@@ -229,9 +285,8 @@ export function buildEnrichedNarrativePrompt(
 
 	return {
 		system: `${base.system}
-You have access to full codebase analysis. Use it to explain HOW the changes relate to existing code, not just WHAT changed.
-Mention specific existing functions, modules, or patterns that are affected.
-Use [[group:Name]], [[file:path]], and [[line:path#L42-L50]](descriptive text) as instructed above.`,
+
+You have full codebase analysis below. Use it to explain HOW the changes relate to existing code — mention specific existing functions, patterns, and callers that are affected. This context should enrich your line anchor usage with cross-references to existing code.`,
 		user: `${base.user}\n\n--- CODEBASE CONTEXT (from agentic exploration) ---\n${context}`,
 	};
 }