diff --git a/README.md b/README.md
index d02ffd1..f0ad1e3 100644
--- a/README.md
+++ b/README.md
@@ -6,33 +6,73 @@ The kit is MIT-licensed and fully generic — install it on a fresh machine and
 
 ## Prerequisites
 
-- **Rust** (stable toolchain) — the assembler + 8 primitive crates are a Cargo workspace
+**Hard** (needed for every install, regardless of profile):
+
+- **Rust** (stable toolchain) — the assembler Cargo workspace is always built
 - **jq** — used by the shell hooks for JSON parsing (`brew install jq` / `apt install jq`)
 - **Claude Code** — the agents, hooks, and skills target Claude Code's agent / skill / hook surface
-- **pandoc** (soft) — the `tomd` primitive falls back to pandoc for `.docx` / `.pptx` / `.html`
-- **Node + Playwright** (soft) — required for frontend primitives (`design-scrape`, `live-preview`, `mock-render`); install with `npm i -g playwright && playwright install chromium`
-- **sqlite3 CLI** (soft) — the `kei-ledger` / `kei-migrate` crates embed SQLite via `rusqlite`; the CLI is only needed if you want to inspect ledger DBs directly
+
+**Soft** (only needed if the chosen profile pulls the primitive in — see the profile table below):
+
+- **pandoc** — `tomd` uses it for `.docx` / `.pptx` / `.html` (needed for `core` / `full` profile)
+- **Node + Playwright** — for the 3 browser-driven frontend primitives `design-scrape`, `live-preview`, `mock-render` (`frontend` / `full` profile); install with `npm i -g playwright && playwright install chromium`
+- **sqlite3 CLI** — optional for manual DB inspection of `kei-ledger` / `kei-migrate` (their binaries embed SQLite via `rusqlite`; `ops` / `dev` profile)
+- **hcloud / vultr-cli** — wrapped by `provision-hetzner` / `provision-vultr` (`ops` profile)
+- **yq v4** (mikefarah/yq Go impl) — required by `kei-ci-lint` (`dev` profile)
+
+`install.sh` checks only the deps relevant to the selected profile and soft-warns once per missing tool.
 
 ## Install
 
 ```bash
 git clone <your-fork-of-this-repo> KeiSeiKit
 cd KeiSeiKit
-./install.sh
+./install.sh                      # profile=minimal (default, no primitives)
 ```
 
 `install.sh` is idempotent. It:
 
 1. Creates `~/.claude/agents/{_blocks,_manifests,_primitives,_bridges,_templates,_assembler,_generated}`, `~/.claude/hooks`, `~/.claude/skills`
-2. Copies all blocks, primitives (shell + Rust workspace), bridges (overwrites — these are SSoT from the kit)
-3. Copies generic manifests (skips if you already have a manifest with that name)
-4. Builds the Rust assembler (`cargo build --release` in `_assembler/`)
-5. Builds the 8 primitive crates (`cargo build --release` in `_primitives/_rust/`)
-6. Generates agent `.md` files in-place with `AGENT_ROOT=~/.claude/agents assemble --in-place`
-7. Copies the five hooks and 34 skills
+2. Copies all blocks + bridges (overwrites — these are SSoT from the kit)
+3. Copies primitives ONLY for the selected profile (default: `minimal` = none). Tracks installed set in `~/.claude/agents/_primitives/.installed`.
+4. Copies generic manifests (skips if you already have a manifest with that name)
+5. Builds the Rust assembler (`cargo build --release` in `_assembler/`)
+6. If any Rust primitive is in the selected profile: writes a scoped workspace `Cargo.toml` listing ONLY the installed crates, then `cargo build --release`
+7. Generates agent `.md` files in-place with `AGENT_ROOT=~/.claude/agents assemble --in-place`
+8. Copies the six hooks and 34 skills
 
 After install, the only remaining step is merging `settings-snippet.json` into your `~/.claude/settings.json` to activate the hooks. You can do this automatically with `./install.sh --activate-hooks` or answer `y` at the end-of-install TTY prompt.
 
