@coswic/aipay 0.7.2 → 0.8.1

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # @coswic/aipay
 
+## 0.8.1 — 2026-10-11
+
+- The sign-in helpers that `aipay init` generates, and the CLI's own sign-in, pass the SDK's new `authOrigin` option (the authorization server origin) instead of the option name the SDK now deprecates.
+- `aipay init` upgrades an `@coswic/aipay-sdk` older than 0.5.1 that the project already has — the installed version, or the package.json range when nothing is installed yet — by running `<package manager> add @coswic/aipay-sdk@latest`; with `--no-install` it prints that command instead, and `--dry-run` shows it. The JSON result reports this as `sdk_upgrade`. `aipay doctor` warns when the installed SDK is older than 0.5.1.
+- The rules section of the generated `aipay-agent.md` is now headed "Rules for the coding agent". README and code comments reworded; no other behavior change.
+- Requires `@coswic/aipay-sdk` ^0.5.1.
+
+## 0.8.0 — 2026-10-09
+
+- `aipay test`: a 401 from the API now says that, during the invitation-only beta, the signed-in user may hold no current invitation (or not have accepted the latest Terms) and that refreshing does not help; a sign-in that never reaches the loopback callback prints the same hint next to the timeout.
+- Developer commands: the 401 hint mentions that the developer account itself may not be invited yet, instead of only "run `aipay login` again".
+- `aipay test` picks its default model among the ones the catalog marks available (`aipay.availability`, SDK 0.5.0 type); older servers without the field behave as before.
+- Brand spelling follows the product: "AI Pay" (no hyphen) in the README, help text, messages, scaffolded templates and the generated `aipay-agent.md`; package.json names the provider, Coswic Labs (https://coswic.ai), as author. Command names, env keys and identifiers are unchanged.
+- Requires `@coswic/aipay-sdk` ^0.5.0.
+
 ## 0.7.2 — 2026-10-09
 
 - README: describe AI-Pay's invitation-only beta instead of self sign-up seats (only invited users can create an account; public registration is not open; your users must be invited before their first sign-in through your app; production does not accept top-ups at the moment), and explain what `aipay test` and the developer commands do when the user or the developer account is not invited. No behavior change.
@@ -23,7 +38,7 @@
 - Add `apps callbacks list/add/remove` with the developer’s own management authorization and linked-project defaults.
 - Preserve other registered callbacks, make no-op changes idempotent, and refuse to remove the final callback.
 - Require server ETag support for mutations; concurrent edits and uncertain outcomes require readback instead of blind retries.
-- Guide agents through developer CLI login and callback management; local `init` remains distinct from server registration.
+- Guide the coding agent through developer CLI login and callback management; local `init` remains distinct from server registration.
 - Allow HTTPS application callbacks in `init` and `doctor`; `test --callback` can use a separately registered loopback callback without changing project settings.
 - Bound developer API requests to 30 seconds and allow conditional mutations to disable automatic retries after a 401.
 

package/README.md

@@ -1,7 +1,7 @@
-# @coswic/aipay — AI-Pay CLI
+# @coswic/aipay — AI Pay CLI
 
 The command-line companion to [`@coswic/aipay-sdk`](https://www.npmjs.com/package/@coswic/aipay-sdk).
-Made for developers and for the coding agents they hand the Console prompt to.
+Made for developers and for the coding agent they hand the Console prompt to.
 
 ```bash
 npx @coswic/aipay@latest login --api <api base>
@@ -16,9 +16,9 @@ npx @coswic/aipay test
 - **Models and prices**: https://ai-pay.coswic.ai/models?lang=en · **API contract**: https://ai-pay.coswic.ai/openapi.yaml
 - **Product overview and what is open today**: https://ai-pay.coswic.ai/about?lang=en
 
-AI-Pay's production environment is in a free beta limited to invited users: only invited users can create an account and use the service, public registration is not open, and your users must also be invited before their first sign-in through your app's "Sign in with AI-Pay". Production does not accept top-ups at the moment. `<api base>` and `<authorization server>` are the endpoints of the environment you integrate with — the developer guide fetched from that environment has both filled in.
+AI Pay's production environment is in a free beta limited to invited users: only invited users can create an account and use the service, public registration is not open, and your users must also be invited before their first sign-in through your app's "Sign in with AI Pay". Production does not accept top-ups at the moment. `<api base>` and `<authorization server>` are the endpoints of the environment you integrate with — the developer guide fetched from that environment has both filled in.
 
-`aipay test` signs in as a real user: during the invitation-only beta that user must already hold an invitation (and have accepted the latest Terms), otherwise the sign-in never reaches the callback and `test` ends with the loopback timeout. The developer account you use with `aipay login` must be invited too; otherwise the developer commands keep answering 401 ("run `aipay login` again").
+`aipay test` signs in as a real user: during the invitation-only beta that user must already hold an invitation (and have accepted the latest Terms), otherwise the sign-in never reaches the callback and `test` ends with the loopback timeout. The developer account you use with `aipay login` must be invited too; otherwise the developer commands answer 401 and say so (since 0.8.0 the message mentions the invitation requirement instead of only "run `aipay login` again").
 
 ## Commands
 
@@ -30,8 +30,8 @@ AI-Pay's production environment is in a free beta limited to invited users: only
 | `aipay apps callbacks list --app <client_id>` | Read the registered callback URLs. In a linked project, `--app` can be omitted; `--dir` selects the project. |
 | `aipay apps callbacks add --app <client_id> --callback <url>` | Add a registered callback while preserving the others. Adding an existing URL makes no write. |
 | `aipay apps callbacks remove --app <client_id> --callback <url>` | Remove one callback; removing an absent URL makes no write. The final callback cannot be removed. |
-| `aipay init` | Links the project to your app: writes `.aipay/project.json` (commit it), `.env.local` (public values only, git-ignored), a start/callback route for your framework (Next.js, Express, Fastify, Hono, plain Node) or a browser helper for a Vite SPA (`--framework` overrides detection), `aipay-agent.md` (the developer docs, fetched once, for your agent to read offline) and installs the SDK. Never overwrites a file it did not write this run. `--dry-run` shows the plan. |
-| `aipay test` | The proof: a real sign-in through the AI-Pay authorization server, received by the CLI on a loopback callback, then one chat completion on that user's behalf. Prints the receipt (`request_id`, amount charged). The Console's verify step turns green from the server side. The authorization server ignores the port for `127.0.0.1` redirect URIs (RFC 8252), so the CLI binds any free port and your dev server can keep running; `--port <n>` forces one. `--no-open` prints the URL instead of opening a browser; `--model <id>` picks the model. |
+| `aipay init` | Links the project to your app: writes `.aipay/project.json` (commit it), `.env.local` (public values only, git-ignored), a start/callback route for your framework (Next.js, Express, Fastify, Hono, plain Node) or a browser helper for a Vite SPA (`--framework` overrides detection), `aipay-agent.md` (the developer docs, fetched once, for your agent to read offline) and installs the SDK — or upgrades it when the project already has one older than 0.5.1, which the generated code needs (`--no-install` prints the command instead). Never overwrites a file it did not write this run. `--dry-run` shows the plan. |
+| `aipay test` | The proof: a real sign-in through the AI Pay authorization server, received by the CLI on a loopback callback, then one chat completion on that user's behalf. Prints the receipt (`request_id`, amount charged). The Console's verify step turns green from the server side. The authorization server ignores the port for `127.0.0.1` redirect URIs (RFC 8252), so the CLI binds any free port and your dev server can keep running; `--port <n>` forces one. `--no-open` prints the URL instead of opening a browser; `--model <id>` picks the model. |
 | `aipay doctor` | Checks Node, the link, `.env.local`, the SDK install, and that the authorization server and API are reachable. `--offline` skips the network. |
 | `aipay status` | What this directory is linked to. |
 | `aipay unlink` | Forgets the link (removes `.aipay/project.json`, strips `AIPAY_*` from `.env.local`); keeps your code. |
@@ -102,7 +102,7 @@ to check the configured endpoints before retrying.
 ```
 .aipay/project.json   # app client_id, endpoints, callback, what was scaffolded — no secrets
 .env.local            # AIPAY_CLIENT_ID / AIPAY_AUTH_ORIGIN / AIPAY_API_BASE / AIPAY_CALLBACK_URL
-aipay-agent.md        # project facts + the developer docs, for coding agents
+aipay-agent.md        # project facts + the developer docs, for your coding agent
 src/aipay.ts          # sign-in helpers (start → callback → first completion)
 src/aipay-routes.ts   # framework wiring (or app/auth/aipay/*/route.ts for Next.js)
 ```

package/dist/agent-guide.d.ts

@@ -1,6 +1,6 @@
 /**
  * `aipay-agent.md`: the file a coding agent reads first. Header = the facts of THIS
- * project (app, endpoints, what was scaffolded, what "done" means); body = the AI-Pay
+ * project (app, endpoints, what was scaffolded, what "done" means); body = the AI Pay
  * developer docs fetched from the API (`/docs.md?lang=en`), so the agent does not need
  * network access to read them later.
  *

package/dist/agent-guide.js

@@ -4,11 +4,11 @@ export function agentGuide(input) {
     const callback = new URL(p.callback);
     const verification = callback.protocol === 'https:' || callback.search
         ? 'Sign in through the running app and make one chat completion whose response carries a receipt (`aipay.request_id`). Alternatively, use `aipay test --callback <registered-http-loopback-url>` with an already registered HTTP loopback URL without a query; leave the project callback unchanged.'
-        : '`aipay test` completes: a real sign-in through the AI-Pay authorization server and one chat completion whose response carries a receipt (`aipay.request_id`).';
+        : '`aipay test` completes: a real sign-in through the AI Pay authorization server and one chat completion whose response carries a receipt (`aipay.request_id`).';
     const files = input.scaffolded.length
         ? input.scaffolded.map((f) => `- \`${f}\``).join('\n')
         : '- (none — the project had them already)';
-    const head = `# AI-Pay integration guide for this project
+    const head = `# AI Pay integration guide for this project
 
 > Written by \`aipay init\` on ${p.linked_at}. Regenerate with \`aipay init --app ${p.app.client_id}\`. Safe to commit: it contains no secrets.
 
@@ -33,7 +33,7 @@ ${files}
 3. ${verification}
 4. Typecheck/build pass. Do not commit automatically and do not deploy.
 
-## Rules for agents
+## Rules for the coding agent
 
 - Read the docs below before changing the integration; they are the source of truth.
 - Use standard OAuth sign-in and app authorization.
@@ -47,7 +47,7 @@ ${files}
     const body = input.docsMarkdown
         ? `---
 
-# AI-Pay developer documentation
+# AI Pay developer documentation
 
 _Fetched from ${input.docsUrl} by \`aipay init\`._
 
@@ -55,7 +55,7 @@ ${input.docsMarkdown.trim()}
 `
         : `---
 
-# AI-Pay developer documentation
+# AI Pay developer documentation
 
 The docs could not be fetched when this file was written (see the \`aipay init\` output).
 Check the endpoint URL and network connectivity, then read

package/dist/args.d.ts

@@ -1,5 +1,5 @@
 /**
- * Tiny argv parser — zero deps on purpose (the CLI is installed by coding agents in
+ * Tiny argv parser — zero deps on purpose (the CLI gets installed by a coding agent into
  * arbitrary projects; every dependency is attack surface and install time).
  *
  * Supports `--flag`, `--flag value`, `--flag=value`, `--no-flag`, and positionals.

package/dist/commands/app-callbacks.js

@@ -53,7 +53,7 @@ function thrownError(error) {
         ? error.publicError
         : error instanceof CliError
             ? { code: error.code, message: error.message }
-            : { code: 'network_error', message: 'Could not confirm the callback request with AI-Pay.' };
+            : { code: 'network_error', message: 'Could not confirm the callback request with AI Pay.' };
 }
 /** Preserve exact URI strings: OAuth callback matching is not URL normalization. */
 function validateCallback(value) {
@@ -134,7 +134,7 @@ function checkEnvironment(project, auth) {
         if (!expected || expected !== normalized(auth[key]))
             throw new CallbackError({
                 code: 'environment_mismatch',
-                message: 'The linked project belongs to a different AI-Pay environment. Sign in to the correct environment first; use --app explicitly only to manage an app in the current login environment.',
+                message: 'The linked project belongs to a different AI Pay environment. Sign in to the correct environment first; use --app explicitly only to manage an app in the current login environment.',
                 outcome: 'not_attempted',
             }, EXIT.problem);
     }
@@ -150,7 +150,7 @@ async function readCallbacks(api, path, appId) {
         (body.client_id !== undefined && body.client_id !== appId))
         throw new CallbackError({
             code: 'invalid_response',
-            message: 'AI-Pay returned an invalid callback list.',
+            message: 'AI Pay returned an invalid callback list.',
         });
     const system = typeof body.test_callback_uri === 'string' ? body.test_callback_uri : undefined;
     return {
@@ -176,13 +176,13 @@ async function execute(api, input) {
         !/^"redirect-uris-[0-9a-f]{64}"$/.test(before.redirect_uris_etag))
         throw new CallbackError({
             code: 'conditional_update_unavailable',
-            message: 'This AI-Pay service does not provide a supported callback version. Update the service before changing callbacks; callbacks list remains available.',
+            message: 'This AI Pay service does not provide a supported callback version. Update the service before changing callbacks; callbacks list remains available.',
             outcome: 'not_attempted',
         }, EXIT.problem);
     if (input.callback === before.test_callback_uri)
         throw new CallbackError({
             code: 'system_callback',
-            message: 'This callback is managed by AI-Pay and cannot be added or removed.',
+            message: 'This callback is managed by AI Pay and cannot be added or removed.',
             outcome: 'not_attempted',
         }, EXIT.problem);
     const present = before.redirect_uris.includes(input.callback);
@@ -257,7 +257,7 @@ async function execute(api, input) {
     };
 }
 export async function runCallbacks(args, out, env) {
-    // Reject malformed invocations before loading credentials or contacting AI-Pay.
+    // Reject malformed invocations before loading credentials or contacting AI Pay.
     const input = inputOf(args);
     let environment;
     try {

package/dist/commands/doctor.js

@@ -7,7 +7,7 @@ import { existsSync, readFileSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { flagBool, flagString } from '../args.js';
 import { parseAppCallback } from '../callback-url.js';
-import { detectProject } from '../detect.js';
+import { detectProject, outdatedSdk, SDK_MIN_VERSION } from '../detect.js';
 import { EXIT } from '../output.js';
 import { ENV_FILE, ENV_KEYS, readProject } from '../project.js';
 import { createRemote, docsUrl, EMPTY_404_HINT } from '../remote.js';
@@ -95,19 +95,29 @@ export async function collectChecks(dir, opts, deps) {
     const det = detectProject(dir);
     if (det.hasPackageJson) {
         const installed = det.sdkInstalled && existsSync(join(dir, 'node_modules', '@coswic', 'aipay-sdk'));
-        checks.push(installed
-            ? { id: 'sdk', level: 'ok', text: '@coswic/aipay-sdk installed' }
-            : det.sdkInstalled
-                ? {
-                    id: 'sdk',
-                    level: 'bad',
-                    text: '@coswic/aipay-sdk is in package.json but not installed — run your package manager install',
-                }
-                : {
-                    id: 'sdk',
-                    level: 'bad',
-                    text: '@coswic/aipay-sdk not a dependency — rerun `aipay init` (or add it yourself)',
-                });
+        // Only the installed version counts here (the spec alone says nothing about what runs).
+        const old = installed && det.sdkVersion
+            ? outdatedSdk({ sdkVersion: det.sdkVersion, sdkSpec: null })
+            : null;
+        checks.push(old
+            ? {
+                id: 'sdk',
+                level: 'warn',
+                text: `@coswic/aipay-sdk ${old} installed — code generated by \`aipay init\` needs ${SDK_MIN_VERSION} or later; rerun \`aipay init\` or upgrade it`,
+            }
+            : installed
+                ? { id: 'sdk', level: 'ok', text: '@coswic/aipay-sdk installed' }
+                : det.sdkInstalled
+                    ? {
+                        id: 'sdk',
+                        level: 'bad',
+                        text: '@coswic/aipay-sdk is in package.json but not installed — run your package manager install',
+                    }
+                    : {
+                        id: 'sdk',
+                        level: 'bad',
+                        text: '@coswic/aipay-sdk not a dependency — rerun `aipay init` (or add it yourself)',
+                    });
         for (const f of project.scaffold.files)
             if (!existsSync(join(dir, f)))
                 checks.push({ id: 'scaffold', level: 'warn', text: `scaffolded file removed: ${f}` });

