kward 0.71.0 → 0.72.0

data/doc/git.md

@@ -0,0 +1,122 @@
+# Git
+
+Kward has a small interactive Git workflow built into the terminal UI. It lets you review the current working tree, inspect per-file diffs, stage or unstage files, write a commit message, and create a commit without leaving the chat.
+
+Use it when you have just finished a change with Kward and want one last pass before committing. It is intentionally focused: it is not a full Git client, just the common review-and-commit loop.
+
+## Quick start
+
+From an interactive Kward session inside a Git repository, run:
+
+```text
+/git
+```
+
+Kward opens a Git overlay showing the same short status style you would see from:
+
+```bash
+git status --short --untracked-files=normal
+```
+
+Example:
+
+```text
+ M lib/kward/cli.rb
+A  doc/git.md
+?? tmp/example.txt
+```
+
+Use the overlay to review and shape the commit:
+
+| Key | Action |
+| --- | --- |
+| `↑` / `↓` | Move between changed files. |
+| `Enter` | Open the selected file in the diff viewer. |
+| `s` | Stage or unstage the selected file. |
+| `Tab` | Switch to commit-message entry. |
+| `Esc` | Cancel and return to chat. |
+
+When you press `Tab`, the prompt changes from `Git>` to `Commit>`. Type the commit message and press `Enter` to commit. Press `Tab` again to return to the file list without losing the draft message.
+
+Use `Shift+Enter` to insert a newline if you need a multi-line commit message.
+
+## Review changes with the diff viewer
+
+Highlight a file in the `/git` overlay and press `Enter`.
+
+Kward opens a read-only diff viewer in the composer area. It shows classic Git diff output with added and removed lines colorized when terminal color is enabled.
+
+Useful keys in the diff viewer:
+
+| Key | Action |
+| --- | --- |
+| `↑` / `↓` | Move through the diff one line at a time. |
+| `Page Up` / `Page Down` | Scroll by a page. |
+| `Home` / `End` | Move within the current line. |
+| `/` or `Ctrl+F` | Search within the diff. |
+| `Enter` | Confirm the current search. |
+| `Esc` | Cancel search, or close the diff viewer. |
+| `Ctrl+Q` | Close the diff viewer. |
+
+After you close the viewer, Kward returns to the Git overlay with the file list refreshed.
+
+The diff viewer is read-only. It is meant for checking what changed, not editing. If you spot something you want to fix, close the viewer, return to chat, and ask Kward to make the change or open the file with the built-in editor using `$path/to/file` (see [Configuration](configuration.md) for editor modes and settings).
+
+## Example workflow
+
+A typical end-to-end flow looks like this:
+
+```text
+/git
+```
+
+1. Use `↑` and `↓` to scan the changed files.
+2. Press `Enter` on a file that looks risky.
+3. Search the diff with `/` if you need to find a symbol or error message.
+4. Press `Esc` to close the diff viewer.
+5. Press `s` on files you want in this commit.
+6. Press `Tab` to write the commit message.
+7. Press `Enter` to commit.
+
+If no files are staged when you submit the commit message, Kward stages all current workspace changes before committing. If at least one file is already staged, Kward commits only the staged changes.
+
+That means you can use `/git` in two ways:
+
+- **Simple commit:** do not stage anything manually; write a message and Kward commits all current changes.
+- **Selective commit:** stage specific files with `s`; Kward commits only what is staged.
+
+## How staged changes work
+
+The `s` key toggles the selected file:
+
+- unstaged files are staged with `git add -- <path>`
+- staged files are unstaged with `git restore --staged -- <path>`
+
+The status list refreshes after each toggle, so you can see what will be included before committing.
+
+For untracked files, the diff viewer shows the file as a new file with every line added. That makes it possible to review new files before staging them.
+
+Renamed or copied files (status codes `R` and `C`) appear in the list with their destination path after the `->` arrow, and the diff viewer shows the destination file.
+
+## Git branch indicator
+
+In the interactive composer status line, Kward also shows the current Git branch or short commit SHA when the workspace is inside a repository. The indicator turns yellow when the working tree has uncommitted changes.
+
+This is just a lightweight status hint. Use `/git` when you want to review or commit the changes.
+
+If the working tree is clean when you run `/git`, the overlay shows `No uncommitted changes.` and there is nothing to stage or commit.
+
+## Notes and limitations
+
+- `/git` is available in the interactive terminal UI, not in one-shot prompts or the RPC backend.
+- The command must run inside a Git repository.
+- The diff viewer compares tracked files against `HEAD` with `git diff HEAD -- <path>`.
+- The commit command uses `git commit -m <message>`.
+- Kward does not push, pull, merge, rebase, amend, or manage branches from this overlay.
+- Commit success still depends on your local Git configuration, hooks, and repository state.
+
+For AI-assisted review without committing, you can still pipe a diff into a one-shot prompt:
+
+```bash
+git diff | kward "Review this diff"
+```

