Docsite deploy & Access gate

How the Ark docsite (apps/docs) ships to Cloudflare Pages, and the one-time setup that gates it to @7hoenix.com. Decision record: RFC 0002.

How deploys work

.github/workflows/docs-deploy.yml publishes to the Cloudflare Pages project ark-docs (production URL https://ark-docs.pages.dev):

• Automatically on every push to main that touches docs/**, apps/docs/**, PLAN.md, any CHANGELOG.md, or the workflow itself.
• Manually via the workflow’s workflow_dispatch (re-deploys whatever main points at).

The job builds with moon run docs:build (→ apps/docs/dist), then runs wrangler pages deploy apps/docs/dist --project-name ark-docs --branch main.

One-time setup

The repo has the code; these account-level steps are done once and can’t live in git.

1. API token

Create at https://dash.cloudflare.com/profile/api-tokens → Create Custom Token:

Field	Value
Permissions	Account → Cloudflare Pages → Edit
	Account → Workers Scripts → Edit (so the same token also serves worker-deploy.yml)
Account Resources	Include → your account (the judgment-trainer account)

Copy the token (shown once) and set it as a repo secret:

gh secret set CLOUDFLARE_API_TOKEN --repo 7hoenix/ark

CLOUDFLARE_ACCOUNT_ID is only needed if the token spans multiple accounts (a single-account token auto-infers it); set it the same way if wrangler asks.

2. Create the Pages project

Once, so CI has a project to deploy into (CI is non-interactive and won’t create it):

cd apps/docs
bun x wrangler pages project create ark-docs --production-branch=main

(Or dashboard → Workers & Pages → Create → Pages → Direct Upload, name ark-docs.)

After this, a manual workflow_dispatch of docs · Deploy (or the next docs merge) publishes the site.

3. Access gate (@7hoenix.com)

In Zero Trust (https://one.dash.cloudflare.com) → Access → Applications → Add an application → Self-hosted:

1. Application domain: ark-docs.pages.dev.
2. Policy: name it (e.g. 7hoenix only), Action Allow, Include → Emails ending in → @7hoenix.com.
3. Login methods: One-time PIN works with no IdP (email a code); or wire Google/GitHub.
4. Save. The site now shows a login wall; only @7hoenix.com addresses get through. No app code.

Preview deployments (*.ark-docs.pages.dev) are not gated by this — only the production domain. Add a wildcard application later if previews need gating.

Manual / local deploys

cd apps/docs
mise exec -- bun run build         # sync + astro build → dist/
mise exec -- bun run deploy        # wrangler pages deploy dist --project-name ark-docs --branch main

(Local deploy needs wrangler login or CLOUDFLARE_API_TOKEN in the environment.)

Adding a custom domain (later)

1. Pages project → Custom domains → add docs.7hoenix.com (requires the zone on Cloudflare).
2. Update site in apps/docs/astro.config.mjs to the new URL.
3. Point the Access application at the new domain (or add it).