wiki-viewer 1.4.3 → 1.5.1

package/.next/standalone/README.md

@@ -22,8 +22,10 @@
 Originally a zero-config single-user tool, it now supports:
 
 - Multi-user sign-in (Google OAuth or email + password) for teams of 3 to 10 sharing a VPS.
-- An HTTP collaboration API that lets AI agents read and edit Markdown files alongside you, with provenance marks, comments, suggestions, and revision-checked mutations.
+- An HTTP API for AI agents with **two tiers**: a raw filesystem (read/write/edit/list/search/move/delete for **all file types**) for fast filework, and a Markdown collaboration layer with provenance marks, comments, suggestions, and revision-checked mutations.
+- A **working-vs-collaborating** safety model: when you have a Markdown doc open, agents automatically defer to the reviewable collab path instead of overwriting it.
 - Per-agent registration and scoped tokens. No shared bearer secret.
+- An optional `npx wiki-viewer-mcp` adapter so MCP-capable agents (Claude Code, Cursor, Codex) get native file tools against a remote instance.
 
 Single-user, no-auth mode still works. Auth turns on automatically once anyone signs up.
 
@@ -279,7 +281,23 @@ The Markdown editor now sends a `baseRevision` with every save. If another user
 
 ## Working with AI agents
 
-wiki-viewer exposes an HTTP collaboration protocol so agents (Claude, Cursor, ChatGPT desktop, custom scripts) can read and edit Markdown files. Every AI-authored insert is wrapped in an inline `<proof-span>` mark so the human reviewer can see, accept, or revert each change.
+wiki-viewer exposes an HTTP API so agents (Claude, Cursor, ChatGPT desktop, custom scripts) can work with files in a running instance — locally or remotely — almost as if they were on their own filesystem. There are **two tiers**, sharing one auth/scope/lock spine:
+
+- **Tier 1 — Raw filesystem** (`/api/agent/fs/*`): `read`, `write`, `edit`, `list`, `search`, `move`, `delete` for **every file type** (code, configs, PDFs, notebooks, Markdown — anything). Fast, boring, byte-accurate. Mutations are audited.
+- **Tier 2 — Markdown collaboration** (`/api/agent/files/*`): structured block-ops where every AI-authored insert is wrapped in an inline `<proof-span>` mark so the human reviewer can see, accept, or revert each change, plus comments and suggestions. Tier-2 is API-compatible in spirit with [Proof SDK](https://github.com/EveryInc/proof-sdk).
+
+### Which tier? Working mode vs collaborating mode
+
+Before editing a Markdown file, an agent reads it and checks the **`X-Collab-State`** response header:
+
+| `X-Collab-State` | Meaning                                                          | Agent uses                                                                      |
+| ---------------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------- |
+| `active`         | A human has the doc open, or it has pending suggestions/comments | **Tier-2 block-ops** (reviewable). A raw write is rejected `409 COLLAB_ACTIVE`. |
+| `tracked`        | Has a collab sidecar, nobody editing now                         | Prefer Tier-2 for prose; raw OK for mechanical edits                            |
+| `untracked`      | Plain Markdown, never collaborated on                            | Either tier                                                                     |
+| `not-markdown`   | Any non-`.md` file                                               | **Tier-1 raw only**                                                             |
+
+This is enforced, not advisory: the collab state is re-checked atomically inside the write lock, so an agent can never silently clobber a doc you just opened. The browser editor sends a presence heartbeat to drive the `active` state. See [`docs/file-vs-collab-authority.md`](docs/file-vs-collab-authority.md) for the full authority model.
 
 The protocol is intentionally API-compatible in spirit with [Proof SDK](https://github.com/EveryInc/proof-sdk).
 
@@ -306,7 +324,42 @@ npx skills add anh-chu/wiki-viewer/agents/wiki-viewer-skill
 
 For any chat agent, paste the bootstrap prompt from `<your-server>/agents/install` (also visible in the AI Panel). The agent fetches `/api/agents/install` and learns the full op vocabulary at runtime.
 
-### Op vocabulary
+### Tier 1 — raw filesystem
+
+Work with any file type. All routes take `Authorization: Bearer <token>` + `X-Agent-Id`, are scope-checked, and reject path traversal, symlink escapes, and anything under `.proof/`.
+
+```bash
+# Read (bytes; ETag is the sha256, supports Range, returns X-Collab-State)
+curl -sD- -H "Authorization: Bearer $TOKEN" -H "X-Agent-Id: ai:claude" \
+  https://wiki.team.com/api/agent/fs/file/src/util.ts
+
+# Write/overwrite (atomic). If-Match: <sha256> is required to overwrite;
+# omit it to create. ?mkdirs=true creates parent dirs. ?force=true overrides (audited).
+curl -s -X PUT -H "Authorization: Bearer $TOKEN" -H "X-Agent-Id: ai:claude" \
+  -H "If-Match: <sha256-from-read>" --data-binary @util.ts \
+  https://wiki.team.com/api/agent/fs/file/src/util.ts
+
+# List a directory (scope-filtered)
+curl -s -H "Authorization: Bearer $TOKEN" -H "X-Agent-Id: ai:claude" \
+  "https://wiki.team.com/api/agent/fs/ls/src?recursive=true&limit=500"
+
+# Search (server-side; kills round-trips)
+curl -s -X POST -H "Authorization: Bearer $TOKEN" -H "X-Agent-Id: ai:claude" \
+  -H "Content-Type: application/json" \
+  -d '{"kind":"grep","query":"TODO","glob":"**/*.ts"}' \
+  https://wiki.team.com/api/agent/fs/search
+
+# Move and delete (delete needs the `delete` scope + If-Match)
+curl -s -X POST -H "Authorization: Bearer $TOKEN" -H "X-Agent-Id: ai:claude" \
+  -H "Content-Type: application/json" -d '{"from":"a.md","to":"b.md"}' \
+  https://wiki.team.com/api/agent/fs/move
+curl -s -X DELETE -H "Authorization: Bearer $TOKEN" -H "X-Agent-Id: ai:claude" \
+  -H "If-Match: <sha256>" https://wiki.team.com/api/agent/fs/file/old.md
+```
+
+Mutating a Markdown file via raw write emits a `file.rawWritten` event and re-binds the collab sidecar; if the doc is `active` it is rejected `409 COLLAB_ACTIVE` (use Tier-2 instead). Use the **`npx wiki-viewer-mcp`** adapter to get all of this as standard MCP file tools — it handles `If-Match`, mode-awareness, and edit-via-read-then-write for you.
+
+### Tier 2 — op vocabulary (Markdown)
 
 Block-level edits (revision-checked, idempotent):
 
@@ -356,15 +409,23 @@ Owner-only (session cookie):
 
 Agent routes (bearer + `X-Agent-Id`, scope-checked):
 
-| Method | Path                                     | Required scope        |
-| ------ | ---------------------------------------- | --------------------- |
-| `GET`  | `/api/agent/files/<path.md>`             | `read` + path match   |
-| `POST` | `/api/agent/files/<path.md>`             | `mutate` + path match |
-| `GET`  | `/api/agent/events/<path.md>?after=<id>` | `read` + path match   |
-| `POST` | `/api/agent/events/<path.md>`            | `read` + path match   |
-| `GET`  | `/api/agent/sidecar/<path.md>`           | `read` + path match   |
-| `GET`  | `/api/agent/settings`                    | `read`                |
-| `GET`  | `/api/agent/activity`                    | `read`                |
+| Method   | Path                                     | Required scope        | Tier |
+| -------- | ---------------------------------------- | --------------------- | ---- |
+| `GET`    | `/api/agent/fs/file/<path>`              | `read` + path match   | 1    |
+| `PUT`    | `/api/agent/fs/file/<path>`              | `mutate` + path match | 1    |
+| `DELETE` | `/api/agent/fs/file/<path>`              | `delete` + path match | 1    |
+| `GET`    | `/api/agent/fs/ls/<path>`                | `read` + path match   | 1    |
+| `POST`   | `/api/agent/fs/move`                     | `mutate` (src+dest)   | 1    |
+| `POST`   | `/api/agent/fs/search`                   | `read` (per match)    | 1    |
+| `GET`    | `/api/agent/files/<path.md>`             | `read` + path match   | 2    |
+| `POST`   | `/api/agent/files/<path.md>`             | `mutate` + path match | 2    |
+| `GET`    | `/api/agent/events/<path.md>?after=<id>` | `read` + path match   | 2    |
+| `POST`   | `/api/agent/events/<path.md>`            | `read` + path match   | 2    |
+| `GET`    | `/api/agent/sidecar/<path.md>`           | `read` + path match   | 2    |
+| `GET`    | `/api/agent/settings`                    | `read`                | —    |
+| `GET`    | `/api/agent/activity`                    | `read`                | —    |
+
+Scopes: `paths` is a glob list (directories work natively, e.g. `notes/**`); `ops` is any of `read`, `mutate` (create/overwrite/move), `delete` (remove). Grant `["read","mutate"]` for edit-but-never-delete.
 
 ### Full curl trace
 
@@ -373,7 +434,7 @@ Agent routes (bearer + `X-Agent-Id`, scope-checked):
 curl -s -X POST https://wiki.team.com/api/agent/register \
   -H "Content-Type: application/json" \
   -d '{"id":"ai:claude","displayName":"Claude",
-       "scope":{"paths":["**/*"],"ops":["read","mutate"]}}'
+       "scope":{"paths":["**/*"],"ops":["read","mutate","delete"]}}'
 # -> { "registrationId":"reg_abc","pollUrl":"/api/agent/register/reg_abc","status":"pending" }
 
 # 2. Owner approves in the AI Panel.
