thurview 0.11.1 → 0.13.0

package/README.md

@@ -1,83 +1,45 @@
 # thurview
 
-Guided, evidence-anchored reviews of agent-written code.
-
-A coding agent studies a branch, pull request or commit range and writes a
-short document in which every claim is anchored to an exact file and line
-range at a pinned commit. thurview validates the anchors, seals a revision,
-and serves it in your browser: the walkthrough, live code peeks, the diff,
-commits, and a software map. You ask questions, leave anchored comments, and
-approve or request changes. The agent answers and republishes.
-
-It also explains a codebase. A **code explainer** is the same document over a
-different unit: one pinned commit instead of a range, so a reader can see the
-architecture well enough to spot design problems themselves. It has no diff and
-nothing to approve, it surfaces structure rather than grading it, and it states
-what it did not examine.
-
-It does not review the code for you. It helps you understand it fast enough
-to review it yourself.
-
-![thurview demo: the agent publishes and answers in the terminal, the reader
-peeks, comments and decides in the browser](./media/thurview-demo.gif)
-
-The clip is the `/thurview` skill's loop end to end: `thurview publish`, a
-question arriving in `thurview wait`, the reply, then the reader following an
-anchor into the code, commenting on a line range in the diff, reading the
-answer in the threads panel and requesting changes.
-
-## What the reader sees
-
-Prose with every claim anchored to code, opened beside the text:
-
-![The review document, with a call stack diff, a storage view and an anchored
-peek open in the side panel](./media/review-review.png)
-
-The diff at the pinned commits, commenting on a selected line range:
-
-![The Files tab, split diff, with a comment on lines 9 to 12 of
-src/auth.ts](./media/review-files.png)
-
-The software map: where the change landed in the system, and what sits next to
-it — the question the diff cannot answer:
-
-![The Map tab: the parts the change touched, drawn first, the links between
-them, and the selected node's files, code and neighbours](./media/review-map.png)
-
-Threads: a question the agent already answered, and a comment held for the
-decision:
-
-![The threads panel, one answered question and one pending
-comment](./media/review-threads.png)
-
-Approve, or send it back with the comments:
-
-![The submit dialog, one pending comment, Approve or Request
-changes](./media/review-decision.png)
-
-```mermaid
-flowchart LR
-  A[Branch, PR or range] --> B[Agent pins base and head]
-  B --> C[Agent authors review.md + data.yaml + map.yaml]
-  C --> D[thurview publish: validate, seal revision]
-  D --> E[You read, ask, comment in the browser]
-  E -->|Request changes| C
-  E -->|Approve| F[Done]
-```
+Guided, evidence-anchored reviews of agent-written code. A coding agent studies
+a branch, pull request or commit range and writes a short document in which
+every claim is anchored to an exact file and line range at a pinned commit. You
+read it in your browser, ask the agent questions, comment on the code, and
+approve or send it back.
 
 ## Install
 
 Give your agent the skill, with the [skills](https://github.com/vercel-labs/skills)
-CLI. It works with Claude Code, Codex, Cursor, OpenCode and every agent that
+CLI - it works with Claude Code, Codex, Cursor, OpenCode and every agent that
 reads the Agent Skills format:
 
 ```sh
 npx skills@latest add https://github.com/Thurbeen/thurview \
   --skill thurview --agent universal claude-code --global --yes
-npx skills@latest add https://github.com/Thurbeen/thurview \
-  --skill review-fix --agent universal claude-code --global --yes   # optional, see below
 ```
 
+The skill reaches the `thurview` command through `npx`, so the requirements
+are Node 22 or later and git (`gh` for pull requests, `glab` for merge
+requests). Then, in any repository, ask your agent:
+
+```text
+Use the thurview skill to review my current branch against up-to-date main
+and open it.
+```
+
+![thurview demo: the reader follows an anchor into the code, comments on a line
+range in the diff, reads the agent's answer and requests changes](./media/thurview-demo.gif)
+
+The clip is the reader's half, the agent working off camera: following an anchor
+from the prose into the code, opening a call stack frame, commenting on a line
+range of the diff, seeing on the map what the change added, reading in the
+threads panel the answer to a question already asked, and sending the review
+back with changes requested.
+
+<details>
+<summary><b>Other ways to install</b> - pin the skill to a release, install the
+command from npm, run from a checkout, session hooks, the thurview-design and
+review-fix skills</summary>
+
 `--global` installs for your user, so one install covers every repository.
 `universal` puts the one real copy in `~/.agents/skills/thurview`, the directory
 no single agent owns, and every other agent you name gets a symlink to it, such
@@ -103,13 +65,11 @@ The npm package ships the same skill, so `thurview setup skill` links the copy
 that matches the command you have installed. Use that when you want the two to
 move together.
 
-The skill drives the `thurview` command, which needs Node 22 or later and
-git (`gh` for pull requests, `glab` for merge requests). Install it, or let
-the skill reach it through `npx`:
+Install the command itself, rather than leaving the skill to reach it through
+`npx` on every run:
 
 ```sh
 npm install -g thurview     # or: pnpm add -g thurview
-npx -y thurview             # no install; the skill falls back to this
 ```
 
 The review reasons over a code graph thurview builds itself from the pinned
@@ -132,14 +92,81 @@ with the reviews of its working directory. `thurview setup skill` links the
 skill from this checkout instead of the `skills` CLI copy; use one or the
 other.
 
-Then, in any repository, ask your agent:
+Also available: `thurview-design`, which authors the design kind described
+[below](#how-it-works), and `review-fix`, the browserless companion skill
+described [below](#review-and-fix).
 
-```text
-Use the thurview skill to review my current branch against up-to-date main
-and open it.
+```sh
+npx skills@latest add https://github.com/Thurbeen/thurview \
+  --skill thurview-design --agent universal claude-code --global --yes
+npx skills@latest add https://github.com/Thurbeen/thurview \
+  --skill review-fix --agent universal claude-code --global --yes
 ```
 
-## What the reader gets
+</details>
+
+## How it works
+
+thurview validates every anchor against the pinned commits, seals a revision,
+and serves it in your browser: the walkthrough, live code peeks, the diff,
+commits, and a software map. You ask questions, leave anchored comments, and
+approve or request changes. The agent answers and republishes.
+
+It also explains a codebase. A **code explainer** is the same document over a
+different unit: one pinned commit instead of a range, so a reader can see the
+architecture well enough to spot design problems themselves. It has no diff and
+nothing to approve, it surfaces structure rather than grading it, and it states
+what it did not examine.
+
+And it reads a plan. A **design** is the same document over a change that is
+not written yet: one pinned commit — the code it argues from — anchors on the
+code as it stands, and what it would build declared as proposals, each attached
+to the code it lands in today. An anchor never points at code that does not
+exist; the reader approves the design or sends it back.
+
+It does not review the code for you. It helps you understand it fast enough
+to review it yourself.
+
+```mermaid
+flowchart LR
+  A[Branch, PR or range] --> B[Agent pins base and head]
+  B --> C[Agent authors review.md + data.yaml + map.yaml]
+  C --> D[thurview publish: validate, seal revision]
+  D --> E[You read, ask, comment in the browser]
+  E -->|Request changes| C
+  E -->|Approve| F[Done]
+```
+
+## What the reader sees
+
+Prose with every claim anchored to code, opened beside the text:
+
+![The review document, with a call stack diff, a storage view and an anchored
+peek open in the side panel](./media/review-review.png)
+
+The diff at the pinned commits, commenting on a selected line range:
+
+![The Files tab, split diff, with a comment on lines 9 to 12 of
+src/auth.ts](./media/review-files.png)
+
+The software map: where the change landed in the system, and what sits next to
+it — the question the diff cannot answer:
+
+![The Map tab: the parts the change touched, drawn first, the links between
+them, and the selected node's files, code and neighbours](./media/review-map.png)
+
+Threads: a question the agent already answered, and a comment held for the
+decision:
+
+![The threads panel, one answered question and one pending
+comment](./media/review-threads.png)
+
+Approve, or send it back with the comments:
+
+![The submit dialog, one pending comment, Approve or Request
+changes](./media/review-decision.png)
+
+## What's in a review
 
 - **Interface delta**: above the document, what the change added to, changed
   in or removed from the surfaces other code can reach - exported functions
@@ -183,20 +210,21 @@ bar.
 
 ## CLI
 
-| Command                                                               | Purpose                                                           |
-| --------------------------------------------------------------------- | ----------------------------------------------------------------- |
-| `thurview scaffold [--pr N \| --base R --head R]`                     | Create a review pinned to exact commits (`--update` re-pins)      |
-| `thurview explain [<path>] [--commit R]`                              | Create a code explainer of a codebase or subsystem at one commit  |
-| `thurview info [--all]`                                               | Reviews bound to this worktree                                    |
-| `thurview publish --review ID [--view T] [--open]`                    | Validate the document and map, seal a revision                    |
-| `thurview open --review ID [--view T]`                                | Start the server if needed and open the browser                   |
-| `thurview wait --review ID [--timeout S]`                             | Block until the reader needs the agent                            |
-| `thurview threads list\|get\|reply\|resolve`                          | Read and answer threads                                           |
-| `thurview graph interfaces\|impact\|callers\|tests-for\|architecture` | Ask the code graph at a review's pins, or at `--base`/`--head`    |
-| `thurview forge status\|prior\|submit\|reply`                         | Read a change request through its forge, and post the review back |
-| `thurview serve` / `thurview stop`                                    | Run the server in the foreground / stop the background one        |
-| `thurview setup hooks\|skill\|status`                                 | Session hooks, agent skill, install state                         |
-| `thurview update`                                                     | Self-update from npm                                              |
+| Command                                                               | Purpose                                                               |
+| --------------------------------------------------------------------- | --------------------------------------------------------------------- |
+| `thurview scaffold [--pr N \| --base R --head R]`                     | Create a review pinned to exact commits (`--update` re-pins)          |
+| `thurview explain [<path>] [--commit R]`                              | Create a code explainer of a codebase or subsystem at one commit      |
+| `thurview design [<path>] [--commit R]`                               | Create a design of what to build, pinned to the commit it argues from |
+| `thurview info [--all]`                                               | Reviews, explainers and designs bound to this worktree                |
+| `thurview publish --review ID [--view T] [--open]`                    | Validate the document and map, seal a revision                        |
+| `thurview open --review ID [--view T]`                                | Start the server if needed and open the browser                       |
+| `thurview wait --review ID [--timeout S]`                             | Block until the reader needs the agent                                |
+| `thurview threads list\|get\|reply\|resolve`                          | Read and answer threads                                               |
+| `thurview graph interfaces\|impact\|callers\|tests-for\|architecture` | Ask the code graph at a review's pins, or at `--base`/`--head`        |
+| `thurview forge status\|prior\|pass\|submit\|reply`                   | Read a change request through its forge, and post the review back     |
+| `thurview serve` / `thurview stop`                                    | Run the server in the foreground / stop the background one            |
+| `thurview setup hooks\|skill\|status`                                 | Session hooks, agent skill, install state                             |
+| `thurview update`                                                     | Self-update from npm                                                  |
 
 thurview is an [AXI](https://axi.md): built for agents that drive it through a
 shell. Output is [TOON](https://toonformat.dev) on stdout, errors are
@@ -232,6 +260,7 @@ on the change request, through `thurview forge`:
 ```sh
 thurview forge status --change 123    # what CI actually did, and whether it is a gate at all
 thurview forge prior  --change 123    # the previous pass, thread by thread
+thurview forge pass   --review <id>   # the reader's submitted threads, as the file below takes
 thurview forge submit --change 123 --file pass.json --dry-run
 thurview forge reply <threadId> --change 123 --body "<answer>" --resolve --at <head>
 ```
@@ -242,6 +271,14 @@ a change request from a fork typically runs a fraction of them, and a
 cancelled job shows no failure while asserting nothing. `ci.trustworthy` is
 the only field that means the tests really passed.
 
+`pass` goes the other way, from a review a reader submitted in the browser to
+that same file: one inline comment per thread anchored to a line, questions and
+resolved threads left out, and threads with no line - a document block, a map
+node, a whole file - gathered into the summary and named in the output, so
+nobody assumes their comment was posted where they wrote it. The verdict comes
+from the reader's decision, `close` becomes a `comment`, and an approve with
+threads still open is refused rather than quietly downgraded.
+
 `submit` takes one JSON file so a human can read the pass before it is posted,
 refuses an `approve` without `--confirm`, and warns about comments too long to
 be read. `reply --resolve` takes `--at <sha>` and refuses any commit but the
@@ -275,12 +312,23 @@ An explainer writes the same files, minus `interfaces`: there is no change to
 derive a delta from, and `graph: base` on an anchor is an error because there
 is one commit.
 
+A design writes the same files, and `interfaces` means something else in it:
+each entry is a **proposal** — what the design would add, change or remove,
+with the anchor of the code that proposal lands in, replaces or plugs into
+today. `graph: base` is an error for the same reason as in an explainer, a
+`symbol:` entry is an error because no diff derived one, and a design that
+proposes nothing is refused: that document is an explainer. In its `map.yaml`,
+`base` is the structure as it stands and `nodes` the structure it proposes, so
+a proposed part may own files that do not exist yet while a `base` node may
+not.
+
 `thurview publish` rejects an anchor whose file or lines do not exist at the
 pinned commit, a call stack frame that claims an added or removed call the
 diff does not show, a storage operation on an unknown field, a map edge
 to an unknown node, an interface annotation for a symbol the change did not
 move, a declared interface whose anchor holds no added or deleted line, and an
-explainer that anchors nothing at all. The full format is in
+explainer that anchors nothing at all, and a design that proposes nothing or
+whose proposal names no site in the code as it stands. The full format is in
 [skills/thurview/references](skills/thurview/references).
 
 Optional guidance for the agent: `~/.thurview/THURVIEW.md` for you,