kward 0.76.0 → 0.77.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bd9108129c3abd1aebeb3d1adb3e9011fbaf4e96c60a4f2ff55505497ff4fd0c
-  data.tar.gz: 14177ca73389b1e2df9239706f20b879d22322ec89e72f31a81aa573915b0b91
+  metadata.gz: 9a18a2a0c800780596999ee897ed61afcef22c964012f2b2ed3f51a3a66239c5
+  data.tar.gz: 83badb23b87cae5e3198e00c65f0c53acbe2e0561f00164c4e5b40aacb3d10d4
 SHA512:
-  metadata.gz: 787448090be2990a36e9d6d5c1911ce3bc5f6031f7c946a6d5d3edde3b78a43742227df6257d64c04e15def86a579e91366db602187200f1c08d241ae705d3b4
-  data.tar.gz: 9a18e14824b3f38d2d1e030adf706629a4e797cd49a8aa1c23786fb53d174e4e81a3d1462c6e7a15de4efa1df517f0aaed7eba89fab1d94f162ba066fff59743
+  metadata.gz: 5c4bd15eb61a2b62b5165b46d393fa60608dc702b773cbb0596bdd64deed1799332f22a5b271c146142f8f1f2769111e3e0075db34626818a71c4e502a14b49d
+  data.tar.gz: 9953137b41415eff742904f3a4f4d63a610da01351000d5b08d4191ad180bfbdff5c001315513bbf4fabd1918843a6c214712f9af737c0025c5494e6c84494f8

data/.github/workflows/ci.yml

@@ -13,6 +13,10 @@ permissions:
 jobs:
   test:
     runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby-version: ['3.2', 'ruby']
     steps:
       - name: Checkout
         uses: actions/checkout@v4
@@ -20,11 +24,14 @@ jobs:
       - name: Set up Ruby
         uses: ruby/setup-ruby@v1
         with:
-          ruby-version: '3.3'
+          ruby-version: ${{ matrix.ruby-version }}
           bundler-cache: true
 
       - name: Check syntax
         run: find lib test -name '*.rb' -print0 | xargs -0 ruby -c
 
+      - name: Check runtime warnings
+        run: ruby -w -Ilib -e 'require "kward"'
+
       - name: Run tests
         run: bundle exec rake test

data/CHANGELOG.md

@@ -4,6 +4,42 @@ All notable changes to Kward will be documented in this file.
 
 ## [Unreleased]
 
+## [0.77.0] - 2026-07-11
+
+### Added
+
+- Added `firstChangedLine` to successful RPC file-mutation results when Kward can derive it from the unified diff, allowing clients to navigate to the first changed line.
+- Added an opt-in Nerd Font icon theme for the `/files` browser, configurable through Interface settings or `project_browser.icons`; text-only rows remain the default.
+- Added Vim-style Vibe editor reindent commands: `==`, `={motion}` and text objects, plus visual `=`; reindentation uses the built-in language-aware auto-indent rules.
+- Added a security and trust guide covering local permissions, external data flow, trusted extensions, stored data, and safe use with unfamiliar repositories.
+- Added a dedicated Pan mode guide covering setup, browser and session workflows, prompt queueing, extensions, network security, and limitations.
+- Added an interactive composer guide covering editing keys, command and file completion, history, reasoning and tab shortcuts, busy input, cancellation, images, and terminal compatibility.
+- Added session browsing, creation, resume, rename, and deletion to Pan mode, with a responsive mobile-first interface using the documentation palette, Kward logo, and CLI-inspired startup screen.
+- Added dependency-free Markdown rendering for Pan transcript entries, including fenced code blocks, lists, blockquotes, inline styles, and safe links.
+
+### Fixed
+
+- Restored busy-tab `/tab` commands, including tab naming, switching, opening, and moving, without replacing the running tab's agent.
+- Fixed `/reload` so newly loaded plugin slash commands appear in the interactive completion overlay.
+- Pan mode now uses the active persona label for assistant messages and interface copy instead of a fixed Kward label.
+- Pan mode now prints the routed LAN address in its startup URL when available.
+- Fixed RPC session close, delete, and shutdown operations to cancel active turns before releasing session state, with a bounded fallback for uncooperative workers.
+- Fixed concurrent RPC turn event recording so replay sequence numbers remain unique and ordered.
+- Kept intentional empty-session garbage collection from deleting live CLI or RPC session files.
+- Removed scheduler timing from the throttled CLI streaming test and restored Ruby 4 image-attachment compatibility.
+
+### Removed
+
+- Removed the experimental worker pipeline, tab-backed worker queue, related CLI flag and commands, RPC capability, lifecycle hooks, and stored-runtime integration. Existing session files, worker metadata, and Git stashes are left untouched.
+
+### Changed
+
+- Improved documentation navigation, command and settings coverage, editor and diff-view workflows, configuration task guidance, and generated API comments for supported extension surfaces.
+- CI now tests the minimum supported Ruby and the current stable Ruby.
+- Removed unused private CLI, transcript-rendering, layout, and shell helpers, and clarified compaction guard naming.
+- Removed production Ruby warnings and added a warning-free runtime require check to CI.
+- Limited session listings now fully reconstruct only the requested newest sessions while still garbage-collecting abandoned empty files.
+
 ## [0.76.0] - 2026-07-10
 
 ### Added

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    kward (0.76.0)
+    kward (0.77.0)
       base64
       nokogiri
       tiktoken_ruby
