docs: lead with env vars in admin docs and add configuration reference (#26824)

## What & why

Admin/setup docs lead with `coder server --flag` examples, but most
operators configure Coder through `CODER_*` environment variables
(system service, container, or Helm chart). There is no single page
mapping a setting to its env var, CLI flag, YAML key, and default, so
searching the docs for an env var name such as `CODER_PG_CONNECTION_URL`
returns nothing.

This adds a generated configuration reference and begins shifting admin
docs to lead with the environment-variable form.

## Changes

- **Generated configuration reference**
(`docs/admin/setup/configuration-reference.md`): a searchable,
per-setting list of every visible deployment option. Each option is a
heading (grouped and nested by serpent group) followed by its
description and the environment variable, CLI flag, YAML key, and
default that apply to it. Generated from `codersdk.DeploymentValues` so
it stays in sync.
- **Generator + `make gen` wiring** (`scripts/configdocgen/`): new
binary plus a Makefile target and `GEN_FILES` entry, mirroring the
existing `clidocgen` / `auditdocgen` pattern. Output is host-independent
(same env normalization as `clidocgen`).
- **Demo conversion** (`docs/admin/users/github-auth.md`): inverted to
lead with the `/etc/coder.d/coder.env` env-var form; the CLI-flag form
becomes a closing note that links to the reference. H2 slugs preserved.
- **Style guide** (`.claude/docs/DOCS_STYLE_GUIDE.md`): documents the
env-var-first convention for admin/setup docs.
- **Navigation**: manifest entry under Administration → Setup, plus a
TIP callout on the setup index.

## Risk

Docs + gen pipeline only; no runtime change. The page is regenerated by
`make gen`; the `gen` and `check-docs` CI checks pass.

## Follow-up

Several other admin pages still lead with flag walls. Recommend sweeping
them incrementally in separate PRs rather than expanding scope here.

<details>
<summary>Implementation notes (provenance, conflict resolution,
verification)</summary>

- Continues prior work by @aslilac and @bpmct from the
`kayla/docs-env-vars-first` branch. Both original commits are
cherry-picked here with authorship preserved.
- Rebased onto current `main`. Resolved two `Makefile` conflicts where
`main` had since added the `feature-stages.md` gen target at the same
locations; kept both targets (union) in `GEN_FILES`, `gen/mark-fresh`,
and the recipe block.
- The original branch's checked-in page predated recent
`codersdk.DeploymentValues` changes, so it was **regenerated** against
current `main` (adds `CODER_SCIM_USE_LEGACY`, the `Networking / Cluster`
section with `CODER_CLUSTER_HOST`, `CODER_BOUNDARY_LOG_RETENTION`, and
the AI Gateway description rename). The `gen` CI check enforces this
stays current.
- Fixed flag-link anchors for short-form flags (`--config`,
`--log-filter`): the generator derives the anchor from `FlagShorthand`
to match `clidocgen`'s heading (e.g. `#-l---log-filter`).
- `linkspector` ignores the AWS Bedrock base URL that appears as an
illustrative `<region>` placeholder in an option description, consistent
with the existing `openai.com` ignore patterns.

</details>

<details>
<summary>Configuration reference layout (2026-07-08 update)</summary>

Reworked the reference from a wide table into a nested, per-setting list
so it fits without horizontal scrolling and stops repeating the group
name in every heading:

- **List, not table.** Each option renders as a heading, its
description, and a bullet list of only the configuration methods that
apply to it (non-applicable methods are omitted instead of shown as
`-`).
- **Nested sections.** Sections nest by the serpent group hierarchy, so
`Email / Email Authentication` becomes `Email` (h2) with an `Email
authentication` (h3) subsection instead of a redundant flat title.
- **Shorter, sentence-case headings.** The redundant group prefix is
stripped from each option name and the remainder is lowercased to
sentence case, preserving acronyms and mixed-case tokens (`URL`, `TLS`,
`OAuth2`, `GitHub`) plus a small proper-noun allowlist (`Coder`,
`Terraform`, `Honeycomb`, `Anthropic`, `Bedrock`, ...). Example: `AI
Gateway Send Actor Headers` becomes `Send actor headers`.
- **Deprecated options** sort to the end of each section and lead with
an emphasized **Deprecated** marker. Headings stay clean (no
`(deprecated)` suffix) so their anchors remain stable.
- **Section intros** render from a group's `Description` when the source
defines one (e.g. DERP); no hand-maintained prose or links are
introduced.

All transformations run in pure Go at `make gen` time (no AI at
generation time). Generation is idempotent, and `markdownlint` and
`golangci-lint` both pass.

</details>

---

🤖 Opened by Coder Agents on behalf of @nickvigilante. Continues work by
@aslilac and @bpmct.

---------

Co-authored-by: Kayla (via Coder Agents) <kayla@coder.com>
Co-authored-by: Coder Agents <noreply@coder.com>
Co-authored-by: Ben Potter <me@bpmct.net>

docs/admin/setup/index.md

@@ -4,6 +4,11 @@ Coder server's primary configuration is done via environment variables. For a
 full list of the options, run `coder server --help` or see our
 [CLI documentation](../../reference/cli/server.md).
 
+> [!TIP]
+> Need to look up an exact environment variable, CLI flag, or YAML key for a
+> setting? See the [configuration reference](./configuration-reference.md) for
+> a searchable list of every option.
+
 ## Access URL
 
 `CODER_ACCESS_URL` is required if you are not using the tunnel. Set this to the

docs/admin/users/github-auth.md

@@ -85,37 +85,13 @@ CODER_OAUTH2_GITHUB_DEFAULT_PROVIDER_ENABLE=false
 
 ## Step 2: Configure Coder with the OAuth credentials
 
-Go to your Coder host and run the following command to start up the Coder server:
+Coder server reads these settings from environment variables. Set them
+wherever your deployment manages environment variables. For example, use
+Helm `values.yaml` for Kubernetes or `/etc/coder.d/coder.env` for a system
+service.
 
-```sh
-coder server --oauth2-github-allow-signups=true --oauth2-github-allowed-orgs="your-org" --oauth2-github-client-id="8d1...e05" --oauth2-github-client-secret="57ebc9...02c24c"
-```
-
-> [!NOTE]
-> For GitHub Enterprise support, specify the `--oauth2-github-enterprise-base-url` flag.
-
-Alternatively, if you are running Coder as a system service, you can achieve the
-same result as the command above by adding the following environment variables
-to the `/etc/coder.d/coder.env` file:
-
-```sh
-CODER_OAUTH2_GITHUB_ALLOW_SIGNUPS=true
-CODER_OAUTH2_GITHUB_ALLOWED_ORGS="your-org"
-CODER_OAUTH2_GITHUB_CLIENT_ID="8d1...e05"
-CODER_OAUTH2_GITHUB_CLIENT_SECRET="57ebc9...02c24c"
-```
-
-> [!TIP]
-> To allow everyone to sign up using GitHub, set:
->
-> ```shell
-> CODER_OAUTH2_GITHUB_ALLOW_EVERYONE=true
-> ```
-
-Once complete, run `sudo service coder restart` to reboot Coder.
-
-If deploying Coder via Helm, you can set the above environment variables in the
-`values.yaml` file as such:
+**Kubernetes (Helm):** set the variables under `coder.env` in your
+`values.yaml`:
 
 ```yaml
 coder:
@@ -129,17 +105,48 @@ coder:
     # If setting allowed orgs, comment out CODER_OAUTH2_GITHUB_ALLOW_EVERYONE and its value
     - name: CODER_OAUTH2_GITHUB_ALLOWED_ORGS
       value: "your-org"
-    # If allowing everyone, comment out CODER_OAUTH2_GITHUB_ALLOWED_ORGS and it's value
+    # If allowing everyone, comment out CODER_OAUTH2_GITHUB_ALLOWED_ORGS and its value
     #- name: CODER_OAUTH2_GITHUB_ALLOW_EVERYONE
     #  value: "true"
 ```
 
-To upgrade Coder, run:
+Then apply the change with `helm upgrade`:
 
 ```sh
 helm upgrade <release-name> coder-v2/coder -n <namespace> -f values.yaml
 ```
 
+**System service:** add the variables to `/etc/coder.d/coder.env`:
+
+```sh
+CODER_OAUTH2_GITHUB_ALLOW_SIGNUPS=true
+CODER_OAUTH2_GITHUB_ALLOWED_ORGS="your-org"
+CODER_OAUTH2_GITHUB_CLIENT_ID="8d1...e05"
+CODER_OAUTH2_GITHUB_CLIENT_SECRET="57ebc9...02c24c"
+```
+
+Then restart Coder with `sudo service coder restart`.
+
+> [!TIP]
+> To allow everyone to sign up using GitHub, set:
+>
+> ```shell
+> CODER_OAUTH2_GITHUB_ALLOW_EVERYONE=true
+> ```
+
+For GitHub Enterprise support, also set
+`CODER_OAUTH2_GITHUB_ENTERPRISE_BASE_URL`.
+
+> [!NOTE]
+> Every option above also has an equivalent CLI flag (for example,
+> `CODER_OAUTH2_GITHUB_CLIENT_ID` becomes `--oauth2-github-client-id`).
+> CLI flags are convenient for ad-hoc invocations of `coder server` during
+> local development. For production deployments, prefer environment
+> variables so the configuration lives with the container, Helm chart, or
+> service unit that manages Coder. See the
+> [configuration reference](../setup/configuration-reference.md) for the
+> full mapping between environment variables and flags.
+
 We recommend requiring and auditing MFA usage for all users in your GitHub organizations.
 This can be enforced from the organization settings page in the **Authentication security** sidebar tab.
 

docs/manifest.json

@@ -423,6 +423,11 @@
 							"path": "./admin/setup/appearance.md",
 							"state": ["premium"]
 						},
+						{
+							"title": "Configuration Reference",
+							"description": "Searchable list of every Coder server setting with its environment variable, CLI flag, and YAML key",
+							"path": "./admin/setup/configuration-reference.md"
+						},
 						{
 							"title": "Telemetry",
 							"description": "Learn what usage telemetry Coder collects, why it is collected, and how to opt out.",