@usestatemachines/sdk 0.11.0 → 0.12.1

package/README.md

@@ -67,14 +67,16 @@ dates, and API key kind. Expiry dates are `Date` objects when present, or `null`
 | `sm` | `me()` |
 | `sm.apps` | `list(query?)`, `versions(appId, query?)` |
 | `sm.workspaces` | `list(query?)`, `get(id)` |
-| `sm.environments` | `create(input, options?)`, `list(query?)`, `get(id)`, `update(id, { name?, labels? })`, `delete(id)`, `wait(id, { status })`, `connect(id, appName, { actorId?, services? }?)` |
-| `sm.snapshots` | `create({ environmentId, name? } \| { importId, name? }, options?)`, `list(query?)`, `get(id)`, `update(id, { name })`, `delete(id)`, `wait(id, { status })` |
+| `sm.environments` | `create(input, options?)`, `list(query?)`, `get(id)`, `update(id, { name?, labels? })`, `delete(id)`, `wait(id, { status })`, `connect(id, appName, { as?, services? }?)`, `actors(id, appName, { search?, limit?, cursor? }?)`, `launchUiSession(id, appName, input)`, `revokeUiSession(id, appName, sessionId)` |
+| `sm.snapshots` | `create({ environmentId, name? } \| { importId, name? } \| { import, name?, workspaceId? }, options?)`, `list(query?)`, `get(id)`, `update(id, { name })`, `delete(id)`, `wait(id, { status })` |
 | `sm.imports` | `upload(zip, options?)`, `list(query?)`, `get(id)`, `delete(id)` |
 | `sm.requests` | `list(query)`, `get(id)`, `stats(query)`, `body(id, 'request' \| 'response')` |
 | `sm.auditEvents` | `list(query?)` |
 
-Every environment the SDK returns carries bound helpers: `env.connect(appName)`, `env.delete()`, `env.refresh()` and `env.snapshots.create({ name? })`. They are
-not enumerable, so `JSON.stringify(env)` holds only the API's fields.
+Every environment the SDK returns carries bound helpers: `env.connect(appName)`, `env.connectAll({ as })`,
+`env.actors(appName)`, `env.launchUiSession(appName, input)`, `env.revokeUiSession(appName, sessionId)`,
+`env.delete()`, `env.refresh()` and `env.snapshots.create({ name? })`. They are not enumerable, so
+`JSON.stringify(env)` holds only the API's fields.
 
 ## Apps
 
@@ -111,13 +113,14 @@ as `setup.preset`.
 checks `services` again when the environment starts, and a value that it refuses fails the start
 with `failure.code: 'invalid_services'`.
 
-`sm.apps.list()` lists the apps. `sm.apps.versions(appId)` lists each version's services and
-actors. A new environment runs each app's default version.
+`sm.apps.list()` lists the apps. `sm.apps.versions(appId)` lists each version's services, and its
+`actors`: the users of the app's seed, for display. A new environment runs each app's default
+version.
 
 ## Credentials
 
-`env.connect(appName, { actorId?, services? })` returns the API's `Credentials`: `token`,
-`services`, `expiresAt` and `login`, plus `fetch(path, init?)` and `service(id)`.
+`env.connect(appName, { as?, services? })` returns the API's `Credentials`: `actorId`, `actor`,
+`token`, `services`, `expiresAt` and `login`, plus `fetch(path, init?)` and `service(id)`.
 
 - Each entry of `services` has an `id`, a `url` and the `headers` that every request to that URL
   needs. A service's `url` is the app URL followed by the service's `path`. The `api` service is
@@ -137,8 +140,18 @@ actors. A new environment runs each app's default version.
   `SessionHeader/sessionId` yourself.
 - `fetch` never sends your API key, never follows redirects, never retries and only reaches paths
   under the `api` service URL.
