docs(remote): explain local gateway toggle prerequisite

[adiarora06]

Problem / Motivation

The persistent SSH tunnel guide did not explain that the desktop app's supervised local gateway must be disabled when the app should act only as a client of the tunnel.

Why it matters

Without the prerequisite and launch order, users can accidentally run a competing local gateway and misdiagnose tunnel connectivity or connect through the wrong mechanism.

What changed (motivation → approach → change)

The guide now documents the required launch order and local-gateway toggle, clarifies that the toggle does not create or supervise the tunnel, and distinguishes the Connected Instance feature from the SSH-tunnel workflow.

Tests

• ./scripts/docs-lint.sh (212 Markdown files scanned; all checks passed)

Manual verification

N/A — this is a documentation-only clarification and the documentation lint passes.

Related Issues

Addresses #3810

Checklist

• At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|refactor|perf|test|chore|ci|build|revert: ...)
• Existing tests pass and new tests added for new functionality
• Self-review completed; code follows project style guidelines
• Documentation updated (if applicable)
• No secrets, credentials, or internal references in the diff

Contribution License Agreement

The repository's CLA placeholder remains pending OSPO wording.

[iamwhatever]

👋 Hi! This PR is currently in draft status. Workflow runs won't be auto-approved until it's marked as ready for review.

When you're ready, click "Ready for review" and the workflows will be approved on the next cycle automatically.

[iamwhatever]

👋 Hi! This PR is currently in draft status. Workflow runs won't be auto-approved until it's marked as ready for review.

When you're ready, click "Ready for review" and the workflows will be approved on the next cycle automatically.

[bolichen97]

👋 Hi! This PR is currently in draft status. Workflow runs won't be auto-approved until it's marked as ready for review.

When you're ready, click "Ready for review" and the workflows will be approved on the next cycle automatically.

[iamwhatever]

👋 Hi! This PR is currently in draft status. Workflow runs won't be auto-approved until it's marked as ready for review.

When you're ready, click "Ready for review" and the workflows will be approved on the next cycle automatically.

[iamwhatever]

👋 Hi! This PR is currently in draft status. Workflow runs won't be auto-approved until it's marked as ready for review.

When you're ready, click "Ready for review" and the workflows will be approved on the next cycle automatically.

[bolichen97]

👋 Hi! This PR is currently in draft status. Workflow runs won't be auto-approved until it's marked as ready for review.

When you're ready, click "Ready for review" and the workflows will be approved on the next cycle automatically.

[iamwhatever]

👋 Hi! This PR is currently in draft status. Workflow runs won't be auto-approved until it's marked as ready for review.

When you're ready, click "Ready for review" and the workflows will be approved on the next cycle automatically.

[iamwhatever]

👋 Hi! This PR is currently in draft status. Workflow runs won't be auto-approved until it's marked as ready for review.

When you're ready, click "Ready for review" and the workflows will be approved on the next cycle automatically.

[iamwhatever]

👋 Hi! This PR is currently in draft status. Workflow runs won't be auto-approved until it's marked as ready for review.

When you're ready, click "Ready for review" and the workflows will be approved on the next cycle automatically.

[iamwhatever]

👋 Hi! This PR is currently in draft status. Workflow runs won't be auto-approved until it's marked as ready for review.

When you're ready, click "Ready for review" and the workflows will be approved on the next cycle automatically.

[bolichen97]

👋 Hi! This PR is currently in draft status. Workflow runs won't be auto-approved until it's marked as ready for review.

When you're ready, click "Ready for review" and the workflows will be approved on the next cycle automatically.

[iamwhatever]

👋 Hi! This PR is currently in draft status. Workflow runs won't be auto-approved until it's marked as ready for review.

When you're ready, click "Ready for review" and the workflows will be approved on the next cycle automatically.

[bolichen97]

👋 Hi! This PR is currently in draft status. Workflow runs won't be auto-approved until it's marked as ready for review.

