diff --git a/Makefile b/Makefile
index e4378ec079..9539d8ccb3 100644
--- a/Makefile
+++ b/Makefile
@@ -909,7 +909,10 @@ site/src/api/countriesGenerated.ts: site/node_modules/.installed scripts/typegen
 	(cd site/ && pnpm exec biome format --write src/api/countriesGenerated.ts)
 	touch "$@"
 
-docs/admin/integrations/prometheus.md: node_modules/.installed scripts/metricsdocgen/main.go scripts/metricsdocgen/metrics
+scripts/metricsdocgen/generated_metrics: $(GO_SRC_FILES)
+	go run ./scripts/metricsdocgen/scanner > $@
+
+docs/admin/integrations/prometheus.md: node_modules/.installed scripts/metricsdocgen/main.go scripts/metricsdocgen/metrics scripts/metricsdocgen/generated_metrics
 	go run scripts/metricsdocgen/main.go
 	pnpm exec markdownlint-cli2 --fix ./docs/admin/integrations/prometheus.md
 	pnpm exec markdown-table-formatter ./docs/admin/integrations/prometheus.md
diff --git a/scripts/metricsdocgen/README.md b/scripts/metricsdocgen/README.md
new file mode 100644
index 0000000000..509cd9d9ef
--- /dev/null
+++ b/scripts/metricsdocgen/README.md
@@ -0,0 +1,52 @@
+# Metrics Documentation Generator
+
+This tool generates the Prometheus metrics documentation at [`docs/admin/integrations/prometheus.md`](https://coder.com/docs/admin/integrations/prometheus#available-metrics).
+
+## How It Works
+
+The documentation is generated from two metrics files:
+
+1. `metrics` (static, manually maintained)
+2. `generated_metrics` (auto-generated, do not edit)
+
+These files are merged and used to produce the final documentation.
+
+### `metrics` (static)
+
+Contains metrics that are **not** directly defined in the coder source code:
+
+- `go_*`: Go runtime metrics
+- `process_*`: Process metrics from prometheus/client_golang
+- `promhttp_*`: Prometheus HTTP handler metrics
+- `coder_aibridged_*`: Metrics from external dependencies
+
+> [!Note]
+> This file also contains edge cases where metric metadata cannot be accurately extracted by the scanner (e.g., labels determined by runtime logic).
+> Static metrics take priority over generated metrics when both files contain the same metric name.
+
+**Edit this file** to add metrics that should appear in the documentation but are not scanned from the coder codebase,
+or to manually override metrics where the scanner generates incorrect metadata (e.g., missing runtime-determined labels like in `agent_scripts_executed_total`).
+
+### `generated_metrics` (auto-generated)
+
+Contains metrics extracted from the coder source code by the AST scanner (`scanner/scanner.go`).
+
+**Do not edit this file directly.** It is regenerated by running:
+
+```bash
+make scripts/metricsdocgen/generated_metrics
+```
+
+## Updating Metrics Documentation
+
+To regenerate the documentation after code changes:
+
+```bash
+make docs/admin/integrations/prometheus.md
+```
+
+This will:
+
+- Run the scanner to update `generated_metrics`
+- Merge `metrics` and `generated_metrics` metric files
+- Update the documentation file