buhtig 0.1.0-alpha.3 → 0.1.0-alpha.5

package/README.md

@@ -93,8 +93,15 @@ proxy in front of it before doing that.
 ### 📝 Review without leaving the keyboard
 - **Inline comments** authored by clicking the diff gutter land in a **local change-request** — a
   draft you can edit, retype, delete, reclassify (plain comment ↔ change-request), or **send now**.
+- **Draft comments survive the author pushing.** Each one stores the same content fingerprint a
+  bookmark or a review finding does, so when the diff on screen moves on it resolves to `active`,
+  `moved` (re-anchored, and published at the line it moved to) or `stale` — greyed, with its
+  captured snippet, and never dropped from the diff. A lost comment is re-anchored by clicking
+  **Re-anchor** and then the gutter line it belongs on.
 - **Publish** the whole batch as a single GitHub review with a verdict (**Approve / Request changes /
   Comment**), or one-click **Approve** from the header (guarded against approving a stale head).
+  A comment whose code the head still has publishes silently; only one nothing can place stops to
+  ask.
 - **Every comment surface has the same powers.** A comment is the same object whether you meet it
   inline in the diff, in a Conversation thread, or in the timeline, so all three render one shared
   card: **edit**, **delete** (always behind a confirmation — GitHub has no undelete), **deal to
@@ -107,6 +114,13 @@ proxy in front of it before doing that.
 - **Conversation tab** hoists the top blocking items (change requests + unresolved threads) into a
   sticky rail so you can clear the path to merge fast; reply to threads, resolve/unresolve, post PR
   comments, and edit the description — all with a **side-by-side markdown editor**.
+- **`@` completes the people already on the PR.** Typing `@` in any composer — a thread reply, a PR
+  comment, a review body, the description, a finding — opens a menu of the PR's participants first
+  and the repository's assignable users after them, under the caret rather than under the box.
+  Boundaries are GitHub's, so `alice@example.test` and a handle in a URL open nothing. Everywhere
+  markdown is *rendered*, a mention is a link to the person or team — and a mention of **you** is
+  drawn as a marked chip, which is what makes the one line in a long thread that is asking you
+  something findable.
 - **Open in `$VISUAL`** per file (at the changed line) or for the whole PR worktree, plus a
   **worktree** affordance — collapsed to one chip in the header, expanding on hover, and reachable as
   `Alt+W` → `t`/`a`/`s` — for a **terminal**, a **coding agent**, or an explicit **worktree setup**
@@ -198,6 +212,47 @@ page. **An edit goes back to wherever the action was declared**: a file-declared
 in its own file, comments and untouched fields left alone, so the file you keep in the repo stays the
 thing that decides. Saving it as this install's override instead is a separate, named button.
 
+### Your own quick prompts
+
+Every ✦ offers a row of chips — the sentences nobody wants to type for the fortieth failing job. They
+are buhtig's to begin with and yours to change, keyed by the surface they appear on:
+
+```yaml
+quickPrompts:
+  pr.thread:
+    # naming a built-in's id PATCHES it — reword it, or switch it off
+    - id: draft-reply
+      text: 'Draft a reply in my voice: short, no apologies. Do not post it.'
+    - id: address
+      enabled: false
+
+    # anything else is a new chip, and needs both a label and a text
+    - id: ask-for-tests
+      label: ask for tests
+      text: Draft a polite reply asking the author to add a regression test.
+
+  selection:
+    builtins: off          # drop buhtig's own for this surface entirely
+    prompts:
+      - id: whose-is-it
+        label: whose is it?
+        text: Who last touched the selected lines, and why? Change nothing.
+```
+
+The contexts are `pr.chat`, `pr.description`, `pr.blockers`, `pr.thread`, `pr.commit`, `pr.job`,
+`pr.todo`, `changes.diff`, `review.run`, `review.summary`, `review.finding`, `review.title`,
+`review.body-finding`, `review.body-why`, `review.body-fix`, `review.inventory`, `selection`, `toast.error` and
+`toast.warning`.
+
+Add, reword, hide and un-hide them from the ✦ itself — the sliders chip beside the row — or keep what
+you just typed as a chip with the bookmark button beside Send. An id that matches nothing buhtig ships is reported
+as a warning rather than failing the file, so a release that renames a preset cannot break a config
+that switched the old name off.
+
+Unlike `customActions`, this one **is** allowed in `.buhtig/config.yaml`: a prompt is prose an agent
+is handed, like a facet brief, and it is gated by the same trust — the weakest layer, which any of
+your own can reword or switch off.
+
 ---
 
 ## Architecture
