feat(prompt): add system prompt builder with context injection (#7)

## Summary

Add a section-based system prompt builder with runtime environment
detection, hierarchical instruction file discovery (CLAUDE.md /
AGENTS.md), and static guidance sections. The prompt is rebuilt each
turn so git status and branch info stay fresh.

The API client now sends the system prompt as an array of text blocks
with the identity prefix in its own block, which is required for OAuth
validation on non-Haiku models.

- Section-based prompt assembly: identity, task guidance, caution, tool
usage, tone / style, environment, user instructions.
- CLAUDE.md / AGENTS.md discovery with root-to-CWD walk and `.claude/`
subdirectory support.
- Runtime environment detection: working directory, platform, shell, git
branch + clean / dirty status, local date, model name.
- Per-turn prompt rebuild for fresh git state on every user message.
- System prompt sent as array of `TextBlock` with identity prefix in its
own block (OAuth requirement).
- Research docs on system prompt architecture and API authentication
(block format, attribution header, third-party restrictions).
- User-facing guide: quickstart, configuration, instruction files.

## Changes

| File | Description |
| ---- | ----------- |
| `crates/oxide-code/src/prompt.rs` | Module root: static guidance
constants, `build_system_prompt` entry, `assemble` (testable core),
`find_git_root` |
| `crates/oxide-code/src/prompt/environment.rs` | `Environment` struct
with `detect` / `render`, parallel git info via `tokio::join!`,
`current_date` via `time` crate with local-offset fallback |
| `crates/oxide-code/src/prompt/instructions.rs` | `Slot`-based
instruction discovery: `load` → `candidate_slots` → `walk_root_to_cwd` →
`load_files` → `render` |
| `crates/oxide-code/src/client/anthropic.rs` | `SystemBlock` type,
`system` field changed from `&str` to `Vec<SystemBlock>`, prefix sent as
separate block, `SYSTEM_PROMPT_PREFIX` moved here |
| `crates/oxide-code/src/main.rs` | Per-turn `build_system_prompt` call,
pass `Some(&system_prompt)` to client |
| `crates/oxide-code/src/config/oauth.rs` | `_ =` style consistency |
| `Cargo.toml` | Add `time` with `local-offset` feature |
| `CLAUDE.md` | Add `prompt.rs`, `prompt/environment.rs`,
`prompt/instructions.rs` to crate structure |
| `docs/research/system-prompt.md` | Research: Claude Code and opencode
prompt architecture, section caching, walk behavior |
| `docs/research/anthropic-api.md` | Research: system block format,
attribution header / fingerprint, third-party restrictions |
| `docs/guide/quickstart.md` | User guide: install, credentials, first
session, tools table |
| `docs/guide/configuration.md` | User guide: API key, OAuth,
environment variables |
| `docs/guide/instructions.md` | User guide: CLAUDE.md / AGENTS.md
discovery hierarchy, walk example |
| `docs/guide/README.md` | Guide index |
| `docs/README.md` | Add User Guide section |
| `docs/roadmap.md` | Move system prompt to Working, update focus |
| `README.md` | Slim down, add Documentation table linking to guide |

## Test plan

- [x] `cargo build` compiles cleanly
- [x] `cargo clippy --all-targets -- -D warnings` — zero warnings
- [x] `cargo test` — 195 tests pass
- [x] `cargo llvm-cov --ignore-filename-regex 'main\.rs'` — 89% line
coverage (prompt modules 98–99%)
- [x] Live test: `ox` responds correctly with full system prompt
(CLAUDE.md injected, environment detected)
- [x] Live test: `main` branch works, `feat/system-prompt` works after
block-format fix

Author: hakula139

.cspell/words.txt

@@ -1,5 +1,6 @@
 anthropic
 anyhow
+claudemd
 clippy
 codex
 creds

CLAUDE.md

@@ -31,6 +31,10 @@ ox                      # Start an interactive session
 │   └── oauth.rs        # Claude Code OAuth credentials (macOS Keychain + file), token refresh, file locking
 ├── main.rs             # CLI entry point, agent loop, async REPL
 ├── message.rs          # Conversation message types
+├── prompt.rs           # System prompt builder (section assembly, static content)
+├── prompt/
+│   ├── environment.rs  # Runtime environment detection (platform, git, date)
+│   └── instructions.rs # Instruction file discovery and loading (CLAUDE.md, AGENTS.md)
 ├── tool.rs             # Tool trait, registry, definitions
 └── tool/
     ├── bash.rs         # Shell command execution with timeout

Cargo.lock

@@ -33,6 +33,7 @@ security-framework = "3"
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"
 tempfile = "3"
+time = { version = "0.3", features = ["local-offset"] }
 tokio = { version = "1", features = [
   "io-std",
   "io-util",

Cargo.toml

@@ -18,23 +18,17 @@ Early development. See [`docs/roadmap.md`](docs/roadmap.md) for the current road
 ## Usage
 
 ```bash
+export ANTHROPIC_API_KEY=sk-ant-...
 ox
 ```
 
-## Configuration
+## Documentation
 
-oxide-code needs an Anthropic API credential. It checks two sources in order:
-
-1. **`ANTHROPIC_API_KEY`** — set this to your Anthropic API key.
-2. **Claude Code OAuth** — if no API key is set, oxide-code reads OAuth credentials from the macOS Keychain and `~/.claude/.credentials.json` (created by [Claude Code]), preferring whichever has the later expiry. Falls back to file-only on Linux.
-
-Optional environment variables:
-
-| Variable               | Default                     | Description             |
-| ---------------------- | --------------------------- | ----------------------- |
-| `ANTHROPIC_MODEL`      | `claude-opus-4-6`           | Model to use            |
-| `ANTHROPIC_BASE_URL`   | `https://api.anthropic.com` | API base URL            |
-| `ANTHROPIC_MAX_TOKENS` | `16384`                     | Max tokens per response |
+| Document                                        | Description                                     |
+| ----------------------------------------------- | ----------------------------------------------- |
+| [Quickstart](docs/guide/quickstart.md)          | Install, first run, basic usage                 |
+| [Configuration](docs/guide/configuration.md)    | API credentials, model selection, environment   |
+| [Instruction Files](docs/guide/instructions.md) | CLAUDE.md / AGENTS.md setup and discovery rules |
 
 ## Building from Source
 

README.md

@@ -23,6 +23,7 @@ regex.workspace = true
 reqwest.workspace = true
 serde.workspace = true
 serde_json.workspace = true
+time.workspace = true
 tokio.workspace = true
 tracing.workspace = true
 tracing-subscriber.workspace = true

crates/oxide-code/Cargo.toml

@@ -17,9 +17,9 @@ const OAUTH_BETA_HEADER: &str = "oauth-2025-04-20";
 /// Matches the referenced Claude Code version.
 const CLAUDE_CLI_VERSION: &str = "2.1.87";
 
-/// System prompt prefix that identifies the client to the Anthropic API. Required
-/// for OAuth tokens — without it, non-Haiku models return 429. Always sent
-/// regardless of auth method for simplicity.
+/// OAuth-required identity prefix. The Anthropic API returns 429 for non-Haiku
+/// models with OAuth tokens unless the system prompt starts with this exact
+/// string in its own text block.
 const SYSTEM_PROMPT_PREFIX: &str = "You are Claude Code, Anthropic's official CLI for Claude.";
 
 // ── Request types ──
@@ -29,14 +29,24 @@ struct CreateMessageRequest<'a> {
     model: &'a str,
     max_tokens: u32,
     messages: &'a [Message],
-    system: &'a str,
+    system: Vec<SystemBlock<'a>>,
     stream: bool,
     #[serde(skip_serializing_if = "Option::is_none")]
     tools: Option<&'a [ToolDefinition]>,
     #[serde(skip_serializing_if = "Option::is_none")]
     thinking: Option<&'a ThinkingConfig>,
 }
 
+/// A text block in the system prompt array. The Anthropic API accepts `system`
+/// as either a string or an array of these blocks. Using the array form lets
+/// the identity prefix occupy its own block, which is required for OAuth
+/// validation on non-Haiku models.
+#[derive(Serialize)]
+struct SystemBlock<'a> {
+    r#type: &'static str,
+    text: &'a str,
+}
+
 // ── SSE response types ──
 
 #[expect(
@@ -230,17 +240,23 @@ impl Client {
         system: Option<&str>,
         tools: &[ToolDefinition],
     ) -> Result<mpsc::Receiver<Result<StreamEvent>>> {
-        let system_prompt = match system {
-            Some(s) => format!("{SYSTEM_PROMPT_PREFIX}\n{s}"),
-            None => SYSTEM_PROMPT_PREFIX.to_owned(),
-        };
+        let mut system_blocks = vec![SystemBlock {
+            r#type: "text",
+            text: SYSTEM_PROMPT_PREFIX,
+        }];
+        if let Some(s) = system {
+            system_blocks.push(SystemBlock {
+                r#type: "text",
+                text: s,
+            });
+        }
 
         let url = format!("{}/v1/messages", self.config.base_url);
         let body = serde_json::to_value(CreateMessageRequest {
             model: &self.config.model,
             max_tokens: self.config.max_tokens,
             messages,
-            system: &system_prompt,
+            system: system_blocks,
             stream: true,
             tools: (!tools.is_empty()).then_some(tools),
             thinking: self.config.thinking.as_ref(),
@@ -253,7 +269,7 @@ impl Client {
         tokio::spawn(async move {
             let result = stream_sse(&http, &url, &body, &tx).await;
             if let Err(e) = result {
-                let _ = tx.send(Err(e)).await;
+                _ = tx.send(Err(e)).await;
             }
         });
 

crates/oxide-code/src/client/anthropic.rs

@@ -302,7 +302,7 @@ struct LockGuard {
 
 impl Drop for LockGuard {
     fn drop(&mut self) {
-        let _ = std::fs::remove_dir_all(&self.path);
+        _ = std::fs::remove_dir_all(&self.path);
     }
 }
 
@@ -318,7 +318,7 @@ async fn acquire_lock(path: &Path) -> Result<LockGuard> {
             }
             Err(e) if e.kind() == std::io::ErrorKind::AlreadyExists => {
                 if is_stale_lock(path) {
-                    let _ = std::fs::remove_dir_all(path);
+                    _ = std::fs::remove_dir_all(path);
                     continue;
                 }
                 if attempt == LOCK_MAX_RETRIES {

crates/oxide-code/src/config/oauth.rs

@@ -1,6 +1,7 @@
 mod client;
 mod config;
 mod message;
+mod prompt;
 mod tool;
 
 use std::io::Write;
@@ -34,6 +35,7 @@ async fn main() -> Result<()> {
 
     let config = Config::load().await?;
     let show_thinking = config.show_thinking;
+    let model = config.model.clone();
     let client = Client::new(config)?;
     let tools = ToolRegistry::new(vec![
         Box::new(BashTool),
@@ -44,10 +46,15 @@ async fn main() -> Result<()> {
         Box::new(GrepTool),
     ]);
 
-    repl(&client, &tools, show_thinking).await
+    repl(&client, &tools, &model, show_thinking).await
 }
 
-async fn repl(client: &Client, tools: &ToolRegistry, show_thinking: bool) -> Result<()> {
+async fn repl(
+    client: &Client,
+    tools: &ToolRegistry,
+    model: &str,
+    show_thinking: bool,
+) -> Result<()> {
     let stdin = BufReader::new(tokio::io::stdin());
     let mut lines = stdin.lines();
     let mut messages: Vec<Message> = Vec::new();
@@ -66,7 +73,8 @@ async fn repl(client: &Client, tools: &ToolRegistry, show_thinking: bool) -> Res
         }
 
         messages.push(Message::user(&input));
-        agent_turn(client, tools, &mut messages, show_thinking).await?;
+        let system_prompt = prompt::build_system_prompt(model).await;
+        agent_turn(client, tools, &mut messages, &system_prompt, show_thinking).await?;
     }
 
     Ok(())
@@ -76,13 +84,15 @@ async fn agent_turn(
     client: &Client,
     tools: &ToolRegistry,
     messages: &mut Vec<Message>,
+    system_prompt: &str,
     show_thinking: bool,
 ) -> Result<()> {
     let tool_defs = tools.definitions();
 
     for _ in 0..MAX_TOOL_ROUNDS {
         strip_trailing_thinking(messages);
-        let blocks = stream_response(client, messages, &tool_defs, show_thinking).await?;
+        let blocks =
+            stream_response(client, messages, &tool_defs, system_prompt, show_thinking).await?;
 
         let tool_uses: Vec<_> = blocks
             .iter()
@@ -205,9 +215,10 @@ async fn stream_response(
     client: &Client,
     messages: &[Message],
     tools: &[ToolDefinition],
+    system_prompt: &str,
     show_thinking: bool,
 ) -> Result<Vec<ContentBlock>> {
-    let mut rx = client.stream_message(messages, None, tools)?;
+    let mut rx = client.stream_message(messages, Some(system_prompt), tools)?;
 
     let mut blocks: Vec<Option<BlockAccumulator>> = Vec::new();
     let mut stdout = std::io::stdout();