nold-ai · djm81 · Mar 17, 2026 · Mar 17, 2026 · Mar 17, 2026
diff --git a/docs/CNAME b/docs/CNAME
@@ -0,0 +1 @@
+modules.specfact.io
diff --git a/docs/_config.yml b/docs/_config.yml
@@ -1,7 +1,11 @@
-title: SpecFact CLI Modules Documentation
-description: Official nold-ai bundle documentation for specfact-cli-modules.
-baseurl: "/specfact-cli-modules"
-url: "https://nold-ai.github.io"
+title: Official SpecFact Modules Docs
+description: Canonical documentation for official nold-ai bundles and module-specific deep workflows.
+baseurl: ""
+url: "https://modules.specfact.io"
+docs_home_url: "https://docs.specfact.io"
+core_cli_docs_url: "https://docs.specfact.io"
+modules_docs_url: "https://modules.specfact.io"
+github_pages_preview_label: "GitHub Pages preview origin"
 
 # Build settings
 markdown: kramdown
@@ -77,4 +81,4 @@ sass:
 footer:
   copyright: "© 2026 NOLD AI"
   trademark: >
-    Official bundle documentation lives in this repository.
+    Official bundle and module-specific deep guidance is canonically owned by specfact-cli-modules.
diff --git a/docs/_layouts/default.html b/docs/_layouts/default.html
@@ -111,10 +111,9 @@
             </span>
           </label>
           <div class="trigger">
-            <a class="page-link" href="{{ '/' | relative_url }}">Home</a>
-            <a class="page-link" href="{{ '/getting-started/installation/' | relative_url }}">Getting Started</a>
-            <a class="page-link" href="{{ '/guides/command-chains/' | relative_url }}">Guides</a>
-            <a class="page-link" href="{{ '/reference/' | relative_url }}">Reference</a>
+            <a class="page-link" href="{{ site.docs_home_url }}">Docs Home</a>
+            <a class="page-link" href="{{ site.core_cli_docs_url }}">Core CLI</a>
+            <a class="page-link" href="{{ site.modules_docs_url }}">Modules</a>
           </div>
         </nav>
       </div>
@@ -125,7 +124,7 @@
         <aside class="docs-sidebar" aria-label="Documentation navigation">
           <div class="docs-sidebar-inner">
             <h2 class="docs-sidebar-title">
-              <a href="{{ '/' | relative_url }}">SpecFact CLI</a>
+              <a href="{{ '/' | relative_url }}">Official Modules Docs</a>
             </h2>
 
             <nav class="docs-nav">
@@ -140,41 +139,39 @@ <h2 class="docs-sidebar-title">
                 <li><a href="{{ '/getting-started/tutorial-daily-standup-sprint-review/' | relative_url }}">Tutorial: Daily Standup and Sprint Review</a></li>
               </ul>
 
-              <p class="docs-nav-section">Guides</p>
+              <p class="docs-nav-section">Official Modules</p>
               <ul>
-                <li><a href="{{ '/guides/command-chains/' | relative_url }}">Command Chains</a></li>
-                <li><a href="{{ '/guides/agile-scrum-workflows/' | relative_url }}">Agile/Scrum Workflows</a></li>
-                <li><a href="{{ '/guides/policy-engine-commands/' | relative_url }}">Policy Engine Commands</a></li>
-                <li><a href="{{ '/guides/creating-custom-bridges/' | relative_url }}">Creating Custom Bridges</a></li>
-                <li><a href="{{ '/guides/module-development/' | relative_url }}">Module Development</a></li>
-                <li><a href="{{ '/guides/adapter-development/' | relative_url }}">Adapter Development</a></li>
-                <li><a href="{{ '/guides/extending-projectbundle/' | relative_url }}">Extending ProjectBundle</a></li>
                 <li><a href="{{ '/guides/installing-modules/' | relative_url }}">Installing Modules</a></li>
                 <li><a href="{{ '/guides/module-marketplace/' | relative_url }}">Module Marketplace</a></li>
