revdeck 0.0.0-stage → 0.1.0

package/docs/adr/0001-daemon-first.md

@@ -0,0 +1,63 @@
+# ADR-0001: Daemon-first architecture
+
+[English](0001-daemon-first.md) | [Русский](../ru/adr/0001-daemon-first.md)
+
+- **Status:** Accepted
+- **Date:** 2026-11-11
+
+## Context
+
+The first version of revdeck ran as a process that a human started manually on the host
+(`node devtools/mr-ui/server.mjs <N>`), and the agent communicated with it through `.revdeck/*.json`
+files. This gave the right security boundary (the agent does not publish, and the token stays on the
+host), but:
+
+- the server died with the terminal, and the link had to be copied manually;
+- file exchange caused races (file version, 409) and required syncing fields between the agent and
+  the UI;
+- it was impossible to have several reviews at once;
+- each project required its own copy of the script and ran in one process.
+
+What was needed: launch from a `/` command in any harness, a full-featured interface, several reviews,
+GitLab and GitHub, configurable project rules, and installation into any agent project.
+
+## Decision
+
+We build the product around a [local daemon](../architecture.md):
+
+- the `revdeck daemon` — a long-lived process owned by the user that holds credentials, SQLite,
+  providers, RPC, HTTP/SSE, and the UI;
+- the CLI and MCP are thin clients over RPC; the MCP server contains no review logic;
+- the agent writes only drafts; publication requires an approval tied to the plan hash;
+- the UI is a Svelte SPA served by the daemon and outlives the agent session;
+- state lives in SQLite under `~/.local/state/revdeck`, not in JSON in the repository;
+- the file format remains as `export`/`import` for compatibility and for sandboxes without a socket.
+
+## Alternatives considered
+
+1. **An MCP process per session, without a daemon.** Simpler installation, but the UI does not survive
+   the session, several agents compete for state, the token ends up in the process that the agent
+   launches, and the container scenario still requires a separate process on the host. Rejected.
+2. **File exchange only.** Maximum compatibility, but races and manual startup remain. Kept as
+   `export/import`, not as the primary path.
+3. **A cloud service.** Removes installation, but requires sending code and tokens outside. Contradicts
+   the "local, one person" requirement.
+
+## Consequences
+
+- A daemon lifecycle appears: socket, pid, logs, autostart (`daemon install`), handling of a stale
+  socket. The client can start the daemon itself.
+- Socket permissions are part of the security model: directory 0700, socket 0600.
+- In a container, either a mounted socket or `REVDECK_URL`/`REVDECK_TOKEN` is needed; otherwise, use
+  `export`/`import` and run on the host.
+- One daemon serves several repositories: `root` is passed on `open`, and the config is read from that
+  root.
+- Client and daemon versions must match; [`PROTOCOL_VERSION`](../protocol.md) was added.
+- This creates room for background sync and SSE, which improves UX compared to manually refreshing
+  the page.
+
+## Follow-up decisions
+
+- Native drafts (GitLab draft notes, GitHub pending review) are the next step; the provider interface
+  already contains `capabilities.nativeDrafts`.
+- A multi-user mode is not planned; if needed, a separate ADR.

package/docs/architecture.md

