docs: document the browser ui

Author: sviat-barbutsa

README.md

@@ -2,7 +2,7 @@
 
 Zharwing Memory is a local-first project context manager for AI-assisted coding workflows. It is not the coding agent. External agents such as Codex, Claude Code, Gemini CLI, Ollama-based tools, LM Studio workflows, and future MCP-capable clients do the engineering work. Zharwing Memory provides their durable, project-scoped memory layer.
 
-The product keeps project knowledge, AI session history, context bundles, diagrams, decisions, commands, gotchas, and optional review proposals organized per project. A human can open the desktop app to understand current work, inspect AI context, inspect the graph, search previous work, and enable review workflows only when wanted.
+The product keeps project knowledge, AI session history, context bundles, diagrams, decisions, commands, gotchas, and optional review proposals organized per project. A human can open the local browser UI or native desktop app to understand current work, inspect AI context, inspect the graph, search previous work, and enable review workflows only when wanted.
 
 > **Status: standalone personal developer preview.** The current product is
 > intended for a trusted developer using a local, single-user environment. It
@@ -130,7 +130,7 @@ check.
 
 ```text
 apps/
-  desktop/          Tauri + React human control plane
+  desktop/          Shared React browser UI and Tauri human control plane
   daemon/           Localhost JSON-RPC daemon
   cli/              zharwing-memory command-line helper
   mcp-server/       MCP-style stdio adapter
@@ -150,6 +150,7 @@ packages/
 
 docs/
   README.md         Documentation index
+  WEB_UI.md         Local browser startup, auth, usage, and troubleshooting
   ARCHITECTURE.md   System architecture
   DATA_MODEL.md     Entities, storage, and metadata
   API_REFERENCE.md  Daemon, CLI, and MCP surfaces
@@ -198,27 +199,52 @@ ZHARWING_MEMORY_AUTH_TOKEN=<local-random-token>
 VITE_ZHARWING_MEMORY_AUTH_TOKEN=<same-local-random-token>
 ```
 
-Start the daemon and browser UI:
+### Local Browser UI
+
+The browser UI is a complete local interface for normal daily use, not a demo
+or a reduced documentation view. It exposes the same React pages and workflows
+as the native desktop window.
+
+Start the daemon in the first terminal:
 
 ```bash
 corepack pnpm dev:daemon
+```
+
+Start the browser UI in a second terminal:
+
+```bash
 corepack pnpm dev:web
 ```
 
-For the native desktop app, run:
+Open `http://localhost:5174/`. Keep both processes running. The browser UI calls
+the daemon at `http://127.0.0.1:37841`; `dev:web` does not start it.
+
+The values of `ZHARWING_MEMORY_AUTH_TOKEN` and
+`VITE_ZHARWING_MEMORY_AUTH_TOKEN` must match. Restart `dev:web` after changing
+Vite environment variables. Browser path fields accept typed or pasted
+absolute paths because browsers cannot expose arbitrary local folders.
+
+See the dedicated [Browser UI guide](docs/WEB_UI.md) for the full setup,
+browser-versus-desktop comparison, local authentication, and troubleshooting.
+
+### Native Desktop UI
+
+For the native Tauri app, run:
 
 ```bash
 corepack pnpm dev:desktop
 ```
 
 In a source checkout, the desktop shell starts or reuses the local daemon
 automatically. A copied release executable reuses an already-running daemon or
-uses `ZHARWING_MEMORY_DESKTOP_DAEMON_COMMAND` when configured. Browser mode
-keeps the normal separate daemon + web server flow.
+uses `ZHARWING_MEMORY_DESKTOP_DAEMON_COMMAND` when configured. The native shell
+adds OS folder pickers; the core project, session, library, graph, and settings
+workflows are shared with the browser UI.
 
-Open `http://localhost:5174/`, create a project, then link repos from
-Repositories. For multi-repo products, create the project first and add each Git
-repo root afterward.
+In either UI, create a project, then link repos from Repositories. For
+multi-repo products, create the project first and add each Git repo root
+afterward.
 
 ### Pointer Files
 
@@ -286,9 +312,10 @@ restore, single-item permanent delete, selected permanent delete, and full empty
 ## Architecture Summary
 
 ```text
-Desktop UI     \
-CLI             -> daemon API -> shared packages -> Markdown source of truth
-MCP adapter    /                              \-> rebuildable indexes
+Browser UI     \
+Desktop UI      \
+CLI              -> daemon API -> shared packages -> Markdown source of truth
+MCP adapter     /                              \-> rebuildable indexes
 ```
 
 The daemon owns:
@@ -306,7 +333,7 @@ The daemon owns:
 - trash, restore, and permanent purge
 - optional assistant jobs
 
-The desktop app, CLI, and MCP server are adapters.
+The browser UI, native desktop app, CLI, and MCP server are adapters.
 
 ## Memory Root Shape
 
@@ -456,10 +483,12 @@ project administration, repository links, workstreams, document editing,
 imports, graph settings, backups, Trash, and other control-plane operations.
 See [API Reference](docs/API_REFERENCE.md) for both surfaces.
 
