kward 0.66.0 → 0.67.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d6d8b5577dbec359eb683a0ce26cb87276b334b2d6346670df0338c9f10b123f
-  data.tar.gz: abbd42bade9aed052e52b0e5c9ef6f9e560b56c35558346736d3963bdb34fc76
+  metadata.gz: d03a2b137c3ef3a1bc27e44b2629de49a41c70c3044088f9bd0c162cf50e3387
+  data.tar.gz: 241753e7eca9acb6ff94cae50afa7ea43ea2e4c13a8d22eb5031d399ae7fad5a
 SHA512:
-  metadata.gz: 81c6bf970a1dd702e30ee6481feaa57fa11457fca292d17dd0f609c2e37981f9cf72d1e610d2f354a77f7093a3e21fd16b67fea03a54ad30e69c560f72081343
-  data.tar.gz: daa54b6f0db9025b84ad14393654dbce127083f307ca67f0612100e0b015a499ab9f06a5cf413b80ea7e4d5f9f8386b11ae175a4d610f4e2fc90ab3817bd5390
+  metadata.gz: ac0d8465faa573ac9878c4bf5b83327145a7810cbe375b64ce8019531ba00ea3be779a82ed912825de2372ba18917dc56137f67f60161d3234e396b6ec82f3a2
+  data.tar.gz: 3e50a23badb84faf825a75cec5f9d0f4b62cc2bb0c76d643ac8bfb41d99a97c0cbc95268508e4b8a0c2e172249d105f3246b8b0e6a44c81725eae52db71235e6

data/CHANGELOG.md

@@ -2,11 +2,58 @@
 
 All notable changes to Kward will be documented in this file.
 
-## Unreleased
+## [Unreleased]
 
-- No changes yet.
+## [0.67.1] - 2026-06-14
 
-## 0.66.0 - 2026-06-12 - Codename: Order
+### Fixed
+
+- Fixed RPC session listing so it no longer deletes the active empty session file while UI clients are starting a first turn.
+
+## [0.67.0] - 2026-06-13
+
+### Added
+
+- Added optional startup resume for the last active session in each workspace through `sessions.auto_resume: true`, including immediate restored transcript/persona data for RPC clients.
+- Added `tools.workspace_guardrails: false` config support for allowing file tools to access paths outside the active workspace.
+- Added `banner.enabled: false` config support for hiding the interactive terminal banner.
+- Added colored CLI help/version commands, command-specific help, and stricter command precedence over one-shot prompts.
+- Added `--working-directory PATH` as a global option for running any CLI mode from another workspace.
+- Added `kward init` for installing the starter pack; `--install-starter-pack` remains as a compatibility alias.
+- Added `kward doctor` to check local config, workspace, auth hints, Pan credentials, and writable directories.
+- Added `--` as a prompt delimiter so option-like text can be sent as a one-shot prompt.
+- Added `kward auth status` and `kward auth logout` for checking and clearing saved credentials without printing secrets.
+- Added `/reload` and RPC runtime reload support for reloading installed plugins without restarting Kward.
+- Added Session Tree support with a CLI `/tree` command plus RPC persisted entry IDs, labels, label timestamps, and branch navigation.
+- Added RPC `ui/footer` notifications for Kward plugin footers.
+- Added `!` shell commands in the interactive CLI composer.
+- Added the active persona label to RPC `runtime/state` responses.
+
+### Changed
+
+- Expanded the interactive `/settings` command into categorized settings for model, accounts, memory, interface, tools, compaction, personalization, logging, and advanced config info.
+- Changed RPC session deletion to use the OS trash/recycle bin when available before falling back to permanent file deletion.
+- Changed automatic session naming to persist the first visible user turn, keeping slash prompt names unexpanded while still saving expanded prompt content.
+- Changed Pan mode to start with the `kward pan` command; `--pan-mode` remains as a compatibility alias.
+- Changed memory retrieval and listing to use a global core, workspace core, workspace soft hierarchy, and added `/memory relax` for downgrading global core memories to the current workspace.
+- Changed session tree rendering to match Pi's active-path-first branch display, markers, tool rows, and connector prefixes.
+- Changed session tree navigation so all persisted entry points are selectable without automatically running anything.
+
+### Fixed
+
+- Fixed RPC session deletion so empty unnamed sessions are explicitly deleted instead of being consumed by unused-session cleanup first.
+- Fixed the TUI `/tree` selector to start on the current tree position, or the last item for a fresh tree.
+- Fixed the normal session list/resume picker to stay in recent modification-time order, delete empty unnamed sessions, return the full list by default, and avoid test-created session pollution.
+- Fixed RPC model selection to accept lowercase provider IDs from UI clients.
+- Fixed cloned sessions to keep the current session name after renaming.
+
+### Removed
+
+- Removed the obsolete `/crew` command reservation and unreleased RPC compatibility aliases.
+
+## [0.66.0] - 2026-06-12 - Codename: Order
+
+### Added
 
 - Initial public release.
 - Prepare RubyGems packaging for the initial public release.

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    kward (0.66.0)
+    kward (0.67.1)
       base64
       nokogiri
       tiktoken_ruby