@@ -0,0 +1,91 @@
+# Architecture
+
+[English](architecture.md) | [Русский](ru/architecture.md)
+
+## Goals
+
+1. The agent receives review context and project rules deterministically, without manual files and
+   without access to platform tokens.
+2. Publishing to GitLab/GitHub happens only after human approval and is idempotent.
+3. One tool works in any harness: MCP for agent clients, the CLI as the universal layer, and a web UI
+   for humans.
+4. Project rules are [configured](configuration.md), not hardcoded in the prompt.
+
+## Non-goals
+
+- Replacing GitLab/GitHub's native diff viewer. The UI is optimized for triage and approval.
+- Built-in static analysis. Checks are delegated to the project's linter, types, and tests.
+- A multi-user server. The model is one user, several reviews, and a
+  [daemon on the host](adr/0001-daemon-first.md).
+
+## Components
+
+```text
+agent (MCP/CLI) ──▶ revdeck daemon ──glab/gh──▶ GitLab/GitHub
+                         │
+                   SQLite + UI ◀── human
+```
+
+- `src/core` — pure functions and models: unified diff parser, rules, finding fingerprints,
+  [publication sanitizer](threat-model.md), secret redaction, safe process execution.
+- `src/providers` — the only place that knows about platforms. `Provider` normalizes MR/PR, diff,
+  threads, replies, resolution, and comment creation.
+- `src/daemon/service.ts` — orchestrator: review refresh, drafts, decisions, publication plan,
+  approval, idempotent writes, background sync.
+- `src/daemon/store.ts` — SQLite (`node:sqlite`): reviews, diff/thread snapshot, drafts, findings,
+  decisions, comments, approvals, audit.
+- `src/daemon/rpc.ts` — [JSON-RPC](protocol.md) over a Unix socket (0600) for the CLI and MCP.
+- `src/daemon/http.ts` — UI and `/api/*`, SSE events, cookie session with a one-time token.
+- `src/cli` — commands, `init`, `doctor`, export/import of the old file format.
+- `src/mcp` — MCP server: tools and prompts, a thin wrapper over RPC.
+- `ui` — Svelte 5 SPA, built into `dist/ui`.
+
+## Data flow
+
+1. `revdeck open 42` → RPC `reviews.open` with the working copy `root`.
+2. The daemon determines the platform/host/project (arguments → config → git remote), creates a
+   provider, reads the MR, diff, and threads, and saves a snapshot and synthetic drafts.
+3. The agent requests `revdeck_context`: the daemon assembles effective rules (documents and sections
+   for changed paths), snippets, threads, and findings.
+4. The agent writes drafts (`drafts.put`, `findings.put`, `summary.put`, `notes.update`).
+5. A human in the UI calls `publish.preview` → sees the exact plan and hash → `publish.approve` →
+   `publish.commit`. The daemon executes only the items included in the approved plan.
+6. Background sync every 2 minutes refreshes open reviews and broadcasts SSE events to the UI.
+
+## Data model
+
+- `ReviewRef` — platform, host, project, number. `reviewId` — `platform:host/project!number`.
+- `DiffFile`/`Hunk`/`DiffLine` — line numbers in the old and new versions; a finding's `line` always
+  refers to the new file.
+- `Thread`/`Note` — shared discussion model.
+- `Finding` — a review finding with `id`, `fingerprint`, severity, file/line, text, and status
+  (`draft`, `accepted`, `rejected`, `published`, `fixed`, `stale`).
+- `Approval` — a one-time id tied to `hash = sha256(canonicalJson({reviewId, kind, items}))`,
+  with a 10-minute TTL.
+
+## Idempotency and concurrency
+
+- Draft and finding writes go through a single process; SQLite in WAL mode.
+- Publication marks the approval as used before execution. Items that have already been posted
+  (matching `posted`, `published`) are skipped. A failure of one item does not cancel the others and
+  is recorded in the draft/finding.
+- The plan hash protects against agent edits between the moment the plan is shown to the human and
+  publication: text changed → hash mismatch → approval rejected.
+- `findings.put` — replaces the set while preserving `id` and decision; findings that disappear are
+  marked `stale` rather than deleted.
+
+## Extension
+
+- **New platform**: implement `Provider` and add a branch in `createProvider`; nothing else changes.
+- **New harness**: `revdeck init --adapters <name>` copies the skill and writes the MCP config.
+  Harnesses without MCP use the CLI.
+- **Rules**: `rules.map`/`rules.sources` in `.revdeck.yml`; rule packs can be distributed as a regular
+  configuration file.
+- **Checks**: `checks` with argv, no shell; run only on explicit confirmation.
+
+## Performance
+
+- The diff is parsed on the server; the UI receives files as a list and hunks one file at a time.
+- Review state does not contain the full diff; SSE reports changes and the UI refetches the state.
+- Snippets for threads and findings are computed on the server and size-limited.
+- Rule context is capped at 320 KB; MCP context is capped by the `max_bytes` parameter.