@@ -249,18 +304,54 @@ pnpm install --frozen-lockfile
 # run in dev (web + server, hot reload)
 pnpm dev
 
-# or build + start the production server
-pnpm build
+# or start the production server (builds first)
 pnpm start
 ```
 
-The server listens on **port 10003** by default (override with `BUHTIG_PORT`). Open the web app,
-pick a repo you have access to, and start reviewing.
+The server listens on **port 10003** by default. Open the web app, pick a repo you have access to,
+and start reviewing.
+
+`BUHTIG_LISTEN` moves it, in any of the forms `--listen` accepts, and the Vite dev proxy follows it
+to the same address:
+
+```bash
+BUHTIG_LISTEN=4321 pnpm dev            # a port
+BUHTIG_LISTEN=127.0.0.1:4321 pnpm dev  # host:port
+BUHTIG_WEB_PORT=4322 pnpm dev          # move the dev web server too, for a second checkout
+```
 
 `buhtig doctor` reports whether this machine is set up — Node, `git`, the config file, and each of
 the three separable auth questions (is the token source reachable, does it yield a token, does
 GitHub accept it). `buhtig doctor --json` is the thing to paste into a bug report.
 
+### Trying it without connecting a repository
+
+`/demo` is a guided tour of the product against a fictional repository. Nothing is sent to GitHub,
+and no repository of yours is touched. From the tour, **Open in the full app** leaves it for the real
+pull-request pages — list, conversation, changes, checks, dashboard, stack — still on the fixture.
+
+That works two ways, and which one you get depends only on what is behind the page:
+
+- **With a buhtig running**, a *throwaway second instance* is launched (`--demo`): its own config,
+  database, clones and fake-GitHub state in a tmp dir, never touching your install. Real git, real
+  diffs, real worktrees.
+- **With nothing running** — the app served as static files — the browser answers `/api` itself from
+  the same fixture, and the diffs are computed in the tab. What you change (viewed marks, drafts,
+  triaged findings) is kept in that browser until you press **Reset demo data**.
+
+So the built web assets are a complete, hostable demo site with no server at all:
+
+```bash
+pnpm --filter @buhtig/web build            # → packages/web/dist
+node scripts/serve-static.mjs              # serve it locally on :10005 to check
+```
+
+Upload `packages/web/dist` anywhere that serves static files with an SPA fallback (unknown paths →
+`index.html`). The app probes `/api/health` once at boot: an answer means a real install and nothing
+changes; HTML or a 404 means a file host, and it switches to the browser-local fixture. A *failed*
+connection is read as "your server is down", not as a demo — a hosted demo must never be what you
+see when your own instance restarts. `?demo=local` forces the browser-only mode anywhere.
+
 ---
 
 ## Running the server
@@ -278,6 +369,15 @@ buhtig serve --listen http://0.0.0.0:80 --allow-remote # URL form, same thing
 `BUHTIG_LISTEN` is the same string. `BUHTIG_PORT` still works and still means a port; where both are
 set, `BUHTIG_LISTEN` wins.
 
+From a source checkout, `pnpm cli` is this same CLI — it builds what the CLI depends on, then runs
+`packages/cli/src` under `tsx`, so every flag and subcommand works without a global install:
+
+```bash
+pnpm cli serve --listen 127.0.0.1:10004
+pnpm cli doctor --json
+pnpm cli service status
+```
+
 Two things are refused by name rather than left to fail later. **`https://`** — buhtig does not
 terminate TLS, and accepting it would listen in plaintext on an address someone believes is
 encrypted. **Unix sockets** — a socket has no address to hand the agents buhtig launches, and every
