diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..0154578
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,71 @@
+# Contributing to Ollie
+
+## Development Workflow
+
+1. **Make changes** in the source directory (`~/src/ollie/`).
+2. **Build and test**: `make` (runs build + test + install).
+3. **Verify**: Run `olliesrv` and test your changes.
+
+## Code Style
+
+- **Go**: `gofmt`, short variable names, error returns (no panics), table-driven tests.
+- **Tool scripts**: Emit structured output (`STATUS=ok`, `STATUS=error`).
+- **Prompts**: Markdown, concise, example-driven.
+
+Match the existing code style: naming conventions, error handling patterns, indentation, imports.
+
+## Testing
+
+```bash
+make test          # all tests
+make test-core     # cmd/olliesrv, cmd/toolsrv, shared packages
+make test-9p       # lib9p tests
+```
+
+Run tests before committing. If you add a feature, add tests.
+
+## Commits
+
+- Keep commits atomic and focused.
+- Write clear commit messages explaining *what* and *why*.
+- Prefer new commits over `--amend` unless incorporating pre-commit hook changes.
+
+## Package Documentation
+
+Each package should have a `doc.go` file with a package-level comment explaining:
+- What the package does
+- Key types and their relationships
+- Usage patterns
+
+## File Organization
+
+Split large files by concern:
+- One primary type per file when it has significant logic
+- Group related functions in the same file
+- Keep files under ~500 lines when practical
+
+## Adding Tools
+
+### Script-based (Python/Bash)
+1. Create executable in `data/tools/<name>`
+2. Create `data/tools/<name>.meta` with JSON metadata
+3. Run `make install-data`
+
+### Compiled (Go)
+1. Create package under `tools/<family>/cmd/<name>/main.go`
+2. Create `<name>.meta` alongside `main.go`
+3. Add build target in Makefile
+4. Run `make`
+
+## Adding Prompts
+
+1. Write markdown in `data/prompts/`
+2. Reference in agent config if needed
+3. Run `make install-data`
+
+## Key Conventions
+
+- **Edit source files here**, not `~/.config/ollie/` (that's the install target)
+- **9P namespace is the API** — every capability is a file
+- **No pointless indirection** — call the real thing directly
+- **Subtraction > addition** — look for what to remove first
diff --git a/cmd/olliesrv/internal/agent/agent.go b/cmd/olliesrv/internal/agent/agent.go
index 4539c71..ce8c616 100644
--- a/cmd/olliesrv/internal/agent/agent.go
+++ b/cmd/olliesrv/internal/agent/agent.go
@@ -36,8 +36,8 @@ type Agent struct {
 	currentAction atomic.Pointer[actionHandle]
 	closed        atomic.Bool
 	actionMu      sync.Mutex // serializes action registration with shutdown
-	warnedContext bool
-	resultCache   resultCache
+	warnedContext bool       // true after warning about context window limits
+	resultCache   resultCache // per-agent cache of tool results for read-safe tools
 
 	// Execution state — owned by the agent, protected by stateMu.
 	state          string              // "idle", "thinking", "calling: <tool>"
@@ -69,13 +69,13 @@ type Agent struct {
 
 	// Chat log — the rendered output stream, exposed via 9P.
 	chatMu       sync.RWMutex
-	chatLog      []byte
-	chatStart    int
-	chatVers     uint32
-	chatCond     *sync.Cond
+	chatLog      []byte        // append-only chat log buffer
+	chatStart    int           // byte offset of first byte in chatLog (for truncation accounting)
+	chatVers     uint32        // incremented on each append for change detection
+	chatCond     *sync.Cond    // signaled on new chat data
 	chatSignalMu sync.Mutex
-	chatSignalCh chan struct{}
-	plan         []byte
+	chatSignalCh chan struct{} // closed on new chat data; replaced with fresh channel
+	plan         []byte        // agent's plan file contents
 }
 
 // Backend returns the active backend from the runtime.