@@ -146,7 +146,7 @@ CHECKSUMS
   html-proofer (5.2.1) sha256=fdd958a7cbf9c3255fb96fe7cfc4e611f64e2706e469488a3326309ad007d2fd
   io-event (1.16.2) sha256=9f9cb0a96ea5c3850a672606c65f27bc96d7621399ef6196acbfe2be0cd1279c
   json (2.19.9) sha256=9b9025b7cdddafa38d316eca0b2358488e42d417045c1b90d216a9fefe46b79a
-  kward (0.76.0)
+  kward (0.77.0)
   logger (1.7.0) sha256=196edec7cc44b66cfb40f9755ce11b392f21f7967696af15d274dde7edff0203
   metrics (0.15.0) sha256=61ded5bac95118e995b1bc9ed4a5f19bc9814928a312a85b200abbdac9039072
   minitest (6.0.6) sha256=153ea36d1d987a62942382b61075745042a2b3123b1cd48f4c3675af9cc7d6f1

data/README.md

@@ -41,18 +41,19 @@ kward init
 
 This downloads Kward's default prompts and base `PRINCIPLES.md` into your config directory. It is useful for a first setup, but safe to skip if you prefer to create your own instructions. Existing files are left untouched.
 
-Then start Kward and sign in when needed:
+Then sign in and start Kward:
 
 ```bash
+kward login                    # sign in or save provider credentials
 kward                          # start an interactive chat
 kward help                     # show available commands and examples
-/login                         # from inside Kward: sign in or save provider credentials
-kward login                    # from your shell: sign in or save provider credentials
 kward hooks doctor             # inspect lifecycle hook setup
 kward "Explain this project"   # run one prompt and exit
 kward --working-directory ~/code/project "Explain this project"
 ```
 
+From inside Kward, `/login` opens the same provider picker.
+
 See [Authentication](doc/authentication.md) for more details about sign-in options and provider credentials.
 
 ## What Kward can do
@@ -74,16 +75,23 @@ Start here:
 - [Usage](doc/usage.md): interactive chat, slash commands, sessions, tools, images, and Pan mode.
 - [Configuration](doc/configuration.md): config files, providers, models, web search, logging, and color output.
 - [Authentication](doc/authentication.md): OpenAI OAuth, Anthropic OAuth, OpenRouter API keys, and Copilot/GitHub setup.
+- [Security and trust](doc/security.md): local permissions, external data flow, trusted extensions, and safe work in unfamiliar repositories.
 - [Troubleshooting](doc/troubleshooting.md): environment-specific install and runtime issues.
 
 Feature guides:
 
 - [Sessions](doc/session-management.md): resume, clone, fork, rewind, compact, and navigate saved work.