-- `actorId` defaults to the app's default actor (for Salesforce, the administrator). Pick another
-  from the version's `actors` to act with that user's permissions.
+- `as` names the user to act as, by email, username or ID, such as
+  `env.connect('salesforce', { as: 'alice.park@acme.example' })`. Any user who can sign in to the
+  running app can act, including a user that an import or a program created. Without `as`, the
+  credentials act as the app's default user. When the app's data came from an import whose
+  `actors` names users for the app, the default user is the first of them. Otherwise it is the
+  app's administrator. `actorId` is the old name of `as`.
+- `actor` holds the `id`, `name`, `email`, `username`, `role` and `default` of the user that the
+  credentials act as. `actorId` holds the app's own ID of that user, whatever `as` named.
+- A user that the app does not have throws `ActorNotFoundError`, whose `nearest` lists the users
+  who can act that are nearest to `as`, each with the fields of `actor`. To act as one of them,
+  send its `id` as `as`. A user that the app does not let sign in now, such as an inactive user,
+  throws `ActorCannotSignInError`.
 - `login` holds what the vendor's own login call needs, when the version declares one for the
   actor.
 - `token` and each service's `headers` are secrets. To use another client, such as jsforce, send
@@ -147,14 +160,58 @@ actors. A new environment runs each app's default version.
 Environments created with `tokenInUrl: true` carry the environment token in each service's `url`
 instead of in its `headers`.
 
+`env.actors(appName, { search?, limit?, cursor? })` returns one page of the users who can act in
+the app, the default user first. `search` matches part of a name, an email or a username in any
+case, or a whole ID.
+
+`env.connectAll({ as })` connects to every app of the environment as the user that `as` names. It
+returns `credentials`, by app name, for each app that lets the user act, and `errors`, with the
+`ActorNotFoundError` or `ActorCannotSignInError` of each other app. Any other error throws.
+
 ## Browser UI sessions
 
+A UI session signs one browser in to a browser service of an app, as one actor. Each app of an
+environment lists its browser services in `browserServices`, each with its `serviceId` and the
+`documents` routes that a session can open first.
+
+Your server launches the session with the API key, then gives the launch only to the browser of
+the user it is for:
+
+```ts
+import { StateMachines } from '@usestatemachines/sdk';
+
+const sm = new StateMachines();
+const env = await sm.environments.get('env_...');
+const launch = await env.launchUiSession('linear', {
+  serviceId: 'ui',
+  mode: 'page',
+  launcherOrigin: 'https://app.example.com',
+  entryPath: '/',
+  as: 'riley@example.com',
+});
+// Send the launch to the browser of that user, such as in the response of its own request.
+```
+
+`launcherOrigin` is the exact origin of the page that posts the grant. `entryPath` is the path that
+the session opens first, with an optional query, and it must match one of the service's document
+routes. `as` names the actor as `connect` takes it. The launch holds a one-use `grant` that
+expires soon, at `grantExpiresAt`, and no reusable credential. The session ends at `expiresAt` or
+when your server calls `env.revokeUiSession(appName, launch.sessionId)`.
+
 `@usestatemachines/sdk/ui` is the only part of the SDK for a browser. It holds no client and no
-credential. Your server launches a UI session with the API key, then gives the launch only to
-the browser of the user it is for. In that browser, `submitLaunch(launch, target)` posts the
-launch's one-use grant into `target`: an iframe for an `embedded` launch, or a window for a
-`page` launch. Open the window in the click handler, such as with
-`window.open('about:blank', name)`, so the browser does not block it.
+credential. In the browser, `submitLaunch(launch, target)` posts the launch's grant into
+`target`: an iframe for an `embedded` launch, or a window for a `page` launch. Open the window
+in the click handler so the browser does not block it:
+
+```ts
+import { submitLaunch } from '@usestatemachines/sdk/ui';
+
+button.addEventListener('click', async () => {
+  const target = window.open('about:blank', 'linear');
+  const launch = await (await fetch('/launch-linear', { method: 'POST' })).json();
+  submitLaunch(launch, target);
+});
+```
 
 `listenToSession(launch, iframe, onMessage, { signal })` calls `onMessage` with `ready`,
 `failure` and `logout`. It passes only messages from the session's origin, from that iframe and
