🤖 docs: refresh docs accuracy and structure

Summary:
- rewrote architecture, troubleshooting, and docs index pages
- improved README structure and app mode coverage
- updated tutorial/deploy guides for correctness and actionability
- fixed control-plane sample image and made license secret optional

---

_Generated with `mux` • Model: `openai:gpt-5.3-codex` • Thinking: `xhigh` • Cost: $2.88_

<!-- mux-attribution: model=openai:gpt-5.3-codex thinking=xhigh costs=2.88 -->

Author: ThomasK33

README.md

@@ -1,133 +1,136 @@
 # coder-k8s
 
+[![CI](https://github.com/coder/coder-k8s/actions/workflows/ci.yaml/badge.svg)](https://github.com/coder/coder-k8s/actions/workflows/ci.yaml)
+[![Go](https://img.shields.io/badge/go-1.25%2B-00ADD8?logo=go)](./go.mod)
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](./LICENSE)
+
 > [!WARNING]
 > **Highly Experimental / Alpha Software**
 > This repository is a **hackathon contribution** and remains a **highly experimental, alpha-stage** project.
 > **Do not use this in production or expose it to end users.**
->
-## Project description
 
-`coder-k8s` is a Go-based Kubernetes control-plane project with two app modes:
+`coder-k8s` is a Kubernetes control-plane project for managing Coder-related resources with native Kubernetes APIs.
+
+## What this project provides
+
+- A controller-runtime operator for `coder.com/v1alpha1` resources:
+  - `CoderControlPlane`
+  - `CoderProvisioner`
+  - `CoderWorkspaceProxy`
+- An aggregated API server for `aggregation.coder.com/v1alpha1` resources:
+  - `CoderWorkspace`
+  - `CoderTemplate`
+- An MCP HTTP server for operational tooling.
+- A single binary that can run in all-in-one mode or split app modes.
 
-- A `controller-runtime` operator for managing `CoderControlPlane` and
-  `CoderWorkspaceProxy` resources (`coder.com/v1alpha1`).
-- An aggregated API server for `CoderWorkspace` and `CoderTemplate` resources
-  (`aggregation.coder.com/v1alpha1`).
+## Application modes
+
+| Mode | Description | Typical usage |
+| --- | --- | --- |
+| `all` (default) | Runs controller + aggregated API + MCP HTTP together | Local dev, demos, simple cluster deployment |
+| `controller` | Runs only Kubernetes reconcilers | Controller-focused debugging and e2e smoke flows |
+| `aggregated-apiserver` | Runs only aggregated API server | Split deployments with explicit Coder backend flags |
+| `mcp-http` | Runs only MCP HTTP server | MCP-focused integrations |
 
 ## Prerequisites
 
 - Go 1.25+ (`go.mod` currently declares Go 1.25.7)
-- A Kubernetes cluster (OrbStack is recommended for local development; any cluster works)
-- `kubectl` configured to point at your cluster context
+- A Kubernetes cluster (OrbStack, KIND, or any conformant cluster)
+- `kubectl` configured for your target cluster
 
-## Quick start / Local development (OrbStack)
+## Quick start (local controller run)
 
 ```bash
-# Generate CRD and RBAC manifests
+# Generate and apply CRDs
 make manifests
-
-# Apply CRDs to your cluster
 kubectl apply -f config/crd/bases/
 
-# Run the controller locally (uses your kubeconfig context)
+# Run controller locally against your kubeconfig context
 GOFLAGS=-mod=vendor go run . --app=controller
 
-# In another terminal: apply the sample CR
+# In another terminal, apply a sample control plane
 kubectl apply -f config/samples/coder_v1alpha1_codercontrolplane.yaml
 
-# Verify
+# Verify resource creation
 kubectl get codercontrolplanes -A
 ```
 
-## Examples
-
-- [`examples/cloudnativepg/`](examples/cloudnativepg/) - Deploy a `CoderControlPlane` with a CloudNativePG-managed PostgreSQL backend.
-
-## KIND development cluster (for k9s demos)
-
-Bootstrap a KIND cluster and install CRDs/RBAC (**this also switches your current kubectl context**):
+## Documentation
 
-```bash
-make kind-dev-up
-```
+The project docs follow Diátaxis and live in `docs/`.
 
-> Tip: override defaults when needed:
->
-> - Use `CLUSTER_NAME` to run multiple clusters in parallel.
-> - Use `KIND_NODE_IMAGE` to pin the node image (default: `kindest/node:v1.34.0`).
->
-> ```bash
-> CLUSTER_NAME=my-cluster make kind-dev-up
-> KIND_NODE_IMAGE=kindest/node:v1.32.0 make kind-dev-up
-> ```
+- Home: [`docs/index.md`](docs/index.md)
+- Tutorial: [`docs/tutorials/getting-started.md`](docs/tutorials/getting-started.md)
+- How-to guides: [`docs/how-to/`](docs/how-to/)
+- Architecture: [`docs/explanation/architecture.md`](docs/explanation/architecture.md)
+- API reference: [`docs/reference/api/`](docs/reference/api/)
 
-> If the cluster already exists and you change `KIND_NODE_IMAGE`, run `make kind-dev-down` first so the new image can be applied.
->
-If you need to switch your kubectl context later:
+Serve docs locally:
 
 ```bash
-make kind-dev-ctx
-# or: CLUSTER_NAME=my-cluster make kind-dev-ctx
+make docs-serve
 ```
 
-Start the controller (pick one):
-
-- Out-of-cluster (fast iteration):
-
-  ```bash
-  GOFLAGS=-mod=vendor go run . --app=controller
-  ```
+## Examples
 
-- In-cluster (closer to CI):
+- [`examples/cloudnativepg/`](examples/cloudnativepg/) — Deploy a `CoderControlPlane` with a CloudNativePG-managed PostgreSQL backend.
 
-  ```bash
-  make kind-dev-load-image
-  kubectl apply -f config/e2e/deployment.yaml
-  kubectl -n coder-system wait --for=condition=Available deploy/coder-k8s --timeout=120s
-  ```
+## KIND development cluster (k9s demos)
 
-Demo:
+Bootstrap a KIND cluster and install CRDs/RBAC (**this switches current kubectl context**):
 
 ```bash
-make kind-dev-k9s
+make kind-dev-up
 ```
 
-Cleanup:
+Useful helpers:
 
 ```bash
+make kind-dev-status
+make kind-dev-ctx
+make kind-dev-load-image
+make kind-dev-k9s
 make kind-dev-down
 ```
 
-Mux users: there is an optional agent skill (`kind-dev`) under `.mux/skills/` with agent-oriented instructions for running per-workspace KIND clusters.
-
 ## Essential commands
 
 | Command | Description |
 | --- | --- |
-| `make build` | Build the project |
-| `make test` | Run tests |
-| `make manifests` | Generate CRD/RBAC manifests |
-| `make codegen` | Run deepcopy code generation |
-| `make verify-vendor` | Verify vendor consistency |
-| `make lint` | Run linter (requires `golangci-lint`) |
-| `make vuln` | Run vulnerability check (requires `govulncheck`) |
-| `make docs-serve` | Serve the documentation site locally (requires `mkdocs`) |
+| `make build` | Build all packages |
+| `make test` | Run unit + integration tests |
+| `make test-integration` | Run focused controller integration tests |
+| `make manifests` | Generate CRD and RBAC manifests |
+| `make codegen` | Run deepcopy generation |
+| `make docs-reference` | Regenerate API reference docs from Go types |
 | `make docs-check` | Build docs in strict mode (CI-equivalent) |
+| `make verify-vendor` | Verify vendored dependency consistency |
+| `make lint` | Run linter + formatting checks |
+| `make vuln` | Run vulnerability scan |
 
-## Testing strategy
+## Repository layout
 
-- **Unit tests**: `make test` runs all tests, including unit tests in `main_test.go`.
-- **Integration tests**: Use `envtest` to exercise reconciliation against a lightweight API server (no real cluster needed). Run them via `make test` (included in the full suite) or `make test-integration` (focused on controller tests only).
-- **E2E smoke tests**: Recommended CI smoke coverage uses a Kind-based flow that deploys the controller image and verifies pod health.
+- `api/v1alpha1/` — CRD API types (`coder.com/v1alpha1`)
+- `api/aggregation/v1alpha1/` — aggregated API types (`aggregation.coder.com/v1alpha1`)
+- `internal/app/` — app mode entrypoints (`allapp`, `controllerapp`, `apiserverapp`, `mcpapp`)
+- `internal/controller/` — controller reconcilers
+- `internal/aggregated/` — aggregated storage + Coder client/provider logic
+- `config/` — generated CRDs, RBAC, samples
+- `deploy/` — deployable manifests for all-in-one, APIService, and MCP service
+- `docs/` — user-facing documentation site content
+- `hack/` — code generation and maintenance scripts
 
-## Project structure
+## Contributing
 
-- `api/v1alpha1/` — CRD types and generated deepcopy code
-- `internal/controller/` — Reconciliation logic
-- `config/crd/bases/` — Generated CRD manifests
-- `config/rbac/` — RBAC manifests (generated role + deployment bindings)
-- `config/samples/` — Sample custom resources
-- `hack/` — Code generation and maintenance scripts
+Before opening a PR, run at least:
+
+```bash
+make verify-vendor
+make test
+make build
+make lint
+make docs-check
+```
 
 ## License
 

config/samples/coder_v1alpha1_codercontrolplane.yaml

@@ -4,7 +4,8 @@ metadata:
   name: codercontrolplane-sample
   namespace: default
 spec:
-  image: "ghcr.io/coder/coder-k8s:main"
-  licenseSecretRef:
-    name: coder-license
-    key: license
+  image: "ghcr.io/coder/coder:latest"
+  # Optional Enterprise license upload:
+  # licenseSecretRef:
+  #   name: coder-license
+  #   key: license

docs/explanation/architecture.md

@@ -1,38 +1,112 @@
 # Architecture
 
-`coder-k8s` builds a single binary (`coder-k8s`) that can run in one of two modes:
+`coder-k8s` is a single Go binary that can run different components depending on the `--app` flag.
 
-- `--app=controller`
-- `--app=aggregated-apiserver`
+## Application modes
 
-The dispatch logic lives in `app_dispatch.go`. The `--app` flag is required, and the code intentionally fails fast with an `assertion failed:` error when it is missing or invalid.
+| Mode | Purpose | Default |
+| --- | --- | --- |
+| `all` | Runs controller + aggregated API server + MCP HTTP server in one process | ✅ |
+| `controller` | Runs only the controller-runtime manager and reconcilers |  |
+| `aggregated-apiserver` | Runs only the aggregated API server (`aggregation.coder.com/v1alpha1`) |  |
+| `mcp-http` | Runs only the MCP HTTP server |  |
 
-## Controller mode
+!!! note
+    `--app` is optional. If omitted, `coder-k8s` defaults to `--app=all`.
 
-In controller mode, the binary runs a `controller-runtime` manager and registers the `CoderControlPlane` API types:
+## Default process model (`--app=all`)
 
-- API group: `coder.com/v1alpha1`
-- Kind: `CoderControlPlane`
+In `all` mode, `internal/app/allapp` creates one shared controller-runtime manager and cache, then:
 
-Key code paths:
+1. Registers controller reconcilers.
+2. Starts aggregated API server as a non-leader runnable.
+3. Starts MCP HTTP server as a non-leader runnable.
 
-- `internal/app/controllerapp/` — scheme construction and manager startup
-- `internal/controller/` — reconciliation logic (`CoderControlPlaneReconciler`)
+This keeps component startup coordinated and avoids separate cache/process management for local and demo deployments.
 
-## Aggregated API server mode
+```mermaid
+graph TD
+  entry["coder-k8s (--app=all)"] --> mgr["controller-runtime manager"]
+  mgr --> ctrl["Controller reconcilers"]
+  mgr --> agg["Aggregated API server runnable"]
+  mgr --> mcp["MCP HTTP runnable"]
 
-In aggregated API server mode, the binary starts an aggregated API server that installs storage for:
+  ctrl --> crds["coder.com/v1alpha1 CRDs"]
+  agg --> api["aggregation.coder.com/v1alpha1"]
+  mcp --> tools["MCP tools over /mcp"]
+```
 
-- API group: `aggregation.coder.com/v1alpha1`
-- Resources: `coderworkspaces`, `codertemplates`
+## Controller subsystem
 
-Key code paths:
+Controller behavior lives in:
 
-- `internal/app/apiserverapp/` — API server bootstrap and API group installation
-- `internal/aggregated/storage/` — storage implementations (currently hardcoded in-memory objects)
+- `internal/app/controllerapp/`
+- `internal/controller/`
 
-## Manifests and generated assets
+Key facts:
 
-- `config/` — generated CRDs and RBAC (via `make manifests`)
-- `deploy/` — example deployment manifests for controller and aggregated API server
-- `vendor/` — vendored dependencies (required by the repo workflow)
+- Uses controller-runtime with leader election.
+- Exposes health probes on `:8081` (`/healthz`, `/readyz`).
+- Reconciles three CRDs in `coder.com/v1alpha1`:
+  - `CoderControlPlane`
+  - `CoderProvisioner`
+  - `CoderWorkspaceProxy`
+
+For `CoderControlPlane`, the reconciler creates/updates a Deployment + Service in the same namespace, and writes status fields such as `status.url`, `status.phase`, and operator token references.
+
+## Aggregated API subsystem
+
+Aggregated API server behavior lives in:
+
+- `internal/app/apiserverapp/`
+- `internal/aggregated/storage/`
+- `internal/aggregated/coder/`
+
+Key facts:
+
+- Serves HTTPS on port `6443` by default.
+- Installs `aggregation.coder.com/v1alpha1` resources:
+  - `coderworkspaces`
+  - `codertemplates`
+- Storage is **codersdk-backed**, not in-memory: requests are translated to Coder API operations.
+
+Client provider behavior:
+
+- In `all` mode, `ControlPlaneClientProvider` discovers eligible `CoderControlPlane` resources and reads operator token secrets dynamically.
+- In standalone `--app=aggregated-apiserver` mode, static configuration is expected via:
+  - `--coder-url`
+  - `--coder-session-token`
+  - `--coder-namespace`
+
+## MCP subsystem
+
+MCP behavior lives in `internal/app/mcpapp/`.
+
+Key facts:
+
+- HTTP listen address: `:8090`
+- Endpoints:
+  - `/mcp`
+  - `/healthz`
+  - `/readyz`
+- Provides tooling for control planes, templates, workspaces, events, pod logs, and run-state updates.
+
+## Kubernetes manifests
+
+- `config/crd/bases/`: generated CRDs for `CoderControlPlane`, `CoderProvisioner`, `CoderWorkspaceProxy`
+- `config/rbac/`: ServiceAccount and RBAC bindings (`manager-role`, `coder-k8s`, auth-delegator bindings)
+- `deploy/deployment.yaml`: all-in-one deployment (defaults to `--app=all`)
+- `deploy/apiserver-service.yaml` + `deploy/apiserver-apiservice.yaml`: aggregated API exposure
+- `deploy/mcp-service.yaml`: MCP service on port `8090`
+
+## High-level request flow (aggregated API)
+
+```mermaid
+graph TD
+  client["kubectl / API client"] --> kube["Kubernetes API aggregation layer"]
+  kube --> apisvc["APIService: v1alpha1.aggregation.coder.com"]
+  apisvc --> agg["coder-k8s aggregated API server"]
+  agg --> provider["ClientProvider"]
+  provider --> sdk["Coder SDK client"]
+  sdk --> coderd["Backing coderd instance"]
+```