When you're ready, click "Ready for review" and the workflows will be approved on the next cycle automatically.

[iamwhatever]

👋 Hi! This PR is currently in draft status. Workflow runs won't be auto-approved until it's marked as ready for review.

When you're ready, click "Ready for review" and the workflows will be approved on the next cycle automatically.

[iamwhatever]

👋 Hi! This PR is currently in draft status. Workflow runs won't be auto-approved until it's marked as ready for review.

When you're ready, click "Ready for review" and the workflows will be approved on the next cycle automatically.

[bolichen97]

👋 Hi! This PR is currently in draft status. Workflow runs won't be auto-approved until it's marked as ready for review.

When you're ready, click "Ready for review" and the workflows will be approved on the next cycle automatically.

[bolichen97]

👋 Hi! This PR is currently in draft status. Workflow runs won't be auto-approved until it's marked as ready for review.

When you're ready, click "Ready for review" and the workflows will be approved on the next cycle automatically.

[iamwhatever]

👋 Hi! This PR is currently in draft status. Workflow runs won't be auto-approved until it's marked as ready for review.

When you're ready, click "Ready for review" and the workflows will be approved on the next cycle automatically.

[iamwhatever]

👋 Hi! This PR is currently in draft status. Workflow runs won't be auto-approved until it's marked as ready for review.

When you're ready, click "Ready for review" and the workflows will be approved on the next cycle automatically.

[bolichen97]

👋 Hi! This PR is currently in draft status. Workflow runs won't be auto-approved until it's marked as ready for review.

When you're ready, click "Ready for review" and the workflows will be approved on the next cycle automatically.

[iamwhatever]

👋 Hi! This PR is currently in draft status. Workflow runs won't be auto-approved until it's marked as ready for review.

When you're ready, click "Ready for review" and the workflows will be approved on the next cycle automatically.

[iamwhatever]

👋 Hi! This PR is currently in draft status. Workflow runs won't be auto-approved until it's marked as ready for review.

When you're ready, click "Ready for review" and the workflows will be approved on the next cycle automatically.

[iamwhatever]

👋 Hi! This PR is currently in draft status. Workflow runs won't be auto-approved until it's marked as ready for review.

When you're ready, click "Ready for review" and the workflows will be approved on the next cycle automatically.

[bolichen97]

👋 Hi! This PR is currently in draft status. Workflow runs won't be auto-approved until it's marked as ready for review.

When you're ready, click "Ready for review" and the workflows will be approved on the next cycle automatically.

[iamwhatever]

👋 Hi! This PR is currently in draft status. Workflow runs won't be auto-approved until it's marked as ready for review.

When you're ready, click "Ready for review" and the workflows will be approved on the next cycle automatically.

[iamwhatever]

👋 Hi! This PR is currently in draft status. Workflow runs won't be auto-approved until it's marked as ready for review.

When you're ready, click "Ready for review" and the workflows will be approved on the next cycle automatically.

[iamwhatever]

👋 Hi! This PR is currently in draft status. Workflow runs won't be auto-approved until it's marked as ready for review.

When you're ready, click "Ready for review" and the workflows will be approved on the next cycle automatically.

[iamwhatever]

👋 Hi! This PR is currently in draft status. Workflow runs won't be auto-approved until it's marked as ready for review.

When you're ready, click "Ready for review" and the workflows will be approved on the next cycle automatically.

[dwu96]

👋 Hi! This PR is currently in draft status. Workflow runs won't be auto-approved until it's marked as ready for review.

When you're ready, click "Ready for review" and the workflows will be approved on the next cycle automatically.

[iamwhatever]

👋 Hi! This PR is currently in draft status. Workflow runs won't be auto-approved until it's marked as ready for review.

When you're ready, click "Ready for review" and the workflows will be approved on the next cycle automatically.

[github-actions]

Opus 4.8 Review (fork) — ✅ no blocking findings

