docs: rewrite README for adopters and SEO-optimize all doc pages

docs/.astro/content-modules.mjs

@@ -1,44 +1,44 @@
 
 export default new Map([
-["src/content/docs/concepts/how-it-works.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fconcepts%2Fhow-it-works.mdx&astroContentModuleFlag=true")],
-["src/content/docs/concepts/security-model.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fconcepts%2Fsecurity-model.mdx&astroContentModuleFlag=true")],
-["src/content/docs/quick-start.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fquick-start.mdx&astroContentModuleFlag=true")],
 ["src/content/docs/concepts/hot-reload.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fconcepts%2Fhot-reload.mdx&astroContentModuleFlag=true")],
+["src/content/docs/contributing.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fcontributing.mdx&astroContentModuleFlag=true")],
+["src/content/docs/concepts/security-model.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fconcepts%2Fsecurity-model.mdx&astroContentModuleFlag=true")],
+["src/content/docs/concepts/how-it-works.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fconcepts%2Fhow-it-works.mdx&astroContentModuleFlag=true")],
 ["src/content/docs/concepts/variable-classification.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fconcepts%2Fvariable-classification.mdx&astroContentModuleFlag=true")],
 ["src/content/docs/concepts/wire-format.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fconcepts%2Fwire-format.mdx&astroContentModuleFlag=true")],
-["src/content/docs/contributing.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fcontributing.mdx&astroContentModuleFlag=true")],
-["src/content/docs/deployment/docker-compose.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fdeployment%2Fdocker-compose.mdx&astroContentModuleFlag=true")],
 ["src/content/docs/index.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Findex.mdx&astroContentModuleFlag=true")],
+["src/content/docs/deployment/docker-compose.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fdeployment%2Fdocker-compose.mdx&astroContentModuleFlag=true")],
+["src/content/docs/quick-start.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fquick-start.mdx&astroContentModuleFlag=true")],
 ["src/content/docs/deployment/ci-cd.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fdeployment%2Fci-cd.mdx&astroContentModuleFlag=true")],
-["src/content/docs/deployment/docker-proxy.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fdeployment%2Fdocker-proxy.mdx&astroContentModuleFlag=true")],
 ["src/content/docs/deployment/docker-embedded.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fdeployment%2Fdocker-embedded.mdx&astroContentModuleFlag=true")],
+["src/content/docs/deployment/docker-proxy.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fdeployment%2Fdocker-proxy.mdx&astroContentModuleFlag=true")],
+["src/content/docs/examples/quick-no-manifest.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fexamples%2Fquick-no-manifest.mdx&astroContentModuleFlag=true")],
 ["src/content/docs/examples/todo-react.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fexamples%2Ftodo-react.mdx&astroContentModuleFlag=true")],
 ["src/content/docs/deployment/kubernetes.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fdeployment%2Fkubernetes.mdx&astroContentModuleFlag=true")],
-["src/content/docs/frameworks/react.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fframeworks%2Freact.mdx&astroContentModuleFlag=true")],
-["src/content/docs/frameworks/svelte.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fframeworks%2Fsvelte.mdx&astroContentModuleFlag=true")],
 ["src/content/docs/frameworks/angular.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fframeworks%2Fangular.mdx&astroContentModuleFlag=true")],
-["src/content/docs/frameworks/vanilla.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fframeworks%2Fvanilla.mdx&astroContentModuleFlag=true")],
-["src/content/docs/examples/quick-no-manifest.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fexamples%2Fquick-no-manifest.mdx&astroContentModuleFlag=true")],
 ["src/content/docs/frameworks/vue.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fframeworks%2Fvue.mdx&astroContentModuleFlag=true")],
-["src/content/docs/guides/development.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fguides%2Fdevelopment.mdx&astroContentModuleFlag=true")],
+["src/content/docs/frameworks/vanilla.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fframeworks%2Fvanilla.mdx&astroContentModuleFlag=true")],
+["src/content/docs/frameworks/react.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fframeworks%2Freact.mdx&astroContentModuleFlag=true")],
+["src/content/docs/frameworks/svelte.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fframeworks%2Fsvelte.mdx&astroContentModuleFlag=true")],
 ["src/content/docs/guides/installation.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fguides%2Finstallation.mdx&astroContentModuleFlag=true")],
+["src/content/docs/guides/development.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fguides%2Fdevelopment.mdx&astroContentModuleFlag=true")],
 ["src/content/docs/guides/testing.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fguides%2Ftesting.mdx&astroContentModuleFlag=true")],
+["src/content/docs/guides/manifest.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fguides%2Fmanifest.mdx&astroContentModuleFlag=true")],
 ["src/content/docs/reference/cli.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Freference%2Fcli.mdx&astroContentModuleFlag=true")],
 ["src/content/docs/reference/codemod.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Freference%2Fcodemod.mdx&astroContentModuleFlag=true")],
