nold-ai · djm81 · Mar 26, 2026 · Feb 8, 2026 · Feb 8, 2026 · Feb 8, 2026
diff --git a/.github/workflows/docs-review.yml b/.github/workflows/docs-review.yml
@@ -9,15 +9,21 @@ on:
       - "**/*.md"
       - "**/*.mdc"
       - "docs/**"
-      - "tests/unit/docs/test_release_docs_parity.py"
+      - "tests/unit/docs/**"
+      - "scripts/check-docs-commands.py"
+      - "scripts/check-cross-site-links.py"
+      - "pyproject.toml"
       - ".github/workflows/docs-review.yml"
   push:
     branches: [main, dev]
     paths:
       - "**/*.md"
       - "**/*.mdc"
       - "docs/**"
-      - "tests/unit/docs/test_release_docs_parity.py"
+      - "tests/unit/docs/**"
+      - "scripts/check-docs-commands.py"
+      - "scripts/check-cross-site-links.py"
+      - "pyproject.toml"
       - ".github/workflows/docs-review.yml"
   workflow_dispatch:
 
@@ -41,16 +47,26 @@ jobs:
           python-version: "3.12"
           cache: "pip"
 
-      - name: Install docs review dependencies
+      - name: Install Hatch
         run: |
           python -m pip install --upgrade pip
-          python -m pip install pytest
+          python -m pip install hatch
+
+      - name: Create hatch environment
+        run: hatch env create
+
+      - name: Validate docs command examples
+        run: hatch run check-docs-commands
+
+      - name: Cross-site links (warn-only; live site may lag deploys)
+        continue-on-error: true
+        run: hatch run check-cross-site-links --warn-only
 
       - name: Run docs review suite
         run: |
           mkdir -p logs/docs-review
           DOCS_REVIEW_LOG="logs/docs-review/docs-review_$(date -u +%Y%m%d_%H%M%S).log"
-          python -m pytest tests/unit/docs/test_release_docs_parity.py -q 2>&1 | tee "$DOCS_REVIEW_LOG"
+          hatch run pytest tests/unit/docs/ -q 2>&1 | tee "$DOCS_REVIEW_LOG"
           exit "${PIPESTATUS[0]:-$?}"
 
       - name: Upload docs review logs

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -9,6 +9,16 @@ All notable changes to this project will be documented in this file.
 
 ---
 
+## [Unreleased]
+
+### Added
+
+- CI: `scripts/check-docs-commands.py` and `scripts/check-cross-site-links.py` with `hatch run docs-validate`
+  (command examples vs CLI; modules URLs warn-only when live site lags); workflow runs validation plus
+  `tests/unit/docs/`.
+- Documentation: `docs/reference/documentation-url-contract.md` and navigation links describing how core and modules published URLs relate; OpenSpec spec updates for cross-site linking expectations.
+- Documentation: converted 20 module-owned guide and tutorial pages under `docs/` to thin handoff summaries with canonical links to `modules.specfact.io`; added `docs/reference/core-to-modules-handoff-urls.md` mapping core permalinks to modules URLs.
+
 ## [0.42.6] - 2026-03-26
 
 ### Fixed

diff --git a/docs/README.md b/docs/README.md
@@ -35,6 +35,10 @@ Use the canonical modules docs site for:
 The canonical modules docs site is currently published at `https://modules.specfact.io/`.
 This docs set keeps release-line overview and handoff content for bundle workflows while the canonical modules docs site carries the deep bundle-specific guidance.
 
+## Cross-site contract
+
+- [Documentation URL contract (core and modules)](reference/documentation-url-contract.md) — linking rules vs `modules.specfact.io`
+
 ## Core Entry Points
 
 - [Docs Home](index.md)

diff --git a/docs/_layouts/default.html b/docs/_layouts/default.html
@@ -164,6 +164,7 @@ <h2 class="docs-sidebar-title">
 
               <p class="docs-nav-section">Reference</p>
               <ul>
+                <li><a href="{{ '/reference/documentation-url-contract/' | relative_url }}">Docs URL contract (core vs modules)</a></li>
                 <li><a href="{{ '/reference/commands/' | relative_url }}">Command Reference</a></li>
                 <li><a href="{{ '/reference/module-categories/' | relative_url }}">Module Categories</a></li>
                 <li><a href="{{ '/reference/module-contracts/' | relative_url }}">Module Contracts</a></li>

diff --git a/docs/examples/integration-showcases/integration-showcases-quick-reference.md b/docs/examples/integration-showcases/integration-showcases-quick-reference.md
@@ -157,7 +157,7 @@ git commit -m "Breaking change test"
 cd /tmp/specfact-integration-tests/example5_agentic
 
 # Option 1: CrossHair exploration (if available)
-specfact --no-banner contract-test-exploration src/validator.py
+hatch run contract-test-exploration src/validator.py
 
 # Option 2: Contract enforcement (fallback)
 specfact --no-banner enforce stage --preset balanced