@@ -406,9 +467,11 @@ Response codes to handle:
 
 - `401 UNAUTHORIZED` — bad token or `X-Agent-Id`.
 - `403 FORBIDDEN` — out of scope or `by` mismatches identity.
-- `409 STALE_REVISION` — refetch and retry. Response includes a fresh snapshot.
-- `409 BLOCK_NOT_FOUND` — the ref no longer exists.
-- `409 IDEMPOTENCY_KEY_REUSED` — same key, different body.
+- `409 STALE_REVISION` — refetch and retry. Response includes a fresh snapshot. (Tier 2)
+- `409 BLOCK_NOT_FOUND` — the ref no longer exists. (Tier 2)
+- `409 IDEMPOTENCY_KEY_REUSED` — same key, different body. (Tier 2)
+- `409 COLLAB_ACTIVE` — raw write to a Markdown doc a human is editing; use Tier-2 block-ops (response includes the snapshot URL) or `?force=true`. (Tier 1)
+- `412 PRECONDITION_FAILED` — `If-Match` sha mismatch (file changed); re-read and retry. (Tier 1)
 - `429 RATE_LIMITED` — honor `Retry-After`. Default 60 ops/minute per agent.
 
 ### Agent rate limit override

package/.next/standalone/agents/bootstrap-prompt.md

