docs: clarify remote deployment topology

[daggerhashimoto]

Summary

Clarify the deployment model and document the real limits of remote and split-topology Nerve installs.

Changes

• update docs/ARCHITECTURE.md with the locality model:
  • browser ↔ Nerve
  • Nerve ↔ gateway
  • Nerve ↔ workspace filesystem
• document that deployment parity depends on workspace locality, not just gateway reachability
• add explicit remote-workspace fallback boundaries for files, memory, and workspace UX
• rewrite docs/DEPLOYMENT-B.md as a partial-parity guide with a support/limitations matrix
• rewrite docs/DEPLOYMENT-C.md to distinguish same-host cloud from split-host cloud
• document the config requirements that matter for B/C:
  • WS_ALLOWED_HOSTS
  • NERVE_PUBLIC_ORIGIN
  • gateway.controlUi.allowedOrigins
  • gateway.tools.allow

Verification

• git diff --check
• code-path audit against current file-browser, workspace, memory, gateway RPC, trust, and deployment config behavior

Summary by CodeRabbit

• Documentation
  • Enhanced deployment and architecture guidance clarifying feature availability across different configuration scenarios.
  • Added detailed matrices showing capabilities and limitations for local, same-host cloud, and split-host cloud deployments.
  • Expanded setup and validation instructions with configuration-specific requirements and troubleshooting.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 3d91951f-f5cb-4ec7-90d0-aec99ad543a6

📥 Commits

Reviewing files that changed from the base of the PR and between a35ffc0 and ac30f19.

📒 Files selected for processing (3)

• docs/ARCHITECTURE.md
• docs/DEPLOYMENT-B.md
• docs/DEPLOYMENT-C.md

---

📝 Walkthrough

Walkthrough

Documentation updates redefine Nerve as "local-first" with three interaction boundaries, add a locality model clarifying remote workspace constraints, and refactor deployment guides to specify separate behaviors for remote gateway, same-host cloud, and split-host topologies with detailed API endpoint fallback limits.

Changes

Cohort / File(s)	Summary
Architecture & Locality Modeling docs/ARCHITECTURE.md	Reframed Nerve as local-first with explicit interaction boundaries. Added locality model section describing remote workspace fallback constraints (allowlisted files, depth limits, text-only scope, unsupported operations). Refined REST API endpoint documentation to reflect remote fallback limits for /api/memories, /api/workspace, /api/skills, and /api/files/*.
Cloud Deployment Guides docs/DEPLOYMENT-B.md, docs/DEPLOYMENT-C.md	Restructured deployment documentation from generic cloud framing to topology-specific guidance. Added "Reality check" and behavior matrices distinguishing what works, degrades, or is unsupported per deployment model. Introduced explicit configuration requirements (NERVE_PUBLIC_ORIGIN, gateway.controlUi.allowedOrigins, TRUSTED_PROXIES). Reworked validation and common-issues sections with remote-host contexts and new failure modes (origin/WS host mismatches, tool availability, directory browsing limitations).

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• PR #168: Both modify docs/ARCHITECTURE.md and deployment documentation, directly overlapping in topology and locality guidance updates.
• PR #60: The main PR significantly restructures and expands the same deployment documents (DEPLOYMENT-B.md, DEPLOYMENT-C.md) that the retrieved PR originally added.
• PR #201: Both clarify remote-workspace and gateway origin behavior, specifically documenting NERVE_PUBLIC_ORIGIN and related gateway origin allowlist configuration.

Poem

🐰 Hops through docs with gleeful care,
Mapping Nerve's boundaries fair—
Local-first, three edges bright,
Deployments split, both wrong and right!
Remote fallbacks, limits clear—
Architecture crystalizes here! ✨

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'docs: clarify remote deployment topology' is concise, specific, and accurately describes the main objective of the documentation updates across multiple files.
Description check	✅ Passed	The pull request description provides a comprehensive summary with clear sections covering changes, verification, and deployment model clarifications, though it deviates from the repository's template structure.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/remote-topology

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}