package/dist/commands/init.js

@@ -13,7 +13,7 @@ import { AGENT_GUIDE_FILE, agentGuide } from '../agent-guide.js';
 import { flagBool, flagString } from '../args.js';
 import { createAuthStore } from '../auth-store.js';
 import { parseAppCallback } from '../callback-url.js';
-import { detectProject, installCommand } from '../detect.js';
+import { detectProject, installCommand, outdatedSdk, SDK_MIN_VERSION } from '../detect.js';
 import { openDeveloperApi } from '../developer-api.js';
 import { CliError, EXIT } from '../output.js';
 import { ENV_FILE, ENV_KEYS, FRAMEWORKS, isFramework, mergeEnvFile, mergeGitignore, readProject, VITE_ENV_KEYS, writeProject, } from '../project.js';
@@ -176,16 +176,23 @@ export async function runInit(args, out, deps = {}) {
     });
     plan.push({ path: AGENT_GUIDE_FILE, action: existsSync(guidePath) ? 'update' : 'write' });
     plan.push({ path: '.aipay/project.json', action: existing ? 'update' : 'write' });
-    // 6. install
+    // 6. install — or upgrade: the generated code passes `authOrigin`, which the SDK accepts
+    //    from SDK_MIN_VERSION on, so an older SDK already in the project would break it.
+    const outdated = det.hasPackageJson && det.sdkInstalled ? outdatedSdk(det) : null;
+    const upgradeCmd = outdated
+        ? installCommand(det.packageManager ?? 'npm', `${SDK_PACKAGE}@latest`)
+        : null;
     let installCmd = null;
