@granular-software/sdk 0.4.12 → 0.4.14

package/README.md

@@ -54,8 +54,8 @@ When the resolved API URL points at `localhost` or `127.0.0.1`, the SDK and CLI
 
 Projects created with `granular init` can include Markdown for coding agents (optional `AGENTS.md` plus generated guides):
 
-- **`docs/granular-manifest.md`** — **What Granular is**, glossary, manifest → build → connect → jobs, **`granular.json`** syntax (**fields**, **relationships**, **effects**), **`@granular-software/sdk`** map, CLI. Self-contained for agents new to the product. Added when you opt in at init (`--agent-docs` / `--no-agent-docs`, or the prompt).
-- **`GRANULAR_SANDBOX.md`** — **This sandbox’s ontology** snapshot: ids, exact names/keys, effect schemas, snippets. Updated after each successful **`granular build`**, **`granular deploy`**, and **`granular dev`** rebuild, and on **`granular document`** (run `build` to record manifest/build ids).
+- **`docs/granular-manifest.md`** — **What Granular is**, glossary, manifest → version → build run → connect → jobs, **`granular.json`** syntax (**fields**, **relationships**, **effects**), **`@granular-software/sdk`** map, CLI. Self-contained for agents new to the product. Added when you opt in at init (`--agent-docs` / `--no-agent-docs`, or the prompt).
+- **`GRANULAR_SANDBOX.md`** — **This sandbox’s ontology** snapshot: ids, exact names/keys, effect schemas, snippets. Updated after each successful **`granular build`**, **`granular deploy`**, and **`granular dev`** rebuild, and on **`granular document`** (run `build` to record version/build metadata).
 - **`AGENTS.md`** — Two-step index: manifest guide first, then sandbox doc (merged idempotently with `<!-- granular-sdk:begin -->`).
 
 ## Quick Start
@@ -65,9 +65,10 @@ import { Granular, type ManifestContent } from '@granular-software/sdk';
 
 const granular = new Granular({ apiKey: process.env.GRANULAR_API_KEY });
 
-// 1. Connect to sandbox for one of your app users
+// 1. Connect to the default dev environment for one of your app users
 const env = await granular.connect({
-  sandbox: 'my-sandbox',
+  ontology: 'my-ontology',
+  environment: 'dev',
   userId: 'user_123',
   permissions: ['agent'],
   name: 'Jane Doe',           // optional
@@ -123,7 +124,7 @@ await env.recordObject({
   fields: { name: 'Acme Corp', email: 'billing@acme.com', tier: 'enterprise' },
 });
 
-// 4. Register live effect handlers for effects already declared in the build manifest
+// 4. Register live effect handlers for effects already declared in the ontology manifest
 await granular.registerEffects(env.sandboxId, [
   {
     name: 'get_billing_summary',
@@ -177,19 +178,19 @@ const job = await env.submitJob(`
 const result = await job.result;
 ```
 
-Effects must be declared ahead of time in the sandbox build manifest with `withEffect`. Live registration only makes already-declared effects available at runtime.
+Effects must be declared ahead of time in the ontology version manifest with `withEffect`. Live registration only makes already-declared effects available at runtime.
 
 ## Core Flow
 
 ```
-declare effects in build manifest → connect({ userId }) → recordObject() → registerEffects() → submitJob()
+declare effects in the manifest → `granular build` creates or reuses a version → `connect({ ontology, environment, userId })` opens a named environment → `recordObject()` → `registerEffects()` → `submitJob()`
 ```
 
-1. **`connect()`** — Connect to a sandbox for a given `userId`, returning an `Environment`
+1. **`connect()`** — Connect to an ontology environment for a given `userId`, returning an `Environment`
 2. **`recordUser()`** — Optional explicit user upsert when you want the returned `granularId`
 3. **`applyManifest()`** — Define your domain ontology (classes, properties, relationships)
 4. **`recordObject()`** — Create/update instances of your classes with fields and relationships
-5. **`granular.registerEffects()`** — Register sandbox-scoped live handlers for effects declared in the build manifest
+5. **`granular.registerEffects()`** — Register sandbox-scoped live handlers for effects declared in the ontology manifest
 6. **`submitJob()`** — Execute code in the sandbox that uses the auto-generated typed classes
 
 ## Defining the Domain Ontology
@@ -246,7 +247,8 @@ After defining the ontology, connect as a user and populate it with data:
 
 ```typescript
 const env = await granular.connect({
-  sandbox: 'library-app',
+  ontology: 'library-app',
+  environment: 'dev',
   userId: 'user_123',
   permissions: ['agent'],
 });
@@ -446,7 +448,7 @@ See [examples/](./examples/) for runnable code:
 Registers a user identity and their assigned permission profiles.
 
 ### `granular.connect(options)`
-Connects to a sandbox session for the specified user.
+Connects to an environment session for the specified user. Pass `ontology` and `environment` explicitly, for example `environment: 'dev'` or `environment: 'prod'`. Only pass `tagName` for advanced overrides.
 
 ### `environment.applyManifest(manifest)`
 Defines domain ontology: classes (with typed properties), and relationships (with cardinality).
@@ -461,7 +463,7 @@ Returns relationship definitions for a given class.
 Lists related instances through a relationship.
 
 ### `granular.registerEffects(sandboxId, effects)`
-Registers sandbox-scoped live handlers for effects declared in the sandbox build manifest. Effects can be instance methods (`className` set, `static` omitted), static methods (`static: true`), or global functions (no `className`).
+Registers sandbox-scoped live handlers for effects declared in the ontology manifest. Effects can be instance methods (`className` set, `static` omitted), static methods (`static: true`), or global functions (no `className`).
 
 ### `environment.submitJob(code)`
 Submits code to be executed in the sandbox. The code imports typed classes from `./sandbox-tools`.