0al-spec · SoundBlaster · Apr 27, 2026 · Apr 27, 2026 · Apr 27, 2026
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -0,0 +1,106 @@
+name: Deploy DocC Documentation
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - "Package.swift"
+      - "Package.resolved"
+      - "Makefile"
+      - "Sources/SpecNode/**"
+      - "Sources/SpecNode-docs/**"
+      - "README.md"
+      - "CONSTITUTION.md"
+      - "docs/**"
+      - "specs/**"
+      - ".github/workflows/docs.yml"
+  pull_request:
+    branches:
+      - main
+    paths:
+      - "Package.swift"
+      - "Package.resolved"
+      - "Makefile"
+      - "Sources/SpecNode/**"
+      - "Sources/SpecNode-docs/**"
+      - "README.md"
+      - "CONSTITUTION.md"
+      - "docs/**"
+      - "specs/**"
+      - ".github/workflows/docs.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: macos-14
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Xcode
+        uses: maxim-lobanov/setup-xcode@v1
+        with:
+          xcode-version: latest-stable
+
+      - name: Build Documentation
+        run: |
+          swift package --allow-writing-to-directory ./.docc-build \
+            generate-documentation \
+            --target SpecNode \
+            --output-path ./.docc-build \
+            --transform-for-static-hosting \
+            --hosting-base-path SpecNode
+
+      - name: Add .nojekyll and index.html redirect
+        run: |
+          touch .docc-build/.nojekyll
+          cat > .docc-build/index.html << 'EOF'
+          <!DOCTYPE html>
+          <html>
+          <head>
+            <meta charset="utf-8">
+            <title>Redirecting to SpecNode Documentation</title>
+            <meta http-equiv="refresh" content="0; url=./documentation/specnode/">
+            <link rel="canonical" href="./documentation/specnode/">
+          </head>
+          <body>
+            <p>Redirecting to <a href="./documentation/specnode/">SpecNode Documentation</a>...</p>
+            <script>
+              window.location.href = "./documentation/specnode/";
+            </script>
+          </body>
+          </html>
+          EOF
+
+      - name: Upload artifact
+        if: github.event_name == 'push'
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: "./.docc-build"
+
+  deploy:
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    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
diff --git a/.gitignore b/.gitignore
@@ -27,7 +27,9 @@ pnpm-debug.log*
 yarn-debug.log*
 
 # Build artifacts
+.build/
 build/
 dist/
 target/
 coverage/
+.docc-build/
diff --git a/Makefile b/Makefile
@@ -0,0 +1,9 @@
+.PHONY: docs-build
+
+docs-build:
+	swift package --allow-writing-to-directory ./.docc-build \
+		generate-documentation \
+		--target SpecNode \
+		--output-path ./.docc-build \
+		--transform-for-static-hosting \
+		--hosting-base-path SpecNode
diff --git a/Package.resolved b/Package.resolved
diff --git a/Package.swift b/Package.swift
@@ -0,0 +1,34 @@
+// swift-tools-version:5.9
+// This package exists only to generate DocC documentation for the SpecNode
+// specification repository. The runtime implementation will live under src.
+
+import PackageDescription
+
+let package = Package(
+    name: "SpecNode",
+    products: [
+        .library(
+            name: "SpecNode",
+            targets: ["SpecNode"]
+        ),
+        .executable(
+            name: "SpecNode-docs",
+            targets: ["SpecNode-docs"]
+        ),
+    ],
+    dependencies: [
+        .package(url: "https://github.com/apple/swift-docc-plugin", from: "1.0.0"),
+    ],
+    targets: [
+        .target(
+            name: "SpecNode",
+            path: "Sources/SpecNode",
+            exclude: []
+        ),
+        .executableTarget(
+            name: "SpecNode-docs",
+            path: "Sources/SpecNode-docs",
+            exclude: []
+        ),
+    ]
+)
diff --git a/README.md b/README.md
@@ -18,6 +18,20 @@ The first implementation target is a local CLI or daemon that connects to a
 SpecGraph/SpecPM control plane through an outbound job channel and executes a
 small allowlisted set of typed jobs.
 
+## Documentation
+
+DocC documentation is published through GitHub Pages at:
+
+```text
+https://0al-spec.github.io/SpecNode/
+```
+
+Build the static documentation locally:
+
+```bash
+make docs-build
+```
+
 ## Core Idea
 
 ```text
@@ -67,6 +81,7 @@ specnode specpm validate ./dist/spec-package.yaml
 ## Repository Layout
 
 ```text
+specpm.yaml          SpecPM package manifest for SpecNode itself.
 docs/
   proposals/          Product and architecture proposals.
 specs/                Protocol, security, and artifact contracts.

