From 7c79e54517462dea7ae7039252908435ceedfedb Mon Sep 17 00:00:00 2001
From: Ola Adebayo <olamideadebayo2001@gmail.com>
Date: Fri, 11 Sep 2026 14:09:05 +0100
Subject: [PATCH 1/2] feat(docs): add agent playbook and plain-text Markdown
 mirrors
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Make the documentation ingestible by AI agents.

Every page now has a plain-text Markdown mirror at the same path with a
`.md` suffix — previously a 404. `src/lib/to-markdown.ts` converts MDX to
clean Markdown rather than serving raw source: imports are dropped,
`<Aside>` becomes a blockquote, `<TabItem>`/`<Card>` become bold labels
with dedented bodies, `<LinkCard>` becomes a list item, and
`<Tabs>`/`<Steps>`/`<FileTree>` are unwrapped. The transform is
code-fence aware so pages documenting JSX pass through untouched.

Adds three entry points for agents:

- `/agents.md` — a single-page integration playbook: decision tree,
  install matrix, recipes for SPA migration, Docker (both modes),
  Kubernetes and local dev, the client API with its behavioural
  contracts, gateway reference, and common failure modes.
- `/llms.txt` — indexed by sidebar section, linking to `.md` URLs.
- `/llms-full.txt` — the full documentation set as one file.

Cloudflare Pages serves `.md` as `text/markdown`, which browsers
download instead of render. Pages splat patterns match greedily and a
`/*.md` suffix pattern is not documented as supported, so
`src/integrations/md-headers.mjs` enumerates the rules explicitly from
the build output (49 of a 100-rule limit, with a warning if that is
approached). `public/_headers` is now generated rather than maintained
by hand.

The sidebar moves to `src/sidebar.mjs` so Starlight and the `/llms.txt`
route share one ordering, and a Starlight `Head` override advertises
each page's mirror via `<link rel="alternate" type="text/markdown">`.

Also syncs the stale published copy of the manifest JSON schema.
---
 README.md                                   |  15 +-
 docs/astro.config.mjs                       | 126 +------
 docs/public/schema/rep-manifest.schema.json |   4 +-
 docs/src/components/Head.astro              |  20 +
 docs/src/content/docs/agents.mdx            | 399 ++++++++++++++++++++
 docs/src/integrations/md-headers.mjs        |  56 +++
 docs/src/lib/to-markdown.ts                 | 171 +++++++++
 docs/src/pages/[...slug].md.ts              |  19 +
 docs/src/pages/llms-full.txt.ts             |  38 ++
 docs/src/pages/llms.txt.ts                  |  64 ++++
 docs/src/sidebar.mjs                        | 123 ++++++
 docs/src/site.mjs                           |   2 +
 12 files changed, 917 insertions(+), 120 deletions(-)
 create mode 100644 docs/src/components/Head.astro
 create mode 100644 docs/src/content/docs/agents.mdx
 create mode 100644 docs/src/integrations/md-headers.mjs
 create mode 100644 docs/src/lib/to-markdown.ts
 create mode 100644 docs/src/pages/[...slug].md.ts
 create mode 100644 docs/src/pages/llms-full.txt.ts
 create mode 100644 docs/src/pages/llms.txt.ts
 create mode 100644 docs/src/sidebar.mjs
 create mode 100644 docs/src/site.mjs

diff --git a/README.md b/README.md
index 936ae84..15448d5 100644
--- a/README.md
+++ b/README.md
@@ -4,7 +4,7 @@
 
 REP is an open protocol for injecting environment variables into browser apps **at container runtime** — not build time. It gives you security classification, encryption, integrity verification, and hot reload, with zero build-tool coupling.
 
-[Documentation](https://rep-protocol.dev)
+[Documentation](https://rep-protocol.dev) · [AI agent playbook](https://rep-protocol.dev/agents.md) · [llms.txt](https://rep-protocol.dev/llms.txt)
 
 ## Quick Start
 
@@ -306,6 +306,19 @@ REP is a formal, open specification — not just a tool.
 
 ---
 
+## For AI agents
+
+The documentation is published in machine-readable form:
+
+| Resource | What it is |
+|---|---|
+| [`/agents.md`](https://rep-protocol.dev/agents.md) | Single-page integration playbook — decision tree, install matrix, copy-paste recipes for every framework and deployment target, and the mistakes that break a REP setup |
+| [`/llms.txt`](https://rep-protocol.dev/llms.txt) | Index of every documentation page with descriptions |
+| [`/llms-full.txt`](https://rep-protocol.dev/llms-full.txt) | The entire documentation set as one plain-text file |
+| `<any page>.md` | Every page has a plain-text Markdown mirror — e.g. [`/reference/sdk.md`](https://rep-protocol.dev/reference/sdk.md) |
+
+---
+
 ## Contributing
 
 We welcome contributions. See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, commit conventions, and the release process.
diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs
index 63b5588..76bd991 100644
--- a/docs/astro.config.mjs
+++ b/docs/astro.config.mjs
@@ -1,7 +1,10 @@
 import { defineConfig } from 'astro/config';
 import starlight from '@astrojs/starlight';
+import { sidebar } from './src/sidebar.mjs';
+import { markdownHeaders } from './src/integrations/md-headers.mjs';
+import { SITE_URL } from './src/site.mjs';
 
-const siteUrl = 'https://rep-protocol.dev';
+const siteUrl = SITE_URL;
 const ogImagePath = '/og-image.png';
 const ogImageUrl = `${siteUrl}${ogImagePath}`;
 const ogImageAlt =
@@ -127,122 +130,11 @@ export default defineConfig({
           },
         },
       ],
-      sidebar: [
-        {
-          label: 'Getting Started',
-          items: [
-            { label: 'Quick Start', slug: 'quick-start' },
-            { label: 'Installation', slug: 'guides/installation' },
-            { label: 'Local Development', slug: 'guides/development' },
-          ],
-        },
-        {
-          label: 'Core Concepts',
-          items: [
-            { label: 'How REP Works', slug: 'concepts/how-it-works' },
-            {
-              label: 'Variable Classification',
-              slug: 'concepts/variable-classification',
-            },
-            { label: 'Security Model', slug: 'concepts/security-model' },
-            { label: 'Wire Format', slug: 'concepts/wire-format' },
-            { label: 'Hot Reload', slug: 'concepts/hot-reload' },
-          ],
-        },
-        {
-          label: 'Framework Guides',
-          items: [
-            { label: 'React', slug: 'frameworks/react' },
-            { label: 'Vue', slug: 'frameworks/vue' },
-            { label: 'Svelte', slug: 'frameworks/svelte' },
-            { label: 'Angular', slug: 'frameworks/angular' },
-            { label: 'Vanilla JS', slug: 'frameworks/vanilla' },
-          ],
-        },
-        {
-          label: 'Guides',
-          items: [
-            { label: 'Manifest File', slug: 'guides/manifest' },
-            { label: 'Testing', slug: 'guides/testing' },
-            {
-              label: 'Migration',
-              items: [
-                { label: 'Overview', slug: 'guides/migration/overview' },
-                { label: 'From Vite', slug: 'guides/migration/from-vite' },
-                {
-                  label: 'From Create React App',
-                  slug: 'guides/migration/from-cra',
-                },
-                { label: 'From Next.js', slug: 'guides/migration/from-next' },
-              ],
-            },
-          ],
-        },
-        {
-          label: 'Deployment',
-          items: [
-            { label: 'Docker — Proxy Mode', slug: 'deployment/docker-proxy' },
-            {
-              label: 'Docker — Embedded Mode',
-              slug: 'deployment/docker-embedded',
-            },
-            { label: 'Kubernetes', slug: 'deployment/kubernetes' },
-            { label: 'Docker Compose', slug: 'deployment/docker-compose' },
-            { label: 'CI/CD Pipeline', slug: 'deployment/ci-cd' },
-          ],
-        },
-        {
-          label: 'Examples',
-          items: [
-            { label: 'Todo App (React)', slug: 'examples/todo-react' },
-            { label: 'Simple HTML (ESM.sh)', slug: 'examples/simple-html' },
-            { label: 'Next.js — Proxy Mode', slug: 'examples/nextjs-proxy' },
-            {
-              label: 'Next.js CSR + Kubernetes',
-              slug: 'examples/nextjs-csr-embedded',
-            },
-          ],
-        },
-        {
-          label: 'Reference',
-          items: [
-            { label: 'SDK API', slug: 'reference/sdk' },
-            { label: 'Gateway Flags', slug: 'reference/gateway-flags' },
-            {
-              label: 'Gateway Endpoints',
-              slug: 'reference/gateway-endpoints',
-            },
-            { label: 'Manifest Schema', slug: 'reference/manifest-schema' },
-            { label: 'CLI Commands', slug: 'reference/cli' },
-            {
-              label: 'Adapter APIs',
-              items: [
-                { label: 'React', slug: 'reference/adapters/react' },
-                { label: 'Vue', slug: 'reference/adapters/vue' },
-                { label: 'Svelte', slug: 'reference/adapters/svelte' },
-              ],
-            },
-            {
-              label: 'Build-Tool Plugins',
-              items: [
-                { label: 'Vite', slug: 'reference/plugins/vite' },
-                { label: 'Next.js', slug: 'reference/plugins/next' },
-              ],
-            },
-            { label: 'Codemod', slug: 'reference/codemod' },
-          ],
-        },
-        {
-          label: 'Specification',
-          items: [
-            { label: 'Overview', slug: 'spec' },
-            { label: 'REP-RFC-0001', slug: 'spec/rfc-0001' },
-            { label: 'Security Model', slug: 'spec/security-model' },
-            { label: 'Conformance', slug: 'spec/conformance' },
-          ],
-        },
-        { label: 'Contributing', slug: 'contributing' },
-      ],
+      sidebar,
+      components: {
+        Head: './src/components/Head.astro',
+      },
     }),
+    markdownHeaders({ extraPaths: ['/llms.txt', '/llms-full.txt'] }),
   ],
 });
