nold-ai · djm81 · Mar 25, 2026 · Mar 25, 2026 · Mar 25, 2026 · Mar 25, 2026
diff --git a/.gitignore b/.gitignore
@@ -45,3 +45,12 @@ logs/
 
 .vibe/skills/openspec-*/
 !.vibe/skills/openspec-workflows/
+
+# Jekyll docs — local Bundler state and build output
+docs/.bundle/
+docs/_site/
+docs/.jekyll-cache/
+
+# local bundle installs (bundle config path vendor/bundle)
+docs/vendor/
+
diff --git a/docs/Gemfile.lock b/docs/Gemfile.lock
@@ -1,21 +1,21 @@
 GEM
   remote: https://rubygems.org/
   specs:
-    addressable (2.8.7)
-      public_suffix (>= 2.0.2, < 7.0)
+    addressable (2.8.9)
+      public_suffix (>= 2.0.2, < 8.0)
     base64 (0.3.0)
     colorator (1.1.0)
-    concurrent-ruby (1.3.5)
+    concurrent-ruby (1.3.6)
     csv (3.3.5)
     em-websocket (0.5.3)
       eventmachine (>= 0.12.9)
       http_parser.rb (~> 0)
     eventmachine (1.2.7)
-    ffi (1.17.2)
+    ffi (1.17.3)
     forwardable-extended (2.6.0)
     google-protobuf (3.25.8-x86_64-linux)
-    http_parser.rb (0.8.0)
-    i18n (1.14.7)
+    http_parser.rb (0.8.1)
+    i18n (1.14.8)
       concurrent-ruby (~> 1.0)
     jekyll (4.4.1)
       addressable (~> 2.4)
@@ -50,15 +50,17 @@ GEM
       jekyll (>= 3.7, < 5.0)
     jekyll-watch (2.2.1)
       listen (~> 3.0)
-    json (2.17.1.2)
-    kramdown (2.5.1)
-      rexml (>= 3.3.9)
+    json (2.19.3)
+    kramdown (2.5.2)
+      rexml (>= 3.4.4)
     kramdown-parser-gfm (1.1.0)
       kramdown (~> 2.0)
     liquid (4.0.4)
-    listen (3.9.0)
+    listen (3.10.0)
+      logger
       rb-fsevent (~> 0.10, >= 0.10.3)
       rb-inotify (~> 0.9, >= 0.9.10)
+    logger (1.7.0)
     mercenary (0.4.0)
     minima (2.5.2)
       jekyll (>= 3.5, < 5.0)
@@ -72,15 +74,15 @@ GEM
     rb-inotify (0.11.1)
       ffi (~> 1.0)
     rexml (3.4.4)
-    rouge (4.6.1)
+    rouge (4.7.0)
     safe_yaml (1.0.5)
     sass-embedded (1.69.5)
       google-protobuf (~> 3.23)
       rake (>= 13.0.0)
     terminal-table (3.0.2)
       unicode-display_width (>= 1.1.1, < 3)
     unicode-display_width (2.6.0)
-    webrick (1.9.1)
+    webrick (1.9.2)
 
 PLATFORMS
   x86_64-linux

diff --git a/docs/_config.yml b/docs/_config.yml
@@ -81,6 +81,10 @@ defaults:
       path: "authoring"
     values:
       layout: default
+  - scope:
+      path: "modules"
+    values:
+      layout: default
 theme: minima
 minima:
   social:

