wiki-viewer 1.4.2 → 1.5.0

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/agent-fs-plan.md

@@ -62,9 +62,10 @@ All routes reuse `checkAuth` + `enforceScope` + `withFileMutex` + `safeRootPath`
 ### 2.2 Write (`PUT .../file/<path>`)
 
 - Atomic: write temp in **same dir** → `fsync` → `rename`. (`fsync` dir optional but documented.)
-- Preserve mode of existing file. Do **not** create parent dirs unless body/flag explicitly opts in.
-- `If-Match: <sha256>` → 412 on mismatch. **Required by default for all writes** (see R4); explicit `?force=true` bypasses and is audited.
-- Response: `{path, sha256, size, mtime}`.
+- Preserve mode of existing file. Do **not** create parent dirs unless `?mkdirs=true`.
+- **Create = implicit.** `PUT` to a non-existent path creates the file (write-with-no-prior). Omit `If-Match` for a create; send `If-Match: <sha256>` only when overwriting. A create where the file already exists (no `If-Match`) → 412, so creates can't silently clobber.
+- `If-Match: <sha256>` → 412 on mismatch. **Required by default for overwrites** (see R4); explicit `?force=true` bypasses and is audited.
+- Response: `{path, sha256, size, mtime, created: bool}`.
 
 ### 2.3 Listing (`GET .../ls`)
 
@@ -82,6 +83,12 @@ All routes reuse `checkAuth` + `enforceScope` + `withFileMutex` + `safeRootPath`
 - Checks: source `read`+`mutate`, dest `mutate`.
 - For `.md`: moves the `.proof/<path>.json` sidecar too. Lock ordering: single operation lock, or lock source+dest in **sorted key order** to avoid deadlock.
 
+### 2.6 Delete (`DELETE .../file/<path>`)
+
+- Requires the `delete` scope op (see §3.5) and `If-Match: <sha256>` — the agent must have read the current file first, so it cannot blind-delete. This `If-Match` requirement **is** the confirmation for v1.
+- `.md`: also deletes the sidecar (R3).
+- Directory delete is opt-in and explicit: `?recursive=true`; without it, deleting a non-empty dir is refused. (No human approval queue in v1 — deferred.)
+
 ---
 
 ## 3. Tier 2 — Collab (unchanged)
