@north-light/cli 0.3.543 → 0.3.544

package/docs/apps/concepts/connections.md

@@ -117,7 +117,3 @@ It needs the app registered with the `app_token_for_user` operation, and an acti
 ## Signing in a visitor
 
 A person who only needs to be recognized, not connected, signs in with identity only: request `openid`, optionally with `email` and `profile`, and no runtime scope. Finish with `exchangeIdentity`, not `exchangeCode`. An `Identity` is not a connection: no runtime URL, grant or refresh token (if the directory answers with one anyway, `exchangeIdentity` revokes the refresh token), nothing goes in the store, and you keep your own session. To act for that person later, send them through `authorizeUrl` again with the runtime scopes you need.
-
-## Checked and not checked
-
-From the SDK source and tests. The refresh and refusal paths against `account.northlight.ai` are not yet checked on production.

package/docs/apps/concepts/providers.md

@@ -54,7 +54,3 @@ if (context?.state !== 'ready') {
 | `unavailable` | The provider does not offer this to the person's account. `message` says so; there is nothing for them to do. |
 
 `message` is the provider's own sentence, present for `pending`, `failed` and `unavailable`. `step` is present when the provider reports where things stand (for example `researching`); its values may grow, so ignore one you do not know. `next` is the absolute URL of the setup page for this provider and your app; `setupLink(dependency, {returnTo})` from `@north-light/sdk` adds a `return_to` with your app's registered origin so the person returns to you, and keeps the query `next` already carries. A key can contain a dot (`context.deep`). An entry is missing when the runtime has not synced the grant since the app began requiring the provider: treat that as `not_started`. The runtime does not block your calls for you, so refuse the dependent operation yourself. To act the moment a state turns `ready`, follow it with `oauth.watchGrants`; see [Grant changes](/docs/guides/grant-changes).
-
-## Checked and not checked
-
-From the SDK source (`providers.tools`, `providers.call`, `grant.get`) and the directory source. The sms limits come from the existing SDK guide. A real `providers.call` for `sms` on production returned a `message_id` for a text to the signed-in person. That the text arrived is not yet checked.

package/docs/apps/concepts/runs.md

@@ -88,7 +88,3 @@ try {
 ## Learn when a background run ends
 
 A run you start and do not wait on ends while nobody holds a request. `oauth.watchRuns(...)` follows those runs for you and calls `onEnded` for each one that comes to rest. See [Background runs](/docs/guides/background-runs).
-
-## Checked and not checked
-
-From the SDK source and its tests. On production, `runs.start` and `runs.wait` ran the quickstart's prompt and settled with status `idle`; the run's reply text and `activity` are not yet checked.

package/docs/apps/concepts/scopes-and-grants.md

@@ -56,7 +56,3 @@ A run's list must stay inside the grant, and a child agent never regains a scope
 ## Your app's own space
 
 Your app has its own space on each person's runtime: documents and files owned by your app. Your server and runs started without a `scopes` list read and write it freely. A run started with a `scopes` list needs `crtr:memory:read:app:<your client id>` or `crtr:memory:rw:app:<your client id>` to touch it. Another app's space is reachable only where that app allows it.
-
-## Checked and not checked
-
-From the SDK source, the directory console source and the existing SDK guide. `403 scope_missing` for a missing `crtr:act` and the consent page's behavior are not yet checked on production.

package/docs/apps/concepts/testing-mode.md

@@ -30,7 +30,3 @@ Email support@northlight.ai to have the app verified. Only Northlight staff can
 ## Test the refusal in code
 
 `@north-light/sdk/testing` has a fake directory that can refuse a sign-in as an app in testing, so you can test this path without a second account. See [Test your app](/docs/guides/test-your-app).
-
-## Checked and not checked
-
-From the SDK source, the console source and the testing-mode specification. Adding a tester, a second person signing in, the `app_in_testing` redirect and removing a tester have not been run on production (not yet checked on production). Those steps need a second account.

package/docs/apps/get-started.md

@@ -0,0 +1,47 @@
+---
+title: Get started
+description: What every Northlight app needs first — an account, a registered app, sign-in with Northlight, a stored connection per person, scopes, and testing mode — and where each is covered.
+---
+
+# Get started
+
+Every app on Northlight starts the same way: a person signs in with their Northlight account, your server stores a connection for them, and from then on it calls their runtime with `oauth.client(userId)`. The six sections of this site all build on that.
+
+```bash
+npx @north-light/sdk@latest init my-app
+```
+
+`init` writes a Node server, a signing key and an env file. [Quick setup](/docs/quickstart) takes it from there to a running app in about ten minutes. Using a coding agent? Tell it: *Read https://sdk.docs.northlight.ai/SKILL.md and follow it.* See [Use your coding agent](/docs/coding-agents).
+
+Once a person has signed in, this is all it takes to use their runtime:
+
+<include lang="ts">../../examples/apps/quickstart-server.ts#run</include>
+
+## What to read, in order
+
+| Page | What it covers |
+|---|---|
+| [Quick setup](/docs/quickstart) | From no account to an app that signs you in, starts a run and texts your phone |
+| [Use your coding agent](/docs/coding-agents) | The `northlight` skill that `init` installs for Claude Code, Codex, Cursor and Copilot |
+| [Where your app runs](/docs/how-it-fits) | Your server, the directory at `account.northlight.ai`, and each person's runtime |
+| [Apps and sign-in](/docs/concepts/apps-and-sign-in) | What registering creates, the key pair, and the sign-in flow `OAuth2Client` runs |
+| [Connections](/docs/concepts/connections) | What you store per person, token refresh, and refused connections |
+| [Scopes and grants](/docs/concepts/scopes-and-grants) | What your app may ask for, what a person allowed, and a run's own scopes |
+| [Testing mode](/docs/concepts/testing-mode) | You and up to 100 testers can sign in until the app is verified |
+| [Test your app](/docs/guides/test-your-app) | Test your server against `@north-light/sdk/testing` without a network |
+| [Manage your app](/docs/guides/manage-your-app) | The console's tabs: sign-in, scopes, profile, sharing, testers and provider |
+| [Go live](/docs/guides/go-live) | Persistent storage, a real host, verification and the marketplace |
+
+Then pick what your app does from the sections in the sidebar: [use our AI](/docs/use-our-ai), [use our apps](/docs/use-our-apps), [know the person](/docs/know-the-person), [reach people by text](/docs/reach-people-by-text), [let the person's AI use your app](/docs/let-their-ai-use-your-app), or [let other apps build on yours](/docs/build-on-your-app).
+
+## Run `crtr cloud apps` yourself
+
+Everything on this site works with the SDK's own commands and the web console. If you also run crouter, the agent runtime Northlight is built on, you can join your machine to your Northlight account and manage your apps with `crtr cloud apps`, or let your own crouter agents build and manage them.
+
+```bash
+npm install -g @north-light/cli
+crtr sys join --directory https://account.northlight.ai --token <token>
+crtr cloud apps mine
+```
+
+The token comes from **Create join token** at `https://account.northlight.ai/account/machines`. The full steps, and what joining changes on your machine, are in [Join a machine to your Northlight account](https://crouter.docs.northlight.ai/docs/cli/join-northlight). The CLI is [`@north-light/cli`](https://www.npmjs.com/package/@north-light/cli) on npm, and crouter's own docs are at [crouter.docs.northlight.ai](https://crouter.docs.northlight.ai).

package/docs/apps/guides/go-live.md

@@ -30,7 +30,7 @@ Four variables configure an app built on the SDK:
 
 A new app is in testing: only you and up to 100 testers can sign in. To open it to everyone, ask Northlight to verify it by email to support@northlight.ai. Include your app's name and client ID, where it runs, and what it asks for and why. Until then, anyone else is refused with `app_in_testing`. See [Testing mode](/docs/concepts/testing-mode).
 
-This site does not state how long verification takes or what Northlight checks beyond that email address (not yet checked on production).
+This site does not state how long verification takes or what Northlight checks beyond that email address.
 
 ## Rotate the key later
 

package/docs/apps/guides/manage-your-app.md

@@ -5,7 +5,7 @@ description: What each tab of the Northlight console does for an app you have re
 
 # Manage your app
 
-You manage an app in the console at `https://account.northlight.ai/console`. Choose your app in the list to open its page. The tabs are Sign-in, What it asks for, Profile, Sharing, Testers and Provider. (Only the first-party apps use Provider.)
+You manage an app in the console at `https://account.northlight.ai/console`. Choose your app in the list to open its page. The tabs are Sign-in, What it asks for, Profile, Sharing, Testers and Provider. **Provider** is where an app offers its own tools to people's agents and to other apps: see [Let their AI use your app](/docs/let-their-ai-use-your-app).
 
 Your **client ID** is shown on the app's page. `npx @north-light/sdk register` writes it to `local/app.env`; for an app registered in the browser, use `npx @north-light/sdk env --client-id <client id>`.
 
@@ -22,7 +22,7 @@ The login cannot do these, and the CLI refuses them without a request:
 - The provider role.
 - On a verified app: signing keys, the JWKS URL, redirect URIs and the run notice URL.
 
-Everything below names its `apps` command when there is one. (Not yet checked on production for any `apps` command.)
+Everything below names its `apps` command when there is one.
 
 ## Sign-in
 
@@ -46,7 +46,7 @@ Until you retire the old key it is your rollback. After you retire it, a sign-in
 - **What your app asks for.** The scopes people are asked to approve. **Add permissions** searches the catalog; take scope strings from it and from `providers.tools`, and do not invent them. From the terminal: `apps asks` lists what the app can ask for, and `apps set-scopes --add <scope>` or `--remove <scope>` changes the list. `crtr:act` needs `crtr:llm`. See [Scopes and grants](/docs/concepts/scopes-and-grants).
 - **What your app requires.** Providers the app cannot work without (`apps set-requires`). A person is taken through that provider's setup the first time they sign in. See [Grant changes](/docs/guides/grant-changes#wait-on-a-provider-your-app-requires).
 - **Monthly spend cap.** The most your app may spend of each person's AI subscription per month, in whole US dollars.
-- **Run notice URL.** Where Northlight posts a signed notice when one of your app's background runs ends. Type it in **Notice URL** and choose **Save**; empty it and save to turn notices off. From the terminal: `apps set-run-notice-url` (apps in testing). The URL must be `https`, at most 512 characters, with no `#fragment`. The directory refuses a plain `http` URL with `run_notice_url` as the field. The field's hint says `http://localhost` is accepted while developing, but the production directory refuses it (checked in the directory source, not yet checked on production), so test notices with a tunnel that gives you an `https` URL. What your app does with a notice is in [Background runs](/docs/guides/background-runs#run-notices).
+- **Run notice URL.** Where Northlight posts a signed notice when one of your app's background runs ends. Type it in **Notice URL** and choose **Save**; empty it and save to turn notices off. From the terminal: `apps set-run-notice-url` (apps in testing). The URL must be `https`, at most 512 characters, with no `#fragment`. The directory refuses a plain `http` URL with `run_notice_url` as the field. The field's hint says `http://localhost` is accepted while developing, but the production directory refuses it, so test notices with a tunnel that gives you an `https` URL. What your app does with a notice is in [Background runs](/docs/guides/background-runs#run-notices).
 
 ## Profile
 
@@ -75,6 +75,6 @@ Once your app is live you can keep developing on your laptop against production
 
 On the **Profile** tab, the **Delete this app** card lists what goes: every person's connection to the app, yours included (each person's runtime deletes the app's runs, space and schedules), the app's sign-ins and keys, and its testers and marketplace listing. This cannot be undone, and the client ID is never reused.
 
-To delete, type the app's full name in **Type the app's name, *name*, to confirm**. **Delete app** stays disabled until what you typed matches the name (surrounding spaces are ignored), and the directory checks the name again when you submit. After it deletes, the console returns to your app list. Checked on production: the app is gone from the list, the console's API answers 404 `App not found` for it, and `/authorize` with its client ID shows "We couldn't start that sign-in" (HTTP 400). The app's next refresh for any person failing with `invalid_grant` is not yet checked on production.
+To delete, type the app's full name in **Type the app's name, *name*, to confirm**. **Delete app** stays disabled until what you typed matches the name (surrounding spaces are ignored), and the directory checks the name again when you submit. After it deletes, the console returns to your app list. After that, `/authorize` with its client ID shows "We couldn't start that sign-in" (HTTP 400).
 
 The card is not shown for a provider or a first-party app, and the directory refuses to delete a provider (`app_is_provider`). If you only want a clean slate for tests, changing the app's redirect URIs and keys is often simpler.

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

@@ -43,4 +43,4 @@ The person's AI subscription pays for model calls, and what your app may do on t
 
 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).
+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.

package/docs/apps/know-the-person.md

@@ -0,0 +1,27 @@
+---
+title: Let your app know the person
+description: Learn who the person is and what they care about from their first sign-in, with the context provider and their public documents.
+---
+
+# Let your app know the person
+
+A person who signs in to your app already has a Northlight agent that knows them. Your app can ask it about them from the first sign-in, so onboarding needs fewer questions and the product fits them sooner.
+
+```ts
+const runtime = await oauth.client(userId);
+const advice = await runtime.providers.call({
+  provider: 'context',
+  tool: 'ask informed', // pass the name exactly as providers.tools('context') lists it
+  arguments: {request: 'Suggest the first three topics for this person\'s reading list.'},
+});
+```
+
+`ask informed` (scope `context:ask_informed`) answers from everything their agent knows, private memories included, without handing you private details. `ask public` (scope `context:ask_public`) answers from their public memories only.
+
+## Guides
+
+| Page | What it covers |
+|---|---|
+| [Context](/docs/providers/context) | The context provider's scopes, setup and tools, including public profile lookups |
+| [Files and documents](/docs/guides/files-and-documents) | Read the documents the person made public with `memory.list` and `memory.get`, with no scope |
+| [Providers](/docs/concepts/providers#providers-your-app-requires) | Require `context` so the person sets it up at first sign-in |

package/docs/apps/let-their-ai-use-your-app.md

@@ -0,0 +1,63 @@
+---
+title: Let the person's AI use your app
+description: Make your app a provider so its tools show up in the person's chat and terminal agents. Define commands with @north-light/plugin, serve them over HTTP, and add the provider role in the console.
+---
+
+# Let the person's AI use your app
+
+Your app can be a provider: it offers tools, and once a person connects it, every agent they run (in Northlight chat, in their terminal, and in other apps that ask for it) can call them. You define the tools once with [`@north-light/plugin`](https://www.npmjs.com/package/@north-light/plugin) and serve them from your own server.
+
+```ts
+import {createFetchHandler, defineLeaf, definePlugin, field, param} from '@north-light/plugin';
+
+export const plugin = definePlugin({
+  name: 'acme',
+  provider: true,
+  version: 1,
+  description: 'Manage Acme orders.',
+  whenToUse: 'you need to look up an Acme order.',
+  summary: 'Acme orders',
+  rootEntry: {concept: 'an Acme order', description: 'Look up orders.', whenToUse: 'the task is about an Acme order.'},
+  groups: {read: {consentLine: 'Read your Acme orders.'}},
+  commands: {
+    order: defineLeaf({
+      group: 'read',
+      description: 'Show one order.',
+      whenToUse: 'you have an order id.',
+      summary: 'show an order',
+      params: {id: param.positional('The order id.', {required: true})},
+      output: {status: field.string('The order status.')},
+      effects: ['Reads one order.'],
+      handler: (input, ctx) => ({status: 'shipped'}), // ctx.caller.sub is the person who connected
+    }),
+  },
+});
+
+export default createFetchHandler(plugin, {
+  auth: {issuer: 'https://account.northlight.ai', audience: 'https://acme.example.com/crtr', providerId: process.env.CROUTER_CLIENT_ID!},
+});
+```
+
+Each group in `groups` is a scope named `<your client id>:<group>`, and its `consentLine` is what the consent page shows. Every request carries a token the directory minted for one person; the handler checks it and the group's scope before your code runs.
+
+## The steps
+
+1. **Define the tools** with `definePlugin({provider: true, version, groups, commands})`. Every leaf names its `group`.
+2. **Serve them** at an HTTPS URL. `createFetchHandler` is a standard Fetch handler; `createNodeHandler` serves the same plugin from Node's `http` server.
+3. **Add the provider role.** In the console, open your app's **Provider** tab, fill in **Offer tools to other apps** with your **Endpoint URL** (and an optional **Manage URL**, where people manage their connection), and choose **Add provider role**. The directory fetches your manifest and saves the groups it declares. After a change, choose **Refresh manifest**.
+4. **Set a price**, if you charge, on the same tab: free, a price per unit, or the cost your provider reports, plus a free monthly allowance per person.
+
+## Who may use a group
+
+A group's `who` says who may be granted it: `own` (only your own app), `user` (the default), `allowlist` (the apps listed in `allowlist`), `any`, or `team:<id>`. The directory applies `own` and `team:<id>`; `user`, `allowlist` and `any` are stored but not yet enforced at consent.
+
+## Guides
+
+These live on the crouter docs site, because the same package also adds commands to a self-run crouter:
+
+| Page | What it covers |
+|---|---|
+| [Plugin docs](https://crouter.docs.northlight.ai/docs/plugin) | What `@north-light/plugin` does and how a plugin is installed |
+| [Commands](https://crouter.docs.northlight.ai/docs/plugin/commands) | Branches, leaves, parameters, outputs, groups and `who` |
+| [Deploying](https://crouter.docs.northlight.ai/docs/plugin/deploying) | `auth: {issuer, audience, providerId}`, `ctx.caller`, versions and breaking changes |
+| [Manage your app](/docs/guides/manage-your-app) | The console's **Provider** tab beside the others |

package/docs/apps/providers/README.md

@@ -25,4 +25,4 @@ A provider is a service the person's runtime calls for your app. Your app asks t
 
 <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.
+Each provider page below shows the tools of a provider as listed on **2026-10-16** by a person's own Northlight runtime, so it shows the groups that person's own grant holds, not an app's view. 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

@@ -9,13 +9,13 @@ The `context` provider answers questions about the person from what their agent
 
 ## 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).
+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`). It was not in that console list on that date, so check that **Add permissions** offers it before your app depends on it.
 
 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).
+Tools as listed on 2026-10-16 (provider major version 1). `*` marks a required parameter. Tool names with a space are written as the provider lists them; pass a multi-word `tool` to `providers.call` exactly as your own `providers.tools` output lists it.
 
 | Tool | Group | Parameters | What it does |
 |---|---|---|---|

package/docs/apps/providers/device.md

@@ -5,7 +5,7 @@ description: "Reach the person's Mac from your app: browser, files, Messages and
 
 # 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. When the person has more than one registered Mac, a call must name the one to use with `machine` (`providers.call({provider: 'device', tool, arguments, machine})`); without it the runtime refuses with `machine_required` (except `browser libs`, which uses the most recently seen Mac).
+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. When the person has more than one registered Mac, a call must name the one to use with `machine` (`providers.call({provider: 'device', tool, arguments, machine})`); without it the runtime refuses with `machine_required` (except `browser libs`, which uses the most recently seen Mac).
 
 ## Scopes
 
@@ -13,7 +13,7 @@ The `device` provider reaches the person's own Mac. Its tools run on the person'
 
 ## 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.
+Tools as listed on 2026-10-16 (provider major version 2, transport `machine`). `*` marks a required parameter.
 
 | Group (scope) | Tools |
 |---|---|
@@ -23,4 +23,4 @@ Captured 2026-10-16 from `GET /v1/providers/device/tools` on a joined runtime (p
 | `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.
+Tool names with spaces are written as the provider lists them; pass them to `providers.call` exactly as your own `providers.tools` output lists them. The table shows 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

@@ -16,7 +16,7 @@ Scope strings come from **What it asks for → Add permissions** (provider `inte
 
 ## 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:
+The provider has thousands of tools: on 2026-10-16 one runtime 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');

package/docs/apps/providers/search.md

@@ -13,7 +13,7 @@ Each scope is `search:<group>`: `search:search`, `search:answer`, `search:conten
 
 ## Tools
 
-Captured 2026-10-16 from `GET /v1/providers/search/tools` on a joined runtime (provider major version 1). `*` marks a required parameter.
+Tools as listed on 2026-10-16 (provider major version 1). `*` marks a required parameter.
 
 | Tool | Group (scope) | Parameters | What it does |
 |---|---|---|---|

package/docs/apps/providers/sms.md

@@ -14,7 +14,7 @@ The `sms` provider sends a text from Northlight's number to the verified phone o
 | Scope | Consent sentence | Gates |
 |---|---|---|
 | `sms:send` | Send you text messages from Northlight's number | `send`, `react` |
-| `sms:status` | Not captured | `status` |
+| `sms:status` | Not listed | `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`.
 
@@ -24,11 +24,11 @@ Add them under **What it asks for → Add permissions** (provider `sms`). Withou
 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).
+`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.
 
 ## Tools
 
-Captured 2026-10-16 from `GET /v1/providers/sms/tools` on a joined runtime (provider major version 1). `*` marks a required parameter.
+Tools as listed on 2026-10-16 (provider major version 1). `*` marks a required parameter.
 
 | Tool | Group (scope) | Parameters | What it does |
 |---|---|---|---|

package/docs/apps/quickstart.md

@@ -9,19 +9,19 @@ description: From no account to a running app that signs a person in with Northl
 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.
+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. To run crouter on your own machine as well, see [Get started](/docs/get-started#run-crtr-cloud-apps-yourself).
 
 You need Node.js 20.6 or later (the start command uses `--env-file`) and a phone that can receive iMessage. The server was run on Node 20.6, 20.20, 22.14, 22.22 and 26.12.
 
 Using a coding agent? Tell it: *Read https://sdk.docs.northlight.ai/SKILL.md and follow it.* It runs every command below; you sign up, then choose **Allow** twice in your browser. 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`.
+Each step below ends with what you should see when it worked.
 
 ## 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`, which asks for a name and a phone number and offers **Text me a confirmation**; `/console` while signed out redirects to sign-in; and the signed-in console lists your apps and has **Register an app**. Completing signup, the confirmation code and the "We couldn't send the text" refusal are not yet checked on production (the walk used an existing 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.
 
 ## 2. Scaffold the app
 
@@ -49,8 +49,6 @@ You should see, on the terminal: `Created a Northlight app in my-app:` with the
 
 Only the browser registration below uses that line: `register` reads the public half from `local/app-key.json` itself. If a file already exists, `init` refuses, names it and exits non-zero without writing anything.
 
-Checked on production: `npx @north-light/sdk@latest init my-app` (npm `latest` 0.3.476) in an empty directory with no crtr on `PATH` printed this output and wrote these files, the private key has mode `0600`, and `server.ts` is the one listed at the end of this page. Running it again names the skill file and writes nothing.
-
 ## 3. Log in
 
 ```bash
@@ -89,8 +87,6 @@ and "Done. Go back to your terminal." in the browser. The name, id and dates are
 
 The login is saved outside your project, in `~/.config/northlight/credentials.json` (mode `0600`). Never commit, paste or print it.
 
-Checked on production: this whole step, including the confirm page and its wording. The confirm page reads "Let a coding agent manage your Northlight apps?", shows the code, the computer's name and platform and the address it asked from ("The computer named itself; Northlight did not check it"), and lists what the login can and can't do. After **Allow** the page reads "Done / Go back to your terminal." and the terminal prints the output above.
-
 If you run `login` again, it does not start over. While a code is pending it prints "Still waiting for the login started at HH:MM." with the same link and code. Once you are logged in it prints "Already logged in as …" and exits 0. If the code expired unapproved it exits 1 and says so: run it again for a new code. See [the CLI reference](/docs/cli#login-logout-whoami).
 
 If `login` cannot reach `account.northlight.ai`, or you would rather use the browser, skip to [Register in the browser instead](#register-in-the-browser-instead).
@@ -118,8 +114,6 @@ Next: npm i && npm start, then open http://localhost:3000/auth/login
 
 `local/app.env` now has all four settings. The name, client ID and key ID are examples. Change the defaults with `--name`, `--logo`, `--justification` and `--redirect-uri`; the default logo is a placeholder, `https://sdk.docs.northlight.ai/app-logo.png`. `register` refuses when `CROUTER_CLIENT_ID` is already set. A login can register at most 10 apps a day.
 
-Checked on production: this step, including that the directory accepts the default logo.
-
 ## 5. Run it
 
 ```bash
@@ -131,8 +125,6 @@ node --env-file=local/app.env --import tsx server.ts
 
 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`, the run's reply (`pong`) and the text's `message_id`, and your phone receives "Hello from my first Northlight app." from Northlight's number.
 
-Checked on production, as the account that owns the app: the server starts (with `npm start` too), `/` 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 listed the four permissions and the monthly cap, **Allow** returned to `http://localhost:3000/` with "Signed in" and the user id, and the button page answered "Done" with status `idle` and a `message_id` for the text. In the console the key then read "Last used just now". Not yet checked on production: that the text reached the phone (the `message_id` is the provider's answer, not a delivery receipt), and the `426` case. The `pong` reply is read through `runs.reply` and has not been run on production since this example changed. Signing in as a second person needs a second account and is not covered here.
-
 If `/` shows "One step left", `CROUTER_CLIENT_ID` is empty: run `npx @north-light/sdk register` (or, for an app you registered in the browser, `env --client-id`) 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.
 
 ## 6. What next
@@ -163,16 +155,12 @@ 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, then choose **Continue to *your app's name***. 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`.
 
-Checked on production: these field labels, registering with a pasted key, and the app page opening in testing with that key active and `crtr:llm` and `crtr:act` listed. The "Next: add your app's public key" message, which shows when the key is left out, is not yet checked on production.
-
 ### Add the permission to text
 
 On the app's page, open the **What it asks for** tab and choose **Add permissions**. Choose **Texting**, tick `sms:send` ("Send you text messages from Northlight's number"), and choose **Done**. Then choose **Save** under the list: **Done** only closes the dialog, and the change is not stored until you save.
 
 You should see: `sms:send` under what your app asks for after **Save** says "Saved", 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 5 is refused. Take scope strings from this list. Do not invent them. See [Scopes and grants](/docs/concepts/scopes-and-grants).
 
-Checked on production: after **Save** and a reload, the tab lists `crtr:llm` and `crtr:act` under Agents and `sms:send` under Texting, and the consent page in step 5 offered the text permission.
-
 ### Write the client ID into the env file
 
 ```bash
@@ -191,8 +179,6 @@ 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 on production: this output, and that the command works in a directory with no `local/` yet. `--origin` is not yet checked on production.
-
 ## The server `init` writes
 
 This is `examples/apps/quickstart-server.ts`. The SDK reads no environment: the server passes the values in.

package/docs/apps/reach-people-by-text.md

@@ -0,0 +1,47 @@
+---
+title: Reach people by text
+description: Give your app its own iMessage number with Comms. People text it, your server answers with an agent run on their runtime, and you can text them again later.
+---
+
+# Reach people by text
+
+Comms gives your app its own iMessage number, under your app's name and avatar. People text that number, Comms sends each text to your server as a signed webhook, and your server answers with an agent run on the person's own runtime. Once a person has texted you, your app can text them again later, for example from a timer.
+
+```ts
+import {continueInRuntime, formatReply, verifyWebhook} from '@north-light/comms';
+
+const event = verifyWebhook(req.headers, rawBody, [process.env.COMMS_WEBHOOK_SECRET!]);
+if (event.type === 'message.received' && event.data.content.type === 'text') {
+  const {contact, content} = event.data;
+  if (!contact.user) return; // only a sender texting from an Apple ID email has no user
+  const client = await oauth.client(contact.user.id); // their Northlight user id, the same as Connection.userId
+  const {runId, reply} = await continueInRuntime({client, message: content.text, runId: runs.get(contact.id), idempotencyKey: event.id});
+  runs.set(contact.id, runId); // later texts continue the same run
+  const {text} = await reply.collect();
+  for (const part of formatReply(text)) {
+    await comms.sendMessage({environment: event.environment, to: {contact_id: contact.id}, text: part, idempotency_key: `reply:${event.id}:${part.length}`});
+  }
+}
+```
+
+`oauth.client` throws `CrouterError` with code `not_connected` when the person has not signed in to your app yet. Answer that with `sendSignInLink(comms, contact, {environment: event.environment})`: Comms texts them a link that signs them in to your app, which lands on your **Sign-in start URL** (console → **Profile** → **Marketplace**).
+
+## The steps
+
+The [Comms guide for coding agents](https://comms.northlight.ai/llms.txt) is the whole reference: the webhook events, the send API, its errors, STOP and HELP handling, and the `crtr comms` commands. In short:
+
+1. **Build in fake mode.** `npx @north-light/comms fake --webhook http://localhost:3000/hook` runs a local Comms with no account. `npx @north-light/comms fake send --from +15550001 --text "hi"` plays a person texting you.
+2. **Register your app on Northlight.** [Quick setup](/docs/quickstart) steps 1 to 4: sign up, `npx @north-light/sdk login`, `npx @north-light/sdk register`. Comms signs in with the same app key.
+3. **Connect the app to Comms.** At `https://comms.northlight.ai`, sign in and choose **Connect an app**. This is done in a browser only.
+4. **Turn Texting on.** On the app's page there, or with `crtr comms turn-on`: a display name, a square avatar, the HELP text and your test webhook URL. The page shows the test webhook signing secret.
+5. **Text it from your own phone, in test mode.** Add yourself as a tester (`crtr comms testers add --app-id <id> --phone <number> --label <name>`, or the site), then text `JOIN <code>` to the test number. Test mode is free; the [Comms guide](https://comms.northlight.ai/llms.txt) has the tester limit.
+6. **Go to production** when you want your app's own number and anyone to text it. Production is paid: add a card on the billing account, and Comms gets your app its own number.
+
+Comms is priced per person your app texts with in production each month; fake mode and testing are free. The SDK is [`@north-light/comms`](https://www.npmjs.com/package/@north-light/comms) on npm. Its 0.3.0 release declares `@north-light/sdk` 0.3.457 as an exact optional peer, so in a project pinned to a newer SDK install it with `npm i @north-light/comms --legacy-peer-deps`.
+
+## Rules
+
+- **People text first.** Your app can text a person only after they texted your number in that environment, and until they send STOP. A send to anyone else fails `403 not_texted_first`.
+- **Address people by `contact_id` or `user_id`**, never by phone number.
+- **Derive `idempotency_key` from the event you are answering**, so a retried webhook sends nothing twice. Deduplicate deliveries on `event.id`.
+- **Verify the raw body** with `verifyWebhook` before you parse it, and answer `2xx` within 15 seconds.

package/docs/apps/use-our-ai.md

@@ -0,0 +1,27 @@
+---
+title: Let your app use our AI
+description: Start agent runs on each person's own Northlight runtime, with their memory, files and tools, paid by their AI subscription. Typed results, streaming, background runs and documents.
+---
+
+# Let your app use our AI
+
+Your app starts agents on the person's own Northlight runtime. Each run has their memory, files and tools, works under the scopes they approved, and its model calls are paid by their AI subscription, not by you.
+
+<include lang="ts">../../examples/apps/runs-parse.ts</include>
+
+`runs.parse` starts a run and returns a value checked against your schema. `runs.start` returns at once and lets you follow the run, reply to it or leave it running.
+
+## Guides
+
+| Page | What it covers |
+|---|---|
+| [Runs](/docs/concepts/runs) | Start a run, its status and outcome, a run's own scopes, and how to bound one |
+| [Typed results](/docs/guides/typed-results) | Get a value back with `runs.parse` and a schema; never parse the trace |
+| [Stream a run](/docs/guides/stream-a-run) | Show the agent's text and tool calls as they happen |
+| [Background runs](/docs/guides/background-runs) | Learn when a run you did not wait on has ended, with `RunWatcher` or run notices |
+| [Files and documents](/docs/guides/files-and-documents) | Download a file from a run, and read the person's public documents |
+| [Many users](/docs/guides/many-users) | Keep each person's runtime separate when people meet in your app |
+
+To schedule work, call `runs.start` from your own timer. A run's agent may also schedule itself with `crtr cron add` when the run holds `crtr:schedule` ([Scopes and grants](/docs/concepts/scopes-and-grants)).
+
+An app that pays for its own model calls instead can serve them from its own service with `inferenceEndpoint` from `@north-light/sdk`; see the [release notes](/docs/release-notes) and the [reference](/docs/reference).

package/docs/apps/use-our-apps.md

@@ -0,0 +1,32 @@
+---
+title: Let your app use our apps
+description: Call Northlight's providers from your app on the person's runtime — texting their phone, web search, their connected accounts, their Mac — with providers.tools and providers.call.
+---
+
+# Let your app use our apps
+
+Northlight's own apps are providers your app can call on the person's runtime: text their phone, place calls, search the web, open a cloud browser, read and act in the accounts they connected, and use their Mac. The person approves each provider's scope once, on your app's consent page.
+
+<include lang="ts">../../examples/apps/provider-tools.ts</include>
+
+Every provider works the same way: ask for its scope, list its tools with `providers.tools('<provider>')`, then call one with `providers.call`. Scope strings, tool names and arguments come from those lists, never from memory.
+
+## Providers
+
+| Provider id | What it does | Page |
+|---|---|---|
+| `sms` | Texts the signed-in person's own verified phone | [Texting (sms)](/docs/providers/sms) |
+| `search` | Web search, sourced answers, page contents and paid data endpoints | [Search](/docs/providers/search) |
+| `integrations` | The person's own accounts at other services | [Integrations](/docs/providers/integrations) |
+| `context` | Ask about the person from their memory, and look up public profiles | [Context](/docs/providers/context) |
+| `device` | The person's Mac: browser, files, Messages and shell | [Device](/docs/providers/device) |
+
+These five have pages here. Northlight also runs `phone` (calls from Northlight's number, with an AI voice), `browser` (cloud browser sessions) and `meetings` (the person's meeting notes and transcripts), which have no page yet. For any of them, `providers.tools()` with no argument lists every provider installed on the person's runtime, `providers.tools('<provider>')` lists its tools and arguments, and the console's **Add permissions** list shows every scope your app can ask for.
+
+## Guides
+
+| Page | What it covers |
+|---|---|
+| [Providers](/docs/concepts/providers) | Scopes, finding and calling tools, and providers your app requires |
+| [Providers index](/docs/providers) | Every first-party provider, its scopes and where names come from |
+| [Grant changes](/docs/guides/grant-changes) | When a person adds or removes a scope, and waiting on a provider's setup |

package/docs/cli/join-northlight.md

@@ -5,7 +5,7 @@ description: Join a laptop to your Northlight account with crtr sys join so crtr
 
 # Join a machine to your Northlight account
 
-Joining makes this machine one of your Northlight account's machines, so `crtr cloud …` commands run as you. Building an app does not need it: the [SDK docs site](https://sdk.docs.northlight.ai/docs/quickstart) takes you through the web console. Join when you want to run `crtr cloud apps` yourself.
+Joining makes this machine one of your Northlight account's machines, so `crtr cloud …` commands run as you. Join when you want to run `crtr cloud apps` yourself, or to let your own crtr agents build and manage your Northlight apps. Building an app works without it too: the [SDK docs site](https://sdk.docs.northlight.ai/docs/get-started) uses `npx @north-light/sdk` and the web console.
 
 Create your account at `https://account.northlight.ai/signup` first. Then install the CLI (`npm i -g @north-light/cli`). Joining needs `crtr` 0.3.436 or later (older versions need `crtr sys daemon stop` first and fail if a viewer is open); `crtr --version` shows yours.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@north-light/cli",
-  "version": "0.3.543",
+  "version": "0.3.544",
   "description": "crtr — agent runtime with memory, plugins, and marketplaces",
   "type": "module",
   "main": "dist/index.js",
@@ -140,7 +140,7 @@
   },
   "license": "UNLICENSED",
   "dependencies": {
-    "@north-light/identity": "0.3.543",
+    "@north-light/identity": "0.3.544",
     "@earendil-works/pi-agent-core": "1.1.0",
     "@earendil-works/pi-ai": "1.1.0",
     "@earendil-works/pi-coding-agent": "1.1.0",

package/packages/crouter-identity/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@north-light/identity",
-  "version": "0.3.543",
+  "version": "0.3.544",
   "description": "Northlight access-token verification and scope rules",
   "type": "module",
   "main": "./dist/index.js",