data/doc/memory.md

@@ -51,7 +51,7 @@ Add a workspace-specific hint when it only applies to the current project:
 /memory add "This workspace uses Minitest."
 ```
 
-Use global core memory sparingly. It has higher priority than workspace memory.
+Use global core memory sparingly. It applies everywhere, so it has a wider blast radius than workspace memory.
 
 ## Let Kward summarize useful memories
 
@@ -61,6 +61,12 @@ Auto-summary is off by default. Enable it if you want Kward to learn recurring p
 /memory auto-summary enable
 ```
 
+Disable it again:
+
+```text
+/memory auto-summary disable
+```
+
 This only runs when memory is enabled. It does not run for one-shot prompts.
 
 You can also ask Kward to summarize the current session manually:
@@ -69,10 +75,14 @@ You can also ask Kward to summarize the current session manually:
 /memory summarize
 ```
 
+`/memory learn` is an alias for `/memory summarize`.
+
 Kward is conservative about inferred memories and refuses to automatically persist emotional, intimate, romantic, or dependency-forming memories.
 
 ## Inspect what Kward remembers
 
+Running `/memory` with no argument prints a summary of all available subcommands.
+
 List active memories for the current workspace:
 
 ```text
@@ -108,6 +118,12 @@ Promote a workspace hint when it should become a stronger rule:
 /memory promote soft_001
 ```
 
+`/memory promote` also works on workspace core memories, promoting them to global scope so they apply everywhere:
+
+```text
+/memory promote core_003
+```
+
 Relax a global memory back to the current workspace:
 
 ```text
@@ -124,7 +140,7 @@ Kward uses three layers:
 
 Core memories override soft memories. Soft memories are treated as hints, not facts.
 
-Kward does not inject every stored memory into every prompt. It retrieves a bounded set that appears relevant to the current turn.
+Kward does not inject every stored memory into every prompt. It retrieves a bounded set that appears relevant to the current turn: up to 6 core and 6 soft memories. Core memories are included by scope match (global and current workspace). Soft memories are scored by text and tag overlap with the current input, confidence level, and expiry, and only the top-scoring ones are injected.
 
 ## Where memory is stored
 
@@ -136,12 +152,16 @@ Default files:
 ~/.kward/memory/events.jsonl
 ```
 
+The memory directory is created with mode `0700` and each file with mode `0600`.
+
 `events.jsonl` stores a small audit trail for actions such as enable, add, retrieve, summarize, promote, and forget.
 
 When a soft memory is forgotten, its text is replaced with `[forgotten]` while inactive audit metadata can remain.
 
-If `KWARD_CONFIG_PATH` is set, memory files live beside that config file instead of under `~/.kward`.
+Soft memories have a time-to-live of 60 days by default. Each time a soft memory is retrieved, its `last_seen_at` timestamp is updated and its hit count is incremented. If a soft memory is not retrieved within its TTL window, it expires and is no longer injected into prompts. Forgotten and expired memories remain in the file for audit but are not shown in `/memory list`.
+
+If `KWARD_CONFIG_PATH` is set, memory files live beside that config file instead of under `~/.kward`. See [Configuration](configuration.md) for the config-file representation.
 
 ## RPC support
 
-The experimental RPC backend exposes memory methods such as `memory/list`, `memory/add`, `memory/forget`, `memory/why`, and `memory/summarize`. See [RPC protocol](rpc.md) if you are building a client.
+The experimental RPC backend exposes memory methods including `memory/status`, `memory/enable`, `memory/disable`, `memory/autoSummary/enable`, `memory/autoSummary/disable`, `memory/list`, `memory/add`, `memory/addCore`, `memory/forget`, `memory/promote`, `memory/relax`, `memory/inspect`, `memory/why`, and `memory/summarize`. See the [RPC documentation](rpc.md) for the full protocol.

data/doc/personas.md

@@ -108,7 +108,7 @@ Assistant> I found the failing test.
 Samantha> I found the failing test.
 ```
 