diff --git a/docs/examples/integration-showcases/integration-showcases-testing-guide.md b/docs/examples/integration-showcases/integration-showcases-testing-guide.md
@@ -1373,7 +1373,7 @@ def validate_and_calculate(data: dict) -> float:
 ### Example 5 - Step 2: Run CrossHair Exploration
 
 ```bash
-specfact --no-banner contract-test-exploration src/validator.py
+hatch run contract-test-exploration src/validator.py
 ```
 
 **Note**: If using `uvx`, the command would be:

diff --git a/docs/getting-started/tutorial-backlog-quickstart-demo.md b/docs/getting-started/tutorial-backlog-quickstart-demo.md
@@ -1,277 +1,14 @@
 ---
 layout: default
 title: Tutorial - Backlog Quickstart Demo (GitHub + ADO)
-description: Short end-to-end demo for backlog init-config, map-fields, daily, and refine on GitHub and Azure DevOps.
+description: Handoff to the backlog quickstart demo tutorial on the modules documentation site.
 permalink: /getting-started/tutorial-backlog-quickstart-demo/
 ---
 
-# Tutorial: Backlog Quickstart Demo (GitHub + ADO)
+# Tutorial — backlog quickstart demo
 
+A short end-to-end demo for backlog init, field mapping, daily flow, and refinement on GitHub and Azure DevOps. Copy-paste steps, screenshots, and troubleshooting are kept current on the modules site.
 
