critique 0.1.39 → 0.1.41

package/CHANGELOG.md

@@ -1,3 +1,16 @@
+# 0.1.41
+
+- `review` command:
+  - Filter `--resume` reviews by current working directory (only shows reviews from cwd or subdirectories)
+  - Use ACP `unstable_listSessions` for OpenCode instead of parsing JSON files directly
+  - Falls back to file-based parsing for Claude Code when ACP method unavailable
+  - Add instruction to always close code blocks before new text (fixes unclosed diagram blocks)
+
+# 0.1.40
+
+- `review` command:
+  - Increased session/review picker limits from 10/20 to 25 for both ACP sessions and `--resume`
+
 # 0.1.39
 
 - `review` command:

package/package.json

@@ -2,7 +2,7 @@
   "name": "critique",
   "module": "src/diff.tsx",
   "type": "module",
-  "version": "0.1.39",
+  "version": "0.1.41",
   "private": false,
   "bin": "./src/cli.tsx",
   "scripts": {

package/scripts/preview-review.tsx

@@ -1,7 +1,7 @@
 #!/usr/bin/env bun
-// Preview script for ReviewApp component
-// Run with: bun run scripts/preview-review.tsx
-// Web mode: bun run scripts/preview-review.tsx --web
+// Development preview script for testing ReviewApp styles without running AI.
+// Renders example hunks and review data to preview TUI appearance.
+// Run with: bun run scripts/preview-review.tsx (TUI) or --web (HTML upload).
 
 import { createCliRenderer } from "@opentui/core"
 import { createRoot } from "@opentui/react"

package/src/ansi-html.ts

@@ -1,3 +1,7 @@
+// ANSI terminal output to HTML converter for web preview generation.
+// Uses ghostty-opentui to parse PTY output and generates responsive HTML documents
+// with proper font scaling to fit terminal content within viewport width.
+
 import { ptyToJson, StyleFlags, type TerminalData, type TerminalLine, type TerminalSpan } from "ghostty-opentui"
 
 export interface AnsiToHtmlOptions {

package/src/cli.tsx

@@ -1,4 +1,8 @@
 #!/usr/bin/env bun
+// CLI entrypoint for the critique diff viewer.
+// Provides TUI diff viewing, AI-powered review generation, and web preview upload.
+// Commands: default (diff), review (AI analysis), web (HTML upload), pick (cherry-pick files).
+
 import { cac } from "cac";
 import {
   createRoot,
@@ -338,7 +342,7 @@ async function runReviewMode(
           return `${days}d ago`;
         };
 
-        // Filter out critique-generated sessions and ACP sessions, limit to first 10
+        // Filter out critique-generated sessions and ACP sessions, limit to first 25
         const filteredSessions = sessions
           .filter((s) => {
             // Filter by _meta if the agent supports it
@@ -350,7 +354,7 @@ async function runReviewMode(
             if (title.includes("review a git diff")) return false
             return true
           })
-          .slice(0, 10);
+          .slice(0, 25);
 
         // Non-TTY mode: log available sessions for agents to use with --session
         if (!process.stdin.isTTY) {
@@ -667,19 +671,19 @@ async function runResumeMode(options: ResumeModeOptions) {
 
   let reviewId = options.reviewId;
 
-  // If no ID provided, show select
+  // If no ID provided, show select (filtered to current cwd and children)
   if (!reviewId) {
-    const reviews = listReviews();
+    const reviews = listReviews(process.cwd());
 
     if (reviews.length === 0) {
-      clack.log.warn("No saved reviews found");
+      clack.log.warn("No saved reviews found for this directory");
       clack.outro("");
       process.exit(0);
     }
 
     const selected = await clack.select({
       message: "Select a review to display",
-      options: reviews.slice(0, 20).map((r) => {
+      options: reviews.slice(0, 25).map((r) => {
         // Show status and time in label to avoid layout shifts (hints only show on focus)
         const status = r.status === "in_progress" ? pc.default.yellow(" (in progress)") : "";
         const time = formatTimeAgo(r.updatedAt);

package/src/components/diff-view.tsx

@@ -1,4 +1,6 @@
-// Shared DiffView component for rendering git diffs with syntax highlighting
+// Shared DiffView component for rendering git diffs with syntax highlighting.
+// Wraps opentui's <diff> element with theme-aware colors and syntax styles.
+// Supports split and unified view modes with line numbers.
 
 import * as React from "react"
 import { SyntaxStyle } from "@opentui/core"

package/src/components/index.ts

@@ -1,2 +1,4 @@
-// Shared components
+// Shared React components for the TUI interface.
+// Exports reusable components used across main diff view and review mode.
+
 export { DiffView, type DiffViewProps } from "./diff-view.tsx"

package/src/diff-utils.ts

@@ -1,4 +1,6 @@
-// Shared utilities for diff processing between CLI commands
+// Shared utilities for git diff processing across CLI commands.
+// Builds git commands, parses diff files, detects filetypes for syntax highlighting,
+// and provides helpers for unified/split view mode selection.
 
 export const IGNORED_FILES = [
   "pnpm-lock.yaml",

package/src/dropdown.tsx

@@ -1,3 +1,7 @@
+// Searchable dropdown component for file and theme selection in TUI.
+// Supports keyboard navigation, fuzzy search filtering, and mouse interaction.
+// Used by main diff view for file picker and theme picker overlays.
+
 import React, { useState, useEffect, useRef, useCallback, type ReactNode } from "react";
 import { useKeyboard } from "@opentui/react";
 import { TextAttributes, TextareaRenderable } from "@opentui/core";

package/src/logger.ts

@@ -1,4 +1,6 @@
-// Debug logger that writes to console and app.log when DEBUG=true
+// Debug logger that writes to console and app.log when DEBUG=true.
+// Provides log levels (log, info, warn, error, debug) with timestamps.
+// Disabled in production; enable with DEBUG=true or DEBUG=1 environment variable.
 
 import fs from "fs"
 import { join } from "path"

package/src/monochrome.ts

@@ -1,3 +1,7 @@
+// Monochrome theme generator for creating grayscale color schemes.
+// Generates VS Code-compatible themes by blending between background and foreground.
+// Supports various contrast levels from subtle to amplified.
+
 type VSCodeTheme = {
   name: string;
   type: "light" | "dark";

package/src/monotone.ts

@@ -1,3 +1,7 @@
+// Monotone theme generator for creating single-hue color schemes.
+// Generates VS Code-compatible themes from a base hue with configurable saturation.
+// Used for creating consistent color palettes across light and dark variants.
+
 type VSCodeTheme = {
   name: string;
   type: "light" | "dark";

package/src/review/acp-client.ts

@@ -1,4 +1,6 @@
-// ACP client for connecting to AI agents (opencode or claude)
+// ACP (Agent Client Protocol) client for communicating with AI coding assistants.
+// Supports OpenCode and Claude Code agents for session listing, content loading,
+// and creating AI-powered review sessions with streaming updates.
 
 import {
   ClientSideConnection,
@@ -157,100 +159,66 @@ export class AcpClient {
 
   /**
    * List sessions for the given working directory
-   * Uses CLI command for opencode, parses JSONL files for claude
+   * Uses ACP unstable_listSessions, falls back to file parsing for Claude
+   * @param cwd - Working directory to filter sessions by
+   * @param limit - Maximum number of sessions to return (default: 10)
    */
-  async listSessions(cwd: string): Promise<SessionInfo[]> {
-    if (this.agent === "opencode") {
-      return this.listOpencodeSessions(cwd)
-    } else {
-      return this.listClaudeSessions(cwd)
+  async listSessions(cwd: string, limit = 10): Promise<SessionInfo[]> {
+    await this.ensureConnected()
+    if (!this.client) {
+      throw new Error("Client connection failed")
     }
-  }
 
-  /**
-   * List OpenCode sessions by reading directly from storage
-   * Storage location: ~/.local/share/opencode/storage/
-   */
-  private async listOpencodeSessions(cwd: string): Promise<SessionInfo[]> {
-    const storageDir = path.join(os.homedir(), ".local", "share", "opencode", "storage")
-    const projectsDir = path.join(storageDir, "project")
-    const sessionsDir = path.join(storageDir, "session")
+    // Try ACP unstable_listSessions first
+    try {
+      const sessions: SessionInfo[] = []
+      let cursor: string | undefined
 
-    if (!fs.existsSync(projectsDir)) {
-      return []
-    }
+      // Paginate until we have enough sessions or no more results
+      while (sessions.length < limit) {
+        const response = await this.client.unstable_listSessions({
+          cwd,
+          cursor,
+        })
 
-    // Find ALL project IDs for the given cwd (there can be multiple)
-    const projectIds: string[] = []
-    try {
-      const projectFiles = fs.readdirSync(projectsDir).filter(f => f.endsWith(".json"))
-      for (const file of projectFiles) {
-        try {
-          const content = fs.readFileSync(path.join(projectsDir, file), "utf-8")
-          const project = JSON.parse(content) as { id: string; worktree: string }
-          if (project.worktree === cwd) {
-            projectIds.push(project.id)
-          }
-        } catch {
-          // Skip invalid project files
-        }
-      }
-    } catch (e) {
-      logger.debug("Failed to scan opencode projects", { error: e })
-      return []
-    }
+        // Convert ACP SessionInfo to our local type
+        for (const acpSession of response.sessions) {
+          if (sessions.length >= limit) break
 
-    if (projectIds.length === 0) {
-      return []
-    }
+          sessions.push({
+            sessionId: acpSession.sessionId,
+            cwd: acpSession.cwd,
+            title: acpSession.title ?? undefined,
+            // Convert ISO 8601 string to timestamp (milliseconds)
+            updatedAt: acpSession.updatedAt ? new Date(acpSession.updatedAt).getTime() : undefined,
+            _meta: acpSession._meta,
+          })
+        }
 
-    // Read sessions from ALL matching projects
-    const sessions: SessionInfo[] = []
-    for (const projectId of projectIds) {
-      const projectSessionsDir = path.join(sessionsDir, projectId)
-      if (!fs.existsSync(projectSessionsDir)) {
-        continue
+        // Check if there are more pages
+        if (!response.nextCursor) break
+        cursor = response.nextCursor
       }
 
-      try {
-        const sessionFiles = fs.readdirSync(projectSessionsDir).filter(f => f.endsWith(".json"))
-        for (const file of sessionFiles) {
-          try {
-            const content = fs.readFileSync(path.join(projectSessionsDir, file), "utf-8")
-            const session = JSON.parse(content) as {
-              id: string
-              title?: string
-              directory: string
-              time: { created: number; updated: number }
-              _meta?: { [key: string]: unknown } | null
-            }
-            sessions.push({
-              sessionId: session.id,
-              cwd: session.directory,
-              title: session.title,
-              updatedAt: session.time.updated,
-              _meta: session._meta,
-            })
-          } catch {
-            // Skip invalid session files
-          }
-        }
-      } catch (e) {
-        logger.debug("Failed to read opencode sessions for project", { projectId, error: e })
+      // Sessions should already be sorted by the server, but ensure descending order
+      return sessions.sort((a, b) => (b.updatedAt || 0) - (a.updatedAt || 0))
+    } catch (error) {
+      // Fall back to file-based listing for agents that don't support listSessions
+      logger.debug("ACP listSessions not supported, falling back to file parsing", { error })
+      if (this.agent === "claude") {
+        return this.listClaudeSessions(cwd, limit)
       }
+      throw error
     }
-
-    // Filter to exact cwd match and sort by updatedAt descending
-    return sessions
-      .filter(s => s.cwd === cwd)
-      .sort((a, b) => (b.updatedAt || 0) - (a.updatedAt || 0))
   }
 
   /**
-   * List Claude Code sessions by parsing JSONL files
+   * List Claude Code sessions by parsing JSONL files (fallback)
    * Sessions are stored in ~/.claude/projects/<path-encoded>/
+   * @param cwd - Working directory to filter sessions by
+   * @param limit - Maximum number of sessions to return
    */
-  private async listClaudeSessions(cwd: string): Promise<SessionInfo[]> {
+  private async listClaudeSessions(cwd: string, limit: number): Promise<SessionInfo[]> {
     // Claude stores sessions in ~/.claude/projects/ with path encoded (/ -> -)
     const claudeDir = path.join(os.homedir(), ".claude", "projects")
     const encodedPath = cwd.replace(/\//g, "-")
@@ -313,8 +281,10 @@ export class AcpClient {
       return []
     }
 
-    // Sort by updatedAt descending (most recent first)
-    return sessions.sort((a, b) => (b.updatedAt || 0) - (a.updatedAt || 0))
+    // Sort by updatedAt descending (most recent first) and apply limit
+    return sessions
+      .sort((a, b) => (b.updatedAt || 0) - (a.updatedAt || 0))
+      .slice(0, limit)
   }
 
   /**
@@ -552,7 +522,8 @@ HOW TO EXPLAIN - Diagrams First, Text Last
 ═══════════════════════════════════════════════════════════════════════════════
 
 PREFER ASCII DIAGRAMS - they explain better than words.
-ALWAYS wrap diagrams in \`\`\`diagram code blocks - never render them as plain text:
+ALWAYS wrap diagrams in \`\`\`diagram code blocks - never render them as plain text.
+CRITICAL: Always close each code block with \`\`\` before any new text or heading. Never leave code blocks unclosed.
 
 \`\`\`diagram
 ┌─────────────┐      ┌─────────────┐      ┌────────────┐

package/src/review/acp-stream-display.ts

@@ -1,5 +1,6 @@
-// Format ACP session notifications for streaming display
-// Shows agent activity while waiting for YAML to be parsed
+// Formatter for ACP session notifications into displayable stream lines.
+// Accumulates consecutive chunks (thinking, messages) and formats tool calls
+// with symbols and colors for the streaming display component.
 
 import type { SessionNotification } from "@agentclientprotocol/sdk"
 

package/src/review/diagram-parser.ts

@@ -1,5 +1,6 @@
-// Diagram parser - parses ASCII/Unicode diagrams into colored segments
-// Used to highlight structural characters (boxes, arrows, lines) differently from text
+// ASCII/Unicode diagram parser for syntax highlighting in markdown code blocks.
+// Separates structural characters (box-drawing, arrows) from text content
+// to render diagrams with muted structural elements and highlighted labels.
 
 /**
  * A segment of text with a specific color type

package/src/review/hunk-parser.ts

@@ -1,4 +1,6 @@
-// Parse git diff into indexed hunks for AI review
+// Git diff parser that creates indexed hunks for AI review processing.
+// Supports hunk splitting for progressive disclosure, coverage tracking,
+// and generates context XML for AI prompts with cat -n style line numbers.
 
 import type { IndexedHunk, HunkCoverage, ReviewCoverage, UncoveredPortion, ReviewGroup } from "./types.ts"
 import { IGNORED_FILES } from "../diff-utils.ts"

package/src/review/index.ts

@@ -1,5 +1,6 @@
-// Review module - AI-powered diff review using ACP
-// Exports for use in CLI
+// AI-powered diff review module using Agent Client Protocol (ACP).
+// Coordinates with OpenCode or Claude Code to generate progressive disclosure reviews.
+// Re-exports all review functionality for use by the CLI.
 
 export {
   parseHunksWithIds,

package/src/review/review-app.test.tsx

@@ -1281,6 +1281,230 @@ Added logger import.`,
                                                                                       
                                                                                       
                                                                                       
+        (1 section)  t theme                   run with --web to share & collaborate  
+                                                                                      
+      "
+    `)
+  })
+
+  it("should document behavior with unclosed diagram code block (AI-generated malformed markdown)", async () => {
+    // This test documents the behavior when AI generates malformed markdown with an unclosed
+    // diagram code block. The first \`\`\`diagram is never closed before **The Solution:**
+    // appears, causing the parser to treat everything as one code block.
+    //
+    // ROOT CAUSE: The AI generated markdown like this:
+    //   **The Problem:**
+    //   \`\`\`diagram
+    //   ...first diagram...
+    //   **The Solution:**       <-- MISSING closing \`\`\` before this!
+    //   \`\`\`diagram
+    //   ...second diagram...
+    //   \`\`\`
+    //
+    // RESULT: marked parser correctly follows markdown spec - everything from first
+    // \`\`\`diagram to the final \`\`\` becomes ONE code block, including:
+    // - "**The Solution:**" as literal text (not bold)
+    // - "\`\`\`diagram" as literal text (not a new code block)
+    //
+    // FIX: AI should generate proper markdown with closing \`\`\` after each diagram.
+    const bugHunk = createHunk(1, "src/config.ts", 0, 1, 1, [
+      "+export const x = 1",
+    ])
+
+    // MALFORMED markdown - first diagram missing closing backticks
+    const malformedMarkdown = `## ActionPanel captures actions to zustand, ActionsDialog renders them
+
+**The Problem:**
+\`\`\`diagram
+BEFORE: Context lost when rendering in dialog
++-----------------------+          +------------------+
+| ListItem              |  push()  | DialogOverlay    |
+| (has useNavigation,   | -------> | (different React |
+|  useFormContext, etc) |          |  tree, no access |
++-----------------------+          |  to contexts)    |
+                                   +------------------+
+
+**The Solution:**
+\`\`\`diagram
+AFTER: Closures preserve context
++------------------------+  capture   +----------------+
+| ListItem               | ---------> | zustand        |
+| <Offscreen>            |  execute() | capturedActions|
+|   <ActionPanel>        |  closures  +-------+--------+
+|     <Action execute={  |                    |
+|       () => push(...)  | <----- closure     | read
+|     }/>                |   retains context  v
+|   </ActionPanel>       |            +----------------+
+| </Offscreen>           |            | ActionsDialog  |
++------------------------+            | (calls execute)|
+                                      +----------------+
+\`\`\`
+
+\`ActionsDialog\` groups actions by section.`
+
+    const bugReviewData: ReviewYaml = {
+      hunks: [{
+        hunkIds: [1],
+        markdownDescription: malformedMarkdown,
+      }],
+    }
+
+    testSetup = await testRender(
+      <ReviewAppView
+        hunks={[bugHunk]}
+        reviewData={bugReviewData}
+        isGenerating={false}
+        themeName="github"
+        width={100}
+      />,
+      { width: 100, height: 50 },
+    )
+
+    await testSetup.renderOnce()
+    const frame = testSetup.captureCharFrame()
+    // Documents the incorrect rendering when markdown is malformed:
+    // - "**The Solution:**" appears as literal text inside code block
+    // - "\`\`\`diagram" appears as literal text
+    // - Both diagrams merge into one big code block
+    expect(frame).toMatchInlineSnapshot(`
+      "                                                                                                    
+                 ActionPanel captures actions to zustand, ActionsDialog renders them                      
+                                                                                                          
+                 The Problem:                                                                             
+                                                                                                          
+                 BEFORE: Context lost when rendering in dialog                                            
+                 +-----------------------+          +------------------+                                  
+                 | ListItem              |  push()  | DialogOverlay    |                                  
+                 | (has useNavigation,   | -------> | (different React |                                  
+                 |  useFormContext, etc) |          |  tree, no access |                                  
+                 +-----------------------+          |  to contexts)    |                                  
+                                                    +------------------+                                  
+                                                                                                          
+                 **The Solution:**                                                                        
+                 \`\`\`diagram                                                                               
+                 AFTER: Closures preserve context                                                         
+                 +------------------------+  capture   +----------------+                                 
+                 | ListItem               | ---------> | zustand        |                                 
+                 | <Offscreen>            |  execute() | capturedActions|                                 
+                 |   <ActionPanel>        |  closures  +-------+--------+                                 
+                 |     <Action execute={  |                    |                                          
+                 |       () => push(...)  | <----- closure     | read                                     
+                 |     }/>                |   retains context  v                                          
+                 |   </ActionPanel>       |            +----------------+                                 
+                 | </Offscreen>           |            | ActionsDialog  |                                 
+                 +------------------------+            | (calls execute)|                                 
+                                                       +----------------+                                 
+                                                                                                          
+                 ActionsDialog groups actions by section.                                                 
+                                                                                                          
+                                                                                                          
+       rc/config.ts +1-0                                                                                  
+                                                                                                          
+        + export const x = 1                                                                              
+                                                                                                          
+                                                                                                          
+                                                                                                          
+                                                                                                          
+                                                                                                          
+                                                                                                          
+                                                                                                          
+                                                                                                          
+                                                                                                          
+                                                                                                          
+                                                                                                          
+                                                                                                          
+                                                                                                          
+                                                                                                          
+        (1 section)  t theme                                       run with --web to share & collaborate  
+                                                                                                          
+      "
+    `)
+  })
+
+  it("should render TWO separate diagrams when markdown is properly formatted", async () => {
+    // This test shows the CORRECT behavior when markdown has proper closing backticks
+    const goodHunk = createHunk(1, "src/config.ts", 0, 1, 1, [
+      "+export const x = 1",
+    ])
+
+    // CORRECT markdown - each diagram properly closed with \`\`\`
+    const correctMarkdown = `## ActionPanel captures actions to zustand
+
+**The Problem:**
+\`\`\`diagram
+BEFORE: Context lost
++-----------+   +-----------+
+| ListItem  |-->| Dialog    |
++-----------+   +-----------+
+\`\`\`
+
+**The Solution:**
+\`\`\`diagram
+AFTER: Closures preserve
++-----------+   +-----------+
+| Offscreen |-->| zustand   |
++-----------+   +-----------+
+\`\`\`
+
+\`ActionsDialog\` groups actions by section.`
+
+    const goodReviewData: ReviewYaml = {
+      hunks: [{
+        hunkIds: [1],
+        markdownDescription: correctMarkdown,
+      }],
+    }
+
+    testSetup = await testRender(
+      <ReviewAppView
+        hunks={[goodHunk]}
+        reviewData={goodReviewData}
+        isGenerating={false}
+        themeName="github"
+        width={80}
+      />,
+      { width: 80, height: 35 },
+    )
+
+    await testSetup.renderOnce()
+    const frame = testSetup.captureCharFrame()
+    // With proper markdown:
+    // - "**The Problem:**" and "**The Solution:**" should render as bold text
+    // - Each diagram should be a separate code block
+    expect(frame).toMatchInlineSnapshot(`
+      "                                                                                
+         ActionPanel captures actions to zustand                                      
+                                                                                      
+         The Problem:                                                                 
+                                                                                      
+         BEFORE: Context lost                                                         
+         +-----------+   +-----------+                                                
+         | ListItem  |-->| Dialog    |                                                
+         +-----------+   +-----------+                                                
+                                                                                      
+         The Solution:                                                                
+                                                                                      
+         AFTER: Closures preserve                                                     
+         +-----------+   +-----------+                                                
+         | Offscreen |-->| zustand   |                                                
+         +-----------+   +-----------+                                                
+                                                                                      
+         ActionsDialog groups actions by section.                                     
+                                                                                      
+                                                                                      
+       rc/config.ts +1-0                                                              
+                                                                                      
+        + export const x = 1                                                          
+                                                                                      
+                                                                                      
+                                                                                      
+                                                                                      
+                                                                                      
+                                                                                      
+                                                                                      
+                                                                                      
+                                                                                      
+                                                                                      
         (1 section)  t theme                   run with --web to share & collaborate  
                                                                                       
       "

package/src/review/review-app.tsx

@@ -1,4 +1,6 @@
-// ReviewApp - TUI component for AI-powered diff review
+// ReviewApp - Main TUI component for AI-powered diff review.
+// Renders streaming review content with markdown descriptions and diff hunks.
+// Supports live generation updates, theme switching, and resume from saved reviews.
 
 import * as React from "react"
 import { useKeyboard, useRenderer, useTerminalDimensions } from "@opentui/react"

package/src/review/session-context.ts

@@ -1,4 +1,6 @@
-// Compress ACP session content into context for AI prompt
+// Session context compression for including coding session history in AI prompts.
+// Extracts key actions (tool calls, messages, thinking) from ACP notifications
+// and formats them as XML context to help the AI understand why changes were made.
 
 import type { SessionNotification } from "@agentclientprotocol/sdk"
 import type { CompressedSession, SessionContent } from "./types.ts"

package/src/review/storage.ts

@@ -1,6 +1,6 @@
-// Storage utilities for persisting review sessions
-// Reviews are stored as JSON files in ~/.critique/reviews/
-// File is written on process exit/completion to prevent concurrent access issues
+// Persistent storage for review sessions in ~/.critique/reviews/.
+// Saves review state on exit/completion, enables resume of interrupted reviews,
+// and provides listing with automatic cleanup of old reviews (max 50).
 
 import fs from "fs"
 import { join } from "path"
@@ -77,10 +77,11 @@ export function saveReview(review: StoredReview): void {
 }
 
 /**
- * List all reviews, sorted by updatedAt descending (most recent first)
+ * List reviews, sorted by updatedAt descending (most recent first)
  * Returns metadata only (no full content) for performance
+ * @param cwd - If provided, only return reviews from this directory or its children
  */
-export function listReviews(): ReviewMetadata[] {
+export function listReviews(cwd?: string): ReviewMetadata[] {
   ensureReviewsDir()
   
   const files = fs.readdirSync(REVIEWS_DIR)
@@ -94,6 +95,11 @@ export function listReviews(): ReviewMetadata[] {
       const content = fs.readFileSync(filepath, "utf-8")
       const data = JSON.parse(content) as StoredReview
       
+      // Filter by cwd if provided: include reviews from cwd or its children
+      if (cwd && !data.cwd.startsWith(cwd)) {
+        continue
+      }
+      
       reviews.push({
         id: data.id,
         createdAt: data.createdAt,

package/src/review/stream-display.tsx

@@ -1,5 +1,6 @@
-// StreamDisplay - TUI component for showing ACP streaming events
-// Displays agent activity while waiting for YAML to be parsed
+// StreamDisplay - TUI component for showing ACP streaming events.
+// Renders real-time agent activity (thinking, messages, tool calls) during review generation.
+// Shows formatted tool operations with file names and edit statistics.
 
 import * as React from "react"
 import { SyntaxStyle } from "@opentui/core"

package/src/review/types.ts

@@ -1,4 +1,6 @@
-// Types for the AI-powered diff review feature
+// Type definitions for the AI-powered diff review feature.
+// Defines IndexedHunk, ReviewYaml, ReviewGroup structures for diff analysis,
+// plus coverage tracking and session context types for ACP integration.
 
 import type { SessionNotification } from "@agentclientprotocol/sdk"
 

package/src/review/yaml-watcher.ts

@@ -1,4 +1,6 @@
-// Watch and parse streaming YAML output from AI review
+// File watcher for streaming YAML output from AI review generation.
+// Parses partial YAML as the AI writes it, enabling progressive UI updates.
+// Handles incomplete YAML gracefully during generation.
 
 import fs from "fs"
 import YAML from "js-yaml"

package/src/store.ts

@@ -1,5 +1,6 @@
-// Global zustand store for critique app
-// Shared between main diff view and review view
+// Global Zustand store for persistent application state.
+// Manages theme selection with automatic persistence to ~/.critique/state.json.
+// Shared between main diff view and review view components.
 
 import { create } from "zustand"
 import fs from "fs"

package/src/themes.ts

@@ -1,5 +1,6 @@
-// Syntax highlighting themes for critique
-// Source: https://github.com/sst/opencode/tree/main/packages/opencode/src/cli/cmd/tui/context/theme
+// Syntax highlighting theme system with 30+ themes from OpenCode.
+// Loads JSON theme files lazily on demand, resolves color references,
+// and provides both UI colors and Tree-sitter compatible syntax styles.
 
 import { parseColor, RGBA } from "@opentui/core";
 

package/src/utils.ts

@@ -1,3 +1,6 @@
+// General utility functions used across the application.
+// Currently provides debounce for rate-limiting file watcher callbacks.
+
 export function debounce<T extends (...args: any[]) => any>(
   fn: T,
   delay: number

package/src/web-utils.ts

@@ -1,5 +1,6 @@
-// Shared utilities for web preview generation
-// Used by both `web` and `explain --web` commands
+// Web preview generation utilities for uploading diffs to critique.work.
+// Captures PTY output using Bun.Terminal, converts to HTML with responsive layout,
+// and uploads desktop/mobile versions for shareable diff viewing.
 
 import { exec } from "child_process"
 import { promisify } from "util"

package/src/worker.ts

@@ -1,3 +1,7 @@
+// Cloudflare Worker for hosting HTML diff previews at critique.work.
+// Handles upload, storage (KV), and responsive serving of desktop/mobile HTML versions.
+// Endpoints: POST /upload, GET /v/:id (view), GET /raw/:id (debug).
+
 import { Hono } from "hono"
 import { cors } from "hono/cors"
 import { stream } from "hono/streaming"