diff --git a/docs/CNAME b/docs/CNAME new file mode 100644 index 0000000..3a55b48 --- /dev/null +++ b/docs/CNAME @@ -0,0 +1 @@ +modules.specfact.io diff --git a/docs/_config.yml b/docs/_config.yml index cd6e568..3aae7c0 100644 --- 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 index 35c33bc..f95cb3f 100644 --- a/docs/_layouts/default.html +++ b/docs/_layouts/default.html @@ -111,10 +111,9 @@
- Home - Getting Started - Guides - Reference + Docs Home + Core CLI + Modules
@@ -125,7 +124,7 @@ diff --git a/docs/guides/README.md b/docs/guides/README.md index 89a286b..79d6683 100644 --- 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 index 4dab610..cdad22b 100644 --- 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 index 601776e..0ea2fc7 100644 --- 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 new file mode 100644 index 0000000..bea0667 --- /dev/null +++ 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 new file mode 100644 index 0000000..ea38d6b --- /dev/null +++ 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 new file mode 100644 index 0000000..e45352a --- /dev/null +++ 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` diff --git a/openspec/changes/docs-01-modules-docs-canonical-site/design.md b/openspec/changes/docs-01-modules-docs-canonical-site/design.md new file mode 100644 index 0000000..dd218f8 --- /dev/null +++ b/openspec/changes/docs-01-modules-docs-canonical-site/design.md @@ -0,0 +1,80 @@ +# Design: Modules Docs Canonical Site And Publishing Contract + +## Context + +The modules repository already owns the content that best represents official bundle workflows, but the public site identity is still weak: + +- the site currently targets `https://nold-ai.github.io/specfact-cli-modules/` +- many overlapping bundle pages are still available in `specfact-cli` +- navigation is not yet coordinated with a canonical docs entry point + +This repository should become the canonical origin for module-specific deep docs without depending on a combined build with the core docs repository. + +## Goals + +- Give the modules docs site a first-class public identity suitable for `modules.specfact.io` +- Make site navigation explicitly interoperable with the core docs portal model +- Support independent publishing of module-only docs changes + +## Non-Goals + +- Implement Cloudflare routing in this repository +- Move every duplicated page out of `specfact-cli` in the same change +- Replace Jekyll or GitHub Pages + +## Publication Model + +Target public topology: + +```text +docs.specfact.io -> canonical docs entry point and core docs origin +modules.specfact.io -> modules docs origin +``` + +This repo is responsible for the `modules.specfact.io` side of the contract: + +- site copy and metadata must present it as the canonical home for official bundle docs +- navigation must include routes back to docs home and core docs +- internal sidebar focus should remain module-specific rather than trying to mirror the entire core docs tree + +## Navigation Contract + +Shared top-level labels: + +- `Docs Home` +- `Core CLI` +- `Modules` + +The modules site should use these labels in its top nav while keeping the local sidebar focused on: + +- bundle guides +- official modules +- publishing and signing +- reference + +## Validation Strategy + +Implementation should add lightweight checks for: + +- canonical site identity in landing page/configuration +- shared top-level navigation labels +- avoidance of wording that presents the GitHub Pages project URL as the long-term canonical home + +Those checks are sufficient because the change is about site identity and publication contract, not runtime behavior. + +## Discovery Notes + +The current modules docs set substantially overlaps with the `specfact-cli` docs tree. Shared files currently include: + +- landing/config/layout assets (`index.md`, `_config.yml`, `_layouts/default.html`, `assets/main.scss`) +- module-focused guide families (`guides/installing-modules.md`, `guides/module-marketplace.md`, `guides/module-development.md`, `guides/publishing-modules.md`, `guides/module-signing-and-key-rotation.md`) +- adapter and backlog workflow guides (`adapters/*.md`, `guides/backlog-*.md`, `guides/devops-adapter-integration.md`) +- module/reference material (`reference/module-*.md`, `reference/bridge-registry.md`, `reference/commands.md`) + +The canonical module-owned destinations for this change are the modules site landing page, top navigation, and the bundle/module deep-guidance sections listed above. This change does not migrate or delete the duplicate pages from `specfact-cli`; it makes the ownership contract explicit here so the follow-on core-docs cleanup can point readers back to this site. + +## Cutover Assumptions + +- `docs.specfact.io` remains the canonical entry point for the overall docs experience and the core docs origin. +- `modules.specfact.io` is the intended canonical modules docs origin once GitHub Pages and Cloudflare are wired. +- Until DNS/routing is live, site copy must describe the modules subdomain as the intended public address and treat GitHub Pages as preview infrastructure rather than the long-term canonical identity. diff --git a/openspec/changes/docs-01-modules-docs-canonical-site/proposal.md b/openspec/changes/docs-01-modules-docs-canonical-site/proposal.md new file mode 100644 index 0000000..7e73160 --- /dev/null +++ b/openspec/changes/docs-01-modules-docs-canonical-site/proposal.md @@ -0,0 +1,28 @@ +# Change: Modules Docs Canonical Site And Publishing Contract + +## Why + +`specfact-cli-modules` already ships its own Jekyll docs site, but that site is still positioned as a secondary GitHub Pages project URL while `specfact-cli` continues to host much of the same bundle documentation on the canonical docs domain. The result is duplicated maintenance, inconsistent ownership language, and no stable public docs identity for official bundle content. + +The modules repository needs a clear docs contract of its own: official bundle and module documentation should publish independently on a first-class docs domain and present itself as the canonical home for deep module workflow guidance. + +## What Changes + +- Define the modules docs site as the canonical published home for official bundle and module-specific documentation. +- Update landing copy, site configuration, and navigation expectations so the site is ready for publication on a stable public docs domain rather than only the GitHub Pages project-path URL. +- Establish cross-site navigation rules linking modules docs back to `docs.specfact.io` and the core docs section. +- Prepare the content model for coordinated migration of duplicate bundle pages out of `specfact-cli` without requiring a combined docs build. + +## Capabilities + +### New Capabilities + +- `modules-docs-publishing`: a stable publication and navigation contract for the dedicated modules docs site + +## Impact + +- Affected docs: `docs/_config.yml`, `docs/index.md`, `docs/_layouts/default.html`, and bundle-focused navigation/landing content in the modules docs set. +- User-facing impact: readers can discover a stable modules docs destination, understand that it is the canonical home for official bundle docs, and navigate back to the canonical docs entry point and core docs. +- Integration points: `specfact-cli` docs ownership wording and shared navigation labels must align with this site; Cloudflare-managed public docs domains will consume the resulting publication contract. +- Risk area: if the public-domain cutover lags behind content updates, the site must avoid hardcoding claims that point to a nonexistent live domain before DNS and routing are ready. + diff --git a/openspec/changes/docs-01-modules-docs-canonical-site/specs/modules-docs-publishing/spec.md b/openspec/changes/docs-01-modules-docs-canonical-site/specs/modules-docs-publishing/spec.md new file mode 100644 index 0000000..2b2e1fc --- /dev/null +++ b/openspec/changes/docs-01-modules-docs-canonical-site/specs/modules-docs-publishing/spec.md @@ -0,0 +1,31 @@ +## ADDED Requirements + +### Requirement: Modules docs site is the canonical home for official bundle documentation + +The modules documentation site SHALL present itself as the canonical published home for official bundle and module-specific deep documentation. + +#### Scenario: Reader opens modules landing page + +- **WHEN** a reader opens the modules docs landing page +- **THEN** the page states that official bundle and module-specific deep guidance is owned by `specfact-cli-modules` +- **AND** the page does not describe the GitHub Pages project-path URL as the long-term canonical public identity. + +### Requirement: Modules docs expose shared cross-site navigation + +The modules documentation site SHALL expose shared top-level navigation labels that align with the canonical docs information architecture. + +#### Scenario: Reader uses top navigation + +- **WHEN** a reader opens the modules docs site +- **THEN** the top navigation includes `Docs Home`, `Core CLI`, and `Modules` +- **AND** the links guide the reader to the canonical docs entry point and core docs section without ambiguity. + +### Requirement: Modules docs remain independently publishable + +The modules documentation site SHALL support independent publishing and deployment without requiring a combined docs build with `specfact-cli`. + +#### Scenario: Module-only docs change is published + +- **WHEN** a change affects only `specfact-cli-modules/docs` +- **THEN** the modules docs build and publication workflow can ship the change without rebuilding the core docs site +- **AND** the site metadata and navigation remain valid for the public docs topology. diff --git a/openspec/changes/docs-01-modules-docs-canonical-site/tasks.md b/openspec/changes/docs-01-modules-docs-canonical-site/tasks.md new file mode 100644 index 0000000..55ee517 --- /dev/null +++ b/openspec/changes/docs-01-modules-docs-canonical-site/tasks.md @@ -0,0 +1,29 @@ +## 1. Change Setup And Discovery + +- [x] 1.1 Create worktree `../specfact-cli-modules-worktrees/feature/docs-01-modules-docs-canonical-site` with branch `feature/docs-01-modules-docs-canonical-site` from `origin/dev` +- [x] 1.2 Inventory modules docs pages that are currently duplicated in `specfact-cli` and identify the pages that should become the canonical module-owned destinations +- [x] 1.3 Confirm the public-domain cutover assumptions so docs wording stays accurate before Cloudflare routing is live + +## 2. Spec Deltas First + +- [x] 2.1 Add the `modules-docs-publishing` spec delta for canonical publication, site identity, and cross-site navigation +- [x] 2.2 Map the required changes to docs configuration, landing copy, and top navigation before implementation begins + +## 3. Validation First + +- [x] 3.1 Add failing docs validation checks or assertions for canonical site identity, shared top-level navigation, and stable public-domain readiness +- [x] 3.2 Add failing docs validation checks or assertions proving module-specific deep guidance is presented as canonically owned by the modules site +- [x] 3.3 Record the failing validation evidence in `openspec/changes/docs-01-modules-docs-canonical-site/TDD_EVIDENCE.md` + +## 4. Modules Site Realignment + +- [x] 4.1 Update `docs/_config.yml` and `docs/index.md` so the site is ready for a first-class public docs domain and canonical modules-site positioning +- [x] 4.2 Update `docs/_layouts/default.html` and any related navigation content to expose `Docs Home`, `Core CLI`, and `Modules` +- [x] 4.3 Update bundle-focused landing and navigation copy so the site clearly serves as the canonical destination for official bundle/module deep docs + +## 5. Validation And Delivery + +- [x] 5.1 Re-run the targeted docs validation checks and record passing evidence in `openspec/changes/docs-01-modules-docs-canonical-site/TDD_EVIDENCE.md` +- [x] 5.2 Run `openspec validate docs-01-modules-docs-canonical-site --strict` +- [x] 5.3 Run the relevant repo quality gates for touched docs/test files +- [ ] 5.4 Open PR to `dev` from `feature/docs-01-modules-docs-canonical-site` diff --git a/tests/unit/test_modules_docs_site_contract.py b/tests/unit/test_modules_docs_site_contract.py new file mode 100644 index 0000000..ff03f27 --- /dev/null +++ b/tests/unit/test_modules_docs_site_contract.py @@ -0,0 +1,63 @@ +from pathlib import Path + + +REPO_ROOT = Path(__file__).resolve().parents[2] +DOCS_CONFIG = REPO_ROOT / "docs" / "_config.yml" +DOCS_INDEX = REPO_ROOT / "docs" / "index.md" +DOCS_LAYOUT = REPO_ROOT / "docs" / "_layouts" / "default.html" +OUTDATED_DOCS_HOSTS = ( + "modules.docs.specfact.io", + "cli.docs.specfact.io", + "nold-ai.github.io/specfact-cli-modules", + "nold-ai.github.io/specfact-cli", +) + + +def _read(path: Path) -> str: + return path.read_text(encoding="utf-8") + + +def test_modules_docs_config_targets_public_modules_domain() -> None: + config = _read(DOCS_CONFIG) + + assert 'url: "https://modules.specfact.io"' in config + assert 'baseurl: ""' in config + assert 'docs_home_url: "https://docs.specfact.io"' in config + assert 'core_cli_docs_url: "https://docs.specfact.io"' in config + assert 'modules_docs_url: "https://modules.specfact.io"' in config + + +def test_modules_landing_page_marks_modules_repo_as_canonical_owner() -> None: + index = _read(DOCS_INDEX) + + assert "canonical published home for official bundle and module-specific deep documentation" in index + assert "specfact-cli-modules owns the official bundle and module-specific deep guidance" in index + assert "nold-ai.github.io/specfact-cli-modules" not in index + + +def test_modules_layout_exposes_shared_cross_site_navigation() -> None: + layout = _read(DOCS_LAYOUT) + + assert ">Docs Home<" in layout + assert ">Core CLI<" in layout + assert ">Modules<" in layout + assert "{{ site.docs_home_url }}" in layout + assert "{{ site.core_cli_docs_url }}" in layout + assert "{{ site.modules_docs_url }}" in layout + + +def test_modules_layout_keeps_sidebar_module_focused() -> None: + layout = _read(DOCS_LAYOUT) + + assert "Official Modules Docs" in layout + assert "Publishing & Signing" in layout + assert ">Examples<" not in layout + + +def test_docs_tree_does_not_reference_retired_public_hosts() -> None: + for path in REPO_ROOT.joinpath("docs").rglob("*"): + if not path.is_file(): + continue + text = _read(path) + for host in OUTDATED_DOCS_HOSTS: + assert host not in text, f"{path} still references retired host {host}"