-- [Integrated Editor](doc/editor.md): open files from the composer, edit in-place, and choose editor keybindings.
+- [Interactive composer](doc/composer.md): use multiline input, completion, history, files, reasoning shortcuts, busy input, and images.
+- [Tabs](doc/tabs.md): keep several conversations open and run work in another tab.
+- [Project files](doc/files.md): browse, search, mention, open, and edit workspace files.
+- [Integrated Editor](doc/editor.md): open files from the shell or composer, edit in-place, and choose editor keybindings.
 - [Git](doc/git.md): review changes, use the diff viewer, stage files, and commit from the interactive TUI.
 - [Shell](doc/shell.md): use `/shell`, the embedded Kward shell with aliases, completion, and per-tab state.
 - [Memory](doc/memory.md): opt-in core, soft, and session memory.
 - [Personas](doc/personas.md): configure Kward's tone and role by default, workspace, model, reasoning effort, time, and weekday.
+- [Skills](doc/skills.md): add reusable instructions that load only for matching tasks.
+- [MCP servers](doc/mcp.md): connect trusted local Model Context Protocol tool servers.
+- [Pan mode](doc/pan.md): use the mobile-friendly browser interface on a trusted local network.
 
 Advanced:
 

data/doc/agent-tools.md

@@ -8,7 +8,6 @@ Tools are part of Kward's safety and context-management boundary:
 - Ruby tool objects validate and execute those calls,
 - workspace tools stay inside the active workspace by default (see [Configuration](configuration.md) for the guardrail setting),
 - file-changing tools require the file to be read first,
-- mutation tools (`edit_file`, `write_file`, `run_shell_command`) are gated by a write lock when agent workers are active, so only one worker can change the workspace at a time,
 - large outputs are bounded or compacted before they enter model context,
 - full tool outputs are kept in the session record for later inspection.
 
@@ -45,8 +44,6 @@ This lets the assistant reason from focused evidence while preserving access to
 - `read_skill` is advertised only when skills are available,
 - `ask_user_question` is advertised only when the frontend can display structured questions.
 
-When agent workers are active, the registry can scope each worker to a subset of tools via an allowed-tool-names filter, so workers only see the tools they need.
-
 When `write_file` or `edit_file` changes an `AGENTS.md` file in the workspace root, Kward automatically rebuilds the system message so the model picks up the new instructions without a restart.
 
 Unknown tool calls are recorded as tool results instead of crashing the session, so the model can recover and choose an advertised tool on the next turn.

data/doc/api.md

@@ -45,6 +45,8 @@ Generated entry points:
 - [`Kward::Tools::Base`](Kward/Tools/Base.html)
 - [`Kward::ToolRegistry`](Kward/ToolRegistry.html)
 
+These pages document the schema and dispatch contract used by built-in tools. Kward does not yet provide a plugin DSL for registering arbitrary model-callable tools; contributors add them through the built-in registry and keep schemas, validation, docs, and tests aligned.
+
 ### RPC and frontend authors
 
 The RPC protocol is the supported integration surface for UI clients. Prefer the protocol guide before reading implementation classes.
@@ -78,6 +80,8 @@ Generated entry points:
 - [`Kward::Skills::Registry`](Kward/Skills/Registry.html)
 - [`Kward::ConfigFiles`](Kward/ConfigFiles.html)
 
+The generated comments focus on these supported extension boundaries rather than trying to make every internal orchestration helper public. When a generated method lacks guide coverage, treat it as internal unless the page explicitly marks it as a public API.
+
 ## Public API expectations
 
 Kward is still evolving. The generated reference is useful for understanding the codebase, but it should not be read as a promise that every class, method, or constructor is public and stable.

data/doc/composer.md

