Skill: gaia-preview

Dispatches a Cloudflare Worker preview deployment for the current branch. The deploy uses the branch's docs/ folder as-is — no gaia dev docs step runs on the runner — so what you see is exactly what production would serve if this branch merged.

When to use

• You've made design, layout, or content changes and want to see them live before opening a PR.
• You're working in a container or remote environment where localhost is unavailable.
• You want to verify a newly curated skill or contributor profile renders correctly on the site.
• You've edited docs/ files and want a sanity check before merging.

Steps

1. Push your work. Commit and push all local changes to the current branch. The workflow runs against what's on the remote, so anything uncommitted won't appear in the preview.

2. Dispatch the preview workflow. Run:

   gh workflow run cf-pr-preview.yml \
     --ref "$(git rev-parse --abbrev-ref HEAD)" \
     -f branch="$(git rev-parse --abbrev-ref HEAD)"

   The --ref selects which copy of the workflow file runs; -f branch=… is the actual branch that gets deployed. In practice these are the same value (the current branch), but the workflow's branch input is a required parameter and must be passed explicitly — omitting it makes the workflow default to main.

3. Report the run + preview URL. After dispatching:

   gh run list --workflow=cf-pr-preview.yml --limit 1

   Give the user the run URL from that output. The preview itself is at a stable workers.dev URL determined by wrangler.toml's name field and the account subdomain — for this project:

   https://gaia-skill-tree.marco-tngsn.workers.dev/

   Each successful deploy overwrites the previous one at that URL, so there's only ever one branch previewable at a time. The workers.dev URL is NOT posted as a workflow output; it's constant, and you report it directly. The deploy usually completes in under a minute (48s on the last measured run) — wait for gh run view <id> --json conclusion -q .conclusion to return success before pointing the user at the URL.

Notes

• Do not use sync-artifacts.yml -f deploy=true. That workflow is gated on github.ref_name == default_branch and silently returns skipped in ~3 seconds on any non-main branch. It's the production release workflow, not the branch-preview workflow.
• The single-slot preview URL is a real constraint. If two people dispatch previews on different branches close together, whichever finished second is what the URL serves. Coordinate before overwriting a coworker's preview.
• The preview will NOT reflect uncommitted regen output. If your branch touches registry/nodes/ or registry/named/ and you haven't committed the Class S artifacts (docs/graph/* — regenerated by gaia dev docs), the preview will render the stale docs. Commit the regen first.

Local inspection (fastest path)

For a quick local look without waiting on the remote build, serve docs/ directly:

python -m http.server 8080 --directory docs

Then open http://localhost:8080/. This serves the static site exactly as GitHub Pages would, minus the Cloudflare Worker badge-validation layer.