docs: align CLAUDE.md + CLI reference with the code (release-skill fixups)#1337
Conversation
…ase skill Follow-up to #1330. Two defects merged with that change: - The new value-prop-first guidance contradicted the existing "read the last 2-3 notes and match the same tone" step — the prior notes are the dry ones we moved away from, so the skill told the model to both break from and copy them. Now: match their structure and length, explicitly not their tone. - The worked example used `gaia email triage`, which isn't a valid command (the agent is `gaia email`), and described it as IMAP-based when it's Gmail/connector based. Corrected both — the example is otherwise accurate (gaia browse, analyze, and email all exist). Also de-duplicated the banned-phrase list (was in two places, already drifting) and noted that non-CLI highlights (UI/SDK/perf) don't need a command in the heading.
SummaryClean, approve-ready fix — all five changes are correct and none introduce new issues. The most consequential fix is the self-contradiction removal: the old skill told the model both "use value-prop-first tone" and "copy the tone of the last three notes," which are exactly the dry, engineering-first notes the new guidance set out to replace. On the next release run, whichever instruction landed last would quietly win and undo the entire intent of #1330. The fix is surgical: "match structure and length (not tone)" in Step 2, plus the explicit callout that the prior notes predate Generation parameters and their shape — not their dryness — is what to follow. Issues FoundNone. Strengths
VerdictApprove. No blocking issues. The PR is well-scoped (one file, five targeted edits), the motivations are clearly articulated, and the fixes directly address the problems described. |
The stale CLI list is what made the release-skill example look fictional in the first place. Reconciled CLAUDE.md against src/gaia/cli.py on main: - Add real-but-undocumented commands: browse, analyze, email, telegram, stats, memory, diagnostics, agent (custom-agent bundles). - Rename yt -> youtube (the command was renamed). - Remove commands that no longer exist in cli.py: gt, generate, batch-exp, visualize, template. - Agent table: add EmailTriageAgent (agents/email/agent.py); note that browse/ analyze are ChatAgent modes and telegram is a messaging adapter, not agents. - Add agents/email/ to the project structure tree.
|
All changes verify cleanly against SummaryThis is a tightly scoped docs-only follow-up to #1330, fixing three concrete defects: a tone self-contradiction in the release skill, a nonexistent Issues Found🟢 Minor —
|
Reconciling against src/gaia/cli.py and src/gaia/agents/: - gaia browse / gaia analyze invoke BrowserAgent and AnalystAgent (dedicated classes under agents/browser/ and agents/analyst/), not ChatAgent modes as a prior note claimed. Added both to the agent table and corrected the note. - Fixed the summarize row: the class is SummarizerAgent, not SummarizeAgent. - Refreshed the User Guides index to list the guides that actually exist (browse, analyze, email, telegram-adapter, memory, install, custom-agent, hardware-advisor, npu) instead of a stale subset.
gaia eval has exactly one subcommand (agent); gt/generate/groundtruth/
batch-experiment/visualize/fix-code no longer exist in cli.py.
- cli.mdx: drop the groundtruth, batch-experiment, and `gaia eval -f` examples;
rewrite the "Visualize Command" section to document the real `gaia perf-vis`
(llama.cpp performance logs: positional log paths + --show).
- CLAUDE.md: `gaia eval {fix-code|agent}` -> `gaia eval agent` (with --fix), and
drop the bogus `gaia eval --use-claude` / `gaia eval fix-code` from the
concurrency rule prose.
These top-level commands existed in cli.py but had no section in the CLI reference. Added concise sections (modeled on the Email command) with verified options pulled from src/gaia/cli.py, linking to the existing guides where they exist.
The connectors command (Google/GitHub OAuth + MCP-server connectors with per-agent grants) exists in cli.py but was missing from the CLI list; the email guide already references `gaia connectors connect google` for setup.
kovtcharov-amd
changed the title
|
The changes are accurate and thoroughly verified — every command addition, removal, and class rename checked out against Issues🟢 Stale
|
Verified against src/gaia/llm/lemonade_client.py, registry.py, and the agents: - Default model is Gemma-4-E4B-it-GGUF (DEFAULT_MODEL_NAME), not Qwen3-0.6B / Qwen3.5-35B. Fixed the Default Models section and the per-agent column: most agents default to Gemma-4-E4B; only Code/Builder/Jira hardcode Qwen3.5-35B-A3B. - KNOWN_TOOLS was missing code_index, filesystem, scratchpad, browser — added. - "ChatAgent renamed to GaiaAgent in v0.20.0" was false; no GaiaAgent class exists and ChatAgent is current. Marked the rename as planned/not-yet-landed. - Fixed broken plan links: installer.mdx -> desktop-installer.mdx, mcp-client.mdx -> mcp-docs.mdx.
Added agent dirs that existed in code but not the tree (browser, analyst, docqa, fileio, code_index, connectors_demo) and top-level packages (code_index, connectors, filesystem, governance, messaging, scratchpad, web). Fixed the summarize label (SummarizerAgent).
|
This is a well-executed documentation alignment pass — every factual claim I could spot-check against Issues Found🟢 Eval-serial rule overstates scope when
|
`gaia mcp add` and `gaia mcp remove` are no longer in cli.py — only start/status/stop/test/agent/docker/serve/list/tools/test-client remain. Removed the two stale cli.mdx sections (replaced with a note pointing at the connectors framework) and dropped add/remove from the CLAUDE.md mcp line. Verified the connectors CLI does not expose a literal `mcp add`, so the note points to `gaia connectors --help` rather than asserting a specific command.
|
Every factual claim spot-checked against SummaryDocumentation-only sweep across three files ( Issues Found🟢 Minor —
|
Verified against the code:
- RoutingAgent uses routing_model = os.getenv("AGENT_ROUTING_MODEL",
"Qwen3.5-35B-A3B-GGUF") (routing/agent.py:68) — corrected my earlier table
entry that wrongly said Gemma-4-E4B.
- spec/agent-base.mdx: base Agent model_id default is None (resolves to
DEFAULT_MODEL_NAME = Gemma-4-E4B), not Qwen3.5-35B-A3B.
- spec/autonomous-agent-mode.md: GAIA_AUTO_OBSERVE_MODEL default is Qwen3-4B-GGUF
(ui/agent_loop.py:49), not Qwen3-0.6B-GGUF.
- guides/custom-agent.mdx: example model_id default updated to the current
default (Gemma-4-E4B-it-GGUF).
|
Two inaccurate model defaults snuck into the agent table — the same category of staleness this PR is fixing everywhere else. Everything else checks out. SummaryA thorough, well-scoped alignment pass. The author's claim to have verified each item against Issues Found🟡 DockerAgent model column is wrong (
|
…P docs The MCP client guide and spec are built around `gaia mcp add`/`remove`, which were removed in #977 — MCP servers are now defined as connectors and configured via `gaia connectors configure <id> --set KEY=VALUE` (keyring-backed, ~/.gaia/mcp_servers.json). There is no 1:1 command replacement (the old flow took an arbitrary shell command; the new one uses registered connector specs), so a blind find/replace would be wrong. Added an accurate deprecation callout at the top of each doc instead; the full step-by-step rewrite is tracked in #1339.
|
A solid, well-scoped alignment pass that removes a large body of stale content and replaces it with verified facts. The test-plan methodology — grepping source to confirm each claim — is the right approach for a doc-only PR of this scope, and it shows: the overwhelming majority of changes are accurate. Two model assignments in the agent table weren't verified against the actual Issues Found🟡 DockerAgent default model is wrong — it hardcodes
|
zycaskevin
left a comment
zycaskevin
left a comment
There was a problem hiding this comment.
Thanks for doing the alignment pass — the MCP add/remove warning and the stale command cleanup are helpful.
I spotted one docs-accuracy issue in the new Jira CLI section. The new card says Jira is “via the MCP bridge”, but the current CLI path imports and runs gaia.apps.jira.app directly (handle_jira_command says “no MCP needed”), and the existing Jira guide also describes direct Atlassian REST API access.
Suggested tweak: make the card wording match the guide/code, e.g. “Natural-language interface for Jira, Confluence, and Compass using Atlassian credentials / REST APIs.” The --mcp-host / --mcp-port options can still stay in the options table if they are intentionally supported by the app, but the high-level description shouldn’t imply users need the MCP bridge to use gaia jira.
3 participants
Why this matters
Started as a release-skill fix (#1330 follow-up), then became a full CLAUDE.md ↔ docs ↔ code alignment pass — the skill bug was caused by stale agent-facing docs. Everything below was verified against
src/gaia/onmain(removed items return zero hits; added items were read from their definitions).Threads (independently reviewable)
SKILL.md) — fixed the tone self-contradiction,gaia email triage→gaia email, IMAP→Gmail, phrase-list de-dupe.browse/analyzeare BrowserAgent/AnalystAgent (not ChatAgent modes); added them + EmailTriageAgent;SummarizeAgent→SummarizerAgent. CLI list: addedbrowse/analyze/email/telegram/connectors/stats/memory/diagnostics/agent,yt→youtube, removed gone commands (gt/generate/batch-exp/visualize/template),gaia eval {fix-code|agent}→gaia eval agent.cli.mdx) — removed stalegroundtruth/batch-experiment/visualize/gaia eval -f; rewrote "Visualize"→realgaia perf-vis; addedjira/docker/summarize/telegramsections with verified options.Gemma-4-E4B-it-GGUF(DEFAULT_MODEL_NAME), not Qwen3-0.6B/Qwen3.5-35B. Fixed the Default Models section and the per-agent column (most agents → Gemma-4-E4B; only Code/Builder/Jira hardcode Qwen3.5-35B-A3B).code_index,filesystem,scratchpad,browser).connectors,governance,messaging,web, …) that existed in code but not the tree.installer.mdx→desktop-installer.mdx,mcp-client.mdx→mcp-docs.mdx.Test plan
gaia <cmd> -hfor added commands; confirm removed ones fail.src/gaia/agents/*/agent.py(Gemma default; Code/Builder/Jira hardcode Qwen3.5-35B-A3B).KNOWN_TOOLSin CLAUDE.md matchessrc/gaia/agents/registry.py.ls src/gaia/andls src/gaia/agents/.Residual content gaps (missing
summarizeguide, duplicatetelegram.mdx, orphansecurity/connectors.mdx,connectors/mcpsubcommand docs) tracked in #1339.