docs: close residual CLAUDE.md/docs/code alignment gaps (summarize guide, telegram dup, connectors)

[kovtcharov-amd]

Why this matters

#1337 reconciled CLAUDE.md and the CLI reference with the code. A few alignment gaps remain that need content work or product judgment, not a mechanical accuracy fix — tracking them here so they aren't lost.

Gaps

1. gaia summarize has no user guide. It's a real top-level command (and SummarizerAgent), documented now in the CLI reference, but there's no docs/guides/summarize.mdx and no nav entry. Needs a written guide modeled on the other agent guides.

2. Duplicate Telegram guide. docs/guides/telegram.mdx ("Telegram Messaging Adapter… v0.18.2 scaffold") and docs/guides/telegram-adapter.mdx ("Telegram Adapter") both exist; only telegram-adapter is in docs/docs.json. telegram.mdx is an orphan and looks like the older copy. Decide which is canonical and remove/redirect the other.

3. Orphan docs/security/connectors.mdx. Exists but isn't referenced anywhere in docs/docs.json. Either add it to the nav or fold it into the existing connectors/* pages.

4. gaia connectors subcommands undocumented. The command exists (Google/GitHub OAuth + MCP-server connectors with per-agent grants; gaia connectors mcp add/remove per feat(connectors): custom MCP server support (gaia connectors mcp) #977) but has no CLI-reference section and only a one-line CLAUDE.md mention. Enumerate its subcommands and document them.

5. gaia mcp subcommand coverage in cli.mdx. cli.py registers serve, tools, and test-client in addition to the documented start/status/stop/test/agent/docker/add/list/remove — audit and fill the gaps.

Acceptance criteria

• docs/guides/summarize.mdx written and added to docs/docs.json.
• One canonical Telegram guide; the duplicate removed or redirected; nav consistent.
• docs/security/connectors.mdx either in nav or merged away (no orphan).
• gaia connectors and the remaining gaia mcp subcommands documented in docs/reference/cli.mdx.

References

• PR docs: align CLAUDE.md + CLI reference with the code (release-skill fixups) #1337 (the code-accuracy alignment pass this follows)
• src/gaia/cli.py, docs/reference/cli.mdx, docs/docs.json

[github-actions]

All five gaps check out against the current tree — this is a clean, well-scoped follow-up to #1337. Quick verification pass:

1. 🟡 summarize guide missing — confirmed. No docs/guides/summarize.mdx; docs.json only references spec/summarizer-app. Model the new guide on docs/guides/docker.mdx or docs/guides/jira.mdx (similar single-agent shape).

2. 🟡 Telegram duplicate — confirmed. telegram.mdx self-describes as a "v0.18.2 scaffold… implementation in progress", while telegram-adapter.mdx is the configuration guide and the only one in docs.json:72. telegram-adapter is canonical; telegram.mdx is the orphan to remove/redirect.

3. 🟢 docs/security/connectors.mdx orphan — confirmed, no docs.json reference. Note there's already a connectors/ nav group (connectors/index|google|github, docs.json:90-92) plus sdk/infrastructure/connectors — folding it in there is likely cleaner than a standalone security/ nav slot.

4. 🟡 gaia connectors undocumented — confirmed. Subcommand inventory from src/gaia/connectors/cli.py to save the doc writer a pass:

   list · status (alias for list) · connect (OAuth, opens browser) · configure (MCP keys / OAuth client creds) · test (health check) · disconnect · grants {list,grant,revoke} (per-agent scope grants) · activations {list,activate,deactivate} (per-agent MCP tool visibility) · mcp {add,remove} (the feat(connectors): custom MCP server support (gaia connectors mcp) #977 entry point).

5. 🟢 gaia mcp gaps in cli.mdx — confirmed. cli.py:2433/2466/2475 register serve, tools, and test-client, none of which appear in docs/reference/cli.mdx.

No blockers — all four acceptance items are actionable as written. The only real product judgment is #2 (kill vs. redirect telegram.mdx); everything else is mechanical doc work. A maintainer should confirm the canonical Telegram page before deletion.

[kovtcharov-amd]

Progress from #1337 (deeper alignment round): the gaia mcp add/remove staleness is fixed — those moved out of gaia mcp (#977); cli.mdx and CLAUDE.md no longer document them as live commands. Note for whoever picks up item 4: the connectors CLI (src/gaia/connectors/cli.py) does not expose a literal mcp add/remove — its real subtree is connect/config/test/disconnect/list/status/grants {list,grant,revoke}/activations {list,activate,deactivate}. That full subtree still needs a cli.mdx section. Remaining residuals (summarize guide, telegram.mdx dup, security/connectors.mdx orphan) unchanged.

[kovtcharov-amd]

More findings from the round-4 alignment sweep (verifiable, not yet fixed — each needs a rewrite rather than a one-line edit):

1. The MCP client tutorials are built around the removed gaia mcp add/remove. Both docs/guides/mcp/client.mdx (lines 84, 245, 341, 345, 411, 415) and docs/spec/mcp-client.mdx (lines 134, 1347–1363) teach gaia mcp add <name> "<cmd>" / gaia mcp remove, which no longer exist (#977 moved MCP-server config into the connectors framework). These tutorials likely need a rewrite around the current connectors flow, not a find/replace — flagging rather than patching.

2. 61 broken internal links in docs/plans/*.mdx use the .mdx extension in relative links (e.g. […](agent-ui.mdx)); Mintlify wants extensionless ([…](/plans/agent-ui)). Plans are published (17 refs in docs.json). Affected: autonomy-engine, connectors, email-triage-agent, image-agent, messaging-integrations-plan, oem-bundling, security-model. Mechanical but high-volume.

3. docs/spec/llm-client.mdx:385 says model defaults to Qwen3-0.6B-GGUF; the LemonadeClient model param defaults to None and the system default is Gemma-4-E4B-it-GGUF. Needs a fix once the exact client/method it documents is confirmed.

Fixed this round (in #1337): RoutingAgent model row (Qwen3.5-35B-A3B via AGENT_ROUTING_MODEL), spec/agent-base.mdx + spec/autonomous-agent-mode.md model defaults, guides/custom-agent.mdx example model.

[kovtcharov-amd]

Partial mitigation landed in #1337: added accurate deprecation callouts at the top of docs/guides/mcp/client.mdx and docs/spec/mcp-client.mdx so a reader is warned before hitting the removed gaia mcp add/remove commands. Key finding for the eventual rewrite: there is no 1:1 replacement — the old flow took an arbitrary shell command (gaia mcp add <name> "<cmd>"), whereas the new model defines MCP servers as registered connector specs configured via gaia connectors configure <id> --set KEY=VALUE (command/args come from the spec; secrets to keyring; entry persisted to ~/.gaia/mcp_servers.json). So the full rewrite must reflect the connector-spec model, not just swap commands.