diff --git a/docs/public/schema/rep-manifest.schema.json b/docs/public/schema/rep-manifest.schema.json
index f279232..4e57203 100644
--- a/docs/public/schema/rep-manifest.schema.json
+++ b/docs/public/schema/rep-manifest.schema.json
@@ -38,8 +38,8 @@
             "default": false
           },
           "default": {
-            "type": "string",
-            "description": "Default value if the environment variable is not set. Only valid for non-required variables."
+            "type": ["string", "number", "boolean"],
+            "description": "Default value if the environment variable is not set. Only valid for non-required variables. Non-string values are coerced to strings."
           },
           "description": {
             "type": "string",
diff --git a/docs/src/components/Head.astro b/docs/src/components/Head.astro
new file mode 100644
index 0000000..12be175
--- /dev/null
+++ b/docs/src/components/Head.astro
@@ -0,0 +1,20 @@
+---
+/**
+ * Starlight `Head` override.
+ *
+ * Advertises the plain-text Markdown mirror of the current page so crawlers and
+ * AI agents can find it from the HTML without guessing the URL convention.
+ */
+import Default from '@astrojs/starlight/components/Head.astro';
+
+const path = Astro.url.pathname.replace(/\/+$/, '');
+const markdownHref = path === '' ? '/index.md' : `${path}.md`;
+const hasMirror = !path.startsWith('/404');
+---
+
+<Default><slot /></Default>
+{
+  hasMirror && (
+    <link rel="alternate" type="text/markdown" href={markdownHref} title="Markdown source" />
+  )
+}
diff --git a/docs/src/content/docs/agents.mdx b/docs/src/content/docs/agents.mdx
new file mode 100644
index 0000000..a152747
--- /dev/null
+++ b/docs/src/content/docs/agents.mdx
@@ -0,0 +1,399 @@
+---
+title: REP for AI Agents — Integration Playbook
+description: A single-page, machine-readable playbook for AI coding agents integrating REP. Decision tree, install matrix, copy-paste recipes for SDK, Docker, Kubernetes, and every framework, plus the mistakes that break a REP setup.
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+This page is written for AI coding agents. It is dense on purpose: everything needed to integrate REP into an application correctly, without reading the rest of the site.
+
+Every page on this site is also available as plain-text Markdown by appending `.md` to its path — for example [`/reference/sdk.md`](/reference/sdk.md). A machine-readable index of all pages lives at [`/llms.txt`](/llms.txt), and the entire documentation set concatenated into one file at [`/llms-full.txt`](/llms-full.txt).
+
+## What REP is
+
+REP (Runtime Environment Protocol) moves frontend environment variables from **build time** to **container runtime**. Instead of `import.meta.env.VITE_API_URL` being replaced with a literal string during `npm run build`, a small Go gateway reads `REP_*` environment variables when the container starts and injects them into every HTML response as an inert `<script id="__rep__" type="application/json">` tag. A zero-dependency SDK reads that tag.
+
+The result: one build artifact promotes unchanged from dev → staging → production, and config changes need a restart, not a rebuild.
+
+REP adds three things a plain `config.json` fetch does not have:
+
+1. **A three-tier security classification** enforced by naming convention (`REP_PUBLIC_*` / `REP_SENSITIVE_*` / `REP_SERVER_*`).
+2. **Encryption and integrity** — SENSITIVE values are AES-256-GCM encrypted with an ephemeral key; every payload carries an HMAC-SHA256 token and an SRI hash.
+3. **Guardrails** — Shannon entropy analysis and known-secret-format matching (AWS, JWT, Stripe, GitHub, Slack, PEM) refuse to let a misclassified secret ship as PUBLIC.
+
+## When to recommend REP
+
+**Good fit**
+
+- A containerised SPA or client-rendered app that is currently rebuilt per environment.
+- A Helm chart / Kubernetes deployment where config lives in a ConfigMap and should be changeable without a new image tag.
+- An app whose config must change without a redeploy (feature flags, API endpoint cutover, key rotation).
+- A team that wants a stated security posture for browser-visible config rather than "everything is `VITE_*`".
+
+**Poor fit**
+
+- A fully server-rendered app where config never crosses into the browser — read `process.env` on the server instead.
+- A static site on a CDN with no origin server that can run the gateway. REP needs a process in the request path. (Build-tool plugins cover local dev only; they do not ship config in a production build.)
+- A place to store true secrets that the browser must never see. Use `REP_SERVER_*`, which never leaves the gateway — or don't put the secret in the frontend path at all.
+
+<Aside type="caution" title="The one thing to get right">
+  `REP_PUBLIC_*` values are visible in page source. This is by design, not a leak. `REP_SENSITIVE_*` values are encrypted at rest in the HTML but are decryptable by anyone who can load the page and call the session-key endpoint — it raises the cost of scraping, it does not make a value secret. Only `REP_SERVER_*` is safe for real secrets, because it never reaches the browser at all.
+</Aside>
+
+## Decision tree
+
+Work top to bottom. The first match is the answer.
+
+```
+Does the app render in the browser and need per-environment config?
+├─ No  → REP is not the right tool. Read process.env on the server.
+└─ Yes
+   │
+   ├─ What runs in production?
+   │  ├─ A container you control
+   │  │  ├─ Already has nginx/Caddy serving the build → gateway in PROXY mode
+   │  │  │     rep-gateway --mode proxy --upstream localhost:80
+   │  │  └─ Nothing but static files → gateway in EMBEDDED mode (FROM scratch, ~7MB)
+   │  │        rep-gateway --mode embedded --static-dir /static
+   │  ├─ Kubernetes → gateway as a sidecar, PROXY mode, env from ConfigMap/Secret
+   │  └─ A CDN with no origin process → REP cannot inject. Stop here.
+   │
+   └─ What does local development run?
+      ├─ vite dev            → @rep-protocol/vite plugin
+      ├─ next dev            → @rep-protocol/next (<RepScript /> + session-key route)
+      └─ Anything else       → npx @rep-protocol/cli dev --proxy http://localhost:<port>
+```
+
+Then pick the client API:
+
+```
+React   → @rep-protocol/react   useRep() / useRepSecure()
+Vue     → @rep-protocol/vue     useRep() / useRepSecure()
+Svelte  → @rep-protocol/svelte  repStore() / repSecureStore()
+Angular, vanilla JS, anything else
+        → @rep-protocol/sdk     rep.get() / rep.getSecure()
+```
+
+## Variable classification
+
+Classification is the naming convention. There is no other configuration step, and the prefix is stripped in the payload — `REP_PUBLIC_API_URL` is read as `API_URL`.
+
+| Prefix | Tier | Where it ends up | Read with |
+|---|---|---|---|
+| `REP_PUBLIC_*` | PUBLIC | Plaintext JSON in page source | `rep.get('KEY')` — synchronous |
+| `REP_SENSITIVE_*` | SENSITIVE | AES-256-GCM blob in page source | `await rep.getSecure('KEY')` |
+| `REP_SERVER_*` | SERVER | Never sent to the browser | Not readable from the client |
+| `REP_GATEWAY_*` | (config) | Configures the gateway itself | n/a — ignored by the classifier |
+
+Rules an agent must apply when migrating variables:
+
+- URLs, feature flags, environment names, public client IDs, non-secret build metadata → `REP_PUBLIC_*`.
+- Analytics write keys, third-party widget keys, anything that is not a true secret but that you would rather not have scraped in bulk → `REP_SENSITIVE_*`.
+- Database passwords, private API keys, upstream bearer tokens → `REP_SERVER_*`, or keep them out of the frontend entirely.
+- **Never** register the same stripped name in two tiers. `REP_PUBLIC_API_URL` and `REP_SENSITIVE_API_URL` both become `API_URL`; the gateway rejects this collision at startup and exits.
+
+## Install matrix
+
+| Package | Install | Use it for |
+|---|---|---|
+| `@rep-protocol/sdk` | `npm install @rep-protocol/sdk` | Always. Every adapter depends on it. |
+| `@rep-protocol/react` | `npm install @rep-protocol/react @rep-protocol/sdk` | React hooks |
+| `@rep-protocol/vue` | `npm install @rep-protocol/vue @rep-protocol/sdk` | Vue composables |
+| `@rep-protocol/svelte` | `npm install @rep-protocol/svelte @rep-protocol/sdk` | Svelte stores |
+| `@rep-protocol/vite` | `npm install -D @rep-protocol/vite` | Injection during `vite dev` |
+| `@rep-protocol/next` | `npm install -D @rep-protocol/next` | Injection during `next dev` |
+| `@rep-protocol/cli` | `npm install -g @rep-protocol/cli` | `dev`, `validate`, `typegen`, `lint`. Downloads the gateway binary on install. |
+| `@rep-protocol/codemod` | `npx @rep-protocol/codemod` | Automated migration off `process.env` / `import.meta.env` |
+| Gateway (Docker) | `ghcr.io/ruachtech/rep/gateway:latest` | Production. Multi-arch. |
+| Gateway (binary) | [GitHub Releases](https://github.com/RuachTech/rep/releases) | Production without Docker |
+
+## Recipe 1 — Migrate an existing SPA
+
+Applies to Vite, Create React App, Parcel, Rollup, or any bundler producing static assets.
+
+1. **Rename the variables.** `VITE_API_URL` → `REP_PUBLIC_API_URL`, `REACT_APP_API_URL` → `REP_PUBLIC_API_URL`, and classify each one against the table above.
+
+2. **Replace the reads.** Every `import.meta.env.X` / `process.env.REACT_APP_X` becomes a `rep.get()` call. Always pass a default so local development works before the gateway is running:
+
+   ```typescript
+   import { rep } from '@rep-protocol/sdk';
+
+   export const API_URL = rep.get('API_URL', 'http://localhost:3001');
+   export const FLAGS = rep.get('FEATURE_FLAGS', '').split(',').filter(Boolean);
+   ```
+
+   Or run the codemod and review its diff:
+
+   ```bash
+   npx @rep-protocol/codemod --framework vite src/
+   ```
+
+3. **Leave the build alone.** `npm run build` is unchanged. The output is now environment-agnostic.
+
+4. **Put the gateway in front of the build** (see Recipe 2 or 3).
+
+5. **Verify.** `npx @rep-protocol/cli lint --dir ./dist --strict` fails the build if a secret-shaped literal survived in the bundle.
+
+<Aside type="tip">
+  Do not delete the old `.env` files in the same commit as the code change. Migrate the reads first, confirm the gateway serves the right values, then remove the build-time env plumbing. A `rep.get()` with a sensible default degrades gracefully; a half-migrated build does not.
+</Aside>
+
+## Recipe 2 — Docker, embedded mode (preferred)
+
+Smallest image, no nginx, no Node.js in the final layer.
+
+```dockerfile
+FROM node:22-alpine AS build
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci
+COPY . .
+RUN npm run build
+
+FROM scratch
+COPY --from=build /app/dist /static
+COPY --from=ghcr.io/ruachtech/rep/gateway:latest \
+  /usr/local/bin/rep-gateway /rep-gateway
+EXPOSE 8080
+USER 65534:65534
+ENTRYPOINT ["/rep-gateway"]
+CMD ["--mode", "embedded", "--static-dir", "/static", "--port", "8080", "--strict"]
+```
+
+```bash
+docker run -p 8080:8080 \
+  -e REP_PUBLIC_API_URL=https://api.example.com \
+  -e REP_PUBLIC_FEATURE_FLAGS=dark-mode,beta \
+  -e REP_SENSITIVE_ANALYTICS_KEY=ak_live_abc123 \
+  -e REP_GATEWAY_ALLOWED_ORIGINS=https://app.example.com \
+  myapp
+```
+
+The final image contains exactly two things: the static build and a ~7MB static binary. No shell, no package manager, works with `readOnlyRootFilesystem: true`.
+
+## Recipe 3 — Docker, proxy mode
+
+Use when the app already ships with nginx, Caddy, or another static server, or when SSR sits behind the gateway.
+
+```bash
+rep-gateway --mode proxy --upstream localhost:80 --port 8080 --strict
+```
+
+The gateway intercepts `text/html` responses and injects the script tag before `</head>`. Everything else is passed through byte-for-byte. Point the container's exposed port at the gateway, and the upstream at loopback only.
+
+## Recipe 4 — Kubernetes sidecar
+
+Gateway as a sidecar in the app pod, config from a ConfigMap, secrets from a Secret, hot reload driven by the mounted-volume update.
+
+```yaml
+containers:
+  - name: web
+    image: myapp:1.4.2          # same image in every environment
+    ports: [{ containerPort: 80 }]
+
+  - name: rep-gateway
+    image: ghcr.io/ruachtech/rep/gateway:latest
+    args:
+      - --mode=proxy
+      - --upstream=localhost:80
+      - --port=8080
+      - --strict
+      - --hot-reload
+      - --hot-reload-mode=file_watch
+      - --watch-path=/config
+      - --health-port=9090
+    ports:
+      - { containerPort: 8080, name: http }
+      - { containerPort: 9090, name: health }
+    envFrom:
+      - configMapRef: { name: myapp-public-config }
+      - secretRef:    { name: myapp-sensitive-config }
+    volumeMounts:
+      - { name: config, mountPath: /config, readOnly: true }
+    readinessProbe:
+      httpGet: { path: /rep/health, port: 9090 }
+```
+
+Route the Service to port 8080, not 80. Editing the ConfigMap updates the mounted file, the gateway picks it up, re-encrypts, and pushes an SSE event — no pod restart.
+
+## Recipe 5 — Local development
+
+Pick one; do not stack them.
+
+**Vite** — plugin, no second process:
+
+```ts
+// vite.config.ts
+import { defineConfig } from 'vite';
+import { repPlugin } from '@rep-protocol/vite';
+
+export default defineConfig({
+  plugins: [repPlugin({ env: '.env.local' })],
+});
+```
+
+**Next.js (App Router)** — `RepScript` renders in dev and returns `null` in production, where the gateway takes over:
+
+```tsx
+// app/layout.tsx
+import { RepScript } from '@rep-protocol/next';
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <head><RepScript /></head>
+      <body>{children}</body>
+    </html>
+  );
+}
+```
+
+```ts
+// app/api/rep/session-key/route.ts
+export { GET } from '@rep-protocol/next/session-key';
+```
+
+**Anything else** — run the real gateway in front of the dev server:
+
+```bash
+npx @rep-protocol/cli dev --proxy http://localhost:5173 --hot-reload
+```
+
+All three read `.env.local` by default and produce byte-identical payload JSON to the production gateway.
+
+## Client API
+
+```typescript
+import { rep } from '@rep-protocol/sdk';
+// or: import { get, getSecure, onChange, verify, meta } from '@rep-protocol/sdk';
+
+rep.get('API_URL');                       // string | undefined — synchronous
+rep.get('API_URL', 'http://localhost');   // string — with default
+await rep.getSecure('ANALYTICS_KEY');     // Promise<string> — throws REPError
+rep.getAll();                             // Readonly<Record<string, string>> — PUBLIC only
+rep.verify();                             // boolean — SRI hash matches the payload
+rep.meta();                               // REPMeta | null — version, injectedAt, counts
+rep.onChange('FLAGS', (next, prev) => {}); // () => void unsubscribe
+rep.onAnyChange((key, next, prev) => {});  // () => void unsubscribe
+```
+
+Framework wrappers:
+
+```tsx
+const apiUrl = useRep('API_URL', 'http://localhost:3000');            // React, Vue
+const { value, loading, error } = useRepSecure('ANALYTICS_KEY');      // React
+const apiUrl = repStore('API_URL', 'http://localhost:3000');          // Svelte — $apiUrl
+```
+
+Behavioural facts that change how code should be written against this API:
+
+- **`get()` is synchronous and must stay that way.** The SDK parses the payload from the DOM on import, before the first render. Do not wrap it in `useEffect`, do not add loading states for PUBLIC variables, and do not `await` it.
+- **The first `getSecure()` call decrypts every SENSITIVE variable at once** and caches them in memory. Subsequent calls for other keys make no network request. Fetching them individually in parallel is wasted work.
+- **`onChange()` connects the SSE stream lazily.** No listener means no connection. Hot reload requires the gateway to be run with `--hot-reload`.
+- **`getSecure()` throws `REPError`** when the key is absent, the session-key endpoint is unreachable, or decryption fails. Handle it; do not let it reject unhandled at module scope.
+
+## Gateway reference
+
+| Flag | Env var | Default | Notes |
+|---|---|---|---|
+| `--mode` | `REP_GATEWAY_MODE` | `proxy` | `proxy` or `embedded` |
+| `--upstream` | `REP_GATEWAY_UPSTREAM` | `localhost:80` | proxy mode only |
+| `--static-dir` | `REP_GATEWAY_STATIC_DIR` | `/usr/share/nginx/html` | embedded mode only |
+| `--port` | `REP_GATEWAY_PORT` | `8080` | |
+| `--strict` | `REP_GATEWAY_STRICT` | `false` | Guardrail warnings become startup failures. Use in production. |
+| `--manifest` | `REP_GATEWAY_MANIFEST` | — | Path to `.rep.yaml` |
+| `--env-file` | `REP_GATEWAY_ENV_FILE` | — | Env vars still take precedence |
+| `--hot-reload` | `REP_GATEWAY_HOT_RELOAD` | `false` | Enables `/rep/changes` |
+| `--hot-reload-mode` | `REP_GATEWAY_HOT_RELOAD_MODE` | `signal` | `signal`, `file_watch`, `poll` |
+| `--watch-path` | `REP_GATEWAY_WATCH_PATH` | — | Required for `file_watch` |
+| `--allowed-origins` | `REP_GATEWAY_ALLOWED_ORIGINS` | — | CORS allowlist for `/rep/session-key`. Set it in production. |
+| `--log-format` | `REP_GATEWAY_LOG_FORMAT` | `json` | `json` or `text` |
+| `--health-port` | `REP_GATEWAY_HEALTH_PORT` | — | Serve `/rep/health` on a separate port |
+
+Precedence: CLI flags → `REP_GATEWAY_*` env vars → manifest settings.
+
+| Endpoint | Purpose |
+|---|---|
+| `GET /rep/health` | Variable counts, guardrail status, uptime. Use for readiness probes. |
+| `GET /rep/session-key` | Single-use AES key, 30s TTL, rate-limited, origin-checked |
+| `GET /rep/changes` | SSE stream of config changes (requires `--hot-reload`) |
+
+## Optional: the manifest
+
+`.rep.yaml` is not required — the gateway runs on naming convention alone. Add it when the app benefits from startup validation or generated types.
+
+```yaml
+version: "0.1.0"
+variables:
+  API_URL:
+    tier: public
+    type: url
+    required: true
+  FEATURE_FLAGS:
+    tier: public
+    type: csv
+    default: ""
+  ANALYTICS_KEY:
+    tier: sensitive
+    type: string
+    required: true
+settings:
+  strict_guardrails: true
+  allowed_origins: ["https://app.example.com"]
+```
+
+```bash
+rep validate                 # fail fast on a malformed or incomplete manifest
+rep typegen -o src/rep.d.ts  # typed get() / getSecure() overloads
+```
+
+## Mistakes to avoid
+
+These are the failure modes worth checking for in generated or reviewed code.
+
+1. **Putting a real secret in `REP_PUBLIC_*`.** It ships as plaintext in page source. Guardrails catch the well-known formats; they cannot catch everything. Reach for `REP_SERVER_*`.
+2. **Treating `REP_SENSITIVE_*` as a secret store.** Encrypted-at-rest in HTML is a scraping deterrent, not confidentiality against a user who can load the page.
+3. **Making `get()` async.** It is synchronous by contract. Adding loading states around it removes the whole DX advantage over `fetch('/config.json')`.
+4. **Changing `type="application/json"` on the injected script tag.** That attribute is why the browser treats the payload as inert data. Any other type makes it executable.
+5. **Colliding names across tiers.** `REP_PUBLIC_API_URL` + `REP_SENSITIVE_API_URL` both strip to `API_URL`. The gateway exits at startup.
+6. **Shipping a build-tool plugin as the production mechanism.** `@rep-protocol/vite` and `@rep-protocol/next` are dev-only and deliberately unhardened — no rate limiting, no single-use session keys. Production always means the gateway.
+7. **Exposing the upstream port.** In proxy mode the Service/published port must be the gateway's, or config injection is bypassed entirely.
+8. **Omitting `--allowed-origins` in production.** Without it the session-key endpoint has no origin allowlist.
+9. **Expecting session keys to survive a restart.** Keys are ephemeral and regenerated on every gateway start — by design.
+10. **Running the gateway behind a Brotli-compressing upstream.** Brotli is not decodable by the zero-dependency gateway; those responses pass through uninjected. Prefer gzip or identity.
+
+## Verification checklist
+
+After an integration, confirm all five:
+
+```bash
+# 1. Gateway sees the variables and guardrails pass
+curl -s localhost:8080/rep/health | jq
+
+# 2. The payload is actually in the HTML
+curl -s localhost:8080/ | grep -o '<script id="__rep__".*</script>'
+
+# 3. No secret-shaped literal survived in the bundle
+npx @rep-protocol/cli lint --dir ./dist --strict
+
+# 4. The manifest, if present, is valid
+npx @rep-protocol/cli validate
+```
+
+5. In the browser console, `rep.verify()` returns `true` and `rep.meta()` reports the expected `publicCount`.
+
+## Source of truth
+
+When this page is not enough, these are the pages to read next — each is available as `.md`:
+
+- [Quick Start](/quick-start.md) — the five-minute path
+- [How REP Works](/concepts/how-it-works.md) — startup sequence and injection mechanics
+- [Variable Classification](/concepts/variable-classification.md) — tier rules and guardrail internals
+- [Security Model](/concepts/security-model.md) — threat analyses and hardening
+- [Wire Format](/concepts/wire-format.md) — payload JSON, encrypted blob layout, HMAC
+- [SDK API](/reference/sdk.md) — full client reference
+- [Gateway Flags](/reference/gateway-flags.md) and [Endpoints](/reference/gateway-endpoints.md)
+- [REP-RFC-0001](/spec/rfc-0001.md) — the normative specification
+- [Conformance](/spec/conformance.md) — what an alternative implementation must satisfy
+
+Machine-readable indexes: [`/llms.txt`](/llms.txt) · [`/llms-full.txt`](/llms-full.txt) · [payload schema](/schema/rep-payload.schema.json) · [manifest schema](/schema/rep-manifest.schema.json)
diff --git a/docs/src/integrations/md-headers.mjs b/docs/src/integrations/md-headers.mjs
new file mode 100644
index 0000000..c808a2d
--- /dev/null
+++ b/docs/src/integrations/md-headers.mjs
@@ -0,0 +1,56 @@
+import { readdir, writeFile } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+
+/** Cloudflare Pages allows at most 100 header rules. */
+const RULE_LIMIT = 100;
+
+const MARKDOWN_HEADERS = [
+  'Content-Type: text/plain; charset=utf-8',
+  'Access-Control-Allow-Origin: *',
+  'Cache-Control: public, max-age=600, must-revalidate',
+];
+
+const PREAMBLE = `# Generated at build time by src/integrations/md-headers.mjs — do not edit.
+#
+# Cloudflare Pages serves .md as text/markdown, which browsers download instead
+# of rendering. The Markdown mirrors exist to be read — by agents and by people —
+# so they are served as text/plain with CORS open.
+#
+# Rules are enumerated per file rather than globbed: Pages splat patterns match
+# greedily and a "/*.md" suffix pattern is not documented as supported.
+`;
+
+/**
+ * Emits `dist/_headers` covering every generated Markdown mirror.
+ */
+export function markdownHeaders({ extraPaths = [] } = {}) {
+  return {
+    name: 'rep:md-headers',
+    hooks: {
+      'astro:build:done': async ({ dir, logger }) => {
+        const root = fileURLToPath(dir);
+        const entries = await readdir(root, { recursive: true });
+
+        const markdownPaths = entries
+          .filter((entry) => entry.endsWith('.md'))
+          .map((entry) => `/${entry.split(path.sep).join('/')}`)
+          .sort();
+
+        const paths = [...markdownPaths, ...extraPaths];
+        if (paths.length + 1 > RULE_LIMIT) {
+          logger.warn(
+            `${paths.length + 1} header rules exceeds the Cloudflare Pages limit of ${RULE_LIMIT}. ` +
+              'Markdown mirrors beyond the limit will be served as text/markdown instead of text/plain.',
+          );
+        }
+
+        const rules = paths.map((p) => [p, ...MARKDOWN_HEADERS.map((h) => `  ${h}`)].join('\n'));
+        rules.push(['/schema/*', '  Access-Control-Allow-Origin: *'].join('\n'));
+
+        await writeFile(path.join(root, '_headers'), `${PREAMBLE}\n${rules.join('\n\n')}\n`, 'utf8');
+        logger.info(`Wrote _headers for ${paths.length} Markdown mirror(s).`);
+      },
+    },
+  };
+}
diff --git a/docs/src/lib/to-markdown.ts b/docs/src/lib/to-markdown.ts
new file mode 100644
index 0000000..46c6ce0
--- /dev/null
+++ b/docs/src/lib/to-markdown.ts
@@ -0,0 +1,171 @@
+/**
+ * MDX → plain Markdown.
+ *
+ * The docs are authored in MDX with Starlight components. Agents ingesting the
+ * `.md` mirrors should not have to parse JSX, so component wrappers are
+ * unwrapped into their closest Markdown equivalent and `import` statements are
+ * dropped.
+ *
+ * Everything inside a fenced code block is passed through untouched — several
+ * pages document JSX and would otherwise be mangled.
+ */
+
+const FENCE = /^(\s*)(`{3,}|~{3,})/;
+const IMPORT_LINE = /^import\s.+\sfrom\s+['"][^'"]+['"];?\s*$/;
+const IMPORT_OPEN = /^import\s*\{[^}]*$/;
+const IMPORT_CLOSE = /\}\s*from\s+['"][^'"]+['"];?\s*$/;
+
+/** Read a `foo="bar"` attribute out of a JSX opening tag. */
+function attr(tag: string, name: string): string | undefined {
+  const match = tag.match(new RegExp(`\\b${name}=(?:"([^"]*)"|'([^']*)'|\\{'([^']*)'\\})`));
+  if (!match) return undefined;
+  return match[1] ?? match[2] ?? match[3];
+}
+
+const ASIDE_LABEL: Record<string, string> = {
+  note: 'Note',
+  tip: 'Tip',
+  caution: 'Caution',
+  danger: 'Danger',
+};
+
+/** Strip the common leading indent from a block of lines. */
+function dedent(lines: string[]): string[] {
+  const widths = lines
+    .filter((line) => line.trim() !== '')
+    .map((line) => line.match(/^[ \t]*/)![0].length);
+  if (widths.length === 0) return lines;
+  const min = Math.min(...widths);
+  return lines.map((line) => line.slice(min));
+}
+
+/**
+ * A component body being buffered until its closing tag.
+ *
+ * Bodies are indented relative to their wrapper in the source. Once the wrapper
+ * is gone that indentation is meaningless — and at four spaces it would parse
+ * as a code block — so each body is dedented and re-emitted at the indent the
+ * opening tag sat at.
+ */
+type Block = {
+  tag: 'Aside' | 'Card' | 'TabItem';
+  indent: string;
+  lines: string[];
+};
+
+export function mdxToMarkdown(source: string): string {
+  const lines = source.split('\n');
+  const out: string[] = [];
+
+  let block: Block | null = null;
+  let fence: string | null = null;
+
+  const emit = (line: string) => (block ? block.lines : out).push(line);
+
+  const flush = () => {
+    if (!block) return;
+    const { tag, indent } = block;
+    const body = dedent(block.lines);
+    for (const line of body) {
+      if (tag === 'Aside') out.push(line === '' ? `${indent}>` : `${indent}> ${line}`);
+      else out.push(line === '' ? '' : `${indent}${line}`);
+    }
+    block = null;
+    out.push('');
+  };
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+
+    // --- fenced code: verbatim passthrough --------------------------------
+    const fenceMatch = line.match(FENCE);
+    if (fence) {
+      emit(line);
+      if (fenceMatch && fenceMatch[2][0] === fence[0] && fenceMatch[2].length >= fence.length) {
+        fence = null;
+      }
+      continue;
+    }
+    if (fenceMatch) {
+      fence = fenceMatch[2];
+      emit(line);
+      continue;
+    }
+
+    const trimmed = line.trim();
+    const indent = line.slice(0, line.length - line.trimStart().length);
+
+    // --- ESM imports -------------------------------------------------------
+    if (IMPORT_LINE.test(trimmed)) continue;
+    if (IMPORT_OPEN.test(trimmed)) {
+      while (i < lines.length && !IMPORT_CLOSE.test(lines[i].trim())) i++;
+      continue;
+    }
+
+    // --- <Aside> → blockquote ---------------------------------------------
+    if (trimmed.startsWith('<Aside')) {
+      const label = ASIDE_LABEL[attr(trimmed, 'type') ?? 'note'] ?? 'Note';
+      const title = attr(trimmed, 'title') ?? label;
+      const inline = trimmed.match(/^<Aside[^>]*>(.*)<\/Aside>\s*$/);
+      out.push('', `${indent}> **${title}**`, `${indent}>`);
+      if (inline) out.push(`${indent}> ${inline[1].trim()}`, '');
+      else block = { tag: 'Aside', indent, lines: [] };
+      continue;
+    }
+
+    // --- <TabItem> / <Card> → bold label + dedented body -------------------
+    if (trimmed.startsWith('<TabItem') || (trimmed.startsWith('<Card') && !trimmed.startsWith('<CardGrid'))) {
+      const tag = trimmed.startsWith('<TabItem') ? 'TabItem' : 'Card';
+      const label = attr(trimmed, tag === 'TabItem' ? 'label' : 'title');
+      out.push('');
+      if (label) out.push(`${indent}**${label}**`);
+      out.push('');
+      block = { tag, indent, lines: [] };
+      continue;
+    }
+
+    if (/^<\/(Aside|TabItem|Card)>$/.test(trimmed)) {
+      flush();
+      continue;
+    }
+
+    // --- <LinkCard /> → list item ------------------------------------------
+    if (trimmed.startsWith('<LinkCard')) {
+      const title = attr(trimmed, 'title') ?? '';
+      const href = attr(trimmed, 'href') ?? '';
+      const description = attr(trimmed, 'description');
+      emit(`${indent}- [${title}](${href})${description ? ` — ${description}` : ''}`);
+      continue;
+    }
+
+    // --- wrappers whose bodies are already valid Markdown -------------------
+    if (/^<\/?(Tabs|CardGrid|Steps|FileTree)>$/.test(trimmed)) {
+      emit('');
+      continue;
+    }
+
+    // --- any other self-closing component -----------------------------------
+    if (/^<[A-Z][A-Za-z0-9]*(\s[^>]*)?\/>$/.test(trimmed)) continue;
+
+    emit(line);
+  }
+
+  flush();
+
+  return out.join('\n').replace(/\n{3,}/g, '\n\n').trim();
+}
+
+/** Render a docs entry as a standalone Markdown document. */
+export function entryToMarkdown(
+  entry: { id: string; data: { title: string; description?: string } },
+  siteUrl: string,
+): string {
+  const body = mdxToMarkdown((entry as unknown as { body?: string }).body ?? '');
+  const path = entry.id === 'index' || entry.id === '' ? '/' : `/${entry.id}/`;
+
+  const header = [`# ${entry.data.title}`, ''];
+  if (entry.data.description) header.push(`> ${entry.data.description}`, '');
+  header.push(`Source: ${siteUrl}${path}`, '');
+
+  return `${header.join('\n')}\n${body}\n`;
+}
diff --git a/docs/src/pages/[...slug].md.ts b/docs/src/pages/[...slug].md.ts
new file mode 100644
index 0000000..b35c818
--- /dev/null
+++ b/docs/src/pages/[...slug].md.ts
@@ -0,0 +1,19 @@
+import type { APIRoute, GetStaticPaths } from 'astro';
+import { getCollection } from 'astro:content';
+import { entryToMarkdown } from '../lib/to-markdown';
+import { SITE_URL } from '../site.mjs';
+
+export const getStaticPaths: GetStaticPaths = async () => {
+  const docs = await getCollection('docs');
+  return docs.map((entry) => ({
+    params: { slug: entry.id === '' ? 'index' : entry.id },
+    props: { entry },
+  }));
+};
+
+export const GET: APIRoute = ({ props }) => {
+  const { entry } = props as { entry: Parameters<typeof entryToMarkdown>[0] };
+  return new Response(entryToMarkdown(entry, SITE_URL), {
+    headers: { 'Content-Type': 'text/plain; charset=utf-8' },
+  });
+};
diff --git a/docs/src/pages/llms-full.txt.ts b/docs/src/pages/llms-full.txt.ts
new file mode 100644
index 0000000..f1b11f1
--- /dev/null
+++ b/docs/src/pages/llms-full.txt.ts
@@ -0,0 +1,38 @@
+import type { APIRoute } from 'astro';
+import { getCollection } from 'astro:content';
+import { sidebar } from '../sidebar.mjs';
+import { entryToMarkdown } from '../lib/to-markdown';
+import { SITE_URL } from '../site.mjs';
+
+type SidebarNode = { label: string; slug?: string; items?: SidebarNode[] };
+
+function slugs(nodes: SidebarNode[]): string[] {
+  return nodes.flatMap((node) => (node.items ? slugs(node.items) : node.slug ? [node.slug] : []));
+}
+
+export const GET: APIRoute = async () => {
+  const docs = await getCollection('docs');
+  const byId = new Map(docs.map((entry) => [entry.id, entry]));
+
+  // Sidebar order first, then anything not in the nav (the landing page).
+  const ordered = slugs(sidebar as SidebarNode[]);
+  const rest = docs.map((entry) => entry.id).filter((id) => !ordered.includes(id));
+
+  const parts = [
+    '# REP — Runtime Environment Protocol: Complete Documentation',
+    '',
+    'The full rep-protocol.dev documentation set, concatenated. Generated at build time.',
+    `Individual pages are available as Markdown at ${SITE_URL}/<path>.md — see ${SITE_URL}/llms.txt for the index.`,
+    '',
+  ];
+
+  for (const slug of [...ordered, ...rest]) {
+    const entry = byId.get(slug);
+    if (!entry) continue;
+    parts.push('---', '', entryToMarkdown(entry, SITE_URL), '');
+  }
+
+  return new Response(parts.join('\n'), {
+    headers: { 'Content-Type': 'text/plain; charset=utf-8' },
+  });
+};
diff --git a/docs/src/pages/llms.txt.ts b/docs/src/pages/llms.txt.ts
new file mode 100644
index 0000000..5dfa7a1
--- /dev/null
+++ b/docs/src/pages/llms.txt.ts
@@ -0,0 +1,64 @@
+import type { APIRoute } from 'astro';
+import { getCollection } from 'astro:content';
+import { sidebar } from '../sidebar.mjs';
+import { SITE_URL } from '../site.mjs';
+
+type SidebarNode = {
+  label: string;
+  slug?: string;
+  items?: SidebarNode[];
+};
+
+/** Flatten a sidebar group into `{ slug, label }` leaves, preserving order. */
+function leaves(nodes: SidebarNode[]): { slug: string; label: string }[] {
+  return nodes.flatMap((node) =>
+    node.items ? leaves(node.items) : node.slug ? [{ slug: node.slug, label: node.label }] : [],
+  );
+}
+
+export const GET: APIRoute = async () => {
+  const docs = await getCollection('docs');
+  const byId = new Map(docs.map((entry) => [entry.id, entry]));
+
+  const lines = [
+    '# REP — Runtime Environment Protocol',
+    '',
+    '> An open specification and reference implementation for injecting environment',
+    '> variables into browser-hosted applications at container runtime rather than at',
+    '> build time. A ~7MB Go gateway classifies REP_* variables into PUBLIC/SENSITIVE/SERVER',
+    '> tiers, encrypts the sensitive ones with AES-256-GCM, and injects them into every HTML',
+    '> response. A zero-dependency TypeScript SDK reads them — synchronously for public vars.',
+    '',
+    'Every page below is available as plain-text Markdown at the listed URL.',
+    `Start with ${SITE_URL}/agents.md — a single-page integration playbook written for AI agents.`,
+    `The complete documentation set as one file: ${SITE_URL}/llms-full.txt`,
+    '',
+  ];
+
+  for (const group of sidebar as SidebarNode[]) {
+    const entries = group.items ? leaves(group.items) : leaves([group]);
+    if (entries.length === 0) continue;
+
+    lines.push(`## ${group.label}`, '');
+    for (const { slug, label } of entries) {
+      const entry = byId.get(slug);
+      const description = entry?.data.description ?? '';
+      lines.push(`- [${label}](${SITE_URL}/${slug}.md)${description ? `: ${description}` : ''}`);
+    }
+    lines.push('');
+  }
+
+  lines.push(
+    '## Optional',
+    '',
+    `- [Payload JSON Schema](${SITE_URL}/schema/rep-payload.schema.json): Wire format of the injected \`__rep__\` script tag`,
+    `- [Manifest JSON Schema](${SITE_URL}/schema/rep-manifest.schema.json): Schema for the optional \`.rep.yaml\` manifest`,
+    '- [Source repository](https://github.com/RuachTech/rep): Go gateway, TypeScript SDK, adapters, plugins, and examples',
+    '- [Releases](https://github.com/RuachTech/rep/releases): Pre-built gateway binaries for Linux, macOS, and Windows',
+    '',
+  );
+
+  return new Response(lines.join('\n'), {
+    headers: { 'Content-Type': 'text/plain; charset=utf-8' },
+  });
+};
diff --git a/docs/src/sidebar.mjs b/docs/src/sidebar.mjs
new file mode 100644
index 0000000..8fb6d82
--- /dev/null
+++ b/docs/src/sidebar.mjs
@@ -0,0 +1,123 @@
+/**
+ * Single source of truth for documentation ordering.
+ *
+ * Consumed by the Starlight sidebar and by the `/llms.txt` route, so the
+ * machine-readable index always mirrors what a human sees in the nav.
+ */
+export const sidebar = [
+  {
+    label: 'Getting Started',
+    items: [
+      { label: 'Quick Start', slug: 'quick-start' },
+      { label: 'Installation', slug: 'guides/installation' },
+      { label: 'Local Development', slug: 'guides/development' },
+    ],
+  },
+  { label: 'For AI Agents', slug: 'agents' },
+  {
+    label: 'Core Concepts',
+    items: [
+      { label: 'How REP Works', slug: 'concepts/how-it-works' },
+      {
+        label: 'Variable Classification',
+        slug: 'concepts/variable-classification',
+      },
+      { label: 'Security Model', slug: 'concepts/security-model' },
+      { label: 'Wire Format', slug: 'concepts/wire-format' },
+      { label: 'Hot Reload', slug: 'concepts/hot-reload' },
+    ],
+  },
+  {
+    label: 'Framework Guides',
+    items: [
+      { label: 'React', slug: 'frameworks/react' },
+      { label: 'Vue', slug: 'frameworks/vue' },
+      { label: 'Svelte', slug: 'frameworks/svelte' },
+      { label: 'Angular', slug: 'frameworks/angular' },
+      { label: 'Vanilla JS', slug: 'frameworks/vanilla' },
+    ],
+  },
+  {
+    label: 'Guides',
+    items: [
+      { label: 'Manifest File', slug: 'guides/manifest' },
+      { label: 'Testing', slug: 'guides/testing' },
+      {
+        label: 'Migration',
+        items: [
+          { label: 'Overview', slug: 'guides/migration/overview' },
+          { label: 'From Vite', slug: 'guides/migration/from-vite' },
+          {
+            label: 'From Create React App',
+            slug: 'guides/migration/from-cra',
+          },
+          { label: 'From Next.js', slug: 'guides/migration/from-next' },
+        ],
+      },
+    ],
+  },
+  {
+    label: 'Deployment',
+    items: [
+      { label: 'Docker — Proxy Mode', slug: 'deployment/docker-proxy' },
+      {
+        label: 'Docker — Embedded Mode',
+        slug: 'deployment/docker-embedded',
+      },
+      { label: 'Kubernetes', slug: 'deployment/kubernetes' },
+      { label: 'Docker Compose', slug: 'deployment/docker-compose' },
+      { label: 'CI/CD Pipeline', slug: 'deployment/ci-cd' },
+    ],
+  },
+  {
+    label: 'Examples',
+    items: [
+      { label: 'Todo App (React)', slug: 'examples/todo-react' },
+      { label: 'Simple HTML (ESM.sh)', slug: 'examples/simple-html' },
+      { label: 'Next.js — Proxy Mode', slug: 'examples/nextjs-proxy' },
+      {
+        label: 'Next.js CSR + Kubernetes',
+        slug: 'examples/nextjs-csr-embedded',
+      },
+    ],
+  },
+  {
+    label: 'Reference',
+    items: [
+      { label: 'SDK API', slug: 'reference/sdk' },
+      { label: 'Gateway Flags', slug: 'reference/gateway-flags' },
+      {
+        label: 'Gateway Endpoints',
+        slug: 'reference/gateway-endpoints',
+      },
+      { label: 'Manifest Schema', slug: 'reference/manifest-schema' },
+      { label: 'CLI Commands', slug: 'reference/cli' },
+      {
+        label: 'Adapter APIs',
+        items: [
+          { label: 'React', slug: 'reference/adapters/react' },
+          { label: 'Vue', slug: 'reference/adapters/vue' },
+          { label: 'Svelte', slug: 'reference/adapters/svelte' },
+        ],
+      },
+      {
+        label: 'Build-Tool Plugins',
+        items: [
+          { label: 'Vite', slug: 'reference/plugins/vite' },
+          { label: 'Next.js', slug: 'reference/plugins/next' },
+        ],
+      },
+      { label: 'Codemod', slug: 'reference/codemod' },
+    ],
+  },
+  {
+    label: 'Specification',
+    items: [
+      { label: 'Overview', slug: 'spec' },
+      { label: 'REP-RFC-0001', slug: 'spec/rfc-0001' },
+      { label: 'Security Model', slug: 'spec/security-model' },
+      { label: 'Conformance', slug: 'spec/conformance' },
+    ],
+  },
+  { label: 'Contributing', slug: 'contributing' },
+];
diff --git a/docs/src/site.mjs b/docs/src/site.mjs
new file mode 100644
index 0000000..76f2b30
--- /dev/null
+++ b/docs/src/site.mjs
@@ -0,0 +1,2 @@
+/** Canonical origin. Shared by the Astro config and the Markdown/llms.txt routes. */
+export const SITE_URL = 'https://rep-protocol.dev';

