Add source-controlled Worker deploys and publishing governance

.github/workflows/adr-governance.yml

@@ -0,0 +1,34 @@
+name: ADR Governance
+
+on:
+  pull_request:
+    paths:
+      - "docs/adr/**"
+      - ".adr-kit.yaml"
+      - "scripts/adr-governance.py"
+      - ".github/workflows/adr-governance.yml"
+  push:
+    branches:
+      - main
+    paths:
+      - "docs/adr/**"
+      - ".adr-kit.yaml"
+      - "scripts/adr-governance.py"
+      - ".github/workflows/adr-governance.yml"
+
+permissions:
+  contents: read
+
+jobs:
+  adr-governance:
+    name: Check ADR governance
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Check ADR governance
+        run: python3 scripts/adr-governance.py

.github/workflows/deploy-worker-preview.yml

@@ -0,0 +1,44 @@
+name: Deploy Worker Preview
+
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: deploy-worker-preview
+  cancel-in-progress: false
+
+jobs:
+  deploy-preview:
+    name: Deploy preview Worker
+    runs-on: ubuntu-latest
+    if: github.ref == 'refs/heads/main'
+    environment: production
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+          cache-dependency-path: worker/package-lock.json
+
+      - name: Install dependencies
+        working-directory: worker
+        run: npm ci
+
+      - name: Validate preview config
+        working-directory: worker
+        run: npm run assert:preview
+
+      - name: Deploy preview Worker
+        working-directory: worker
+        env:
+          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+        run: npm run deploy:preview

.github/workflows/deploy-worker-production.yml

@@ -0,0 +1,44 @@
+name: Deploy Worker Production
+
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: deploy-worker-production
+  cancel-in-progress: false
+
+jobs:
+  deploy-production:
+    name: Deploy production Worker
+    runs-on: ubuntu-latest
+    if: github.ref == 'refs/heads/main'
+    environment: production
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+          cache-dependency-path: worker/package-lock.json
+
+      - name: Install dependencies
+        working-directory: worker
+        run: npm ci
+
+      - name: Validate production config
+        working-directory: worker
+        run: npm run assert:production
+
+      - name: Deploy production Worker
+        working-directory: worker
+        env:
+          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+        run: npm run deploy:production

.github/workflows/worker-check.yml

@@ -0,0 +1,44 @@
+name: Worker Check
+
+on:
+  pull_request:
+    paths:
+      - "worker/**"
+      - ".github/workflows/worker-check.yml"
+      - ".github/workflows/deploy-worker-preview.yml"
+      - ".github/workflows/deploy-worker-production.yml"
+  push:
+    branches:
+      - main
+    paths:
+      - "worker/**"
+      - ".github/workflows/worker-check.yml"
+      - ".github/workflows/deploy-worker-preview.yml"
+      - ".github/workflows/deploy-worker-production.yml"
+
+permissions:
+  contents: read
+
+jobs:
+  check:
+    name: Check worker
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+          cache-dependency-path: worker/package-lock.json
+
+      - name: Install dependencies
+        working-directory: worker
+        run: npm ci
+
+      - name: Check worker
+        working-directory: worker
+        run: npm run check

README.md