-["src/content/docs/guides/manifest.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fguides%2Fmanifest.mdx&astroContentModuleFlag=true")],
-["src/content/docs/reference/manifest-schema.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Freference%2Fmanifest-schema.mdx&astroContentModuleFlag=true")],
-["src/content/docs/reference/sdk.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Freference%2Fsdk.mdx&astroContentModuleFlag=true")],
 ["src/content/docs/reference/gateway-endpoints.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Freference%2Fgateway-endpoints.mdx&astroContentModuleFlag=true")],
 ["src/content/docs/reference/gateway-flags.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Freference%2Fgateway-flags.mdx&astroContentModuleFlag=true")],
+["src/content/docs/reference/manifest-schema.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Freference%2Fmanifest-schema.mdx&astroContentModuleFlag=true")],
+["src/content/docs/reference/sdk.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Freference%2Fsdk.mdx&astroContentModuleFlag=true")],
 ["src/content/docs/spec/conformance.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fspec%2Fconformance.mdx&astroContentModuleFlag=true")],
-["src/content/docs/spec/index.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fspec%2Findex.mdx&astroContentModuleFlag=true")],
 ["src/content/docs/spec/rfc-0001.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fspec%2Frfc-0001.mdx&astroContentModuleFlag=true")],
+["src/content/docs/spec/index.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fspec%2Findex.mdx&astroContentModuleFlag=true")],
 ["src/content/docs/spec/security-model.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fspec%2Fsecurity-model.mdx&astroContentModuleFlag=true")],
-["src/content/docs/guides/migration/from-cra.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fguides%2Fmigration%2Ffrom-cra.mdx&astroContentModuleFlag=true")],
-["src/content/docs/guides/migration/from-vite.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fguides%2Fmigration%2Ffrom-vite.mdx&astroContentModuleFlag=true")],
-["src/content/docs/guides/migration/overview.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fguides%2Fmigration%2Foverview.mdx&astroContentModuleFlag=true")],
-["src/content/docs/guides/migration/from-next.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fguides%2Fmigration%2Ffrom-next.mdx&astroContentModuleFlag=true")],
+["src/content/docs/reference/adapters/vue.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Freference%2Fadapters%2Fvue.mdx&astroContentModuleFlag=true")],
 ["src/content/docs/reference/adapters/svelte.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Freference%2Fadapters%2Fsvelte.mdx&astroContentModuleFlag=true")],
 ["src/content/docs/reference/adapters/react.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Freference%2Fadapters%2Freact.mdx&astroContentModuleFlag=true")],
-["src/content/docs/reference/adapters/vue.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Freference%2Fadapters%2Fvue.mdx&astroContentModuleFlag=true")]]);
+["src/content/docs/guides/migration/from-vite.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fguides%2Fmigration%2Ffrom-vite.mdx&astroContentModuleFlag=true")],
+["src/content/docs/guides/migration/from-next.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fguides%2Fmigration%2Ffrom-next.mdx&astroContentModuleFlag=true")],
+["src/content/docs/guides/migration/from-cra.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fguides%2Fmigration%2Ffrom-cra.mdx&astroContentModuleFlag=true")],
+["src/content/docs/guides/migration/overview.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fguides%2Fmigration%2Foverview.mdx&astroContentModuleFlag=true")]]);
 

docs/astro.config.mjs