@@ -66,7 +66,7 @@ CHECKSUMS
   date (3.5.1) sha256=750d06384d7b9c15d562c76291407d89e368dda4d4fff957eb94962d325a0dc0
   drb (2.2.3) sha256=0b00d6fdb50995fe4a45dea13663493c841112e4068656854646f418fda13373
   erb (6.0.4) sha256=38e3803694be357fe2bfe312487c74beaf9fb4e5beb3e22498952fe1645b95d9
-  kward (0.66.0)
+  kward (0.67.1)
   minitest (6.0.6) sha256=153ea36d1d987a62942382b61075745042a2b3123b1cd48f4c3675af9cc7d6f1
   nokogiri (1.19.3-arm64-darwin) sha256=71b9bd424b1b7abc18b05052a1a3cfd3627abdca62be280854cc411791357e42
   pastel (0.8.0) sha256=481da9fb7d2f6e6b1a08faf11fa10363172dc40fd47848f096ae21209f805a75

data/README.md

@@ -15,7 +15,7 @@ gem install kward
 Optionally install the starter pack after installation:
 
 ```bash
-kward --install-starter-pack
+kward init
 ```
 
 This downloads Kward's default prompts and base `AGENTS.md` into your config directory. It is useful for a first setup, but safe to skip if you prefer to create your own instructions. Existing files are left untouched.
@@ -24,9 +24,11 @@ Then start Kward and sign in when needed:
 
 ```bash
 kward                          # start an interactive chat
+kward help                     # show available commands and examples
 /login                         # from inside Kward: sign in or save provider credentials
 kward login                    # from your shell: sign in or save provider credentials
 kward "Explain this project"   # run one prompt and exit
+kward --working-directory ~/code/project "Explain this project"
 ```
 
 See [Authentication](doc/authentication.md) for more details about sign-in options and provider credentials.
@@ -39,6 +41,7 @@ If you are working from a checkout:
 bundle install
 ruby lib/main.rb login                    # sign in or save provider credentials
 ruby lib/main.rb                          # start an interactive chat