-This is not only decorative. It is the name Kward uses when rendering assistant messages in the terminal transcript. If no active persona label is available, Kward uses `Assistant>`.
+This is not only decorative. It is the name Kward uses when rendering assistant messages in the terminal transcript. If the active persona has no `label` field, Kward uses `Assistant>` instead — the character `key` is not used as a fallback label. If no persona is active at all, Kward also uses `Assistant>`.
 
 For RPC clients, the active label is also exposed as `activePersonaLabel` so a UI can show the same speaker identity.
 
@@ -163,6 +163,19 @@ You can also define characters as a map:
 }
 ```
 
+In the map form, the key is the character key. You can also use a bare string as the definition, which becomes the instruction; the transcript label then falls back to `Assistant>` unless you use a hash with `label`:
+
+```json
+{
+  "personas": {
+    "characters": {
+      "duck": "You are a patient rubber duck."
+    },
+    "default": "duck"
+  }
+}
+```
+
 The array form is easier to read and is recommended for new configs.
 
 `personas.crew` is accepted as a legacy alias for `personas.characters`.
@@ -179,13 +192,25 @@ Set `personas.default` to the character key you want by default:
 }
 ```
 
+`personas.default` can also be a raw instruction string instead of a character key. When the value does not match any character, Kward uses it directly as the persona instruction:
+
+```json
+{
+  "personas": {
+    "default": "You are a calm assistant."
+  }
+}
+```
+
+This is a quick way to set a persona without defining a `characters` entry.
+
 You can also change the default from interactive Kward:
 
 ```text
 /settings
 ```
 
-Then choose the personalization/default persona option.
+Choose **Personalization**, then **Default persona** to pick from your configured characters. The same menu also offers **Active instructions summary**, which shows the active persona label and whether `PRINCIPLES.md` and workspace `AGENTS.md` are present.
 
 ## Workspace-specific personas
 
@@ -268,7 +293,7 @@ anthropic_reasoning_effort
 copilot_reasoning_effort
 ```
 
-Personas do not choose the model and do not set reasoning effort by themselves. What personas can do is add extra character direction based on the active reasoning effort.
+Personas do not choose the model and do not set reasoning effort by themselves. What personas can do is add extra character direction based on the active reasoning effort. See [Configuration](configuration.md) for the full provider, model, and reasoning config reference.
 
 In plain English:
 
@@ -324,7 +349,7 @@ Example:
 }
 ```
 
-If no bucket matches, no time-of-day modifier is added.
+If no bucket matches, no time-of-day modifier is added. Hours 12:00-20:59 (noon through early evening) have no bucket, so no time-of-day modifier is applied during that window.
 
 ## Weekday modifiers
 
@@ -404,7 +429,11 @@ From the shell:
 kward sysprompt
 ```
 
-`kward sysprompt` shows the assembled prompt sections, including the persona text that would be used for a new conversation.
+`kward sysprompt` shows the assembled prompt sections, including the persona text that would be used for a new conversation. Add `--raw` to print the raw system prompt content without section formatting, which is useful for scripting or piping to another tool:
+
+```bash
+kward sysprompt --raw
+```
 
 ## When to use personas
 

data/doc/plugins.md

@@ -21,6 +21,8 @@ Plugins run inside the Kward process with your user permissions. Install only pl
 | Repository rules | `AGENTS.md` |
 | Local Ruby code or integration | plugin |
 
+See [Extensibility](extensibility.md) for the full overview of Kward's extension points and prompt assembly order.
+
 ## Where plugins live
 
 Kward loads top-level Ruby files from:
@@ -56,6 +58,8 @@ Start Kward and run:
 /hello World
 ```
 
+When developing plugins, use `/reload` inside Kward to reload all plugin files without restarting. This picks up changes to existing plugins and registers new ones, then rebuilds the system message.
+
 ## Add a slash command
 
 Use plugin commands for local actions that should not call the model.
@@ -77,7 +81,7 @@ A plugin command cannot replace a built-in command or prompt-template command.
 
 Prompt context is short text injected into future model requests.
 