package/docs/configuration.md

@@ -0,0 +1,121 @@
+# Configuration
+
+[English](configuration.md) | [Русский](ru/configuration.md)
+
+Configuration lives in the `.revdeck.yml` (or `.revdeck.yaml`) file at the repository root. The schema
+is validated with zod; an unknown field produces an error with the field path.
+
+```yaml
+version: 1
+provider:
+  type: auto            # auto | gitlab | github
+  host: gitlab.example.com
+  project: group/project
+  base: develop
+output:
+  language: auto        # auto | ru | en — language of findings and replies
+rules:
+  sources: [AGENTS.md]
+  map:
+    - match: ["src/**", "lib/**"]
+      docs: ["docs/Architecture.md", "docs/Styleguide.md#Базовый стиль"]
+      note: "application code"
+  ignore: ["**/generated/**"]
+checks:
+  - id: lint
+    name: ESLint
+    argv: [npm, run, lint]
+    when: ["src/**"]
+    consent: true
+    timeoutMs: 300000
+publish:
+  requireApproval: true
+  maxComments: 50
+```
+
+## provider
+
+| Field | Default | Meaning |
+|---|---|---|
+| `type` | `auto` | `auto` — inferred from the git remote; otherwise an explicit platform |
+| `host` | from the remote | host without a scheme |
+| `project` | from the remote | GitLab `group/project`, GitHub `owner/repo` |
+| `base` | `develop`/`main` | base for the local diff |
+
+Explicit CLI arguments (`--platform`, `--project`, `--host`) take precedence over the config, and the
+config takes precedence over the git remote. This way, tampering with `.git/config` cannot redirect the
+review to a different project.
+
+## output
+
+- `language: auto` — findings and replies are written in the language of the MR description and
+  discussions; if there is no text, English is used. `ru`/`en` pin the language explicitly.
+- The language of the rules and documents does not depend on this: the agent reads them as they are and
+  quotes them verbatim.
+- This is the language of the **review output**, not of the CLI/UI interface. The interface is switched
+  via `--lang ru|en`, `REVDECK_LANG`, or the toggle in the UI.
+- `revdeck init --lang en` selects the English skill and writes `REVDECK_LANG` to the MCP config.
+
+## rules
+
+- `sources` — the default documents when none of the `map` rows match. Empty — auto-discovery
+  (`AGENTS.md`, `CLAUDE.md`, `CONTRIBUTING.md`, `docs/ARCHITECTURE.md`, `docs/Architecture.md`,
+  `docs/STYLEGUIDE.md`, `docs/Styleguide.md`, `docs/CONTRIBUTING.md`).
+- `map` — a list of rules: `match` (a glob or an array of globs) and `docs` (an array of selectors).
+  Multiple matching rows are merged.
+- `ignore` — glob exclusions: a matching file is left out of rule analysis.
+
+### Document selectors
+
+| Selector | What is included |
+|---|---|
+| `docs/Architecture.md` | the entire document |
+| `docs/Styleguide.md#Базовый стиль` | the section for the heading (that level and below, up to the next heading of the same level) |
+| `docs/File.md#L10-L25` | a line range |
+| `docs/File.md#10-25` | the same range |
+
+A heading is normalized: case, whitespace, and punctuation do not matter. `#Слои и зависимости` and
+`#layers` are different sections, while `#Слои-и-зависимости` and `#Слои и зависимости` are the same
+section. If a section is not found, revdeck emits a warning and does not fall back to the whole document.
+
+### Glob
+
+`*` matches within one segment, `**` matches any depth, `?` matches one character, `{a,b}` is an
+alternative. Examples: `src/**/*.ts`, `docs/{guides,adr}/**`, `**/*.test.ts`.
+
+## checks
+
+Checks are argv arrays, not shell strings. This matters: the config lives in the repository, and a shell
+string would allow arbitrary code to be executed during a review.
+
+| Field | Meaning |
+|---|---|
+| `id` | stable identifier |
+| `name` | display name |
+| `argv` | command and arguments; the executable comes first |
+| `when` | glob paths: run only if the diff touched them; empty — always |
+| `consent` | requires explicit confirmation (default `true`) |
+| `timeoutMs` | timeout (default 300,000) |
+
+Running: `revdeck checks <N> --run --yes`. The MCP tool only shows the plan.
+
+## publish
+
+- `requireApproval` — kept for backward compatibility; approval is always required when publishing is
+  done by a non-interactive process.
+- `maxComments` — maximum number of comments per plan (1–200).
+
+## Environment variables
+
+| Variable | Meaning |
+|---|---|
+| `REVDECK_STATE_DIR` | state directory (default `~/.local/state/revdeck`) |
+| `REVDECK_RUNTIME_DIR` | socket directory (default `$XDG_RUNTIME_DIR/revdeck`) |
+| `REVDECK_URL` + `REVDECK_TOKEN` | connect to the daemon over HTTP (container/port forwarding) |
+| `REVDECK_ROOT` | project root for the MCP server |
+| `REVDECK_LANG` | CLI/MCP/daemon language: `ru` or `en` (default: system locale) |
+
+## Validation
+
+`revdeck config --json` shows the effective config, the path where it was found, and warnings.
+`revdeck rules --explain src/app.ts` shows which documents and sections were selected for the file.

