prepare runtime loop

Co-authored-by: Codex <noreply@openai.com>

docs/agents/README.md

@@ -0,0 +1,31 @@
+# Agent Prompts
+
+These prompts are for the three sibling Devin clones:
+
+```text
+/home/rathi/Documents/GitHub/betterNAS/
+  betterNAS
+  betterNAS-runtime
+  betterNAS-control
+  betterNAS-node
+```
+
+Use them in this order:
+
+1. start the runtime agent first
+2. wait until the runtime loop is green
+3. start the control and node agents in parallel
+
+Rules that apply to all three:
+
+- `packages/contracts/**` is frozen for this wave
+- `docs/architecture.md` is frozen for this wave
+- if an agent finds a real contract gap, it should stop and report the exact change instead of freelancing a workaround
+- each agent should stay inside its assigned lane unless a tiny unblocker is strictly required
+- each agent must verify with real commands, not only code inspection
+
+Prompt files:
+
+- [`runtime-agent.md`](./runtime-agent.md)
+- [`control-plane-agent.md`](./control-plane-agent.md)
+- [`node-agent.md`](./node-agent.md)

docs/agents/control-plane-agent.md

@@ -0,0 +1,56 @@
+# Control Plane Agent Prompt
+
+```text
+You are working in /home/rathi/Documents/GitHub/betterNAS/betterNAS-control.
+
+Goal:
+Make the Go control plane implement the current first-loop contracts for node registration, export inventory, heartbeat, mount profile issuance, and cloud profile issuance.
+
+Primary scope:
+- apps/control-plane/**
+
+Read-only references:
+- packages/contracts/**
+- docs/architecture.md
+- control.md
+- TODO.md
+
+Do not change:
+- packages/contracts/**
+- docs/architecture.md
+- runtime scripts
+- node-agent code
+
+Use the existing contracts as fixed for this task.
+
+Implement cleanly:
+- POST /api/v1/nodes/register
+  - store or update a node
+  - store or update its exports
+- POST /api/v1/nodes/{nodeId}/heartbeat
+  - update status and lastSeenAt
+- GET /api/v1/exports
+  - return registered exports
+- POST /api/v1/mount-profiles/issue
+  - validate that the export exists
+  - return a mount profile for that export
+- POST /api/v1/cloud-profiles/issue
+  - validate that the export exists
+  - return a Nextcloud cloud profile for that export
+
+Constraints:
+- simplest correct implementation first
+- in-memory storage is acceptable for this slice
+- add tests
+- do not invent new request or response shapes
+- if you discover a real contract gap, stop and report the exact required contract change instead of patching around it
+
+Acceptance criteria:
+1. pnpm agent:bootstrap succeeds.
+2. pnpm verify succeeds.
+3. control-plane tests cover the implemented API behavior.
+4. If the runtime loop is already green on this machine, pnpm stack:up and pnpm stack:verify also stays green in this clone.
+
+Deliverable:
+A real contract-backed control plane for the first mount loop, without contract drift.
+```

docs/agents/node-agent.md

@@ -0,0 +1,53 @@
+# Node Agent Prompt
+
+```text
+You are working in /home/rathi/Documents/GitHub/betterNAS/betterNAS-node.
+
+Goal:
+Make the node agent a clean NAS-side runtime for the first loop, with reliable WebDAV behavior and export configuration.
+
+Primary scope:
+- apps/node-agent/**
+
+Read-only references:
+- packages/contracts/**
+- docs/architecture.md
+- control.md
+- TODO.md
+
+Do not change:
+- packages/contracts/**
+- docs/architecture.md
+- runtime scripts
+- control-plane code
+
+Use the existing contracts as fixed for this task.
+
+Implement cleanly:
+- stable WebDAV serving from BETTERNAS_EXPORT_PATH
+- Finder-friendly behavior at /dav/
+- clean env-driven node identity and export metadata
+  - machine id
+  - display name
+  - export label
+  - tags if useful
+- keep the health endpoint clean
+- add tests where practical
+
+Optional only if it fits cleanly without changing contracts:
+- node self-registration and heartbeat client wiring behind env configuration
+
+Constraints:
+- do not invent new shared APIs
+- keep this a boring, reliable NAS-side service
+- prefer correctness and configurability over features
+
+Acceptance criteria:
+1. pnpm agent:bootstrap succeeds.
+2. pnpm verify succeeds.
+3. WebDAV behavior is reliable against the configured export path.
+4. If the runtime loop is already green on this machine, pnpm stack:up and pnpm stack:verify also stays green in this clone.
+
+Deliverable:
+A clean node agent that serves the first real WebDAV export path without cross-lane drift.
+```

docs/agents/runtime-agent.md

@@ -0,0 +1,49 @@
+# Runtime Agent Prompt
+
+```text
+You are working in /home/rathi/Documents/GitHub/betterNAS/betterNAS-runtime.
+
+Goal:
+Make the clone-local runtime and integration loop deterministic and green on this machine.
+
+Primary scope:
+- infra/docker/**
+- scripts/**
+- README.md
+- control.md only if the command surface changes
+
+Do not change:
+- packages/contracts/**
+- docs/architecture.md
+- app behavior unless a tiny startup or health fix is strictly required to get the runtime green
+
+Rules:
+- keep this clone isolated and clone-safe
+- do not hardcode ports or paths outside .env.agent
+- do not invent new contracts
+- prefer fixing runtime wiring, readiness, healthchecks, compose config, and verification scripts
+
+Required command surface:
+- pnpm agent:bootstrap
+- pnpm verify
+- pnpm stack:up
+- pnpm stack:verify
+- pnpm stack:down --volumes
+
+Acceptance criteria:
+1. From a fresh clone, pnpm agent:bootstrap succeeds.
+2. pnpm verify succeeds.
+3. pnpm stack:up succeeds.
+4. pnpm stack:verify succeeds.
+5. pnpm stack:down --volumes succeeds.
+6. After a full reset, stack:up and stack:verify succeeds again.
+7. The runtime stays deterministic and clone-safe.
+
+If blocked:
+- inspect the actual failing service logs
+- make the smallest necessary fix
+- keep fixes inside runtime-owned files unless a tiny startup fix is unavoidable
+
+Deliverable:
+A green runtime loop for this clone on this machine.
+```