-Use it for stable facts the model should know, not for large files or secrets.
+Use it for stable facts the model should know, not for large files or secrets. The block should return a string (injected into the system prompt) or `nil` (skipped). The example below uses Ruby's `next` to return `nil` early when the condition does not match.
 
 ```ruby
 Kward.plugin do |plugin|
@@ -109,6 +113,71 @@ end
 
 Only one footer is active. If multiple plugins register footers, the later one replaces the earlier one and Kward prints a warning.
 
+## Add an interactive command
+
+Interactive commands take over the composer region with a Kward-driven render and
+input loop. The plugin receives a controller object with a canvas API for
+drawing colored cells and reading keys. This is useful for games, dashboards,
+viewers, and similar full-region interactive experiences.
+
+`interactive_command` accepts `description:` and `argument_hint:` keyword arguments, which appear in the slash command list and completion overlay just like regular plugin commands. `rows:` sets the fixed canvas height (minimum 1), and `fps:` sets the target frame rate (1–120, default 30).
+
+```ruby
+Kward.plugin do |plugin|
+  plugin.interactive_command "demo", rows: 10, fps: 30, description: "Canvas demo" do |ui, ctx|
+    x = 0
+    ui.on_tick do |ui|
+      ui.clear_frame
+      ui.put(0, x, "X", :red)
+      x = (x + 1) % ui.width
+      key = ui.poll_key
+      return :exit if key == :ctrl_c || key == "q"
+    end
+  end
+end
+```
+
+Run it with `/demo` from the interactive TUI. The canvas renders inside the
+composer area for the specified number of rows. The transcript above stays
+intact.
+
+### Controller API
+
+The `ui` controller object passed to the handler block exposes:
+
+| Method | Description |
+| --- | --- |
+| `put(row, col, char, *colors)` | Place a character at a zero-based position with optional ANSI color styles |
+| `clear_frame` | Reset all canvas cells to blank |
+| `render` | Mark the canvas as ready for Kward to draw |
+| `poll_key` | Return the next pending key (non-blocking, nil if none) |
+| `exit` | Request that the interactive loop exit |
+| `on_tick { \|ui\| }` | Register a tick callback invoked each frame at the configured fps |
+| `width` | Canvas width in terminal columns |
+| `height` | Canvas height in terminal rows |
+| `fps` | Target frame rate |
+
+Keys are returned as symbols (`:left`, `:right`, `:up`, `:down`, `:return`,
+`:backspace`, `:space`, `:pageup`, `:pagedown`) or raw strings for keys
+without a named mapping. Ctrl+C always exits the loop immediately.
+
+The tick callback runs at the configured frame rate (1–120 fps, default 30).
+Returning `:exit` from the tick callback ends the loop, same as calling
+`ui.exit`.
+
+### Lifecycle
+
+- The composer state is saved on entry and fully restored on exit (input text,
+  cursor, and transcript viewport).
+- Interactive mode is a distinct state from the busy-input spinner lifecycle —
+  no spinner or busy chrome is shown.
+- Ctrl+C, the plugin calling `exit`, or the tick callback returning `:exit`
+  all exit cleanly and restore the prior composer state.
+- Resize during interactive mode forces a clean exit and restore.
+
+Interactive commands require the TUI prompt interface. They are not available
+in piped/non-interactive mode or through RPC.
+
 ## Observe transcript events
 
 Use transcript events when you need to log or react to live activity:
@@ -151,6 +220,8 @@ Handlers receive a `ctx` object. Common methods:
 - `ctx.session_path`
 - `ctx.refresh_system_message!`
 
+These methods are available in all handler types: commands, footers, prompt context renderers, and transcript event observers. `ctx.say` outputs to the active frontend (terminal or RPC) wherever it is called.
+
 The transcript is read-only. Use context methods instead of mutating Kward internals.
 
 ## RPC support

data/doc/releasing.md

@@ -1,16 +1,24 @@
 # Releasing Kward
 
+Kward requires Ruby >= 3.2 (`spec.required_ruby_version` in `kward.gemspec`). If you develop with a newer Ruby, verify tests pass against the minimum supported version before releasing.
+
 Release steps before publishing:
 
-1. Update `CHANGELOG.md` for the version.
+1. Update `CHANGELOG.md` for the version. Move `[Unreleased]` entries under a new version heading.
 2. Update `Kward::VERSION` in `lib/kward/version.rb`.
-3. Run the test suite:
+3. Run the full test suite:
 
    ```bash
    bundle exec rake test
    ```
 
-4. Preview docs locally if you changed documentation or public APIs:
+4. Run focused tests for any areas you changed during the release prep itself (docs, config, etc.):
+
+   ```bash
+   ruby -Itest test/test_cli.rb
+   ```
+
+5. Preview docs locally if you changed documentation or public APIs:
 
    ```bash
    bundle exec rake docs:serve