@@ -163,6 +220,9 @@ loaded to your page. So wait for `ready` with a timeout, and on `failure` or the
 a `page` launch. The page that posts the grant must send its `Origin`, so do not serve it with
 `Referrer-Policy: no-referrer`.
 
+To open a browser service from a terminal or a coding agent, run `statemachines open <environment>`.
+The CLI serves the page that posts the grant on `127.0.0.1`.
+
 ## Snapshots
 
 ```ts
@@ -182,11 +242,51 @@ const copy = await sm.environments.create({ snapshotId: built.id });
 ```
 
 A snapshot from a `ready` import holds every app of the import, each on its default version,
-with empty setup and services. Each app's `load` counts the records of the import that did not
-load, as `absentCount`, and lists the first of them, as `absent`. An app that refuses the import
-fails the snapshot with `failure.code: 'invalid_import'`, and `SnapshotFailedError.problems`
-lists its problems. An environment from the snapshot does not load the import, so it starts
-after the import is deleted.
+with empty setup and services. Each app's `load` is the report of its load: the counts per
+object, the IDs that the app made, the records that took over seed records, the filled values,
+the actors, the seed users that the load deactivated, the records that did not load, the known
+differences, and the problems. Each list holds its first items beside the count of all of them,
+such as `absent` and `absentCount`. `actors` keeps the order of the import's `actors`, so the
+first is the default user. A record that wrote a text ID, such as `acme`, holds it in `text`.
+`sm.snapshots.list()` answers each app's `load` with every count and no list, so read one
+snapshot with `sm.snapshots.get(id)` for the lists. An app that
+refuses the import fails the snapshot with `failure.code: 'invalid_import'`, and
+`SnapshotFailedError.problems` lists its problems. An environment from the snapshot does not
+load the import, so it starts after the import is deleted.
+
+```ts
+const accounts = await sm.snapshots.create({
+  import: {
+    format: 'statemachines.import/v1',
+    name: 'q3-accounts',
+    apps: {
+      salesforce: {
+        records: {
+          Account: [{ Id: '001g5000003wfcFAAQ', Name: 'Brightwater Shipping' }],
+        },
+      },
+    },
+  },
+});
+```
+
+`{ import }` takes an import as one object, the manifest with each app's records in it. The SDK
+writes the object as a zip file, uploads it as `sm.imports.upload` does, and builds the snapshot
+from the import, in one call. Each app holds its manifest settings, such as `loadMode`, and its
+`records` by object. `content` holds the bytes of the files that the app's records name, by path
+inside the app's `content/` folder, such as Box's `file_version/41500000004`.
+
+The zip file holds the manifest as `statemachines.json`, without `records` and `content`. It
+holds the records of each object as `<app>/records/<Object>.jsonl`, one record per line. So a
+problem at line N of `salesforce/records/Account.jsonl` names
+`apps.salesforce.records.Account[N - 1]`. A problem of `statemachines.json` points into the
+manifest, such as `/apps/salesforce/loadMode` for `apps.salesforce.loadMode`.
+
+Data that the SDK cannot write as a zip file, such as records that are not plain objects, throws
+`StateMachinesError` with `code: 'invalid_request'` and `fields` before any request. An import
+that its check leaves `invalid` throws `ImportInvalidError`, and the SDK creates no snapshot. The
+import and the snapshot share one `idempotencyKey`, so a retry with the same key and the same
+data finds both.
 
 ## Waiting
 
@@ -224,6 +324,9 @@ response body.
 | `StateMachinesError` | any failed call | `code`, `status`, `requestId`, `fields`, `retryAfterMs` |
 | `EnvironmentFailedError` (a `StateMachinesError`) | a waited environment failed | `environment` |
 | `SnapshotFailedError` (a `StateMachinesError`) | a waited snapshot failed | `snapshot` and `problems`. `problems` is empty unless an app refused the import that the snapshot was built from. |
