Skip to content

REVIEW NOTES

Jump to bottom
Pedro Gomes Branquinho edited this page Feb 15, 2026 · 1 revision

Wiki Agent-Readability Review

Goal: Can an AI agent set up hive-mcp by reading these docs with ZERO human intervention?

Overall Score: 7/10 - Good foundation but placeholders block automation

Universal Issues

Critical: Placeholder Problem

/path/to/hive-mcp appears ~18 times across all pages. Agents cannot:

  • Copy-paste commands with placeholders
  • Know what to substitute without human guidance

Fix: Use $HIVE_MCP_DIR environment variable consistently, with setup instruction at start.

docker-compose Inconsistency

  • Some pages: docker-compose (hyphen, v1)
  • Other pages: docker compose (space, v2)

Fix: Standardize on docker compose (v2 is current)

Per-Page Gaps

Home.md

  • Session-Continuity not in quick links table
  • Seed-Memories not in quick links table
  • Step 4 path ./start-bb-mcp.sh is relative
  • Missing prerequisite verification step

Installation.md

  • BB_MCP_DIR assumes ~/projects path
  • Step 6 daemon doesn't explain persistence
  • Step 7 hardcoded path ~/projects/hive-mcp
  • Step 8 verification shows prose not command

Infrastructure-Setup.md (Best: 8/10)

  • /path/to/hive-mcp placeholder x3
  • Free-tier models list may be outdated
  • Missing: behavior WITHOUT OpenRouter

Emacs-Configuration.md (7/10)

  • /path/to/hive-mcp placeholder x4
  • (getenv "DOTFILES") is user-specific
  • YOUR-PROJECT-UUID-HERE unexplained
  • start-bb-mcp.sh vs start-mcp.sh confusion
  • Missing Doom sync verification

Troubleshooting.md (7/10)

  • /path/to/hive-mcp x5
  • No table of contents
  • Missing Session-Continuity in Related Pages
  • Missing seed memory troubleshooting

Session-Continuity.md (6/10)

  • /path/to/hive-mcp x3
  • docker-compose vs docker compose inconsistent
  • Not listed in Home.md quick links
  • Missing: does catchup work WITHOUT Chroma?

Seed-Memories.md (NEW - needs review)

  • Review for placeholder usage
  • Verify tool names match implementation

Priority Fix Order

  1. P0: Replace all /path/to/hive-mcp with $HIVE_MCP_DIR pattern
  2. P0: Add Home.md quick links for Session-Continuity and Seed-Memories
  3. P1: Standardize docker compose (no hyphen)
  4. P1: Add prerequisite verification commands
  5. P2: Explain optional components (OpenRouter, Chroma fallback)
  6. P2: Add table of contents to Troubleshooting.md

Agent Quick Setup Pattern

For agent-readable docs, each page should have:

## Agent Quick Reference
1. Set environment: `export HIVE_MCP_DIR=/path/to/your/clone`
2. Commands to run (copy-paste ready)
3. Verification command with expected output

Clone this wiki locally