kward 0.74.0 → 0.75.0

data/doc/rpc.md

@@ -2,7 +2,7 @@
 
 <div class="kward-no-toc"></div>
 
-Kward RPC is an experimental backend protocol for UI clients. It is versioned as protocol version `1`, but method names and payloads may still change while the UI integration is built.
+Kward RPC is a JSON-RPC backend protocol for trusted local UI clients. It is versioned as protocol version `1`: new methods and fields may be added in compatible releases, and clients should ignore unknown fields. Removing or changing existing methods or field meanings requires a protocol version bump. Individual capability groups may still report unsupported status in `initialize.capabilities`.
 
 This page is for people building UI clients or integrations. If you use Kward from the terminal, you can skip it.
 
@@ -44,27 +44,28 @@ Result fields:
 
 - `protocolVersion`: currently `1`.
 - `serverName`: `"kward"`.
-- `experimental`: `true`.
-- `capabilities`: includes Tauren-compatible capability groups.
+- `experimental`: `false`.
+- `capabilities`: includes frontend-neutral 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, 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, explicit unsupported import support, and unsupported live session updates reported with `notification: "session/updated"`.
-- `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, focused context and context-budget stats tool support, and explicit unsupported shell changed-file detection/session update flags.
+- `transcript`: Kward 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, active live-session discovery, supported linear-session fork methods, supported compaction, supported tree navigation with labels and branch summarization, explicit unsupported import support, and unsupported live session updates reported with `notification: "session/updated"`.
+- `turns`: async turn mode, per-session concurrency, active/recent turn listing, provider-gated native busy-input steering, queued follow-up input, best-effort cancellation, recent in-memory event replay behavior, per-turn options for model/reasoning/tool scope/tool approval, and structured client context for editor integrations.
+- `events`: `turn/event` notification details, assistant/reasoning event names, normalized tool metadata, tool update/result events, 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.
+- `lifecycleHooks`: supported lifecycle hook events, decisions, command/plugin/workspace/HTTP/async hook availability, audit log path, hook approval routing through tool approval, and hook notifications (`hook/event`, `hook/message`).
 - `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, 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.
+- `auth`: Kward 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.
-- `mcp`: local stdio MCP server support through the shared `mcpServers` config. RPC exposes MCP tools to turns; MCP resources, prompts, sampling, and Streamable HTTP are explicitly unsupported for now.
+- `mcp`: local stdio MCP server support through the shared `mcpServers` config. RPC exposes MCP tools to turns and advertises discovery with `methods: ["tools/list", "mcp/status"]`, `toolMetadata: true`, and `serverStatus: true`. MCP resources, prompts, sampling, and Streamable HTTP are explicitly unsupported for now.
 - `startupResources`: supported startup resource listing for context, skills, prompts, and plugins.
 - `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. File-tool workspace guardrails are reported under `capabilities.events.tools.workspaceGuardrails` and `runtime/state.workspaceGuardrailsEnabled`.
+- `security`: trusted-local behavior with optional per-turn tool approval. By default there is no workspace mutation guard or tool approval and 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.
@@ -89,6 +90,23 @@ Returns the real workspace root. Any existing local directory accessible to the
 
 Returns root, basename, and writability for a workspace.
 
+## Lifecycle hook notifications
+
+RPC clients can subscribe by listening for JSON-RPC notifications:
+
+- `hook/event`: emitted after a lifecycle hook event runs at least one matching handler. The payload includes event identity, phase, timestamp, session/turn/workspace/frontend/agent metadata, sorted `payloadKeys`, and the final decision summary. Raw event payload values are intentionally omitted.
+- `hook/message`: emitted when trusted hook/plugin code calls `ctx.say`.
+
+Both notifications are redacted by the same RPC redactor used for other outbound messages.
+
+### `hooks/logs`
+
+Params:
+
+- `limit`: optional positive integer, default `20`, capped at `200`.
+
+Returns `{ path, records }` from the local lifecycle hook audit log. Unreadable JSONL lines are skipped and records are redacted before they are sent over RPC.
+
 ## Session methods
 
 RPC sessions are explicit and have an RPC `id`, a persisted session `path`, and a `workspaceRoot`. When a client creates, resumes, clones, or forks into another session, idle empty unnamed sessions are cleaned up automatically.
@@ -224,13 +242,17 @@ 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/active`
+
+Returns currently live RPC sessions in this server process. This is intended for clients reconnecting to an existing local RPC process; it does not list persisted sessions that are not currently open. Use `sessions/list` for persisted session files.
+
 ### `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.
