@granular-software/sdk 0.4.9 → 0.4.11

package/dist/cli/index.js

@@ -5388,6 +5388,7 @@ var import_dotenv = __toESM(require_main());
 // src/endpoints.ts
 var LOCAL_API_URL = "ws://localhost:8787/granular";
 var PRODUCTION_API_URL = "wss://cf-api-gateway.arthur6084.workers.dev/granular";
+var DEFAULT_LOCAL_API_KEY = "gn_sk_tenant_default_principal_local_e2e_00000000";
 var LOCAL_AUTH_URL = "http://localhost:3000";
 var PRODUCTION_AUTH_URL = "https://app.granular.software";
 function readEnv(name) {
@@ -5407,6 +5408,21 @@ function isTruthy(value) {
   const normalized = value.trim().toLowerCase();
   return normalized === "1" || normalized === "true" || normalized === "yes" || normalized === "on";
 }
+function isLocalApiUrl(url) {
+  try {
+    const parsed = new URL(url);
+    return parsed.hostname === "localhost" || parsed.hostname === "127.0.0.1";
+  } catch {
+    return false;
+  }
+}
+function resolveAuthTokenForApiUrl(authToken, apiUrl) {
+  if (!authToken.startsWith("sk_") || !isLocalApiUrl(apiUrl) || isTruthy(readEnv("GRANULAR_DISABLE_LOCAL_API_KEY_FALLBACK"))) {
+    return authToken;
+  }
+  const override = readEnv("GRANULAR_LOCAL_API_KEY")?.trim();
+  return override || DEFAULT_LOCAL_API_KEY;
+}
 function resolveEndpointMode(explicitMode) {
   const explicit = normalizeMode(explicitMode);
   if (explicit === "local" || explicit === "production") {
@@ -6762,7 +6778,7 @@ var ApiClient = class {
   apiKey;
   baseUrl;
   constructor(apiKey, apiUrl) {
-    this.apiKey = apiKey;
+    this.apiKey = resolveAuthTokenForApiUrl(apiKey, apiUrl);
     this.baseUrl = apiUrl.replace("wss://", "https://").replace("ws://", "http://").replace(/\/ws$/, "");
   }
   async request(path4, options = {}) {
@@ -8660,6 +8676,816 @@ function buildStatus(status) {
   }
 }
 
+// src/cli/agent-docs/parse-manifest.ts
+function cardinalityLabel(rel) {
+  const a = rel.leftIsMany ? rel.rightIsMany ? "Many-to-Many" : "One-to-Many" : rel.rightIsMany ? "Many-to-One" : "One-to-One";
+  return a;
+}
+function parseManifestContent(manifest) {
+  const classes = [];
+  const relationships = [];
+  const effects = [];
+  for (const vol of manifest.volumes ?? []) {
+    for (const op of vol.operations ?? []) {
+      if (op.create && op.extends === "@std/class") {
+        classes.push({
+          name: op.create,
+          fields: op.has || {},
+          description: op.description
+        });
+      }
+      if (op.defineRelationship) {
+        const rel = op.defineRelationship;
+        relationships.push({
+          left: rel.left,
+          right: rel.right,
+          leftSubmodel: rel.leftSubmodel,
+          rightSubmodel: rel.rightSubmodel,
+          leftIsMany: rel.leftIsMany,
+          rightIsMany: rel.rightIsMany,
+          cardinalityLabel: cardinalityLabel(rel)
+        });
+      }
+      if (op.withEffect) {
+        const w = op.withEffect;
+        effects.push({
+          name: w.name,
+          description: w.description,
+          attachedClass: w.attachedClass,
+          isStatic: w.isStatic,
+          inputSchema: w.inputSchema,
+          outputSchema: w.outputSchema
+        });
+      }
+    }
+  }
+  return { classes, relationships, effects };
+}
+function relationshipEdgesForClass(className, rels) {
+  const edges = [];
+  for (const r of rels) {
+    if (r.left === className) {
+      edges.push({
+        submodelKey: r.leftSubmodel,
+        foreignClass: r.right,
+        isMany: r.leftIsMany
+      });
+    }
+    if (r.right === className) {
+      edges.push({
+        submodelKey: r.rightSubmodel,
+        foreignClass: r.left,
+        isMany: r.rightIsMany
+      });
+    }
+  }
+  return edges;
+}
+function toPascalCase(name) {
+  return name.charAt(0).toUpperCase() + name.slice(1);
+}
+
+// src/cli/agent-docs/concept-blocks.ts
+function manifestGuideGranularProductSection() {
+  return `## What is Granular?
+
+**Granular** is a **hosted service** plus **\`@granular-software/sdk\`**. Together they let you:
+
+1. **Declare** a **domain** (classes, relationships between entities, and **effects** \u2014 named actions that run in **your** backend).
+2. **Build** that declaration from \`granular.json\` so the service compiles types and tooling for a **sandbox** (a workspace identified by \`sbx_\u2026\`).
+3. **Store** **records** (instances of your classes) and **run jobs** (code executed in Granular\u2019s **sandbox runtime**) that call generated helpers and effects.
+
+**Split of responsibility:** Data and domain rules live in Granular; **secrets, payment providers, email, and arbitrary HTTP** stay in **your** server via **effect handlers** you register with \`registerEffects\`.
+
+---
+
+## Which document to use
+
+| Need | Open |
+|------|------|
+| **Understand Granular** (product, glossary, how to edit \`granular.json\`, validate with **build**, SDK + CLI reference) | **This file** \u2014 [docs/granular-manifest.md](granular-manifest.md) |
+| **This repository\u2019s ontology only** (exact class names, relationship keys, effect schemas, snippets for **this** \`sbx_\u2026\`) | [GRANULAR_SANDBOX.md](../GRANULAR_SANDBOX.md) |
+
+Edit the domain in **git** (\`granular.json\`); the **sandbox** on the service holds the **built** domain and **data**.`;
+}
+function manifestGuideMainConceptsSection() {
+  return `## Main concepts
+
+The rest of this guide assumes these terms.
+
+| Term | What it means |
+|------|----------------|
+| **Sandbox** | A **workspace** on Granular (\`sbx_\u2026\`). It stores the **compiled domain** and **your records** for one project/environment. Not a browser sandbox \u2014 think \u201Ctenant + schema + data\u201D for this app. |
+| **Domain** | The **ontology**: **classes**, **relationships**, and **effects**. Declared in \`granular.json\`, installed on the sandbox by **build**. Same idea as *schema* / *model*. |
+| **Manifest** | \`granular.json\` (definition under \`manifest\`). **Source** in the repo until you **build**. |
+| **Build** | \`granular build\` \u2014 uploads and compiles the manifest. Primary **validation**; fixes errors before relying on types. |
+| **Environment** | Return value of \`granular.connect({ sandbox, \u2026 })\`. Your **server-side** handle for \`recordObject\`, \`submitJob\`, \`graphql\`, etc., bound to one sandbox. |
+| **Session** | SDK base type; \`Environment\` **extends** \`Session\`. Job/prompt APIs live on \`Session\`; you still use the **\`Environment\`** instance from \`connect()\` in normal apps. |
+| **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\`. |
+| **Relationship** | Declared link between two classes; defines **property names** and cardinality. Keys appear in \`recordObject({ relationships })\`. |
+
+### Data vs actions (short)
+
+- **In-graph:** classes, fields, instances, relationships \u2014 manipulated with \`recordObject\` and job APIs on generated classes.
+- **Outside declared data:** **effects** \u2014 declared in the manifest, implemented on your server, called from jobs like functions.
+
+There is no separate \`granular validate\`: **\`granular build\`** (and its errors) is how you catch manifest mistakes.`;
+}
+function manifestGuideEndToEndSection() {
+  return `## From manifest to running app
+
+| Step | Action | Outcome |
+|------|--------|---------|
+| 1 | Edit \`granular.json\` (\`manifest\` \u2192 \`volumes\` \u2192 \`operations\`) | Domain **source** in the repo |
+| 2 | \`granular build\` | Manifest **uploaded**; domain **compiled** for the configured sandbox; 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({ sandbox, userId, permissions })\` | **\`Environment\`** for that sandbox |
+| 5 | \`recordObject\` / \`recordObjects\` | **Records** stored with correct fields and relationship keys |
+| 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.`;
+}
+function sandboxDocMainConceptsSection() {
+  return `## Main concepts (recap)
+
+| Term | One line |
+|------|----------|
+| **Sandbox** | Workspace \`sbx_\u2026\` \u2014 **domain** + **data** for this project. |
+| **Domain / ontology** | Classes + relationships + effects \u2014 **built** from \`granular.json\`. |
+| **Manifest** | \`granular.json\` \u2014 **source**; edit here, then \`granular build\`. |
+| **Environment** | \`connect()\` result \u2014 **record**, **submitJob**, **graphql** for this sandbox. |
+| **Session** | Base type; \`Environment\` extends it (job APIs). |
+| **Job** | \`submitJob\` code using \`./sandbox-tools\`. |
+| **Effect** | Declared in manifest; **handler** in your process. |
+
+**Full product + manifest how-to:** [docs/granular-manifest.md](docs/granular-manifest.md).`;
+}
+function sandboxDocScopeSection(projectName) {
+  return `## How this doc fits with the manifest guide
+
+| Document | Role |
+|----------|------|
+| [docs/granular-manifest.md](docs/granular-manifest.md) | **Product + how-to:** glossary, \`granular.json\` shape, \`create\` / \`defineRelationship\` / \`withEffect\`, \`granular build\`, SDK + CLI. Use it to **define an accurate manifest** and understand **environment** vs **sandbox**. |
+| **This file** (\`GRANULAR_SANDBOX.md\`, project **${projectName}**) | **This sandbox only:** ids, **exact** names and keys, effect JSON schemas, copy-paste snippets \u2014 so you can **build** and **call** the API without guessing strings. |
+
+If **syntax** or **Granular behavior** is unclear, use the manifest guide; use **this** file for **ontology facts** for **${projectName}**.`;
+}
+
+// src/cli/agent-docs/manifest-guide.ts
+function generateManifestAgentGuide(options) {
+  const { projectName } = options;
+  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).
+
+**Precedence:** User instructions in chat override this file. When in doubt, read \`granular.json\` and [AGENTS.md](../AGENTS.md).
+
+---
+
+${manifestGuideGranularProductSection()}
+
+---
+
+${manifestGuideMainConceptsSection()}
+
+---
+
+${manifestGuideEndToEndSection()}
+
+---
+
+## \`granular.json\` file shape (read this first)
+
+The CLI stores the manifest inside a wrapper object. The file must look like:
+
+\`\`\`json
+{
+  "manifest": {
+    "schemaVersion": 2,
+    "name": "${projectName}",
+    "description": "\u2026",
+    "volumes": [ \u2026 ]
+  }
+}
+\`\`\`
+
+- **Do not** put \`schemaVersion\` / \`volumes\` at the top level without the \`manifest\` key \u2014 that is invalid for this CLI.
+- All schema work happens under \`manifest\`.
+
+Project display name in this file: **${projectName}**.
+
+---
+
+## Manifest structure (\`schemaVersion: 2\`)
+
+\`\`\`json
+{
+  "schemaVersion": 2,
+  "name": "my-app",
+  "description": "optional string",
+  "volumes": [
+    {
+      "name": "schema",
+      "scope": "sandbox",
+      "imports": [
+        { "alias": "@std", "name": "standard_modules", "label": "prod" }
+      ],
+      "operations": [ ]
+    }
+  ]
+}
+\`\`\`
+
+| Field | Meaning |
+|-------|---------|
+| \`volumes\` | Logical groups of operations. Starters use one volume named \`schema\`. |
+| \`scope\` | \`sandbox\` (typical), \`build\`, or \`user\` \u2014 where the volume applies. |
+| \`imports\` | Brings in \`standard_modules\` under alias \`@std\` so you can \`"extends": "@std/class"\`. |
+| \`imports[].label\` | Version label (e.g. \`prod\`) for the module. |
+| \`operations\` | Ordered list of **operations** (see below). |
+
+---
+
+## Operations: create a class (fields)
+
+Domain classes **must** extend the standard class prototype:
+
+\`\`\`json
+{
+  "create": "invoice",
+  "extends": "@std/class",
+  "has": {
+    "amount_cents": { "type": "number", "description": "Amount in minor units" },
+    "status": { "type": "string", "description": "Workflow status" }
+  }
+}
+\`\`\`
+
+### Field entries (\`has\`): precise rules
+
+Each key under \`has\` is a **field name** on the class. Each value is a **field spec**. Getting this wrong breaks types and generated tooling.
+
+| Property | Required? | Purpose |
+|----------|-----------|---------|
+| \`type\` | **Yes** for normal scalar fields | \`string\`, \`number\`, \`boolean\`, \`email\`, \`url\`, \`date\`, etc. |
+| \`description\` | Strongly recommended | Used in docs and UX. |
+| \`value\` | Optional | **Default** baked into the model (static metadata), not per-record data. Rare for entity fields. |
+| \`ref\` | Optional | Advanced reference. Prefer \`defineRelationship\` for links between entities. |
+| \`has\` | Optional | Nested structure (advanced). |
+
+**Precision checklist for fields**
+
+- Use **snake_case** consistently across manifest, \`recordObject\`, and sandbox code.
+- Every scalar field should have \`"type": "..."\`.
+- Do **not** store links to other entities as opaque strings when you can use **relationships** (next section).
+
+---
+
+## Operations: \`defineRelationship\` (model links precisely)
+
+Relationships connect two classes and fix **property names** and **cardinality** on each side.
+
+Example (customer \u2194 orders: one customer, many orders; each order has one customer):
+
+\`\`\`json
+{
+  "defineRelationship": {
+    "left": "customer",
+    "right": "order",
+    "leftSubmodel": "orders",
+    "rightSubmodel": "customer",
+    "leftIsMany": true,
+    "rightIsMany": false
+  }
+}
+\`\`\`
+
+### How to read one \`defineRelationship\` block
+
+| JSON field | Meaning |
+|------------|---------|
+| \`left\`, \`right\` | **Class names** (same strings as in \`"create": "customer"\`). |
+| \`leftSubmodel\` | On an instance of \`left\`, the **property name** pointing toward \`right\` (e.g. \`customer.orders\`). |
+| \`rightSubmodel\` | On an instance of \`right\`, the **property name** pointing back to \`left\` (e.g. \`order.customer\`). |
+| \`leftIsMany\` | If \`true\`, when recording a \`left\` instance, this side is a **list** of target ids. |
+| \`rightIsMany\` | Same for the \`right\` side. |
+
+### Mapping to \`recordObject({ relationships })\`
+
+**Keys** in \`relationships\` are \`leftSubmodel\` or \`rightSubmodel\` depending on which **class** you are recording:
+
+- Recording a **left** class instance \u2192 use \`leftSubmodel\` as the key (values are \`right\` class ids).
+- Recording a **right** class instance \u2192 use \`rightSubmodel\` as the key (values are \`left\` class ids).
+
+**Values** are always **ids of the target objects** (the foreign class), as plain strings:
+
+- **Many** side \u2192 \`string[]\`.
+- **One** side \u2192 a single \`string\`.
+
+Example:
+
+- \`recordObject({ className: 'customer', id: 'acme', relationships: { orders: ['ord_1', 'ord_2'] } })\`
+- \`recordObject({ className: 'order', id: 'ord_1', relationships: { customer: 'acme' } })\`
+
+**Anti-patterns**
+
+- Storing \`customer_id\` as a raw string field on \`order\` **without** a \`defineRelationship\` \u2014 you lose cardinality and typed navigation in the sandbox.
+- Putting **synthetic path strings** (e.g. class name + underscore + id) in \`relationships\` \u2014 pass **only** the other object\u2019s \`id\` for its class (e.g. \`ord_1\`), not encoded paths.
+
+---
+
+## Operations: \`withEffect\` (declare actions outside the sandbox)
+
+**An effect** is a named, schema-backed **action** that sandbox code can call like a function. The **declaration** is in the manifest; the **implementation** runs in **your** server (API keys, databases, external APIs live there\u2014not inside the sandbox).
+
+\`\`\`json
+{
+  "withEffect": {
+    "name": "charge_card",
+    "description": "Charge the customer",
+    "attachedClass": "invoice",
+    "isStatic": false,
+    "inputSchema": { "type": "object", "properties": { "amount_cents": { "type": "number" } }, "required": ["amount_cents"] },
+    "outputSchema": { "type": "object", "properties": { "chargeId": { "type": "string" } }, "required": ["chargeId"] },
+    "stability": "stable",
+    "tags": ["billing"]
+  }
+}
+\`\`\`
+
+| Field | Meaning |
+|-------|---------|
+| \`name\` | Must match the \`name\` in \`registerEffects\`. |
+| \`attachedClass\` | Omit for **global** effects. Set for class-bound effects. |
+| \`isStatic\` | \`true\` \u2192 static method; \`false\` or omit \u2192 **instance** method (handler receives the object **id** first). |
+| \`inputSchema\` / \`outputSchema\` | JSON Schema; used for codegen and validation. |
+
+**Lifecycle:** declare in manifest \u2192 \`granular build\` \u2192 implement handlers \u2192 \`granular.registerEffects(sandboxId, [...])\` \u2192 jobs call generated methods \u2192 your handler runs and returns the result to the job.
+
+**Permissions:** \`connect({ permissions: [...] })\` assigns profiles (e.g. \`default\`) that can allow or deny which effects a user may call.
+
+---
+
+## IDs and labels
+
+| Concept | Rule |
+|---------|------|
+| \`id\` in \`recordObject\` | **Per-class** unique string you choose. Two different classes *may* reuse the same id string. |
+| \`label\` | Display label; optional. |
+| \`recordObject\` | Upserts by \`{ className, id }\`; fields and relationships are reapplied. |
+| \`relationships\` values | Use the **target object\u2019s id** for its class (see above). |
+
+---
+
+## \`@granular-software/sdk\` \u2014 capability map (after build)
+
+### \`Granular\` client
+
+| API | Purpose |
+|-----|---------|
+| \`new Granular({ apiKey, apiUrl?, endpointMode?, token?, tokenProvider?, \u2026 })\` | Auth. Env: \`GRANULAR_API_KEY\`, \`GRANULAR_API_URL\`, \`GRANULAR_ENDPOINT_MODE\`. |
+| \`recordUser({ userId, name?, email?, permissions? })\` | Upsert user for later \`connect\`. |
+| \`connect({ sandbox, userId?, granularId?, user?, permissions?, clientId?, initialHeap? })\` | Opens a session \u2192 **\`Environment\`**. |
+| \`registerEffects(sandboxId, effects)\` / \`registerEffect\` | Register handlers for manifest \`withEffect\` declarations. |
+| \`unregisterEffect\` / \`unregisterAllEffects\` / \`disconnectEffects\` | Stop effect handlers for a sandbox. |
+| \`granular.sandboxes\` | \`.list()\`, \`.get\`, \`.create\`, \`.update\`, \`.delete\` |
+| \`granular.permissionProfiles\` | Permission profiles per sandbox. |
+| \`granular.environments\` | List/create/delete environments (usually use \`connect()\`). |
+| \`granular.subjects\` | Subjects / assignments (see typings). |
+
+### \`Environment\` (connected session)
+
+| API | Purpose |
+|-----|---------|
+| \`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. |
+| \`enqueueRecordImport\`, \`listRecordImports\`, \`getRecordImportSummary\`, \u2026 | Background bulk import. |
+| \`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\`. |
+| \`getDomain()\`, \`getDomainTypes()\`, \`getDomainDocs()\`, \`getDomainDocumentation()\` | Domain summary and generated TypeScript / docs. |
+| \`getEffects()\` / \`getTools()\`, \`onEffectsChanged()\` | Effect catalog and updates. |
+| \`checkReadiness()\`, \`on('readiness', \u2026)\` | Environment readiness. |
+| \`getHeap()\` | Session state snapshot (advanced). |
+| \`rpc(method, params)\` | Low-level session RPC (advanced). |
+| \`disconnect()\` | End the session. |
+
+### GraphQL API (\`env.graphql\`)
+
+Use \`environment.graphql(query, variables?)\` when you need **query/mutation access to the underlying graph** (paths, models, relationships). This is optional for many apps; \`recordObject\` and generated classes cover the common case. Authenticated with your API key.
+
+### \`Session\` (base class)
+
+| API | Purpose |
+|-----|---------|
+| \`submitJob\`, \`answerPrompt\`, job APIs | Jobs and human-in-the-loop prompts. |
+
+---
+
+## CLI commands
+
+| Command | Purpose |
+|---------|---------|
+| \`granular build\` | Upload \`granular.json\` and compile (primary **validation**). |
+| \`granular deploy\` | Build + deploy current production. |
+| \`granular dev\` | Watch manifest, rebuild on change. |
+| \`granular document\` | Regenerate \`GRANULAR_SANDBOX.md\`. |
+| \`granular init\` | Scaffold project; optional \`--agent-docs\`. |
+| \`granular add class|field|relation\` | Mutate local manifest. |
+| \`granular simulate\` | Open simulator in browser. |
+| \`granular pull\` | Pull manifest from API. |
+| \`granular login\`, \`granular whoami\`, \`granular status\` | Auth / project info. |
+
+---
+
+## After you change the manifest
+
+1. \`granular build\` (or \`granular dev\`).
+2. Align **effect handlers** with every \`withEffect\` name + schemas.
+3. \`granular document\` to refresh \`GRANULAR_SANDBOX.md\` without a full build if needed (build still records manifest/build ids).
+
+---
+
+## Further reading
+
+- [docs.granular.dev](https://docs.granular.dev)
+- Generated sandbox snapshot: [GRANULAR_SANDBOX.md](../GRANULAR_SANDBOX.md)
+`;
+}
+
+// src/cli/agent-docs/agents-md.ts
+var GRANULAR_AGENTS_BEGIN = "<!-- granular-sdk:begin -->";
+var GRANULAR_AGENTS_END = "<!-- granular-sdk:end -->";
+function generateGranularAgentsBlock(options) {
+  const manifestPath = options?.manifestGuidePath ?? "docs/granular-manifest.md";
+  return `${GRANULAR_AGENTS_BEGIN}
+
+## Granular (this project)
+
+**No prior Granular context assumed.** Read in order:
+
+1. **[${manifestPath}](${manifestPath})** \u2014 What Granular is, glossary, \`granular.json\` operations, \`granular build\`, \`connect\` / **environment** / **session**, \`submitJob\`, \`recordObject\`, **effects**, SDK + CLI reference.
+2. **[GRANULAR_SANDBOX.md](GRANULAR_SANDBOX.md)** \u2014 This repo\u2019s **ontology only**: exact class/field names, relationship keys, effect schemas, snippets for **this** sandbox id.
+
+**Instruction precedence:** User chat > this section > other content in this file.
+
+${GRANULAR_AGENTS_END}`;
+}
+function mergeGranularAgentsBlock(existingContent, block) {
+  const trimmed = existingContent.trimEnd();
+  if (trimmed.includes(GRANULAR_AGENTS_BEGIN) && trimmed.includes(GRANULAR_AGENTS_END)) {
+    const re = new RegExp(
+      `${escapeRegex(GRANULAR_AGENTS_BEGIN)}[\\s\\S]*?${escapeRegex(GRANULAR_AGENTS_END)}`,
+      "m"
+    );
+    return existingContent.replace(re, block.trim());
+  }
+  if (!trimmed) {
+    return `${block.trim()}
+`;
+  }
+  return `${trimmed}
+
+${block.trim()}
+`;
+}
+function escapeRegex(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+// src/cli/agent-docs/sandbox-doc.ts
+function exampleScalarValue(type) {
+  if (type === "number") return 0;
+  if (type === "boolean") return true;
+  if (type === "date") return "2026-01-01";
+  if (type === "email") return "user@example.com";
+  if (type === "url") return "https://example.com";
+  return "example";
+}
+function formatSchemaSnippet(obj, maxLen = 2e3) {
+  const s = JSON.stringify(obj, null, 2);
+  if (s.length <= maxLen) return s;
+  return `${s.slice(0, maxLen)}
+  /* \u2026 truncated \u2026 */`;
+}
+function generateSandboxAgentDoc(manifest, meta) {
+  const parsed = parseManifestContent(manifest);
+  const { classes, relationships, effects } = parsed;
+  const lines = [];
+  const seed = meta.seedScriptName ?? "granular-seed.ts";
+  const eff = meta.effectsScriptName ?? "granular-effects.ts";
+  lines.push(`# ${manifest.name} \u2014 sandbox agent reference`);
+  lines.push("");
+  lines.push(
+    "> **For coding agents:** **Project-specific** snapshot (this sandbox\u2019s classes, keys, effects). For what Granular is and how manifests work, read [docs/granular-manifest.md](docs/granular-manifest.md) first. Regenerate with `granular document` or after `granular build`."
+  );
+  lines.push("");
+  lines.push("## Sandbox identity");
+  lines.push("");
+  lines.push("| Key | Value |");
+  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.buildId) lines.push(`| Last build id | \`${meta.buildId}\` |`);
+  if (meta.buildPending) {
+    lines.push("| Build status | *No successful 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("");
+  for (const line of sandboxDocMainConceptsSection().split("\n")) {
+    lines.push(line);
+  }
+  lines.push("");
+  for (const line of sandboxDocScopeSection(manifest.name).split("\n")) {
+    lines.push(line);
+  }
+  lines.push("");
+  lines.push("## Quick CLI");
+  lines.push("");
+  lines.push("| Command | Purpose |");
+  lines.push("|---------|---------|");
+  lines.push("| `granular build` | Upload manifest and build |");
+  lines.push("| `granular document` | Refresh this file from `granular.json` |");
+  lines.push("| `npx tsx " + seed + "` | Seed sample records (if present) |");
+  lines.push("| `npx tsx " + eff + "` | Run effect handler host (if present) |");
+  lines.push("");
+  lines.push("## Connect");
+  lines.push("");
+  lines.push("```typescript");
+  lines.push(`import { Granular } from '@granular-software/sdk';`);
+  lines.push("");
+  lines.push(`const granular = new Granular({`);
+  lines.push(`  apiKey: process.env.GRANULAR_API_KEY!,`);
+  lines.push(`  // apiUrl: process.env.GRANULAR_API_URL, // optional`);
+  lines.push(`});`);
+  lines.push("");
+  lines.push(`const env = await granular.connect({`);
+  lines.push(`  sandbox: '${meta.sandboxId}',`);
+  lines.push(`  userId: 'your_app_user_id',`);
+  lines.push(`  permissions: ['default'],`);
+  lines.push(`});`);
+  lines.push("```");
+  lines.push("");
+  lines.push("## Classes and fields");
+  lines.push("");
+  if (classes.length === 0) {
+    lines.push("*No `create` + `@std/class` operations found in the manifest.*");
+    lines.push("");
+  } else {
+    for (const cls of classes) {
+      lines.push(`### \`${cls.name}\``);
+      lines.push("");
+      if (cls.description) lines.push(cls.description);
+      lines.push("");
+      const keys = Object.keys(cls.fields);
+      if (keys.length === 0) {
+        lines.push("*No scalar fields in `has`.*");
+      } else {
+        lines.push("| Field | Type | Description |");
+        lines.push("|-------|------|-------------|");
+        for (const k of keys) {
+          const spec = cls.fields[k];
+          const t = spec?.type || "\u2014";
+          const d = spec?.description || "\u2014";
+          lines.push(`| \`${k}\` | \`${String(t)}\` | ${d} |`);
+        }
+      }
+      lines.push("");
+    }
+  }
+  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("");
+  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("|------|-------|-------------|---------------------------|----------------------------|");
+    for (const r of relationships) {
+      lines.push(
+        `| \`${r.left}\` | \`${r.right}\` | ${r.cardinalityLabel} | \`${r.leftSubmodel}\` | \`${r.rightSubmodel}\` |`
+      );
+    }
+    lines.push("");
+  }
+  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("");
+  for (const cls of classes) {
+    const edges = relationshipEdgesForClass(cls.name, relationships);
+    lines.push(`### \`${cls.name}\``);
+    lines.push("");
+    lines.push("```typescript");
+    lines.push(`await env.recordObject({`);
+    lines.push(`  className: '${cls.name}',`);
+    lines.push(`  id: 'your_${cls.name}_id',`);
+    lines.push(`  label: 'Label',`);
+    const fieldKeys = Object.keys(cls.fields);
+    if (fieldKeys.length > 0) {
+      lines.push(`  fields: {`);
+      for (const k of fieldKeys) {
+        const spec = cls.fields[k];
+        const v = exampleScalarValue(spec?.type);
+        const lit = typeof v === "string" ? `'${v}'` : JSON.stringify(v);
+        lines.push(`    ${k}: ${lit},`);
+      }
+      lines.push(`  },`);
+    }
+    if (edges.length > 0) {
+      lines.push(`  relationships: {`);
+      for (const e of edges) {
+        if (e.isMany) {
+          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(`  },`);
+    }
+    lines.push(`});`);
+    lines.push("```");
+    lines.push("");
+  }
+  if (classes.length === 0) {
+    lines.push("*No classes \u2014 no examples.*");
+    lines.push("");
+  }
+  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("");
+  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("");
+  if (effects.length === 0) {
+    lines.push("*No `withEffect` operations in this manifest.*");
+    lines.push("");
+  } else {
+    for (const ef of effects) {
+      const scope = ef.attachedClass ? ef.isStatic ? `static on \`${ef.attachedClass}\`` : `instance on \`${ef.attachedClass}\`` : "global";
+      lines.push(`### \`${ef.name}\` (${scope})`);
+      lines.push("");
+      if (ef.description) lines.push(ef.description);
+      lines.push("");
+      lines.push("**Input schema:**");
+      lines.push("");
+      lines.push("```json");
+      lines.push(formatSchemaSnippet(ef.inputSchema));
+      lines.push("```");
+      lines.push("");
+      if (ef.outputSchema) {
+        lines.push("**Output schema:**");
+        lines.push("");
+        lines.push("```json");
+        lines.push(formatSchemaSnippet(ef.outputSchema));
+        lines.push("```");
+        lines.push("");
+      }
+      lines.push("**Handler signature (TypeScript):**");
+      lines.push("");
+      if (!ef.attachedClass) {
+        lines.push("```typescript");
+        lines.push(`// Global: (params, ctx) => Promise<output>`);
+        lines.push(`handler: async (params, ctx) => { /* ... */ }`);
+        lines.push("```");
+      } else if (ef.isStatic) {
+        lines.push("```typescript");
+        lines.push(`// Static: (params, ctx) => Promise<output>`);
+        lines.push(`handler: async (params, ctx) => { /* ... */ }`);
+        lines.push("```");
+      } 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("```");
+      }
+      lines.push("");
+    }
+  }
+  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("");
+  const pascalImports = classes.map((c) => toPascalCase(c.name));
+  const effectNames = effects.map((e) => e.name).filter(Boolean);
+  const globalEffects = effects.filter((e) => !e.attachedClass);
+  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);
+  if (importList.length > 0) {
+    lines.push(`  import { ${importList.join(", ")} } from './sandbox-tools';`);
+  } else {
+    lines.push(`  // import generated classes/tools from './sandbox-tools'`);
+  }
+  lines.push("");
+  if (classes.length > 0) {
+    const classWithInstanceEffect = classes.find(
+      (cl) => effects.some((e) => e.attachedClass === cl.name && !e.isStatic)
+    );
+    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 row = rows[0] ?? null;`);
+    lines.push("");
+    const instEffects = effects.filter((e) => e.attachedClass === c && !e.isStatic);
+    if (instEffects.length > 0) {
+      const n = instEffects[0].name;
+      lines.push(`  if (row) {`);
+      lines.push(`    const out = await row.${n}({ /* input per schema */ });`);
+      lines.push(`    console.log(out);`);
+      lines.push(`  }`);
+    } else {
+      lines.push(`  console.log(row?.id);`);
+    }
+    lines.push("");
+  }
+  if (firstGlobal) {
+    lines.push(`  await ${firstGlobal}({ /* input per schema */ });`);
+    lines.push("");
+  }
+  lines.push(`  return { ok: true };`);
+  lines.push(`\`);`);
+  lines.push("");
+  lines.push(`const result = await job.result;`);
+  lines.push("```");
+  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("");
+  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("| Jobs | `submitJob`, `answerPrompt` |");
+  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("");
+  lines.push("---");
+  lines.push("");
+  lines.push(`*Generated at ${(/* @__PURE__ */ new Date()).toISOString()} by @granular-software/sdk*`);
+  lines.push("");
+  return lines.join("\n");
+}
+var MANIFEST_GUIDE_RELATIVE = path__namespace.join("docs", "granular-manifest.md");
+var SANDBOX_DOC_FILENAME = "GRANULAR_SANDBOX.md";
+function getAgentsMdPath(projectRoot) {
+  return path__namespace.join(projectRoot, "AGENTS.md");
+}
+function getManifestGuidePath(projectRoot) {
+  return path__namespace.join(projectRoot, MANIFEST_GUIDE_RELATIVE);
+}
+function getSandboxDocPath(projectRoot) {
+  return path__namespace.join(projectRoot, SANDBOX_DOC_FILENAME);
+}
+function writeManifestAgentDocs(projectRoot, projectName) {
+  const docsDir = path__namespace.join(projectRoot, "docs");
+  if (!fs__namespace.existsSync(docsDir)) {
+    fs__namespace.mkdirSync(docsDir, { recursive: true });
+  }
+  const guidePath = getManifestGuidePath(projectRoot);
+  const guide = generateManifestAgentGuide({ projectName });
+  fs__namespace.writeFileSync(guidePath, guide, "utf-8");
+  const agentsPath = getAgentsMdPath(projectRoot);
+  const block = generateGranularAgentsBlock({ manifestGuidePath: MANIFEST_GUIDE_RELATIVE.replace(/\\/g, "/") });
+  const previous = fs__namespace.existsSync(agentsPath) ? fs__namespace.readFileSync(agentsPath, "utf-8") : "";
+  const merged = mergeGranularAgentsBlock(previous, block);
+  fs__namespace.writeFileSync(agentsPath, merged, "utf-8");
+}
+function writeSandboxAgentDocFile(projectRoot, manifest, meta) {
+  const metaWithScripts = {
+    ...meta,
+    seedScriptName: meta.seedScriptName ?? SEED_SCRIPT_NAME,
+    effectsScriptName: meta.effectsScriptName ?? EFFECTS_SCRIPT_NAME
+  };
+  const body = generateSandboxAgentDoc(manifest, metaWithScripts);
+  const out = getSandboxDocPath(projectRoot);
+  fs__namespace.writeFileSync(out, body, "utf-8");
+}
+
 // src/cli/commands/init.ts
 function prompt(question, defaultValue) {
   const rl = readline__namespace.createInterface({ input: process.stdin, output: process.stdout });
@@ -8726,6 +9552,10 @@ async function selectStarterTemplate(requestedTemplate) {
 }
 async function initCommand(projectName, options) {
   printHeader();
+  if (options?.agentDocs && options?.noAgentDocs) {
+    error("Cannot use --agent-docs and --no-agent-docs together.");
+    process.exit(1);
+  }
   if (manifestExists()) {
     warn("A granular.json already exists in this directory.");
     const overwrite = await confirm("Overwrite?", false);
@@ -8803,6 +9633,25 @@ async function initCommand(projectName, options) {
   success(`Created ${brand.bold(".granularrc")}`);
   ensureGitignore();
   success("Updated .gitignore");
+  let wantAgentDocs = false;
+  if (options?.agentDocs) {
+    wantAgentDocs = true;
+  } else if (options?.noAgentDocs) {
+    wantAgentDocs = false;
+  } else if (process.stdin.isTTY && process.stdout.isTTY) {
+    console.log();
+    wantAgentDocs = await confirm(
+      "Add agent documentation (AGENTS.md + docs/granular-manifest.md for AI coding tools)?",
+      true
+    );
+  }
+  if (wantAgentDocs) {
+    writeManifestAgentDocs(getProjectRoot(), name);
+    success(`Created ${brand.bold("AGENTS.md")} and ${brand.bold("docs/granular-manifest.md")}`);
+  }
+  let lastManifestId;
+  let lastBuildId;
+  let initialBuildSucceeded = false;
   console.log();
   const shouldBuild = options?.skipBuild ? false : await confirm("Trigger initial build?", true);
   if (shouldBuild) {
@@ -8814,12 +9663,15 @@ async function initCommand(projectName, options) {
         project.manifest,
         "1.0.0"
       );
+      lastManifestId = manifest.manifestId;
       building.text = "  Triggering build...";
       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)}`);
     } catch (err) {
       building.fail(`  Build failed: ${err.message}`);
@@ -8840,20 +9692,34 @@ async function initCommand(projectName, options) {
     "utf-8"
   );
   success(`Created ${brand.bold(SEED_SCRIPT_NAME)} (sample record seeding script)`);
+  writeSandboxAgentDocFile(getProjectRoot(), project.manifest, {
+    sandboxId: sandbox.sandboxId,
+    apiUrl,
+    manifestId: lastManifestId,
+    buildId: lastBuildId,
+    buildPending: !initialBuildSucceeded
+  });
+  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();
-  keyValue({
+  const kv = {
     "Sandbox": sandbox.sandboxId,
     "Template": template.label,
     "Manifest": "granular.json",
     "Config": ".granularrc",
     "API Key": ".env.local",
     "Seed script": SEED_SCRIPT_NAME,
-    "Effects script": EFFECTS_SCRIPT_NAME
-  });
+    "Effects script": EFFECTS_SCRIPT_NAME,
+    "Sandbox agent doc": "GRANULAR_SANDBOX.md"
+  };
+  if (wantAgentDocs) {
+    kv["Agent manifest guide"] = "docs/granular-manifest.md";
+    kv["Agent index"] = "AGENTS.md";
+  }
+  keyValue(kv);
   const nextSteps2 = options?.skipBuild ? [
     { command: "granular build", description: "Build the starter ontology before you seed or simulate" },
     { command: `npx tsx ${SEED_SCRIPT_NAME}`, description: "Push the sample records into your sandbox" },
@@ -8872,7 +9738,7 @@ async function initCommand(projectName, options) {
   dim("  The seed script shows how records enter the graph. The effects script shows how external systems plug in.");
   console.log();
 }
-var DEFAULT_LOCAL_API_KEY = "gn_sk_tenant_default_principal_local_e2e_00000000";
+var DEFAULT_LOCAL_API_KEY2 = "gn_sk_tenant_default_principal_local_e2e_00000000";
 function promptSecret(question) {
   const rl = readline__namespace.createInterface({ input: process.stdin, output: process.stdout });
   return new Promise((resolve) => {
@@ -8898,7 +9764,7 @@ function maskApiKey(apiKey) {
   if (apiKey.length < 10) return `${apiKey}...`;
   return `${apiKey.substring(0, 10)}...`;
 }
-function isLocalApiUrl(apiUrl) {
+function isLocalApiUrl2(apiUrl) {
   return apiUrl.startsWith("ws://localhost:") || apiUrl.startsWith("wss://localhost:") || apiUrl.startsWith("ws://127.0.0.1:") || apiUrl.startsWith("wss://127.0.0.1:") || apiUrl.startsWith("http://localhost:") || apiUrl.startsWith("https://localhost:") || apiUrl.startsWith("http://127.0.0.1:") || apiUrl.startsWith("https://127.0.0.1:");
 }
 async function loginCommand(options = {}) {
@@ -8912,8 +9778,8 @@ async function loginCommand(options = {}) {
   const apiUrl = loadApiUrl();
   let apiKey = options.apiKey?.trim();
   if (!apiKey) {
-    if (!options.manual && isLocalApiUrl(apiUrl)) {
-      apiKey = existing?.trim() || process.env.GRANULAR_LOCAL_API_KEY?.trim() || DEFAULT_LOCAL_API_KEY;
+    if (!options.manual && isLocalApiUrl2(apiUrl)) {
+      apiKey = existing?.trim() || process.env.GRANULAR_LOCAL_API_KEY?.trim() || DEFAULT_LOCAL_API_KEY2;
       info("Using local Granular API key for localhost development.");
     } else if (options.manual) {
       dim("Get your API key at https://app.granular.software/w/default/api-keys");
@@ -9040,12 +9906,19 @@ async function buildCommand() {
     });
     const totalTime = Math.round((Date.now() - startTime) / 1e3);
     building.succeed(`  Build completed in ${totalTime}s`);
+    writeSandboxAgentDocFile(getProjectRoot(), manifest, {
+      sandboxId: config.sandboxId,
+      apiUrl: config.apiUrl,
+      manifestId: uploadedManifest.manifestId,
+      buildId: completed.buildId
+    });
     console.log();
     keyValue({
       "Build ID": completed.buildId,
       "Manifest": uploadedManifest.manifestId,
       "Status": "completed",
-      "Duration": `${totalTime}s`
+      "Duration": `${totalTime}s`,
+      "Agent doc": "GRANULAR_SANDBOX.md"
     });
     console.log();
   } catch (err) {
@@ -9063,9 +9936,9 @@ async function deployCommand() {
     process.exit(1);
   }
   const api = new ApiClient(config.apiKey, config.apiUrl);
-  const manifest = config.project.manifest;
   step("Deploy", `Sandbox ${config.sandboxId}`);
   console.log();
+  const manifest = config.project.manifest;
   const uploading = spinner(`Uploading manifest "${manifest.name}"...`);
   let uploadedManifest;
   try {
@@ -9085,13 +9958,20 @@ async function deployCommand() {
     });
     const totalTime = Math.round((Date.now() - startTime) / 1e3);
     building.succeed(`  Build completed in ${totalTime}s`);
+    writeSandboxAgentDocFile(getProjectRoot(), manifest, {
+      sandboxId: config.sandboxId,
+      apiUrl: config.apiUrl,
+      manifestId: uploadedManifest.manifestId,
+      buildId: completed.buildId
+    });
     console.log();
     success(`Deployed ${brand.bold(manifest.name)} successfully!`);
     console.log();
     keyValue({
       "Build": completed.buildId,
       "Manifest": uploadedManifest.manifestId,
-      "Status": "live"
+      "Status": "live",
+      "Agent doc": "GRANULAR_SANDBOX.md"
     });
     console.log();
   } catch (err) {
@@ -9404,6 +10284,12 @@ async function devCommand() {
       });
       const totalTime = Math.round((Date.now() - startTime) / 1e3);
       spin.succeed(`  Build completed in ${totalTime}s \u2014 ${brand.secondary(completed.buildId)}`);
+      writeSandboxAgentDocFile(getProjectRoot(), project.manifest, {
+        sandboxId: config.sandboxId,
+        apiUrl: config.apiUrl,
+        manifestId: uploaded.manifestId,
+        buildId: completed.buildId
+      });
     } catch (err) {
       error(`Build failed: ${err.message}`);
     }
@@ -9423,251 +10309,30 @@ async function devCommand() {
   await new Promise(() => {
   });
 }
+
+// src/cli/commands/document.ts
 async function documentCommand() {
   printHeader();
-  const spinner2 = spinner("Generating documentation...");
+  const spinner2 = spinner("Generating GRANULAR_SANDBOX.md...");
   const project = readManifestFile();
   if (!project) {
     spinner2.fail("No granular.json found. Run `granular init` first.");
     return;
   }
   const rc = readRcFile();
-  const sandboxId = rc.sandboxId || "my-sandbox";
-  const manifest = project.manifest;
-  const classes = [];
-  const relationships = [];
-  for (const vol of manifest.volumes) {
-    for (const op of vol.operations) {
-      if (op.create && op.extends === "@std/class") {
-        classes.push({
-          name: op.create,
-          fields: op.has || {},
-          description: op.description
-          // Description might be on the operation in some versions
-        });
-      }
-      if (op.defineRelationship) {
-        const rel = op.defineRelationship;
-        const type = rel.leftIsMany ? rel.rightIsMany ? "Many-to-Many" : "One-to-Many" : rel.rightIsMany ? "Many-to-One" : "One-to-One";
-        relationships.push({
-          left: rel.left,
-          right: rel.right,
-          relName: `${rel.left}.${rel.leftSubmodel} \u2194 ${rel.right}.${rel.rightSubmodel}`,
-          type
-        });
-      }
-    }
-  }
-  const lines = [];
-  lines.push(`# ${manifest.name}`);
-  if (manifest.description) lines.push(`
-${manifest.description}`);
-  lines.push(`
-> Generated by Granular SDK from \`granular.json\``);
-  lines.push(`
-## Table of Contents`);
-  lines.push(`- [Getting Started](#getting-started)`);
-  lines.push(`- [Schema Overview](#schema-overview)`);
-  lines.push(`- [Integration Guide](#integration-guide)`);
-  lines.push(`  - [1. Initialize & Connect](#1-initialize--connect)`);
-  lines.push(`  - [2. Record Objects](#2-record-objects)`);
-  lines.push(`  - [3. Declare And Register Effects](#3-declare-and-register-effects)`);
-  lines.push(`  - [4. Submit Jobs](#4-submit-jobs)`);
-  lines.push(`
-## Getting Started`);
-  lines.push(`
-1. **Install the SDK**`);
-  lines.push(`   \`\`\`bash
-   npm install @granular-software/sdk
-   \`\`\``);
-  lines.push(`
-2. **Get your API Key**`);
-  lines.push(`   Get your key from [Granular Dashboard](https://granular.dev) and set it in your environment:`);
-  lines.push(`   \`\`\`bash
-   export GRANULAR_API_KEY=your_key_here
-   \`\`\``);
-  lines.push(`
-## Schema Overview`);
-  if (classes.length > 0) {
-    lines.push(`
-### Classes`);
-    for (const cls of classes) {
-      lines.push(`
-#### \`${cls.name}\``);
-      if (cls.description) lines.push(`*${cls.description}*`);
-      const fieldNames = Object.keys(cls.fields);
-      if (fieldNames.length > 0) {
-        lines.push(`
-| Field | Type | Description |`);
-        lines.push(`|---|---|---|`);
-        for (const [key, spec] of Object.entries(cls.fields)) {
-          const type = spec.type || "unknown";
-          const desc = spec.description || "-";
-          lines.push(`| \`${key}\` | \`${type}\` | ${desc} |`);
-        }
-      } else {
-        lines.push(`
-*No fields defined.*`);
-      }
-    }
-  }
-  if (relationships.length > 0) {
-    lines.push(`
-### Relationships`);
-    lines.push(`
-| Relationship | Type |`);
-    lines.push(`|---|---|`);
-    for (const rel of relationships) {
-      lines.push(`| \`${rel.relName}\` | ${rel.type} |`);
-    }
-  }
-  lines.push(`
-## Integration Guide`);
-  lines.push(`
-### 1. Initialize & Connect`);
-  lines.push(`
-\`\`\`typescript`);
-  lines.push(`import { Granular } from '@granular-software/sdk';`);
-  lines.push(`
-const granular = new Granular({`);
-  lines.push(`  apiKey: process.env.GRANULAR_API_KEY!,`);
-  lines.push(`});`);
-  lines.push(`
-// 1. Connect to the sandbox for one of your app users`);
-  lines.push(`const env = await granular.connect({`);
-  lines.push(`  sandbox: '${sandboxId}',`);
-  lines.push(`  userId: 'user_123', // Your app's user ID`);
-  lines.push(`  email: 'user@example.com', // optional`);
-  lines.push(`  permissions: ['default'], // Permission profile`);
-  lines.push(`});`);
-  lines.push(`
-console.log('Connected to:', env.environmentId);`);
-  lines.push(`\`\`\``);
-  lines.push(`
-### 2. Record Objects`);
-  lines.push(`Sync your data into the graph.`);
-  if (classes.length > 0) {
-    lines.push(`
-\`\`\`typescript`);
-    lines.push(`const env = await granular.connect({`);
-    lines.push(`  sandbox: '${sandboxId}',`);
-    lines.push(`  userId: 'user_123',`);
-    lines.push(`  permissions: ['default'],`);
-    lines.push(`});`);
-    lines.push(``);
-    for (const cls of classes) {
-      const exampleFields = {};
-      for (const [k, v] of Object.entries(cls.fields)) {
-        if (v.type === "string") exampleFields[k] = "example_value";
-        else if (v.type === "number") exampleFields[k] = 123;
-        else if (v.type === "boolean") exampleFields[k] = true;
-        else exampleFields[k] = null;
-      }
-      lines.push(`await env.recordObject({`);
-      lines.push(`  className: '${cls.name}',`);
-      lines.push(`  id: 'unique_${cls.name}_id',`);
-      lines.push(`  label: 'My ${cls.name}',`);
-      if (Object.keys(exampleFields).length > 0) {
-        if (Object.keys(exampleFields).length > 2) {
-          lines.push(`  fields: {`);
-          for (const [k, v] of Object.entries(exampleFields)) {
-            const val = typeof v === "string" ? `'${v}'` : v;
-            lines.push(`    ${k}: ${val},`);
-          }
-          lines.push(`  },`);
-        } else {
-          const entries = Object.entries(exampleFields).map(([k, v]) => `${k}: ${typeof v === "string" ? `'${v}'` : v}`).join(", ");
-          lines.push(`  fields: { ${entries} },`);
-        }
-      }
-      lines.push(`});`);
-      lines.push(``);
-    }
-    lines.push(`\`\`\``);
-  } else {
-    lines.push(`*(No classes defined in manifest)*`);
-  }
-  lines.push(`
-### 3. Declare And Register Effects`);
-  lines.push(`Declare effects in your manifest with \`withEffect\`, then register live handlers at sandbox scope. Use effects for actions in external systems, not for graph reads or search.`);
-  lines.push(`
-\`\`\`typescript`);
-  lines.push(`await granular.registerEffects('your-sandbox-id', [`);
-  if (classes.length > 0) {
-    const cls = classes[0];
-    lines.push(`  // Instance method on ${cls.name}`);
-    lines.push(`  {`);
-    lines.push(`    name: 'sync_external_action',`);
-    lines.push(`    description: 'Perform an external action for this ${cls.name}',`);
-    lines.push(`    className: '${cls.name}',`);
-    lines.push(`    inputSchema: { type: 'object', properties: { reason: { type: 'string' } } },`);
-    lines.push(`    outputSchema: { type: 'object', properties: { actionId: { type: 'string' }, status: { type: 'string' } }, required: ['actionId', 'status'] },`);
-    lines.push(`    handler: async (id, params, ctx) => {`);
-    lines.push(`      // 'id' is the real-world ID of the ${cls.name}`);
-    lines.push(`      console.log('Invoked for user', ctx.user.subjectId);`);
-    lines.push(`      return { actionId: \`act_\${id}\`, status: 'queued' };`);
-    lines.push(`    },`);
-    lines.push(`  },`);
-  }
-  lines.push(`  // Global effect`);
-  lines.push(`  {`);
-  lines.push(`    name: 'notify_team',`);
-  lines.push(`    description: 'Send a message through an external workflow',`);
-  lines.push(`    inputSchema: { type: 'object', properties: { msg: { type: 'string' } }, required: ['msg'] },`);
-  lines.push(`    handler: async (params, ctx) => {`);
-  lines.push(`      console.log('Invoked for user', ctx.user.subjectId);`);
-  lines.push(`      console.log('Notification:', params.msg);`);
-  lines.push(`    },`);
-  lines.push(`  },`);
-  lines.push(`]);`);
-  lines.push(`\`\`\``);
-  lines.push(`
-### 4. Submit Jobs`);
-  lines.push(`Execute code in the sandbox using your domain classes.`);
-  lines.push(`
-\`\`\`typescript`);
-  lines.push(`const job = await env.submitJob(\``);
-  const classImports = classes.map((c) => c.name.charAt(0).toUpperCase() + c.name.slice(1)).join(", ");
-  if (classImports) {
-    lines.push(`  import { ${classImports}, notify_team } from './sandbox-tools';`);
-  } else {
-    lines.push(`  import { notify_team } from './sandbox-tools';`);
+  const sandboxId = rc.sandboxId;
+  if (!sandboxId) {
+    spinner2.fail("No sandbox in .granularrc. Run `granular init` first.");
+    return;
   }
-  lines.push(``);
-  if (classes.length > 0) {
-    const cls = classes[0];
-    const ClassName = cls.name.charAt(0).toUpperCase() + cls.name.slice(1);
-    lines.push(`  // 1. List objects`);
-    lines.push(`  const items = await ${ClassName}.list({ limit: 10, saveAs: '${cls.name}_items' });`);
-    lines.push(`  const item = items[0] ?? null;`);
-    lines.push(`  console.log('Loaded:', item?.id);`);
-    lines.push(``);
-    lines.push(`  // 2. Call instance method`);
-    lines.push(`  if (item) {`);
-    lines.push(`    const action = await item.sync_external_action({ reason: 'Example workflow' });`);
-    lines.push(`    console.log(action);`);
-    lines.push(`  }`);
-    lines.push(``);
-  }
-  lines.push(`  // Call global tool`);
-  lines.push(`  await notify_team({ msg: 'Job completed' });`);
-  lines.push(``);
-  lines.push(`  return { success: true };`);
-  lines.push(`\`);`);
-  lines.push(``);
-  lines.push(`// Wait for result`);
-  lines.push(`const result = await job.result;`);
-  lines.push(`console.log(result);`);
-  lines.push(`\`\`\``);
-  const footer = `
----
-*Documentation generated on ${(/* @__PURE__ */ new Date()).toISOString()}*`;
-  lines.push(footer);
-  const content = lines.join("\n");
-  const outFile = path__namespace.join(getProjectRoot(), "GRANULAR.md");
-  fs__namespace.writeFileSync(outFile, content, "utf-8");
-  spinner2.succeed(`Generated ${brand.bold("GRANULAR.md")}`);
-  info(`Open GRANULAR.md to see your project documentation.`);
+  const apiUrl = loadApiUrl();
+  writeSandboxAgentDocFile(getProjectRoot(), project.manifest, {
+    sandboxId,
+    apiUrl,
+    buildPending: true
+  });
+  spinner2.succeed(`Generated ${brand.bold("GRANULAR_SANDBOX.md")}`);
+  info("This file lists classes, relationships, and effects from granular.json. After a successful build, run again or use `granular build` to fill in manifest and build ids.");
 }
 var SIMULATOR_BASE = "https://app.granular.software/simulator";
 function openUrl(url) {
@@ -9675,13 +10340,19 @@ function openUrl(url) {
   const cmd = platform === "darwin" ? "open" : platform === "win32" ? "start" : "xdg-open";
   child_process.spawn(cmd, [url], { stdio: "ignore", shell: platform === "win32" });
 }
-async function simulateCommand(sandboxIdArg) {
+async function simulateCommand(sandboxIdArg, options) {
   const sandboxId = sandboxIdArg ?? resolveConfig().sandboxId;
   if (!sandboxId) {
     error("No sandbox ID. Run from a project with `granular init` or pass a sandbox ID: granular simulate <sandbox-id>");
     process.exit(1);
   }
-  const url = `${SIMULATOR_BASE}?sandboxId=${encodeURIComponent(sandboxId)}`;
+  const params = new URLSearchParams({
+    sandboxId
+  });
+  if (options?.subjectId) {
+    params.set("subject_id", options.subjectId);
+  }
+  const url = `${SIMULATOR_BASE}?${params.toString()}`;
   info(`Opening simulator: ${url}`);
   openUrl(url);
 }
@@ -9712,11 +10383,13 @@ program2.hook("preAction", () => {
     process.env.GRANULAR_ENDPOINT_MODE = mode;
   }
 });
-program2.command("init [project-name]").description("Initialize a new Granular project").option("--skip-build", "Skip the initial build step").option("--template <template>", "Starter ontology template: library|support|delivery").action(async (projectName, opts) => {
+program2.command("init [project-name]").description("Initialize a new Granular project").option("--skip-build", "Skip the initial build step").option("--template <template>", "Starter ontology template: library|support|delivery").option("--agent-docs", "Add AGENTS.md and docs/granular-manifest.md (for AI coding agents)").option("--no-agent-docs", "Skip agent documentation files").action(async (projectName, opts) => {
   try {
     await initCommand(projectName, {
       skipBuild: opts.skipBuild,
-      template: opts.template
+      template: opts.template,
+      agentDocs: opts.agentDocs,
+      noAgentDocs: opts.noAgentDocs
     });
   } catch (err) {
     error(err.message);
@@ -9811,7 +10484,7 @@ program2.command("dev").description("Start development mode (watch + auto-rebuil
     process.exit(1);
   }
 });
-program2.command("document").description("Generate GRANULAR.md documentation from your manifest").action(async () => {
+program2.command("document").description("Generate GRANULAR_SANDBOX.md (agent reference) from granular.json").action(async () => {
   try {
     await documentCommand();
   } catch (err) {
@@ -9819,9 +10492,9 @@ program2.command("document").description("Generate GRANULAR.md documentation fro
     process.exit(1);
   }
 });
-program2.command("simulate [sandbox-id]").description("Open the Granular simulator in the browser for the current (or given) sandbox").action(async (sandboxId) => {
+program2.command("simulate [sandbox-id]").description("Open the Granular simulator in the browser for the current (or given) sandbox").option("--subject-id <subjectId>", "Open the simulator preloaded for a specific subject").action(async (sandboxId, options) => {
   try {
-    await simulateCommand(sandboxId);
+    await simulateCommand(sandboxId, options);
   } catch (err) {
     error(err.message);
     process.exit(1);