wiki-viewer 1.14.1 → 2.0.0

package/.next/standalone/docs/mobile-readiness-spec.md

@@ -1,229 +0,0 @@
-# Mobile-readiness spec
-
-Implementation-ready spec for making wiki-viewer usable on phones/tablets. Desktop layout and behavior stay visually unchanged. Mobile is additive, gated behind a breakpoint.
-
-Stack: Next.js 16, React 19, Tailwind 3, Radix/shadcn, TipTap 3, Zustand.
-
-## Design principle
-
-The app already has the two primitives we need:
-
-1. Sidebar already has a **collapse/expand** state (`sidebarCollapsed`, local `useState` in `src/app/page.tsx:405`). When collapsed, the sidebar `Card` is unmounted and a reopen button appears top-left of the editor area (`page.tsx:~2057`).
-2. AI panel is already a **fixed overlay + backdrop** driven by zustand (`useAIPanelStore.isOpen`), not part of the flex row (`src/components/ai-panel/ai-panel.tsx:152`).
-
-So mobile work is mostly: (a) make the sidebar **overlay instead of push** on small screens, (b) auto-collapse it on mobile, (c) add a hamburger affordance, (d) cap fixed panel widths, (e) make touch-only affordances reachable, (f) fix the viewport meta. We do NOT introduce a new layout engine.
-
----
-
-## 1. Breakpoint strategy
-
-Single breakpoint. Mobile = viewport `< 768px` (Tailwind `md`). At/above `md` = desktop, unchanged.
-
-- Tailwind prefix: `md:` is the desktop gate. Mobile styles are the unprefixed base; `md:` restores desktop.
-- Rationale: one breakpoint keeps the matrix small and matches the real failure mode (3 panels do not fit on a phone; they fit fine on a ≥768px tablet in landscape and on iPad portrait). Tablets ≥768px keep the desktop 3-panel layout, which is acceptable.
-- No second tier. Phone-vs-tablet nuance is not worth the complexity here.
-
-A JS boolean is needed in a few places (auto-collapse on mount, "opening sidebar closes AI panel" logic, ignoring the resize handle). Add a `useIsMobile()` hook (section 7) backed by `matchMedia("(max-width: 767px)")`. Everything purely visual stays in Tailwind `md:` classes; only logic that branches on the boolean uses the hook.
-
----
-
-## 2. Layout transformation
-
-Desktop (`md` and up): unchanged. `flex h-screen overflow-hidden` row of [sidebar (resizable, pushes content)] + [editor flex-1] + [AI panel overlay].
-
-Mobile (`< md`):
-
-### Sidebar → overlay drawer (left)
-
-- Sidebar must **overlay** the editor, not occupy a flex column. On mobile the sidebar `Card` becomes `fixed inset-y-0 left-0 z-50` with its own backdrop (`fixed inset-0 z-40`, tap-to-close). On desktop it stays in-flow (`md:static md:z-auto`, no backdrop).
-- Width on mobile: `w-[85vw] max-w-[20rem]` (≈ phone-width minus a peek of the editor). Ignore the `sidebarWidth` store on mobile (section 9). On desktop keep `style={{ width: sidebarWidth }}` and `md:w-[var(...)]` is not needed because the inline style wins; instead gate the inline width so it only applies at `md+` (section 7 / component table).
-- Default state on mobile: **collapsed** (closed). On first mount at mobile width, force `sidebarCollapsed = true`.
-- Open trigger: hamburger button in the mobile top bar (section 3).
-- Close: tap backdrop, tap a file (navigating opens the file then closes the drawer on mobile), or the existing collapse button in the sidebar header.
-- Backdrop: only rendered on mobile (`md:hidden`) and only when sidebar open.
-- z-index: backdrop `z-40`, sidebar `z-50`. AI panel uses backdrop `z-40` / panel `z-50` too; they are mutually exclusive on mobile (opening one closes the other, section 8) so no stacking conflict.
-
-### AI panel → full-ish width sheet (right)
-
-- Already an overlay. Only change: width. `w-80` becomes `w-[90vw] max-w-sm md:w-80` so it never exceeds viewport on small screens. Everything else (backdrop, Esc, focus trap) already works.
-
-### Editor → full width
-
-- Editor area is already `flex-1 min-w-0`. With the sidebar overlaying instead of pushing, it naturally spans full width on mobile. No change beyond the top-bar offset (section 3).
-
-### Body scroll
-
-- Keep `h-screen overflow-hidden` on the shell on all breakpoints. The editor body already scrolls internally (`overflow-y-auto`). Do not switch to body scroll. Reason: the editor toolbar and doc header are sticky chrome; body scroll would detach them and complicate the on-screen-keyboard case. The editor's own scroll container handles long docs.
-
----
-
-## 3. Mobile top bar / chrome
-
-Desktop has no global header; do not add one there. The editor's doc-header row already exists per-view (`page.tsx:2086`, `:2198`) and hosts the collapsed-sidebar reopen button via `pl-11` padding.
-
-Mobile approach: **reuse the existing reopen-button slot, add an AI-panel toggle next to it.** No new full-width header bar.
-
-- The existing `sidebarCollapsed && <PanelLeftOpen>` button (top-left, `absolute left-2 top-2`) already serves as the hamburger. On mobile the sidebar is always collapsed-by-default, so this button is the persistent menu affordance. Change: render it whenever `isMobile || sidebarCollapsed` (so it shows on mobile even though state is "collapsed"), icon stays `PanelLeftOpen` (menu-like). Keep `pl-11` header offset logic but key it on the same condition.
-- Add an **AI panel toggle** button: top-right of the editor area, `absolute right-2 top-2 z-10`, `md:hidden` (desktop opens AI panel via existing mechanism/keyboard; do not change desktop). Icon: `Bot` (already imported in ai-panel; import in page). `onClick={() => useAIPanelStore.getState().open()}`. 44px tap target on mobile (section 5).
-- These two floating buttons sit above the editor doc-header. They must not overlap the doc title; the existing `pl-11` already reserves left space, add matching `pr-11` on mobile when the AI toggle shows.
-
-Rationale for no dedicated header: the per-view doc headers already carry title + actions. A second global bar would eat vertical space (precious with the on-screen keyboard up) and duplicate chrome. Floating buttons over existing chrome is the minimal, non-regressing change.
-
----
-
-## 4. Touch interaction replacements
-
-Decisive choice per item:
-
-### Hover-gated sidebar row actions (`page.tsx:1326`, `:1861`)
-
-- Make them **always visible on coarse pointers**. Use `@media (hover: none)` to neutralize the `opacity-0 ... group-hover:opacity-100` reveal. Add a global CSS rule in `globals.css`:
-  ```css
-  @media (hover: none) {
-    .hover-reveal {
-      opacity: 1 !important;
-      max-width: none !important;
-    }
-  }
-  ```
-  Add class `hover-reveal` to the two reveal wrappers. Keeps desktop hover behavior intact; on touch the actions are simply always shown. Chosen over a per-row "..." menu because the actions already collapse cleanly and always-visible is zero new UI.
-
-### Image resize handles (`resizable-image.tsx:100-107`)
-
-- Same `@media (hover: none)` always-visible treatment via the `hover-reveal` class. Handles already use `onPointerDown` (touch-capable) so once visible they work. Bump handle hit area on coarse pointers to ≥24px (visually can stay small via a transparent padded hit zone) so they are tappable.
-
-### Tree drag-reorder (`page.tsx:1202`, HTML5 `draggable`)
-
-- **Disable on touch.** HTML5 DnD is not touch-capable and a touch DnD lib is out of scope. Set `draggable={!isMobile}`. Reordering on mobile is done via the existing context menu (long-press opens Radix `ContextMenu`, already wired at `page.tsx:1189`) which exposes move/rename actions. No new UI.
-
-### Sidebar resize handle (`page.tsx:2009`, `onMouseDown`)
-
-- **Hide on mobile.** The mobile sidebar is a fixed-width drawer; resizing is meaningless. Add `md:block hidden` (or render-gate on `!isMobile`). No touch handler added.
-
----
-
-## 5. Tap targets
-
-Target: 44×44 CSS px on touch (iOS HIG; covers Android 48 in practice with padding). Apply **only on coarse pointers** so desktop density is unchanged.
-
-- Current `h-7 w-7` (28px) and `h-8 w-8` (32px) icon buttons are below target. Do not resize globally.
-- Add a global rule:
-  ```css
-  @media (hover: none) and (pointer: coarse) {
-    button,
-    [role="button"],
-    a.btn {
-      min-height: 44px;
-      min-width: 44px;
-    }
-  }
-  ```
-  Scope carefully: this can distort dense editor toolbar. Prefer a utility class `touch-target` applied to the specific mobile-critical controls (hamburger, AI toggle, sidebar row primary tap, file-tree rows) rather than all buttons, if the blanket rule visually breaks the toolbar. Implementer picks blanket vs scoped after a quick visual check; default to **scoped** to avoid toolbar regressions.
-- File-tree rows: ensure row height ≥44px on coarse pointers (they are currently compact). Add `touch-target`-style min-height to the row container on mobile.
-
----
-
-## 6. Viewport meta
-
-`src/app/layout.tsx:43`, replace:
-
-```ts
-export const viewport: Viewport = {
-  themeColor: "#0c0a09",
-  width: "device-width",
-  initialScale: 1,
-  viewportFit: "cover",
-};
-```
-
-- `width: device-width`, `initialScale: 1`: standard responsive baseline.
-- `viewportFit: "cover"`: needed for notch / safe-area on installed iOS PWA (status bar is `black-translucent`). Pairs with safe-area insets (section 9).
-- **Do NOT set `maximumScale` or `userScalable: false`.** This is a text editor; pinch-zoom is an accessibility requirement. Allow zoom.
-
----
-
-## 7. Component-by-component change list
-
-New shared hook: `src/hooks/use-is-mobile.ts` (create `src/hooks/`).
-
-```ts
-"use client";
-import { useEffect, useState } from "react";
-export function useIsMobile(query = "(max-width: 767px)") {
-  const [isMobile, setIsMobile] = useState(false); // SSR-safe default
-  useEffect(() => {
-    const mql = window.matchMedia(query);
-    const on = () => setIsMobile(mql.matches);
-    on();
-    mql.addEventListener("change", on);
-    return () => mql.removeEventListener("change", on);
-  }, [query]);
-  return isMobile;
-}
-```
-
-SSR returns `false` (desktop) to avoid hydration mismatch; corrects on mount. Acceptable: first paint is desktop layout, snaps to mobile in one frame.
-
-| File                                                   | Change                                                                                                                                                                                                                                                                                                                                                                   | Verdict gate              |
-| ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ |
-| `src/app/layout.tsx`                                   | Expand `viewport` export (section 6). Add safe-area CSS hook if needed.                                                                                                                                                                                                                                                                                                  | always                    |
-| `src/hooks/use-is-mobile.ts`                           | New hook.                                                                                                                                                                                                                                                                                                                                                                | new                       |
-| `src/app/page.tsx`                                     | Consume `useIsMobile()`. Force `sidebarCollapsed=true` on mobile mount. Sidebar `Card`: add `fixed inset-y-0 left-0 z-50 w-[85vw] max-w-[20rem] md:static md:z-auto md:w-auto` and gate inline `style={{width}}` to desktop only (apply `width` only when `!isMobile`). Render a `md:hidden` backdrop when sidebar open on mobile. Hamburger button shows when `isMobile |                           | sidebarCollapsed`. Add `md:hidden`AI-panel toggle button (top-right). Resize handle`hidden md:block`. Tree items `draggable={!isMobile}`. On mobile, selecting a file closes the sidebar drawer. `pr-11` doc-header offset when AI toggle visible. | `md:` + hook |
-| `src/components/ai-panel/ai-panel.tsx`                 | Panel width `w-80` → `w-[90vw] max-w-sm md:w-80`. No other change.                                                                                                                                                                                                                                                                                                       | `md:` only                |
-| `src/components/auth-settings-sheet.tsx`               | Width `w-80` → `w-[90vw] max-w-sm md:w-80` (line ~158).                                                                                                                                                                                                                                                                                                                  | `md:` only                |
-| `src/components/editor/extensions/resizable-image.tsx` | Add `hover-reveal` class to the resize-handle wrapper(s) (lines ~100-107). Enlarge touch hit area on coarse pointers.                                                                                                                                                                                                                                                    | CSS `@media (hover:none)` |
-| `src/components/editor/editor-toolbar.tsx`             | Verify `overflow-x-scroll` still works with larger touch targets; if blanket 44px rule breaks it, keep toolbar buttons out of the touch-target scope. Likely no code change.                                                                                                                                                                                             | verify only               |
-| `src/app/globals.css`                                  | Add `@media (hover: none)` always-visible rule for `.hover-reveal`; add scoped `touch-target` min-size rule; add safe-area padding utilities for notch (section 9).                                                                                                                                                                                                      | CSS                       |
-
-Sidebar row reveal wrappers (`page.tsx:1326`, `:1861`): add `hover-reveal` class.
-
----
-
-## 8. State management
-
-- **Mobile sidebar drawer** reuses the existing `sidebarCollapsed` local state. No new store. `collapsed === closed` on mobile; `collapsed === pushed-off` on desktop. Same boolean, different presentation (overlay vs in-flow), gated by `md:`/`useIsMobile`.
-- **AI panel** keeps its zustand `isOpen`.
-- **Mutual exclusion on mobile only:** opening the sidebar calls `useAIPanelStore.getState().close()`; opening the AI panel sets `sidebarCollapsed=true`. Only do this when `isMobile` (desktop can show both). Wire in the respective open handlers in `page.tsx`.
-- Persist nothing new. `sidebarWidth` store stays for desktop.
-
----
-
-## 9. Edge cases
-
-- **Orientation change:** `matchMedia` change listener re-evaluates `isMobile`; rotating a phone to landscape ≥768px wide will switch to desktop layout. Acceptable and correct. Ensure the sidebar `style` width gate re-reads `isMobile` on render (it will, via hook).
-- **On-screen keyboard:** editor focus raises the keyboard, shrinking visual viewport. Because the shell is `h-screen overflow-hidden` and the editor scrolls internally, the focused caret stays in view via native scroll-into-view. Do not add JS viewport-resize handling. Verify the sticky toolbar does not cover the caret; if it does, that is a follow-up, not a blocker.
-- **Safe-area insets (notch)** given `viewportFit: cover`: add safe-area padding so chrome is not under the notch/home indicator. In `globals.css`:
-  ```css
-  @supports (padding: max(0px)) {
-    .safe-top {
-      padding-top: max(0.5rem, env(safe-area-inset-top));
-    }
-    .safe-bottom {
-      padding-bottom: env(safe-area-inset-bottom);
-    }
-  }
-  ```
-  Apply `safe-top` to the mobile floating buttons / sidebar header, `safe-bottom` to the AI panel and any bottom-anchored sheet. Desktop unaffected (`env()` is 0).
-- **`sidebarWidth` store on mobile:** ignored. The drawer uses `w-[85vw] max-w-[20rem]`. Do not write to the store from mobile; do not clamp. On return to desktop the stored width applies again unchanged.
-
----
-
-## Implementation order
-
-1. `useIsMobile` hook + viewport meta (`layout.tsx`). Foundational, zero risk.
-2. Width caps: `ai-panel.tsx`, `auth-settings-sheet.tsx` (`w-[90vw] max-w-sm md:w-80`). Independent, low risk, immediate win.
-3. globals.css: `.hover-reveal` always-visible rule, `touch-target` scoped rule, safe-area utilities.
-4. Sidebar overlay + auto-collapse + backdrop + hamburger in `page.tsx`. Core layout change.
-5. AI-panel mobile toggle + mutual exclusion in `page.tsx`.
-6. Touch fixes: `draggable={!isMobile}`, resize handle `hidden md:block`, `hover-reveal` on reveal wrappers + resizable-image, tree row min-height.
-7. Verify editor toolbar + tap-target scoping doesn't regress desktop.
-
-## Out of scope
-
-- Touch drag-and-drop reordering of the file tree (use context menu instead).
-- Touch-resizable sidebar (fixed-width drawer on mobile).
-- Bottom-sheet redesign of the AI panel (side sheet with width cap is enough).
-- Any change to desktop layout, spacing, or behavior.
-- Editor on-screen-keyboard caret-tracking JS.
-- New global mobile header bar.
-- PWA/manifest changes (already solid).