+Returns the full branching session tree as flattened frontend-neutral rows (`kward-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`
 
@@ -267,6 +289,8 @@ Params:
 - `input`
 - `streamingBehavior`: optional; `newTurn` by default when idle. `followUp` queues behind the active turn. `steer` routes input to the active turn only when `initialize.capabilities.turns.busyInput.steer` is `native`; unsupported providers return an invalid params error instead of queueing or approximating steering. When native steering is supported and a turn is already running, omitted `streamingBehavior` defaults to `steer`.
 - `attachments`: optional array of image attachments: `{ "type": "image", "data": "base64", "mimeType": "image/png", "name": "optional.png", "sizeBytes": 12345 }`.
+- `options`: optional object with per-turn overrides. Supported fields are `provider`, `model`, `reasoningEffort`, `allowedTools`, `disabledTools`, and `approvalMode`. `model` may be a string or an object with `id`/`model`. `allowedTools` and `disabledTools` are arrays of model tool names and are mutually exclusive. `approvalMode` is `none` by default; `ask` emits `tool/approvalRequested` before each tool execution and waits for `tool/answerApproval`. Tool scoping and approval affect only the current turn; they do not change the session or saved config.
+- `context`: optional structured client/editor context. Supported fields are `activeFile`, `openFiles`, `selection`, and `diagnostics`. `selection` may include `path`, `startLine`, `endLine`, and `text`; diagnostics may include `path`, `line`, `severity`, and `message`. Kward appends this context to the turn input for model use without persisting it as separate protocol state.
 
 Supported attachment MIME types are `image/png`, `image/jpeg`, `image/gif`, and `image/webp`. Image data must be raw base64 without a `data:` prefix, and the RPC boundary limit is 10MB per image.
 
@@ -295,6 +319,22 @@ Params:
 
 Returns recent in-memory events after the requested sequence. Event history is not persisted and is bounded in memory.
 
+### `turns/list`
+
+Params:
+
+- `sessionId`: optional active RPC session ID filter.
+
+Returns recent in-memory turn metadata for this server process. Turn metadata is not persisted across RPC process restarts.
+
+### `turns/listActive`
+
+Params:
+
+- `sessionId`: optional active RPC session ID filter.
+
+Returns queued and running turns for this server process. Use this after reconnecting to rebuild live UI state.
+
 ## Turn notifications
 
 The server emits `turn/event` notifications:
@@ -321,6 +361,7 @@ Known event types:
 - `assistantMessage`
 - `modelRetry`
 - `toolCall`
+- `toolUpdate`
 - `toolResult`
 - `answer`
 - `turnCancelRequested`
@@ -333,12 +374,14 @@ Lifecycle payloads include `status` for `turnQueued`, `turnStarted`, and `turnFi
 
 `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:
+`toolCall`, `toolUpdate`, and `toolResult` payloads include canonical Kward-normalized fields:
 
 - `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`.
 
+`toolUpdate` additionally includes `delta.content` and optional `elapsedMs` for clients that want progress/status updates before the final result. Kward currently emits one update after each built-in tool finishes; clients should treat future additional updates as additive.
+
 `toolResult` additionally includes `result` with `content`, `isError`, optional unified `diff`, optional `changedFiles`, and `images`. Failed or declined tools set `isError: true`.
 
 Examples:
@@ -347,6 +390,28 @@ Examples:
 - `write_file`: `toolName: "write"`, `args: { "path": "...", "content": "..." }`.
 - `run_shell_command`: `toolName: "bash"`, `args: { "command": "...", "timeout": 30 }`.
 
+## Tool approval bridge
+
+When `turns/start` is called with `options.approvalMode: "ask"`, Kward emits `tool/approvalRequested` before executing each tool.
+
+Notification params include:
+
+- `sessionId`
+- `approvalRequestId`
+- `toolCallId`
+- `toolName`
+- `args`
+
+Clients answer with `tool/answerApproval`:
+
+Params:
+
+- `sessionId`
+- `approvalRequestId`
+- `approved`: boolean.
+
+Denied tools are returned to the model as error-like tool results instead of executing the local operation.
+
 ## UI question bridge
 
 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.
@@ -390,7 +455,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. Clients must send the active RPC session `id`/`rpcSessionId` in RPC request params. Unsupported runtime settings are returned as false or omitted.
+Returns frontend-neutral 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`
 
@@ -580,7 +645,34 @@ Updates the config-backed OpenAI/Codex reasoning effort and returns the current
 
 ### `tools/list`
 
-Returns current tool schemas.
+Params:
+
+- `sessionId`: optional active RPC session ID. When supplied, returns the exact tool set for that session/workspace. When omitted, returns the default current tool schemas.
+
+Returns current tool schemas. The existing model-facing schema shape is preserved: each entry still has `type: "function"` and `function` with `name`, `description`, and `parameters`. Entries also include additive metadata for UI discovery:
+
+- `metadata.source`: one of practical source labels such as `builtin`, `mcp`, `web`, `skill`, `ui`, or `unknown`.
+- `metadata.displayName`: human-readable tool label.
+- MCP tools also include `metadata.serverName` and `metadata.remoteName`. The callable name remains sanitized with a double underscore, for example `github__search_issues`, while `displayName` is `github.search_issues`.
+
+Clients that only read `tools[].function` remain compatible.
+
+### `mcp/status`
+
+Returns configured MCP stdio server status without exposing environment values or raw sensitive arguments.
+
+Result shape:
+
+```json
+{
+  "servers": [
+    { "name": "github", "transport": "stdio", "status": "available", "toolCount": 8 },
+    { "name": "linear", "transport": "stdio", "status": "unavailable", "toolCount": 0, "error": "Failed to start MCP server linear-mcp: command not found" }
+  ]
+}
+```
+
+Disabled MCP servers are omitted, matching runtime tool exposure. Unsupported MCP capabilities remain unsupported: resources, prompts, sampling, and Streamable HTTP.
 
 ### `commands/list`
 
@@ -588,7 +680,7 @@ Params:
 
 - `sessionId`: active RPC session ID.
 
-Returns Tauren-compatible slash command metadata for configured prompt templates, skills, and plugins. Prompt command names omit the leading slash. Skill command names use `skill:<name>`. Plugin command names omit the leading slash and include `executable: true`. Builtin terminal-only commands are omitted. Prompt commands can be submitted directly to `turns/start` as slash commands or expanded first with `prompts/expand`; plugin commands can be submitted to `turns/start` or run explicitly with `commands/run`.
+Returns frontend-neutral slash command metadata for configured prompt templates, skills, and plugins. Prompt command names omit the leading slash. Skill command names use `skill:<name>`. Plugin command names omit the leading slash and include `executable: true`. Builtin terminal-only commands are omitted. Prompt commands can be submitted directly to `turns/start` as slash commands or expanded first with `prompts/expand`; plugin commands can be submitted to `turns/start` or run explicitly with `commands/run`.
 
 ### `resources/startup`
 
@@ -635,7 +727,7 @@ Returns whether OpenAI OAuth, Anthropic OAuth, OpenAI access token env, and Open
 
 ### `auth/providers`
 
-Returns Tauren-compatible provider cards for OpenAI OAuth, Anthropic OAuth, OpenRouter API-key auth, and GitHub/Copilot status. Provider cards report whether credentials are configured, whether they came from stored config or environment variables, and whether stored credentials can be removed.
+Returns frontend-neutral provider cards for OpenAI OAuth, Anthropic OAuth, OpenRouter API-key auth, and GitHub/Copilot status. Provider cards report whether credentials are configured, whether they came from stored config or environment variables, and whether stored credentials can be removed.
 
 ### `auth/loginWithApiKey`
 

data/doc/session-management.md

@@ -23,7 +23,7 @@ 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`.
+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 `/session`.
 
 ## A normal session workflow
 
@@ -33,7 +33,7 @@ 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.
+`/rename` requires a name. Use `/session name` without an argument to clear the current session name.
 
 Work normally:
 
@@ -52,19 +52,19 @@ Leave when you are done for now:
 Later, resume the work:
 
 ```text
-/sessions
+/session
 ```
 
 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`.
+`/resume` is an alias for `/session`.
 
 ## The sessions picker
 
 Open it with:
 
 ```text
-/sessions
+/session
 ```
 
 Inside the picker you can:
@@ -91,7 +91,7 @@ From inside the active session:
 /clone
 ```
 
-Or from `/sessions`, highlight a session and press `c`.
+Or from `/session`, 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.
 
@@ -114,7 +114,7 @@ From inside the active session:
 /fork
 ```
 
-Or from `/sessions`, highlight a session and press `f`.
+Or from `/session`, 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.
 
@@ -228,9 +228,9 @@ This is useful when you want to confirm which session you are in or check whethe
 
 | Need | Use |
 | --- | --- |
-| Continue earlier work | `/sessions` or `/resume` |
+| Continue earlier work | `/session` or `/resume` |
 | Give the current session a better name | `/rename <name>` |
-| Clear the current session name | `/name` |
+| Clear the current session name | `/session 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` |

data/doc/skills.md

@@ -0,0 +1,199 @@
+# Skills
+
+Skills are reusable instructions that Kward loads only when they are useful. They are good for workflows such as testing, code review, release checks, writing documentation, or working in a domain with specific rules.
+
+Kward supports the Agent Skills folder format: each skill is a directory with a `SKILL.md` file. Kward shows the model only each skill's name and description at startup. The full instructions are loaded later, either when the model decides they match the task or when you activate the skill yourself.
+
+## When to use a skill
+
+Use a skill when you want specialized guidance that should not be in every prompt.
+
+Good skill examples:
+
+- testing practices for your project
+- release checklist steps
+- API review rules
+- incident response workflow
+- documentation style guidance
+- domain-specific terminology and examples
+
+Use `AGENTS.md` instead for repository-wide rules that should apply to almost every task. Use prompt templates when you want to expand a reusable user prompt with arguments.
+
+## Create a skill
+
+A minimal skill looks like this:
+
+```text
+~/.agents/skills/testing/SKILL.md
+```
+
+```markdown
+---
+name: testing
+description: Use when adding or changing tests, fixing regressions, or verifying behavior.
+---
+
+Prefer focused tests near the changed behavior.
+Do not weaken assertions to make tests pass.
+Run the smallest relevant test first, then broaden if needed.
+```
+
+The `name` and `description` fields are required. The description matters: Kward puts it in the skill catalog so the model can decide when to load the skill.
+
+Skill names should be lowercase letters, numbers, and hyphens, such as `testing`, `code-review`, or `release-checklist`.
+
+## Skill locations
+
+User-level skills are available in every project:
+
+```text
+~/.kward/skills/<name>/SKILL.md
+~/.agents/skills/<name>/SKILL.md
+```
+
+Project-level skills live in the current workspace:
+
+```text
+<workspace>/.kward/skills/<name>/SKILL.md
+<workspace>/.agents/skills/<name>/SKILL.md
+```
+
+The `.agents/skills` paths are the cross-client Agent Skills convention. Use them when you want skills to work across compatible agents.
+
+Project skills are skipped by default because repository-provided instructions may be untrusted. If you trust the repository, enable project skills from inside Kward:
+
+```text
+/settings
+```
+
+Then choose:
+
+```text
+Tools & Search → Trust project skills
+```
+
+Or set it manually:
+
+```json
+{
+  "skills": {
+    "trust_project": true
+  }
+}
+```
+
+## How Kward uses skills
+
+Kward uses progressive loading:
+
+1. At startup, Kward lists available skill names and descriptions in the system prompt.
+2. When a task matches a skill, the model calls `read_skill` to load `SKILL.md`.
+3. If the skill references supporting files, the model reads only the needed files.
+
+You can also activate a skill explicitly:
+
+```text
+/skill testing
+```
+
+or:
+
+```text
+/skill:testing
+```
+
+Explicit activation loads the skill instructions into the current conversation without asking the model to infer that the skill is relevant.
+
+Activated skills are preserved during context compaction, so Kward does not silently forget the workflow in a long session.
+
+## Add supporting files
+
+A skill can include extra files:
+
+```text
+~/.agents/skills/release-checklist/
+├── SKILL.md
+├── references/
+│   └── versioning.md
+├── scripts/
+│   └── check_changelog.rb
+└── assets/
+    └── release-template.md
+```
+
+Example `SKILL.md`:
+
+```markdown
+---
+name: release-checklist
+description: Use when preparing a release, updating versions, or writing changelog entries.
+---
+
+Follow the release checklist:
+
+1. Read `references/versioning.md`.
+2. Confirm `CHANGELOG.md` has an Unreleased entry.
+3. If needed, inspect `assets/release-template.md`.
+4. Run `scripts/check_changelog.rb` before proposing the final release notes.
+```
+
+When Kward loads the skill, it lists bundled files under `references/`, `scripts/`, and `assets/` without reading all of them. The model can then request a specific file with `read_skill`, using a path relative to the skill directory.
+
+For example, the model can call:
+
+```json
+{
+  "name": "release-checklist",
+  "path": "references/versioning.md"
+}
+```
+
+Paths are constrained to the skill directory. Absolute paths and `..` traversal outside the skill are rejected.
+
+## Discovery precedence
+
+If multiple skills have the same `name`, Kward uses the first one in this order:
+
+1. `<workspace>/.kward/skills`
+2. `<workspace>/.agents/skills`
+3. Kward config directory `skills` (`~/.kward/skills` by default, or beside `KWARD_CONFIG_PATH`)
+4. `~/.agents/skills`
+
+Shadowed skills are skipped with a warning. Rename one of the skills if you want both to be available.
+
+## Optional metadata
+
+Kward understands these optional `SKILL.md` frontmatter fields:
+
+```yaml
+license: MIT
+compatibility: Requires git and Ruby.
+metadata:
+  author: example-team
+  version: "1.0"
+allowed-tools: Bash(git:*) Read
+```
+
+`allowed-tools` is parsed for compatibility with the Agent Skills format, but Kward does not currently use it to grant extra permissions. Treat skill scripts and instructions as trusted only when you trust their source.
+
+## Troubleshooting
+
+If a skill does not appear:
+
+- Check that the file is named exactly `SKILL.md`.
+- Check that `name` and `description` are present in frontmatter.
+- Check that the directory name and skill name are sensible and unique.
+- If it is a project skill, make sure project skills are trusted in `/settings`.
+- Look for warnings about skipped, malformed, or shadowed skills.
+
+If a skill activates but cannot read a supporting file, make sure the path is relative to the skill directory, for example:
+
+```text
+references/details.md
+```
+
+not:
+
+```text
+../other-skill/details.md
+```

data/doc/usage.md

@@ -94,7 +94,7 @@ kward login                    # sign in or save credentials
 kward auth status              # show credential status without secrets
 kward sysprompt                # inspect assembled instructions
 kward stats tokens             # export local token telemetry as CSV
-kward rpc                      # start the experimental RPC backend
+kward rpc                      # start the RPC backend for trusted local UI clients
 ```
 
 Use another workspace without changing directories:
@@ -135,9 +135,9 @@ Slash commands run local actions in the current session. Most do not send a prom
 | `/tab close` | close the active tab. |
 | `/tab new` | open a new tab. |
 | `/tab name <label>` | rename the active tab label. |
-| `/sessions` | open the saved sessions picker or continue a previous session by path. |
-| `/resume` | alias for `/sessions`. |
-| `/name <name>` | name or clear the current session. |
+| `/session` | open the saved sessions picker or continue a previous session by path. |
+| `/resume` | alias for `/session`. |
+| `/session name <name>` | name or clear the current session. |
 | `/rename <name>` | rename the current session. |
 | `/clone` | copy the current session into a new branch. |
 | `/rewind` | revisit an earlier prompt and try a different direction. |
@@ -208,10 +208,10 @@ Typical flow:
 Later:
 
 ```text
-/sessions
+/session
 ```
 
-In the sessions picker, press `r` to rename the highlighted session, `c` to clone it, `f` to fork from an earlier prompt, or `d` twice to delete it. `/resume` remains available as an alias for `/sessions`.
+In the sessions picker, press `r` to rename the highlighted session, `c` to clone it, `f` to fork from an earlier prompt, or `d` twice to delete it. `/resume` remains available as an alias for `/session`.
 
 For the full guide to context management, cloning, forking, rewinding, `/tree`, compaction, and exports, read [Sessions](session-management.md).
 
@@ -280,4 +280,4 @@ Use it only on trusted networks. It exposes the same file, shell, and web tools
 
 ## RPC backend
 
-`kward rpc` starts the experimental JSON-RPC backend for UI clients and editor integrations. Terminal users can ignore it. Integration authors should read [RPC protocol](rpc.md).
+`kward rpc` starts the JSON-RPC backend for trusted local UI clients and editor integrations. Terminal users can ignore it. Integration authors should read [RPC protocol](rpc.md).