feat(docs): publish rule docs with github pages

Author: kaanyagci

.github/workflows/docs.yml

@@ -0,0 +1,54 @@
+name: Docs
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - ".github/workflows/docs.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install MkDocs
+        run: python -m pip install --upgrade pip mkdocs
+
+      - name: Build docs site
+        run: mkdocs build --strict
+
+      - name: Upload pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -0,0 +1 @@
+site/

AGENTS.md

@@ -27,3 +27,4 @@
 - 2026-02-26: Formalized stable JSON envelope contract with `schemaVersion` and always-present `errors` array.
 - 2026-02-26: Doctor UX now includes attempt trail, resolved backend details, paste-ready config snippet, and remediation guidance.
 - 2026-02-26: Minimum required Go version is Go 1.26 for local builds and CI/release workflows.
+- 2026-03-02: Documentation is published via MkDocs + GitHub Pages workflow (`.github/workflows/docs.yml`) with custom domain `docs.buildgraph.dev`.

README.md

@@ -86,6 +86,16 @@ All machine-readable command output uses a versioned envelope:
 }
 ```
 
+## Rule Documentation
+
+Rule pages backing finding links are tracked in this repository:
+
+- [Rules Index](./docs/rules/index.md)
+
+Docs are published from `docs/` using the GitHub Actions workflow:
+
+- [docs.yml](./.github/workflows/docs.yml)
+
 ## What Data Is Collected
 
 `buildgraph` stores local state in a SQLite database to support diagnostics and history:

docs/CNAME

@@ -0,0 +1 @@
+docs.buildgraph.dev

docs/README.md

@@ -0,0 +1,14 @@
+# Buildgraph Documentation
+
+This directory contains the source content for the public documentation URLs used by `buildgraph` findings.
+
+## Rules
+
+- [Rules Index](./rules/index.md)
+
+Each rule page is named after its rule ID, for example:
+- `docs/rules/BG_REPRO_FROM_MUTABLE.md`
+- `docs/rules/BG_SEC_ROOT_USER.md`
+
+These pages are designed to map directly to public URLs under:
+- `https://docs.buildgraph.dev/rules/<RULE_ID>`

docs/index.md

@@ -0,0 +1,18 @@
+# Buildgraph Documentation
+
+Buildgraph publishes rule-level guidance for findings reported by `buildgraph analyze`.
+
+## Primary Sections
+
+- [Rules Overview](./rules/index.md)
+
+## Public Rule URLs
+
+Finding links are designed to resolve under:
+
+- `https://docs.buildgraph.dev/rules/<RULE_ID>`
+
+Examples:
+
+- `https://docs.buildgraph.dev/rules/BG_REPRO_FROM_MUTABLE`
+- `https://docs.buildgraph.dev/rules/BG_SEC_ROOT_USER`

docs/rules/BG_CACHE_ARG_LATE.md

@@ -0,0 +1,36 @@
+# BG_CACHE_ARG_LATE
+
+- Dimension: `cacheability`
+- Severity: `medium`
+
+## Summary
+
+`ARG` values are declared late, after expensive build steps.
+
+## Why It Matters
+
+Changing late `ARG` values can invalidate large portions of the build graph.
+
+## Typical Trigger
+
+```dockerfile
+RUN make deps
+ARG APP_VERSION
+RUN make build
+```
+
+## Recommended Fix
+
+Declare stable `ARG` values before expensive operations.
+
+```dockerfile
+ARG APP_VERSION
+RUN make deps
+RUN make build
+```
+
+## Remediation Checklist
+
+- Move stable args earlier.
+- Keep volatile args scoped only where needed.
+- Re-check cache hit rate in CI.

docs/rules/BG_CACHE_COPY_ALL_EARLY.md

@@ -0,0 +1,35 @@
+# BG_CACHE_COPY_ALL_EARLY
+
+- Dimension: `cacheability`
+- Severity: `high`
+
+## Summary
+
+A broad `COPY .` happens before dependency install steps.
+
+## Why It Matters
+
+Any source file change invalidates dependency cache and forces expensive reinstall/build steps.
+
+## Typical Trigger
+
+```dockerfile
+COPY . .
+RUN npm ci
+```
+
+## Recommended Fix
+
+Copy dependency manifests first, install dependencies, then copy the remaining source.
+
+```dockerfile
+COPY package.json package-lock.json ./
+RUN npm ci
+COPY . .
+```
+
+## Remediation Checklist
+
+- Move lockfiles/manifests before install steps.
+- Keep app source copy after dependency restore.
+- Add `.dockerignore` to reduce noisy context changes.

docs/rules/BG_PERF_APT_SPLIT.md

@@ -0,0 +1,35 @@
+# BG_PERF_APT_SPLIT
+
+- Dimension: `performance`
+- Severity: `medium`
+
+## Summary
+
+`apt-get update` is executed without an install in the same layer.
+
+## Why It Matters
+
+Splitting update and install into separate layers increases rebuild time and can use stale package indexes.
+
+## Typical Trigger
+
+```dockerfile
+RUN apt-get update
+RUN apt-get install -y curl
+```
+
+## Recommended Fix
+
+Combine update and install in one instruction and clear apt lists:
+
+```dockerfile
+RUN apt-get update \
+ && apt-get install -y --no-install-recommends curl \
+ && rm -rf /var/lib/apt/lists/*
+```
+
+## Remediation Checklist
+
+- Merge `apt-get update` with related install commands.
+- Add `--no-install-recommends` where possible.
+- Remove apt cache in the same layer.