-> Modules docs handoff: this page remains in the core docs set as release-line overview content.
-> Canonical bundle-specific deep guidance now lives in the canonical modules docs site, currently
-> published at `https://modules.specfact.io/`.
+**Prerequisites:** Accounts and tokens for your tracker; [Installation](https://docs.specfact.io/getting-started/installation/) completed.
 
-This is a short, copy/paste-friendly demo for new users covering:
-
-1. `specfact backlog init-config`
-2. `specfact backlog map-fields`
-3. `specfact backlog daily`
-4. `specfact backlog refine` (GitHub + ADO)
-
-It also includes a minimal create/check loop using `specfact backlog add`.
-
-Preferred ceremony aliases:
-
-- `specfact backlog ceremony standup` (same behavior as `backlog daily`)
-- `specfact backlog ceremony refinement` (same behavior as `backlog refine`)
-
-## Targets Used in This Demo
-
-- **GitHub**: `nold-ai/specfact-demo-repo`
-- **Azure DevOps**: `dominikusnold/Specfact CLI`
-
-## Prerequisites
-
-- SpecFact CLI installed
-- Auth configured:
-
-```bash
-specfact backlog auth github
-specfact backlog auth azure-devops
-specfact backlog auth status
-```
-
-Expected status should show both providers as valid.
-
-## 1) Initialize Backlog Config
-
-```bash
-specfact backlog init-config --force
-```
-
-This creates `.specfact/backlog-config.yaml`.
-
-## 2) Map Fields (ADO)
-
-Run field mapping for your ADO project. Start with automatic mapping and use interactive mode only if required fields remain unresolved.
-
-```bash
-# Automatic mapping for repeatable setup
-specfact backlog map-fields \
-  --provider ado \
-  --ado-org dominikusnold \
-  --ado-project "Specfact CLI" \
-  --ado-framework scrum \
-  --non-interactive
-
-# Interactive mapping / manual correction
-specfact backlog map-fields \
-  --provider ado \
-  --ado-org dominikusnold \
-  --ado-project "Specfact CLI" \
-  --ado-framework scrum
-```
-
-Notes:
-
-- Select the process style intentionally (`--ado-framework scrum|agile|safe|kanban|default`).
-- Mapping is written to `.specfact/templates/backlog/field_mappings/ado_custom.yaml`.
-- Required fields, selected work item type, and constrained values are persisted in `.specfact/backlog-config.yaml`.
-- `--non-interactive` fails fast with guidance to rerun interactive mapping if required fields remain unresolved.
-
-Optional reset:
-
-```bash
-specfact backlog map-fields \
-  --provider ado \
-  --ado-org dominikusnold \
-  --ado-project "Specfact CLI" \
-  --ado-framework scrum \
-  --reset
-```
-
-## 3) Daily Standup View (Check Backlog Read)
-
-GitHub:
-
-```bash
-specfact backlog daily github \
-  --repo-owner nold-ai \
-  --repo-name specfact-demo-repo \
-  --state open \
-  --limit 5
-```
-
-Disable default state/assignee filters explicitly (for exact ID checks):
-
-```bash
-specfact backlog daily github \
-  --repo-owner nold-ai \
-  --repo-name specfact-demo-repo \
-  --id 28 \
-  --state any \
-  --assignee any
-```
-
-ADO:
-
-```bash
-specfact backlog daily ado \
-  --ado-org dominikusnold \
-  --ado-project "Specfact CLI" \
-  --limit 5
-```
-
-## 4) Refine Workflow (Preview + Tmp Export/Import)
-
-GitHub export:
-
-```bash
-specfact backlog refine github \
-  --repo-owner nold-ai \
-  --repo-name specfact-demo-repo \
-  --limit 3 \
-  --export-to-tmp
-```
-
-ADO export:
-
-```bash
-specfact backlog refine ado \
-  --ado-org dominikusnold \
-  --ado-project "Specfact CLI" \
-  --limit 3 \
-  --export-to-tmp
-```
-
-After refining in your AI IDE, import and write back:
-
-```bash
-# GitHub
-specfact backlog refine github \
-  --repo-owner nold-ai \
-  --repo-name specfact-demo-repo \
-  --import-from-tmp \
-  --write
-
-# ADO
-specfact backlog refine ado \
-  --ado-org dominikusnold \
-  --ado-project "Specfact CLI" \
-  --import-from-tmp \
-  --write
-```
-
-### Required Tmp File Contract (Important)
-
-For `--import-from-tmp`, each item block must keep:
-
-- `## Item N: <title>`
-- `**ID**: <original-id>` (mandatory, unchanged)
-- `**URL**`, `**State**`, `**Provider**`
-- `**Body**:` fenced with ```markdown
-
-Minimal scaffold:
-
-````markdown
-## Item 1: Example title
-
-**ID**: 123
-**URL**: https://example
-**State**: Active
-**Provider**: ado
-
-**Body**:
-```markdown
-## As a
-...
-```
-````
-
-Do not rename labels and do not remove details during refinement.
-
-## 5) Minimal Create + Check Loop
-
-Create test issue/work item:
-
-```bash
-# GitHub create
-specfact backlog add \
-  --adapter github \
-  --project-id nold-ai/specfact-demo-repo \
-  --type story \
-  --title "SpecFact demo smoke test $(date +%Y-%m-%d-%H%M)" \
-  --body "Demo item created by quickstart." \
-  --acceptance-criteria "Demo item exists and is retrievable" \
-  --non-interactive
-
-# ADO create
-specfact backlog add \
-  --adapter ado \
-  --project-id "dominikusnold/Specfact CLI" \
-  --type story \
-  --title "SpecFact demo smoke test $(date +%Y-%m-%d-%H%M)" \
-  --body "Demo item created by quickstart." \
-  --acceptance-criteria "Demo item exists and is retrievable" \
-  --custom-field category=Architecture \
-  --custom-field subcategory="Runtime validation" \
-  --non-interactive
-```
-
-Then verify retrieval by ID using `daily` or `refine --id <id>`.
-
-For ADO projects with required custom fields or picklists:
-
-- run `backlog map-fields` first so `backlog add` has required-field and allowed-values metadata
-- use repeatable `--custom-field key=value` for mapped custom fields
-- non-interactive `backlog add` rejects invalid picklist values before create and prints accepted values
-
-## Quick Troubleshooting
-
-- DNS/network errors (`api.github.com`, `dev.azure.com`): verify outbound network access.
-- Auth errors: re-run `specfact backlog auth status`.
-- ADO mapping issues: re-run `backlog map-fields` and confirm `--ado-framework` is correct. Use interactive mode if auto-mapping cannot resolve required fields.
-- Refine import mismatch: check `**ID**` was preserved exactly.
-
-## ADO Hardening Profile (Corporate Networks)
-
-For unstable corporate VPN/proxy/firewall paths, use this reliability profile.
-
-### Runtime behavior now hardened in CLI
-
-- ADO `daily`/`refine` read paths now retry transient transport failures (`ConnectionError`, reset/disconnect, timeout).
-- Retry policy also covers retryable HTTP statuses (`429`, `500`, `502`, `503`, `504`) with backoff.
-- Hardened paths include:
-  - WIQL query execution
-  - Work-item batch fetch
-  - Iteration/team lookup
-  - Work-item comments fetch
-
-### Operational command recommendations
-
-Use explicit provider context and bounded scope to reduce query fragility:
-
-```bash
-# Daily: explicit scope
-specfact backlog daily ado \
-  --ado-org dominikusnold \
-  --ado-project "Specfact CLI" \
-  --state New \
-  --limit 20
-
-# Refine: small batches first, then scale
-specfact backlog refine ado \
-  --ado-org dominikusnold \
-  --ado-project "Specfact CLI" \
-  --state New \
-  --limit 5 \
-  --export-to-tmp
-```
-
-If current iteration auto-detection is unreliable in your environment, pass explicit filters (`--state`, `--sprint`, `--iteration`) rather than relying on defaults.
-
-### Create flow reliability notes
-
-- `backlog add` uses safe no-replay behavior for create operations to avoid accidental duplicate work-item creation on ambiguous transport failures.
-- If create returns an ambiguous transport error, check ADO for the title before retrying manually.
+**Full tutorial on the canonical modules docs site:** [Backlog quickstart demo](https://modules.specfact.io/getting-started/tutorial-backlog-quickstart-demo/)