@north-light/cli 0.3.473 → 0.3.475

package/dist/builtin-memory/crouter-sdk/streaming.md

@@ -9,76 +9,7 @@ when-and-why-to-read: When you need Streaming, this knowledge should be read
 
 Watch a run as it works: assistant text as it is produced, tool calls as they start and finish, reports as they are pushed, and the settled outcome.
 
-## Forwarding a run to a browser
-
-The app server keeps the runtime token and connection; the browser connects only to the app. The app server calls `forwardRunEvents(client, runId, {after: cursorFromRequest(request), signal: request.signal})` and returns the Fetch `Response`. After a host cuts the browser connection, EventSource sends its last SSE id as `Last-Event-ID`; `cursorFromRequest` prefers it over the URL's `after` query parameter.
-
-Every forwarded run event is an unnamed SSE record with its `sequence_number` as `id` and the complete event object as `data`. Receive all event types with one handler:
-
-```ts
-const source = new EventSource(`/api/runs/${runId}/events?after=${cursor}`);
-source.onmessage = ({data}) => {
-  const event = JSON.parse(data);
-  if (event.type === 'stream.refused') { showRefusal(event.error); source.close(); return; }
-  if (event.type === 'stream.reconnecting') { showConnectionFailure(event.error); return; }
-  if (event.type === 'stream.reconnected') { clearConnectionFailure(); return; }
-  if (event.type === 'stream.idle') { source.close(); markIdle(event.cursor); return; } // reopen on your own trigger
-  showRunEvent(event);
-};
-```
-
-The four `stream.*` records are forwarded-stream notices, not daemon run events; they have no `sequence_number` or SSE id.
-
-`stream.idle` (`{type: 'stream.idle', cursor}`) means the runtime closed the stream after 60 s with no running turn and no new event. The helper writes it and then ends the response, so a browser `EventSource` would otherwise reconnect at once and keep a hosted runtime awake indefinitely. Close the `EventSource` on `stream.idle` and reopen it with `after=cursor` on your own trigger: the person sends a message, or your server handles a run notice (see `verifyRunNotice`). A `stream.refused` carries the full error envelope, including `stream_gap`'s `details.latest_sequence` and `details.earliest_sequence`. The helper ends that response after a refusal. The SDK does not recover a gap by skipping missing events.
-
-When the page reloads mid-reply or gets `stream_gap`, the app reads `runs.trace(runId)` through its server and shows each node's `in_progress_message` (`{thinking, text}` or `null`) as that node's open message. The trace's `latest_sequence` is read consistently with its conversations and open messages. Resume `runs.events(runId, {after: trace.latest_sequence})` (or forward with that cursor); do not use a separately read `runs.get` cursor. Continue appending new deltas to the open message, but replace its thinking or text with the complete content repeated by `node.thinking.done` or `node.output_text.done`. This shows the message from its beginning without duplicating content. `runs.get` and every `runs.list` entry expose `latest_sequence` and `last_activity_at`; a cursor equal to `latest_sequence` is not a gap even when older events have expired.
-
-## Following the reply to one message
-
-A chat app sends a message and shows the answer to it. `runs.reply(runId, sent, {signal?})` takes what `runs.message` returned and follows only the turn that delivers that message:
-
-```ts
-const sent = await client.runs.message(runId, 'What did the report say?');
-for await (const event of client.runs.reply(runId, sent)) {
-  if (event.type === 'text.delta') append(event.delta);
-  if (event.type === 'turn.completed' && event.error) showError(event.error); // {code: 'content_refused' | 'model_error', message}
-}
-// or collect it: text as it streams, then the whole text and how the turn ended
-const {text, ended, error, outcome} = await client.runs.reply(runId, sent).collect({onDelta: (delta) => append(delta)});
-// ended: 'completed' | 'error' (error set) | 'waiting_on_user' | 'settled' (outcome set)
-```
-
-It reads `runs.events(runId, {after: sent.sequence_number})`, skips child nodes' events, starts at the root's `node.turn.started` whose `input.message_ids` holds `sent.message_id`, and yields:
-
-| Event | Fields | From |
-|---|---|---|
-| `text.delta` | `delta` | `node.output_text.delta` |
-| `message.done` | `text` (the message's whole text, possibly empty), `stop_reason` | `node.output_text.done`, once per assistant message |
-| `turn.completed` | `run_status`, `stop_reason`, `error?`, `message_ids` | `node.turn.completed`; always last |
-| `run.settled` | `outcome` | `node.settled`, when the run settles before the turn completes; always last |
-
-Every event also carries its `sequence_number`. The reply ends after `turn.completed` or `run.settled` and closes its event stream. A resident run never settles when it goes idle, so a plain `runs.events` stream stays open, but a reply does not. `.text()` consumes the reply and resolves to the text of its `message.done` events joined with a blank line, so a turn that speaks, calls a tool and speaks again returns both texts. `.collect({onDelta?})` consumes the reply too: it passes each streamed piece to `onDelta`, starting a later assistant message's first piece with a blank line, and resolves to `RunReplyResult` `{text, ended, error?, outcome?}`, where `text` is the trimmed messages joined with a blank line. `ended` is `completed` (text may be empty when the model wrote nothing), `error` (the turn's last message failed; `error` says why), `waiting_on_user` (the turn ended on a question to the person), or `settled` (the run settled first; `outcome` says how). `.text({onDelta?})` is `collect`'s `text`. A reply can be consumed once.
-
-Several messages delivered in one turn, including a `start_turn: false` message that joined it, all resolve to that turn. To have a reply to the run's first message, pass it as `runs.start({prompt, message})` and follow `runs.reply(run.run_id, run.message!)`: a message stored with the run always joins the first turn. A refused or failed model call ends the turn with an empty `message.done` (`stop_reason: 'error'`) and `turn.completed.error`; the run stays usable, and `runs.get` shows the same error as `last_turn_error` until a later turn completes without one. A provider failure the runtime retries on its own (connection, rate limit, overloaded) does not end the reply: the recovery attempt continues the same turn, so the reply yields its answer and one `turn.completed` without an error, and only a turn whose retries run out ends with `model_error`. An interrupt, `runs.cancel`, or a closed node ends the turn with `stop_reason: 'aborted'` and no error. An expired cursor throws `APIError` with code `stream_gap`; aborting `signal` rejects with `APIUserAbortError`.
-
-## A quiet run: `event: idle`
-
-A runtime that sleeps when nothing holds a connection to it ends a run's SSE stream after 60 s in which the run has no running turn and no new event: it sends `event: idle` (`data: {}`) and closes. `RunStream` reports that and does not reconnect:
-
-```ts
-const stream = client.runs.events(runId, {after: cursor});
-for await (const event of stream) handle(event);
-const end = await stream.whenEnded(); // rejects on a transport failure or abort()
-if (end.reason === 'idle') {
-  // the run is quiet and nothing was missed; reopen later with client.runs.events(runId, {after: end.cursor})
-}
-```
-
-`stream.idle` and `stream.position` read the same facts synchronously. A settled run ends with `reason: 'settled'`; a transport error rejects as before. `runs.reply` reopens through an idle close on its own.
-
-## Typed run events
-
-`RunEvent`, exported by the SDK, is the union of every run event, discriminated on `type`. Its types are exactly the daemon's run event vocabulary, declared once. `RunEventOf<'node.turn.completed'>` picks one event, and `RunStream.on(type, listener)` passes the listener that event. An event type a newer daemon adds and this SDK does not declare is still delivered as-is.
+Streaming a run of an app (forwarding it to a browser, following the reply to one message, `event: idle`, typed run events) is on the SDK docs site: [Stream a run](https://sdk.docs.northlight.ai/docs/guides/stream-a-run).
 
 ## The SDK surface
 

package/dist/builtin-memory/northlight-apps/INDEX.md

@@ -0,0 +1,15 @@
+---
+kind: knowledge
+description: Building a third-party app on Northlight with @north-light/sdk — register it, sign people in, start runs on their runtime, call providers
+when-and-why-to-read: When you are building, debugging or shipping an app that signs people in with Northlight, starts runs on a person's Northlight runtime, or calls Northlight providers (sms, search, integrations, context, device) with @north-light/sdk, this reference should be read because the app runs on the developer's own server while its agent work runs on each person's runtime, and the sign-in, scope and connection rules differ from driving a local daemon with `new Crouter()`.
+short-form: The app-builder guide from sdk.docs.northlight.ai as pages — quick setup, concepts (sign-in, scopes and grants, connections, runs, testing mode, providers), guides, provider pages, errors and the CLI.
+surfaces:
+  - on: boot
+    at: name
+---
+
+# `northlight-apps/` — build an app on Northlight
+
+An app built on Northlight runs on the developer's own server. People sign in to it with Northlight, its agent work runs on each person's Northlight-hosted runtime, and it can call that person's providers. Northlight does not host the app. The app uses `OAuth2Client` and `oauth.client(userId)` from `@north-light/sdk`, never `new Crouter()`, which drives a daemon you run yourself (`crouter-sdk/`).
+
+Start at `northlight-apps/quickstart` for the path from a new account to a running app, then `northlight-apps/how-it-fits` for where each part runs. The directory listing names every page. The same pages are published at https://sdk.docs.northlight.ai, where the generated API reference also lives.

package/dist/builtin-memory/northlight-apps/cli.md

@@ -0,0 +1,41 @@
+---
+kind: knowledge
+when-and-why-to-read: When you need CLI reference, this knowledge should be read
+  because The npx @north-light/sdk commands for scaffolding an app, writing its
+  signing key and environment file, and installing the agent skill.
+---
+
+# 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. An unknown command prints the list and exits 1.
+
+| Command | What it does | Needs crtr |
+|---|---|---|
+| `npx @north-light/sdk init [dir] [--agent claude\|agents\|all] [--global-skill]` | Scaffold a Northlight app in an empty or new directory (server.ts, key, env file, skill), or add the SDK, a key and the skill to an existing project. Never overwrites a file. | No |
+| `npx @north-light/sdk skill [--agent claude\|agents\|all] [--global] [--print]` | Write the packaged `northlight` skill into `.agents/skills` and `.claude/skills` (or `~/` with `--global`), replacing an older copy. `--print` writes it to stdout. | No |
+| `npx @north-light/sdk keygen [--out <path>] [--app <client id>] [--yes]` | Write a private signing key to `local/app-key.json` (mode 0600) and print the public JWK to register. | Only with `--app` |
+| `npx @north-light/sdk env --client-id <client id> [--origin <url>] [--issuer <url>] [--out <path>]`<br/>`npx @north-light/sdk env --app <client id> [--out <path>]` | Write `CROUTER_ISSUER`, `CROUTER_CLIENT_ID` and `APP_ORIGIN` into `local/app.env`, keeping every other line. `--client-id` makes no network call; `--app` reads them through crtr. | Only with `--app` |
+
+`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.
+
+## Details
+
+### `init`
+
+In an empty or new directory it writes `package.json` (with `@north-light/sdk` pinned to the CLI's own exact version, plus `tsx`), `server.ts` (the quickstart server), `.gitignore` (`local/`, `node_modules/`) and `local/app.env`, and runs `keygen` into `local/app-key.json`. It installs the skill. Then it prints the public JWK, the console URL `https://account.northlight.ai/console/new`, the values to type, and `npx @north-light/sdk env --client-id <client id>` as the next step.
+
+In a directory that already has a `package.json` it writes no app code. It runs `npm i --save-exact @north-light/sdk@<its own version>`, runs `keygen` unless `local/app-key.json` exists, and installs the skill.
+
+It never overwrites a file. On a refused step it exits non-zero and names the file it refused.
+
+### `skill`
+
+Writes the `northlight` Agent Skill that ships in the package, replacing an older copy. `--agent` picks `.claude/skills`, `.agents/skills` or both. `--global` writes under your home directory instead of the project. The skill's `metadata.sdk-version` is the package version, so run `skill` again after you change the pinned SDK version.
+
+### `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.
+
+### `env`
+
+`env --client-id <client id>` writes `CROUTER_ISSUER` (default `https://account.northlight.ai`), `CROUTER_CLIENT_ID` and `APP_ORIGIN` (default: the existing value in the file, else `http://localhost:3000`) into `local/app.env`. It keeps every other line and makes no network call. `--out <path>` writes another file. `env --app <client id>` reads the same values through crtr instead. Passing both `--client-id` and `--app` is a usage error.

package/dist/builtin-memory/northlight-apps/coding-agents.md

@@ -0,0 +1,75 @@
+---
+kind: knowledge
+when-and-why-to-read: When you need Use your coding agent, this knowledge should
+  be read because What npx @north-light/sdk init and skill install for Claude
+  Code, Codex, Cursor and Copilot, where the skill lives, and how it stays in
+  step with your SDK version.
+---
+
+# Use your coding agent
+
+The `northlight` skill teaches a coding agent the whole path in the [[northlight-apps/quickstart]]: the commands, the console fields, the code patterns and the rules. `npx @north-light/sdk init` installs it into your project. The skill needs no account and no crtr.
+
+## Install it
+
+For a new app, `init` installs it with everything else:
+
+```bash
+npx @north-light/sdk@latest init my-app
+```
+
+For a project that already has a `package.json`, run `npx @north-light/sdk init` in it. It adds `@north-light/sdk` at an exact version, makes a key if `local/app-key.json` does not exist, installs the skill, and writes no app code. It never overwrites a file: if one is in the way, it names the file and exits non-zero.
+
+To install only the skill, or to replace an older copy:
+
+```bash
+npx @north-light/sdk skill
+```
+
+`skill` always replaces the `northlight` skill it finds. `--print` writes the skill to stdout instead of to files.
+
+## Where it goes
+
+| Agent | In the project (default) | With `--global` |
+|---|---|---|
+| Codex, Cursor, GitHub Copilot, VS Code | `.agents/skills/northlight/SKILL.md` | `~/.agents/skills/northlight/SKILL.md` |
+| Claude Code | `.claude/skills/northlight/SKILL.md` | `~/.claude/skills/northlight/SKILL.md` |
+
+`--agent claude`, `--agent agents` or `--agent all` (the default) picks which. `all` writes both places. Cursor and Copilot also read `.claude/skills`, so they may list the skill twice. Use `--agent agents` or `--agent claude` to write one place. `init` takes `--global-skill` where `skill` takes `--global`.
+
+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: the files `init` writes, and that `skill` rewrites both, from the SDK source built on this branch. Which agent loads which directory is from each agent's documentation and is not yet checked on production for every agent.
+
+## Without a project: the hosted skill
+
+An agent that has no project yet can read the hosted copy:
+
+> Read https://sdk.docs.northlight.ai/SKILL.md and follow it.
+
+The agent runs `npx @north-light/sdk@latest init` and then follows the quick setup. It asks you to do the browser steps: sign up, register the app at `https://account.northlight.ai/console/new`, and add permissions. The hosted copy matches the SDK version the docs site was last built from.
+
+## How it stays current
+
+The skill's frontmatter carries `metadata.sdk-version`. Its first instruction tells the agent to compare that number with `node_modules/@north-light/sdk/package.json`. If they differ, the agent runs `npx @north-light/sdk skill`, which rewrites the skill from the installed package. A skill therefore always documents the SDK your project pins, and a newer SDK never gets documented against an older one.
+
+## Example prompts
+
+After `init`:
+
+> Add a "Summarize my day" button to the app. It starts a run on the signed-in person's runtime with `runs.start`, waits with `runs.wait`, and shows the report. Use the northlight skill.
+
+Starting from nothing:
+
+> Read https://sdk.docs.northlight.ai/SKILL.md and build me an app where people sign in with Northlight and the app texts them a daily summary. Tell me which console steps I need to do.
+
+## Rules the skill gives your agent
+
+Your agent reads them from the skill. They are worth knowing as the person reviewing its work:
+
+- Pin the exact SDK version.
+- Take scope strings from the console's Add permissions list, never from memory.
+- Never print, paste or commit `local/app-key.json`.
+- Reach a person's runtime with `oauth.client(userId)`, not `new Crouter()`.
+- Use a persistent `ConnectionStore` in production.
+- Get data back with `runs.parse`, not by reading `runs.trace`.

package/dist/builtin-memory/northlight-apps/concepts/apps-and-sign-in.md

@@ -0,0 +1,109 @@
+---
+kind: knowledge
+when-and-why-to-read: When you need Apps and sign-in, this knowledge should be
+  read because What registering an app creates, how an app proves who it is with
+  a key pair, and the authorization-code flow with PKCE that OAuth2Client runs.
+---
+
+# Apps and sign-in
+
+An app is a registration in the Northlight directory: a client ID, a public signing key, the redirect URIs people return to after sign-in, and the list of scopes the app may ask for. You create it in the console at `https://account.northlight.ai/console/new`. Your server proves it is that app by signing its requests with the matching private key.
+
+## What registration holds
+
+| Part | What it is |
+|---|---|
+| **Client ID** | The app's id. The console shows it after you register. Your code passes it as `clientId`. |
+| **Origin URL** | Where your app runs. People see its domain as your app's maker. `http://localhost:<port>` is accepted for development. |
+| **Redirect URIs** | The only places sign-in may return to. A URI must match exactly: `localhost` and `127.0.0.1` are different, and the port counts. `http://localhost`, `http://127.0.0.1` and `http://[::1]` are accepted over plain http; every other URI is `https`. |
+| **Public key** | The half of your key pair the directory keeps. |
+| **Scopes** | What the app may ask for. See [[northlight-apps/concepts/scopes-and-grants]]. |
+
+Name, logo and "Why your app needs access" appear on the consent page.
+
+## A key pair, not a client secret
+
+An app has no client secret. It signs a short assertion with its private key (`private_key_jwt`, the only token authentication method the directory supports) each time it exchanges a code or refreshes a token. The directory checks the signature against the public keys it holds.
+
+- `npx @north-light/sdk keygen` writes the private key to `local/app-key.json` (mode `0600`) and prints the public key as JSON. `init` runs it for you. Paste the public key into **Public key** when you register, or under **Add key** on the app's **Sign-in** tab.
+- The private key stays on your server. Never paste it, log it or commit it. The console refuses a pasted private key.
+- An app holds at most 2 active keys, so you can add a new one beside the old one, switch, and retire the old one without downtime.
+- Instead of pasting keys you can give the directory a **JWKS URL** (**Use a JWKS URL instead** on the **Sign-in** tab).
+- Until a key is added, `exchangeCode` throws an `AuthenticationError`.
+
+## The sign-in flow
+
+`OAuth2Client` runs the OAuth 2.0 authorization-code flow with PKCE (`S256`) and an OpenID Connect nonce. Your two routes are short:
+
+```ts
+if (url.pathname === '/auth/login') {
+  const {url: authorizeUrl, codeVerifier, state, nonce} = await oauth.authorizeUrl({
+    scopes: ['openid', 'profile', 'crtr:llm', 'crtr:act', 'sms:send'],
+    state: randomBytes(16).toString('base64url'),
+  });
+  pending.set(state, {codeVerifier, nonce});
+  return void res.writeHead(303, {location: authorizeUrl}).end();
+}
+```
+
+`authorizeUrl` returns the URL to redirect to, plus three values to keep for this sign-in: `codeVerifier`, `state` and `nonce`. The example keeps them in a `Map` keyed by `state`. Use your own session store.
+
+```ts
+if (url.pathname === '/auth/callback') {
+  if (authorizationRefusalOf(url)?.code === 'app_in_testing') {
+    return page(res, 403, '<h1>This app is still in testing</h1><p>Ask its owner to add you on the Testers tab in the console.</p>');
+  }
+  const state = url.searchParams.get('state') ?? '';
+  const code = url.searchParams.get('code');
+  const saved = pending.get(state);
+  if (!saved || !code) return page(res, 400, '<p>Start sign-in again at <a href="/auth/login">/auth/login</a>.</p>');
+  pending.delete(state);
+  const connection = await oauth.exchangeCode({code, codeVerifier: saved.codeVerifier, state, expectedState: state, nonce: saved.nonce});
+  await store.save(connection);
+  const sid = randomBytes(16).toString('base64url');
+  sessions.set(sid, connection.userId);
+  return void res.writeHead(303, {location: '/', 'set-cookie': `sid=${sid}; HttpOnly; SameSite=Lax; Path=/`}).end();
+}
+```
+
+On the callback:
+
+1. Read `state` and `code` from the query. Find what you saved for that `state`. If nothing is there, send the person back to the login route.
+2. Call `exchangeCode` with the code, the saved `codeVerifier` and `nonce`, the `state` from the query as `state`, and the value you saved as `expectedState`. Never pass the callback's `state` for both. A missing or different `expectedState` throws `CrouterError` with code `oauth_state_mismatch` before the code is sent anywhere.
+3. `exchangeCode` verifies the ID token (ES256 signature, issuer, audience and nonce) when it has one, and returns a `Connection`. Save it in your [[northlight-apps/concepts/connections]].
+
+Then set your own session for the person. The SDK does not manage your sessions.
+
+### Scopes decide what comes back
+
+A sign-in that asks only for `openid`, optionally with `email` and `profile`, creates no connection. Finish it with `oauth.exchangeIdentity(...)`, which returns the verified `Identity` (`sub`, and `email`, `name` and `picture` when approved and present). A sign-in that asks for runtime scopes such as `crtr:llm` finishes with `exchangeCode`. Each method refuses the other's answer with `oauth_exchange_mismatch`.
+
+### When the directory refuses to sign someone in
+
+If the app is in testing and the person is not a tester, the directory redirects to your callback with `error=access_denied` and `error_description=app_in_testing` instead of a `code`. `authorizationRefusalOf(url)` reads it. See [[northlight-apps/concepts/testing-mode]].
+
+## Keep sign-in secrets out of HTTP logs
+
+The callback URL carries a one-use `code` and your `state`, and the response that follows carries a session cookie. Request loggers such as `pino-http` log full URLs and response headers by default. Log the method, the path without the query string, an id and the response status, for every route, not only the callback. Redacting only the `authorization` and `cookie` request headers does not cover these values.
+
+```ts
+LoggerModule.forRoot({
+  pinoHttp: {
+    serializers: {
+      req: (req: { method?: string; url?: string; id?: unknown }) => ({
+        method: req.method,
+        path: req.url?.split('?')[0],
+        id: req.id,
+      }),
+      res: (res: { statusCode?: number }) => ({ statusCode: res.statusCode }),
+    },
+    redact: ['req.headers.authorization', 'req.headers.cookie'],
+  },
+});
+```
+
+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 with a real account is not yet checked on production.

package/dist/builtin-memory/northlight-apps/concepts/connections.md

@@ -0,0 +1,109 @@
+---
+kind: knowledge
+when-and-why-to-read: When you need Connections, this knowledge should be read
+  because A connection is the stored token set for one person. How
+  ConnectionStore keeps it, how it refreshes, and what to do when the directory
+  refuses a refresh.
+---
+
+# Connections
+
+A connection is what your server stores for one person after they sign in: their user id, the URL of their runtime, a refresh token, and a short-lived access token. `oauth.client(userId)` loads it and gives you a client on that person's runtime. You keep connections in a `ConnectionStore`.
+
+```ts
+const connection = await oauth.exchangeCode({code, codeVerifier, state, expectedState, nonce});
+await store.save(connection);
+
+// Later, in any process that shares the store:
+const runtime = await oauth.client(connection.userId);
+```
+
+Access tokens last 10 minutes. Refresh tokens rotate on every use and expire after 90 days without one. `oauth.client(userId)` refreshes the access token when it needs to. When nothing is stored for the id it throws `CrouterError` with code `not_connected`: send the person through sign-in again.
+
+## The store
+
+`ConnectionStore` has `load(userId)`, `save(connection)`, `lock(userId, fn)` and `remove(userId, refreshToken)`, and may have `listStale(before)`.
+
+- `MemoryConnectionStore` keeps connections in one process. Use it for development and tests. Every sign-in is lost when the process restarts, and its lock does not reach other processes.
+- `PostgresConnectionStore` from `@north-light/sdk/stores/postgres` is the production store. Install `pg` in your app. It locks across every process that shares the database.
+
+```ts
+import {Pool} from 'pg';
+import {PostgresConnectionStore} from '@north-light/sdk/stores/postgres';
+
+const store = new PostgresConnectionStore(new Pool({connectionString: process.env.DATABASE_URL}), {table: 'connection'});
+```
+
+Create the table first:
+
+```sql
+CREATE TABLE connection (
+  user_id text PRIMARY KEY,
+  runtime_url text NOT NULL,
+  refresh_token text NOT NULL,
+  grant_id text NOT NULL,
+  access_token text NOT NULL,
+  access_token_expires_at timestamptz NOT NULL,
+  id_token text,
+  updated_at timestamptz NOT NULL DEFAULT clock_timestamp()
+);
+CREATE INDEX connection_updated_at_idx ON connection (updated_at, user_id);
+```
+
+The table holds credentials. Restrict database access and encrypt backups. All workers must use the same database. The store holds an advisory lock for the whole refresh, so size the pool for concurrent refreshes and do not set a transaction timeout shorter than a token request.
+
+### Why the lock matters
+
+Two processes refreshing one person at once would spend the same refresh token twice, and the directory ends the grant's refresh tokens when it sees that (`refresh_token_reused`). `lock` makes the SDK reload the connection, refresh only if no other process already did, and save the result while it holds the lock. If you write your own store, `lock` must hold across every process that shares it and commit what `fn` wrote when `fn` resolves.
+
+## When a refresh is refused
+
+When the directory refuses to refresh a stored connection, the SDK runs your `onRefusal(refusal)` once the lock is released, then removes the stored connection, then rejects the call that needed the refresh with an `AuthenticationError` (status 401, `userAction: 'reconnect'`). Handle every dead connection in that one place:
+
+```ts
+const oauth = new OAuth2Client({
+  clientId, privateKey, redirectUri, issuer, store,
+  onRefusal: async ({kind, userId}) => {
+    if (kind === 'removed') await forgetUser(userId);      // the runtime already deleted the app's runs
+    else if (kind === 'paused') await markPaused(userId);  // keep everything
+    else await askToSignIn(userId);                        // keep everything
+  },
+});
+
+// In a request handler, answer the one request:
+try { await (await oauth.client(userId)).runs.start({prompt}); }
+catch (error) { if (refusalOf(error)) return showSignInAgain(); throw error; }
+```
+
+A `Refusal` is `{kind, code, userId, grantId, error}`. **Delete what you keep for a person only on `grant_removed`** (`kind: 'removed'`). On every other code, keep it.
+
+| `code` | `kind` | What happened | What your app does |
+|---|---|---|---|
+| `grant_removed` | `removed` | The person removed your app or deleted their account. The runtime has deleted your app's space, runs, schedules and shares. | You may delete what you keep for that person. Do not call `runs.delete`; the runs are gone. If they connect again, they see the consent page and start fresh. |
+| `grant_suspended` | `paused` | Your app's access for that person is paused. Nothing was deleted. | Keep everything, stop calling for them, show the app as paused. If they connect again, the same grant comes back. |
+| `app_in_testing` | `paused` | Your app is in testing and this person is not a tester (they were removed, or their email or phone stopped matching). The grant is revoked, not removed. | Keep everything, stop calling for them, and tell them the developer must add them. If you add them back and they sign in again, the same space returns. |
+| `refresh_token_expired` | `reconnect` | The refresh token went 90 days unused. The grant is still active. | Keep everything. Run sign-in again; the consent page is skipped. Prevent it with `refreshIdleConnections`. |
+| `refresh_token_reused` | `reconnect` | Two processes raced on one refresh token. | Keep everything. Fix the store's `lock`, then reconnect. |
+| `grant_revoked` | `reconnect` | The directory refused without naming a reason. | Keep everything and reconnect. Never delete data on this code. |
+
+`onRefusal` runs at least once per dead connection, so make it idempotent. If it throws, the connection stays stored, the caller still receives the directory's refusal, and the next use calls the handler again. It must not call the runtime for `refusal.userId`: `oauth.client(userId)` for that user inside the handler throws `CrouterError` code `refusal_handler_reentry`.
+
+`refusalOf(error)` returns a `Refusal` only for an error raised while refreshing a stored connection. A 429, `cap_exhausted`, `scope_missing`, or an `invalid_client` refusal of your app's key is not a refused connection, and `refusalOf` returns `null` for it.
+
+## Keep offline people connected
+
+A refresh token expires after 90 days without use. Run a worker, for example daily, that calls:
+
+```ts
+await oauth.refreshIdleConnections({olderThanMs: 30 * 24 * 60 * 60 * 1000});
+```
+
+It refreshes every connection last saved before the cutoff, through the store's lock, and returns `{refreshed, refused, failures}`. A refused connection goes through `onRefusal` and is removed. `failures` holds connections that could not be refreshed and are still stored; the next run retries them. The SDK starts no timer. The store needs `listStale(before)`, which both `MemoryConnectionStore` and `PostgresConnectionStore` have.
+
+## 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, 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/dist/builtin-memory/northlight-apps/concepts/providers.md

@@ -0,0 +1,76 @@
+---
+kind: knowledge
+when-and-why-to-read: When you need Providers, this knowledge should be read
+  because A provider is a service the person's runtime calls for your app.
+  Provider scopes, providers.tools, providers.call, and apps that require a
+  provider.
+---
+
+# Providers
+
+A provider is a service that a person's runtime calls on your app's behalf: sending a text, searching the web, reading their connected accounts, or using their device. Northlight runs the first-party providers (sms, search, integrations, context and device). Your server asks the person's runtime to call one with `providers.call`.
+
+## Scopes
+
+Each provider's tools are grouped, and each group is a scope named `<provider>:<group>`. The `sms` provider has one: `sms:send`. Your app can call a provider only if all three of these hold:
+
+1. The scope is on the app's **What it asks for** list (console → **Add permissions**).
+2. Your sign-in requested it (`authorizeUrl({scopes: […]})`).
+3. The person approved it on the consent page.
+
+Take scope strings from the **Add permissions** list. Do not guess them. [[northlight-apps/providers/README]] lists the first-party providers.
+
+## Find the tools, then call one
+
+`providers.tools('<provider>')` lists the tools the person has granted your app, with their descriptions and parameters. Tool names and arguments come from there, never from memory:
+
+```ts
+import type {ConnectedCrouter} from '@north-light/sdk';
+
+/** List the tools a provider offers this person, then call one. Scope strings come from the console's
+ *  "Add permissions" list; tool names and arguments come from `providers.tools`. Never invent either. */
+export async function textMe(runtime: ConnectedCrouter, body: string) {
+  const sms = await runtime.providers.tools('sms');
+  console.log(JSON.stringify(sms.groups, null, 2)); // each leaf: tool, description, params
+
+  return runtime.providers.call({provider: 'sms', tool: 'send', arguments: {body}});
+}
+```
+
+`providers.call({provider, tool, arguments})` makes the call and returns the tool's output. The quickstart sends a text this way:
+
+```ts
+// Texts the signed-in person's own verified phone through the sms provider (50 per person per UTC day).
+const sent = await runtime.providers.call({provider: 'sms', tool: 'send', arguments: {body: 'Hello from my first Northlight app.'}});
+```
+
+`send` takes a required `body` and an optional `file`. It has no recipient argument: it texts the verified phone of the person who signed in to your app, from Northlight's number, at most 50 texts per person per UTC day. Calling `providers.tools()` with no provider lists every provider the person's runtime can reach.
+
+A call is refused when the scope is missing from the grant. The refusal is an `APIError` whose code says why (`scope_missing` for a scope the run or grant lacks).
+
+## Providers your app requires
+
+Some apps do not work until a provider is set up for the person. Name it under **What your app requires** on the **What it asks for** tab. The person is then taken through that provider's setup the first time they sign in. Context, for example, asks for a profile URL, and its state stays `pending` for a few minutes afterwards.
+
+Read the state on each request that depends on it. `runtime.grant.get()` returns `dependencies`, one entry per required provider, keyed by provider id (or `{}` when the app requires none):
+
+```ts
+const {dependencies} = await runtime.grant.get();
+const context = dependencies['context']; // {state, message?, next} or undefined
+if (context?.state !== 'ready') {
+  // Show context.message and link context.next; never hard-code either.
+}
+```
+
+| `state` | Meaning |
+|---|---|
+| `not_started` | The person has not done their part. |
+| `pending` | The provider is working. |
+| `ready` | Calls that depend on it work. |
+| `failed` | Setup failed. `message` says why. |
+
+`message` is the provider's own sentence, present for `pending` and `failed`. `next` is the absolute URL of the setup page for this provider and your app; add a `return_to` query parameter with your app's registered origin so the person returns to you. 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 [[northlight-apps/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 is not yet checked.

package/dist/builtin-memory/northlight-apps/concepts/runs.md

@@ -0,0 +1,101 @@
+---
+kind: knowledge
+when-and-why-to-read: When you need Runs, this knowledge should be read because
+  A run is an agent working on the person's runtime, with their AI subscription,
+  under the grant's scopes. Status, outcome, result, activity, and how to bound
+  one.
+---
+
+# Runs
+
+A run is an agent that works on a person's Northlight runtime, on your behalf and with their AI subscription, under the scopes of their grant. Your server starts it with `runs.start`, and the run keeps going on the runtime whether or not your server is waiting.
+
+```ts
+const runtime = await oauth.client(userId); // a client on this person's runtime, from their stored connection
+const started = await runtime.runs.start({prompt: 'Reply with exactly the word: pong', scopes: ['crtr:llm', 'crtr:act']});
+const run = await runtime.runs.wait(started.run_id); // status is 'idle' once the reply is done
+```
+
+`runs.start` returns at once with a `run_id`. `runs.wait(runId)` long-polls until the run is no longer `running`.
+
+## Status
+
+`RunObject.status` is one of:
+
+| `status` | Meaning |
+|---|---|
+| `running` | The run's root agent is working. |
+| `waiting_on_user` | The agent asked the person a question (`pending_question_ids` lists them). |
+| `idle` | The agent finished a turn and is waiting. A reply to your prompt leaves the run `idle`. Send `runs.message` for another turn, or `runs.cancel` to end it. |
+| `settled` | The run has ended. `outcome` says how. |
+
+`runs.wait` returns on `waiting_on_user`, `idle` and `settled`, so check the status before you read a result.
+
+## Outcome and result
+
+A `settled` run has an `outcome`:
+
+| `outcome.kind` / `reason` | Meaning |
+|---|---|
+| `result` | The run finished. If you passed an `output_schema`, `result` holds the validated value. |
+| `declined` | The agent could not honestly satisfy the schema. `details` has `reason`, `code` and `retryable`. |
+| `canceled` | You or the person ended it. |
+| `deadline_exceeded` | A deadline ended it. |
+| `runtime_error` | The runtime failed. `details.crouter_reason` says why. |
+
+`last_report` is the agent's last report text. To get data back, give the run an `output_schema` and read it with `runs.parse`: see [[northlight-apps/guides/typed-results]]. Do not parse the assistant's text out of `runs.trace`. The trace is what the model said, not a value anything checked.
+
+## Scopes
+
+`runs.start({prompt, scopes})` starts the run with only those scopes. `crtr:llm` goes in every run. See [[northlight-apps/concepts/scopes-and-grants]].
+
+## Showing progress
+
+While a run is `running`, `runs.get(runId).activity` says what the root agent is doing now. It is `null` in any other status.
+
+| `phase` | The root agent is |
+|---|---|
+| `starting` | launching; its first turn has not begun |
+| `thinking` | reasoning, or waiting on the model before any output |
+| `tool` | calling a tool: `tool.name`, and `tool.summary` (the command's first line or the path it acts on) |
+| `submitting_result` | writing or recording its `output_schema` result |
+| `writing` | streaming its answer text |
+| `between_turns` | between turns while the run still works: a child agent is running, a message is about to start the next turn, or the runtime is reminding it to submit its result |
+
+```ts
+const run = await runtime.runs.get(runId);
+const badge = run.activity?.phase === 'tool' ? `Running ${run.activity.tool.name}` : run.activity?.phase ?? run.status;
+```
+
+`activity` covers the root agent only and is read each time you call `runs.get`, so a phase shorter than your poll interval can be missed. To show text as it streams, follow `runs.events` or `runs.reply` instead of polling. Do not read `runs.trace` for progress.
+
+## Bounding a run
+
+`runs.wait` and `runs.parse` take a `signal`. When it aborts, the helper rejects with the signal's reason and leaves the run alone. Call `runs.cancel` if you want the run ended:
+
+```ts
+const controller = new AbortController();
+const timer = setTimeout(() => controller.abort(new Error('took too long')), 10 * 60_000);
+let runId: string | undefined;
+try {
+  const started = await runtime.runs.start({prompt, scopes: ['crtr:llm']});
+  runId = started.run_id;
+  const run = await runtime.runs.wait(runId, {signal: controller.signal});
+  // read run.status, run.outcome, run.result
+} catch (error) {
+  if (controller.signal.aborted && runId) await runtime.runs.cancel(runId);
+  throw error;
+} finally {
+  clearTimeout(timer);
+}
+```
+
+`runs.parse` rejects with `APIError` code `run_idle` when the agent stopped without submitting a result. The runtime reminds the agent of the schema up to three times, then leaves the run `idle` with the schema still armed. Send `runs.message` to nudge it, or `runs.cancel` to end it. A question from the run rejects with `waiting_on_user` unless you pass `onQuestion`.
+
+## 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 [[northlight-apps/guides/background-runs]].
+
+## Checked and not checked
+
+From the SDK source and its tests. The `runs.start`, `runs.wait` and `activity` behavior against a real runtime on production is not yet checked.