kward 0.66.0

data/doc/memory.md

@@ -0,0 +1,192 @@
+# Memory
+
+Kward has an opt-in structured memory system for interactive sessions. Memory is designed to be inspectable, explainable, and removable. It is disabled by default.
+
+Memory is not used for one-shot prompts such as `kward "..."`.
+
+Use memory when you want Kward to remember stable preferences, recurring project facts, or personal workflow habits across interactive sessions. Leave it disabled when you want every session to start clean.
+
+## Enable or disable memory
+
+In interactive chat:
+
+```text
+/memory enable
+/memory disable
+```
+
+Enabling memory stores this config in `~/.kward/config.json`:
+
+```json
+{
+  "memory": {
+    "enabled": true
+  }
+}
+```
+
+When memory is disabled, Kward does not inject retrieved memories into the prompt.
+
+## Auto-summary
+
+Memory auto-summary is off by default. When both memory and auto-summary are enabled, Kward quietly runs the same learning flow as `/memory summarize` after each completed interactive agent turn, when it is ready for the next user prompt:
+
+```text
+/memory auto-summary enable
+/memory auto-summary disable
+```
+
+The config value is stored as:
+
+```json
+{
+  "memory": {
+    "enabled": true,
+    "auto_summary": true
+  }
+}
+```
+
+Auto-summary does not run when memory is disabled and is not used for one-shot prompts.
+
+## Memory layers
+
+### 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:
+
+```text
+/memory core "Prefer small, focused patches with tests."
+```
+
+Core memories are stored as human-readable JSON in:
+
+```text
+~/.kward/memory/core.json
+```
+
+### 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:
+
+```text
+/memory add "This workspace usually uses Minitest."
+```
+
+Soft memories are stored as JSON Lines in:
+
+```text
+~/.kward/memory/soft.jsonl
+```
+
+Kward can also infer soft memories when auto-summary is enabled, or when you explicitly ask it to summarize/learn from the current session:
+
+```text
+/memory summarize
+```
+
+The v1 inference is conservative and heuristic-based, with optional model-based reformulation when summarization has an available client. Kward refuses to automatically persist inferred emotional, intimate, romantic, or dependency-forming memories.
+
+### Session memories
+
+Session memories record memories learned during the current conversation so Kward can avoid learning the same item again when summarizing or resuming the session. They are stored with the session JSONL file, but they are not injected into the prompt as a separate memory layer and are not automatically promoted into core memories.
+
+## Inspect, explain, and remove memory
+
+List memories:
+
+```text
+/memory list
+```
+
+Inspect memory state and file paths:
+
+```text
+/memory inspect
+```
+
+Explain why memories were retrieved for the most recent interactive turn:
+
+```text
+/memory why
+```
+
+Forget a memory:
+
+```text
+/memory forget core_001
+/memory forget soft_001
+```
+
+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:
+
+```text
+/memory promote soft_001
+```
+
+Promotion creates a new core memory and marks the soft memory forgotten.
+
+## 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
+- soft-memory confidence
+- soft-memory recency/TTL, updated when a soft memory is retrieved
+- hard limits on injected memory count
+
+Retrieved memories are injected into the system prompt as a bounded block similar to:
+
+```text
+<kward_memory>
+Core Memories:
+- [core_001] ...
+
+Relevant Soft Memories:
+- [soft_001] ...
+
+Rules:
+- Core memories override soft memories.
+- Soft memories are contextual hints, not guaranteed facts.
+</kward_memory>
+```
+
+Kward never injects every stored memory.
+
+## Storage and audit trail
+
+Default files:
+
+```text
+~/.kward/memory/core.json
+~/.kward/memory/soft.jsonl
+~/.kward/memory/events.jsonl
+```
+
+`events.jsonl` records minimal audit events such as enable, disable, add, forget, promote, retrieve, and summarize. Audit events use IDs, scopes, tags, and timestamps rather than full memory text where practical. Forgotten soft memories keep inactive metadata in `soft.jsonl`, but their stored text is replaced with `[forgotten]`.
+
+If `KWARD_CONFIG_PATH` is set, memory files live beside that config file instead of under `~/.kward`.
+
+## RPC methods
+
+The experimental RPC backend exposes dedicated memory methods:
+
+- `memory/status`
+- `memory/enable`
+- `memory/disable`
+- `memory/autoSummary/enable`
+- `memory/autoSummary/disable`
+- `memory/list`
+- `memory/add`
+- `memory/addCore`
+- `memory/forget`
+- `memory/promote`
+- `memory/inspect`
+- `memory/why`
+- `memory/summarize`
+
+See [RPC protocol](rpc.md) for method details.

