@north-light/cli 0.3.472 → 0.3.473

package/docs/apps/guides/typed-results.md

@@ -0,0 +1,72 @@
+---
+title: Typed results
+description: Start a run with a schema and get back a value that was checked against it.
+---
+
+# Typed results
+
+Pass an `output_schema` and call `runs.parse`. The runtime arms the schema on the run's root agent, which must submit a value that validates against it. The run settles with that value, and `runs.parse` returns it as `output_parsed`, typed from your schema.
+
+<include lang="ts">../../../examples/apps/runs-parse.ts</include>
+
+The runtime validates the value before it records it. A submission that does not match is refused with its field errors and never appears in `runs.get`, an event or a report, so the agent fixes it and resubmits.
+
+- `output_schema` accepts a plain JSON Schema object or anything with `toJSONSchema()`, such as a Zod v4 object. The SDK sends it as JSON and validates nothing itself.
+- A schema that is not an object, or is over 256 KB serialized, is refused with `invalid_request` and `param: 'output_schema'`, and no run is created. A submitted result can be at most 1 MiB.
+- The value is validated exactly as submitted, with no coercion: `"5"` is not turned into `5`.
+- A `$ref` can point only into the schema itself (`#/$defs/x`, `#anchor`) or at another schema document bundled under `$defs` with its own `$id`. Files are never fetched. A `$ref` that resolves nowhere, or a schema that cannot be compiled (a bad `pattern`), is refused with `invalid_request` and `param: 'output_schema'`.
+- The agent submits with its `submit_result` tool, which needs no scope, so a run that only reasons and answers can start with `scopes: ['crtr:llm']`.
+- The same value is in `runs.get(runId).result`, which `runs.wait` returns unchanged.
+
+Do not parse assistant text out of `runs.trace` to get data back. `runs.trace` is for showing a person the transcript.
+
+## A run that declines
+
+An agent that cannot honestly satisfy the schema declines. A decline, a cancel, a deadline and a runtime error all come back as an outcome. They do not throw. Narrow on `outcome.kind` and `outcome.reason`, as the example does.
+
+## Stopping without a result: `run_idle`
+
+`runs.parse` rejects with an `APIError` with code `run_idle` when the agent stopped without submitting. The runtime reminds the agent of the schema up to three times in a row, then leaves the run `idle` with the schema still armed. The run is untouched: send `runs.message` to nudge the agent (this resets the reminders), or end it with `runs.cancel`.
+
+A question from the run rejects with `waiting_on_user` unless you pass `onQuestion`. With `onQuestion`, `parse` answers each open question once and keeps waiting.
+
+## Bounding a run
+
+No run is bounded in time by default. Pass a `signal` to `runs.parse` or `runs.wait`. When it aborts, the helper rejects with the signal's reason and leaves the run alone. Call `runs.cancel` if you want the run ended:
+
+```ts
+const controller = new AbortController();
+const timer = setTimeout(() => controller.abort(new Error('took too long')), 10 * 60_000);
+let runId: string | undefined;
+try {
+  const started = await runtime.runs.start({prompt, output_schema: Profile});
+  runId = started.run_id;
+  const run = await runtime.runs.wait(runId, {signal: controller.signal});
+  // read run.status, run.outcome, run.result
+} catch (error) {
+  if (controller.signal.aborted && runId) await runtime.runs.cancel(runId);
+  throw error;
+} finally {
+  clearTimeout(timer);
+}
+```
+
+## Showing progress
+
+For a run you poll, `runs.get(runId).activity` is `null` unless `status` is `running`, and otherwise says what the root agent is doing:
+
+| `phase` | The root agent is |
+|---|---|
+| `starting` | launching; its first turn has not begun |
+| `thinking` | reasoning, or waiting on the model before any output |
+| `tool` | calling a tool: `tool.name`, and `tool.summary` (`null` while the call is still being written) |
+| `submitting_result` | writing or recording its `output_schema` result |
+| `writing` | streaming its answer text |
+| `between_turns` | between turns while the run still works |
+
+```ts
+const run = await runtime.runs.get(runId);
+const badge = run.activity?.phase === 'tool' ? `Running ${run.activity.tool.name}` : run.activity?.phase ?? run.status;
+```
+
+`activity` covers the root agent only, and it is read each time you call `runs.get`, so a phase shorter than your poll interval can be missed. To show text as it streams, follow the events instead: see [Stream a run](/docs/guides/stream-a-run). To be told when a background run ends, see [Background runs](/docs/guides/background-runs).

