🤖 fix: refresh docs accuracy and structure (#71)

## Summary
This PR refreshes the user-facing docs and README for accuracy,
structure, and learnability. It updates outdated
architecture/troubleshooting guidance, improves getting-started and
deployment how-tos, and fixes the control-plane sample manifest used in
docs and CI smoke flows.

## Background
Recent documentation drift left several pages out of date with current
runtime behavior (`--app=all` default mode, expanded app modes,
codersdk-backed aggregated storage, and current Kubernetes resource
names). The README also needed a clearer project narrative and more
consistent onboarding flow.

## Implementation
- Reworked `README.md` into a structured project entrypoint with badges,
capability summary, app-mode matrix, docs links, commands, repo layout,
and contributing checks.
- Rewrote `docs/explanation/architecture.md`:
- documents all app modes (`all`, `controller`, `aggregated-apiserver`,
`mcp-http`)
  - corrects `--app` default behavior
  - describes controller, aggregated API, and MCP subsystems
- replaces outdated in-memory storage claim with codersdk-backed
architecture
  - adds mermaid diagrams for process and request flow
- Rewrote `docs/how-to/troubleshooting.md` with correct resource names
and current failure modes.
- Improved `docs/index.md` with clearer orientation, links, and quick
commands.
- Expanded `docs/tutorials/getting-started.md` with improved flow,
verification, and cleanup.
- Updated deployment guides:
- `docs/how-to/deploy-controller.md` now explicitly covers
controller-only mode
- `docs/how-to/deploy-aggregated-apiserver.md` now distinguishes
all-in-one vs standalone mode and required standalone settings
- Fixed `config/samples/coder_v1alpha1_codercontrolplane.yaml`:
  - image changed to `ghcr.io/coder/coder:latest`
  - `licenseSecretRef` made optional/commented

## Validation
- `make verify-vendor`
- `make test`
- `make build`
- `make lint`
- `make docs-check`

## Risks
- **Low to moderate:** This is primarily documentation and
sample-manifest scope, but command correctness and deployment semantics
changed in text. Main residual risk is user confusion if they rely on
stale external copies of old docs; in-repo docs now reflect current code
behavior.

---

_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

.cspell.json

@@ -2,19 +2,22 @@
   "version": "0.2",
   "language": "en",
   "words": [
+    "allapp",
     "Diátaxis",
     "GOFLAGS",
     "Millis",
     "apiregistration",
     "apiserverapp",
     "apiserver",
     "apiservice",
+    "apisvc",
     "clusterrole",
     "clusterrolebinding",
     "coder-k8s",
     "codercontrolplane",
     "codercontrolplanes",
     "coderd",
+    "codersdk",
     "codertemplate",
     "codertemplates",
     "coderworkspace",
@@ -28,15 +31,19 @@
     "workspaceproxy",
     "workspaceproxies",
     "derp",
+    "crds",
     "devshell",
+    "healthz",
     "gofumpt",
     "javascripts",
     "kubeconfig",
     "kubebuilder",
     "corev",
     "metav",
+    "mcpapp",
     "mkdocs",
     "pymdownx",
+    "readyz",
     "superfences"
   ],
   "ignorePaths": [

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