update docs

README.md

@@ -1,41 +1,83 @@
 # betterNAS
 
-- control-plane owns policy and identity (decides)
-- node-agent owns file serving (serves)
-- web owns UX (consumer facing)
-- nextcloud-app is optional adapter only for cloud storage in s3 n shit
+betterNAS is a self-hostable WebDAV stack for mounting NAS exports in Finder.
 
-## Monorepo
+The default product shape is:
 
-- `apps/web`: Next.js control-plane UI
-- `apps/control-plane`: Go control-plane service
-- `apps/node-agent`: Go NAS runtime / WebDAV node
-- `apps/nextcloud-app`: optional Nextcloud adapter
-- `packages/contracts`: canonical shared contracts
-- `packages/ui`: shared React UI
-- `infra/docker`: local Docker runtime
+- `node-service` serves the real files from the NAS over WebDAV
+- `control-server` owns auth, nodes, exports, grants, and mount profile issuance
+- `web control plane` lets the user manage the NAS and get mount instructions
+- `macOS client` starts as native Finder WebDAV mounting, with a thin helper later
 
-The root planning and delegation guide lives in [skeleton.md](./skeleton.md).
+For now, the whole stack should be able to run on the user's NAS device.
+
+## Current repo shape
+
+- `apps/node-agent`
+  - NAS-side Go runtime and WebDAV server
+- `apps/control-plane`
+  - Go backend for auth, registry, and mount profile issuance
+- `apps/web`
+  - Next.js web control plane
+- `apps/nextcloud-app`
+  - optional Nextcloud adapter, not the product center
+- `packages/contracts`
+  - canonical shared contracts
+- `infra/docker`
+  - self-hosted local stack
+
+The main planning docs are:
+
+- [docs/architecture.md](./docs/architecture.md)
+- [skeleton.md](./skeleton.md)
+- [docs/05-build-plan.md](./docs/05-build-plan.md)
+
+## Default runtime model
+
+```text
+                   self-hosted betterNAS on the user's NAS
+
+                         +------------------------------+
+                         | web control plane            |
+                         | Next.js UI                   |
+                         +--------------+---------------+
+                                        |
+                                        v
+                         +------------------------------+
+                         | control-server               |
+                         | auth / nodes / exports       |
+                         | grants / mount profiles      |
+                         +--------------+---------------+
+                                        |
+                                        v
+                         +------------------------------+
+                         | node-service                 |
+                         | WebDAV + export runtime      |
+                         | real NAS bytes               |
+                         +------------------------------+
+
+ user Mac
+   |
+   +--> browser -> web control plane
+   |
+   +--> Finder -> WebDAV mount URL from control-server
+```
 
 ## Verify
 
-Run the repo acceptance loop with:
+Static verification:
 
 ```bash
 pnpm verify
 ```
 
-## Runtime loop
-
-Bootstrap clone-local runtime settings with:
+Bootstrap clone-local runtime settings:
 
 ```bash
 pnpm agent:bootstrap
 ```
 
-If `.env.agent` is missing, bootstrap writes clone-local defaults for this checkout.
-
-Bring the stack up, verify it, and tear it down with:
+Bring the self-hosted stack up, verify it, and tear it down:
 
 ```bash
 pnpm stack:up
@@ -43,16 +85,30 @@ pnpm stack:verify
 pnpm stack:down --volumes
 ```
 
-## Agent loop
-
-Run the full static and integration loop with:
+Run the full loop:
 
 ```bash
 pnpm agent:verify
 ```
 
-Create or refresh the sibling agent clones with:
+## Current end-to-end slice
 
-```bash
-pnpm clones:setup
-```
+The first proven slice is:
+
+1. boot the stack with `pnpm stack:up`
+2. verify it with `pnpm stack:verify`
+3. get the WebDAV mount URL
+4. mount it in Finder
+
+If the stack is running on a remote machine, tunnel the WebDAV port first, then
+use Finder `Connect to Server` with the tunneled URL.
+
+## Product boundary
+
+The default betterNAS product is self-hosted and WebDAV-first.
+
+Nextcloud remains optional and secondary:
+
+- useful later for browser/mobile/share surfaces
+- not required for the core mount flow
+- not the system of record