docs: the Windows node's three modes and one lifecycle, and what it cost

- MESHBAY_DESIGN.md §11.2: the node runs only while the app is open, at
  sign-in, or as a boot-time service; starting and stopping have one
  implementation, the CLI's; a second instance refuses before it writes
  anything the running one depends on.
- packaging/win/README.md: the three modes, switching between them, upgrading
  a running node, where the log is, the service task's settings.
- docs/windows-build.md: the build's smoke start of the frozen daemon, the log
  location, and what an upgrade does to a running node.
- CLAUDE.md: four engineering lessons -- an upgrade that cannot stop the node
  installs around it; on Windows the CLI is the process it is stopping; a
  second instance must fail before it touches anything shared; a test that
  redirects HOME isolates nothing on Windows.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

2 files changed, 27 insertions, 6 deletions

diff --git a/docs/MESHBAY_DESIGN.md b/docs/MESHBAY_DESIGN.md
index 4541d64..38ceec8 100644
--- a/docs/MESHBAY_DESIGN.md
+++ b/docs/MESHBAY_DESIGN.md
@@ -2942,10 +2942,20 @@ treated as correctness from the start. What the port needed is registered as
 
 Two Windows-specific design points worth stating here:
 
-- **Autostart has two modes, chosen at install and switchable afterwards** from the
-  Node page: a per-user startup launcher (the default) and a scheduled-task service
-  mode. A per-user default is right for the desktop persona; a service is what a
-  machine that must serve while nobody is logged in needs.
+- **The node runs in one of three modes, chosen at install and switchable
+  afterwards** from the Node page: only while the application is open (it starts
+  the node and stops one it started), at sign-in through a per-user startup
+  launcher, or as a scheduled-task service from boot. The two automatic ones
+  exclude each other. A per-user mode is right for the desktop persona; a service
+  is what a machine that must serve while nobody is logged in needs.
+- **Starting and stopping have one implementation, the CLI's**, which the
+  application, the installer's restart and a terminal all call. A stop asks the
+  node through its own control API first — the one channel that reaches it in any
+  session without elevation, and the one that runs its shutdown — then Task
+  Scheduler, then a forced stop that spares the command running it (the CLI and
+  the daemon are one executable). A start reports the version that answered, never
+  "started" about a node nobody asked. A second instance refuses before it writes
+  anything the running one depends on.
 - **A user service unit cannot carry a system unit's user directive.** Two unit
   templates exist, held apart by a test that parses directives rather than
   searching the file — searching matched the *comment* explaining why the directive
diff --git a/docs/windows-build.md b/docs/windows-build.md
index 88133cb..3f14664 100644
--- a/docs/windows-build.md
+++ b/docs/windows-build.md
@@ -40,7 +40,9 @@ This runs [`packaging/win/build-win.ps1`](../packaging/win/build-win.ps1), which
 4. `npm run sync-ui` — copies the SPA from `meshbay-hub/.../static`
 5. runs [`build-node-runtime.ps1`](../packaging/win/build-node-runtime.ps1) —
    creates a throwaway venv, installs `meshbay-node` + `meshbay-common`,
-   freezes the daemon with PyInstaller, fetches and verifies ffmpeg
+   freezes the daemon with PyInstaller, fetches and verifies ffmpeg, then
+   starts the frozen daemon in a throwaway profile and checks it answers
+   (`smoke-node-runtime.ps1` — also runnable against an installed build)
 6. `electron-builder --win nsis`
 
 Expect this to take several minutes the first time (Chromium download,
@@ -76,7 +78,16 @@ prompt unless you opt into service mode (background daemon that starts at
 boot, before sign-in) or accept the firewall rules, both offered during setup
 and both switchable afterwards from the Node page. Installs to
 `%LOCALAPPDATA%\Programs\MeshBay\`; runtime data lives in
-`%LOCALAPPDATA%\meshbay\`.
+`%LOCALAPPDATA%\meshbay\`, and the node's log in
+`%LOCALAPPDATA%\meshbay\state\node.log`.
+
+Installing over a previous version stops a running node first (including a
+background-service one) and starts the new one afterwards. To check what an
+installed build actually runs:
+
+```powershell
+meshbay-node service start    # waits for the node, prints the version that answered
+```
 
 ## What's not automated yet