@@ -1 +1,12 @@
-You are connecting to a running wiki-viewer instance at $WIKI_URL (e.g. `http://localhost:3000`). Fetch `$WIKI_URL/api/agents/install`and follow the instructions there to register, wait for human approval, then read and edit markdown files via its HTTP API. Set`basis`and`basisDetail`on every content op so the human can see where your changes came from. Prefer`suggestion.add` over direct block ops unless told otherwise.
+You are connecting to a running wiki-viewer instance at $WIKI_URL (e.g. `http://localhost:3000`). Fetch `$WIKI_URL/api/agents/install` and follow the instructions there to register, wait for human approval, then work with files via its HTTP API.
+
+**Two tiers — pick by `X-Collab-State`:**
+
+- **Tier 1 Raw FS** (`/api/agent/fs/*`) — all file types, fast read/write/ls/search. Use for code, binaries, and markdown that isn't being actively co-edited.
+- **Tier 2 Collab** (`/api/agent/files/*.md`) — markdown only, reviewable proof-spans. Use when `X-Collab-State: active` (human has the doc open or it has pending suggestions).
+
+**Mode rule:** Every file read returns `X-Collab-State`. If `active` → use Tier-2 block-ops so the human can review. Otherwise → use Tier-1 raw fs. A raw write to an `active` .md is rejected 409 `COLLAB_ACTIVE` with the Tier-2 URL.
+
+Set `basis` and `basisDetail` on every Tier-2 content op so the human can see where your changes came from. Prefer `suggestion.add` over direct block ops unless told otherwise.
+
+MCP-capable agents: `npx wiki-viewer-mcp` (set `WIKI_VIEWER_URL`, `WIKI_VIEWER_TOKEN`, `WIKI_VIEWER_AGENT_ID`) handles tier routing automatically.

package/.next/standalone/agents/wiki-viewer-skill/SKILL.md