+| `ImportInvalidError` (a `StateMachinesError`) | the check of the import that `snapshots.create({ import })` uploaded left it `invalid` | `import` and `problems` |
+| `ActorNotFoundError` (a `StateMachinesError`) | the app has no user that `as` names | `appName` and `nearest` |
+| `ActorCannotSignInError` (a `StateMachinesError`) | the app does not let the user that `as` names sign in now | `appName` |
 | `UnexpectedStatusError` | a waited resource cannot reach the status without another call | `resource`, `status` |
 | `WaitTimeoutError` | a wait passed `timeoutMs` | `resource` (the last read), `timeoutMs` |
 
@@ -233,12 +336,14 @@ response body.
 | `unauthenticated` | 401 | A missing, expired or revoked key. |
 | `forbidden` | 403 | The key lacks the permission. |
 | `not_found` | 404 | No such resource in this workspace. |
-| `invalid_status` | 409 | The status does not allow the call. |
+| `invalid_status` | 409 | The status does not allow the call. Credentials need a `running` environment. |
 | `snapshot_in_progress` | 409 | The environment has a snapshot in `saving`. |
 | `idempotency_key_reused` | 409 | The same `idempotencyKey` with a different input. |
 | `workspace_archived` | 409 | A write in an archived workspace. |
+| `actor_cannot_sign_in` | 409 | The app does not let the user sign in now. `fields.as` gives the reason. |
 | `body_too_large` | 413 | The request body is over the API's size limit, which the message names. |
 | `version_unavailable` | 422 | The app has no default version. |
+| `actor_not_found` | 422 | The app has no user with that email, username or ID. `nearest` lists the nearest users. |
 | `environment_limit_reached` | 429 | Too many environments `starting` or `running`. |
 | `internal_error` | 500 | An error in State Machines. |
 | `unavailable` | 503 | Retried automatically. |

package/agents/SKILL.md

@@ -15,17 +15,17 @@ The SDK reads `STATEMACHINES_API_KEY` from the process environment. It does not
 
 If the project's existing command loads `STATEMACHINES_API_KEY`, keep using that command and secret loader. Keep the same credential loader, CLI profile and API origin across setup commands. Call `sm.me()` in that process to verify access and workspace scope. `me.limits` can be null.
 
-Otherwise, run `npx @usestatemachines/cli@0.1.1 whoami --json`. Confirm the returned account and organization match the task, then use the workspace commands below. If the CLI credential is missing, expired or revoked, complete this login:
+Otherwise, run `npx @usestatemachines/cli@0.1.4 whoami --json`. Confirm the returned account and organization match the task, then use the workspace commands below. If the CLI credential is missing, expired or revoked, complete this login:
 
-1. Run `npx @usestatemachines/cli@0.1.1 login --no-wait --json`. For an expired or revoked saved session, add `--yes` to replace that invalid session in the same profile. Do not replace a valid session for a different account.
+1. Run `npx @usestatemachines/cli@0.1.4 login --no-wait --json`. For an expired or revoked saved session, add `--yes` to replace that invalid session in the same profile. Do not replace a valid session for a different account.
 2. Show the returned `verificationUrl` and `userCode`. Ask the user to approve only the login you just started. A matching code does not identify the computer requesting access. Wait for the user to approve the login.
-3. After that approval, run `npx @usestatemachines/cli@0.1.1 login --resume --json` with the same profile used to start the login. Resume that attempt instead of starting another login. If it expired, offer a new login.
+3. After that approval, run `npx @usestatemachines/cli@0.1.4 login --resume --json` with the same profile used to start the login. Resume that attempt instead of starting another login. If it expired, offer a new login.
 
