Mention browser mcp in AGENTS.md

Author: st0012

AGENTS.md

@@ -213,6 +213,26 @@ Use Red, Green, Refactor approach:
 3. Check output in `_site/` directory
 4. Check coverage: `bundle exec rake coverage`
 
+### Modifying Themes/Styling
+
+When making changes to theme CSS or templates (e.g., Darkfish or Aliki themes):
+
+1. **Generate documentation**: Run `bundle exec rake rerdoc` to create baseline
+2. **Start HTTP server**: Run `cd _site && python3 -m http.server 8000` (use different port if 8000 is in use)
+3. **Investigate with sub-agent**: Use Task tool to launch a general-purpose agent to inspect the documentation with Browser MCP
+   - The agent will connect browser to `http://localhost:8000`, navigate pages, and take screenshots
+   - Agent reports findings back (styling issues, layout problems, etc.)
+   - This saves context in main conversation
+4. **Make changes**: Edit files in `lib/rdoc/generator/template/<theme>/` as needed
+5. **Regenerate**: Run `bundle exec rake rerdoc` to rebuild documentation with changes
+6. **Verify with sub-agent**: Use Task tool again to launch agent that uses Browser MCP to verify fixes
+   - Agent takes screenshots and compares to original issues
+   - Agent reports back whether issues are resolved
+7. **Lint templates** (if modified): Run `npx @herb-tools/linter "lib/rdoc/generator/template/**/*.rhtml"`
+8. **Stop server**: Kill the HTTP server process when done
+
+**Tip:** Keep HTTP server running during iteration. Just regenerate with `bundle exec rake rerdoc` between changes.
+
 ## Notes for AI Agents
 
 1. **Always run tests** after making changes: `bundle exec rake`
@@ -221,3 +241,35 @@ Use Red, Green, Refactor approach:
 4. **Use `rake rerdoc`** to regenerate documentation (not just `rdoc`)
 5. **Verify generated files** with `rake verify_generated`
 6. **Don't edit generated files** directly (in `lib/rdoc/markdown/` and `lib/rdoc/rd/`)
+
+## Browser MCP for Testing Generated Documentation
+
+Browser MCP allows AI agents to visually inspect and interact with the generated HTML documentation. This is useful for verifying CSS styling, layout issues, and overall appearance.
+
+**Repository:** <https://github.com/BrowserMCP/mcp>
+
+### Setup
+
+If Browser MCP is not already installed, users should:
+
+1. Install the BrowserMCP Chrome extension from the Chrome Web Store
+2. Run: `claude mcp add --scope user browsermcp npx @browsermcp/mcp@latest`
+3. Connect a browser tab by clicking the BrowserMCP extension icon and selecting "Connect"
+
+### Testing Generated Documentation
+
+To test the generated documentation with Browser MCP:
+
+```bash
+# Generate documentation
+bundle exec rake rerdoc
+
+# Start a simple HTTP server in the _site directory (use an available port)
+cd _site && python3 -m http.server 8000
+```
+
+If port 8000 is already in use, try another port (e.g., `python3 -m http.server 9000`).
+
+Then navigate to the appropriate URL (e.g., `http://localhost:8000`) in your connected browser tab and ask Claude to use browser MCP tools (e.g., "use browser MCP to navigate to <http://localhost:8000> and take a screenshot").
+
+**Note:** Browser MCP requires a proper HTTP server (not `file://` URLs) for full functionality. The generated documentation must be served via HTTP/HTTPS.