docs: restructure README so users can judge fit first

.cursor/skills/verify-pace/SKILL.md

@@ -11,7 +11,7 @@ Read `features/README.md` before driving. One feature file is the recipe. A proo
 
 ## Launch
 
-Human quickstart (hot reload, writes `~/.pace-dev` and a `Pace-dev` userData profile) is `bun install` then `bun run dev`. See README "Quick start" and `docs/dogfooding.md`. Do not use that process for a scripted proof.
+Human quickstart (hot reload, writes `~/.pace-dev` and a `Pace-dev` userData profile) is `bun install` then `bun run dev`. See "Setup" in `CONTRIBUTING.md` and `docs/dogfooding.md`. Do not use that process for a scripted proof.
 
 Verification launch:
 

AGENTS.md

@@ -6,7 +6,7 @@ Pace is the desktop workbench for the [Pi coding agent](https://pi.dev). Pi is t
 
 ## Orientation
 
-The "Architecture" section of `README.md` is the canonical map: the event-pipeline diagram, the "Where things live" table (which file to edit for which concern), and the step-by-step prompt flow. Consult it before searching the codebase. Backend modules mirror that map: `packages/backend/src/{drivers,gateway,persistence,workspace}` with `service.ts` as the composition root.
+`docs/architecture.md` is the canonical map: the event-pipeline diagram, the "代码在哪里" (Where things live) table (which file to edit for which concern), and the step-by-step prompt flow. Consult it before searching the codebase. Backend modules mirror that map: `packages/backend/src/{drivers,gateway,persistence,workspace}` with `service.ts` as the composition root.
 
 Process conventions, each documented in its own file:
 
@@ -17,7 +17,7 @@ Process conventions, each documented in its own file:
 
 ## Verification
 
-Before opening a PR, `bun run typecheck`, `bun run lint`, `bun run test` and `bun run build` must be green (see "Development and verification" in `README.md` for the full command list, including E2E and packaging).
+Before opening a PR, `bun run typecheck`, `bun run lint`, `bun run test` and `bun run build` must be green (see `CONTRIBUTING.md` for the full command list, including E2E and packaging).
 
 ## Design system discipline
 

CONTRIBUTING.md

@@ -61,10 +61,46 @@ All four must be green. Also:
 
 UI work has extra rules in [`docs/design/`](docs/design/). Discover Astryx components before writing new ones; reusable pieces live only in `shared/ui/`.
 
+## Testing, packaging and dev tools
+
+The four commands above are the PR gate. Two more suites cover the edges:
+
+```bash
+bun run test:e2e         # Playwright smoke tests against the dev Electron build
+bun run test:release     # release script and publish behavior tests
+```
+
+The manual `Validate macOS ARM64` workflow runs packaging and the packaged-app E2E on demand.
+
+Packaging:
+
+```bash
+bun run package:mac:unsigned   # unsigned .app + zip, for local testing
+bun run dist:mac               # signed + notarized DMG (needs Apple credentials)
+bun run dist:linux             # AppImage + deb (x64)
+```
+
+The signing, notarization and release pipeline is documented in [`docs/release/macos.md`](docs/release/macos.md). Linux AppImage and deb builds ship on the same tag: [`docs/release/linux.md`](docs/release/linux.md).
+
+Two dev-only tools help when working on the UI locally:
+
+- The `/design` route: a live gallery of the design system, showing every base component under `shared/ui/` with all of its states and variants.
+- The **UI Intent Picker**: press `Cmd/Ctrl+Shift+X` to activate a crosshair, then click any element to copy its CONTEXT.md term, its component stack with file and line, and the nearest `data-testid` (see [`docs/ui-intent-picker.md`](docs/ui-intent-picker.md)).
+
 ## A good first PR
 
 Add a new fixture stream to the event normalizer (`packages/backend/src/gateway/agent-runtime-event-normalizer.test.ts`): record a Pi session, add the raw events, and assert the normalized `AgentRuntimeEvent` sequence. That exercises the protocol without touching UI.
 
+## Documentation map
+
+- [`docs/architecture.md`](docs/architecture.md): the canonical code map — the event pipeline, which file owns which concern, and the step-by-step prompt flow.
+- [`CONTEXT.md`](CONTEXT.md): domain glossary. The terms here are the names used in code, tests and issues.
+- [`docs/adr/`](docs/adr/): architecture decision records, from the control-plane pivot ([ADR-0001](docs/adr/0001-agent-workspace-control-plane.md)) to the current surfaces.
+- [`docs/design/`](docs/design/): which tokens, which Astryx variants, which self-built components.
+- [`docs/release/macos.md`](docs/release/macos.md), [`docs/release/linux.md`](docs/release/linux.md), [`docs/dogfooding.md`](docs/dogfooding.md): shipping and daily-driving Pace.
+- [`docs/agents/`](docs/agents/): how issues, triage labels and domain docs are organized for both human and agent contributors.
+- [`.scratch/<feature>/PRD.md`](.scratch/): point-in-time product requirement records.
+
 ## License
 
 Contributions are accepted under the [Apache License 2.0](LICENSE). There is no CLA. The Pace name and icon are not covered by that grant.