docs: move experiments from Internals to Contributing section

.github/workflows/site-build.yml

@@ -19,6 +19,7 @@ jobs:
       - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
         with:
           ref: ${{ github.event_name == 'pull_request' && github.event.pull_request.head.sha || github.sha }}
+          submodules: true
 
       - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
         with:

docs/admin-oauth-worker.md

@@ -2,7 +2,7 @@
 
 This document describes intentional behavior of the **Cloudflare site Worker** that backs the admin SPA (`cloudflare_site/worker/`), especially CORS for `GET /api/github/user` and why there is **no** separate “admin OAuth enabled” boolean in configuration.
 
-For local setup and env vars, see [`web/admin/README.md`](../web/admin/README.md). For CI and deploy layout, see [`docs/site-deployment.md`](site-deployment.md).
+For local setup and env vars, see [`web/admin/README.md`](../web/admin/README.md). For CI and deploy layout, see [`docs/web-admin-deployment.md`](web-admin-deployment.md).
 
 ## `GET /api/github/user` CORS: missing `Origin`
 

docs/doc-site.md

@@ -0,0 +1,46 @@
+# Documentation site
+
+The documentation site is built with **[VitePress](https://vitepress.dev/)**. Markdown source lives in `docs/`, site configuration in `website/.vitepress/config.ts`, and build output in `website/dist/`.
+
+## Local development
+
+```bash
+cd website
+npm ci
+npm run dev
+```
+
+The dev server starts on `http://localhost:5173/docs/`. Submodules (e.g. `experiments/`) are initialized automatically via a `predev` hook — no manual `git submodule` step needed.
+
+## Building
+
+```bash
+cd website
+npm run build
+```
+
+A `prebuild` hook runs `git submodule update --init` before the VitePress build, matching CI behavior.
+
+## How it works
+
+- `docs/` contains all markdown content, organized by section (agents, guides, ADRs, etc.)
+- `website/.vitepress/config.ts` defines the sidebar navigation and markdown processing
+- `getMarkdownFiles()` auto-discovers markdown files and subdirectory READMEs for dynamic sidebar sections (ADRs, experiments, design docs, specs, plans)
+- Symlinks connect submodule content into `docs/` (e.g. `docs/experiments` → `../experiments`)
+
+## Submodules
+
+Some doc content lives in separate repositories linked as git submodules:
+
+| Submodule | Path | Docs symlink |
+|-----------|------|-------------|
+| [fullsend-ai/experiments](https://github.com/fullsend-ai/experiments) | `experiments/` | `docs/experiments` → `../experiments` |
+
+The `predev` and `prebuild` hooks in `website/package.json` handle initialization automatically for local dev. CI uses `submodules: true` on `actions/checkout` in `.github/workflows/site-build.yml`.
+
+## CI/CD
+
+- **`.github/workflows/site-build.yml`** — builds the VitePress site on PRs and pushes to `main`, uploads the artifact
+- **`.github/workflows/site-deploy.yml`** — deploys the built artifact to Cloudflare Workers on `main` pushes, uploads preview versions on PRs
+
+For Cloudflare Worker setup, secrets, and troubleshooting, see [`web-admin-deployment.md`](web-admin-deployment.md).

docs/experiments

@@ -0,0 +1 @@
+../experiments