+                <li><a href="{{ '/guides/module-development/' | relative_url }}">Module Development</a></li>
+                <li><a href="{{ '/guides/adapter-development/' | relative_url }}">Adapter Development</a></li>
                 <li><a href="{{ '/guides/marketplace/' | relative_url }}">Marketplace Bundles</a></li>
-                <li><a href="{{ '/guides/module-signing-and-key-rotation/' | relative_url }}">Module Signing and Key Rotation</a></li>
                 <li><a href="{{ '/guides/using-module-security-and-extensions/' | relative_url }}">Using Module Security and Extensions</a></li>
-                <li><a href="{{ '/guides/brownfield-engineer/' | relative_url }}">Working With Existing Code</a></li>
-                <li><a href="{{ '/guides/brownfield-journey/' | relative_url }}">Existing Code Journey</a></li>
-                <li><a href="{{ '/guides/sidecar-validation/' | relative_url }}">Sidecar Validation</a></li>
-                <li><a href="{{ '/guides/ux-features/' | relative_url }}">UX Features</a></li>
-                <li><a href="{{ '/guides/use-cases/' | relative_url }}">Use Cases</a></li>
-                <li><a href="{{ '/guides/ide-integration/' | relative_url }}">IDE Integration</a></li>
-                <li><a href="{{ '/guides/copilot-mode/' | relative_url }}">CoPilot Mode</a></li>
-                <li><a href="{{ '/guides/troubleshooting/' | relative_url }}">Troubleshooting</a></li>
-                <li><a href="{{ '/guides/competitive-analysis/' | relative_url }}">Competitive Analysis</a></li>
+                <li><a href="{{ '/guides/custom-registries/' | relative_url }}">Custom Registries</a></li>
+                <li><a href="{{ '/guides/creating-custom-bridges/' | relative_url }}">Creating Custom Bridges</a></li>
+                <li><a href="{{ '/guides/extending-projectbundle/' | relative_url }}">Extending ProjectBundle</a></li>
               </ul>
 
-              <p class="docs-nav-section">DevOps & Backlog Sync</p>
+              <p class="docs-nav-section">Bundle Workflows</p>
               <ul>
-                <li><a href="{{ '/guides/devops-adapter-integration/' | relative_url }}">DevOps Integration Guide</a></li>
                 <li><a href="{{ '/guides/backlog-refinement/' | relative_url }}">Backlog Refinement</a></li>
-                <li><a href="{{ '/getting-started/tutorial-backlog-quickstart-demo/' | relative_url }}">Backlog Quickstart Demo</a></li>
-                <li><a href="{{ '/reference/authentication/' | relative_url }}">Authentication</a></li>
+                <li><a href="{{ '/guides/backlog-delta-commands/' | relative_url }}">Backlog Delta Commands</a></li>
+                <li><a href="{{ '/guides/backlog-dependency-analysis/' | relative_url }}">Backlog Dependency Analysis</a></li>
+                <li><a href="{{ '/guides/project-devops-flow/' | relative_url }}">Project DevOps Flow</a></li>
+                <li><a href="{{ '/guides/policy-engine-commands/' | relative_url }}">Policy Engine Commands</a></li>
+                <li><a href="{{ '/guides/devops-adapter-integration/' | relative_url }}">DevOps Adapter Integration</a></li>
+                <li><a href="{{ '/adapters/backlog-adapter-patterns/' | relative_url }}">Backlog Adapter Patterns</a></li>
                 <li><a href="{{ '/adapters/github/' | relative_url }}">GitHub Adapter</a></li>
                 <li><a href="{{ '/adapters/azuredevops/' | relative_url }}">Azure DevOps Adapter</a></li>
