kward 0.68.0 → 0.69.0

data/doc/extensibility.md

@@ -1,181 +1,125 @@
 # Extensibility
 
-Kward can be customized at several levels:
+Kward can be customized without changing its source code. Use extensibility when you want Kward to follow your conventions, repeat common prompts, or add local behavior.
 
-- `AGENTS.md` for coding guidance and repository rules.
-- Prompt templates for reusable slash-command prompts.
-- Skills for reusable agent instructions the model can load on demand.
-- Personas for assistant personality and communication style.
-- Plugins for trusted Ruby extensions that add commands, footer UI, prompt context, transcript-event observers, and RPC-visible behavior.
+Start simple. Most users only need `PRINCIPLES.md`, workspace `AGENTS.md`, and maybe a prompt template.
 
-Prompts, skills, personas, and config-directory `AGENTS.md` live beside the config file. By default this is `~/.kward`; if `KWARD_CONFIG_PATH` is set, Kward uses that file's directory instead.
+## Choose the right extension point
 
-Plugins are different: user plugins are loaded only from `~/.kward/plugins`, regardless of `KWARD_CONFIG_PATH` or the current project directory. See the dedicated [Plugins guide](plugins.md).
+| Need | Use |
+| --- | --- |
+| Global coding preferences | `~/.kward/PRINCIPLES.md` |
+| Repository-specific rules | `<workspace>/AGENTS.md` |
+| Reusable slash prompts | prompt templates |
+| Task-specific reusable instructions | skills |
+| Different tone or role | [personas](personas.md) |
+| Local Ruby behavior or integrations | plugins |
 
-## Which extension point should I use?
-
-- Use `AGENTS.md` when you want Kward to follow coding rules, project conventions, or review expectations.
-- Use prompt templates when you want reusable slash commands such as `/plan <task>` or `/review <diff>`.
-- Use skills when you want reusable instructions that Kward can load only when a task needs them.
-- Use personas when you want to change tone, role, or communication style.
-- Use plugins when you need Ruby code to run locally, add commands, observe transcript events, or integrate with another tool.
-
-The optional starter pack installs a useful base `AGENTS.md` and prompt templates. You can install it with:
+Install the starter pack for a useful starting point:
 
 ```bash
 kward init
 ```
 
-## Agent instructions
+## Global instructions: `PRINCIPLES.md`
 
-Kward separates repository guidance from workspace-specific agent personality.
+Use this for preferences you want in most projects:
 
-- Config-directory `AGENTS.md`: global coding guidance appended to Kward's built-in system instructions when present.
-- Workspace `AGENTS.md`: repository guidance loaded from the active workspace root when present.
+```markdown
+Prefer small, focused changes.
+Add tests for new behavior.
+Do not refactor unrelated code.
+Explain risky assumptions before editing.
+```
 
-Use `AGENTS.md` for engineering instructions such as coding rules, project conventions, testing requirements, review expectations, and workflow guidance. Avoid putting personality, roleplay, or communication style there; configure those as personas instead.
+Default location:
 
-Workspace `AGENTS.md` is injected once when a conversation starts. Kward refreshes it only when the file changes or when the agent edits the workspace `AGENTS.md`. Config-directory and workspace `AGENTS.md` files are skipped with a warning if they exceed 32 KiB, because they are injected into every model request.
+```text
+~/.kward/PRINCIPLES.md
+```
 
-## Prompt templates
+If `KWARD_CONFIG_PATH` is set, `PRINCIPLES.md` lives beside that config file.
 
-Prompt templates create user-invocable slash commands for reusable prompts.
+## Project instructions: `AGENTS.md`
 
-Create a template at:
+Put repository-specific rules in the workspace root:
 
 ```text
-<config-dir>/prompts/<command>.md
+my-project/AGENTS.md
 ```
 
-For example, `prompts/plan.md` becomes `/plan` in interactive mode. Templates support `$ARGUMENTS`, replaced by the text after the command.
-
-Built-in commands such as `/exit`, `/new`, `/resume`, `/name`, `/clone`, `/export`, `/redraw`, and `/status` are reserved.
-
-Example prompt template:
+Good examples:
 
 ```markdown
----
-description: Create an implementation plan.
-argument-hint: <task>
----
+Run tests with `bundle exec rake test`.
+Use Minitest, not RSpec.
+Do not change generated files under `schema/`.
+Update CHANGELOG.md for user-visible changes.
+```
 
-Plan this implementation request:
+Use `AGENTS.md` for project facts and engineering rules. Do not put personality or roleplay instructions there; use [personas](personas.md) for tone.
 
-$ARGUMENTS
-```
+By default, Kward adds a compact instruction telling the model that `AGENTS.md` exists and should be read when relevant. Set `enforce_workspace_agents_file: true` only if you want the full file injected every time.
 
-## Skills
+## Prompt templates
 
-Skills are reusable instruction packs the assistant can load when a task matches their description. They are useful when an instruction is too specific to include in every conversation, but important enough to keep around.
+Use prompt templates when you repeatedly type the same kind of request.
 
-Create a skill at:
+Create:
 
 ```text
