kward 0.70.0 → 0.72.0

data/doc/session-management.md

@@ -0,0 +1,254 @@
+# Sessions
+
+Sessions are Kward's way of keeping real work alive across time. An interactive chat is not just a scrollback buffer: it is saved as a session with messages, tool calls, tool results, compaction checkpoints, branches, and enough metadata for Kward to resume the work later.
+
+Think of sessions as **context management**. They let you decide which conversation context Kward should use next.
+
+Think of rewinding and forking as **context time travel**. You can go back to an earlier prompt, try a different path, and keep both versions instead of losing the original work.
+
+## Where sessions live
+
+Interactive sessions are saved under:
+
+```text
+~/.kward/sessions/
+```
+
+Sessions are scoped to the workspace. If you run Kward in two different projects, each project has its own recent sessions.
+
+One-shot prompts such as `kward "Explain this project"` do not use session history. Start interactive Kward when you want ongoing context:
+
+```bash
+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:
+
+```text
+/rename oauth cleanup
+```
+
+`/rename` requires a name. Use `/name` without an argument to clear the current session name.
+
+Work normally:
+
+```text
+Find the OAuth callback code and explain how errors are handled.
+Add a focused test for the missing expired-token case.
+Run the related test file.
+```
+
+Leave when you are done for now:
+
+```text
+/exit
+```
+
+Later, resume the work:
+
+```text
+/sessions
+```
+
+The session picker shows recent sessions for the current workspace. Choose one to restore its transcript and continue with the same context.
+
+`/resume` is an alias for `/sessions`.
+
+## The sessions picker
+
+Open it with:
+
+```text
+/sessions
+```
+
+Inside the picker you can:
+
+| Key | Action |
+| --- | --- |
+| `Enter` | resume the highlighted session. |
+| `r` | rename the highlighted session. |
+| `c` | clone the highlighted session. |
+| `f` | fork the highlighted session from an earlier prompt. |
+| `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.
+
+From inside the active session:
+
+```text
+/clone
+```
+
+Or from `/sessions`, highlight a session and press `c`.
+
+A clone keeps the same conversation so far, but future messages are written to the new session file. The original session remains unchanged.
+
+Good uses:
+
+- try a risky refactor while preserving the safe version,
+- continue a review with a different strategy,
+- keep a checkpoint before asking Kward to make broad changes,
+- split one investigation into two independent paths.
+
+Mental model: **clone copies the whole timeline and starts a new future from now.**
+
+## Fork from an earlier prompt
+
+Fork when you want to go back to a specific user prompt and create a new independent session from before that prompt.
+
+From inside the active session:
+
+```text
+/fork
+```
+
+Or from `/sessions`, highlight a session and press `f`.
+
+Kward shows earlier user prompts. Choose the prompt where the new path should begin. Kward creates a new session containing the conversation before that prompt, then pre-fills the selected prompt so you can edit or resubmit it.
+
+Good uses:
+
+- you asked the wrong question and want to rephrase it,
+- Kward solved the right problem in the wrong style,
+- you want to try a smaller implementation after a larger one,
+- you want two alternative designs starting from the same point.
+
+Mental model: **fork cuts the timeline before a selected prompt and starts a new session there.**
+
+## Rewind within the current session
+
+Rewind is the fastest way to revisit an earlier prompt in the current session:
+
+```text
+/rewind
+```
+
+Kward shows previous user prompts from the active branch. Choose one, edit it if needed, and continue from that point. Future messages become a new branch in the same session history.
+
+Use rewind when you are still working inside one session and want to quickly try a different direction.
+
+Good uses:
+
+- undo a bad turn without throwing away the whole session,
+- retry an earlier request with tighter instructions,
+- branch from a known-good point after a tool result revealed something new,
+- jump back after realizing the current path is too broad.
+
+When available, `/rewind` also offers a return option so you can go back to where you were before rewinding.
+
+Mental model: **rewind moves the active point inside the same session timeline.**
+
+## Inspect the full tree
+
+Use `/tree` when you need the technical view of a session's history:
+
+```text
+/tree
+```
+
+The session tree includes more than the friendly `/rewind` list. It can show branches, assistant entries, tool calls, tool results, compaction checkpoints, and the current active leaf. Choose an entry to move the active session position there.
+
+Most users should reach for `/rewind` first. Use `/tree` when you need to understand or navigate the full branching structure.
+
+Good uses:
+
+- inspect where a branch split,
+- return to a specific tool-heavy checkpoint,
+- understand what happened after multiple rewinds,
+- navigate a long session with several alternative paths.
+
+Mental model: **`/tree` is the map; `/rewind` is the friendly time machine.**
+
+## Compact long sessions
+
+Long sessions can outgrow the model's useful context window. Use compacting to keep going:
+
+```text
+/compact
+```
+
+You can add focus instructions:
+
+```text
+/compact preserve the API docs navigation decisions and current failing checks
+```
+
+Compaction summarizes older conversation into a checkpoint and keeps recent context active. Historical messages remain in the session file for audit, export, and tree navigation, but the live model context becomes smaller.
+
+After compaction, Kward may need to re-read files before editing them again. That is normal: read-before-edit guardrails apply to the current live context.
+
+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:
+
+```text
+/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
+
+- Rename sessions early when work becomes important.
+- Clone before risky or broad changes.
+- Fork when the earlier prompt was the wrong starting point.
+- Rewind when you want a fast alternate attempt inside the same session.
+- Use `/tree` only when the friendly commands are not enough.
+- 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`.