@north-light/cli 0.3.472 → 0.3.474

package/dist/builtin-memory/crouter-sdk/release-notes.md

@@ -73,28 +73,28 @@ The SDK no longer refuses a runtime because its release number is lower than the
 
 Not breaking: no type or wire shape an app reads is removed or changed.
 
-- An app Northlight has not verified is in testing: only its admin and named testers can sign in. A refused sign-in redirects with `error=access_denied`, `error_description=app_in_testing`; a refused refresh answers `invalid_grant` `app_in_testing`. The refresh refusal is a new `Refusal` with `code: 'app_in_testing'` and `kind: 'paused'`, like `grant_suspended`: keep the person's data. If you `switch` exhaustively on `refusal.code`, add the case. See [[crouter-sdk/client]].
-- New `authorizationRefusalOf(callback)` reads the sign-in refusal from the callback's query and returns `AuthorizationRefusal` (`{code: 'app_in_testing', error: 'access_denied', state}`), else `null`. See [[crouter-sdk/client]].
-- `@north-light/sdk/testing`: `cloud.testing` (`enable`, `disable`, `active`, `addTester`, `removeTester`, `testers`, `allowed`), `cloud.authorize(userId, {redirectUri, state})`, `user.setAccount({email, emailVerified, phone})`, and `'app_in_testing'` in `FakeRefusalCode`. The fake directory now serves `grant_type=authorization_code` for codes `cloud.authorize` issued. See [[crouter-sdk/testing]].
+- An app Northlight has not verified is in testing: only its admin and named testers can sign in. A refused sign-in redirects with `error=access_denied`, `error_description=app_in_testing`; a refused refresh answers `invalid_grant` `app_in_testing`. The refresh refusal is a new `Refusal` with `code: 'app_in_testing'` and `kind: 'paused'`, like `grant_suspended`: keep the person's data. If you `switch` exhaustively on `refusal.code`, add the case. See [When a refresh is refused](/docs/concepts/connections#when-a-refresh-is-refused).
+- New `authorizationRefusalOf(callback)` reads the sign-in refusal from the callback's query and returns `AuthorizationRefusal` (`{code: 'app_in_testing', error: 'access_denied', state}`), else `null`. See [When sign-in is refused](/docs/concepts/apps-and-sign-in#when-the-directory-refuses-to-sign-someone-in).
+- `@north-light/sdk/testing`: `cloud.testing` (`enable`, `disable`, `active`, `addTester`, `removeTester`, `testers`, `allowed`), `cloud.authorize(userId, {redirectUri, state})`, `user.setAccount({email, emailVerified, phone})`, and `'app_in_testing'` in `FakeRefusalCode`. The fake directory now serves `grant_type=authorization_code` for codes `cloud.authorize` issued. See [Testing mode](/docs/guides/test-your-app#testing-mode).
 
 ## 0.3.415
 
 ### Monthly spend cap enforced; `usage.get` (additive; one behavior change)
 
 - **Behavior change:** user-paid model calls (`/v1/llm`) and provider calls now count against the grant's `spend_cap` (from `grant.get()`; Northlight sets $50) for the current UTC month. Once the month reaches it, the next call answers 402 `cap_exhausted` (a `RateLimitError`, `retryable: false`, `userAction: 'raise_cap'`, `resetAt` the first instant of next month) before any model or provider is called. A run whose model call is refused this way ends with outcome reason `cap_exhausted`. The check runs before each call, so the call that crosses the cap still completes. App-paid usage never counts. A grant with `spend_cap: null` is not capped.
-- New `client.usage.get({month?})` (`month` is `YYYY-MM`, UTC; default the current month) answers `SpendUsageDTO`: `usd_equivalent` (user-paid spend, provider receipts included), `by_model`, `app_paid`, `spend_cap` and `reset_at`. See [[crouter-sdk/client]].
+- New `client.usage.get({month?})` (`month` is `YYYY-MM`, UTC; default the current month) answers `SpendUsageDTO`: `usd_equivalent` (user-paid spend, provider receipts included), `by_model`, `app_paid`, `spend_cap` and `reset_at`. See [Show what a person's month has cost](/docs/guides/grant-changes#show-what-a-persons-month-has-cost).
 - A completion's `usage.usd_equivalent` is now the served model's list-price cost; before it was always `null`. It stays `null` for a model with no list price, and that usage adds nothing to the month.
 
 ### `npx @north-light/sdk env` (additive); keygen on an unjoined machine exits 2
 
-- New `npx @north-light/sdk env --app <client id> [--out <path>]` writes `CROUTER_ISSUER`, `CROUTER_CLIENT_ID` and `APP_ORIGIN` from `crtr cloud apps get` into `local/app.env`, keeping every other line. See [[crouter-sdk/getting-started]].
+- New `npx @north-light/sdk env --app <client id> [--out <path>]` writes `CROUTER_ISSUER`, `CROUTER_CLIENT_ID` and `APP_ORIGIN` from `crtr cloud apps get` into `local/app.env`, keeping every other line. See [Go live with an app key](/docs/guides/go-live).
 - `keygen --app` on a machine whose `crtr` isn't joined to a Northlight account now prints the join step and the manual steps and exits 2. A missing `crtr` keeps its message and exit 0.
 
 ### One deadline per SDK call, and a deadline on every OAuth/JWKS fetch (additive, with one behaviour change)
 
 Not breaking: no type or wire shape an app reads is removed or changed. Apps pinned to the previous release keep working unchanged.
 
-- `RequestOptions` gains `budgetMs` and `deadlineAt`: one absolute deadline for the call covering every attempt, every retry wait (including a `Retry-After`) and the token fetch/refresh. A wait that would pass the deadline rejects at once with the new `DeadlineExceededError` (`code: 'deadline_exceeded'`, `reason: 'elapsed' | 'retry_after'`, `deadlineAt`, `cause`), which extends `APIConnectionTimeoutError`, so code catching that still catches it. A transport that ignores its `AbortSignal` can no longer outlive the deadline. Without `budgetMs`/`deadlineAt` nothing about retries changes. See [[crouter-sdk/client]].
+- `RequestOptions` gains `budgetMs` and `deadlineAt`: one absolute deadline for the call covering every attempt, every retry wait (including a `Retry-After`) and the token fetch/refresh. A wait that would pass the deadline rejects at once with the new `DeadlineExceededError` (`code: 'deadline_exceeded'`, `reason: 'elapsed' | 'retry_after'`, `deadlineAt`, `cause`), which extends `APIConnectionTimeoutError`, so code catching that still catches it. A transport that ignores its `AbortSignal` can no longer outlive the deadline. Without `budgetMs`/`deadlineAt` nothing about retries changes. See [One deadline per call](/docs/errors#retries).
 - An app that holds a lease or lock while it makes an SDK call should pass `budgetMs` and keep the lease longer than it, with margin, and state that in code.
 - `OAuth2Options.timeoutMs` (default 10 s): one deadline per directory operation (discovery, token exchange, refresh, revoke, `runtime_provisioning` retries and their `retry_after_s`). A refresh under the connection-store lock now holds the lock at most `timeoutMs`. `JwksCache` (and so `verifyIdToken`) takes `{timeoutMs}` (default 10 s) over its discovery and key-set reads together.
 - **Behaviour change:** these directory fetches used to have no deadline (only discovery had one). A directory that takes longer than 10 s now fails with `DeadlineExceededError` where it used to wait; set `timeoutMs` to change it.
@@ -114,11 +114,11 @@ Not breaking: no type or wire shape an app reads is removed or changed. Apps pin
 
 ### `@north-light/sdk/testing` (additive)
 
-New `@north-light/sdk/testing`: `FakeCloud`, a fake directory and runtime your real `OAuth2Client` and `Crouter` talk to through `fetch`. It covers runs (events, replies, long-poll, idempotency, endings), grant watch, refusals, directory failures, memory, providers and run notices, and is checked against the real runtime on every release. Additive: `verifyRunNotice` accepts `fetch`. No behaviour change. See [[crouter-sdk/testing]].
+New `@north-light/sdk/testing`: `FakeCloud`, a fake directory and runtime your real `OAuth2Client` and `Crouter` talk to through `fetch`. It covers runs (events, replies, long-poll, idempotency, endings), grant watch, refusals, directory failures, memory, providers and run notices, and is checked against the real runtime on every release. Additive: `verifyRunNotice` accepts `fetch`. No behaviour change. See [Testing your app](/docs/guides/test-your-app).
 
 ### `oauth.accountAppUrl()` (additive), and a failed discovery read is retried (behaviour fix)
 
-- New `OAuth2Client.accountAppUrl()` returns the app's page on the signed-in person's Northlight account, as the directory's discovery document advertises it (`account_app_uri_template`). Use it instead of building `<issuer>/account/apps/<client id>` yourself. It needs no user or connection and throws `CrouterError` naming the fault when the directory advertises no template or an invalid one. See [[crouter-sdk/client]].
+- New `OAuth2Client.accountAppUrl()` returns the app's page on the signed-in person's Northlight account, as the directory's discovery document advertises it (`account_app_uri_template`). Use it instead of building `<issuer>/account/apps/<client id>` yourself. It needs no user or connection and throws `CrouterError` naming the fault when the directory advertises no template or an invalid one. See [Link to the app's settings on Northlight](/docs/guides/grant-changes#link-to-the-apps-settings-on-northlight).
 - **Behaviour fix:** `OAuth2Client`'s discovery read now times out after 10 seconds, and a read that failed or timed out is retried by the next call that needs it. Before, one failed read was kept for the client's life, so every later `authorizeUrl`, `exchangeCode`, refresh and `verifyIdToken` failed until the process restarted, and a hung directory stalled them indefinitely. A successful read is still kept for the client's life.
 
 ## 0.3.405
@@ -169,25 +169,25 @@ The runtime gains what a sandbox that sleeps needs; no app-facing type or route
 
 ### Follow a person's grant with `oauth.watchGrants` (additive)
 
-`grant.get()` answers a new field, `version`: opaque, it changes exactly when `rev`, `resolved_scopes`, `spend_cap`, `payer` or `dependencies` changes. `grant.get({wait, since})` (`wait` an integer 1–25; anything else throws `RangeError` before sending) holds the read until the grant's `version` differs from `since` or `wait` seconds pass, and extends the request timeout by `wait`. A grant revoked or removed during the hold answers 401 `grant_revoked`. `oauth.watchGrants({users, onChanged, onError?, sweepMs?, concurrency?, wait?})` returns a `GrantWatcher` that follows the grants of the people `users()` names and calls `onChanged({userId, grant, previous})` level-triggered, at least once per version, so an app learns when a required provider's setup turns `ready` without a browser tab or a poll loop. New exports `GrantWatcher`, `GrantWatchOptions`, `GrantChanged`. Not breaking: nothing existing changes shape, and `RunWatcher` behaves exactly as before. The hold needs a runtime at this release and, for a hosted runtime, a hosting router that lets `GET /v1/grant?wait=N` through (before then a held read answers 504 after 10 s and the watcher backs off). See [[crouter-sdk/client]].
+`grant.get()` answers a new field, `version`: opaque, it changes exactly when `rev`, `resolved_scopes`, `spend_cap`, `payer` or `dependencies` changes. `grant.get({wait, since})` (`wait` an integer 1–25; anything else throws `RangeError` before sending) holds the read until the grant's `version` differs from `since` or `wait` seconds pass, and extends the request timeout by `wait`. A grant revoked or removed during the hold answers 401 `grant_revoked`. `oauth.watchGrants({users, onChanged, onError?, sweepMs?, concurrency?, wait?})` returns a `GrantWatcher` that follows the grants of the people `users()` names and calls `onChanged({userId, grant, previous})` level-triggered, at least once per version, so an app learns when a required provider's setup turns `ready` without a browser tab or a poll loop. New exports `GrantWatcher`, `GrantWatchOptions`, `GrantChanged`. Not breaking: nothing existing changes shape, and `RunWatcher` behaves exactly as before. The hold needs a runtime at this release and, for a hosted runtime, a hosting router that lets `GET /v1/grant?wait=N` through (before then a held read answers 504 after 10 s and the watcher backs off). See [Learn when a person's grant changes](/docs/guides/grant-changes#follow-grants-with-watchgrants).
 
 ## 0.3.399
 
 ### `onActivity` no longer blocks the watcher
 
-In 0.3.398 the watcher awaited `onActivity` before its next read, so a slow or hung hook delayed that run's `onEnded`, held its `concurrency` slot, and kept `stop()` from resolving. The watcher now never awaits it: at most one call per run runs at a time, a newer reading taken meanwhile replaces any still waiting, and `stop()` does not wait for a call already running. A call can now finish after that run's `onEnded`: guard the write on the row still waiting on the run. Runs that leave `pending()` without an ending no longer keep their last phase in memory. See [[crouter-sdk/client]].
+In 0.3.398 the watcher awaited `onActivity` before its next read, so a slow or hung hook delayed that run's `onEnded`, held its `concurrency` slot, and kept `stop()` from resolving. The watcher now never awaits it: at most one call per run runs at a time, a newer reading taken meanwhile replaces any still waiting, and `stop()` does not wait for a call already running. A call can now finish after that run's `onEnded`: guard the write on the row still waiting on the run. Runs that leave `pending()` without an ending no longer keep their last phase in memory. See [Learn when a background run ends](/docs/guides/background-runs#follow-runs-with-runwatcher).
 
 ## 0.3.398
 
 ### `RunWatcher` reports live progress with `onActivity` (additive)
 
-`oauth.watchRuns({..., onActivity, activityWait?})` calls `onActivity({userId, runId, activity, run})` with each read of a still-`running` run whose `activity` differs from the last one handed over for that run (compared as JSON: `phase`, `tool.name`, `tool.summary`), so an app can show a progress badge from the watcher it already runs instead of a second `runs.get` per page read. It is never called for a run at rest. With `onActivity` set, running runs are read with `wait: activityWait` (integer 1–25, default 2) rather than 25, because the runtime's long-poll answers early only at rest. Best effort: a throwing `onActivity` goes to `onError` and is not retried, and `onEnded` delivery is unchanged. Not breaking: without `onActivity` the watcher behaves exactly as before. New exported type `RunActivityEvent`. See [[crouter-sdk/client]].
+`oauth.watchRuns({..., onActivity, activityWait?})` calls `onActivity({userId, runId, activity, run})` with each read of a still-`running` run whose `activity` differs from the last one handed over for that run (compared as JSON: `phase`, `tool.name`, `tool.summary`), so an app can show a progress badge from the watcher it already runs instead of a second `runs.get` per page read. It is never called for a run at rest. With `onActivity` set, running runs are read with `wait: activityWait` (integer 1–25, default 2) rather than 25, because the runtime's long-poll answers early only at rest. Best effort: a throwing `onActivity` goes to `onError` and is not retried, and `onEnded` delivery is unchanged. Not breaking: without `onActivity` the watcher behaves exactly as before. New exported type `RunActivityEvent`. See [Learn when a background run ends](/docs/guides/background-runs#follow-runs-with-runwatcher).
 
 ## 0.3.397
 
 ### A runtime older than the SDK is refused before it handles the request
 
-The SDK now sends `Crouter-Minimum-Runtime-Version: <SDK_VERSION>` on every request except `/healthz`. The hosting router in front of a hosted runtime, and a runtime at this release or later, answer a request that names a newer release than the runtime's with `RuntimeVersionError` (`status` 426, `code` `runtime_version_unsupported`) **before any handler runs**: nothing is accepted, no `Idempotency-Key` is recorded, and a retry after the runtime is rolled forward is a first send. Previously an older runtime handled the request and the SDK raised afterwards. Not breaking: no app code changes. An app that worked around the late check, such as a `runs.list` read before every send, can delete it once its runtimes are at or after this release behind a hosting router that has the check. Back off on `RuntimeVersionError` and retry under the same key. A browser app's preflight now lists `crouter-minimum-runtime-version` in `Access-Control-Allow-Headers`. See [[crouter-sdk/errors]].
+The SDK now sends `Crouter-Minimum-Runtime-Version: <SDK_VERSION>` on every request except `/healthz`. The hosting router in front of a hosted runtime, and a runtime at this release or later, answer a request that names a newer release than the runtime's with `RuntimeVersionError` (`status` 426, `code` `runtime_version_unsupported`) **before any handler runs**: nothing is accepted, no `Idempotency-Key` is recorded, and a retry after the runtime is rolled forward is a first send. Previously an older runtime handled the request and the SDK raised afterwards. Not breaking: no app code changes. An app that worked around the late check, such as a `runs.list` read before every send, can delete it once its runtimes are at or after this release behind a hosting router that has the check. Back off on `RuntimeVersionError` and retry under the same key. A browser app's preflight now lists `crouter-minimum-runtime-version` in `Access-Control-Allow-Headers`. See [Errors](/docs/errors).
 
 ## 0.3.396
 
@@ -201,7 +201,7 @@ The SDK now sends `Crouter-Minimum-Runtime-Version: <SDK_VERSION>` on every requ
 
 ### `OAuth2Client` owns the connection store; one `onRefusal` for a dead connection (breaking)
 
-`OAuth2Client` now takes the app's `ConnectionStore` once, as `store` (required), plus an optional `onRefusal(refusal)` handler, and every refused refresh goes through that one handler: a request on a connected client, `refreshIdleConnections`, and the new `RunWatcher`. Apps no longer keep their own refusal table or delete dead connections themselves. See [[crouter-sdk/client]].
+`OAuth2Client` now takes the app's `ConnectionStore` once, as `store` (required), plus an optional `onRefusal(refusal)` handler, and every refused refresh goes through that one handler: a request on a connected client, `refreshIdleConnections`, and the new `RunWatcher`. Apps no longer keep their own refusal table or delete dead connections themselves. See [When a refresh is refused](/docs/concepts/connections#when-a-refresh-is-refused).
 
 - **`oauth.client(connection, store)` is now `await oauth.client(userId)`.** It loads the stored connection and returns a `ConnectedCrouter` (a `Crouter` with `userId` and `runtimeUrl`). Nothing stored throws `CrouterError` code `not_connected`. Save `exchangeCode`'s connection with `store.save(connection)` first.
 - **`oauth.refreshIdleConnections(store, {olderThanMs})` is now `oauth.refreshIdleConnections({olderThanMs})`** and returns `{refreshed, refused, failures}`. `RefreshFailure.reason` is removed: a refused connection is handled by `onRefusal`, removed, and counted in `refused`; `failures` holds only connections still stored (any other error, or a refusal whose handler threw).
@@ -215,25 +215,25 @@ The SDK now sends `Crouter-Minimum-Runtime-Version: <SDK_VERSION>` on every requ
 
 ### `RunWatcher`: learn when a background run ends (additive)
 
-`oauth.watchRuns({pending, onEnded, onError?, sweepMs?, concurrency?})` returns a `RunWatcher` (`start()`, `nudge()`, `stop()`) that follows the runs `pending()` reads from the app's own rows with `runs.get(wait)` and calls `onEnded({userId, runId, ended, run})` when each comes to rest (`settled`, `idle`, `waiting_on_user`) or is deleted (`gone`, only for a 404 `not_found` from the runtime, never the router). Delivery is at least once per `(runId, status, latest_sequence)`: a delivered run is re-read once per sweep and delivered again only when that key changes (an `idle` run later canceled is delivered as `settled`). A throwing `onEnded` is retried after 5 s, doubling to 5 min. Runs are opened with `oauth.client(userId)`, so a refused connection reaches `onRefusal`. There is no runtime-to-app webhook: the runtime cannot mint an app-audience token, a directory relay would add a hop, and the app's rows already make a pull durable and work on localhost. See [[crouter-sdk/client]].
+`oauth.watchRuns({pending, onEnded, onError?, sweepMs?, concurrency?})` returns a `RunWatcher` (`start()`, `nudge()`, `stop()`) that follows the runs `pending()` reads from the app's own rows with `runs.get(wait)` and calls `onEnded({userId, runId, ended, run})` when each comes to rest (`settled`, `idle`, `waiting_on_user`) or is deleted (`gone`, only for a 404 `not_found` from the runtime, never the router). Delivery is at least once per `(runId, status, latest_sequence)`: a delivered run is re-read once per sweep and delivered again only when that key changes (an `idle` run later canceled is delivered as `settled`). A throwing `onEnded` is retried after 5 s, doubling to 5 min. Runs are opened with `oauth.client(userId)`, so a refused connection reaches `onRefusal`. There is no runtime-to-app webhook: the runtime cannot mint an app-audience token, a directory relay would add a hop, and the app's rows already make a pull durable and work on localhost. See [Learn when a background run ends](/docs/guides/background-runs#follow-runs-with-runwatcher).
 
 ## 0.3.394
 
 ### `grant.get` dependencies are one `{ state, message?, next }` entry per provider (breaking)
 
-`GrantGetDTO.dependencies[provider]` was a bare `SetupState` string; it is now a `ProviderDependency` (exported from `@north-light/sdk` and `@north-light/api`): `{ state, message?, next }`. `state` is the setup state the string used to be. `message` is the provider's own sentence for `pending` and `failed` (its `message_pending` / `message_failed`), so delete any copy of a provider's prose your app hard-codes and show `message` instead. `next` is the absolute URL of the directory's setup page for that provider and your app; link the person there (append `return_to` with your registered redirect origin) instead of building the URL yourself. **Change every read of `dependencies[p]` to `dependencies[p].state`** (or `dependencies[p]?.state` where the entry may be missing), and carry `message` and `next` into your `provider_setup_pending` details. The runtime reads only this shape from the directory's grant sync: a runtime on this release paired with a directory that still sends bare strings reports `dependencies` as `{}`, so roll the directory change with it. See [[crouter-sdk/guides/apps-on-northlight]].
+`GrantGetDTO.dependencies[provider]` was a bare `SetupState` string; it is now a `ProviderDependency` (exported from `@north-light/sdk` and `@north-light/api`): `{ state, message?, next }`. `state` is the setup state the string used to be. `message` is the provider's own sentence for `pending` and `failed` (its `message_pending` / `message_failed`), so delete any copy of a provider's prose your app hard-codes and show `message` instead. `next` is the absolute URL of the directory's setup page for that provider and your app; link the person there (append `return_to` with your registered redirect origin) instead of building the URL yourself. **Change every read of `dependencies[p]` to `dependencies[p].state`** (or `dependencies[p]?.state` where the entry may be missing), and carry `message` and `next` into your `provider_setup_pending` details. The runtime reads only this shape from the directory's grant sync: a runtime on this release paired with a directory that still sends bare strings reports `dependencies` as `{}`, so roll the directory change with it. See [Waiting on a provider your app requires](/docs/guides/grant-changes#wait-on-a-provider-your-app-requires).
 
 ## 0.3.393
 
 ### The runtime orders grant state by revision; a failed grant check is `service_unavailable` (breaking)
 
-A runtime on this release requires the `rev` claim in every app access token, so it needs a directory that issues it; a token without `rev` is refused 401 `unauthorized`, "access token has no rev claim: the directory is older than this runtime". A freshly consented or re-consented grant is now authorized on the first call, with no wait: the runtime pulls grant state once whenever a token is newer than its mirror. **Delete any retry your app added for a 401 `grant_revoked` right after consent.** When that pull fails, the call answers 503 `service_unavailable` (`retryable: true`) instead of 401 `grant_revoked`, so a directory outage no longer looks like a refused connection. `service_unavailable` was already in `errorCodes`; app calls can now receive it. See [[crouter-sdk/client]].
+A runtime on this release requires the `rev` claim in every app access token, so it needs a directory that issues it; a token without `rev` is refused 401 `unauthorized`, "access token has no rev claim: the directory is older than this runtime". A freshly consented or re-consented grant is now authorized on the first call, with no wait: the runtime pulls grant state once whenever a token is newer than its mirror. **Delete any retry your app added for a 401 `grant_revoked` right after consent.** When that pull fails, the call answers 503 `service_unavailable` (`retryable: true`) instead of 401 `grant_revoked`, so a directory outage no longer looks like a refused connection. `service_unavailable` was already in `errorCodes`; app calls can now receive it. See [An app connection and refresh](/docs/concepts/connections).
 
 ## 0.3.391
 
 ### The SDK refuses a runtime older than itself (breaking)
 
-`@north-light/sdk` now accepts only a runtime at or above its own version, and fails loudly otherwise instead of handing an app data its types do not describe. Every runtime answer carries `Crouter-Runtime-Version`; when that version is older than `SDK_VERSION`, or the header is absent (every runtime before this release), the call throws `RuntimeVersionError` (`code: 'runtime_version_unsupported'`, `status: 426`, `retryable: false`) whose message and `sdkVersion` / `runtimeVersion` name both versions. A refusal without the header (a router in front of the runtime answering 401 or 503) is still raised as that refusal. There is no capability negotiation: `RunObject.activity` and every other field are typed for a runtime at this release. **Upgrade every runtime the app talks to before upgrading the SDK**, and pin the SDK to an exact version. A test double that fakes the runtime with `fetch` must send `Crouter-Runtime-Version` at the SDK's version on its 2xx answers. See [[crouter-sdk/errors]].
+`@north-light/sdk` now accepts only a runtime at or above its own version, and fails loudly otherwise instead of handing an app data its types do not describe. Every runtime answer carries `Crouter-Runtime-Version`; when that version is older than `SDK_VERSION`, or the header is absent (every runtime before this release), the call throws `RuntimeVersionError` (`code: 'runtime_version_unsupported'`, `status: 426`, `retryable: false`) whose message and `sdkVersion` / `runtimeVersion` name both versions. A refusal without the header (a router in front of the runtime answering 401 or 503) is still raised as that refusal. There is no capability negotiation: `RunObject.activity` and every other field are typed for a runtime at this release. **Upgrade every runtime the app talks to before upgrading the SDK**, and pin the SDK to an exact version. A test double that fakes the runtime with `fetch` must send `Crouter-Runtime-Version` at the SDK's version on its 2xx answers. See [Errors](/docs/errors).
 
 ### One release is one version set
 
@@ -261,7 +261,7 @@ A runtime on this release requires the `rev` claim in every app access token, so
 
 ### `runs.get` reports what a running run is doing (additive)
 
-`RunObject.activity` is `{phase: 'starting' | 'thinking' | 'writing' | 'between_turns'}` or `{phase: 'tool', tool: {name, summary}}` while the run is `running`, and `null` otherwise, so a polling app can show progress from `runs.get` without reading `runs.trace`. `runs.list` entries carry it too. See [[crouter-sdk/guides/apps-on-northlight]]. A test double that builds a `RunObject` literal must add `activity`.
+`RunObject.activity` is `{phase: 'starting' | 'thinking' | 'writing' | 'between_turns'}` or `{phase: 'tool', tool: {name, summary}}` while the run is `running`, and `null` otherwise, so a polling app can show progress from `runs.get` without reading `runs.trace`. `runs.list` entries carry it too. See [Showing a background run's progress](/docs/guides/typed-results#showing-progress). A test double that builds a `RunObject` literal must add `activity`.
 
 ## 0.3.374
 
@@ -273,7 +273,7 @@ A sign-in that grants the `profile` scope returns `name`, `givenName`, and `fami
 
 ### `CrouterError.code` is typed `SdkErrorCode`
 
-Every code the SDK raises itself is now listed in `sdkErrorCodes` (exported with `SdkErrorCode` and `mapError` from `@north-light/sdk/errors`), and `CrouterError`'s `code` and constructor are typed with it. Runtime behavior is unchanged. **An app that constructs `new CrouterError(message, code)` with a code of its own, for example in a test double, no longer typechecks:** throw its own error class or an `APIError` instead. See [[crouter-sdk/errors]].
+Every code the SDK raises itself is now listed in `sdkErrorCodes` (exported with `SdkErrorCode` and `mapError` from `@north-light/sdk/errors`), and `CrouterError`'s `code` and constructor are typed with it. Runtime behavior is unchanged. **An app that constructs `new CrouterError(message, code)` with a code of its own, for example in a test double, no longer typechecks:** throw its own error class or an `APIError` instead. See [Errors](/docs/errors).
 
 ### Run ergonomics (additive)
 
@@ -289,7 +289,7 @@ When the directory refuses a connection's refresh token, the SDK now raises the
 - `grant_suspended`: your app is paused for that person. Nothing was deleted; keep their data.
 - `refresh_token_expired`: the refresh token went 90 days unused. The grant is still active; reconnecting skips the consent page.
 
-Each is a 401 `AuthenticationError` with `retryable: false`, `userAction: 'reconnect'`, and `origin: 'directory'`, and the connected client from `oauth.client(...)` stops refreshing after it, as it already did for `grant_revoked` and `refresh_token_reused`. `errorCodes` and the `ErrorCode` type gain the three codes. The table of codes and app actions is in [[crouter-sdk/client]].
+Each is a 401 `AuthenticationError` with `retryable: false`, `userAction: 'reconnect'`, and `origin: 'directory'`, and the connected client from `oauth.client(...)` stops refreshing after it, as it already did for `grant_revoked` and `refresh_token_reused`. `errorCodes` and the `ErrorCode` type gain the three codes. The table of codes and app actions is in [When a refresh is refused](/docs/concepts/connections#when-a-refresh-is-refused).
 
 **Behavior changes for existing apps:**
 

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.