feat(website): three equal 'ways to use GAIA' + build→publish userguide journey

[kovtcharov]

Why this matters

The landing page funneled everyone through one 'Build → Run → Distribute' pipeline, but GAIA has three distinct audiences who deserve equal footing. The page now presents them as three equal front doors, easiest → hardest:

1. Run agents — install the Agent UI desktop app, pick an agent, go (no code)
2. Embed agents in your app — drop a published agent in as a sidecar / MCP / API
3. Build & publish your own — write one with the SDK, publish via PR

Each card has equal billing and its own CTA (Get the Agent UI · Browse the Hub · Build & publish guide).

The build→publish journey was broken

The build guide (custom-agent.mdx) stopped at a local agent and never told you how to share it. Added a 'Publish and share your agent' section that bridges to the PR-route publishing guide (steps + what's required), framed the local-vs-shareable split up front, and cross-linked hub-publishing back to it.

New build-agent skill

There was a publishing skill (agent-hub-release) but none for building. Added .claude/skills/gaia-build-agent (scaffold → @tool → model → test → hand off to publish), and both guides now point Claude Code users at the two skills.

Test plan

• astro check 0 errors / 0 warnings; astro build against the live hub succeeds
• Landing renders the 3 equal paths; old pipeline copy removed
• MDX tags balanced in both guides (Steps/Card/CardGroup/Tip/Note)
• Reviewer: eyeball the 3-card section + the new 'Publish and share' flow in the rendered docs

Note: depends on nothing else; the new Website CI (PR #1856) will build-check this once merged.

[github-actions]

Verdict: Approve with suggestions — docs + website only, no runtime code.

This PR reframes the landing page from a single "Build → Run → Distribute" pipeline into three equal "ways to use GAIA" cards (run / embed / build), adds a "Publish and share your agent" bridge to custom-agent.mdx, cross-links hub-publishing.mdx, and ships a new gaia-build-agent Claude Code skill. The Astro template, CLI commands (gaia agent init / test --lint), and npm package names all verify correctly.

One thing worth fixing before merge: the new skill's first step says gaia agent init "generates a starter package (the BuilderAgent)" — but those are two different scaffolders. gaia agent init is the CLI command that creates a publishable hub package (gaia-agent.yaml); the conversational BuilderAgent is the Agent-UI feature that creates a local ~/.gaia/agents/ agent. Conflating them could send a developer down the wrong path. Details and a suggested rewrite below.

🔍 Technical details

🟡 Important

Skill Step 1 conflates two distinct scaffolders (.claude/skills/gaia-build-agent/SKILL.md:35-37)
gaia agent init is the CLI hub-package scaffolder (cli_agent.py:75 → emits gaia-agent.yaml + skeleton); the BuilderAgent is the in-Agent-UI conversational scaffolder that writes ~/.gaia/agents/<id>/agent.py (custom-agent.mdx:37-69). The parenthetical "(the BuilderAgent)" is incorrect, and the "For a hub package, gaia agent init…" framing implies the command has a non-hub mode — it doesn't; it always produces a hub package. This is the one place in the PR where the instructions could actively mislead.

1. **Scaffold.** `gaia agent init my-agent` scaffolds a publishable hub package
   (a `gaia-agent.yaml` manifest + skeleton) under the output dir — mirror an
   existing one (e.g. `analyst`, `browser`). Prefer running it under
   `hub/agents/python/<id>/`. (The conversational **BuilderAgent** in the Agent UI
   is the alternative — it writes a *local* `~/.gaia/agents/<id>/agent.py`.)

🟢 Minor

Both publish-section cards share one href (custom-agent.mdx:144,148) — the "Claude Code skills" card links to /guides/hub-publishing, identical to the "Publishing guide" card next to it. Since the card is about the two skills, a more relevant target (or distinct anchor) would reduce the duplicate. Non-blocking.

Strengths

• Template refactor is consistent: every paths entry defines cta/secondary/level/n/title, the old badge field and its conditional render are both removed, and nothing dangling references the dropped step/pipeline names.
• CLI commands in the new docs are real and verified (gaia agent init, gaia agent test --lint in cli_agent.py), and npm names match @amd-gaia/agent-ui (webui package.json) and the existing @amd-gaia/agent-email usage.
• The skill correctly restates the repo's hard rules (No Silent Fallbacks, real-CLI testing, the eval gate for LLM-affecting surfaces) and cleanly delineates build-vs-publish against the existing agent-hub-release skill.

[github-actions]

🟡 The "Package it" step in the new publish section gives a command that doesn't do what it says — a user running it will be confused.

gaia agent init <id> defaults to the current directory (./<id>/). The docs claim it scaffolds under hub/agents/python/<id>/, but that only happens if the user passes -o hub/agents/python/. Without the flag, someone following step 1 will create the package in the wrong place, then hit step 3 ("commit under hub/agents/python/<id>/") and not know how to reconcile.

The new gaia-build-agent SKILL.md (added in the same PR) gets this right — it says gaia agent init <id> -o hub/agents/python/.

🔍 Technical details

cli_agent.py:92: --output defaults to "." (current directory).

docs/guides/custom-agent.mdx:412-413 currently reads:

`gaia agent init <id>` scaffolds a publishable package under
`hub/agents/python/<id>/`

Should be:

`gaia agent init <id> -o hub/agents/python/` scaffolds a publishable package under
`hub/agents/python/<id>/`

[github-actions]

🟡 The new "Publish and share your agent" step in custom-agent.mdx misstates where gaia agent init places the package — a contributor following it will scaffold in the wrong location and then open a PR with the package missing from the expected tree.

The Step 1 prose reads: "gaia agent init <id> scaffolds a publishable package under hub/agents/python/<id>/". That's not true: the default --output is . (current directory), so the package lands wherever the user happens to be running from, not in hub/agents/python/. The SKILL.md added in this same PR gets it right with gaia agent init <id> -o hub/agents/python/ — the user-facing guide just needs to match.

🔍 Technical details

src/gaia/cli_agent.py:90-93 — --output / -o defaults to ".". cmd_init (line 339) resolves Path(args.output) / names.id, so without -o the package lands in <cwd>/<id>/.

The misleading sentence is in docs/guides/custom-agent.mdx, the new <Step title="Package it"> block. Fix options:

`gaia agent init <id> -o hub/agents/python/` scaffolds a publishable package at
`hub/agents/python/<id>/` — a `gaia-agent.yaml` manifest, your agent code, a
README, and `pyproject.toml`. Move your `agent.py` logic in and fill the manifest.

Or omit the path claim and just say "scaffolds a publishable package (use -o hub/agents/python/ when contributing back to the GAIA repo)".

The SKILL.md in this same PR already shows the flag correctly, so this is a single-file fix.