Improve technical guides and repair plain docs

package.json

@@ -18,7 +18,7 @@
   "dependencies": {
     "astro": "^7.1.6",
     "posthog-js": "^1.372.3",
-    "puppeteer": "^24.39.0",
+    "puppeteer": "^25.9.0",
     "sharp": "^0.35.3"
   }
 }

public/.well-known/integrations.json

@@ -0,0 +1,46 @@
+{
+  "version": 3,
+  "summary": "Pilot Protocol is an open-source overlay network for AI agents. Integration surfaces: the pilotctl CLI (daemon, messaging, file transfer, app store), a Model Context Protocol server (pilot-mcp, run locally or self-hosted), and SDKs for Go, Python, Node, and Swift. The network is deny-by-default: bilateral trust or explicit network membership is required before traffic flows. Agent-readable docs at /llms.txt; agent skill manifest at /SKILLS.md.",
+  "surfaces": [
+    {
+      "slug": "pilot-mcp-server",
+      "name": "pilot-mcp — Pilot Protocol MCP server",
+      "type": "mcp",
+      "url": "https://github.com/pilot-protocol/pilot-mcp",
+      "transports": ["stdio", "streamable-http"],
+      "notes": "Runs locally beside the Pilot daemon or self-hosted over SSH/HTTP; there is no Pilot-operated public MCP endpoint. Exposes agent messaging, peer discovery, trust management, and file transfer as MCP tools.",
+      "basis": {
+        "via": "declared",
+        "source": "https://pilotprotocol.network/.well-known/integrations.json"
+      },
+      "auth": {
+        "status": "none",
+        "notes": "No API key or account. Requires a running local Pilot daemon; network access is governed by Pilot's bilateral trust model, not credentials.",
+        "basis": {
+          "via": "declared",
+          "source": "https://pilotprotocol.network/.well-known/integrations.json"
+        }
+      }
+    },
+    {
+      "slug": "pilotctl-cli",
+      "name": "pilotctl — Pilot Protocol CLI",
+      "type": "cli",
+      "url": "https://pilotprotocol.network/docs/cli-reference",
+      "install": "curl -fsSL https://pilotprotocol.network/install.sh | sh",
+      "notes": "Statically linked Go CLI and daemon. Covers daemon lifecycle, agent-to-agent messaging, peer discovery, trust, file transfer, and the agent app store (`pilotctl appstore catalogue|install|call`).",
+      "basis": {
+        "via": "declared",
+        "source": "https://pilotprotocol.network/.well-known/integrations.json"
+      },
+      "auth": {
+        "status": "none",
+        "notes": "No signup or API key to install and join the network. Peer traffic requires bilateral trust or explicit network membership (deny by default).",
+        "basis": {
+          "via": "declared",
+          "source": "https://pilotprotocol.network/.well-known/integrations.json"
+        }
+      }
+    }
+  ]
+}

public/agents.txt

@@ -0,0 +1,12 @@
+# agents.txt
+# Agent-readable entry points for Pilot Protocol, an open-source
+# network layer for AI agents:
+# permanent virtual addresses, encrypted UDP tunnels, NAT traversal,
+# deny-by-default peer trust, and an app store of agent-native tools.
+
+Docs: https://pilotprotocol.network/llms.txt
+MCP: https://github.com/pilot-protocol/pilot-mcp
+Skills: https://pilotprotocol.network/SKILLS.md
+CLI: https://pilotprotocol.network/docs/cli-reference
+Install: https://pilotprotocol.network/install.sh
+Integrations: https://pilotprotocol.network/.well-known/integrations.json

scripts/regen-plain.mjs

@@ -132,6 +132,11 @@ async function loadDocManifest() {
     const source = `src/pages/docs/${file}`;
     const dest = `src/pages/plain/docs/${file}`;
     const full = await readFile(join(REPO_ROOT, source), 'utf8');
+    // Managed documentation renders from src/data/managedDocs.ts on both the
+    // human and plain routes. Feeding the thin route wrapper to the prose
+    // generator loses the authoritative content and produces placeholders.
+    // Its plain wrapper is intentionally unstamped and data-driven.
+    if (full.includes("from '../../data/managedDocs'")) continue;
     const meta = readDocMeta(full);
     const isIndex = slugPart === 'index';
     const canonical = isIndex

src/components/ManagedPlainDoc.astro

@@ -0,0 +1,20 @@
+---
+import PlainLayout from '../layouts/PlainLayout.astro';
+import { managedDocs } from '../data/managedDocs';
+
+interface Props {
+  slug: string;
+}
+
+const { slug } = Astro.props;
+const doc = managedDocs[slug];
+if (!doc) throw new Error(`Unknown managed documentation slug: ${slug}`);
+---
+<PlainLayout
+  title={`${doc.title} — Pilot Protocol (plain)`}
+  description={doc.description}
+  canonical={`https://pilotprotocol.network/plain/docs/${slug}/`}
+>
+  <p><a href="/plain/docs/">&larr; Docs index</a></p>
+  <Fragment set:html={doc.body} />
+</PlainLayout>

src/data/learnGuides.ts

@@ -24,6 +24,14 @@ export const learnGuides: LearnGuide[] = [
     isoDate: '2026-07-22',
     track: 'Foundations',
   },
+  {
+    slug: 'grounding-ai-agents-web-search-retrieval',
+    title: 'Grounding AI Agents with Web Search',
+    description: 'Design a retrieval loop that reads full sources, preserves provenance, verifies consequential claims, and treats retrieved text as untrusted input.',
+    date: 'August 2, 2026',
+    isoDate: '2026-08-02',
+    track: 'Foundations',
+  },
   {
     slug: 'ai-in-networking-for-multicloud',
     title: 'AI Networking Across Multiple Clouds',
@@ -56,6 +64,14 @@ export const learnGuides: LearnGuide[] = [
     isoDate: '2026-07-25',
     track: 'Transport',
   },
+  {
+    slug: 'webhooks-sse-streaming-long-running-jobs',
+    title: 'Webhooks and SSE for Long-Running Jobs',
+    description: 'Compare callbacks, event streams, polling, fan-in, retries, and stable agent delivery without promising connection permanence.',
+    date: 'August 20, 2026',
+    isoDate: '2026-08-20',
+    track: 'Transport',
+  },
   {
     slug: 'how-are-network-agent-tokens-different',
     title: 'How Network Agent Tokens Differ',