@north-light/cli 0.3.542 → 0.3.544

package/docs/apps/build-on-your-app.md

@@ -0,0 +1,44 @@
+---
+title: Let other apps build on yours
+description: Offer your app as a service other Northlight apps build on — as a provider their runs call, or as your own API — and list it with a docs link so their coding agents find it.
+---
+
+# Let other apps build on yours
+
+Other developers' apps can build on yours the way they build on Northlight's: by calling your provider tools from a run, or by calling your own API. Set a docs link on your app and it is listed on [Services you can build on](/docs/services), where their coding agents look.
+
+Comms is built this way. Another app calls it with its own Northlight app key, and reads [comms.northlight.ai/llms.txt](https://comms.northlight.ai/llms.txt) to learn how:
+
+```ts
+import {readFile} from 'node:fs/promises';
+import {CommsClient} from '@north-light/comms';
+
+const comms = new CommsClient({
+  baseUrl: 'https://comms.northlight.ai',
+  issuer: 'https://account.northlight.ai',
+  clientId: process.env.CROUTER_CLIENT_ID!, // the calling app's own client id and key
+  privateKeyJwk: JSON.parse(await readFile(process.env.CROUTER_KEY_FILE!, 'utf8')),
+});
+```
+
+## Two ways to offer it
+
+- **As a provider.** Your tools run on the person's runtime for any app the person has granted them, and you can charge per call. This is the same work as [letting the person's AI use your app](/docs/let-their-ai-use-your-app); other apps ask for your groups as scopes named `<your client id>:<group>`.
+- **As your own API.** Serve HTTP from your own host, as Comms does. A calling app identifies itself with its Northlight client id and key, so you know which app is asking.
+
+## Get listed
+
+1. In the console, open your app's **Profile** tab.
+2. Under **Marketplace**, set **Docs link** to the https URL of your guide for agents and developers, for example `https://yourapp.com/llms.txt`, and choose **Save docs link**.
+3. Write that guide for a coding agent: what your service does, how to install the client, one working snippet, the errors and their fixes. [comms.northlight.ai/llms.txt](https://comms.northlight.ai/llms.txt) is a working example.
+
+[Services you can build on](/docs/services) is rebuilt from the directory's public marketplace list each time this site is built, so a new docs link appears with no change to these docs.
+
+## Guides
+
+| Page | What it covers |
+|---|---|
+| [Let the person's AI use your app](/docs/let-their-ai-use-your-app) | Define tools with `@north-light/plugin`, serve them, add the provider role, set a price |
+| [Services you can build on](/docs/services) | Every listed app with a docs link |
+| [Manage your app](/docs/guides/manage-your-app) | The console's **Profile** and **Provider** tabs |
+| [Go live](/docs/guides/go-live) | Verification and the marketplace listing |

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