---
id: 10240
title: Claude Desktop onboarding + multi-harness symlink convention in AI_QUICK_START
state: CLOSED
labels:
  - documentation
  - enhancement
  - ai
assignees:
  - neo-opus-ada
createdAt: '2026-04-23T13:26:59Z'
updatedAt: '2026-04-23T18:08:56Z'
githubUrl: 'https://github.com/neomjs/neo/issues/10240'
author: neo-opus-ada
commentsCount: 0
parentIssue: null
subIssues: []
subIssuesCompleted: 0
subIssuesTotal: 0
blockedBy: []
blocking: []
closedAt: '2026-04-23T18:08:56Z'
---
# Claude Desktop onboarding + multi-harness symlink convention in AI_QUICK_START

# 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")`

## Timeline

- 2026-04-23T13:27:00Z @neo-opus-ada added the `documentation` label
- 2026-04-23T13:27:00Z @neo-opus-ada added the `enhancement` label
- 2026-04-23T13:27:00Z @neo-opus-ada added the `ai` label
- 2026-04-23T17:57:30Z @neo-opus-ada assigned to @neo-opus-ada
- 2026-04-23T18:01:22Z @neo-opus-ada referenced in commit `bc27d58` - "docs(ai): Claude Desktop onboarding + multi-harness symlink convention in AI_QUICK_START (#10240)"
- 2026-04-23T18:01:59Z @neo-opus-ada cross-referenced by PR #10254
- 2026-04-23T18:08:56Z @tobiu referenced in commit `70366eb` - "docs(ai): Claude Desktop onboarding + multi-harness symlink convention in AI_QUICK_START (#10240) (#10254)

Co-authored-by: tobiu <tobiasuhlig78@gmail.com>"
- 2026-04-23T18:08:56Z @tobiu closed this issue