+ruby lib/main.rb help                     # show available commands and examples
 ruby lib/main.rb "Explain this project"   # run one prompt and exit
 ```
 
@@ -67,6 +70,7 @@ Start here:
 - [Usage](doc/usage.md): interactive chat, slash commands, sessions, tools, images, and Pan mode.
 - [Configuration](doc/configuration.md): config files, providers, models, web search, logging, and color output.
 - [Authentication](doc/authentication.md): OpenAI OAuth, OpenRouter API keys, and Copilot/GitHub setup.
+- [Troubleshooting](doc/troubleshooting.md): environment-specific install and runtime issues.
 
 Feature guides:
 

data/doc/configuration.md

@@ -141,6 +141,20 @@ Overlay settings control terminal picker/card layout:
 
 You can change these interactively with `/settings`.
 
+## Banner settings
+
+The interactive terminal banner shows the avatar Kward logo and the “State your business.” message by default. To hide the full banner:
+
+```json
+{
+  "banner": {
+    "enabled": false
+  }
+}
+```
+
+This only affects the interactive terminal UI.
+
 ## Composer settings
 
 The busy composer shows a short Ctrl+C cancellation hint by default. To hide it:
@@ -155,6 +169,20 @@ The busy composer shows a short Ctrl+C cancellation hint by default. To hide it:
 
 This only hides the hint text; Ctrl+C still stops the current running response.
 
+## Session settings
+
+Interactive CLI and RPC clients start fresh by default. To automatically resume the last active session for the current workspace:
+
+```json
+{
+  "sessions": {
+    "auto_resume": true
+  }
+}
+```
+
+The `/resume` command and RPC `sessions/resume` work regardless of this automatic resume setting.
+
 ## Memory
 
 Memory is off by default. Enabling it writes:
@@ -198,7 +226,7 @@ Manual `/compact [instructions]` works even when auto-compaction is disabled.
 
 ## Pan mode
 
-`--pan-mode` starts a LAN-reachable web UI and requires HTTP Basic Auth. Configure credentials before starting it:
+`kward pan` starts a LAN-reachable web UI and requires HTTP Basic Auth. Configure credentials before starting it:
 
 ```json
 {
@@ -246,6 +274,20 @@ For higher limits or alternate providers, add user-specific keys. Model-backed a
 
 Do not put shared or published API keys in this file.
 
+## Tool workspace guardrails
+
+Workspace guardrails are enabled by default. File tools such as `read_file`, `write_file`, `edit_file`, and `list_directory` are limited to the active workspace. To allow those file tools to access paths outside the workspace:
+
+```json
+{
+  "tools": {
+    "workspace_guardrails": false
+  }
+}
+```
+
+This is not a sandbox setting. Shell commands already run as your OS user from the workspace directory and can access anything that user can access.
+
 ## Logging and stats
 
 Local telemetry logs are off by default. Enable logging with the master flag and each category you want:

data/doc/memory.md

@@ -53,7 +53,13 @@ Auto-summary does not run when memory is disabled and is not used for one-shot p
 
 ### Core memories
 
-Core memories are explicit user instructions. They are high-trust and persistent until removed. Add them only when you intentionally want Kward to remember something:
+Memory is organized as a hierarchy for the active workspace:
+
+1. Global core memories
+2. Workspace core memories
+3. Workspace soft memories
+
+Global core memories are explicit user instructions. They are high-trust, apply everywhere, and are ranked before workspace-specific memory. Add them only when you intentionally want Kward to remember something globally:
 
 ```text
 /memory core "Prefer small, focused patches with tests."
@@ -65,9 +71,11 @@ Core memories are stored as human-readable JSON in:
 ~/.kward/memory/core.json
 ```
 
+Workspace core memories are core memories scoped to a specific workspace. They usually come from promoting workspace soft memories.
+
 ### Soft memories
 
-Soft memories are contextual hints, such as workflow preferences or recurring project facts. They are confidence-based and treated as non-authoritative. Add one manually with:
+Soft memories are workspace-scoped contextual hints, such as workflow preferences or recurring project facts. They are confidence-based and treated as non-authoritative. Add one manually with:
 
 ```text
 /memory add "This workspace usually uses Minitest."
@@ -93,12 +101,14 @@ Session memories record memories learned during the current conversation so Kwar
 
 ## Inspect, explain, and remove memory
 
-List memories:
+List memories for the active workspace hierarchy:
 
 ```text
 /memory list
 ```
 
+The list is grouped as global core, workspace core, and workspace soft. Memories from other workspaces are not shown in this hierarchy view.
+
 Inspect memory state and file paths:
 
 ```text
@@ -120,21 +130,29 @@ Forget a memory:
 
 For core memories, forget removes the record. For soft memories, forget marks the record inactive and redacts its stored text, tags, confidence, and hit count so inactive audit metadata can remain without retaining the memory content.
 
-Promote a soft memory to a core memory:
+Promote a memory:
 
 ```text
 /memory promote soft_001
+/memory promote core_001
 ```
 
-Promotion creates a new core memory and marks the soft memory forgotten.
+Promoting a soft memory creates a new workspace core memory and marks the soft memory forgotten. Promoting a workspace core memory upgrades it to global core.
+
+Relax a global core memory back to the current workspace:
+
+```text
+/memory relax core_001
+```
 
 ## Retrieval behavior
 
 For each interactive turn, Kward selectively retrieves memories using:
 
 - scope: `global` and `workspace:<canonical path>`
-- core memories first
-- soft-memory text or tag overlap with the current input; soft memories without overlap are not injected
+- global core memories first
+- workspace core memories second
+- workspace soft-memory text or tag overlap with the current input; soft memories without overlap are not injected
 - soft-memory confidence
 - soft-memory recency/TTL, updated when a soft memory is retrieved
 - hard limits on injected memory count
@@ -143,10 +161,13 @@ Retrieved memories are injected into the system prompt as a bounded block simila
 
 ```text
 <kward_memory>
-Core Memories:
+Global Core Memories:
 - [core_001] ...
 
-Relevant Soft Memories:
+Workspace Core Memories:
+- [core_002] ...
+
+Workspace Soft Memories:
 - [soft_001] ...
 
 Rules:
@@ -185,6 +206,7 @@ The experimental RPC backend exposes dedicated memory methods:
 - `memory/addCore`
 - `memory/forget`
 - `memory/promote`
+- `memory/relax`
 - `memory/inspect`
 - `memory/why`
 - `memory/summarize`

data/doc/rpc.md

@@ -47,14 +47,14 @@ Result fields:
 - `protocolVersion`: currently `1`.
 - `serverName`: `"kward"`.
 - `experimental`: `true`.
-- `capabilities`: includes detailed Tauren-compatible capability groups. Some legacy simple fields remain for older clients, but `sessions` is now the detailed session capability object.
+- `capabilities`: includes Tauren-compatible capability groups.
 
 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, 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, and explicit unsupported import/tree/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, 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, 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.
@@ -63,13 +63,11 @@ Detailed capability fields include:
 - `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.
-- `extensionUi`: question bridge support via `ui/question` and `ui/answerQuestion`; other UI primitives are explicitly unsupported.
+- `extensionUi`: question bridge support via `ui/question` and `ui/answerQuestion`, plus plugin footer updates via `ui/footer`; other UI primitives are explicitly unsupported.
 - `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.
+- `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`.
 
-Legacy compatibility fields still present include `asyncTurns`, `turnCancellation`, `turnEventReplay`, `uiQuestions`, `authLogin`, `configUpdate`, `session`, `cancellation`, `eventReplay`, `uiQuestion`, `prompts`, `skills`, `tools`, and `config`.
-
 ### `shutdown`
 
 Requests process shutdown after the response.
@@ -98,8 +96,9 @@ Params:
 
 - `workspaceRoot`: optional existing directory; defaults to launch cwd.
 - `name`: optional session name.
+- `resumeLast`: optional boolean. Defaults to the configured `sessions.auto_resume` behavior when omitted by clients that use `sessions/create` for startup. `false` forces a fresh session.
 
-Creates a persisted Kward session and returns session metadata.
+Creates a persisted Kward session and returns session metadata. The response includes `activePersonaLabel` so clients can render the correct avatar immediately. When `resumeLast` is enabled, no `name` is provided, and `sessions.auto_resume` is `true`, Kward resumes the remembered last session for the workspace instead of creating a fresh file; that auto-resume response also includes `resumed: true` and normalized `messages` so clients do not need to briefly render a fresh avatar while fetching transcript state.
 
 ### `sessions/resume`
 
@@ -115,9 +114,9 @@ Loads a persisted session and returns a new RPC session ID.
 Params:
 
 - `workspaceRoot`: optional.
-- `limit`: optional, default `20`.
+- `limit`: optional; omitted or non-positive values return all sessions.
 
-Returns recent persisted sessions for that workspace. Existing sessions without ancestry are roots; cloned or forked sessions include parent metadata and tree display fields. Each item includes absolute `path`, `cwd`, `workspaceRoot`, `createdAt`, `modifiedAt`, optional `name`, compact `firstMessage`, `messageCount` excluding metadata records, optional `parentId`/`parentPath`, `depth`, `isLast`, and `ancestorContinues` for tree rendering.
+Returns recent persisted sessions for that workspace in modification-time order. Empty unnamed sessions are deleted during listing. Cloned or forked sessions include parent metadata. Each item includes absolute `path`, `cwd`, `workspaceRoot`, `createdAt`, `modifiedAt`, optional `name`, compact `firstMessage`, `messageCount` excluding metadata records, optional `parentId`/`parentPath`, `depth`, `isLast`, and `ancestorContinues` fields.
 
 ### `sessions/rename`
 
@@ -302,8 +301,6 @@ Lifecycle payloads include `status` for `turnQueued`, `turnStarted`, and `turnFi
 - `toolCallId`: tool call ID.
 - `toolName`: normalized tool name, such as `read`, `edit`, `write`, or `bash`.
 - `args`: normalized arguments. Edit replacements use `oldText`/`newText`; shell timeout is `timeout`.
-- `rawToolCall` and `toolCall`: original model tool call for compatibility.
-- `tool`: legacy normalized metadata retained for older clients.
 
 `toolResult` additionally includes `result` with `content`, `isError`, optional unified `diff`, optional `changedFiles`, and `images`. Failed or declined tools set `isError: true`.
 
@@ -315,7 +312,7 @@ Examples:
 
 ## UI question bridge
 
-Kward's only supported extension-style UI surface is the structured question bridge. The `extensionUi` capability reports `question.supported: true` with `notification: "ui/question"`, `method: "ui/answerQuestion"`, `maxQuestions: 4`, `multiSelect: false`, and `preview: false`. Other Pi-style extension UI primitives (`select`, `confirm`, `input`, `editor`, `widgets`, `footer`, `custom`, and `terminalInput`) are explicitly reported as unsupported until Kward has a real plugin/extension consumer for them.
+Kward supports the structured question bridge and plugin footer updates over RPC. The `extensionUi` capability reports `question.supported: true` with `notification: "ui/question"`, `method: "ui/answerQuestion"`, `maxQuestions: 4`, `multiSelect: false`, and `preview: false`. It also reports `footer.supported: true` with `notification: "ui/footer"`. Other Pi-style extension UI primitives (`select`, `confirm`, `input`, `editor`, `widgets`, `custom`, and `terminalInput`) are explicitly reported as unsupported until Kward has a real plugin/extension consumer for them.
 
 Question requests are validated before notification. Kward accepts 1-4 questions, each with 2-4 options, and rejects unsupported `multiSelect` or option `preview` requests.
 
@@ -329,6 +326,17 @@ When the model calls `ask_user_question`, RPC emits a `ui/question` notification
 }
 ```
 
+When a loaded Kward plugin registers a footer, RPC emits `ui/footer` after session creation/resume/clone and after each completed turn:
+
+```json
+{
+  "sessionId": "...",
+  "text": "custom footer text"
+}
+```
+
+An empty `text` value clears the client footer.
+
 The UI must respond with `ui/answerQuestion`:
 
 Params:
@@ -345,7 +353,7 @@ Params:
 
 - `sessionId`: active RPC session ID.
 
-Returns Tauren-compatible runtime state for the session, including session file, persisted session ID/name, active `rpcSessionId`, `persistentSessionId`, current model metadata, current thinking level, streaming/pending-message state, and stable Kward defaults. The legacy `sessionId` field remains the persisted session ID; clients must send the active RPC session `id`/`rpcSessionId` in RPC request params. Unsupported runtime settings are returned as false or omitted.
+Returns Tauren-compatible runtime state for the session, including session file, persisted session ID/name, active `rpcSessionId`, `persistentSessionId`, current model metadata, current thinking level, streaming/pending-message state, and stable Kward defaults. Clients must send the active RPC session `id`/`rpcSessionId` in RPC request params. Unsupported runtime settings are returned as false or omitted.
 
 ### `runtime/stats`
 
@@ -353,7 +361,7 @@ Params:
 
 - `sessionId`: active RPC session ID.
 
-Returns session file/id/name, active `rpcSessionId`, `persistentSessionId`, message-count stats: user messages, assistant messages, tool calls, tool results, and total non-system messages. The legacy `sessionId` field remains the persisted session ID; clients must send the active RPC session `id`/`rpcSessionId` in RPC request params. For OpenAI/Codex sessions with a known model context window and text-only non-empty conversation context, also returns `contextUsage` with estimated current next-request context tokens, context window, percent used, and `estimated: true`. Fresh sessions with no non-system content omit `contextUsage` because only static prompt/tool overhead would be measurable. Cumulative token and cost fields are omitted until Kward tracks provider usage responses.
+Returns session file/id/name, active `rpcSessionId`, `persistentSessionId`, message-count stats: user messages, assistant messages, tool calls, tool results, and total non-system messages. Clients must send the active RPC session `id`/`rpcSessionId` in RPC request params. For OpenAI/Codex sessions with a known model context window and text-only non-empty conversation context, also returns `contextUsage` with estimated current next-request context tokens, context window, percent used, and `estimated: true`. Fresh sessions with no non-system content omit `contextUsage` because only static prompt/tool overhead would be measurable. Cumulative token and cost fields are omitted until Kward tracks provider usage responses.
 
 ### `runtime/updateSetting`
 
@@ -416,8 +424,9 @@ Disables quiet memory summarization after completed interactive turns. Returns `
 Params:
 
 - `includeInactive`: optional boolean; includes forgotten soft memories when true.