Reviewed 161b7ee2403418a8131791c6b6e219fd044fca9b via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 161b7ee

[github-actions]

GPT 5.6 Review (fork) — ✅ no blocking findings

Reviewed 161b7ee2403418a8131791c6b6e219fd044fca9b via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 161b7ee

[github-actions]

Design Review (Fable 5, fork) — ✅ PASS

Design-level review of 161b7ee2403418a8131791c6b6e219fd044fca9b via the fork AI-review pipeline — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: PASS

A real footgun (competing supervised gateway on port 5476), fixed at the right place; every factual claim checks out against the toggle, quit, and Instances code.

The added prose matches the base tree: the Run a local gateway switch and its off-path port resolution exist in website/electron/main.js:106 (resolvePort targets an already-running gateway when the toggle is off), before-quit tears down the supervised gateway so the quit-first launch order is accurate, and the Instances distinction matches docs/system-specs/modules/instances.md (hub-supervised tunnels on allocated loopback ports). No design-level concerns.

[DESIGN-REVIEWED] 161b7ee

[bolichen97]

Open PR relationship audit

This is a consolidated, point-in-time code-level audit note. It compares complete merge-base diffs and current/merged code; it does not treat a shared topic as duplication or partial coverage as completion.

Relationship findings

• This PR is PARTIALLY_COVERED with PR #2917. Coverage is explicitly incomplete; this finding is not a completion or closure claim. Recommended action for PR #4259: CONTINUE_DEVELOPMENT. The merged feature supplies the toggle and generic help text but not the prerequisite documentation this PR adds, so the docs gap is real and unclosed; the PR's own content defects (launch order, paragraph placement) still need a fix before merge. Files: website/electron/local-gateway.js.

No PR, Issue, label, branch, or review state was changed by the relationship-note portion of this audit.

[bolichen97]

@adiarora06 Thanks for this. The gap is real and still unclosed on main, so this should land rather than be closed. #2917 shipped the toggle itself plus one line of in-UI help text, which covers client-only mode and "takes effect next launch". It does not state the prerequisite that something must already answer on port 5476, the launch order, that the toggle neither creates nor supervises a tunnel, or that a connected Instances entry does not satisfy it. None of that prose exists anywhere under docs/ on main.

Two notes, audited at 79d8647 and re-checked against your current head.

Your latest revision already fixed the two content problems the audit found. The paragraph now sits before the "A ready-made plist is at ...:" sentence instead of splitting it from the code block that colon introduces, and the launch order now disables the toggle and quits the app before starting the tunnel, which is correct because a still-enabled local gateway holds port 5476. Nothing further needed there.

Please rebase before we merge. The branch is still on merge base 3af243d and roughly 1224 commits behind. docs/guides/remote-and-mobile.md has been reworked several times since, in #7780, #7999, #8617, #8208 and #8905. None of those touch this prerequisite, so the rebase should be textual only.

One scope point: the body says this addresses #3810, but that issue's primary asks are help text under the toggle and a pre-flight confirmation using startGateway()'s existing probe. This PR is the companion docs change the issue anticipated, so please keep #3810 open when this merges.

Posted from the 2026-09-08 open-PR relationship audit (read-only, one auditor per PR); reply here if any of this is wrong.

[bolichen97]

Maintainer review (agent-assisted, on behalf of @bolichen97), head 161b7ee24.

Docs-only, one file. Every claim in the new paragraph holds against main: the toggle is Settings → Developer → Gateway → "Run a local gateway" (en.json:8038-8042, settingsRegistry.gen.ts:1267-1273); gateway-supervisor.js:167 reads it once at launch and startGateway() at :577-588 refuses to spawn when it is off, so a gateway must already be answering.

Non-blocking: remote-and-mobile.md:678 "answer on port 5476" is exact only with no Instances host configured; with one configured main.js:113-127 targets that crew's port — "on port 5476 (or the port dashboard.url names)" would be precise.