@@ -0,0 +1,219 @@
+# Interactive composer
+
+The composer is the input area at the bottom of Kward's interactive terminal UI. It is more than a single-line prompt: it supports multiline editing, command and file completion, persistent history, image attachments, reasoning selection, background tabs, queued follow-ups, and in-flight steering.
+
+This guide is a practical keyboard reference for working quickly without leaving the conversation.
+
+## Write and submit a prompt
+
+Type a prompt and press Return to submit it:
+
+```text
+Find where authentication errors are handled and explain the flow.
+```
+
+Use Shift+Return to insert a newline without submitting:
+
+```text
+Review the current diff.
+Focus on:
+- correctness
+- missing tests
+- confusing naming
+```
+
+Modified Enter support depends on what your terminal sends. If Shift+Return is swallowed or arrives as an ordinary Return, paste multiline text with bracketed paste, or compose it in another editor before pasting.
+
+The composer supports familiar line-editing keys:
+
+| Key | Action |
+| --- | --- |
+| `Left` / `Right` | Move by character |
+| `Home` / `Ctrl+A` | Move to the start of the current line |
+| `End` / `Ctrl+E` | Move to the end of the current line |
+| `Ctrl+B` / `Ctrl+F` | Move left or right |
+| `Alt+B` / `Alt+F` | Move by word |
+| `Backspace` / `Delete` | Delete before or at the cursor |
+| `Ctrl+W` | Delete the word before the cursor |
+| `Alt+D` | Delete the word after the cursor |
+| `Ctrl+U` / `Ctrl+K` | Kill from the cursor to the start or end of the line |
+| `Ctrl+Y` | Yank the most recently killed composer text |
+| `Ctrl+L` | Redraw the terminal UI |
+| `Ctrl+D` | Delete at the cursor, or exit when the composer is empty |
+
+These are composer bindings. The integrated editor, shell, Git view, file browser, and plugin interfaces have their own keymaps.
+
+## Find slash commands
+
+Type `/` at the beginning of the composer to open the slash-command picker:
+
+```text
+/ses
+```
+
+Use Up/Down to select a match. Press Tab to complete it, then add arguments if needed:
+
+```text
+/session name OAuth cleanup
+```
+
+Press Esc to dismiss the picker without deleting your draft. Return submits the command.
+
+The picker includes:
+
+- Kward's built-in commands,
+- configured prompt templates,
+- configured skills as `/skill:<name>`,
+- plugin slash commands,
+- plugin interactive commands.
+
+See [Usage](usage.md#Interactive_slash_commands) for the built-in command reference and [Extensibility](extensibility.md) for adding commands.
+
+## Mention a file with `@`
+
+Type `@` followed by part of a workspace path anywhere in a prompt:
+
+```text
+@agent
+```
+
+Kward shows fuzzy project-file matches. Use Up/Down to select one and Tab to insert the path:
+
+```text
+@lib/kward/agent.rb Explain how tool execution works here.
+```
+
+An `@path` is a textual pointer for the agent. It does not automatically place the whole file into model context; Kward can inspect the file with its tools when the task requires it. This keeps large files from being attached blindly.
+
+Press Esc to dismiss file completion. You can also insert a mention from the `/files` browser with `@`. See [Project files](files.md).
+
+## Open a file with `$`
+
+Start the composer with `$` to open a workspace file in the integrated editor:
+
+```text
+$lib/kward/agent.rb
+```
+
+The `$` token must begin at the first character of the composer. Use Up/Down to choose a match, then press Return or Tab to open it. If you type a path that does not exist and press Return, Kward can ask whether to create it.
+
+A successful `$path` open is saved in prompt history using the resolved workspace-relative path. It opens the editor instead of sending a model prompt.
+
+See [Integrated Editor](editor.md) for editing modes, save and quit keys, scratchpads, and conflict handling.
+
+## Reuse prompt history
+
+Kward stores prompt history per workspace under `~/.kward/history/`.
+
+- Press Up/Down when no completion picker is visible to move through earlier prompts.
+- Press `Ctrl+R` to start fuzzy history search.
+- Type a query, then use Up/Down to choose a match.
+- Press Return to place the selected result back into the composer for editing or submission.
+- Press Esc or `Ctrl+C` to cancel search and restore the draft you had before searching.
+
+History survives restarts. It contains submitted prompt text and successful `$path` editor-open commands, so protect it like other local Kward data. See [Security and trust](security.md#Local_data_and_permissions).
+
+## Change reasoning effort
+
+When no slash or file picker is open, Tab cycles forward through reasoning efforts supported by the current model. Shift+Tab cycles backward. The selection wraps and is persisted for later turns.
+
+The composer status line shows the current provider, model, and reasoning effort. Use `/reasoning` or `/model` when you prefer the explicit picker.
+
+Tab is context-sensitive:
+
+- in slash or `@path` completion, it accepts the selected match,
+- in `$path` completion, it opens the selected file,
+- otherwise, it changes reasoning effort,
+- in other modal interfaces, it follows that interface's own controls.
+
+## Work with tabs
+
+`Ctrl+Tab` and `Ctrl+Shift+Tab` switch conversations when your terminal reports those keys. Additional shortcuts depend on `composer.tab_keybindings`:
+
+- `ctrl`: `Ctrl+T` creates a tab, `Ctrl+W` closes one, and reported `Ctrl+1` through `Ctrl+9` select numbered tabs.
+- `alt`: `Alt+T` creates a tab, `Alt+Left`/`Alt+Right` move between tabs, and `Alt+1` through `Alt+9` select numbered tabs.
+- `auto`: prefers the Ctrl family on macOS and the Alt family elsewhere.
+
+Use `/settings` → Interface → Tab keybindings to change the family. If your terminal intercepts a shortcut, `/tab` commands always provide the same operations.
+
+See [Tabs](tabs.md) for background work, status colors, persistence, naming, and moving tabs.
+
+## Type while Kward is busy
+
+The composer stays available during a model turn or many long local actions.
+
+For a normal model turn:
+
+- If the current provider supports native in-flight steering, a non-empty prompt is sent as guidance to the running turn. Kward marks it as steered until the model applies it.
+- If steering is unavailable or fails, the prompt is queued and starts after the active turn.
+- Kward displays queued and steered counts in the busy composer.
+
+Use steering for short corrections that should affect work already in progress:
+
+```text
+Do not change the public API. Keep the fix internal.
+```
+
+Use a separate tab when you want an independent task rather than a correction to the current one.
+
+Most slash commands typed into a busy composer are intentionally ignored because delayed local state changes would be surprising. `/exit`, `/quit`, and `/new` are queued as control actions. `/tab` commands run immediately while work runs, so you can name, switch, open, or move tabs; closing the running tab remains unavailable.
+
+During local operations that do not support steering, submitted text is queued for later processing.
+
+## Cancel running work
+
+Press `Ctrl+C` while the busy composer is active to request cancellation of the current operation. Kward stops rendering further work and cooperatively cancels model and tool activity where possible.
+
+Cancellation is best effort. A network request, shell command, or side effect already in progress may finish before the underlying API can stop. Always inspect the workspace after cancelling a mutating task.
+
+When Kward is idle, `Ctrl+C` does not exit the interactive session. Use `/exit`, `/quit`, or `Ctrl+D` on an empty composer.
+
+The busy composer shows a cancellation hint by default. Hide only the hint—not cancellation itself—with `composer.busy_help: false` or the Interface settings menu.
+
+## Attach images
+
+Paste supported image references into the composer. Kward recognizes:
+
+- image paths,
+- Markdown image links,
+- `file://` URLs,
+- base64 image data URLs.
+
+Supported formats are GIF, JPEG, PNG, and WebP, up to 20 MB per image. Pasted references become badges above the draft, and their source text is removed from the visible prompt. Duplicate pasted references are ignored. References typed normally are resolved when the prompt is submitted.
+
+Example:
+
+```text
+./tmp/broken-layout.png Find the likely CSS problem shown in this screenshot.
+```
+
+If the cursor is at the start of an otherwise empty draft, Backspace removes the most recently added pending attachment. Submitting the draft clears its pending attachments.
+
+The active model must support image input. iTerm2 and Kitty-compatible terminals can render submitted images inline; other terminals still show attachment badges and send the image to the model without an inline preview.
+
+## Understand composer status
+
+The composer area can include:
+
+- the current Git branch or short commit, colored yellow when dirty,
+- additions and deletions recorded in the current session,
+- approximate context-window usage,
+- provider, model, and reasoning effort,
+- a tab bar plus queued or steered input counts,
+- an optional plugin footer.
+
+Context usage is an estimate, not provider billing. Use `/status` for more session and compaction detail.
+
+## Recover from terminal issues
+
+Terminal support for Shift+Return, Ctrl+Tab, modified number keys, OSC clipboard access, and inline images varies.
+
+If rendering becomes corrupted after resize or after an external program writes terminal controls:
+
+```text
+/redraw
+```
+
+You can also press `Ctrl+L`. If a shortcut never reaches Kward, prefer its slash-command equivalent or change `composer.tab_keybindings` in `/settings`.
+
+For full-screen interactive programs such as Vim or `less`, use `/pty <command>` or `pty <command>` inside `/shell` so the program temporarily owns the terminal instead of fighting the composer.

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.
@@ -234,21 +259,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 +314,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 +451,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
 {

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