-<config-dir>/skills/<skill-name>/SKILL.md
+~/.kward/prompts/review.md
 ```
 
-A skill is listed in the system instructions by its frontmatter `name` and `description`. The assistant can then call `read_skill` to load `SKILL.md` or related files inside that skill folder.
-
-Example skill:
+Example:
 
 ```markdown
 ---
-name: planner
-description: Helps plan implementation work.
+description: Review a change for correctness.
+argument-hint: <focus>
 ---
 
-# Planner
-
-Use this when planning a code change.
+Review the current diff for correctness, tests, and maintainability.
+Focus on: $ARGUMENTS
 ```
 
-## Personas
-
-Personas configure personality, role, and communication style without modifying repository files. New configs include a single active `kward` character by default; edit or remove `personas.default` to change the first-run experience. `personas.crew` is still accepted as an alias for `personas.characters`.
-
-A small persona config looks like this:
-
-```json
-{
-  "personas": {
-    "characters": [
-      {
-        "key": "kward",
-        "label": "Kward",
-        "instruction": "Be concise, practical, and friendly. Prefer small, safe changes."
-      }
-    ],
-    "default": "kward"
-  }
-}
-```
+Then run inside Kward:
 
-You can also target personas by workspace, model, reasoning effort, time of day, or weekday:
-
-```json
-{
-  "personas": {
-    "characters": [
-      {
-        "key": "reviewer",
-        "label": "Reviewer",
-        "instruction": "Be skeptical and focus on correctness, tests, and maintainability."
-      },
-      {
-        "key": "coach",
-        "label": "Coach",
-        "instruction": "Explain tradeoffs and teach as you go."
-      }
-    ],
-    "default": "reviewer",
-    "workspaces": {
-      "/Users/kwood/Repositories/github.com/kaiwood/tauren": "coach"
-    },
-    "models": {
-      "gpt-5.5": "reviewer"
-    },
-    "persona_modifiers": {
-      "reasoning": {
-        "high": "Think strategically before answering."
-      },
-      "suffix": "Act like it."
-    }
-  }
-}
+```text
+/review auth edge cases
 ```
 
-Persona evaluation order is:
+Prompt templates are best for reusable text. They do not run local code.
 
-1. `personas.default`
-2. Matching `personas.workspaces` entry, using normalized workspace paths
-3. Matching `personas.models` entry for the current model
-4. Matching `persona_modifiers.reasoning` entry for the current reasoning effort
-5. Matching `persona_modifiers.time_of_day` entry for local time: `morning` 05:00-10:59, `before_lunch` 11:00-11:59, `late_evening` 21:00-04:59
-6. Matching `persona_modifiers.weekday` entry for the local weekday
-7. `persona_modifiers.suffix`
+## Skills
 
-Prompt assembly order is:
+Use skills for reusable instructions that should only be loaded for certain tasks.
 
-1. Kward built-in base prompt
-2. Config-directory `AGENTS.md`
-3. Evaluated persona text
-4. Plugin prompt context
-5. Skills listing
-6. Workspace `AGENTS.md`
+Create:
 
-If no persona entries match, Kward simply omits that part. Conversation compaction uses a neutral prompt without workspace personality, so summaries stay continuation-focused and machine-oriented.
+```text
+~/.kward/skills/testing/SKILL.md
+```
 
-## Plugins
+Example:
+
+```markdown
+---
+name: testing
+or description: Use when adding or changing tests.
+---
 
-Plugins are Kward's trusted Ruby extension layer. Use them when you need behavior rather than just instructions or reusable prompts.
+Prefer focused tests near the changed behavior.
+Do not weaken assertions to make tests pass.
+```
 
-Plugins can add:
+Skills are listed to the model by name and description. Kward can load the full skill only when it is relevant.
 
-- slash commands,
-- one custom terminal footer,
-- prompt context,
-- live transcript-event observers,
-- command behavior exposed to RPC clients.
+## Plugins
+
+Use plugins when text instructions are not enough and you need Ruby code to run locally.
+
+Plugins can add slash commands, prompt context, footer UI, transcript observers, and RPC-visible commands.
 
 Plugin files live in:
 
