🤖 docs: refocus product docs and tutorial flow

Move contributor workflow out of README, add CONTRIBUTING, and align tutorials/samples with the product deployment path (coder namespace, external provisioner tutorial, clearer example naming).

---

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

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

Author: ThomasK33

CONTRIBUTING.md

@@ -0,0 +1,74 @@
+# Contributing to coder-k8s
+
+Thanks for contributing to `coder-k8s`.
+
+> [!NOTE]
+> The root [`README.md`](./README.md) is end-user focused. This guide contains local development and contribution workflows.
+
+## Development prerequisites
+
+- Go 1.25+ (`go.mod` currently declares Go 1.25.7)
+- A Kubernetes cluster (OrbStack, KIND, or any conformant cluster)
+- `kubectl` configured for your target cluster
+
+## Local development quick start (controller mode)
+
+```bash
+# Generate and apply CRDs
+make manifests
+kubectl apply -f config/crd/bases/
+
+# Run controller locally against your kubeconfig context
+GOFLAGS=-mod=vendor go run . --app=controller
+
+# In another terminal, apply a sample control plane
+kubectl apply -f config/samples/coder_v1alpha1_codercontrolplane.yaml
+
+# Verify resource creation
+kubectl get codercontrolplanes -A
+```
+
+## KIND development cluster (k9s demos)
+
+Bootstrap a KIND cluster and install CRDs/RBAC (**this switches current kubectl context**):
+
+```bash
+make kind-dev-up
+```
+
+Useful helpers:
+
+```bash
+make kind-dev-status
+make kind-dev-ctx
+make kind-dev-load-image
+make kind-dev-k9s
+make kind-dev-down
+```
+
+## Essential development commands
+
+| Command | Description |
+| --- | --- |
+| `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 |
+
+## Before opening a PR
+
+Run at least:
+
+```bash
+make verify-vendor
+make test
+make build
+make lint
+make docs-check
+```

README.md

@@ -11,13 +11,26 @@
 
 `coder-k8s` is a Kubernetes control-plane project for managing Coder-related resources with native Kubernetes APIs.
 
+## Documentation
+
+Start with the published docs: **https://coder.github.io/coder-k8s/**
+
+Helpful entry points:
+
+- Getting started: <https://coder.github.io/coder-k8s/tutorials/getting-started/>
+- Deploy the controller: <https://coder.github.io/coder-k8s/how-to/deploy-controller/>
+- Deploy the workspace/template API server: <https://coder.github.io/coder-k8s/how-to/deploy-aggregated-apiserver/>
+- API reference: <https://coder.github.io/coder-k8s/reference/api/codercontrolplane/>
+
+Prefer reading docs in-repo? See [`docs/`](docs/) and run `make docs-serve`.
+
 ## 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:
+- A workspace/template API server for `aggregation.coder.com/v1alpha1` resources:
   - `CoderWorkspace`
   - `CoderTemplate`
 - An MCP HTTP server for operational tooling.
@@ -27,113 +40,35 @@
 
 | 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 |
+| `all` (default) | Runs controller + workspace/template API + MCP HTTP together | Single deployment for evaluation environments |
+| `controller` | Runs only Kubernetes reconcilers | Controller-only deployments |
+| `aggregated-apiserver` | Runs only the workspace/template API server | Split deployments with dedicated API serving |
 | `mcp-http` | Runs only MCP HTTP server | MCP-focused integrations |
 
-## Prerequisites
+## Quick start (brief, in-cluster)
 
-- Go 1.25+ (`go.mod` currently declares Go 1.25.7)
-- A Kubernetes cluster (OrbStack, KIND, or any conformant cluster)
-- `kubectl` configured for your target cluster
-
-## Quick start (local controller run)
+For a full setup guide, use the docs links above. For a quick smoke deploy:
 
 ```bash
-# Generate and apply CRDs
-make manifests
+kubectl create namespace coder-system
 kubectl apply -f config/crd/bases/
