@north-light/cli 0.3.543 → 0.3.545

package/docs/apps/cli.md

@@ -5,7 +5,7 @@ description: The npx @north-light/sdk commands for scaffolding an app, logging i
 
 # CLI reference
 
-`npx @north-light/sdk <command>` runs the package's one command-line tool. Run it with no command, or with `--help`, to print the list below. `npx @north-light/sdk <command> --help` (or `-h`) prints that command's usage and exits 0. An unknown command, or a bad flag, prints the usage and exits 1.
+`npx @north-light/sdk <command>` runs the command-line tool of [`@north-light/sdk`](https://www.npmjs.com/package/@north-light/sdk) on npm. (crouter's own CLI, `crtr`, is a different package: [`@north-light/cli`](https://www.npmjs.com/package/@north-light/cli). Tools you offer to agents are built with [`@north-light/plugin`](https://www.npmjs.com/package/@north-light/plugin).) Run it with no command, or with `--help`, to print the list below. `npx @north-light/sdk <command> --help` (or `-h`) prints that command's usage and exits 0. An unknown command, or a bad flag, prints the usage and exits 1.
 
 With no dependencies installed, `npx` downloads the newest published release of the SDK (the one tagged latest on npm), not the version your project pins. Run `npm i` in the project first if the pinned version must run; `init` pins the version of the CLI that ran it.
 
@@ -21,7 +21,7 @@ With no dependencies installed, `npx` downloads the newest published release of
 | `npx @north-light/sdk register [--name <text>] [--scope <scope>]... [--logo <url>] [--justification <text>] [--redirect-uri <uri>]... [--issuer <url>]` | Run in a project made by `init`, after `login`: registers the app with the public key from `local/app-key.json`, adds each `--scope` beyond `crtr:llm crtr:act`, and writes `CROUTER_CLIENT_ID` and `CROUTER_ISSUER` to `local/app.env`. | No |
 | `npx @north-light/sdk apps <leaf> [--app <client id>] [--issuer <url>] [leaf flags] [--json]` | Call one app-management leaf with the login and print its answer as JSON. Leaves: `mine`, `get`, `update`, `set-logo --file <path>`, `set-brand-color --color <#rrggbb|none>`, `set-redirect-uris`, `asks`, `set-scopes`, `set-requires`, `set-run-notice-url`, `keys list\|add\|retire\|delete\|set-jwks-uri\|remove-jwks-uri`, `testers list\|add\|remove`. `--app` defaults to `CROUTER_CLIENT_ID` in `local/app.env`; `keys add` takes `--key-file <path>` and sends only the public half. Deleting an app, its marketplace listing, monthly spend cap, sharing and provider role are console-only: those leaves exit 1 and name the console page, with no request. | No |
 
-`keygen` and `env` are the only commands that can call `crtr`, and only with `--app`. The documented path on this site never uses `--app`, so you do not need crtr. `login`, `logout`, `whoami`, `register` and `apps` call only the Northlight directory.
+`keygen` and `env` are the only commands that can call `crtr`, and only with `--app`. The rest of this site never uses `--app`, so crtr is optional; to use it, see [Run `crtr cloud apps` yourself](/docs/get-started#run-crtr-cloud-apps-yourself). `login`, `logout`, `whoami`, `register` and `apps` call only the Northlight directory.
 
 ## Details
 
@@ -63,7 +63,7 @@ Writes the `northlight` Agent Skill that ships in the package, replacing an olde
 
 ### `keygen`
 
-Writes a private signing key to `local/app-key.json` with mode `0600`, refuses to overwrite an existing file (pass `--out` for another path), and prints the public JWK on stdout. Register the JWK in the console with **Add key** on the app's **Sign-in** tab, or paste it under **Register an app**. With `--app <client id>`, it offers to add the key to your app through your own `crtr` (`crtr cloud apps keys add`); `--yes` skips the question. This needs a joined crtr, which this site does not otherwise require.
+Writes a private signing key to `local/app-key.json` with mode `0600`, refuses to overwrite an existing file (pass `--out` for another path), and prints the public JWK on stdout. Register the JWK in the console with **Add key** on the app's **Sign-in** tab, or paste it under **Register an app**. With `--app <client id>`, it offers to add the key to your app through your own `crtr` (`crtr cloud apps keys add`); `--yes` skips the question. This needs a joined crtr.
 
 ### `env`
 

package/docs/apps/coding-agents.md

@@ -5,7 +5,7 @@ description: What npx @north-light/sdk init and skill install for Claude Code, C
 
 # Use your coding agent
 
-The `northlight` skill teaches a coding agent the whole path in the [quick setup](/docs/quickstart): the commands, the code patterns and the rules. With it, your agent signs you up, logs in, registers the app and runs it, and you choose **Allow** twice in your browser: once on the login page, once on the app's consent page. `npx @north-light/sdk init` installs it into your project. The skill needs no account and no crtr.
+The `northlight` skill teaches a coding agent the whole path in the [quick setup](/docs/quickstart): the commands, the code patterns and the rules. With it, your agent signs you up, logs in, registers the app and runs it, and you choose **Allow** twice in your browser: once on the login page, once on the app's consent page. `npx @north-light/sdk init` installs it into your project. The skill needs no account to install, and works whether or not crouter is on your machine.
 
 ## Install it
 
@@ -25,6 +25,17 @@ npx @north-light/sdk skill
 
 `skill` always replaces the `northlight` skill it finds. `--print` writes the skill to stdout instead of to files.
 
+## Install it once for every project (Claude Code)
+
+If you build more than one app, install the Claude Code plugin instead of a copy in each project:
+
+```
+/plugin marketplace add Northlight-Systems/plugins
+/plugin install northlight
+```
+
+It adds the `northlight` skill, one skill for each section of this site, and the commands `/northlight:new-app`, `/northlight:add-permission`, `/northlight:text-people`, `/northlight:become-a-provider` and `/northlight:go-live`. The plugin repository is generated from these docs and the skill at each release, so it matches the current SDK version.
+
 ## Where it goes
 
 | Agent | In the project (default) | With `--global` |
@@ -36,7 +47,7 @@ npx @north-light/sdk skill
 
 The project copy is the default so it is committed with the project, and teammates get it from git. It matches the SDK version your project pins.
 
-Checked on production: the files `init` writes, that `init` in a directory that already has a `package.json` pins the SDK and writes the key and skill but no app code, and that `skill` rewrites both skill files. In such a directory `init` creates a `.gitignore` with `local/`, or adds `local/` to the one you have, so the key stays out of git. Which agent loads which directory is from each agent's documentation and is not yet checked on production for every agent.
+In a directory that already has a `package.json`, `init` creates a `.gitignore` with `local/`, or adds `local/` to the one you have, so the key stays out of git.
 
 ## Without a project: the hosted skill
 
@@ -50,7 +61,7 @@ If the agent's shell call times out or is interrupted while you approve, it runs
 
 The skill tells the agent to read the whole message `login` printed and its exit code before it tells you what happened.
 
-Checked on production with Claude Code (an interactive session, no crtr on `PATH`, an empty directory), given only the skill URL plus the quickstart request: a fresh session ran `init`, `login`, `npm i`, `register --scope sms:send` and `npm start` by itself. The person's part was choosing **Allow** on the login page and on the app's consent page, and pressing the button; the run replied `pong` and the text was sent (whether it reached the phone is not checked). When the first login code expired unapproved, that session said so and ran `login` again for a new code. In an earlier session on the same day, before this guidance, the agent misread a failed second `login` as a network timeout and fell back to the console steps. Name what you want built in the prompt.
+Name what you want built in the prompt.
 
 ## What the login can do
 
@@ -65,13 +76,11 @@ Checked on production with Claude Code (an interactive session, no crtr on `PATH
 | Change signing keys, redirect URIs and the run notice URL on an app in testing | Change those on a verified app: do it in the console |
 | | Approve another login |
 
-Deleting an app, its listing, spend cap and sharing stay in the console on purpose. The CLI refuses them without sending a request, and the directory refuses them (403 `provider_refused`) if a call is made by hand. Checked on production for delete, the marketplace listing and the spend cap.
+Deleting an app, its listing, spend cap and sharing stay in the console on purpose. The CLI refuses them without sending a request, and the directory refuses them (403 `provider_refused`) if a call is made by hand.
 
 The login lives in `~/.config/northlight/credentials.json` (`$XDG_CONFIG_HOME/northlight/credentials.json` when set), mode `0600`, outside your project. The CLI refuses a file that other users can read. It lasts 30 days, or until it has gone 14 days unused, and then you run `login` again. An account holds at most 10 logins; an eleventh replaces the oldest. The Developer access page shows the date the login goes unused, "Expires Oct 31" for a login approved on Oct 17, not the 30-day date the CLI prints.
 
-Revoke it on your account's Developer access page (`https://account.northlight.ai/account/developer`), or run `npx @north-light/sdk logout`, which revokes it on the server and removes it from the file. The file is not deleted: it is rewritten as `{"version":1,"issuers":{}}`, with no secret in it. A revoked login stops working at once: `whoami` and every other command fail with "This login was revoked" and ask for `login`, and a token minted before the revoke is refused with 401 `credential_revoked` even before it expires. Checked on production: the Developer access page, Revoke, `logout`, and what the next command prints.
-
-Not yet checked on production: the 10-login limit and the eleventh login replacing the oldest, and the 14-day and 30-day expiries.
+Revoke it on your account's Developer access page (`https://account.northlight.ai/account/developer`), or run `npx @north-light/sdk logout`, which revokes it on the server and removes it from the file. The file is not deleted: it is rewritten as `{"version":1,"issuers":{}}`, with no secret in it. A revoked login stops working at once: `whoami` and every other command fail with "This login was revoked" and ask for `login`, and a token minted before the revoke is refused with 401 `credential_revoked` even before it expires.
 
 ## How it stays current
 

package/docs/apps/concepts/apps-and-sign-in.md

@@ -76,7 +76,3 @@ LoggerModule.forRoot({
 ```
 
 Test it: send a callback with a recognizable fake code and assert that the code, the state and the cookie never appear in the log output.
-
-## Checked and not checked
-
-Checked on production: the discovery document lists `S256` and `private_key_jwt`, and the login route of the quickstart server redirects to `https://account.northlight.ai/authorize` with the PKCE challenge and nonce. The rest is from the SDK and directory source. A full sign-in as the account that owns the app, through the consent page and the callback, was run on production with the quickstart server. A sign-in by a second person, token refresh and the refusals are not yet checked on production.

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/guides/watchable-objects.md

@@ -0,0 +1,71 @@
+---
+title: Watchable objects
+description: Give each person a canvas object per thing in your app, let their agents watch it, and publish events to it reliably with the PostgreSQL object kit.
+---
+
+# Watchable objects
+
+`PostgresObjectStore` from `@north-light/sdk/stores/postgres` keeps one canvas object per person for each thing in your app (a problem, a ticket, a workspace), links the person's nodes to it, and delivers events to it from a database outbox. An agent that runs `crtr <your-plugin> thing watch T-12` then receives the events you publish for T-12.
+
+Your app declares the object kinds and their events in its plugin with `definePlugin({objectKinds})` (see [Deploying a plugin](https://crouter.docs.northlight.ai/docs/plugin/deploying)). The store registers objects of those kinds. Install `pg` in your app.
+
+## Create the tables
+
+`objectKitSchemaSql()` returns the DDL. Put it in your migration; the store never creates tables.
+
+```ts
+import {objectKitSchemaSql} from '@north-light/sdk/stores/postgres';
+
+console.log(objectKitSchemaSql()); // or objectKitSchemaSql({object: 'app.watch_object', watcher: '…', publish: '…'})
+```
+
+It creates three tables (names default to `watch_object`, `watch_watcher`, `watch_publish`):
+
+| Table | Holds |
+|---|---|
+| object | `object_id` (the runtime's id), `sub`, `kind`, `target`, `name`, `created_at`; unique on (`sub`, `kind`, `target`) |
+| watcher | `object_id`, `node`, `machine` (`''` for the person's hosted runtime); one row per linked node |
+| publish | the outbox: `id`, `object_id`, `event`, `summary`, `state` (jsonb), `status` (`pending`, `done`, `dropped`), `attempts`, `last_error`, `next_attempt_at`, `created_at` |
+
+Table names are lowercase identifiers, optionally schema-qualified.
+
+## Use it
+
+```ts
+import {Pool} from 'pg';
+import {PostgresObjectStore} from '@north-light/sdk/stores/postgres';
+
+const pool = new Pool({connectionString: process.env.DATABASE_URL});
+const objects = new PostgresObjectStore(pool, {
+  providerId: process.env.CROUTER_CLIENT_ID!,          // kinds register as `<providerId>.<kind>`
+  runtime: (sub) => oauth.appClient(sub),               // the app's client on that person's runtime
+});
+
+// In a command: find or create the person's object, then link the calling node to it.
+const object = await objects.instance(sub, 'problem', 'P-12', {name: 'problem/P-12', description: 'Problem P-12'});
+await objects.watch(object.objectId, ctx.caller.crtr.node, ctx.caller.crtr.machine);
+
+// In the transaction of the write the event records:
+await client.query('BEGIN');
+// … your writes …
+await objects.enqueue(client, object.objectId, {event: 'recovered', summary: 'P-12 recovered', state: {id: 'P-12'}});
+await client.query('COMMIT');
+
+// Once per process:
+const publisher = objects.startPublisher();             // every 5 s, up to 100 rows
+// on shutdown: await publisher.stop();
+```
+
+- `instance(sub, kind, target, {name, description})` returns the existing object for that (person, kind, target), or registers a private object on the person's runtime and stores it. Two calls racing to create the same object each register one; the row that committed first is kept and the other registration is unregistered. Use `''` as `target` for a kind with one object per person.
+- `watch(objectId, node, machine?)` links the node on the person's runtime (`canvas.watch` with `watcher`, plus `watcher_machine` when `machine` is set) and records the link. It is safe to repeat. A node the runtime does not know rejects with `NotFoundError`.
+- `enqueue(client, objectId, {event, summary, state?})` inserts an outbox row with the client you pass. Pass the client of your open transaction and the row exists exactly when your write committed. `summary` is cut to 500 characters. The object must already exist (the outbox references it).
+- `startPublisher({tick?, batch?})` delivers pending rows oldest first, every `tick` ms (default 5000), at most `batch` per tick (default 100). A Postgres advisory lock lets one process at a time deliver, so every instance of your app can run it. Delivery is at least once.
+
+## Delivery rules
+
+- A transient failure (network, 5xx, 429, `unknown_event`) keeps the row pending and retries after `min(2^attempts × 10 s, 15 min)`.
+- A refusal the runtime will never accept (HTTP 400, 404 or 422, other than `unknown_event`) marks the row `dropped` with `last_error` set.
+- A row still undelivered 24 hours after it was enqueued is marked `dropped`.
+- Rows are never deleted; delete `done` and `dropped` rows from your own cleanup job.
+
+`PostgresObjectStore.tick()` runs one delivery pass and answers `false` when another process holds the lock; `startPublisher` calls it on a timer, logging a failed tick and carrying on. Pass `log: {warn, error}` to route those messages.

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 |
 |---|---|---|---|