Add SpecGraph DocC technical surface

.github/workflows/pages-technical-root.yml

@@ -1,19 +1,30 @@
-name: Deploy Technical Root to GitHub Pages
+name: Deploy DocC Technical Surface
 
 on:
   push:
     branches:
       - main
       - master
     paths:
+      - "Package.swift"
+      - "Package.resolved"
+      - "Sources/SpecGraph/**"
+      - "docs/github-pages-root/**"
+      - ".github/workflows/pages-technical-root.yml"
+  pull_request:
+    branches:
+      - main
+      - master
+    paths:
+      - "Package.swift"
+      - "Package.resolved"
+      - "Sources/SpecGraph/**"
       - "docs/github-pages-root/**"
       - ".github/workflows/pages-technical-root.yml"
   workflow_dispatch:
 
 permissions:
   contents: read
-  pages: write
-  id-token: write
 
 concurrency:
   group: github-pages
@@ -23,32 +34,69 @@ env:
   FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
 
 jobs:
-  deploy:
-    name: Deploy technical root
-    runs-on: ubuntu-latest
-    environment:
-      name: github-pages
-      url: ${{ steps.deployment.outputs.page_url }}
+  build:
+    name: Build DocC technical surface
+    runs-on: macos-14
 
     steps:
       - name: Checkout
         uses: actions/checkout@v5
 
+      - name: Setup Xcode
+        uses: maxim-lobanov/setup-xcode@v1
+        with:
+          xcode-version: latest-stable
+
       - name: Verify technical root source
         run: |
           test -f docs/github-pages-root/index.html || {
             echo "docs/github-pages-root/index.html is missing."
             exit 1
           }
 
-      - name: Configure GitHub Pages
-        uses: actions/configure-pages@v5
+      - name: Build DocC documentation
+        run: |
+          swift package --allow-writing-to-directory ./.docc-build \
+            generate-documentation \
+            --target SpecGraph \
+            --output-path ./.docc-build \
+            --transform-for-static-hosting \
+            --hosting-base-path SpecGraph
+
+      - name: Add technical root
+        run: |
+          cp docs/github-pages-root/index.html ./.docc-build/index.html
 
-      - name: Upload technical root artifact
+      - name: Verify Pages artifact
+        run: |
+          test -f ./.docc-build/index.html
+          test -f ./.docc-build/documentation/specgraph/index.html
+
+      - name: Upload Pages artifact
+        if: github.event_name == 'push' || github.event_name == 'workflow_dispatch'
         uses: actions/upload-pages-artifact@v4
         with:
-          path: docs/github-pages-root
+          path: ./.docc-build
 
+  deploy:
+    if: |
+      github.event_name == 'workflow_dispatch' ||
+      (
+        github.event_name == 'push' &&
+        (github.ref == 'refs/heads/main' || github.ref == 'refs/heads/master')
+      )
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    steps:
       - name: Deploy to GitHub Pages
         id: deployment
         uses: actions/deploy-pages@v4

.gitignore

@@ -9,6 +9,8 @@ __pycache__/
 htmlcov/
 dist/
 build/
+.build/
+.docc-build/
 
 # Supervisor runtime scratch state and generated run artifacts are local by default.
 .worktrees/

Package.swift

@@ -0,0 +1,25 @@
+// swift-tools-version:5.9
+// This package exists only to generate DocC documentation for the SpecGraph
+// Python project. The runtime implementation lives under tools/.
+
+import PackageDescription
+
+let package = Package(
+    name: "SpecGraph",
+    products: [
+        .library(
+            name: "SpecGraph",
+            targets: ["SpecGraph"]
+        ),
+    ],
+    dependencies: [
+        .package(url: "https://github.com/apple/swift-docc-plugin", from: "1.0.0"),
+    ],
+    targets: [
+        .target(
+            name: "SpecGraph",
+            path: "Sources/SpecGraph",
+            exclude: []
+        ),
+    ]
+)

Sources/SpecGraph/Documentation.docc/ArtifactPublishing.md

@@ -0,0 +1,26 @@
+# Artifact Publishing
+
+SpecGraph publishes technical and product-facing surfaces through separate
+channels.
+
+## GitHub Pages
+
+GitHub Pages owns the technical surface:
+
+- the repository root technical entrypoint;
+- DocC documentation under `documentation/specgraph/`;
+- future generated technical artifacts that belong next to documentation.
+
+The root page is intentionally not the product landing page.
+
+## Static Host
+
+The custom static host owns product-facing landing content and generated public
+artifact bundles. Static-host uploads must remain non-destructive so separate
+jobs do not delete each other's files.
+
+## Boundary
+
+Do not deploy `landing/` to GitHub Pages root. That can hide the technical
+documentation entrypoint behind product navigation and create loops where
+documentation links return to a landing page.

Sources/SpecGraph/Documentation.docc/GettingStarted.md

@@ -0,0 +1,27 @@
+# Getting Started
+
+Use SpecGraph to keep specification work tied to explicit artifacts and runtime
+evidence.
+
+## Operator Surface
+
+The repository keeps the following surfaces separate:
+
+- `docs/` contains source documentation, proposal records, and operator notes.
+- `tools/` contains Python tooling for derived surfaces and validation gates.
+- `runs/` contains local runtime artifacts and is not published directly.
+- GitHub Pages publishes the technical entrypoint and DocC documentation.
+- The custom static host publishes product-facing landing content and generated
+  public artifacts.
+
+## Routine Validation
+
+Common local checks are exposed through Make targets:
+
+```bash
+make publish-bundle
+make proposal-tracking-gate
+make test
+```
+
+Use narrower tests when changing a focused workflow or documentation surface.

Sources/SpecGraph/Documentation.docc/ProposalsAndRuntime.md

