Summary

Solid, well-grounded docs PR — the example-agent dependency fix is correct and the new publishing guide is comprehensive and mostly accurate. The one thing to fix before merge: the guide tells users to install agents with gaia agent install <id>, a command that doesn't exist — that's the guide's payoff step, so a new author following it end-to-end hits command-not-found right at "Verify". A handful of smaller CLI-flag/behavior mismatches ride along. No security concerns; no functional code bugs in the dependency change.

I verified the core fix against the codebase: all three example manifests (hub/agents/python/{hello-world,word-count,doc-search}/gaia-agent.yaml) declare api_server: true + mcp_server: true, doc-search genuinely composes RAGToolsMixin/RAGSDK, and [api]/[rag]/[publish] are real extras — so the packaging change is justified and matches the email agent reference.

Issues Found

🟡 gaia agent install is not a real command (guide intro + Step 9)

The gaia agent dispatch map (src/gaia/cli_agent.py:273) has init, version, test, pack, publish, login, configure, health, status — there is no install. The real install paths (per docs/reference/cli.mdx:529) are pip install gaia-agent-<id> (PyPI) or the Agent UI's Hub discover/install panel (POST /api/agents/install). The guide references the nonexistent command in the intro ("installable with one command (gaia agent install <id>)", ~line 9) and in Step 9 (~line 241).

For Step 9:

# Install it like any user (PyPI path):
pip install gaia-agent-my-agent

# …or browse and install it from the Agent UI's Hub panel.

And reword the intro line to "installable with pip install gaia-agent-<id> (or from the Agent UI's Hub panel)".

🟢 gaia agent init --dir flag doesn't exist (Step 1, ~line 61)

The flag is --output / -o (src/gaia/cli_agent.py:89), not --dir.

existing directory, and `--output <parent>` (`-o`) to scaffold elsewhere.

🟢 gaia agent test doesn't run the package's pytest suite (Step 7, ~line 205)

gaia agent test defaults to --lint — static gates (manifest validity, structure, syntax, black+isort), no pytest (src/gaia/cli_agent.py:116, docs/reference/cli.mdx:419). The # runs the package's tests comment overstates it, and the Step 1 note ("tests/ … so they run with no Lemonade server") implies this command runs them.

gaia agent test            # static quality gates (manifest, structure, black+isort); add --live for an LLM smoke test

🟢 Author-side manifest validation points at the wrong schema (Step 3 + Troubleshooting)

workers/agent-hub/schemas/manifest.schema.json is the server-side aggregate manifest — its required block includes latest_version, versions, deprecated, and download_size_bytes, which an author never writes into gaia-agent.yaml. Validating a source manifest against it would spuriously fail. The actual author-side contract is the parser in src/gaia/hub/manifest.py (run via gaia agent test --lint). Worth noting that gaia agent test --lint is the way to validate locally, rather than the JSON schema.

🟢 Comment wording: "mcp … are already core" (all three pyproject.toml)

Functionally the conclusion is correct — the standalone agent's mcp_server interface is a hand-rolled stdio JSON-RPC loop in src/gaia/agents/base/server.py that imports only json/sys, so [api] is genuinely sufficient. But the mcp package is not in install_requires (it's the [mcp] extra); only keyring is core. Since the comment mirrors the established email-agent pattern and the outcome is right, this is cosmetic — consider "the stdio MCP server is built-in; keyring is core" for precision.

Strengths

• The dependency fix is real and verified, not cargo-culted. Each manifest's declared interfaces were checked against the new extras, and doc-search's RAGToolsMixin composition genuinely needs [rag] — the inline comments correctly explain why each extra is required.
• The guide is grounded in actual code — manifest fields, the two-path publish model, immutability/409 semantics, and most CLI commands all check out against cli_agent.py and manifest.schema.json.
• docs.json is valid JSON and the nav entry is sensibly placed after custom-agent.

Verdict

Request changes — only because the gaia agent install command is the guide's headline value prop and its final step, and it doesn't exist; a new author hits a dead end there. All five fixes are one-line doc edits with no code impact. Once the install path is corrected (and ideally the --dir/test/schema nits), this is a clear merge.

🟡 hub/agents/python/*/gaia-agent.yaml — python.dependencies stale after pyproject.toml update

The three example agents had their pyproject.toml dependencies updated to add [api] / [api,rag] extras, but the corresponding gaia-agent.yaml manifests were not updated. They all still declare "amd-gaia>=0.20.0" under python.dependencies, which now diverges from what's actually installed.

These are reference agents that contributors copy. If the catalog exports python.dependencies to the Hub website (it's parsed in manifest.py:585), it'll show the wrong deps; and new authors copying the manifest will write the incomplete extras.

Fix — update each manifest to match pyproject.toml:

# hello-world/gaia-agent.yaml and word-count/gaia-agent.yaml
python:
  dependencies:
    - "amd-gaia[api]>=0.20.0"

# doc-search/gaia-agent.yaml
python:
  dependencies:
    - "amd-gaia[api,rag]>=0.20.0"

🟡 gaia-agent.yaml manifests are out of sync with the updated pyproject.toml files.

This PR bumped three pyproject.toml dependencies:

• hello-world → amd-gaia[api]>=0.20.0
• word-count → amd-gaia[api]>=0.20.0
• doc-search → amd-gaia[api,rag]>=0.20.0

But the corresponding gaia-agent.yaml files weren't updated — all three still declare:

python:
  dependencies:
    - "amd-gaia>=0.20.0"

This matters because the new guide (hub-publishing.mdx) points readers to these three agents as copy-paste reference examples. An author who copies a manifest and sees amd-gaia>=0.20.0 will miss the [api] / [rag] extras their own sidecar or RAG agent needs.

Suggested fix for hello-world and word-count (same change):

  dependencies:
    - "amd-gaia[api]>=0.20.0"

And for doc-search:

  dependencies:
    - "amd-gaia[api,rag]>=0.20.0"