@@ -28,11 +28,47 @@ export default defineConfig({
       tableOfContents: { minHeadingLevel: 2, maxHeadingLevel: 3 },
       customCss: ['./src/styles/custom.css'],
       head: [
+        {
+          tag: 'meta',
+          attrs: {
+            property: 'og:type',
+            content: 'website',
+          },
+        },
+        {
+          tag: 'meta',
+          attrs: {
+            property: 'og:site_name',
+            content: 'REP — Runtime Environment Protocol',
+          },
+        },
         {
           tag: 'meta',
           attrs: {
             property: 'og:image',
-            content: '/og-image.png',
+            content: 'https://rep-protocol.dev/og-image.png',
+          },
+        },
+        {
+          tag: 'meta',
+          attrs: {
+            name: 'twitter:card',
+            content: 'summary_large_image',
+          },
+        },
+        {
+          tag: 'meta',
+          attrs: {
+            name: 'twitter:image',
+            content: 'https://rep-protocol.dev/og-image.png',
+          },
+        },
+        {
+          tag: 'meta',
+          attrs: {
+            name: 'keywords',
+            content:
+              'runtime environment variables, docker frontend config, inject env vars browser, runtime config react, environment variables containers, build once deploy anywhere, frontend environment variables docker, runtime configuration protocol',
           },
         },
       ],

docs/public/robots.txt

@@ -0,0 +1,4 @@
+User-agent: *
+Allow: /
+
+Sitemap: https://rep-protocol.dev/sitemap-index.xml

docs/src/content/docs/concepts/hot-reload.mdx

@@ -1,6 +1,6 @@
 ---
-title: Hot Reload
-description: Live config updates via Server-Sent Events — no page reload, no redeployment.
+title: Hot Reload — Live Config Updates via Server-Sent Events
+description: Push environment variable changes to every connected browser via SSE. No page reload, no redeployment. File watch, signal, and poll detection modes.
 ---
 
 import { Aside } from '@astrojs/starlight/components';

docs/src/content/docs/concepts/how-it-works.mdx

@@ -1,6 +1,6 @@
 ---
-title: How REP Works
-description: Architecture overview — gateway modes, startup sequence, and HTML injection.
+title: How REP Works — Gateway Architecture and HTML Injection
+description: How the REP gateway injects environment variables into HTML at runtime. Proxy and embedded modes, startup sequence, script tag injection, and SDK initialization.
 ---
 
 import { Aside } from '@astrojs/starlight/components';

docs/src/content/docs/concepts/security-model.mdx

@@ -1,6 +1,6 @@
 ---
-title: Security Model
-description: Threat analysis, trust boundaries, and what REP protects against (and what it doesn't).
+title: Security Model — Threat Analysis and Trust Boundaries
+description: REP's security model explained. Threat analysis for XSS, CDN compromise, env var leaks, and more. Trust boundaries, encryption design, and known limitations.
 ---
 
 import { Aside } from '@astrojs/starlight/components';

docs/src/content/docs/concepts/variable-classification.mdx

@@ -1,6 +1,6 @@
 ---
-title: Variable Classification
-description: The three-tier security model — PUBLIC, SENSITIVE, and SERVER variables.
+title: Variable Classification — PUBLIC, SENSITIVE, and SERVER Tiers
+description: REP's three-tier security model for environment variables. PUBLIC for plaintext, SENSITIVE for AES-256 encrypted, SERVER for gateway-only. Classified by naming convention.
 ---
 
 import { Aside } from '@astrojs/starlight/components';

docs/src/content/docs/concepts/wire-format.mdx

@@ -1,6 +1,6 @@
 ---
-title: Wire Format
-description: Payload JSON structure, encrypted blob format, and integrity verification.
+title: Wire Format — Payload JSON, Encryption, and HMAC Integrity
+description: The REP payload wire format. JSON structure, AES-256-GCM encrypted blob, HKDF key derivation, HMAC-SHA256 integrity tokens, and SRI verification.
 ---
 
 import { Aside } from '@astrojs/starlight/components';

docs/src/content/docs/contributing.mdx

@@ -1,6 +1,6 @@
 ---
-title: Contributing
-description: How to contribute to the Runtime Environment Protocol project.
+title: Contributing to REP
+description: How to contribute to the Runtime Environment Protocol. Development setup with pnpm and Go, commit conventions, code style for Go and TypeScript, testing, and the automated release process.
 ---
 
 import { Aside } from '@astrojs/starlight/components';

docs/src/content/docs/deployment/ci-cd.mdx

@@ -1,6 +1,6 @@
 ---
-title: CI/CD Pipeline
-description: Build once, deploy everywhere — same image across staging and production.
+title: CI/CD Pipeline — Build Once, Deploy Everywhere
+description: Build your frontend Docker image once in CI and promote it across staging and production without rebuilding. GitHub Actions example with manifest validation and bundle scanning.
 ---
 
 import { Aside } from '@astrojs/starlight/components';

docs/src/content/docs/deployment/docker-compose.mdx

@@ -1,6 +1,6 @@
 ---
-title: Docker Compose
-description: Local multi-service setup with Docker Compose — same image, different config.
+title: Docker Compose — Same Image, Different Config Per Environment
+description: Run the same frontend Docker image across staging and production with Docker Compose. Different environment variables per service, .env file support, and dev proxy setup.
 ---
 
 ## Basic setup

docs/src/content/docs/deployment/docker-embedded.mdx

@@ -1,6 +1,6 @@
 ---
-title: Docker — Embedded Mode
-description: Minimal FROM scratch containers with the gateway serving files directly.
+title: Docker Embedded Mode — Minimal FROM scratch Containers
+description: Deploy a frontend app in a minimal FROM scratch Docker container. The REP gateway serves static files directly — no nginx, no Node.js, no shell. Under 10MB total.
 ---
 
 import { Aside } from '@astrojs/starlight/components';

docs/src/content/docs/deployment/docker-proxy.mdx

@@ -1,6 +1,6 @@
 ---
-title: Docker — Proxy Mode
-description: Run the REP gateway as a reverse proxy in front of nginx or Caddy.
+title: Docker Proxy Mode — Gateway in Front of nginx or Caddy
+description: Deploy the REP gateway as a reverse proxy in front of nginx or Caddy. Multi-stage Dockerfile, runtime environment variable injection into HTML responses.
 ---
 
 import { Aside } from '@astrojs/starlight/components';

docs/src/content/docs/deployment/kubernetes.mdx

@@ -1,6 +1,6 @@
 ---
-title: Kubernetes
-description: Deploy REP with ConfigMaps, Secrets, sidecars, and hot reload in Kubernetes.
+title: Kubernetes Deployment — ConfigMaps, Secrets, and Hot Reload
+description: Deploy REP in Kubernetes with ConfigMaps for public vars, Secrets for sensitive vars, sidecar patterns, and hot reload via file watch. Includes health probes and Service config.
 ---
 
 import { Aside } from '@astrojs/starlight/components';