kward 0.76.0 → 0.78.0

data/doc/permissions.md

@@ -0,0 +1,179 @@
+# Permissions
+
+Kward's permission policy lets you put a human decision between a model-requested tool call and its side effect. It is useful when you want the agent to inspect a project freely, but want to confirm edits, commands, web requests, or MCP calls as they arise.
+
+Permissions are **off by default**. Enabling them does not sandbox Kward or its subprocesses: an allowed shell command still runs with your operating-system user permissions.
+
+## Start with approval mode
+
+Add this to `~/.kward/config.json`, or enable it through your usual configuration workflow:
+
+```json
+{
+  "permissions": {
+    "enabled": true,
+    "mode": "ask"
+  }
+}
+```
+
+In `ask` mode, Kward allows ordinary read-only tools and asks before the agent:
+
+- writes or edits a workspace file,
+- runs `run_shell_command`,
+- searches or fetches content on the web,
+- calls an MCP tool.
+
+When approval is required in the interactive CLI, Kward opens a modal overlay. It shows the complete tool arguments, so an approval for `read_skill` includes the requested skill name and relative path, and an approval for a write includes its path and content. Choose **Allow once** to run that one call, **Allow this tool for this session** to allow later calls to the same tool in the current Kward session, or **Deny** to stop it. Pressing `Esc`, cancelling the overlay, or losing the approval bridge denies the call.
+
+### Steer the agent with `Type something`
+
+**Type something** is more than a denial. It stops the requested tool call and sends your text back to the agent as the tool result, so you can redirect its workflow without waiting for it to finish a wrong turn.
+
+For example, the agent may propose this command:
+
+```text
+run_shell_command: grep -R "Permission" lib test
+```
+
+Choose **Type something** and enter:
+
+```text
+Use ack instead of grep; it is installed here and respects our ignore files.
+```
+
+Kward does not run `grep`. The agent receives:
+
+```text
+Declined: Use ack instead of grep; it is installed here and respects our ignore files.
+```
+
+It can then continue by choosing an `ack` command. This is useful for steering details that are difficult to encode in a static rule, such as:
+
+- use the project’s preferred formatter or test runner;
+- run a focused test rather than the full suite;
+- use a local mirror or a documented API endpoint;
+- explain a proposed database command before running it;
+- choose an existing project script instead of inventing a new command.
+
+The typed response is part of the conversation, just like a normal follow-up message. It is stored in the session and may be sent to the active model provider. Do not put secrets in it unless that is acceptable for your selected provider and retained session data.
+
+Use this mode first when working in an unfamiliar repository or when you want to review an agent's actions without preventing ordinary exploration.
+
+## Choose a mode
+
+Set `permissions.mode` to one of these values:
+
+| Mode | Good for | Default behavior |
+| --- | --- | --- |
+| `ask` | Interactive supervised work | Asks before file changes, shell commands, web tools, and MCP tools. |
+| `workspace-write` | Routine edits in selected paths | Allows file changes in `write_scopes`; still asks before shell, web, and MCP tools. |
+| `read-only` | Code review and investigation | Denies risky tools by default. |
+| `deny-by-default` | Automation or tightly controlled runs | Denies risky tools unless an `allow` rule matches. |
+
+All modes leave ordinary read-only Kward tools available. Rules can make a decision more specific; see [Rules and precedence](#Rules_and_precedence).
+
+## Let Kward edit only selected paths
+
+Use `workspace-write` when you want routine changes in known source and test directories without an approval prompt for each edit:
+
+```json
+{
+  "permissions": {
+    "enabled": true,
+    "mode": "workspace-write",
+    "write_scopes": ["lib/**", "test/**"]
+  }
+}
+```
+
+With this configuration, the agent may edit `lib/` and `test/` without asking. A proposed edit to `README.md` or `config/` is denied by the policy.
+
+`write_scopes` narrows the policy's default workspace-write behavior; it does not broaden Kward's built-in workspace boundary. File tools still stay inside the active workspace by default, and existing files must still be read before Kward can edit them. See [Workspace tools](workspace-tools.md) for those guardrails.
+
+An empty `write_scopes` array permits no default workspace writes. Omit `write_scopes` if you want the `workspace-write` mode to cover the normal workspace file-tool boundary.
+
+## Rules and precedence
+
+Use `allow`, `ask`, and `deny` arrays to describe exceptions. A rule can match these fields:
+
+- `tool` — a model tool name, such as `run_shell_command` or `write_file`;
+- `path` — the file-tool path supplied by the model;
+- `command` — the requested shell command text;
+- `host` — the host in a `fetch_content` or `fetch_raw` URL;
+- `source` — currently useful for `mcp` tools.
+
+Patterns support `*` within a path segment and `**` across directories. Rule matching is case-sensitive.
+
+```json
+{
+  "permissions": {
+    "enabled": true,
+    "mode": "ask",
+    "allow": [
+      { "tool": "write_file", "path": "doc/**" },
+      { "tool": "fetch_content", "host": "docs.ruby-lang.org" }
+    ],
+    "ask": [
+      { "tool": "run_shell_command", "command": "bundle exec *" }
+    ],
+    "deny": [
+      { "tool": "run_shell_command", "command": "git push*" },
+      { "tool": "write_file", "path": "**/.env" }
+    ]
+  }
+}
+```
+
+Kward evaluates matching rules in this order:
+
+1. `deny`
+2. `ask`
+3. `allow`
+4. the selected mode's default
+
+A matching deny always wins. An ask rule wins over an allow rule. Keep rules narrow and easy to explain; prefer an exact command or a small path scope over a broad wildcard.
+
+## A practical workflow
+
+For a normal coding task:
+
+1. Enable `ask` mode.
+2. Ask Kward to inspect the project and propose a change.
+3. Approve the file edit after checking its path and intent.
+4. Approve a focused test command, or choose **Type something** to redirect it—for example, “run `bin/test unit` instead of the full suite.”
+5. Review the diff and `git status` as usual.
+
+If you repeatedly work in one source tree, move to `workspace-write` with narrow write scopes. Keep shell and network calls in approval mode unless you have a well-understood policy for them.
+
+## RPC and Pan
+
+RPC clients can continue to use the existing per-turn approval bridge:
+
+```json
+{
+  "approvalMode": "ask"
+}
+```
+
+That requests an approval notification for every tool call in that turn. The global permission policy is an additional restriction: a deny rule prevents the call even if the RPC client would approve it. If the global policy requires approval, a frontend without an approval bridge fails closed.
+
+Pan currently has no dedicated approval interface. With permissions enabled, a Pan session cannot approve a policy `ask` decision, so Kward denies it. Use `read-only`, explicit allows, or a CLI/RPC frontend when approvals are needed.
+
+## Limits: policy is not a sandbox
+
+The policy runs before Kward dispatches a model-requested tool. It does not constrain what happens after a shell command starts. In particular:
+
+- a permitted shell command can access files, processes, credentials, and network services available to your user account;
+- command-text rules are useful review controls, not a reliable way to enforce network destinations or all subprocess behavior;
+- direct commands that you type yourself—`!command`, `/shell`, and `/pty`—are treated as your actions and are outside this first policy scope;
+- plugins, hooks, and MCP servers are trusted local extensions with their own process access.
+
+For sensitive work, use a restricted operating-system account, container, virtual machine, or disposable checkout. A future OS-enforced sandbox may provide stronger filesystem and network isolation; it is not part of the current permissions feature.
+
+## Related guides
+
+- [Security and trust](security.md): trust boundaries, extensions, and safe work in unfamiliar repositories.
+- [Configuration](configuration.md#Permissions): the complete configuration reference.
+- [Lifecycle hooks](lifecycle-hooks.md): add trusted local policy or automation around Kward events.
+- [RPC protocol](rpc.md#Tool_approval_bridge): implement the approval bridge in an RPC client.

data/doc/plugins.md

@@ -178,6 +178,64 @@ Returning `:exit` from the tick callback ends the loop, same as calling
 Interactive commands require the TUI prompt interface. They are not available
 in piped/non-interactive mode or through RPC.
 
+## Add a plugin-owned tab
+
+A plugin can provide a persistent tab with Kward's normal composer, transcript
+rendering, streaming, image input, cancellation, and tab switching. The plugin
+owns its transcript, storage, model behavior, and any global state; it does not
+need to use a Kward workspace session.
+
+```ruby
+Kward.plugin do |plugin|
+  plugin.tab_type "example", id: "com.example.chat", title: "Example", singleton: :global do |host, descriptor|
+    ExampleChat.new(client: host.client, descriptor: descriptor)
+  end
+end
+```
+
+Open it from interactive Kward:
+
+```text
+/tab open example
+```
+
+`id` is a stable persisted identifier: do not change it after release.
+Use `singleton: :global` for one plugin-managed chat shared by all tab views.
+
+Plugin tabs do not notify global transcript observers by default. Set
+`transcript_events: true` only when the tab explicitly permits its streamed
+content to be delivered to every installed `on_transcript_event` handler, such
+as a local text-to-speech plugin:
+
+```ruby
+plugin.tab_type "example", id: "com.example.chat", transcript_events: true do |host, descriptor|
+  ExampleChat.new(client: host.client, descriptor: descriptor)
+end
+```
+
+The observer context exposes the plugin tab's `messages` through
+`ctx.transcript.messages`; it has no workspace session. The tab driver returned by the block must provide:
+
+- `messages` — renderable transcript messages;
+- `submit(input, display_input:, cancellation:, steering:)` — a turn method
+  that returns the final response and yields stream events;
+- `descriptor` — the durable tab descriptor;
+- `supports_steering?` and `assistant_label`.
+
+A driver may optionally implement `handles_command?(input)` and
+`handle_command(input)` for its own slash commands. Other Kward session and
+workspace commands stay unavailable inside plugin tabs.
+
+Set `rpc: true` when the plugin tab can also be exposed as a trusted local RPC chat:
+
+```ruby
+plugin.tab_type "example", id: "com.example.chat", rpc: true do |host, descriptor|
+  ExampleChat.new(client: host.client, descriptor: descriptor)
+end
+```
+
+RPC clients discover opted-in types through `initialize.capabilities.pluginChats`, open a chat with `pluginChats/open`, and must explicitly subscribe before receiving live `pluginChat/event` notifications. See [RPC](rpc.md) for the protocol. Plugin tabs remain CLI-only unless they opt in.
+
 ## Observe transcript events
 
 Use transcript events when you need to log or react to live activity:

data/doc/rpc.md

@@ -52,6 +52,7 @@ Detailed capability fields include:
 - `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.
+- `pluginChats`: optional plugin-owned chats. The capability lists opted-in chat types and methods. Clients must explicitly subscribe before receiving `pluginChat/event` notifications; plugin chats are independent from workspace sessions.
 - `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.
@@ -67,7 +68,6 @@ 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 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.
 - `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.
@@ -277,6 +277,66 @@ Moves the active branch to the selected tree entry. If the entry is a user messa
 
 Returns `{ "session": {}, "editorText": "...", "cancelled": false, "aborted": false }`. Fields with no value are omitted.
 
+## Plugin chat methods
+
+Plugin chats are optional trusted-plugin capabilities, not Kward workspace sessions. When `initialize.capabilities.pluginChats.supported` is true, use `pluginChats/list` to discover available types.
+
+### `pluginChats/open`
+
+Params:
+
+- `typeId`: an opted-in plugin chat type, such as `kward.maria`.
+
+Opens the plugin-owned chat in this RPC process and returns its metadata plus normalized transcript.
+
+### `pluginChats/transcript`
+
+Params:
+
+- `chatId`;
+- `limit`: optional bounded page size for plugin drivers that support transcript paging;
+- `before`: optional opaque cursor returned by a preceding page.
+
+Returns chat metadata and its normalized transcript. Paging-capable plugin chats return the newest page first plus `hasMore` and, when more history is available, `nextBefore`. Clients send that cursor as `before` to load the preceding page. Plugins that do not opt in retain the original complete-transcript behavior.
+
+### `pluginChats/subscribe` and `pluginChats/unsubscribe`
+
+Params:
+
+- `chatId`.
+
+Subscriptions are opt-in. `pluginChats/subscribe` enables live `pluginChat/event` notifications for that chat on the current RPC connection. `pluginChats/unsubscribe` disables them without affecting the chat or archive.
+
+### `pluginChats/turns/start`
+
+Params:
+
+- `chatId`;
+- `input`;
+- `attachments`: optional base64 image attachments using the same MIME and size limits as `turns/start`.
+
+Queues a plugin-chat turn and returns `{ id, chatId, status, ... }`. Plugin chat turns are serialized per chat and do not use workspace sessions, agents, or model overrides.
+
+### `pluginChats/turns/cancel`, `pluginChats/turns/status`, `pluginChats/turns/events`, `pluginChats/turns/list`, `pluginChats/turns/listActive`
+
+These methods mirror the corresponding `turns/*` lifecycle methods, using `chatId` where a list filter is needed. Event replay is bounded in memory and subscriptions are required for live notifications.
+
+## Plugin chat notifications
+
+Subscribed clients receive `pluginChat/event` notifications:
+
+```json
+{
+  "chatId": "kward.maria",
+  "turnId": "...",
+  "sequence": 1,
+  "type": "assistantDelta",
+  "payload": { "delta": "text" }
+}
+```
+
+Known event types are `turnQueued`, `turnStarted`, `reasoningDelta`, `reasoningBoundary`, `assistantDelta`, `assistantMessage`, `toolCall`, `toolResult`, `answer`, `turnCancelRequested`, and `turnFinished`.
+
 ## Turn methods
 
 Turns are asynchronous. A session queues turns sequentially; only one turn runs per session at a time.
@@ -784,27 +844,6 @@ 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.

data/doc/security.md

@@ -0,0 +1,184 @@
+# Security and trust
+
+Kward can read code, edit files, run commands, call model and search providers, and load local extensions. That makes it useful, but it also means you should treat it like a developer tool running with your account—not like a sandbox.
+
+This guide explains the trust boundaries and gives you a safe way to start work in an unfamiliar repository.
+
+## The short version
+
+- Kward and anything it launches run with your operating-system permissions.
+- File tools stay inside the active workspace by default, but shell commands are not sandboxed.
+- Existing files must be read before Kward's file tools can edit or overwrite them.
+- Plugins, MCP servers, command hooks, and HTTP hooks should be configured only from sources and endpoints you trust.
+- Project skills and workspace hooks are disabled until you opt in or trust them.
+- Prompts, selected file contents, tool results, and conversation history may be sent to the active model provider as needed to answer a request.
+- Web searches, fetched URLs, MCP calls, and HTTP hooks can send additional data to their respective services.
+
+If a task involves secrets, production credentials, customer data, or an untrusted repository, narrow the workspace and tools before asking Kward to act.
+
+## A safe first run in an unfamiliar repository
+
+Start with project-provided extensions disabled, which is the default:
+
+```bash
+cd ~/code/unfamiliar-project
+kward doctor
+kward
+```
+
+Then use a read-first workflow:
+
+```text
+Inspect the project structure and its AGENTS.md. Do not edit files or run project scripts yet. Tell me what instructions, hooks, skills, plugins, generated files, and risky setup commands I should review first.
+```
+
+Before enabling or running anything:
+
+1. Read the workspace `AGENTS.md` and any referenced instructions.
+2. Inspect `.kward/hooks.json`, `.kward/skills/`, and `.agents/skills/` yourself.
+3. Review setup scripts, package hooks, build files, and shell commands before allowing them to run.
+4. Keep project skills disabled unless you trust their instructions.
+5. Trust workspace hooks only after reviewing the full file with `kward hooks doctor` and `kward hooks trust`.
+6. Do not add repository-provided Ruby files to `~/.kward/plugins` unless you are willing to run them as your user.
+7. Ask Kward to explain proposed edits and commands before applying them when the impact is unclear.
+
+For especially sensitive work, use a disposable checkout, container, virtual machine, or restricted operating-system account. Kward's own guardrails do not replace operating-system isolation.
+
+## Workspace access is a guardrail, not a sandbox
+
+Kward's built-in file tools normally resolve paths inside the active workspace. They reject paths outside that boundary, and existing files must be read in the current conversation before `write_file` or `edit_file` can change them.
+
+These protections reduce accidental edits. They do not contain the whole process:
+
+- `run_shell_command`, `!command`, `/shell`, and `/pty` run with your user permissions.
+- A shell command can access files, environment variables, processes, and networks available to your account.
+- Plugins, command hooks, and MCP servers are local processes with the same general operating-system access.
+- Read-before-edit applies to Kward's file tools, not to arbitrary shell commands or extension code.
+
+You can disable the file boundary with `tools.workspace_guardrails: false`, but doing so broadens file-tool access and is rarely needed. See [Workspace tools](workspace-tools.md) for exact limits and [Configuration](configuration.md#Tool_workspace_guardrails) for the setting.
+
+## Tool approvals and policy hooks
+
+The interactive CLI does not ask for blanket approval before every tool call. Built-in guardrails and configured lifecycle hooks still apply, but ordinary file and shell tools can run during a turn.
+
+RPC clients can request per-turn approval with `approvalMode: "ask"`. Kward then emits `tool/approvalRequested` before each tool executes and waits for the client to answer. The default RPC approval mode is `none`.
+
+Lifecycle hooks can add deterministic policy around tools, shell commands, files, Git actions, model requests, and other events. A hook can allow, deny, modify supported data, warn, or ask for approval. An `ask` decision fails closed when the frontend has no approval bridge.
+
+Pan mode does not provide a dedicated hook-approval UI. Use `deny` or `warn` for Pan-facing policies instead of depending on interactive approval.
+
+See [Lifecycle hooks](lifecycle-hooks.md) for policy examples and [RPC protocol](rpc.md#Tool_approval_bridge) for the approval contract.
+
+## Opt-in permission policy
+
+`permissions.enabled` is off by default. When enabled, Kward can allow, ask, or deny model-requested file changes, shell commands, web tools, and MCP tools before execution. The interactive CLI uses an approval overlay; an unavailable approval bridge fails closed. The policy is not a sandbox: after Kward permits a shell command, it still runs with the permissions of your user account. See [Permissions](permissions.md) for workflows, modes, rules, and limits.
+
+## Know what you are trusting
+
+### Workspace instructions
+
+A repository-level `AGENTS.md` is guidance for the model, not executable code. Kward tells the model to read it for repository tasks. Instructions can still influence what the model proposes or which tools it calls, so review unfamiliar guidance just as you would review a contributor script.
+
+### Project skills
+
+Project skills under `.kward/skills/` and `.agents/skills/` are skipped by default. Enable them only after reviewing their `SKILL.md` instructions and supporting files:
+
+```text
+/settings → Tools & Search → Trust project skills
+```
+
+This setting trusts project skills generally; it is not a per-repository digest. A skill's `allowed-tools` metadata does not grant permissions or constrain tools in Kward.
+
+### Workspace hooks
+
+Project hooks in `.kward/hooks.json` run only after `/hooks trust`. Trust is tied to the file digest, so a change invalidates it and requires another review. Command hooks execute local commands; HTTP hooks send event data to their configured endpoint.
+
+### Plugins
+
+Ruby plugins in `~/.kward/plugins/*.rb` run inside the Kward process with your permissions. They can read files and environment variables, write files, run commands, and make network requests. Kward intentionally does not load plugins from a workspace directory.
+
+### MCP servers
+
+Configured MCP servers are local child processes. Their tools can expose application state such as browser pages, console messages, network traffic, or screenshots. Kward currently supports local stdio servers, but local transport does not make an untrusted server safe.
+
+Only add commands you trust to `mcpServers`, and review any environment variables supplied to them. See [MCP servers](mcp.md).
+
+## What leaves your machine
+
+### Model providers
+
+To answer a turn, Kward sends the assembled conversation context to the active model provider. Depending on the task, that context can include:
+
+- your prompts and prior conversation,
+- system instructions, personas, skills, memory, and plugin context,
+- file content read into the conversation,
+- shell and tool results,
+- images you attach,
+- summaries produced during compaction.
+
+Provider retention and training policies are controlled by the provider and your account or organization. Do not give Kward content you are not permitted to send to that provider.
+
+### Web tools
+
+Search queries go to the selected search provider. `fetch_content` and `fetch_raw` request the URL you provide or the model selects. Disable web tools when external lookup is inappropriate:
+
+```json
+{
+  "web_search": {
+    "enabled": false
+  }
+}
+```
+
+See [Web search](web-search.md#Network_behavior) for provider order and request behavior.
+
+### Hooks and MCP
+
+HTTP hook payloads can include prompts, commands, file paths, tool arguments, and selected event results. Avoid forwarding raw events to third parties. Git and file after-events may include command output or changed content.
+
+MCP tool arguments and results pass between Kward and the configured server. What the MCP server stores or forwards is determined by that server.
+
+## Local data and permissions
+
+Kward keeps user data under `~/.kward` by default, or mostly beside `KWARD_CONFIG_PATH` when that override is set.
+
+| Data | Typical location | Notes |
+| --- | --- | --- |
+| Main config and OpenRouter key | `~/.kward/config.json` | Do not commit or share it. |
+| OAuth credentials | `~/.kward/auth.json`, `anthropic_auth.json`, `github_auth.json` | Written with mode `0600` when possible. |
+| Sessions and tool results | `~/.kward/sessions/` | Conversation, file/tool output, and compaction history; files use mode `0600`. |
+| Prompt history | `~/.kward/history/` | Workspace-scoped submitted prompts; files use mode `0600`. |
+| Memory | `~/.kward/memory/` | Off by default; directory `0700` and files `0600`. |
+| Telemetry logs | `~/.kward/logs/` | Off by default; redacted metadata, not intentional prompt or file-content logging. |
+| Plugins | `~/.kward/plugins/` | Trusted Ruby code, not private data storage. |
+| Hook audit log and trust records | `~/.kward/logs/`, `~/.kward/trusted_workspace_hooks.json` | Audit records use redacted metadata rather than raw event values. |
+
+Private file modes help on normal Unix-like systems but do not protect data from your own account, privileged users, backups, malware, or a compromised machine. Session exports are written to the path you choose and should be protected separately.
+
+Use these commands to inspect or remove stored credentials and context:
+
+```bash
+kward auth status
+kward auth logout
+```
+
+```text
+/session
+/memory list
+/memory forget <id>
+```
+
+See [Authentication](authentication.md), [Sessions](session-management.md), [Memory](memory.md), and [Configuration](configuration.md#Logging_and_stats) for retention and management details.
+
+## Practical habits
+
+- Keep secrets out of prompts, screenshots, shell output, plugin context, and hook messages.
+- Prefer temporary environment variables to storing short-lived API keys in config.
+- Disable web search for private work that should not trigger external requests.
+- Keep memory off unless cross-session recall is useful and appropriate.
+- Review diffs and `git status` before committing agent changes.
+- Treat generated commands as suggestions you are responsible for running.
+- Use `kward sysprompt` to inspect instructions assembled for a new conversation.
+- Run `kward doctor` and `kward hooks doctor` when configuration or trust behavior is unclear.
+
+Security here is layered: Kward supplies guardrails and explicit trust controls, while real isolation and least privilege come from the environment in which you run it.

data/doc/tabs.md

@@ -2,7 +2,7 @@
 
 Use tabs when you want more than one Kward conversation open in the same interactive terminal session.
 
-Each tab has its own session-backed conversation, transcript, composer state, and running agent turn. That makes tabs useful for splitting work without losing your place: one tab can investigate a bug, another can draft docs, and a third can wait on a long-running answer.
+Normal tabs have their own session-backed conversation, transcript, composer state, and running agent turn. Plugins can also provide their own persistent tab types while Kward continues to supply the same composer and tab behavior. This makes tabs useful for splitting work without losing your place: one tab can investigate a bug, another can draft docs, and a third can wait on a long-running answer.
 
 ## Quick start
 
@@ -56,6 +56,7 @@ Tabs keep the conversations separate, so context from one tab does not automatic
 | Command | Action |
 | ------- | ------ |
 | `/tab new` | Open a new tab with a fresh conversation |
+| `/tab open <plugin-tab>` | Open a plugin-provided tab, such as a persistent companion chat. |
 | `/tab 1` through `/tab 9` | Switch to a numbered tab |
 | `/tab close` | Close the current tab |
 | `/tab name <label>` | Rename the current tab |
@@ -110,9 +111,9 @@ Slash commands such as `/tab` still work while a tab is busy, so you can switch
 
 ## Persistence
 
-Tabs are backed by normal Kward sessions. Kward stores the open tab list, labels, and active tab per workspace, then restores them the next time you start interactive Kward in that workspace.
+Normal tabs are backed by Kward sessions. Plugins may also provide their own tab types; those tabs own their transcript and persistence independently of Kward sessions.
 
-The tab layout is stored in Kward's config directory under `tabs/`. Session transcripts stay in the normal sessions directory. See [Sessions](session-management.md) for session naming, resuming, forking, exporting, and cleanup.
+Kward stores the open tab list, labels, and active tab per workspace, then restores them the next time you start interactive Kward in that workspace. The tab layout is stored in Kward's config directory under `tabs/`. Session transcripts stay in the normal sessions directory. See [Sessions](session-management.md) for session naming, resuming, forking, exporting, and cleanup.
 
 ## Notes and limitations