wiki-viewer 1.14.1 → 1.14.2

package/.next/standalone/docs/agent-fs-plan.md

@@ -1,232 +0,0 @@
-# Agent Filesystem Plan — "Two tiers, one spine"
-
-**Status:** Proposed (co-designed; ready for sign-off).
-**Goal:** Let a remote AI agent work with files in a wiki-viewer instance "barely worse than local filesystem", for **all file types**, without disturbing the existing markdown collaboration feature.
-**Principle:** Elegant, minimalistic, boring on purpose. The bytes API is strict and observable; the collab tier stays special. No CRDT pivot. No exec. No PATCH. No JSON-RPC.
-
-> Supersedes the unbuilt `docs/agent-collab-v2-plan.md` Yjs/Hocuspocus/Postgres direction, which is treated as discarded. App today = `better-auth` + `better-sqlite3`, file-on-disk-is-truth.
-
----
-
-## 1. The model: two provenance tiers, one shared spine
-
-```
-                 ┌────────────────────────────────────────────┐
-                 │              SHARED SPINE                  │
-                 │  discovery (/api/agents/install)           │
-                 │  TOFU register → approve → one-shot token  │
-                 │  Authorization: Bearer + X-Agent-Id        │
-                 │  enforceScope(path-glob, op)               │
-                 │  withFileMutex (in-proc + proper-lockfile) │
-                 │  safeRootPath (traversal/symlink guard)    │
-                 │  event log + audit                         │
-                 └───────────────┬───────────────┬────────────┘
-                                 │               │
-              ┌──────────────────▼──┐      ┌─────▼───────────────────────┐
-              │  TIER 1 — RAW FS    │      │  TIER 2 — COLLAB (existing) │
-              │  all file types     │      │  markdown only              │
-              │  read/write/ls/     │      │  block-ops + proof-spans    │
-              │  move/delete/search │      │  comments / suggestions     │
-              │  boring bytes       │      │  reviewable prose, accept/  │
-              │  light audit        │      │  revert provenance          │
-              └─────────────────────┘      └─────────────────────────────┘
-```
-
-- **Tier 1 (Raw FS, NEW):** bytes on disk, every file type, fast agent tooling. Light audit (event + sha). The "do filework" tier.
-- **Tier 2 (Collab, EXISTING, UNCHANGED):** markdown review layer — block-ops, `<proof-span>` marks, comments, suggestions. The "reviewable prose" tier.
-- **Do NOT** fold block-ops into the fs endpoint as a content-type. Collab is a review/provenance _workflow_, not file IO. Different invariants. Keep them separate; share the spine only.
-
----
-
-## 2. Tier 1 — Raw FS API (v1, minimal)
-
-All routes reuse `checkAuth` + `enforceScope` + `withFileMutex` + `safeRootPath`. All reject paths under `.proof/`, the lock dir, and the app db/config. Scope is enforced on **every** surface (reads, listings, search results, move endpoints).
-
-| Method   | Route                                           | Purpose                                                                      |
-| -------- | ----------------------------------------------- | ---------------------------------------------------------------------------- |
-| `GET`    | `/api/agent/fs/file/<path>`                     | Read file. Supports `Range`. Returns raw bytes.                              |
-| `PUT`    | `/api/agent/fs/file/<path>`                     | Atomic whole-file write. `If-Match: <sha256>` optional (REQUIRED for `.md`). |
-| `DELETE` | `/api/agent/fs/file/<path>`                     | Delete file (+ sidecar if `.md`).                                            |
-| `GET`    | `/api/agent/fs/ls/<path>?recursive&limit&depth` | Directory listing. Scope-filtered.                                           |
-| `POST`   | `/api/agent/fs/move`                            | `{from, to, ifMatch?}`. Moves sidecar for `.md`.                             |
-| `POST`   | `/api/agent/fs/search`                          | `{kind:"grep"\|"glob", query, path?, glob?, limit?}`. Server-side.           |
-
-**No exec. No batch. No separate grep/glob.** Add later only if profiling proves need.
-
-> **Update (shipped):** A server-side `PATCH /api/agent/fs/file/<path>` str-replace endpoint was added after profiling proved the whole-file-PUT payload dominates latency for large docs on slow uplinks (500KB @ 0.5Mbps ≈ 7.8s/edit transfer). It is strict: exact substring (no regex), text/UTF-8 only, `If-Match` required, `expectedOccurrences` must match exactly (default 1, else 422 `MATCH_COUNT_MISMATCH`). It shares one mutation code path (`applyMutation`) with PUT, so lock / R6 `COLLAB_ACTIVE` / reconcile / audit behave identically. The MCP `edit_file` tool uses PATCH first and falls back to read+PUT on older servers.
-
-### 2.1 Read (`GET .../file/<path>`)
-
-- Returns **raw bytes**, not a JSON wrapper.
-- Metadata in headers: `ETag: "<sha256>"`, `X-File-Size`, `X-File-Mtime`, `Content-Type`.
-- Supports HTTP `Range` for big/binary files.
-
-### 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 `?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`)
-
-- Hard limits: `max entries`, `max depth`, cursor or hard cap. Excludes `.proof/`; ignores `.git/` (configurable).
-- Each entry: `{name, type, size, mtime}`. Unauthorized paths omitted (scope-filtered).
-
-### 2.4 Search (`POST .../search`)
-
-- `kind: "grep" | "glob"`. No shell interpolation (spawn ripgrep with arg array, or in-process).
-- Limits: timeout, max matches, max bytes scanned, skip binary. Each matched path re-checked against scope.
-- This is the **round-trip-explosion mitigation** — one call replaces dozens of `ls`+`read`.
-
-### 2.5 Move (`POST .../move`)
-
-- 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)
-
-Markdown block-ops (`block.replace/insertAfter/insertBefore/delete/append/prepend`), `comment.*`, `suggestion.*`, `<proof-span>` marks, `baseRevision` optimistic concurrency, mandatory `Idempotency-Key`, sidecar JSON in `.proof/`. **No changes.** This remains the reviewable-prose path.
-
----
-
-## 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. **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 + `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)
-
-- `file.rawWritten` — writer **known** (`by: ai:<id>`, `oldSha`, `newSha`, `path`, `at`). Emitted by raw-fs mutations.
-- `file.externallyEdited` — writer **unknown** (chokidar watcher, vim, git). Existing behavior, untouched.
-
-### Audit
-
-- `.md`: append event to sidecar (already have the machinery).
-- All other files: durable audit row (reuse SQLite). Non-negotiable — without it an agent could silently rewrite a PDF.
-
-### Collab-anchor safety (raw `.md` overwrite)
-
-A full-file `PUT` to a `.md` can strip `<proof-span>` marks and shift block boundaries, orphaning pending comments/suggestions. **Invariant:** after any raw write to a `.md`, the synchronous reconciliation (R2) MUST re-bind or mark-stale every affected proof ref **before** the human UI reads the snapshot. A suggestion/comment whose anchor no longer resolves is flagged `stale`, not silently dropped. This is the explicit guard that keeps Tier 1 from corrupting Tier 2.
-
----
-
-## 5. Discovery
-
-Extend `/api/agents/install` manifest:
-
-- Advertise the new `fs/*` routes.
-- 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.
-
----
-
-## 6. Client story
-
-- **Canonical = the HTTP API.** Easy to curl, test, version. Independent of MCP transport churn.
-- **`npx wiki-viewer-mcp`** = thin MCP adapter mapping standard MCP filesystem tools onto these endpoints:
-  - `read_file` → `GET fs/file`
-  - `write_file` → `PUT fs/file` (with `If-Match` from a prior read)
-  - `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.
-
----
-
-## 7. Path identity (must specify before build)
-
-- Stable **relative** paths only; reject traversal and symlinks escaping root.
-- Decide + document symlink listing behavior.
-- Hard-deny: `.proof/`, `~/.wiki-viewer/.locks/`, the app SQLite db + config.
-- Unicode normalization policy stated explicitly.
-
----
-
-## 8. Non-goals (explicit)
-
-- **No remote compute / exec.** wiki-viewer is a remote **filesystem + review surface**, not a sandbox. Real exec needs quotas, secrets/env/cwd policy, process lifecycle, cancellation, logs — a different product. Server-side `search` covers the ~80% case (find code) without it. Future: a separate optional "workspace daemon" with its own scope + manifest capability.
-- **No CRDT / Yjs / Hocuspocus.** File-on-disk stays truth.
-- **No PATCH, no JSON-RPC, no batch endpoint** in v1.
-
----
-
-## 9. Build order
-
-1. Spine confirm: nothing new — reuse auth/scope/lock/safePath.
-2. `GET/PUT/DELETE fs/file` + atomic write + `If-Match` + headers/ETag/Range.
-3. Audit row + `file.rawWritten` event; wire R1/R2 for `.md`.
-4. `fs/ls` (limits, scope filter) + `fs/move` (sidecar move, R3).
-5. `fs/search` (grep/glob, limits).
-6. Extend `/api/agents/install` manifest + capabilities.
-7. `wiki-viewer-mcp` adapter (read/write/edit/list/search).
-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/editorial-skin-spec.md

@@ -1,242 +0,0 @@
-# Editorial Skin Spec — "Literary Review"
-
-A selectable skin for wiki-viewer. Refined printed-journal aesthetic (LRB / vintage
-Penguin / n+1), not a loud brutalist newspaper. Calm authority for a reading-and-writing tool.
-
-It is a NEW axis, independent of the existing light/dark theme. Composes 4 ways:
-default-light, default-dark, editorial-light, editorial-dark.
-
-## Architecture
-
-- Existing theme axis: `next-themes`, `attribute="class"`, toggles `.dark` on `<html>`.
-- New skin axis: `data-skin="editorial"` attribute on `<html>`. Absence = default skin.
-- Persistence: `localStorage` key `wiki-skin`. No-flash inline script in `layout.tsx` sets
-  the attribute before paint (same pattern next-themes uses).
-- Selectable from settings sheet Appearance section.
-
-CSS layering in globals.css (append AFTER existing :root and .dark blocks so it overrides):
-
-```css
-[data-skin="editorial"] {
-  /* editorial light token overrides */
-}
-[data-skin="editorial"].dark {
-  /* editorial dark token overrides */
-}
-```
-
-Editorial only OVERRIDES tokens (fonts, colors, radius). Inherits everything else.
-
-## Fonts (next/font/google, real, loadable)
-
-In layout.tsx, load alongside existing Inter (keep Inter for default skin):
-
-- `Fraunces` — display: headings, drop caps, document title. variable, opsz axis.
-  CSS var `--font-fraunces`.
-- `Newsreader` — body prose + editorial UI labels. variable. CSS var `--font-newsreader`.
-- `IBM Plex Mono` — file tree, code, metadata, outline panel. weights 400,500,600.
-  CSS var `--font-plex-mono`.
-
-Expose all three variables on `<body>` className alongside `--font-inter`.
-
-Tailwind: add fontFamily entries `display` (Fraunces), `reading` (Newsreader), `mono`
-(IBM Plex Mono) referencing the vars with serif/mono fallbacks. Do NOT change the existing
-`sans`/`serif` defaults (default skin must stay Inter).
-
-Under editorial skin, body font becomes Newsreader, headings/.tiptap headings become Fraunces,
-code/tree/outline become IBM Plex Mono — via the [data-skin] token block setting font on the
-relevant containers (use a `--skin-font-body`, `--skin-font-display`, `--skin-font-mono`
-indirection OR target containers directly in the editorial CSS block).
-
-## Color tokens — map to EXISTING var names
-
-### Editorial Light `[data-skin="editorial"]`
-
-```
---background: #faf6f0;   /* warm newsprint */
---foreground: #1a1714;   /* warm ink */
---card: #fffdfa;
---card-foreground: #1a1714;
---popover: #fffdfa;
---popover-foreground: #1a1714;
---primary: #b54a1f;      /* terracotta accent (NOT vermilion — avoids destructive clash) */
---primary-foreground: #fffdfa;
---primary-soft: #f3e2d8;
---secondary: #f1ebe1;
---secondary-foreground: #1a1714;
---muted: #f1ebe1;
---muted-foreground: #756c5f;
---accent: #f1ebe1;
---accent-foreground: #b54a1f;
---accent-soft: #f3e2d8;
---destructive: #b3261e;  /* keep distinct true-red for danger */
---destructive-foreground: #fffdfa;
---destructive-soft: #f7dcda;
---success: #4a7c59;
---success-soft: #dceadf;
---warning: #b8860b;
---warning-soft: #f5ecd2;
---warning-ink: #8a6508;
---info: #1a1714;
---border: #ddd2c2;       /* parchment hairline */
---input: #ccc0ad;
---switch-checked: #b54a1f;
---ring: #b54a1f;
---overlay: rgb(26 23 20 / 0.4);
---radius: 0px;           /* square print corners */
---sidebar-background: #f4eee4;
---sidebar-foreground: #1a1714;
---sidebar-primary: #b54a1f;
---sidebar-primary-foreground: #fffdfa;
---sidebar-accent: #faf6f0;
---sidebar-accent-foreground: #b54a1f;
---sidebar-border: #ddd2c2;
---sidebar-ring: #b54a1f;
-```
-
-### Editorial Dark `[data-skin="editorial"].dark`
-
-```
---background: #1a1714;   /* warm charcoal */
---foreground: #ece4d8;   /* warm paper-white */
---card: #221e1a;
---card-foreground: #ece4d8;
---popover: #221e1a;
---popover-foreground: #ece4d8;
---primary: #e8a07d;      /* warm terracotta, lifted for dark */
---primary-foreground: #1a1714;
---primary-soft: #3a2c22;
---secondary: #262019;
---secondary-foreground: #ece4d8;
---muted: #262019;
---muted-foreground: #a89e8e;
---accent: #2c2620;
---accent-foreground: #e8a07d;
---accent-soft: #3a2c22;
---destructive: #e5544b;
---destructive-foreground: #1a1714;
---destructive-soft: #4a211d;
---success: #7fae8c;
---success-soft: #24341f;
---warning: #d9a441;
---warning-soft: #3a2e18;
---warning-ink: #d9a441;
---info: #ece4d8;
---border: #382f26;
---input: #4a3f33;
---switch-checked: #e8a07d;
---ring: #e8a07d;
---overlay: rgb(0 0 0 / 0.6);
---sidebar-background: #161310;
---sidebar-foreground: #ece4d8;
---sidebar-primary: #e8a07d;
---sidebar-primary-foreground: #1a1714;
---sidebar-accent: #221e1a;
---sidebar-accent-foreground: #e8a07d;
---sidebar-border: #382f26;
---sidebar-ring: #e8a07d;
-```
-
-Accent appears on: links, active file in tree (left-border + text), drop cap, focus ring,
-section-label underline, blockquote rule, active toolbar buttons.
-
-## Prose redesign — `.tiptap` under `[data-skin="editorial"]`
-
-Scope ALL of this under `[data-skin="editorial"] .tiptap` so default skin untouched.
-
-- Container: `max-width: 66ch; margin: 0 auto;` body font Newsreader,
-  `font-size: 1.0625rem; line-height: 1.65; letter-spacing: 0;`
-  `text-rendering: optimizeLegibility; font-feature-settings: "liga","kern";`
-- Headings: Fraunces. h1 2.25rem/600, h2 1.6rem/600, h3 1.25rem/600, h4 1.05rem/600 small-caps.
-  Generous top margin (h1 0, h2 2em, h3 1.6em).
-- Drop cap: `[data-skin="editorial"] .tiptap > p:first-of-type::first-letter` —
-  `float:left; font-family:Fraunces; font-size:3.4em; line-height:0.72; padding:0.05em 0.12em 0 0;
-color:var(--primary); font-weight:600;`
-- Scotch rule under document title: handled in chrome (content header), see below.
-- Blockquote: no gray fill. `border-left: 3px solid var(--primary); padding-left: 1.1rem;
-font-style: italic; font-size: 1.15rem; color: var(--foreground);`
-- Inline code: IBM Plex Mono, `0.85em`, `background: var(--muted); border: 1px solid var(--border);
-border-radius: 0; padding: 0.05rem 0.3rem;`
-- Code block (pre): IBM Plex Mono, `border-radius: 0; border-top: 1px solid var(--border);
-border-bottom: 1px solid var(--border); background: var(--muted);` keep existing hljs token colors
-  (they read fine on warm muted).
-- Links: `color: var(--primary); text-decoration: underline; text-underline-offset: 2px;
-text-decoration-thickness: 1px;`
-- Lists: `ul { list-style-type: square; }` keep ol decimal.
-- hr (asterism): hide the line, inject centered `✳ ✳ ✳` (Fraunces, muted, letter-spacing 0.4em)
-  via `::before` on a zero-border hr; `margin: 2.5rem 0;`
-- Tables: square corners, hairline borders var(--border), header row small-caps Fraunces.
-
-## Chrome redesign — under `[data-skin="editorial"]`
-
-All square corners (radius:0 via token). Targets are utility classes on existing markup in
-src/app/page.tsx; prefer adding skin-scoped CSS in globals.css over rewriting JSX where possible.
-Where a class hook is missing, add a stable className to the JSX (do not restructure layout).
-
-- Sidebar / file tree: IBM Plex Mono for file names (`--font-plex-mono`), `font-size: 0.8125rem`.
-  Active file: left border `2px solid var(--primary)`, text color var(--primary), no rounded
-  background pill. Hover: subtle `var(--muted)` fill, no radius. Folder/file lucide icons may
-  stay but de-emphasize (muted-foreground).
-- Top toolbars (`bg-muted border-b`): make background `var(--background)` (transparent feel),
-  keep single hairline bottom `1px solid var(--border)`.
-- Content pane header (the `flex items-center justify-between px-4 py-2 border-b` at page.tsx
-  ~1990 / ~2100): under this header add a SCOTCH RULE as the bottom border — implement via a
-  skin-scoped `::after` or replace border with layered box-shadow:
-  `box-shadow: 0 1px 0 0 var(--foreground), 0 3px 0 0 var(--foreground)` is wrong;
-  use: bottom border 2px solid var(--foreground) + a 1px var(--foreground) hairline 2px below via
-  `::after` absolute. Keep it ONLY on the active-document header, not every bar.
-  Simpler acceptable version: `border-bottom: 3px double var(--foreground)` (CSS double rule).
-  Use the `double` rule approach for reliability.
-- Document title in header: Fraunces, slightly larger, tracking -0.01em.
-- Outline panel (right): IBM Plex Mono, uppercase tracked `caption` style for the "Outline" label
-  (small-caps, letter-spacing 0.12em, muted). Active outline item: var(--primary).
-- Buttons: square. Primary = solid var(--primary). Ghost/secondary = transparent, hairline border
-  appears on hover. Inputs: square, hairline border, focus ring var(--ring).
-
-## Section labels (signature)
-
-Any existing uppercase tracked `<h3>` labels (settings sections, sidebar headers): under editorial
-render as small-caps Fraunces with a short terracotta underline rule. Scope via skin selector.
-
-## Motion
-
-Restrained. Page/content load: content fades opacity 0→1 over 400ms ease-out (no slide).
-Hover: color swaps instant, background fades 120ms. No bounce. Respect existing motion tokens.
-
-## Settings UI — Appearance section
-
-Add a new `<section className="space-y-2">` in auth-settings-sheet.tsx (after Account, before
-Signup allowlist) titled "Appearance". Contains a skin selector: two choices "Default" and
-"Editorial" (segmented buttons or radio row matching existing button styling). Wire to the new
-skin store. Keep the existing ThemeToggle behavior intact (theme axis is separate; it lives in
-the top bar today — leave it there).
-
-## Skin store
-
-Create `src/stores/skin-store.ts` (zustand, matching existing store conventions). State:
-`skin: "default" | "editorial"`, `setSkin(skin)`. On set: write `localStorage["wiki-skin"]`
-and set/remove `document.documentElement.dataset.skin`. Initialize from the attribute the
-no-flash script already set (read on mount), do NOT re-read localStorage in a way that causes
-hydration mismatch.
-
-## No-flash script (layout.tsx)
-
-Add an inline `<script>` in `<head>` (before body) that reads `localStorage["wiki-skin"]` and,
-if `=== "editorial"`, sets `document.documentElement.setAttribute("data-skin","editorial")`.
-Mirror next-themes' approach. Use `suppressHydrationWarning` already present on `<html>`.
-
-## Highest-impact, ranked
-
-1. Fonts wired + editorial token block (the single biggest visible jump — serif prose + warm paper)
-2. .tiptap prose redesign (drop cap, measure, blockquote, links)
-3. File tree mono + active terracotta border
-4. Scotch rule under document title + square corners
-5. Outline panel + toolbars + settings selector
-
-## Out of scope / do not touch
-
-- Do not change default-skin appearance at all. Every editorial rule MUST be scoped under
-  `[data-skin="editorial"]`.
-- Do not restructure page.tsx layout/DOM hierarchy. Add classNames only where a hook is missing.
-- Do not alter auth, agent API, editor logic, stores other than the new skin-store.
-- Do not bump deps. next/font/google fonts need no install.

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

@@ -1,124 +0,0 @@
-# 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).