package/.next/standalone/docs/workspacing-plan.md

@@ -1,364 +0,0 @@
-# Workspacing plan
-
-> **Status: IMPLEMENTED.** Phases A–E complete. 294 tests pass, tsc clean.
-> Key files: `src/lib/workspaces.ts`, `src/lib/workspace-context.ts`,
-> `src/lib/auth/admin.ts`, `src/lib/workspace-client.ts`, workspace + admin
-> APIs under `src/app/api/system/`, agent scope via `scope.workspaceId`.
-> The legacy `src/lib/root-dir.ts` global is retained as a fallback source
-> (synthetic default workspace) for `ROOT_DIR`/CLI/tests — not yet deleted.
-
-## Goal
-
-Let one running wiki-viewer serve multiple root directories ("workspaces")
-concurrently, with zero state bleed between them. A user can have two tabs open
-on two different workspaces at once. AI agents target a specific workspace.
-
-Decisions (locked):
-
-- **Selection**: URL/query carries `ws=<wsId>` for browser routes; agents send
-  an `X-Workspace: <wsId>` header. No process-global "current root".
-- **Agents are workspace-scoped**: every agent request resolves a workspace and
-  is denied if it has no grant for it.
-- **Isolation type**: organizational, not OS-level ACL. We add an explicit
-  per-workspace access list (which users / which agents may use a workspace).
-  We do NOT add per-user filesystem path restrictions on the directory browser.
-
-## Why the current code bleeds
-
-`src/lib/root-dir.ts` keeps a single `globalThis.__wikiRootDir`. Every route
-calls `getRootDir()` / `safeRootPath()` against that one value, so:
-
-- "Change" (`/api/system/clear-root`) wipes the root for every user/tab.
-- Only one root can be active per process. No concurrency at all.
-
-In-memory stores keyed by **relPath only** (collide across roots once more than
-one root is live):
-
-- `src/lib/proof/lease.ts` — `leases` + `generations` maps keyed by relPath.
-- `src/lib/proof/idempotency.ts` — single LRU keyed by idempotency key.
-- `src/lib/proof/mutex.ts` — in-process lock map keyed by relPath / mdPath.
-- `src/lib/proof/file-lock.ts` — cross-process sentinel hashed from lockKey
-  (relPath). Two workspaces with `notes.md` share one lock.
-
-Config is single-root shaped:
-
-- `src/lib/config.ts` — one `lastOpenedPath`, one flat `pinnedPaths`.
-
-Already correctly scoped (these take `rootDir` as a param, keep as-is):
-
-- `src/lib/proof/sidecar.ts`, `activity.ts` — read/write under
-  `<rootDir>/.proof/`. Naturally isolated once `rootDir` is per-workspace.
-
-Global, needs a `workspaceId` column / field:
-
-- `src/lib/proof/audit.ts` — `agent_fs_audit` table mixes paths from all roots.
-- `src/lib/proof/registry.ts` — `agents.json`; agent scope is path globs with
-  no workspace dimension.
-
-## Target architecture
-
-### 0. Admin role (new prerequisite)
-
-No admin concept exists today: every signed-in user is equal, and the settings
-routes just `requireUser`. Workspace access management is admin-gated, so we
-introduce a minimal global admin role.
-
-New `src/lib/auth/admin.ts`:
-
-```ts
-isAdmin(userId, email): Promise<boolean>
-listAdmins(): Promise<string[]>        // user ids
-addAdmin(userId): Promise<void>
-removeAdmin(userId): Promise<void>     // refuse to remove the last admin
-requireAdmin(req): Promise<{ ok: true; user } | { ok: false; status; code }>
-```
-
-Resolution:
-
-- `adminUserIds: string[]` stored in `config.json`.
-- `WIKI_ADMIN_EMAILS` (csv) env: any matching signed-in user is treated as
-  admin regardless of config (seed/override, headless-friendly).
-- **Bootstrap**: if `adminUserIds` is empty AND no `WIKI_ADMIN_EMAILS`, the
-  first user to sign up is written into `adminUserIds`. Hook the better-auth
-  signup path, or do it lazily on the first authenticated request when the
-  admin set is empty (behind the config write mutex). Log once.
-- `requireAdmin` returns 403 `ADMIN_REQUIRED` for non-admins.
-
-Admin management API: `GET/POST/DELETE /api/system/admins` (admin-gated; list
-users, promote, demote). `DELETE` refuses to remove the last admin (lockout
-guard). A small Admins section in the settings sheet lists users (from the
-better-auth `user` table) with promote/demote toggles.
-
-Non-admin users keep full file access to workspaces they are granted; admin is
-only about creating workspaces and editing access lists (and promoting admins).
-
-### 1. Workspace registry (replaces single rootDir)
-
-New `src/lib/workspaces.ts`. Persisted in `~/.wiki-viewer/config.json` under a
-new `workspaces` array. Each entry:
-
-```ts
-interface Workspace {
-  id: string; // "ws_" + short random; stable, URL-safe
-  name: string; // display label, defaults to basename(rootDir)
-  rootDir: string; // absolute, resolved
-  createdAt: string;
-  lastOpenedAt?: string;
-  pinnedPaths?: string[]; // moved here from the flat top-level list
-  createdBy?: string; // user id of the admin who created it
-  // access management (organizational, admin-edited only):
-  allowedUserIds?: string[]; // empty/undefined = any signed-in user
-  // agent grants live in the agent registry, keyed by workspaceId
-}
-```
-
-API surface (pure functions, no globalThis root):
-
-```ts
-listWorkspaces(): Promise<Workspace[]>
-getWorkspace(id): Promise<Workspace | null>
-createWorkspace({ rootDir, name? }): Promise<Workspace>
-renameWorkspace(id, name): Promise<void>
-removeWorkspace(id): Promise<void>          // does NOT touch the directory
-setWorkspaceAccess(id, userIds): Promise<void>   // admin-only, edits allowedUserIds
-userCanAccess(ws, userId): boolean          // admins always pass; else allowedUserIds check
-resolveWorkspaceRoot(id): Promise<string|null>
-safeWorkspacePath(rootDir, rel): string|null   // the old safeRootPath logic
-```
-
-`safeRootPath` logic moves here as `safeWorkspacePath(rootDir, rel)` (takes an
-explicit root instead of reading the global). Keep `root-dir.ts` as a thin
-deprecated shim during migration if helpful, then delete.
-
-### 2. Request-scoped workspace resolution
-
-New `src/lib/workspace-context.ts`:
-
-```ts
-// Browser/session routes
-async function resolveWorkspaceForUser(
-  req,
-): Promise<
-  | { ok: true; ws: Workspace; rootDir: string }
-  | { ok: false; status: number; code: string }
->;
-```
-
-Resolution order for browser routes:
-
-1. `ws` query param (preferred) or `x-workspace` header.
-2. If absent, fall back to the user's `lastOpenedAt` workspace (back-compat,
-   single-workspace users never notice).
-3. 400 `WORKSPACE_REQUIRED` if none and more than one workspace exists.
-
-Then enforce `userCanAccess(ws, user.id)` → 403 `WORKSPACE_FORBIDDEN`.
-
-For agent routes, `checkAuth` (in `src/lib/proof/auth.ts`) additionally reads
-`X-Workspace`, looks up the workspace, and checks the agent's grant for it
-(see §5). Returns `{ ok, agent, workspace, rootDir }`.
-
-### 3. Namespacing the in-memory stores
-
-Every store keyed by relPath becomes keyed by `wsId + "\0" + relPath` (the
-workspace id is a stable prefix, NUL separator avoids collisions).
-
-- `lease.ts`: `setLease`, `hasActiveLease`, `clearLease`, `leaseGeneration`
-  gain a `wsId` first arg → internal key `${wsId}\0${relPath}`.
-  `computeCollabState(rootDir, relPath)` already has rootDir; add `wsId` (or
-  derive a key from rootDir — but explicit wsId is cleaner). Update
-  `collab-state.ts` and `presence/route.ts` callers.
-- `mutex.ts` / `file-lock.ts`: callers pass a key already; change every call
-  site to prefix with `wsId` (e.g. `withFileMutex(`${wsId}\0${relPath}`, ...)`).
-  Cross-process sentinel hash then differs per workspace automatically.
-- `idempotency.ts`: prefix the key with `wsId` at the call site
-  (`events/[...path]/route.ts`, `files/[...path]/route.ts`).
-- `registry.ts` `lastSeenWriteAt` throttle map is keyed by agentId — fine, no
-  change.
-
-### 4. Threading rootDir through routes (29 files)
-
-Pattern, every session route:
-
-```ts
-const ctx = await resolveWorkspaceForUser(request);
-if (!ctx.ok)
-  return NextResponse.json({ error: ctx.code }, { status: ctx.status });
-const { ws, rootDir } = ctx;
-const filePath = safeWorkspacePath(rootDir, rel);
-```
-
-Replace all `getRootDir()` → `ctx.rootDir`, `safeRootPath(rel)` →
-`safeWorkspacePath(rootDir, rel)`, `isRootDirSet()` → existence of ctx.
-
-Route inventory (all under `src/app/api`):
-
-- `wiki/route.ts`, `wiki/content/route.ts`, `wiki/page/route.ts`,
-  `wiki/slugs/route.ts`, `wiki/file/route.ts`, `wiki/new-file/route.ts`,
-  `wiki/folder/route.ts`, `wiki/move/route.ts`, `wiki/upload/route.ts`,
-  `wiki/download/route.ts`, `wiki/app/route.ts`, `wiki/watch/route.ts`,
-  `wiki/presence/route.ts`
-- `assets/[...path]/route.ts`, `upload/[...path]/route.ts`
-- `system/reveal/route.ts`
-- agent: `fs/file`, `fs/ls`, `fs/move`, `fs/search`, `files`, `events`,
-  `sidecar`, `activity`, `settings`, `internal/span`
-
-`watch/route.ts` (SSE / chokidar): watcher must watch `ws.rootDir`. Each EventSource
-connection is per-workspace; the client opens `/api/wiki/watch?ws=<id>`.
-
-### 5. Workspace-scoped agents
-
-Agent grants gain a workspace dimension. In `registry.ts`:
-
-```ts
-interface AgentScope {
-  workspaceId: string; // NEW — the workspace this grant applies to
-  paths: string[];
-  ops: Array<"read" | "mutate" | "delete">;
-}
-```
-
-(An agent id may appear once per workspace, or scope becomes an array of
-per-workspace grants. Simpler: one registry row per (agentId, workspaceId).
-Recommend: keep `Agent.id` unique, add `workspaceId` to the record; an agent
-that needs two workspaces registers twice.)
-
-- `register` route: request body includes target `workspaceId`. Approval UI in
-  the AI panel shows which workspace the request is for.
-- `checkAuth`: resolve `X-Workspace`, then `enforceScope` also checks
-  `agent.scope.workspaceId === ws.id`. Mismatch → 403.
-- Browser session users (`user:<id>`) are synthesized in `checkAuth` with full
-  scope; gate them with `userCanAccess(ws, userId)` instead.
-- `audit.ts`: add `workspace_id` column to `agent_fs_audit`
-  (`ALTER TABLE ... ADD COLUMN`; tolerate existing DBs). Write it on every row.
-
-### 6. Config migration
-
-On first read of `config.json` with the new code:
-
-- If `workspaces` is absent but `lastOpenedPath` exists, synthesize one
-  workspace `{ id: ws_*, rootDir: lastOpenedPath, name: basename, pinnedPaths:
-config.pinnedPaths }` and mark it lastOpened. Keep old fields for one release
-  for rollback safety; new writes use `workspaces`.
-- `agents.json`: existing agents have no `workspaceId`. On load, backfill them
-  to the migrated default workspace id (and log once, mirroring the existing
-  legacy `ownerUserId` handling in the README checklist).
-
-### 7. API: workspace management routes
-
-New under `src/app/api/system/workspaces`:
-
-- `GET  /api/system/workspaces` — list workspaces visible to the user
-  (filtered by `userCanAccess`).
-- `POST /api/system/workspaces` — create `{ rootDir, name? }` (validates dir
-  exists, isDirectory). Replaces `set-root` semantics.
-- `PATCH /api/system/workspaces/<id>` — rename / pin-unpin allowed for any
-  user with access; **editing `allowedUserIds` is admin-only** (enforced field
-  by field in the handler).
-- `DELETE /api/system/workspaces/<id>` — **admin-only**. Unregister (directory
-  untouched).
-
-Workspace create (`POST`) is **admin-only** and sets `createdBy`. `GET` is open
-to any signed-in user but filtered: admins see all, others see only workspaces
-they can access. Admins management: `GET/POST/DELETE /api/system/admins`.
-
-Deprecate / re-point: `set-root`, `clear-root`, `root-status`, `pins`. Keep
-thin back-compat shims that operate on "the user's current/last workspace" so
-nothing 404s mid-migration, then remove in a follow-up.
-
-### 8. Client (browser)
-
-- `src/app/page.tsx`: hold `activeWorkspaceId` in state. Read from URL `?ws=`
-  first, else last opened. Put `ws` into every fetch (`/api/wiki?ws=...`,
-  watch URL, presence body). Cleanest: a small `wsFetch(path, init)` helper /
-  thin client store (`workspace-store.ts`) that injects `ws` automatically so
-  we are not editing dozens of `fetch` calls by hand.
-- Sidebar footer "Change" → opens a workspace switcher (list of workspaces the
-  user may access). "Add workspace" (reuses `DirPicker`) is shown **only to
-  admins**. Switching navigates to `?ws=<id>` (and `path` resets). Two tabs
-  with different `?ws=` are fully independent.
-- `DirPicker` (`src/components/dir-picker.tsx`): admin-only path. "Select" now
-  POSTs `/api/system/workspaces` (create) instead of `set-root`, then routes
-  to `?ws=<newId>`. Pins move under the chosen workspace.
-- Settings sheet, admins only: an **Admins** section (promote/demote users)
-  and a per-workspace **Access** editor (`allowedUserIds`). The client reads an
-  `isAdmin` flag (from `/api/system/admins` or root-status) to gate this UI.
-- `wiki-slugs-store`, `editor-store`, `tree-store`: any cached state that is
-  keyed by path must also be reset on workspace switch (cheap: remount the
-  page subtree on `ws` change via a React `key={activeWorkspaceId}`).
-
-### 9. CLI / startup (`bin/wiki-viewer.js`, `ROOT_DIR`)
-
-- `ROOT_DIR` (and `wiki-viewer ~/dir`) still works: on boot, if no workspaces
-  exist, auto-create one from `ROOT_DIR` and mark it default/lastOpened. So the
-  zero-config single-dir path is unchanged for existing users.
-- README "switch the served directory" copy updates to mention multiple
-  concurrent workspaces.
-
-## Isolation guarantees (the "no bleed" contract)
-
-| Surface              | Before            | After                           |
-| -------------------- | ----------------- | ------------------------------- |
-| Root dir             | one global        | per request, from `ws`          |
-| Sidecars / activity  | `<root>/.proof/`  | unchanged (already per-root)    |
-| Edit leases          | key=relPath       | key=`wsId\0relPath`             |
-| In-proc + file locks | key=relPath       | key=`wsId\0relPath`             |
-| Idempotency LRU      | key=idemKey       | key=`wsId\0idemKey`             |
-| Audit DB             | path only         | `+ workspace_id` column         |
-| Agents               | global path globs | `+ workspaceId` grant, enforced |
-| Access control       | any signed-in     | admin-set `allowedUserIds`/ws   |
-
-Two workspaces sharing the same relative path (`notes.md`) can be edited
-simultaneously without lock contention, lease confusion, or idempotency
-cross-talk.
-
-## Testing
-
-Extend `src/tests/proof/*`:
-
-- Two-workspace lease test: lease on `(wsA, x.md)` does not make
-  `(wsB, x.md)` active.
-- Mutex/lock test: concurrent writes to same relPath in two workspaces do not
-  serialize against each other (or at least do not corrupt).
-- Idempotency: same key in two workspaces are independent.
-- Scope test: agent granted `wsA` is 403 on `X-Workspace: wsB`.
-- Access test: user not in `allowedUserIds` is 403; admin always passes.
-- Admin test: non-admin POST /workspaces is 403; last-admin DELETE refused;
-  first-signup bootstrap promotes one admin.
-- Migration test: old config.json (lastOpenedPath + pinnedPaths) yields one
-  workspace; old agents.json backfills workspaceId.
-- Update existing tests: `setRootDir(tmpRoot)` calls in test setup become
-  "create a workspace + resolve it" (helper).
-
-## Rollout / sequencing
-
-0. Admin role: `auth/admin.ts`, `/api/system/admins`, bootstrap, settings UI
-   section. Independent, shippable alone.
-1. `workspaces.ts` + `workspace-context.ts` + config migration (no route
-   changes yet; default workspace mirrors old behavior).
-2. Namespacing stores (lease, mutex, file-lock, idempotency) with `wsId` arg,
-   defaulting to the single default workspace so nothing breaks.
-3. Thread `ctx.rootDir` through all 29 routes; delete `getRootDir` global.
-4. Agent workspace scoping + audit column.
-5. Workspace management API + client switcher + DirPicker repoint.
-6. Tests, README, CLI copy.
-
-Steps 1-2 are non-breaking and shippable alone. Step 3 is the big mechanical
-diff (good candidate for a `worker` pass with explicit outcomes per route).
-
-## Open questions / risks
-
-- **`pnpm-workspace.yaml` naming clash**: this repo is itself a pnpm workspace.
-  Use "workspace" in UI/API, but consider an internal code name like `space` or
-  keep `workspace` and just be careful in docs. Low risk, naming only.
-- **SSE watcher fan-out**: one chokidar watcher per (connection, workspace).
-  Many open tabs on the same workspace = many watchers. Acceptable now;
-  optimize later with a shared per-workspace watcher + ref count if needed.
-- **Admin bootstrap timing**: writing the first user into `adminUserIds` must
-  happen exactly once. Better-auth has no built-in "first user" hook, so
-  either tap the signup callback or do it lazily on the first authenticated
-  request when the admin set is empty (race-safe behind the config write
-  mutex). Decide during step 0.
-- **`allowedUserIds` default**: empty = any signed-in user (matches today's
-  behavior). Admins tighten per workspace via the Access editor.
-- Removing a workspace leaves `.proof/` and `.locks/` sentinels on disk; fine
-  (directory untouched by design), but document it.