diff --git a/README.md b/README.md
index da18884..9a415fb 100644
--- a/README.md
+++ b/README.md
@@ -1,67 +1,93 @@
- 
+
-# Merger
-
-Merger is a mutation control plane for AI-native engineering organizations. It converts pull requests into structured Change Packets, classifies semantic mutations, estimates blast radius and rollout risk, applies policy, and assigns a merge lane that reflects how changes should safely propagate.
-
-It is not a code review bot. The design center is operational coordination at a scale where autonomous agents can generate more software mutations than humans can inspect manually.
+
+ 
+ 
+
+ 
+
+
+ 
+
+
+ 
+
+ 
+
+ 
+
+
-## Open-Source Shape
+# merger
-Merger is being built as an open-source platform core. The repository includes first-party implementations for GitHub, NATS, and PostgreSQL, but the extension seams are public so other organizations can plug in their own SCM systems, topology sources, event backbones, analyzers, and persistence adapters.
+`merger` is a Go-native mutation control plane and CLI for AI-native engineering
+organizations. It turns a pull request diff into a structured **Change Packet** —
+classifying semantic mutations, estimating blast radius and rollout risk, applying
+policy, and assigning a **merge lane** that reflects how a change should safely
+propagate.
-See [docs/extending-merger.md](/Users/alex/Documents/GitHub/merger/docs/extending-merger.md:1) for the current extension surface.
+It is not a code review bot. The design center is operational coordination at a
+scale where autonomous agents generate more software mutations than humans can
+inspect by hand.
-## Phase 1 Foundation
+**Contents:** [What it does](#what-it-does) · [Install](#install) · [Quickstart](#quickstart) · [SDK](#sdk) · [Merge lane model](#merge-lane-model) · [Change Packet flow](#change-packet-flow) · [Open-source shape](#open-source-shape) · [Docs](#docs)
-This repository scaffolds the first production-oriented control plane slice:
+## What it does
-- GitHub webhook ingest
-- PR diff parsing
-- Change Packet generation
-- Rule-based semantic mutation detection
-- Risk scoring
-- Merge lane assignment
-- YAML-backed policy evaluation
-- GitHub Check Run publishing abstraction
-- Internal event bus abstraction
-- Structured logging and trace-ready instrumentation
+- parses a PR diff into normalized changed files
+- detects semantic mutations from path rules, patch signals, and structured analyzers
+- resolves a runtime graph and estimates blast radius from topology hints and `CODEOWNERS`
+- computes a weighted risk score and a policy decision from composable YAML rules
+- assigns a merge lane — `GREEN`, `YELLOW`, `RED`, or `BLACK`
+- runs the same pipeline three ways: offline CLI, embeddable SDK, and a full control plane
-## CLI
+## Install
-The `merger` CLI is the local, installable face of the control plane. It runs
-the same analysis pipeline offline — no services, database, or event bus
-required — so you can classify a diff and preview its merge lane from a laptop
-or a CI job.
+Recommended (Go):
```bash
go install github.com/devr-tools/merger/cmd/merger@latest
-# or: brew install devr-tools/tap/merger
+merger version
+```
+
+Other install paths:
+
+- GitHub Releases: tagged archives for direct download
+- Homebrew: `brew install devr-tools/tap/merger`
+- GitHub Marketplace Action: `Devr Merger`
+- Source build: `make build`
+
+Full setup — including the local control plane, toolchain bootstrap, and the
+GitHub Action — lives in [docs/getting-started.md](docs/getting-started.md).
+
+## Quickstart
+The CLI runs the analysis pipeline offline — no services, database, or event bus
+required — so you can classify a diff and preview its merge lane from a laptop or
+a CI job:
+
+```bash
merger init # scaffold .merger/ config + policy
merger validate # check config and policy resolve
merger scan -base-ref origin/main # analyze the diff vs a base ref
merger scan -diff change.diff -format json
```
-`merger scan` parses a unified diff (from `-diff ` or a
-`-base-ref [` git range), runs mutation detection, runtime-graph, risk,
-policy, and lane assignment, and prints a report (`-format text|json`). Pass
-`-fail-on-lane RED` to exit non-zero when a change lands in a given lane or
-higher — useful as a CI gate.
-
-Configuration is auto-discovered from `merger.yaml` or `.merger/merger.yaml`
-(see [internal/cli](/Users/alex/Documents/GitHub/merger/internal/cli:1) and the
-offline pipeline in [internal/scan](/Users/alex/Documents/GitHub/merger/internal/scan/scan.go:1)).
+`merger scan` parses a unified diff (from `-diff ` or a `-base-ref ][`
+git range), runs mutation detection, runtime-graph, risk, policy, and lane
+assignment, and prints a report (`-format text|json`). Pass `-fail-on-lane RED`
+to exit non-zero when a change lands in a given lane or higher — a ready-made CI
+gate.
+Configuration is auto-discovered from `merger.yaml` or `.merger/merger.yaml`.
`merger mcp` serves the same analysis as agent tools over the Model Context
Protocol (stdio) — see [docs/mcp.md](docs/mcp.md).
## SDK
-The same offline pipeline is available as a library from
+The offline pipeline is available as a library from
`github.com/devr-tools/merger/pkg/merger`:
```go
@@ -89,37 +115,34 @@ func main() {
Load a policy rule set with `merger.LoadPolicy(path)` and pass it as
`ScanOptions.Policy`. See [docs/sdk.md](docs/sdk.md).
-## Architecture
-
-The repository is organized around domain boundaries instead of a single service package:
-
-- `cmd/merger-ingest`: HTTP ingress for GitHub pull request webhooks.
-- `cmd/merger-controlplane`: control-plane process for downstream orchestration and subscriptions.
-- `internal/domain`: strongly typed core models such as `ChangePacket`, `Mutation`, `Risk`, and `PolicyDecision`.
-- `internal/ingest`: request handling and Change Packet assembly.
-- `internal/mutations`: semantic mutation engine and signal extractors.
-- `internal/risk`: weighted risk scoring and risk summary generation.
-- `internal/policy`: YAML-backed policy evaluation.
-- `internal/lanes`: merge lane assignment.
-- `internal/runtimegraph`: runtime graph contracts and pluggable topology sources.
-- `internal/github`: GitHub App auth, webhook verification, PR/diff fetch, file content fetch, and check publishing.
-- `internal/events`: async-friendly event bus abstraction with memory and NATS JetStream implementations.
-- `internal/store`: PostgreSQL-backed persistence for Change Packets and emitted events.
-- `internal/bootstrap`: provider construction for first-party adapters.
-- `internal/telemetry`: structured logging, correlation IDs, and trace-ready interfaces.
-- `pkg/diff`: unified diff parsing reusable across services.
-- `pkg/merger`: public aliases for core MergeR types.
-- `pkg/extensions`: public provider interfaces for open-source extension.
-- `tests/`: black-box and package-level tests kept separate from source packages.
-
-## Merge Lane Model
-
-- `GREEN`: isolated, low-risk mutation with automated evidence and no mandatory human escalation.
-- `YELLOW`: standard review path.
-- `RED`: high-risk or owner/security-gated change.
-- `BLACK`: blocked; decomposition, rework, or policy exception required.
-
-## Change Packet Flow
+## Merge lane model
+
+- `GREEN` — isolated, low-risk mutation with automated evidence and no mandatory human escalation.
+- `YELLOW` — standard review path.
+- `RED` — high-risk or owner/security-gated change.
+- `BLACK` — blocked; decomposition, rework, or policy exception required.
+
+Policies are YAML and intentionally composable:
+
+```yaml
+policies:
+ - name: auth_requires_security_review
+ when:
+ mutations:
+ - auth_behavior_change
+ require:
+ reviewers:
+ - security
+ evidence:
+ - auth_integration_tests
+ deployment:
+ strategy: canary
+ requires_canary: true
+ action:
+ minimum_lane: RED
+```
+
+## Change Packet flow
```mermaid
flowchart LR
@@ -153,85 +176,32 @@ flowchart LR
lane --> bus
```
-1. GitHub sends a `pull_request` webhook.
-2. The ingest service creates a correlation-aware processing context.
-3. Pull request metadata, diff, and file content are fetched through the GitHub App adapter.
-4. The diff parser produces normalized changed files.
-5. The mutation engine combines path rules, patch signals, and AST/structured analyzers.
-6. Runtime graph sources ingest topology hints such as deploy manifests and `CODEOWNERS`.
-7. The risk engine computes risks and an aggregate risk score.
-8. The policy engine resolves reviewers, evidence, deployment constraints, and blockers.
-9. The lane assigner selects `GREEN`, `YELLOW`, `RED`, or `BLACK`.
-10. Change Packets and event envelopes are persisted in PostgreSQL.
-11. A GitHub Check Run summary is published and internal events are emitted through NATS JetStream.
-
-See [docs/flows/github-webhook-flow.md](/Users/alex/Documents/GitHub/merger/docs/flows/github-webhook-flow.md:1) for the detailed flow and [docs/examples/change-packet.json](/Users/alex/Documents/GitHub/merger/docs/examples/change-packet.json:1) for a sample Change Packet.
-
-## Policy Example
-
-Policies are YAML and intentionally composable:
-
-```yaml
-policies:
- - name: auth_requires_security_review
- when:
- mutations:
- - auth_behavior_change
- require:
- reviewers:
- - security
- evidence:
- - auth_integration_tests
- deployment:
- strategy: canary
- requires_canary: true
- action:
- minimum_lane: RED
-```
-
-## Local Development
-
-Merger now requires Go `1.25.10` for local development and CI. That upgrade is part of the security baseline, not an optional tooling preference.
-
-Bootstrap the expected toolchain into your shell before running repo commands:
-
-```bash
-eval "$(./scripts/dev/use-go-1.25.10.sh)"
-go version
-```
-
-That helper installs the `go1.25.10` launcher if needed, downloads the toolchain into `$HOME/sdk/go1.25.10`, and exports `GOROOT`, `PATH`, and `GO` for the current shell.
+See [docs/flows/github-webhook-flow.md](docs/flows/github-webhook-flow.md) for
+the detailed flow and [docs/examples/change-packet.json](docs/examples/change-packet.json)
+for a sample Change Packet.
-After that one-time install, plain `make` targets will automatically prefer `$HOME/sdk/go1.25.10/bin/go` when it exists, so `make ci` does not depend on your shell defaulting to the right Go version.
+## Open-source shape
-Use the provided compose stack for platform dependencies:
+merger is built as an open-source platform core. The repository ships first-party
+implementations for GitHub, NATS, and PostgreSQL, but the extension seams are
+public so other organizations can plug in their own SCM systems, topology sources,
+event backbones, analyzers, and persistence adapters. See
+[docs/extending-merger.md](docs/extending-merger.md) for the current extension
+surface.
-```bash
-make compose-up
-make run-ingest
-make run-controlplane
-```
-
-Default services:
+## Docs
-- Ingest HTTP: `:8080`
-- Control-plane HTTP: `:8081`
-- Control-plane gRPC: `:9091`
-- PostgreSQL: `:5432`
-- Redis: `:6379`
-- NATS: `:4222`
+- [Getting started](docs/getting-started.md)
+- [SDK guide](docs/sdk.md)
+- [MCP server](docs/mcp.md)
+- [Extending merger](docs/extending-merger.md)
+- [GitHub webhook flow](docs/flows/github-webhook-flow.md)
+- [Release automation](docs/release-automation.md)
+- [Contributing](CONTRIBUTING.md)
+- [Security](SECURITY.md)
-Suggested verification:
+---
-```bash
-make verify
-```
-
-## Near-Term TODOs
-
-- Add Kafka and non-GitHub SCM providers to validate the public extension model.
-- Expand runtime graph ingestion from service catalogs, deployment systems, and ownership registries.
-- Add analyzer SDK examples for out-of-tree semantic detectors.
-- Introduce replay workers and outbox-based delivery guarantees.
-- Learn policy weights and lane thresholds from deploy outcomes and incident history.
-- Upgrade generated protobuf plugins in lockstep with future gRPC releases.
+]
+ Apache 2.0 · part of the devr-tools suite
+
diff --git a/docs/getting-started.md b/docs/getting-started.md
new file mode 100644
index 0000000..5f1285a
--- /dev/null
+++ b/docs/getting-started.md
@@ -0,0 +1,176 @@
+# Getting Started
+
+This guide covers installing `merger`, running your first scan, and standing up
+the full control plane locally. If you only want to classify a diff and preview
+its merge lane, you can stop after [Install](#install) and [First scan](#first-scan)
+— no services, database, or event bus required.
+
+## Prerequisites
+
+| Use case | Requirements |
+| --- | --- |
+| CLI / SDK | Go `1.25+` (only to build from source or `go install`; prebuilt binaries need nothing) |
+| Local control plane | Docker + Docker Compose, Go `1.25.10` |
+| GitHub Action | None — the action installs `merger` for you |
+
+## Install
+
+Recommended (Go):
+
+```bash
+go install github.com/devr-tools/merger/cmd/merger@latest
+merger version
+```
+
+Other install paths:
+
+- **GitHub Releases** — tagged archives for direct download
+- **Homebrew** — `brew install devr-tools/tap/merger`
+- **GitHub Marketplace Action** — `Devr Merger` (see [GitHub Action](#github-action))
+- **Source build** — `make build` produces `./bin/merger`
+
+## First scan
+
+`merger` runs the same analysis pipeline the control plane uses, entirely
+offline. Scaffold a config, validate it, then scan a diff:
+
+```bash
+merger init # scaffold .merger/ config + policy
+merger validate # check config and policy resolve
+merger scan -base-ref origin/main # analyze the diff vs a base ref
+```
+
+You can also feed a diff file (or stdin) directly and choose an output format:
+
+```bash
+merger scan -diff change.diff -format json
+git diff main...HEAD | merger scan -diff - -format text
+```
+
+Use `merger scan` as a CI gate by failing on a lane threshold:
+
+```bash
+merger scan -base-ref origin/main -fail-on-lane RED
+```
+
+This exits non-zero when the assigned lane is at or above `RED`.
+
+### Configuration discovery
+
+`merger` auto-discovers configuration from, in order:
+
+1. `merger.yaml` in the repository root
+2. `.merger/merger.yaml`
+
+Point `-config` at an explicit file or a directory (such as `.merger`) to
+override discovery. Policies default to the config's policy path; override with
+`-policy `.
+
+A minimal, composable policy looks like:
+
+```yaml
+policies:
+ - name: auth_requires_security_review
+ when:
+ mutations:
+ - auth_behavior_change
+ require:
+ reviewers:
+ - security
+ evidence:
+ - auth_integration_tests
+ deployment:
+ strategy: canary
+ requires_canary: true
+ action:
+ minimum_lane: RED
+```
+
+## MCP server
+
+Serve the same offline analysis as agent tools over the Model Context Protocol
+(stdio):
+
+```bash
+merger mcp
+```
+
+Point an MCP client at the `merger mcp` command as a stdio server. See
+[docs/mcp.md](mcp.md) for the tool contract.
+
+## GitHub Action
+
+Add the `Devr Merger` action to gate pull requests on their assigned lane:
+
+```yaml
+- uses: devr-tools/merger@v1
+ with:
+ base-ref: ${{ github.base_ref }}
+ fail-on-lane: RED
+```
+
+| Input | Default | Description |
+| --- | --- | --- |
+| `base-ref` | `main` | Base ref to diff against (`git diff ...HEAD`) |
+| `config` | auto-discover | Path to a config file or directory |
+| `repo-root` | `.` | Repository root for content lookups and relative paths |
+| `format` | `text` | Output format (`text` or `json`) |
+| `fail-on-lane` | report only | Fail when the assigned lane is at or above this lane |
+| `version` | `latest` | `merger` version to install |
+
+## Run the control plane locally
+
+The full control plane (webhook ingest, persistence, event bus) needs the local
+toolchain and the Compose stack for platform dependencies.
+
+### 1. Bootstrap the toolchain
+
+Merger requires Go `1.25.10` for local development and CI — this is part of the
+security baseline, not an optional preference. Bootstrap it into your shell:
+
+```bash
+eval "$(./scripts/dev/use-go-1.25.10.sh)"
+go version
+```
+
+The helper installs the `go1.25.10` launcher if needed, downloads the toolchain
+into `$HOME/sdk/go1.25.10`, and exports `GOROOT`, `PATH`, and `GO` for the
+current shell. After that one-time install, plain `make` targets prefer
+`$HOME/sdk/go1.25.10/bin/go` when it exists, so `make ci` does not depend on your
+shell defaulting to the right Go version.
+
+### 2. Start dependencies and services
+
+```bash
+make compose-up # Postgres, Redis, NATS via deployments/local/docker-compose.yml
+make run-ingest # HTTP ingress for GitHub pull_request webhooks
+make run-controlplane # downstream orchestration and subscriptions
+```
+
+Default ports:
+
+| Service | Port |
+| --- | --- |
+| Ingest HTTP | `:8080` |
+| Control-plane HTTP | `:8081` |
+| Control-plane gRPC | `:9091` |
+| PostgreSQL | `:5432` |
+| Redis | `:6379` |
+| NATS | `:4222` |
+
+Tear the stack down with `make compose-down`.
+
+### 3. Verify
+
+```bash
+make verify # test-all + build
+make ci # full local CI (fmt, vet, tests, coverage, lint, security)
+```
+
+## Next steps
+
+- [SDK guide](sdk.md) — embed the offline pipeline as a Go library
+- [MCP server](mcp.md) — agent tool contract
+- [Extending merger](extending-merger.md) — plug in your own SCM, topology, event, and persistence adapters
+- [GitHub webhook flow](flows/github-webhook-flow.md) — detailed end-to-end flow
+- [Release automation](release-automation.md) — how releases are cut