diffprism 0.48.2 → 1.0.0

package/README.md

@@ -29,7 +29,7 @@ Then in Claude Code:
   → calls get_file_diff + get_file_context → full file from your local clone
 
 > Flag line 47 as a concern
-  → calls add_review_comment → annotation appears on the diff in your browser
+  → calls annotate → annotation appears on the diff in your browser
 ```
 
 ## Setup
@@ -57,24 +57,16 @@ The server auto-detects your local clone by matching `git remote -v` against the
 
 ## MCP Tools
 
-DiffPrism exposes 14 MCP tools to your AI:
+DiffPrism exposes 14 MCP tools to your AI.
 
-### PR Review
-| Tool | Purpose |
-|------|---------|
-| `get_pr_context` | High-level PR overview: metadata, briefing, file list, local repo status |
-| `get_file_diff` | Diff hunks for a specific file with triage category |
-| `get_file_context` | Full file content from local repo via `git show` |
-| `add_review_comment` | Post a comment that appears inline on the diff in real-time |
-| `get_review_comments` | Read all comments and annotations on the session |
-| `get_user_focus` | What file/line the user is currently viewing in the browser |
+Reviews are **one per repo**: opening a review for a repo that already has one updates it instead of starting another, and keeps its annotations. Tools that work on an open review act on the one for the repo your AI is running in, or take `session_id` / `repo_path` — and if that's ambiguous they say so rather than guess.
 
-### Review Lifecycle
+### Opening and deciding
 | Tool | Purpose |
 |------|---------|
-| `open_review` | Open browser review UI for local changes or a GitHub PR |
-| `get_review_result` | Fetch result from a previous review |
-| `update_review_context` | Push updated reasoning/description to a running session |
+| `open_review` | Open a review of local changes and **wait for the decision** (`wait: false` to return at once) |
+| `get_review_result` | Check the decision on a review already open |
+| `update_review_context` | Push updated reasoning/description to an open review |
 
 ### Analysis
 | Tool | Purpose |
@@ -82,12 +74,37 @@ DiffPrism exposes 14 MCP tools to your AI:
 | `analyze_diff` | Returns analysis JSON (patterns, complexity, test gaps) |
 | `get_diff` | Returns structured diff JSON (file-level and hunk-level changes) |
 
-### Annotation
+### Working in an open review
 | Tool | Purpose |
 |------|---------|
-| `add_annotation` | Post a structured finding on a specific line |
-| `flag_for_attention` | Mark files for human attention |
-| `get_review_state` | Get current state of a session including all annotations |
+| `annotate` | Post findings inline on the diff; `warning` flags the session for attention |
+| `get_review_comments` | Read every thread on the session; `awaiting_reply` narrows to unanswered ones |
+| `reply` | Reply to a thread — answer the reviewer's question on a line |
+| `wait_for_comments` | Block until the reviewer writes something the agent hasn't answered |
+| `get_review_state` | Session status, attention and new-changes flags, and annotations |
+| `get_user_focus` | What file/line the user is currently viewing in the browser |
+| `get_pr_context` | High-level PR overview: metadata, briefing, file list, local repo status |
+| `get_file_diff` | Diff hunks for a specific file with triage category |
+| `get_file_context` | Full file content from local repo via `git show` |
+
+In a local review, **Ask agent now** in a line's comment form asks the agent while you're still reviewing: the agent's wait for your decision ends with your question, it answers in the thread, and goes back to waiting.
+
+PR reviews are opened with `diffprism review <PR URL>` or the dashboard — not by `open_review` — and your AI then works inside them with the tools above. Click a line to ask the agent about it; an agent listening with `wait_for_comments` answers in the thread.
+
+When you're done, **Approve**, **Request changes** or **Comment** from the bar at the bottom: DiffPrism posts it to GitHub as a pull request review. Your threads are a conversation with the agent, so none of them goes to GitHub unless you tick it; a ticked thread posts your opening message as an inline review comment. The token comes from `GITHUB_TOKEN`, `gh auth token`, or `~/.diffprism/config.json`.
+
+## Choosing a scope
+
+Every review — CLI, dashboard, and the MCP tools — defaults to the **working copy**.
+
+| Scope | Shows |
+|---|---|
+| `working-copy` *(default)* | Everything uncommitted; staged and unstaged as separate groups |
+| `staged` | Only what the next commit contains |
+| `unstaged` | Only edits not yet staged |
+| `HEAD~3..HEAD`, `main..feature` | A range of commits |
+
+The one exception is the [commit gate](#commit-gate), which always reviews `staged`.
 
 ## Local Agent Review
 
@@ -113,7 +130,9 @@ diffprism hook install              # Add the gate to this repo's pre-commit hoo
 diffprism hook uninstall            # Remove it
 ```
 
-By default a staged diff of **120+ changed lines** opens a review; anything smaller
+It reviews **staged** changes only, where every other entry point defaults to the whole
+working copy: a commit contains exactly the index, so unstaged edits aren't part of what
+is being approved. By default a staged diff of **120+ changed lines** opens a review; anything smaller
 commits untouched. A gate that stops every commit is one you learn to skip with
 `--no-verify`, and a skipped gate is worse than none. Tune it per repo:
 
@@ -137,6 +156,13 @@ Commit blocked: the review requested changes.
 Install adds one line between markers, so uninstall removes exactly that and leaves
 the rest of your hook alone. Repos using `core.hooksPath` are handled.
 
+**Reviews take as long as they take.** An agent's shell command usually times out long
+before a person finishes reading, so the review outlives the `git commit` that opened it.
+A decision stands for as long as the staged diff it answered is unchanged: re-run the
+same commit after the reviewer decides and it is picked up immediately, with no second
+review. Agents running `git commit` should use a long shell timeout — the `/review`
+skill tells them so.
+
 ## Features
 
 - **AI-powered PR review** — Your AI gets full codebase context via 14 MCP tools
@@ -161,9 +187,23 @@ diffprism server status             # Check server status
 diffprism server stop               # Stop the server
 diffprism hook install              # Gate commits on a review
 diffprism hook uninstall            # Remove the gate
+diffprism feedback                  # Share feedback as a prefilled GitHub issue
+diffprism feedback --bug            # Report a bug, including the last error
 diffprism teardown                  # Remove configuration
 ```
 
+## Feedback
+
+```bash
+diffprism feedback                 # Share an idea or what's working
+diffprism feedback --bug           # Report a bug
+diffprism feedback -m "…" --print  # Start with text; print the URL instead of opening it
+```
+
+Both open a **prefilled GitHub issue** in your browser — DiffPrism version, OS, Node, and for a bug the last error it hit, with your home directory replaced by `~`. Nothing is sent automatically and DiffPrism collects no telemetry: you read and edit the issue, then submit it or don't. The dashboard has a **Send feedback** link that does the same.
+
+When a command fails, it says how to report it, and keeps the error in `~/.diffprism/last-error.json` so `--bug` can include it.
+
 ## Development
 
 ```bash