Running & Deploying the Docs

This page is the full, copy-paste walkthrough for running this docs site on your machine and putting it online. Run every command from the repo root (Kairo/), not from inside docs-site/.

Two ways to run locally (pick the right one)

You want to…	Use	Chat works?
Write/preview pages fast (hot reload)	npm run docs:dev	❌ No
Test the AI chat too	wrangler pages dev (below)	✅ Yes

The AI chat needs the Cloudflare Function in functions/api/chat.ts. npm run docs:dev is just VitePress — it never serves /api/chat, so the chat button will fail there. That's expected, not a bug.

Preview content only (no chat)

npm run docs:dev

Opens a hot-reloading dev server (the URL is printed, usually http://localhost:5173). Edit any .md file and it updates instantly. Best for writing.

Run locally with the AI chat

You need a Gemini API key (get one free).

1. Create a file named .dev.vars in the repo root (same folder as package.json). One line — quotes optional:

   GEMINI_API_KEY=AIzaSy...your-key

   It's already gitignored, so it won't be committed.

2. Build the static site (Wrangler serves the built output, not live source):

   npm run docs:build

3. Serve it with Cloudflare's local runtime, which runs the Function:

   npx wrangler pages dev docs-site/.vitepress/dist

   First run may prompt to install wrangler — accept. It auto-loads .dev.vars and auto-detects the functions/ folder.

4. Open the printed URL — usually http://localhost:8788 (the 8788 one, not the docs:dev port). Click the chat button and ask something.

Chat says "function not running" / 404?

You're viewing the docs:dev server. Chat only works under wrangler pages dev. Re-run steps 2–3 and open the :8788 URL.

Changed a page and don't see it under Wrangler?

Wrangler serves a build, not live source. Re-run npm run docs:build after edits. (For fast content iteration, use docs:dev instead and just don't test chat there.)

First-time deploy to Cloudflare Pages

Do this once. After it's set up, deploys are automatic (next section).

1. Push your latest work so the remote is current:

   git add -A
   git commit -m "docs: update"
   git push

2. Go to dash.cloudflare.com and sign in (free account is fine).

3. Left sidebar → Workers & Pages → Create → Pages tab → Connect to Git.

4. Authorize Cloudflare for GitHub, then select the SeiynJie/Kairo repo → Begin setup.

5. On the build-config screen set:

   • Production branch: main
   • Framework preset: None (VitePress isn't in the preset list — leave it None)
   • Build command: npm run docs:build
   • Build output directory: docs-site/.vitepress/dist

6. Expand Environment variables (advanced) → Add variable:

   • Name: GEMINI_API_KEY
   • Value: your key → click Encrypt (stores it as a secret).

7. Click Save and Deploy. Wait ~1–2 min.

8. You get a live URL like https://kairo-xyz.pages.dev. Open it — docs load, and chat works because the repo-root functions/ folder deploys automatically alongside the site.

Forgot the env var?

Chat will just say "AI chat isn't configured yet." Add it later under the project's Settings → Variables and Secrets, then redeploy.

Ongoing deploys (automatic)

Every push to main triggers a rebuild + redeploy. Your PC can be off — the site stays online.

git add -A
git commit -m "docs: update <page>"
git push        # Cloudflare rebuilds automatically

Watch build logs under Workers & Pages → your project → Deployments. A red build is almost always a dead internal link (npm run docs:build fails loudly on those — catch it locally first).

Lock it down

The *.pages.dev URL is public to anyone who has it. To restrict the site to only your GitHub account, see Access Control.