kward 0.71.0 → 0.72.0

data/doc/session-management.md

@@ -23,6 +23,8 @@ cd ~/code/project
 kward
 ```
 
+To automatically resume the last active session for the current workspace on startup, enable `sessions.auto_resume` in your config — see [Configuration](configuration.md). When auto-resume is off (the default), Kward starts fresh each time and you can resume earlier work with `/sessions`.
+
 ## A normal session workflow
 
 Start a chat and give it a useful name:
@@ -31,6 +33,8 @@ Start a chat and give it a useful name:
 /rename oauth cleanup
 ```
 
+`/rename` requires a name. Use `/name` without an argument to clear the current session name.
+
 Work normally:
 
 ```text
@@ -71,10 +75,12 @@ Inside the picker you can:
 | `r` | rename the highlighted session. |
 | `c` | clone the highlighted session. |
 | `f` | fork the highlighted session from an earlier prompt. |
-| `d d` | delete the highlighted session after confirmation. |
+| `d` | start deleting the highlighted session. Press `d` again to confirm, or `Esc` to cancel. |
 
 Use names generously. A session named `oauth cleanup` or `release checklist` is much easier to find later than a timestamp.
 
+Deleted sessions are moved to your OS trash or recycle bin when a supported platform tool is available (Finder on macOS, `gio trash` or `trash-put` on Linux, Recycle Bin on Windows). If no trash tool is found, the session file is permanently deleted. You can recover accidentally deleted sessions from your trash.
+
 ## Clone a session
 
 Clone when you want an exact copy of the current conversation and then continue in a separate branch.
@@ -185,6 +191,17 @@ After compaction, Kward may need to re-read files before editing them again. Tha
 
 Compaction is also context management. It trades detailed old conversation for a concise working summary so Kward can spend tokens on the next task.
 
+## Copy session text to the clipboard
+
+Use `/copy` to copy conversation text without writing a file:
+
+```text
+/copy last         # copy the latest assistant response
+/copy transcript   # copy the full transcript as Markdown
+```
+
+With no argument, `/copy` defaults to `last`. Copying uses the terminal clipboard (OSC 52) when supported.
+
 ## Export a session
 
 Export when you want notes outside Kward:
@@ -193,20 +210,35 @@ Export when you want notes outside Kward:
 /export notes.md
 ```
 
+With no argument, `/export` writes a Markdown file beside the session file, derived from the session name with a `.md` extension.
+
 Exports are useful for handoff notes, review summaries, release records, or saving a human-readable transcript before deleting old sessions.
 
+## Check session status
+
+Use `/status` to see the active session name, file path, and auto-compaction reserve at a glance:
+
+```text
+/status
+```
+
+This is useful when you want to confirm which session you are in or check whether auto-compaction is active.
+
 ## Which command should I use?
 
 | Need | Use |
 | --- | --- |
 | Continue earlier work | `/sessions` or `/resume` |
 | Give the current session a better name | `/rename <name>` |
+| Clear the current session name | `/name` |
 | Keep the current state but try another future | `/clone` |
 | Start a separate session from before an earlier prompt | `/fork` |
 | Quickly retry an earlier prompt in this session | `/rewind` |
 | Inspect or navigate the full branch structure | `/tree` |
 | Reduce old context so a long session can continue | `/compact` |
+| Copy the last response or full transcript to clipboard | `/copy [last\|transcript]` |
 | Save a readable transcript | `/export <path>` |
+| Check the active session and compaction status | `/status` |
 
 ## Practical habits
 
@@ -218,3 +250,5 @@ Exports are useful for handoff notes, review summaries, release records, or savi
 - Compact when the conversation gets long, but keep the focus instruction specific.
 
 Sessions make Kward less like a single chat box and more like a workspace timeline. You can preserve context, branch it, compress it, and return to it when the work needs another pass.
+
+RPC clients have their own session API with equivalent create, resume, list, clone, fork, rename, and compaction methods. See the [RPC documentation](rpc.md) for details.

data/doc/shell.md

