Add system identity and default skills to RAG context

README.md

@@ -47,7 +47,8 @@ Openheim is built in Rust from the ground up:
 - **Tool execution** — built-in shell, file read, and file write tools. Trait-based, so you can add your own.
 - **MCP (Model Context Protocol)** — connect external MCP servers (stdio or Streamable HTTP) and their tools are automatically exposed to the LLM as `{server_name}__{tool_name}`.
 - **Conversation memory** — conversations (including full tool call history) persist to disk and resume across sessions
-- **Skills** — drop a markdown file into `~/.openheim/skills/` and it's prepended to the system prompt. ACP clients can also pass skills per-session via `_meta`.
+- **System identity** — edit `~/.openheim/system.md` to define how the agent presents itself. Required when preparing a session (created by `openheim init`).
+- **Skills** — drop a markdown file into `~/.openheim/skills/` and it's injected into the system prompt. Set `default_skills` in config to auto-load skills every session; pass `--skills` for per-session additions. ACP clients can also pass skills per-session via `_meta`.
 - **ACP transport** — implements the [Agent Client Protocol](https://github.com/block/agent-client-protocol) over stdio (for editor integrations) and WebSocket (for remote clients), with real-time streaming of message chunks and tool calls
 - **Unified WebSocket** — single multiplexed `WS /ws` connection carries both ACP agent traffic (sessions, streaming, tool calls) and filesystem operations (file CRUD, live watching) via channel envelopes
 - **Retry with backoff** — transient failures (429s, 5xx, network errors) are retried automatically with exponential backoff
@@ -79,11 +80,12 @@ cargo build --release
 ### Configure
 
 ```bash
-# Generate the default config
-cargo run -- init
+# Generate the default config and system.md
+openheim init
 
-# Edit it
+# Edit them
 vim ~/.openheim/config.toml
+vim ~/.openheim/system.md
 ```
 
 Example config:
@@ -92,6 +94,9 @@ Example config:
 default_provider = "anthropic"
 max_iterations = 10
 
+# Skills loaded in every new session automatically (no --skills flag needed)
+# default_skills = ["rules"]
+
 [providers.anthropic]
 api_base = "https://api.anthropic.com/v1"
 default_model = "claude-sonnet-4-6"
@@ -129,26 +134,26 @@ models = ["llama3", "mistral", "codellama"]
 
 ```bash
 # Interactive REPL (default — no subcommand)
-cargo run
+openheim
 
 # Load skills in the REPL
-cargo run -- --skills rust,debugging
+openheim --skills rust,debugging
 
 # Single headless prompt, streams to stdout
-cargo run -- run "List the files in the current directory"
+openheim run "List the files in the current directory"
 
 # Single headless prompt with a model override
-cargo run -- run "Hello" --model gpt-4o
+openheim run "Hello" --model gpt-4o
 
 # ACP stdio agent (for Zed, Claude Code, and other ACP clients)
-cargo run -- acp
+openheim acp
 
 # ACP-over-WebSocket server
-cargo run -- serve
-cargo run -- serve --host 0.0.0.0 --port 1217
+openheim serve
+openheim serve --host 0.0.0.0 --port 1217
 
 # Initialize config
-cargo run -- init
+openheim init
 ```
 
 ---
@@ -170,15 +175,46 @@ Conversations are saved to `~/.openheim/history/` as JSON after every run.
 
 ---
 
-## Skills
+## Agent identity and skills
+
+### `~/.openheim/system.md`
+
+This file defines the agent's base identity. It is loaded when preparing each session (via `prepare()` / session setup) and is required — run `openheim init` to create it, then edit it freely.
+
+```markdown
+You are a senior software engineer who writes clean, idiomatic code.
+You prefer simple solutions and ask clarifying questions before making large changes.
+```
 
-Skills are markdown files in `~/.openheim/skills/`. When loaded, their content is injected into the system prompt before the conversation starts.
+### Skills
 
-Use them to give the agent a persona, a set of coding standards, domain knowledge, or anything you'd otherwise paste into the system prompt every time.
+Skills are markdown files in `~/.openheim/skills/`. They are injected into the system prompt after the identity block.
 
 ```bash
-# Run the REPL with specific skills loaded
-cargo run -- --skills rust,debugging
+# Run with specific skills for this session
+openheim --skills rust,debugging
+
+# Always load certain skills (set in config.toml)
+# default_skills = ["rules", "concise"]
+```
+
+The system message the LLM receives is assembled in this order:
+
+```
+You are a general purpose multiprovider LLM agent.
+
+---
+
+The user has given you the following identity:
+
+<system.md content>
+
+---
+
+These are the skills you have mastered:
+
+### rust
+<rust.md content>
 ```
 
 ACP clients (Zed, Claude Code, etc.) can pass skills per-session by including a `skills` array in the `_meta` field of the `NewSession` request — no flag needed on the server side.
@@ -187,7 +223,7 @@ ACP clients (Zed, Claude Code, etc.) can pass skills per-session by including a
 
 ## Server mode
 
-Start with `cargo run -- serve` (defaults to `0.0.0.0:1217`).
+Start with `openheim serve` (defaults to `0.0.0.0:1217`).
 
 The server speaks the [Agent Client Protocol](https://github.com/block/agent-client-protocol) over WebSocket and exposes a multiplexed WS endpoint plus REST API routes:
 
@@ -284,7 +320,7 @@ src/
   mcp/              MCP (Model Context Protocol) client integration
     client.rs       MCP server connection (stdio + Streamable HTTP)
     tool_handler.rs  Adapts MCP tools to the ToolHandler trait
-  rag/              Conversation history, prompt builder, and skills manager
+  rag/              Conversation history, prompt builder, skills manager, and system identity
   acp/              ACP agent core — session state and protocol handling
   transport/
     stdio.rs        ACP-over-stdio transport (for editor integrations)
@@ -298,7 +334,7 @@ src/
 ## Development
 
 ```bash
-RUST_LOG=debug cargo run -- run "test"
+RUST_LOG=debug openheim run "test"
 cargo test
 cargo fmt --check
 cargo clippy

docs/architecture.md

@@ -44,10 +44,11 @@ src/
 ├── error.rs            Unified Error / Result types
 │
 ├── rag/                Retrieval-Augmented Generation utilities
-│   ├── mod.rs          RagContext — history + skills bundled together
+│   ├── mod.rs          RagContext — history + skills + system identity
 │   ├── history.rs      HistoryManager — conversation persistence
 │   ├── skills.rs       SkillsManager — Markdown skill files
-│   └── prompt.rs       PromptBuilder — injects skills as a system message
+│   ├── system.rs       SystemLoader — reads ~/.openheim/system.md
+│   └── prompt.rs       PromptBuilder — assembles structured system message
 │
 ├── tools/              Tool abstraction and built-in implementations
 │   ├── mod.rs          ToolHandler / ToolExecutor traits, SystemToolExecutor
@@ -108,8 +109,10 @@ User / Client
 │            rag::RagContext::prepare         │
 │                                             │
 │  1. Load conversation from disk (history)   │
-│  2. Load skill files by name                │
-│  3. Build PromptBuilder (system message)    │
+│  2. Load ~/.openheim/system.md (identity)   │
+│  3. Merge default_skills + session skills   │
+│  4. Load skill files by name                │
+│  5. Build PromptBuilder (system message)    │
 │                                             │
 │  Returns: (Conversation, PromptBuilder)     │
 └────────────────────┬────────────────────────┘
@@ -160,7 +163,8 @@ All persistence lives under `~/.openheim/` by default.
 
 ```
 ~/.openheim/
-├── config.toml              Agent configuration (providers, MCP servers, …)
+├── config.toml              Agent configuration (providers, MCP servers, default_skills, …)
+├── system.md                Agent identity — loaded on every session (required)
 ├── history/
 │   ├── {uuid}.json          One file per conversation
 │   └── …
@@ -169,7 +173,7 @@ All persistence lives under `~/.openheim/` by default.
     └── …
 ```
 
-`HistoryManager` reads and writes conversation JSON files. `SkillsManager` reads `.md` files from the skills directory. Both paths are configurable at construction time, which is how the test suite uses temporary directories.
+`SystemLoader` reads `system.md` on every `prepare()` call — missing file is a hard error (run `openheim init` to create it). `HistoryManager` reads and writes conversation JSON files. `SkillsManager` reads `.md` files from the skills directory. Both history and skills paths are configurable at construction time, which is how the test suite uses temporary directories.
 
 ---
 

docs/configuration.md

@@ -3,7 +3,7 @@
 Openheim loads its configuration from `~/.openheim/config.toml`. Generate a default file with:
 
 ```bash
-cargo run -- init
+openheim init
 ```
 
 ---
@@ -14,11 +14,15 @@ cargo run -- init
 |---|---|---|---|
 | `default_provider` | string | — | Provider to use when no `--model` override is given (must match a key under `[providers]`) |
 | `max_iterations` | integer | `10` | Maximum number of agent loop iterations per prompt before stopping |
+| `default_skills` | string[] | `[]` | Skills loaded automatically in every new session. Merged with per-session `--skills`; defaults appear first, duplicates removed. |
 | `theme_color` | string | `"white"` | TUI accent color. Valid values: `white`, `gray`, `blue`, `cyan`, `magenta`, `green`, `yellow`, `red`, `pink`. Can also be changed at runtime with `:theme` |
 
 ```toml
 default_provider = "anthropic"
 max_iterations = 20
+
+# Always load these skills without passing --skills each time
+default_skills = ["rules", "concise"]
 ```
 
 ---

docs/skills.md

@@ -1,10 +1,33 @@
-# Skills
+# Skills & Agent Identity
 
-Skills are Markdown files that inject system-level instructions into every LLM request in a session. They let you shape the agent's behaviour — tone, domain expertise, constraints, output format — without touching code or configuration.
+This document covers two related concepts:
+
+- **System identity** (`~/.openheim/system.md`) — the agent's base character, loaded on every session.
+- **Skills** (`~/.openheim/skills/*.md`) — domain-specific instructions injected on demand.
+
+---
+
+## Agent Identity (`system.md`)
+
+`~/.openheim/system.md` defines who the agent is. It is loaded at the start of every session and is **required** — openheim will error on startup if the file is missing.
+
+Run `openheim init` to create it with a default starting point, then edit it to match how you want the agent to behave:
+
+```markdown
+You are a senior software engineer specialising in Rust and distributed systems.
+You write clean, idiomatic code and prefer simple solutions over clever ones.
+Ask clarifying questions before making large changes.
+```
+
+The identity is placed at the top of the system message, before any skills.
 
 ---
 
-## Where skills live
+## Skills
+
+Skills are Markdown files that inject domain-specific instructions into the system prompt. They let you shape the agent's behaviour — tone, domain expertise, constraints, output format — without touching code or configuration.
+
+### Where skills live
 
 Skills are stored as `.md` files in `~/.openheim/skills/`:
 
@@ -19,23 +42,32 @@ The filename (without extension) is the skill name. Names are case-sensitive and
 
 ---
 
-## How they work
+## How the system message is assembled
 
-When a session starts with one or more skills, `SkillsManager` reads each file and passes the content to `PromptBuilder`. Before each LLM call, the builder prepends a single system message containing all active skills, joined by `---` separators:
+When a session has an identity and skills, the LLM receives a single system message structured like this:
 
 ```
-[System message]
-## Skill: rust
+You are a general purpose multiprovider LLM agent.
+
+---
 
-You are an expert Rust programmer. Always prefer idiomatic Rust…
+The user has given you the following identity:
+
+<system.md content>
 
 ---
 
-## Skill: tdd
+These are the skills you have mastered:
+
+### rust
 
-Write tests first. Every function should have at least one test…
+<rust.md content>
+
+---
 
-[Conversation history follows]
+### tdd
+
+<tdd.md content>
 ```
 
 The system message is reconstructed on every LLM call in the session, so it is always present regardless of how long the conversation runs.
@@ -72,21 +104,23 @@ This skill is about systems programming. The assistant knows Rust and C.
 
 ## Enabling skills
 
-### Via CLI
+### Default skills (loaded every session)
 
-Pass `--skills` as a comma-separated list of skill names:
+Set `default_skills` in `~/.openheim/config.toml` to load skills automatically in every new session — no `--skills` flag needed:
 
-```bash
-openheim --skills rust,tdd
-openheim run --skills concise "Summarise the project structure"
+```toml
+default_skills = ["rules", "concise"]
 ```
 
-### Via configuration
+Default skills are merged with any per-session skills. Duplicates are deduplicated; defaults always appear first.
 
-Set skills globally in `~/.openheim/config.toml` so they apply to every session:
+### Per-session via CLI
 
-```toml
-skills = ["rust", "concise"]
+Pass `--skills` as a comma-separated list of skill names:
+
+```bash
+openheim --skills rust,tdd
+openheim run --skills concise "Summarise the project structure"
 ```
 
 ### Via the Rust library
@@ -108,9 +142,6 @@ Skills are persisted in the conversation metadata (`ConversationMeta.skills`), s
 ## Listing available skills
 
 ```bash
-# CLI
-openheim --skills ""   # lists available skills on startup (TUI)
-
 # API (REST when running openheim serve)
 curl http://localhost:1217/api/skills
 # → ["concise","rust","tdd"]
@@ -125,7 +156,15 @@ let skills = client.rag().skills.list_skills()?;
 
 ---
 
-## Example skills
+## Example files
+
+### `~/.openheim/system.md`
+
+```markdown
+You are a pragmatic software engineer who writes clean, well-tested code.
+You prefer simple solutions and always consider the maintenance burden of your suggestions.
+When you are uncertain, say so rather than guessing.
+```
 
 ### `~/.openheim/skills/concise.md`