@@ -9,6 +9,7 @@ This repository contains:
 - **llms.txt** - Main index file following the [llms.txt standard](https://llmstxt.org/)
 - **Markdown documentation** - Clean, comprehensive content about Autonomi's architecture, features, and developer experience
 - **Page variants** - `.md` versions of key autonomi.com pages for AI consumption
+- **Cloudflare Worker config** - Source-controlled Worker code/config in [`worker/`](worker/README.markdown), with manual deployment workflows documented in the Worker runbook
 
 ## How It Works
 
@@ -20,6 +21,123 @@ Files appear to live on autonomi.com but are actually served from this GitHub re
 - Single source of truth
 - Clean content without HTML wrappers
 
+## Public Serving Policy
+
+The Cloudflare Worker serves `.md`, `/llms.txt`, and `/llms-full.txt` from this repo at canonical `autonomi.com` URLs, except for internal repository prefixes.
+
+Public by default:
+
+- `.md` files outside internal prefixes
+- `/llms.txt`
+- `/llms-full.txt`
+
+Internal prefixes not served from GitHub raw content:
+
+- `/worker/`
+- `/.github/`
+
+To publish machine-readable content, add a `.md` file outside the internal prefixes. To keep operational or repository-internal documentation out of canonical `autonomi.com` serving, place it under an internal prefix or use a non-served extension. See ADR-0006 for the decision record.
+
+## Publishing and Managing Content
+
+This repo is for machine-readable, LLM-parsable, AI-optimised content served from the `autonomi.com` domain.
+
+It provides Markdown/plain-text versions of key `autonomi.com` pages, and any other content the team wants available at stable `autonomi.com` URLs. These files are maintained in GitHub in parallel with the human-readable HTML pages managed in Framer.
+
+For pages that have a Markdown counterpart in this repo, the `.md` URL is the LLM-friendly version of the page. For example, a human-facing page on `autonomi.com` can have a Markdown counterpart such as `https://autonomi.com/overview.md` when `overview.md` exists in this repository.
+
+This repo also provides:
+
+- `llms.txt`: a concise index for AI assistants and crawlers
+- `llms-full.txt`: a fuller context file for AI assistants that want more inline detail
+- Markdown versions of selected public pages and reference material
+- foundational whitepapers in both Markdown and PDF form
+- source-controlled Worker code/config for serving the content at `autonomi.com`
+
+For a normal content update:
+
+1. Edit the existing public content file, or add a new public `.md` file outside internal prefixes.
+2. Update `llms.txt` so it includes every public content URL that should be discoverable.
+3. Update `llms-full.txt` so it reflects the current public content set and messaging.
+4. Open a PR.
+5. Review the Markdown and the final `autonomi.com` URL it will map to.
+6. Merge the PR to `main`.
+7. Check the live URL after merge if needed.
+
+After a content PR is merged to `main`, the Cloudflare Worker serves the updated content automatically from GitHub raw content. There is usually no separate deployment step for content-only changes. Served documentation responses use `Cache-Control: public, max-age=300`, so changes may take up to about five minutes to appear at `autonomi.com`.
+
+When public content is added, removed, renamed, or substantially changed:
+
+- add new public URLs to `llms.txt`
+- remove deleted public URLs from `llms.txt`
+- update `llms-full.txt` to match the current content and messaging
+- check whether the content should be linked from an existing section or whether a new section is needed
+- keep URLs stable where possible, because agents and external tools may cache or reference them
+
+Public content is served when it matches one of these rules:
+
+- `.md` files outside internal prefixes
+- `/llms.txt`
+- `/llms-full.txt`
+
+Examples:
+
+- `overview.md` is served at `https://autonomi.com/overview.md`
+- `whitepapers/autonomous-network.md` is served at `https://autonomi.com/whitepapers/autonomous-network.md`
+- `llms.txt` is served at `https://autonomi.com/llms.txt`
+- `llms-full.txt` is served at `https://autonomi.com/llms-full.txt`
+
+### Whitepapers
+
+Foundational whitepapers are kept in two forms:
+
+- Markdown versions for LLM-readable content served from `autonomi.com`
+- PDF versions for stable, shareable, human-readable original documents
+
+When adding or updating a whitepaper:
+
+1. Keep the Markdown version under `whitepapers/`.
+2. Keep the corresponding PDF in the same directory when a PDF counterpart exists.
+3. For whitepapers that have a PDF counterpart, link from the Markdown page to the PDF using an explicit GitHub raw URL.
+4. Add or update the Markdown URL in `llms.txt`.
+5. Update `llms-full.txt` so the whitepaper set and summary remain current.
+
+The Worker does not currently serve `.pdf` files from `autonomi.com`. Whitepaper PDF links should use explicit GitHub raw URLs, for example:
+
+`https://raw.githubusercontent.com/maidsafe/autonomi-llm-docs/main/whitepapers/Autonomous-Network.pdf`
+
+Do not use relative PDF links such as `Autonomous-Network.pdf` from a served Markdown page, because that would resolve against `autonomi.com` and fall through to Framer rather than serving the file from this repo.
+
+Under the current policy, any `.md` file outside internal prefixes can be served from `autonomi.com`. This includes repo-level and governance Markdown such as `README.md` and `docs/adr/*.md`; those files are intentionally visible as public repository context.
+
+Operational or maintenance material that should not be published as canonical Autonomi documentation should live under an internal prefix, or use a non-served extension such as `.markdown`.
+
+Internal prefixes not served from GitHub raw content:
+
+- `/worker/`
+- `/.github/`
+
+Use internal locations for:
+
+- Worker source and runbooks
+- GitHub workflow files or workflow documentation
+- repository-maintenance notes
+- operational material that is useful in GitHub but should not appear as public `autonomi.com` documentation
+
+Changing content is different from changing serving behaviour.
+
+Content-only changes normally need only a PR merge. Worker or serving-policy changes need additional review and, after merge, a manual Worker deployment. Treat these as serving changes:
+
+- editing `worker/src/index.js`
+- changing Wrangler config
+- changing deploy workflows
+- adding new public file types beyond `.md`, `/llms.txt`, or `/llms-full.txt`
+- serving PDFs from `autonomi.com` instead of GitHub raw URLs
+- changing internal prefixes or routing policy
+- changing cache behaviour or response headers
+
+Serving-policy changes should be reflected in Worker tests and checked against ADR-0006. PDF-linking behaviour is documented in ADR-0004 and should be revisited if the Worker is changed to serve PDFs directly from `autonomi.com`.
+
 ## Who This Is For
 
 **Primary audience:** AI assistants (Claude, ChatGPT, etc.) helping developers build on Autonomi

docs/adr/ADR-0001-adopt-architecture-decision-records.md

@@ -1,6 +1,6 @@
 # ADR-0001: Adopt Architecture Decision Records
 
-- **Status:** Proposed
+- **Status:** Accepted
 - **Date:** 2026-06-24
 - **Decision owners:** Jim Collinson
 - **Reviewers:** Jim Collinson

docs/adr/ADR-0002-serve-docs-via-cloudflare-worker-and-github.md

@@ -1,14 +1,14 @@
 # ADR-0002: Serve documentation at autonomi.com via a Cloudflare Worker backed by GitHub
 
-- **Status:** Proposed
+- **Status:** Accepted
 - **Date:** 2026-06-24
 - **Decision owners:** Jim Collinson
 - **Reviewers:** Jim Collinson (retrospective — author attestation)
 - **Supersedes:** none
 - **Superseded by:** none
-- **Related:** ADR-0001 (ADR adoption); ADR-0003 (`llms.txt`); ADR-0004 (PDF serving); planned ADR-0005 (bring Worker source under version control)
+- **Related:** ADR-0001 (ADR adoption); ADR-0003 (`llms.txt`); ADR-0004 (PDF serving); ADR-0005 (Worker source management)
 
-> **Retrospective ADR.** This record reconstructs a decision made earlier in development, before the ADR process existed in this repo. It is backfilled and proposed on 2026-06-24 (accepted on merge of this PR), on the basis of the decision owner's attestation and direct inspection of the deployed system; it was not produced by contemporaneous review.
+> **Retrospective ADR.** This record reconstructs a decision made earlier in development, before the ADR process existed in this repo. It was backfilled on 2026-06-24 and accepted by the decision owner during PR #6 review, on the basis of the decision owner's attestation and direct inspection of the deployed system; it was not produced by contemporaneous review.
 
 ## Context
 
@@ -47,9 +47,11 @@ If the GitHub fetch for a matched path does **not** return OK (e.g. the file doe
 
 For interception to work, the relevant `autonomi.com` DNS records must be **Proxied** (orange-cloud) in Cloudflare rather than DNS-only (grey-cloud), so traffic passes through Cloudflare where the Worker can act on it. DNS-only records bypass the Worker entirely and were the cause of early interception failures during development.
 
-### Current management state (as of this record)
+### Management state and later refinement
 
-The Worker source is currently authored and edited **only via the Cloudflare web UI**; it is not yet committed to or managed from any Git repository. The source reproduced in discussion is a copy, not a tracked artefact — the deployed Worker is whatever exists in the Cloudflare dashboard. Bringing the Worker under version control in this repo (with the Cloudflare UI demoted to a break-glass fallback) is planned as separate work and will be recorded in its own ADR (ADR-0005). This ADR documents the serving architecture as currently deployed; it does not decide the management approach.
+At the time this architecture was first deployed, the Worker source was authored and edited only via the Cloudflare web UI. This ADR records the serving architecture: a Cloudflare Worker in front of `autonomi.com`, GitHub raw content for machine-readable documentation, and Framer fallthrough for normal site traffic.
+
+Worker source management was decided separately in ADR-0005. ADR-0005 makes this repository the source of truth for Worker source code, Wrangler configuration, deployment workflows, and the operational runbook, with the Cloudflare dashboard reserved for observability, rollback, and break-glass recovery.
 
 ## Consequences
 
@@ -68,7 +70,7 @@ The Worker source is currently authored and edited **only via the Cloudflare web
 - The Worker's routing logic (which paths it intercepts) is an architectural surface that must be kept correct; a mistake can shadow or leak Framer routes.
 - DNS proxy status is load-bearing: flipping a record to DNS-only silently breaks doc serving.
 - Two sources of truth for one domain (Framer + GitHub) can confuse contributors who don't know the split.
-- **The Worker source is currently unversioned and Cloudflare-UI-only**: no history, no review, no rollback except by hand, and a single point of accidental change. This risk is the motivation for the planned ADR-0005.
+- At initial deployment, Worker source was unversioned and Cloudflare-UI-only. ADR-0005 addresses this by moving normal Worker source/config/deploy management into this repository while keeping Cloudflare available for observability, rollback, and break-glass recovery.
 
 ### Neutral / Operational
 
@@ -82,7 +84,7 @@ The Worker source is currently authored and edited **only via the Cloudflare web
 - `autonomi.com/llms.txt` and `autonomi.com/llms-full.txt` resolve to repo content.
 - Normal site pages still resolve to Framer.
 - Required `autonomi.com` records are Proxied in Cloudflare (owner-confirmed; not inspectable from the repo).
-- Review trigger: any change to the Worker's routing rules, the hosting of the marketing site, the DNS proxy posture, or the move of the Worker under version control (ADR-0005) requires revisiting this ADR.
+- Review trigger: any change to the Worker's routing rules, the hosting of the marketing site, the DNS proxy posture, or the Worker source-management model (ADR-0005) requires revisiting this ADR.
 
 ## Notes for AI-assisted work
 

worker/.gitignore

@@ -0,0 +1,3 @@
+node_modules/
+.wrangler/
+.dev.vars

worker/.prettierignore

@@ -0,0 +1,2 @@
+node_modules/
+package-lock.json