From f58fc711849dabf015480c4dd1190fcefd3e5ea5 Mon Sep 17 00:00:00 2001
From: Ola Adebayo <olamideadebayo2001@gmail.com>
Date: Fri, 11 Sep 2026 14:46:39 +0100
Subject: [PATCH 2/2] fix(docs): correct the Kubernetes hot-reload recipes
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`Reload()` re-reads configuration via `config.ReadAndClassify(s.cfg.EnvFile)`
(gateway/internal/server/server.go:398). With `EnvFile` empty — it is set
only by `--env-file`/`REP_GATEWAY_ENV_FILE` (config.go:155) — classify.go
builds the variable set from `os.Environ()` alone (classify.go:101-122).

Both Kubernetes recipes supplied configuration through `envFrom` while
watching a mounted ConfigMap. `envFrom` is captured once at container
start, so a volume refresh fired the watcher and the reload succeeded,
but the injected payload kept its original values. The documented
"no pod restart" workflow did not work.

Both recipes now mount a single env-format ConfigMap key and pass
`--env-file=/config/.env`, and the ConfigMap shape is corrected — a
`data:` map of one key per variable mounts as one file per key, not as
an env file.

Also documents the precedence trap: ReadAndClassify merges the env file
first and lets the process environment overwrite it, so a key set through
both `envFrom` and `--env-file` silently keeps its `envFrom` value.