package/docs/integrations.md

@@ -0,0 +1,84 @@
+# Harness integrations
+
+[English](integrations.md) | [Русский](ru/integrations.md)
+
+revdeck has two portable layers and one adapter layer:
+
+- **MCP** (stdio) — the `revdeck_*` tools work in any MCP-capable client.
+- **CLI** — the same capabilities without MCP: `revdeck open/context/findings/reply/publish`.
+- **`/` command** — each harness has its own; `revdeck init` creates the right file.
+
+A full integration = MCP + skill (procedures) + command (entry point). Without MCP, the CLI and
+skill remain: the agent calls commands through the shell.
+
+## Matrix
+
+| Harness | `/` command | What `init` writes |
+|---|---|---|
+| Claude Code | `/revdeck` | `.claude/commands/revdeck.md`, `.claude/skills/revdeck/*`, `.mcp.json` |
+| Cursor | `/revdeck` | `.cursor/commands/revdeck.md`, `.cursor/mcp.json` |
+| Codex CLI | prompt `revdeck` | `.codex/prompts/revdeck.md`; MCP in `~/.codex/config.toml` (manually) |
+| Gemini CLI | `/revdeck` | `.gemini/commands/revdeck.toml`; MCP in the Gemini settings (manually) |
+| OpenCode | `/revdeck` | `.opencode/command/revdeck.md` |
+| GitHub Copilot | prompt file | `.github/prompts/revdeck.prompt.md` |
+| DSH | plugin (see below) | `.agents/skills/revdeck/*` + YAML snippet in the output |
+| Universal | — | `.agents/skills/revdeck/*` + MCP |
+
+`revdeck init --adapters dsh,claude` explicitly enables the adapters you need. A repeated `init`
+does not overwrite existing command files and does not clobber other keys in `.mcp.json`.
+
+## MCP
+
+```json
+{
+  "mcpServers": {
+    "revdeck": {
+      "command": "npx",
+      "args": ["-y", "revdeck", "mcp"],
+      "env": { "REVDECK_LANG": "en" }
+    }
+  }
+}
+```
+
+`init` writes `npx -y revdeck mcp` into the MCP config. Publishing over MCP
+requires an `approval_id`: a human issues it in the UI or in the CLI with `--yes`, and the agent
+cannot obtain it.
+
+## DSH
+
+The DSH MCP client is configured in the Cordis profile:
+
+```yaml
+- id: mcp-revdeck
+  name: '@deepseek-ai/dsh-mcp-client'
+  config:
+    serverName: revdeck
+    transport: stdio
+    command: npx
+    args: ['-y', 'revdeck', 'mcp']
+    env:
+      REVDECK_LANG: en
+```
+
+The tools will appear as `mcp__revdeck__*`. DSH does not support MCP prompt templates, so `/revdeck`
+requires a host command (`ctx.commands.register`) or a client action — that is a separate wrapper
+plugin. Until then, use the skill + MCP tools: the `/` slash is not required for things to work.
+
+## Container
+
+The daemon runs on the host, the agent in a container. Options in decreasing order of convenience:
+
+1. Mount `$XDG_RUNTIME_DIR/revdeck` into the container at the same path — the socket works as is.
+2. `REVDECK_URL=http://host.docker.internal:<port>` and `REVDECK_TOKEN=<token>` — the HTTP transport.
+   The port and token are printed by `revdeck daemon start` (or in `daemon.json` in the state
+   directory).
+3. `revdeck export <N>` on the host and `revdeck import <N>` in the container — a file bridge.
+
+## Verification
+
+```bash
+revdeck doctor
+```
+
+Shows the binaries found, `glab`/`gh` authorization, daemon status and the installed adapter.