-If a pending login's approval URL or code is unavailable, ask before recovering it. Explain that recovery may finish an already-approved login. After confirmation, run `npx @usestatemachines/cli@0.1.1 login --resume --json --stream` with the same profile and API origin. Keep that process running and show its URL and code. Request approval only for a recognized login. Wait for `signed-in` before continuing setup. Do not start another login or resume process. If streaming output is unavailable, report the blocker without reading credential files.
+If a pending login's approval URL or code is unavailable, ask before recovering it. Explain that recovery may finish an already-approved login. After confirmation, run `npx @usestatemachines/cli@0.1.4 login --resume --json --stream` with the same profile and API origin. Keep that process running and show its URL and code. Request approval only for a recognized login. Wait for `signed-in` before continuing setup. Do not start another login or resume process. If streaming output is unavailable, report the blocker without reading credential files.
 
-If a command returns `cli.not_linked`, run `npx @usestatemachines/cli@0.1.1 workspaces list --json`. Ask the user which workspace to use when there is more than one. Run `npx @usestatemachines/cli@0.1.1 link --workspace <workspace-id> --json` with the selected ID.
+If a command returns `cli.not_linked`, run `npx @usestatemachines/cli@0.1.4 workspaces list --json`. Ask the user which workspace to use when there is more than one. Run `npx @usestatemachines/cli@0.1.4 link --workspace <workspace-id> --json` with the selected ID.
 
-Run the user's existing command with `npx @usestatemachines/cli@0.1.1 run -- <command>`. The child receives a workspace key. The CLI keeps the credential out of its output.
+Run the user's existing command with `npx @usestatemachines/cli@0.1.4 run -- <command>`. The child receives a workspace key. The CLI keeps the credential out of its output.
 
 If access is denied, the API origin differs, or the workspace differs from the task, report the blocker. Do not invite or remove members, or change permissions.
 