-    if (det.hasPackageJson && !det.sdkInstalled && install && det.packageManager)
-        installCmd = installCommand(det.packageManager, SDK_PACKAGE);
+    if (det.hasPackageJson && install && det.packageManager)
+        installCmd = det.sdkInstalled ? upgradeCmd : installCommand(det.packageManager, SDK_PACKAGE);
     out.blank();
     for (const p of plan)
         out.line(p.action === 'skip' ? 'info' : 'ok', `${p.action.padEnd(6)} ${p.path}${p.why ? `  (${p.why})` : ''}`);
+    if (outdated)
+        out.line(installCmd ? 'info' : 'warn', `${SDK_PACKAGE} ${outdated} is too old for the generated code (needs ${SDK_MIN_VERSION} or later)${installCmd ? '' : ` — upgrade it: ${upgradeCmd?.join(' ')}`}`);
     if (installCmd)
         out.line('info', `${dryRun ? 'would run' : 'run   '} ${installCmd.join(' ')}`);
-    else if (det.hasPackageJson && det.sdkInstalled)
+    else if (det.hasPackageJson && det.sdkInstalled && !outdated)
         out.line('info', `skip   ${SDK_PACKAGE} (already a dependency)`);
     let installExit = null;
     if (!dryRun) {
@@ -201,10 +208,10 @@ export async function runInit(args, out, deps = {}) {
             if (installExit !== 0)
                 out.line('bad', `install failed (exit ${installExit}); run it yourself: ${installCmd.join(' ')}`);
             else
-                out.line('ok', `installed ${SDK_PACKAGE}`);
+                out.line('ok', `${outdated ? 'upgraded' : 'installed'} ${SDK_PACKAGE}`);
         }
     }