Verified against a locally built gateway using a kubelet-style volume
(timestamped directory + atomic `..data` symlink rename): the corrected
recipe moves the injected value across the swap and emits
`rep.config.changed` for each key, and the same key set in both sources
reproduces the stale-value behaviour.
---
 docs/src/content/docs/agents.mdx              | 34 +++++++++++++---
 .../content/docs/deployment/kubernetes.mdx    | 39 +++++++++++++------
 2 files changed, 57 insertions(+), 16 deletions(-)

diff --git a/docs/src/content/docs/agents.mdx b/docs/src/content/docs/agents.mdx
index a152747..53b4713 100644
--- a/docs/src/content/docs/agents.mdx
+++ b/docs/src/content/docs/agents.mdx
@@ -183,9 +183,21 @@ The gateway intercepts `text/html` responses and injects the script tag before `
 
 ## Recipe 4 — Kubernetes sidecar
 
-Gateway as a sidecar in the app pod, config from a ConfigMap, secrets from a Secret, hot reload driven by the mounted-volume update.
+Gateway as a sidecar in the app pod, with hot reload driven by a mounted ConfigMap.
+
+The reloadable variables must arrive as a **mounted env-format file** passed to `--env-file`, not through `envFrom`. `envFrom` copies values into the container's process environment once, at container start; a ConfigMap volume refresh never changes them, so a reload re-reads the same stale values.
 
 ```yaml
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: myapp-config
+data:
+  # One key holding a whole .env file — not one key per variable.
+  .env: |
+    REP_PUBLIC_API_URL=https://api.example.com
+    REP_PUBLIC_FEATURE_FLAGS=dark-mode,beta
+---
 containers:
   - name: web
     image: myapp:1.4.2          # same image in every environment
