Deployment

Audience: maintainers publishing docs and configuring CI.

Documentation site (mdbook → Cloudflare Pages)

Flock docs are built with mdbook from book/ and deployed on every push to main that touches book/, docs/, or .github/workflows/docs.yml.

Environment	URL
Production	`https://flock-docs.pages.dev`
Workers subdomain	`https://flock-docs.sgoldbeg.workers.dev` (may vary by account)

Local build

cargo install mdbook mdbook-mermaid --locked   # once
mdbook build book
open book/book/index.html

Live preview:

mdbook serve book --open

./scripts/verify.sh runs scripts/smoke-docs.sh, which includes mdbook build book.

CLI help snapshots

When CLI flags or subcommands change intentionally:

UPDATE_SNAPSHOTS=1 cargo test -p flock-cli cli_help_snapshot

verify.sh runs cli_help_snapshot tests (BL-014). MCP tool names must appear in MCP tools — enforced by scripts/check-mcp-doc-parity.sh (BL-015).

CI workflow

Workflow: .github/workflows/docs.yml

Install Rust toolchain and mdbook
mdbook build book → output in book/book/
cloudflare/wrangler-action uploads book/book/ to Pages project flock-docs

Model A (canonical): GitHub Actions direct upload — not Cloudflare Git integration. Keep CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID in GitHub secrets.

gh workflow run docs.yml   # manual deploy

Required GitHub secrets

Secret	Description
`CLOUDFLARE_API_TOKEN`	Account Settings Read + Cloudflare Pages Edit
`CLOUDFLARE_ACCOUNT_ID`	32-char account ID from dashboard sidebar — not a zone ID

Troubleshooting

Symptom	Fix
Deploy 403	Token lacks Pages Edit for target account
Wrong account ID	Copy from Workers & Pages sidebar, not zone overview
Dashboard build token error	Disconnect Git builds; use Model A CI upload only

Application / CLI releases

The Flock CLI is not yet on crates.io. Install from source:

cargo install --path crates/flock-cli

CI runs ./scripts/verify.sh on every PR and push to main.

Keyboard shortcuts

Flock