diff --git a/Sources/SpecNode-docs/main.swift b/Sources/SpecNode-docs/main.swift
@@ -0,0 +1,5 @@
+// Documentation generator entry point.
+// This executable exists to satisfy Swift Package requirements for DocC.
+
+print("SpecNode documentation generator")
+print("See the documentation at: https://0al-spec.github.io/SpecNode")
diff --git a/Sources/SpecNode/Documentation.docc/GettingStarted.md b/Sources/SpecNode/Documentation.docc/GettingStarted.md
@@ -0,0 +1,57 @@
+# Getting Started
+
+SpecNode does not have an installable runtime yet. The repository currently
+defines the protocol, security posture, provenance model, and MVP execution
+shape for a future local node.
+
+## Build Documentation
+
+Build the DocC documentation locally:
+
+```bash
+make docs-build
+```
+
+The documentation build writes static output to `.docc-build/`.
+
+## Target Runtime Shape
+
+The expected CLI shape remains a design target:
+
+```bash
+specnode connect --code 8K4P-X2Q9
+specnode providers list
+specnode test --model qwen3:4b
+specnode specpm build --repo . --model qwen3:4b
+specnode specpm validate ./dist/spec-package.yaml
+```
+
+The first executable slice should prove one local SpecGraph extraction job and
+one SpecPM package-build job through a local provider.
+
+## Useful Paths
+
+- Product and architecture proposals: `docs/proposals/`
+- Protocol and security contracts: `specs/`
+- Runtime implementation, once selected: `src/`
+- Conformance and regression tests, once runtime exists: `tests/`
+- Developer or validation tooling: `tools/`
+
+## Quality Gates
+
+Use repository validation before opening or merging changes:
+
+```bash
+git diff --check
+make docs-build
+```
+
+Runtime changes should add focused tests for the behavior being introduced.
+Security-sensitive changes should name the trust boundary and at least one
+negative case or abuse scenario.
+
+## Next Topics
+
+- <doc:JobProtocol>
+- <doc:SecurityModel>
+- <doc:ProvenanceReceipts>
diff --git a/Sources/SpecNode/Documentation.docc/JobProtocol.md b/Sources/SpecNode/Documentation.docc/JobProtocol.md
@@ -0,0 +1,112 @@
+# Job Protocol
+
+SpecNode jobs are typed protocol messages exchanged between a SpecGraph or
+SpecPM control plane and a local node.
+
+## Goals
+
+The job protocol must:
+
+- keep remote work bounded and auditable;
+- avoid arbitrary prompt execution;
+- make policy explicit per job;
+- require output schema validation;
+- leave room for signed receipts and Agent Passport identity.
+
+## Pairing
+
+Pairing starts in the web service and completes from the local node. The node
+registers its runtime, providers, capabilities, and limits.
+
+```json
+{
+  "node_name": "Egor MacBook Pro",
+  "runtime": {
+    "os": "macOS",
+    "arch": "arm64",
+    "specnode_version": "0.1.0"
+  },
+  "providers": [
+    {
+      "kind": "ollama",
+      "base_url_kind": "localhost",
+      "models": ["qwen3:4b", "llama3.2:3b"]
+    }
+  ],
+  "capabilities": [
+    "repo.scan",
+    "repo.chunk",
+    "llm.chat",
+    "specgraph.extract",
+    "specgraph.build",
+    "specpm.package"
+  ],
+  "limits": {
+    "max_concurrent_jobs": 1,
+    "max_repo_size_mb": 500,
+    "max_job_duration_ms": 900000
+  }
+}
+```
+
+## Job Envelope
+
+A job describes the repository input, task type, policy, and output schema.
+Policy must be checked before execution.
+
+```json
+{
+  "job_id": "job_01H00000000000000000000000",
+  "service": "specgraph",
+  "type": "specgraph.extract_module_intent",
+  "repo": {
+    "source": "remote",
+    "url": "https://github.com/org/project",
+    "commit": "8f3a1c0d2e4f67890123456789abcdef01234567"
+  },
+  "policy": {
+    "allow_network": false,
+    "allow_shell": false,
+    "allow_filesystem_outside_workspace": false,
+    "allow_llm_tools": false,
+    "max_input_tokens": 12000,
+    "max_output_tokens": 1200,
+    "timeout_ms": 60000
+  }
+}
+```
+
+## Rejection Cases
+
+The node may reject a job before execution if:
+
+- the job type is not allowlisted;
+- the policy exceeds local limits;
+- the requested provider or model is unavailable;
+- the repository size exceeds local policy;
+- the output schema is missing or invalid.
+
+## Initial Job Types
+
+SpecGraph jobs:
+
+- `specgraph.extract_file_summary`
+- `specgraph.extract_module_intent`
+- `specgraph.extract_capabilities`
+- `specgraph.build_graph_fragment`
+
+SpecPM jobs:
+
+- `specpm.inspect_repo`
+- `specpm.extract_package_metadata`
+- `specpm.build_package_manifest`
+- `specpm.generate_conformance_hints`
+
+## Source
+
+The canonical contract is `specs/JOB_PROTOCOL.md`.
+
+## Next Topics
+
+- <doc:SecurityModel>
+- <doc:ProvenanceReceipts>