-## Desktop UI
+## Browser And Desktop UI
 
-The desktop app is the human control plane. The sidebar stays intentionally
-small:
+The local browser UI and native desktop app share the same React human control
+plane. The browser UI is often the fastest way to use Memory from a source
+checkout: run the daemon, run `dev:web`, and open `http://localhost:5174/`.
+The sidebar stays intentionally small:
 
 - project switcher for selecting, creating, and deleting projects
 - Dashboard
@@ -478,12 +507,12 @@ Secondary pages live inside section tabs:
 - Settings: Project, Setup, Assistant, Backups
 
 In the native Tauri desktop window, Setup, Repositories, and Import provide
-Browse buttons for selecting folders with the OS file picker. Browser dev mode
-keeps typed paths as a fallback because browsers do not expose arbitrary local
-folder paths to web apps.
+Browse buttons for selecting folders with the OS file picker. The browser UI
+provides the same underlying workflows but uses typed or pasted absolute paths
+because browsers do not expose arbitrary local folder paths to web apps.
 
-See [Desktop UI](docs/DESKTOP_UI.md) for the current navigation and first-run
-flow.
+See [Browser UI](docs/WEB_UI.md) for startup and troubleshooting, and
+[Browser And Desktop UI](docs/DESKTOP_UI.md) for navigation and first-run flow.
 
 The visual direction follows the Graphite + Copper theme from the product plan.
 
@@ -498,7 +527,8 @@ Start here:
 - [Data Model](docs/DATA_MODEL.md)
 - [API Reference](docs/API_REFERENCE.md)
 - [User Flows](docs/USER_FLOWS.md)
-- [Desktop UI](docs/DESKTOP_UI.md)
+- [Browser UI](docs/WEB_UI.md)
+- [Browser And Desktop UI](docs/DESKTOP_UI.md)
 - [Graph Rules](docs/GRAPH_RULES.md)
 - [Diagrams](docs/DIAGRAMS.md)
 - [Operations](docs/OPERATIONS.md)

docs/DESKTOP_UI.md

@@ -1,13 +1,13 @@
-# Desktop And Web UI
+# Browser And Desktop UI
 
-The desktop/web UI is the human control plane for Zharwing Memory. It is not an
-agent. It lets a user create memory projects, link repos, import old notes,
-review context, inspect sessions, manage durable memory, and recover deleted
-items.
+The local browser UI and native desktop app are two runtime modes for the same
+React human control plane. Neither is an agent. Both let a user create memory
+projects, link repos, import old notes, review context, inspect sessions, manage
+durable memory, and recover deleted items.
 
 ## Runtime Modes
 
-Browser development mode:
+Browser mode uses two processes. Start them in separate terminals:
 
 ```text
 pnpm dev:daemon
@@ -38,6 +38,16 @@ The browser UI cannot browse arbitrary local folders. In browser mode, path
 fields accept typed or pasted absolute paths. In the Tauri window, Setup,
 Repos, and Import can use OS folder picker buttons.
 
+| Behavior | Browser UI | Native Tauri app |
+| --- | --- | --- |
+| Pages and workflows | Full shared React UI | Full shared React UI |
+| Daemon | Start separately | Starts or reuses it in a source checkout |
+| Folder selection | Type or paste absolute paths | OS folder picker buttons |
+| Window | `http://localhost:5174/` | Native application window |
+
+For browser environment variables, token matching, first startup, and common
+errors, see the dedicated [Browser UI guide](WEB_UI.md).
+
 Setup also includes Agent MCP actions for automatic install, installing Codex,
 Claude Code, or Claude Desktop config, and checking the current MCP setup.
 These actions call the same installer as `zharwing-memory mcp install` and require

docs/MVP_WALKTHROUGH.md

@@ -25,15 +25,19 @@ Browser UI:
 pnpm dev:web
 ```
 
+Run this in a second terminal while `pnpm dev:daemon` remains active, then open
+`http://localhost:5174/`. The local browser UI contains the complete React
+control plane. See [Browser UI](WEB_UI.md) for environment setup and
+troubleshooting.
+
 Native Tauri window:
 
 ```text
 pnpm dev:desktop
 ```
 
-Use `dev:web` when you only need the browser app at
-`http://localhost:5174/`. Use `dev:desktop` when you need the Tauri desktop
-window and OS folder picker support.
+Use `dev:web` for daily browser-based use or development. Use `dev:desktop`
+when you want the same UI in a Tauri window with OS folder picker support.
 
 ## UI First Run
 

docs/OPERATIONS.md

@@ -98,16 +98,37 @@ CLI:
 corepack pnpm dev:cli projects
 ```
 
-Browser UI:
+### Local Browser UI
+
+The browser UI is a full local control plane for daily use. It renders the same
+React application as the Tauri window, but it does not manage the daemon
+process. Start the daemon first and keep it running:
+
+```text
+corepack pnpm dev:daemon
+```
+
+Then start the UI in a second terminal:
 
 ```text
 corepack pnpm dev:web
 ```
 
-The React/Vite dev server is pinned to `http://localhost:5174` so it does
+Open `http://localhost:5174/`. The React/Vite dev server is pinned to that port so it does
 not collide with other local product runtimes that commonly use Vite's default
 `5173`.
 
