Skip to content

Cloudflare Pages Doc Site — Setup Spec

Goal: Auto-syncing, mobile-friendly documentation site so Jeff can read rendered workspace docs from anywhere (iPhone, iPad, hotel wifi, cellular).

Design Principle: Site structure mirrors local directory structure. Same names, same hierarchy. No reorganization.

Stack

  • MkDocs + Material theme — static site generator, best-in-class markdown rendering
  • mkdocs-awesome-pages plugin — auto-generates nav from directory tree (no manual config)
  • Wrangler CLI — Cloudflare's deploy tool
  • fswatch + cron — auto-detect changes, rebuild + deploy

Cost

  • $0/month — Cloudflare Pages free tier (500 builds/month, unlimited bandwidth)
  • $0/month — Cloudflare Access free tier (up to 50 users, email-based auth)

Setup Steps

Jeff's Part (one-time, ~10 minutes)

  1. Create Cloudflare account
  2. Go to https://dash.cloudflare.com/sign-up
  3. Use business email (ops@viverevitalis.com or personal — your call)

  4. Free plan is all we need

  5. Create an API token for Jules

  6. Dashboard → My Profile → API Tokens → Create Token
  7. Use template: "Edit Cloudflare Pages"
  8. Scope: Account-level, Pages only

  9. Copy the token and send it to Jules (Signal or Telegram DM, not group chat)

  10. Optional: Set up Cloudflare Access

  11. Zero Trust → Access → Applications → Add Application
  12. Self-hosted, protect the Pages URL
  13. Policy: Allow emails matching yours (one-time click-through auth via email code)
  14. This keeps docs private — only you can view them

Jules's Part (automated after token received)

  1. Install local tooling 

    pip install mkdocs mkdocs-material mkdocs-awesome-pages-plugin
npm install -g wrangler

  2. Configure Wrangler auth

  3. Store API token in ~/.wrangler/config.toml or env var

  4. Verify with wrangler pages project list

  5. Create MkDocs project

  6. mkdocs.yml at workspace root with Material theme config
  7. Configure docs_dir pointing to publishable content
  8. Auto-nav from directory structure via awesome-pages plugin

  9. Exclude patterns: memory/, MEMORY.md, HEARTBEAT.md, *.secret, etc.

  10. Create Cloudflare Pages project 

    wrangler pages project create vv-docs

  11. Build + deploy script (scripts/deploy-docs.sh) 

    #!/bin/bash
cd /Users/viverevitalis/.openclaw/workspace
mkdocs build --clean
wrangler pages deploy site/ --project-name vv-docs

  12. Auto-sync daemon (launchd plist)

  13. fswatch monitors publishable directories
  14. On change: debounce 10s → run deploy script

  15. Cron backup: rebuild + deploy every 30 minutes as safety net

  16. Test + verify

    • Deploy initial site
    • Verify on iPhone/iPad via cellular
    • Confirm directory tree matches local structure
    • Confirm auth works (if Cloudflare Access enabled)

What Gets Published

Included: - initiatives/ — briefs, specs, research, status docs - research/ — standalone research docs - specs/ — this file and other specs - skills/ — skill documentation (public-safe parts) - Any future docs/ directory content

Excluded (never published): - memory/ — daily logs, heartbeat state - MEMORY.md — long-term memory (private) - USER.md — personal info - HEARTBEAT.md — internal ops - *.env, *.secret, credentials - SOUL.md, IDENTITY.md — internal agent config - AGENTS.md — operational playbook

End Result

  • URL: vv-docs.pages.dev (or custom domain later)
  • Mobile: Bookmark on iPhone/iPad, works on any connection
  • Features: Search, sidebar nav, dark mode, responsive layout
  • Sync: ~30 seconds from local edit → live on site
  • Maintenance: Zero — fully automated after setup

Timeline

  • Jeff's part: 10 minutes whenever convenient
  • Jules's part: ~1 hour after receiving API token
  • Total: live same day