-                <li><a href="{{ '/adapters/backlog-adapter-patterns/' | relative_url }}">Backlog Adapter Patterns</a></li>
-                <li><a href="{{ '/guides/template-customization/' | relative_url }}">Template Customization</a></li>
+                <li><a href="{{ '/guides/sidecar-validation/' | relative_url }}">Sidecar Validation</a></li>
+              </ul>
+
+              <p class="docs-nav-section">Publishing &amp; Signing</p>
+              <ul>
+                <li><a href="{{ '/guides/publishing-modules/' | relative_url }}">Publishing Modules</a></li>
+                <li><a href="{{ '/guides/module-signing-and-key-rotation/' | relative_url }}">Module Signing and Key Rotation</a></li>
+                <li><a href="{{ '/reference/module-security/' | relative_url }}">Module Security</a></li>
+                <li><a href="{{ '/reference/bridge-registry/' | relative_url }}">Bridge Registry</a></li>
               </ul>
 
               <p class="docs-nav-section">Reference</p>
@@ -184,23 +181,14 @@ <h2 class="docs-sidebar-title">
                 <li><a href="{{ '/reference/thorough-codebase-validation/' | relative_url }}">Thorough Codebase Validation</a></li>
                 <li><a href="{{ '/reference/authentication/' | relative_url }}">Authentication</a></li>
                 <li><a href="{{ '/reference/architecture/' | relative_url }}">Architecture</a></li>
-                <li><a href="{{ '/architecture/implementation-status/' | relative_url }}">Architecture Implementation Status</a></li>
-                <li><a href="{{ '/architecture/adr/' | relative_url }}">Architecture ADRs</a></li>
                 <li><a href="{{ '/reference/modes/' | relative_url }}">Operational Modes</a></li>
                 <li><a href="{{ '/reference/directory-structure/' | relative_url }}">Directory Structure</a></li>
                 <li><a href="{{ '/reference/projectbundle-schema/' | relative_url }}">ProjectBundle Schema</a></li>
                 <li><a href="{{ '/reference/module-contracts/' | relative_url }}">Module Contracts</a></li>
-                <li><a href="{{ '/reference/module-security/' | relative_url }}">Module Security</a></li>
                 <li><a href="{{ '/reference/module-categories/' | relative_url }}">Module Categories</a></li>
-                <li><a href="{{ '/reference/bridge-registry/' | relative_url }}">Bridge Registry</a></li>
+                <li><a href="{{ '/reference/dependency-resolution/' | relative_url }}">Dependency Resolution</a></li>
                 <li><a href="{{ '/guides/integrations-overview/' | relative_url }}">Integrations Overview</a></li>
               </ul>
-
-              <p class="docs-nav-section">Examples</p>
-              <ul>
-                <li><a href="{{ '/examples/' | relative_url }}">All Examples</a></li>
-                <li><a href="{{ '/examples/quick-examples/' | relative_url }}">Quick Examples</a></li>
-              </ul>
             </nav>
           </div>
         </aside>

diff --git a/docs/guides/README.md b/docs/guides/README.md
@@ -1,6 +1,6 @@
 # Guides
 
-Practical guides for using SpecFact CLI effectively.
+Practical module-owned guides for official bundles, adapters, publishing, and deep workflow documentation.
 
 ## Available Guides
 

diff --git a/docs/index.md b/docs/index.md
@@ -1,33 +1,49 @@
 ---
 layout: default
-title: SpecFact CLI Modules Docs
+title: Official SpecFact Modules Docs
 nav_order: 1
 permalink: /
 ---
 
-# SpecFact CLI Modules Documentation
+# Official SpecFact Modules Docs
 
-This site is the canonical documentation home for official nold-ai module bundles hosted in `specfact-cli-modules`.
+This site is the canonical published home for official bundle and module-specific deep documentation.
 
-## Bundle guides
+specfact-cli-modules owns the official bundle and module-specific deep guidance, while the core CLI platform docs remain separately owned by the core docs site.
 
-- [Marketplace](guides/marketplace.md)
-- [Import Features](guides/import-features.md)
-- [Backlog Refinement](guides/backlog-refinement.md)
-- [Backlog Dependency Analysis](guides/backlog-dependency-analysis.md)
-- [Backlog Delta Commands](guides/backlog-delta-commands.md)
-- [Project DevOps Flow](guides/project-devops-flow.md)
-- [Policy Engine Commands](guides/policy-engine-commands.md)
-- [Sidecar Validation](guides/sidecar-validation.md)
+The intended public docs topology is:
 
-## Reference
+- `Docs Home` at `https://docs.specfact.io`
+- `Core CLI` at `https://docs.specfact.io`
+- `Modules` at `https://modules.specfact.io`
 
-- [Command Reference](reference/commands.md)
-- [Module Categories](reference/module-categories.md)
-- [Module Contracts](reference/module-contracts.md)
+Until Cloudflare routing is enabled for the modules domain, GitHub Pages should be treated as a preview origin rather than the long-term canonical public address.
 
-## Docs ownership
+## Official module guides
 
-- Bundle/module docs are maintained in this repository.
-- Core CLI platform docs remain in `nold-ai/specfact-cli`.
-- Published URL target: `https://nold-ai.github.io/specfact-cli-modules/`.
+- [Marketplace bundles](guides/marketplace.md)
+- [Installing modules](guides/installing-modules.md)
+- [Module marketplace](guides/module-marketplace.md)
+- [Module development](guides/module-development.md)
+- [Publishing modules](guides/publishing-modules.md)
+- [Module signing and key rotation](guides/module-signing-and-key-rotation.md)
+- [Adapter development](guides/adapter-development.md)
+- [Custom registries](guides/custom-registries.md)
+
+## Bundle workflows
+
+- [Import features](guides/import-features.md)
+- [Backlog refinement](guides/backlog-refinement.md)
+- [Backlog dependency analysis](guides/backlog-dependency-analysis.md)
+- [Backlog delta commands](guides/backlog-delta-commands.md)
+- [Project DevOps flow](guides/project-devops-flow.md)
+- [Policy engine commands](guides/policy-engine-commands.md)
+- [Sidecar validation](guides/sidecar-validation.md)
+
+## Module reference
+
+- [Command reference](reference/commands.md)
+- [Module categories](reference/module-categories.md)
+- [Module contracts](reference/module-contracts.md)
+- [Module security](reference/module-security.md)
+- [Bridge registry](reference/bridge-registry.md)
diff --git a/docs/reference/README.md b/docs/reference/README.md
@@ -6,7 +6,7 @@ permalink: /reference/
 
 # Reference Documentation
 
-Complete technical reference for SpecFact CLI.
+Complete technical reference for the official modules site and bundle-owned workflow surface area.
 
 ## Available References
 