+- `workspaceRoot`: optional workspace root for hierarchy filtering; defaults to the server process workspace.
 
-Returns `{ "core": [], "soft": [] }`.
+Returns `{ "global_core": [], "workspace_core": [], "workspace_soft": [] }`.
 
 ### `memory/add`
 
@@ -453,13 +462,24 @@ Returns `{ "forgotten": true }` when a memory was removed or marked forgotten. C
 
 ### `memory/promote`
 
-Promotes an active soft memory to a new core memory and marks the soft memory forgotten.
+Promotes an active soft memory to a new workspace core memory and marks the soft memory forgotten, or promotes a workspace core memory to global core.
 
 Params:
 
-- `id`: soft memory ID.
+- `id`: soft memory ID or workspace core memory ID.
 
-Returns `{ "memory": {} }` for the new core memory.
+Returns `{ "memory": {} }`.
+
+### `memory/relax`
+
+Downgrades a global core memory to the current workspace hierarchy.
+
+Params:
+
+- `id`: global core memory ID.
+- `workspaceRoot`: optional workspace root for the relaxed scope; defaults to the server process workspace.
+
+Returns `{ "memory": {} }`.
 
 ### `memory/inspect`
 
@@ -487,7 +507,7 @@ Returns `{ "memories": [] }`.
 
 ### `models/list`
 
