docs: align README + governance docs with current state (uninstall, files, ADR index, ship-archive) (#59)

Multiple documentation polish items rolled into one PR (one layer:
"docs alignment with current state").

### README.md

- **Uninstall section** added between Server Setup and Client Setup
  (was missing — `node uninstall.mjs` exists but went undocumented).
- **OpenClaw definition** added as a footnote on first README mention
  (the architecture diagram and Supported Tools table both reference
  OpenClaw without ever defining it).
- **Repository Layout section** added before Security — table of
  top-level files (server.mjs, setup.mjs, uninstall.mjs, keys.mjs,
  models.json, ocp/ocp-connect, dashboard.html, scripts/, .claude/skills/,
  ocp-plugin/, docs/adr/, ALIGNMENT.md, AGENTS.md, CLAUDE.md) so a new
  contributor knows what each file does.
- **LICENSE link** added to the License section footer.

### docs/adr/README.md (new)

- Index of the three published ADRs (0002, 0003, 0004) with a one-line
  description each.
- Explains the `0001` placeholder (early internal proposal that was
  superseded; numbering deliberately starts at `0002`).
- Guidance on when to write a new ADR vs. when a commit message suffices.

### Spec/plan housekeeping

- `specs/.gitkeep` removed (the empty `specs/` placeholder confused the
  picture; canonical paths are `docs/superpowers/plans/` for active plans
  and `docs/superpowers/specs/` for long-lived design docs that other
  code references).
- Shipped plans moved to `docs/superpowers/plans/shipped/`:
  - `2026-04-10-lan-mode.md` (shipped: README LAN mode section)
  - `2026-04-25-47-sse-heartbeat-plan.md` (shipped: v3.12.0 per CHANGELOG)
- `2026-04-25-47-sse-heartbeat-design.md` left in `docs/superpowers/specs/`
  unchanged because both `server.mjs:565` and `CHANGELOG.md:7` link to
  that exact path; moving it would require a `server.mjs` edit, which
  needs `cli.js` citation per ALIGNMENT.md Rule 1.

### AGENTS.md

- Updated "Key files to know" to add `docs/adr/README.md`,
  `docs/superpowers/plans/`, and `memory/constitution.md`.
- Note explaining `memory/constitution.md` is spec-kit's standard
  location, distinct from `~/.cc-rules/memory/` and `ALIGNMENT.md`.
- Updated "Handoff expectations" item 5 from `docs/superpowers/specs/*/tasks.md`
  (which never matched anything — there were no `tasks.md` files there)
  to `docs/superpowers/plans/` (excluding `shipped/`).

### Coordination with PR #53

PR #53 is open and adds "Why OCP?", "Comparison", and "Governance"
sections to README. This PR deliberately avoids those areas — only edits
the Supported Tools table footnote, inserts Uninstall before Client Setup,
inserts Repository Layout before Security, and updates the License footer.
No expected merge conflict.

Refs: audit findings M6, M8, M9, M11, L2, L3, L6.

Co-authored-by: dtzp555 <dtzp555@gmail.com>

README.md

@@ -55,9 +55,11 @@ Any tool that accepts `OPENAI_BASE_URL` works with OCP:
 | **OpenCode** | `OPENAI_BASE_URL=http://127.0.0.1:3456/v1` |
 | **Aider** | `aider --openai-api-base http://127.0.0.1:3456/v1` |
 | **Continue.dev** | config.json → `apiBase: "http://127.0.0.1:3456/v1"` |
-| **OpenClaw** | `setup.mjs` auto-configures |
+| **OpenClaw** [^openclaw] | `setup.mjs` auto-configures |
 | **Any OpenAI client** | Set base URL to `http://127.0.0.1:3456/v1` |
 
+[^openclaw]: **OpenClaw** is an IDE-agnostic AI coding agent (sibling project to OCP). When OCP runs on the same machine, OpenClaw can use it as a local provider — see `scripts/sync-openclaw.mjs` and ADR 0004.
+
 ## Installation
 
 OCP has two roles: **Server** (runs the proxy, needs Claude CLI) and **Client** (connects to a server, zero dependencies).
@@ -131,6 +133,17 @@ curl http://127.0.0.1:3456/v1/models
 
 ---
 
+### Uninstall
+
+```bash
+# From the cloned repo
+node uninstall.mjs
+```
+
+Removes the launchd (macOS) or systemd (Linux) auto-start entry. Handles both legacy (`ai.openclaw.proxy` / `openclaw-proxy`) and current (`dev.ocp.proxy` / `ocp-proxy`) service names. Does not delete `~/.openclaw/`, `~/.ocp/`, or the cloned repo — remove those manually if desired.
+
+---
+
 ### Client Setup
 
 > Clients do **not** need to install Node.js, Claude CLI, or the OCP repo. Only `curl` and `python3` are required (pre-installed on most Linux/Mac systems).
@@ -645,6 +658,26 @@ Heartbeats are inert SSE comment lines — conforming SSE clients ignore them. I
 
 OCP also sends `X-Accel-Buffering: no` on SSE responses so nginx-default proxy buffering does not hold heartbeats in an upstream buffer.
 
+## Repository Layout
+
+Top-level files a contributor or operator may need to know:
+
+| Path | Role |
+|------|------|
+| `server.mjs` | The proxy itself; every request path lives here. Governed by `ALIGNMENT.md`. |
+| `setup.mjs` | First-time installer — verifies Claude CLI, patches OpenClaw config, installs auto-start. |
+| `uninstall.mjs` | Reverses the launchd / systemd auto-start install. |
+| `keys.mjs` | API-key management module (multi-mode auth: create/list/revoke, quotas, usage tracking). |
+| `models.json` | Single source of truth for model IDs, aliases, context windows. See ADR 0003. |
+| `ocp` / `ocp-connect` | User-facing CLI wrappers (server-side / client-side respectively). |
+| `dashboard.html` | Static dashboard served from `/dashboard`. |
+| `scripts/sync-openclaw.mjs` | Idempotent OpenClaw registry sync invoked by `ocp update`. See ADR 0004. |
+| `.claude/skills/` | Project-specific Claude Code skills. |
+| `ocp-plugin/` | OpenClaw gateway plugin (optional installation). |
+| `docs/adr/` | Architecture Decision Records. Read these before proposing governance or SPOT changes — see [`docs/adr/README.md`](docs/adr/README.md). |
+| `ALIGNMENT.md` | The constitution. Binding for any `server.mjs` change. |
+| `AGENTS.md` / `CLAUDE.md` | Agent and Claude-Code-specific session instructions. |
+
 ## Security
 
 - **Localhost by default** — binds to `127.0.0.1`; set `CLAUDE_BIND=0.0.0.0` to enable LAN access
@@ -670,4 +703,4 @@ If you want to contribute: read `ALIGNMENT.md` first, search `cli.js` for the op
 
 ## License
 
-MIT
+MIT — see [`LICENSE`](LICENSE).