Site ops — deploy and access

Status note: one-time cloud setup. The code in this repo is complete; the steps below need an org/cloud admin and are not done by the docs PR.

Hosting (Cloudflare Pages, free)

1. Cloudflare dashboard → Workers & Pages → Create → Pages → Connect to Git → select BloxClips/docs (private org repo).
2. Production branch: main. Preview deployments: on (every docs PR gets a URL).
3. Build settings:
   • Build command: npm run docs:build
   • Output directory: .vitepress/dist
   • Node version: 20 or above.
4. No environment variables required. No functions/ or redirects are used.

Team-only access (Cloudflare Zero Trust Access)

Pages URLs are public by default. To gate the site to the team:

1. Cloudflare dashboard → Zero Trust → Access → Applications → Add → Self-hosted → point at the Pages *.pages.dev domain.
2. Policy: Allow, configured with your identity provider (e.g. Google Workspace / GitHub OAuth limited to org members / approved emails).
3. Verify in an incognito window: unauthenticated visits are challenged, team identities pass through to the docs.

Local preview

npm install
npm run docs:dev      # hot-reload draft loop
npm run docs:build    # must stay clean before every docs PR
npm run docs:preview  # serve the production build locally

Conventions

• Markdown files are the source of truth; AI tooling reads the raw .md.
• Never commit .vitepress/dist, .vitepress/cache, or node_modules.
• Keep filenames stable — GitHub issues and code PRs link to these paths.
• Docs PRs target main and link their counterpart code PRs explicitly.
• Links starting with ../ (e.g. ../AGENTS.md, ../.agents/skills/*) or pointing at sibling checkouts (Bloxclips-backend/…, absolute /home/… paths) resolve in the outer BloxClips workspace checkout, not on this site. They are preserved intentionally; the site build does not dead-link-check them (see ignoreDeadLinks in .vitepress/config.mts).