@@ -35,7 +35,7 @@ Never print, log or commit API keys, `credentials.token`, the `headers` of `cred
 
 Apply the rest of this skill once the user has chosen a task. `sm.apps.list()` returns app IDs and each app's `defaultVersionId`. Every list returns `{ data, nextCursor }`. Follow cursors until you find the entry or `nextCursor` is null.
 
-Read the app's default version from `sm.apps.versions(appId)` before you write code. It is the current guidance for that app. Each of its `services` has an `id`, a `visibility`, `limitations` and a `prompt`, and a service that serves MCP lists its `servers` with their `tools`. Its `actors` are the app's users, each with an `id`, a `name` and a `summary`. Check the `limitations` against the behavior under test, as [known differences](https://app.usestatemachines.com/docs/apps/known-differences.md) does for Salesforce. A replica does not import a customer's data or run arbitrary customer automation.
+Read the app's default version from `sm.apps.versions(appId)` before you write code. It is the current guidance for that app. Each of its `services` has an `id`, a `visibility`, `limitations` and a `prompt`, and a service that serves MCP lists its `servers` with their `tools`. Its `actors` are users of the app's seed, for display. They do not say who can act. Check the `limitations` against the behavior under test, as [known differences](https://app.usestatemachines.com/docs/apps/known-differences.md) does for Salesforce. A replica never calls the vendor and does not run arbitrary customer automation. An environment holds a customer's org data only when it starts from a snapshot created from an import of that data.
 
 - Salesforce: the `api` service serves REST, Bulk API 2.0 and SOAP. Its `mcp` service is `preview`.
 - Box: the `api` service serves the Box Platform API, uploads and OAuth. Its `mcp` service is `preview`.
@@ -45,18 +45,38 @@ Read the app's default version from `sm.apps.versions(appId)` before you write c
 
 Create only the apps the task needs. A string such as `'linear'` is both the app ID and the app's name in the environment. Use `{ appId, name, setup, services }` to choose a name, run two copies of one app, pass `setup`, or configure a service. For example, `services` sets which MCP servers and tools the `mcp` service serves. Later calls take the name. Set `tokenInUrl: true` only for a client that cannot send headers.
 
-`env.connect(name)` acts as the app's default actor and lists each `public` service. Pass `{ services: ['mcp'] }` to also list a `preview` service. To act as another user, pass an `actorId` from the `actors` of the exact version that `env.apps` names for the app. Never use a role label, a workspace member ID, or the first version in a list.
+`env.connect(name)` acts as the app's default user and lists each `public` service. Pass `{ services: ['mcp'] }` to also list a `preview` service. To act as another user of the app, pass `as` with the user's email, username or ID, such as `env.connect('salesforce', { as: 'alice.park@acme.example' })`. Any user who can sign in to the running app can act, including a user that the test created. `credentials.actor` names the user that the credentials act as. Never pass a role label or a workspace member ID.
 
+- `env.actors(name, { search })` pages through the users who can act, the default user first. Use it to find a user when the task does not name one by email, username or ID.
+- `env.connectAll({ as })` connects to every app of the environment as one person. Its `credentials` hold each app that lets the user act, by app name. Its `errors` hold the `ActorNotFoundError` or `ActorCannotSignInError` of each other app. Any other error throws.
+- A user that the app does not have throws `ActorNotFoundError`, and `err.nearest` lists the nearest users who can act. A user that the app does not let sign in now, such as an inactive user, throws `ActorCannotSignInError`.
 - `credentials.fetch(path)` calls the `api` service with its headers and never follows redirects. It throws when the credentials list no `api` service, as for Linear.
 - For MCP, `credentials.service('mcp').servers` lists the MCP servers, and `.server(name)` returns one server's `url` and `headers` to give the MCP client.
 - An external client must send a service's `headers` only to that service's `url`, with redirects off. For Salesforce SOAP, put the actor token in `SessionHeader/sessionId`. See [credentials](https://app.usestatemachines.com/docs/environments/credentials.md).
-- On a `tokenInUrl` environment, a Salesforce or Box MCP request without an `Authorization` header acts as the default actor. To act as `actorId`, send the service's headers. Linear refuses an MCP request without them, so a Linear MCP client always sends the `mcp` service's headers.
+- On a `tokenInUrl` environment, an MCP request without an `Authorization` header acts as the app's default user. To act as the user of the credentials, send the service's headers.
 
 Point the existing integration's test transport at these URLs and credentials. If that needs a broader change, explain it before you expand the task.
 
+## Use an app in a browser
+
+Use a browser only when the task needs an app's UI. Each entry of `env.apps` lists the app's UI in `browserServices`, with each service's `id` and the `documents` routes that a session can open first. Linear's `ui` service is one. A UI session signs one browser in to the service as one actor.
+
+1. Create the environment with `{ wait: false }` and keep its ID. `open` waits for `running`, so you do not need to wait first.
+2. Start `npx @usestatemachines/cli@0.1.4 open <environment-id> --json` in the background. It opens the only app with a browser service, and that app's only browser service. When the environment has more, name the app as the second argument and the service with `--service`. `--actor` takes a user as `connect --actor` does.
+3. Read the line `Open http://127.0.0.1:<port>/<token> in the browser ...` from the command's stderr. While the environment starts, the line `Waiting for <environment-id> to run (now starting).` comes first. If the environment fails or is deleted first, the command fails and prints no link. Open that URL in your browser tool before you do anything else. The command launches the session only when the browser opens the URL, and the browser then loads the app as the actor.
+4. Use the app in that browser tab. The command exits once the browser opened the link, and its JSON result names the session, the actor, the path that it opened and when the session expires.
+5. Read each write back through the app's MCP server or API with `env.connect`. Do not trust the page alone.
+6. Delete the environment. The session ends with it.
+
+The link works once. While the command runs, a second visit shows that the link was used. After the command exits, the link no longer answers. Run `open` again for a new link. The session's grant lives for a short time, which is why the command launches the session only when the browser opens the link. If no browser opens the link within the `--timeout` seconds, the command fails with `cli.wait_timeout`.
+
+A page titled `Access required` or `Open this app again` means that the session ended. Run `open` again for a new link. If `open` then fails because the environment is deleted, create a new environment.
+
+To open one record, pass its URL to `--path`. MCP tools return the vendor's URLs, such as `https://linear.app/<workspace>/issue/<id>/<slug>` for a Linear issue, and the replica serves the same paths. The command keeps the URL's path and query and opens them in the replica. A vendor URL that you open as it is goes to the vendor, not to the replica. Without `--path`, the command opens the service's first route without parameters. The API refuses a path that matches none of the service's `documents` routes.
+
 ## Seed your own data
 
