Add SpecGraph DocC technical surface

[SoundBlaster]

Summary

• Added a documentation-only Swift package and DocC catalog for SpecGraph.
• Changed the GitHub Pages technical-root workflow to build and deploy a combined artifact: root technical entrypoint plus DocC under documentation/specgraph/.
• Added a mixed-case compatibility redirect so https://0al-spec.github.io/SpecGraph/documentation/SpecGraph/ works as the operator-facing docs URL.
• Updated the root Docs card and publishing notes to point at the DocC surface.
• Link related issue/task (if any): n/a

Motivation

• SpecGraph did not actually publish DocC, so linking GitHub Pages root to /documentation/... produced 404s.
• The expected public docs URL is https://0al-spec.github.io/SpecGraph/documentation/SpecGraph/, while DocC emits the generated module path as lowercase documentation/specgraph/.
• The SpecPM model is the right boundary: custom/static host owns product landing, GitHub Pages owns technical documentation and generated public entrypoints.

Goals

• Publish DocC at https://0al-spec.github.io/SpecGraph/documentation/specgraph/ after merge/deploy.
• Make https://0al-spec.github.io/SpecGraph/documentation/SpecGraph/ a working compatibility entrypoint.
• Keep https://0al-spec.github.io/SpecGraph/ as the technical root, not the product landing page.
• Preserve manual workflow_dispatch deployment behavior for the Pages workflow.

Changes

• Added Package.swift, Package.resolved, and Sources/SpecGraph/Documentation.docc/*.
• Reworked .github/workflows/pages-technical-root.yml into a DocC build + Pages deploy workflow.
• Copied docs/github-pages-root/index.html into .docc-build/index.html so the root technical entrypoint remains available.
• Added a static documentation/SpecGraph/ redirect to the generated lowercase DocC module path.
• Added regression tests for the workflow shape, redirect artifact, and Docs card URL.
• Ignored local Swift build output directories.

Validation

• Tests added/updated for changed behavior
• Local checks passed

Commands run:

git diff --check
python -m ruff format tests/test_publish_static_artifacts_workflow.py
python -m pytest tests/test_publish_static_artifacts_workflow.py -q
python tools/python_quality.py
make proposal-tracking-gate
swift package --allow-writing-to-directory ./.docc-build generate-documentation --target SpecGraph --output-path ./.docc-build --transform-for-static-hosting --hosting-base-path SpecGraph
make PYTHON=python test

Results:

• Focused workflow tests: 9 passed.
• Python quality: passed.
• Proposal tracking gate: passed.
• DocC local build produced documentation/specgraph/index.html.
• Full suite with Python 3.10: 870 passed.

Risks / Notes

• Backward compatibility impact: GitHub Pages root remains a technical entrypoint, but the Docs card now points to generated DocC via the mixed-case compatibility entrypoint.
• Migration/config changes required: after merge, the Pages deploy must run before the new DocC URL becomes live.
• Local make test without PYTHON=python uses macOS /usr/bin/python3 3.9 on this machine and fails on existing Python 3.10 syntax (zip(..., strict=True), str | int type unions). CI uses Python 3.10.

Checklist

• PR title clearly describes the change
• Scope is focused and minimal
• Documentation updated (or N/A)
• No secrets or sensitive data added

[Copilot]

Pull request overview

Updates the repository’s GitHub Pages technical root documentation/navigation so the “Docs” entry consistently points to the canonical generated DocC documentation entrypoint (rather than docs/ source files in the repo), aligning Pages-root navigation with the intended “Docs = DocC” contract.

Changes:

• Updated the GitHub Pages root “Docs” card link/title/description to the DocC entrypoint URL.
• Updated publishing notes to refer to the canonical DocC URL instead of repository docs/.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.

File	Description
docs/github-pages-root/index.html	Repoints the “Docs” card on the Pages technical root to the DocC entrypoint and updates the card copy accordingly.
docs/static_artifact_publish.md	Updates publishing notes to name the canonical DocC entrypoint as part of the Pages technical entrypoint contract.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: e9c941e891

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".