skeleton schemas

packages/contracts/README.md

@@ -0,0 +1,42 @@
+# `@betternas/contracts`
+
+This package is the machine-readable source of truth for shared interfaces in
+betterNAS.
+
+Use it to keep the four product parts aligned:
+
+- NAS node
+- control plane
+- local device
+- cloud/web layer
+
+## What belongs here
+
+- shared TypeScript types
+- route constants
+- JSON schemas for payloads we want to validate outside TypeScript
+
+## What does not belong here
+
+- business logic
+- per-service config
+- implementation-specific helpers
+
+## Current contract layers
+
+- [`src/control-plane.ts`](/home/rathi/Documents/GitHub/betterNAS/packages/contracts/src/control-plane.ts)
+  - current runtime scaffold for health and version
+- [`src/foundation.ts`](/home/rathi/Documents/GitHub/betterNAS/packages/contracts/src/foundation.ts)
+  - first product-level entities and route constants for node, mount, and cloud flows
+- [`schemas/`](/home/rathi/Documents/GitHub/betterNAS/packages/contracts/schemas)
+  - JSON schema mirrors for the first shared entities
+
+## Change rules
+
+1. Shared API shape changes happen here first.
+2. If the boundary changes, also update
+   [`docs/architecture.md`](/home/rathi/Documents/GitHub/betterNAS/docs/architecture.md).
+3. Prefer additive changes until all four parts are live.
+4. Do not put Nextcloud-only assumptions into the core contracts unless the
+   field is explicitly part of the cloud adapter.
+5. Keep the first version narrow. Over-modeling early is another form of drift.