@north-light/cli 0.3.473 → 0.3.475

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

@@ -0,0 +1,210 @@
+---
+kind: knowledge
+when-and-why-to-read: When you need Quick setup, this knowledge should be read
+  because From no account to a running app that signs a person in with
+  Northlight, starts a run on their runtime and sends them a text.
+---
+
+# Quick setup
+
+```bash
+npx @north-light/sdk@latest init my-app
+```
+
+This command creates a small Node server, a signing key and an env file. About ten minutes later you have an app on your laptop that signs you in with Northlight, starts an agent run on your own Northlight runtime, and texts your phone. The app runs on your machine and talks to Northlight's production directory at `https://account.northlight.ai`. There is no local Northlight stack to run, and you do not need crouter.
+
+You need Node.js 22.19 or later and a phone that can receive iMessage.
+
+Using a coding agent? Run the same `init` command, or tell your agent: *Read https://sdk.docs.northlight.ai/SKILL.md and follow it.* See [[northlight-apps/coding-agents]].
+
+Each step below ends with what you should see when it worked. A step marked "(not yet checked on production)" is written from the source code and has not been run end to end against `account.northlight.ai`.
+
+## 1. Create an account
+
+Open `https://account.northlight.ai/signup` and create your account. Signup texts a confirmation code to your phone, and that text is sent over iMessage. A number that cannot receive iMessage gets "We couldn't send the text", and retrying does not help. One phone number belongs to one account.
+
+You should see: your account's page after you enter the code. Opening `https://account.northlight.ai/console` while signed in shows the console, where your apps are listed. Checked on production: `/signup` redirects to the phone step at `/signup/phone`, and `/console` while signed out redirects to sign-in. Completing signup and the signed-in console are not yet checked on production.
+
+## 2. Scaffold the app
+
+```bash
+npx @north-light/sdk@latest init my-app
+cd my-app
+```
+
+`init` writes these files into `my-app/`:
+
+| File | What it is |
+|---|---|
+| `package.json` | Pins `@north-light/sdk` to the exact version of the CLI you ran, and adds `tsx`. |
+| `server.ts` | The server shown at the end of this page. |
+| `local/app-key.json` | Your app's private signing key, mode `0600`. Never commit it or paste it anywhere. |
+| `local/app.env` | The settings the server reads: `CROUTER_ISSUER`, `APP_ORIGIN`, an empty `CROUTER_CLIENT_ID=` and `CROUTER_KEY_FILE`. |
+| `.gitignore` | Keeps `local/` and `node_modules/` out of git. |
+| `.agents/skills/northlight/SKILL.md` and `.claude/skills/northlight/SKILL.md` | The Northlight skill for your coding agent. |
+
+You should see, on the terminal: `Created a Northlight app in my-app:` with the file names, the path of the private key, the next steps in order, and last, on its own line, the **public key** as one line of JSON:
+
+```json
+{"kty":"EC","x":"…","y":"…","crv":"P-256","kid":"…","alg":"ES256","use":"sig"}
+```
+
+Copy that line. You paste it into the console in the next step. If a file already exists, `init` refuses, names it and exits non-zero without writing anything.
+
+Checked: this output and these files, from the SDK source built on this branch in an empty directory with no crtr on `PATH`. `npx @north-light/sdk@latest` fetches the npm `latest` release, and that release does not include `init` until the site goes live (not yet checked on production).
+
+## 3. Register the app in the console
+
+Open `https://account.northlight.ai/console/new`. The page is titled **Register an app**. Fill in:
+
+| Field | Value |
+|---|---|
+| **Name** | Shown to people on the consent page and in their account. |
+| **Origin URL** | `http://localhost:3000` |
+| **Logo URL** | Required. A square image shown beside your app's name. |
+| **Why your app needs access** | One sentence. It is quoted on the consent page as your words. |
+| **Redirect URIs** | `http://localhost:3000/auth/callback`, one URL per line. Sign-in returns only to a URI listed here, matched exactly. `localhost` and `127.0.0.1` are different URIs, and the port counts. |
+| **Public key (optional)** | The JSON line `init` printed. |
+
+Choose **Register app**.
+
+You should see: a page titled "*your app's name* is registered" with a **Client ID** and, under it, the key ID of the key you pasted. Copy the client ID. If it says "Next: add your app's public key on the Sign-in tab", the key was left out: open the app's **Sign-in** tab and choose **Add key**. The app starts asking for `crtr:llm` and `crtr:act`.
+
+The field labels are from the console's source. Pasting a key at registration is not yet checked on production.
+
+## 4. Add the permission to text
+
+On the app's page, open the **What it asks for** tab and choose **Add permissions**. Add `sms:send` from the list.
+
+You should see: `sms:send` under what your app asks for, next to `crtr:llm` and `crtr:act`. The server in this guide asks for all three, so without `sms:send` the consent page does not offer it and the text in step 6 is refused. Take scope strings from this list. Do not invent them. See [[northlight-apps/concepts/scopes-and-grants]].
+
+Not yet checked on production.
+
+## 5. Write the client ID into the env file
+
+```bash
+npx @north-light/sdk env --client-id <client id>
+```
+
+You should see:
+
+```text
+Set in local/app.env:
+  CROUTER_ISSUER=https://account.northlight.ai
+  CROUTER_CLIENT_ID=<client id>
+  APP_ORIGIN=http://localhost:3000
+Key file: local/app-key.json (set CROUTER_KEY_FILE to change it).
+```
+
+`local/app.env` now has all four settings. The command makes no network call and keeps every other line in the file. Add `--origin <url>` if your app does not run on `http://localhost:3000`.
+
+Checked from the SDK source built on this branch.
+
+## 6. Run it
+
+```bash
+npm i
+node --env-file=local/app.env --import tsx server.ts
+```
+
+(`npm start` runs the same command.) You should see `Listening on http://localhost:3000`.
+
+Open `http://localhost:3000/auth/login`. Your browser goes to `account.northlight.ai`. Sign in if asked, read the consent page, and choose Allow. You land back on `http://localhost:3000/` with "Signed in" and your Northlight user id. Press **Start a run and send me a text**. The page answers "Done", shows the run's status `idle`, and your phone receives "Hello from my first Northlight app." from Northlight's number.
+
+What was checked: the server starts, `/` shows the sign-in link, and `/auth/login` answers `303` to `https://account.northlight.ai/authorize?client_id=…&scope=openid+profile+crtr%3Allm+crtr%3Aact+sms%3Asend…&code_challenge_method=S256…`. The consent page, the callback, the run and the text are not yet checked on production.
+
+If `/` shows "One step left", `CROUTER_CLIENT_ID` is empty: repeat step 5 and restart. If a call fails with `426 runtime_version_unsupported`, your SDK is newer than the Northlight runtimes. Install the previous version with `npm i --save-exact @north-light/sdk@<version>` and tell support@northlight.ai.
+
+## 7. What next
+
+- Only you can sign in until you add testers: see [[northlight-apps/concepts/testing-mode]].
+- Keep each person's sign-in across restarts and processes: see [[northlight-apps/concepts/connections]].
+- See what `server.ts` does and where each piece runs: [[northlight-apps/how-it-fits]].
+
+## The server `init` writes
+
+This is `examples/apps/quickstart-server.ts`. The SDK reads no environment: the server passes the values in.
+
+```ts
+// The server `npx @north-light/sdk init` writes as server.ts: sign a person in with Northlight, then start a run on
+// their runtime and send them a text. It keeps sign-in state in memory, so it is a sketch for one process, not production.
+import {createServer, type IncomingMessage, type ServerResponse} from 'node:http';
+import {randomBytes} from 'node:crypto';
+import {readFile} from 'node:fs/promises';
+import {MemoryConnectionStore, OAuth2Client, authorizationRefusalOf} from '@north-light/sdk';
+
+const origin = process.env.APP_ORIGIN ?? 'http://localhost:3000';
+
+const store = new MemoryConnectionStore(); // one process only; use a persistent ConnectionStore in production
+const oauth = new OAuth2Client({
+  clientId: process.env.CROUTER_CLIENT_ID ?? '',
+  issuer: process.env.CROUTER_ISSUER ?? 'https://account.northlight.ai',
+  redirectUri: `${origin}/auth/callback`,
+  privateKey: JSON.parse(await readFile(process.env.CROUTER_KEY_FILE ?? 'local/app-key.json', 'utf8')),
+  store,
+});
+
+const pending = new Map<string, {codeVerifier: string; nonce: string}>(); // sign-ins in flight, keyed by state
+const sessions = new Map<string, string>(); // session id -> userId; use a real session store in production
+
+const escapeHtml = (text: string) => text.replace(/[&<>"']/g, (c) => `&#${c.charCodeAt(0)};`);
+const page = (res: ServerResponse, status: number, body: string) => {
+  res.writeHead(status, {'content-type': 'text/html; charset=utf-8'}).end(`<!doctype html><meta charset="utf-8"><title>Northlight app</title><body style="font-family:system-ui;max-width:40rem;margin:3rem auto">${body}`);
+};
+const userOf = (req: IncomingMessage) => {
+  const sid = /(?:^|; )sid=([\w-]+)/.exec(req.headers.cookie ?? '')?.[1];
+  return sid ? sessions.get(sid) : undefined;
+};
+
+const server = createServer(async (req, res) => {
+  const url = new URL(req.url ?? '/', origin);
+  try {
+    if (!process.env.CROUTER_CLIENT_ID) {
+      return page(res, 200, '<h1>One step left</h1><p>Register the app in the console, then run <code>npx @north-light/sdk env --client-id &lt;client id&gt;</code> and restart this server.</p>');
+    }
+
+    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();
+    }
+
+    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();
+    }
+
+    const userId = userOf(req);
+    if (!userId) return page(res, 200, '<h1>Northlight app</h1><p><a href="/auth/login">Sign in with Northlight</a></p>');
+
+    if (url.pathname === '/run' && req.method === 'POST') {
+      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
+      // 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.'}});
+      return page(res, 200, `<h1>Done</h1><p>The run finished with status <code>${escapeHtml(run.status)}</code>. A text is on its way to your phone.</p><pre>${escapeHtml(JSON.stringify({run: run.run_id, outcome: run.outcome, report: run.last_report, text: sent}, null, 2))}</pre><p><a href="/">Back</a></p>`);
+    }
+    return page(res, 200, `<h1>Signed in</h1><p>You are <code>${escapeHtml(userId)}</code>.</p><form method="post" action="/run"><button>Start a run and send me a text</button></form>`);
+  } catch (error) {
+    console.error(error);
+    return page(res, 500, `<h1>Something failed</h1><pre>${escapeHtml(error instanceof Error ? error.message : String(error))}</pre>`);
+  }
+});
+
+server.listen(Number(new URL(origin).port) || 3000, () => console.log(`Listening on ${origin}`));
+```

package/docs/apps/guides/background-runs.md

@@ -68,11 +68,4 @@ app.post('/run-notices', async (req, res) => {
 
 ### Set the run notice URL
 
-The console has no field for this yet. Until it does, set it with crtr on a machine joined to your Northlight account (`crtr sys join`; see [joining a machine](https://crouter.docs.northlight.ai/docs/sdk/guides/apps-on-northlight#1-account-and-join) in the crouter docs):
-
-```bash
-crtr cloud apps set-run-notice-url --app-id <client id> --url https://app.example.com/run-notices
-crtr cloud apps set-run-notice-url --app-id <client id> --clear   # stop notices
-```
-
-The URL must be https (plain http only on localhost in development) and at most 512 characters. `crtr cloud apps get --app-id <client id>` shows it as `run_notice_url`.
+In the [console](https://account.northlight.ai/console), open your app, choose the **What it asks for** tab, and fill in **Notice URL** under **Run notice URL**. Choose **Save**. The URL must be `https` and at most 512 characters. To stop notices, empty the field and save. The full list of console fields is in [Manage your app](/docs/guides/manage-your-app#what-it-asks-for).

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

@@ -1,6 +1,6 @@
 ---
 title: Manage your app
-description: What each tab of the Northlight console does for an app you have registered, and the two things the console cannot do yet.
+description: What each tab of the Northlight console does for an app you have registered, including setting the run notice URL and deleting the app.
 ---
 
 # Manage your app
@@ -31,11 +31,13 @@ Until you retire the old key it is your rollback. After you retire it, a sign-in
 - **What your app asks for.** The scopes people are asked to approve. **Add permissions** searches the catalog; take scope strings from it and from `providers.tools`, and do not invent them. `crtr:act` needs `crtr:llm`. See [Scopes and grants](/docs/concepts/scopes-and-grants).
 - **What your app requires.** Providers the app cannot work without. A person is taken through that provider's setup the first time they sign in. See [Grant changes](/docs/guides/grant-changes#wait-on-a-provider-your-app-requires).
 - **Monthly spend cap.** The most your app may spend of each person's AI subscription per month, in whole US dollars.
+- **Run notice URL.** Where Northlight posts a signed notice when one of your app's background runs ends. Type it in **Notice URL** and choose **Save**; empty it and save to turn notices off. The URL must be `https`, at most 512 characters, with no `#fragment`. The directory refuses a plain `http` URL with `run_notice_url` as the field. The field's hint says `http://localhost` is accepted while developing, but the production directory refuses it (checked in the directory source, not yet checked on production), so test notices with a tunnel that gives you an `https` URL. What your app does with a notice is in [Background runs](/docs/guides/background-runs#run-notices).
 
 ## Profile
 
 - **How people see your app**: Name, Origin URL, Logo URL, and **Why your app needs access** (quoted on the consent page as your words). **Save details**.
 - **Marketplace**: **Listed in the marketplace**, Price, **Sign-in start URL** and **Text welcome**. Agents can install a listed app for a person by text. A testing app stays out of the marketplace even when listed. The sign-in start URL is where Install sends people; your `/auth/login` route is a valid one, and a `localhost` URL is accepted. The text welcome is one or two plain sentences, at most 120 characters, with no links.