@@ -18,24 +26,36 @@ Release steps before publishing:
 
    The preview builds `_yardoc/`, serves it with WEBrick, and rebuilds in a fresh process when documentation sources, library code, or templates change. Refresh your browser after rebuilds.
 
-5. Generate and check documentation:
+6. Generate and check documentation:
 
    ```bash
-   bundle exec rake rdoc
    bundle exec rake docs:build
    bundle exec rake docs:check
    ```
 
-   `docs:check` validates generated internal links, images, and scripts. Pushes to `main` deploy the generated YARD site to GitHub Pages.
+   `docs:check` validates generated internal links, images, and scripts. Pushes to `main` deploy the generated YARD site to GitHub Pages. You can also run `bundle exec rake rdoc` to generate a separate RDoc site as a sanity check, but it is not deployed.
 
-6. Build the gem locally:
+7. Build the gem locally:
 
    ```bash
    gem build kward.gemspec
    ```
 
-7. Inspect the packaged files and confirm no local config, sessions, logs, or secrets are included.
-8. Install the built gem locally and smoke test the `kward` executable.
+8. Inspect the packaged files and confirm no local config, sessions, logs, or secrets are included. The gemspec uses `git ls-files` and excludes `test/`, `plan/`, `.ruby-lsp/`, `.gitignore`, and `AGENTS.md`. To verify what is packaged:
+
+   ```bash
+   tar tf kward-VERSION.gem
+   ```
+
+9. Install the built gem locally and smoke test the `kward` executable in a clean workspace.
+
+Commit the version bump and create a git tag:
+
+```bash
+git commit -am "Bump to VERSION"
+git tag vVERSION
+git push && git push --tags
+```
 
 Publish the built gem from the release checkout:
 
@@ -44,3 +64,11 @@ gem push kward-VERSION.gem
 ```
 
 RubyGems MFA is required for publishing. Prefer RubyGems trusted publishing for automated releases if CI publishing is added later, so long-lived API keys do not need to be stored in CI secrets.
+
+If a published gem has a serious problem, you can yank it within 24 hours of pushing:
+
+```bash
+gem yank kward --version VERSION
+```
+
+Yanking removes the gem from the default install index but does not delete the version entirely. After yanking, fix the issue, bump the version, and release again.

data/doc/rpc.md

@@ -6,6 +6,8 @@ Kward RPC is an experimental backend protocol for UI clients. It is versioned as
 
 This page is for people building UI clients or integrations. If you use Kward from the terminal, you can skip it.
 
+Prompt history search is a CLI terminal feature only. RPC clients own their composer/input UX and Kward does not currently expose prompt-history read, append, or search methods over RPC.
+
 ## Launch
 
 ```bash
@@ -48,14 +50,14 @@ Result fields:
 Detailed capability fields include:
 
 - `transcript`: Tauren transcript format support, including normalized messages, image/tool support, compaction summaries, and restored assistant reasoning as Pi-compatible `thinking` content blocks.
-- `sessions`: explicit RPC session mode, JSONL persistence, supported session methods, startup auto-resume capability/default, immediate transcript support for auto-resume, RPC list support, supported linear-session fork methods, supported compaction, and explicit unsupported import/tree/update features.
+- `sessions`: explicit RPC session mode, JSONL persistence, supported session methods, startup auto-resume capability/default, immediate transcript support for auto-resume, RPC list support, supported linear-session fork methods, supported compaction, supported tree navigation with labels and branch summarization, and explicit unsupported import/update features.
 - `turns`: async turn mode, per-session concurrency, provider-gated native busy-input steering, queued follow-up input, best-effort cancellation, and recent in-memory event replay behavior.