package/docs/apps/how-it-fits.md

@@ -0,0 +1,46 @@
+---
+title: Where your app runs
+description: Your app runs on your server, people sign in at account.northlight.ai, and the agent work runs on each person's own Northlight runtime. Northlight does not host your app's code.
+---
+
+# Where your app runs
+
+Your app runs on a server you choose. Northlight hosts two other things: the directory at `account.northlight.ai`, and each person's agent runtime. Northlight does not host your app's code, and there is no flow for deploying it to Northlight.
+
+| Piece | Runs where | What it does |
+|---|---|---|
+| **Your server** | Anywhere you choose. Your laptop while you develop. | Your pages and logic. It holds the app's private signing key and a stored connection for each person. |
+| **The directory** | `https://account.northlight.ai`, hosted by Northlight | Accounts, app registration (the console at `/console`), consent, tokens and the marketplace. |
+| **The person's runtime** | Hosted by Northlight, one per person | Their agents, runs, files, documents and providers (sms, search and others), using their own AI subscription. |
+
+"Build on Northlight" therefore means three things. Your app's agent work runs on the person's Northlight-hosted runtime. People sign in to your app with their Northlight account. And your app can be listed in the Northlight marketplace.
+
+```mermaid
+sequenceDiagram
+  participant P as Person's browser
+  participant A as Your server
+  participant D as account.northlight.ai
+  participant R as Person's runtime
+  P->>A: GET /auth/login
+  A->>P: redirect to the directory (client ID, scopes, PKCE challenge)
+  P->>D: sign in, consent
+  D->>P: redirect to your /auth/callback with a code
+  P->>A: GET /auth/callback?code=…
+  A->>D: exchange the code, signed with your private key
+  D->>A: access token, refresh token, runtime URL
+  Note over A: store the connection for this person
+  A->>R: oauth.client(userId).runs.start(…)
+  R->>A: the run, its status and its result
+```
+
+1. **Sign-in.** Your `/auth/login` route sends the person to the directory with your client ID and the scopes you ask for. The directory shows its consent page and returns them to your registered redirect URI with a one-use code.
+2. **Token.** Your server exchanges the code for tokens. It proves it is your app by signing the request with its private key. No client secret exists. The result is a connection: a short-lived access token, a rotating refresh token, and the URL of that person's runtime. See [Apps and sign-in](/docs/concepts/apps-and-sign-in).
+3. **Calls.** `oauth.client(userId)` loads the stored connection, refreshes the access token when it needs to, and returns a client on that person's runtime. You call `runs.*` and `providers.*` on it. See [Connections](/docs/concepts/connections) and [Runs](/docs/concepts/runs).
+
+The person's AI subscription pays for model calls, and what your app may do on their runtime is limited by the scopes they approved. See [Scopes and grants](/docs/concepts/scopes-and-grants).
+
+## What you operate
+
+You operate your server, its sessions, its database and its `ConnectionStore`. You register the app in the console and keep its key pair. Northlight operates the directory and the runtimes; you do not run either, and there is no local Northlight to start. If you run crouter yourself and want a runtime of your own, that is a different path: see [crouter.docs.northlight.ai](https://crouter.docs.northlight.ai).
+
+The directory's discovery document at `https://account.northlight.ai/.well-known/openid-configuration` lists the endpoints, the `S256` PKCE method and `private_key_jwt` as the only token authentication method (checked on production).

package/docs/apps/providers/README.md

@@ -0,0 +1,26 @@
+---
+title: Providers
+description: The first-party providers an app can call on a person's runtime, their ids, how scope strings are named, and how to list a provider's tools.
+---
+
+# Providers
+
+A provider is a service the person's runtime calls for your app. Your app asks the runtime with `runtime.providers.call(...)`, and the runtime checks that the person approved the provider's scope for your app. See [Providers](/docs/concepts/providers) for the model.
+
+| Provider id | What it does | Scopes | Page |
+|---|---|---|---|
+| `sms` | Texts the signed-in person's own verified phone | `sms:send`, `sms:status` | [Texting (sms)](/docs/providers/sms) |
+| `search` | Web search, sourced answers, page contents and paid data endpoints | `search:<group>` | [Search](/docs/providers/search) |
+| `integrations` | The person's own accounts at other services | `integrations:discover`, `integrations:<service>_read`, `integrations:<service>_write` | [Integrations](/docs/providers/integrations) |
+| `context` | Ask about the person from their memory, and look up public profiles | `context:<group>` | [Context](/docs/providers/context) |
+| `device` | The person's Mac: browser, files, Messages and shell | `device:<group>` | [Device](/docs/providers/device) |
+
+## Where names come from
+
+- **Scope strings** come from the console's **What it asks for → Add permissions** list. A scope is `<provider id>:<group>`. Do not guess them.
+- **Tool names and arguments** come from `runtime.providers.tools('<provider id>')`. It answers the provider's groups, and each group's tools with a description, parameters and output. It lists only the groups your app's grant holds, so ask for the scope first, then list.
+- **Required providers.** If your app does not work without a provider being set up first, add it under **What your app requires** in the console. See [Grant changes](/docs/guides/grant-changes#wait-on-a-provider-your-app-requires).
+
+<include lang="ts">../../../examples/apps/provider-tools.ts</include>
+
+Each provider page below shows the tools of a provider as captured on **2026-10-16**. The capture is not an app's view: it came from the runtime of a person's own Northlight account (`GET /v1/providers/<id>/tools` on `crtr` 0.3.462, joined to production), which shows the groups that person's own grant holds. What `providers.tools` answers for your app depends on the scopes your app was granted. Tools can change between releases, so treat a table as a starting point and list the tools at run time.

package/docs/apps/providers/context.md

@@ -0,0 +1,32 @@
+---
+title: Context
+description: Ask about the person from their memory, and look up public profiles, through the context provider.
+---
+
+# Context
+
+The `context` provider answers questions about the person from what their agent knows, and looks up public profiles.
+
+## Scopes and setup
+
+Scopes are `context:<group>`. The console's **Add permissions** list shows `context:ask_informed` and `context:ask_public` on 2026-10-16; the tool list also shows a `research` group (`context:research`) that was not in that console list when we checked (not yet checked on production).
+
+Context needs setup before it works: the person gives a profile URL on the provider's setup page, and its state stays `pending` for a few minutes afterwards. If your app depends on it, add `context` under **What your app requires** and follow the state with `grant.get().dependencies['context']`. See [Grant changes](/docs/guides/grant-changes#wait-on-a-provider-your-app-requires).
+
+## Tools
+
+Captured 2026-10-16 from `GET /v1/providers/context/tools` on a joined runtime (provider major version 1). `*` marks a required parameter. Tool names with a space are written as the provider lists them; check how to pass a multi-word `tool` to `providers.call` against your own `providers.tools` output before relying on it (not yet checked on production).
+
+| Tool | Group | Parameters | What it does |
+|---|---|---|---|
+| `ask informed` | `ask_informed` | `request`\*, `question` (repeatable, up to 10) | Advice about the person shaped by everything their agent knows, private memories included, without being told private details |
+| `ask public` | `ask_public` | `request`\*, `question` (repeatable, up to 10) | Answers about the person from public memories only |
+| `linkedin profile` | `research` | `profile`\* | A person's LinkedIn profile |
+| `linkedin posts` | `research` | `profile`\*, `limit` | Recent LinkedIn posts |
+| `x profile` | `research` | `profile`\* | A person's X profile |
+| `x posts` | `research` | `profile`\*, `limit` | Not available |
+| `github profile` | `research` | `profile`\* | A person's GitHub profile |
+| `github repos` | `research` | `profile`\*, `limit` | Public repositories |
+| `search people` | `research` | `query`\* | Search LinkedIn people |
+
+`request` is the task you are doing, 1 to 4000 characters. Each `question` is 1 to 500 characters. Run `runtime.providers.tools('context')` for the current list and each tool's output shape.

package/docs/apps/providers/device.md

@@ -0,0 +1,26 @@
+---
+title: Device
+description: "Reach the person's Mac from your app: browser, files, Messages and shell, each behind its own scope."
+---
+
+# Device
+
+The `device` provider reaches the person's own Mac. Its tools run on the person's machine (the provider's transport is `machine`), and each group is its own scope, so ask only for the groups your app needs. What happens when the Mac is asleep or offline is not yet checked on production.
+
+## Scopes
+
+`device:browser`, `device:files`, `device:messages_read`, `device:messages_send` and `device:shell`. Add them under **What it asks for → Add permissions** (provider `device`).
+
+## Tools
+
+Captured 2026-10-16 from `GET /v1/providers/device/tools` on a joined runtime (provider major version 2, transport `machine`). `*` marks a required parameter.
+
+| Group (scope) | Tools |
+|---|---|
+| `browser` | `browser profiles`, `browser executor create` (`url`, `mode`, `profile`, `target-pattern`), `browser executor list`, `browser executor navigate` (`executor`\*, `url`\*), `browser executor exec` (`executor`\*, `code`\*, `timeout-ms`, `short-description`), `browser executor result` (`run`\*), `browser executor close` (`executor`\*), `browser libs` (`query`, `limit`, `service`, `fn`), `browser cdp` (`method`\*, `params`, `tab`) |
+| `files` | `files list` (`path`\*, `limit`), `files stat` (`path`\*), `files read` (`path`\*, `encoding`, `offset`, `length`), `files write` (`path`\*, `text`, `base64`, `from`, `append`, `parents`), `files delete` (`path`\*, `recursive`), `files move` (`from`\*, `to`\*, `overwrite`), `files mkdir` (`path`\*) |
+| `messages_read` | `messages chats` (`limit`), `messages history` (`chat`, `participant`, `since`, `until`, `limit`, `attachments`), `messages search` (`text`\*, `limit`), `messages contacts` (`query`\*, `limit`), `messages permissions` (`open`) |
+| `messages_send` | `messages send` (`recipient`\*, `text`\*, `file`, `service`) |
+| `shell` | `shell run` (`command`\*, `cwd`, `timeout`, `stdin`) |
+
+Tool names with spaces are written as the provider lists them; check how to pass them to `providers.call` against your own `providers.tools` output (not yet checked on production). The capture is of a person's own grant, not an app's. Run `runtime.providers.tools('device')` for the list your app can use.

package/docs/apps/providers/integrations.md

@@ -0,0 +1,26 @@
+---
+title: Integrations
+description: Call the person's own accounts at other services through the integrations provider, and find the tool you need.
+---
+
+# Integrations
+
+The `integrations` provider lets your app act in the person's own accounts at other services, with the person's consent for each service.
+
+## Scopes
+
+- `integrations:discover` allows `search` and `schema`, which find services and their tools, and the `link` group's `accounts`, which lists the person's linked accounts.
+- `integrations:<service>_read` and `integrations:<service>_write` gate each service's tools. For example, a service named `gmail` has `integrations:gmail_read` and `integrations:gmail_write`.
+
+Scope strings come from **What it asks for → Add permissions** (provider `integrations`). The catalog is large, so search it by service name.
+
+## Find the tool you need
+
+The provider has thousands of tools: on 2026-10-16 the runtime we captured from listed 3,061 tools across 3,060 groups, one `_read` group and one `_write` group per service, plus `discover` and `link`. This page does not table them. List them from your app:
+
+```ts
+const integrations = await runtime.providers.tools('integrations');
+for (const group of integrations.groups) console.log(group.group, group.leaves.map((leaf) => leaf.tool));
+```
+
+`providers.tools('integrations')` is large (several megabytes on that runtime), and it lists only groups your app's grant holds, so it stays small until you add service scopes. To find a service or a tool, call the provider's `search` and `schema` tools (group `discover`) instead of reading the whole list.

package/docs/apps/providers/search.md

@@ -0,0 +1,29 @@
+---
+title: Search
+description: Web search, sourced answers, page contents, and paid data endpoints through the search provider.
+---
+
+# Search
+
+The `search` provider runs web search and returns ranked pages, sourced answers, page contents and deep research, and it finds and calls paid data endpoints.
+
+## Scopes
+
+Each scope is `search:<group>`: `search:search`, `search:answer`, `search:contents`, `search:discover`, `search:research` and `search:run`. Add them under **What it asks for → Add permissions** (provider `search`). A tool is available when your app holds its group's scope.
+
+## Tools
+
+Captured 2026-10-16 from `GET /v1/providers/search/tools` on a joined runtime (provider major version 1). `*` marks a required parameter.
+
+| Tool | Group (scope) | Parameters | What it does |
+|---|---|---|---|
+| `search` | `search` | `query`\*, `type`, `category`, `num-results`, `start-published-date`, `end-published-date`, `include-domains`, `exclude-domains`, `no-text` | Ranked web pages |
+| `answer` | `answer` | `query`\*, `structured` | A sourced answer |
+| `contents` | `contents` | `urls`\*, `no-text`, `highlights`, `summary`, `livecrawl` | Contents of known pages |
+| `research` | `research` | `query`\*, `depth` | Deep web research |
+| `discover` | `discover` | `query`\*, `limit`, `min-score` | Matching data endpoints and prices |
+| `inspect` | `discover` | `provider`\*, `endpoint`\* | Data endpoint details and price |
+| `run` | `run` | `provider`\*, `endpoint`\*, `input`\* | A paid data result, or a pending run ID |
+| `status` | `run` | `run-id`\* | State and result of a data run |
+
+The capture is of a person's own grant, not an app's. Run `runtime.providers.tools('search')` for what your app's grant holds. A call is billed to the person under your app's spend cap ([Grant changes](/docs/guides/grant-changes#show-what-a-persons-month-has-cost)).

package/docs/apps/providers/sms.md

@@ -0,0 +1,37 @@
+---
+title: Texting (sms)
+description: Text the signed-in person's own verified phone from your app with the sms provider.
+---
+
+# Texting (sms)
+
+The `sms` provider sends a text from Northlight's number to the verified phone of the person who signed in to your app. It has no recipient argument, so an app cannot text anyone else.
+
+## Scopes
+
+| Scope | Consent sentence | Gates |
+|---|---|---|
+| `sms:send` | Send you text messages from Northlight's number | `send`, `react` |
+| `sms:status` | Not captured | `status` |
+
+Add them under **What it asks for → Add permissions** (provider `sms`). Without `sms:send` the consent page does not offer it and `providers.call` for `sms` is refused with `scope_missing`.
+
+## Send a text
+
+```ts
+await runtime.providers.call({provider: 'sms', tool: 'send', arguments: {body: 'Your summary is ready.'}});
+```
+
+`body` is required. The text goes from Northlight's number to the person's verified phone, and each person can receive at most 50 texts from your app per UTC day. These limits are the provider's documented behavior (the 50-per-day limit is not yet checked on production).
+
+## Tools
+
+Captured 2026-10-16 from `GET /v1/providers/sms/tools` on a joined runtime (provider major version 1). `*` marks a required parameter.
+
+| Tool | Group (scope) | Parameters | What it does |
+|---|---|---|---|
+| `send` | `send` (`sms:send`) | `body`\*, `file`, `reply-to` | Send a text to your verified phone. `file` is a signed URL of at most 5 MiB sent after the text. `reply-to` is the label of a message in the conversation, such as `m3`, to send a threaded reply. Answers `message_id`. |
+| `react` | `send` (`sms:send`) | `label`\*, `emoji`\* | React to a text in the conversation with a tapback or any emoji. |
+| `status` | `status` (`sms:status`) | `message-id`\* | Check the delivery state of a text. |
+
+Parameter names are the provider's own. In a `providers.call`, `arguments` is an object keyed by those names, such as `{body, file}`. Run `runtime.providers.tools('sms')` for the current list.

package/docs/apps/quickstart.md

@@ -1,8 +1,126 @@
 ---
 title: Quick setup
-description: Register an app, sign a person in with Northlight, and start a run on their runtime.
+description: From no account to a running app that signs a person in with Northlight, starts a run on their runtime and sends them a text.
 ---
 
 # Quick setup
 
-This page is a placeholder. The quick setup path is written in a later change.
+```bash
+npx @north-light/sdk@latest init my-app
+```
+
+This command creates a small Node server, a signing key and an env file. About ten minutes later you have an app on your laptop that signs you in with Northlight, starts an agent run on your own Northlight runtime, and texts your phone. The app runs on your machine and talks to Northlight's production directory at `https://account.northlight.ai`. There is no local Northlight stack to run, and you do not need crouter.
+
+You need Node.js 22.19 or later and a phone that can receive iMessage.
+
+Using a coding agent? Run the same `init` command, or tell your agent: *Read https://sdk.docs.northlight.ai/SKILL.md and follow it.* See [Use your coding agent](/docs/coding-agents).
+
+Each step below ends with what you should see when it worked. A step marked "(not yet checked on production)" is written from the source code and has not been run end to end against `account.northlight.ai`.
+
+## 1. Create an account
+
+Open `https://account.northlight.ai/signup` and create your account. Signup texts a confirmation code to your phone, and that text is sent over iMessage. A number that cannot receive iMessage gets "We couldn't send the text", and retrying does not help. One phone number belongs to one account.
+
+You should see: your account's page after you enter the code. Opening `https://account.northlight.ai/console` while signed in shows the console, where your apps are listed. Checked on production: `/signup` redirects to the phone step at `/signup/phone`, and `/console` while signed out redirects to sign-in. Completing signup and the signed-in console are not yet checked on production.
+
+## 2. Scaffold the app
+
+```bash
+npx @north-light/sdk@latest init my-app
+cd my-app
+```
+
+`init` writes these files into `my-app/`:
+
+| File | What it is |
+|---|---|
+| `package.json` | Pins `@north-light/sdk` to the exact version of the CLI you ran, and adds `tsx`. |
+| `server.ts` | The server shown at the end of this page. |
+| `local/app-key.json` | Your app's private signing key, mode `0600`. Never commit it or paste it anywhere. |
+| `local/app.env` | The settings the server reads: `CROUTER_ISSUER`, `APP_ORIGIN`, an empty `CROUTER_CLIENT_ID=` and `CROUTER_KEY_FILE`. |
+| `.gitignore` | Keeps `local/` and `node_modules/` out of git. |
+| `.agents/skills/northlight/SKILL.md` and `.claude/skills/northlight/SKILL.md` | The Northlight skill for your coding agent. |
+
+You should see, on the terminal: `Created a Northlight app in my-app:` with the file names, the path of the private key, the next steps in order, and last, on its own line, the **public key** as one line of JSON:
+
+```json
+{"kty":"EC","x":"…","y":"…","crv":"P-256","kid":"…","alg":"ES256","use":"sig"}
+```
+
+Copy that line. You paste it into the console in the next step. If a file already exists, `init` refuses, names it and exits non-zero without writing anything.
+
+Checked: this output and these files, from the SDK source built on this branch in an empty directory with no crtr on `PATH`. `npx @north-light/sdk@latest` fetches the npm `latest` release, and that release does not include `init` until the site goes live (not yet checked on production).
+
+## 3. Register the app in the console
+
+Open `https://account.northlight.ai/console/new`. The page is titled **Register an app**. Fill in:
+
+| Field | Value |
+|---|---|
+| **Name** | Shown to people on the consent page and in their account. |
+| **Origin URL** | `http://localhost:3000` |
+| **Logo URL** | Required. A square image shown beside your app's name. |
+| **Why your app needs access** | One sentence. It is quoted on the consent page as your words. |
+| **Redirect URIs** | `http://localhost:3000/auth/callback`, one URL per line. Sign-in returns only to a URI listed here, matched exactly. `localhost` and `127.0.0.1` are different URIs, and the port counts. |
+| **Public key (optional)** | The JSON line `init` printed. |
+
+Choose **Register app**.
+
+You should see: a page titled "*your app's name* is registered" with a **Client ID** and, under it, the key ID of the key you pasted. Copy the client ID. If it says "Next: add your app's public key on the Sign-in tab", the key was left out: open the app's **Sign-in** tab and choose **Add key**. The app starts asking for `crtr:llm` and `crtr:act`.
+
+The field labels are from the console's source. Pasting a key at registration is not yet checked on production.
+
+## 4. Add the permission to text
+
+On the app's page, open the **What it asks for** tab and choose **Add permissions**. Add `sms:send` from the list.
+
+You should see: `sms:send` under what your app asks for, next to `crtr:llm` and `crtr:act`. The server in this guide asks for all three, so without `sms:send` the consent page does not offer it and the text in step 6 is refused. Take scope strings from this list. Do not invent them. See [Scopes and grants](/docs/concepts/scopes-and-grants).
+
+Not yet checked on production.
+
+## 5. Write the client ID into the env file
+
+```bash
+npx @north-light/sdk env --client-id <client id>
+```
+
+You should see:
+
+```text
+Set in local/app.env:
+  CROUTER_ISSUER=https://account.northlight.ai
+  CROUTER_CLIENT_ID=<client id>
+  APP_ORIGIN=http://localhost:3000
+Key file: local/app-key.json (set CROUTER_KEY_FILE to change it).
+```
+
+`local/app.env` now has all four settings. The command makes no network call and keeps every other line in the file. Add `--origin <url>` if your app does not run on `http://localhost:3000`.
+
+Checked from the SDK source built on this branch.
+
+## 6. Run it
+
+```bash
+npm i
+node --env-file=local/app.env --import tsx server.ts
+```
+
+(`npm start` runs the same command.) You should see `Listening on http://localhost:3000`.
+
+Open `http://localhost:3000/auth/login`. Your browser goes to `account.northlight.ai`. Sign in if asked, read the consent page, and choose Allow. You land back on `http://localhost:3000/` with "Signed in" and your Northlight user id. Press **Start a run and send me a text**. The page answers "Done", shows the run's status `idle`, and your phone receives "Hello from my first Northlight app." from Northlight's number.
+
+What was checked: the server starts, `/` shows the sign-in link, and `/auth/login` answers `303` to `https://account.northlight.ai/authorize?client_id=…&scope=openid+profile+crtr%3Allm+crtr%3Aact+sms%3Asend…&code_challenge_method=S256…`. The consent page, the callback, the run and the text are not yet checked on production.
+
+If `/` shows "One step left", `CROUTER_CLIENT_ID` is empty: repeat step 5 and restart. If a call fails with `426 runtime_version_unsupported`, your SDK is newer than the Northlight runtimes. Install the previous version with `npm i --save-exact @north-light/sdk@<version>` and tell support@northlight.ai.
+
+## 7. What next
+
+- Only you can sign in until you add testers: see [Testing mode](/docs/concepts/testing-mode).
+- Keep each person's sign-in across restarts and processes: see [Connections](/docs/concepts/connections).
+- See what `server.ts` does and where each piece runs: [Where your app runs](/docs/how-it-fits).
+
+## The server `init` writes
+
+This is `examples/apps/quickstart-server.ts`. The SDK reads no environment: the server passes the values in.
+
+<include lang="ts">../../examples/apps/quickstart-server.ts</include>

package/docs/sdk/README.md

@@ -82,7 +82,7 @@ The directory rejects the key until its public JWK is added to the app. To chang
 | [Errors](./errors.md) | The error class table and the retry policy |
 | [Docker environment](./docker.md) | `start()`, `attach()`, `connection()` from `@north-light/env-docker` |
 | [Testing your app](./testing.md) | `FakeCloud` from `@north-light/sdk/testing`: a fake directory and runtime your real `OAuth2Client` and `Crouter` talk to through `fetch` |
-| [Release notes](./release-notes.md) | Behavior changes an existing app must act on, newest first |
+| [Release notes](https://sdk.docs.northlight.ai/docs/release-notes) | Behavior changes an existing app must act on, newest first |
 | [Apps on Northlight](./guides/apps-on-northlight.md) | Building and registering an app against production (joining a laptop, `crtr cloud apps` registration, keys, env file, scopes, running locally, the `crtr cloud apps` commands); typed results from app runs with `runs.parse`, declines, bounding a run, `run_idle`, and waiting on a provider your app requires |
 | [Apps with many users](./guides/apps-with-many-users.md) | Per-person runtime connections, app-owned user access, privacy, and spending |
 

package/docs/sdk/errors.md

@@ -24,7 +24,7 @@ Every class below extends `APIError`, which carries `status`, `code`, `message`,
 | Condition | Class |
 |---|---|
 | SDK configuration error | `CrouterError` with `status: 0`, `code: 'crouter_error'` |
-| The runtime does not serve the contract level the SDK requires, or names none. The hosting router or the runtime refuses this *before* handling (the SDK sends `Crouter-Required-Contract` and a frozen `Crouter-Minimum-Runtime-Version`): nothing was accepted and no idempotency key was recorded. A runtime that predates the contract level handles the request first, and the SDK then raises after | `RuntimeVersionError` with `status: 426`, `code: 'runtime_version_unsupported'`; `requiredContract` and `runtimeContract` (or `null`) name both levels, `sdkVersion` and `runtimeVersion` stay for logging, and it is never retryable. A level is `MAJOR.MINOR`; the runtime satisfies it when it serves the same major and a minor at or above. See [Release notes](./release-notes.md) |
+| The runtime does not serve the contract level the SDK requires, or names none. The hosting router or the runtime refuses this *before* handling (the SDK sends `Crouter-Required-Contract` and a frozen `Crouter-Minimum-Runtime-Version`): nothing was accepted and no idempotency key was recorded. A runtime that predates the contract level handles the request first, and the SDK then raises after | `RuntimeVersionError` with `status: 426`, `code: 'runtime_version_unsupported'`; `requiredContract` and `runtimeContract` (or `null`) name both levels, `sdkVersion` and `runtimeVersion` stay for logging, and it is never retryable. A level is `MAJOR.MINOR`; the runtime satisfies it when it serves the same major and a minor at or above. See [Release notes](https://sdk.docs.northlight.ai/docs/release-notes) |
 | HTTP 400 | `BadRequestError` |
 | HTTP 401 | `AuthenticationError` |
 | HTTP 403 | `PermissionDeniedError` |

package/docs/sdk/getting-started.md

@@ -25,7 +25,7 @@ npm i --save-exact @north-light/sdk@0.3.451
 
 One dependency. It re-exports every data type you need, so you do not also install `@north-light/api`.
 
-`@latest` always works against production: a release reaches `latest` only once production serves its contract level. The `next` tag carries every release the moment it is published and may need a newer runtime than production runs (see [Errors](./errors.md) for `RuntimeVersionError`). Keep the exact pin: the compatibility gate protects the wire, not the TypeScript API. To move it, check `npm view @north-light/sdk dist-tags` and read the [release notes](./release-notes.md) first.
+`@latest` always works against production: a release reaches `latest` only once production serves its contract level. The `next` tag carries every release the moment it is published and may need a newer runtime than production runs (see [Errors](./errors.md) for `RuntimeVersionError`). Keep the exact pin: the compatibility gate protects the wire, not the TypeScript API. To move it, check `npm view @north-light/sdk dist-tags` and read the [release notes](https://sdk.docs.northlight.ai/docs/release-notes) first.
 
 ## 3. Node, on the owner's own daemon
 

package/docs/sdk/guides/apps-on-northlight.md

@@ -50,7 +50,7 @@ npm init -y
 npm i --save-exact @north-light/sdk@0.3.451
 ```
 
-`0.3.451` is the version this guide was last checked against on production. To move on purpose, run `npm view @north-light/sdk dist-tags`, read the [release notes](../release-notes.md) for the versions in between, and install the new exact version the same way.
+`0.3.451` is the version this guide was last checked against on production. To move on purpose, run `npm view @north-light/sdk dist-tags`, read the [release notes](https://sdk.docs.northlight.ai/docs/release-notes) for the versions in between, and install the new exact version the same way.
 
 Pin an exact version of `@north-light/sdk` rather than a range or `latest`. A compatibility gate between the SDK and Northlight's runtimes protects the wire, so an SDK that is too new for the runtime is refused cleanly. It does not protect the TypeScript API: a later SDK release can change a type or a method your code uses, and an unpinned install picks that up on its next `npm i`. 
 If a call fails with `426 runtime_version_unsupported`, the SDK is newer than the Northlight runtimes. This can happen briefly right after a new SDK release, until production runtimes are upgraded. Install the previous version or wait, and tell Northlight at support@northlight.ai.

package/docs/sdk/nodes.md

@@ -63,7 +63,7 @@ Wire fields are `snake_case`. Every `NodeCreateParams` property is optional; `pa
 | `description` | `string` | Display description. |
 | `parent` | node id | Graph placement. An external caller leaves this unset. |
 | `creator` | node id | Graph placement. An external caller leaves this unset. |
-| `scopes` | `string[]` | Per-run allow-list. Omit it to inherit every scope, or under a scoped token to receive that token's ceiling; a list outside the ceiling answers `403 scope_denied` with the offending scopes in `details.scopes`. Scopes are prefixed (`crtr:llm`, `crtr:act`, `crtr:schedule`, `crtr:memory:…`, `crtr:files:…`); `crtr:act` requires `crtr:llm`, and the list must stay inside what the creator's grant holds. Some scopes are recorded rather than enforced, per the `CreateNodeRequest` contract. See [scoped tokens](./getting-started.md#a-token-that-holds-less-than-the-owner). |
+| `scopes` | `string[]` | Per-run allow-list. Omit it to inherit every scope, or under a scoped token to receive that token's ceiling; a list outside the ceiling answers `403 scope_denied` with the offending scopes in `details.scopes`. Scopes are prefixed (`crtr:llm`, `crtr:act`, `crtr:schedule`, `crtr:memory:…`, `crtr:files:…`); `crtr:act` requires `crtr:llm`, and the list must stay inside what the creator's grant holds. Provider-group scopes (`device:messages_send`) are enforced on the broker route; on an unsandboxed host a same-UID process can bypass the list by calling the daemon socket directly, so it guards against a mistaken call, not a hostile node. Keep the list short: it travels in a request header on every device call. See [scoped tokens](./getting-started.md#a-token-that-holds-less-than-the-owner). |
 | `worktree` | `string \| boolean` | Create a managed git worktree for the run. |
 | `fork_from` | `string` | Start from an existing conversation. |
 | `no_kickoff` | `boolean` | Create the node without sending the first message. |