@@ -0,0 +1,286 @@
+# Embedded shell
+
+Use `/shell` when you want to run a sequence of local commands without leaving Kward's interactive TUI.
+
+`/shell` opens **ekwsh**, the embedded Kward shell. It is not a full terminal emulator. Kward keeps ownership of the composer, transcript, tab bar, and keybindings while each command runs through your normal shell one command at a time.
+
+This makes it good for:
+
+- checking Git state,
+- running focused tests,
+- inspecting files with command-line tools,
+- using project aliases,
+- keeping command output visible beside the current Kward session.
+
+It is not intended for full-screen interactive programs such as `vim`, `less`, `top`, `ssh`, or REPLs.
+
+## Start shell mode
+
+Inside interactive Kward:
+
+```text
+/shell
+```
+
+The composer prompt changes to show the shell's current directory:
+
+```text
+Shell ~/code/project $
+```
+
+Type commands as you would in a normal shell:
+
+```sh
+git status --short
+bundle exec ruby -Itest test/test_ekwsh.rb
+cd lib/kward
+pwd
+```
+
+Leave shell mode with:
+
+```sh
+exit
+```
+
+or press Ctrl+D on an empty shell prompt.
+
+## How commands run
+
+`ekwsh` runs each command through your configured shell using the shell's `-c` mode. It uses `$SHELL` when set, otherwise `/bin/sh`. The shell is intentionally not started as a login shell so Kward-managed environment values, such as configured PATH entries, are not overwritten by login startup files.
+
+The current directory and exported environment are tracked by Kward between commands, so this works as expected:
+
+```sh
+cd test
+pwd
+export FOO=bar
+printf '%s\n' "$FOO"
+unset FOO
+```
+
+`cd` changes only the embedded shell's current directory. It does not change Kward's workspace root or the process directory used by the rest of Kward.
+
+Shell output is shown in the transcript area, but it is not added to the AI conversation history.
+
+## Built-ins
+
+`ekwsh` handles a small set of built-ins itself:
+
+| Built-in | What it does |
+| --- | --- |
+| `cd [dir]` | Change the embedded shell directory. Supports `cd`, `cd -`, and normal relative paths. |
+| `pwd` | Print the embedded shell directory. |
+| `export KEY=value` | Set an environment variable for later commands. |
+| `unset KEY` | Remove an environment variable from later commands. |
+| `alias [name]` | List configured aliases, or show specific configured aliases. |
+| `clear` | Clear Kward's visible transcript. |
+| `exit` / `logout` | Leave shell mode. |
+
+Built-ins take precedence over aliases and executables.
+
+## Tabs
+
+Shell mode is tracked per Kward tab.
+
+If you enter `/shell` in one tab, switch to another tab, and later switch back, that tab is still in shell mode. Its shell state and transcript snapshot are restored until you leave shell mode in that tab.
+
+This means each tab can have its own:
+
+- shell current directory,
+- exported environment,
+- visible shell transcript,
+- command prompt state.
+
+Kward's normal tab-switching shortcuts continue to work in shell mode.
+
+## Tab completion
+
+Plain Tab completes shell input while in `ekwsh`.
+
+Completion includes:
+
+- built-in command names,
+- configured aliases,
+- executable names from `$PATH`,
+- file paths from the shell's current directory.
+
+Examples:
+
+```sh
+pw<Tab>          # pwd
+ll<Tab>          # configured alias, if present
+cat lib/kw<Tab>  # path completion
+cd doc<Tab>      # directory-only completion for cd
+```
+
+Directory completions get a trailing slash. File and command completions get a trailing space when there is a single match.
+
+Paths with spaces are shell-escaped:
+
+```sh
+cat my<Tab>
+# => cat my\ file.txt
+```
+
+If there are multiple candidates, Kward applies any common prefix. When there is no longer common prefix, it prints a compact candidate list in the transcript.
+
+## Colors and ANSI output
+
+`ekwsh` preserves safe ANSI SGR color/style sequences in command output, such as:
+
+- colors,
+- bold,
+- dim,
+- italic,
+- underline,
+- 256-color and truecolor SGR sequences.
+
+It strips terminal-control sequences that could corrupt Kward's TUI, such as cursor movement, clear-screen controls, OSC title changes, and alternate-screen controls.
+
+When rbenv is available, `ekwsh` also prepends the rbenv shims and bin directories to PATH and sets `RBENV_ROOT` when it was missing. This lets commands such as `ruby`, `bundle`, and `./exe/kward` use the same Ruby selected by rbenv without requiring `rbenv init` support in `ekwsh`.
+
+By default, `ekwsh` sets conservative color-friendly environment values:
+
+```sh
+CLICOLOR=1
+COLORTERM=truecolor
+TERM=xterm-256color  # only when TERM is missing or dumb
+```
+
+It does **not** force color by default. If a tool does not emit color because stdout is not a TTY, use a command-specific flag or configure forced color yourself:
+
+```sh
+git diff --color=always
+grep --color=always TODO lib/**/*.rb
+```
+
+## Global ekwsh config
+
+You can configure environment variables and aliases in:
+
+```text
+~/.kward/ekwsh.yml
+```
+
+If `KWARD_CONFIG_PATH` points to another config file, `ekwsh.yml` is read from that file's directory instead.
+
+Example:
+
+```yaml
+env:
+  FORCE_COLOR: "1"
+  CLICOLOR_FORCE: "1"
+  RAILS_ENV: "test"
+
+aliases:
+  ll: "ls -la"
+  gs: "git status --short"
+  gd: "git diff --color=always"
+  be: "bundle exec"
+  t: "bundle exec ruby -Itest"
+```
+
+### Environment variables
+
+`env` values are applied when shell mode starts, after Kward's conservative color defaults.
+
+Keys must look like environment variable names:
+
+```text
+A_Z, digits after the first character, and underscores
+```
+
+Invalid keys are ignored. Values are converted to strings. Nil values are ignored.
+
+Configured env is useful for local preferences such as:
+
+```yaml
+env:
+  FORCE_COLOR: "1"
+  BUNDLE_WITHOUT: "production"
+  RAILS_ENV: "test"
+```
+
+For one shell session, you can also use the built-in `export` command:
+
+```sh
+export FORCE_COLOR=1
+```
+
+### Aliases
+
+Aliases expand the first word of a command once.
+
+With this config:
+
+```yaml
+aliases:
+  ll: "ls -la"
+  t: "bundle exec ruby -Itest"
+```
+
+these commands run as:
+
+```sh
+ll lib
+# runs: ls -la lib
+
+t test/test_ekwsh.rb
+# runs: bundle exec ruby -Itest test/test_ekwsh.rb
+```
+
+Aliases are intentionally simple:
+
+- only the first word is expanded,
+- aliases do not recursively expand,
+- built-ins win over alias names,
+- aliases are not shell functions,
+- aliases are global for now.
+
+List configured aliases inside `ekwsh`:
+
+```sh
+alias
+```
+
+Show specific aliases:
+
+```sh
+alias ll gs
+```
+
+Aliases also appear in command-name Tab completion.
+
+## `/shell` versus `!command`
+
+Kward has two ways to run local commands yourself:
+
+```text
+!git status --short
+```
+
+runs one command directly from the normal composer.
+
+```text
+/shell
+```
+
+starts an embedded command mode for several commands with persistent shell state, aliases, completion, and per-tab shell context.
+
+Use `!command` for one-offs. Use `/shell` when you expect to run several commands in a row.
+
+## Limitations
+
+`ekwsh` is deliberately not a full interactive terminal.
+
+Current limitations:
+
+- no job control,
+- no persistent shell functions,
+- no shell startup file sourcing,
+- no full-screen terminal applications,
+- no native readline from your login shell,
+- command output is captured through pipes, not a PTY.
+
+Some tools only emit color or progress UI when stdout is a real terminal. Prefer explicit command flags such as `--color=always` when needed.