-- `events`: `turn/event` notification details, assistant/reasoning event names, normalized tool metadata, diff result support, configured workspace guardrail status, and explicit unsupported shell changed-file detection/session update flags.
+- `events`: `turn/event` notification details, assistant/reasoning event names, normalized tool metadata, diff result support, configured workspace guardrail status, focused context and context-budget stats tool support, and explicit unsupported shell changed-file detection/session update flags.
 - `attachments`: supported input attachment contract for `turns/start`, with accepted base64 image MIME types and a stable max byte value.
 - `models`: model/reasoning RPC methods, explicit OpenRouter catalog listing, exposed model fields, and no scoped model support.
 - `runtime`: supported state/stats methods with message-count stats and OpenAI/Codex context usage. Cumulative token and cost stats are not computed.
 - `runtimeSettings`: live `runtime/updateSetting` support for `defaultModel` and `defaultThinkingLevel`, plus `runtime/reload`.
-- `auth`: Tauren auth provider format, OpenAI and Anthropic OAuth, OpenRouter API-key login, and provider logout for stored credentials.
+- `auth`: Tauren auth provider format, OpenAI and Anthropic OAuth, OpenRouter API-key login, GitHub/Copilot status reporting, and provider logout for stored credentials. GitHub OAuth login is CLI-only; RPC reports `supported: false` for the GitHub provider with a reason string.
 - `memory`: opt-in structured memory support, interactive prompt injection only, JSON/JSONL local storage, and dedicated `memory/*` methods.
 - `commands`: supported `commands/list` capability for prompt, skill, and plugin command sources, plus plugin execution through `commands/run` or plugin slash turns.
 - `startupResources`: supported startup resource listing for context, skills, prompts, and plugins.
@@ -63,6 +65,10 @@ Detailed capability fields include:
 - `composer`: composer-only UI features. Interactive session diff totals are explicitly unsupported over RPC (`composer.sessionDiff.supported: false`) because RPC clients already receive per-tool diff results and no live composer status payload is exposed. Clipboard copy is also unsupported over RPC (`composer.copy.supported: false`) because UI clients own clipboard access.
 - `security`: trusted-local behavior; no workspace mutation guard or tool approval, shell/file mutation can run. File-tool workspace guardrails are reported under `capabilities.events.tools.workspaceGuardrails` and `runtime/state.workspaceGuardrailsEnabled`.
 - `export`: supported transcript export formats. Currently `markdown` and `html`; default is `markdown`.
+- `workers`: experimental agent worker pipeline. Reports `supported: false` by default; set to `supported: true` with `methods: ["workers/list", "workers/show"]` when Kward is launched with `--experimental-workers`.
+- `starterPack`: explicitly unsupported (`supported: false`, reason `cliOnlyInstallCommand`). Use `kward init` from the shell.
+- `shell`: explicitly unsupported (`supported: false`, reason `interactiveTuiOnly`) because `/shell` is the local embedded TUI shell.
+- `logging`: local redacted telemetry logging support, the log directory, enabled categories, `methods: ["logging/stats", "logging/tokenCsv"]`, `usageCsv` sub-capability with bucket support, JSONL format, rotation (10 MB, manual retention), config key `logging`, env prefix `KWARD_LOGGING`, and redacted-metadata-only content.
 
 ### `shutdown`
 
@@ -217,6 +223,37 @@ Closes the RPC session. Empty unnamed session files may be cleaned up.
 
 Returns session metadata and full conversation messages. Assistant `reasoning_summary` values and existing `thinking`/`reasoning` content parts are restored as normalized `{ "type": "thinking", "thinking": "..." }` blocks before assistant text; reasoning is not merged into normal text blocks.
 