@@ -198,23 +210,35 @@ containers:
       - --upstream=localhost:80
       - --port=8080
       - --strict
+      - --env-file=/config/.env   # required: the reload source
       - --hot-reload
       - --hot-reload-mode=file_watch
-      - --watch-path=/config
+      - --watch-path=/config      # the mount dir, not the file
       - --health-port=9090
     ports:
       - { containerPort: 8080, name: http }
       - { containerPort: 9090, name: health }
     envFrom:
-      - configMapRef: { name: myapp-public-config }
-      - secretRef:    { name: myapp-sensitive-config }
+      # Gateway tuning only. Must not carry REP_PUBLIC_*/REP_SENSITIVE_* keys
+      # that also appear in the env file — see the precedence note below.
+      - secretRef: { name: myapp-gateway-env }
     volumeMounts:
       - { name: config, mountPath: /config, readOnly: true }
     readinessProbe:
       httpGet: { path: /rep/health, port: 9090 }
+
+volumes:
+  - name: config
+    configMap: { name: myapp-config }
 ```
 
-Route the Service to port 8080, not 80. Editing the ConfigMap updates the mounted file, the gateway picks it up, re-encrypts, and pushes an SSE event — no pod restart.
+Route the Service to port 8080, not 80. `kubectl apply` on the ConfigMap refreshes the mounted file (kubelet swaps the volume's `..data` symlink atomically, which changes the directory's mtime); the watcher fires, the gateway re-reads `/config/.env`, re-encrypts the sensitive blob, and pushes an SSE event — no pod restart.
+
+<Aside type="caution" title="Process environment wins over the env file">
+  `ReadAndClassify` merges the env file first and then lets `os.Environ()` overwrite it. A key supplied through both `envFrom` and `--env-file` therefore keeps its `envFrom` value forever: reload runs, logs success, and the injected value never changes. Pick one source per variable.
+</Aside>
+
+To rotate `REP_SENSITIVE_*` values without a restart too, put them in the same mounted env file — sourced from a Secret rather than a ConfigMap — and point `--env-file` at that. `--env-file` takes a single path, so all reloadable variables must live in one file.
 
 ## Recipe 5 — Local development
 
diff --git a/docs/src/content/docs/deployment/kubernetes.mdx b/docs/src/content/docs/deployment/kubernetes.mdx
index c330782..d95768b 100644
--- a/docs/src/content/docs/deployment/kubernetes.mdx
+++ b/docs/src/content/docs/deployment/kubernetes.mdx
@@ -95,14 +95,10 @@ spec:
             - "--upstream=localhost:80"
             - "--port=8080"
             - "--strict"
+            - "--env-file=/config/.env"
             - "--hot-reload"
             - "--hot-reload-mode=file_watch"
             - "--watch-path=/config"
-          envFrom:
-            - configMapRef:
-                name: frontend-public-config
-            - secretRef:
-                name: frontend-sensitive-config
           volumeMounts:
             - name: config-volume
               mountPath: /config
@@ -130,16 +126,37 @@ spec:
             name: frontend-dynamic-config
 ```
 