diff --git a/docs/bundles/backlog/overview.md b/docs/bundles/backlog/overview.md
@@ -0,0 +1,114 @@
+---
+layout: default
+title: Backlog bundle overview
+nav_order: 2
+permalink: /bundles/backlog/overview/
+---
+
+# Backlog bundle overview
+
+The **Backlog** bundle (`nold-ai/specfact-backlog`) connects SpecFact to external backlog tools (GitHub Issues, Azure DevOps, and other adapters), adds ceremony-oriented workflows, dependency analysis, delta tracking, and deterministic backlog policy checks.
+
+## Prerequisites
+
+- [SpecFact CLI](https://docs.specfact.io) installed
+- Bundle installed: `specfact module install nold-ai/specfact-backlog` (or include it via `specfact init --profile …`)
+- For provider access: configure tokens or use `specfact backlog auth` where your adapter requires it
+
+## Command surface
+
+After installation, `specfact backlog --help` lists the backlog command group. The backlog category also mounts **policy** as `specfact backlog policy` (see below).
+
+### Ceremony (`specfact backlog ceremony`)
+
+| Command | Purpose |
+|--------|---------|
+| `standup` | Alias for daily standup-style views (`backlog daily`) |
+| `refinement` | Alias for AI-assisted refinement (`backlog refine`) |
+| `planning` | Delegates to sprint-summary style flows when available |
+| `flow` | Kanban-style flow views when available |
+| `pi-summary` | PI summary views when available |
+
+### Core workflows
+
+| Command | Purpose |
+|--------|---------|
+| `daily` | Daily standup table: filtered items, optional interactive mode, summarize prompts |
+| `refine` | AI-assisted template-driven refinement (preview/write, filters, DoR checks) |
+| `add` | Create backlog items with hierarchy and Definition-of-Ready validation |
+| `sync` | Sync backlog graph with stored baseline and export delta outputs |
+| `verify-readiness` | Verify release readiness for selected backlog items |
+| `analyze-deps` | Analyze backlog dependencies for a project |
+| `diff` | Show changes since baseline sync |
+| `promote` | Validate promotion impact and print promotion intent |
+| `init-config` | Scaffold `.specfact/backlog-config.yaml` structure |
+| `map-fields` | Interactive mapping of ADO fields to canonical names |
+
+### Delta (`specfact backlog delta`)
+
+| Command | Purpose |
+|--------|---------|
+| `status` | Compare current graph to baseline; show delta summary |
+| `impact` | Downstream dependency impact for an item |
+| `cost-estimate` | Rough effort points from delta volume |
+| `rollback-analysis` | Rollback risk from current delta |
+
+### Policy (`specfact backlog policy`)
+
+Deterministic policy validation against backlog snapshots (bundled with this package; not core CLI-owned).
+
+| Command | Purpose |
+|--------|---------|
+| `init` | Scaffold `.specfact/policy.yaml` from a template |
+| `validate` | Run policy checks (JSON/Markdown/both) |
+| `suggest` | Patch-ready suggestions (no automatic writes) |
+
+See [Policy engine](policy-engine/) for details.
+
+### Auth (`specfact backlog auth`)
+
+Backlog provider authentication for **GitHub** and **Azure DevOps**: store tokens, run OAuth / device-code flows, inspect status, and clear credentials for setup and troubleshooting.
+
+| Subcommand | Purpose |
+|------------|---------|
+| `azure-devops` | Authenticate to Azure DevOps via PAT (`--pat`) or OAuth (interactive browser or `--use-device-code`) |
+| `github` | Authenticate to GitHub (or GitHub Enterprise) via RFC 8628 device code flow; optional `--client-id`, `--base-url`, `--scopes` |
+| `status` | Show stored auth state for supported providers (valid vs expired tokens) |
+| `clear` | Remove stored tokens; optional `--provider` (`azure-devops` or `github`) or omit to clear all |
+
+## Bundle-owned prompts and templates
+
+Refinement and ceremony flows **emit prompts and instructions** for your IDE copilot. Those assets ship with the backlog bundle (and related payloads); they are **not** maintained as core CLI-owned files. Install or refresh IDE resources with `specfact init ide` (and your team’s bundle publishing workflow) so the CLI and bundles stay aligned.
+
+## Quick examples
+
+Validate the exact flags for your adapter:
+
+```bash
+specfact backlog daily --help
+specfact backlog refine --help
+specfact backlog delta status --help
+specfact backlog policy validate --help
+specfact backlog auth --help
+specfact backlog auth status --help
+specfact backlog auth github --help
+```
+
+GitHub refinement preview (typical entry point):
+
+```bash
+specfact backlog refine github --preview --labels feature
+```
+
+Daily standup scope:
+
+```bash
+specfact backlog daily github --state open --limit 20
+```
+
+## Deep dives
+
+- [Refinement](refinement/)
+- [Dependency analysis](dependency-analysis/)
+- [Delta](delta/)
+- [Policy engine](policy-engine/)
diff --git a/docs/bundles/code-review/overview.md b/docs/bundles/code-review/overview.md
@@ -0,0 +1,58 @@
+---
+layout: default
+title: Code Review bundle overview
+nav_order: 2
+permalink: /bundles/code-review/overview/
+---
+
+# Code Review bundle overview
+
+The **Code Review** bundle (`nold-ai/specfact-code-review`) extends the shared **`specfact code`** command group with **`review`** workflows: governed review runs, **reward ledger** history, and **house-rules** skill management.
+
+Use it together with the [Codebase](../codebase/overview/) bundle (`import`, `analyze`, `drift`, `validate`, `repro`) on the same `code` surface.
+
+## Prerequisites
+
+- `specfact module install nold-ai/specfact-code-review`
+- Optional tool installs (Ruff, Radon, Semgrep, Pyright, etc.) as described in command help
+
+## `specfact code review` — nested commands
+
+| Command | Purpose |
+|--------|---------|
+| `run` | Execute a governed review (scope, JSON output, `--fix`, TDD gate, etc.) |
+| `ledger` | Inspect and update review reward history |
+| `rules` | Manage the house-rules skill (`show`, `init`, `update`) |
+
+### `ledger` subcommands
+
+| Subcommand | Purpose |
+|------------|---------|
+| `update` | Update ledger entries |
+| `status` | Show ledger status |
+| `reset` | Reset ledger state |
+
+### `rules` subcommands
+
+| Subcommand | Purpose |
+|------------|---------|
+| `show` | Show current rules configuration |
+| `init` | Initialize rules/skill assets |
+| `update` | Update rules content |
+
+## Bundle-owned skills and policy packs
+
+House rules and review payloads ship **inside the bundle** (for example Semgrep packs and skill metadata). They are **not** core CLI-owned resources. Install or refresh IDE-side assets with `specfact init ide` after upgrading the bundle.
+
+## Quick examples
+
+```bash
+specfact code review run --help
+specfact code review ledger status --help
+specfact code review rules show --help
+```
+
+## See also
+
+- [Code review module](../../modules/code-review/)
+- [Codebase bundle overview](../codebase/overview/) — import, drift, validation, repro
diff --git a/docs/bundles/codebase/overview.md b/docs/bundles/codebase/overview.md
@@ -0,0 +1,74 @@
+---
+layout: default
+title: Codebase bundle overview
+nav_order: 2
+permalink: /bundles/codebase/overview/
+---
+
+# Codebase bundle overview
+
+The **Codebase** bundle (`nold-ai/specfact-codebase`) mounts under `specfact code` alongside the Code Review bundle. It focuses on **brownfield import**, **contract coverage analysis**, **drift detection**, **sidecar validation**, and **reproducible validation suites**.
+
+For automated review runs (Ruff, Semgrep, ledger, rules), see [Code Review](../code-review/overview/) — also on the `code` command group.
+
+## Prerequisites
+
+- `specfact module install nold-ai/specfact-codebase` (often together with `nold-ai/specfact-project`)
+- Python repos for import/sidecar workflows; optional tool installs (CrossHair, Specmatic, Ruff, etc.) per command help
+
+## Command groups (`specfact code …`)
+
+### `import` — brownfield intake
+
+| Entry | Purpose |
+|-------|---------|
+| `specfact code import` (default) | Import a repository into a project bundle (`from-code` behavior; see `--help`) |
+| `specfact code import from-bridge` | Import from an external bridge/export flow |
+
+Advanced import topics: [Project import command features](../project/import-migration/) (cross-bundle).
+
+### `analyze` — structure and contracts
+
+| Command | Purpose |
+|--------|---------|
+| `contracts` | Analyze codebase for OpenAPI contract coverage and related signals |
+
+### `drift`
+
+| Command | Purpose |
+|--------|---------|
+| `detect` | Detect drift between implementation and specifications |
+
+### `validate` — sidecar
+
+| Command | Purpose |
+|--------|---------|
+| `sidecar init` | Initialize a sidecar workspace for external-repo validation |
+| `sidecar run` | Run the sidecar validation pipeline |
+
+### `repro` — reproducibility
+
+| Command | Purpose |
+|--------|---------|
+| `repro` (default) | Run the full validation suite |
+| `setup` | Prepare repro validation setup |
+
+Use `specfact code repro --help` for the default invocation flags (`--repo`, `--verbose`, `--sidecar`, …).
+
+## Bundle-owned prompts for import/generation
+
+Import and enrichment flows may ship **prompts or helper templates** with the bundle. They are **bundle payload**, not core-owned assets. Align your IDE with `specfact init ide` after bundle upgrades.
+
+## Quick examples
+
+```bash
+specfact code import --help
+specfact code analyze contracts --help
+specfact code drift detect --help
+specfact code validate sidecar init my-bundle /path/to/repo
+specfact code repro --verbose --repo .
+```
+
+## Deep dives
+
+- [Sidecar validation](sidecar-validation/)
diff --git a/docs/bundles/govern/overview.md b/docs/bundles/govern/overview.md
@@ -0,0 +1,45 @@
+---
+layout: default
+title: Govern bundle overview
+nav_order: 2
+permalink: /bundles/govern/overview/
+---
+
+# Govern bundle overview
+
+The **Govern** bundle (`nold-ai/specfact-govern`) adds **enforcement** and **patch-mode** workflows: configure quality gates tied to SDD plans, and preview/apply patches with explicit write controls.
+
+## Prerequisites
+
+- `specfact module install nold-ai/specfact-govern`
+- Project bundles with SDD manifests when using SDD enforcement paths
+
+## `specfact govern enforce`
+
+| Command | Purpose |
+|--------|---------|
+| `stage` | Configure enforcement stages for bundles and plans |
+| `sdd` | Enforce SDD quality gates against manifests and plans |
+
+## `specfact govern patch`
+
+| Command | Purpose |
+|--------|---------|
+| `apply` | Preview and apply patches (local or upstream with `--write`) |
+
+## Bundle-owned policy packs
+
+Enforcement may ship **bundle-local policy packs or presets** with the package. Treat them as **bundle payload** referenced by the govern module, not as core CLI-owned configuration. Refresh IDE-facing resources with `specfact init ide` (core IDE prompts from installed modules). The **Code Review** bundle (`nold-ai/specfact-code-review`) provides `specfact code review rules init --ide` and `specfact code review rules update --ide` (e.g. `--ide cursor`, `--ide claude`, `--ide codex`, or `--ide vibe`; see `--help`) for the house-rules skill—install that bundle separately when you need those commands.
+
+## Quick examples
+
+```bash
+specfact govern --help
+specfact govern enforce stage --help
+specfact govern enforce sdd --help
+specfact govern patch apply --help
+```
+
+## See also
+
+- [Command reference](../../reference/commands/) — nested `govern` commands