-    // C2 setup session：登入狀態下回報 init（Console 的「等待工具連線」變綠）；失敗不影響結果
+    // setup session：登入狀態下回報 init（Console 的「等待工具連線」變綠）；失敗不影響結果
     let reported = false;
     if (!dryRun)
         reported = await reportSetupEvent(clientId, 'cli.init', {
@@ -227,6 +234,9 @@ export async function runInit(args, out, deps = {}) {
         detection: det,
         plan,
         install: installCmd ? { command: installCmd, exit: installExit } : null,
+        sdk_upgrade: outdated
+            ? { from: outdated, minimum: SDK_MIN_VERSION, command: upgradeCmd }
+            : null,
         docs: { fetched: !!docs.markdown, empty404: docs.empty404, status: docs.status },
         reported,
     });

package/dist/commands/login.d.ts

@@ -6,14 +6,14 @@ export interface CliConfig {
     scopes: string[];
     redirect_path: string;
     audience: string;
-    /** A2: the server allows the device grant for the CLI (older APIs omit it = false). */
+    /** The server allows the device grant for the CLI (older APIs omit it = false). */
     device_authorization: boolean;
 }
 export interface LoginDeps {
     env?: NodeJS.ProcessEnv;
     open?: (url: string) => boolean;
     onAuthorizeUrl?: (url: string) => void;
-    /** A2: called with the verification URL and the user code (tests / drivers). */
+    /** `--device`: called with the verification URL and the user code (tests / drivers). */
     onDeviceCode?: (info: {
         url: string;
         userCode: string;

package/dist/commands/login.js

@@ -1,11 +1,11 @@
 /**
  * `aipay login [--api <base>] [--device] [--no-open] [--timeout <s>] [--json]`
  *
- * Developer sign-in for the CLI itself (consultant §10.2, auth model A): the CLI is a
- * first-party public client. It asks the API for its client config, then either
- *   A1 — runs loopback PKCE against the authorization server (a browser on this machine), or
- *   A2 — `--device`: RFC 8628 device authorization (no browser here: SSH boxes, containers,
- *        CI) — prints a URL + short code, the developer approves on any device, the CLI polls.
+ * Developer sign-in for the CLI itself: the CLI is a first-party public client. It asks
+ * the API for its client config, then either
+ *   - runs loopback PKCE against the authorization server (a browser on this machine), or
+ *   - `--device`: RFC 8628 device authorization (no browser here: SSH boxes, containers,
+ *     CI) — prints a URL + short code, the developer approves on any device, the CLI polls.
  * Both use audience aipay-developer-api and the management scope, and keep the tokens in
  * the OS keychain (or a 0600 file). No app secrets exist.
  */
@@ -54,7 +54,7 @@ export async function fetchCliConfig(apiBase) {
 export function resolveApiBase(args, env, dir) {
     const v = flagString(args.flags, 'api') ?? env.AIPAY_API_BASE ?? readProjectSafe(dir)?.api_base ?? null;
     if (!v)
-        throw new CliError('usage', 'which AI-Pay? pass --api <api base> (the Console prompt lists it) or set AIPAY_API_BASE', EXIT.usage);
+        throw new CliError('usage', 'which AI Pay? pass --api <api base> (the Console prompt lists it) or set AIPAY_API_BASE', EXIT.usage);
     try {
         return new URL(v).origin;
     }
@@ -99,7 +99,7 @@ export async function runLogin(args, out, deps = {}) {
     const loop = await startLoopback({ host: '127.0.0.1', port: 0, path: cfg.redirect_path }, { timeoutMs: timeoutS * 1000 });
     const redirectUri = `http://127.0.0.1:${loop.port}${cfg.redirect_path}`;
     const { url, state, codeVerifier } = managementAuthorizeUrl(cfg, redirectUri);
-    out.line('info', `signing in to ${apiBase} as a developer — approve "AI-Pay CLI" in your browser:\n\n  ${url}\n`);
+    out.line('info', `signing in to ${apiBase} as a developer — approve "AI Pay CLI" in your browser:\n\n  ${url}\n`);
     if (cfg.device_authorization)
         out.line('info', 'no browser on this machine? run `aipay login --device` instead');
     if (out.json)
@@ -118,7 +118,7 @@ export async function runLogin(args, out, deps = {}) {
         const code = u.searchParams.get('code');
         if (!code)
             throw new CliError('remote', 'callback without a code', EXIT.remote);
-        const tokens = await exchangeCode({ hydraPublicUrl: cfg.auth_origin, clientId: cfg.client_id, redirectUri }, { code, codeVerifier, fetchImpl });
+        const tokens = await exchangeCode({ authOrigin: cfg.auth_origin, clientId: cfg.client_id, redirectUri }, { code, codeVerifier, fetchImpl });
         return finishLogin({
             accessToken: tokens.accessToken,
             refreshToken: tokens.refreshToken,
@@ -130,7 +130,7 @@ export async function runLogin(args, out, deps = {}) {
         await loop.close();
     }
 }
-/** A2 (RFC 8628): print URL + code, poll until approved on another device. */
+/** `--device` (RFC 8628): print URL + code, poll until approved on another device. */
 async function deviceLogin(cfg, apiBase, timeoutS, fetchImpl, env, out, deps) {
     if (!cfg.device_authorization)
         throw new CliError('device_unsupported', `${apiBase} does not offer device sign-in yet — run \`aipay login\` on a machine with a browser`, EXIT.remote);
@@ -154,7 +154,7 @@ async function deviceLogin(cfg, apiBase, timeoutS, fetchImpl, env, out, deps) {
 }
 /** Shared tail of both flows: identity → keychain/file → summary. */
 async function finishLogin(tokens, cfg, apiBase, fetchImpl, env, out) {
-    const user = await getUserInfo({ hydraPublicUrl: cfg.auth_origin }, tokens.accessToken, {
+    const user = await getUserInfo({ authOrigin: cfg.auth_origin }, tokens.accessToken, {
         fetchImpl,
     });
     const store = createAuthStore(env);

package/dist/commands/region.d.ts

@@ -1,14 +1,14 @@
 /**
  * `aipay region` (show) and
  * `aipay region set --country <CC> [--state US-XX --line1 <street> [--line2 <apt>] --city <city> --zip <ZIP>] [--accept-terms]`.
- * US accounts (0121) must carry a full postal address: the backend locates the sales-tax jurisdiction
+ * US accounts must carry a full postal address: the backend locates the sales-tax jurisdiction
  * (state / county / city / special district) from it; `aipay region` shows the lookup result.
  *
  * The developer API is closed (403 region_required) until the account has a declared region and an
  * accepted current Terms of Service version. Both endpoints used here are exempt from that gate:
  *   GET  /v1/developer/me/region  → current state + the version to accept
  *   POST /v1/developer/me/region  → declare (same body as the dashboard)
- * Non-interactive on purpose (agents drive this): everything is a flag; missing input is a usage error.
+ * Non-interactive on purpose (a coding agent may drive this): everything is a flag; missing input is a usage error.
  */
 import { type ParsedArgs } from '../args.js';
 import { type Reporter } from '../output.js';
@@ -38,7 +38,7 @@ export interface RegionState {
     declared: boolean;
     terms_current: boolean;
     complete: boolean;
-    /** US only (0121): the full postal address on file */
+    /** US only: the full postal address on file */
     address?: RegionAddress | null;
     /** US only: background jurisdiction lookup (state / county / city / special district) */
     tax_location?: TaxLocationState | null;

package/dist/commands/region.js

@@ -1,14 +1,14 @@
 /**
  * `aipay region` (show) and
  * `aipay region set --country <CC> [--state US-XX --line1 <street> [--line2 <apt>] --city <city> --zip <ZIP>] [--accept-terms]`.
- * US accounts (0121) must carry a full postal address: the backend locates the sales-tax jurisdiction
+ * US accounts must carry a full postal address: the backend locates the sales-tax jurisdiction
  * (state / county / city / special district) from it; `aipay region` shows the lookup result.
  *
  * The developer API is closed (403 region_required) until the account has a declared region and an
  * accepted current Terms of Service version. Both endpoints used here are exempt from that gate:
  *   GET  /v1/developer/me/region  → current state + the version to accept
  *   POST /v1/developer/me/region  → declare (same body as the dashboard)
- * Non-interactive on purpose (agents drive this): everything is a flag; missing input is a usage error.
+ * Non-interactive on purpose (a coding agent may drive this): everything is a flag; missing input is a usage error.
  */
 import { flagBool, flagString } from '../args.js';
 import { createAuthStore } from '../auth-store.js';
@@ -116,7 +116,7 @@ export async function runRegion(args, out, env = process.env) {
         }
         if (country === 'US' && !state)
             throw new CliError('usage', 'the United States needs --state (e.g. --state US-CA)', EXIT.usage);
-        // 0121: the US needs a full address (street, city, ZIP) — the backend locates the sales-tax jurisdiction from it
+        // The US needs a full address (street, city, ZIP) — the backend locates the sales-tax jurisdiction from it
         if (country === 'US')
             address = parseAddressFlags(args.flags);
         else if (flagString(args.flags, 'line1') ||
@@ -134,7 +134,7 @@ export async function runRegion(args, out, env = process.env) {
         return EXIT.ok;
     }
     if (!current.region.terms_current && !acceptTerms)
-        throw new CliError('terms_required', `the AI-Pay Terms of Service (version ${current.terms_version_required}, ${termsUrl(api.auth.api_base, current)}) need your explicit acceptance — read them, then rerun with --accept-terms`, EXIT.problem);
+        throw new CliError('terms_required', `the AI Pay Terms of Service (version ${current.terms_version_required}, ${termsUrl(api.auth.api_base, current)}) need your explicit acceptance — read them, then rerun with --accept-terms`, EXIT.problem);
     const body = {
         country,
         ...(state ? { subdivision: state } : {}),

package/dist/commands/test.d.ts

@@ -7,6 +7,17 @@ export interface TestDeps {
     onAuthorizeUrl?: (url: string) => void;
 }
 export declare function runTest(args: ParsedArgs, out: Reporter, deps?: TestDeps): Promise<number>;
-/** Cheapest sensible default: prefer a small/cheap model id if present, else the first. */
-export declare function pickModel(ids: string[]): string | null;
+/** What pickModel needs from a `GET /v1/models` entry (plain ids still accepted). */
+export type PickableModel = string | {
+    id: string;
+    aipay?: {
+        availability?: {
+            status: string;
+        };
+    };
+};
+/** Cheapest sensible default: skip models the catalog marks unavailable right now (v0.8.0;
+ * if every model is unavailable, fall back to all of them so the server can say why), then
+ * prefer a small/cheap model id if present, else the first. */
+export declare function pickModel(models: PickableModel[]): string | null;
 export declare function formatUusd(uusd: string): string;

package/dist/commands/test.js

@@ -1,12 +1,12 @@
 /**
  * `aipay test [--model <id>] [--no-open] [--timeout <s>] [--json]`
  *
- * The one check only a CLI can do end to end: a real sign-in through the AI-Pay
+ * The one check only a CLI can do end to end: a real sign-in through the AI Pay
  * authorization server on the registered loopback callback, then one chat completion
  * on the user's behalf. The receipt in the response is the proof (and the Console's
  * verify step turns green from the server-side facts). Tokens live in memory only.
  */
-import { AIPayClient, AuthorizationError, ConnectError, createConnectUrl, getUserInfo, handleCallback, InsufficientBalanceError, } from '@coswic/aipay-sdk';
+import { AIPayApiError, AIPayClient, AuthorizationError, ConnectError, createConnectUrl, getUserInfo, handleCallback, InsufficientBalanceError, } from '@coswic/aipay-sdk';
 import { flagBool, flagString } from '../args.js';
 import { openBrowser } from '../browser.js';
 import { parseCallback, portIsVariable, redirectUriFor, startLoopback } from '../loopback.js';
@@ -42,7 +42,7 @@ export async function runTest(args, out, deps = {}) {
         throw e;
     });
     const redirectUri = redirectUriFor(target, loop.port);
-    const cfg = { hydraPublicUrl: project.auth_origin, clientId: project.app.client_id, redirectUri };
+    const cfg = { authOrigin: project.auth_origin, clientId: project.app.client_id, redirectUri };
     const { url, state, codeVerifier } = await createConnectUrl(cfg);
     const note = redirectUri === callback
         ? ''
@@ -89,7 +89,7 @@ export async function runTest(args, out, deps = {}) {
             const models = await client.models.list().catch((e) => {
                 throw new CliError('models', `cannot list models: ${e.message}`, EXIT.remote);
             });
-            model = pickModel(models.map((m) => m.id));
+            model = pickModel(models);
             if (!model)
                 throw new CliError('models', 'no sellable model right now — pass --model <id>', EXIT.remote);
         }
@@ -113,7 +113,7 @@ export async function runTest(args, out, deps = {}) {
             };
             result.ok = true;
             out.line('ok', `receipt: request_id ${r.request_id}, charged ${formatUusd(charged)} ${r.currency}`);
-            // C2 setup session：登入狀態下回報 test 通過（伺服器本來就看得到回執；這條是給 Console 的時間戳）
+            // setup session：登入狀態下回報 test 通過（伺服器本來就看得到回執；這條是給 Console 的時間戳）
             await reportSetupEvent(project.app.client_id, 'cli.test', { request_id: r.request_id, model: res.model, ok: true }, out, env);
             out.line('ok', "done — the Console's verify step reads this from the server side");
         }
@@ -127,6 +127,10 @@ export async function runTest(args, out, deps = {}) {
             }
             if (e instanceof AuthorizationError)
                 throw new CliError('unauthorized', `the API rejected the token: ${e.message}`, EXIT.remote);
+            // v0.8.0: during the invitation-only beta a 401 is also what an uninvited (or
+            // invitation-revoked / terms-not-accepted) user gets — refreshing does not help.
+            if (e instanceof AIPayApiError && e.status === 401)
+                throw new CliError('unauthorized', `the API rejected the user's token (401 ${e.code}). During the invitation-only beta this also happens when the signed-in user holds no current invitation or has not accepted the latest Terms — refreshing does not help; see ${project.api_base}/about`, EXIT.remote);
             throw e;
         }
         out.result(result);
@@ -136,7 +140,7 @@ export async function runTest(args, out, deps = {}) {
         if (e instanceof CliError) {
             result.error = { code: e.code, message: e.message };
             out.line('bad', e.message);
-            // 顧問 §13.2：失敗也回報（error_code 進 Console 的驗證步與 setup 事件；best effort、無 token）
+            // 失敗也回報（error_code 進 Console 的驗證步與 setup 事件；best effort、無 token）
             await reportSetupEvent(project.app.client_id, 'cli.test', { ok: false, error_code: e.code }, out, env);
             out.result(result);
             return e.exitCode;
@@ -146,6 +150,8 @@ export async function runTest(args, out, deps = {}) {
         out.line('bad', msg);
         if (/\b404\b/.test(msg))
             out.line('info', 'Check the endpoint URL and network connectivity before retrying.');
+        if (/no callback received/.test(msg))
+            out.line('info', `if the AI Pay sign-in page never completed, the user may not be invited: during the invitation-only beta only invited users can sign in (see ${project.api_base}/about)`);
         out.result(result);
         return EXIT.remote;
     }
@@ -153,8 +159,15 @@ export async function runTest(args, out, deps = {}) {
         await loop.close();
     }
 }
-/** Cheapest sensible default: prefer a small/cheap model id if present, else the first. */
-export function pickModel(ids) {
+/** Cheapest sensible default: skip models the catalog marks unavailable right now (v0.8.0;
+ * if every model is unavailable, fall back to all of them so the server can say why), then
+ * prefer a small/cheap model id if present, else the first. */
+export function pickModel(models) {
+    const entries = models.map((m) => typeof m === 'string'
+        ? { id: m, available: true }
+        : { id: m.id, available: m.aipay?.availability?.status !== 'unavailable' });
+    const pool = entries.filter((e) => e.available);
+    const ids = (pool.length ? pool : entries).map((e) => e.id);
     if (!ids.length)
         return null;
     const cheap = ids.find((id) => /mini|flash|haiku|nano|small|8b|7b/i.test(id));

package/dist/commands/unlink.js

@@ -61,7 +61,7 @@ export function stripEnvKeys(content, keys) {
     const set = new Set(keys);
     const lines = content.split(/\r?\n/);
     const kept = lines.filter((line) => {
-        if (line.startsWith('# AI-Pay (written by `aipay init`'))
+        if (line.startsWith('# AI Pay (written by `aipay init`'))
             return false;
         const m = /^\s*(?:export\s+)?([A-Z0-9_]+)\s*=/.exec(line);
         return !(m && set.has(m[1]));

package/dist/detect.d.ts

@@ -1,5 +1,8 @@
 import type { Framework } from './project.js';
 export type PackageManager = 'pnpm' | 'npm' | 'yarn' | 'bun';
+/** Oldest @coswic/aipay-sdk the scaffolded code works with: it passes `authOrigin`, which
+ * the SDK accepts from 0.5.1 on. */
+export declare const SDK_MIN_VERSION = "0.5.1";
 export interface Detection {
     packageManager: PackageManager | null;
     framework: Framework | null;
@@ -7,6 +10,10 @@ export interface Detection {
     typescript: boolean;
     /** Whether @coswic/aipay-sdk is already a dependency. */
     sdkInstalled: boolean;
+    /** Its version spec in package.json (null when it is not a dependency). */
+    sdkSpec: string | null;
+    /** Version in node_modules/@coswic/aipay-sdk/package.json (null when absent or unreadable). */
+    sdkVersion: string | null;
     /** `src/` exists → scaffold under it, else project root. */
     srcDir: string;
 }
@@ -23,5 +30,12 @@ export declare function detectPackageManager(pkg: PackageJsonLike | null, lockfi
 }): PackageManager | null;
 export declare function detectFramework(pkg: PackageJsonLike | null): Framework | null;
 export declare function detectProject(dir: string): Detection;
+/**
+ * The SDK version this project would run when it is older than SDK_MIN_VERSION: the
+ * installed one when known, else the lowest version the package.json spec allows
+ * (`^0.5.0` → 0.5.0). Null when it is new enough or cannot be told (not a dependency, or a
+ * spec such as `latest`, `*`, a range or a `file:` / `workspace:` link).
+ */
+export declare function outdatedSdk(det: Pick<Detection, 'sdkSpec' | 'sdkVersion'>): string | null;
 /** The install command for the detected manager (printed in --dry-run, run otherwise). */
 export declare function installCommand(pm: PackageManager, pkgName: string): string[];

package/dist/detect.js

@@ -5,6 +5,9 @@
  */
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
+/** Oldest @coswic/aipay-sdk the scaffolded code works with: it passes `authOrigin`, which
+ * the SDK accepts from 0.5.1 on. */
+export const SDK_MIN_VERSION = '0.5.1';
 export function detectPackageManager(pkg, lockfiles) {
     const pm = pkg?.packageManager;
     if (typeof pm === 'string') {
@@ -59,15 +62,64 @@ export function detectProject(dir) {
         npm: existsSync(join(dir, 'package-lock.json')),
     };
     const deps = { ...(pkg?.dependencies ?? {}), ...(pkg?.devDependencies ?? {}) };
+    const sdkSpec = deps['@coswic/aipay-sdk'];
     return {
         packageManager: detectPackageManager(pkg, lockfiles),
         framework: detectFramework(pkg),
         hasPackageJson,
         typescript: 'typescript' in deps || existsSync(join(dir, 'tsconfig.json')),
         sdkInstalled: '@coswic/aipay-sdk' in deps,
+        sdkSpec: typeof sdkSpec === 'string' ? sdkSpec : null,
+        sdkVersion: installedSdkVersion(dir),
         srcDir: existsSync(join(dir, 'src')) ? 'src' : '.',
     };
 }
+function installedSdkVersion(dir) {
+    try {
+        const p = join(dir, 'node_modules', '@coswic', 'aipay-sdk', 'package.json');
+        const v = JSON.parse(readFileSync(p, 'utf8')).version;
+        return typeof v === 'string' ? v : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The SDK version this project would run when it is older than SDK_MIN_VERSION: the
+ * installed one when known, else the lowest version the package.json spec allows
+ * (`^0.5.0` → 0.5.0). Null when it is new enough or cannot be told (not a dependency, or a
+ * spec such as `latest`, `*`, a range or a `file:` / `workspace:` link).
+ */
+export function outdatedSdk(det) {
+    const version = det.sdkVersion ?? lowestAllowed(det.sdkSpec);
+    return version !== null && isOlder(version, SDK_MIN_VERSION) ? version : null;
+}
+/** Exact, `^`, `~`, `=` or `>=` spec → the version it starts at; anything else → null. */
+function lowestAllowed(spec) {
+    const m = /^\s*(?:[\^~=]|>=)?\s*v?(\d+)\.(\d+)(?:\.(\d+|x|\*))?(-[0-9A-Za-z.-]+)?\s*$/.exec(spec ?? '');
+    if (!m)
+        return null;
+    const patch = m[3] === undefined || m[3] === 'x' || m[3] === '*' ? '0' : m[3];
+    return `${m[1]}.${m[2]}.${patch}${m[4] ?? ''}`;
+}
+/** Semver precedence for `major.minor.patch[-prerelease]` (a prerelease sorts before its
+ * release); false when either side cannot be parsed. */
+function isOlder(version, than) {
+    const parse = (v) => {
+        const m = /^v?(\d+)\.(\d+)\.(\d+)(-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/.exec(v.trim());
+        return m ? { core: [Number(m[1]), Number(m[2]), Number(m[3])], pre: m[4] !== undefined } : null;
+    };
+    const a = parse(version);
+    const b = parse(than);
+    if (!a || !b)
+        return false;
+    for (let i = 0; i < 3; i++) {
+        const d = a.core[i] - b.core[i];
+        if (d !== 0)
+            return d < 0;
+    }
+    return a.pre && !b.pre;
+}
 /** The install command for the detected manager (printed in --dry-run, run otherwise). */
 export function installCommand(pm, pkgName) {
     switch (pm) {

package/dist/developer-api.js

@@ -35,7 +35,7 @@ export async function openDeveloperApi(store) {
             if (isEmpty404(res.status, text))
                 throw new CliError('empty_404', EMPTY_404_HINT, EXIT.remote);
             if (res.status === 401 && opts.retryUnauthorized !== false)
-                throw new CliError('unauthorized', 'the API rejected the developer token — run `aipay login` again', EXIT.remote);
+                throw new CliError('unauthorized', 'the API rejected the developer token — run `aipay login` again (if you just did, the developer account may not be invited yet: during the invitation-only beta only invited users can use the developer API — see the product overview at /about)', EXIT.remote);
             let body = null;
             try {
                 body = text ? JSON.parse(text) : null;
@@ -43,10 +43,10 @@ export async function openDeveloperApi(store) {
             catch {
                 body = { raw: text.slice(0, 500) };
             }
-            // 0074 hard gate: the developer API is closed until region + current Terms are on file.
+            // Hard gate: the developer API is closed until region + current Terms are on file.
             // `aipay region …` talks to the exempt endpoints, so this never traps the fix itself.
             if (res.status === 403 && errorCodeOf(body) === 'region_required')
-                throw new CliError('region_required', 'AI-Pay needs your country/region and your acceptance of the current Terms of Service before the developer API can be used — run `aipay region set --country <ISO 3166-1> [--state US-XX] --accept-terms` (`aipay region` shows the version and terms URL)', EXIT.problem);
+                throw new CliError('region_required', 'AI Pay needs your country/region and your acceptance of the current Terms of Service before the developer API can be used — run `aipay region set --country <ISO 3166-1> [--state US-XX] --accept-terms` (`aipay region` shows the version and terms URL)', EXIT.problem);
             return { status: res.status, body: body };
         },
     };
@@ -56,7 +56,7 @@ async function refresh(store, auth, fetchImpl) {
     if (!auth.refresh_token)
         throw new CliError('expired', 'the developer token expired — run `aipay login` again', EXIT.problem);
     const t = await refreshAccessToken({
-        hydraPublicUrl: auth.auth_origin,
+        authOrigin: auth.auth_origin,
         clientId: auth.client_id,
     }, auth.refresh_token, { fetchImpl }).catch(() => {
         throw new CliError('expired', 'could not renew the developer token — run `aipay login` again', EXIT.problem);

package/dist/device.js

@@ -1,5 +1,5 @@
 /**
- * RFC 8628 device authorization for `aipay login --device` (consultant §10.2, auth model A2):
+ * RFC 8628 device authorization for `aipay login --device`:
  * for machines without a browser (SSH boxes, containers, CI). The CLI asks the
  * authorization server for a device code + a short user code, prints the verification
  * URL and the code, then polls the token endpoint until the developer approves it in
@@ -29,7 +29,7 @@ export async function requestDeviceCode(cfg, fetchImpl = fetch) {
     if (!res.ok) {
         const err = parseOAuthError(text);
         if (err?.error === 'invalid_grant' || err?.error === 'unauthorized_client')
-            throw new CliError('device_unsupported', 'this AI-Pay does not allow device sign-in for the CLI yet — use `aipay login` on a machine with a browser', EXIT.remote);
+            throw new CliError('device_unsupported', 'this AI Pay does not allow device sign-in for the CLI yet — use `aipay login` on a machine with a browser', EXIT.remote);
         throw new CliError('remote', `device authorization failed: HTTP ${res.status} ${err?.error ?? ''} ${err?.error_description ?? ''}`.trim(), EXIT.remote);
     }
     const j = JSON.parse(text);

package/dist/loopback.d.ts

@@ -11,9 +11,10 @@ export interface LoopbackTarget {
     path: string;
 }
 /**
- * Hydra compares loopback redirect URIs per RFC 8252 §7.3: for 127.0.0.1 / [::1] the port
- * is ignored, so the CLI may receive the callback on any free port while the app keeps
- * its registered URI. `localhost` is NOT treated as loopback by the server — exact port.
+ * The authorization server compares loopback redirect URIs per RFC 8252 §7.3: for
+ * 127.0.0.1 / [::1] the port is ignored, so the CLI may receive the callback on any free
+ * port while the app keeps its registered URI. `localhost` is NOT treated as loopback by
+ * the server — exact port.
  */
 export declare function portIsVariable(target: LoopbackTarget): boolean;
 /** The redirect_uri to send for a receiver bound to `port` (same host + path). */

package/dist/loopback.js

@@ -7,9 +7,10 @@
 import { createServer } from 'node:http';
 import { hasUnsafeCallbackText } from './callback-url.js';
 /**
- * Hydra compares loopback redirect URIs per RFC 8252 §7.3: for 127.0.0.1 / [::1] the port
- * is ignored, so the CLI may receive the callback on any free port while the app keeps
- * its registered URI. `localhost` is NOT treated as loopback by the server — exact port.
+ * The authorization server compares loopback redirect URIs per RFC 8252 §7.3: for
+ * 127.0.0.1 / [::1] the port is ignored, so the CLI may receive the callback on any free
+ * port while the app keeps its registered URI. `localhost` is NOT treated as loopback by
+ * the server — exact port.
  */
 export function portIsVariable(target) {
     return target.host === '127.0.0.1' || target.host === '::1';
@@ -86,7 +87,7 @@ export function startLoopback(target, opts = {}) {
     });
 }
 function defaultPage(ok) {
-    const title = ok ? 'AI-Pay: signed in' : 'AI-Pay: authorization failed';
+    const title = ok ? 'AI Pay: signed in' : 'AI Pay: authorization failed';
     const body = ok
         ? 'You can close this tab and return to the terminal.'
         : 'The terminal shows the error. You can close this tab.';

package/dist/main.d.ts

@@ -1,4 +1,4 @@
-export declare const HELP = "aipay \u2014 AI-Pay CLI\n\nUsage\n  aipay login [--api <base>] [--device] [--json]      developer sign-in for the CLI itself\n  aipay whoami [--json] \u00B7 aipay logout [--json]\n  aipay region [--json]                                your country/region + Terms of Service status\n  aipay region set --country <CC> [--state US-XX --line1 <street> [--line2 <apt>] --city <city> --zip <ZIP>]\n             [--accept-terms] [--json]                      US accounts need the full address (sales-tax jurisdiction)\n  aipay apps list [--json]\n  aipay apps create --name <name> [--callback <url>] [--json]\n  aipay apps callbacks list [--app <client_id>] [--dir <path>] [--json]\n  aipay apps callbacks add|remove --callback <url> [--app <client_id>] [--dir <path>] [--json]\n  aipay init --app <client_id> [--auth <origin>] [--api <base>] [--callback <url>] [--name <app name>]\n             [--framework next|express|fastify|hono|vite|node]  override detection\n             [--dir <path>] [--dry-run] [--no-install] [--json]\n  aipay init --create <app name> [--api <base>] ...     create the app (needs login) and link it\n  aipay test [--model <id>] [--callback <registered-loopback-url>] [--port <n>] [--no-open] [--timeout <seconds>] [--dir <path>] [--json]\n  aipay doctor [--offline] [--dir <path>] [--json]\n  aipay status [--dir <path>] [--json]\n  aipay unlink [--dry-run] [--dir <path>] [--json]\n\nlogin   sign in as a developer (loopback PKCE, audience aipay-developer-api); tokens go to the\n        OS keychain or a 0600 file \u2014 never into the project\nregion  the developer API stays closed (403 region_required) until your account has a country/region\n        (US: a state) and has accepted the current Terms of Service \u2014 \"region set\" does both; the\n        version to accept and the terms URL are printed by \"aipay region\"\napps    list/create your apps; callbacks list/add/remove manages registered redirects\n        callback changes preserve other URLs and reject concurrent edits\ninit    link this project to an app: .aipay/project.json, .env.local, .gitignore,\n        a callback route for your framework, aipay-agent.md, and the SDK install\n        (--auth/--api are optional once you are signed in; --create makes the app first)\ntest    real sign-in via a loopback callback (any free port on 127.0.0.1) + one chat completion \u2192 receipt\ndoctor  check the link, files, SDK, and that AI-Pay is reachable\nstatus  what this directory is linked to\nunlink  forget the link (keeps your code)\n\nExit codes: 0 ok \u00B7 1 problem you can fix \u00B7 2 usage \u00B7 3 network/auth\n";
+export declare const HELP = "aipay \u2014 AI Pay CLI\n\nUsage\n  aipay login [--api <base>] [--device] [--json]      developer sign-in for the CLI itself\n  aipay whoami [--json] \u00B7 aipay logout [--json]\n  aipay region [--json]                                your country/region + Terms of Service status\n  aipay region set --country <CC> [--state US-XX --line1 <street> [--line2 <apt>] --city <city> --zip <ZIP>]\n             [--accept-terms] [--json]                      US accounts need the full address (sales-tax jurisdiction)\n  aipay apps list [--json]\n  aipay apps create --name <name> [--callback <url>] [--json]\n  aipay apps callbacks list [--app <client_id>] [--dir <path>] [--json]\n  aipay apps callbacks add|remove --callback <url> [--app <client_id>] [--dir <path>] [--json]\n  aipay init --app <client_id> [--auth <origin>] [--api <base>] [--callback <url>] [--name <app name>]\n             [--framework next|express|fastify|hono|vite|node]  override detection\n             [--dir <path>] [--dry-run] [--no-install] [--json]\n  aipay init --create <app name> [--api <base>] ...     create the app (needs login) and link it\n  aipay test [--model <id>] [--callback <registered-loopback-url>] [--port <n>] [--no-open] [--timeout <seconds>] [--dir <path>] [--json]\n  aipay doctor [--offline] [--dir <path>] [--json]\n  aipay status [--dir <path>] [--json]\n  aipay unlink [--dry-run] [--dir <path>] [--json]\n\nlogin   sign in as a developer (loopback PKCE, audience aipay-developer-api); tokens go to the\n        OS keychain or a 0600 file \u2014 never into the project\nregion  the developer API stays closed (403 region_required) until your account has a country/region\n        (US: a state) and has accepted the current Terms of Service \u2014 \"region set\" does both; the\n        version to accept and the terms URL are printed by \"aipay region\"\napps    list/create your apps; callbacks list/add/remove manages registered redirects\n        callback changes preserve other URLs and reject concurrent edits\ninit    link this project to an app: .aipay/project.json, .env.local, .gitignore,\n        a callback route for your framework, aipay-agent.md, and the SDK install\n        (--auth/--api are optional once you are signed in; --create makes the app first)\ntest    real sign-in via a loopback callback (any free port on 127.0.0.1) + one chat completion \u2192 receipt\ndoctor  check the link, files, SDK, and that AI Pay is reachable\nstatus  what this directory is linked to\nunlink  forget the link (keeps your code)\n\nExit codes: 0 ok \u00B7 1 problem you can fix \u00B7 2 usage \u00B7 3 network/auth\n";
 export declare function main(argv: string[], io?: {
     stdout?: (s: string) => void;
     stderr?: (s: string) => void;

package/dist/main.js

@@ -10,7 +10,7 @@ import { runTest } from './commands/test.js';
 import { runUnlink } from './commands/unlink.js';
 import { CliError, createReporter, EXIT } from './output.js';
 import { cliVersion } from './version.js';
-export const HELP = `aipay — AI-Pay CLI
+export const HELP = `aipay — AI Pay CLI
 
 Usage
   aipay login [--api <base>] [--device] [--json]      developer sign-in for the CLI itself
@@ -42,7 +42,7 @@ init    link this project to an app: .aipay/project.json, .env.local, .gitignore
         a callback route for your framework, aipay-agent.md, and the SDK install
         (--auth/--api are optional once you are signed in; --create makes the app first)
 test    real sign-in via a loopback callback (any free port on 127.0.0.1) + one chat completion → receipt
-doctor  check the link, files, SDK, and that AI-Pay is reachable
+doctor  check the link, files, SDK, and that AI Pay is reachable
 status  what this directory is linked to
 unlink  forget the link (keeps your code)
 

package/dist/network.d.ts

@@ -1,3 +1,3 @@
 /** Describe the observed response without inferring its network or server-side cause. */
 export declare function isEmpty404(status: number, bodyText: string): boolean;
-export declare const EMPTY_404_HINT = "AI-Pay answered 404 with an empty body. Check the endpoint URL and network connectivity, then retry. An empty 404 alone does not identify the cause.";
+export declare const EMPTY_404_HINT = "AI Pay answered 404 with an empty body. Check the endpoint URL and network connectivity, then retry. An empty 404 alone does not identify the cause.";

package/dist/network.js

@@ -2,4 +2,4 @@
 export function isEmpty404(status, bodyText) {
     return status === 404 && bodyText.trim() === '';
 }
-export const EMPTY_404_HINT = 'AI-Pay answered 404 with an empty body. Check the endpoint URL and network connectivity, then retry. An empty 404 alone does not identify the cause.';
+export const EMPTY_404_HINT = 'AI Pay answered 404 with an empty body. Check the endpoint URL and network connectivity, then retry. An empty 404 alone does not identify the cause.';

package/dist/output.d.ts

@@ -1,7 +1,8 @@
 /**
  * Output channel: human-readable lines on stderr-ish stdout, or one JSON document when
- * `--json` is set (agents parse it; humans read the other one). Both go to stdout so
- * `aipay status --json | jq` works; diagnostics that must never pollute JSON go to stderr.
+ * `--json` is set (for scripts and coding tools; humans read the other one). Both go to
+ * stdout so `aipay status --json | jq` works; diagnostics that must never pollute JSON go
+ * to stderr.
  */
 export type Level = 'ok' | 'warn' | 'bad' | 'info';
 export interface Reporter {
@@ -19,14 +20,14 @@ export declare function createReporter(opts: {
     stdout?: (s: string) => void;
     stderr?: (s: string) => void;
 }): Reporter;
-/** Exit codes are part of the contract (agents branch on them). */
+/** Exit codes are part of the contract (scripts and coding tools branch on them). */
 export declare const EXIT: {
     readonly ok: 0;
     /** Something in the project/config is wrong and the user can fix it. */
     readonly problem: 1;
     /** Bad invocation (unknown command/flag, missing required flag). */
     readonly usage: 2;
-    /** Network/auth failure talking to AI-Pay. */
+    /** Network/auth failure talking to AI Pay. */
     readonly remote: 3;
 };
 export declare class CliError extends Error {

package/dist/output.js

@@ -30,14 +30,14 @@ export function createReporter(opts) {
         },
     };
 }
-/** Exit codes are part of the contract (agents branch on them). */
+/** Exit codes are part of the contract (scripts and coding tools branch on them). */
 export const EXIT = {
     ok: 0,
     /** Something in the project/config is wrong and the user can fix it. */
     problem: 1,
     /** Bad invocation (unknown command/flag, missing required flag). */
     usage: 2,
-    /** Network/auth failure talking to AI-Pay. */
+    /** Network/auth failure talking to AI Pay. */
     remote: 3,
 };
 export class CliError extends Error {

package/dist/project.d.ts

@@ -5,7 +5,7 @@ export interface ProjectConfig {
         client_id: string;
         name: string | null;
     };
-    /** Authorization server origin (Hydra public), e.g. https://auth.ai-pay.example */
+    /** Authorization server origin, e.g. https://auth.ai-pay.example */
     auth_origin: string;
     /** API base for the SDK client, e.g. https://api.ai-pay.example */
     api_base: string;

package/dist/project.js

@@ -1,5 +1,5 @@
 /**
- * Local artifacts (consultant report §6.5):
+ * Local artifacts:
  *   .aipay/project.json  — committable: which app this project is linked to (no secrets)
  *   .env.local           — NOT committed: only public values (client_id, URLs)
  *   .gitignore           — gets `.env.local` and `.aipay/local/` appended once
@@ -33,7 +33,7 @@ export function readProject(dir) {
     const raw = readFileSync(p, 'utf8');
     const parsed = JSON.parse(raw);
     if (!isProjectConfig(parsed))
-        throw new Error(`${p} is not a valid AI-Pay project file`);
+        throw new Error(`${p} is not a valid AI Pay project file`);
     return parsed;
 }
 export function writeProject(dir, cfg) {
@@ -98,7 +98,7 @@ export function mergeEnvFile(existing, values) {
     if (missing.length) {
         if (out.length)
             out.push('');
-        out.push('# AI-Pay (written by `aipay init`; public values, safe to keep local)');
+        out.push('# AI Pay (written by `aipay init`; public values, safe to keep local)');
         for (const k of missing) {
             out.push(`${k}=${values[k]}`);
             changed.push(k);
@@ -121,6 +121,6 @@ export function mergeGitignore(existing, entries) {
     if (!added.length)
         return { content: existing ?? '', added };
     const base = existing ? (existing.endsWith('\n') ? existing : `${existing}\n`) : '';
-    const block = `${base}${base ? '\n' : ''}# AI-Pay local files (never commit)\n${added.join('\n')}\n`;
+    const block = `${base}${base ? '\n' : ''}# AI Pay local files (never commit)\n${added.join('\n')}\n`;
     return { content: block, added };
 }

package/dist/remote.d.ts

@@ -1,5 +1,5 @@
 /**
- * Everything that talks to AI-Pay over the network, in one place so the commands stay
+ * Everything that talks to AI Pay over the network, in one place so the commands stay
  * readable and tests can stub it.
  */
 import { EMPTY_404_HINT } from './network.js';

package/dist/remote.js

@@ -1,5 +1,5 @@
 /**
- * Everything that talks to AI-Pay over the network, in one place so the commands stay
+ * Everything that talks to AI Pay over the network, in one place so the commands stay
  * readable and tests can stub it.
  */
 import { EMPTY_404_HINT, isEmpty404 } from './network.js';

package/dist/setup-events.js

@@ -1,5 +1,5 @@
 /**
- * Setup-session events (consultant §6.3): after `init` / `test` the CLI tells the Console
+ * Setup-session events: after `init` / `test` the CLI tells the Console
  * what happened so the "waiting for the tool" line turns into "the CLI finished init".
  * Best effort and strictly opt-in by state: only when the developer is signed in with the
  * CLI (`aipay login`); never blocks the command, never sends tokens or file contents.

package/dist/templates.d.ts

@@ -1,13 +1,3 @@
-/**
- * Scaffold templates: one `aipay` helper module (sign-in flow + first completion) and a
- * thin wiring file per framework. Authored twice (TypeScript / JavaScript) so nothing is
- * generated by stripping types. The callback path is the one registered in the Console
- * for the app (default /auth/aipay/callback); the start path sits next to it.
- *
- * Sessions are the developer's business — the template keeps pending flows and signed-in
- * users in memory with a loud comment, which is correct for a dev server and obviously
- * wrong for production.
- */
 import type { Framework } from './project.js';
 export interface TemplateFile {
     /** Path relative to the project root. */

package/dist/templates.js

@@ -1,3 +1,14 @@
+/**
+ * Scaffold templates: one `aipay` helper module (sign-in flow + first completion) and a
+ * thin wiring file per framework. Authored twice (TypeScript / JavaScript) so nothing is
+ * generated by stripping types. The callback path is the one registered in the Console
+ * for the app (default /auth/aipay/callback); the start path sits next to it.
+ *
+ * Sessions are the developer's business — the template keeps pending flows and signed-in
+ * users in memory with a loud comment, which is correct for a dev server and obviously
+ * wrong for production.
+ */
+import { SDK_MIN_VERSION } from './detect.js';
 export function startPathFor(callbackPath) {
     return callbackPath.replace(/\/[^/]*$/, '/start');
 }
@@ -72,7 +83,7 @@ import {
 } from '@coswic/aipay-sdk'
 
 const cfg = {
-  hydraPublicUrl: process.env.AIPAY_AUTH_ORIGIN${t(' as string', '')},
+  authOrigin: process.env.AIPAY_AUTH_ORIGIN${t(' as string', '')}, // needs @coswic/aipay-sdk ${SDK_MIN_VERSION}+
   clientId: process.env.AIPAY_CLIENT_ID${t(' as string', '')},
   redirectUri: process.env.AIPAY_CALLBACK_URL${t(' as string', '')},
 }
@@ -82,7 +93,7 @@ const apiBase = process.env.AIPAY_API_BASE${t(' as string', '')}
 const pendingFlows = new Map${t('<string, { codeVerifier: string; expires: number }>', '')}()
 const sessions = new Map${t('<string, TokenSet>', '')}()
 
-/** Step 1 — build the AI-Pay sign-in URL; remember the PKCE verifier under the state. */
+/** Step 1 — build the AI Pay sign-in URL; remember the PKCE verifier under the state. */
 export async function beginSignIn()${t(': Promise<string>', '')} {
   const { url, state, codeVerifier } = await createConnectUrl(cfg)
   pendingFlows.set(state, { codeVerifier, expires: Date.now() + 10 * 60_000 })
@@ -239,7 +250,7 @@ export async function handleAIPay(req${ts ? ': IncomingMessage' : ''}, res${ts ?
 function browserModule(input) {
     const ts = input.typescript;
     const t = (typed, plain) => (ts ? typed : plain);
-    return `${ts ? '/// <reference types="vite/client" />\n' : ''}// Browser (Vite) build of the AI-Pay helper. Reads the VITE_AIPAY_* values \`aipay init\`
+    return `${ts ? '/// <reference types="vite/client" />\n' : ''}// Browser (Vite) build of the AI Pay helper. Reads the VITE_AIPAY_* values \`aipay init\`
 // wrote to .env.local (Vite exposes only VITE_-prefixed values to the page). No secret
 // exists: the app is a public PKCE client and the token endpoint accepts browser calls.
 import {
@@ -250,7 +261,7 @@ import {
 } from '@coswic/aipay-sdk'
 
 const cfg = {
-  hydraPublicUrl: import.meta.env.VITE_AIPAY_AUTH_ORIGIN${t(' as string', '')},
+  authOrigin: import.meta.env.VITE_AIPAY_AUTH_ORIGIN${t(' as string', '')}, // needs @coswic/aipay-sdk ${SDK_MIN_VERSION}+
   clientId: import.meta.env.VITE_AIPAY_CLIENT_ID${t(' as string', '')},
   redirectUri: import.meta.env.VITE_AIPAY_CALLBACK_URL${t(' as string', '')},
 }
@@ -258,10 +269,10 @@ const apiBase = import.meta.env.VITE_AIPAY_API_BASE${t(' as string', '')}
 /** Path part of the registered callback — the page that must call completeSignInIfCallback(). */
 export const CALLBACK_PATH = ${JSON.stringify(input.callbackPath)}
 
-const PENDING_KEY = 'aipay:pending' // { state, codeVerifier } while the user is at AI-Pay
+const PENDING_KEY = 'aipay:pending' // { state, codeVerifier } while the user is at AI Pay
 const TOKENS_KEY = 'aipay:tokens' // TokenSet for this tab (sessionStorage: cleared when the tab closes)
 
-/** Step 1 — send the user to AI-Pay. The PKCE verifier is kept under the state for the callback. */
+/** Step 1 — send the user to AI Pay. The PKCE verifier is kept under the state for the callback. */
 export async function beginSignIn()${t(': Promise<void>', '')} {
   const { url, state, codeVerifier } = await createConnectUrl(cfg)
   sessionStorage.setItem(PENDING_KEY, JSON.stringify({ state, codeVerifier }))
@@ -313,7 +324,7 @@ function viteBoot(input) {
     const ts = input.typescript;
     const from = ts ? './aipay' : './aipay.js';
     return `// Call bootAIPay() once when your app starts (top of main.${ts ? 'ts' : 'js'} / before rendering).
-// It completes the sign-in when the page is the AI-Pay callback (${input.callbackPath}) and
+// It completes the sign-in when the page is the AI Pay callback (${input.callbackPath}) and
 // otherwise does nothing. Vite's dev server serves index.html for that path (SPA fallback),
 // so no route configuration is needed; with a client-side router, keep the path unrouted.
 import { beginSignIn, completeSignInIfCallback, currentTokens, firstCompletion } from '${from}'
@@ -323,7 +334,7 @@ export async function bootAIPay() {
   const signedIn = justSignedIn !== null || currentTokens() !== null
   return {
     signedIn,
-    /** Wire this to your "Sign in with AI-Pay" button. */
+    /** Wire this to your "Sign in with AI Pay" button. */
     beginSignIn,
     /** After sign-in: one model call; the receipt (cost, request id) is on the result. */
     firstCompletion,

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@coswic/aipay",
-  "version": "0.7.2",
-  "description": "AI-Pay CLI — developer sign-in, App and callback management, project integration, diagnostics, and real sign-in + AI receipt verification.",
+  "version": "0.8.1",
+  "description": "AI Pay CLI — developer sign-in, App and callback management, project integration, diagnostics, and real sign-in + AI receipt verification.",
+  "author": "Coswic Labs (https://coswic.ai)",
   "license": "MIT",
   "homepage": "https://ai-pay.coswic.ai/docs?lang=en",
   "type": "module",
@@ -26,7 +27,7 @@
     "node": ">=20"
   },
   "dependencies": {
-    "@coswic/aipay-sdk": "^0.4.2"
+    "@coswic/aipay-sdk": "^0.5.1"
   },
   "devDependencies": {
     "@types/node": "^26.1.1",