feat(docs): add agent playbook and plain-text Markdown mirrors

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.

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'] }),
   ],
 });

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",

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" />
+  )
+}