data/doc/tabs.md

@@ -0,0 +1,122 @@
+# Tabs
+
+Use tabs when you want more than one Kward conversation open in the same interactive terminal session.
+
+Each tab has its own session-backed conversation, transcript, composer state, and running agent turn. That makes tabs useful for splitting work without losing your place: one tab can investigate a bug, another can draft docs, and a third can wait on a long-running answer.
+
+## Quick start
+
+Open a new tab:
+
+```text
+/tab new
+```
+
+Switch to tab 1, 2, or another visible tab number:
+
+```text
+/tab 1
+/tab 2
+```
+
+Rename the current tab:
+
+```text
+/tab name Docs
+```
+
+Close the current tab:
+
+```text
+/tab close
+```
+
+The tab bar appears at the bottom of the composer. The active tab is framed, and each tab label starts with its number.
+
+## Common workflow
+
+A typical multi-tab flow looks like this:
+
+1. Start Kward interactively in your project.
+2. Use the main tab for the current implementation task.
+3. Run `/tab new` to open a clean conversation.
+4. Ask a separate question, such as:
+
+   ```text
+   Review the current API docs structure and suggest where a Tabs guide belongs.
+   ```
+
+5. Switch back with `/tab 1` while the other answer runs.
+6. Return to the second tab with `/tab 2` when it is ready.
+
+Tabs keep the conversations separate, so context from one tab does not automatically spill into another.
+
+## Slash commands
+
+| Command | Action |
+| ------- | ------ |
+| `/tab new` | Open a new tab with a fresh conversation |
+| `/tab 1` through `/tab 9` | Switch to a numbered tab |
+| `/tab close` | Close the current tab |
+| `/tab name <label>` | Rename the current tab |
+| `/tab rename <label>` | Same as `/tab name` |
+| `/tab move left` | Move the current tab one slot left |
+| `/tab move right` | Move the current tab one slot right |
+| `/tab move <number>` | Move the current tab to a numbered position |
+
+If you close the only remaining tab, Kward exits the interactive session. A running tab cannot be closed until it finishes or is cancelled.
+
+## Keyboard shortcuts
+
+Kward supports two tab shortcut families. You can choose one in `/settings` or with `composer.tab_keybindings` in `config.json`.
+
+`Ctrl+Tab` and `Ctrl+Shift+Tab` switch tabs when your terminal sends those keys:
+
+| Key | Action |
+| --- | ------ |
+| `Ctrl+Tab` | Next tab |
+| `Ctrl+Shift+Tab` | Previous tab |
+
+When `composer.tab_keybindings` is `ctrl`:
+
+| Key | Action |
+| --- | ------ |
+| `Ctrl+T` | New tab |
+| `Ctrl+W` | Close tab |
+| `Ctrl+1` through `Ctrl+9` | Switch to a numbered tab, if your terminal reports modified number keys |
+
+When `composer.tab_keybindings` is `alt`:
+
+| Key | Action |
+| --- | ------ |
+| `Alt+T` | New tab |
+| `Alt+Right` | Next tab |
+| `Alt+Left` | Previous tab |
+| `Alt+1` through `Alt+9` | Switch to a numbered tab |
+
+`auto` is the default. On macOS it prefers the Ctrl family; elsewhere it prefers the Alt family, because many terminals reserve or swallow Ctrl-based tab shortcuts.
+
+## Running work in another tab
+
+A tab can keep running while you switch away. Kward marks tab labels by status:
+
+- Yellow: running or queued.
+- Green: waiting for your answer to an interactive question, or unread output is ready in a background tab.
+- Red: failed or cancelled.
+
+If you type into a busy tab, Kward queues normal prompts until the current turn finishes. Some running turns also support steering input, so short follow-up guidance may be delivered to the active run instead of waiting for the next turn.
+
+Slash commands such as `/tab` still work while a tab is busy, so you can switch tabs, open a new tab, or move around without waiting.
+
+## Persistence
+
+Tabs are backed by normal Kward sessions. Kward stores the open tab list, labels, and active tab per workspace, then restores them the next time you start interactive Kward in that workspace.
+
+The tab layout is stored in Kward's config directory under `tabs/`. Session transcripts stay in the normal sessions directory. See [Sessions](session-management.md) for session naming, resuming, forking, exporting, and cleanup.
+
+## Notes and limitations
+
+- Tabs are available in the interactive TUI.
+- Each tab has its own conversation context; use explicit file mentions or summaries when you want to carry information between tabs.
+- A running tab cannot be closed until it is idle.
+- Terminal support for modified keys varies. If shortcuts do not arrive, use the `/tab` slash commands or switch `composer.tab_keybindings` between `ctrl` and `alt`.

