docs(guides): reorganize User Guides nav, fill stubs, trim bloated guides

[kovtcharov]

Why this matters

The User Guides were a flat, 22-item sidebar list with three near-empty stub pages and three 700+ line guides padded with duplicate examples and copy-pasted test harnesses — a new user couldn't tell where to start, and the Telegram, Browser, and Analyst agents had effectively no documentation. This restructures the guides into seven logical sub-groups ordered easiest→advanced, brings every stub up to the chat/code quality bar, and trims the bloated guides down to their load-bearing content. Every command and flag was re-verified against src/gaia/cli.py and the agent source, so the docs now match the shipping CLI.

Threads

• Nav reorg (discoverability) — flat 22-page list → seven sub-groups (Setup & Hardware → Core Agents → Developer Tools → Connected Agents → Specialized Agents → Build & Extend → MCP Integration). All pages preserved; no orphans.
• Stub guides filled (missing docs) — telegram-adapter rewritten from a 17-line placeholder into a full guide (install extra, BotFather token, start/stop/status, allow-list, background daemon, per-user sessions); browse and analyze gain prerequisites + next-steps cross-links.
• Bloated guides trimmed (maintainability) — jira 760→388, memory 781→523, emr 695→464, cutting duplicate examples and padded sections while preserving accurate content. Several stale commands/paths fixed against source.
• Frontmatter consistency (polish) — added missing icon (analyze, browse, email, npu, telegram) and description (blender, docker, jira, routing, telegram); every guide now has a consistent title/description/icon triple. Landing page rebuilt to mirror the new groups.

Test plan

• python3 util/check_doc_links.py --internal-only → Broken: 0 (985 links checked)
• Every docs/guides/*.mdx page still referenced in docs.json (no orphans)
• docs.json is valid JSON
• JSX components balanced and in-page anchors resolve in all edited guides
• Visual check of the reorganized sidebar in a local Mintlify preview

[github-actions]

Verdict: Approve with suggestions — safe to merge.

This PR reorganizes the User Guides sidebar into seven sub-groups, fills the Telegram/Browse/Analyst stub guides, and trims the bloated Jira/memory/EMR guides — all on top of the in-flight #1102 routing-migration baseline, which moves DocumentQAAgent and RoutingAgent out of core into standalone gaia-agent-docqa / gaia-agent-routing hub wheels. I checked the code carefully: no stale imports of the old gaia.agents.routing / gaia.agents.docqa paths remain, the tests are guarded with importorskip, the new CI workflows install the right local wheels, and the API-server error path now fails loudly with an install hint instead of degrading. CLAUDE.md was updated to match the move, so nothing self-contradicts.

The one thing worth fixing before merge is small: the new Document Q&A packaging manifest under-declares its filesystem permissions — it registers file write/edit tools but its manifest only lists read access (details below). Non-blocking.

🔍 Technical details

🟢 Minor

DocQA manifest under-declares write permission (hub/agents/python/docqa/gaia-agent.yaml:31-32)

DocumentQAAgent composes FileIOToolsMixin and calls register_file_io_tools() (gaia_agent_docqa/agent.py:27,69), which exposes write/edit tools — but the manifest declares only filesystem:read. The sibling fileio agent, which uses the same mixin, correctly declares both filesystem:read and filesystem:write (hub/agents/python/fileio/gaia-agent.yaml). Manifest permissions are declarative metadata (format-validated in src/gaia/hub/manifest.py, not runtime-enforced), so this is a documentation-accuracy issue rather than a functional bug — but it misleads anyone reading the manifest about what the agent can do.

permissions:
  - filesystem:read
  - filesystem:write

(If the read-only declaration is intentional — i.e. DocQA is meant to be retrieval-only — the cleaner fix is to drop register_file_io_tools() instead, so the manifest and the registered tools agree.)

Strengths

• Migration is consistent end-to-end. The old gaia.agents.routing / gaia.agents.docqa paths are gone from src/, setup.py packages, errors.py FRAMEWORK_PATHS, check_agent_conventions.py (_STANDALONE_ALLOWED now empty), and both lint runners — with matching test updates. No dangling references.
• Fail-loud done right (src/gaia/api/agent_registry.py:157-171): the gaia-code ImportError now re-raises ... from e with an actionable pip install hint and a docs pointer, instead of a bare ValueError. Exactly the no-silent-fallback pattern CLAUDE.md asks for.
• Tests degrade gracefully in a framework-only env via pytest.importorskip("gaia_agent_docqa"/"gaia_agent_routing"), and the test_default_max_steps swap to BuilderAgentConfig is valid — it uses field(default_factory=default_max_steps) so it still exercises the env override.
• CI wiring is correct: routing installed before code (dependency order, not on PyPI yet), both new agent workflows registered in test_gaia_cli.yml's test-summary needs: list, and path filters cover the moved trees.