kward 0.71.0 → 0.73.0

data/doc/getting-started.md

@@ -18,13 +18,21 @@ Install the gem:
 gem install kward
 ```
 
-Install the starter pack:
+Optionally install the starter pack:
 
 ```bash
 kward init
 ```
 
-The starter pack adds default prompts and a base `PRINCIPLES.md` under `~/.kward`. It does not overwrite existing files.
+The starter pack adds default prompts and a base `PRINCIPLES.md` under `~/.kward`. It does not overwrite existing files. It is safe to skip if you prefer to create your own instructions. It requires network access because it fetches the pack from GitHub.
+
+Verify your setup:
+
+```bash
+kward doctor
+```
+
+This checks your config, auth, writable directories, and workspace. Run `kward help` to see all available commands and examples.
 
 If you are working from a checkout instead:
 
@@ -49,6 +57,14 @@ Or from inside an interactive session:
 
 Kward supports OpenAI/ChatGPT, Anthropic Claude Pro/Max, OpenRouter, and experimental Copilot credentials. See [Authentication](authentication.md) when you need a specific provider.
 
+Confirm your credentials are saved:
+
+```bash
+kward auth status
+```
+
+If your provider offers multiple models, choose one inside Kward with `/model`.
+
 ## Start an interactive chat
 
 Run Kward from the project you want it to work on:
@@ -58,6 +74,12 @@ cd ~/code/my-project
 kward
 ```
 
+Or point Kward at a project without leaving your shell:
+
+```bash
+kward --working-directory ~/code/my-project
+```
+
 Ask something concrete:
 
 ```text
@@ -88,7 +110,7 @@ git diff | kward "Review this diff for bugs"
 
 One-shot prompts do not use Kward memory.
 
-## Useful first commands
+## Useful interactive commands
 
 Inside interactive Kward:
 
@@ -97,27 +119,12 @@ Inside interactive Kward:
 /model              choose a model
 /status             show session and context status
 /sessions           open the saved sessions picker
-/resume             alias for /sessions
 /rewind             revisit an earlier prompt
 /export notes.md    export the transcript
 /compact            summarize older context when a chat gets long
 /exit               leave Kward
 ```
 
-## Run from source
-
-```bash
-ruby lib/main.rb login
-ruby lib/main.rb
-ruby lib/main.rb "Explain this project"
-```
-
-You can also run:
-
-```bash
-exe/kward
-```
-
 ## Next steps
 
 - Read [Usage](usage.md) for day-to-day workflows.

data/doc/git.md

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

data/doc/memory.md

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

data/doc/personas.md

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

data/doc/plugins.md

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

data/doc/releasing.md

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