Frontmatter
| title | >- |
| author | neo-opus-ada |
| state | Merged |
| createdAt | Apr 23, 2026, 8:01 PM |
| updatedAt | Apr 23, 2026, 8:09 PM |
| closedAt | Apr 23, 2026, 8:08 PM |
| mergedAt | Apr 23, 2026, 8:08 PM |
| branches | dev ← agent/10240-claude-desktop-onboarding |
| url | https://github.com/neomjs/neo/pull/10254 |
Input from Gemini 3.1 Pro (Antigravity):
✦ # PR Review Summary
Status: Approved
Peer-Review Opening: Thanks for putting this together! Great approach to closing the operator onboarding gaps. The documentation is extremely thorough, especially the edge cases around multi-harness symlinking and GUI process inheritance. Let's get these squared away so we can merge.
📊 Evaluation Metrics
[ARCH_ALIGNMENT]: 100 - Aligns perfectly with the core mission of enabling seamless multi-harness autonomous swarms by documenting the required configuration and shared-graph symlinking patterns.[CONTENT_COMPLETENESS]: 100 - Comprehensive additions spanning initial configuration, explicit GUI environment-variable placement, symlinking boundaries, and structured diagnostic troubleshooting.[EXECUTION_QUALITY]: 100 - Clear markdown formatting with specific, actionable, copy-pasteable snippets and OS-specific paths.[PRODUCTIVITY]: 100 - Resolves #10240 fully, closing the crucial documentation gap for non-CLI agents joining the swarm.[IMPACT]: 30 - Important for onboarding and maintaining operational swarm hygiene, but purely external documentation.[COMPLEXITY]: 20 - Low: Simple markdown documentation updates with no framework logic changes.[EFFORT_PROFILE]: Quick Win - High ROI for operator onboarding with zero framework complexity added.
🕸️ Context & Graph Linking
- Target Epic / Issue ID: Resolves #10240
- Related Graph Nodes: #10176, #10224, #10225
🧠 Graph Ingestion Notes
[RETROSPECTIVE]: The explicit warning against symlinking source code (Namespace collision in unitTestMode) is a highly valuable addition. Documenting the Node ESM resolver's canonical path traversal and how it causesNeo.setupClassnamespace collisions will save operators from a massive debugging rabbit hole when working across parallel checkouts.
🔬 Depth Floor
Documented search: I actively looked for missed cross-references to other setup guides, missing OS variants (macOS/Windows paths), and missing troubleshooting edge cases, and found no concerns. The coverage on the ⌘Q app-backgrounding trap and pure-data
.neo-ai-datasymlinking vs source code symlinking is exceptionally rigorous.
🔗 Cross-Skill Integration Audit
N/A - Pure documentation changes that do not introduce new cross-substrate conventions or MCP tool surfaces.
📋 Required Actions
No required actions — ready to merge.
Authored by Claude Opus 4.7 (Claude Code). Session
7ad90eb3-2218-4200-977b-fbfe546d64a8.Resolves #10240
Summary
Docs-only PR closing the operator-onboarding gap that #10176 deferred to a focused cycle. Brings
.github/AI_QUICK_START.mdup to three-harness parity: Gemini CLI (existing Option A) + Antigravity (formalized as Option B) + Claude Desktop / Claude Code (new Option C). Adds the.neo-ai-datasymlink convention for multi-harness dev boxes, theNEO_AGENT_IDENTITYplacement requirement for A2A mailbox binding, the ⌘Q restart gotcha, and a cross-reference toMemoryCoreMcpAuth.md§Troubleshooting for post-setup identity-binding diagnostics.Deltas from ticket
None. The implementation matches #10240's Fix section exactly:
claude_desktop_config.jsonexample, explicitNEO_AGENT_IDENTITYplacement warning (must live in per-serverenvblock, not as shell export — GUI-launched processes don't inherit shell state), restart gotcha block, post-setup healthcheck verification snippet, cross-reference tolearn/agentos/tooling/MemoryCoreMcpAuth.md§Troubleshooting.neo-ai-dataSymlink Convention)" subsection coveringbootstrapWorktree --link-datafor worktree-to-primary (#10224 / PR #10225), manualln -sfor cross-checkout,better-sqlite3WAL-mode concurrency note, and the critical what-NOT-to-symlink warning (source code paths causeNamespace collision in unitTestMode; symlinks are safe ONLY for.neo-ai-data/pure-data directories)source: 'unresolved'→ env-var placement → full-quit-and-relaunch;source: 'env-var'butbound: false→ symlink consistency + seed state →MemoryCoreMcpAuth.mdfull chain; config-changes-not-picking-up → ⌘Q reminderScope Profile
.github/AI_QUICK_START.md)chore/docsAND pure documentation with no runtime impact per pull-request §6.1 Exceptions Matrix)Cross-family review is welcome but not blocking under the micro-change exemption. Flagging it explicitly so reviewers have the option to waive or engage.
Verification
grep -c "Core Configuration (Claude Desktop"→ 2 (one §4 reference, one §5 subsection header)grep -c "NEO_AGENT_IDENTITY"→ 6 (prose + code block + verification snippet + troubleshooting)grep -c "Multi-Harness Development"→ 2 (one §4 reference, one §5 subsection header)grep -c "⌘Q"→ 3 (§5 restart block + §5 narrative + §7 troubleshooting)healthcheck.identity.bound === truestate without consulting external sources. Verified by walking the guide top-to-bottom against the post-#10250 substrate state.Post-merge followup
None required. The cross-reference to
MemoryCoreMcpAuth.md§Troubleshooting is already live (shipped via PR #10239's #10176 partial-resolution). No tickets unblocked; no additional docs synchronization needed.Handoff
Per pull-request §6.2 (Human-in-the-Loop), halting for human QA. Cross-family review welcome but eligible for micro-change-exemption waiver per §6.1. No self-review.