data/doc/plugins.md

@@ -0,0 +1,223 @@
+# Plugins
+
+Plugins are Kward's trusted local extension system. They let you add project or personal workflow features without changing Kward itself.
+
+A plugin can:
+
+- add interactive slash commands,
+- expose commands through the RPC backend,
+- render a custom terminal footer,
+- inject concise prompt context into future model requests,
+- observe live transcript events such as assistant output, tool calls, and retries.
+
+Plugins are plain Ruby files. They run inside the Kward process with your local user permissions, so install only plugins you trust.
+
+Use a prompt template when reusable text is enough. Use a skill when you need reusable instructions. Use a plugin when you need local Ruby behavior, file or network integration, custom commands, or transcript observers.
+
+## Where plugins live
+
+Kward loads top-level Ruby files from:
+
+```text
+~/.kward/plugins/*.rb
+```
+
+Plugins are intentionally **not** loaded from the current workspace, from a project repository, or from a custom `KWARD_CONFIG_PATH` directory. This keeps plugin loading tied to the local user account rather than to whatever project Kward is currently inspecting.
+
+If a legacy plugin directory exists beside a custom config path, Kward warns and ignores it.
+
+## A first plugin
+
+Create the plugin directory:
+
+```bash
+mkdir -p ~/.kward/plugins
+```
+
+Then create `~/.kward/plugins/hello.rb`:
+
+```ruby
+Kward.plugin do |plugin|
+  plugin.command "hello", description: "Say hello", argument_hint: "[name]" do |args, ctx|
+    name = args.strip.empty? ? "captain" : args.strip
+    ctx.say("Hello, #{name}.")
+  end
+end
+```
+
+Start Kward and run:
+
+```text
+/hello Kai
+```
+
+Plugin commands appear in interactive slash completion and in RPC command listings.
+
+## Slash commands
+
+Register a command with `plugin.command`:
+
+```ruby
+Kward.plugin do |plugin|
+  plugin.command "session-info", description: "Show session details" do |_args, ctx|
+    ctx.say("Session: #{ctx.session_name || ctx.session_id || 'unnamed'}")
+    ctx.say("Path: #{ctx.session_path || 'not saved'}")
+    ctx.say("Workspace: #{ctx.workspace_root}")
+  end
+end
+```
+
+Command names:
+
+- do not include the leading `/`,
+- must start with a letter or number,
+- may contain letters, numbers, `_`, and `-`,
+- cannot replace built-in commands or prompt-template commands.
+
+If a plugin command conflicts with a reserved or duplicate command, Kward skips it and prints a warning.
+
+Command handlers receive:
+
+- `args`: the raw text after the command name,
+- `ctx`: a plugin context object.
+
+Use `ctx.say(message)` for user-visible output.
+
+## Prompt context
+
+Plugins can add concise context to future system prompts:
+
+```ruby
+Kward.plugin do |plugin|
+  plugin.prompt_context do |ctx|
+    next unless File.exist?(File.join(ctx.workspace_root, "Gemfile"))
+
+    "Workspace note: this project uses Ruby. Prefer bundle exec for project commands."
+  end
+end
+```
+
+Prompt context is injected after personas and before skills/workspace instructions. Keep it short and stable. Long or noisy prompt context will be sent repeatedly to the model and can reduce useful context space.
+
+If plugin state changes and the active conversation should rebuild its system message, call:
+
+```ruby
+ctx.refresh_system_message!
+```
+
+from a command or event handler.
+
+## Custom footer
+
+A plugin can render one custom footer for the terminal UI:
+
+```ruby
+Kward.plugin do |plugin|
+  plugin.footer do |ctx|
+    name = ctx.session_name || "unnamed"
+    messages = ctx.transcript.messages.length
+    "#{name} • #{messages} messages"
+  end
+end
+```
+
+Only one footer renderer is active. If multiple plugins register footers, the later one replaces the earlier one and Kward prints a warning.
+
+Footer errors are caught and printed as warnings so they do not break the session.
+
+## Transcript events
+
+Plugins can observe live transcript stream events:
+
+```ruby
+Kward.plugin do |plugin|
+  plugin.on_transcript_event do |event, ctx|
+    next unless event.type == "assistant_delta"
+
+    File.open(File.join(ctx.workspace_root, ".assistant-stream.log"), "a") do |file|
+      file.write(event.payload[:delta])
+    end
+  end
+end
+```
+
+Supported event types include:
+
+- `reasoning_delta`
+- `assistant_delta`
+- `assistant_message`
+- `model_retry`
+- `turn_steered`
+- `tool_call`
+- `tool_result`
+- `answer`
+
+Event payloads are deep-frozen copies. Treat them as read-only.
+
+Transcript-event handler errors are caught and printed as warnings.
+
+## Plugin context API
+
+Plugin handlers receive a `ctx` object with:
+
+- `ctx.args` - raw command arguments for contexts that have them.
+- `ctx.workspace_root` - active workspace path.
+- `ctx.transcript.messages` - deep-frozen copy of active conversation messages.
+- `ctx.say(message)` - emit output to the active frontend when available.
+- `ctx.session_id` - current persisted session ID when available.
+- `ctx.session_name` - current session name when available.
+- `ctx.session_path` - current session file path when available.
+- `ctx.refresh_system_message!` - rebuild the active conversation system message.
+
+The transcript is read-only by design. Plugins should use Kward APIs exposed through the context rather than mutating conversation internals.
+
+## RPC support
+
+Plugins are available to both the CLI and the experimental RPC backend.
+
+RPC clients can:
+
+- list plugin commands through `commands/list`,
+- run plugin commands through `commands/run`,
+- run plugin slash commands through `turns/start` input such as `/hello Kai`.
+
+When a plugin command is run as a turn, Kward emits command output through normal turn events without calling the model.
+
+## Security model
+
+Plugins are trusted local Ruby code. A plugin can read and write files, run commands, make network requests, and access process environment variables just like any Ruby code running as your user.
+
+Recommended practices:
+
+- Install plugins only from sources you trust.
+- Keep plugins in your personal `~/.kward/plugins` directory.
+- Do not place secrets directly in plugin files if they will be shared.
+- Prefer user-specific config or environment variables for credentials.
+- Keep prompt context concise and avoid injecting secrets into model prompts.
+- Be careful when writing transcript observers that persist conversation content.
+
+## Complete example
+
+```ruby
+Kward.plugin do |plugin|
+  plugin.command "last-message", description: "Show transcript size" do |_args, ctx|
+    ctx.say("Messages: #{ctx.transcript.messages.length}")
+  end
+
+  plugin.footer do |ctx|
+    "#{ctx.session_name || 'unnamed'} • #{ctx.transcript.messages.length} messages"
+  end
+
+  plugin.prompt_context do |_ctx|
+    "Project background: prefer small, focused changes."
+  end
+
+  plugin.on_transcript_event do |event, ctx|
+    next unless event.type == "assistant_delta"
+
+    File.open(File.join(ctx.workspace_root, ".assistant-stream.log"), "a") do |file|
+      file.write(event.payload[:delta])
+    end
+  end
+end
+```

data/doc/releasing.md

@@ -0,0 +1,36 @@
+# Releasing Kward
+
+Release steps that can be completed before publishing:
+
+1. Update `CHANGELOG.md` for the version.
+2. Update `Kward::VERSION` in `lib/kward/version.rb`.
+3. Run the test suite:
+
+   ```bash
+   bundle exec rake test
+   ```
+
+4. Generate documentation:
+
+   ```bash
+   bundle exec rake rdoc
+   bundle exec yard doc
+   ```
+
+5. Build the gem locally:
+
+   ```bash
+   gem build kward.gemspec
+   ```
+
+6. Inspect the packaged files and confirm no local config, sessions, logs, or secrets are included.
+7. Install the built gem locally and smoke test the `kward` executable.
+
+RubyGems setup before the first public release:
+
+1. Create or sign in to a RubyGems.org account.
+2. Enable multi-factor authentication for the account.
+3. Confirm the `kward` gem name is available.
+4. Add final homepage, source code, changelog, documentation, and bug tracker metadata to `kward.gemspec` once the public repository URLs are final.
+5. Prefer RubyGems trusted publishing for automated releases so long-lived API keys do not need to be stored in CI secrets.
+6. Push the built gem or publish through the trusted publishing workflow.