kward 0.76.0 → 0.78.0

data/doc/configuration.md

@@ -1,10 +1,25 @@
 # Configuration
 
-Kward reads user configuration from `~/.kward/config.json` by default. Most users do not need to edit this file by hand at first: use `/login`, `/model`, `/reasoning`, and `/settings` from inside Kward when possible.
+Kward reads user configuration from `~/.kward/config.json` by default. Most users should start with `/settings`, `/login`, `/model`, or `/reasoning` inside Kward. Edit JSON directly when you need an advanced setting, an integration, or a reproducible configuration.
 
-On first start, if the file does not exist, Kward creates a starter config with an active Kward persona, explicit disabled memory settings, and the default composer busy-help setting so you can inspect and edit them. Provider-specific model defaults are added only when you choose a provider/model. See [Personas](personas.md) for configuring persona selection by workspace, model, or reasoning effort. If `KWARD_CONFIG_PATH` is set, Kward uses that file instead and treats that file's directory as the config directory for prompts, skills, memory, logs, and caches.
+On first start, Kward creates the file when it does not exist. The starter config records defaults for personas, memory, the composer, editor, overlays, web search, update checks, sessions, skills, MCP, and workspace guardrails. Provider-specific model defaults are added only when you choose a provider or model.
 
-Small examples:
+If `KWARD_CONFIG_PATH` is set, Kward uses that file and treats its directory as the config directory for prompts, skills, memory, logs, and caches.
+
+## Common changes
+
+| Goal | Recommended path |
+| --- | --- |
+| Sign in or change accounts | `/settings` → Accounts, or `/login` |
+| Choose a provider, model, or reasoning effort | `/settings` → Model & Reasoning, `/model`, or `/reasoning` |
+| Change editor, diff, overlay, or session UI behavior | `/settings` → Interface |
+| Enable memory | `/settings` → Memory |
+| Configure web search or trust project skills | `/settings` → Tools & Search |
+| Tune compaction | `/settings` → Context & Compaction |
+| Configure personas | `/settings` → Personalization; see [Personas](personas.md) |
+| Add MCP servers, lifecycle hooks, or environment-specific paths | Edit `config.json` directly |
+
+Here is a minimal direct provider configuration:
 
 ```json
 {
@@ -13,6 +28,10 @@ Small examples:
 }
 ```
 
+### MCP servers
+
+Add trusted local Model Context Protocol servers under `mcpServers`:
+
 ```json
 {
   "mcpServers": {
@@ -24,7 +43,11 @@ Small examples:
 }
 ```
 
-See [MCP servers](mcp.md) for connecting local Model Context Protocol servers such as Safari's browser automation server.
+See [MCP servers](mcp.md) for setup, supported fields, and security notes.
+
+### Project skills
+
+Kward loads user-level skills but skips project-level skills by default. Enable them only for repositories you trust, either through `/settings` → Tools & Search → Trust project skills or with:
 
 ```json
 {
@@ -34,40 +57,42 @@ See [MCP servers](mcp.md) for connecting local Model Context Protocol servers su
 }
 ```
 
-By default, Kward loads user-level skills but skips project-level skills from the workspace. Set `skills.trust_project` to `true`, or use `/settings` → `Tools & Search` → `Trust project skills`, when you trust the repository's `.kward/skills` or `.agents/skills` directories. See [Skills](skills.md) for skill locations and examples.
+See [Skills](skills.md) for skill locations, precedence, examples, and trust behavior.
 
-```json
-{
-  "updates": {
-    "check": true
-  }
-}
-```
+### Update checks
 
-Kward checks RubyGems for newer `kward` versions on the interactive startup screen. Results are cached under `~/.kward/cache/update_check.json` so startup does not hit RubyGems every time. Set `updates.check` to `false`, or set `KWARD_DISABLE_UPDATE_CHECK=1`, to disable the check.
+Kward checks RubyGems for newer versions on the interactive startup screen. Results are cached so startup does not contact RubyGems every time. Disable this automatic network request with:
 
 ```json
 {
-  "memory": {
-    "enabled": true
+  "updates": {
+    "check": false
   }
 }
 ```
 
+You can also set `KWARD_DISABLE_UPDATE_CHECK=1` for one run. The cache lives at `<config-dir>/cache/update_check.json`.
+
 ## Config directory
 