package/docs/protocol.md

@@ -0,0 +1,96 @@
+# Protocol
+
+[English](protocol.md) | [Русский](ru/protocol.md)
+
+## Transports
+
+1. **Unix socket** (primary): `$XDG_RUNTIME_DIR/revdeck/daemon.sock`, directory 0700, socket 0600.
+   JSON lines, one request/response per line.
+2. **HTTP**: `POST /api/rpc` on loopback with a cookie session. Needed for containers where the socket
+   is not forwarded (`REVDECK_URL` + `REVDECK_TOKEN`).
+3. **UI HTTP**: `/api/*` and SSE `/api/events` for the browser.
+
+## Messages
+
+Request:
+
+```json
+{"id": 1, "method": "reviews.get", "params": {"review": "gitlab:gitlab.com/group/project!42"}}
+```
+
+Response:
+
+```json
+{"id": 1, "result": {"review": {"id": "...", "info": {}, "threads": []}}}
+```
+
+Error:
+
+```json
+{"id": 1, "error": {"message": "...", "code": "APPROVAL", "hint": "..."}}
+```
+
+`id` is a number. A connection is considered untrusted until the first successful request:
+authorization is enforced by the socket file's permissions.
+
+## Methods
+
+| Method | Parameters | Result |
+|---|---|---|
+| `ping` | — | version, protocol, pid |
+| `reviews.list` | — | saved reviews |
+| `reviews.remoteList` | `root`, `scope`, `limit` | open reviews from the platform |
+| `reviews.open` | `root`, `input`/`platform`/`project`/`host`/`branch` | review snapshot |
+| `reviews.refresh` | `review` | refreshed snapshot |
+| `reviews.get` | `review`, `refresh?` | snapshot (without the full diff) |
+| `diff.get` | `review`, `file` | file hunks |
+| `drafts.put` | `review`, `threadId`, `patch` | draft |
+| `findings.put` | `review`, `findings[]` | findings after merge |
+| `findings.list` | `review` | findings |
+| `summary.put` | `review`, `summary` | summary |
+| `decisions.put` | `review`, `decisions` | human decisions |
+| `notes.add` | `review`, `file`, `line`, `text`, `toAgent` | line comment |
+| `notes.update` | `review`, `noteId`, `patch` | updated comment |
+| `notes.delete` | `review`, `noteId` | `{ok}` |
+| `publish.preview` | `review`, `kind`, `ids[]` | plan + warnings |
+| `publish.approve` | `review`, `kind`, `ids[]`, `hash` | `approvalId`, `expiresAt` |
+| `publish.commit` | `review`, `approvalId` | per-item results |
+| `rules.get` | `review` | rules markdown, checks, warnings |
+| `checks.run` | `review`, `allowRun`, `ids[]` | check results |
+| `audit.tail` | `limit` | latest actions |
+
+## Approval
+
+1. `publish.preview` builds `items` — the exact bodies, paths, lines, and resolve flags — and
+   `hash = sha256(canonicalJson({reviewId, kind, items}))`.
+2. The human sees the plan. `publish.approve` recomputes the plan from the same `ids`; if the hash does
+   not match, it returns an error. Otherwise it creates a one-time `approval_id` with a 10-minute TTL.
+3. `publish.commit` verifies that the approval has not been used and has not expired, marks it as used,
+   and executes only `items`. Items that have already been posted are skipped.
+
+The agent cannot call `publish.approve`: the MCP tool does not expose it. A human confirms in the UI or
+in the CLI with `--yes`.
+
+## HTTP API (UI)
+
+| Method | Path | Purpose |
+|---|---|---|
+| GET | `/` | SPA; `?t=<token>` sets the cookie and redirects |
+| GET | `/assets/*` | static build assets |
+| GET | `/api/health` | liveness |
+| GET | `/api/reviews` | review list |
+| GET | `/api/state?review=` | snapshot for the UI |
+| GET | `/api/diff?review=&file=` | file hunks |
+| GET | `/api/rules?review=` | rules |
+| GET | `/api/events` | SSE: `review` |
+| POST | `/api/reviews/open`, `/api/reviews/refresh` | open/refresh |
+| POST | `/api/drafts`, `/api/findings`, `/api/summary`, `/api/decisions` | drafts |
+| POST | `/api/notes` | `action: add/update/delete` |
+| POST | `/api/publish/preview`, `/approve`, `/commit` | publishing |
+| POST | `/api/checks` | checks |
+| POST | `/api/rpc` | RPC proxy for the HTTP transport |
+
+## Versioning
+
+`PROTOCOL_VERSION` in `src/version.ts` is checked during the handshake; the client and daemon must be
+the same package version. A method mismatch returns `METHOD` with a hint to update revdeck.

