Internal Docs Cloudflare Access¶

Use this runbook to make the LeafEnterprise implementation docs available to internal team members.

Target¶

Item	Value
Public team URL	`https://docs.leaf-enterprise.com/`
Cloudflare Pages project	`leafenterprise-docs`
Access application	`leafenterprise-docs`
Identity provider	Existing `LeafEnterprise Entra ID` Cloudflare Access provider
Temporary fallback	One-time PIN only during rollout, then remove
Source artifact	`docs-site/site` from `python -m mkdocs build -f docs-site/mkdocs.yml --strict`

GitHub Secrets¶

Add these repository secrets before expecting CI deployment to Cloudflare Pages:

Secret	Purpose
`CLOUDFLARE_ACCOUNT_ID`	Cloudflare account that owns `leaf-enterprise.com`.
`CLOUDFLARE_API_TOKEN`	Token allowed to deploy the `leafenterprise-docs` Pages project.

The workflow still builds and uploads the GitHub Pages artifact if Cloudflare secrets are missing. The Cloudflare deploy step runs only when both secrets exist.

Current account id resolved from the live leaf-enterprise.com zone:

278b9888f005d78f1f57c085b4ad0b0d

The API token used for CI must include Cloudflare Pages project/deployment permissions for this account. A token that can only read Access and zone metadata is not sufficient for wrangler pages project list or wrangler pages deploy.

Cloudflare Pages Setup¶

Create a Pages project named leafenterprise-docs.

For the first live deployment, the workflow can deploy the generated static folder:

python scripts\generate_docs_api_reference.py --check --check-route-coverage
python scripts\validate_docs_semantic_registry.py
python -m mkdocs build -f docs-site\mkdocs.yml --strict
npx wrangler@latest pages deploy docs-site/site --project-name leafenterprise-docs --branch main

Attach the custom domain:

docs.leaf-enterprise.com

Then make docs.leaf-enterprise.com the URL shared with employees and agents.

Cloudflare Access Setup¶

Create a self-hosted Access application:

Field	Value
Name	`leafenterprise-docs`
Domain	`docs.leaf-enterprise.com`
Policy	Allow internal employees
IdP	`LeafEnterprise Entra ID`
Selector	`Emails ending in @leafhealth.net` or a dedicated Entra group
Session duration	Short internal session, aligned to the existing LeafEnterprise apps

If the Entra login is not yet validated for docs, keep One-time PIN as a temporary fallback. Remove OTP after two clean employee validations.

Pages.dev Exposure¶

Do not leave leafenterprise-docs.pages.dev as an unprotected bypass. Use one of these controls:

configure Cloudflare Access over the Pages preview/production hostname when available for the project,
redirect the pages.dev hostname to docs.leaf-enterprise.com,
or avoid sharing pages.dev URLs and validate that custom-domain Access is the only team-facing route.

Validation¶

Run these checks after deployment:

Check	Expected result
unauthenticated `https://docs.leaf-enterprise.com/`	Redirects to Cloudflare Access.
clean browser session	Shows `LeafEnterprise Entra ID` login.
authenticated employee	Loads docs homepage and search.
`https://docs.leaf-enterprise.com/llms.txt`	Loads after authentication.
`https://docs.leaf-enterprise.com/machine/system-authority.json`	Loads after authentication.
`https://docs.leaf-enterprise.com/machine/api-reference.json`	Loads after authentication.
`leafenterprise-docs.pages.dev`	Not a public bypass.

Agent Access¶

Human users should authenticate through Entra-backed Cloudflare Access. Future non-human agents should use a separate Cloudflare Access service-token policy for docs retrieval. Do not reuse human sessions for background MCP or indexing jobs.