-By default, Kward stores user data under `~/.kward`:
+By default, Kward stores user data under `~/.kward`. Common files and directories include:
 
 ```text
 ~/.kward/config.json
 ~/.kward/auth.json
 ~/.kward/anthropic_auth.json
 ~/.kward/github_auth.json
+~/.kward/PRINCIPLES.md
+~/.kward/ekwsh.yml
+~/.kward/prompts/
+~/.kward/skills/
+~/.kward/plugins/
 ~/.kward/sessions/
+~/.kward/history/
 ~/.kward/memory/
 ~/.kward/logs/
 ~/.kward/cache/
-~/.kward/plugins/
+~/.kward/trusted_workspace_hooks.json
 ```
 
 When `KWARD_CONFIG_PATH=/path/to/config.json` is set, most config-related files live beside that file instead. User plugins are the exception: they are loaded only from `~/.kward/plugins`. See [Plugins](plugins.md) for writing and loading user plugins.
@@ -159,6 +184,8 @@ Model settings:
 
 Set `codex_show_raw_reasoning` to `true` to display raw Codex `reasoning_text` when the API does not provide reasoning summary text. It defaults to `false`; raw reasoning can include internal or unstable model output, so enable it only when you explicitly want to inspect that stream.
 
+`stream_idle_timeout_seconds` limits how long a streamed Codex or Anthropic response may go without receiving data. It defaults to `120`; set a positive value to override it. When the provider is silent longer than this limit, Kward closes the request and applies its normal transient-network retry behavior.
+
 Defaults:
 
 - OpenAI/Codex: `gpt-5.6-sol`
@@ -234,21 +261,20 @@ Overlay settings control terminal picker/card layout. New default configs includ
 
 You can change these interactively with `/settings`.
 
-## Web search settings
+<a id="project-browser-icons"></a>
+## Project browser icons
 
-New default configs enable web search with the automatic provider order:
+`/files` uses text-only rows by default so it remains legible in terminals without a patched icon font. To enable Nerd Font icons explicitly:
 
 ```json
 {
-  "web_search": {
-    "enabled": true,
-    "provider": "auto",
-    "allow_model_providers": false
+  "project_browser": {
+    "icons": "nerd-font"
   }
 }
 ```
 
-Existing configs without `web_search` keep the same behavior: web search is enabled, the provider is `auto`, and model-provider fallbacks are disabled unless explicitly enabled.
+`icons` defaults to `off`; the supported values are `off` and `nerd-font`. Kward does not detect terminal fonts. Enable `nerd-font` only after configuring a compatible Nerd Font, such as Hack Nerd Font, in your terminal. You can also select **File icons** under the Interface section of `/settings`.
 
 ## Composer settings
 