-
-# Run controller locally against your kubeconfig context
-GOFLAGS=-mod=vendor go run . --app=controller
-
-# In another terminal, apply a sample control plane
-kubectl apply -f config/samples/coder_v1alpha1_codercontrolplane.yaml
-
-# Verify resource creation
-kubectl get codercontrolplanes -A
-```
-
-## Documentation
-
-The project docs follow Diátaxis and live in `docs/`.
-
-- 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/)
-
-Serve docs locally:
-
-```bash
-make docs-serve
+kubectl apply -f config/rbac/
+kubectl apply -f deploy/deployment.yaml
+kubectl apply -f deploy/apiserver-service.yaml
+kubectl apply -f deploy/apiserver-apiservice.yaml
+kubectl apply -f deploy/mcp-service.yaml
+kubectl rollout status deployment/coder-k8s -n coder-system
 ```
 
 ## Examples
 
 - [`examples/cloudnativepg/`](examples/cloudnativepg/) — Deploy a `CoderControlPlane` with a CloudNativePG-managed PostgreSQL backend.
 - [`examples/argocd/`](examples/argocd/) — Bootstrap CloudNativePG + `coder-k8s` + PostgreSQL + `CoderControlPlane` from one Argo CD `ApplicationSet`.
-
-- [`examples/aggregated/`](examples/aggregated/) - Reusable `CoderTemplate` manifests for aggregated API testing.
-
-## KIND development cluster (k9s demos)
-
-Bootstrap a KIND cluster and install CRDs/RBAC (**this switches current kubectl context**):
-
-```bash
-make kind-dev-up
-```
-
-Useful helpers:
-
-```bash
-make kind-dev-status
-make kind-dev-ctx
-make kind-dev-load-image
-make kind-dev-k9s
-make kind-dev-down
-```
-
-## Essential commands
-
-| Command | Description |
-| --- | --- |
-| `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 |
-
-## Repository layout
-
-- `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
+- [`examples/coder-templates/`](examples/coder-templates/) — Reusable `CoderTemplate` manifests for workspace/template API testing.
 
 ## Contributing
 
-Before opening a PR, run at least:
-
-```bash
-make verify-vendor
-make test
-make build
-make lint
-make docs-check
-```
+For local development workflows, validation commands, and PR guidance, see [CONTRIBUTING.md](./CONTRIBUTING.md).
 
 ## License
 

config/samples/coder_v1alpha1_codercontrolplane.yaml

@@ -2,7 +2,7 @@ apiVersion: coder.com/v1alpha1
 kind: CoderControlPlane
 metadata:
   name: codercontrolplane-sample
-  namespace: default
+  namespace: coder
 spec:
   image: "ghcr.io/coder/coder:latest"
   # Optional Enterprise license upload:

config/samples/coder_v1alpha1_coderprovisioner.yaml

@@ -2,25 +2,16 @@
 #
 # Prerequisites:
 #   1. A CoderControlPlane resource must exist in the same namespace.
-#   2. Create the bootstrap credentials Secret with a valid Coder session token:
+#   2. Operator access on that control plane is enabled and ready.
 #
-#      kubectl create secret generic coder-bootstrap-token \
-#        --namespace=default \
-#        --from-literal=token=<YOUR_SESSION_TOKEN>
-#
-#      IMPORTANT: Never commit real tokens to source control.
 apiVersion: coder.com/v1alpha1
 kind: CoderProvisioner
 metadata:
   name: coderprovisioner-sample
-  namespace: default
+  namespace: coder
 spec:
   controlPlaneRef:
     name: codercontrolplane-sample
-  bootstrap:
-    credentialsSecretRef:
-      name: coder-bootstrap-token
-      key: token
   # key:
   #   name: my-provisioner-key    # Provisioner key name in coderd (defaults to CR name)
   #   secretName: my-key-secret   # K8s Secret to store the key (defaults to "{name}-provisioner-key")

config/samples/coder_v1alpha1_coderworkspaceproxy.yaml

@@ -2,7 +2,7 @@ apiVersion: coder.com/v1alpha1
 kind: CoderWorkspaceProxy
 metadata:
   name: coderworkspaceproxy-sample
-  namespace: default
+  namespace: coder
 spec:
   image: "ghcr.io/coder/coder:latest"
   primaryAccessURL: "https://coder.example.com"

docs/index.md

@@ -4,38 +4,33 @@
     **Highly experimental / alpha software**
     This project is an active prototype. Do not use it in production.
 
-`coder-k8s` is a Kubernetes control-plane project for running and managing Coder through Kubernetes APIs.
+`coder-k8s` is a Kubernetes control-plane stack for running and managing Coder through Kubernetes APIs.
 
-## What is in this repository?
+## What you can deploy
 
 `coder-k8s` ships one binary with four app modes:
 
-- **`all` (default)**: controller + aggregated API server + MCP server in one process.
-- **`controller`**: reconciles `CoderControlPlane`, `CoderProvisioner`, `CoderWorkspaceProxy` (`coder.com/v1alpha1`).
+- **`all` (default)**: operator + workspace/template API server + MCP server in one process.
+- **`controller`**: reconciles `CoderControlPlane`, `CoderProvisioner`, and `CoderWorkspaceProxy` (`coder.com/v1alpha1`).
 - **`aggregated-apiserver`**: serves `CoderWorkspace` + `CoderTemplate` (`aggregation.coder.com/v1alpha1`).
-- **`mcp-http`**: serves MCP tooling over HTTP.
-
-## Documentation map (Diátaxis)
-
-- **Tutorials**: guided learning path
-  - [Getting started](tutorials/getting-started.md)
-- **How-to guides**: task-focused operations
-  - [Deploy controller](how-to/deploy-controller.md)
-  - [Deploy aggregated API server](how-to/deploy-aggregated-apiserver.md)
-  - [Run MCP server](how-to/mcp-server.md)
-  - [Troubleshooting](how-to/troubleshooting.md)
-- **Reference**: generated API reference
-  - [API reference](reference/api/codercontrolplane.md)
-- **Explanation**: conceptual internals
-  - [Architecture](explanation/architecture.md)
-
-## Quick commands
-
-```bash
-make manifests
-make test
-make build
-make docs-serve
-```
-
-New here? Start with the [Getting started tutorial](tutorials/getting-started.md).
+- **`mcp-http`**: serves operational MCP tooling over HTTP.
+
+## Quick start path
+
+If you want to deploy quickly and validate the end-to-end flow:
+
+1. Follow [Deploy a Coder Control Plane](tutorials/getting-started.md).
+2. Verify the managed Coder Deployment and Service.
+3. If you need external provisioners, continue with [Deploy an External Provisioner](tutorials/deploy-coderprovisioner.md).
+
+## Learn more
+
+- [Deploy an External Provisioner](tutorials/deploy-coderprovisioner.md)
+- [Deploy controller](how-to/deploy-controller.md)
+- [Deploy aggregated API server](how-to/deploy-aggregated-apiserver.md)
+- [Run MCP server](how-to/mcp-server.md)
+- [Troubleshooting](how-to/troubleshooting.md)
+- [API reference](reference/api/codercontrolplane.md)
+- [Architecture](explanation/architecture.md)
+
+Start with [Deploy a Coder Control Plane](tutorials/getting-started.md).