@@ -90,14 +97,61 @@ Markdown block-ops (`block.replace/insertAfter/insertBefore/delete/append/prepen
 
 ---
 
+## 3.5 Working mode vs Collaborating mode (THE central distinction)
+
+The whole design hinges on the agent knowing **when a file is being actively co-edited by a human** (use the reviewable Tier-2 path) versus **when it's just a file to work on** (use fast raw Tier-1). Today nothing tells the agent this; a wrong guess clobbers a human's pending suggestions. We make the mode **discoverable, documented, and enforced** — three layers so the agent cannot miss it.
+
+### The signal: `X-Collab-State` header (on every read, both tiers)
+
+Every `GET fs/file/<path>` and every Tier-2 snapshot read returns:
+
+```
+X-Collab-State: active | tracked | untracked | not-markdown
+X-Collab-Snapshot: /api/agent/files/<path>.md      # present when state != not-markdown
+```
+
+| State          | Meaning                                                                                                                                                                                                                                      | Agent should…                                                                                                                                             |
+| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `active`       | `.md` that is **live**: either has review artifacts (pending suggestions / unresolved comments / unreverted proof-spans) **OR has a current human edit lease** (someone has the doc open in the editor). A human is collaborating right now. | **Use Tier-2 block-ops.** Your edits become reviewable suggestions. A raw `PUT` is rejected unless `If-Collab-Match` matches (see R6).                    |
+| `tracked`      | `.md` with a sidecar, no artifacts, no lease.                                                                                                                                                                                                | **Prefer Tier-2 for any semantic/prose edit** so provenance accrues. Raw only for mechanical/whole-file ops (e.g. reformat, regenerate). Not a free pass. |
+| `untracked`    | `.md`, no sidecar, no lease — nobody has collaborated.                                                                                                                                                                                       | Raw ok. A reviewable (Tier-2) edit creates a sidecar so future edits are tracked.                                                                         |
+| `not-markdown` | Any non-`.md` file.                                                                                                                                                                                                                          | **Tier-1 raw only** (Tier-2 doesn't apply).                                                                                                               |
+
+**Definition of `active` (two sources, OR'd):**
+
+1. **Artifacts:** `pendingSuggestions > 0` OR `unresolvedComments > 0` OR `proofSpanCount > 0` (from sidecar — cheap, already in memory on read).
+2. **Human edit lease:** a short-TTL presence marker (default 90s, heartbeat ~30s) set when a human opens the doc in the editor and refreshed while it stays open. **This closes the false-negative GPT-5.5 caught:** a human who opens a doc but hasn't typed a suggestion yet still reads `active`, so the agent won't blind-write into a live session. Lease lives in-memory (or the existing SQLite), keyed by `(path)`, set by a lightweight `POST /api/wiki/presence` ping the editor already can issue alongside its chokidar SSE connection. No lease + no artifacts → not active.
+
+### Layer 2 — documented (manifest + skill)
+
+The `/api/agents/install` manifest and the skill state the rule in one sentence:
+
+> _"Before editing a `.md`, read it and check `X-Collab-State`. If `active`, use block-ops (Tier 2) so a human can review. Otherwise use raw fs (Tier 1). For non-markdown, always use raw fs."_
+
+### Layer 3 — enforced (R4 + R6 backstop)
+
+Even a confused or racing agent cannot silently clobber a live session: a raw `PUT` to an `active` `.md` is **rejected with 409 `COLLAB_ACTIVE`** unless it carries a matching `If-Collab-Match` (R6) — and the state is re-checked atomically inside the write mutex, so a session that goes active mid-flight still wins. Any genuinely orphaned suggestion/comment is marked `stale` by reconciliation (R2), never dropped. The 409 returns the Tier-2 snapshot URL, re-teaching the mode.
+
+### What the human sees
+
+- Agent works in Tier-2 on an `active` doc → normal reviewable suggestions (existing UX).
+- Agent raw-writes an `active` doc anyway → `file.rawWritten by ai:<id>` in the AI Panel feed + any unbindable anchors flagged `stale` (not vanished).
+- Agent works on `untracked`/non-md → silent, fast, audited. No collab noise.
+
+---
+
 ## 4. Integration rules (load-bearing)
 
 - **R1 — Shared lock.** A raw write/move/delete on a `.md` acquires the **same** `withFileMutex` key the ops-applier uses. No interleaving with block-ops mid-proof-span.
 - **R2 — No fake provenance.** Raw writes never author proof-spans. After a raw write to a tracked `.md`, emit `file.rawWritten` (writer known) and **reconcile the sidecar synchronously, inside the same mutex** (rebuild `refMap`, set fingerprint to `newSha`, mark affected proof refs stale). Raw edits are unmarked by definition; human sees _who_ via the event, not as an accept/revert suggestion.
   - **GOTCHA (do not regress):** do NOT just "bump fingerprint to newSha and let existing reconciliation fire later." The existing reconciliation triggers on `sidecar.fingerprint != file sha256`; if the raw write sets fingerprint current, the mismatch is gone and rebuild never runs. Because the writer is known, reconcile **eagerly within the write**, not lazily on next read.
-- **R3 — Sidecar lifecycle.** Raw `mv`/`rm` of a `.md` moves/deletes its sidecar (reuse human `wiki/move` logic).
+- **R3 — Sidecar lifecycle.** Raw `mv`/`rm` of a `.md` moves/deletes its sidecar. **NOTE:** the human `wiki/move` route currently does a bare `rename` and does NOT move the sidecar — a latent bug that orphans `.proof/` JSON today. Build a shared `moveSidecar`/`deleteSidecar` helper in `sidecar.ts` and wire **both** the raw-fs path and `wiki/move` to it (fixes the existing bug for free).
 - **R4 — Write guard (If-Match by default).** **All** mutating raw ops (`PUT`/`DELETE`/`move`) REQUIRE `If-Match: <sha256>` by default; 412 on mismatch. An explicit `?force=true` bypasses it and is recorded in the audit row. Rationale: agents edit code/config just as much as `.md`; optional concurrency = silent lost updates, and a format-based safety boundary is arbitrary. Cheap because the agent already has the sha from `GET`.
-- **R5 — Scope unification.** Registration `scope.paths` glob + `scope.ops:[read,mutate]` already exist; raw-fs honors the same. No new scope concepts in v1.
+- **R5 — Scope unification + `delete` op.** Registration `scope.paths` glob already covers **directories natively** (e.g. `notes/**` grants the whole subtree — no file lists). Raw-fs honors the same glob, on every surface (read/ls/search/move/delete results all re-checked). **One addition:** split `delete` out of `mutate`, so `scope.ops` becomes `[read, mutate, delete]`. This lets a human grant "edit but never delete." `mutate` = create/overwrite/move; `delete` = remove. Back-compat: existing `[read, mutate]` agents simply can't delete until re-scoped. Glob dialect (v1): `**`, `*`, `?` only — no braces/negation; advertise this in the manifest.
+- **R6 — Collab-state precondition on raw `.md` writes (closes the TOCTOU race).** `If-Match` protects _bytes_, not _collaboration intent_: a human could create a sidecar/lease after the agent's read but before its raw `PUT`, leaving bytes unchanged so `If-Match` still passes. To prevent silently writing into a session that went `active` mid-flight:
+  - Every `.md` read also returns `X-Collab-Revision: <n>` (bumped on any sidecar/lease state change).
+  - A raw `PUT` to a `.md` must, **inside the same mutex, re-read collab state immediately before writing**: if the doc is now `active` and the request did not supply a matching `If-Collab-Match: <n>`, **reject with 409 `COLLAB_ACTIVE`** + the Tier-2 snapshot URL. The agent then switches to block-ops. `?force=true` still bypasses (audited) for deliberate overrides.
+  - This makes the mode check atomic with the write, not advisory.
 
 ### Event taxonomy (don't overload)
 
@@ -120,7 +174,8 @@ A full-file `PUT` to a `.md` can strip `<proof-span>` marks and shift block boun
 Extend `/api/agents/install` manifest:
 
 - Advertise the new `fs/*` routes.
-- Add a `capabilities` block: `{ maxFileBytes, supportsRange, ifMatchRequired:true, forceBypass:true, search:["grep","glob"] }`.
+- Add a `capabilities` block: `{ maxFileBytes, supportsRange, ifMatchRequired:true, forceBypass:true, search:["grep","glob"], globDialect:"**,*,?", scopeOps:["read","mutate","delete"], collabStates:["active","tracked","untracked","not-markdown"], collabPrecondition:"If-Collab-Match" }`.
+- State the **working-vs-collaborating rule** (§3.5) in prose so the agent self-configures its tier choice.
 - Advertise the optional MCP adapter package + version.
   One manifest; agent self-configures. HTTP routes are the canonical contract.
 
@@ -135,6 +190,8 @@ Extend `/api/agents/install` manifest:
   - `edit_file` (str-replace) → **client-side**: read → transform → `PUT If-Match`. (Server stays dumb; edit footguns live in the adapter.)
   - `list_directory` → `GET fs/ls`
   - `search` → `POST fs/search`
+  - `delete_file` → `DELETE fs/file` (requires `delete` scope + `If-Match`)
+- The shim reads `X-Collab-State` and, when `active`, **warns or routes the edit through the Tier-2 block-op tools** instead of a blind raw write — so even off-the-shelf MCP clients respect collaborating mode.
 - Do **not** make the core app MCP-native first. The app already has HTTP auth/discovery; the shim adapts to Claude Code / Cursor / Codex without poisoning the core.
 
 ---
@@ -165,7 +222,8 @@ Extend `/api/agents/install` manifest:
 5. `fs/search` (grep/glob, limits).
 6. Extend `/api/agents/install` manifest + capabilities.
 7. `wiki-viewer-mcp` adapter (read/write/edit/list/search).
-8. Tests: traversal, symlink escape, If-Match 412, sidecar move, scope filtering on ls/search, big-file Range, binary skip in grep.
+8. **Mode plumbing:** human edit-lease (`POST /api/wiki/presence` + TTL, editor heartbeat), `X-Collab-State` + `X-Collab-Revision` headers on both read paths, R6 atomic re-check + 409 `COLLAB_ACTIVE` on raw `.md` writes. Plus `delete` scope op + create/`?mkdirs`/`?recursive` semantics.
+9. Tests: traversal, symlink escape, If-Match 412, create-collision 412, sidecar move (incl. `wiki/move` bug fix), scope filtering on ls/search, big-file Range, binary skip in grep, **`X-Collab-State` matrix incl. lease-only `active`**, **R6 TOCTOU: doc goes active between read and raw PUT → 409**, stale-anchor after raw `.md` overwrite, `delete` op gating, lease expiry flips active→tracked.
 
 ```
 

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.2",
+  "version": "1.5.0",
   "description": "Local file viewer and wiki — view markdown, HTML, PDFs, notebooks, office docs, and more from any directory",
   "license": "MIT",
   "type": "module",