+In token mode, the daemon and browser bundle must use the same local token:
+
+```text
+ZHARWING_MEMORY_AUTH_TOKEN=<local-random-token>
+VITE_ZHARWING_MEMORY_AUTH_TOKEN=<same-local-random-token>
+```
+
+Vite loads `.env` when the process starts. Restart `dev:web` after changing a
+`VITE_` value. See [Browser UI](WEB_UI.md) for complete setup and
+troubleshooting.
+
 Desktop/web UI workflows currently include setup, project selection, project
 delete, repo links, import preview/commit, workstreams, sessions, docs, search,
 context preview, inbox, graph, backup management, and Trash restore/purge. The

docs/README.md

@@ -32,9 +32,13 @@ This folder contains product and engineering documentation for the Zharwing Memo
 - [User Flows](USER_FLOWS.md)
   First-time setup, daily coding, project return, context preview, inbox review, assistant workflows, backup, and recovery.
 
-- [Desktop UI](DESKTOP_UI.md)
-  Browser and Tauri runtime modes, lightweight sidebar model, first-run setup,
-  import workflow, opt-in session graph visibility, and Trash behavior.
+- [Browser UI](WEB_UI.md)
+  Complete local browser startup, daemon and token configuration, daily use,
+  browser-versus-desktop differences, and troubleshooting.
+
+- [Browser And Desktop UI](DESKTOP_UI.md)
+  Shared navigation, browser and Tauri runtime modes, first-run setup, import
+  workflow, opt-in session graph visibility, and Trash behavior.
 
 - [Diagrams](DIAGRAMS.md)
   Mermaid diagrams: architecture, UML class diagram, ERD, sequence diagrams, state machines, user flow, context pipeline, storage layout, and backup flow.
@@ -68,18 +72,19 @@ This folder contains product and engineering documentation for the Zharwing Memo
 2. Read [Architecture](ARCHITECTURE.md).
 3. Review [Diagrams](DIAGRAMS.md) for system shape.
 4. Use [User Flows](USER_FLOWS.md) to understand behavior.
-5. Use [Desktop UI](DESKTOP_UI.md) when operating the browser or Tauri app.
-6. Use [API Reference](API_REFERENCE.md) when wiring clients.
-7. Use [Agent Protocol](AGENT_PROTOCOL.md) when wiring agents or generating agent-specific instructions.
-8. Use [MCP Setup](MCP_SETUP.md) when connecting Codex, Claude, or another MCP client.
-9. Use [Agent Automation](AGENT_AUTOMATION.md) when configuring bootstrap files or the generic skill.
-10. Use [Repositories](REPOSITORIES.md) when linking multiple repos to one memory project.
-11. Use [Workstreams](WORKSTREAMS.md) when grouping multi-day topics.
-12. Use [Importing](IMPORTING.md) when bringing in existing Markdown memory or session folders.
-13. Use [Graph Rules](GRAPH_RULES.md) when imported memory needs better graph hubs.
-14. Use [Semantic Graph Analysis](SEMANTIC_GRAPH.md) when enabling AI-reviewed relationships.
-15. Use [Testing With AI Providers](AI_TESTING.md) when checking LM Studio, session TLDR generation, or another model-backed provider.
-16. Use [Operations](OPERATIONS.md) when running or packaging the app.
+5. Use [Browser UI](WEB_UI.md) to run Memory in a browser.
+6. Use [Browser And Desktop UI](DESKTOP_UI.md) for the shared navigation and workflows.
+7. Use [API Reference](API_REFERENCE.md) when wiring clients.
+8. Use [Agent Protocol](AGENT_PROTOCOL.md) when wiring agents or generating agent-specific instructions.
+9. Use [MCP Setup](MCP_SETUP.md) when connecting Codex, Claude, or another MCP client.
+10. Use [Agent Automation](AGENT_AUTOMATION.md) when configuring bootstrap files or the generic skill.
+11. Use [Repositories](REPOSITORIES.md) when linking multiple repos to one memory project.
+12. Use [Workstreams](WORKSTREAMS.md) when grouping multi-day topics.
+13. Use [Importing](IMPORTING.md) when bringing in existing Markdown memory or session folders.
+14. Use [Graph Rules](GRAPH_RULES.md) when imported memory needs better graph hubs.
+15. Use [Semantic Graph Analysis](SEMANTIC_GRAPH.md) when enabling AI-reviewed relationships.
+16. Use [Testing With AI Providers](AI_TESTING.md) when checking LM Studio, session TLDR generation, or another model-backed provider.
+17. Use [Operations](OPERATIONS.md) when running or packaging the app.
 
 ## Documentation Policy