docs: fill in development + testing guides

CONTRIBUTING.md

@@ -40,11 +40,22 @@ If you accidentally based your branch off another feature branch, fix it by cher
 
 ### Expectations
 
+- Open a PR as **Draft** early (especially for multi-step work) so progress is visible and local changes aren’t lost.
 - Keep PRs **small and focused** when possible.
 - Include a clear description of the change and why it’s needed.
 - Add/adjust tests when behavior changes.
 - Update docs when contributor-facing or operator-facing behavior changes.
 
+### Draft PR policy
+
+- Start as **Draft** when:
+  - the PR is incomplete,
+  - CI is expected to fail,
+  - or you need early feedback on direction.
+- Mark **Ready for review** when:
+  - `make check` is green locally (or you’ve explained why it can’t be), and
+  - the description includes repro/verification notes.
+
 ### Local checks
 
 From repo root, the closest “CI parity” command is:

README.md

@@ -112,6 +112,15 @@ make setup
 make check
 ```
 
+## Contributing / PR workflow
+
+- Contribution guide: [`CONTRIBUTING.md`](./CONTRIBUTING.md)
+- Preferred flow: open a **Draft PR early**, then iterate until `make check` is green.
+
+## Releasing
+
+- Maintainer checklist: [Release checklist](./docs/release/README.md)
+
 ## License
 
 This project is licensed under the MIT License. See [`LICENSE`](./LICENSE).

backend/tests/test_error_handling.py

@@ -14,6 +14,7 @@ from app.core.error_handling import (
     _error_payload,
     _get_request_id,
     _http_exception_exception_handler,
+    _json_safe,
     _request_validation_exception_handler,
     _response_validation_exception_handler,
     install_error_handling,
@@ -209,6 +210,23 @@ def test_error_payload_omits_request_id_when_none() -> None:
     assert _error_payload(detail="x", request_id=None) == {"detail": "x"}
 
 
+def test_json_safe_decodes_bytes() -> None:
+    assert _json_safe(b"abc") == "abc"
+
+
+def test_json_safe_decodes_bytearray_and_memoryview() -> None:
+    assert _json_safe(bytearray(b"abc")) == "abc"
+    assert _json_safe(memoryview(b"abc")) == "abc"
+
+
+def test_json_safe_falls_back_to_str() -> None:
+    class Thing:
+        def __str__(self) -> str:
+            return "thing"
+
+    assert _json_safe(Thing()) == "thing"
+
+
 @pytest.mark.asyncio
 async def test_request_validation_exception_wrapper_rejects_wrong_exception() -> None:
     req = Request({"type": "http", "headers": [], "state": {}})

docs/03-development.md

@@ -1,3 +1,58 @@
 # Development workflow
 
-Placeholder: see root `README.md` for current setup steps.
+This page describes a contributor-friendly local dev loop.
+
+## Prereqs
+
+- Python 3.12+
+- Node 22+
+- Docker + Docker Compose v2 (`docker compose`)
+- `uv` (installed automatically by `make backend-sync` in CI; for local install see https://docs.astral.sh/uv/)
+
+## Fast local loop (DB in Docker, apps on host)
+
+1) Start Postgres (via compose)
+
+```bash
+cp .env.example .env
+# Configure .env as needed (see root README for auth-mode notes)
+
+docker compose -f compose.yml --env-file .env up -d db
+```
+
+2) Install deps
+
+```bash
+make setup
+```
+
+3) Apply DB migrations
+
+```bash
+make backend-migrate
+```
+
+4) Run backend (dev)
+
+```bash
+cd backend
+uv run uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
+```
+
+5) Run frontend (dev)
+
+In another terminal:
+
+```bash
+cd frontend
+npm run dev -- --hostname 0.0.0.0 --port 3000
+```
+
+Open:
+- Frontend: http://localhost:3000
+- Backend health: http://localhost:8000/healthz
+
+## Notes
+
+- If you want the fully-containerized stack instead, see the root README’s compose instructions.
+- If you add new env vars, prefer documenting them in `.env.example` and linking from docs rather than pasting secrets.

docs/README.md

@@ -10,6 +10,7 @@ This folder is the starting point for Mission Control documentation.
 - [Deployment](./deployment/README.md)
 - [Production notes](./production/README.md)
 - [Troubleshooting](./troubleshooting/README.md)
+- [Release checklist](./release/README.md)
 - [Gateway WebSocket protocol](./openclaw_gateway_ws.md)
 
 ## Status

docs/release/README.md

@@ -0,0 +1,104 @@
+# Release checklist (maintainers)
+
+This project does not yet have a fully automated release pipeline.
+
+Use this checklist for **manual releases** and as a place to evolve the process over time.
+
+## Before you start
+
+- [ ] You have maintainer permissions on `abhi1693/openclaw-mission-control`
+- [ ] You know which **scope** you’re releasing:
+  - [ ] backend-only change
+  - [ ] frontend-only change
+  - [ ] infra/docs-only change
+  - [ ] full release
+
+## 1) Pick the release commit
+
+- [ ] Ensure you’re on the latest `master`:
+
+```bash
+git fetch origin
+git checkout master
+git reset --hard origin/master
+```
+
+- [ ] Identify the commit SHA you want to release (usually `origin/master`).
+
+## 2) Verify CI + local checks
+
+- [ ] CI is green on the target commit.
+- [ ] Run the local CI-parity checks:
+
+```bash
+make setup
+make check
+make docs-check
+```
+
+## 3) Smoke test (recommended)
+
+If the change affects runtime behavior (API/UI/auth), do a quick smoke test using the compose stack.
+
+```bash
+cp .env.example .env
+# Configure .env (see repo README for auth mode notes)
+
+docker compose -f compose.yml --env-file .env up -d --build
+
+after_up() {
+  echo "Frontend: http://localhost:3000"
+  echo "Backend health: http://localhost:8000/healthz"
+}
+
+after_up
+```
+
+- [ ] Validate basic flows (at minimum):
+  - [ ] frontend loads
+  - [ ] backend `/healthz` returns 200
+  - [ ] auth mode behaves as expected (local or clerk)
+
+## 4) Prepare release notes
+
+There is no enforced changelog format yet.
+
+Choose one:
+- [ ] GitHub Release notes (recommended for now)
+- [ ] `CHANGELOG.md` (TODO: adopt Keep a Changelog)
+
+Minimum release notes:
+- [ ] Summary of key changes
+- [ ] Any config changes / env var changes
+- [ ] Any DB migration notes
+- [ ] Known issues
+
+## 5) Tag + publish
+
+Tagging convention:
+- Use semver tags: `vMAJOR.MINOR.PATCH` (e.g. `v1.4.0`).
+- Create a GitHub Release from the tag (release notes can be manual for now).
+- If the repo already has existing tags/releases, mirror the established convention exactly.
+
+Suggested manual flow:
+
+```bash
+# Example (adjust once tag conventions are decided)
+git tag -a v0.1.0 -m "Release v0.1.0"
+git push origin v0.1.0
+```
+
+- [ ] Create a GitHub Release from the tag
+- [ ] Paste the release notes
+
+## 6) Post-release
+
+- [ ] Monitor new issues for regressions
+- [ ] If you changed public behavior, ensure docs are updated (README + docs pages)
+
+## Notes / follow-ups
+
+- Consider adding:
+  - automated versioning (changesets / semantic-release)
+  - release workflow in `.github/workflows/release.yml`
+  - a `CHANGELOG.md`

docs/testing/README.md

@@ -1,3 +1,57 @@
 # Testing guide
 
-Placeholder: see root `README.md` and `CONTRIBUTING.md` for current commands.
+This repo’s CI parity entrypoint is:
+
+```bash
+make check
+```
+
+That target runs lint + typecheck + unit tests + coverage gate + frontend build.
+
+## Quick commands
+
+From repo root:
+
+```bash
+make setup
+
+# Format + lint + typecheck + tests + build (CI parity)
+make check
+```
+
+Docs-only quality gates:
+
+```bash
+make docs-check
+```
+
+## Backend
+
+```bash
+make backend-lint
+make backend-typecheck
+make backend-test
+make backend-coverage
+```
+
+## Frontend
+
+```bash
+make frontend-lint
+make frontend-typecheck
+make frontend-test
+make frontend-build
+```
+
+## E2E (Cypress)
+
+CI runs Cypress E2E in `.github/workflows/ci.yml`.
+
+Locally, the frontend package.json provides the E2E script:
+
+```bash
+cd frontend
+npm run e2e
+```
+
+If your E2E tests require auth, ensure you have the necessary env configured (see root README for auth mode). Do **not** paste tokens into docs.