-Returns known model entries from the current client/config backend. OpenRouter entries prefer models available to the configured OpenRouter API key when they can be fetched; otherwise Kward falls back to defaults/currently configured options. Entries use `{ "provider", "id", "name", "reasoning", "reasoningEffort", "contextWindow", "current" }`; legacy `model` is retained as an alias for older clients.
+Returns known model entries from the current client/config backend. OpenRouter entries prefer models available to the configured OpenRouter API key when they can be fetched; otherwise Kward falls back to defaults/currently configured options. Entries use `{ "provider", "id", "name", "reasoning", "reasoningEffort", "contextWindow", "current" }`.
 
 ### `openrouter/catalog`
 
@@ -495,7 +515,7 @@ Returns the full OpenRouter model catalog as model entries. This is separate fro
 
 ### `models/current`
 
-Returns the current model entry with `id`, `name`, `reasoning`, `reasoningEffort`, and legacy `model` alias where available.
+Returns the current model entry with `provider`, `id`, `name`, `reasoning`, `reasoningEffort`, `contextWindow`, and `current` where available.
 
 ### `models/set`
 

data/doc/troubleshooting.md

@@ -0,0 +1,55 @@
+# Troubleshooting
+
+This page collects environment-specific issues that can affect Kward but are not caused by Kward itself.
+
+## `gem install kward` succeeds, but `kward` is not found with rbenv
+
+When using rbenv, RubyGems installs gem executables into the active Ruby version's `bin` directory. rbenv then exposes those executables through shims in `$RBENV_ROOT/shims`.
+
+If `gem install kward` succeeds but `kward` is not available on your `PATH`, first check whether RubyGems installed the executable:
+
+```bash
+rbenv which kward
+```
+
+If that prints a path such as:
+
+```text
+/Users/you/.rbenv/versions/4.0.3/bin/kward
+```
+
+then the gem executable exists and the missing command is likely an rbenv shim issue.
+
+Regenerate shims:
+
+```bash
+rbenv rehash
+```
+
+Then verify the shim exists:
+
+```bash
+test -x "$RBENV_ROOT/shims/kward"
+```
+
+If `rbenv rehash` fails with an error like:
+
+```text
+rbenv: cannot rehash: /Users/you/.rbenv/shims/.rbenv-shim exists
+```
+
+remove the stale rbenv prototype shim and rehash again:
+
+```bash
+rm -f "$RBENV_ROOT/shims/.rbenv-shim"
+rbenv rehash
+```
+
+After that, `kward` should be available through the rbenv shim:
+
+```bash
+which kward
+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.

data/doc/usage.md

@@ -4,8 +4,12 @@ Kward's most common commands are:
 
 ```bash
 kward                          # interactive chat
