Skip to content
Adventive Adventive Engineering

04 — Runbook

Add a new project

Section titled “Add a new project”
  1. cp -R _templates/project-skeleton/ projects/<new-project-kebab-name>/
  2. Edit 00-context.md through 05-appendix.md.
  3. (Optional) projects/.pages — add the new folder to the nav order.
  4. Commit on a branch, push, open PR.
  5. Pages produces a preview URL. Verify the new project appears in the left nav.
  6. Merge.

Add a new platform service standard

Section titled “Add a new platform service standard”
  1. mkdir platform/cloudflare/<service>/ (or new vendor under platform/<vendor>/).
  2. Author README.md + numbered SOP sections.
  3. Build the SOP PDF (WeasyPrint per house style).
  4. Commit, PR, merge.

Publish a draft for review without making it public

Section titled “Publish a draft for review without making it public”

Drafts are visible on the Pages preview deployment for the PR. Share that preview URL with the reviewer. The preview is also gated by Cloudflare Access, so only Adventive engineers can read it.

Restrict a single page to a smaller group

Section titled “Restrict a single page to a smaller group”

Default Access policy covers the whole site. To restrict a path (e.g. platform/cloudflare/access/incident-2026-04-XX.md) to a smaller group:

  1. Cloudflare Zero Trust → Access → Applications → Add a second self-hosted app.
  2. Application domain pattern: docs.adventive.dev/platform/cloudflare/access/incident-*.
  3. Policy: members of incident-response JumpCloud group only.
  4. Order: place this app ABOVE the main docs app so the more-restrictive rule wins.

Remove a reader

Section titled “Remove a reader”
  1. Remove the user from the engineering-docs-readers group in JumpCloud.
  2. Cloudflare Access picks up the change on next session refresh (within 24h, or immediately if their session is revoked from the Access dashboard).

Site is down

Section titled “Site is down”
  1. Check Cloudflare Pages → Deployments. Did the most recent deployment fail?
    • If yes: rollback to last good deployment (one click), then debug the build locally with mkdocs serve.
  2. Check Cloudflare Access → is the policy denying everyone? (Common cause: IdP group sync broke.)
  3. If neither: check the Cloudflare status page.

Local development

Section titled “Local development”
Terminal window
cd ~/Documents/Claude/Projects/Adventive\ Engineering/
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
mkdocs serve     # http://localhost:8000, auto-reloads on file change
Section titled “Build fails with “broken link””

mkdocs build --strict rejects broken internal links. The error tells you the source file and the broken target. Fix the link, push again. This is the most common failure mode and exactly why we run strict mode in CI — better to catch in PR than in production.