Website Update Workflow

Public site: https://www.apex.fan

Deploy target: Cloudflare Pages, build output directory = www/.

Purpose: make future site updates repeatable, safe, and easy to hand to any agent.

What Belongs On The Site

www/ is public. Treat every file in this directory as already published to the internet.

Allowed:

• Product and methodology descriptions.
• Synthetic sample reports.
• Public ADRs and public manuals.
• Provider-agnostic setup instructions.
• Links to GitHub source files.

Not allowed:

• Real reports from reports/.
• Real cases from cases/.
• Raw material from raw/ or anchors/*/raw/.
• Internal Feishu / Lark links.
• Customer names, exact financial figures, or confidential project details.

If a real report needs to become public, generate a Set B public export first, run the public safety checks, and get explicit approval before copying anything into www/.

Standard Update Steps

1. Inspect the current site and local source.

curl -I -L https://www.apex.fan
shasum www/index.html /tmp/apex-index.html

2. Edit only public files.

Typical files:

• www/index.html
• www/changelog.md
• www/changelog.html — generated from changelog.md, do not hand-edit (see below)
• www/docs.html
• www/installation.md
• www/user-manual.md
• www/deployment.md
• README.md
• www/sitemap.xml

3. Run public safety checks.

python3 scripts/check_public_safe.py --root www
python3 scripts/redact_check.py --dry-run README.md www/index.html www/changelog.md www/installation.md www/user-manual.md www/deployment.md

4. Confirm reports are not staged.

git status --ignored --short reports cases writing/reports-export
git diff --cached --name-only

The status for generated reports should remain ignored (!!) or untracked but unstaged. Do not git add reports/ cases/ writing/reports-export/.

5. Commit public code and docs.

git add README.md www/
git commit -m "docs(site): update public website"

6. Push to the Cloudflare production branch.

Cloudflare Pages is configured to deploy from main.

git switch main
git pull --ff-only origin main
git merge --ff-only <feature-branch>
git push origin main

If the feature branch cannot fast-forward into main, open a GitHub PR and merge it normally after checks pass.

7. Verify Cloudflare deployment.

curl -I -L https://www.apex.fan
curl -I -L https://www.apex.fan/sitemap.xml
curl -L https://www.apex.fan | shasum

The production homepage hash should match www/index.html after the Cloudflare build completes.

Release Checklist

• [ ] www/ has no real report content.
• [ ] scripts/check_public_safe.py --root www passes.
• [ ] scripts/check_public_safe.py --root handbook-src passes (if handbook changed).
• [ ] redact_check.py --dry-run passes for changed docs.
• [ ] pnpm --dir handbook-src run build succeeds locally (if handbook changed).
• [ ] git diff --cached --name-only contains only intended code/docs (no www/handbook/ build artifacts).
• [ ] reports/, cases/, and writing/reports-export/ are not staged.
• [ ] Commit is pushed to main.
• [ ] https://www.apex.fan returns HTTP 200.
• [ ] https://www.apex.fan/sitemap.xml returns HTTP 200.
• [ ] https://www.apex.fan/handbook/ returns HTTP 200 (if handbook changed).

Common Updates

Add A New Capability To The Homepage

Update:

• Hero eyebrow or subtitle.
• Relevant FAQ entry.
• www/changelog.md only — then run python3 scripts/gen_changelog_html.py to regenerate www/changelog.html. The HTML is deterministically generated from the Markdown (chrome is preserved, only the <main> article region is rewritten); never hand-edit it. CI test test_committed_html_is_generated_from_md red-lights any drift.
• README.md current status.

Add A New Public Doc

Update:

• Add the file under www/.
• Link it from www/docs.html or www/index.html.
• Add it to www/sitemap.xml.

Add Or Update A Handbook Page (/handbook/, ADR-008)

The handbook is a VitePress site built from handbook-src/. Build output lands at www/handbook/ (gitignored). Do not edit www/handbook/ directly.

Edit:

• Add or update handbook-src/<section>/<page>.md. Frontmatter (title, description) is required.
• Update handbook-src/.vitepress/config.ts sidebar if the page is new.
• Local preview: pnpm --dir handbook-src run dev (defaults to http://localhost:5173/handbook/).

Safety checks (in addition to standard www/ checks):

python3 scripts/check_public_safe.py --root handbook-src
python3 scripts/redact_check.py --dry-run handbook-src/**/*.md

Build verification before push:

pnpm --dir handbook-src install --frozen-lockfile
pnpm --dir handbook-src run build
# Inspect handbook-src/.vitepress/dist for the page

Cloudflare Pages runs the same build on push. If the build fails, the entire www/ deploy fails — preview deploy on a feature branch first.

Publish A Public Report

Default answer: do not publish real reports.

If explicitly approved:

1. Generate Set B public export.
2. Run redact_check.py on the public Markdown.
3. Run check_public_safe.py on the destination directory.
4. Copy only the approved public artifact into www/showcase/ or another public directory.
5. Add a clear synthetic/public-status note on the page.

Rollback

If Cloudflare publishes a bad site:

1. Revert the Git commit on main.
2. Push main.
3. Confirm Cloudflare redeploys the reverted commit.

git switch main
git revert <bad-commit>
git push origin main