diff --git a/README.md b/README.md
index 94fd4a4f9..ed8d1d77f 100644
--- a/README.md
+++ b/README.md
@@ -63,6 +63,32 @@ For the full walkthrough, see **[Getting Started](https://codevos.ai/getting-sta
 
 See [CLI Reference](codev/resources/commands/overview.md) for details.
 
+## Upgrading
+
+Upgrading is **two steps, not one** — the npm package and your projects' framework files update separately:
+
+```bash
+# 1. Update the CLI (once per machine)
+npm install -g @cluesmith/codev@latest    # or @next for the release-candidate channel
+
+# 2. Update framework files (once per project/workspace)
+cd my-project
+codev update
+```
+
+`npm install -g` updates the binaries (`codev`, `afx`, `porch`, `consult`) and the built-in
+protocol skeleton. `codev update` then refreshes the files checked into each project —
+`CLAUDE.md`/`AGENTS.md`, protocol and resource files, skills — merging your local
+customizations. Skipping step 2 leaves your projects running old prompts against a new CLI,
+which is the most common source of "my agents stopped following the protocol" reports.
+
+**VS Code extension**: "Codev for VS Code" updates through the Marketplace like any
+extension (auto-update by default, or Extensions panel → Codev → Update). Keep it current
+with the CLI — Tower and the extension are versioned together.
+
+If Tower is running during an upgrade, restart it afterwards so it picks up the new code:
+`afx tower stop && afx tower start`.
+
 ## How It Works
 
 1. **Write a spec** — Describe what you want. The architect helps refine it.
diff --git a/codev/resources/arch.md b/codev/resources/arch.md
index e94df2c2b..8a645a23f 100644
--- a/codev/resources/arch.md
+++ b/codev/resources/arch.md
@@ -1952,6 +1952,16 @@ consult -m claude spec 42
 
 > **Historical note** (Spec 0008, Spec 0098): Originally allocated deterministic 100-port blocks per repository. After the Tower Single Daemon architecture (Spec 0090), per-workspace port blocks became unnecessary and were removed in Spec 0098. The global registry now tracks workspace metadata and terminal sessions instead.
 
+### 8. No Internal Authentication in Tower (By Design)
+**Decision**: Tower performs no internal request authentication (`isRequestAllowed()` returns true unconditionally); the authentication boundary is external — localhost binding for local actors, the codevos.ai edge for tunnel-borne traffic (owner ruling, issue #1375).
+
+**Rationale**:
+- **Localhost binding** covers the local case: filesystem/OS user boundary is the auth mechanism, consistent with the terminal-endpoint stance above
+- **The cloud edge owns remote auth** - tunnel-borne requests are gated at codevos.ai before they reach the tunnel; duplicating auth inside Tower adds a second credential system to keep in sync
+- **Management endpoints are still origin-restricted** - `/api/tunnel/*` rejects tunnel-borne requests outright (PR #1374), so a compromised or misconfigured edge cannot deregister the tower; `via=tunnel/local` attribution logs every proxied request
+
+**Consequence**: do not file or "fix" the missing 401s as a vulnerability; harden at the edge or via origin-restriction of specific endpoints instead.
+
 ## Integration Points
 
 ### External Services