Gaia Preview

---
name: gaia-preview
description: >
  Use this skill whenever the user wants to see how their branch will look on the live Gaia
  website before merging — "preview this branch", "show me what this looks like", "deploy a
  preview", "trigger a design preview", "can I see the site with these changes", "preview the
  skill profile", "check how this renders on the site", "spin up a preview deployment". This
  skill dispatches a Cloudflare Worker preview deployment for the current branch via GitHub
  Actions — no local build tooling required. Ideal for containerized environments, design
  reviews, and confirming that newly curated skills or profile pages render correctly before
  a PR is merged to main. The preview does NOT regenerate docs; it deploys `docs/` from the
  branch as-is. If your change depends on regenerated Class S artifacts, run `gaia dev docs`
  and commit those first — the preview then reflects them.
---

# 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:
   ```bash
   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:
   ```bash
   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:
```bash
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.