Context

Fast-follow to PR #10239 (#10176 partial resolution). PR #10239 shipped the substrate-observability substrate (healthcheck.identity block + MemoryCoreMcpAuth Troubleshooting refresh). This ticket lands the operator-onboarding docs that were in #10176's AC list but deferred to a focused docs-only cycle.

Scope separation rationale: PR #10239 was load-bearing for immediate A2A diagnostic. These docs are load-bearing for NEW contributor onboarding and survive independent of the healthcheck substrate.

The Problem

.github/AI_QUICK_START.md currently documents two harness options (Gemini CLI + Antigravity). The Claude Desktop harness — which now embeds Claude Code — is absent. Empirically (multiple sessions this week), this created onboarding friction that manifested as identity-unbound failures operators had to diagnose from scratch. Specific gaps:

1. Claude Desktop not listed as a harness Option in §4 "Choosing Your Agent Environment"
2. claude_desktop_config.json path not documented: ~/Library/Application Support/Claude/claude_desktop_config.json is neither obvious nor discoverable
3. NEO_AGENT_IDENTITY env-var placement — must live in the per-server env block, NOT shell export. This distinction cost at least two sessions' worth of diagnostic time.
4. .neo-ai-data symlink convention for multi-harness dev boxes — codified in #10176 as "tactical convention" but never documented in the operator onboarding guide
5. Restart gotcha — MCP config changes require a FULL harness quit (⌘Q on macOS), not just a window close

The Architectural Reality

• .github/AI_QUICK_START.md — the current harness-onboarding entry point (referenced from top-level docs)
• ~/Library/Application Support/Claude/claude_desktop_config.json — the mcpServers source of truth for Claude Desktop (and Claude Code via inheritance, per memory 1639a1a5)
• .neo-ai-data/ symlink convention — documented in #10176 ticket body + #10224 (worktree bootstrap) + PR #10225 (the bootstrapWorktree --link-data flag)
• learn/agentos/tooling/MemoryCoreMcpAuth.md — already updated by PR #10239 with the new healthcheck-based troubleshooting; cross-link from AI_QUICK_START natural

The Fix

Three landing items in .github/AI_QUICK_START.md:

1. §4 "Choosing Your Agent Environment" — add Option C: Claude Desktop (with embedded Claude Code). Position alongside Gemini CLI (Option A) and Antigravity (Option B). Note the shared-config implication.
2. §5 "Understanding the Configuration Files" — new "Core Configuration (Claude Desktop)" subsection with a concrete claude_desktop_config.json shape example showing the mcpServers block for all four Neo servers (memory-core, knowledge-base, github-workflow, neural-link) with NEO_AGENT_IDENTITY shown in the memory-core env block. Explicitly call out env placement (not shell export).
3. §"Multi-harness dev" new subsection — document the .neo-ai-data symlink pattern:
   • Why it's needed (shared SQLite graph across harnesses; per #10224 / PR #10225)
   • bootstrapWorktree --link-data convention for worktree-to-main symlinks
   • Manual symlink pattern for cross-checkout scenarios (antigravity checkout → github checkout)
   • better-sqlite3 WAL-mode note: safe for multiple reader + serialized writer processes
4. Restart gotcha — noted once in the setup flow: MCP config changes require full harness quit (⌘Q on macOS), not window close. Most natural placement is the end of §5 or a "First-time setup" checklist.

Acceptance Criteria

• .github/AI_QUICK_START.md §4 lists Claude Desktop as Option C alongside Gemini CLI + Antigravity
• .github/AI_QUICK_START.md §5 includes complete claude_desktop_config.json example with NEO_AGENT_IDENTITY shown in the memory-core env block for all four Neo servers
• .github/AI_QUICK_START.md includes the .neo-ai-data symlink convention subsection — covers worktree bootstrap flag + cross-checkout manual pattern + WAL-mode note
• Restart-gotcha (⌘Q, not window close) noted once in the setup flow
• Cross-reference from AI_QUICK_START.md to learn/agentos/tooling/MemoryCoreMcpAuth.md §Troubleshooting for post-setup diagnostic flow (PR #10239's healthcheck-based diagnostic)
• Spot check: a new contributor following ONLY this guide can reach a healthy healthcheck.identity.bound === true state without consulting external sources

Out of Scope

• Claude Desktop internals (that belongs to Claude's own docs)
• Antigravity Twin Language Server configuration (already covered in .agent/skills/debugging-antigravity/)
• PR #10239's substrate-observability work (already shipped)
• Automation of the symlink convention beyond what bootstrapWorktree.mjs already does (follow-up epic if ever)

Avoided Traps

• "Bundle into PR #10239": rejected. PR #10239 shipped substrate code + one Troubleshooting refresh; bundling extensive operator-onboarding docs would have bloated the PR + delayed the diagnostic substrate's landing. Clean scope separation wins.
• "Document in .claude/settings.json convention instead": rejected. .claude/settings.json is a repo-tracked Claude Code convention file that doesn't own MCP servers on macOS Claude Desktop. Mixing the documentation across both locations introduces ambiguity. AI_QUICK_START.md is the single source of truth for all harness setup; Claude Desktop belongs there alongside Gemini CLI and Antigravity.
• "File the .neo-ai-data symlink convention as a separate ticket": rejected. It only exists because of the mailbox bootstrap + multi-harness pain; aggregated here for throughput.

Related

• Predecessor: PR #10239 (partial #10176 resolution — substrate-observability shipped)
• Source ticket: #10176 (original Mailbox identity observability + Claude Desktop onboarding docs — this ticket resolves its deferred portion)
• Adjacent: #10224 / PR #10225 (worktree .neo-ai-data symlink via bootstrapWorktree --link-data)
• Cross-reference target: learn/agentos/tooling/MemoryCoreMcpAuth.md §Troubleshooting (updated in PR #10239)

Origin Session ID: 24aa1fa1-9a22-498e-97f2-760c12e5a79d

Handoff Retrieval Hints

• query_raw_memories(query="Claude Desktop onboarding AI_QUICK_START NEO_AGENT_IDENTITY env block")
• query_raw_memories(query=".neo-ai-data symlink convention multi-harness dev")
• query_summaries(query="MCP config claude_desktop_config restart gotcha")