kward 0.71.0 → 0.72.0

data/doc/editor.md

@@ -0,0 +1,394 @@
+# Integrated Editor
+
+<quote>
+Three Modes for the Elven-kings under the sky,<br>
+Seven Keymaps for the Dwarf-lords in their halls of stone,<br>
+Nine Editors for Mortal Men doomed to compile,<br>
+One Kward to rule them all,<br>
+One Kward to find them,<br>
+One Kward to bring them all and in the transcript bind them<br>
+In the Land of Ruby where the agents lie.<br>
+</quote>
+
+Kward includes a terminal editor with 3 editing modes to choose from: Modern, Emacs and Vibe. It opens inside the chat composer, so you can jump into a file, make a change, save it, and return to the conversation without switching tools.
+
+The editor is scoped to the current workspace. It only opens files inside that directory, which helps keep edits tied to the project you started Kward in.
+
+## Quick start
+
+Open the file picker by typing `$` as the first character in the composer:
+
+```text
+$lib/kward/agent.rb
+```
+
+As you type, Kward shows matching files. Use the arrow keys to choose one and press `Enter` to open it.
+
+For a nested project tree, run:
+
+```text
+/files
+```
+
+In the tree browser, use `↑`/`↓` to move, `←`/`→` to collapse or expand directories, `Enter` to toggle a directory or open a file, `Tab` or `/` to search, `@` to insert the selected file as an `@path` mention, and `Esc` to close. When you open a file from `/files`, quitting the editor returns to the browser at the same position.
+
+You can also type a relative path yourself and press `Enter`. If the file does not exist, Kward asks whether to create it.
+
+A few things to know:
+
+- `$` only opens the editor when it is the first character in the composer.
+- Once a file opens, the composer becomes the editor.
+- Save or quit to return to normal chat.
+- If the file changed on disk while you were editing, Kward asks before overwriting it.
+- If you quit with unsaved changes, Kward asks before discarding them.
+
+## Example workflow
+
+```text
+$doc/editor.md
+```
+
+1. Type `$doc/editor.md` in the composer.
+2. Pick the file from the matching results, or press `Enter` if the path is already complete.
+3. Edit the file.
+4. Save with `Ctrl+S` in Modern mode, `C-x C-s` in Emacs mode, or `:w` in Vibe mode.
+5. Quit with `Ctrl+Q`, `C-x C-c`, or `:q`.
+6. Continue chatting with Kward.
+
+## What the editor supports
+
+The editor is intentionally compact, but it covers the basics you need for quick changes:
+
+- Syntax highlighting for common languages, including 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. Unknown file types render as plain text.
+- Auto-indent, enabled by default. New lines inherit indentation, Tab jumps to the expected indentation or the next indentation stop, Shift+Tab moves indentation back, obvious closing tokens are re-indented, and Backspace in leading whitespace removes one indentation unit when possible. For Ruby, Crystal, Elixir, Julia, Lua, Makefiles, and shell scripts, Enter after a block opener inserts the matching closing keyword; Ctrl+Enter also works from the middle of the line in terminals that report modified Enter keys.
+- Undo and redo, with up to 100 history entries per buffer.
+- Incremental search forward and backward.
+- Selection, copy, cut, and paste. Copy and cut also write to the terminal clipboard through OSC 52 when the terminal supports it.
+- A line-number gutter and a status line that shows the current mode and prompts.
+- Soft-wrap, enabled by default so long lines wrap within the editor width instead of scrolling sideways. Disable it with `editor.soft_wrap: false`.
+
+## Choosing an editor mode
+
+The editor has three keybinding modes:
+
+- **Modern**: default mode, with familiar shortcuts like `Ctrl+S`, `Ctrl+Q`, `/` search, and `?` reverse search.
+- **Emacs**: non-modal Emacs-style chords, including `C-x C-s`, `C-x C-c`, and a per-buffer kill ring.
+- **Vibe**: modal editing inspired by classic vi/vim workflows, with normal, insert, replace, visual, and command modes.
+
+Change the mode from:
+
+```text
+/settings > Interface > Editor mode
+```
+
+New editor buffers use the updated setting immediately. You do not need to restart Kward.
+
+You can also configure it in `config.json`:
+
+```json
+{
+  "editor": {
+    "mode": "modern"
+  }
+}
+```
+
+`mode` can be `modern`, `emacs`, or `vibe`. The old `default` value is still accepted as an alias for `modern`.
+
+To disable auto-indent or auto-close pairs:
+
+```json
+{
+  "editor": {
+    "auto_indent": false,
+    "auto_close_pairs": false
+  }
+}
+```
+
+Auto-close pairs inserts matching `()`, `[]`, `{}`, quotes, and backticks while editing.
+
+Line numbers are absolute by default. Set `editor.line_numbers` to `relative` to show distances from the cursor line in editable buffers while keeping the current line absolute.
+
+Editable editor buffers request a vertical bar cursor by default. Set `editor.bar_cursor` to `false` if you want Kward to leave the terminal cursor shape alone.
+
+See [Configuration](configuration.md) for the full editor settings reference.
+
+## Modern mode
+
+Modern mode is the default and is the easiest place to start. It uses common terminal-editor shortcuts and supports Shift+Arrow selection.
+
+| Key                   | Action                                            |
+| --------------------- | ------------------------------------------------- |
+| `Ctrl+S`              | Save                                              |
+| `Ctrl+Q`              | Quit; press again to discard unsaved changes      |
+| `/`                   | Search forward                                    |
+| `?`                   | Search backward                                   |
+| `Ctrl+C`              | Copy selection, or cancel search                  |
+| `Ctrl+X`              | Cut selection                                     |
+| `Ctrl+V`              | Paste kill buffer                                 |
+| `Ctrl+Y`              | Copy selection, or paste if there is no selection |
+| `Ctrl+Z`              | Undo                                              |
+| `Ctrl+Shift+Z`        | Redo                                              |
+| `Ctrl+Space`          | Begin selection                                   |
+| `Shift+Arrow`         | Extend selection                                  |
+| `Alt+Up` on macOS, `Ctrl+Up` elsewhere | Move up by indentation level          |
+| `Alt+Down` on macOS, `Ctrl+Down` elsewhere | Move down by indentation level    |
+| `Alt+Right` on macOS, `Ctrl+Right` elsewhere | Move to indentation, then word end |
+| `Alt+Shift+Up` on macOS, `Ctrl+Shift+Up` elsewhere | Select up by indentation level |
+| `Alt+Shift+Down` on macOS, `Ctrl+Shift+Down` elsewhere | Select down by indentation level |
+| `Alt+Shift+Right` on macOS, `Ctrl+Shift+Right` elsewhere | Select to indentation, then word end |
+| `Ctrl+Left`           | Move to start of line                             |
+| `Alt+Shift+Left`      | Extend selection to previous word boundary        |
+| `Ctrl+A`              | Move to start of line                             |
+| `Ctrl+E`              | Move to end of line                               |
+| `Ctrl+B`              | Move left                                         |
+| `Ctrl+F`              | Move right                                        |
+| `Ctrl+N`              | Move down                                         |
+| `Ctrl+P`              | Move up                                           |
+| `Ctrl+K`              | Kill to end of line                               |
+| `Ctrl+U`              | Kill to start of line                             |
+| `Ctrl+W`              | Delete word before cursor                         |
+| `Ctrl+D`              | Delete character at cursor                        |
+| `Alt+B`               | Move to previous word                             |
+| `Alt+F`               | Move to next word                                 |
+| `Alt+D`               | Delete word after cursor                          |
+| `Alt+Backspace`       | Delete word before cursor                         |
+| `Arrow keys`          | Move cursor                                       |
+| `Home` / `End`        | Move to start / end of line                       |
+| `PageUp` / `PageDown` | Scroll                                            |
+| `Enter`               | Insert newline, or confirm search                 |
+| `Tab`                 | Smart-indent to the expected indentation or next stop |
+| `Shift+Tab`           | Move indentation back by one stop                 |
+| `Backspace`           | Delete before cursor                              |
+| `Delete`              | Delete character at cursor                        |
+| `Esc`                 | Cancel search or clear selection                  |
+
+## Emacs mode
+
+Emacs mode is for users who prefer classic Emacs-style non-modal editing. Save and quit use two-key `C-x` commands, and kills are stored in a per-buffer kill ring so you can yank and cycle recent kills.
+
+| Key                   | Action                                       |
+| --------------------- | -------------------------------------------- |
+| `C-x C-s`             | Save                                         |
+| `C-x C-c`             | Quit; press again to discard unsaved changes |
+| `C-s`                 | Search forward                               |
+| `C-r`                 | Search backward                              |
+| `C-g`                 | Cancel search, pending command, or selection |
+| `Esc`                 | Clear selection, or cancel search            |
+| `C-Space`             | Set the mark and begin a region              |
+| `C-w`                 | Kill region, or delete word before cursor    |
+| `M-w`                 | Copy region                                  |
+| `C-y`                 | Yank from kill ring                          |
+| `M-y`                 | Cycle kill ring after a yank                 |
+| `C-a`                 | Move to start of line                        |
+| `C-e`                 | Move to end of line                          |
+| `C-b`                 | Move left                                    |
+| `C-f`                 | Move right                                  |
+| `C-n`                 | Move down                                    |
+| `C-p`                 | Move up                                      |
+| `C-k`                 | Kill to end of line                          |
+| `C-u`                 | Kill to start of line                        |
+| `M-d`                 | Delete word after cursor                     |
+| `M-Backspace`         | Delete word before cursor                    |
+| `M-b`                 | Move to previous word                        |
+| `M-f`                 | Move to next word                            |
+| `C-v`                 | Page down                                    |
+| `M-v`                 | Page up                                      |
+| `Arrow keys`          | Move cursor                                  |
+| `Home` / `End`        | Move to start / end of line                  |
+| `PageUp` / `PageDown` | Scroll                                       |
+| `Enter`               | Insert newline, or confirm search            |
+| `Tab`                 | Smart-indent to the expected indentation or next stop |
+| `Shift+Tab`           | Move indentation back by one stop            |
+| `Backspace`           | Delete before cursor                         |
+| `Delete` / `C-d`      | Delete character at cursor                   |
+
+## Vibe mode
+
+Vibe mode is a modal editor built for Kward, inspired by classic Vi and Vim. If you already know Vim, you will feel at home here. Files open in normal mode, where keys run commands. Press `i`, `a`, `o`, or another insert command to type text, then press `Esc` to return to normal mode.
+
+It supports a compact but practical modal-editing set: counts, operators with motions, visual selections, visual block edits, marks, registers, macros, search, repeat (`.`), Ruby-aware navigation, and `:` commands. It is not a full Vim clone — there are no splits or ex-mode scripting — but it covers everyday keyboard editing inside the conversation.
+
+The status line always shows the current mode (`NORMAL`, `INSERT`, `VISUAL`, `REPLACE`, or `:`) so you never lose track of where you are.
+
+### Normal mode
+
+Use normal mode for movement, operators, marks, registers, macros, search, and command mode. Visual-mode-specific commands are listed in their own section below.
+
+| Key                     | Action                                          |
+| ----------------------- | ----------------------------------------------- |
+| `h` / `←` / `Backspace` | Move left                                       |
+| `j` / `↓` / `Ctrl+N`    | Move down                                       |
+| `k` / `↑` / `Ctrl+P`    | Move up                                         |
+| `l` / `Space`           | Move right                                      |
+| `0` / `Home`            | Move to start of line                           |
+| `^`                     | Move to first non-blank character               |
+| `$` / `End`             | Move to end of line                             |
+| `w`                     | Move to next word                               |
+| `e`                     | Move to end of word                             |
+| `b`                     | Move to previous word                           |
+| `gg`                    | Move to start of file                           |
+| `G`                     | Move to end of file                             |
+| `N G`                   | Move to line `N`                                |
+| `H`                     | Move to top of screen                           |
+| `M`                     | Move to middle of screen                        |
+| `L`                     | Move to bottom of screen                        |
+| `zz`                    | Center cursor line in viewport                  |
+| `zt`                    | Scroll cursor line to top of viewport           |
+| `zb`                    | Scroll cursor line to bottom of viewport         |
+| `+` / `Enter`           | Move to first non-blank of next line            |
+| `-`                     | Move to first non-blank of previous line        |
+| `_`                     | Move to first non-blank of current line         |
+| `Ctrl+J`                | Move down by indentation level                  |
+| `Ctrl+K`                | Move up by indentation level                    |
+| `Ctrl+F`                | Page down                                       |
+| `Ctrl+B`                | Page up                                         |
+| `Ctrl+D`                | Half page down                                  |
+| `Ctrl+U`                | Half page up                                    |
+| `Ctrl+E`                | Scroll down one line                            |
+| `Ctrl+Y`                | Scroll up one line                              |
+| `i`                     | Insert before cursor                            |
+| `I`                     | Insert at first non-blank of line               |
+| `a`                     | Insert after cursor                             |
+| `A`                     | Insert at end of line                           |
+| `o`                     | Open line below and insert                      |
+| `O`                     | Open line above and insert                      |
+| `x`                     | Delete character at cursor                      |
+| `X`                     | Delete character before cursor                  |
+| `dd`                    | Delete line                                     |
+| `D`                     | Delete to end of line                           |
+| `C`                     | Change to end of line                           |
+| `cc`                    | Change line                                     |
+| `s`                     | Substitute character                            |
+| `S`                     | Change line                                     |
+| `J`                     | Join lines                                      |
+| `r` then char           | Replace character                               |
+| `R`                     | Replace mode                                    |
+| `dw` / `yw` / `cw`      | Delete / yank / change with motion              |
+| `diw` / `yiw` / `ciw`   | Delete / yank / change inner word               |
+| `daw` / `yaw` / `caw`   | Delete / yank / change a word plus spacing      |
+| `di(`/`ci(`/`yi(`       | Delete / change / yank inside a pair            |
+| `da(`/`ca(`/`ya(`       | Delete / change / yank around a pair            |
+| `dib` / `ciB`           | Pair aliases for parentheses/braces             |
+| `dip` / `cip` / `yip`   | Delete / change / yank inside a paragraph       |
+| `dap` / `cap` / `yap`   | Delete / change / yank around a paragraph       |
+| `dir` / `cir` / `yir`   | Delete / change / yank inside a Ruby block      |
+| `dar` / `car` / `yar`   | Delete / change / yank around a Ruby block      |
+| `yy`                    | Yank line                                       |
+| `"ayy` / `"ap`         | Yank / paste with named registers               |
+| `p`                     | Paste after cursor                              |
+| `P`                     | Paste before cursor                             |
+| `u`                     | Undo                                            |
+| `Ctrl+R`                | Redo                                            |
+| `%`                     | Jump to matching pair                           |
+| `f`/`F`/`t`/`T`         | Find character on current line                  |
+| `{` / `}`               | Move by paragraph                               |
+| `]m` / `[m`             | Jump to next / previous Ruby method             |
+| `df)` / `ct,` / `d%`    | Use character and pair motions with operators   |
+| `;` / `,`               | Repeat character find forward/backward          |
+| `U`                     | Restore current line                            |
+| `.`                     | Repeat last change                              |
+| `v`                     | Visual character mode                           |
+| `V`                     | Visual line mode                                |
+| `Ctrl+V`                | Visual block mode                               |
+| `gv`                    | Restore previous visual selection               |
+| `ma` / `` `a `` / `'a`  | Set and jump to marks                           |
+| `qa` / `@a` / `@@`      | Record and replay macros                        |
+| `/`                     | Search forward                                  |
+| `?`                     | Search backward                                 |
+| `n`                     | Repeat search                                   |
+| `N`                     | Repeat search in opposite direction             |
+| `*`                     | Search word under cursor forward                |
+| `#`                     | Search word under cursor backward               |
+| `:`                     | Enter command mode                              |
+| `:%s/a/b/g`             | Substitute text across command ranges           |
+| `Esc` / `Ctrl+C`        | Cancel pending command                          |
+| `N`command              | Repeat command `N` times, such as `3dd` or `2w` |
+
+### Visual mode
+
+Visual mode uses the same motion language as normal mode where practical. Start characterwise visual mode with `v`, linewise mode with `V`, or visual block mode with `Ctrl+V`.
+
+| Key                     | Action                                          |
+| ----------------------- | ----------------------------------------------- |
+| `o`                     | Switch active end of visual selection           |
+| `G` / `gg` / `N`motion  | Extend visual selection with counts/motions     |
+| `%`, `f`/`F`/`t`/`T`    | Extend visual selection with advanced motions   |
+| `iw` / `a(` / `ip`      | Select visual text objects                      |
+| `>` / `<`               | Indent / outdent selected lines                 |
+| `I` / `A`               | Insert / append text across visual block lines  |
+| `J`                     | Join selected lines                             |
+| `~` / `u` / `U`         | Swapcase / lowercase / uppercase selection      |
+| `/` / `?` / `n` / `N`   | Extend visual selection with search             |
+| `y` / `d` / `c` / `p`   | Yank / delete / change / paste selection        |
+
+### Insert mode
+
+In insert mode, typed characters are inserted at the cursor. Press `Esc` or `Ctrl+C` to return to normal mode. Arrow keys move the cursor without leaving insert mode.
+
+Vibe insert mode also supports readline-style shortcuts for efficient editing without dropping back to normal mode:
+
+| Key              | Action                                   |
+| ---------------- | ---------------------------------------- |
+| type text        | Insert characters                        |
+| `Enter`          | Insert newline                           |
+| `Tab`            | Smart-indent to the expected indentation or next stop |
+| `Shift+Tab`      | Move indentation back by one stop        |
+| `Backspace`      | Delete before cursor                     |
+| `Delete`         | Delete character at cursor               |
+| `Ctrl+A`         | Move to start of line                    |
+| `Ctrl+E`         | Move to end of line                      |
+| `Ctrl+B`         | Move left                                |
+| `Ctrl+F`         | Move right                               |
+| `Ctrl+D`         | Delete character at cursor               |
+| `Ctrl+K`         | Kill to end of line                      |
+| `Ctrl+U`         | Kill to start of line                    |
+| `Ctrl+W`         | Delete word before cursor                |
+| `Ctrl+Y`         | Paste kill buffer                        |
+| `Alt+B`          | Move to previous word                    |
+| `Alt+F`          | Move to next word                        |
+| `Alt+D`          | Delete word after cursor                 |
+| `Alt+Backspace`  | Delete word before cursor                |
+| `Arrow keys`     | Move cursor                              |
+| `Home` / `End`   | Move to start / end of line              |
+| `Esc` / `Ctrl+C` | Return to normal mode                    |
+
+### Replace mode
+
+Replace mode overwrites characters at the cursor instead of inserting. Each typed character replaces the character under the cursor and advances. Press `Esc` or `Ctrl+C` to return to normal mode.
+
+| Key              | Action                      |
+| ---------------- | --------------------------- |
+| type text        | Replace character at cursor |
+| `Enter`          | Insert newline              |
+| `Backspace`      | Delete before cursor        |
+| `Esc` / `Ctrl+C` | Return to normal mode       |
+
+Typing an opening bracket (`(`, `[`, `{`) or quote (`"`, `'`, `` ` ``) in visual mode wraps the selection in the matching pair, then returns to normal mode.
+
+### Command mode
+
+Enter command mode with `:` from normal mode. Type a command and press `Enter`. Press `Esc` or `Ctrl+C` to cancel.
+
+| Command | Action                                     |
+| ------- | ------------------------------------------ |
+| `:w`    | Save                                       |
+| `:q`    | Quit; refuses if there are unsaved changes |
+| `:q!`   | Quit and discard changes                   |
+| `:wq`   | Save and quit                              |
+| `:x`    | Save if changed, then quit                 |
+| `:N`    | Go to line `N`                             |
+
+### Vibe design notes
+
+Vibe mode is not trying to be Vim. It is a focused subset designed for quick edits inside a chat-based coding agent. Here is what to expect:
+
+- **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).
+- **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.
+- **Indentation navigation**: `Ctrl+J` and `Ctrl+K` jump to the next or previous indentation level, which is useful for navigating nested code blocks in Ruby and other indented languages.

data/doc/extensibility.md

@@ -40,6 +40,8 @@ Default location:
 
 If `KWARD_CONFIG_PATH` is set, `PRINCIPLES.md` lives beside that config file.
 
+If `PRINCIPLES.md` is absent, Kward also reads `~/.kward/AGENTS.md` (or the equivalent beside a custom config path) as a legacy alias. New setups should use `PRINCIPLES.md`. See [Configuration](configuration.md) for details.
+
 ## Project instructions: `AGENTS.md`
 
 Put repository-specific rules in the workspace root:
@@ -59,7 +61,7 @@ Update CHANGELOG.md for user-visible changes.
 
 Use `AGENTS.md` for project facts and engineering rules. Do not put personality or roleplay instructions there; use [personas](personas.md) for tone.
 
-By default, Kward adds a compact instruction telling the model that `AGENTS.md` exists and should be read when relevant. Set `enforce_workspace_agents_file: true` only if you want the full file injected every time.
+By default, Kward adds a compact instruction telling the model that `AGENTS.md` exists and should be read when relevant. Set `enforce_workspace_agents_file: true` only if you want the full file injected every time. See [Configuration](configuration.md) for details.
 
 ## Prompt templates
 
@@ -89,6 +91,8 @@ Then run inside Kward:
 /review auth edge cases
 ```
 
+The `description` frontmatter field appears in the slash command list and completion overlay so you can find the template by purpose. `argument-hint` is shown as a usage hint. The `$ARGUMENTS` placeholder in the body is replaced with whatever you type after the command.
+
 Prompt templates are best for reusable text. They do not run local code.
 
 ## Skills
@@ -106,14 +110,16 @@ Example:
 ```markdown
 ---
 name: testing
-or description: Use when adding or changing tests.
+description: Use when adding or changing tests.
 ---
 
 Prefer focused tests near the changed behavior.
 Do not weaken assertions to make tests pass.
 ```
 
-Skills are listed to the model by name and description. Kward can load the full skill only when it is relevant.
+Skills are listed to the model by name and description. When a task matches a skill, the model calls the `read_skill` tool to load the full `SKILL.md` instructions before proceeding.
+
+Skills can also contain additional files alongside `SKILL.md`. The model can read them through `read_skill` with a relative `path` argument (for example, `path: examples.md`). Files must stay inside the skill folder; paths outside are rejected.
 
 ## Plugins
 
@@ -135,13 +141,16 @@ When Kward builds instructions for a turn, it combines roughly:
 
 1. Kward's built-in operating instructions.
 2. `PRINCIPLES.md`.
-3. selected persona.
-4. plugin prompt context.
-5. available skills list.
-6. workspace `AGENTS.md` hint or full content.
+3. memory context (when memory is enabled and relevant).
+4. selected persona.
+5. plugin prompt context.
+6. available skills list.
+7. workspace `AGENTS.md` hint or full content.
 
 If behavior seems surprising, inspect the assembled instructions:
 
 ```bash
 kward sysprompt
 ```
+
+Add `--raw` to print the raw system prompt content without section formatting, useful for piping to another tool:

data/doc/files.md

@@ -0,0 +1,100 @@
+# Project files
+
+Use `/files` when you want to browse the current workspace as a tree, open a file in Kward's integrated editor, or insert a file mention into the chat composer without typing the path by hand.
+
+It is built for the moment when you know the file is somewhere in the project, but you do not want to leave the TUI to run `find`, `ls`, or your external editor. The browser opens as an overlay inside the composer and keeps you in the same conversation.
+
+## Quick start
+
+From an interactive Kward session, run:
+
+```text
+/files
+```
+
+Kward opens the project file browser. Use the arrow keys to move through the tree, then press `Enter` on a file to open it in the integrated editor.
+
+When you quit the editor, Kward returns to the file browser at the same position so you can keep browsing nearby files.
+
+## What appears in the browser
+
+Inside a Git repository, `/files` uses Git's project view:
+
+```bash
+git ls-files --cached --others --exclude-standard
+```
+
+That means tracked files and normal untracked files appear, while ignored files stay out of the list.
+
+Outside Git, Kward scans the workspace directory and skips common noisy directories such as `.git`, `.yardoc`, `_yardoc`, `node_modules`, `rdoc`, `tmp`, and `vendor/bundle`.
+
+## Navigation
+
+| Key | Action |
+| --- | ------ |
+| `↑` / `↓` | Move the selection |
+| `Enter` | Open a file, or toggle a directory |
+| `←` | Collapse the selected directory, or jump to its parent |
+| `→` | Expand the selected directory |
+| `Tab` | Start or stop search |
+| `/` | Start search |
+| `Backspace` | Delete the last search character |
+| `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.
+
+## Search files
+
+Press `Tab` or `/` to search. While search is active, type part of a path and Kward filters the browser to matching files.
+
+For example:
+
+```text
+/files
+/agent
+```
+
+Use `↑` and `↓` to choose a result, then press `Enter` to open it. Press `Esc` to return to the tree view.
+
+## Mention a file in chat
+
+Press `@` on a selected file to insert it into the composer as an `@path` mention:
+
+```text
+@lib/kward/agent.rb
+```
+
+This is useful when you want Kward to talk about a specific file instead of opening it yourself. After inserting the mention, finish your prompt normally:
+
+```text
+@lib/kward/agent.rb Explain how tool execution works here.
+```
+
+## Open and edit files
+
+Press `Enter` on a file to open it in the integrated editor. The editor uses your configured editor mode: Modern, Emacs, or Vibe.
+
+A typical workflow:
+
+1. Run `/files`.
+2. Search for `README`, `agent`, or another path fragment.
+3. Press `Enter` on the file you want.
+4. Make the edit in the integrated editor.
+5. Save and quit.
+6. Continue browsing files, or press `Esc` to return to chat.
+
+See [Integrated Editor](editor.md) for editor modes, save/quit keys, search, selection, and configuration.
+
+## Remembered state
+
+Kward remembers the expanded folders and selected path for each workspace. The next time you open `/files` in the same project, it restores the browser close to where you left it.
+
+Search itself is temporary. Closing search returns to the normal tree, and closing the browser leaves your chat session intact.
+
+## Notes and limitations
+
+- `/files` is only available in the interactive prompt.
+- It opens files inside the current workspace.
+- It is a focused project browser, not a full file manager: it does not rename, move, copy, or delete files.
+- Ignored Git files are intentionally hidden when Git can provide the file list.

data/doc/getting-started.md

@@ -18,13 +18,21 @@ Install the gem:
 gem install kward
 ```
 
-Install the starter pack:
+Optionally install the starter pack:
 
 ```bash
 kward init
 ```
 
-The starter pack adds default prompts and a base `PRINCIPLES.md` under `~/.kward`. It does not overwrite existing files.
+The starter pack adds default prompts and a base `PRINCIPLES.md` under `~/.kward`. It does not overwrite existing files. It is safe to skip if you prefer to create your own instructions. It requires network access because it fetches the pack from GitHub.
+
+Verify your setup:
+
+```bash
+kward doctor
+```
+
+This checks your config, auth, writable directories, and workspace. Run `kward help` to see all available commands and examples.
 
 If you are working from a checkout instead:
 
@@ -49,6 +57,14 @@ Or from inside an interactive session:
 
 Kward supports OpenAI/ChatGPT, Anthropic Claude Pro/Max, OpenRouter, and experimental Copilot credentials. See [Authentication](authentication.md) when you need a specific provider.
 
+Confirm your credentials are saved:
+
+```bash
+kward auth status
+```
+
+If your provider offers multiple models, choose one inside Kward with `/model`.
+
 ## Start an interactive chat
 
 Run Kward from the project you want it to work on:
@@ -58,6 +74,12 @@ cd ~/code/my-project
 kward
 ```
 
+Or point Kward at a project without leaving your shell:
+
+```bash
+kward --working-directory ~/code/my-project
+```
+
 Ask something concrete:
 
 ```text
@@ -88,7 +110,7 @@ git diff | kward "Review this diff for bugs"
 
 One-shot prompts do not use Kward memory.
 
-## Useful first commands
+## Useful interactive commands
 
 Inside interactive Kward:
 
@@ -97,27 +119,12 @@ Inside interactive Kward:
 /model              choose a model
 /status             show session and context status
 /sessions           open the saved sessions picker
-/resume             alias for /sessions
 /rewind             revisit an earlier prompt
 /export notes.md    export the transcript
 /compact            summarize older context when a chat gets long
 /exit               leave Kward
 ```
 
-## Run from source
-
-```bash
-ruby lib/main.rb login
-ruby lib/main.rb
-ruby lib/main.rb "Explain this project"
-```
-
-You can also run:
-
-```bash
-exe/kward
-```
-
 ## Next steps
 
 - Read [Usage](usage.md) for day-to-day workflows.