Codex/ux graph json doctor go126

.github/workflows/ci.yml

@@ -21,7 +21,7 @@ jobs:
       - name: Setup Go
         uses: actions/setup-go@v5
         with:
-          go-version: '1.25.x'
+          go-version: '1.26.x'
 
       - name: Download modules
         run: go mod download
@@ -37,7 +37,7 @@ jobs:
       - name: Setup Go
         uses: actions/setup-go@v5
         with:
-          go-version: '1.25.x'
+          go-version: '1.26.x'
 
       - name: Start buildkitd
         run: |

.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

.github/workflows/release.yml

@@ -38,7 +38,7 @@ jobs:
       - name: Setup Go
         uses: actions/setup-go@v5
         with:
-          go-version: "1.25.x"
+          go-version: "1.26.x"
 
       - name: Build binary
         shell: bash

.gitignore

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

AGENTS.md

@@ -23,3 +23,8 @@
 - 2026-02-25: Integration build fixtures must be deterministic and self-contained (no external digest dependency) to avoid flaky CI.
 - 2026-02-25: Repository metadata is managed with GitHub CLI (`gh`) and should include concise description + discoverable topics.
 - 2026-02-25: Public release policy: publish prebuilt CLI artifacts for Linux/macOS/Windows on each published GitHub release.
+- 2026-02-26: Added first-class build trace + graph workflows (`build --progress/--trace`, `graph --from`, `top --from`) powered by local JSONL trace artifacts.
+- 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

@@ -1,15 +1,122 @@
 # buildgraph
 
-`buildgraph` is a Build Intelligence CLI focused on BuildKit-first workflows.
+`buildgraph` is a Build Intelligence CLI for BuildKit-first workflows.
 
-## Goals
-- BuildKit-first build orchestration and diagnostics.
-- Dockerfile intelligence across performance, cacheability, reproducibility, security, and policy.
-- Human-first output with stable `--json` mode.
-- Extensible backend architecture for future providers such as Buildah.
-- SaaS-ready foundations (auth/events/capabilities) with opt-in behavior.
+## 30-Second Quickstart
 
-## Install
+### Direct BuildKit socket
+
+```bash
+go build ./cmd/buildgraph
+
+./buildgraph build \
+  --context integration/fixtures \
+  --file Dockerfile.integration \
+  --output local \
+  --local-dest /tmp/buildgraph-out \
+  --endpoint unix:///run/buildkit/buildkitd.sock \
+  --progress=json \
+  --trace /tmp/buildgraph.trace.jsonl
+
+./buildgraph graph --from /tmp/buildgraph.trace.jsonl --format dot --output /tmp/buildgraph.dot
+./buildgraph top --from /tmp/buildgraph.trace.jsonl
+```
+
+### Docker Desktop / Docker Engine
+
+```bash
+go build ./cmd/buildgraph
+
+./buildgraph build \
+  --context integration/fixtures \
+  --file Dockerfile.integration \
+  --image-ref buildgraph/quickstart:dev \
+  --progress=human \
+  --trace ./buildgraph.trace.jsonl
+
+./buildgraph graph --from ./buildgraph.trace.jsonl --format json
+./buildgraph top --from ./buildgraph.trace.jsonl --limit 5
+```
+
+## Example Output (Sample)
+
+```text
+$ buildgraph top --from ./buildgraph.trace.jsonl
+Vertices analyzed: 9
+
+Slowest vertices:
+1. 4823 ms  RUN apk add --no-cache build-base (sha256:...)
+2. 2111 ms  RUN go build ./cmd/buildgraph (sha256:...)
+
+Critical path: 7034 ms
+1. FROM golang:1.26-alpine (112 ms)
+2. RUN apk add --no-cache build-base (4823 ms)
+3. RUN go build ./cmd/buildgraph (2111 ms)
+```
+
+## Commands
+
+```bash
+buildgraph analyze [--context .] [--file Dockerfile] [--severity-threshold low|medium|high|critical] [--fail-on policy|security|any] [--json]
+buildgraph build [--context .] [--file Dockerfile] [--target NAME] [--platform linux/amd64] [--build-arg KEY=VALUE] [--secret id=foo,src=./foo.txt] [--output image|oci|local] [--image-ref REF] [--oci-dest PATH] [--local-dest PATH] [--backend auto|buildkit] [--endpoint URL] [--progress human|json|none] [--trace out.jsonl] [--json]
+buildgraph graph --from out.jsonl [--format dot|svg|json] [--output PATH] [--json]
+buildgraph top --from out.jsonl [--limit N] [--json]
+buildgraph backend list
+buildgraph doctor
+buildgraph auth login --user <user> --token <token>
+buildgraph auth logout
+buildgraph auth whoami
+buildgraph config show
+buildgraph version
+```
+
+## JSON Output Contract (`--json`)
+
+All machine-readable command output uses a versioned envelope:
+
+```json
+{
+  "apiVersion": "buildgraph.dev/v1",
+  "command": "build",
+  "schemaVersion": "1",
+  "timestamp": "2026-02-26T00:00:00Z",
+  "durationMs": 1234,
+  "result": {},
+  "errors": []
+}
+```
+
+## 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:
+- run metadata (`command`, duration, exit code, success/failure)
+- analysis findings
+- build result metadata
+- local events
+
+`buildgraph` can also write local build traces (`--trace`) as JSONL.
+
+## What Is Never Uploaded By Default
+
+- no build context files are uploaded by default
+- no findings/build metadata are uploaded by default
+- no telemetry is sent unless explicitly enabled (`telemetry.enabled: true`)
+
+Auth credentials are stored locally via OS keyring when available, with local file fallback.
+
+## Install from Source
+
+Requires Go 1.26+.
 
 ```bash
 go build ./cmd/buildgraph
@@ -45,20 +152,6 @@ Invoke-WebRequest -Uri "https://github.com/Makepad-fr/buildgraph/releases/latest
 Expand-Archive -Path ".\\buildgraph_windows_amd64.zip" -DestinationPath ".\\buildgraph"
 ```
 
-## Commands
-
-```bash
-buildgraph analyze [--context .] [--file Dockerfile] [--severity-threshold low|medium|high|critical] [--fail-on policy|security|any] [--json]
-buildgraph build [--context .] [--file Dockerfile] [--target NAME] [--platform linux/amd64] [--build-arg KEY=VALUE] [--secret id=foo,src=./foo.txt] [--output image|oci|local] [--image-ref REF] [--oci-dest PATH] [--local-dest PATH] [--backend auto|buildkit] [--endpoint URL] [--json]
-buildgraph backend list
-buildgraph doctor
-buildgraph auth login --user <user> --token <token>
-buildgraph auth logout
-buildgraph auth whoami
-buildgraph config show
-buildgraph version
-```
-
 ## Configuration
 
 Default merge precedence:
@@ -98,5 +191,6 @@ go test ./...
 ```
 
 ## Notes
-- Build execution avoids shelling out to external build commands.
-- Docker-backed mode currently supports image export, while direct BuildKit mode supports image/OCI/local exports.
+
+- Build execution avoids shelling out to Docker/BuildKit CLIs.
+- Docker-backed mode supports image export; direct BuildKit mode supports image/OCI/local exports.

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.