docs: Material for MkDocs site with GitHub Pages deploy

.github/workflows/docs.yaml

@@ -0,0 +1,55 @@
+name: Docs
+
+# Build the Material for MkDocs site and publish to GitHub Pages.
+# Fully decoupled from ci.yaml — no Go, CGO, or bifrost checkout needed.
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - docs/**
+      - overrides/**
+      - examples/**
+      - mkdocs.yml
+      - requirements-docs.txt
+      - .github/workflows/docs.yaml
+  pull_request:
+    paths:
+      - docs/**
+      - overrides/**
+      - examples/**
+      - mkdocs.yml
+      - requirements-docs.txt
+      - .github/workflows/docs.yaml
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.x'
+      - run: pip install -r requirements-docs.txt
+      - run: mkdocs build --strict
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  # Deploy only from main; PRs just build (above) to catch --strict failures.
+  deploy:
+    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -171,3 +171,6 @@ coverage.txt
 
 # benchmark run output (results summarized in docs/PR, not tracked)
 deploy/eval-containers/sweep-results*.csv
+
+# MkDocs build output
+site/

.pre-commit-config.yaml

@@ -6,6 +6,9 @@ repos:
       - id: trailing-whitespace
       - id: end-of-file-fixer
       - id: check-yaml
+        # --unsafe: validate syntax without resolving custom tags, so MkDocs'
+        # !!python/name: tags in mkdocs.yml don't break the hook.
+        args: [--unsafe]
       - id: check-added-large-files
 
   - repo: https://github.com/dnephin/pre-commit-golang

adapters/bifrost/plugin.go

@@ -8,11 +8,11 @@
 package bifrost
 
 import (
+	bschemas "github.com/maximhq/bifrost/core/schemas"
 	"github.com/rossoctl/context-guru/components"
 	"github.com/rossoctl/context-guru/schema"
 	"github.com/rossoctl/context-guru/session"
 	"github.com/rossoctl/context-guru/store"
-	bschemas "github.com/maximhq/bifrost/core/schemas"
 )
 
 // SessionContextKey is the BifrostContext value key the transport sets from the

adapters/bifrost/plugin_test.go

@@ -6,11 +6,11 @@ import (
 	"testing"
 	"time"
 
+	bschemas "github.com/maximhq/bifrost/core/schemas"
 	_ "github.com/rossoctl/context-guru/components/all"
 	"github.com/rossoctl/context-guru/config"
 	"github.com/rossoctl/context-guru/schema"
 	"github.com/rossoctl/context-guru/store"
-	bschemas "github.com/maximhq/bifrost/core/schemas"
 )
 
 func toolMsg(text string) bschemas.ChatMessage {

apply/apply.go

@@ -27,11 +27,11 @@ import (
 	"strconv"
 	"strings"
 
+	bschemas "github.com/maximhq/bifrost/core/schemas"
 	"github.com/rossoctl/context-guru/components"
 	"github.com/rossoctl/context-guru/schema"
 	"github.com/rossoctl/context-guru/session"
 	"github.com/rossoctl/context-guru/store"
-	bschemas "github.com/maximhq/bifrost/core/schemas"
 	"github.com/tidwall/gjson"
 	"github.com/tidwall/sjson"
 )

apply/apply_test.go

@@ -6,12 +6,12 @@ import (
 	"strings"
 	"testing"
 
+	bschemas "github.com/maximhq/bifrost/core/schemas"
 	"github.com/rossoctl/context-guru/apply"
 	"github.com/rossoctl/context-guru/components"
 	_ "github.com/rossoctl/context-guru/components/all"
 	"github.com/rossoctl/context-guru/config"
 	"github.com/rossoctl/context-guru/store"
-	bschemas "github.com/maximhq/bifrost/core/schemas"
 	"github.com/tidwall/gjson"
 )
 

components/all/all_test.go

@@ -5,13 +5,13 @@ import (
 	"strings"
 	"testing"
 
+	"github.com/maximhq/bifrost/core/schemas"
 	"github.com/rossoctl/context-guru/components"
 	_ "github.com/rossoctl/context-guru/components/all"
 	"github.com/rossoctl/context-guru/config"
 	"github.com/rossoctl/context-guru/expand"
 	"github.com/rossoctl/context-guru/schema"
 	"github.com/rossoctl/context-guru/store"
-	"github.com/maximhq/bifrost/core/schemas"
 )
 
 func toolMsg(text string) schemas.ChatMessage {

components/all/llm_test.go

@@ -6,10 +6,10 @@ import (
 	"strings"
 	"testing"
 
+	bschemas "github.com/maximhq/bifrost/core/schemas"
 	"github.com/rossoctl/context-guru/components"
 	"github.com/rossoctl/context-guru/schema"
 	"github.com/rossoctl/context-guru/store"
-	bschemas "github.com/maximhq/bifrost/core/schemas"
 )
 
 // stubModel is a fixed LLM used to drive the model-based components in tests.

components/all/markermode_test.go

@@ -7,12 +7,12 @@ import (
 	"strings"
 	"testing"
 
+	"github.com/maximhq/bifrost/core/schemas"
 	"github.com/rossoctl/context-guru/apply"
 	"github.com/rossoctl/context-guru/config"
 	"github.com/rossoctl/context-guru/expand"
 	"github.com/rossoctl/context-guru/schema"
 	"github.com/rossoctl/context-guru/store"
-	"github.com/maximhq/bifrost/core/schemas"
 	"github.com/tidwall/gjson"
 )
 

components/all/more_test.go

@@ -6,13 +6,13 @@ import (
 	"strings"
 	"testing"
 
+	"github.com/maximhq/bifrost/core/schemas"
 	"github.com/rossoctl/context-guru/components"
 	_ "github.com/rossoctl/context-guru/components/all"
 	"github.com/rossoctl/context-guru/config"
 	"github.com/rossoctl/context-guru/expand"
 	"github.com/rossoctl/context-guru/schema"
 	"github.com/rossoctl/context-guru/store"
-	"github.com/maximhq/bifrost/core/schemas"
 )
 
 func run(t *testing.T, yaml string, req *schemas.BifrostChatRequest) (*components.RunReport, store.Store) {

components/all/p4_test.go

@@ -6,9 +6,9 @@ import (
 	"strings"
 	"testing"
 
+	bschemas "github.com/maximhq/bifrost/core/schemas"
 	"github.com/rossoctl/context-guru/expand"
 	"github.com/rossoctl/context-guru/schema"
-	bschemas "github.com/maximhq/bifrost/core/schemas"
 )
 
 func userMsg(text string) bschemas.ChatMessage {

components/all/reuse_test.go

@@ -6,10 +6,10 @@ import (
 	"sync"
 	"testing"
 
+	bschemas "github.com/maximhq/bifrost/core/schemas"
 	"github.com/rossoctl/context-guru/components"
 	"github.com/rossoctl/context-guru/schema"
 	"github.com/rossoctl/context-guru/store"
-	bschemas "github.com/maximhq/bifrost/core/schemas"
 )
 
 // countingModel is a stubModel that records how many times it was called, so a

components/all/skeleton_test.go

@@ -11,9 +11,9 @@ import (
 	"strings"
 	"testing"
 
+	"github.com/maximhq/bifrost/core/schemas"
 	"github.com/rossoctl/context-guru/expand"
 	"github.com/rossoctl/context-guru/schema"
-	"github.com/maximhq/bifrost/core/schemas"
 )
 
 func TestSkeletonElidesBodies(t *testing.T) {

components/component.go

@@ -21,8 +21,8 @@ import (
 	"context"
 	"time"
 
-	"github.com/rossoctl/context-guru/store"
 	"github.com/maximhq/bifrost/core/schemas"
+	"github.com/rossoctl/context-guru/store"
 )
 
 // Component is the common surface: identity + a per-request enable check.

components/offload/cmdfilter.go

@@ -8,11 +8,11 @@ import (
 	"encoding/hex"
 	"strings"
 
+	"github.com/maximhq/bifrost/core/schemas"
 	"github.com/rossoctl/context-guru/components"
 	"github.com/rossoctl/context-guru/components/dsl"
 	"github.com/rossoctl/context-guru/expand"
 	"github.com/rossoctl/context-guru/schema"
-	"github.com/maximhq/bifrost/core/schemas"
 	"gopkg.in/yaml.v3"
 )
 

components/offload/collapse.go

@@ -4,10 +4,10 @@ import (
 	"fmt"
 	"strings"
 
+	"github.com/maximhq/bifrost/core/schemas"
 	"github.com/rossoctl/context-guru/components"
 	"github.com/rossoctl/context-guru/expand"
 	"github.com/rossoctl/context-guru/schema"
-	"github.com/maximhq/bifrost/core/schemas"
 	"gopkg.in/yaml.v3"
 )
 

components/offload/common.go

@@ -3,8 +3,8 @@ package offload
 import (
 	"strings"
 
-	"github.com/rossoctl/context-guru/schema"
 	bschemas "github.com/maximhq/bifrost/core/schemas"
+	"github.com/rossoctl/context-guru/schema"
 )
 
 // errWords mark a tool output (or an item) as carrying a failure — such items

components/offload/dedup.go

@@ -1,9 +1,9 @@
 package offload
 
 import (
+	"github.com/maximhq/bifrost/core/schemas"
 	"github.com/rossoctl/context-guru/components"
 	"github.com/rossoctl/context-guru/schema"
-	"github.com/maximhq/bifrost/core/schemas"
 	"gopkg.in/yaml.v3"
 )
 

components/offload/extract.go

@@ -5,11 +5,11 @@ import (
 	"strings"
 	"time"
 
+	bschemas "github.com/maximhq/bifrost/core/schemas"
 	"github.com/rossoctl/context-guru/components"
 	"github.com/rossoctl/context-guru/expand"
 	"github.com/rossoctl/context-guru/internal/extract"
 	"github.com/rossoctl/context-guru/schema"
-	bschemas "github.com/maximhq/bifrost/core/schemas"
 	"gopkg.in/yaml.v3"
 )
 

components/offload/failed_run.go

@@ -3,10 +3,10 @@ package offload
 import (
 	"regexp"
 
+	"github.com/maximhq/bifrost/core/schemas"
 	"github.com/rossoctl/context-guru/components"
 	"github.com/rossoctl/context-guru/expand"
 	"github.com/rossoctl/context-guru/schema"
-	"github.com/maximhq/bifrost/core/schemas"
 	"gopkg.in/yaml.v3"
 )
 

components/offload/mask.go

@@ -1,10 +1,10 @@
 package offload
 
 import (
+	bschemas "github.com/maximhq/bifrost/core/schemas"
 	"github.com/rossoctl/context-guru/components"
 	"github.com/rossoctl/context-guru/expand"
 	"github.com/rossoctl/context-guru/schema"
-	bschemas "github.com/maximhq/bifrost/core/schemas"
 	"gopkg.in/yaml.v3"
 )
 

components/offload/phi_evict.go

@@ -3,10 +3,10 @@ package offload
 import (
 	"sort"
 
+	bschemas "github.com/maximhq/bifrost/core/schemas"
 	"github.com/rossoctl/context-guru/components"
 	"github.com/rossoctl/context-guru/expand"
 	"github.com/rossoctl/context-guru/schema"
-	bschemas "github.com/maximhq/bifrost/core/schemas"
 	"gopkg.in/yaml.v3"
 )
 

components/offload/skeleton.go

@@ -13,11 +13,11 @@ import (
 	"regexp"
 	"strings"
 
+	"github.com/maximhq/bifrost/core/schemas"
 	"github.com/rossoctl/context-guru/components"
 	"github.com/rossoctl/context-guru/expand"
 	"github.com/rossoctl/context-guru/internal/treesitter"
 	"github.com/rossoctl/context-guru/schema"
-	"github.com/maximhq/bifrost/core/schemas"
 	sitter "github.com/tree-sitter/go-tree-sitter"
 	"gopkg.in/yaml.v3"
 )

components/offload/smartcrush.go

@@ -5,10 +5,10 @@ import (
 	"fmt"
 	"strings"
 
+	bschemas "github.com/maximhq/bifrost/core/schemas"
 	"github.com/rossoctl/context-guru/components"
 	"github.com/rossoctl/context-guru/expand"
 	"github.com/rossoctl/context-guru/schema"
-	bschemas "github.com/maximhq/bifrost/core/schemas"
 	"gopkg.in/yaml.v3"
 )
 

components/offload/state.go

@@ -5,8 +5,8 @@ import (
 	"encoding/hex"
 	"encoding/json"
 
-	"github.com/rossoctl/context-guru/components"
 	bschemas "github.com/maximhq/bifrost/core/schemas"
+	"github.com/rossoctl/context-guru/components"
 )
 
 // State reuse over the generic Store (key→bytes), session-scoped by key prefix

components/offload/summarize.go

@@ -6,10 +6,10 @@ import (
 	"strings"
 	"time"
 
+	bschemas "github.com/maximhq/bifrost/core/schemas"
 	"github.com/rossoctl/context-guru/components"
 	"github.com/rossoctl/context-guru/expand"
 	"github.com/rossoctl/context-guru/schema"
-	bschemas "github.com/maximhq/bifrost/core/schemas"
 	"gopkg.in/yaml.v3"
 )
 

components/offload/zz_live_test.go

@@ -6,9 +6,9 @@ import (
 	"strings"
 	"testing"
 
+	bschemas "github.com/maximhq/bifrost/core/schemas"
 	"github.com/rossoctl/context-guru/internal/cheapmodel"
 	"github.com/rossoctl/context-guru/schema"
-	bschemas "github.com/maximhq/bifrost/core/schemas"
 )
 
 // Live example of the summarize component: real model compresses a realistic

components/pipeline.go

@@ -3,8 +3,8 @@ package components
 import (
 	"fmt"
 
-	"github.com/rossoctl/context-guru/schema"
 	"github.com/maximhq/bifrost/core/schemas"
+	"github.com/rossoctl/context-guru/schema"
 )
 
 // Pipeline runs an ordered list of components over a request. Order is set by

components/pipeline_test.go

@@ -5,8 +5,8 @@ import (
 	"strings"
 	"testing"
 
-	"github.com/rossoctl/context-guru/store"
 	"github.com/maximhq/bifrost/core/schemas"
+	"github.com/rossoctl/context-guru/store"
 )
 
 // --- fakes ---