## Context

README.md currently serves as a single documentation file for both users and developers. It contains ~290 lines mixing installation/usage instructions with build-from-source steps, release scripts, Docker image internals, and developer notes (e.g., ROCm migration plans). There is no DEVELOPER.md or CONTRIBUTING.md file.

## Goals / Non-Goals

**Goals:**
- Separate user-facing documentation (README.md) from developer-facing documentation (DEVELOPER.md)
- README.md should answer: "What is this? How do I install it? How do I use it?"
- DEVELOPER.md should answer: "How do I build from source? How do I release? How do I contribute?"
- Provide a clear cross-reference link between the two files

**Non-Goals:**
- Rewriting or improving documentation content itself (just moving it)
- Creating additional docs files (CONTRIBUTING.md, architecture docs, etc.)
- Changing any code, build scripts, or CI configuration

## Decisions

### 1. Single DEVELOPER.md file (not multiple docs files)

All developer content goes into one top-level DEVELOPER.md rather than a `docs/` directory or separate CONTRIBUTING.md / BUILDING.md files. The total developer content is small enough (~80 lines) that splitting further would be unnecessary overhead. A single file at the repo root is immediately discoverable.

**Alternative considered**: `docs/` directory with multiple files. Rejected because the content volume doesn't justify the structure, and root-level DEVELOPER.md is a well-known convention.

### 2. Content split boundary

Content stays in README.md if it's needed by someone who just wants to **run** kb. Content moves to DEVELOPER.md if it's only needed by someone who wants to **build, modify, or release** kb.

Specifically moving to DEVELOPER.md:
- "From source" subsections under both engine and client install
- Entire "Building and releasing" section (release scripts, version checking, Docker image tags, registry overrides)
- "Future: ROCm runtime migration" developer note

Staying in README.md:
- Architecture overview (helps users understand what they're running)
- Pre-built image / release install instructions
- Client configuration
- Usage examples
- Engine configuration table
- Data portability
- API reference
- Claude Code skill reference

### 3. Cross-reference approach

A short note in README.md's Quick Start section pointing to DEVELOPER.md for building from source. No back-link needed from DEVELOPER.md since developers will naturally find README.md first.

## Risks / Trade-offs

- **[Stale cross-references]** If DEVELOPER.md sections are renamed, the link from README.md could break. Mitigation: link to the file, not to a specific anchor.
- **[Discoverability]** Some users who want to build from source might miss DEVELOPER.md. Mitigation: explicit "See DEVELOPER.md" callout in the Quick Start section where "from source" instructions used to be.