diff --git a/README.md b/README.md
index e5b3673..a3af0d7 100644
--- a/README.md
+++ b/README.md
@@ -8,7 +8,25 @@ It federates existing registries — the official MCP Registry, Smithery, Glama,
 
 ## Status
 
-**v0.0.0 — scaffold only.** Commands are stubs while the underlying engine is built.
+**v0.1 in active build.** Working subcommands today:
+
+| Command | What it does |
+|---|---|
+| `pakx init` | Interactive scaffolder for `agents.yml`. |
+| `pakx add <id>` | Append a dep to the manifest; best-effort validation against the official MCP Registry. |
+| `pakx install` | Resolve every MCP dep via the federated registry, install into Claude Code's project-scoped `.mcp.json`, and write `agents.lock`. |
+| `pakx list` | Show pinned lockfile entries with `[ok]` / `[drift]` against on-disk reality. |
+| `pakx doctor` | 5-section health check (manifest, lockfile, drift, adapter detection, on-disk vs lockfile). |
+| `pakx search <query>` | Federated search across registered sources. |
+
+In progress:
+- Smithery + GitHub-raw skill source (so `pakx install` covers skills too).
+- `pakx login` / `pakx pack` / `pakx publish` (Phase C — needs the registry backend).
+- `pakxdev/pakx-registry` (Phase B — Next.js + Vercel Postgres + Vercel Blob, hosts publish/auth/private packages).
+- Web dashboard at [pakx.dev](https://pakx.dev) (Phase D).
+- Stripe Connect marketplace payouts (Phase E).
+
+See [`crates/pakx`](./crates/pakx), [`crates/pakx-core`](./crates/pakx-core), [`crates/pakx-agents`](./crates/pakx-agents), [`crates/pakx-registry-client`](./crates/pakx-registry-client).
 
 ## Install (preview — wired up once first release ships)
 
@@ -45,16 +63,19 @@ winget install pakxdev.pakx
 
 **Direct download:** prebuilt binaries for every supported OS / arch are on the [Releases](https://github.com/pakxdev/pakx/releases) page.
 
-## Quick start (preview)
+## Quick start
 
 ```sh
-pakx init                     # interactive: creates agents.yml
-pakx add pdf                  # add + install anthropics/skills/pdf
-pakx add smithery/github-mcp  # add + install GitHub MCP server
-pakx install                  # idempotent reinstall from manifest
-pakx list                     # show what's installed where
+pakx init                                       # interactive: creates agents.yml
+pakx add io.github.modelcontextprotocol/server-filesystem  # add MCP server
+pakx install                                    # resolve + install + write lockfile
+pakx list                                       # show what's pinned
+pakx doctor                                     # diagnose drift / missing agents
+pakx search github                              # browse the federated registry
 ```
 
+After `pakx install`, Claude Code picks up new MCP servers from `<project>/.mcp.json` automatically.
+
 ## Build from source
 
 Requires Rust 1.87+ (toolchain pinned to `stable` via `rust-toolchain.toml`).
@@ -71,10 +92,14 @@ cargo clippy --workspace --all-targets -- -D warnings
 | Crate | Description |
 |---|---|
 | `pakx` | The binary you install |
-| `pakx-core` | Manifest, lockfile, resolver, installer logic |
+| `pakx-core` | Manifest, lockfile, install payloads, integrity hashing |
 | `pakx-agents` | Adapters for Claude Code, Cursor, Codex, Copilot, Windsurf |
 | `pakx-registry-client` | Federated index queries (MCP Registry, Smithery, Glama, GitHub) |
 
+## Contributing
+
+PRs welcome. Every change goes through a feature branch + PR + squash auto-merge (no direct main pushes). CI runs `fmt`, `clippy --all-targets -D warnings`, and the test matrix on ubuntu / macos / windows for every commit.
+
 ## License
 
 MIT — see [LICENSE](./LICENSE).
diff --git a/crates/pakx/tests/smoke.rs b/crates/pakx/tests/smoke.rs
index 8d3ee4c..464435b 100644
--- a/crates/pakx/tests/smoke.rs
+++ b/crates/pakx/tests/smoke.rs
@@ -44,13 +44,17 @@ fn init_help_runs() {
 }
 
 #[test]
-fn install_subcommand_runs() {
+fn install_help_runs() {
+    // Bare `install` without a manifest would fail trying to read agents.yml;
+    // smoke-coverage uses --help. End-to-end install flow lives in
+    // tests/install.rs.
     Command::cargo_bin(BIN)
         .unwrap()
-        .arg("install")
+        .args(["install", "--help"])
         .assert()
         .success()
-        .stderr(predicate::str::contains("pakx v0.0.0"));
+        .stdout(predicate::str::contains("Install everything"))
+        .stdout(predicate::str::contains("--no-lockfile"));
 }
 
 #[test]