+kward help                     # command overview and examples
 kward "Explain this project"   # one-shot prompt
-kward --install-starter-pack   # optional first-time setup
+kward init                     # optional first-time setup
+kward doctor                   # check local setup
+kward auth status              # show saved credential status
+kward pan                      # Pan mode web UI
 kward rpc                      # experimental JSON-RPC backend
 ```
 
@@ -16,7 +20,7 @@ When running from source, replace `kward` with `ruby lib/main.rb`.
 Install Kward's starter prompts and base `AGENTS.md` into your config directory, usually `~/.kward`:
 
 ```bash
-kward --install-starter-pack
+kward init
 ```
 
 The installer downloads the pinned `kaiwood/kward-starter-pack` `v1.0.0` release, creates the config directory and base `config.json` if needed, and copies only starter-pack instruction/prompt files. It preserves the starter-pack layout in your config directory and skips files that already exist.
@@ -27,12 +31,41 @@ Interactive mode opens a terminal composer and saves the conversation as a per-w
 
 The composer stays available while assistant and tool output streams. If you press Enter while a response is still running, Kward queues your next prompt and sends it after the current turn finishes. Press Ctrl+C while a response is running to stop the current turn and return to the composer.
 
+Prefix input with `!` to run a local shell command from the workspace root without sending it to the model:
+
+```text
+!git status --short
+```
+
+## Shell commands
+
+Use `kward help` or `kward --help` to print a colored overview of available commands and examples. Use `kward help <command>` or `<command> --help` for command-specific help. Use `kward version` or `kward --version` to print the installed version.
+
+Use `kward doctor` to check local config, workspace, auth hints, Pan credentials, and writable directories. Use `kward auth status` to show saved credential status without printing secrets, or `kward auth logout` to remove saved OpenAI, GitHub, and OpenRouter credentials.
+
+Use `--working-directory PATH` with any mode to run Kward from a different workspace:
+
+```bash
+kward --working-directory ~/code/project
+kward --working-directory ~/code/project "Summarize this project"
+kward --working-directory ~/code/project pan
+kward --working-directory ~/code/project rpc
+```
+
 ## One-shot prompts
 
-Pass a prompt as command-line text to ask once and exit:
+Command names take precedence. Invalid arguments for known commands show usage instead of becoming prompts. Anything else passed as command-line text is sent as a one-shot prompt:
 
 ```bash
 kward "Summarize the changes in this repository"