+- **Delete this app.** At the bottom of the tab; see [Delete an app](#delete-an-app).
 
 ## Testers
 
@@ -53,23 +55,10 @@ Once your app is live you can keep developing on your laptop against production
 
 **Register a separate development app.** Do this when you are changing what the app asks for, or need grants and data that live people never touch. Register another app in the console, for example "Texty (dev)", with a `localhost` origin and redirect URI and its own key. It starts in testing and stays there, so only you and your testers can sign in, and it never appears in the marketplace. Point your laptop's environment file at its client ID.
 
-## Two things the console can't do yet
+## Delete an app
 
-Deleting an app and setting its run notice URL are not in the console today. Both need `crtr`, the Northlight command line, on a machine joined to your Northlight account. Joining is a one-time setup described in [the crouter docs](https://crouter.docs.northlight.ai/docs/sdk/guides/apps-on-northlight#1-account-and-join): install `@north-light/cli`, then run `crtr sys join` with a token from `https://account.northlight.ai/account/machines`. Joining rewrites the local crtr home and has no unjoin, so join from a home you can throw away. These steps are the only part of building an app that needs crtr.
+On the **Profile** tab, the **Delete this app** card lists what goes: every person's connection to the app, yours included (each person's runtime deletes the app's runs, space and schedules), the app's sign-ins and keys, and its testers and marketplace listing. This cannot be undone, and the client ID is never reused.
 
-### Delete an app
+To delete, type the app's full name in **Type the app's name, *name*, to confirm**. **Delete app** stays disabled until what you typed matches the name (surrounding spaces are ignored), and the directory checks the name again when you submit. After it deletes, the console returns to your app list. The app's next refresh for any person fails with `invalid_grant`, its key stops working and its page answers 404.
 
-```bash
-crtr cloud apps delete --app-id <client id> --confirm <client id>
-```
-
-It answers `deleted: true` and `removed_grants`, the number of people's grants it removed. Each person's runtime deletes the app's runs, space and schedules, and the app's next refresh fails with `invalid_grant`. The app's key stops working, its page answers 404 and it disappears from your list. This cannot be undone. You must run it yourself in the terminal of the joined machine: an agent, including your chat agent, is refused with `provider_refused`. If you only want a clean slate for tests, changing the app's redirect URIs and keys is often simpler.
-
-### Set the run notice URL
-
-```bash
-crtr cloud apps set-run-notice-url --app-id <client id> --url https://app.example.com/run-notices
-crtr cloud apps set-run-notice-url --app-id <client id> --clear
-```
-
-The URL must be https (plain http only on localhost in development) and at most 512 characters. What the app does with notices is in [Background runs](/docs/guides/background-runs#run-notices).
+The card is not shown for a provider or a first-party app, and the directory refuses to delete a provider (`app_is_provider`). If you only want a clean slate for tests, changing the app's redirect URIs and keys is often simpler.

package/docs/cli/README.md

@@ -14,4 +14,5 @@ Use these pages to start and return to an agent conversation, see the work runni
 | [Canvas and dashboard](./canvas-and-dashboard.md) | See the node graph, find work that needs attention, and reopen a node. |
 | [Human inbox](./human-inbox.md) | Answer decisions, review documents, and follow a live display. |
 | [Documents and preferences](./documents-and-preferences.md) | Save knowledge and instructions that should shape later agents. |
+| [Join a machine to your Northlight account](./join-northlight.md) | Run `crtr cloud apps` commands as you, from a joined laptop. |
 | [The official plugin marketplace](./official-marketplace.md) | Find a plugin, see what it needs, and install it. |

package/docs/cli/join-northlight.md

@@ -0,0 +1,58 @@
+---
+title: Join a machine to your Northlight account
+description: Join a laptop to your Northlight account with crtr sys join so crtr cloud apps commands run as you, and the crtr cloud apps command list.
+---
+
+# Join a machine to your Northlight account
+
+Joining makes this machine one of your Northlight account's machines, so `crtr cloud …` commands run as you. Building an app does not need it: the [SDK docs site](https://sdk.docs.northlight.ai/docs/quickstart) takes you through the web console. Join when you want to run `crtr cloud apps` yourself.
+
+Create your account at `https://account.northlight.ai/signup` first. Then install the CLI (`npm i -g @north-light/cli`). Joining needs `crtr` 0.3.436 or later (older versions need `crtr sys daemon stop` first and fail if a viewer is open); `crtr --version` shows yours.
+
+Then join your laptop to the account:
+
+1. Open `https://account.northlight.ai/account/machines` and choose **Create join token**. A token needs a sign-in within the last 10 minutes, so the page asks you to sign in again if yours is older.
+2. The page shows the join command with the token filled in. On your laptop, run it from a plain terminal: `crtr sys join --directory https://account.northlight.ai --token <token>`. Leave your crtr windows open: join stops the daemon itself, holds it down while it writes your identity (so an open viewer cannot restart it early), and starts it again on the joined settings. Run it outside any crtr node, because a node's engine stops with the daemon; from inside one, join refuses with `join_inside_node`. Add `--name <label>` to name the machine on the page. The token works once and expires at the time the page shows; the page shows it only once.
+
+   ```bash
+   crtr sys join --directory https://account.northlight.ai --token <token> --name my-laptop
+   ```
+
+   It answers with `registered: true`, the machine id (`runtime:<id>`), your user id and `daemon: restarted` (`daemon: started` when crtr was not running: join starts the daemon, and its first grant sync installs `crtr cloud …` and your other provider plugins). Your open viewers and nodes reconnect on their own.
+3. Check it: `crtr cloud apps mine` lists the apps you manage. Before you have joined, it answers `not_joined` and prints these same steps.
+
+Things to know before you join:
+
+- **Joining rewrites your crtr home.** Everything in your everyday crtr home that belonged to the local user (`user:local`) becomes your Northlight user, the next time the daemon starts. If you would rather not do that to your everyday home, join from a home you can throw away.
+- **There is no unjoin.** The only undo is removing the machine on `/account/machines`.
+- **Removing the machine stops it.** Once you choose **Remove** next to a machine, it gets no new tokens at once and the ones it holds expire within 5 minutes. After that its `cloud` commands answer `machine_revoked`: "This machine was removed from your Northlight account." It stays that way until you create a new join token and run `crtr sys join` again. Files on the computer stay on it.
+- **Your hosted machine is unchanged.** `/account/machines` lists it as "Northlight (hosted)", the default. Your chat agent at `https://chat.northlight.ai` still runs `crtr cloud apps …` as before.
+
+## `crtr cloud apps`
+
+Every app-management leaf of Northlight's `cloud` provider runs as you and needs a joined machine. `--app-id` takes `app:<client id>` or the bare client id.
+
+Your Northlight chat agent at `https://chat.northlight.ai` can run these commands as you, on your hosted runtime. It can list and change an app (`mine` and `set-scopes` were checked on production). It cannot delete one. Generate keys on your laptop and give an agent only a public JWK, never the private key.
+
+| Command | What it does |
+|---|---|
+| `crtr cloud apps mine` | Lists the apps you manage. |
+| `crtr cloud apps register --name … --origin … --logo … --justification … --redirect-uri …` | Registers an app and answers its registration, including `env` (the issuer, client id and origin). The `--redirect-uri` flag repeats. |
+| `crtr cloud apps get --app-id <id>` | Shows the registration. |
+| `crtr cloud apps update --app-id <id> --name … / --origin … / --logo … / --justification …` | Changes the profile fields you pass. |
+| `crtr cloud apps set-redirect-uris --app-id <id> --redirect-uri …` | Replaces the whole redirect URI list; repeat the flag for each. |
+| `crtr cloud apps asks --app-id <id>` | Lists what an app may ask for, with whether it asks now. Large sources such as `integrations` print as a count. Narrow it with `--query sms:send`, `--source sms`, `--group providers\|apps\|agents\|space`, or `--query <text>`; `--requested` lists only what the app asks for now. For example `crtr cloud apps asks --app-id <id> --source sms`. |
+| `crtr cloud apps set-scopes --app-id <id> --add … --remove …` | Edits the scope list the app has now; repeat `--add`/`--remove` per scope. Removing a scope that is not in the list is refused. Or replace the whole list with repeated `--scope`; `--clear` empties it. `crtr:act` needs `crtr:llm`. |
+| `crtr cloud apps set-requires --app-id <id> --add … --remove …` | Edits the providers your app does not work without (for example `context`). Or replace the list with repeated `--provider`; `--clear` empties it. |
+| `crtr cloud apps keys add --app-id <id> --jwk '<public JWK>'` | Adds a signing key beside any existing one. Answers `created: false` if that key is already on the app. `keygen --app` calls it for you. |
+| `crtr cloud apps keys list --app-id <id>` | Lists the keys with their `kid` and `active` or `retired` status. |
+| `crtr cloud apps keys retire --app-id <id> --kid <kid>` | Retires a key so it no longer signs in. |
+| `crtr cloud apps set-listing --app-id <id> --login-start-url … --text-welcome …` (also `--listed`, `--price`) | Sets the listing fields; pass at least one. A loopback `--login-start-url` is accepted. `--listed true --price free` lists the app, so `cloud apps install` finds it; while the app is in testing it still stays out of the marketplace list. |
+| `crtr cloud apps install --app-id <id>` | Texts an install link to the signed-in person. If they already hold a grant it answers `status: already_have` and the install URL instead of texting. The app must be listed. |
+| `crtr cloud apps testers add --app-id <id> --email …` (or `--phone …`) | Lets that person sign in while the app is in testing; at most 100. Not yet run on production. |
+| `crtr cloud apps testers list --app-id <id>` | Lists the testers. |
+| `crtr cloud apps testers remove --app-id <id> --email …` (or `--phone …`) | Removes a tester and revokes their grants for the app. Not yet run on production. |
+| `crtr cloud apps set-run-notice-url --app-id <id> --url …` (or `--clear`) | Sets or clears the URL the runtime posts run notices to. https only, plain http on localhost for development, at most 512 characters. |
+| `crtr cloud apps delete --app-id <id> --confirm <client id>` | Deletes the app and removes every person's grant for it. Only you at a joined machine's terminal can run it: an agent, including your chat agent, is refused with `provider_refused`. |
+
+Deleting an app removes every person's grant for it and cannot be undone. Each runtime deletes the app's runs, space and schedules, and the app's next refresh fails with `invalid_grant`. Apps that hold the provider role cannot be deleted.

package/docs/sdk/README.md

@@ -24,48 +24,9 @@ const run = await client.nodes.parse({
 if (run.kind === 'result') console.log(run.output_parsed.root_cause);
 ```
 
-## Go live with an app key
+## Building an app for other people
 
-Once you have installed the SDK and tried the local flow in [Getting started](./getting-started.md), build against production: [Build and register an app](./guides/apps-on-northlight.md#build-and-register-an-app) takes you from signing up at `https://account.northlight.ai` and joining your laptop (`crtr sys join`) to a running app on your laptop, registered with `crtr cloud apps register`. Generate the key and pull the settings with:
-
-```bash
-npx @north-light/sdk keygen --app <client id>
-npx @north-light/sdk env --app <client id>
-```
-
-`keygen` saves the private JWK to `local/app-key.json` (mode `0600`); keep that file out of git. With `--app`, it offers to add the public key to your registered app through your own `crtr`, as an additional key that never replaces the current one. Otherwise, add the public JWK printed on stdout with `crtr cloud apps keys add --app-id <client id> --jwk '<public JWK>'`. An app authenticates only with its key; the directory issues no client secret.
-
-`env` reads the registration through `crtr cloud apps get` and writes `CROUTER_ISSUER`, `CROUTER_CLIENT_ID` and `APP_ORIGIN` into `local/app.env` (`--out` picks another file), keeping every other line. Both commands need this machine's `crtr` joined to your Northlight account; on a machine that isn't, they print a join step and exit 2. An app is configured from four variables:
-
-| Variable | Value |
-|---|---|
-| `CROUTER_ISSUER` | The directory's issuer URL |
-| `CROUTER_CLIENT_ID` | The app's client id |
-| `APP_ORIGIN` | The app's origin; its redirect URI is `${APP_ORIGIN}/auth/callback` by convention |
-| `CROUTER_KEY_FILE` | Path to the private JWK, default `local/app-key.json`. `env` never writes it |
-
-The SDK reads no environment itself: load the values in your own config and pass them to `OAuth2Client`.
-
-```ts
-import {readFile} from 'node:fs/promises';
-import {OAuth2Client} from '@north-light/sdk';
-
-const privateKey = JSON.parse(await readFile(process.env.CROUTER_KEY_FILE ?? 'local/app-key.json', 'utf8'));
-const oauth = new OAuth2Client({
-  clientId: process.env.CROUTER_CLIENT_ID!,
-  issuer: process.env.CROUTER_ISSUER!,
-  redirectUri: `${process.env.APP_ORIGIN}/auth/callback`,
-  privateKey,
-  store, // your ConnectionStore
-});
-const {url, state, codeVerifier, nonce} = await oauth.authorizeUrl({scopes: ['openid', 'crtr:llm', 'crtr:act'], state: sessionState});
-// Save state, codeVerifier, nonce in the user's session, then redirect to url.
-const connection = await oauth.exchangeCode({code: callbackCode, state: callbackState, expectedState: state, codeVerifier, nonce});
-await store.save(connection);
-const client = await oauth.client(connection.userId); // Refreshes through the store from here on.
-```
-
-The directory rejects the key until its public JWK is added to the app. To change keys later, follow [Rotating your key](./getting-started.md#rotating-your-key): add the new key, switch the app to it, verify a real sign-in, then retire the old key. An app can hold two active keys at once, so there is no downtime.
+An app that signs people in with Northlight and runs agents on their runtimes is documented on the SDK docs site, which starts at [Quick setup](https://sdk.docs.northlight.ai/docs/quickstart). This section and the pages below cover driving a crouter daemon you run yourself.
 
 ## Pages
 
@@ -77,14 +38,10 @@ The directory rejects the key until its public JWK is added to the app. To chang
 | [Streaming](./streaming.md) | The event table, `stream()` / `events()`, the activity helper, resume with `after`, `stream_gap` and `stream_dropped` |
 | [Files](./files.md) | Absolute-path reads, writes, and one-level lists |
 | [Bash](./bash.md) | One bounded command and its output result |
-| [Memory](./memory.md) | `memory.list` and `memory.get`: an app reads the person's `public` documents with no scope |
 | [Resource map](./resources.md) | Every namespace (including `customObjects`, `runs`, `memory`, `shares`, `providers`) with its routes, what is deliberately excluded, and the `client.request()` escape hatch |
-| [Errors](./errors.md) | The error class table and the retry policy |
+| [Errors](./errors.md) | The daemon's scoped-token and wire errors, identifier validation, and node retries |
 | [Docker environment](./docker.md) | `start()`, `attach()`, `connection()` from `@north-light/env-docker` |
-| [Testing your app](./testing.md) | `FakeCloud` from `@north-light/sdk/testing`: a fake directory and runtime your real `OAuth2Client` and `Crouter` talk to through `fetch` |
 | [Release notes](https://sdk.docs.northlight.ai/docs/release-notes) | Behavior changes an existing app must act on, newest first |
-| [Apps on Northlight](./guides/apps-on-northlight.md) | Building and registering an app against production (joining a laptop, `crtr cloud apps` registration, keys, env file, scopes, running locally, the `crtr cloud apps` commands); typed results from app runs with `runs.parse`, declines, bounding a run, `run_idle`, and waiting on a provider your app requires |
-| [Apps with many users](./guides/apps-with-many-users.md) | Per-person runtime connections, app-owned user access, privacy, and spending |
 
 ## Phases