diff --git a/openspec/changes/docs-01-modules-docs-canonical-site/.openspec.yaml b/openspec/changes/docs-01-modules-docs-canonical-site/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-03-17
diff --git a/openspec/changes/docs-01-modules-docs-canonical-site/CHANGE_VALIDATION.md b/openspec/changes/docs-01-modules-docs-canonical-site/CHANGE_VALIDATION.md
@@ -0,0 +1,53 @@
+# Change Validation Report: docs-01-modules-docs-canonical-site
+
+**Validation Date**: 2026-03-17
+**Change Proposal**: [proposal.md](./proposal.md)
+**Validation Method**: Dry-run documentation dependency and publication-contract analysis
+
+## Executive Summary
+
+- Breaking Changes: 0 detected at runtime
+- Dependent Files: `README.md`, `docs/_config.yml`, `docs/index.md`, `docs/_layouts/default.html`, and bundle-focused navigation pages
+- Impact Level: Medium (public docs identity and cross-site navigation change)
+- Validation Result: Pass
+- User Decision: Proceed with dedicated modules docs publication contract
+
+## Breaking Changes Detected
+
+None at runtime. This is documentation-site and publication-contract work only.
+
+The main risk is public-link churn if the site starts claiming a first-class public domain before DNS/routing is available. That is mitigated by keeping wording domain-ready rather than claiming the cutover is already live until Cloudflare configuration exists.
+
+## Dependencies Affected
+
+### Critical Alignment Dependencies
+
+- `README.md` still treats the GitHub Pages project URL as the docs target.
+- `docs/_config.yml` still targets `https://nold-ai.github.io` with `baseurl: "/specfact-cli-modules"`.
+- `docs/index.md` already claims canonical ownership for official module docs, but the surrounding site identity and navigation do not yet match that claim.
+- `docs/_layouts/default.html` still uses the same top navigation structure as the core docs set and will need explicit cross-site labels (`Docs Home`, `Core CLI`, `Modules`).
+
+### Cross-Repository Dependencies
+
+- `specfact-cli` must update its docs portal and ownership language so module-specific deep pages in core become handoff/overview content rather than competing canonicals.
+- Cloudflare/public-domain setup is required for final publication on `modules.docs.specfact.io`, but content and navigation alignment can land before that cutover.
+
+## Impact Assessment
+
+- **Code Impact**: None expected
+- **Docs Impact**: Medium-to-high; site config, landing copy, and shared navigation are all in scope
+- **Test Impact**: Lightweight docs assertions are appropriate for site identity, top-nav labels, and canonical ownership wording
+- **Release Impact**: Low-to-medium; the main risk is publishing mixed signals about canonical URLs during the transition window
+
+## Format Validation
+
+- **proposal.md Format**: Pass
+- **tasks.md Format**: Pass
+- **specs Format**: Pass
+- **Config.yaml Compliance**: Pass
+
+## OpenSpec Validation
+
+- **Status**: Pass
+- **Command**: `openspec validate docs-01-modules-docs-canonical-site --strict`
+- **Issues Found/Fixed**: 0
diff --git a/openspec/changes/docs-01-modules-docs-canonical-site/TDD_EVIDENCE.md b/openspec/changes/docs-01-modules-docs-canonical-site/TDD_EVIDENCE.md
@@ -0,0 +1,61 @@
+# TDD Evidence
+
+## Discovery
+
+- Inventory of duplicated docs paths found `86` files shared between `specfact-cli-modules/docs` and `specfact-cli/docs`.
+- The canonical module-owned destinations for this change were documented in `design.md`: landing/config/layout plus module-specific guides, adapter workflows, publishing/signing, and module reference pages.
+- Public-domain cutover assumptions were documented in `design.md`: `docs.specfact.io` remains the entry point and core docs origin, and `modules.specfact.io` becomes the canonical modules origin once GitHub Pages and Cloudflare routing are enabled.
+
+## Red Phase
+
+Command:
+
+```bash
+hatch run pytest tests/unit/test_modules_docs_site_contract.py -q
+```
+
+Result:
+
+- `4` tests collected
+- `4` failed
+- Failures covered the expected gaps:
+  - `_config.yml` still targeted the GitHub Pages project URL instead of the modules public domain contract
+  - `docs/index.md` did not yet state canonical ownership for module-specific deep guidance
+  - `docs/_layouts/default.html` did not expose `Docs Home`, `Core CLI`, and `Modules`
+  - the sidebar remained broad/core-oriented instead of module-focused
+
+## Green Phase
+
+Command:
+
+```bash
+hatch run pytest tests/unit/test_modules_docs_site_contract.py -q
+```
+
+Result:
+
+- `4` tests collected
+- `4` passed
+
+## Validation
+
+Command:
+
+```bash
+openspec validate docs-01-modules-docs-canonical-site --strict
+```
+
+Result:
+
+- Change validated successfully in strict mode
+
+Command:
+
+```bash
+hatch run test -- tests/unit/test_modules_docs_site_contract.py -q
+```
+
+Result:
+
+- The repo `test` script ignored the narrow file selection and executed the broader test suite
+- Full result: `389 passed in 45.42s`