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
  • Clarified architecture and deployment topologies (local, same-host, split-host) and introduced a locality model with a remote-workspace fallback behavior.
  • Added “what works / what degrades” matrices describing UI surface impacts (file browsing, previews, rename/move/trash, memory/skills behaviors).
  • Updated deployment guides with revised setup, validation, allowlist/origin configuration, troubleshooting, and security guidance for remote/split-host scenarios.

[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: 93bf0941-f20b-43fb-b2f5-07bdcf52e4f4

📥 Commits

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

📒 Files selected for processing (1)

• docs/ARCHITECTURE.md

🚧 Files skipped from review as they are similar to previous changes (1)

• docs/ARCHITECTURE.md

---

📝 Walkthrough

Walkthrough

Documentation updates redefine Nerve as "local-first", add an explicit locality model with a remote-workspace fallback and per-surface fallback matrix, and restructure deployment guides into topology-specific guidance (remote gateway, same-host, split-host) with clarified API endpoint fallback limits and configuration requirements.

Changes

Cohort / File(s)	Summary
Architecture & Locality Modeling docs/ARCHITECTURE.md	Redefines Nerve as local-first; documents three communication boundaries (Browser↔Nerve, Nerve↔OpenClaw gateway, Nerve↔workspace FS). Adds a locality model with a remote workspace fallback behavior matrix and refines REST API semantics to restrict remote fallbacks (e.g., MEMORY.md only, top-level allowlisted files, no /api/files/raw remote fallback, rename/move/trash/restore local-only).
Deployment — Remote Gateway (B) docs/DEPLOYMENT-B.md	Reframes guidance for remote-gateway + local Nerve topology: adds topology diagram, “Reality check”/locality partitioning, a “what works/what degrades” matrix, updated setup steps (WS proxy allowlist targets remote gateway host), new NERVE_PUBLIC_ORIGIN guidance and gateway allowlist requirements, and revised validation/common-issues and security notes for remote-host context.
Deployment — Same-host / Split-host (C) docs/DEPLOYMENT-C.md	Expands into topology comparison (same-host vs split-host), adds recommendation table, reworks same-host setup (auth, HTTPS, TRUSTED_PROXIES, loopback gateway URL), details same-host vs split-host behavior differences (full features vs partial/unavailable features), validation updates, and new common-issues and remediation guidance (including origin/allowlist fixes).

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• [FEATURE] Command drawer when typing slash #168: Overlaps edits to docs/ARCHITECTURE.md and deployment topology/locality guidance — likely direct content-level conflict.
• docs: add deployment guides and improve setup links #60: Prior deployment documentation changes that this PR restructures and expands; review for overlapping guidance or duplicated instructions.
• chore(release): prepare 1.5.2 #201: Related changes documenting NERVE_PUBLIC_ORIGIN, gateway origin allowlist, and remote-workspace constraints.

Poem

🐰 I hopped through lines of docs tonight,
Redrew the paths where Nerve takes flight,
Local-first beats the distant drum,
Gateways whisper when the workspace hums,
Boundaries sketched, the map now bright.

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the main objective of the PR: clarifying documentation for remote deployment topology across three architecture files.
Description check	✅ Passed	The description covers the 'What' (clarifying deployment models and limits), 'Why' (document real limits), and detailed 'How' (specific files and sections changed), but the Type of Change checkbox and Checklist sections are not filled out.
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.}