docs: add initial docs/ information architecture + stubs

docs/README.md

@@ -1,20 +1,24 @@
-# Mission Control docs
+# Mission Control Docs
 
-This folder is the starting point for Mission Control documentation.
+This folder is the documentation home for **OpenClaw Mission Control**.
 
-## Sections
+## Start here
 
-- [Development workflow](./03-development.md)
+- [Getting started](./getting-started/README.md)
-- [Testing guide](./testing/README.md)
-- [Coverage policy](./coverage-policy.md)
 - [Deployment](./deployment/README.md)
-- [Production notes](./production/README.md)
+- [Development](./development/README.md)
+- [Operations](./operations/README.md)
 - [Troubleshooting](./troubleshooting/README.md)
 - [Gateway agent provisioning and check-in troubleshooting](./troubleshooting/gateway-agent-provisioning.md)
 - [Gateway WebSocket protocol](./openclaw_gateway_ws.md)
 - [OpenClaw baseline configuration](./openclaw_baseline_config.md)
 
-## Status
+## Reference
 
-These pages are minimal placeholders so repo-relative links stay healthy. The actual docs
+- [Configuration reference](./reference/configuration.md)
-information architecture will be defined in the Docs overhaul tasks.
+- [Authentication](./reference/authentication.md)
+- [API notes](./reference/api.md)
+
+## Contributing to docs
+
+- [Docs style guide](./style-guide.md)

docs/architecture/README.md

@@ -0,0 +1,10 @@
+# Architecture
+
+## High level
+
+- Frontend: Next.js
+- Backend: FastAPI
+- Database: Postgres
+
+> **Note**
+> Add component diagrams and key data flows (auth, task lifecycle, gateway integration) as they solidify.

docs/deployment/README.md

@@ -1,3 +1,13 @@
-# Deployment guide
+# Deployment
 
-Placeholder.
+This section covers deploying Mission Control in self-hosted environments.
+
+## Topics
+
+- Docker Compose (single host)
+- Environment variables and secrets
+- Database persistence and migrations
+- Reverse proxy / TLS
+
+> **Note**
+> This page is currently a stub; expand it as deployment patterns stabilize.

docs/development/README.md

@@ -0,0 +1,16 @@
+# Development
+
+This section is for contributors developing Mission Control locally.
+
+## Useful commands
+
+From repo root:
+
+```bash
+make help
+make setup
+make check
+```
+
+> **Note**
+> Add deeper guides here (frontend, backend, DB/migrations) as the workflow stabilizes.

docs/getting-started/README.md

@@ -0,0 +1,30 @@
+# Getting started
+
+## What is Mission Control?
+
+Mission Control is the web UI and HTTP API for operating OpenClaw.
+
+It provides a control plane for boards, tasks, agents, approvals, and (optionally) gateway connections.
+
+## Quickstart (Docker Compose)
+
+From repo root:
+
+```bash
+cp .env.example .env
+
+# REQUIRED when AUTH_MODE=local
+# Set LOCAL_AUTH_TOKEN to a non-placeholder value with at least 50 characters.
+
+docker compose -f compose.yml --env-file .env up -d --build
+```
+
+Open:
+- Frontend: http://localhost:3000
+- Backend health: http://localhost:8000/healthz
+
+## Next steps
+
+- [Authentication](../reference/authentication.md)
+- [Deployment](../deployment/README.md)
+- [Development](../development/README.md)

docs/operations/README.md

@@ -0,0 +1,10 @@
+# Operations
+
+Runbooks and operational notes for running Mission Control.
+
+## Topics
+
+- Monitoring/metrics
+- Backups
+- Log locations and common errors
+- Upgrade/rollback

docs/reference/api.md

@@ -0,0 +1,10 @@
+# API notes
+
+- Backend defaults to http://localhost:8000
+- Health endpoints:
+  - `/health`
+  - `/healthz`
+  - `/readyz`
+
+> **Note**
+> Add canonical API docs strategy here (OpenAPI, versioning, examples).

docs/reference/authentication.md

@@ -0,0 +1,30 @@
+# Authentication
+
+Mission Control supports two auth modes via `AUTH_MODE`:
+
+- `local`: shared bearer token auth for self-hosted deployments
+- `clerk`: Clerk JWT auth
+
+## Local mode
+
+Backend:
+
+- `AUTH_MODE=local`
+- `LOCAL_AUTH_TOKEN=<token>`
+
+Frontend:
+
+- `NEXT_PUBLIC_AUTH_MODE=local`
+- Provide the token via the login UI.
+
+## Clerk mode
+
+Backend:
+
+- `AUTH_MODE=clerk`
+- `CLERK_SECRET_KEY=<secret>`
+
+Frontend:
+
+- `NEXT_PUBLIC_AUTH_MODE=clerk`
+- `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=<key>`

docs/reference/configuration.md

@@ -0,0 +1,19 @@
+# Configuration reference
+
+This page collects the most important config values.
+
+## Root `.env` (Compose)
+
+See `.env.example` for defaults and required values.
+
+### `NEXT_PUBLIC_API_URL`
+
+- **Where set:** `.env` (frontend container environment)
+- **Purpose:** Public URL the browser uses to call the backend.
+- **Gotcha:** Must be reachable from the *browser* (host), not a Docker network alias.
+
+### `LOCAL_AUTH_TOKEN`
+
+- **Where set:** `.env` (backend)
+- **When required:** `AUTH_MODE=local`
+- **Policy:** Must be non-placeholder and at least 50 characters.

docs/style-guide.md

@@ -0,0 +1,39 @@
+# Docs style guide
+
+## Principles
+
+- **Be concrete.** Prefer commands, examples, and “expected output” over prose.
+- **Don’t invent behavior.** If unsure, link to the source file and mark it as “verify”.
+- **Optimize for scanning.** Short sections, bullets, and tables.
+- **Call out risk.** Anything destructive or security-sensitive should be labeled clearly.
+
+## Markdown conventions
+
+- Use sentence-case headings.
+- Prefer fenced code blocks with a language (`bash`, `yaml`, `json`).
+- For warnings/notes, use simple callouts:
+
+```md
+> **Note**
+> ...
+
+> **Warning**
+> ...
+```
+
+## Common templates
+
+### Procedure
+
+1. Prereqs
+2. Steps
+3. Verify
+4. Troubleshooting
+
+### Config reference entry
+
+- **Name**
+- **Where set** (`.env`, env var, compose)
+- **Default**
+- **Example**
+- **Notes / pitfalls**

docs/troubleshooting/README.md

@@ -1,3 +1,12 @@
 # Troubleshooting
 
 - [Gateway agent provisioning and check-in](./gateway-agent-provisioning.md)
+
+## Common issues
+
+- Frontend can’t reach backend (check `NEXT_PUBLIC_API_URL`)
+- Auth errors (check `AUTH_MODE`, tokens)
+- DB connection/migrations
+
+> **Note**
+> Expand with concrete symptoms + fixes as issues are discovered.