data/doc/troubleshooting.md

@@ -1,6 +1,74 @@
 # Troubleshooting
 
-This page collects environment-specific issues that can affect Kward but are not caused by Kward itself.
+This page covers common issues and how to diagnose them. When something is not working, start with `kward doctor` — it checks your config, directories, workspace, model, and auth status in one pass.
+
+## Run `kward doctor` first
+
+`kward doctor` reports the state of your local setup without printing secrets:
+
+```bash
+kward doctor
+```
+
+It checks that your config file is readable and valid JSON, that the config and session directories are writable, that the workspace exists, which provider and model are active, and which credentials are configured. Use it as the first diagnostic step for any unexpected behavior.
+
+`kward auth status` gives a focused view of credentials only, also without printing secrets:
+
+```bash
+kward auth status
+```
+
+## Authentication errors and token expiration
+
+OAuth tokens expire. Kward refreshes access tokens automatically when a refresh token is available, but if the refresh token is missing or expired, requests fail with a provider-specific error:
+
+- OpenAI: `No OpenAI OAuth login found.`
+- Anthropic: `No Anthropic OAuth login found.`
+- Copilot: `No GitHub Copilot OAuth login found.`
+- OpenRouter: `No OpenRouter API key found.`
+
+Re-run login for the affected provider:
+
+```bash
+kward login              # OpenAI
+kward login anthropic    # Anthropic
+kward login openrouter   # OpenRouter
+kward login github       # Copilot
+```
+
+Or use `/login` inside Kward. See [Authentication](authentication.md) for the full provider flow.
+
+## Provider usage limits and billing errors
+
+Kward detects non-retryable quota and billing errors from providers, including messages such as `quota exceeded`, `insufficient_quota`, `out of credits`, and `monthly usage limit reached`. These are not retried — the request fails immediately.
+
+If you see one of these errors:
+
+- Check your provider dashboard for usage or billing limits.
+- For OpenRouter, verify your account balance at [openrouter.ai](https://openrouter.ai).
+- For OpenAI, check your organization's usage and billing settings.
+- Switch to a different provider or model with `/model` if you have alternative credentials.
+
+## Rate limiting and transient server errors
+
+Kward automatically retries transient failures: HTTP 429 (rate limit) and 5xx server errors. It makes up to 3 attempts total with short backoff delays. Network errors such as timeouts and connection resets are also retried.
+
+If requests fail after retries, you will see a message like `request failed after 3 attempts`. Common causes:
+
+- You are hitting the provider's rate limit. Wait a moment and retry, or reduce request frequency.
+- The provider is experiencing an outage. Check the provider's status page.
+- Your session context is very large, making each request slower and more likely to time out. Use `/compact` to reduce context.
+
+## Context overflow errors
+
+When a conversation exceeds the model's context window, the provider returns an error such as `prompt is too long` or `exceeds the context window`. Kward detects these and does not retry them.
+
+To resolve context overflow:
+
+- Run `/compact` to summarize and reduce the conversation context.
+- Start a new session with `/new` if the current one is no longer needed.
+- Enable auto-compaction if it is off — see [Configuration](configuration.md).
+- Switch to a model with a larger context window via `/model`.
 
 ## `gem install kward` succeeds, but `kward` is not found with rbenv
 
@@ -53,3 +121,11 @@ kward --help
 ```
 
 This stale `.rbenv-shim` file can be left behind by an interrupted `rbenv rehash` or gem installation. It is local rbenv state, not a Kward packaging issue.
+
+## Still stuck?
+
+If none of the above resolves your issue:
+
+1. Run `kward doctor` and `kward auth status` to gather diagnostics.
+2. Check the [Authentication](authentication.md) and [Configuration](configuration.md) docs.
+3. Search or report issues at the [Kward issue tracker](https://github.com/kaiwood/kward/issues).