@north-light/sdk 0.3.487 → 0.3.488

package/README.md

@@ -6,7 +6,7 @@
   <a href="https://www.npmjs.com/package/@north-light/sdk"><img alt="npm" src="https://img.shields.io/npm/v/@north-light/sdk?label=npm"></a>
 </p>
 
-`@north-light/sdk` is the application-facing client for a crouter daemon (`crtrd`). Create an agent run, wait for a result checked against a Zod or Standard Schema, stream the run's text and tool calls to a UI, and use the daemon's other APIs: files, bash, documents ("memory"), crons, human requests, and the OAuth connection flow for apps whose users each have their own runtime. It is ESM-only.
+`@north-light/sdk` is the application-facing client for a crouter daemon (`crtrd`). Create an agent run, wait for a result checked against a Zod or Standard Schema, stream the run's text and tool calls to a UI, and use the daemon's other APIs: files, bash, documents ("memory" for the person's, `docs` for ones your app owns), crons, human requests, and the OAuth connection flow for apps whose users each have their own runtime. It is ESM-only.
 
 It is a client, not a runtime. It never runs an agent itself, and it does not bundle a model: the daemon it talks to does, using the provider that daemon is signed in to. In Node, `new Crouter()` connects to the local daemon over its unix socket and starts it on the first request if it is not running. In a browser or from another machine it needs the daemon's TCP URL and a bearer token. The lower-level contract it is built on is [`@north-light/api`](https://www.npmjs.com/package/@north-light/api); most applications should install this package instead.
 

package/dist/apps-command.js

@@ -1,3 +1,4 @@
+import { readFile } from 'node:fs/promises';
 import { usageOf } from './cli-usage.js';
 import { callLeaf } from './directory-client.js';
 import { envValueOf } from './env-command.js';
@@ -9,6 +10,8 @@ const LEAVES = {
     'mine': { path: 'mine', app: false, flags: {} },
     'get': { path: 'get', app: true, flags: {} },
     'update': { path: 'update', app: true, flags: { value: list('name', 'origin', 'logo', 'justification') } },
+    'set-logo': { path: 'set-logo', app: true, flags: { value: list('file') }, imageFile: true },
+    'set-brand-color': { path: 'set-brand-color', app: true, flags: { value: list('color') } },
     'set-redirect-uris': { path: 'set-redirect-uris', app: true, flags: { list: list('redirect-uri') } },
     'asks': { path: 'asks', app: true, flags: { value: list('group', 'source', 'query'), bool: list('requested') } },
     'set-scopes': { path: 'set-scopes', app: true, flags: { list: list('scope', 'add', 'remove'), bool: list('clear') } },
@@ -26,9 +29,9 @@ const LEAVES = {
 };
 /** What a coding agent's login can't do, by CLI leaf name. */
 const REFUSED = {
-    'set-listing': 'list an app in the marketplace',
-    'set-spend-cap': "change an app's spend cap",
-    'set-allows': 'change what an app shares',
+    'set-listing': "change an app's marketplace listing, price or welcome text",
+    'set-spend-cap': "change an app's monthly spend cap",
+    'set-allows': "change an app's sharing (what other apps may use)",
     'provider get': "read an app's provider role",
     'provider set': "change an app's provider role",
     'provider refresh': "refresh an app's provider role",
@@ -101,6 +104,14 @@ export async function runApps(argv) {
             }
             params.jwk = (await publicJwkFromFile(keyFile)).json;
         }
+        if (leaf.imageFile) {
+            const imageFile = flags.values.get('--file');
+            if (imageFile === undefined) {
+                console.error('Pass --file <path to a square PNG, JPEG, WebP or SVG, at most 512 KB>.');
+                return 1;
+            }
+            params.file = (await readFile(imageFile)).toString('base64');
+        }
     }
     catch (error) {
         console.error(error.message);

package/dist/cli-usage.d.ts

@@ -7,6 +7,8 @@ export interface CommandUsage {
     crtr: string;
 }
 export declare const COMMANDS: CommandUsage[];
+/** The text `crouter-sdk <command> --help` prints (exit 0): the usage lines and the summary. */
+export declare function helpOf(name: string): string;
 /** The usage text a command prints on a usage error. */
 export declare function usageOf(name: string): string;
 /** The text `crouter-sdk` prints with no command, an unknown one, or `--help`. */

package/dist/cli-usage.js

@@ -32,13 +32,13 @@ export const COMMANDS = [
     {
         name: 'login',
         forms: ['login [--no-browser] [--new] [--issuer <url>]'],
-        summary: 'Log this computer in to your Northlight account: prints a link and a code, you approve once in the browser, and a revocable login is saved to `~/.config/northlight/credentials.json`. Run it again if it times out: it resumes the same code. Calls only the Northlight directory.',
+        summary: 'Log this computer in to your Northlight account: prints a link and a code, you approve once in the browser, and a revocable login is saved to `~/.config/northlight/credentials.json`. Run it again if it times out or is interrupted: it resumes the same code. When this computer is already logged in it says so and exits 0; `--new` logs in again. Calls only the Northlight directory.',
         crtr: 'No',
     },
     {
         name: 'logout',
         forms: ['logout [--issuer <url>]'],
-        summary: 'Revoke this computer\'s login on the server and delete it locally.',
+        summary: 'Revoke this computer\'s login on the server and remove it from the credentials file (the file stays, without that login).',
         crtr: 'No',
     },
     {
@@ -58,11 +58,18 @@ export const COMMANDS = [
         forms: [
             'apps <leaf> [--app <client id>] [--issuer <url>] [leaf flags] [--json]',
         ],
-        summary: 'Call one app-management leaf with the login and print its answer as JSON. Leaves: `mine`, `get`, `update`, `set-redirect-uris`, `asks`, `set-scopes`, `set-requires`, `set-run-notice-url`, `keys list|add|retire|delete|set-jwks-uri|remove-jwks-uri`, `testers list|add|remove`. `--app` defaults to `CROUTER_CLIENT_ID` in `local/app.env`; `keys add` takes `--key-file <path>` and sends only the public half. Deleting an app, its marketplace listing, spend cap, sharing and provider role are console-only.',
+        summary: 'Call one app-management leaf with the login and print its answer as JSON. Leaves: `mine`, `get`, `update`, `set-logo`, `set-brand-color`, `set-redirect-uris`, `asks`, `set-scopes`, `set-requires`, `set-run-notice-url`, `keys list|add|retire|delete|set-jwks-uri|remove-jwks-uri`, `testers list|add|remove`. `--app` defaults to `CROUTER_CLIENT_ID` in `local/app.env`; `keys add` takes `--key-file <path>` and sends only the public half. Deleting an app, its marketplace listing, spend cap, sharing and provider role are console-only.',
         crtr: 'No',
     },
 ];
 const BIN = 'crouter-sdk';
+/** The text `crouter-sdk <command> --help` prints (exit 0): the usage lines and the summary. */
+export function helpOf(name) {
+    const command = COMMANDS.find((entry) => entry.name === name);
+    if (!command)
+        throw new Error(`unknown command ${name}`);
+    return `${usageOf(name)}\n\n${command.summary.replaceAll('`', '')}`;
+}
 /** The usage text a command prints on a usage error. */
 export function usageOf(name) {
     const command = COMMANDS.find((entry) => entry.name === name);

package/dist/client.d.ts

@@ -2,6 +2,7 @@ import { type HealthDTO, type MessageResultDTO, type NodeDetailDTO, type ListNod
 import { Bash } from './resources/bash.js';
 import { Canvas } from './resources/canvas.js';
 import { Crons } from './resources/crons.js';
+import { Docs } from './resources/docs.js';
 import { CustomObjects } from './resources/custom-objects.js';
 import { Attachments } from './resources/attachments.js';
 import { Files } from './resources/files.js';
@@ -127,6 +128,8 @@ export declare class Crouter {
     /** Read the documents the person owns (`store: 'user'`): an app sees their `public` documents, `private` ones too while the grant holds
      *  `crtr:memory:read_private:user` (read-only; `friends` never), and every privacy level with a `crtr:memory:manage:user` grant. */
     readonly memory: Memory;
+    /** Write, read and edit documents the calling app owns (`docs.write`, `docs.edit`, `docs.get`): for example one app-owned `preference` with a `boot` rule that carries the app's agent instructions. */
+    readonly docs: Docs;
     /** Scope-filtered provider tools and daemon-mediated calls. */
     readonly providers: Providers;
     /** The caller's grant. With `wait` (1–25 s) and `since` (a `version` from an earlier answer), the runtime holds the

package/dist/client.js

@@ -3,6 +3,7 @@ import { APIConnectionError, APIUserAbortError, AuthenticationError, CrouterErro
 import { Bash } from './resources/bash.js';
 import { Canvas } from './resources/canvas.js';
 import { Crons } from './resources/crons.js';
+import { Docs } from './resources/docs.js';
 import { CustomObjects } from './resources/custom-objects.js';
 import { Attachments } from './resources/attachments.js';
 import { Files } from './resources/files.js';
@@ -66,6 +67,8 @@ export class Crouter {
     /** Read the documents the person owns (`store: 'user'`): an app sees their `public` documents, `private` ones too while the grant holds
      *  `crtr:memory:read_private:user` (read-only; `friends` never), and every privacy level with a `crtr:memory:manage:user` grant. */
     memory;
+    /** Write, read and edit documents the calling app owns (`docs.write`, `docs.edit`, `docs.get`): for example one app-owned `preference` with a `boot` rule that carries the app's agent instructions. */
+    docs;
     /** Scope-filtered provider tools and daemon-mediated calls. */
     providers;
     /** The caller's grant. With `wait` (1–25 s) and `since` (a `version` from an earlier answer), the runtime holds the
@@ -223,6 +226,7 @@ export class Crouter {
         this.shares = new Shares(request);
         this.questions = new Questions(request);
         this.memory = new Memory(request);
+        this.docs = new Docs(request);
         this.runs = new Runs(request, (id, after, signal) => this.openRunEvents(id, after, signal), this.questions);
         this.providers = new Providers(request);
         this.grant = { get: (options = {}) => {

package/dist/index.d.ts

@@ -12,6 +12,7 @@ export type { FileDownloadOptions } from './resources/files.js';
 export type { Upload, UploadCreateParams } from './resources/uploads.js';
 export type { AttachmentLink } from './resources/attachments.js';
 export type { Share, ShareCreated, ShareCreateParams } from './resources/shares.js';
+export type { Doc, DocEditParams, DocWriteParams } from './resources/docs.js';
 export type { MemoryDocument, MemoryGetParams, MemoryListItem, MemoryListPage, MemoryListParams } from './resources/memory.js';
 export type { Question, QuestionAnswered, QuestionFields, QuestionResponses, QuestionSlot, QuestionStatus } from './resources/questions.js';
 export type { ProviderToolEntry } from './resources/providers.js';

package/dist/init-command.js

@@ -52,6 +52,9 @@ const packageJson = () => `${JSON.stringify({
     type: 'module',
     scripts: { start: START },
     dependencies: { '@north-light/sdk': SDK_VERSION, tsx: '^4.20.0' },
+    // npm 11.20+ warns about tsx's esbuild postinstall unless the project decides. esbuild runs from its platform
+    // binary without the script (it only swaps in a faster launcher), so the app denies it.
+    allowScripts: { esbuild: false },
 }, null, 2)}\n`;
 const ENV_TEXT = `CROUTER_ISSUER=${DEFAULT_ISSUER}\nAPP_ORIGIN=${DEFAULT_ORIGIN}\nCROUTER_CLIENT_ID=\nCROUTER_KEY_FILE=${KEY_FILE}\n`;
 const exists = (path) => stat(path).then(() => true, () => false);

package/dist/keygen-cli.js

@@ -2,7 +2,7 @@
 // The `crouter-sdk` bin: `init`, `skill`, `keygen`, `env`, and the developer commands `login`, `logout`, `whoami`, `register` and `apps`. The file keeps its first command's name because the
 // published bin path (`dist/keygen-cli.js`) is part of the package, and the package keeps exactly one bin so that
 // `npx @north-light/sdk <command>` works without naming it.
-import { overviewUsage } from './cli-usage.js';
+import { helpOf, overviewUsage } from './cli-usage.js';
 import { runEnv } from './env-command.js';
 import { runInit } from './init-command.js';
 import { runKeygen } from './keygen-command.js';
@@ -16,10 +16,19 @@ const args = process.argv.slice(2);
 const commands = { init: runInit, skill: runSkill, keygen: runKeygen, env: runEnv, login: runLogin, logout: runLogout, whoami: runWhoami, register: runRegister, apps: runApps };
 const command = args[0] ?? '';
 async function main() {
+    if (command === 'help' && args[1] !== undefined && Object.hasOwn(commands, args[1])) {
+        console.log(helpOf(args[1]));
+        return 0;
+    }
     if (command === '--help' || command === '-h' || command === 'help') {
         console.log(overviewUsage());
         return 0;
     }
+    // Help for a command is never an error: `<command> --help` and `<command> -h` print its usage and exit 0.
+    if (Object.hasOwn(commands, command) && args.slice(1).some((arg) => arg === '--help' || arg === '-h')) {
+        console.log(helpOf(command));
+        return 0;
+    }
     const run = Object.hasOwn(commands, command) ? commands[command] : undefined;
     if (!run) {
         console.error(overviewUsage());

package/dist/login-command.js

@@ -1,12 +1,14 @@
 import { spawn } from 'node:child_process';
 import { loadStore, newSecret, displayPath, credentialsPath, updateEntry } from './credentials.js';
 import { usageOf } from './cli-usage.js';
-import { NetworkError, DirectoryError, machineName, pollLogin, revokeCredential, startLogin } from './directory-client.js';
+import { NetworkError, DirectoryError, exchange, machineName, pollLogin, revokeCredential, startLogin } from './directory-client.js';
 import { parseFlags, reportFailure, resolveIssuer } from './developer-common.js';
 const USAGE = usageOf('login');
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 /** The poll interval in ms. The directory says 5 s; tests shorten it with NORTHLIGHT_LOGIN_POLL_MS. */
 const intervalMs = () => Number(process.env.NORTHLIGHT_LOGIN_POLL_MS) || 5000;
+/** How long polling keeps retrying through network failures (a sleeping laptop, a dropped connection) before it gives up. Tests shorten it with NORTHLIGHT_LOGIN_GIVEUP_MS. */
+const giveUpMs = () => Number(process.env.NORTHLIGHT_LOGIN_GIVEUP_MS) || 180_000;
 /** Tries to open `url` in a browser, detached. Resolves true when the opener started. */
 function openBrowser(url) {
     if (process.env.CI)
@@ -57,6 +59,25 @@ export async function runLogin(argv) {
     try {
         const store = await loadStore();
         let pending = store.issuers[issuer]?.pending;
+        const saved = store.issuers[issuer];
+        // Already logged in and nothing pending: say so instead of starting a second login that would replace this one.
+        if (saved?.credential && !pending && !flags.bools.has('--new')) {
+            try {
+                const token = await exchange(issuer, saved.credential);
+                console.log([
+                    `Already logged in as ${token.account.display} (${token.account.id}) on ${issuer}. Nothing to do.`,
+                    `The login for ${saved.name ?? token.credential_id} expires on ${token.expires_at.slice(0, 10)}, or after 14 days unused. To log in again as a new login, run \`npx @north-light/sdk login --new\`.`,
+                ].join('\n'));
+                return 0;
+            }
+            catch (error) {
+                // A login the directory no longer accepts is dropped, and a fresh login starts below. Anything else is reported.
+                if (!(error instanceof DirectoryError && error.status === 401))
+                    throw error;
+                await updateEntry(issuer, ({ credential: _c, credential_id: _i, name: _n, account_id: _a, account_display: _d, expires_at: _e, ...rest }) => rest);
+                console.log('The saved login is no longer valid, so starting a new one.');
+            }
+        }
         const now = Date.now();
         let resumed = false;
         if (pending && (flags.bools.has('--new') || !pending.device_code || !pending.expires_at || Date.parse(pending.expires_at) <= now)) {
@@ -97,8 +118,31 @@ export async function runLogin(argv) {
         console.log(`Waiting for approval (the code expires in ${minutes} minute${minutes === 1 ? '' : 's'})…`);
         let wait = intervalMs();
         const deadline = Date.parse(pending.expires_at) + 30_000;
+        let failingSince;
         for (;;) {
-            const answer = await pollLogin(issuer, pending.device_code);
+            let answer;
+            try {
+                answer = await pollLogin(issuer, pending.device_code);
+            }
+            catch (error) {
+                // One failed poll (the laptop slept, the connection dropped) does not end the login: the code is still saved and the
+                // person may be approving right now. Keep polling; give up only after a sustained outage or once the code has expired.
+                const transient = error instanceof NetworkError || (error instanceof DirectoryError && error.status >= 500);
+                if (!transient)
+                    throw error;
+                failingSince ??= Date.now();
+                if (Date.now() - failingSince > giveUpMs() || Date.now() > deadline) {
+                    const reason = error instanceof NetworkError ? error.reason : error.message;
+                    const left = Date.parse(pending.expires_at) > Date.now();
+                    console.error(left
+                        ? `Couldn't reach ${issuer} to check the login (${reason}). The code ${code} is still saved and valid until ${hhmm(pending.expires_at)}: run \`npx @north-light/sdk login\` again to carry on with it.`
+                        : `Couldn't reach ${issuer} (${reason}) and the code ${code} has expired. Run \`npx @north-light/sdk login\` again.`);
+                    return 1;
+                }
+                await sleep(wait);
+                continue;
+            }
+            failingSince = undefined;
             if (answer.status === 'approved') {
                 const old = (await loadStore()).issuers[issuer]?.credential;
                 await updateEntry(issuer, () => ({

package/dist/resources/docs.d.ts

@@ -0,0 +1,64 @@
+import { type DeliveryRuleDTO, type DocEditedDTO, type DocEditRequest, type DocKindName, type DocWriteRequest, type DocWrittenDTO, type ObjectDTO } from '@north-light/api';
+import type { RequestOptions } from '../types.js';
+import { type Request } from './request.js';
+/** `docs.write` input. */
+export interface DocWriteParams extends Omit<DocWriteRequest, 'owner' | 'cwd' | 'kind' | 'rules'> {
+    /** The document's name inside its owner: segments of letters, digits, `_` or `-` joined by `/`. */
+    name: string;
+    /** The markdown body. `[[name]]` links are resolved against the app's view. */
+    body: string;
+    /** One non-empty line saying when to read the document. */
+    preview: string;
+    /** `knowledge` (default) or `preference`. A `preference` is loaded into every node's context that sees it. */
+    kind?: DocKindName;
+    /** When the document is delivered to a node: `{on: 'boot', deliver: 'content'}` puts the whole body into the context of every node at boot. */
+    rules?: DeliveryRuleDTO[];
+    /** Whose document it is. Defaults to the calling app (`'app'`), which is the only owner an app server can write as. */
+    owner?: 'app';
+}
+/** `docs.edit` input: a new `body` or exact-text `replace` blocks (not both), and/or document fields. */
+export type DocEditParams = Omit<DocEditRequest, 'base'> & {
+    /** The `base` from the `docs.get` the change was computed from. Absent, the edit is made from this app's last `docs.get` or `docs.write` of the document;
+     *  with neither it is refused (`ConflictError`, code `read_first`). A base that is no longer current is refused (`ConflictError`, code `stale_revision`) and writes nothing. */
+    base?: string;
+};
+/** A document read by `docs.get`. */
+export interface Doc {
+    id: string;
+    /** `<owner handle>/<name>`: what `docs.write` returned and what `docs.edit` and `docs.get` accept. */
+    name: string;
+    /** The document's kind: `knowledge` or `preference`. */
+    kind: string | null;
+    privacy: ObjectDTO['privacy'];
+    preview: string;
+    summary: string | null;
+    owner: ObjectDTO['owner'];
+    /** The current revision number. */
+    revision: number;
+    /** The current body (the first head's, when `needsMerge`). */
+    body: string;
+    /** Every head's body, in head order. More than one only after concurrent edits. */
+    bodies: string[];
+    /** `true` when the document has several heads: the next edit must pass the whole merged `body`. */
+    needsMerge: boolean;
+    /** The edit base for this read: pass it as `base` to `docs.edit` to change exactly this revision. */
+    base: string;
+    /** The delivery rules the document carries. */
+    rules: DeliveryRuleDTO[];
+}
+/**
+ * Documents the calling app owns (`docs.write` defaults the owner to the app): write one, read it, edit it in place.
+ * An app server holds no node, so it cannot write as `node`; it writes as `app`. A document the app owns is readable
+ * and changeable with no scope. Served on the app listener.
+ */
+export declare class Docs {
+    private readonly request;
+    constructor(request: Request);
+    /** Create a document. Returns its canonical `name`. A name already taken in the owner throws `ConflictError` (`name_taken`). */
+    write(params: DocWriteParams, options?: RequestOptions): Promise<DocWrittenDTO>;
+    /** Change a document in place: a new body or replacements, and/or fields (`preview`, `rules`, `privacy`, …). Returns the new `revision`.
+     *  `ref` is the canonical name `docs.write` returned. */
+    edit(ref: string, params: DocEditParams, options?: RequestOptions): Promise<DocEditedDTO>;
+    /** Read a document with its body, revision, edit base and rules. Throws `NotFoundError` when no such document is in the app's view. */
+    get(ref: string, options?: RequestOptions): Promise<Doc>;
+}

package/dist/resources/docs.js

@@ -0,0 +1,47 @@
+import { routes, } from '@north-light/api';
+import { BadRequestError, NotFoundError } from '../errors.js';
+import { withQuery } from './request.js';
+/**
+ * Documents the calling app owns (`docs.write` defaults the owner to the app): write one, read it, edit it in place.
+ * An app server holds no node, so it cannot write as `node`; it writes as `app`. A document the app owns is readable
+ * and changeable with no scope. Served on the app listener.
+ */
+export class Docs {
+    request;
+    constructor(request) {
+        this.request = request;
+    }
+    /** Create a document. Returns its canonical `name`. A name already taken in the owner throws `ConflictError` (`name_taken`). */
+    write(params, options) {
+        return this.request('POST', routes.docs(), params, options);
+    }
+    /** Change a document in place: a new body or replacements, and/or fields (`preview`, `rules`, `privacy`, …). Returns the new `revision`.
+     *  `ref` is the canonical name `docs.write` returned. */
+    edit(ref, params, options) {
+        return this.request('PATCH', routes.doc(ref), params, options);
+    }
+    /** Read a document with its body, revision, edit base and rules. Throws `NotFoundError` when no such document is in the app's view. */
+    async get(ref, options) {
+        const read = await this.request('GET', withQuery(routes.object(ref), { fields: 1 }), undefined, options);
+        if (read.state !== 'object')
+            throw new NotFoundError(404, 'not_found', `${ref} is ${read.state === 'deleted' ? 'deleted' : 'not a document in this runtime'}`);
+        if (read.type !== 'document')
+            throw new BadRequestError(400, 'invalid_request', `${ref} is a ${read.type}, not a document`);
+        const data = read.data;
+        const owner = read.object.owner;
+        return {
+            id: read.object.id,
+            name: owner ? `${owner.handle}/${read.object.name}` : read.object.name,
+            kind: read.object.kind, privacy: read.object.privacy, preview: read.object.preview, summary: data.summary, owner,
+            revision: data.revision, body: data.bodies[0] ?? '', bodies: data.bodies, needsMerge: data.needs_merge,
+            base: data.heads.map((h) => h.rev_id).sort().join(','),
+            // The daemon's rule rows carry storage columns (`rowid`, `object`, `owner`, `position`); hand back only the rule.
+            rules: (data.fields?.rules ?? []).map(({ on, deliver, match, match_frontmatter, if: condition }) => ({
+                on, deliver,
+                ...(match !== undefined ? { match } : {}),
+                ...(match_frontmatter !== undefined ? { match_frontmatter } : {}),
+                ...(condition !== undefined ? { if: condition } : {}),
+            })),
+        };
+    }
+}

package/dist/skill/northlight/SKILL.md

@@ -2,7 +2,7 @@
 name: northlight
 description: "Use when building, debugging or shipping an app that signs people in with Northlight, starts runs on their Northlight runtime, or calls Northlight providers (sms, search, integrations, context, device) with @north-light/sdk."
 metadata:
-  sdk-version: "0.3.487"
+  sdk-version: "0.3.488"
 ---
 
 # Building a Northlight app
@@ -11,7 +11,7 @@ An app on Northlight signs people in with their Northlight account, then starts
 
 ## First: check this skill matches the SDK
 
-This skill is for SDK version `0.3.487`. If the project has `node_modules/@north-light/sdk/package.json`, compare its `version` with that number. If they differ, run `npx @north-light/sdk skill` in the project, then read the rewritten `.agents/skills/northlight/SKILL.md` (or `.claude/skills/northlight/SKILL.md`) instead of this copy. That command needs no account and no crtr. A project that has no SDK yet starts with `npx @north-light/sdk@latest init <dir>`.
+This skill is for SDK version `0.3.488`. If the project has `node_modules/@north-light/sdk/package.json`, compare its `version` with that number. If they differ, run `npx @north-light/sdk skill` in the project, then read the rewritten `.agents/skills/northlight/SKILL.md` (or `.claude/skills/northlight/SKILL.md`) instead of this copy. That command needs no account and no crtr. A project that has no SDK yet starts with `npx @north-light/sdk@latest init <dir>`.
 
 ## Where things run
 
@@ -27,9 +27,15 @@ You run the commands. The person does two things in a browser: signs up, and cho
 
 1. **Account (person).** They sign up at `https://account.northlight.ai/signup`. Signup texts a code over iMessage, so the phone must have iMessage.
 2. **Scaffold (you).** In a new folder run `npx @north-light/sdk@latest init my-app`. In an existing Node project run `npx @north-light/sdk init` instead: it adds the SDK pinned to an exact version, a key and this skill, and overwrites nothing. A new app gets `local/app.env` with the issuer, the origin `http://localhost:3000` and an empty `CROUTER_CLIENT_ID=`.
-3. **Log in (you run it, the person approves).** Run `npx @north-light/sdk login`. It prints a link and a code. Show the person the link and the code exactly as printed and ask them to open the link, check the page shows the same code, and choose **Allow**. If your command times out first, run `login` again: it resumes the same code (do not pass `--new`). `npx @north-light/sdk whoami` checks the login. If `login` cannot reach `account.northlight.ai`, use step 7.
-4. **Register (you).** For the quickstart app run `npx @north-light/sdk register --scope sms:send`. `sms:send` is the scope `server.ts` requests. It registers the app with the public key from `local/app-key.json`, adds the scope and writes `CROUTER_CLIENT_ID` to `local/app.env`. For any other provider scope: register first, find the string with `npx @north-light/sdk apps asks` (it needs the registered app), then add it with `npx @north-light/sdk apps set-scopes --add <scope>`. Never invent a scope string ([Scopes and grants](https://sdk.docs.northlight.ai/docs/concepts/scopes-and-grants.md)).
-5. **Run it (you, then the person).** `npm i`, then `npm start`. Ask the person to open `http://localhost:3000/auth/login`, sign in and choose **Allow**. The page then starts a run and sends them a text.
+3. **Log in (you run it, the person approves).** Run `npx @north-light/sdk login`. It prints a link and a code. Show the person the link and the code exactly as printed and ask them to open the link, check the page shows the same code, and choose **Allow**. Read everything `login` printed and its exit code before you tell the person what happened. If your command times out or is killed first, run `login` again: it resumes the same code (do not pass `--new`). Each message means one thing:
+   - `Still waiting for the login started at HH:MM.` is the same code: ask the person to approve it.
+   - `Already logged in as …` (exit 0) means the login exists: go to step 4. Do not log in again.
+   - `The code expired before it was approved` (exit 1) means nobody approved it in 10 minutes: run `login` again for a new code and tell the person to approve that one promptly. It is not a network problem.
+   - `The login was declined in the browser` (exit 1): the person chose Deny. Ask before trying again.
+   - `Couldn't reach … The code … is still saved` (exit 1) is a network problem that may pass: run `login` again to resume. Only if it keeps failing, use step 7.
+   `npx @north-light/sdk whoami` checks the login. Never describe a failure as a network timeout unless the output says it couldn't reach the directory.
+4. **Register (you).** For the quickstart app run `npx @north-light/sdk register --scope sms:send`. `sms:send` is the scope `server.ts` requests. It registers the app with the public key from `local/app-key.json`, adds the scope and writes `CROUTER_CLIENT_ID` to `local/app.env`. For any other provider scope: register first, find the string with `npx @north-light/sdk apps asks` (it needs the registered app), then add it with `npx @north-light/sdk apps set-scopes --add <scope>`. Never invent a scope string ([Scopes and grants](https://sdk.docs.northlight.ai/docs/concepts/scopes-and-grants.md)). To give the app a logo image or brand colour, use `apps set-logo --file <path>` and `apps set-brand-color --color <#rrggbb>`.
+5. **Run it (you, then the person).** `npm i`, then `npm start`. Run `npm i` before `register` or any other command if the project pins an SDK version: without installed dependencies `npx` downloads the newest published release of the SDK, not the pinned one. Ask the person to open `http://localhost:3000/auth/login`, sign in and choose **Allow**. The page then starts a run and sends them a text.
 6. **Testing mode.** A new app is in testing: only its owner and up to 100 testers can sign in. Add one with `npx @north-light/sdk apps testers add --email <email>`. Anyone else's callback gets `error=access_denied` with `error_description=app_in_testing` ([Testing mode](https://sdk.docs.northlight.ai/docs/concepts/testing-mode.md)). Going public needs verification: email support@northlight.ai.
 7. **If login is not possible** (no network to `account.northlight.ai`, or the person prefers the browser): they register at `https://account.northlight.ai/console/new`. Ask them to fill in **Name**, **Origin URL** (`http://localhost:3000`), **Logo URL** (a square image), **Why your app needs access** (one sentence) and **Redirect URIs** (`http://localhost:3000/auth/callback`, matched exactly), and to paste the public JWK that `init` printed. Never ask for or accept the private key. On the app's **What it asks for** tab they choose **Add permissions**, add `sms:send` and choose **Save** (**Done** alone stores nothing). Ask for the client ID the console shows, then run `npx @north-light/sdk env --client-id <client id>`.
 
@@ -147,8 +153,8 @@ Details behind each rule: [Errors](https://sdk.docs.northlight.ai/docs/errors.md
 - **Pin the exact SDK version** (`npm i --save-exact`). A later release can change a type or method, and `^` picks it up on the next `npm i`.
 - **Take scope strings from `npx @north-light/sdk apps asks`, the console's Add permissions list or `providers.tools`.** Never invent one. Tool names and arguments also come from `providers.tools('<provider>')`.
 - **Never print, paste, log or commit `local/app-key.json`, `~/.config/northlight/credentials.json` or any `nld_` value.** `local/` is in `.gitignore`. If the app key leaks, add a new key in the console, switch to it, and retire the old one.
-- **Do not run `logout` unless the person asks.** It revokes the login and the next session must ask them to approve again.
-- **Deleting an app, listing it in the marketplace, its spend cap and sharing are the person's, in the console** (`https://account.northlight.ai/console`). Name the page; do not try the CLI, which refuses. On a verified app, signing keys, the JWKS URL, redirect URIs and the run notice URL change there too ([Manage your app](https://sdk.docs.northlight.ai/docs/guides/manage-your-app.md)).
+- **Do not run `logout` unless the person asks.** It revokes the login on the server and removes it from `~/.config/northlight/credentials.json` (the file stays, with no login in it); the next session must ask them to approve again.
+- **Deleting an app, listing it in the marketplace, its monthly spend cap and sharing are the person's, in the console** (`https://account.northlight.ai/console`). Name the page; do not try the CLI, which refuses. On a verified app, signing keys, the JWKS URL, redirect URIs and the run notice URL change there too ([Manage your app](https://sdk.docs.northlight.ai/docs/guides/manage-your-app.md)).
 - **Use `oauth.client(userId)` for a person's runtime. Never `new Crouter()`.** `Crouter` is the client for a runtime you run yourself, not for apps.
 - **Use a persistent `ConnectionStore` in production.** `MemoryConnectionStore` loses every sign-in on restart and does not work across processes. `@north-light/sdk/stores/postgres` is the production store.
 - **Use `runs.parse` with a schema for data. Never parse `runs.trace`.** The trace is what the model said; `output_parsed` is a value checked against your schema.
@@ -166,11 +172,11 @@ Details behind each rule: [Errors](https://sdk.docs.northlight.ai/docs/errors.md
 | `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 |
 | `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` |
 | `env --client-id <client id> [--origin <url>] [--issuer <url>] [--out <path>]`<br>`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` |
-| `login [--no-browser] [--new] [--issuer <url>]` | Log this computer in to your Northlight account: prints a link and a code, you approve once in the browser, and a revocable login is saved to `~/.config/northlight/credentials.json`. Run it again if it times out: it resumes the same code. Calls only the Northlight directory. | No |
-| `logout [--issuer <url>]` | Revoke this computer's login on the server and delete it locally. | No |
+| `login [--no-browser] [--new] [--issuer <url>]` | Log this computer in to your Northlight account: prints a link and a code, you approve once in the browser, and a revocable login is saved to `~/.config/northlight/credentials.json`. Run it again if it times out or is interrupted: it resumes the same code. When this computer is already logged in it says so and exits 0; `--new` logs in again. Calls only the Northlight directory. | No |
+| `logout [--issuer <url>]` | Revoke this computer's login on the server and remove it from the credentials file (the file stays, without that login). | No |
 | `whoami [--issuer <url>]` | Show the account this computer is logged in as and when the login expires. Exits 1 when not logged in. | No |
 | `register [--name <text>] [--scope <scope>]... [--logo <url>] [--justification <text>] [--redirect-uri <uri>]... [--issuer <url>]` | Run in a project made by `init`, after `login`: registers the app with the public key from `local/app-key.json`, adds each `--scope` beyond `crtr:llm crtr:act`, and writes `CROUTER_CLIENT_ID` and `CROUTER_ISSUER` to `local/app.env`. | No |
-| `apps <leaf> [--app <client id>] [--issuer <url>] [leaf flags] [--json]` | Call one app-management leaf with the login and print its answer as JSON. Leaves: `mine`, `get`, `update`, `set-redirect-uris`, `asks`, `set-scopes`, `set-requires`, `set-run-notice-url`, `keys list|add|retire|delete|set-jwks-uri|remove-jwks-uri`, `testers list|add|remove`. `--app` defaults to `CROUTER_CLIENT_ID` in `local/app.env`; `keys add` takes `--key-file <path>` and sends only the public half. Deleting an app, its marketplace listing, spend cap, sharing and provider role are console-only. | No |
+| `apps <leaf> [--app <client id>] [--issuer <url>] [leaf flags] [--json]` | Call one app-management leaf with the login and print its answer as JSON. Leaves: `mine`, `get`, `update`, `set-logo`, `set-brand-color`, `set-redirect-uris`, `asks`, `set-scopes`, `set-requires`, `set-run-notice-url`, `keys list|add|retire|delete|set-jwks-uri|remove-jwks-uri`, `testers list|add|remove`. `--app` defaults to `CROUTER_CLIENT_ID` in `local/app.env`; `keys add` takes `--key-file <path>` and sends only the public half. Deleting an app, its marketplace listing, spend cap, sharing and provider role are console-only. | No |
 
 ## Pages
 

package/dist/version.d.ts

@@ -1,5 +1,5 @@
 /** This SDK's release version. Informational only: compatibility is the contract level, not this number. */
-export declare const SDK_VERSION = "0.3.487";
+export declare const SDK_VERSION = "0.3.488";
 /** The release sent in `Crouter-Minimum-Runtime-Version` on every request. It is frozen, so a runtime from before the
  *  contract level existed (which only knows this header) refuses this SDK, while every later runtime accepts it. */
 export declare const LEGACY_FLOOR = "0.3.423";

package/dist/version.js

@@ -1,6 +1,6 @@
 // SDK_VERSION is written by scripts/release-version.mjs on every release; do not edit by hand.
 /** This SDK's release version. Informational only: compatibility is the contract level, not this number. */
-export const SDK_VERSION = '0.3.487';
+export const SDK_VERSION = '0.3.488';
 // LEGACY_FLOOR is written once by `scripts/contract.mjs release`, at the first release that carries the contract level
 // (the `0.0.0` placeholder is replaced there and never again); do not edit by hand.
 /** The release sent in `Crouter-Minimum-Runtime-Version` on every request. It is frozen, so a runtime from before the

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@north-light/sdk",
-  "version": "0.3.487",
-  "crouterContract": "1.11",
+  "version": "0.3.488",
+  "crouterContract": "1.12",
   "description": "Typed Node and browser client for running crouter agents through the crtrd /v1 API.",
   "type": "module",
   "main": "./dist/index.js",
@@ -44,8 +44,8 @@
     "prepublishOnly": "node -e \"if (process.env.npm_config_tag !== 'next') { console.error('@north-light/sdk publishes only with --tag next; scripts/promote-sdk.mjs is the only mover of latest.'); process.exit(1); }\""
   },
   "dependencies": {
-    "@north-light/api": "0.3.487",
-    "@north-light/identity": "0.3.487",
+    "@north-light/api": "0.3.488",
+    "@north-light/identity": "0.3.488",
     "jose": "^6.2.1"
   },
   "peerDependencies": {