docs: add testing + release checklist; fix contributing links

CONTRIBUTING.md

@@ -11,8 +11,9 @@ This repo welcomes contributions in three broad categories:
 ## Where to start
 
 - Docs landing page: [Docs landing](./docs/README.md)
-- Development workflow: [Development workflow](./docs/03-development.md)
-- Testing guide: [Testing guide](./docs/testing/README.md)
+- Development workflow: [Development](./docs/development/README.md)
+- Testing guide: [Testing](./docs/testing/README.md)
+- Release checklist: [Release checklist](./docs/release/README.md)
 
 ## Filing issues
 

docs/README.md

@@ -5,8 +5,10 @@ This folder is the documentation home for **OpenClaw Mission Control**.
 ## Start here
 
 - [Getting started](./getting-started/README.md)
-- [Deployment](./deployment/README.md)
 - [Development](./development/README.md)
+- [Testing](./testing/README.md)
+- [Deployment](./deployment/README.md)
+- [Release checklist](./release/README.md)
 - [Operations](./operations/README.md)
 - [Troubleshooting](./troubleshooting/README.md)
 - [Gateway agent provisioning and check-in troubleshooting](./troubleshooting/gateway-agent-provisioning.md)

docs/development/README.md

@@ -2,15 +2,58 @@
 
 This section is for contributors developing Mission Control locally.
 
-## Useful commands
+## Recommended workflow (fast loop)
+
+Run Postgres in Docker, run backend + frontend on your host.
+
+### 1) Start Postgres
 
 From repo root:
 
+```bash
+cp .env.example .env
+docker compose -f compose.yml --env-file .env up -d db
+```
+
+### 2) Run the backend (dev)
+
+```bash
+cd backend
+cp .env.example .env
+
+uv sync --extra dev
+uv run uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
+```
+
+Verify:
+
+```bash
+curl -f http://localhost:8000/healthz
+```
+
+### 3) Run the frontend (dev)
+
+```bash
+cd frontend
+cp .env.example .env.local
+npm install
+npm run dev
+```
+
+Open http://localhost:3000.
+
+## Useful repo-root commands
+
 ```bash
 make help
 make setup
 make check
 ```
 
-> **Note**
-> Add deeper guides here (frontend, backend, DB/migrations) as the workflow stabilizes.
+- `make setup`: sync backend + frontend deps
+- `make check`: lint + typecheck + tests + build (closest CI parity)
+
+## Related docs
+
+- [Testing](../testing/README.md)
+- [Release checklist](../release/README.md)

docs/release/README.md

@@ -0,0 +1,62 @@
+# Release checklist
+
+This is a lightweight, operator-friendly checklist for releasing Mission Control.
+
+> Goal: **no data loss** and **near-zero (ideally zero) user-visible downtime**.
+
+## Before you release
+
+- [ ] Confirm the target version/commit SHA.
+- [ ] Review merged PRs since last release (especially DB schema/auth changes).
+- [ ] Ensure CI is green on the target SHA.
+- [ ] Confirm you have:
+  - [ ] access to the host(s)
+  - [ ] access to Postgres backups (or snapshots)
+  - [ ] a rollback plan
+
+## Database safety
+
+- [ ] Verify migrations are **backward compatible** with the current running app (if doing rolling deploys).
+- [ ] Take a backup / snapshot.
+- [ ] If migrations are risky or not backward compatible, schedule a maintenance window.
+
+## Deploy (Docker Compose)
+
+- [ ] Pull / build the new images (or update the repo checkout).
+- [ ] Apply migrations (if you run them manually):
+
+```bash
+# example: if running backend locally on the host
+cd backend
+uv run alembic upgrade head
+```
+
+- [ ] Restart services with minimal disruption:
+
+```bash
+docker compose -f compose.yml --env-file .env up -d --build
+```
+
+## Post-deploy verification
+
+- [ ] Backend health: `GET /healthz` returns 200
+- [ ] Backend readiness: `GET /readyz` returns 200
+- [ ] Frontend loads (no console spam)
+- [ ] Login works (local/clerk mode)
+- [ ] Core flows work end-to-end:
+  - [ ] View board
+  - [ ] Create/update a task
+  - [ ] Post a comment
+  - [ ] Heartbeat check-in succeeds
+
+## Rollback (if needed)
+
+- [ ] Roll back the app version (compose / images).
+- [ ] If migrations were applied and are not reversible, rollbacks may require a DB restore.
+
+## Notes to keep this honest
+
+- If you add a new operational dependency (e.g., redis), update:
+  - `README.md` (overview + quickstart)
+  - `docs/deployment/README.md`
+  - this checklist

docs/testing/README.md

@@ -1,3 +1,82 @@
-# Testing guide
+# Testing
 
-Placeholder: see root `README.md` and `CONTRIBUTING.md` for current commands.
+This guide describes how to run Mission Control tests locally.
+
+## Quick start (repo root)
+
+```bash
+make setup
+make check
+```
+
+`make check` is the closest thing to “CI parity”:
+
+- backend: lint + typecheck + unit tests (with scoped coverage gate)
+- frontend: lint + typecheck + unit tests (Vitest) + production build
+
+## Backend tests
+
+From repo root:
+
+```bash
+make backend-test
+make backend-coverage
+```
+
+Or from `backend/`:
+
+```bash
+cd backend
+uv run pytest
+```
+
+Notes:
+
+- Some tests may require a running Postgres (see root `compose.yml`).
+- `make backend-coverage` enforces a strict coverage gate on a scoped set of modules.
+
+## Frontend tests
+
+From repo root:
+
+```bash
+make frontend-test
+```
+
+Or from `frontend/`:
+
+```bash
+cd frontend
+npm run test
+npm run test:watch
+```
+
+## End-to-end (Cypress)
+
+The frontend has Cypress configured in `frontend/cypress/`.
+
+Typical flow:
+
+1) Start the stack (or start backend + frontend separately)
+2) Run Cypress
+
+Example (two terminals):
+
+```bash
+# terminal 1
+cp .env.example .env
+docker compose -f compose.yml --env-file .env up -d --build
+```
+
+```bash
+# terminal 2
+cd frontend
+npm run e2e
+```
+
+Or run interactively:
+
+```bash
+cd frontend
+npm run e2e:open
+```