buhtig 0.1.0-alpha.1

package/LICENSE

@@ -0,0 +1,8 @@
+Copyright (c) 2026 veracioux. All rights reserved.
+
+This source code is publicly visible, but no license is granted to use, copy,
+modify, merge, publish, distribute, sublicense, or sell it.
+
+The project is UNLICENSED pending selection of a license. Viewing the source and
+submitting feedback through the project's GitHub repository are permitted. Any
+other use requires prior written permission from the copyright holder.

package/README.md

@@ -0,0 +1,552 @@
+# buhtig
+
+**A local-first, keyboard-driven pull-request review cockpit that's faster than github.com.**
+
+`buhtig` is `github` spelled backwards — because it flips the model. Instead of round-tripping
+every diff and click through the GitHub web app, buhtig runs as a single local process: it computes
+diffs straight from local git worktrees, caches aggressively by commit SHA, talks to the GitHub API
+only when it must, and puts every action a keystroke away. The result is a review surface that opens
+instantly, never burns your rate limit on a re-scroll, and is built end-to-end for keyboard-first
+review ergonomics.
+
+> Review PRs at the speed of `git`, with the comfort of a real editor and the muscle memory of vim.
+
+> **Public-source preview:** buhtig is currently `UNLICENSED`. The source is visible for evaluation
+> and feedback, but no open-source license has been granted yet. See [`LICENSE`](LICENSE).
+
+## Install the preview
+
+The npm release is being prepared but has not been published yet. Install from a checkout:
+
+```bash
+git clone https://github.com/veracioux/buhtig.git
+cd buhtig
+pnpm install --frozen-lockfile
+pnpm package:build
+pnpm link --global
+
+gh auth login
+buhtig setup
+buhtig doctor
+buhtig serve
+```
+
+Open <http://127.0.0.1:10003>. Node 22+, pnpm 11+, `git`, and a GitHub token source are required.
+`gh auth login` is the default and recommended token source.
+
+For a persistent install on Linux or macOS:
+
+```bash
+buhtig service install
+buhtig service status
+```
+
+The server binds to loopback by default because its local API has no authentication. Exposing it on
+another interface requires both an explicit address and `--allow-remote`; put an authenticating TLS
+proxy in front of it before doing that.
+
+---
+
+## Why buhtig?
+
+| github.com              |                        | **buhtig**                                                                                         |
+|-------------------------|------------------------|----------------------------------------------------------------------------------------------------|
+| API round-trip per view | Diff source            | **Local git worktree**, cached by SHA (immutable)                                                  |
+| Full reload             | PR list                | **Virtualized + stale-while-revalidate** (renders from cache, revalidates in the background)       |
+| Mouse-first             | Navigation             | **Keyboard-first**, one central shortcut registry + `?` help                                       |
+| Lives on GitHub         | Drafting review notes  | **Local change-requests** (a real resource agents can write via an API), published on your command |
+| —                       | Come-back-to-this pins | **Private bookmarks** at PR / file / line scope, cross-PR, that survive force-pushes               |
+| —                       | Open in your editor    | **Open any file (at the changed line) or the whole PR in `$VISUAL`** from a checked-out worktree   |
+| New token               | Auth                   | **Reuses your `gh` login** — no new secret to store                                                |
+
+---
+
+## Highlights
+
+### ⚡ A PR list that's already loaded
+- **Virtualized** list that stays smooth at thousands of PRs.
+- **Stale-while-revalidate**: the last-seen list is seeded from `localStorage`, so a (re)visit paints
+  rows immediately while a background refresh reconciles with GitHub.
+- **At-a-glance status per row**: CI rollup, mergeable signals (conflicts ⚠ / behind-base ↧ /
+  required-checks-failing ✗), review state, author, and an inline assignee picker.
+- **Powerful filtering & search** with keyboard shortcuts: draft/ready, assigned-to-me,
+  authored-by-me, a "care about" lens, review state, and a **triage queue**. Search understands
+  `#number`, a full PR URL, `TICKET-123` ticket keys, `@author`, or plain fuzzy text.
+
+### 🔬 A Changes tab built for actually reading code
+- **Diffs computed locally** from the PR worktree — the primary rate-limit mitigation — with
+  **syntax highlighting** (Prism One Dark) and **word-level intra-line** edit markers.
+- **Split / unified** toggle, and a **per-file context-lines** control to widen or tighten the
+  window around each hunk.
+- **Viewed tracking that understands staleness**: each file's *Viewed* checkbox is keyed on its git
+  blob OID, so when the PR head advances the file is marked **stale** (not silently unchecked) — you
+  always know you reviewed an older version.
+- **Collapse/expand per file** (viewed files auto-collapse), **collapse-all**, a live **viewed
+  progress** counter, **fuzzy or regex file filter**, **status filter** (added/changed/deleted), and
+  **custom tri-state regex filters** (off → *only* → *hide*) seeded with test/module presets and
+  persisted per repo.
+- **Focus mode** narrows the page to a single file so the browser's native find-in-page is scoped to
+  just that diff.
+- **Rich in-diff navigation**: jump file-to-file, hop to the next addition / removal / change /
+  comment / unviewed file via a which-key menu, and cycle through every inline comment or bookmark.
+
+### 📝 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**.
+- **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).
+- **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
+  deck**, and for a review thread also **resolve/reopen**, **reply**, and its **replies inline**
+  (expanded, each editable in its own right). Edit/delete follow GitHub's own `viewerCanUpdate` /
+  `viewerCanDelete`, so buhtig doesn't offer an action the API would refuse.
+- **Close** a PR from the header behind a confirmation that doubles as the place to explain it: an
+  optional comment (the same deck-backed composer used everywhere else) is posted *before* the close,
+  and a closed PR's button becomes **Re-open**, so undoing one doesn't mean a trip to GitHub.
+- **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**.
+- **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**
+  whose recorded state expires when the PR, the setup script, or the tree moves on.
+
+### 🔖 Private bookmarks that survive rebases
+- Pin a **PR, a file, or a single line** — cross-PR, repo-global, local-only.
+- One keystroke to pin/unpin; an optional one-line note added lazily.
+- **Never auto-deleted**: each pin stores a content fingerprint so on reload it resolves to
+  `active`, `moved` (re-anchored, shown with a ↕), or `stale` (greyed, with its captured snippet so
+  it stays recognisable and re-pinnable).
+- A **bookmarks hub overlay** lists everything grouped by scope; jump with Enter, plus a
+  bookmarked-only filter on the PR list for triage.
+
+### ⌨️ Keyboard-first, discoverable everywhere
+- One **central shortcut registry** — the `?` **help overlay** falls out of it for free.
+- **Every binding is yours to change.** The keyboard settings page lists every action buhtig has;
+  click one and press the key you want (Backspace unbinds it). Overrides are stored **server-side**,
+  so they follow the install rather than the browser, and can live in `config.yml` instead.
+- **Custom actions**: give a name and a shell command, pick a key, and it appears in the `Alt+W`
+  menu — or on a shortcut of its own. It runs in the PR worktree, with `$BUHTIG_PR` and friends
+  already set.
+- Every primary action is **also reachable by mouse**, and right-click **context menus** label each
+  entry with its keybind, so the menus double as a shortcut-discovery surface.
+- Shortcuts are suppressed while you're typing in a field, with careful handling of `+`, `Shift`,
+  and modifier combos.
+
+---
+
+## Keyboard shortcuts (a taste)
+
+Press **`?`** anywhere for the full, always-current list.
+
+| Keys                                    | Scope         | Action                                                                                                |
+|-----------------------------------------|---------------|-------------------------------------------------------------------------------------------------------|
+| `?` · `b`                               | **Global**    | Toggle help · open the bookmarks hub                                                                  |
+| `j`/`k` · `Enter` · `Alt+Enter`         | **PR list**   | Move cursor · open · open in new tab                                                                  |
+| `d` · `a` · `s` · `c` · `u` · `t` · `m` |               | Cycle draft · assigned-to-me · authored-by-me · care-about · review filter · triage · bookmarked-only |
+| `Ctrl+K`                                |               | Focus search (`#num`, URL, `TICKET-123`, `@author`, fuzzy)                                            |
+| `[` / `]` · `u`                         | **PR detail** | Previous / next tab · back to list                                                                    |
+| `Alt+W` → `t`/`a`/`s`                   |               | PR worktree menu: terminal · agent · run worktree setup                                               |
+| `j`/`k` · `Space` · `v` · `e`           | **Changes**   | Next/prev file · expand/collapse · toggle viewed · open in `$VISUAL`                                  |
+| `c` · `s` · `+`/`-` · `.`/`f`           |               | Collapse/expand all · cycle status filter · more/less context · focus file                            |
+| `n` → `a`/`r`/`c`/`m`/`u`               |               | "Jump to next…" menu (addition / removal / change / comment / unviewed)                               |
+| `{` / `}` · `'`                         |               | Previous / next inline comment · next bookmark in diff                                                |
+
+Every row above is a **default**, not a fact: rebind any of it under Settings → Keyboard, or in
+`config.yml`:
+
+```yaml
+keymap:
+  changes.next-file: [n]     # rebind
+  global.help: []            # unbind entirely
+```
+
+### Your own actions
+
+A custom action is a name and a command. It shows up in the `Alt+W` menu (or on its own shortcut),
+runs in the PR worktree, and gets its context from the environment — nothing is spliced into the
+command string, so nothing needs quoting:
+
+| variable | what it holds |
+| --- | --- |
+| `BUHTIG_PR` | the pull request number |
+| `BUHTIG_REPO` | `owner/repo` |
+| `BUHTIG_WORKTREE` | absolute path to the PR worktree |
+| `BUHTIG_URL` | this install's API base URL |
+
+The same variables reach every other command buhtig runs for you — the `postCheckoutWorktree` setup
+hook and the launched coding agent included.
+
+Add one from `Alt+W` → `+`, or from either settings page. In a file:
+
+```yaml
+customActions:
+  - slug: run-tests
+    label: Run tests
+    placement: pr.worktree   # or `global` for a shortcut of its own
+    key: r
+    command: pnpm test
+    cwd: worktree            # worktree | repo-clone | home
+    run: terminal            # or `background`: awaited, result in a toast
+```
+
+Put it under a repo's entry (or in its `.git/buhtig.yaml`) to scope it to that repository.
+
+Edit one from the menu it lives in — `Shift` + its key, or the ✎ on hover — or from either settings
+page. **An edit goes back to wherever the action was declared**: a file-declared action is rewritten
+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.
+
+---
+
+## Architecture
+
+A single local Node process serves both the API and the built web app — not multi-tenant, no cloud
+component.
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  packages/web      React 19 + Vite + Tailwind + Radix          │
+│                    TanStack Query · react-diff-view · Shiki    │
+│                    (dev: Vite proxies to Hono; prod: Hono       │
+│                     serves the built static assets)            │
+├─────────────────────────────────────────────────────────────┤
+│  packages/server   Hono · @hono/zod-openapi                    │
+│    ├─ GitHub:  Octokit (REST + ETag/304 for the list,          │
+│    │           GraphQL for batch enrichment); token from       │
+│    │           `gh auth token`                                 │
+│    ├─ git:     shells out to system `git`, serialized per repo │
+│    │           — diffs from worktrees, not the API             │
+│    └─ state:   SQLite (Drizzle) for change-requests + viewed   │
+├─────────────────────────────────────────────────────────────┤
+│  packages/shared   zod schemas + types = the one contract      │
+│                    (also published as an OpenAPI spec)         │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**Three distinct cache layers, never conflated:**
+1. **GitHub API cache** — ETag-keyed, TTL'd; `304`s are free, protecting your rate limit.
+2. **Diff / blob cache** — keyed on commit SHA, immutable, lives on the filesystem (XDG dirs).
+3. **User-state store** — Viewed/stale flags, local change-requests, drafts — in SQLite. (Ephemeral
+   UI prefs like the selected repo live in `localStorage` via a typed accessor.)
+
+**Agent-facing API.** Change-requests are a first-class resource: an agent can create inline review
+notes through the OpenAPI-described API (`/api/openapi.json`) and a separate call publishes them to
+GitHub — the exact same drafts a human authors in the Changes tab.
+
+---
+
+## Getting started
+
+**Requirements:** Node ≥ 22, pnpm ≥ 11, system `git`, and a source of a GitHub token — by default
+the GitHub CLI (`gh`) authenticated with `gh auth login`. See [Auth](#auth) for the alternatives.
+
+```bash
+# install from source
+pnpm install --frozen-lockfile
+
+# run in dev (web + server, hot reload)
+pnpm dev
+
+# or build + start the production server
+pnpm build
+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.
+
+`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.
+
+---
+
+## Running the server
+
+One `--listen` address in every form, rather than a port flag and a host flag that can disagree:
+
+```bash
+buhtig serve                              # 127.0.0.1:10003
+buhtig serve --listen 10004 --allow-remote # a port on every interface
+buhtig serve --listen 127.0.0.1:10004     # loopback only
+buhtig serve --listen '[::1]:10004'       # IPv6 — brackets required
+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.
+
+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
+one of them is told to `curl` the API; terminating in a proxy and forwarding to loopback keeps that
+answer well-defined. For either, put a proxy in front and point it at a port.
+
+### In the background
+
+```bash
+buhtig service install --listen 127.0.0.1:10004
+buhtig service status          # --json for a bug report
+buhtig service logs -f
+buhtig service restart | stop | start
+buhtig service uninstall
+```
+
+**systemd** user unit on Linux, **launchd** LaunchAgent on macOS — each platform's own convention.
+(Not `brew services`, which generates a plist from a Homebrew formula and would leave two supervisors
+for one process; not `SMAppService`, which needs a signed `.app` bundle.)
+
+The unit bakes in an absolute `PATH` covering node, `git`, and your token command. This is the
+difference between a service that works and one that boots and fails every request: launchd hands an
+agent `/usr/bin:/bin:/usr/sbin:/sbin`, which contains no Homebrew prefix and no version-manager
+shims. No secret is ever written to a unit — the token is resolved live at every start.
+
+`status` decides on a **health probe**, not on what the supervisor claims: launchd calls an agent
+loaded while the process inside it crash-loops. The supervisor's own view and the restart count are
+reported next to it, and a disagreement is called out.
+
+Two platform differences the CLI states rather than hides:
+
+- **Linux** — a user service dies when your last session ends unless you `loginctl enable-linger`.
+  `status` says so when lingering is off.
+- **macOS** — a LaunchAgent stops at logout and there is no per-user equivalent of lingering (the
+  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.
+
+---
+
+## Auth
+
+buhtig never stores a token. Every source is a pointer at a credential you already own, resolved
+fresh at startup, in this order:
+
+1. **`GH_TOKEN`** in the environment (`GITHUB_TOKEN` is also read, but don't use that name — under
+   GitHub Actions it holds the ephemeral workflow token).
+2. **`auth.tokenCommand`** — any command whose stdout is a token. Defaults to `gh auth token`.
+
+```yaml
+auth:
+  tokenCommand: [op, read, "op://Private/GitHub/token"]   # or: pass show github/token
+```
+
+`buhtig setup auth` walks through the choice and verifies the result against GitHub.
+
+> **Running as a background service?** Prefer a `tokenCommand` over `GH_TOKEN`. A launchd agent or a
+> systemd user unit reads no shell rc, so an exported variable never reaches it — and it gets a
+> four-entry `PATH` with no Homebrew prefix and no version-manager shims, so store the **absolute**
+> path to the binary. Missing the token is fatal at boot, and the error lands in a log file rather
+> than your terminal.
+
+---
+
+## Configuration
+
+Config lives at `~/.config/buhtig/config.yml` (XDG-aware) and is keyed by `org/repo`:
+
+```yaml
+acme/webapp:
+  # Where PR worktrees are checked out. Placeholders:
+  #   %n = PR number   %t = (cleaned) PR title   %a = PR author
+  worktreePathTemplate: /home/me/work/webapp-pr%n_%t
+
+  # Link ticket references in PR and commit titles, and expand references entered on stacks.
+  ticketing:
+    provider: linear
+    urlTemplate: https://linear.app/acme/issue/{ticket}
+    patterns:
+      - '(?<ticket>ENG-\d+)'
+```
+
+Ticket regexes use the named `ticket` group when present and the full match otherwise. Settings →
+Ticket links provides Linear, Jira, GitHub Issues and Azure Boards presets, a Custom option, and a
+live title preview. An exact URL can always be stored on a stack entry. Pull request numbers are
+linked regardless of the separately gated bare-issue linking feature.
+
+Per repo you can also configure a **local clone path** in Settings, so buhtig adds PR worktrees as
+siblings of your existing checkout (sharing its object store), and override the worktree template
+from the UI. Open-in-editor uses `$VISUAL`.
+
+### The coding agent
+
+Which agent the worktree actions launch is configured, never guessed:
+
+```yaml
+agent:
+  default: claude          # claude | codex | opencode
+  commands:
+    codex: [codex, --search]
+```
+
+A repo can override the *choice* (`agent: codex` in its own entry, or in `.git/buhtig.yaml`); the
+*commands* stay global, because which binary and flags `codex` means is a fact about your machine.
+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
+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
+window at a time). Where the CLI supports it that briefing goes in as an extra system prompt
+(`claude --append-system-prompt`) so it costs no user turn; everywhere else it rides in
+`$BUHTIG_AGENT_CONTEXT`, which the buhtig skills read.
+
+### 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.
+
+`/settings` holds the install-wide settings; each repo's gear holds its own and links there.
+
+### Structured review
+
+An agent-authored review is a **resource**, not a directory of markdown: a run over a PR at a head
+SHA, carrying one report per facet and scored, line-anchored findings.
+
+The facet taxonomy is **per-repo configuration**, resolved from a tree of facet markdown files the
+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.
+
+```yaml
+acme/webapp:
+  review:
+    # REQUIRED. How many subagents a review of this repo is worth; the orchestrator picks inside the
+    # band by change size and packs the facets into that many bundles. There is no default: a repo
+    # with no budget refuses to start a run, because the cost of a review has to be a decision
+    # somebody made rather than a consequence of how many facet files the taxonomy contains.
+    subagentBudget: { min: 3, max: 5 }
+
+    contract: REVIEW_CONTRACT.md        # relative to the taxonomy root
+    briefs: [../skills/business-rules/SKILL.md]
+
+    # The scales ship WITH their definitions — buhtig owns what `P0` means, which is what keeps a
+    # repo from having to restate the vocabulary in a reviewer contract of its own. Omit them
+    # entirely for P0–P4 and R0–R3; list bare keys to drop or reorder levels while keeping buhtig's
+    # prose; write a level out to give it this repo's own risks.
+    severities:
+      - P0
+      - { key: P1, title: Should block, hint: broken team scoping, unhandled failure path }
+    # sections defaults to the standard summary set.
+```
+
+Everything above is editable in the UI at `/<owner>/<repo>/review/settings`, alongside the facet
+tree itself.
+
+Discovery follows the taxonomy's own convention: a directory with an `index.md` is part of the tree,
+an `R<n>_` prefix sets priority, an **unprefixed** file inside a facet directory is a sub-facet leaf
+inheriting its parent's priority and slug, and `slug` is a *namespace* several files may share — the
+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:
+
+```bash
+./scripts/install-agent-integration.sh   # also run by install.sh
+```
+
+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.
+
+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,
+and files follow-ups. An agent cannot post its own findings.
+
+Findings anchor durably — resolved against the whole file at the run's head, not the diff, so a
+finding on code the PR never touched stays `active` — and a later push re-resolves them to
+`active` / `moved` / `stale`. Nothing is ever auto-deleted.
+
+```bash
+pnpm server    # rebuilds @buhtig/shared, then boots on $BUHTIG_PORT (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.
+
+### 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**:
+
+```yaml
+hooks:
+  # The PR worktree's setup command, run by the "Setup" button on the PR detail page. The command
+  # path is resolved relative to this file (i.e. the repo's .git dir), runs in the worktree's CWD,
+  # and gets a BUHTIG_PR env var with the PR number. A non-zero exit surfaces as an error.
+  postCheckoutWorktree: ./setup-worktree.sh
+```
+
+For example, `.git/setup-worktree.sh` might `gh pr checkout "$BUHTIG_PR"`, install deps, and
+generate a Prisma client so the worktree is ready to work in.
+
+Setup is **explicit**: checking a worktree out (to open a terminal, an agent, or a file in
+`$VISUAL`) never runs it. The button carries the worktree's setup state, and that state **decays** —
+buhtig records which worktree was set up, at which head, with which command, and when, then reports
+it as stale once the PR gets new commits, the setup command changes, the worktree is removed, or the
+record is over a day old (a setup script's real inputs — a registry, a lockfile, a database — live
+outside anything buhtig can watch, so an old "ready" is a guess, and says so).
+
+Secrets are never written to config or the database — the GitHub token is always sourced live from
+`gh`.
+
+---
+
+## Testing
+
+The testing seam fakes **GitHub's egress only** — never buhtig's own API or `git`.
+
+- **Unit / integration (Vitest):** a fake `GitHubClient` (selected with `BUHTIG_GH_MODE=fake`) backs
+  hand-authored fixtures, while `git` runs for real against ephemeral tmp repos. Backend tests read
+  as user scenarios (nested `describe`/`it` + expressive builders); the ephemeral repo is the single
+  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`).
+
+```bash
+pnpm test            # unit + integration (vitest)
+pnpm test:watch
+pnpm test:e2e        # playwright
+pnpm test:e2e:ui     # playwright UI mode
+pnpm typecheck
+pnpm lint            # biome
+```
+
+---
+
+## Project layout
+
+```
+packages/
+  server/   Hono API, git/worktree plumbing, GitHub client, SQLite state
+            (src/skills/ — the buhtig-review skill it serves to agents)
+  web/      React app: PR list, PR detail (Conversation + Changes), overlays
+  shared/   zod schemas & types — the single source-of-truth contract
+  sdk/      Generated OpenAPI client
+  github/   Octokit client, ETag cache, REST→domain mapping
+  mobile/   Capacitor wrapper (Android)
+e2e/        Playwright specs + fixtures
+```
+
+---
+
+<sub>buhtig is a local single-user tool. It reuses your `gh` credentials and scopes, stores no
+tokens, and talks to GitHub on your behalf only when an action requires it.</sub>

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "buhtig",
+  "version": "0.1.0-alpha.1",
+  "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"
+  },
+  "files": ["LICENSE", "README.md", "packages/cli/dist"],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/veracioux/buhtig.git"
+  },
+  "homepage": "https://github.com/veracioux/buhtig#readme",
+  "bugs": {
+    "url": "https://github.com/veracioux/buhtig/issues"
+  },
+  "author": "veracioux",
+  "keywords": ["github", "pull-request", "code-review", "git", "cli", "local-first"],
+  "publishConfig": {
+    "access": "public"
+  },
+  "packageManager": "pnpm@11.3.0",
+  "engines": {
+    "node": ">=22",
+    "pnpm": ">=11"
+  },
+  "scripts": {
+    "build": "turbo run build",
+    "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 .",
+    "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",
+    "test": "vitest run",
+    "test:e2e": "playwright test",
+    "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"
+  },
+  "dependencies": {
+    "better-sqlite3": "^11.8.1"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^1.9.4",
+    "@playwright/test": "^1.50.1",
+    "@types/node": "^22.13.1",
+    "esbuild": "^0.25.0",
+    "tsx": "^4.19.2",
+    "turbo": "^2.9.18",
+    "typescript": "^5.7.3",
+    "vitest": "^4.1.0"
+  }
+}