update docs

docs/01-nas-node.md

@@ -1,6 +1,7 @@
 # betterNAS Part 1: NAS Node
 
-This document describes the software that runs on the actual NAS machine, VM, or workstation that owns the files.
+This document describes the software that runs on the actual NAS machine, VM,
+or workstation that owns the files.
 
 ## What it is
 
@@ -8,10 +9,11 @@ The NAS node is the machine that actually has the storage.
 
 It should run:
 
-- a WebDAV server
-- a small betterNAS node agent
-- declarative config via Nix
-- optional tunnel or relay connection if the machine is not directly reachable
+- the `node-service`
+- a WebDAV server surface
+- export configuration
+- optional enrollment or heartbeat back to `control-server`
+- later, a reproducible install path such as Docker or Nix
 
 It should expose one or more storage exports such as:
 
@@ -24,47 +26,38 @@ It should expose one or more storage exports such as:
 
 - serves the real file bytes
 - exposes chosen directories over WebDAV
-- registers itself with the control plane
-- reports health, identity, and available exports
-- optionally keeps an outbound connection alive for remote access
+- reports identity, health, and exports to `control-server`
+- stays simple enough to self-host on a single NAS box
 
 ## What it should not do
 
-- own user-facing product logic
-- decide permissions by itself
-- become the system of record for shares, devices, or policies
+- own product policy
+- decide user access rules by itself
+- become the system of record for users, grants, or shares
 
 ## Diagram
 
 ```text
-                            betterNAS system
+                      self-hosted betterNAS stack
 
-   local device  <------->  control plane  <------->  cloud/web layer
-        |                         |                          |
-        |                         |                          |
-        +-------------------------+--------------------------+
-                                  |
-                                  v
-                      +---------------------------+
-                      | [THIS DOC] NAS node       |
-                      |---------------------------|
-                      | WebDAV server             |
-                      | node agent                |
-                      | exported directories      |
-                      | optional tunnel/relay     |
-                      +---------------------------+
+      web control plane ---> control-server ---> [THIS DOC] node-service
+               ^                                        |
+               |                                        |
+               +---------------- user browser ----------+
+
+      local Mac ---------------- Finder mount ----------+
 ```
 
 ## Core decisions
 
 - The NAS node should be where WebDAV is served from whenever possible.
-- The control plane should configure access, but file bytes should flow from the node to the user device as directly as possible.
-- The node should be installable with a Nix module or flake so setup is reproducible.
+- The node should be installable as one boring runtime on the user's machine.
+- The node should expose exports, not product semantics.
 
 ## TODO
 
-- Choose the WebDAV server we will standardize on for the node.
-- Define the node agent responsibilities and API back to the control plane.
-- Define the storage export model: path, label, capacity, tags, protocol support.
-- Define direct-access vs relayed-access behavior.
-- Define how the node connects to the cloud/web layer for optional Nextcloud integration.
+- Define the self-hosted install shape: Docker first, Nix second, or both.
+- Define the node identity and enrollment model.
+- Define the storage export model: path, label, tags, permissions, capacity.
+- Define when the node self-registers vs when bootstrap tooling registers it.
+- Define direct-access vs relay-access behavior for remote use.