@granular-software/sdk 0.4.21 → 0.4.23

package/dist/cli/index.js

@@ -5496,13 +5496,19 @@ var LIBRARY_TEMPLATE = {
   operations: [
     createClassOperation("author", {
       name: { type: "string", description: "Author full name" },
-      nationality: { type: "string", description: "Primary nationality or home region" },
+      nationality: {
+        type: "string",
+        description: "Primary nationality or home region"
+      },
       birth_year: { type: "number", description: "Year of birth" }
     }),
     createClassOperation("book", {
       title: { type: "string", description: "Book title" },
       isbn: { type: "string", description: "ISBN identifier" },
-      publication_year: { type: "number", description: "Year the book was first published" },
+      publication_year: {
+        type: "number",
+        description: "Year the book was first published"
+      },
       price_eur: { type: "number", description: "Current list price in euros" }
     }),
     createClassOperation("publisher", {
@@ -5512,7 +5518,10 @@ var LIBRARY_TEMPLATE = {
     }),
     createClassOperation("editor", {
       name: { type: "string", description: "Editor full name" },
-      specialty: { type: "string", description: "Editorial focus or genre specialty" },
+      specialty: {
+        type: "string",
+        description: "Editorial focus or genre specialty"
+      },
       email: { type: "email", description: "Work email address" }
     }),
     createRelationshipOperation({
@@ -5710,8 +5719,14 @@ var LIBRARY_TEMPLATE = {
       inputSchema: {
         type: "object",
         properties: {
-          collection: { type: "string", description: "Destination collection name" },
-          note: { type: "string", description: "Optional note attached to the bookmark" }
+          collection: {
+            type: "string",
+            description: "Destination collection name"
+          },
+          note: {
+            type: "string",
+            description: "Optional note attached to the bookmark"
+          }
         }
       },
       outputSchema: {
@@ -5745,7 +5760,10 @@ var LIBRARY_TEMPLATE = {
       inputSchema: {
         type: "object",
         properties: {
-          format: { type: "string", description: "Requested format such as paperback, ebook, or audio" },
+          format: {
+            type: "string",
+            description: "Requested format such as paperback, ebook, or audio"
+          },
           quantity: { type: "number", description: "How many copies to order" }
         },
         required: ["format"]
@@ -5782,7 +5800,10 @@ var LIBRARY_TEMPLATE = {
       inputSchema: {
         type: "object",
         properties: {
-          channel: { type: "string", description: "Notification channel such as email or push" }
+          channel: {
+            type: "string",
+            description: "Notification channel such as email or push"
+          }
         },
         required: ["channel"]
       },
@@ -5813,8 +5834,15 @@ var LIBRARY_TEMPLATE = {
         type: "object",
         properties: {
           email: { type: "string", description: "Destination email address" },
-          bookIds: { type: "array", items: { type: "string" }, description: "Books to include in the list" },
-          message: { type: "string", description: "Optional note for the recipient" }
+          bookIds: {
+            type: "array",
+            items: { type: "string" },
+            description: "Books to include in the list"
+          },
+          message: {
+            type: "string",
+            description: "Optional note for the recipient"
+          }
         },
         required: ["email", "bookIds"]
       },
@@ -5849,10 +5877,16 @@ var SUPPORT_TEMPLATE = {
     createClassOperation("customer", {
       name: { type: "string", description: "Customer display name" },
       email: { type: "email", description: "Customer email address" },
-      segment: { type: "string", description: "Customer segment such as self-serve or enterprise" }
+      segment: {
+        type: "string",
+        description: "Customer segment such as self-serve or enterprise"
+      }
     }),
     createClassOperation("order", {
-      number: { type: "string", description: "Order number shown to the customer" },
+      number: {
+        type: "string",
+        description: "Order number shown to the customer"
+      },
       total_eur: { type: "number", description: "Order total in euros" },
       status: { type: "string", description: "Current fulfillment status" }
     }),
@@ -6017,7 +6051,10 @@ var SUPPORT_TEMPLATE = {
       inputSchema: {
         type: "object",
         properties: {
-          message: { type: "string", description: "Reply body sent to the customer" }
+          message: {
+            type: "string",
+            description: "Reply body sent to the customer"
+          }
         },
         required: ["message"]
       },
@@ -6049,7 +6086,10 @@ var SUPPORT_TEMPLATE = {
         type: "object",
         properties: {
           amount: { type: "number", description: "Refund amount in euros" },
-          reason: { type: "string", description: "Reason shown in the payment platform" }
+          reason: {
+            type: "string",
+            description: "Reason shown in the payment platform"
+          }
         },
         required: ["amount"]
       },
@@ -6153,7 +6193,10 @@ var DELIVERY_TEMPLATE = {
     createClassOperation("project", {
       name: { type: "string", description: "Project name" },
       status: { type: "string", description: "Current delivery status" },
-      budget_k_eur: { type: "number", description: "Budget in thousands of euros" }
+      budget_k_eur: {
+        type: "number",
+        description: "Budget in thousands of euros"
+      }
     }),
     createClassOperation("milestone", {
       name: { type: "string", description: "Milestone title" },
@@ -6163,7 +6206,10 @@ var DELIVERY_TEMPLATE = {
     createClassOperation("task", {
       title: { type: "string", description: "Task title" },
       status: { type: "string", description: "Task execution status" },
-      estimate_days: { type: "number", description: "Estimated effort in days" }
+      estimate_days: {
+        type: "number",
+        description: "Estimated effort in days"
+      }
     }),
     createClassOperation("owner", {
       name: { type: "string", description: "Owner full name" },
@@ -6354,7 +6400,10 @@ var DELIVERY_TEMPLATE = {
       inputSchema: {
         type: "object",
         properties: {
-          environment: { type: "string", description: "Target environment such as staging or production" }
+          environment: {
+            type: "string",
+            description: "Target environment such as staging or production"
+          }
         },
         required: ["environment"]
       },
@@ -6385,7 +6434,10 @@ var DELIVERY_TEMPLATE = {
       inputSchema: {
         type: "object",
         properties: {
-          channel: { type: "string", description: "Destination channel such as slack or email" },
+          channel: {
+            type: "string",
+            description: "Destination channel such as slack or email"
+          },
           message: { type: "string", description: "Message body" }
         },
         required: ["channel", "message"]
@@ -6417,7 +6469,10 @@ var DELIVERY_TEMPLATE = {
         type: "object",
         properties: {
           email: { type: "string", description: "Destination email address" },
-          projectId: { type: "string", description: "Project referenced by the report" },
+          projectId: {
+            type: "string",
+            description: "Project referenced by the report"
+          },
           summary: { type: "string", description: "Status report summary" }
         },
         required: ["email", "projectId", "summary"]
@@ -6491,17 +6546,17 @@ function createStarterManifest(name, templateId) {
     schemaVersion: 2,
     name,
     description: `${name} \u2014 ${template.manifestDescription}`,
-    volumes: [{
-      name: "schema",
-      scope: "sandbox",
-      imports: [
-        { alias: "@std", name: "standard_modules", label: "prod" }
-      ],
-      operations: [
-        ...template.operations,
-        ...template.effects.map(createEffectOperation)
-      ]
-    }]
+    volumes: [
+      {
+        name: "schema",
+        scope: "sandbox",
+        imports: [{ alias: "@std", name: "standard_modules", label: "prod" }],
+        operations: [
+          ...template.operations,
+          ...template.effects.map(createEffectOperation)
+        ]
+      }
+    ]
   };
 }
 function generateSeedScript(sandboxId, apiUrl, templateId) {
@@ -6512,8 +6567,12 @@ function generateSeedScript(sandboxId, apiUrl, templateId) {
  * Seed script for the "${template.label}" starter template.
  *
  * Safe to re-run:
- * - \`recordObject()\` upserts by \`{ className, id }\`
+ * - \`recordObject()\` / \`recordObjects()\` upsert by \`{ className, id }\`
  * - relationships are re-applied on each run
+ *
+ * Guidance:
+ * - Use \`recordObject()\` for one record or one targeted update
+ * - Use \`recordObjects()\` for starter datasets like this one so you get chunked writes + progress
  */
 
 import { Granular } from '@granular-software/sdk';
@@ -6548,10 +6607,19 @@ async function main() {
   });
 
   try {
-    for (const record of records) {
-      await env.recordObject(record);
-      console.log(\`Upserted \${record.className}:\${record.id}\`);
-    }
+    let completed = 0;
+    const results = await env.recordObjects(records, {
+      onChunkComplete(info) {
+        completed += info.recordCount;
+        console.log(
+          \`[Seed] Chunk \${info.chunkIndex + 1}/\${info.totalChunks}: committed \${completed}/\${records.length} records (\${info.durationMs}ms)\`,
+        );
+      },
+    });
+
+    const createdCount = results.filter((result) => result.created).length;
+    const updatedCount = results.length - createdCount;
+    console.log(\`[Seed] Created \${createdCount} records, updated \${updatedCount} records.\`);
   } finally {
     await env.disconnect();
   }
@@ -8922,7 +8990,7 @@ The rest of this guide assumes these terms.
 | **Job** | Code string passed to \`environment.submitJob(code)\`. Runs in Granular\u2019s **sandbox runtime** with access to \`./sandbox-tools\` (generated classes + effect entrypoints). |
 | **Effect** | Declared with \`withEffect\`; **handler** registered with \`registerEffects\` in **your** process. Jobs invoke effects; handlers do IO outside Granular. |
 | **Class** | Entity **kind** in the domain (e.g. \`book\`) with \`has\` fields in the manifest. |
-| **Record / object** | One **instance**: \`className\`, \`id\`, \`fields\`, \`relationships\`. Upsert with \`recordObject\`. |
+| **Record / object** | One **instance**: \`className\`, \`id\`, \`fields\`, \`relationships\`. Use \`recordObject\` for one upsert, \`recordObjects\` for several immediate upserts, and record-import APIs for async bulk loads. |
 | **Relationship** | Declared link between two classes; defines **property names** and cardinality. Keys appear in \`recordObject({ relationships })\`. |
 
 ### Data vs actions (short)
@@ -8941,7 +9009,7 @@ function manifestGuideEndToEndSection() {
 | 2 | \`granular build\` | Manifest **uploaded**; ontology version created or reused; build run compiles it; errors surface here |
 | 3 | (Optional) Run your **effects host** \u2014 e.g. \`npx tsx granular-effects.ts\` \u2014 calling \`registerEffects(sandboxId, \u2026)\` | Effect **handlers** attached in **your** process |
 | 4 | \`new Granular({ apiKey })\` then \`connect({ ontology, environment, userId, permissions })\` | **\`Environment\`** for that ontology environment slot |
-| 5 | \`recordObject\` / \`recordObjects\` | **Records** stored with correct fields and relationship keys. \`recordObjects\` chunks to the control plane (default 100 rows/request); pass \`onChunkComplete\` / \`concurrency\` for UI progress. For async bulk loads use \`enqueueRecordImport\` + import status APIs. |
+| 5 | \`recordObject\` / \`recordObjects\` | **Records** stored with correct fields and relationship keys. Use \`recordObject\` for one targeted write. Use \`recordObjects\` for one synchronous multi-record write with chunking (default 100 rows/request), retries, and optional \`onChunkComplete\` / \`concurrency\` progress. For async bulk loads use \`enqueueRecordImport\` + import status APIs. |
 | 6 | \`submitJob(\`\u2026\`)\` with imports from \`./sandbox-tools\` | **Jobs** run; may call **effects** \u2192 your handlers execute and return results |
 
 **Accuracy tip:** After changing the manifest, always **re-build** before assuming generated types, \`./sandbox-tools\` names, or effect signatures match the file on disk.`;
@@ -14629,9 +14697,15 @@ function renderMetamodelDocTable(rows) {
 // src/cli/agent-docs/manifest-guide.ts
 function generateManifestAgentGuide(options) {
   const { projectName } = options;
-  const fieldMetamodelTable = renderMetamodelDocTable(getFieldMetamodelDocRows());
-  const modelMetamodelTable = renderMetamodelDocTable(getModelMetamodelDocRows());
-  const effectMetamodelTable = renderMetamodelDocTable(getEffectMetamodelDocRows());
+  const fieldMetamodelTable = renderMetamodelDocTable(
+    getFieldMetamodelDocRows()
+  );
+  const modelMetamodelTable = renderMetamodelDocTable(
+    getModelMetamodelDocRows()
+  );
+  const effectMetamodelTable = renderMetamodelDocTable(
+    getEffectMetamodelDocRows()
+  );
   return `# Granular manifest guide (for coding agents)
 
 This guide is for **coding agents** who may have **no prior context on Granular**. It explains the product, core terms, how to **author** \`granular.json\`, **build** the domain, and use the SDK (\`connect\` \u2192 **environment**, \`recordObject\`, \`submitJob\`, **effects**). For **this repository\u2019s** exact class names, relationship keys, and effect payloads only, see [GRANULAR_SANDBOX.md](../GRANULAR_SANDBOX.md).
@@ -14961,8 +15035,8 @@ ${effectMetamodelTable}
 |-----|---------|
 | \`environmentId\`, \`sandboxId\`, \`apiEndpoint\`, \u2026 | Session context. |
 | \`applyManifest(manifest)\` | Apply manifest operations at runtime (alternative to CLI build for dynamic ontologies). |
-| \`recordObject\` / \`recordObjects\` | Upsert instances and relationships. \`recordObjects\` uses chunked HTTP batch writes (default 100 rows/chunk); optional \`onChunkComplete\`, \`batchSize\`, \`concurrency\`. |
-| \`enqueueRecordImport\`, \`listRecordImports\`, \`getRecordImportSummary\`, \u2026 | **Async** bulk import (worker queue + aggregate progress). Prefer when loads are huge and fire-and-forget is OK. |
+| \`recordObject\` / \`recordObjects\` | Upsert instances and relationships. Use \`recordObject\` for one object or a targeted patch. Use \`recordObjects\` for synchronous multi-record ingestion with chunked HTTP writes (default 100 rows/chunk), retries, and optional \`onChunkComplete\`, \`batchSize\`, \`concurrency\`. |
+| \`enqueueRecordImport\`, \`listRecordImports\`, \`getRecordImport\`, \`getRecordImportSummary\`, \u2026 | **Async** bulk import (worker queue + aggregate progress). Prefer when loads are huge, returning an \`importId\` is enough up front, and background processing is acceptable. |
 | \`graphql(query, variables?)\` | **GraphQL** \u2014 see dedicated subsection below. |
 | \`defineRelationship\`, \`getRelationships\`, \`attach\`, \`detach\`, \`listRelated\` | Imperative relationship operations (same ideas as manifest \`defineRelationship\`). |
 | \`submitJob(code)\` | Run code in the sandbox; import from \`./sandbox-tools\`. |
@@ -15099,13 +15173,18 @@ function generateSandboxAgentDoc(manifest, meta) {
   lines.push("|-----|-------|");
   lines.push(`| Sandbox id | \`${meta.sandboxId}\` |`);
   if (meta.apiUrl) lines.push(`| API / WS base | \`${meta.apiUrl}\` |`);
-  if (meta.manifestId) lines.push(`| Last uploaded manifest id | \`${meta.manifestId}\` |`);
+  if (meta.manifestId)
+    lines.push(`| Last uploaded manifest id | \`${meta.manifestId}\` |`);
   if (meta.buildId) lines.push(`| Last version id | \`${meta.buildId}\` |`);
   if (meta.buildPending) {
-    lines.push("| Version status | *No successful version/build recorded in this doc run \u2014 run `granular build`.* |");
+    lines.push(
+      "| Version status | *No successful version/build recorded in this doc run \u2014 run `granular build`.* |"
+    );
   }
   lines.push("");
-  lines.push("Set `GRANULAR_API_KEY` (e.g. in `.env.local`). Optional: `GRANULAR_API_URL` overrides the WebSocket URL.");
+  lines.push(
+    "Set `GRANULAR_API_KEY` (e.g. in `.env.local`). Optional: `GRANULAR_API_URL` overrides the WebSocket URL."
+  );
   lines.push("");
   for (const line of sandboxDocMainConceptsSection().split("\n")) {
     lines.push(line);
@@ -15119,18 +15198,40 @@ function generateSandboxAgentDoc(manifest, meta) {
   lines.push("");
   lines.push("| Command | Purpose |");
   lines.push("|---------|---------|");
-  lines.push("| `granular build` | Create or rebuild the current ontology version |");
-  lines.push("| `granular version current --json` | Resolve the latest/current ontology version |");
-  lines.push("| `granular version diff <version> [base]` | Show the semantic diff between versions |");
-  lines.push("| `granular tag move <tag> <version>` | Move a release tag such as `prod` |");
-  lines.push("| `granular document` | Refresh this file from `granular.json` |");
-  lines.push("| `granular connect test --json` | Verify auth and environment connectivity |");
-  lines.push("| `granular session heap --json` | Inspect the normalized session heap |");
-  lines.push("| `granular graphql --query '...' --json` | Query the live graph |");
-  lines.push("| `granular effects list --json` | Inspect declared and live effects |");
-  lines.push("| `granular job run --file ./job.ts --json` | Execute a real runtime job |");
+  lines.push(
+    "| `granular build` | Create or rebuild the current ontology version |"
+  );
+  lines.push(
+    "| `granular version current --json` | Resolve the latest/current ontology version |"
+  );
+  lines.push(
+    "| `granular version diff <version> [base]` | Show the semantic diff between versions |"
+  );
+  lines.push(
+    "| `granular tag move <tag> <version>` | Move a release tag such as `prod` |"
+  );
+  lines.push(
+    "| `granular document` | Refresh this file from `granular.json` |"
+  );
+  lines.push(
+    "| `granular connect test --json` | Verify auth and environment connectivity |"
+  );
+  lines.push(
+    "| `granular session heap --json` | Inspect the normalized session heap |"
+  );
+  lines.push(
+    "| `granular graphql --query '...' --json` | Query the live graph |"
+  );
+  lines.push(
+    "| `granular effects list --json` | Inspect declared and live effects |"
+  );
+  lines.push(
+    "| `granular job run --file ./job.ts --json` | Execute a real runtime job |"
+  );
   lines.push("| `npx tsx " + seed + "` | Seed sample records (if present) |");
-  lines.push("| `npx tsx " + eff + "` | Run effect handler host (if present) |");
+  lines.push(
+    "| `npx tsx " + eff + "` | Run effect handler host (if present) |"
+  );
   lines.push("");
   lines.push("## Connect");
   lines.push("");
@@ -15153,7 +15254,9 @@ function generateSandboxAgentDoc(manifest, meta) {
   lines.push("## Classes and fields");
   lines.push("");
   if (classes.length === 0) {
-    lines.push("*No `create` + `@std/class` operations found in the manifest.*");
+    lines.push(
+      "*No `create` + `@std/class` operations found in the manifest.*"
+    );
     lines.push("");
   } else {
     for (const cls of classes) {
@@ -15179,14 +15282,20 @@ function generateSandboxAgentDoc(manifest, meta) {
   }
   lines.push("## Relationships");
   lines.push("");
-  lines.push("Declared with `defineRelationship`. Submodel names are the **keys** on each class for `recordObject({ relationships: { ... } })`. Values are **foreign class ids** (single string or `string[]` when \u201Cmany\u201D).");
+  lines.push(
+    "Declared with `defineRelationship`. Submodel names are the **keys** on each class for `recordObject({ relationships: { ... } })`. Values are **foreign class ids** (single string or `string[]` when \u201Cmany\u201D)."
+  );
   lines.push("");
   if (relationships.length === 0) {
     lines.push("*No relationships defined.*");
     lines.push("");
   } else {
-    lines.push("| Left | Right | Cardinality | Left key (`leftSubmodel`) | Right key (`rightSubmodel`) |");
-    lines.push("|------|-------|-------------|---------------------------|----------------------------|");
+    lines.push(
+      "| Left | Right | Cardinality | Left key (`leftSubmodel`) | Right key (`rightSubmodel`) |"
+    );
+    lines.push(
+      "|------|-------|-------------|---------------------------|----------------------------|"
+    );
     for (const r of relationships) {
       lines.push(
         `| \`${r.left}\` | \`${r.right}\` | ${r.cardinalityLabel} | \`${r.leftSubmodel}\` | \`${r.rightSubmodel}\` |`
@@ -15196,7 +15305,9 @@ function generateSandboxAgentDoc(manifest, meta) {
   }
   lines.push("## `recordObject` \u2014 examples per class");
   lines.push("");
-  lines.push("`recordObject` upserts by `{ className, id }`. In `relationships`, use **only the target object\u2019s id** for its class (see keys below).");
+  lines.push(
+    "`recordObject` upserts by `{ className, id }`. In `relationships`, use **only the target object\u2019s id** for its class (see keys below)."
+  );
   lines.push("");
   for (const cls of classes) {
     const edges = relationshipEdgesForClass(cls.name, relationships);
@@ -15222,9 +15333,13 @@ function generateSandboxAgentDoc(manifest, meta) {
       lines.push(`  relationships: {`);
       for (const e of edges) {
         if (e.isMany) {
-          lines.push(`    ${e.submodelKey}: ['${e.foreignClass}_id_1'], // ${e.foreignClass} ids`);
+          lines.push(
+            `    ${e.submodelKey}: ['${e.foreignClass}_id_1'], // ${e.foreignClass} ids`
+          );
         } else {
-          lines.push(`    ${e.submodelKey}: '${e.foreignClass}_id', // one ${e.foreignClass} id`);
+          lines.push(
+            `    ${e.submodelKey}: '${e.foreignClass}_id', // one ${e.foreignClass} id`
+          );
         }
       }
       lines.push(`  },`);
@@ -15237,15 +15352,27 @@ function generateSandboxAgentDoc(manifest, meta) {
     lines.push("*No classes \u2014 no examples.*");
     lines.push("");
   }
-  lines.push("## Effects declared in this manifest (`withEffect` + live handlers)");
+  lines.push(
+    "## Effects declared in this manifest (`withEffect` + live handlers)"
+  );
   lines.push("");
-  lines.push("Each entry below matches one `withEffect` operation. For every declaration you must:");
+  lines.push(
+    "Each entry below matches one `withEffect` operation. For every declaration you must:"
+  );
   lines.push("");
-  lines.push("1. **Build** the manifest so the domain package includes the effect (`granular build`).");
-  lines.push("2. **Register** a handler whose `name` (and `className` / `static` when applicable) matches \u2014 use `granular.registerEffects('" + meta.sandboxId + "', [...])` in your host process (see `granular-effects.ts` in starter projects).");
-  lines.push("3. **Invoke** from sandbox code via `./sandbox-tools` inside `submitJob`; the handler you registered runs in your process and the result returns to the job.");
+  lines.push(
+    "1. **Build** the manifest so the domain package includes the effect (`granular build`)."
+  );
+  lines.push(
+    "2. **Register** a handler whose `name` (and `className` / `static` when applicable) matches \u2014 use `granular.registerEffects('" + meta.sandboxId + "', [...])` in your host process (see `granular-effects.ts` in starter projects)."
+  );
+  lines.push(
+    "3. **Invoke** from sandbox code via `./sandbox-tools` inside `submitJob`; the handler you registered runs in your process and the result returns to the job."
+  );
   lines.push("");
-  lines.push("**Handler shapes:** global \u2192 `(params, ctx) => \u2026`; static class effect \u2192 `(params, ctx) => \u2026`; instance effect \u2192 `(objectId, params, ctx) => \u2026` where `objectId` is the real-world id for `attachedClass`.");
+  lines.push(
+    "**Handler shapes:** global \u2192 `(params, ctx) => \u2026`; static class effect \u2192 `(params, ctx) => \u2026`; instance effect \u2192 `(objectId, params, ctx) => \u2026` where `objectId` is the real-world id for `attachedClass`."
+  );
   lines.push("");
   if (effects2.length === 0) {
     lines.push("*No `withEffect` operations in this manifest.*");
@@ -15286,7 +15413,9 @@ function generateSandboxAgentDoc(manifest, meta) {
       } else {
         lines.push("```typescript");
         lines.push(`// Instance: (objectId, params, ctx) => Promise<output>`);
-        lines.push(`handler: async (objectId, params, ctx) => { /* objectId is the ${ef.attachedClass} id */ }`);
+        lines.push(
+          `handler: async (objectId, params, ctx) => { /* objectId is the ${ef.attachedClass} id */ }`
+        );
         lines.push("```");
       }
       lines.push("");
@@ -15294,7 +15423,9 @@ function generateSandboxAgentDoc(manifest, meta) {
   }
   lines.push("## `submitJob` / sandbox code");
   lines.push("");
-  lines.push("Jobs run in the sandbox with generated classes from `./sandbox-tools`. Class names are PascalCase.");
+  lines.push(
+    "Jobs run in the sandbox with generated classes from `./sandbox-tools`. Class names are PascalCase."
+  );
   lines.push("");
   const pascalImports = classes.map((c) => toPascalCase(c.name));
   const effectNames = effects2.map((e) => e.name).filter(Boolean);
@@ -15302,7 +15433,9 @@ function generateSandboxAgentDoc(manifest, meta) {
   const firstGlobal = globalEffects[0]?.name;
   lines.push("```typescript");
   lines.push(`const job = await env.submitJob(\``);
-  const importList = [...pascalImports, ...effectNames].filter((v, i, a) => a.indexOf(v) === i);
+  const importList = [...pascalImports, ...effectNames].filter(
+    (v, i, a) => a.indexOf(v) === i
+  );
   if (importList.length > 0) {
     lines.push(`  import { ${importList.join(", ")} } from './sandbox-tools';`);
   } else {
@@ -15316,10 +15449,14 @@ function generateSandboxAgentDoc(manifest, meta) {
     const target = classWithInstanceEffect ?? classes[0];
     const C = toPascalCase(target.name);
     const c = target.name;
-    lines.push(`  const rows = await ${C}.list({ limit: 10, saveAs: '${c}_rows' });`);
+    lines.push(
+      `  const rows = await ${C}.list({ limit: 10, saveAs: '${c}_rows' });`
+    );
     lines.push(`  const row = rows[0] ?? null;`);
     lines.push("");
-    const instEffects = effects2.filter((e) => e.attachedClass === c && !e.isStatic);
+    const instEffects = effects2.filter(
+      (e) => e.attachedClass === c && !e.isStatic
+    );
     if (instEffects.length > 0) {
       const n = instEffects[0].name;
       lines.push(`  if (row) {`);
@@ -15343,28 +15480,50 @@ function generateSandboxAgentDoc(manifest, meta) {
   lines.push("");
   lines.push("## Companion scripts");
   lines.push("");
-  lines.push(`- **\`${seed}\`** \u2014 example \`recordObject\` batch for starter data.`);
-  lines.push(`- **\`${eff}\`** \u2014 long-running process that registers effect handlers for this sandbox.`);
+  lines.push(
+    `- **\`${seed}\`** \u2014 example starter-data script using \`recordObjects(...)\` with progress updates.`
+  );
+  lines.push(
+    `- **\`${eff}\`** \u2014 long-running process that registers effect handlers for this sandbox.`
+  );
   lines.push("");
   lines.push("## SDK surface (reminder)");
   lines.push("");
   lines.push("| Area | APIs |");
   lines.push("|------|------|");
-  lines.push("| Auth / session | `Granular`, `connect`, `disconnect`, `recordUser` |");
-  lines.push("| Data | `recordObject`, `recordObjects`, record import queue APIs |");
-  lines.push("| GraphQL API | `graphql` \u2014 query/mutate the underlying graph when you need it |");
-  lines.push("| Relationships (API) | `defineRelationship`, `getRelationships`, `attach`, `detach`, `listRelated` |");
-  lines.push("| Ontology | `applyManifest` (runtime), or CLI `granular build` |");
+  lines.push(
+    "| Auth / session | `Granular`, `connect`, `disconnect`, `recordUser` |"
+  );
+  lines.push(
+    "| Data | `recordObject` (one write), `recordObjects` (immediate multi-write), record import queue APIs (async bulk load) |"
+  );
+  lines.push(
+    "| GraphQL API | `graphql` \u2014 query/mutate the underlying graph when you need it |"
+  );
+  lines.push(
+    "| Relationships (API) | `defineRelationship`, `getRelationships`, `attach`, `detach`, `listRelated` |"
+  );
+  lines.push(
+    "| Ontology | `applyManifest` (runtime), or CLI `granular build` |"
+  );
   lines.push("| Jobs | `submitJob`, `answerPrompt` |");
-  lines.push("| Domain | `getDomain`, `getDomainTypes`, `getDomainDocumentation` |");
-  lines.push("| Effects | `registerEffects`, `getEffects`, `onEffectsChanged` |");
+  lines.push(
+    "| Domain | `getDomain`, `getDomainTypes`, `getDomainDocumentation` |"
+  );
+  lines.push(
+    "| Effects | `registerEffects`, `getEffects`, `onEffectsChanged` |"
+  );
   lines.push("| Ops | `checkReadiness`, `getHeap`, `rpc` |");
   lines.push("");
-  lines.push("Full list: [docs/granular-manifest.md](docs/granular-manifest.md).");
+  lines.push(
+    "Full list: [docs/granular-manifest.md](docs/granular-manifest.md)."
+  );
   lines.push("");
   lines.push("---");
   lines.push("");
-  lines.push(`*Generated at ${(/* @__PURE__ */ new Date()).toISOString()} by @granular-software/sdk*`);
+  lines.push(
+    `*Generated at ${(/* @__PURE__ */ new Date()).toISOString()} by @granular-software/sdk*`
+  );
   lines.push("");
   return lines.join("\n");
 }
@@ -15501,8 +15660,10 @@ edit granular.json -> granular build -> granular document -> run tests -> option
 # Quick reminders
 
 - Default auth story: \`granular login\`. Manual \`.env.local\` editing is fallback guidance only.
-- Read \`GRANULAR_SANDBOX.md\` before writing \`recordObject\` payloads or relationship keys.
-- Large ingests: use \`recordObjects(rows, { onChunkComplete, concurrency })\` for synchronous chunked writes with progress, or \`enqueueRecordImport\` + \`getRecordImport\` for async queue-based bulk loads.
+- Read \`GRANULAR_SANDBOX.md\` before writing \`recordObject\` or \`recordObjects\` payloads, especially relationship keys.
+- Use \`recordObject(...)\` for one object or one targeted update.
+- Use one \`recordObjects(rows, { onChunkComplete, concurrency })\` call when you need to write several records now and want chunk-level progress.
+- Use \`enqueueRecordImport(...)\` with \`getRecordImport(...)\` / \`getRecordImportSummary()\` only for large async imports where returning an \`importId\` is better than waiting for every row to finish.
 - Build failures should be mapped to the exact class, relationship, or effect declaration that caused them.
 - If the user starts from the control plane UI, converge back to the same repo state and the same CLI commands.
         `
@@ -15815,8 +15976,12 @@ function renderControlPlaneSection(controlPlaneSessionId) {
 `;
 }
 function renderOnboardingStateTemplate(options = {}) {
-  const controlPlaneSection = renderControlPlaneSection(options.controlPlaneSessionId);
-  const controlPlaneSetupSection = renderControlPlaneSetupSection(options.onboardingContext);
+  const controlPlaneSection = renderControlPlaneSection(
+    options.controlPlaneSessionId
+  );
+  const controlPlaneSetupSection = renderControlPlaneSetupSection(
+    options.onboardingContext
+  );
   return `# Granular onboarding state
 
 Use this file to track the first-run flow. After the first successful loop, switch to the short daily loop:
@@ -15902,8 +16067,12 @@ ${authHint}
 `;
 }
 function renderStartHereTemplate(options = {}) {
-  const controlPlaneSection = renderControlPlaneSection(options.controlPlaneSessionId);
-  const controlPlaneSetupSection = renderControlPlaneSetupSection(options.onboardingContext);
+  const controlPlaneSection = renderControlPlaneSection(
+    options.controlPlaneSessionId
+  );
+  const controlPlaneSetupSection = renderControlPlaneSetupSection(
+    options.onboardingContext
+  );
   return `# Granular start here
 
 This file is generated by \`granular init\`. Use it as the shared kickoff file for Codex, Cursor, Claude Code, and humans.
@@ -15976,7 +16145,10 @@ function mergeReadmeSnippet(existingContent) {
 `;
   }
   if (existingContent.includes(README_BEGIN) && existingContent.includes(README_END)) {
-    const re = new RegExp(`${escapeRegex2(README_BEGIN)}[\\s\\S]*?${escapeRegex2(README_END)}`, "m");
+    const re = new RegExp(
+      `${escapeRegex2(README_BEGIN)}[\\s\\S]*?${escapeRegex2(README_END)}`,
+      "m"
+    );
     return existingContent.replace(re, block.trim());
   }
   return `${existingContent.trimEnd()}
@@ -16009,27 +16181,52 @@ ${endMarker}`;
     return;
   }
   if (previous.includes(beginMarker) && previous.includes(endMarker)) {
-    const re = new RegExp(`${escapeRegex2(beginMarker)}[\\s\\S]*?${escapeRegex2(endMarker)}`, "m");
-    fs__namespace.writeFileSync(filePath, previous.replace(re, nextContent.trim()), "utf-8");
+    const re = new RegExp(
+      `${escapeRegex2(beginMarker)}[\\s\\S]*?${escapeRegex2(endMarker)}`,
+      "m"
+    );
+    fs__namespace.writeFileSync(
+      filePath,
+      previous.replace(re, nextContent.trim()),
+      "utf-8"
+    );
     return;
   }
-  fs__namespace.writeFileSync(filePath, `${previous.trimEnd()}
+  fs__namespace.writeFileSync(
+    filePath,
+    `${previous.trimEnd()}
 
 ${nextContent}
-`, "utf-8");
+`,
+    "utf-8"
+  );
 }
 function writeCursorHooks(projectRoot) {
   const hooksConfigPath = path3__namespace.join(projectRoot, ".cursor", "hooks.json");
-  const afterShellPath = path3__namespace.join(projectRoot, ".cursor", "hooks", "after-shell.mjs");
-  const afterFileEditPath = path3__namespace.join(projectRoot, ".cursor", "hooks", "after-file-edit.mjs");
+  const afterShellPath = path3__namespace.join(
+    projectRoot,
+    ".cursor",
+    "hooks",
+    "after-shell.mjs"
+  );
+  const afterFileEditPath = path3__namespace.join(
+    projectRoot,
+    ".cursor",
+    "hooks",
+    "after-file-edit.mjs"
+  );
   upsertFile(
     hooksConfigPath,
     JSON.stringify(
       {
         version: 1,
         hooks: {
-          afterShellExecution: [{ command: "node .cursor/hooks/after-shell.mjs" }],
-          afterFileEdit: [{ command: "node .cursor/hooks/after-file-edit.mjs" }]
+          afterShellExecution: [
+            { command: "node .cursor/hooks/after-shell.mjs" }
+          ],
+          afterFileEdit: [
+            { command: "node .cursor/hooks/after-file-edit.mjs" }
+          ]
         }
       },
       null,
@@ -16140,7 +16337,33 @@ policy:
 `;
 }
 function writeGranularAgentSkills(options) {
-  const { projectRoot, includeCursorHooks, includeCursorSubagents, controlPlaneSessionId, onboardingContext } = options;
+  const {
+    projectRoot,
+    includeCursorHooks,
+    includeCursorSubagents,
+    controlPlaneSessionId,
+    onboardingContext
+  } = options;
+  const readmePath = path3__namespace.join(projectRoot, "README.md");
+  const readmeContent = fs__namespace.existsSync(readmePath) ? fs__namespace.readFileSync(readmePath, "utf-8") : "";
+  fs__namespace.writeFileSync(readmePath, mergeReadmeSnippet(readmeContent), "utf-8");
+  maybeWriteFile(
+    path3__namespace.join(projectRoot, ONTOLOGY_BRIEF_NAME),
+    renderOntologyBriefTemplate(onboardingContext)
+  );
+  upsertFile(
+    path3__namespace.join(projectRoot, GRANULAR_START_HERE_NAME),
+    renderStartHereTemplate({ controlPlaneSessionId, onboardingContext })
+  );
+  maybeWriteFile(
+    path3__namespace.join(projectRoot, "ONBOARDING_STATE.md"),
+    renderOnboardingStateTemplate({ controlPlaneSessionId, onboardingContext })
+  );
+  maybeWriteFile(
+    path3__namespace.join(projectRoot, ".agents", "openai.yaml"),
+    renderOpenAiAgentMetadata()
+  );
+  writeClaudeIndex(projectRoot);
   for (const definition of GRANULAR_SKILLS) {
     upsertFile(
       path3__namespace.join(projectRoot, ".agents", "skills", definition.name, "SKILL.md"),
@@ -16164,25 +16387,14 @@ function writeGranularAgentSkills(options) {
   if (includeCursorHooks) {
     writeCursorHooks(projectRoot);
   }
-  maybeWriteFile(path3__namespace.join(projectRoot, ONTOLOGY_BRIEF_NAME), renderOntologyBriefTemplate(onboardingContext));
-  upsertFile(
-    path3__namespace.join(projectRoot, GRANULAR_START_HERE_NAME),
-    renderStartHereTemplate({ controlPlaneSessionId, onboardingContext })
-  );
-  maybeWriteFile(
-    path3__namespace.join(projectRoot, "ONBOARDING_STATE.md"),
-    renderOnboardingStateTemplate({ controlPlaneSessionId, onboardingContext })
-  );
-  maybeWriteFile(path3__namespace.join(projectRoot, ".agents", "openai.yaml"), renderOpenAiAgentMetadata());
-  writeClaudeIndex(projectRoot);
-  const readmePath = path3__namespace.join(projectRoot, "README.md");
-  const readmeContent = fs__namespace.existsSync(readmePath) ? fs__namespace.readFileSync(readmePath, "utf-8") : "";
-  fs__namespace.writeFileSync(readmePath, mergeReadmeSnippet(readmeContent), "utf-8");
 }
 
 // src/cli/commands/init.ts
 function prompt(question, defaultValue) {
-  const rl = readline__namespace.createInterface({ input: process.stdin, output: process.stdout });
+  const rl = readline__namespace.createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
   const suffix = defaultValue ? ` ${brand.muted(`(${defaultValue})`)}` : "";
   return new Promise((resolve2) => {
     rl.question(`  ${question}${suffix}: `, (answer) => {
@@ -16195,7 +16407,10 @@ function waitForEnter(message) {
   if (!process.stdin.isTTY || !process.stdout.isTTY) {
     return Promise.resolve();
   }
-  const rl = readline__namespace.createInterface({ input: process.stdin, output: process.stdout });
+  const rl = readline__namespace.createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
   return new Promise((resolve2) => {
     rl.question(`  ${message}`, () => {
       rl.close();
@@ -16223,12 +16438,16 @@ async function selectStarterTemplate(requestedTemplate) {
     return DEFAULT_STARTER_TEMPLATE_ID;
   }
   const templates = listStarterTemplates();
-  const defaultIndex = templates.findIndex((template) => template.id === DEFAULT_STARTER_TEMPLATE_ID);
+  const defaultIndex = templates.findIndex(
+    (template) => template.id === DEFAULT_STARTER_TEMPLATE_ID
+  );
   step("Choose a starter ontology template");
   for (const [index, template] of templates.entries()) {
     const isDefault = template.id === DEFAULT_STARTER_TEMPLATE_ID;
     const defaultLabel = isDefault ? ` ${brand.muted("(default)")}` : "";
-    console.log(`  ${index + 1}. ${brand.bold(template.label)}${defaultLabel}`);
+    console.log(
+      `  ${index + 1}. ${brand.bold(template.label)}${defaultLabel}`
+    );
     dim(`     ${template.id} \u2014 ${template.summary}`);
   }
   console.log();
@@ -16241,7 +16460,9 @@ async function selectStarterTemplate(requestedTemplate) {
   if (isStarterTemplateId(normalizedChoice)) {
     return normalizedChoice;
   }
-  warn(`Unknown template "${rawChoice}". Falling back to ${DEFAULT_STARTER_TEMPLATE_ID}.`);
+  warn(
+    `Unknown template "${rawChoice}". Falling back to ${DEFAULT_STARTER_TEMPLATE_ID}.`
+  );
   return DEFAULT_STARTER_TEMPLATE_ID;
 }
 async function initCommand(projectName, options) {
@@ -16263,7 +16484,9 @@ async function initCommand(projectName, options) {
     info("No API key found. Starting browser login...");
     await waitForEnter("Press Enter to open the login page in your browser...");
     console.log();
-    const waiting = spinner("Opening browser and waiting for authentication...");
+    const waiting = spinner(
+      "Opening browser and waiting for authentication..."
+    );
     try {
       apiKey = await loginWithBrowser({
         authBaseUrl: loadAuthUrl(),
@@ -16310,7 +16533,9 @@ async function initCommand(projectName, options) {
   try {
     sandbox = await api.findOrCreateSandbox(name);
     if (sandbox.name === name) {
-      creating.succeed(`  Sandbox ready: ${brand.secondary(sandbox.sandboxId)}`);
+      creating.succeed(
+        `  Sandbox ready: ${brand.secondary(sandbox.sandboxId)}`
+      );
     }
   } catch (err) {
     creating.fail(`  Failed to create sandbox: ${err.message}`);
@@ -16318,7 +16543,9 @@ async function initCommand(projectName, options) {
   }
   const project = createDefaultManifest(name, templateId);
   writeManifestFile(project);
-  success(`Created ${brand.bold("granular.json")} with the ${template.label} starter ontology`);
+  success(
+    `Created ${brand.bold("granular.json")} with the ${template.label} starter ontology`
+  );
   writeRcFile({
     sandboxId: sandbox.sandboxId,
     sandboxName: sandbox.name,
@@ -16354,6 +16581,37 @@ async function initCommand(projectName, options) {
     writeAgentsMdFile(getProjectRoot());
     success(`Updated ${brand.bold("AGENTS.md")}`);
   }
+  const effectsPath = path3__namespace.join(getProjectRoot(), EFFECTS_SCRIPT_NAME);
+  const seedPath = path3__namespace.join(getProjectRoot(), SEED_SCRIPT_NAME);
+  const integrationTestPath = path3__namespace.join(
+    getProjectRoot(),
+    INTEGRATION_TEST_NAME
+  );
+  fs__namespace.writeFileSync(
+    effectsPath,
+    generateEffectsScript(sandbox.sandboxId, apiUrl, templateId),
+    "utf-8"
+  );
+  success(
+    `Created ${brand.bold(EFFECTS_SCRIPT_NAME)} (external effect host)`
+  );
+  fs__namespace.writeFileSync(
+    seedPath,
+    generateSeedScript(sandbox.sandboxId, apiUrl, templateId),
+    "utf-8"
+  );
+  success(
+    `Created ${brand.bold(SEED_SCRIPT_NAME)} (sample record seeding script)`
+  );
+  fs__namespace.mkdirSync(path3__namespace.dirname(integrationTestPath), { recursive: true });
+  fs__namespace.writeFileSync(
+    integrationTestPath,
+    generateIntegrationTest(sandbox.sandboxId, apiUrl, templateId),
+    "utf-8"
+  );
+  success(
+    `Created ${brand.bold(INTEGRATION_TEST_NAME)} (real integration smoke test)`
+  );
   writeGranularAgentSkills({
     projectRoot: getProjectRoot(),
     includeCursorHooks: options?.cursorHooks,
@@ -16368,7 +16626,9 @@ async function initCommand(projectName, options) {
       rolesSummary: options?.rolesSummary
     }
   });
-  success("Generated Granular agent skills for Codex, Cursor, and Claude Code");
+  success(
+    "Generated Granular agent skills for Codex, Cursor, and Claude Code"
+  );
   success(
     `Created ${brand.bold(ONTOLOGY_BRIEF_NAME)}, ${brand.bold(GRANULAR_START_HERE_NAME)}, and ${brand.bold("ONBOARDING_STATE.md")}; updated ${brand.bold("README.md")}`
   );
@@ -16388,41 +16648,24 @@ async function initCommand(projectName, options) {
       );
       lastManifestId = manifest.manifestId;
       building.text = "  Triggering build...";
-      const build = await api.triggerBuild(sandbox.sandboxId, manifest.manifestId);
+      const build = await api.triggerBuild(
+        sandbox.sandboxId,
+        manifest.manifestId
+      );
       building.text = "  Building...";
       const completed = await api.waitForBuild(build.buildId, (status) => {
         building.text = `  Building... ${brand.muted(status)}`;
       });
       lastBuildId = completed.buildId;
       initialBuildSucceeded = true;
-      building.succeed(`  Build completed: ${brand.secondary(completed.buildId)}`);
+      building.succeed(
+        `  Build completed: ${brand.secondary(completed.buildId)}`
+      );
     } catch (err) {
       building.fail(`  Build failed: ${err.message}`);
       dim("You can retry with `granular build`");
     }
   }
-  const effectsPath = path3__namespace.join(getProjectRoot(), EFFECTS_SCRIPT_NAME);
-  const seedPath = path3__namespace.join(getProjectRoot(), SEED_SCRIPT_NAME);
-  const integrationTestPath = path3__namespace.join(getProjectRoot(), INTEGRATION_TEST_NAME);
-  fs__namespace.writeFileSync(
-    effectsPath,
-    generateEffectsScript(sandbox.sandboxId, apiUrl, templateId),
-    "utf-8"
-  );
-  success(`Created ${brand.bold(EFFECTS_SCRIPT_NAME)} (external effect host)`);
-  fs__namespace.writeFileSync(
-    seedPath,
-    generateSeedScript(sandbox.sandboxId, apiUrl, templateId),
-    "utf-8"
-  );
-  success(`Created ${brand.bold(SEED_SCRIPT_NAME)} (sample record seeding script)`);
-  fs__namespace.mkdirSync(path3__namespace.dirname(integrationTestPath), { recursive: true });
-  fs__namespace.writeFileSync(
-    integrationTestPath,
-    generateIntegrationTest(sandbox.sandboxId, apiUrl, templateId),
-    "utf-8"
-  );
-  success(`Created ${brand.bold(INTEGRATION_TEST_NAME)} (real integration smoke test)`);
   writeSandboxAgentDocFile(getProjectRoot(), project.manifest, {
     sandboxId: sandbox.sandboxId,
     apiUrl,
@@ -16430,18 +16673,20 @@ async function initCommand(projectName, options) {
     buildId: lastBuildId,
     buildPending: !initialBuildSucceeded
   });
-  success(`Wrote ${brand.bold("GRANULAR_SANDBOX.md")} (agent reference for this sandbox)`);
+  success(
+    `Wrote ${brand.bold("GRANULAR_SANDBOX.md")} (agent reference for this sandbox)`
+  );
   console.log();
   divider();
   console.log();
   success(`Project ${brand.bold(name)} initialized!`);
   console.log();
   const kv = {
-    "Ontology": sandbox.sandboxId,
-    "Template": template.label,
-    "Manifest": "granular.json",
-    "Config": ".granularrc",
-    "Auth": "granular login / .env.local",
+    Ontology: sandbox.sandboxId,
+    Template: template.label,
+    Manifest: "granular.json",
+    Config: ".granularrc",
+    Auth: "granular login / .env.local",
     "Start here": GRANULAR_START_HERE_NAME,
     "Ontology brief": ONTOLOGY_BRIEF_NAME,
     "Seed script": SEED_SCRIPT_NAME,
@@ -16477,25 +16722,65 @@ async function initCommand(projectName, options) {
   }
   keyValue(kv);
   const nextSteps2 = options?.skipBuild ? [
-    { command: "granular login", description: "Ensure local auth is ready before building or testing" },
-    { command: `open ${GRANULAR_START_HERE_NAME}`, description: "Read the happy path and file map shared by humans and agents" },
-    { command: `open ${ONTOLOGY_BRIEF_NAME}`, description: "Fill the product brief before editing granular.json" },
-    { command: "granular build", description: "Build the starter ontology before you seed or simulate" },
-    { command: `node --test ${INTEGRATION_TEST_NAME}`, description: "Run the generated real Granular smoke test against your dev ontology" },
-    { command: "granular simulate", description: "Open the simulator for this sandbox" }
+    {
+      command: "granular login",
+      description: "Ensure local auth is ready before building or testing"
+    },
+    {
+      command: `open ${GRANULAR_START_HERE_NAME}`,
+      description: "Read the happy path and file map shared by humans and agents"
+    },
+    {
+      command: `open ${ONTOLOGY_BRIEF_NAME}`,
+      description: "Fill the product brief before editing granular.json"
+    },
+    {
+      command: "granular build",
+      description: "Build the starter ontology before you seed or simulate"
+    },
+    {
+      command: `node --test ${INTEGRATION_TEST_NAME}`,
+      description: "Run the generated real Granular smoke test against your dev ontology"
+    },
+    {
+      command: "granular simulate",
+      description: "Open the simulator for this sandbox"
+    }
   ] : [
-    { command: `open ${GRANULAR_START_HERE_NAME}`, description: "Read the happy path and file map shared by humans and agents" },
-    { command: `open ${ONTOLOGY_BRIEF_NAME}`, description: "Fill the brief, then use it to guide your first manifest edits" },
-    { command: "granular build", description: "Compile the ontology after updating granular.json" },
-    { command: "granular document", description: "Refresh GRANULAR_SANDBOX.md so agents and tests use exact keys" },
-    { command: `node --test ${INTEGRATION_TEST_NAME}`, description: "Run the generated real Granular smoke test against your dev ontology" },
-    { command: "granular simulate", description: "Open the simulator for this sandbox" }
+    {
+      command: `open ${GRANULAR_START_HERE_NAME}`,
+      description: "Read the happy path and file map shared by humans and agents"
+    },
+    {
+      command: `open ${ONTOLOGY_BRIEF_NAME}`,
+      description: "Fill the brief, then use it to guide your first manifest edits"
+    },
+    {
+      command: "granular build",
+      description: "Compile the ontology after updating granular.json"
+    },
+    {
+      command: "granular document",
+      description: "Refresh GRANULAR_SANDBOX.md so agents and tests use exact keys"
+    },
+    {
+      command: `node --test ${INTEGRATION_TEST_NAME}`,
+      description: "Run the generated real Granular smoke test against your dev ontology"
+    },
+    {
+      command: "granular simulate",
+      description: "Open the simulator for this sandbox"
+    }
   ];
   nextSteps(nextSteps2);
   console.log();
   dim("Mental model:");
-  dim("  Query and navigate data through the ontology. Use effects only for actions that leave the sandbox.");
-  dim("  The seed script shows how records enter the graph. The effects script shows how external systems plug in.");
+  dim(
+    "  Query and navigate data through the ontology. Use effects only for actions that leave the sandbox."
+  );
+  dim(
+    "  The seed script shows synchronous batch recording with progress. The effects script shows how external systems plug in."
+  );
   console.log();
 }
 var DEFAULT_LOCAL_API_KEY2 = "gn_sk_tenant_default_principal_local_e2e_00000000";
@@ -18015,7 +18300,9 @@ var Session = class {
       }
     }
     if (!revision) {
-      throw new Error("No domain revision available. Register live effects or ensure the build schema is activated.");
+      throw new Error(
+        "No domain revision available. Register live effects or ensure the build schema is activated."
+      );
     }
     const result = await this.client.call("job.submit", {
       domainRevision: revision,
@@ -18051,7 +18338,11 @@ var Session = class {
     const prompt3 = this.promptCache.get(promptId);
     const resolvedAnswer = resolvePromptAnswer(prompt3, answer);
     this.promptCache.delete(promptId);
-    await this.client.call("prompt.answer", { promptId, answer: resolvedAnswer, value: resolvedAnswer });
+    await this.client.call("prompt.answer", {
+      promptId,
+      answer: resolvedAnswer,
+      value: resolvedAnswer
+    });
   }
   /**
    * Get the current list of available effects.
@@ -18083,7 +18374,8 @@ var Session = class {
       for (const tool of cat.tools) {
         if (!tool?.name) continue;
         const existing = toolMap.get(tool.name);
-        if (existing?.publishedAt && cat.publishedAt && existing.publishedAt > cat.publishedAt) continue;
+        if (existing?.publishedAt && cat.publishedAt && existing.publishedAt > cat.publishedAt)
+          continue;
         const isLocal = clientId === this.clientId;
         const ready = isLocal ? this.effects.has(tool.name) || this.toolHandlers.has(tool.name) || this.instanceTools.has(tool.name) : true;
         toolMap.set(tool.name, {
@@ -18121,7 +18413,10 @@ var Session = class {
     return () => {
       const listeners = this.eventListeners.get("effects:changed");
       if (listeners) {
-        this.eventListeners.set("effects:changed", listeners.filter((h) => h !== handler));
+        this.eventListeners.set(
+          "effects:changed",
+          listeners.filter((h) => h !== handler)
+        );
       }
     };
   }
@@ -18137,7 +18432,10 @@ var Session = class {
     return () => {
       const listeners = this.eventListeners.get("tools:changed");
       if (listeners) {
-        this.eventListeners.set("tools:changed", listeners.filter((h) => h !== handler));
+        this.eventListeners.set(
+          "tools:changed",
+          listeners.filter((h) => h !== handler)
+        );
       }
     };
   }
@@ -18145,11 +18443,16 @@ var Session = class {
    * Get the current domain state and available tools
    */
   async getDomain() {
-    const summary = await this.client.call("domain.getSummary", {});
+    const summary = await this.client.call(
+      "domain.getSummary",
+      {}
+    );
     if (summary.activeDomainRevision) {
       this.currentDomainRevision = summary.activeDomainRevision;
     } else {
-      this.currentDomainRevision = this.extractDomainRevisionFromDoc(this.client.doc);
+      this.currentDomainRevision = this.extractDomainRevisionFromDoc(
+        this.client.doc
+      );
     }
     return summary;
   }
@@ -18324,20 +18627,31 @@ import { ${allImports} } from "./sandbox-tools";
   off(event, handler) {
     const handlers = this.eventListeners.get(event);
     if (handlers) {
-      this.eventListeners.set(event, handlers.filter((h) => h !== handler));
+      this.eventListeners.set(
+        event,
+        handlers.filter((h) => h !== handler)
+      );
     }
   }
   // --- Internal ---
   setupToolInvokeHandler() {
     this.client.registerRpcHandler("tool.invoke", async (params) => {
       const { callId, toolName, input } = params;
-      this.emit("effect:invoke", { callId, effectKey: toolName, toolName, input });
+      this.emit("effect:invoke", {
+        callId,
+        effectKey: toolName,
+        toolName,
+        input
+      });
       this.emit("tool:invoke", { callId, toolName, input });
       const handler = this.toolHandlers.get(toolName);
       if (!handler) {
         await this.client.call("tool.result", {
           callId,
-          error: { code: "TOOL_NOT_FOUND", message: `Tool handler not found: ${toolName}` }
+          error: {
+            code: "TOOL_NOT_FOUND",
+            message: `Tool handler not found: ${toolName}`
+          }
         });
         return;
       }
@@ -18346,7 +18660,11 @@ import { ${allImports} } from "./sandbox-tools";
         const invocationContext = this.buildLegacyEffectContext();
         if (this.instanceTools.has(toolName) && input && typeof input === "object" && "_objectId" in input) {
           const { _objectId, ...restParams } = input;
-          result = await handler(_objectId, restParams, invocationContext);
+          result = await handler(
+            _objectId,
+            restParams,
+            invocationContext
+          );
         } else {
           result = await handler(input, invocationContext);
         }
@@ -18358,7 +18676,11 @@ import { ${allImports} } from "./sandbox-tools";
         });
       } catch (error2) {
         const errorMessage = error2 instanceof Error ? error2.message : String(error2);
-        this.emit("effect:result", { callId, effectKey: toolName, error: errorMessage });
+        this.emit("effect:result", {
+          callId,
+          effectKey: toolName,
+          error: errorMessage
+        });
         this.emit("tool:result", { callId, error: errorMessage });
         await this.client.call("tool.result", {
           callId,
@@ -18368,7 +18690,10 @@ import { ${allImports} } from "./sandbox-tools";
     });
   }
   setupEventHandlers() {
-    this.client.on("open", (payload) => this.emit("open", payload || {}));
+    this.client.on(
+      "open",
+      (payload) => this.emit("open", payload || {})
+    );
     this.client.on("sync", (doc) => {
       this.currentDomainRevision = this.extractDomainRevisionFromDoc(doc);
       this.emit("sync", doc);
@@ -18382,8 +18707,14 @@ import { ${allImports} } from "./sandbox-tools";
     };
     this.client.on("prompt", emitPrompt);
     this.client.on("prompt.request", emitPrompt);
-    this.client.on("disconnect", (payload) => this.emit("disconnect", payload || {}));
-    this.client.on("reconnect_error", (payload) => this.emit("reconnect_error", payload || {}));
+    this.client.on(
+      "disconnect",
+      (payload) => this.emit("disconnect", payload || {})
+    );
+    this.client.on(
+      "reconnect_error",
+      (payload) => this.emit("reconnect_error", payload || {})
+    );
     this.client.on("job.status", (data) => {
       this.emit("job:status", data);
     });
@@ -18499,7 +18830,10 @@ function sanitizeFeedbackValue(value, depth = 0, seen = /* @__PURE__ */ new Weak
       return "[Circular]";
     }
     seen.add(value);
-    const entries = Object.entries(value).slice(0, MAX_FEEDBACK_OBJECT_KEYS);
+    const entries = Object.entries(value).slice(
+      0,
+      MAX_FEEDBACK_OBJECT_KEYS
+    );
     const sanitized = {};
     for (const [key, entryValue] of entries) {
       sanitized[key] = sanitizeFeedbackValue(entryValue, depth + 1, seen);
@@ -18550,12 +18884,18 @@ var JobImplementation = class {
       if (progressData.execId === id || progressData.jobId === id) {
         if (progressData.stdout) {
           this.markStarted();
-          this.metadata.stdout = [...this.metadata.stdout, truncateFeedbackString(progressData.stdout)].slice(-100);
+          this.metadata.stdout = [
+            ...this.metadata.stdout,
+            truncateFeedbackString(progressData.stdout)
+          ].slice(-100);
           this.emit("stdout", progressData.stdout);
         }
         if (progressData.stderr) {
           this.markStarted();
-          this.metadata.stderr = [...this.metadata.stderr, truncateFeedbackString(progressData.stderr)].slice(-100);
+          this.metadata.stderr = [
+            ...this.metadata.stderr,
+            truncateFeedbackString(progressData.stderr)
+          ].slice(-100);
           this.emit("stderr", progressData.stderr);
         }
       }
@@ -18577,12 +18917,18 @@ var JobImplementation = class {
     });
     this.client.on(`job.${id}.stdout`, (line) => {
       this.markStarted();
-      this.metadata.stdout = [...this.metadata.stdout, truncateFeedbackString(String(line))].slice(-100);
+      this.metadata.stdout = [
+        ...this.metadata.stdout,
+        truncateFeedbackString(String(line))
+      ].slice(-100);
       this.emit("stdout", line);
     });
     this.client.on(`job.${id}.stderr`, (line) => {
       this.markStarted();
-      this.metadata.stderr = [...this.metadata.stderr, truncateFeedbackString(String(line))].slice(-100);
+      this.metadata.stderr = [
+        ...this.metadata.stderr,
+        truncateFeedbackString(String(line))
+      ].slice(-100);
       this.emit("stderr", line);
     });
     this.client.on(`job.${id}.result`, (result) => {
@@ -18614,7 +18960,11 @@ var JobImplementation = class {
     this.client.on("job.failed", (data) => {
       const jobData = data;
       if (jobData.jobId === id) {
-        this.finalize("failed", void 0, jobData.error || new Error("Job failed"));
+        this.finalize(
+          "failed",
+          void 0,
+          jobData.error || new Error("Job failed")
+        );
         this.emit("status", this.status);
       }
     });
@@ -18627,7 +18977,12 @@ var JobImplementation = class {
           input: sanitizeFeedbackValue(d.input),
           startedAt: d.timestamp || Date.now()
         });
-        this.emit("toolCallStart", { callId: d.callId, toolName: d.toolName, input: d.input, timestamp: d.timestamp });
+        this.emit("toolCallStart", {
+          callId: d.callId,
+          toolName: d.toolName,
+          input: d.input,
+          timestamp: d.timestamp
+        });
       }
     });
     this.client.on("tool.call.end", (data) => {
@@ -18642,7 +18997,25 @@ var JobImplementation = class {
           completedAt,
           durationMs: typeof d.durationMs === "number" ? d.durationMs : void 0
         });
-        this.emit("toolCallEnd", { callId: d.callId, toolName: d.toolName, result: d.result, error: d.error, durationMs: d.durationMs, timestamp: d.timestamp });
+        this.emit("toolCallEnd", {
+          callId: d.callId,
+          toolName: d.toolName,
+          result: d.result,
+          error: d.error,
+          durationMs: d.durationMs,
+          timestamp: d.timestamp
+        });
+      }
+    });
+    this.client.on("job.agent_message", (data) => {
+      const d = data;
+      if (d.jobId === id) {
+        this.emit("agentMessage", {
+          messageId: d.messageId,
+          reply: typeof d.reply === "string" ? d.reply : "",
+          show: d.show,
+          timestamp: d.timestamp || Date.now()
+        });
       }
     });
   }
@@ -18712,7 +19085,9 @@ var JobImplementation = class {
   }
   upsertToolCall(next) {
     const callId = next.callId || `tool-call-${Date.now()}`;
-    const existingIndex = this.metadata.toolCalls.findIndex((entry) => entry.callId === callId);
+    const existingIndex = this.metadata.toolCalls.findIndex(
+      (entry) => entry.callId === callId
+    );
     const existing = existingIndex >= 0 ? this.metadata.toolCalls[existingIndex] : void 0;
     const merged = {
       ...existing,