create-githolon 0.59.1 → 0.60.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-githolon",
-  "version": "0.59.1",
+  "version": "0.60.0",
   "type": "module",
   "description": "Scaffold a Nomos domain package: the starter domain + compile config + live e2e. `npm create githolon my-app`.",
   "license": "SEE LICENSE IN LICENSE.md",

package/template/docs/03-client.md

@@ -33,6 +33,25 @@ params)`, `holon.queryById(id)`, `holon.count(id, group)`, `holon.sum(id,
 group)`. Hover anything in your editor — `@githolon/client` ships full types
 and the semantics live in the doc comments.
 
+## Many workspaces at once (the normal shape)
+
+Everything about Nomos is multi-workspace: a real app holds a dozen+ live
+local workspaces (the user's home, each estate, each catalogue). Don't build
+on a single-connection assumption — hold one PLANE and many handles on it.
+
+- **TS/JS**: `openRealm` mounts N workspaces in ONE engine; give each
+  generated client its own handle:
+  `const realm = await openRealm({ cloud }); const estate = estateClient(await realm.workspace("estate-…"));`
+  (`connect()` remains the one-workspace sugar over the same machinery.)
+- **Flutter/Dart**: one `NomosBridge` per app, one `NomosSession` per
+  workspace: `EstateClient(bridge.session('estate-…'))`. A session IS a
+  `NomosBridge` (generated clients take it unchanged) with every op pinned to
+  its workspace. Calling a bare multi-session bridge without a session refuses
+  LOUDLY (`multiple sessions connected — pass session`) rather than guessing.
+
+A workspace opened with no `cloud` is LOCAL-ONLY (never converges upstream);
+cloud sync is a per-workspace posture, and one plane freely mixes both.
+
 ## sync()
 
 ```ts