Deployment

Audience: maintainers publishing docs and configuring CI.

Documentation site (mdbook → Cloudflare Pages)

Castellan 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://castellan-docs.pages.dev`
Workers subdomain	`https://castellan-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 castellan-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 castellan-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 Castellan CLI is not yet published to crates.io (API still moving). Install from source:

cargo install --path crates/castellan-cli --locked

Semver tags and CI

Step	Command / workflow
Local verify	`./scripts/verify.sh`
Release prep (dry-run publish)	`./scripts/release-prep.sh [version]`
Tag push	`git tag -a v0.1.0 -m "Release v0.1.0" && git push origin v0.1.0`
GitHub Release	`.github/workflows/release.yml` — verify, artifact upload, changelog body

MSRV: rust-version = "1.75" in root Cargo.toml. Release workflow pins toolchain 1.75.

Changelog: CHANGELOG.md (Keep a Changelog format).

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

Keyboard shortcuts

Castellan