[monsterlag]

Note

AI-generated, not reviewed by a human. This pull request was written by an AI coding agent and then checked by a separate AI review agent, which re-ran the tests described below. No human has reviewed the code. It is submitted by @monsterlag, who runs these agents. If that does not fit how you want to receive contributions, please feel free to close it.

Linked issue

Related to #828; documents the maintainer's workaround without adding remote MCP support.

What & why

Running install --platform zed on a remote host updates that host's user settings,
not the local Zed instance. The generated server entry also points cwd at that
host's checkout. The platform guide listed settings paths but did not explain this
mismatch.

Add a symptom/cause/fix entry with local-checkout install/build commands, explain
that the local graph does not include remote-only edits, and link it from the
platform guide. Link the upstream Zed reports for version-dependent remote behavior.
Add a documentation regression check for the guidance and its link.

How it was tested

Python 3.11.2, with environments, caches and test state isolated outside the checkout:

uv run --locked --extra dev pytest -p no:cacheprovider tests/test_documentation.py tests/test_skills.py --tb=short -q
uv run --locked --extra dev ruff check code_review_graph/ tests/test_documentation.py
uv run --locked --extra dev mypy code_review_graph/ --ignore-missing-imports --no-strict-optional
uvx bandit -r code_review_graph/ -c pyproject.toml

• Regression against unchanged documentation: 1 failed, 5 passed; with the change:
  215 passed across the documentation/installer modules.
• Ruff, mypy and Bandit passed; schema-sync and git diff --check passed.

Earlier full-suite run (not repeated for this PR-text-only revision):

uv run --locked --extra dev pytest -p no:cacheprovider tests/ --tb=short -q --cov=code_review_graph --cov-report=term-missing --cov-fail-under=65

5,045 passed, 1 failed, 880 skipped, 3 xfailed, 2 xpassed; 86.66% coverage.
The failure, test_hybrid_search_ranks_impact_radius_nodes_first in
tests/test_e2e_real_repo.py, also reproduces on unchanged baseline code and depends
on checkout-path length. Rechecking it during this revision produced the same failure.

No live Zed client or SSH end-to-end session was tested.

Checklist

• Tests added for new functionality (documentation regression)
• All tests pass: uv run pytest tests/ --tb=short -q (baseline failure above)
• Linting passes: uv run ruff check code_review_graph/
• Type checking passes: uv run mypy code_review_graph/ --ignore-missing-imports --no-strict-optional
• Lines are at most 100 characters (added lines)
• Docs updated where behavior changed (README, docs/, docstrings)

[Copilot]

🟢 Approval recommended

No active review issues are recorded for the Zed SSH workaround documentation and accompanying regression test.

No open issues 🎉

What changed in this PR

Documents the local-checkout workaround for Zed native agents that cannot see MCP in SSH projects, addressing the setup confusion in #828 without adding remote MCP support.

Changes:

• Explains the local/remote settings mismatch and provides local install/build steps, synchronization caveats, and upstream references.
• Links the troubleshooting guidance from the platform guide.
• Adds a regression test for the guidance and its discoverability.

File	Description
tests/​test_documentation.py	Checks required Zed troubleshooting details and the platform-guide link.
docs/​USAGE.md	Links SSH users to Zed troubleshooting.
docs/​TROUBLESHOOTING.md	Documents symptoms, causes, and the local-checkout workaround.

_{Review effort: Balanced}