+kward Summarize the changes in this repository
+```
+
+Use `--` before the prompt when the prompt itself starts with a command name or contains option-like text:
+
+```bash
+kward -- pan extra
+kward -- explain --working-directory option
 ```
 
 Kward also accepts piped input:
@@ -95,7 +128,7 @@ Useful session commands:
 
 - `/resume` opens a picker for recent sessions.
 - `/name <name>` gives the current session a human-readable name.
-- `/clone` creates a new independent copy. Cloned sessions remember their parent and appear indented in the resume picker.
+- `/clone` creates a new independent copy. Cloned sessions remember their parent and appear in the recent session picker by modification time.
 - `/copy` and `/copy last` copy the latest assistant response without terminal borders or ANSI styling. `/copy transcript` copies the clean Markdown transcript. Mouse selection may still include terminal UI chrome.
 - `/export [path]` writes a Markdown transcript. Explicit paths are resolved relative to the current workspace and must stay inside the workspace or Kward session directory.
 - `/compact [instructions]` summarizes older conversation into a structured Ruby-aware checkpoint. Text after `/compact ` is freeform focus text, not parsed as flags.
@@ -132,6 +165,8 @@ Common commands:
 /memory add <text>
 /memory list
 /memory why
+/memory promote <id>
+/memory relax <id>
 /memory forget <id>
 /memory disable
 ```
@@ -165,13 +200,13 @@ In the interactive composer, pasted image references appear as attachment badges
 Pan mode starts a minimal LAN web UI with a prompt textarea and transcript:
 
 ```bash
-kward --pan-mode --working-directory="/path/to/workspace"
+kward --working-directory="/path/to/workspace" pan
 ```
 
 From source:
 
 ```bash
-ruby lib/main.rb --pan-mode --working-directory="/path/to/workspace"
+ruby lib/main.rb --working-directory="/path/to/workspace" pan
 ```
 
 Pan mode streams assistant output and tool calls, queues prompts submitted while a turn is running, and saves the conversation as a normal per-workspace session.