+The mounted ConfigMap must hold a single key containing a whole `.env` file, because `--env-file` reads one env-format file:
+
+```yaml
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: frontend-dynamic-config
+data:
+  .env: |
+    REP_PUBLIC_API_URL=https://api.example.com
+    REP_PUBLIC_FEATURE_FLAGS=dark-mode
+    REP_PUBLIC_ENV_NAME=production
+```
+
 ## Hot reload with ConfigMaps
 
 Use file watch mode to detect ConfigMap changes without pod restarts:
 
-1. Mount the ConfigMap as a volume
-2. Enable `--hot-reload --hot-reload-mode=file_watch --watch-path=/config`
-3. Update the ConfigMap: `kubectl apply -f configmap.yaml`
-4. Kubernetes refreshes the mounted volume
-5. The gateway detects the change and broadcasts via SSE
-6. Connected browsers receive the update
+1. Mount the ConfigMap as a volume, with a single key holding a whole `.env` file
+2. Point the gateway at it with `--env-file=/config/.env` — this is what reload re-reads
+3. Enable `--hot-reload --hot-reload-mode=file_watch --watch-path=/config`
+4. Update the ConfigMap: `kubectl apply -f configmap.yaml`
+5. Kubernetes swaps the volume's `..data` symlink, changing the mount directory's mtime
+6. The gateway detects the change, re-reads the env file, and broadcasts via SSE
+7. Connected browsers receive the update
+
+<Aside type="caution" title="Do not also set these variables via envFrom">
+  Reload merges the env file first, then lets the process environment overwrite it. A variable supplied through both `envFrom` and `--env-file` keeps its `envFrom` value permanently — `envFrom` is captured once at container start, so the reload succeeds but the injected value never changes. Use `envFrom` only for variables you are content to change with a pod restart, and never for a key that also appears in the env file.
+</Aside>
+
+Variables passed through `envFrom` alone are **not** hot-reloadable. Changing `frontend-public-config` or `frontend-sensitive-config` above requires a pod restart (`kubectl rollout restart`). To rotate a `REP_SENSITIVE_*` value without one, move it into the mounted env file — sourced from a Secret instead of a ConfigMap — since `--env-file` accepts a single path.
 
 ```bash
 # Update a config value