diff --git a/docs/cli.md b/docs/cli.md
new file mode 100644
index 0000000..b00f58f
--- /dev/null
+++ b/docs/cli.md
@@ -0,0 +1,279 @@
+# The Remote Control 💅✨
+
+One CLI to rule them all. `sunbeam` is a single Rust binary that wraps kubectl, kustomize, helm, and every service API in The Super Boujee Business Box ✨ into one command. No more juggling twelve different tools to manage your stack.
+
+It has kustomize and helm *compiled into the binary*. ~50MB, zero external dependencies. Install it, configure it, and you're running infrastructure.
+
+> We built this because typing `kubectl port-forward svc/openbao-0 -n data 8200:8200` followed by `vault kv put secret/...` is not a vibe. `sunbeam vault kv put` is a vibe.
+
+---
+
+## Installation
+
+```bash
+# From source (you'll need Rust)
+git clone https://src.sunbeam.pt/studio/cli.git
+cd cli
+cargo install --path sunbeam
+
+# Or grab the binary from Gitea releases
+sunbeam update  # self-updates from latest mainline commit
+```
+
+Binary lands at `~/.cargo/bin/sunbeam`. Config lives at `~/.sunbeam.json`.
+
+---
+
+## Configuration
+
+Sunbeam uses named contexts (like kubectl) to manage multiple environments.
+
+```bash
+# Set up your local dev context
+sunbeam config set \
+  --domain 192.168.5.2.sslip.io \
+  --infra-dir /path/to/sbbb \
+  --acme-email ops@sunbeam.pt
+
+# Set up production
+sunbeam config set \
+  --domain sunbeam.pt \
+  --host admin@62.210.145.138 \
+  --infra-dir /path/to/sbbb \
+  --acme-email ops@sunbeam.pt
+
+# Switch contexts
+sunbeam config use-context production
+sunbeam config get  # show current
+```
+
+Production contexts use SSH tunneling — `sunbeam` forwards localhost:16443 to the remote k3s API server automatically.
+
+---
+
+## Infrastructure Lifecycle
+
+The big commands. These are how you go from bare metal to running stack.
+
+### `sunbeam up`
+
+Full cluster bring-up. Installs cert-manager, Gateway API CRDs, Linkerd (CRDs + control plane), and sets up mkcert CA for local TLS. Run this once on a fresh cluster.
+
+### `sunbeam apply [namespace]`
+
+The deploy command. Builds kustomize overlays, substitutes your domain, and applies via server-side apply.
+
+```bash
+sunbeam apply              # everything
+sunbeam apply lasuite      # just La Suite apps
+sunbeam apply monitoring   # just the observatory
+```
+
+### `sunbeam seed`
+
+Generates and stores ALL credentials in OpenBao — PostgreSQL passwords, OIDC secrets, DKIM keys, Django secret keys. Run once after `sunbeam up`. Seeds the entire vault.
+
+### `sunbeam verify`
+
+End-to-end test that OpenBao + Vault Secrets Operator are syncing correctly. Creates a test secret, watches for the K8s Secret to appear, validates the content.
+
+### `sunbeam bootstrap`
+
+Creates Gitea organizations, repositories, and bootstraps services. The finishing touch after everything's deployed.
+
+---
+
+## Service Management
+
+Day-to-day operations. The stuff you actually use every morning.
+
+```bash
+sunbeam status                  # pod health across all namespaces
+sunbeam status lasuite          # scoped to a namespace
+sunbeam status lasuite/drive    # scoped to a service
+
+sunbeam logs matrix/sol -f      # stream Sol☀️ logs
+sunbeam logs data/postgres      # check the database
+
+sunbeam restart lasuite/drive   # rolling restart
+sunbeam restart monitoring      # restart entire namespace
+
+sunbeam check                   # functional health probes (not just pod readiness)
+sunbeam check matrix            # check Matrix + Sol☀️
+```
+
+`sunbeam check` goes beyond pod readiness — it actually hits health endpoints, tests S3 connectivity, validates OpenSearch cluster status, checks Kratos/Hydra/Gitea/Matrix APIs. Real functional probes, not just "is the container running."
+
+---
+
+## Build & Deploy
+
+```bash
+sunbeam build proxy             # build proxy image
+sunbeam build sol --push        # build + push to Gitea registry
+sunbeam build drive --push --deploy  # build + push + rollout restart
+sunbeam build messages          # builds all messages components
+```
+
+BuildKit under the hood. Images pushed to `src.DOMAIN/studio/{name}:latest`.
+
+### Available build targets
+
+proxy, integration, kratos-admin, meet, docs-frontend, people-frontend, people, messages, messages-backend, messages-frontend, messages-mta-in, messages-mta-out, messages-mpa, messages-socks-proxy, tuwunel, calendars, projects, sol
+
+---
+
+## Service-Specific Commands
+
+Every major service in the stack has a dedicated subcommand. These talk directly to the service APIs.
+
+### Auth & Identity — `sunbeam auth`
+
+```bash
+sunbeam auth login              # OAuth2 PKCE login (opens browser)
+sunbeam auth token              # get/refresh access token
+sunbeam auth identity list      # list all identities
+sunbeam auth identity create sienna@sunbeam.pt --name "Sienna"
+sunbeam auth identity get <id>
+```
+
+The login flow spins up a local callback server, redirects you to Hydra, captures the auth code, exchanges for tokens, and caches everything at `~/.local/share/sunbeam/auth/`. Also creates a Gitea PAT on first login.
+
+### Version Control — `sunbeam vcs`
+
+```bash
+sunbeam vcs repo list
+sunbeam vcs repo search -q "proxy"
+sunbeam vcs issue list -r studio/sbbb
+sunbeam vcs issue create --repo studio/sbbb --title "Bug: thing broke"
+```
+
+### Chat — `sunbeam chat`
+
+```bash
+sunbeam chat rooms              # list joined Matrix rooms
+sunbeam chat send <room> "hey"  # send a message
+sunbeam chat users <room>       # list room members
+```
+
+### Project Management — `sunbeam pm`
+
+Unified interface across Projects and Gitea. Ticket IDs use prefixes: `p:42` for Projects, `g:studio/cli#7` for Gitea.
+
+```bash
+sunbeam pm list                 # all tickets, all sources
+sunbeam pm list --source gitea --state open
+sunbeam pm show g:studio/cli#7
+sunbeam pm create "New feature" --body "Details here" --target studio/sbbb
+sunbeam pm close p:42
+sunbeam pm assign g:studio/cli#7 sienna
+```
+
+### La Suite Services
+
+```bash
+# Drive
+sunbeam drive list
+sunbeam drive upload ./asset.png /game-assets/
+sunbeam drive download <id> ./local-copy.png
+
+# Docs
+sunbeam docs list
+sunbeam docs search "design document"
+
+# Mail
+sunbeam mail send --to amber@sunbeam.pt --subject "hey" --body "brunch?"
+sunbeam mail folders
+sunbeam mail messages inbox
+
+# Calendar
+sunbeam cal events
+sunbeam cal create --title "Standup" --date 2026-03-25
+
+# Meet
+sunbeam meet rooms
+sunbeam meet room create --name "Playtest"
+
+# Search (cross-service)
+sunbeam find "deployment guide"
+
+# People
+sunbeam people list
+sunbeam people search "Amber"
+```
+
+### Infrastructure Services
+
+```bash
+# OpenSearch
+sunbeam search indexes
+sunbeam search query sol-archive "deployment"
+
+# S3 Storage
+sunbeam storage buckets
+sunbeam storage objects sunbeam-drive
+sunbeam storage put sunbeam-game-assets textures/hero.png ./hero.png
+
+# LiveKit
+sunbeam media rooms
+sunbeam media participants <room>
+
+# Monitoring
+sunbeam mon prometheus query 'up{job="pingora"}'
+sunbeam mon loki logs '{namespace="matrix"}'
+sunbeam mon grafana dashboards
+
+# Vault
+sunbeam vault status
+sunbeam vault kv get secret/sol
+sunbeam vault kv list secret/
+```
+
+### Passthrough
+
+When you need the raw tools:
+
+```bash
+sunbeam k8s get pods -n matrix   # kubectl passthrough
+sunbeam bao secrets list         # bao CLI inside OpenBao pod
+```
+
+---
+
+## Self-Update
+
+```bash
+sunbeam update
+```
+
+Pulls the latest binary from your Gitea instance's releases. Checks once per day by default. SHA256 verified. Atomic binary replacement.
+
+---
+
+## Architecture
+
+```
+┌─────────────────────────────────┐
+│  sunbeam binary (thin CLI)      │
+│  clap parsing → verb dispatch   │
+└──────────┬──────────────────────┘
+           │
+┌──────────▼──────────────────────┐
+│  sunbeam-sdk (library crate)    │
+├─────────────────────────────────┤
+│ Core: config, client, errors    │
+│ Kube: apply, exec, tools, ssh  │
+│ Ops: status, logs, restart     │
+│ Secrets: OpenBao client, seed  │
+│ Build: BuildKit, mirroring     │
+│ Auth: OAuth2 PKCE, tokens      │
+├─────────────────────────────────┤
+│ Service Clients (feature-gated) │
+│ identity, matrix, search, s3   │
+│ media, monitoring, lasuite     │
+└─────────────────────────────────┘
+```
+
+Two-crate workspace: thin CLI binary + SDK library with all domain logic. Feature flags control which service clients are compiled in. 232 tests across the workspace.
+
+Source: [cli repository](../cli)