+### `sessions/tree`
+
+Params:
+
+- `sessionId`
+
+Returns the full branching session tree as flattened Tauren-compatible rows (`tauren-tree-items-v1`). Each row includes `entryId`, `parentId`, `role`, `text` (compact display text), `current` (whether it is the active leaf), `depth`, `isLast`, `ancestorContinues`, `activePath`, `selectable`, `label`, `labelTimestamp`, and `prefix` (tree-drawing connector string). User-message entries are selectable; assistant/tool entries are not.
+
+### `sessions/tree/setLabel`
+
+Params:
+
+- `sessionId`
+- `entryId`
+- `label`: optional display label override for the entry.
+
+Persists a label override for one tree entry and returns `{ "ok": true }`.
+
+### `sessions/tree/navigate`
+
+Params:
+
+- `sessionId`
+- `entryId`: a selectable entry ID from `sessions/tree`.
+- `summarize`: optional boolean; when true, Kward summarizes the abandoned branch before moving.
+- `customInstructions`: optional additional guidance for the summarizer.
+
+Moves the active branch to the selected tree entry. If the entry is a user message, its parent becomes the new active leaf and the user message text is returned as `editorText` so clients can place it into the composer for editing/resubmission. When `summarize` is true, a branch summary is generated and appended to the session before moving.
+
+Returns `{ "session": {}, "editorText": "...", "cancelled": false, "aborted": false }`. Fields with no value are omitted.
+
 ## Turn methods
 
 Turns are asynchronous. A session queues turns sequentially; only one turn runs per session at a time.
@@ -276,6 +313,7 @@ Known event types:
 
 - `turnQueued`
 - `turnSteered`
+- `steeringApplied`
 - `turnStarted`
 - `reasoningDelta`
 - `assistantDelta`
@@ -292,6 +330,8 @@ Lifecycle payloads include `status` for `turnQueued`, `turnStarted`, and `turnFi
 
 `modelRetry` is emitted before Kward retries a transient model request failure. Its payload includes `provider`, `model`, `attempt`, `maxAttempts`, `delaySeconds`, and `error`.
 
+`steeringApplied` is emitted after queued steering input has been appended to conversation context. Its payload includes `count`, the number of steering messages applied.
+
 `toolCall` and `toolResult` payloads include canonical Tauren-normalized fields:
 
 - `toolCallId`: tool call ID.
@@ -379,7 +419,7 @@ Refreshes config-backed runtime state and returns `{ "ok": true, "message": "Res
 
 ## Logging methods
 
-The `logging` capability reports local redacted telemetry logging support, the log directory, enabled categories, and `methods: ["logging/stats"]`. Logging stats require logging to be enabled by config or environment for at least one category.
+The `logging` capability reports local redacted telemetry logging support, the log directory, enabled categories, `methods: ["logging/stats", "logging/tokenCsv"]`, `usageCsv` sub-capability with bucket support, JSONL format with 10 MB rotation and manual retention, config key `logging`, env prefix `KWARD_LOGGING`, and redacted-metadata-only content. Logging methods require logging to be enabled by config or environment for at least one category.
 
 ### `logging/stats`
 
@@ -391,6 +431,15 @@ Accepted units are minutes, hours, days, weeks, months, and years. Ranges use UT
 
 Returns structured stats for enabled categories only, including the requested range, log directory, record counts by category/event, `usageStats` token totals, performance duration summaries, tool call summaries, and error counts by event/class/provider/code. Error messages are not included in the stats response.
 
+### `logging/tokenCsv`
+
+Params:
+
+- `range`: optional duration string; defaults to `1 week`.
+- `bucket`: optional aggregation bucket: `second`, `minute`, `hour`, `day`, `week`, `month`, or `year`.
+
+Returns `{ "csv": "..." }` with token usage data as CSV. Accepted range units and calendar-period behavior match `logging/stats`. This is the RPC equivalent of `kward stats tokens`.
+
 ## Memory methods
 
 Memory is disabled by default. Auto-summary is also disabled by default. RPC memory methods operate on the same local storage as the CLI: `<config-dir>/memory/core.json`, `<config-dir>/memory/soft.jsonl`, and `<config-dir>/memory/events.jsonl`. Retrieved memory is injected only for normal session turns when memory is enabled.
@@ -639,6 +688,27 @@ Completes the login using the submitted code.
 
 Returns login status for a login ID.
 
+## Worker methods (experimental)
+
+Worker methods are available only when Kward is launched with `--experimental-workers`. The `workers` capability reports `supported: false` by default and `supported: true` with `methods: ["workers/list", "workers/show"]` when the flag is active.
+
+### `workers/list`
+
+Params:
+
+- `sessionId`: active RPC session ID.
+
+Returns the list of agent workers for the session.
+
+### `workers/show`
+
+Params:
+
+- `sessionId`: active RPC session ID.
+- `workerId`: worker ID.
+
+Returns details for a specific worker.
+
 ## Security and privacy notes
 
 - RPC is intended for a trusted local UI and can read/write files, run shell commands, update secrets, and use OAuth.