+## Install profiles
+
+By default `./install.sh` is **minimal** — agents + hooks + skills + bridges, no primitives. Fastest (~5s) and zero Rust compile for primitives. You opt into primitives via `--profile=<name>` or one-at-a-time via `--add=<name>`.
+
+| Profile | Primitives added | Install time | Disk (approx) |
+|---|---|---|---|
+| `minimal` (default) | none | ~5s | ~2 MB |
+| `core` | `tomd` | ~5s | ~2 MB |
+| `frontend` | 8 site tools: `mock-render`, `visual-diff`, `tokens-sync`, `design-scrape`, `live-preview`, `figma-tokens`, `frontend-inspect`, `screenshot-decode` | ~60s | ~80 MB |
+| `ops` | 8 infra tools: `kei-ledger`, `ssh-check`, `firewall-diff`, `provision-hetzner`, `provision-vultr`, `harden-base`, `metrics-scrape`, `log-ship` | ~90s | ~50 MB |
+| `dev` | 4 dev tools: `kei-migrate`, `kei-changelog`, `kei-ci-lint`, `kei-docs-scaffold` | ~60s | ~40 MB |
+| `full` | everything (21 primitives) | ~5 min | ~200 MB |
+
+Examples:
+
+```bash
+./install.sh                        # minimal (no primitives)
+./install.sh --profile=frontend     # minimal + 8 site tools
+./install.sh --profile=full         # everything (old default behaviour)
+./install.sh --add=kei-ledger       # add a single primitive on top of current install
+./install.sh --add=kei-ledger,ssh-check
+./install.sh --add=ops              # a profile name works too — unions its members in
+./install.sh --list                 # show each primitive: name | kind | installed? | description
+./install.sh --remove=kei-migrate   # remove one (rebuilds scoped rust workspace if needed)
+```
+
+Profile resolution lives in `_primitives/MANIFEST.toml` — one `[primitive.<name>]` entry per primitive plus a `[profile]` block. Edit the manifest to define new profiles without touching `install.sh`.
+
+> **Migrating from a full install:** if you're re-running `install.sh` after an earlier version that installed all 21 primitives unconditionally, the new default (`minimal`) will REMOVE them. To preserve the old behaviour explicitly, pass `--profile=full`.
+
 > **Re-install disclaimer:** `install.sh` is idempotent for clean state but **overwrites kit-owned `_blocks/`, `_primitives/`, `_bridges/`, `_templates/`, `_assembler/`, `hooks/`, and `skills/` on re-run** — local modifications under those directories are backed up to `<dir>.bak-TIMESTAMP/` (or, for shared hook files, to `<file>.bak-TIMESTAMP`). User-owned `_manifests/*.toml` are never overwritten.
 
 ## What you get
@@ -43,8 +83,8 @@ After install, the only remaining step is merging `settings-snippet.json` into y
 | Generic agents (manifests) | 12 | `kei-code-implementer`, `kei-critic`, `kei-validator`, `kei-security-auditor`, `kei-architect`, `kei-researcher`, `kei-ml-implementer`, `kei-cost-guardian`, `kei-modal-runner`, ... |
 | Hooks | 6 | `assemble-agents`, `assemble-validate`, `no-hand-edit-agents`, `tomd-preread`, `agent-fork-logger`, `site-wysiwyd-check` |
 | Portable skills | 34 | `compose-solution`, `new-agent`, `new-project`, `site-create`, `schema-design`, `observability-setup`, `auth-setup`, `api-design`, `ci-scaffold`, `test-matrix`, `docs-scaffold`, `vm-provision`, ... |
-| Primitives (Rust crates) | 8 | `kei-ledger`, `kei-migrate`, `kei-changelog`, `ssh-check`, `firewall-diff`, `mock-render`, `visual-diff`, `tokens-sync` |
-| Primitives (shell) | 13 | `tomd`, `design-scrape`, `live-preview`, `figma-tokens`, `frontend-inspect`, `screenshot-decode`, `metrics-scrape`, `log-ship`, `provision-hetzner`, `provision-vultr`, `harden-base`, `kei-ci-lint`, `kei-docs-scaffold` |
+| Primitives (Rust crates, opt-in) | 8 | `kei-ledger`, `kei-migrate`, `kei-changelog`, `ssh-check`, `firewall-diff`, `mock-render`, `visual-diff`, `tokens-sync` |
+| Primitives (shell, opt-in) | 13 | `tomd`, `design-scrape`, `live-preview`, `figma-tokens`, `frontend-inspect`, `screenshot-decode`, `metrics-scrape`, `log-ship`, `provision-hetzner`, `provision-vultr`, `harden-base`, `kei-ci-lint`, `kei-docs-scaffold` |
 | Cross-tool bridges | 11 | Cursor legacy/MDC, Codex, Copilot, Windsurf, Junie, Continue, Gemini, Aider, Replit |
 
 Of the 73 blocks, the **8 base blocks** (`baseline`, `evidence-grading`, `memory-protocol`, `rule-pre-dev-gate`, `rule-test-first`, `rule-error-budget`, `rule-double-audit`, `rule-math-first`) are referenced directly by the 12 shipped manifests. The remaining blocks (`stack-*`, `deploy-*`, `api-*`, `scraper-*`, `domain-*`) are a library consumed by the `/new-agent` wizard and the hub-and-spoke pipeline skills: when you compose a project specialist or spin up a site, the wizard / pipeline picks the appropriate blocks and emits artefacts that reference them.