Publishing Pipeline

Confirmed source of truth

The wiki source lives in:

/home/clay/wiki/content/

The Quartz project lives in:

/home/clay/wiki/

The GitHub repository is:

https://github.com/claydunker-yalc/wiki

The publishing branch is:

v4

The Cloudflare Pages project is:

wiki

The live custom domain is:

https://wiki.claydunker.com

The Cloudflare Pages deployment subdomain is:

https://wiki-96d.pages.dev

Confirmed production pipeline

The wiki now uses push-to-deploy through GitHub Actions and Wrangler.

commit approved changes
  → push to claydunker-yalc/wiki branch v4
  → GitHub Actions workflow .github/workflows/deploy.yml runs
  → npm ci
  → npx quartz build
  → npx wrangler pages deploy public --project-name wiki --branch v4
  → Cloudflare Pages production deployment
  → wiki.claydunker.com serves the new build behind Basic Auth

The Cloudflare Pages project wiki is still a Direct Uploads project. It is not Git-connected in Cloudflare.

Verified reason: Cloudflare rejected attaching GitHub directly to the existing Direct Uploads project with this error:

You cannot update the `source` object in a Direct Uploads project.

Therefore, GitHub Actions is the confirmed deploy trigger.

GitHub Actions workflow

Workflow file:

.github/workflows/deploy.yml

Trigger:

on:
  push:
    branches:
      - v4

Build command:

npx quartz build

Deploy command:

npx wrangler pages deploy public \
  --project-name wiki \
  --branch v4 \
  --commit-hash "${GITHUB_SHA}" \
  --commit-message "$(git log -1 --pretty=%s)"

GitHub repository secrets required:

CLOUDFLARE_ACCOUNT_ID
CLOUDFLARE_API_TOKEN

The Cloudflare API token should remain narrowly scoped:

Account → Cloudflare Pages → Edit
Account → Account Settings → Read

Scope:

Specific account → 50231022de6e539f91fea81fb0850102

No DNS, Workers, Zone, WAF, or account-wide extra permissions are needed for the deploy workflow.

Confirmed deployment tests

The first workflow deployment succeeded from commit:

d299a1dc650dbe70ab71e77d1c804fcf7bf83caf

Cloudflare deployment:

9ed086c9-e999-4a49-bae6-ac03714f83a4
https://9ed086c9.wiki-96d.pages.dev

The second push-to-deploy test succeeded from commit:

baf3fbc1be431acd92a364fd27b7879689112278

Cloudflare deployment:

400ef4e1-da45-4255-8a2e-63a09d4d372f
https://400ef4e1.wiki-96d.pages.dev

These confirm that a push to origin/v4 runs the GitHub Action and produces a Cloudflare Pages production deployment.

Custom domain access gate

wiki.claydunker.com is intentionally protected by a Cloudflare Worker Basic Auth route.

Worker route:

wiki.claydunker.com/* → claydunker-private-site-guard

The same Worker also protects other hostnames through separate routes. Do not remove or modify those routes unless explicitly requested.

The unauthenticated custom domain response is expected to be:

HTTP 401 Authentication required.

Authenticated access should return:

HTTP 200

The current local credential handoff file is:

/home/clay/.hermes/private/wiki-basic-auth.txt

That file is local-only, permissioned 0600, and should not be committed.

URL submission intake flow

The wiki includes a URL submission form at:

https://wiki.claydunker.com/submit/

Submission plumbing:

content/submit.md
  → POST /api/submit-url
  → Cloudflare Pages advanced worker public/_worker.js
  → GitHub issue in claydunker-yalc/wiki
  → labels: wiki-submission, automation-intake

The source worker lives in:

cloudflare/wiki-submission-worker.js

The deploy workflow copies the worker into the built public/ directory after Quartz builds and before Wrangler uploads the site.

Runtime requirements for the worker:

GITHUB_TOKEN — Cloudflare Pages secret with permission to create issues in claydunker-yalc/wiki
GITHUB_REPO  — optional plain env var; defaults to claydunker-yalc/wiki

The worker only accepts submissions from wiki.claydunker.com, localhost, or 127.0.0.1. This prevents the public Pages preview host from being used as an unauthenticated intake endpoint.

Queued submissions are governed by Auto-Ingestion Rubric. Routine submissions that pass the threshold may be auto-published; uncertain submissions stay review-first.

Approved-ingestion publishing flow

For normal article ingestion, use this review-first flow:

1. Donn receives an article link in the wiki ingestion channel using the wiki: trigger.
2. Donn digests the source and proposes wiki changes in review-first mode.
3. Donn shows the planned article, author, Big Idea, claim, synthesis, and cross-link updates before writing or committing.
4. Donn applies the [[plain-language-style-guide|Plain-Language Style Guide]] to new or revised Big Idea titles, claim titles, definitions, claim statements, practical implications, and link aliases while preserving stable URL slugs unless a path is actively misleading.
5. After Clay approves, Donn writes Markdown under /home/clay/wiki/content/.
6. Donn shows changed files and git diff.
7. Donn runs local validation:
   - npx quartz build
8. Donn commits approved changes to branch v4.
9. Donn pushes to origin v4.
10. GitHub Actions builds and deploys to Cloudflare Pages.
11. Donn watches the GitHub Actions run.
12. If the workflow fails, Donn does not retry automatically; Donn reports the failure mode and relevant log.
13. If the workflow succeeds, Donn reports the Cloudflare deployment ID and deployment URL.
14. Donn verifies the live custom domain behind Basic Auth.

Verification commands

Check workflow runs:

gh run list --repo claydunker-yalc/wiki --workflow deploy.yml --branch v4

Watch a workflow run:

gh run watch <run_id> --repo claydunker-yalc/wiki --exit-status

List Cloudflare Pages deployments:

npx wrangler pages deployment list --project-name wiki

Verify the custom domain with local Basic Auth credentials:

cred_file="$HOME/.hermes/private/wiki-basic-auth.txt"
user_val=$(grep '^BASIC_AUTH_USER=' "$cred_file" | cut -d= -f2-)
pass_val=$(grep '^BASIC_AUTH_PASS=' "$cred_file" | cut -d= -f2-)
curl -sS -u "$user_val:$pass_val" -o /dev/null -w '%{http_code} %{url_effective}\n' https://wiki.claydunker.com/
curl -sS -u "$user_val:$pass_val" -o /dev/null -w '%{http_code} %{url_effective}\n' https://wiki.claydunker.com/references/

Expected authenticated result:

200 https://wiki.claydunker.com/
200 https://wiki.claydunker.com/references/

Rollback paths

There are two rollback paths.

Rollback path 1: Cloudflare dashboard rollback

Cloudflare Pages keeps deployment history for Wrangler deployments.

Use:

Cloudflare dashboard
→ Workers & Pages
→ wiki
→ Deployments
→ All deployments
→ Rollback to this deployment

This rolls the active Cloudflare Pages deployment back without changing Git history.

Rollback path 2: Git revert and push

Use Git when the source history itself should be corrected:

git revert <bad_commit_sha>
git push origin v4

The push triggers GitHub Actions, which builds and deploys the reverted source state.

Safety gates

Before committing or pushing ingestion-generated content:

show proposed file changes,
show the git diff,
run local Quartz build,
get Clay’s approval,
do not deploy manually unless asked,
let the GitHub Action deploy from v4,
watch the run and report success or failure.

Current operational rule

Push to v4 is now live deploy behavior.

Treat every push to origin/v4 as a production deployment to Cloudflare Pages, with wiki.claydunker.com remaining behind the Worker Basic Auth gate.

Clay's Wiki

Collections