@@ -315,8 +415,8 @@ Two platform differences the CLI states rather than hides:
   system-domain answer is a LaunchDaemon, which runs as root — wrong for a tool authenticating as
   you). It also appears under System Settings → Login Items, where switching it off stops it.
 
-Installing refuses to overwrite a `buhtig.service` this CLI did not write — `install.sh` creates one
-— unless you pass `--force`. Set `BUHTIG_SERVICE_UNIT` to run a second instance under its own name.
+Installing refuses to overwrite a `buhtig.service` this CLI did not write unless you pass `--force`.
+Set `BUHTIG_SERVICE_UNIT` to run a second instance under its own name.
 
 ---
 
@@ -387,7 +487,7 @@ A repo can override the *choice* (`agent: codex` in its own entry, or in `.git/b
 Until something chooses, the Alt+W → Agent action reads "configure…" and takes you to the settings
 page rather than launching whatever buhtig happened to be written against.
 
-A launched agent is **briefed on the way in**: it is told that you can send it a one-line instruction
+A launched agent is **briefed on the way in**: it is told that you can send it a one-line message
 from the UI, and given one exact command to watch for one — `buhtig agent listen`, pointed at
 `$BUHTIG_STREAM` and chosen for the agent being launched (Claude Code sets it up as a persistent
 monitor that never returns and wakes it on each message; Codex and opencode run it for one bounded
@@ -397,13 +497,84 @@ window at a time). Where the CLI supports it that briefing goes in as an extra s
 
 ### Settings, and where a value comes from
 
-Every option lives in up to three layers, and the settings pages show all of them with the one in
-force marked: buhtig's own store (this install), the repo's `.git/buhtig.yaml` (travels with the
-clone), and `config.yml`. You pick which layer a save lands in. Writes to a YAML file keep its
-comments and key order.
+Every option lives in up to four layers, and the settings pages show all of them with the one in
+force marked. They are named by **reach**, not by filename, because reach is what decides which one
+wins:
+
+| badge | file | reach |
+| --- | --- | --- |
+| `this install` | buhtig's own store | this machine only |
+| `this clone` | `.git/buhtig.yaml` | this clone; not versioned, unreachable by any branch |
+| `your config.yml` | `~/.config/buhtig/config.yml` | this machine, every repo |
+| `in the repo` | `.buhtig/config.yaml` | **committed** — everyone who clones it |
+
+Precedence runs top to bottom. Everything above `in the repo` is something *you* wrote; the committed
+layer is what the project ships, so it is a default you can always override. The inverse ordering
+would let a repository you merely read pull requests from configure your machine.
+
+You pick which layer a save lands in. Writes to a YAML file keep its comments and key order.
 
 `/settings` holds the install-wide settings; each repo's gear holds its own and links there.
 
+### The repo's own committed config
+
+`.buhtig/` at the repo root is the layer that travels:
+
+```
+.buhtig/
+  config.yaml          # the review block, ticket links, the preferred agent
+  review-facets/       # the facet taxonomy
+```
+
+Its schema is the same one the layers above it use, **minus everything that would let a pull request
+reach off its own tree**. `hooks`, `customActions`, `worktreePathTemplate` and `trust` are *rejected*
+rather than dropped — the first two are commands this machine would run, the third is a location on
+it, and the fourth would let a repository declare itself trusted. A key buhtig has no meaning for is
+still stripped rather than fatal, exactly as in the other layers.
+
+#### Trust
+
+A committed config is content a pull request can propose changes to, and facet prose is the brief a
+review subagent is handed. So buhtig reads `.buhtig/` only when the content is attributable to
+somebody this install trusts, at a level you set per repo:
+
+```yaml
+# config.yml — the default for every repo
+trust:
+  repoConfig: approved
+
+acme/webapp:
+  trust:
+    repoConfig: trunk
+```
+
+| level | what it means |
+| --- | --- |
+| `none` | `.buhtig/` is never read for this repo |
+| `approved` *(default)* | nothing is used until you have seen it; a change comes back as a diff to approve |
+| `trunk` | trunk needs no approval — but anyone who can push to trunk can change how your reviews run |
+| `any-branch` | no prompts at all; only for repos where every branch is yours |
+
+Content is read **at trunk** while your checkout has no uncommitted changes under `.buhtig/`, which
+keeps the answer the same whatever branch you happen to have out. A dirty root switches the read to
+your working tree, because that is the only reason to prefer it: you are authoring the taxonomy, and
+showing you trunk's copy while you type would be useless. **A pull request's own worktree is never a
+source.**
+
+Beyond the level, two things count as your own work without being approved: **uncommitted local
+edits** (no pull request can produce those), and commits **signed by your own key** — matched on the
+`user.signingkey` fingerprint, never on an author address, since a signature proves a key and not a
+claimed identity. Attribution is per file, so one local edit never vouches for a committed rewrite
+beside it.
+
+Three refusals hold at every level, including `any-branch`: a **committed symlink or submodule** under
+`.buhtig/` (a read-anywhere primitive nobody spots in a markdown diff), two paths differing only by
+case, and a range git cannot walk. A deletion is attributed like an edit — removing the facet that
+would have caught the bug is the quietest way to suppress a review.
+
+Every run records what judged it: the commit, the `.buhtig` tree OID, the layer, and the trust
+verdict that admitted it.
+
 ### Structured review
 
 An agent-authored review is a **resource**, not a directory of markdown: a run over a PR at a head
@@ -413,9 +584,15 @@ The facet taxonomy is **per-repo configuration**, resolved from a tree of facet
 review skill already reads — so one project has a `TENANCY` facet and another has none, and adding a
 facet is a markdown file rather than a code change.
 
-The taxonomy lives in `.git/buhtig/review-facets/` — inside the git directory rather than the tree,
-so no branch, merge or pull request can rewrite the rules of its own review, and every linked
-worktree sees one taxonomy. There is nothing to configure to place it.
+The taxonomy lives in one of two places. `.buhtig/review-facets/` is **committed**: it travels with
+the repository, so everyone who clones it reviews against the same dimensions — and because a pull
+request can propose changes to it, it is read only when [trust](#trust) says the content is
+attributable. `.git/buhtig/review-facets/` is the older home: unreachable by any branch and therefore
+unconditionally trusted, but local to one clone.
+
+The committed one wins **once it is trusted**. Until then this clone's copy keeps serving, so a
+colleague landing a `.buhtig/` cannot take a working taxonomy dark. Whichever is not in force is
+reported as present and unused rather than dropped from the answer.
 
 ```yaml
 acme/webapp:
@@ -448,22 +625,42 @@ inheriting its parent's priority and slug, and `slug` is a *namespace* several f
 identity of a unit of review work is its **file path**.
 
 Reviews are driven by the `buhtig-review` skill, which buhtig **serves** rather than ships into your
-repositories — `curl localhost:10003/api/skills/buhtig-review`. What you install is a ~25-line
-bootstrap that knows how to fetch the rest, once, at user level:
+repositories — `curl localhost:10003/api/skills/buhtig-review`. An agent holding the **MCP server**
+asks for it by name (`skill({ skill: "buhtig-review", doc: "SKILL" })`) and reads the instructions
+rendered as tool calls; an agent with only a shell reads the same instructions rendered as `curl`,
+and neither is shown the other's version. The tool set is generated from one declared catalogue
+(`AGENT_CALLS` in `@buhtig/shared`) with schemas derived from the OpenAPI document. It is curated:
+there is no tool to publish a review, merge or close a PR, or write settings. Dismissing a finding
+and staging one for posting *are* there, because you will want to ask an agent to do them — they
+carry a destructive hint so your CLI stops and asks, and the instructions are blunt that those marks
+answer your instruction and never the agent's own opinion of a finding.
+
+The MCP server is a subcommand of the CLI, and `install` registers it with the agent hosts on the
+machine — through each host's own CLI, never by rewriting a config file someone maintains by hand:
+
+```bash
+buhtig mcp install                      # asks which of the hosts it found
+buhtig mcp install --all                # all of them, without asking
+buhtig mcp install --host claude --dry-run
+buhtig mcp install --scope project      # for the hosts that offer the choice
+```
+
+The checklist opens with the hosts whose config already names buhtig ticked, so re-running after an
+install moves is one keypress; where nothing is configured yet it suggests everything it found.
+`--host` and `--all` answer it outright, and a run with no terminal takes every host found.
+
+OpenCode and Cursor have no CLI to register through, so they get the block to paste. Re-running is
+safe — each entry is removed and re-added, which is also how a moved install gets re-pointed.
+
+Running it directly is the same server:
 
 ```bash
-./scripts/install-agent-integration.sh   # also run by install.sh
+buhtig mcp                               # stdio, what a host launches
+buhtig mcp --http                        # streamable HTTP on 10005, for a host that takes a URL
+buhtig mcp --url http://localhost:10004  # drive a different install
 ```
 
-That script registers buhtig's **MCP server** with your agent CLI as well, and the two work together:
-an agent holding the MCP tools reads the instructions rendered as tool calls, an agent with only a
-shell reads the same instructions rendered as `curl`, and neither is shown the other's version. The
-tool set is generated from one declared catalogue (`AGENT_CALLS` in `@buhtig/shared`) with schemas
-derived from the OpenAPI document. It is curated: there is no tool to publish a review, merge or
-close a PR, or write settings. Dismissing a finding and staging one for posting *are* there, because
-you will want to ask an agent to do them — they carry a destructive hint so your CLI stops and asks,
-and the instructions are blunt that those marks answer your instruction and never the agent's own
-opinion of a finding.
+`buhtig-mcp` remains as its own binary for anything registered before the subcommand existed.
 
 The division of labour is deliberate: the agent supplies prose and `(path, line)`; buhtig derives anchor fingerprints,
 staleness, whether a line is postable to GitHub, and `F<N>` numbering; **the human** dismisses, posts,
@@ -474,18 +671,19 @@ finding on code the PR never touched stays `active` — and a later push re-reso
 `active` / `moved` / `stale`. Nothing is ever auto-deleted.
 
 ```bash
-pnpm server    # rebuilds @buhtig/shared, then boots on $BUHTIG_PORT (10003)
+pnpm dev:server  # server only, watched, on $BUHTIG_LISTEN (default 10003)
 curl -s localhost:10003/api/repos/acme/webapp/review/config | jq '{state, facets: (.facets|length)}'
 ```
 
 > A bare `tsx packages/server/src/index.ts` resolves `@buhtig/shared` to its **build output**. If
-> `dist/` is stale you get `does not provide an export named …` at import. `pnpm server` and
-> `pnpm dev` both handle this; a raw `tsx` invocation does not.
+> `dist/` is stale you get `does not provide an export named …` at import. Every `pnpm` script here
+> builds what it depends on first; a raw `tsx` invocation does not.
 
 ### Repo-local config & hooks
 
-A repo can carry its own config at `.git/buhtig.yaml` (unkeyed — it's already repo-scoped). Today it
-supports lifecycle **hooks**:
+A repo can carry its own config at `.git/buhtig.yaml` (unkeyed — it's already repo-scoped), local to
+this clone and unreachable by any branch. For settings that should travel with the repository, use
+the committed `.buhtig/config.yaml` layer instead. Hooks are the one thing that can *only* live here:
 
 ```yaml
 hooks:
@@ -520,12 +718,17 @@ The testing seam fakes **GitHub's egress only** — never buhtig's own API or `g
   source of truth for SHAs, so headline flows like "viewed → stale on advance" stay honest.
 - **End-to-end (Playwright):** a real backend booted against an isolated sandbox (tmp XDG dirs,
   fixture `config.yml`, ephemeral git repos, fake `GitHubClient`).
+- **The hosted demo (Playwright, `static-demo` project):** the built assets on a file server with no
+  `/api` behind them at all. Its own project because the condition under test is the *absence* of a
+  backend, which the shared server cannot provide.
 
 ```bash
 pnpm test            # unit + integration (vitest)
 pnpm test:watch
-pnpm test:e2e        # playwright
+pnpm test:e2e        # playwright (both projects)
+pnpm test:e2e --project static-demo   # just the browser-only demo
 pnpm test:e2e:ui     # playwright UI mode
+pnpm --filter buhtig test:setup:local # packed CLI + setup + foreground server, isolated under .tmp
 pnpm typecheck
 pnpm lint            # biome
 ```

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "buhtig",
-  "version": "0.1.0-alpha.3",
+  "version": "0.1.0-alpha.5",
   "description": "Local-first, keyboard-driven pull-request review cockpit",
   "license": "UNLICENSED",
   "type": "module",
   "bin": {
-    "buhtig": "./packages/cli/dist/index.js",
-    "buhtig-mcp": "./packages/cli/dist/mcp.js"
+    "buhtig": "./release/index.js",
+    "buhtig-mcp": "./release/mcp.js"
   },
-  "files": ["LICENSE", "README.md", "packages/cli/dist"],
+  "files": ["LICENSE", "README.md", "release"],
   "repository": {
     "type": "git",
     "url": "git+https://github.com/veracioux/buhtig.git"
@@ -28,25 +28,33 @@
     "pnpm": ">=11"
   },
   "scripts": {
+    "cli": "turbo run build --filter='@buhtig/cli^...' && tsx packages/cli/src/index.ts",
+    "dev": "turbo run dev",
+    "dev:server": "turbo run dev --filter=@buhtig/server",
+    "dev:web": "turbo run dev --filter=@buhtig/web",
+    "start": "turbo run build && node packages/server/dist/index.js",
     "build": "turbo run build",
+    "sdk:generate": "turbo run generate --filter=@buhtig/sdk",
     "package:build": "BUHTIG_RELEASE=1 pnpm build && node scripts/build-package.mjs",
     "package:check": "node scripts/check-package.mjs",
     "prepack": "pnpm package:build && pnpm package:check",
-    "dev": "turbo run dev",
-    "format": "biome format --write .",
+    "check": "pnpm lint && pnpm typecheck && pnpm test",
     "lint": "biome check .",
-    "mobile:sync": "pnpm --filter @buhtig/mobile sync:android",
-    "mobile:apk:debug": "pnpm --filter @buhtig/mobile apk:debug",
-    "mobile:apk:release": "pnpm --filter @buhtig/mobile apk:release",
-    "server": "pnpm --filter @buhtig/shared build && pnpm --filter @buhtig/github build && BUHTIG_PORT=${BUHTIG_PORT:-10003} tsx packages/server/src/index.ts",
-    "start": "pnpm --filter @buhtig/cli build && pnpm --filter @buhtig/server start",
+    "format": "biome check --write .",
+    "typecheck": "tsc -p tsconfig.typecheck.json",
     "test": "vitest run",
+    "test:watch": "vitest",
+    "test:mobile": "pnpm --filter @buhtig/web test:mobile",
     "test:e2e": "playwright test",
+    "test:e2e:ui": "playwright test --ui",
     "test:e2e:debug": "playwright test --debug",
     "test:e2e:report": "playwright show-report",
-    "test:e2e:ui": "playwright test --ui",
-    "test:watch": "vitest",
-    "typecheck": "tsc -p tsconfig.typecheck.json"
+    "test:setup:local": "node test/setup-smoke/local.mjs",
+    "mobile:sync": "pnpm --filter @buhtig/mobile sync:android",
+    "mobile:open": "pnpm --filter @buhtig/mobile open:android",
+    "mobile:apk:debug": "pnpm --filter @buhtig/mobile apk:debug",
+    "mobile:apk:release": "pnpm --filter @buhtig/mobile apk:release",
+    "prepare": "husky"
   },
   "dependencies": {
     "better-sqlite3": "^13.0.3"
@@ -56,9 +64,14 @@
     "@playwright/test": "^1.50.1",
     "@types/node": "^22.13.1",
     "esbuild": "^0.25.0",
+    "husky": "^9.1.7",
+    "lint-staged": "^17.3.0",
     "tsx": "^4.19.2",
     "turbo": "^2.9.18",
     "typescript": "^5.7.3",
     "vitest": "^4.1.0"
+  },
+  "lint-staged": {
+    "*.{ts,tsx,js,jsx,mjs,cjs,json,astro,vue,svelte}": "biome format --write --no-errors-on-unmatched"
   }
 }

package/release/docs/buhtig-review/ANNOTATIONS.md

@@ -0,0 +1,151 @@
+# Annotating a resource
+
+Attach a small typed mark to something in buhtig, saying what you observed about its state.
+
+Standalone. It needs no review run, and nothing here is review input: an annotation is not a finding,
+carries no score, and is counted toward no verdict.
+
+{{preamble}}
+
+## What an annotation is, and what it is not
+
+An annotation is an **observation**. It changes nothing about the thing it describes — it resolves no
+thread, posts no comment, and is never seen on GitHub.
+
+That is the whole reason you may set one on your own reading, unlike a disposition, which is the
+human's decision and only ever carried out on their instruction. It is also why an annotation has to
+be honest. A human acts on these: a `resolvable` you were not sure about costs them exactly the trip
+it was meant to save. **Where you are unsure, reply instead.**
+
+| | Who owns it | May you act on your own judgement | Reaches GitHub |
+|---|---|---|---|
+| A disposition (`review_dispositions`) | the human's decision | no — on instruction only | no |
+| A note (`note_file`) | your answer to a question | yes | not until they promote it |
+| An annotation | your observation | **yes** | **never** |
+
+## Read the vocabulary first
+
+Which marks exist, and **when each applies**, is per-repo configuration. Never work from a kind list
+you remember, and never from a `when` you remember: a repo may have rewritten the instruction,
+dropped the kind, or added one of its own.
+
+```call annotation.vocabulary
+{
+  "owner": "acme",
+  "repo": "widgets",
+  "targetType": "thread"
+}
+```
+
+Each kind comes back with:
+
+- **`when`** — the condition you judge against. This is the instruction; there is no other.
+- **`stance`** — whose side of the PR the claim speaks from, `reviewer` or `author`. You do not choose
+  a stance and you do not record one. Choosing the kind is what states it.
+- **`soWhat`** — what the human is expected to do about the mark. Useful for deciding whether your
+  reason gives them enough to do it.
+- **`expiresOn`** — what voids the mark later. See below.
+- **`settableByHand`** — whether a *person* can also set this one from the UI. Not your concern for
+  deciding anything; it explains why a thread may carry a mark you did not make.
+
+An empty `kinds` means this repo does not annotate this target type. Say so and stop; do not pick a
+kind anyway. `issues` names anything the repo tried to declare and may not — worth relaying, because
+the human cannot see it from the thread.
+
+The kinds buhtig ships for a `thread`, as a repo that has changed nothing gets them:
+
+| Kind | Stance | The claim |
+|---|---|---|
+| `resolvable` | reviewer | Nothing is left in the complaint this thread raised — the reviewer who wrote it would have nothing more to ask. |
+| `i_addressed` | author | The code now does what the thread asked, and you can name the commit and lines that do it. |
+| `wont-do` | author | The author has said the change is not going to be made — out of scope, a deliberate choice, or deferred elsewhere. |
+
+`i_addressed` and `resolvable` are not alternatives. `i_addressed` is *"I fixed it"*; `resolvable` is
+*"there is nothing left to ask"*. Both on one thread is the strongest signal the pair can carry.
+
+`wont-do` is the one that contradicts `i_addressed`, and nothing enforces that — set one or the other,
+never both. It is also the kind you are least often entitled to: it records a **decision the author
+already stated**, in the thread or elsewhere on the PR. You never take that decision. A request
+nobody has answered is unanswered, not declined, and reading silence as a refusal is how a thread
+the author meant to come back to gets closed.
+
+## Read what is already there
+
+```call annotation.list
+{
+  "owner": "acme",
+  "repo": "widgets",
+  "number": 42
+}
+```
+
+Read before writing, so you replace your own earlier reading rather than restating it.
+
+**A mark with `author.kind: "human"` is not yours.** A person set it themselves and is standing
+behind it — do not clear it, do not overwrite it with the same kind, and do not treat it as something
+to verify. If you think a person's `i_addressed` is wrong, say so in a reply, which is where a
+disagreement belongs. Same rule as a disposition: never write over a decision you did not make.
+
+## Write the mark
+
+```call annotation.set
+{
+  "owner": "acme",
+  "repo": "widgets",
+  "number": 42,
+  "targetType": "thread",
+  "targetId": "<thread-id>",
+  "kind": "resolvable",
+  "reason": "the reviewer asked for a nil guard; src/parse.ts:88 has one and parse.test.ts:41 covers it",
+  "observed": {
+    "commentCount": 3,
+    "lastCommentId": "<id of the last comment you read>",
+    "headSha": "<the head you read the code at>"
+  }
+}
+```
+
+`reason` is required **of you**, and it is read **instead of** the thread. Make it the finding — what
+you checked and where — not a restatement of the kind. "This is resolvable" tells the human nothing
+they did not already see on the chip. (A person marking a thread themselves may omit it; they are
+the claimant, and there is nothing for them to check.)
+
+**Never send `author`.** It defaults to naming you an agent, and the UI draws an agent's mark
+differently from a person's — ✦ against a person glyph. Claiming to be a human would make the chip
+lie about who assessed the thread, which is the one thing the reader is using it to find out.
+
+`observed` must be the state you **actually read**. It is not bookkeeping: it is what lets buhtig tell
+a standing mark from one the conversation has moved past.
+
+Writing the same kind on the same target again replaces it. That is how a mark is renewed after a
+reply, not a second claim.
+
+## Expiry
+
+A mark carries the target's state at the moment you made it. When the live target has moved past
+that, buhtig stops counting the mark — it renders it struck through, as the record that somebody
+looked, and drops it from the filters.
+
+For a thread, the default `expiresOn: ["reply"]` means any new comment voids it. A repo may add
+`"head"`, which voids it when the PR's head moves.
+
+So: **a `resolvable` set before a reply is not wrong, it is spent.** If you are asked to re-check a
+thread that has since gained a reply, judge it again and set the mark again with the new `observed`.
+Do not clear the old one first.
+
+## Withdrawing one
+
+```call annotation.clear
+{
+  "owner": "acme",
+  "repo": "widgets",
+  "number": 42,
+  "targetType": "thread",
+  "targetId": "<thread-id>",
+  "kind": "resolvable"
+}
+```
+
+Only for a claim you no longer stand behind. A mark that has merely gone out of date needs nothing
+from you — buhtig already shows it as superseded, and clearing it destroys the evidence that the
+thread was assessed at all.