fix(server): serve docs/index.html at GET / — x402.sentinel.co root was a Cloudflare cache ghost

The deployed server has no root route: GET / returns the JSON 404 and the
HTML page on x402.sentinel.co exists only as a stale Cloudflare edge-cache
copy from 2026-06-13. Same root cause left /llms.txt serving its stub —
docs/ was never bundled into the Docker image.

- index.ts: resolve docs/ once (image layout /app/docs, checkout ../../docs),
  serve docs/index.html at GET / with Cache-Control: public, max-age=300 so
  the edge can never pin a copy for weeks; 301 /index.html -> /; llms.txt
  route now uses the same resolver (fixes the live stub).
- Dockerfile: build from repo-root context and COPY docs ./docs.
- build.yml: context . and rebuild the image on docs/** changes too.

Verified: tsc clean; smoke test on :4920 — GET / 200 text/html (latest docs
fingerprint), GET /?x=1 200, /index.html 301, /llms.txt real content.

Author: Sentinel-Bluebuilder

.github/workflows/build.yml

@@ -5,6 +5,7 @@ on:
     branches: [ "master" ]
     paths:
       - "server/**"
+      - "docs/**"
       - ".github/workflows/build.yml"
   workflow_dispatch:
 
@@ -36,7 +37,8 @@ jobs:
         uses: docker/build-push-action@v6
         with:
           push: true
-          context: ./server
+          # Repo-root context so the image bundles docs/ (served at GET /)
+          context: .
           file: ./server/Dockerfile
           tags: |
             ghcr.io/${{ env.REPO }}:latest

server/Dockerfile

@@ -1,12 +1,14 @@
 # syntax=docker/dockerfile:1.7
+# Build context is the REPO ROOT (see .github/workflows/build.yml) so the
+# image can bundle docs/ — the server serves docs/index.html at GET /.
 
 # ─── Build the server ───
 FROM node:22-alpine AS build
 WORKDIR /app
-COPY package.json package-lock.json* ./
+COPY server/package.json server/package-lock.json* ./
 RUN npm ci --ignore-scripts --no-audit --no-fund --loglevel=error
-COPY tsconfig.json ./
-COPY src ./src
+COPY server/tsconfig.json ./
+COPY server/src ./src
 RUN npm run build \
  && npm prune --omit=dev --ignore-scripts
 
@@ -21,7 +23,8 @@ RUN addgroup -S app && adduser -S app -G app
 
 COPY --from=build /app/node_modules ./node_modules
 COPY --from=build /app/dist         ./dist
-COPY package.json ./
+COPY docs ./docs
+COPY server/package.json ./
 
 USER app
 

server/src/index.ts

@@ -6,7 +6,7 @@ import { createFacilitatorConfig } from '@coinbase/x402';
 import { HTTPFacilitatorClient, type FacilitatorConfig } from '@x402/core/server';
 import { initSentinel, provisionAgent, checkAgentStatus, checkProvisioningCapacity, getEnrichedPlanNodes, matchNodesByCountry } from './sentinel.js';
 import { createSelfHostedFacilitator, startFacilitatorServer } from './facilitator.js';
-import { readFileSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { dirname, join } from 'node:path';
 
@@ -596,18 +596,49 @@ app.get('/health', async (_req, res) => {
   res.json({ status: 'ok', uptime: process.uptime(), capacity });
 });
 
+// ─── Docs (served by this process — x402.sentinel.co has no separate static host) ───
+// docs/ lives at /app/docs in the Docker image (see Dockerfile) and at ../../docs
+// in a repo checkout (__dirname is server/dist or server/src).
+const docsDir = [join(__dirname, '..', 'docs'), join(__dirname, '..', '..', 'docs')]
+  .find(dir => existsSync(join(dir, 'index.html')));
+
+// Human-readable docs page at the root. max-age=300 keeps Cloudflare from
+// pinning a stale copy at the edge for weeks.
+let docsHtmlCache: string | null = null;
+app.get('/', (_req, res) => {
+  if (!docsHtmlCache && docsDir) {
+    try {
+      docsHtmlCache = readFileSync(join(docsDir, 'index.html'), 'utf8');
+    } catch (err) {
+      console.warn('[x402] docs/index.html not readable:', (err as Error).message);
+    }
+  }
+  if (!docsHtmlCache) {
+    return res.json({
+      protocol: 'x402',
+      message: 'Docs page not bundled in this build. See GET /manifest for the machine-readable spec.',
+      docs: '/manifest',
+    });
+  }
+  res.set('Cache-Control', 'public, max-age=300').type('html').send(docsHtmlCache);
+});
+
+app.get('/index.html', (_req, res) => res.redirect(301, '/'));
+
 // llms.txt — AI-readable summary (https://llmstxt.org convention)
 let llmsTxtCache: string | null = null;
 app.get('/llms.txt', (_req, res) => {
-  if (!llmsTxtCache) {
+  if (!llmsTxtCache && docsDir) {
     try {
-      llmsTxtCache = readFileSync(join(__dirname, '..', '..', 'docs', 'llms.txt'), 'utf8');
+      llmsTxtCache = readFileSync(join(docsDir, 'llms.txt'), 'utf8');
     } catch (err) {
       console.warn('[x402] docs/llms.txt not readable, serving stub:', (err as Error).message);
-      llmsTxtCache = '# x402\n\nSee /manifest for the machine-readable spec.\n';
     }
   }
-  res.type('text/plain').send(llmsTxtCache);
+  if (!llmsTxtCache) {
+    llmsTxtCache = '# x402\n\nSee /manifest for the machine-readable spec.\n';
+  }
+  res.set('Cache-Control', 'public, max-age=300').type('text/plain').send(llmsTxtCache);
 });
 
 // Node list — free, enriched with live geo data from each node's /status
@@ -715,6 +746,7 @@ async function start() {
   console.log('    POST /vpn/connect/30days  $1.00');
   console.log('');
   console.log('  Free Endpoints:');
+  console.log('    GET  /                     (docs page)');
   console.log('    GET  /manifest             (AI-readable JSON spec)');
   console.log('    GET  /llms.txt             (AI-readable summary)');
   console.log('    GET  /pricing');