create-holon 0.1.3 → 0.1.5

package/LICENSE.md

@@ -24,6 +24,15 @@ with it; we keep the rest for now.
 - offer the Nomos runtime, or anything materially similar, as a hosted service;
 - reverse-engineer the holon wasm runtime.
 
+## Data retention
+
+This is a pre-release we are actively evaluating. Workspaces you retire stop
+counting toward your quota but are NOT deleted: **we retain all workspace data
+(ledgers, law, intents) and may examine it to evaluate how the product is
+used.** Don't put anything in a pre-release workspace you wouldn't want the
+builders to read. If you need something truly expunged, ask:
+jack@captainapp.co.uk.
+
 ## The rest
 
 Provided **as is**, with no warranty of any kind; to the maximum extent

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-holon",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "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/README.md

@@ -43,6 +43,34 @@ After birth, `holon/` tracks YOUR workspace: new writes admitted on main arrive
 with `git pull`. (`githolon git setup` installed a git credential helper, so plain
 git just works against the cloud.)
 
+## Make it YOURS — the five-minute walkthrough
+
+The starter is the tutorial; this is the exact path from guestbook to your own law.
+
+1. **Rename the law file** and reshape it:
+   `git mv domains/guestbook.ts domains/<yours>.ts` — keep the patterns
+   (aggregate fields each tagged a merge driver; directives = zod payload → pure
+   plan; `addToSet` for AddWins sets — `set()` on a set field is refused).
+2. **Point the compile config at it** — `nomos.package.mjs`:
+   ```js
+   export default { name: "<pkg>", domains: [{ key: "<pkg>", modules: ["./domains/<yours>.ts"] }] };
+   ```
+   **Naming convention:** make `<pkg>` ONE lowercase word (`potluck`, `studygroup`).
+   It becomes the generated symbols verbatim: `build/<pkg>.client.ts` exporting
+   `<pkg>Client(holon)` and `<PKG>_DOMAIN_HASH`.
+3. **Compile and read what you built:**
+   ```bash
+   npx githolon compile && cat build/<pkg>.summary.txt
+   ```
+4. **Re-point the proof** — in `test/e2e.mts`, update the client import and the
+   directive/query/count names to yours; `npm run typecheck` names every stale
+   reference until it's clean.
+5. **Prove it live:** `npm run e2e` — your law deploys to a throwaway workspace,
+   an offline write syncs through admission, the cloud answers your declared
+   query and count, and two blind clients prove the AddWins merge.
+
+Then deploy it for real: `npx githolon login --agent && npx githolon ws create <ws> && npx githolon deploy <ws>`.
+
 ## What's here
 
 - `domains/guestbook.ts` — the starter domain (the law): one aggregate, two

package/template/test/e2e.mts

@@ -51,6 +51,11 @@ ok("local replay — guestbook law Active in the local projection");
 
 // 3. LOCAL-FIRST write through the TYPED surface: payload shape + enum are compile-checked
 const signedAt = new Date().toISOString();
+// THE OFFLINE PROOF IS ENFORCED, not narrated: while we author/query/count
+// LOCALLY, fetch THROWS — if any "local" path touched the network, this test fails.
+const realFetch = globalThis.fetch;
+globalThis.fetch = (() => { throw new Error("OFFLINE PROOF VIOLATED: local authoring touched the network"); }) as typeof fetch;
+
 await app.signGuestbook({ author: "ada", message: "hello from the edge of the network", mood: "delighted", signedAt, tags: ["first-entry"] });
 ok("typed dispatch signGuestbook — offline write under the pulled law");
 
@@ -77,6 +82,9 @@ const localCount = await app.entriesPerMood("delighted");
 if (localCount !== 1) fail(`local declared count: ${localCount}`);
 ok("declared count maintained locally — entriesPerMood('delighted') = 1");
 
+globalThis.fetch = realFetch;
+ok("offline proof ENFORCED — fetch was trapped: local write/query/mutate/count touched no network");
+
 // 6. sync: push the session branch + edge admission merges to main
 const s = await holon.sync({ admit: true });
 if (!s.admission?.ok) fail(`sync/admit: ${JSON.stringify(s)}`);