@@ -290,7 +316,19 @@ The built-in TUI file editor supports three keybinding modes. Modern is the defa
 }
 ```
 
-`mode` can be `modern`, `emacs`, or `vibe`. The old `default` value is still accepted as an alias for `modern`. You can change this from `/settings` > Interface > Editor mode; newly opened editor buffers pick up the setting immediately.
+`mode` can be `modern`, `emacs`, or `vibe`. The old `default` value is still accepted as an alias for `modern`. You can change this from `/settings` → Interface → Editor mode; newly opened editor buffers pick up the setting immediately.
+
+The integrated Git and session diff viewers support unified and side-by-side layouts:
+
+```json
+{
+  "editor": {
+    "diff_view": "auto"
+  }
+}
+```
+
+`diff_view` can be `auto`, `unified`, or `side_by_side`. In `auto` mode, Kward uses side-by-side output when the terminal is at least 120 columns wide and unified output in narrower terminals. Change it with `/settings` → Interface → Diff view.
 
 The editor automatically highlights Ruby, Crystal, Elixir, Julia, JavaScript, TypeScript, JSON, Markdown, YAML, Shell, Makefile, HTML, CSS, SCSS, Python, Go, Rust, Java, C#, C, C++, Swift, Kotlin, Lua, and SQL files when terminal color is enabled. Unknown file types and color-disabled terminals render plain text.
 
@@ -415,11 +453,23 @@ Manual `/compact [instructions]` works even when auto-compaction is disabled.
 
 `host` defaults to `0.0.0.0` and `port` defaults to `8765`. Kward fails to start pan mode unless `username` and `password` are configured.
 
-These credentials are stored in plaintext config. Use a private, user-specific password and do not share the config file. Pan mode exposes the agent's file, shell, and web tools to anyone on the LAN who has the credentials, so use it only on trusted networks.
+These credentials are stored in plaintext config. Use a private, user-specific password and do not share the config file. Pan mode exposes the agent's file, shell, web, and configured extension tools to anyone on the LAN who has the credentials, so use it only on trusted networks. See [Pan mode](pan.md) for the full browser workflow, session behavior, security guidance, and limitations.
 
 ## Web search
 
-Web search works without an API key through Exa's public MCP endpoint and is advertised to the model by default. To hide the tool:
+Web search is enabled by default with automatic provider selection. Model-backed fallback providers remain disabled unless you explicitly allow them:
+
+```json
+{
+  "web_search": {
+    "enabled": true,
+    "provider": "auto",
+    "allow_model_providers": false
+  }
+}
+```
+
+Existing configs without a `web_search` object use those same defaults. Web search works without an API key through Exa's public MCP endpoint and is advertised to the model by default. To hide the tool:
 
 ```json
 {
@@ -480,6 +530,43 @@ Workspace guardrails are enabled by default. File tools such as `read_file`, `wr
 
 This is not a sandbox setting. Shell commands already run as your OS user from the workspace directory and can access anything that user can access.
 
+## Permissions
+
+Permissions are off by default. When enabled, Kward evaluates model-requested tools before execution. This is a permission policy, not an operating-system sandbox: permitted shell commands still run with your user account's access.
+
+```json
+{
+  "permissions": {
+    "enabled": true,
+    "mode": "ask"
+  }
+}
+```
+
+Available modes are:
+
+| Mode | Behavior |
+| --- | --- |
+| `ask` | Read-only tools run normally; file changes, shell commands, web tools, and MCP tools need approval. |
+| `workspace-write` | File changes within `write_scopes` run without approval; shell and network tools still need approval. |
+| `read-only` | Denies file changes, shell commands, web tools, and MCP tools. |
+| `deny-by-default` | Denies risky tools unless an `allow` rule matches. |
+
+`allow`, `ask`, and `deny` rules are arrays of objects matching `tool`, `path`, `host`, `command`, or `source`. Deny rules always take precedence, then ask, then allow. Use `write_scopes` to restrict writes in `workspace-write` mode:
+
+```json
+{
+  "permissions": {
+    "enabled": true,
+    "mode": "workspace-write",
+    "write_scopes": ["lib/**", "test/**"],
+    "deny": [{ "tool": "run_shell_command", "command": "git push*" }]
+  }
+}
+```
+
+The interactive CLI presents an approval overlay for an `ask` decision. RPC clients can use their existing `approvalMode: "ask"` bridge. Frontends without an approval bridge, including Pan, fail closed for policy approvals.
+
 ## Logging and stats
 
 Local telemetry logs are off by default. Enable logging with the master flag and each category you want:

data/doc/editor.md

@@ -16,7 +16,20 @@ The editor is scoped to the current workspace. It only opens files inside that d
 
 ## Quick start
 
-Open the file picker by typing `$` as the first character in the composer:
+Open a file directly from your shell:
+
+```bash
+cd ~/code/my-project
+kward edit lib/kward/agent.rb
+```
+
+Kward uses the current directory as the workspace, opens the file in the integrated editor, and exits when you close the editor. Use `--working-directory` when the file belongs to another workspace:
+
+```bash
+kward --working-directory ~/code/my-project edit lib/kward/agent.rb
+```
+
+From an interactive Kward session, open the file picker by typing `$` as the first character in the composer:
 
 ```text
 $lib/kward/agent.rb
@@ -297,6 +310,8 @@ Use normal mode for movement, operators, marks, registers, macros, search, and c
 | `dir` / `cir` / `yir`   | Delete / change / yank inside a Ruby block      |
 | `dar` / `car` / `yar`   | Delete / change / yank around a Ruby block      |
 | `yy`                    | Yank line                                       |
+| `==`                    | Reindent current line                           |
+| `={motion}`             | Reindent lines covered by a motion or text object |
 | `"ayy` / `"ap`         | Yank / paste with named registers               |
 | `p`                     | Paste after cursor                              |
 | `P`                     | Paste before cursor                             |
@@ -338,6 +353,7 @@ Visual mode uses the same motion language as normal mode where practical. Start
 | `%`, `f`/`F`/`t`/`T`    | Extend visual selection with advanced motions   |
 | `iw` / `a(` / `ip`      | Select visual text objects                      |
 | `>` / `<`               | Indent / outdent selected lines                 |
+| `=`                     | Reindent selected lines                         |
 | `I` / `A`               | Insert / append text across visual block lines  |
 | `J`                     | Join selected lines                             |
 | `~` / `u` / `U`         | Swapcase / lowercase / uppercase selection      |
@@ -408,7 +424,7 @@ Vibe mode is not trying to be Vim. It is a focused subset designed for quick edi
 - **Counts work with commands and motions**: `3dd` deletes three lines, `2w` moves two words, `5x` deletes five characters.
 - **`.` repeats the last change**: after `cw word Esc`, pressing `.` changes the next word the same way. Insert-mode keystrokes are recorded as part of the change.
 - **`/` and `?` search forward and backward**: `n` and `N` repeat the last search. `*` and `#` search for the word under the cursor.
-- **Operators with motions**: `d`, `y`, and `c` work with `w` (word), `e` (end of word), `b` (back word), `$` (end of line), `0` (start of line), and `^` (first non-blank).
+- **Operators with motions**: `d`, `y`, `c`, and `=` work with `w` (word), `e` (end of word), `b` (back word), `$` (end of line), `0` (start of line), and `^` (first non-blank). `=` uses Kward's built-in language-aware auto-indent rules.
 - **Yanks copy to the terminal clipboard**: when OSC 52 is supported, yanked text is also sent to the system clipboard, so you can paste into other applications.
 - **Registers and macros are supported**: named registers work with yank/delete/paste flows, and `q`/`@` record and replay simple macros for repeated edits.
 - **Viewport commands**: `zz`, `zt`, and `zb` reposition the cursor line to the center, top, or bottom of the viewport without moving the cursor itself — the same as Vim.

data/doc/files.md

@@ -42,7 +42,7 @@ Outside Git, Kward scans the workspace directory and skips common noisy director
 | `Esc` | Leave search; press again to close the browser |
 | `@` | Insert the selected file as an `@path` mention |
 
-Directories use `▸` and `▾` markers to show collapsed and expanded state. Files are shown under their containing directory with indentation.
+Directories use `▸` and `▾` markers to show collapsed and expanded state. Files are shown under their containing directory with indentation. File-type icons are off by default; users with a compatible Nerd Font can enable them under Interface in `/settings`. See [Configuration](configuration.md#project-browser-icons).
 
 ## Search files
 

data/doc/getting-started.md

@@ -34,6 +34,8 @@ kward doctor
 
 This checks your config, auth, writable directories, and workspace. Run `kward help` to see all available commands and examples.
 
+Interactive startup also performs a cached RubyGems version check by default. It does not contact RubyGems on every start; disable it with `KWARD_DISABLE_UPDATE_CHECK=1` or the `updates.check` configuration setting. See [Configuration](configuration.md#Update_checks).
+
 If you are working from a checkout instead:
 
 ```bash
@@ -128,5 +130,7 @@ Inside interactive Kward:
 ## Next steps
 
 - Read [Usage](usage.md) for day-to-day workflows.
+- Read [Interactive composer](composer.md) for completion, history, file mentions, keyboard shortcuts, busy input, and images.
 - Read [Configuration](configuration.md) when you want to change providers, models, memory, or web search.
+- Read [Security and trust](security.md) before using Kward with sensitive data, untrusted repositories, or third-party extensions.
 - Read [Extensibility](extensibility.md) when you want reusable prompts, skills, or project rules.

data/doc/git.md

@@ -44,7 +44,7 @@ Use `Shift+Enter` to insert a newline if you need a multi-line commit message.
 
 Highlight a file in the `/git` overlay and press `Enter`.
 
-Kward opens a read-only diff viewer in the composer area. It shows classic Git diff output with added and removed lines colorized when terminal color is enabled.
+Kward opens a read-only diff viewer in the composer area. Added and removed lines are colorized when terminal color is enabled. The viewer supports unified and side-by-side layouts; its default `auto` mode uses side-by-side output at 120 columns or wider and unified output in narrower terminals. Choose a fixed layout with `/settings` → Interface → Diff view. See [Configuration](configuration.md#Editor_settings) for the JSON setting.
 
 Useful keys in the diff viewer:
 
@@ -61,7 +61,7 @@ Useful keys in the diff viewer:
 
 After you close the viewer, Kward returns to the Git overlay with the file list refreshed.
 
-The diff viewer is read-only. It is meant for checking what changed, not editing. If you spot something you want to fix, close the viewer, return to chat, and ask Kward to make the change or open the file with the built-in editor using `$path/to/file` (see [Configuration](configuration.md) for editor modes and settings).
+The diff viewer is read-only. It is meant for checking what changed, not editing. If you spot something you want to fix, close the viewer, return to chat, and ask Kward to make the change or open the file with the built-in editor using `$path/to/file`. See [Integrated Editor](editor.md) for editor workflows and keybindings.
 
 ## Example workflow
 

data/doc/lifecycle-hooks.md

@@ -302,18 +302,6 @@ MCP events are emitted in addition to generic `tool_call_*` events for tools pro
 | `shell_command_before` | `command`, `timeout_seconds`, `cwd` | `command`, `timeout_seconds` |
 | `shell_command_after` | shell metadata plus `content` | none |
 
-### Worker events
-
-| Event | Payload highlights | Supported modifications |
-| --- | --- | --- |
-| `worker_job_create` | `worker_id`, `role`, `title`, `status`, `session_path` | none |
-| `worker_job_start_before` | worker metadata | none |
-| `worker_job_start_after` | worker metadata | none |
-| `worker_job_ready_for_review` | worker metadata | none |
-| `worker_job_failed` | worker metadata plus `error` | none |
-
-Worker hooks are observe-and-warn hooks for background worker automation and audit trails. They do not control worker scheduling.
-
 ### Git events
 
 | Event | Payload highlights | Supported modifications |
@@ -337,9 +325,9 @@ Worker hooks are observe-and-warn hooks for background worker automation and aud
 
 `file_change_before` fires before `write_file` or `edit_file` mutates the workspace and can deny or ask for approval. `file_change_after` fires only after successful `write_file` or `edit_file` results.
 
-### MCP events
+### Matching MCP tools
 
-MCP tools are surfaced through generic tool events with:
+In addition to the dedicated MCP events above, MCP tools are surfaced through generic tool events with:
 
 - `source: "mcp"`
 - `server_name`

data/doc/pan.md

@@ -0,0 +1,167 @@
+# Pan mode
+
+Pan mode is Kward's browser interface for a workspace. It gives you a mobile-friendly transcript, prompt composer, live tool activity, and access to recent sessions while Kward continues running on your development machine.
+
+Use it when you want to work from another browser or device on a trusted network without running the full terminal UI there.
+
+## Before you start
+
+Pan is a small local HTTP server, not a hosted service. The machine running Kward performs model requests, reads and edits workspace files, runs tools, and stores sessions.
+
+Pan requires HTTP Basic Auth. Add credentials to `~/.kward/config.json`:
+
+```json
+{
+  "pan_mode": {
+    "host": "0.0.0.0",
+    "port": 8765,
+    "username": "kward",
+    "password": "choose-a-long-private-password"
+  }
+}
+```
+
+The defaults are:
+
+- `host`: `0.0.0.0`, which listens on all network interfaces.
+- `port`: `8765`.
+
+Kward refuses to start Pan unless both `username` and `password` are configured. The password is stored as plaintext in your config file, so do not reuse an important password or share the file.
+
+For access from the same machine only, bind to loopback instead:
+
+```json
+{
+  "pan_mode": {
+    "host": "127.0.0.1",
+    "port": 8765,
+    "username": "kward",
+    "password": "choose-a-long-private-password"
+  }
+}
+```
+
+## Start Pan
+
+Run Pan from the project it should control:
+
+```bash
+cd ~/code/my-project
+kward pan
+```
+
+Or select the workspace explicitly:
+
+```bash
+kward --working-directory ~/code/my-project pan
+```
+
+Kward prints the listening URL, workspace, and initial session path. With the default LAN binding, it detects and prints the machine's routed LAN address when available. Open port `8765` at that address, for example:
+
+```text
+http://192.168.1.25:8765/
+```
+
+Your browser asks for the configured Basic Auth username and password.
+
+Press `Ctrl+C` in the server terminal to stop Pan. Closing a browser tab does not stop the server or an active turn.
+
+## A normal workflow
+
+1. Start Pan in the workspace you want to use.
+2. Open the printed address in a browser and sign in.
+3. Enter a concrete request in the composer:
+
+   ```text
+   Review the current changes, inspect the affected files, and run the focused tests.
+   ```
+
+4. Watch reasoning, tool calls, tool output, retries, and the answer stream into the transcript.
+5. Continue in the same session, or use the session sidebar to switch work.
+
+Press Return to send. Use Shift+Return for a new line. The composer grows with multiline input up to its display limit.
+
+Prompts are accepted while another turn is running. Pan puts them into a single queue and executes them sequentially. The status below the composer shows whether Kward is working and how many prompts remain queued.
+
+## Work with sessions
+
+Pan saves conversations through the same workspace-scoped session store as the interactive CLI. The session sidebar shows up to 50 recent sessions with their title, modified time, and message count.
+
+From the sidebar you can:
+
+- select a session to resume it,
+- create a new session,
+- rename the active session,
+- delete the active session.
+
+On smaller screens, use the menu button to open the session drawer. Selecting a session closes the drawer and loads its transcript.
+
+A few details matter:
+
+- Pan starts with a new session when the server launches.
+- Creating or resuming a session rebuilds the active conversation and agent around it.
+- You cannot create, resume, rename, or delete sessions while a turn is active or prompts are queued. Wait for the queue to finish.
+- Deleting the active session creates and activates a replacement session first.
+- Pan asks for confirmation before deletion. The interface does not provide an undo action.
+- Sessions remain available to the terminal CLI through `/session` because both frontends use the same session files.
+
+See [Sessions](session-management.md) for storage, exports, forks, compaction, and other session operations that remain CLI-oriented.
+
+## Tools and live output
+
+Pan creates the normal Kward agent tool registry for the selected workspace. Depending on configuration, the model can use file, shell, web, code-search, skill, and MCP tools just as it can in a normal agent turn.
+
+The transcript displays:
+
+- user prompts,
+- streamed reasoning and assistant text,
+- tool names and arguments,
+- tool results,
+- retries and errors,
+- restored compaction summaries and prior session content.
+
+Assistant and reasoning entries use a built-in, dependency-free Markdown renderer. It supports headings, paragraphs, fenced code blocks, blockquotes, ordered and unordered lists (including task lists), inline code, emphasis, strikethrough, and HTTP(S) or `mailto:` links. Message content remains text-based; unsupported Markdown stays readable as plain text.
+
+Structured clarification questions are disabled in Pan because it does not have the interactive question picker. Ask the model to state uncertainties in the transcript when a task needs your decision.
+
+Pan does not reproduce terminal-only interfaces such as `/git`, `/files`, `/shell`, the integrated editor, settings pickers, tabs, or clipboard commands. Use natural-language requests for agent work and return to the CLI for those local UI workflows.
+
+## Hooks and plugins
+
+Pan runs configured command hooks and trusted plugin lifecycle hooks. Hook events and messages can appear in the browser's live event stream.
+
+Pan does not provide a dedicated approval interface for hook `ask` decisions. An approval request without a bridge fails closed, so use deterministic `deny` or non-blocking `warn` policies for Pan-facing hooks.
+
+Other plugin UI features, such as custom terminal commands, footers, or interactive canvas commands, are designed for the CLI or RPC clients and do not become controls in the Pan page.
+
+See [Lifecycle hooks](lifecycle-hooks.md#Frontend_support) and [Plugins](plugins.md) for the supported extension surfaces.
+
+## Network and security
+
+Pan exposes powerful agent tools through ordinary HTTP. Basic Auth protects every page and endpoint, but Pan does not provide TLS.
+
+Use these precautions:
+
+- Run it only on a network and machine you trust.
+- Prefer `127.0.0.1` when remote access is unnecessary.
+- Do not expose the port directly to the public internet.
+- Do not put Pan behind a public tunnel unless you provide a properly secured TLS/authentication boundary and understand the risk.
+- Use a unique password and protect `config.json`.
+- Remember that anyone with the credentials can submit prompts that cause file reads, edits, shell commands, web requests, or MCP calls with your account's permissions.
+- Stop the server when you are finished.
+
+Multiple authenticated browser tabs connect to the same Pan process, active session, prompt queue, and workspace. They are not isolated users. A session change or prompt submitted in one connected browser is visible to the others.
+
+Read [Security and trust](security.md) before using Pan with sensitive data or an unfamiliar repository.
+
+## Notes and limitations
+
+- Pan serves one configured workspace per process.
+- Turns run one at a time; queued prompts cannot be reordered or cancelled from the page.
+- Session changes are blocked until all active and queued work finishes.
+- There is no model or reasoning picker in the page; Pan uses the configured client defaults when it creates a conversation.
+- There is no dedicated tool-approval UI or structured-question UI.
+- The browser reconnects its event stream after a connection interruption, but events emitted while disconnected are not replayed through that stream. Reloading restores the persisted transcript.
+- Request bodies are limited to 64 KB.
+- Pan displays image entries from restored transcripts as text placeholders rather than rendering attached image data.
+- The server is intentionally small and does not replace the richer CLI or the integration-oriented [RPC protocol](rpc.md).