🤖 refactor: refocus docs for product deployment flow (#78)

## Summary
Refocused repository docs from contributor-centric setup toward
product/operator usage, added a dedicated External Provisioner tutorial,
and standardized tutorial/sample namespace usage on `coder` (never
`default`).

## Background
The existing README/tutorial flow mixed end-user docs with contributor
workflows and repeated setup steps across tutorials, which increased
drift risk. This PR separates contributor guidance, simplifies tutorial
progression, and updates examples for clearer terminology and safer
defaults.

## Implementation
- Reworked `README.md` to be end-user focused and link to hosted docs.
- Added `CONTRIBUTING.md` and moved local-dev/contributor workflows
there.
- Updated docs landing/tutorial framing:
  - Product-focused `docs/index.md`
  - `Deploy a Coder Control Plane`
  - `Deploy an External Provisioner` as a follow-on tutorial
- Switched tutorial commands to raw GitHub manifest URLs for copy/paste
usability.
- Renamed `examples/aggregated` to `examples/coder-templates` and
updated references.
- Standardized tutorial and sample resource namespace to `coder`:
  - `config/samples/coder_v1alpha1_codercontrolplane.yaml`
  - `config/samples/coder_v1alpha1_coderprovisioner.yaml`
  - `config/samples/coder_v1alpha1_coderworkspaceproxy.yaml`
- Updated non-generated docs/sample content to assume operator-managed
provisioner flow and removed user-facing `credentialsSecretRef` usage
from the sample/tutorials in this branch context.

## Validation
- `make verify-vendor`
- `make test`
- `make build`
- `make lint`
- `make docs-check` *(fails by design when `mkdocs.yml` changes because
`docs-reference-check` asserts no `mkdocs.yml` diff)*
- `mkdocs build --strict`
- Raw URL download checks for tutorial-referenced manifest links (curl
verification)

## Risks
Low to medium. Changes are mostly docs/samples, but sample behavior
assumptions were updated to match the intended API direction in this
workstream. Generated API reference docs are intentionally left for the
API-removal PR that updates types/CRDs.

---

_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,75 @@
+# 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, create the sample namespace and apply a sample control plane
+kubectl create namespace coder
+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_coderprovisioner.yaml

@@ -4,6 +4,7 @@
 #   1. A CoderControlPlane resource must exist in the same namespace.
 #   2. The referenced CoderControlPlane status must report operator access ready:
 #      status.operatorAccessReady=true and status.operatorTokenSecretRef set.
+#
 apiVersion: coder.com/v1alpha1
 kind: CoderProvisioner
 metadata:

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).

docs/tutorials/deploy-coderprovisioner.md

@@ -0,0 +1,79 @@
+# Deploy an External Provisioner
+
+This tutorial deploys a `CoderProvisioner` for an existing `CoderControlPlane` managed by `coder-k8s`.
+
+Estimated time: **5 minutes**.
+
+## Prerequisite
+
+Complete [Deploy a Coder Control Plane](getting-started.md) first.
+
+This tutorial assumes the setup from that guide:
+
+- `CoderControlPlane` **`codercontrolplane-sample`** exists in namespace **`coder`** and is `Ready`.
+- Operator access is enabled and ready (default behavior):
+  `.status.operatorAccessReady=true`.
+
+Quick check:
+
+```bash
+kubectl get codercontrolplane codercontrolplane-sample -n coder \
+  -o jsonpath='{.status.phase}{"\n"}{.status.operatorAccessReady}{"\n"}'
+```
+
+Expected output:
+
+```text
+Ready
+true
+```
+
+## 1) Confirm external provisioner entitlement
+
+`CoderProvisioner` requires external provisioner entitlement in the referenced Coder deployment.
+
+```bash
+kubectl get codercontrolplane codercontrolplane-sample -n coder \
+  -o jsonpath='{.status.externalProvisionerDaemonsEntitlement}{"\n"}'
+```
+
+Expected values to proceed: `entitled` or `grace_period`.
+
+If the value is `not_entitled`, update the control-plane license before continuing.
+
+## 2) Deploy the `CoderProvisioner`
+
+Apply the sample manifest:
+
+```bash
+kubectl apply -f "https://raw.githubusercontent.com/coder/coder-k8s/main/config/samples/coder_v1alpha1_coderprovisioner.yaml"
+```
+
+## 3) Verify reconciliation
+
+```bash
+kubectl get coderprovisioner coderprovisioner-sample -n coder
+kubectl get coderprovisioner coderprovisioner-sample -n coder -o jsonpath='{.status.phase}{"\n"}'
+kubectl get coderprovisioner coderprovisioner-sample -n coder -o jsonpath='{range .status.conditions[*]}{.type}={.status} {.reason}{"\n"}{end}'
+```
+
+Verify generated resources:
+
+```bash
+kubectl get deployment provisioner-coderprovisioner-sample -n coder
+kubectl get sa coderprovisioner-sample-provisioner -n coder
+kubectl get role provisioner-coderprovisioner-sample -n coder
+kubectl get rb provisioner-coderprovisioner-sample -n coder
+kubectl get secret coderprovisioner-sample-provisioner-key -n coder
+```
+
+Expected: `status.phase=Ready`, `DeploymentReady=True`, and a ready provisioner pod.
+
+## 4) Clean up (optional)
+
+```bash
+kubectl delete coderprovisioner coderprovisioner-sample -n coder
+```
+
+To tear down the full stack, follow cleanup in
+[Deploy a Coder Control Plane](getting-started.md#5-clean-up-optional).