create-githolon 0.93.0 → 0.94.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-githolon",
-  "version": "0.93.0",
+  "version": "0.94.2",
   "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/02-authoring.md

@@ -16,13 +16,27 @@ export const Book = aggregate("Book", {
 });
 ```
 
-Field kinds: `t.string()` · `t.int()` · `t.enum([...] as const)` (typos squeal
+Field kinds: `t.string()` · `t.int()` · `t.bool()` (a true/false flag —
+count/filter key on it; NOT a 2-value `t.enum`) · `t.enum([...] as const)` (typos squeal
 at compile time) · `t.set(t.string())` · `t.map(inner)` · `t.json()` /
 `t.jsonObject()` (JSON-string leaf; `jsonObject` asserts an object and reads
 back structured) · `t.ref(Agg)` (an id-valued reference) ·
 `t.hasMany(Child).via("parent")` (the virtual read side of a child's ref —
 nothing stored on the parent). Add `.optional()` where absence is legal.
 
+**Cross-workspace links are TYPED — never a bare string.** A reference into ANOTHER
+workspace (its own app-specific ledger — a Task pointing at a Space, a Project at a
+catalogue) is `t.foreignRef({ workspace: "<sibling field holding the foreign workspace
+id>", target: SpaceOwner })`. It stores the foreign aggregate id, types the edge as
+`ForeignRef<SpaceOwnerData>`, and the generated client emits `.resolve(nomos)` /
+`.watch(nomos)` to open the other holon on demand. Cross-domain imports are first-class
+(`import { SpaceOwner } from "./space.ts"`). It is a typed LOCATOR, not a gate-enforced
+foreign key (separate ledgers = no cross-workspace referential integrity at the gate);
+law that must depend on the foreign FACT opts into attested evidence via `trustSource`
++ `.readsFrom(...)`. Worked four-layer example (home → Space + Project with a typed
+cross-ref): `bench/scale/fixtures/four-layer-nested-topology`. **Do NOT store a foreign
+workspace name in a plain `t.string()` — that throws away the type and the resolver.**
+
 ## Relationships: reference aggregates, don't hand-roll composite ids
 
 When one aggregate points at another — a listing's primary image, its many
@@ -75,20 +89,20 @@ const PostalAddress = valueObject("PostalAddress", {
   streetAddress: z.string(), city: z.string(), countryCode: z.string(),
 });
 const GeoPoint = geo.point("GeoPoint");            // RFC 7946 Point
-const SiteLocation = valueObject("SiteLocation", {
+const TaskLocation = valueObject("TaskLocation", {
   address: PostalAddress.optional(),               // VOs nest in VOs
   point: GeoPoint.optional(),
 });
 
-export const EstateSite = aggregate("EstateSite", {
+export const ProjectTask = aggregate("ProjectTask", {
   name: t.string().merge(Lww),
-  location: SiteLocation.field().optional(),       // ONE json-object leaf
+  location: TaskLocation.field().optional(),       // ONE json-object leaf
   point: GeoPoint.field().optional(),              // give a geometry its OWN field…
 });
-export const sitesByBounds = spatial("sitesByBounds").of(EstateSite).on("point"); // …to index it
-export const recordSite = directive("recordSite").creates(EstateSite)
-  .payload(z.object({ name: z.string(), location: SiteLocation.zod })) // the SAME zod validates
-  .plan((p) => { create(EstateSite).set("name", p.name).set("location", p.location); return []; });
+export const tasksByBounds = spatial("tasksByBounds").of(ProjectTask).on("point"); // …to index it
+export const recordTask = directive("recordTask").creates(ProjectTask)
+  .payload(z.object({ name: z.string(), location: TaskLocation.zod })) // the SAME zod validates
+  .plan((p) => { create(ProjectTask).set("name", p.name).set("location", p.location); return []; });
 ```
 
 ONE definition yields the zod (payload validation — a malformed VO is the
@@ -128,29 +142,29 @@ no behavior:
 
 ```ts
 // contracts.ts — the shared public shapes
-export const CatalogueListingContract = contract("CatalogueListing", {
-  listingId: t.string(),
+export const SpaceLabelContract = contract("SpaceLabel", {
+  labelId: t.string(),
   name: t.string(),
 });
 
-// catalogue.ts — the concrete owner declares it satisfies the shape (compile-checked;
+// space.ts — the concrete owner declares it satisfies the shape (compile-checked;
 // a missing/mismatched field fails the build naming it). Private fields stay private.
-export const CatalogueListing = aggregate("CatalogueListing", {
-  listingId: t.string().merge(Lww),
+export const SpaceLabel = aggregate("SpaceLabel", {
+  labelId: t.string().merge(Lww),
   name: t.string().merge(Lww),
   internalNotes: t.string().merge(Lww),      // not in the contract — behind the boundary
-}).implements(CatalogueListingContract);
+}).implements(SpaceLabelContract);
 
-// estate.ts — reference the CONTRACT, never the concrete aggregate
-export const EstateAsset = aggregate("EstateAsset", {
-  catalogueWorkspaceName: t.string().merge(Lww),
-  listing: t.foreignRef({ workspace: "catalogueWorkspaceName", target: CatalogueListingContract, domain: "catalogue" }),
+// project.ts — reference the CONTRACT, never the concrete aggregate
+export const ProjectTask = aggregate("ProjectTask", {
+  spaceWorkspaceName: t.string().merge(Lww),
+  label: t.foreignRef({ workspace: "spaceWorkspaceName", target: SpaceLabelContract, domain: "space" }),
 });
 ```
 
-The generated client types the reference as `ForeignRef<CatalogueListingContract>`;
-the Dart DTO class lives in a shared `contracts.dart` every domain imports, so `estate`
-never imports `catalogue`'s implementation. If two domains ever import each other's
+The generated client types the reference as `ForeignRef<SpaceLabelContract>`;
+the Dart DTO class lives in a shared `contracts.dart` every domain imports, so `project`
+never imports `space`'s implementation. If two domains ever import each other's
 concrete types, the compiler fails with a cycle diagnostic pointing you here. Contracts
 are pure typing metadata — they never change an aggregate's law hash.
 
@@ -161,9 +175,9 @@ each deliberately (the names below are the DEFAULTS, derived from your ids):
 
 | tier | what it is | generated name |
 |---|---|---|
-| **Command payloads** | the typed input to a directive (`toPayloadJson()`) | `<Cap(directiveId)>Payload` — e.g. `CreateSitePayload` |
-| **Aggregate state** | the concrete decoded aggregate class | `<Cap(aggId)>` — e.g. `EstateSite` |
-| **Read models / projections** | the typed projection row (incl. derived/combined fields) | `<stem(aggId)>ReadModel` — e.g. `EstateSiteReadModel` |
+| **Command payloads** | the typed input to a directive (`toPayloadJson()`) | `<Cap(directiveId)>Payload` — e.g. `RecordTaskPayload` |
+| **Aggregate state** | the concrete decoded aggregate class | `<Cap(aggId)>` — e.g. `ProjectTask` |
+| **Read models / projections** | the typed projection row (incl. derived/combined fields) | `<stem(aggId)>ReadModel` — e.g. `ProjectTaskReadModel` |
 | **Value objects** | a named structured value (`valueObject`/`geo.*`) | the VO's own declared name, unprefixed |
 
 The wire identity (aggregate id, stable ids, projection type tag) is separate from ALL of
@@ -171,34 +185,34 @@ these — names are labels, identity is minted. Renaming below never touches the
 
 ### `.dartName()` — declare the product name (Dart codegen only)
 
-An aggregate id is often long for uniqueness (`EstateSite`); the Dart product name you want
-is short (`Site`). `.dartName("Site")` makes `Site` the PRIMARY generated Dart identity —
+An aggregate id is often long for uniqueness (`ProjectTask`); the Dart product name you want
+is short (`Task`). `.dartName("Task")` makes `Task` the PRIMARY generated Dart identity —
 not a post-hoc alias:
 
 ```ts
-export const EstateSite = aggregate("EstateSite", {
+export const ProjectTask = aggregate("ProjectTask", {
   owner: t.string().merge(Lww),
   name: t.string().merge(Lww),
-}).public().dartName("Site");
+}).public().dartName("Task");
 ```
 
-Now EVERY Dart site renames consistently: the state class `Site`, the read model
-`SiteReadModel`, the typed id `SiteId`, the by-id accessors `readSiteById`/`watchSiteById`,
-`listSites`, and any `ForeignRef<Site>`. The WIRE id stays `EstateSite` (unchanged law,
-unchanged stable ids — the minted-id tag is still `EstateSite_<uuid>`). It is validated
+Now EVERY Dart site renames consistently: the state class `Task`, the read model
+`TaskReadModel`, the typed id `TaskId`, the by-id accessors `readTaskById`/`watchTaskById`,
+`listTasks`, and any `ForeignRef<Task>`. The WIRE id stays `ProjectTask` (unchanged law,
+unchanged stable ids — the minted-id tag is still `ProjectTask_<uuid>`). It is validated
 at author time (must be a Dart type identifier `^[A-Z][A-Za-z0-9_]*$`; a collision with
 another aggregate's name fails the compile). **TS codegen is deliberately unaffected** —
-the generated `.client.ts` stays id-derived (`EstateSiteData`), so there is no
+the generated `.client.ts` stays id-derived (`ProjectTaskData`), so there is no
 cross-language identity confusion; `.dartName()` is a Dart-only presentation choice.
 
 ### Namespaces, not prefixes (multi-domain packages)
 
-Each domain compiles to its OWN generated `.dart` library (`estate.dart`, `catalogue.dart`).
-That IS Dart's namespace mechanism: two domains can BOTH declare a `Site` and stay
-unambiguous — `import 'package:x/src/generated/estate.dart' as estate;` then `estate.Site`.
+Each domain compiles to its OWN generated `.dart` library (`project.dart`, `space.dart`).
+That IS Dart's namespace mechanism: two domains can BOTH declare a `Comment` and stay
+unambiguous — `import 'package:x/src/generated/project.dart' as project;` then `project.Comment`.
 The compiler never smashes a domain word into your class name. The top-level package barrel
 flat-re-exports every domain's classes by default (`dart.packages.barrelExports: 'all'`);
-for a multi-domain package where you'd rather force prefixed imports (so two `Site`s never
+for a multi-domain package where you'd rather force prefixed imports (so two `Comment`s never
 silently share one flat scope), set `barrelExports: 'explicit'` — the barrel then exports
 only the shared core and you import each domain with an `as` prefix. A single-domain package
 is unaffected either way.
@@ -215,24 +229,24 @@ generated name via `dart.names`, and route it to the compat package:
 dart: {
   support: "package",
   packages: {
-    types:  "co2_estate_types",
-    client: "co2_estate_client",
-    test:   "co2_estate_test",
-    compat: "co2_estate_compat_names",   // ← the migration-only shim
+    types:  "task_tracker_types",
+    client: "task_tracker_client",
+    test:   "task_tracker_test",
+    compat: "task_tracker_compat_names",   // ← the migration-only shim
   },
-  // EstateSite.dartName("Site") → the read model is now `SiteReadModel`. Callers that
-  // imported the old `SiteRootAggregate` name keep compiling via the compat typedef.
-  names: { SiteReadModel: "SiteRootAggregate" },
+  // ProjectTask.dartName("Task") → the read model is now `TaskReadModel`. Callers that
+  // imported the old `TaskRootAggregate` name keep compiling via the compat typedef.
+  names: { TaskReadModel: "TaskRootAggregate" },
 }
 ```
 
-The `co2_estate_compat_names` package then contains exactly:
+The `task_tracker_compat_names` package then contains exactly:
 
 ```dart
 // MIGRATION-ONLY — delete this package once callers have moved to the real names in
-// `co2_estate_types`. …
-import 'package:co2_estate_types/co2_estate_types.dart';
-typedef SiteRootAggregate = SiteReadModel;
+// `task_tracker_types`. …
+import 'package:task_tracker_types/task_tracker_types.dart';
+typedef TaskRootAggregate = TaskReadModel;
 ```
 
 When `compat` is UNSET, the typedefs land in the types barrel exactly as before.

package/template/docs/03-client.md

@@ -36,7 +36,7 @@ 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
+local workspaces (the user's home, each space, each project). Don't build
 on a single-connection assumption — hold one PLANE and many handles on it.
 The four-layer split (the blessed shape):
 
@@ -50,7 +50,7 @@ The four-layer split (the blessed shape):
 
 - **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-…"));`
+  `const realm = await openRealm({ cloud }); const project = projectClient(await realm.workspace("project-…"));`
   (`connect()` remains the one-workspace sugar over the same machinery.)
 - **Flutter/Dart** — session-bound clients, preflighted at construction:
 
@@ -61,13 +61,13 @@ The four-layer split (the blessed shape):
   final homeClient = await HomeClient.bind(home); // ASYNC preflight (see below)
 
   final platform = await engine.open(cloud: cloud, workspace: platformWs);
-  final platformClient = await Co2PlatformClient.bind(platform);
+  final platformClient = await PlatformClient.bind(platform);
 
   // A `.births()` directive takes NO parent — the parent IS the session workspace:
-  final birth = await platformClient.birthEstateWorkspace(payload: order);
+  final birth = await platformClient.birthProjectWorkspace(payload: order);
   // NomosRef is THE cross-workspace primitive — follow it, bind the next client:
-  final estate = await engine.follow(birth.bornRefs.single);
-  final estateClient = await EstateClient.bind(estate);
+  final project = await engine.follow(birth.bornRefs.single);
+  final projectClient = await ProjectClient.bind(project);
   ```
 
   `XClient.bind(session)` verifies the session's workspace is reachable, holds
@@ -127,6 +127,37 @@ AddWins union keeps every add. No locks, no "last writer wins the whole
 record", no merge code — the field's declared driver did it
 (see [02-authoring.md](./02-authoring.md)).
 
+## Typed-client patterns (the three gotchas)
+
+Building with the generated typed client (`XClient.bind(session)` — no string
+directive ids), three things trip people up once and never again:
+
+- **Success = `outcome.ok`.** A directive method returns a `NomosOfferOutcome`;
+  `outcome.ok` is true when it committed (a refusal *throws* / surfaces its typed
+  law error, it doesn't return a false outcome). For a `.creates` you also get the
+  minted id back with no query round-trip; for a `.births` you get `outcome.born`.
+- **Timestamps are caller-stamped — pass them.** Payload fields like `createdAt` /
+  `bornAt` are `required` BY DESIGN, not an oversight: a plan is a pure function of
+  its payload and reads no clock (determinism — every peer replays the same bytes).
+  Stamp `DateTime.now().toUtc().toIso8601String()` at the call site. This is the
+  timestamp doctrine, not friction to remove.
+- **Apps hold MANY workspaces open at once — that is the model, not an edge case.**
+  `bridge.session(ws)` returns a live session from the REALM (one engine, N mounted
+  workspaces, LRU park/remount above a budget). A Space AND a Project AND the home
+  are all open concurrently; there is no singleton "current workspace" (that surface
+  would be the bug). See [10-flutter-layering.md](./10-flutter-layering.md).
+- **A cross-workspace `ForeignRef` has TWO read paths — don't confuse them.**
+  `task.space` (a `ForeignRef<SpaceOwnerData>`) is a typed LOCATOR.
+  - **App/presentation read:** `await task.space.resolve(nomos)` / `.watch(nomos)`
+    reads the target THROUGH the open realm — instant when that Space is already a
+    live session (it usually is), a mount otherwise. This is live UI data, not law.
+  - **Law read (a plan's DECISION depends on the foreign fact):** never a live
+    resolve — declare `trustSource` + `.readsFrom(...)` so the fact is CAPTURED onto
+    the intent and re-verified on every replay (the captured-ports / attested-read
+    doctrine, deterministic). `foreignRef` also generates `.attest(nomos)` for that
+    evidence. Separate ledgers mean readability is policy, not a gate-checked FK —
+    see [09-attested-reads.md](./09-attested-reads.md).
+
 ## Persistence
 
 `holon.export()` → bytes; `connect({ restoreFrom: bytes })` restores. Pending

package/template/docs/06-law-evolution.md

@@ -153,9 +153,9 @@ intent parks in the dead-letter queue on both sides, then replays with
 `retryDeadLetter` once the law is deployed (see [04-cloud.md](./04-cloud.md)).
 Deploy first, then ship the client.
 
-### Sharded estates
+### Sharded workspaces
 
-On a sharded (coordinator + shards) estate you deploy ONCE, to the coordinator:
+On a sharded (coordinator + shards) workspace you deploy ONCE, to the coordinator:
 the cloud fans the same deploy into every open shard
 (`/deploy-from-coordinator`, idempotent per package hash). Proven live in
 `cloud/web-client/test/heavy_coordinator.e2e.mjs`.

package/template/docs/07-security.md

@@ -67,6 +67,22 @@ How it behaves:
 - **Who you are.** A read carries the principal (an `x-nomos-auth` token, verified;
   or the transitional `x-nomos-principal`). No principal ⇒ a private read is
   refused, fail-closed.
+- **⚠️ A private workspace needs its OWN verifier (`setAuthProvider`).** The token is
+  verified **against the workspace's own law-declared AuthProvider** — every workspace
+  verifies for itself; there is no global verifier, and **a child does NOT inherit its
+  parent's AuthProvider**. If a private workspace has **no** AuthProvider, a presented
+  `x-nomos-auth` token cannot be verified and the read falls back to the **unverified**
+  bare `x-nomos-principal` claim — i.e. anyone who *claims* to be the owner is served.
+  So a workspace that holds private (`requires(cap)`) or `.encrypted()` data **must**
+  `setAuthProvider` for itself (issuer + JWKS/keys + audience), authored by a principal
+  the workspace's law authorizes. This is true for **every** private workspace — a
+  platform, and each home/space/project born under it. Births do **not** seed it for you:
+  the birth recipe installs law + seats the owner, but the AuthProvider is a separate
+  `setAuthProvider` the new workspace's owner authors (you can copy the parent's config).
+  Refusals are typed — a 403 on a bulk read (`/pack`, `/snapshot`, clone) names the
+  premise (`no-authprovider-verifier` / `token-verification-failed` / `no-principal-presented`
+  / `principal-lacks-workspace-read-cap`), the resolved principal, the required cap, and
+  the workspace's issuer — so the app can tell "token expired" from "not granted."
 - **Revocation is honest.** Remove-wins: a revoked principal can never be
   re-granted by a replayed grant. The post-revoke read re-derives authority from
   the maintained projection — cost scales with the number of *identities*, not

package/template/docs/08-births.md

@@ -1,7 +1,7 @@
 # Birthing child workspaces (law-at-birth)
 
 A directive in your law can **birth a child workspace** that is born already running its own domain law.
-A home births estate children; a platform births workspaces; root births platforms — all the **same one
+A home births project children; a platform births workspaces; root births platforms — all the **same one
 way**. You do *not* ask Nomos for a new primitive and you do *not* hand a finished workspace to the cloud.
 
 ## How it works (birth is a kernel concern, defined by the ledger)
@@ -18,7 +18,7 @@ The host installs nothing and decides nothing. The recipe is a **ledger fact**,
 
 ## The leaf recipe = two installs + your seed
 
-A leaf child (a home, an estate item) is born with exactly:
+A leaf child (a home, a project) is born with exactly:
 
 ```
 [ bootstrap/installDomain(<frameworkHash>),   // the bootstrap controller (bytes-by-hash, kernel-resolved)
@@ -31,9 +31,9 @@ resolves the bytes from custody by hash — they are never shipped on the wire).
 
 ## Every birth is **keyed** — so you can find the workspace again
 
-A workspace exists to be **used**, and using it — sync it, open it, place an asset in it — means **finding it
+A workspace exists to be **used**, and using it — sync it, open it, add a task to it — means **finding it
 again**, often from another device or after a restart. So a born workspace's name is **never** opaque or
-minted-and-forgotten: it is always **derived from a key you already own** (a business id like `estateId`, or
+minted-and-forgotten: it is always **derived from a key you already own** (a business id like `projectId`, or
 an owner uid). One verb: **`birth.keyed`**.
 
 > **The one rule.** The name comes from a key you own → the client re-derives the same name from that same
@@ -44,10 +44,10 @@ an owner uid). One verb: **`birth.keyed`**.
 ```ts
 import { directive, birth, create, z } from "@githolon/dsl";
 
-export const birthEstate = directive("birthEstate")
-  .creates(EstateBirth)                       // your lineage/audit row
+export const birthProject = directive("birthProject")
+  .creates(ProjectBirth)                      // your lineage/audit row
   .payload(z.object({
-    estateId: z.string().min(1),              // THE KEY — an id you mint app-side; the workspace is FOR it
+    projectId: z.string().min(1),             // THE KEY — an id you mint app-side; the workspace is FOR it
     owner: z.string().min(1),
     frameworkHash: z.string().min(1),
     lawHash: z.string().min(1),
@@ -56,36 +56,36 @@ export const birthEstate = directive("birthEstate")
   .plan((p) => {
     const actor = "user:" + p.owner;
     birth.keyed({
-      key: p.estateId,                        // ← the workspace name is derived from this
-      namespace: "estate",                    // → estate-<sha256(estate ⏎ estateId)[:40]>
+      key: p.projectId,                       // ← the workspace name is derived from this
+      namespace: "project",                   // → project-<sha256(project ⏎ projectId)[:40]>
       genesisChain: (ws) => [                 // the builder receives the resolved name
         { domain: "bootstrap", directiveId: "installDomain", actor, payload: { domainHash: p.frameworkHash }, domainHash: p.frameworkHash, domainPackageB64: "" },
         { domain: "nomos",     directiveId: "installDomain", actor, payload: { domainHash: p.lawHash },       domainHash: p.lawHash,       domainPackageB64: "" },
-        { domain: "estate",    directiveId: "seedEstate", actor, payload: { estateId: p.estateId, workspaceName: ws, bornAt: p.bornAt } },
+        { domain: "project",   directiveId: "seedProject", actor, payload: { projectId: p.projectId, workspaceName: ws, bornAt: p.bornAt } },
       ],
     });
     return [];
   })
   .births()
-  .requires("estateCreator");
+  .requires("projectCreator");
 ```
 
-Then in the app you address that estate from just its id — **no lookup table, no persisted name**:
+Then in the app you address that project from just its id — **no lookup table, no persisted name**:
 
 ```dart
 // Dart (nomos_client)
-final ws = deriveWorkspaceName('estate', estateId);
-final session = await engine.open(ws);        // open / sync / place assets — any device, any time
+final ws = deriveWorkspaceName('project', projectId);
+final session = await engine.open(ws);        // open / sync / add tasks — any device, any time
 ```
 ```ts
 // TS (@githolon/client)
-const ws = await deriveWorkspaceName('estate', estateId);
+const ws = await deriveWorkspaceName('project', projectId);
 const holon = await connect({ cloud, workspace: ws, clientId });
 ```
 
 `deriveWorkspaceName` computes the byte-identical name the law's `birth.keyed` produced (contract-tested
 across the engine, Dart, and TS). This is the helper that replaces every hand-rolled
-`estateWorkspaceForEstateId` — delete yours and use this.
+`projectWorkspaceForProjectId` — delete yours and use this.
 
 ### One-per-user things (a home): `birth.singleton`
 
@@ -111,9 +111,9 @@ workspace IS the parent — no loose parent string, and the born child comes bac
 
 ```dart
 final parentClient = await MyPlatformClient.bind(parentSession);
-final birth = await parentClient.birthEstateChild(payload: order);   // parent = the session workspace
+final birth = await parentClient.birthProjectChild(payload: order);  // parent = the session workspace
 final child = await engine.follow(birth.bornRefs.single);            // mount the born child
-final childClient = await EstateClient.bind(child);                  // typed client on the child
+final childClient = await ProjectClient.bind(child);                 // typed client on the child
 ```
 
 (The old `parent:` parameter survives one minor version as a deprecated legacy-gateway shim; its verdict
@@ -122,13 +122,13 @@ rides `outcome.gatewayVerdict`.)
 ## Authority — who may birth
 
 `.requires("creator")` gates the birth on a relation tuple. Grant the home owner `#creator` on their own
-home (self-bound at birth, the same way the owner is seeded) so a verified owner can birth their estate
+home (self-bound at birth, the same way the owner is seeded) so a verified owner can birth their project
 children — and only their own. (Relations: `grant` / `writeTuple`, see `07-security.md`. Use whatever
 relation models your policy; `creator` is the convention `birthChild` uses.)
 
 ## What NOT to do
 
-- **Don't hand-roll the child's name** (`estate-<sha256(owner)>`, or your own `estateWorkspaceForEstateId`).
+- **Don't hand-roll the child's name** (`project-<sha256(owner)>`, or your own `projectWorkspaceForProjectId`).
   `birth.keyed` owns the naming and `deriveWorkspaceName` gives the client the identical name — hand-rolling
   either half is how the two drift and a workspace becomes unfindable.
 - **Don't use `birth.instance`.** It's deprecated — it mints a name you can't re-derive, so the workspace is
@@ -154,7 +154,7 @@ npx githolon proof        # OFFLINE: drives your .births() directive on the real
 A red proof names the exact genesis step the child's gate refused. The most common first-timer halt: a
 plan that returns a fluent builder — builders record themselves, so end the plan with `return [];`.
 A complete working two-domain births package to copy: `bench/scale/fixtures/home-delegated-estate` (nomos2
-repo) — it births estates with `birth.keyed` (addressable by estate key) and is exercised by
+repo) — it births child workspaces with `birth.keyed` (addressable by key) and is exercised by
 `bench/scale/home_delegated_estate.smoke.mjs`.
 
 ## Posture at birth
@@ -166,11 +166,11 @@ the child's own consent fact first (a heal = consent first). See
 [11-governance-postures.md](./11-governance-postures.md) for the two postures, the consent ceremony, and
 the exit rights.
 
-## Offline estate creation via delegated authority (`delegatedRole` / `.delegatedFrom(parent)`)
+## Offline workspace creation via delegated authority (`delegatedRole` / `.delegatedFrom(parent)`)
 
 Sometimes a CHILD must birth its own children **offline**, under authority a PARENT granted — with no
-contact with the parent at authoring time. Example: a platform **P** lets a user **U** create estates; U
-holds a **home** holon **H** on-device; U births an estate **E** as a child of H, offline, gated by H's
+contact with the parent at authoring time. Example: a platform **P** lets a user **U** create projects; U
+holds a **home** holon **H** on-device; U births a project **E** as a child of H, offline, gated by H's
 law. The parent's grant cannot be an author-time attested read (that needs connectivity). Instead the
 grant is **delivered into H as a signed cert and folded as a local authority fact** — then read offline.
 
@@ -178,21 +178,21 @@ Author the delivery directive with `.delegatedRole(relation).delegatedFrom(paren
 
 ```ts
 export const acceptDelegatedRole = directive("acceptDelegatedRole")
-  .creates(EstateCreatorGrant)
+  .creates(ProjectCreatorGrant)
   .payload(z.object({ subject: roleSubject, delegationCert: z.string().min(1), grantedBy: roleSubject, grantedAt: z.string() }))
   .plan((p) => {
-    create(EstateCreatorGrant).set("subject", p.subject).set("grantedAt", p.grantedAt);
-    return writeTuple({ object: "workspace:self", relation: "estateCreator", subject: p.subject, grantedBy: p.grantedBy, grantedAt: p.grantedAt });
+    create(ProjectCreatorGrant).set("subject", p.subject).set("grantedAt", p.grantedAt);
+    return writeTuple({ object: "workspace:self", relation: "projectCreator", subject: p.subject, grantedBy: p.grantedBy, grantedAt: p.grantedAt });
   })
-  .grants("estateCreator")
-  .delegatedRole("estateCreator", { subjectField: "subject", certField: "delegationCert" })
+  .grants("projectCreator")
+  .delegatedRole("projectCreator", { subjectField: "subject", certField: "delegationCert" })
   .delegatedFrom({ parentKeyObject: "birth-attestation:self", parentKeyField: "parentKey" }); // H's parent P's key
 
 // the birth itself is gated on the DELIVERED local tuple — read OFFLINE, no parent contact:
-export const birthEstateWorkspace = directive("birthEstateWorkspace")
-  .creates(EstateBirthOrder).payload(/* … */).plan(/* birth(...) */)
+export const birthProjectWorkspace = directive("birthProjectWorkspace")
+  .creates(ProjectBirthOrder).payload(/* … */).plan(/* birth(...) */)
   .births()
-  .requires("estateCreator"); // ← reads the delegated tuple folded by acceptDelegatedRole
+  .requires("projectCreator"); // ← reads the delegated tuple folded by acceptDelegatedRole
 ```
 
 How it works:
@@ -204,7 +204,7 @@ How it works:
 - **The birth is authored OFFLINE**, gated only by H's LOCAL folded tuple; `verify_chain` re-verifies the
   delegation to `K_root` with no cross-workspace read.
 - **Revocation is forward-only + evidence-preserving.** P delivers a revoke (`removeTuple`, same gate);
-  the folded tuple flips revoked (`RemoveWins`), so U's NEXT birth refuses — but an estate born WHILE the
+  the folded tuple flips revoked (`RemoveWins`), so U's NEXT birth refuses — but a project born WHILE the
   grant was live re-verifies green forever (verify_chain re-folds the chain prefix at each intent's
   position). Both the grant and the revoke are permanent ledger facts.
 

package/template/docs/09-attested-reads.md

@@ -13,7 +13,7 @@ import { z, directive, read, trustSource, foreignQuery } from "@githolon/dsl";
 const platformPolicy = foreignQuery("platformPolicy"); // the SOURCE's declared query, by id
 
 // module level — the trust boundary IS law (rides the domainHash):
-export const platformTrust = trustSource("co2-platform", {
+export const platformTrust = trustSource("acme-platform", {
   genesis: "9d1c…",            // the source's genesis oid (its true identity — names are routing)
   keyHashes: ["41aa…"],        // sha256 of the source's read-attestor public key(s)
   maxAgeMs: 86_400_000,        // how stale an envelope may be vs the intent's own clock
@@ -24,9 +24,9 @@ export const platformTrust = trustSource("co2-platform", {
 export const enrollDevice = directive("enrollDevice")
   .creates(HomeDevice)
   .payload(z.object({ device: z.string() }))
-  .readsFrom("co2-platform", platformPolicy)   // the declared foreign read
+  .readsFrom("acme-platform", platformPolicy)   // the declared foreign read
   .plan((p) => {
-    const rows = read(platformPolicy, { scope: "homes" }, { from: "co2-platform" });
+    const rows = read(platformPolicy, { scope: "homes" }, { from: "acme-platform" });
     if (rows[0]?.data?.enrollmentOpen !== "true") throw new Error("enrollment closed");
     create(HomeDevice).set("device", p.device);
     return [];
@@ -51,10 +51,10 @@ lanes, in precedence order:
 
 ```ts
 const holon = await connect({ cloud, workspace, clientId,
-  attestedSources: { "co2-platform": "https://nomos.captainapp.co.uk" } }); // optional override
+  attestedSources: { "acme-platform": "https://nomos.captainapp.co.uk" } }); // optional override
 await holon.dispatch("home", "enrollDevice", { device: "d-1" });
 // → the kernel refuses TYPED naming the missing read; the client fetches
-//   GET <sourceCloud>/v2/workspaces/co2-platform/platformPolicy?scope=homes&attest=1
+//   GET <sourceCloud>/v2/workspaces/acme-platform/platformPolicy?scope=homes&attest=1
 //   injects the signed envelope, retries — automatically.
 ```
 

package/template/docs/10-flutter-layering.md

@@ -17,8 +17,8 @@ export default {
     },
     names: {
       // public aliases over the stable generated identities (typedefs in the types barrel)
-      AcmeEstateCustomFieldDefinitionFieldType: "FieldType",
-      AcmeEstateDrawingTransform2d: "DrawingTransform2d",
+      AcmeProjectCustomFieldDefinitionFieldType: "FieldType",
+      AcmeProjectDrawingTransform2d: "DrawingTransform2d",
     },
   },
 };