package/docs/ru/README.md

@@ -0,0 +1,17 @@
+# Документация revdeck
+
+[English](../README.md) | Русский
+
+Английская документация в `docs/` — каноническая; русские переводы лежат рядом в `docs/ru/` и могут
+немного отставать.
+
+| Документ | Английский | Русский |
+|---|---|---|
+| Архитектура | [../architecture.md](../architecture.md) | [architecture.md](architecture.md) |
+| Конфигурация и правила | [../configuration.md](../configuration.md) | [configuration.md](configuration.md) |
+| Протокол RPC и HTTP | [../protocol.md](../protocol.md) | [protocol.md](protocol.md) |
+| Модель угроз | [../threat-model.md](../threat-model.md) | [threat-model.md](threat-model.md) |
+| Интеграции с харнессами | [../integrations.md](../integrations.md) | [integrations.md](integrations.md) |
+| ADR-0001: демон-first | [../adr/0001-daemon-first.md](../adr/0001-daemon-first.md) | [adr/0001-daemon-first.md](adr/0001-daemon-first.md) |
+
+Начните с [README](../../README.ru.md): установка, команды и настройка MCP.

package/docs/ru/adr/0001-daemon-first.md

@@ -0,0 +1,61 @@
+# ADR-0001: Демон-first архитектура
+
+[English](../../adr/0001-daemon-first.md) | Русский
+
+- **Статус:** Accepted
+- **Дата:** 2026-11-11
+
+## Контекст
+
+Первая версия revdeck работала как процесс, который человек запускал вручную на хосте
+(`node devtools/mr-ui/server.mjs <N>`), а агент общался с ним через файлы `.revdeck/*.json`.
+Это давало правильную границу безопасности (агент не публикует, токен остаётся на хосте), но:
+
+- сервер умирал вместе с терминалом, ссылку нужно было копировать вручную;
+- файловый обмен давал гонки (версия файла, 409) и требовал синхронизации полей между агентом и UI;
+- нельзя было держать несколько ревью одновременно;
+- каждый проект требовал своей копии скрипта и шёл в одном процессе.
+
+Нужны: запуск по `/`-команде в любом харнессе, полноценный интерфейс, несколько ревью, GitLab и
+GitHub, конфигурируемые правила проекта и установка в любой агентский проект.
+
+## Решение
+
+Строим продукт вокруг локального демона:
+
+- демон `revdeck daemon` — долгоживущий процесс пользователя, держит креды, SQLite, провайдеры, RPC,
+  HTTP/SSE и UI;
+- CLI и MCP — тонкие клиенты к RPC; MCP-сервер не содержит логики ревью;
+- агент пишет только черновики; публикация требует approval, привязанного к хешу плана;
+- UI — Svelte SPA, отдаётся демоном, живёт дольше сессии агента;
+- состояние — SQLite в `~/.local/state/revdeck`, а не JSON в репозитории;
+- файловый формат остаётся как `export`/`import` для совместимости и песочниц без сокета.
+
+## Рассмотренные альтернативы
+
+1. **MCP-процесс на сессию, без демона.** Проще установка, но UI не переживает сессию, несколько
+   агентов конкурируют за состояние, токен оказывается в процессе, который запускает агент, и
+   контейнерный сценарий всё равно требует отдельного процесса на хосте. Отклонено.
+2. **Только файловый обмен.** Максимальная совместимость, но гонки и ручной запуск остаются.
+   Оставлено как `export/import`, не как основной путь.
+3. **Облачный сервис.** Снимает установку, но требует передавать код и токены наружу. Противоречит
+   требованию «локально, один человек».
+
+## Последствия
+
+- Появляется жизненный цикл демона: сокет, pid, логи, автозапуск (`daemon install`), обработка
+  зависшего сокета. Клиент умеет поднять демон сам.
+- Права на сокет — часть модели безопасности: каталог 0700, сокет 0600.
+- В контейнере нужен либо смонтированный сокет, либо `REVDECK_URL`/`REVDECK_TOKEN`; иначе —
+  `export`/`import` и запуск на хосте.
+- Один демон обслуживает несколько репозиториев: `root` передаётся при `open`, конфиг читается из
+  этого корня.
+- Версии клиента и демона должны совпадать; добавлен `PROTOCOL_VERSION`.
+- Появляется место для фонового sync и SSE, что улучшает UX по сравнению с ручным обновлением
+  страницы.
+
+## Последующие решения
+
+- Native drafts (GitLab draft notes, GitHub pending review) — следующий шаг; интерфейс провайдера
+  уже содержит `capabilities.nativeDrafts`.
+- Многопользовательский режим не планируется; при необходимости — отдельный ADR.