@@ -183,4 +127,21 @@ Plugin files live in:
 ~/.kward/plugins/*.rb
 ```
 
-See [Plugins](plugins.md) for the full plugin API, examples, and security model.
+Plugins are trusted local Ruby code. Install only plugins you trust. See [Plugins](plugins.md).
+
+## Prompt assembly order
+
+When Kward builds instructions for a turn, it combines roughly:
+
+1. Kward's built-in operating instructions.
+2. `PRINCIPLES.md`.
+3. selected persona.
+4. plugin prompt context.
+5. available skills list.
+6. workspace `AGENTS.md` hint or full content.
+
+If behavior seems surprising, inspect the assembled instructions:
+
+```bash
+kward sysprompt
+```

data/doc/getting-started.md

@@ -1,125 +1,123 @@
 # Getting started
 
-Kward is a Ruby CLI coding agent for local projects. It can answer questions, inspect files, propose and apply edits, run confirmed commands, search the web, and keep session history.
+Use Kward when you want an agent in your terminal that can inspect the current project, explain code, edit files, run local commands, and keep an interactive session history.
 
-This page gets you to a first working chat. For day-to-day features after that, see [Usage](usage.md).
+This page gets you from install to a first useful chat.
 
 ## Requirements
 
 - Ruby 3.2 or newer.
-- Bundler when running from source.
-- Credentials for at least one model provider. You can add them with `/login` inside Kward or with `kward login` from your shell.
+- Credentials for one model provider. The easiest setup is `kward login` or `/login` inside Kward.
+- Bundler only if you run Kward from a source checkout.
 
 ## Install
 
-Install Kward from RubyGems:
+Install the gem:
 
 ```bash
 gem install kward
 ```
 
-Optionally install the starter pack:
+Install the starter pack:
 
 ```bash
 kward init
 ```
 
-The starter pack adds useful default prompts and a base `AGENTS.md` to your config directory. It is helpful for a first setup, but safe to skip if you want to write your own instructions. Existing files are not overwritten.
+The starter pack adds default prompts and a base `PRINCIPLES.md` under `~/.kward`. It does not overwrite existing files.
 
-If you are working from a repository checkout:
+If you are working from a checkout instead:
 
 ```bash
 bundle install
-ruby lib/main.rb init   # optional
+ruby lib/main.rb init
 ```
 
-## Start Kward and sign in
+## Sign in
 
-Start an interactive session:
+From your shell:
 
 ```bash
-kward
-```
-
-From source:
-
-```bash
-ruby lib/main.rb
+kward login
 ```
 
-When Kward needs credentials, sign in from inside the session:
+Or from inside an interactive session:
 
 ```text
 /login
 ```
 
-You can also sign in from your shell before starting a chat:
+Kward supports OpenAI/ChatGPT, Anthropic Claude Pro/Max, OpenRouter, and experimental Copilot credentials. See [Authentication](authentication.md) when you need a specific provider.
 
-```bash
-kward login
-```
+## Start an interactive chat
 
-From source:
+Run Kward from the project you want it to work on:
 
 ```bash
-ruby lib/main.rb login
+cd ~/code/my-project
+kward
 ```
 
-For provider-specific login options, such as OpenRouter API keys or experimental Copilot support, see [Authentication](authentication.md).
+Ask something concrete:
 
-## Ask one question and exit
+```text
+Explain the structure of this project.
+```
 
-Pass a prompt as command-line text:
+Then try a task that uses the workspace:
 
-```bash
-kward "Explain this project"
+```text
+Find where user authentication is implemented and summarize the flow.
 ```
 
-From source:
+Kward can read files, suggest edits, apply changes, and run commands from the workspace. Existing files must be read in the current conversation before Kward can edit them.
+
+## Ask one question and exit
+
+For quick tasks, pass the prompt directly:
 
 ```bash
-ruby lib/main.rb "Explain this project"
+kward "Explain this project"
 ```
 
-You can also pipe input:
+Review a diff:
 
 ```bash
-git diff | kward "Review this diff"
+git diff | kward "Review this diff for bugs"
 ```
 
 One-shot prompts do not use Kward memory.
 
 ## Useful first commands
 
-Inside an interactive session:
+Inside interactive Kward:
 
 ```text
 /login              sign in or save provider credentials
-/status             show current session and compaction status
-/model              choose the default model
-/reasoning          choose reasoning effort
-/resume             resume a saved session
-/export notes.md    export the current session as Markdown
-/exit               leave the session
+/model              choose a model
+/status             show session and context status
+/resume             resume a previous session
+/export notes.md    export the transcript
+/compact            summarize older context when a chat gets long
+/exit               leave Kward
 ```
 
-Kward saves interactive sessions under `~/.kward/sessions/`.
-
-## Safety basics
-
-- Kward must read an existing file in the current conversation before it can edit or overwrite it.
-- Tool reads are bounded so large files are not accidentally loaded into context.
-
-## Run tests
-
-If you are developing Kward itself:
+## Run from source
 
 ```bash
-bundle exec rake test
+ruby lib/main.rb login
+ruby lib/main.rb
+ruby lib/main.rb "Explain this project"
 ```
 
-Equivalent direct command:
+You can also run:
 
 ```bash
-ruby -Itest -e 'Dir["test/**/test_*.rb"].sort.each { |file| require_relative file }'
+exe/kward
 ```
+
+## Next steps
+
+- Read [Usage](usage.md) for day-to-day workflows.
+- Read [Configuration](configuration.md) when you want to change providers, models, memory, or web search.
+- Read [Extensibility](extensibility.md) when you want reusable prompts, skills, or project rules.