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

[olamide226]

Makes the documentation site ingestible by AI agents, and fixes the 404 every docs path returned when suffixed with .md.

Plain-text Markdown mirrors

Every page now has a mirror at the same path with a .md suffix — /reference/sdk.md, /concepts/wire-format.md, and so on (46 pages, plus /index.md for the landing page).

docs/src/lib/to-markdown.ts converts MDX to clean Markdown rather than serving raw source, so agents don't have to parse JSX:

Source	Output
import … from '@astrojs/starlight/components'	dropped
<Aside type="caution">	> **Caution** blockquote
<TabItem label="Docker"> / <Card title="…">	bold label, body dedented to the wrapper's indent
<LinkCard title href description />	- [title](href) — description
<Tabs> / <Steps> / <FileTree>	unwrapped; bodies are already valid Markdown

The transform is code-fence aware, so the pages that document JSX (<RepScript />, Next.js layouts, component examples) pass through untouched. Verified across all 46 files: no leftover component tags, no stray imports, even code-fence parity everywhere.

Entry points for agents

• /agents.md — a single-page integration playbook. Decision tree for choosing gateway mode, dev tooling and client API; tier classification rules; install matrix across all npm packages, the Docker image and the raw binary; five copy-paste recipes (SPA migration, Docker embedded, Docker proxy, Kubernetes sidecar, local dev); the client API with the behavioural contracts that change how code is written against it (get() is synchronous, the first getSecure() decrypts everything, SSE connects lazily); gateway flag/env/endpoint tables; ten failure modes; and a verification checklist. It also renders as a normal docs page and appears in the sidebar.
• /llms.txt — indexed by sidebar section with descriptions, linking to the .md URLs.
• /llms-full.txt — the complete documentation set as one file (~187 KB).

Content-type handling

Cloudflare Pages serves .md as text/markdown, which browsers download rather than render. A _headers override fixes that, but the wildcard form wasn't safe to assume: Cloudflare documents a splat as greedily matching all characters and doesn't document a /*.md suffix pattern as supported.

docs/src/integrations/md-headers.mjs therefore enumerates the rules explicitly from the real build output — 49 rules against a 100-rule limit, with a build warning if that is ever approached. public/_headers is generated rather than hand-maintained, so it can't drift from the routes.

Supporting changes

• The sidebar moves out of astro.config.mjs into docs/src/sidebar.mjs, shared by Starlight and the /llms.txt route so the index can't drift from the nav.
• A Starlight Head override adds <link rel="alternate" type="text/markdown"> to each page, making mirrors discoverable from the HTML without guessing the convention.
• SITE_URL consolidated into docs/src/site.mjs.
• README gains a "For AI agents" section and header links.
• Syncs the stale published copy of rep-manifest.schema.json (copy-schemas.mjs output that had drifted from schema/).

Verification

• pnpm build succeeds; all 48 mirrors plus both llms files generated.
• pnpm check — 0 errors, 0 warnings, 0 hints.
• Dev server serves /reference/sdk.md, /llms.txt and /agents.md with content-type: text/plain; charset=utf-8.
• Content in agents.md cross-checked against source: gateway env var names against gateway/internal/config/config.go, the Kubernetes sidecar against deployment/kubernetes.mdx, CLI flags and the rep bin name against cli/package.json.

[greptile-apps]

Greptile Summary

Summary

• The Kubernetes hot-reload example correctly describes the mounted .env reload source, but its update command modifies a separate ConfigMap key instead of that file.
• As written, operators following the command retain the prior feature-flag value after the gateway reloads.

Confidence Score: 5/5

The documented update command should be corrected, but this is a non-blocking documentation defect.

The remaining issue is limited to the Kubernetes documentation: the example patch creates a second ConfigMap entry while the configured gateway continues reading the unchanged .env entry. greptile-apps[bot] resolved the previously reported Kubernetes reload recipe without explanation; the current documentation now uses a mounted env-format file and passes it through --env-file, which addresses that issue.

Files Needing Attention: docs/src/content/docs/deployment/kubernetes.mdx

T-Rex Logs

What T-Rex did

• T-Rex produced finding-comment-proofs for two posted P2 findings.
• T-Rex ran a general-contract-validation-proof to validate the patch against the ConfigMap and envfile semantics, and performed the work locally due to the lack of a Kubernetes client or cluster access.
• T-Rex captured and organized artifacts from the validation run to support reviewer inspection.

_{Ran code and verified through T-Rex}

Comments Outside Diff (2)

1. docs/src/content/docs/deployment/kubernetes.mdx, line 163-164 (link)

   Patch updates wrong key

   The documented ConfigMap stores all reloadable values in its single .env key, and the gateway reloads only /config/.env. This patch instead adds a separate REP_PUBLIC_FEATURE_FLAGS key, so Kubernetes mounts a new /config/REP_PUBLIC_FEATURE_FLAGS file while /config/.env retains its old value. The documented update appears to reload successfully but does not deliver the requested feature-flag value to connected clients.

   Artifacts

   
   

   Evidence from the check

   • Authored Python harness that applies the documented patch to the documented ConfigMap shape and parses only `/config/.env`, establishing the tested path.

   Command output from the check

   • Executed baseline command shows the sole `.env` key mounts as `/config/.env` and yields `REP_PUBLIC_FEATURE_FLAGS=dark-mode`, establishing the comparison point.

   Command output from the check

   • Executed patched command shows a new ConfigMap key and separate mounted file while `/config/.env` remains unchanged and the gateway still reads `dark-mode`, confirming no requested feature-flag reload.

   

   _{Ran code and verified through T-Rex}

2. General comment

   Hot-reload patch updates a new ConfigMap key rather than the mounted env file

   • Bug
     • The patch at lines 163-164 adds data.REP_PUBLIC_FEATURE_FLAGS. The configured dynamic ConfigMap stores all variables under the .env key, which mounts as /config/.env; the gateway reload path reads only that file. Consequently the requested dark-mode,ai-assist value is mounted as separate /config/REP_PUBLIC_FEATURE_FLAGS and does not reload into the gateway.
   • Cause
     • The patch payload addresses a top-level data key named REP_PUBLIC_FEATURE_FLAGS instead of replacing or updating the contents of data[".env"].
   • Fix
     • Patch the .env ConfigMap entry with complete updated env-file content, or generate and kubectl apply an updated ConfigMap manifest whose .env value contains REP_PUBLIC_FEATURE_FLAGS=dark-mode,ai-assist.

   _{Ran code and verified through T-Rex}

_{Reviews (2): Last reviewed commit: "fix(docs): correct the Kubernetes hot-re..." | Re-trigger Greptile}