@@ -0,0 +1,24 @@
+# Proposals and Runtime Evidence
+
+SpecGraph treats proposal records and runtime evidence as connected surfaces.
+
+## Proposal Records
+
+Proposal markdown under `docs/proposals/` describes bounded changes and their
+intended relationship to canonical specifications. Changes that affect proposal
+documents should include matching tracking material or an explicit
+documentation-only classification.
+
+## Runtime Evidence
+
+Runtime evidence lives in generated registries, viewer-facing JSON, and local
+run artifacts. Evidence should support claims about realized behavior without
+turning local runtime artifacts into canonical documentation by accident.
+
+## Validation Gate
+
+Use the proposal tracking gate when proposal documentation changes:
+
+```bash
+make proposal-tracking-gate
+```

Sources/SpecGraph/Documentation.docc/SpecGraph.md

@@ -0,0 +1,44 @@
+# ``SpecGraph``
+
+SpecGraph is a specification graph for evolving agent-facing contracts,
+proposal traces, runtime evidence, and publication surfaces.
+
+## Overview
+
+SpecGraph keeps specification work auditable by connecting canonical specs,
+proposal records, generated viewer surfaces, runtime evidence, and downstream
+handoff artifacts.
+
+The runtime implementation remains in the Python tooling under `tools/`. This
+DocC catalog is the hosted technical documentation surface for operators and
+downstream consumers.
+
+The current public surfaces are:
+
+- a GitHub Pages technical root;
+- generated static artifacts for read-only consumers;
+- proposal and runtime-evidence documentation under `docs/`;
+- product landing content on the custom static host.
+
+Product landing and technical documentation are separate publication surfaces.
+The custom/static host owns product-facing landing content. GitHub Pages owns
+generated technical documentation and public artifact entrypoints.
+
+## Source Documents
+
+The canonical source files remain in the repository:
+
+- `README.md`
+- `CONTRIBUTING.md`
+- `AGENTS.md`
+- `docs/static_artifact_publish.md`
+- `docs/proposals/*.md`
+- `tools/README.md`
+
+## Topics
+
+### Start Here
+
+- <doc:GettingStarted>
+- <doc:ArtifactPublishing>
+- <doc:ProposalsAndRuntime>

Sources/SpecGraph/specgraph.swift

@@ -0,0 +1,2 @@
+/// Documentation-only Swift target for the SpecGraph DocC catalog.
+public enum SpecGraphDocs {}

docs/github-pages-root/index.html

@@ -154,11 +154,11 @@ <h1>SpecGraph technical surface.</h1>
             Current generated dashboard surface consumed by viewers.
           </span>
         </a>
-        <a class="card" href="https://github.com/0al-spec/SpecGraph/tree/main/docs">
+        <a class="card" href="https://0al-spec.github.io/SpecGraph/documentation/specgraph/">
           <span class="label">Docs</span>
-          <span class="title">Repository documentation</span>
+          <span class="title">DocC documentation</span>
           <span class="desc">
-            Viewer contracts, publishing notes, proposals, and operator guides.
+            Canonical generated technical documentation entrypoint.
           </span>
         </a>
         <a class="card" href="https://specgraph.tech/">

docs/static_artifact_publish.md

@@ -54,9 +54,10 @@ surface.
 
 GitHub Pages is not the product landing surface. The repository Pages root is
 published from `docs/github-pages-root/` as a technical entrypoint with links to
-the public artifact manifest, generated runs, repository docs, and the custom
-landing page. Do not deploy `landing/` to GitHub Pages root; doing so can create
-navigation loops where documentation links return to the marketing page.
+the canonical DocC entrypoint at `documentation/specgraph/`, the public artifact
+manifest, generated runs, and the custom landing page. Do not deploy `landing/`
+to GitHub Pages root; doing so can create navigation loops where documentation
+links return to the marketing page.
 
 The source `runs/` directory remains local and unchanged. The publish bundle is
 a redacted mirror: local absolute paths such as `/Users/...` are replaced with

tests/test_publish_static_artifacts_workflow.py

@@ -94,6 +94,32 @@ def test_landing_page_deploys_as_separate_non_destructive_job() -> None:
     assert "--delete" not in landing_job
 
 
+def test_pages_technical_root_builds_docc_surface() -> None:
+    workflow = _workflow_text("pages-technical-root.yml")
+
+    assert "name: Deploy DocC Technical Surface" in workflow
+    assert "pull_request:" in workflow
+    assert "runs-on: macos-14" in workflow
+    assert "generate-documentation" in workflow
+    assert "--target SpecGraph" in workflow
+    assert "--hosting-base-path SpecGraph" in workflow
+    assert "cp docs/github-pages-root/index.html ./.docc-build/index.html" in workflow
+    assert "test -f ./.docc-build/documentation/specgraph/index.html" in workflow
+    assert "if: github.event_name == 'push' || github.event_name == 'workflow_dispatch'" in workflow
+    assert "actions/upload-pages-artifact@v4" in workflow
+    assert "path: ./.docc-build" in workflow
+    assert "actions/deploy-pages@v4" in workflow
+
+
+def test_github_pages_root_docs_card_points_to_docc_entrypoint() -> None:
+    root_page = (
+        Path(__file__).resolve().parents[1] / "docs" / "github-pages-root" / "index.html"
+    ).read_text(encoding="utf-8")
+
+    assert "https://0al-spec.github.io/SpecGraph/documentation/specgraph/" in root_page
+    assert "https://github.com/0al-spec/SpecGraph/tree/main/docs" not in root_page
+
+
 def test_workflows_opt_into_node24_actions_runtime() -> None:
     workflow_dir = Path(__file__).resolve().parents[1] / ".github" / "workflows"
     workflow_paths = sorted(workflow_dir.glob("*.yml"))