-Create the data a test reads before the test runs. Write it through the app's own API or MCP tools as the actor that owns it: Salesforce REST, composite or Bulk API 2.0, Linear MCP create tools, or Box uploads. A Linear workspace starts with one team and no issues. Use `setup` only for identity and configuration. To reuse seeded data, save it with `env.snapshots.create({ name })`, then create each test's environment from `{ snapshotId }`. See [isolated tests](https://app.usestatemachines.com/docs/sdk-api/testing.md).
+Create the data a test reads before the test runs. Write it through the app's own API or MCP tools as the actor that owns it: Salesforce REST, composite or Bulk API 2.0, Linear MCP create tools, or Box uploads. A Linear workspace starts with one team and no issues. Use `setup` only for identity and configuration. To start from records, users and files that you write in one file, build a snapshot from an import, as [build a snapshot from an import](https://app.usestatemachines.com/docs/snapshots/import.md) shows. To reuse seeded data, save it with `env.snapshots.create({ name })`, then create each test's environment from `{ snapshotId }`. See [isolated tests](https://app.usestatemachines.com/docs/sdk-api/testing.md).
 
 ## Verify the result
 
@@ -74,7 +94,7 @@ When `sm.me().limits` is non-null, it gives the cap on concurrent environments a
 
 ## Optional connection check
 
-Run this only when the user asks to verify the connection. It proves the connection and cleanup, not an existing integration's behavior. Save it in the project's examples or test location. Use the existing TypeScript runner and secret loader, or pass that runner through `npx @usestatemachines/cli@0.1.1 run -- <command>`. For an empty Node.js project, save `state-quickstart.mts` and run `npx @usestatemachines/cli@0.1.1 run -- npx tsx state-quickstart.mts`.
+Run this only when the user asks to verify the connection. It proves the connection and cleanup, not an existing integration's behavior. Save it in the project's examples or test location. Use the existing TypeScript runner and secret loader, or pass that runner through `npx @usestatemachines/cli@0.1.4 run -- <command>`. For an empty Node.js project, save `state-quickstart.mts` and run `npx @usestatemachines/cli@0.1.4 run -- npx tsx state-quickstart.mts`.
 
 ```ts
 import { StateMachines } from '@usestatemachines/sdk';
@@ -104,6 +124,8 @@ Management failures throw SDK errors. App HTTP failures are returned as `Respons
 | `unauthenticated` | The key is missing, expired or revoked. Fix the credential in the process that runs the task. |
 | `invalid_request` | Read `err.fields` and the installed method signature. |
 | `version_unavailable` | Discover the app ID and available versions. Stop if the required version is unavailable. |
+| `ActorNotFoundError` | The app has no user with that email, username or ID. Check `err.nearest` or `env.actors(appName, { search })`. Act as another user only when the task allows it. |
+| `ActorCannotSignInError` | The app does not let the user sign in now, for the reason in `err.fields.as`. Report it. Do not act as another user to make the test pass. |
 | `environment_limit_reached` | Clean up only this task's known leftovers, or report the capacity blocker. |
 | `EnvironmentFailedError` | Read `err.environment.failure.code`: `start_failed`, `pause_removed`, `version_unavailable`, `invalid_setup` or `invalid_services`. Clean up the owned environment. |
 | `WaitTimeoutError` or abort | Use the kept environment ID. A non-null `WaitTimeoutError.resource` also carries it. If neither an ID nor a replay key is available, report unresolved cleanup. Do not guess from a list. |