@@ -8,6 +8,17 @@ license: MIT
 
 You are working with **wiki-viewer**, a local-first markdown viewer that exposes a Proof-SDK-compatible HTTP API for agents. Files on disk are the source of truth. Every AI-authored edit is wrapped in an inline `<proof-span>` mark so the human can see, accept, or revert your contribution.
 
+## Quick orientation: two tiers
+
+| Tier                | Routes                  | File types                          | When to use                                                                       |
+| ------------------- | ----------------------- | ----------------------------------- | --------------------------------------------------------------------------------- |
+| **Tier 1 — Raw FS** | `/api/agent/fs/*`       | All types (markdown, code, binary…) | Fast filework. Read, write, list, move, delete, search. Audited but no review UI. |
+| **Tier 2 — Collab** | `/api/agent/files/*.md` | Markdown only                       | Reviewable prose. Edits become proof-spans the human can accept/revert.           |
+
+Both tiers use the same auth (TOFU token). Pick the tier based on `X-Collab-State` (see [Which tier do I use?](#which-tier-do-i-use)).
+
+---
+
 ## Discovery
 
 The server publishes everything you need at one URL:
@@ -214,6 +225,180 @@ Acks are advisory; events are never deleted.
 | 422    | INVALID_MARKDOWN       | op's markdown failed to parse                      |
 | 429    | RATE_LIMITED           | bucket exhausted, honor `Retry-After` header       |
 
+---
+
+## Working with files (raw filesystem — Tier 1)
+
+All Tier-1 routes require `Authorization: Bearer <token>` + `X-Agent-Id: ai:<name>` (same as Tier 2). The agent's `scope.paths` glob applies to every surface (reads, ls results, search results, move, delete).
+
+### Scope ops
+
+When registering, `scope.ops` can include:
+
+- `read` — read files + list + search
+- `mutate` — create / overwrite / move
+- `delete` — remove files/dirs (separate from mutate so a human can grant edit-but-never-delete)
+
+Example registration with full access:
+
+```json
+{
+  "id": "ai:claude",
+  "scope": { "paths": ["**/*"], "ops": ["read", "mutate", "delete"] }
+}
+```
+
+### Read a file
+
+```
+GET /api/agent/fs/file/<path>
+```
+
+Returns raw bytes. Metadata in response headers:
+
+```
+ETag: "<sha256>"
+X-File-Size: <bytes>
+X-File-Mtime: <ISO-8601>
+Content-Type: <mime>
+X-Collab-State: active | tracked | untracked | not-markdown
+X-Collab-Revision: <n>
+X-Collab-Snapshot: /api/agent/files/<path>.md   # when applicable
+```
+
+Supports `Range` header for large/binary files.
+
+### Write a file
+
+```
+PUT /api/agent/fs/file/<path>
+If-Match: "<sha256>"          # required for overwrites; omit for creates
+Content-Type: <mime>
+<raw bytes body>
+```
+
+- **Create** (file doesn't exist): omit `If-Match`. Creating a file that already exists without `If-Match` → 412 (no blind clobber).
+- **Overwrite** (file exists): send `If-Match` with the sha256 you read. Mismatch → 412.
+- `?mkdirs=true` — create parent directories.
+- `?force=true` — bypass `If-Match` check (audited; use sparingly).
+
+For `.md` files, also send:
+
+```
+If-Collab-Match: <X-Collab-Revision>   # prevents writing into a live collab session
+```
+
+(See [Which tier do I use?](#which-tier-do-i-use).)
+
+Response:
+
+```json
+{
+  "path": "...",
+  "sha256": "...",
+  "size": 1234,
+  "mtime": "...",
+  "created": false
+}
+```
+
+### Delete a file
+
+```
+DELETE /api/agent/fs/file/<path>
+If-Match: "<sha256>"    # required — you must have read the file first
+```
+
+Requires `delete` in `scope.ops`. Deletes the `.proof/` sidecar too for `.md` files. For directories: `?recursive=true`.
+
+### List a directory
+
+```
+GET /api/agent/fs/ls/<path>?recursive=true&limit=500&depth=3
+```
+
+Returns `{ entries: [{name, type, path, size, mtime}] }`. Unauthorized paths silently omitted. Excludes `.proof/`.
+
+### Move / rename
+
+```
+POST /api/agent/fs/move
+Content-Type: application/json
+
+{ "from": "notes/old.md", "to": "notes/new.md", "ifMatch": "<sha256>" }
+```
+
+Moves the `.proof/` sidecar for `.md` files automatically.
+
+### Search (grep / glob)
+
+```
+POST /api/agent/fs/search
+Content-Type: application/json
+
+{ "kind": "grep", "query": "TODO", "path": "src", "glob": "*.ts", "limit": 100 }
+```
+
+```
+POST /api/agent/fs/search
+Content-Type: application/json
+
+{ "kind": "glob", "query": "**/*.test.ts" }
+```
+
+Server-side: one call replaces dozens of `ls`+`read` round-trips. Results are scope-filtered. Glob dialect: `**`, `*`, `?` only (no braces/negation in v1).
+
+### Error codes (Tier 1)
+
+| Status | Code                | Meaning                                                                     |
+| ------ | ------------------- | --------------------------------------------------------------------------- |
+| 400    | BAD_REQUEST         | Invalid path or body                                                        |
+| 401    | UNAUTHORIZED        | Bad/missing token or X-Agent-Id                                             |
+| 403    | FORBIDDEN           | Scope mismatch or missing `delete` op                                       |
+| 404    | NOT_FOUND           | Path doesn't exist                                                          |
+| 409    | COLLAB_ACTIVE       | Raw PUT rejected — doc is active-collab; use Tier-2 or send If-Collab-Match |
+| 412    | PRECONDITION_FAILED | If-Match sha mismatch (concurrent modification)                             |
+| 413    | PAYLOAD_TOO_LARGE   | File exceeds 50 MB limit                                                    |
+| 429    | RATE_LIMITED        | Honor `Retry-After`                                                         |
+
+---
+
+## Which tier do I use?
+
+Every `GET /api/agent/fs/file/<path>` (and every Tier-2 snapshot read) returns `X-Collab-State`.
+
+| `X-Collab-State` | Meaning                                                                                       | Use                                                                                                  |
+| ---------------- | --------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| `active`         | Human has this `.md` open in the editor, OR it has pending suggestions / unresolved comments. | **Tier 2 block-ops only.** A raw `PUT` returns `409 COLLAB_ACTIVE`.                                  |
+| `tracked`        | `.md` has a sidecar (prior collab history), no active session.                                | Prefer Tier-2 for prose/semantic edits. Raw ok for mechanical/whole-file ops (reformat, regenerate). |
+| `untracked`      | `.md`, no sidecar yet.                                                                        | Raw is fine. Tier-2 creates a sidecar (starts provenance tracking).                                  |
+| `not-markdown`   | Any non-`.md` file.                                                                           | **Tier-1 raw only.** Tier 2 does not apply.                                                          |
+
+**Rule (one sentence):** Read the file, check `X-Collab-State`, use Tier-2 if `active`, else use Tier-1. For non-markdown, always Tier-1.
+
+**Editing a `.md` safely:**
+
+```
+1. GET /api/agent/fs/file/<path>.md
+   → note ETag (sha256) and X-Collab-Revision + X-Collab-State
+
+2a. If X-Collab-State == "active":
+    → POST /api/agent/files/<path>.md  (block-ops, Tier-2)
+      Use the X-Collab-Snapshot URL. See "Mutating" section below.
+
+2b. Otherwise (tracked / untracked):
+    → PUT /api/agent/fs/file/<path>.md  (raw Tier-1)
+         If-Match: "<ETag from step 1>"
+         If-Collab-Match: <X-Collab-Revision from step 1>
+
+3. If you get 409 COLLAB_ACTIVE: the doc became active after your read.
+   Switch to Tier-2 (block-ops) using the URL in the response body.
+```
+
+**MCP-capable agents:** run `npx wiki-viewer-mcp` — it reads `X-Collab-State` automatically and routes to the correct tier. Set env vars `WIKI_VIEWER_URL`, `WIKI_VIEWER_TOKEN`, `WIKI_VIEWER_AGENT_ID`.
+
+---
+
 ## Working style
 
 - Read before write. Always GET a fresh snapshot to capture current `revision` and block `ref`s.
@@ -226,11 +411,19 @@ Acks are advisory; events are never deleted.
 ## Sample first interaction
 
 ```
-1. GET /api/agents/install                      # discovery
-2. POST /api/agent/register                     # register
+1. GET /api/agents/install                               # discovery
+2. POST /api/agent/register                              # register (include "delete" in ops if needed)
 3. tell human: "approve me in the AI Panel"
-4. GET /api/agent/register/<regId>              # poll until approved
-5. GET /api/agent/files/<path>.md               # read
-6. POST /api/agent/files/<path>.md              # suggest or mutate
-7. GET /api/agent/events/<path>.md?after=<id>   # listen for replies
+4. GET /api/agent/register/<regId>                       # poll until approved
+
+# Working mode (Tier-1, e.g. code files or untracked .md)
+5. GET /api/agent/fs/ls/src?recursive=true               # list
+6. GET /api/agent/fs/file/src/main.ts                    # read -> capture ETag
+7. PUT /api/agent/fs/file/src/main.ts (If-Match: <sha>) # write
+
+# Collaborating mode (Tier-2, active .md)
+5. GET /api/agent/fs/file/notes/plan.md                  # read -> X-Collab-State: active
+6. GET /api/agent/files/notes/plan.md                    # read snapshot (Tier-2)
+7. POST /api/agent/files/notes/plan.md                   # suggest or mutate (Tier-2)
+8. GET /api/agent/events/notes/plan.md?after=<id>        # listen for replies
 ```

package/.next/standalone/docs/file-vs-collab-authority.md

@@ -0,0 +1,124 @@
+# File vs Collab Authority Model
+
+**TL;DR:** File on disk is truth. Tier-1 raw edits are fast + audited but unmarked. Tier-2 block-ops are slower but reviewable. The `X-Collab-State` header tells an agent which tier to use; the server enforces it atomically.
+
+---
+
+## Source of truth
+
+The `.md` file on disk is the canonical document. The `.proof/<path>.json` sidecar holds provenance metadata (comments, suggestions, proof-span refs, fingerprint) but is never the source of truth for content. If the sidecar is lost the document is intact; if the document is lost the sidecar is orphaned.
+
+---
+
+## Two tiers
+
+### Tier 1 — Raw FS
+
+- Routes: `GET/PUT/DELETE /api/agent/fs/file/<path>`, `GET /api/agent/fs/ls/...`, `POST /api/agent/fs/move`, `POST /api/agent/fs/search`.
+- All file types. Raw bytes in, raw bytes out.
+- Writes are **atomic** (temp-file + rename in same directory).
+- **Audit:** every mutation records a row in the `agent_fs_audit` SQLite table (`path`, `op`, `agentId`, `oldSha`, `newSha`, `forced`, `at`).
+- **Event:** `file.rawWritten` emitted with `{ by: "ai:<id>", path, oldSha, newSha }`. Distinct from `file.externallyEdited` (chokidar, writer unknown).
+- No `<proof-span>` marks. No accept/revert UI. Audit log is the paper trail.
+
+### Tier 2 — Collab
+
+- Routes: `GET/POST /api/agent/files/<path>.md`, `GET/POST /api/agent/events/<path>.md`.
+- Markdown only.
+- Edits are wrapped in `<proof-span>` marks inline in the `.md` file.
+- Provenance (suggestions, comments, block refs) stored in `.proof/<path>.json` sidecar.
+- Human can accept or revert individual spans in the editor UI.
+- Mandatory `baseRevision` optimistic concurrency + `Idempotency-Key` per request.
+
+---
+
+## The `X-Collab-State` header
+
+Every `GET /api/agent/fs/file/<path>` (Tier-1 read) and every Tier-2 snapshot read returns:
+
+```
+X-Collab-State: active | tracked | untracked | not-markdown
+X-Collab-Revision: <n>
+X-Collab-Snapshot: /api/agent/files/<path>.md   # present when not not-markdown
+```
+
+### State machine
+
+```
+[file created]
+      │
+      ▼
+  untracked   ──── first Tier-2 op ────►  tracked
+      │                                      │
+      │  (Tier-1 writes stay untracked)      │  human opens editor
+      │                                      ▼
+      │                                   active
+      │                                      │
+      │                              editor closes +
+      │                              no artifacts
+      │                                      │
+      │                                      ▼
+      └──────────────────────────────────  tracked
+```
+
+**`active`** is set by two independent sources (OR'd):
+
+1. **Artifacts** — sidecar has `pendingSuggestions > 0` OR `unresolvedComments > 0` OR `proofSpanCount > 0`. Cheap: always in memory when sidecar is loaded.
+2. **Human edit lease** — a short-TTL presence marker (default 90 s, heartbeat ~30 s) set via `POST /api/wiki/presence { path, action: "open" | "heartbeat" | "close" }`. Closes the false-negative: a human who opens a doc but hasn't typed a suggestion yet still reads `active`.
+
+`X-Collab-Revision` bumps on any sidecar write OR lease open/close. Used by R6.
+
+---
+
+## R6 — atomic TOCTOU race fix
+
+`If-Match` (sha256) protects _bytes_. But a human could open the doc between the agent's read and its raw `PUT`, making it `active` while bytes are unchanged — so `If-Match` passes but the write clobbers a live session.
+
+**Fix:** a raw `PUT` to any `.md` re-checks `collabState` **inside the same `withFileMutex` call, immediately before writing**. If the state is now `active` and the request did not supply a matching `If-Collab-Match: <revision>`, the write is **rejected 409 `COLLAB_ACTIVE`** with the Tier-2 URL. This check is atomic with the write — not advisory.
+
+`?force=true` bypasses both `If-Match` and `If-Collab-Match` and is recorded in the audit row as `forced: true`.
+
+---
+
+## R2 — eager sidecar reconciliation
+
+After a raw `PUT` to a tracked/active `.md`, the sidecar must be reconciled **synchronously, inside the same mutex**, before the lock is released:
+
+1. Re-scan the new file bytes for surviving `<proof-span>` marks.
+2. Re-bind each proof ref to its new block offset; mark unresolvable refs `stale: true`.
+3. Set `sidecar.fingerprint = newSha` (so the lazy mismatch-trigger in `readSnapshot` does NOT re-fire — the reconcile already ran).
+4. Emit `file.rawWritten` event.
+
+**Do not** just bump the fingerprint and let reconciliation fire lazily on the next read. The lazy trigger fires only when `sidecar.fingerprint != file sha256`; once the raw write sets fingerprint current, the mismatch is gone and rebuild never runs. Eager reconciliation is the correct invariant.
+
+---
+
+## Known v1 limitations
+
+### (a) Editor does not call `/api/wiki/presence` yet
+
+The front-end editor does **not** currently issue `POST /api/wiki/presence` on open/heartbeat/close. Consequence: lease-based `active` never fires. Only artifact-based `active` works (pending suggestions, unresolved comments, proof-spans in sidecar).
+
+**Impact:** a human who opens a doc but has no pending review artifacts will see `X-Collab-State: tracked` (or `untracked`), not `active`. An agent raw-writing that doc won't be blocked. This is a safety gap — not a correctness bug (no data loss), but the intended "lock out while human is live-editing" experience is incomplete until the editor heartbeat is wired.
+
+**Fix:** call `POST /api/wiki/presence { path, action: "open" }` when the editor mounts the doc and `{ action: "close" }` on unmount. Heartbeat every ~30 s. Tracked as a follow-up task.
+
+### (b) Lease store is in-memory (single-process only)
+
+The presence lease map lives in the Node.js process memory. In a multi-process deployment (PM2 cluster mode, multiple Next.js instances behind a load balancer) each process has its own lease state and processes do not share it.
+
+**Impact:** a human's open lease set by process A is invisible to process B. A raw write handled by process B may not see the `active` state and proceed when it should block.
+
+**Fix:** move the lease store to the shared SQLite (`~/.wiki-viewer/auth.db`) with a TTL column and a periodic cleanup job. The table is already shared across the process boundary. Tracked as a follow-up task.
+
+---
+
+## Sidecar lifecycle rules
+
+| Raw-fs op                | On non-`.md` | On `.md`                                                           |
+| ------------------------ | ------------ | ------------------------------------------------------------------ |
+| `PUT` (create/overwrite) | plain write  | acquire mutex → write → reconcile sidecar → emit `file.rawWritten` |
+| `DELETE`                 | plain delete | delete file + delete `.proof/<path>.json` sidecar                  |
+| `POST /fs/move`          | plain rename | rename file + rename `.proof/<old>.json` → `.proof/<new>.json`     |
+
+The human `wiki/move` route was previously a bare `rename` that orphaned sidecars. It now uses the same shared `moveSidecar` helper (fixed in Phase 1).

package/.next/standalone/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wiki-viewer",
-  "version": "1.4.3",
+  "version": "1.5.1",
   "description": "Local file viewer and wiki — view markdown, HTML, PDFs, notebooks, office docs, and more from any directory",
   "license": "MIT",
   "type": "module",