docs: full documentation audit (accuracy, dark-mode diagrams, persona review)#1982
Merged
Conversation
…ona review Sweep of the published docs against main (guides, C++, reference, connectors/security, integrations/deployment). Fixes reader-facing breakage: mermaid diagrams were unreadable in dark mode (sequence-message and flowchart edge-label text rendered dark-on-dark); the CLI/feature reference listed removed commands; the connectors page described a fictional catalog; the Browser Agent guide was too thin; and an invalid FontAwesome icon rendered blank. SDK, specifications, playbooks, and roadmap/releases sections land in follow-up commits on this branch.
github-actions
Bot
added
documentation
added 2 commits
July 9, 2026 13:19
…amples Verified every SDK doc example against src/gaia/. Fixed examples that would crash on copy-paste: RAGSDK.indexed_files treated as a dict (it's a set), an async audio callback signature, an agent-ui system_prompt TypeError, and a removed `gaia mcp add` / `timeout=` MCP usage. Aligned the tool-mixins list with registry.KNOWN_TOOLS and corrected config env-var names that were no-ops.
The C++ docs audit changed the Lemonade base URL from 13305 to 8000 to match a stale LEMONADE_DEFAULT_URL constant in the C++ source (cpp/include/gaia/ lemonade_client.h). But Lemonade Server actually listens on 13305, so 8000 does not work for users. Restore 13305 across the C++ docs (also fixes a pre-existing stale 8000 in bash-agent's env-var table). Note: cpp/include/gaia/lemonade_client.h and cpp/include/gaia/types.h still hardcode 8000 as the default — that is a separate source-level bug to fix.
Contributor
|
🟡 The routing guide now points developers to the wrong file for CLI integration.
🔍 Technical details
-CLI integration: `src/gaia/cli.py` (search for "RoutingAgent")
+CLI integration: `hub/agents/python/code/gaia_agent_code/cli.py` (search for "RoutingAgent")
|
Contributor
Verdict: ✅ ApproveThis is a documentation-only audit (Pass 1) that reconciles the published docs against No blocking issues, no security concerns. Docs-only, so no tests/eval are required. 🔍 Technical detailsClaims verified accurate against the codebase:
Strengths:
Minor process note (non-blocking): the eval scenario/category counts (91 / 12) are stamped "at the time of writing" with a dynamic-discovery caveat — a sensible hedge, but they will drift as scenarios are added. |
added 2 commits
July 9, 2026 13:51
The C++ framework hardcoded http://localhost:8000/api/v1 as the default Lemonade endpoint, but the production Lemonade Server (what users install) listens on 13305 — so C++ agents failed to connect out-of-the-box unless the user set LEMONADE_BASE_URL/GAIA_CPP_BASE_URL. This is also what the C++ integration CI already uses (build_cpp.yml starts lemonade-server on 13305). Updates LEMONADE_DEFAULT_URL and types.h defaultBaseUrl to 13305, the matching unit-test assertions, the integration-test env fallbacks, examples, and README. URL-normalization unit tests keep 8000 as arbitrary input (port-agnostic). The Python CLI CI is unchanged: it uses lemonade-server-dev, which binds to 8000.
Reconciled the spec reference pages (core, SDKs, infrastructure, code internals, tool mixins, agents/apps) against src/gaia and the hub agent packages: corrected class/method/signature drift, fixed stale module paths for agents that moved to hub/agents/python/<id>/, aligned the tool-mixin pages with registry.KNOWN_TOOLS, and applied the dark-mode mermaid fix where diagrams exist.
github-actions
Bot
added
mcp
…, links) Playbooks: verified the step-by-step tutorials (chat, code, emr, hardware-advisor, sd, custom-installer) run in order against the current CLI/source — fixed stale agent paths (hub/agents/python/<id>/), commands, and applied the dark-mode mermaid fix. Roadmap/plans + release notes: link and dark-mode-diagram fixes only; historical release content left intact, and roadmap design docs not rewritten (shipped/stale items flagged for a maintainer, not edited).
itomek
approved these changes
Jul 10, 2026
4 tasks
pull Bot
pushed a commit
to bhardwajRahul/gaia
that referenced
this pull request
Jul 11, 2026
…ports) (amd#1988) ## Why this matters Follow-up to the documentation audit (amd#1982), fixing the three items that were flagged for a maintainer decision. Before: the "Supported LLMs" reference listed pre-Lemonade OGA/ONNX-hybrid models (Phi-3.5, Llama-2, Mistral) and dead installer names — actively misleading for anyone choosing a model today; several roadmap docs described already-shipped features as "Planning"; and a container plan's `EXPOSE` list contradicted its own port table. After: model docs match what GAIA actually runs (Lemonade GGUF/FLM), shipped work is marked shipped, and ports are consistent. ## What changed - **`reference/features.mdx` + `reference/faq.mdx`** — replaced the stale OGA hybrid model tables (and empty "generic installer" table) with the current Lemonade model set, verified against source (`lemonade_client.py`, `init_command.py` profiles): `Gemma-4-E4B-it-GGUF` (default), `Qwen3.5-35B-A3B-GGUF` (agents), `Qwen3-4B-Instruct-2507-GGUF` (summarize), `Qwen3-VL-4B-Instruct-GGUF` (VLM), `embeddinggemma-300m-GGUF` (RAG), FLM NPU models, `SDXL-Turbo`. Fixed the silent-install example from the dead `gaia-windows-setup.exe` to the current NSIS artifact name. - **Roadmap plans** — status corrected to reflect reality: `agent-hub-ui` Phase 0 (agents already in `hub/agents/python/`), `image-agent` (SD ships as `gaia sd`), `vision-sdk` (VLM SDK ships in `src/gaia/vlm/`), and the email agent row in `email-calendar-integration` (now `hub/agents/python/email/`). Designs left intact — only status/paths corrected. - **`plans/docker-containers.mdx`** — `EXPOSE` lines had a stale `8000` and omitted `8080`; aligned to the doc's own port table → `3000 5174 8080 13305 9229 9222`. ## Test plan - [ ] `reference/features` "Supported LLMs" matches `src/gaia/llm/lemonade_client.py` + `src/gaia/installer/init_command.py` profiles. - [ ] No remaining `gaia-windows-setup.exe` / `GAIA_Installer.exe` / `onnx-hybrid` references in reference docs. - [ ] `docs/plans/docker-containers` EXPOSE list matches its port table. - [ ] Roadmap status notes render and read correctly. Co-authored-by: Ovtcharov <kovtchar@amd.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why this matters
A full audit of the published documentation against
main. It fixes reader-facing breakage across the whole docs surface: mermaid diagrams that were unreadable in dark mode (sequence-message and flowchart edge-label text rendered dark-on-dark — e.g. the flagged Wi-Fi agent diagram); CLI/feature reference pages that documented removed commands; a connectors page that described a fictional catalog; a Browser Agent guide too thin to use; SDK examples that would crash on copy-paste; and the C++ framework defaulting to a Lemonade port (8000) that the server doesn't use (13305). After: diagrams are legible in both themes, documented commands/APIs match the code, and examples run.Every change was verified against the latest
main: CLI reconciled via actual-houtput, Python/C++ examples checked againstsrc/gaia/+hub/agents/python/+cpp/(with import smoke tests), links checked againstdocs/docs.json, and each page reviewed through developer / end-user / enterprise / ISV personas. The dark-mode mermaid fix was validated by rendering both themes.Scope (7 commits)
indexed_filesset/dict bug, async audio callback, agent-uisystem_promptTypeError, removedgaia mcp add).hub/agents/python/<id>/), tool-mixins aligned toregistry.KNOWN_TOOLS.8000→13305in the C++ source, tests, examples, and README (this is what the C++ integration CI already uses). Python-CLI CI keeps8000because it useslemonade-server-dev, which binds there.Notable correctness fixes
gaia generate,groundtruth,batch-experiment,eval -d,visualize) → current commands.cli.mdx: addedmcp serve, eval flags (--agent-type/--iterations/--keep-sessions/--device); connectors doc reflectsgaia mcp add/removeremoval.stars(rendered blank) →wand-magic-sparkles.2.1→2.2.Test plan
cpp/wifi-agent,guides/sd,guides/routing,sdk/sdks/rag).PYTHONPATH=src python -m gaia.cli -hand spot-checkreference/cli.mdxmatches (incl.schedule,config,uninstall,knowledge,mcp serve).13305default (build_cpp.ymlintegration job already targets 13305).docs/docs.json).docs/browsereads completely; its flag table matchesgaia browse -h.Follow-ups flagged (not changed here)
faq.mdx/features.mdx(Phi-3.5, Llama-2 …).agent-hub-uiPhase 0,image-agent/vision-sdksupersets) — maintainer call.plans/docker-containersDockerfileEXPOSElist includes8000, inconsistent with its own port table.