package/docs/ru/architecture.md

@@ -0,0 +1,91 @@
+# Архитектура
+
+[English](../architecture.md) | Русский
+
+## Цели
+
+1. Агент получает контекст ревью и правила проекта детерминированно, без ручных файлов и без доступа
+   к токенам платформ.
+2. Публикация в GitLab/GitHub происходит только после подтверждения человеком и идемпотентна.
+3. Один инструмент работает в любом харнессе: MCP для агентских клиентов, CLI как универсальный
+   слой, веб-интерфейс для человека.
+4. Правила проекта конфигурируются, а не зашиты в промпт.
+
+## Не цели
+
+- Замена нативного diff-вьюера GitLab/GitHub. UI оптимизирован под триаж и подтверждение.
+- Собственный статический анализ. Проверки делегируются линту, типам и тестам проекта.
+- Многопользовательский сервер. Модель — один пользователь, несколько ревью, демон на хосте.
+
+## Компоненты
+
+```text
+agent (MCP/CLI) ──▶ revdeck daemon ──glab/gh──▶ GitLab/GitHub
+                         │
+                   SQLite + UI ◀── human
+```
+
+- `src/core` — чистые функции и модели: парсер unified diff, правила, fingerprints замечаний,
+  санитайзер публикации, редакция секретов, безопасный запуск процессов.
+- `src/providers` — единственное место, знающее о платформах. `Provider` нормализует MR/PR, diff,
+  треды, ответы, резолв и создание комментариев.
+- `src/daemon/service.ts` — оркестратор: обновление ревью, черновики, решения, план публикации,
+  approval, идемпотентная запись, фоновый sync.
+- `src/daemon/store.ts` — SQLite (`node:sqlite`): ревью, снимок diff/тредов, черновики, замечания,
+  решения, комментарии, approvals, аудит.
+- `src/daemon/rpc.ts` — JSON-RPC поверх unix-сокета (0600) для CLI и MCP.
+- `src/daemon/http.ts` — UI и `/api/*`, SSE-события, cookie-сессия с одноразовым токеном.
+- `src/cli` — команды, `init`, `doctor`, экспорт/импорт старого файлового формата.
+- `src/mcp` — MCP-сервер: инструменты и промпты, тонкая обёртка над RPC.
+- `ui` — Svelte 5 SPA, собирается в `dist/ui`.
+
+## Поток данных
+
+1. `revdeck open 42` → RPC `reviews.open` с `root` рабочей копии.
+2. Демон определяет платформу/хост/проект (аргументы → конфиг → git remote), создаёт провайдер,
+   читает MR, diff и треды, сохраняет снимок и синтетические черновики.
+3. Агент запрашивает `revdeck_context`: демон собирает эффективные правила (документы и секции для
+   изменённых путей), сниппеты, треды и замечания.
+4. Агент пишет черновики (`drafts.put`, `findings.put`, `summary.put`, `notes.update`).
+5. Человек в UI вызывает `publish.preview` → видит точный план и хеш → `publish.approve` →
+   `publish.commit`. Демон выполняет только пункты, вошедшие в подтверждённый план.
+6. Фоновый sync раз в 2 минуты обновляет открытые ревью и рассылает SSE-события UI.
+
+## Модель данных
+
+- `ReviewRef` — платформа, хост, проект, номер. `reviewId` — `platform:host/project!number`.
+- `DiffFile`/`Hunk`/`DiffLine` — номера строк по старой и новой версии; `line` замечания всегда по
+  новому файлу.
+- `Thread`/`Note` — общая модель обсуждений.
+- `Finding` — замечание с `id`, `fingerprint`, уровнем, файлом/строкой, текстом и статусом
+  (`draft`, `accepted`, `rejected`, `published`, `fixed`, `stale`).
+- `Approval` — одноразовый id, привязанный к `hash = sha256(canonicalJson({reviewId, kind, items}))`,
+  TTL 10 минут.
+
+## Идемпотентность и конкурентность
+
+- Записи черновиков и замечаний идут через один процесс; SQLite в WAL.
+- Публикация помечает approval использованным до выполнения. Пункты, которые уже ушли (совпадающий
+  `posted`, `published`), пропускаются. Ошибка одного пункта не отменяет остальные и записывается в
+  черновик/замечание.
+- Хеш плана защищает от правки агентом между показом человеку и публикацией: изменился текст → хеш
+  не совпал → approve отклонён.
+- `findings.put` — замена набора с сохранением `id` и решения; исчезнувшие замечания помечаются
+  `stale`, а не удаляются.
+
+## Расширение
+
+- **Новая платформа**: реализовать `Provider` и добавить ветку в `createProvider`; всё остальное не
+  меняется.
+- **Новый харнесс**: `revdeck init --adapters <имя>` копирует skill и пишет MCP-конфиг. Для
+  харнессов без MCP используется CLI.
+- **Правила**: `rules.map`/`rules.sources` в `.revdeck.yml`; паки правил можно распространять как
+  обычный файл конфигурации.
+- **Проверки**: `checks` с argv без shell; запуск только по явному подтверждению.
+
+## Производительность
+
+- Diff парсится на сервере, UI получает файлы списком и hunks по одному файлу.
+- Состояние ревью не содержит полный diff; SSE сообщает об изменениях, UI перезапрашивает состояние.
+- Сниппеты для тредов и замечаний считаются на сервере и ограничены по размеру.
+- Контекст правил ограничен 320 КБ; MCP-контекст — параметром `max_bytes`.