Skip to content

docs: rewrite Agent UI guide — lead with features, not plumbing#641

Draft
kovtcharov wants to merge 7 commits intomainfrom
kalin/docs-agent-ui-guide-updates
Draft

docs: rewrite Agent UI guide — lead with features, not plumbing#641
kovtcharov wants to merge 7 commits intomainfrom
kalin/docs-agent-ui-guide-updates

Conversation

@kovtcharov
Copy link
Copy Markdown
Collaborator

@kovtcharov kovtcharov commented Mar 27, 2026

Summary

Rewrites the Agent UI guide to lead with the user experience instead of technical setup.

Structure changes:

  • New hero intro that shows what the agent does, not what it is
  • "What You Can Do" moved above install — features first, plumbing second
  • Install section simplified — prerequisites folded into the Python CLI tab where relevant
  • MCP section condensed — server/client merged with card links instead of long prose

Content additions:

  • Uninstall instructions (npm + Python CLI) with data cleanup steps
  • MCP Client section with timeout warning for misconfigured servers
  • LLM timeout troubleshooting accordion
  • Example prompts as blockquotes for visual weight
  • File format support table (replaces bullet-list wall)
  • Video demo placeholder (commented out until asset is uploaded)

Fixes:

  • Missing --ui flag in port troubleshooting example
  • Windows-compatible commands in troubleshooting (Get-Content vs cat)

Test plan

  • Verify docs render correctly on Mintlify (mintlify dev)
  • Confirm all internal links resolve (/guides/mcp/client, /guides/mcp/agent-ui, /setup)
  • Record and upload Agent UI demo video to assets.amd-gaia.ai

kovtcharov and others added 3 commits March 27, 2026 15:38
…shing

setup-node with registry-url creates an .npmrc that sets NODE_AUTH_TOKEN,
which overrides OIDC authentication. Removing it lets npm use the OIDC
token from the id-token permission directly.
Prevents rc/alpha/beta tags from updating the release branch
which publishes documentation.
…, examples

- Add uninstall instructions (npm + Python CLI) with data cleanup
- Add video demo placeholder for upcoming recording
- Add MCP Client section explaining ~/.gaia/mcp_servers.json configuration
- Add LLM timeout troubleshooting for misconfigured MCP servers
- Expand "What You Can Do" with example prompts for each capability
- Expand Session Management with actionable how-to details
- Fix Windows compatibility in troubleshooting (Get-Content vs cat)
- Soften Warning box to Note to reduce friction for new users

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@github-actions github-actions bot added documentation Documentation changes devops DevOps/infrastructure changes labels Mar 27, 2026
Restructure to show what the agent can do before install instructions.
Add hero intro, blockquote examples, format table, condensed MCP section.
All technical content preserved.
@kovtcharov kovtcharov changed the title docs: improve Agent UI guide docs: rewrite Agent UI guide — lead with features, not plumbing Mar 29, 2026
- Hardware disclaimer no longer kills momentum after the hero intro
- Sessions + keyboard shortcuts merged into one compact section
- MCP section reduced to card links — power users click through
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

devops DevOps/infrastructure changes documentation Documentation changes

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant