Documentation Hosting

Status: Active. Last updated April 13, 2026. Purpose: SOC 2 evidence for CC6.1 (Logical Access), CC6.6 (System Boundaries), CC7.1 (Infrastructure Management)

---

Overview

Internal documentation is hosted on Cloudflare Pages with Cloudflare Access (Zero Trust) for email-gated authentication. Docs are not public. Only approved team members can access them via one-time PIN email verification.

URL: https://docs.askflorence.health

---

Architecture

Component	Service	Purpose
Static site generator	VitePress 1.6.x	Builds markdown to static HTML with search + Mermaid
Hosting	Cloudflare Pages	Deploys from GitHub repo, global CDN
Authentication	Cloudflare Access (Zero Trust)	Email-gated one-time PIN access
DNS	Cloudflare	CNAME for docs.askflorence.health
Source	GitHub repo docs/ directory	Single source of truth, version controlled

Deployment

Automatic. Cloudflare Pages is connected to the GitHub repo. Every push to main triggers a rebuild and deploy.

Setting	Value
GitHub repo	askflorencehealth/ask-florence
Production branch	main
Build command	cd docs && npm install && npm run build
Build output directory	docs/.vitepress/dist
Framework preset	None
Auto-deploy	Yes (on every push to main)

No manual deployment needed. Edit a markdown file, push to main, docs update automatically within ~1 minute.

Access Control

Cloudflare Access Application

Setting	Value
Application name	AskFlorence Docs
Application URL	docs.askflorence.health
Type	Self-hosted
Session duration	24 hours
Authentication method	One-time PIN (email-based)
Application ID	87b977b3-56f2-42fb-a680-e41643abbae4
Created	April 13, 2026

Access Policy

Setting	Value
Policy name	Allowed team
Action	Allow
Include rule	Emails
Allowed emails	[email protected], [email protected], [email protected]

How Access Works

1. User visits docs.askflorence.health
2. Cloudflare Access intercepts the request
3. User sees a login screen asking for their email
4. If the email is in the allowed list, a one-time 6-digit PIN is sent
5. User enters the PIN
6. Access is granted for 24 hours (session-based)
7. After 24 hours, re-authentication required

Adding New Users

1. Go to Cloudflare Zero Trust dashboard (one.dash.cloudflare.com)
2. Access controls > Policies > "Allowed team" > Configure
3. Add the new email address to the Include > Emails list
4. Save
5. Update this document

Removing Users

1. Remove their email from the Allowed team policy
2. Their existing session expires within 24 hours (or revoke immediately via Access > Logs)
3. Update this document

---

Local Development

To run docs locally:

cd docs
npm install
npm run dev

Opens at http://localhost:5173 with hot reload, search, and Mermaid rendering.

To build locally (verify before pushing):

cd docs
npm run build

Output goes to docs/.vitepress/dist/ (gitignored).

Authoring conventions (read before adding new docs)

These conventions exist because the Cloudflare Pages build is strict — ignoreDeadLinks is [] in docs/.vitepress/config.ts, so any dead link fails the build and blocks deploy. The rules below prevent the most common breakage class.

1. Cross-repo links MUST be absolute GitHub URLs

When linking from a docs markdown file to source code, IaC, CI workflows, or anything else outside docs/, use the absolute GitHub URL, not a relative path.

✅ [`src/lib/db.ts`](https://github.com/askflorencehealth/ask-florence/blob/main/src/lib/db.ts)
✅ [`infra/modules/ses/`](https://github.com/askflorencehealth/ask-florence/tree/main/infra/modules/ses/)

❌ [`src/lib/db.ts`](../../src/lib/db.ts)
❌ [`scripts/audit/foo.ts`](../../../scripts/audit/foo.ts)

URL shape:

• File: https://github.com/askflorencehealth/ask-florence/blob/main/<path>
• Directory: https://github.com/askflorencehealth/ask-florence/tree/main/<path>/

Use main (not a SHA) so links stay current as files evolve. This matches the convention every GitHub-issue link in these docs already follows.

Why: only the docs/ directory ships to Cloudflare Pages. Relative paths like ../../src/lib/db.ts render correctly when reading the markdown source on GitHub but resolve to a 404 on docs.askflorence.health. Worse, before the fix in PR #129, VitePress would silently let some of these through (anything with a non-.md extension was skipped by the dead-link checker), so they'd ship broken without anyone noticing.

Background: PR #129 (ENG-261) rewrote 43 such links and tightened ignoreDeadLinks to []. Earlier history: commit 4971e81 (April 2026) was the first time we hit this; the v0.15.0 narrow infra/-only suppression let it grow back over the next month.

2. Links inside docs/ use relative paths

Internal links (between docs pages, to docs/audits/, docs/adr/, etc.) stay relative — that's how VitePress generates the navigation graph and live-reload works.

✅ [ADR 0004](../adr/0004-cross-cluster-atlas-privatelink.md)
✅ See the [change log](./change-log.md)

If the target is a directory, ensure it has an index.md — VitePress doesn't auto-resolve README.md as the index. Linking to a directory without index.md fails the build (e.g. [docs/audits/](../audits/) — the audits/ dir has no index.md, so use a GitHub tree/main/ URL instead).

3. Verify locally before pushing

cd docs
npm install   # one-time / on lockfile change
npm run build

Expect build complete in N.NNs. with no errors. If you see Found dead link …, fix it before pushing — the same failure will block the Cloudflare Pages deploy of main and break docs.askflorence.health.

---

Technical Details

VitePress Configuration

• Config: docs/.vitepress/config.ts
• Dependencies: docs/package.json (separate from main app)
• Mermaid: via vitepress-plugin-mermaid
• Search: VitePress built-in local search (no external service)
• Theme: Default VitePress theme with AskFlorence brand colors
• Dead-link policy: ignoreDeadLinks: [] — strict. See "Authoring conventions" above.

Node Version

VitePress requires Node 18+. The main Next.js app runs on Node 25. Use fnm (Fast Node Manager) to switch if needed:

fnm use 22   # for docs
fnm use 25   # for main app (default)

Known Limitations

• vite and esbuild have moderate Dependabot alerts (dev-only build tools, not in production app). Dismissed as tolerable risk until VitePress 2.0 stable releases with vite 6+.
• Email delivery to new askflorence.health Google Workspace may be delayed (domain reputation building). Use personal emails as fallback in the Access policy.

---

SOC 2 Control Mapping

Control	Evidence
CC6.1 (Logical Access)	Email-gated access, named user policy, session expiry
CC6.3 (Access Removal)	Documented removal process, 24-hour session max
CC6.6 (System Boundaries)	Docs isolated on separate subdomain with separate auth
CC7.1 (Infrastructure)	Hosting configuration documented, auto-deploy from repo
CC8.1 (Change Management)	Git-based deployment, all changes tracked in commit history

---

Change Log

Date	Change	By
April 13, 2026	Migrated from Jekyll/GitHub Pages to VitePress/Cloudflare Pages	Taha Abbasi
April 13, 2026	Added Cloudflare Access (Zero Trust) email-gated auth	Taha Abbasi
April 13, 2026	Added [email protected] as fallback email	Taha Abbasi