@hasna/skills 0.9.20 → 0.10.0

package/dist/lib/auth-store.d.ts

@@ -82,12 +82,56 @@ export declare function getAuthConfig(env?: Env, options?: SkillsFleetOptions):
 /** Alias kept for the read-only callers; resolution never writes. */
 export declare function getAuthConfigReadOnly(env?: Env, options?: SkillsFleetOptions): AuthConfig | null;
 /**
- * Persist the credential (and any identity the server returned) for this user.
+ * How the stored key was obtained. `sign-in` keys were minted for this CLI by a
+ * browser/device or email sign-in, so `skills logout` may revoke them on the
+ * server; an `api-key` the user pasted is theirs to manage and is only
+ * forgotten locally. Recorded in identity.json (never a secret).
+ */
+export type StoredKeyIssuer = "sign-in" | "api-key";
+export declare function saveAuthConfig(config: StoredAuthConfig, env?: Env, authenticatedOrigin?: string, issuedBy?: StoredKeyIssuer): string;
+/**
+ * Who put the active profile's stored credential there — the question
+ * `skills logout` has to answer before it touches it (Instructions rule
+ * global-cli-logout-semantics, points 1 and 2).
+ *
+ *   sign-in  — minted for this CLI by `skills login` (browser, device code,
+ *              email code) or workspace enrollment. Revoked on logout by default.
+ *   api-key  — brought by the user with `skills login --api-key`. Deleted
+ *              locally on logout; revoked only with an explicit `--revoke`.
+ *   legacy   — stored by an older `skills auth login` that did not record how
+ *              the key was issued, so it cannot be revoked automatically.
+ *   external — no sign-in record at all: a provisioned key, a vault pointer, or
+ *              one written by another tool. Logout leaves it alone.
+ */
+export type StoredCredentialOrigin = StoredKeyIssuer | "legacy" | "external";
+/** The active profile's stored credential, as `skills logout` sees it. The key is never printed. */
+export interface StoredCredential {
+    /** The credentials file. A path: safe to print. */
+    file: string;
+    /** The stored key, or null when the file holds only a vault pointer. Never printed or logged. */
+    apiKey: string | null;
+    /** The instance the credential belongs to: its recorded binding, else the file URL, else the internal gateway. */
+    origin: string;
+    storedBy: StoredCredentialOrigin;
+    /** True when the file's URL line is there only because `skills login` wrote it; logout then removes it too. */
+    urlWrittenByLogin: boolean;
+}
+/**
+ * Read the active profile's stored credential WITHOUT the resolution ladder:
+ * logout must act on exactly the credential login stored for this profile,
+ * never on one the environment or the Keychain would supply instead.
+ */
+export declare function readStoredCredential(env?: Env): StoredCredential | null;
+/**
+ * Delete the stored credential for the active profile, and throw when it cannot
+ * be deleted: the key, its binding, any vault pointer and the display identity.
  *
- * Returns the file it wrote, so the CLI can name the real path rather than a
- * path it assumed.
+ * `removeUrl` also deletes the URL line, for a URL that `skills login` wrote
+ * (the product default or a `--url` given only to login). Leaving it would let
+ * a later environment-only key pair with a server nobody configured. A URL the
+ * user configured (`skills setup --api-url`) stays.
  */
-export declare function saveAuthConfig(config: StoredAuthConfig, env?: Env, authenticatedOrigin?: string): string;
+export declare function deleteStoredCredential(env?: Env, removeUrl?: boolean): string;
 /** Store (or clear, with null) the API URL beside the credential. */
 export declare function saveApiUrl(apiUrl: string | null, env?: Env): string;
 /** The API URL recorded in the credentials file, or null. */

package/dist/lib/fleet-credentials.d.ts

@@ -26,8 +26,11 @@
  *
  * URL: `HASNA_SKILLS_API_URL` → the Keychain `api-url` item → the credentials
  * file → the fleet gateway `https://api.hasna.com/skills`. The gateway default
- * applies ONLY once a credential has resolved, so an install with no credential
- * still names no host at all (the R1 boundary in vendor-host-policy.ts).
+ * applies ONLY once a credential has resolved, so a DATA request from an install
+ * with no credential names no host at all (the R1 boundary in
+ * vendor-host-policy.ts). Signing in is the one exception: with no URL and no
+ * credential, `resolveSkillsSignInOrigin` returns the product default
+ * (product-default.ts; owner rulings 2026-09-23).
  *
  * The unprefixed `SKILLS_API_URL` / `SKILLS_API_KEY` spellings are still
  * accepted, silently, because the shared seam accepts `<APP>_API_URL` /
@@ -81,6 +84,13 @@ export interface SkillsFleetOptions {
     /** Tier-1 credential inputs and the Keychain-tier controls (a fake runner in tests). */
     credentials?: CredentialChainOptions;
 }
+/**
+ * Every tier the shared resolver can return, in its precedence order. The
+ * pairing invariant (assertCredentialInstancePairing) classifies each one, and
+ * the pairing matrix test derives its rows from this list; the type below fails
+ * to compile if the resolver gains a tier this list does not name.
+ */
+export declare const SKILLS_CREDENTIAL_TIERS: readonly ["argument", "override", "pointer", "profile", "keychain", "disk", "env"];
 /** A hosted resolution: an authority to call and a credential to call it with. */
 export interface HostedSkillsFleet {
     mode: "hosted";
@@ -137,7 +147,9 @@ export type SkillsFleetErrorCode = "MISSING_API_CREDENTIAL" | "INVALID_API_URL"
  */
 export declare class SkillsFleetCredentialError extends Error {
     readonly code: SkillsFleetErrorCode;
-    constructor(message: string, code?: SkillsFleetErrorCode);
+    /** Machine-readable next steps, the same ones the message names. Never a value. */
+    readonly next?: readonly string[];
+    constructor(message: string, code?: SkillsFleetErrorCode, next?: readonly string[]);
 }
 /**
  * True for this package's own refusal, across bundle boundaries.
@@ -183,6 +195,12 @@ export interface ConfiguredSkillsApiUrl {
     value: string;
     /** An env key NAME, a `keychain:<service>@<account>` reference, or an absolute path. */
     source: string;
+    /**
+     * Which trust source configured it: the process environment, the Keychain,
+     * a credentials file (default or profile), or nothing (the gateway fallback
+     * of a selected profile). The pairing invariant reads this, never the name.
+     */
+    trust: "environment" | "keychain" | "file" | "default";
 }
 /**
  * The authority an operator configured, in the shared seam's precedence order —
@@ -222,6 +240,35 @@ export declare function resetLocalSkillsModeNotice(): void;
  * configured authority to local mode.
  */
 export declare function resolveSkillsFleet(env?: Env, options?: SkillsFleetOptions): SkillsFleet;
+/**
+ * Where a resolved credential may be sent: THE pairing invariant, classified
+ * once for every tier in {@link SKILLS_CREDENTIAL_TIERS} (the switch below is
+ * exhaustive, and an unknown tier is refused rather than guessed).
+ *
+ *   bound   — a stored credential that records its instance. The credentials
+ *             file key (`disk`), a profile file key (`profile`), a vault pointer
+ *             stored in a credentials file (`pointer` from a file) and the
+ *             Keychain key (`keychain`, bound to the Keychain `api-url` beside
+ *             it). It is sent only to that instance. A stored credential that
+ *             recorded none is a legacy internal key: the internal gateway.
+ *   unbound — a credential that records no instance: `HASNA_SKILLS_API_KEY` /
+ *             `SKILLS_API_KEY` (`env`), `HASNA_SKILLS_API_KEY_OVERRIDE`
+ *             (`override`), an environment `HASNA_SKILLS_API_KEY_REF` (`pointer`
+ *             from the environment) and an explicit argument (`argument`). It is
+ *             sent only to the internal gateway or to a URL from the environment
+ *             — never to a URL from a credentials file or the Keychain, which may
+ *             have been written for a different credential (a `skills login`, a
+ *             `skills setup`, a station provisioner).
+ *
+ * So a URL that `skills login` wrote binds only the key login stored beside it.
+ */
+export type CredentialPairing = {
+    kind: "bound";
+    instance: string;
+} | {
+    kind: "unbound";
+};
+export declare function credentialPairing(credential: ResolvedCredential, env: Env, options?: SkillsFleetOptions): CredentialPairing;
 /**
  * The usable API key for this process, completing a vault pointer if that is
  * the tier that won.
@@ -282,6 +329,43 @@ export declare function resolveSkillsApiOrigin(env?: Env, options?: SkillsFleetO
 } | null;
 /** The authority for an auth flow, or throw naming what is missing. */
 export declare function requireSkillsApiOrigin(action?: string, env?: Env, options?: SkillsFleetOptions): string;
+/** Where a sign-in goes, and what decided it. */
+export interface SignInTarget {
+    origin: string;
+    /** "--url", a configured URL's source, or "default". */
+    source: string;
+    /** Set when an already-resolving credential decided the origin: its source NAME, never a value. */
+    credentialSource?: string;
+}
+/**
+ * The refusal for a sign-in that would target the internal gateway, which has
+ * no sign-in service — or null. It names what to unset or remove, and never
+ * suggests pointing this machine at the product server while an internal
+ * credential is still configured. Nothing is sent either way.
+ */
+export declare function gatewaySignInRefusal(target: SignInTarget): SkillsFleetCredentialError | null;
+/**
+ * The authority a SIGN-IN talks to: `skills login`, `skills auth login` /
+ * `signup`, and the TUI `/login`. Resolved on its own because signing in is how
+ * a credential is obtained, so it cannot require one.
+ *
+ * In order:
+ *
+ *   1. `--url <origin>` — an explicit choice for this sign-in. It is refused when
+ *      an outranking URL (the environment or the Keychain) names a different
+ *      instance, because the key it mints would be shadowed the moment it is
+ *      saved. A URL in the credentials file is what a sign-in replaces.
+ *   2. a configured URL — environment, profile or credentials file, Keychain.
+ *   3. the instance an already-stored credential belongs to. A legacy internal
+ *      key with no recorded URL belongs to the fleet gateway, so a machine that
+ *      holds one keeps signing in there: its key is never sent to the product
+ *      default, and the product default is never chosen for it silently.
+ *   4. the product default ({@link SKILLS_PRODUCT_DEFAULT_ORIGIN}) — only when
+ *      no URL and no credential resolve anywhere (owner rulings 2026-09-23).
+ *
+ * Nothing here sends a request.
+ */
+export declare function resolveSkillsSignInOrigin(env?: Env, options?: SkillsFleetOptions, explicitUrl?: string): SignInTarget;
 /**
  * The hosted resolution, or throw. Use on every auth and write path.
  *

package/dist/lib/instance-credentials.d.ts

@@ -10,4 +10,10 @@ export declare function readSkillsInstanceMetadata(file: string): {
     apiUrl?: string;
     binding?: string;
 };
+/**
+ * Whether a credentials file names a key or a vault pointer. Reads key NAMES
+ * only, never a value; a missing file has none. Used to tell a brand-new named
+ * profile (nothing stored yet, so it may sign in) from a broken selection.
+ */
+export declare function skillsFileHasCredential(file: string): boolean;
 export {};

package/dist/lib/product-default.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Where `skills login` signs in when no URL and no credential are configured.
+ *
+ * It is not a data default: with no credential every data surface still fails
+ * closed and sends nothing. It is not a fallback for a credential that already
+ * resolves either: a legacy internal key with no bound URL keeps its internal
+ * gateway, for data and for signing in, and is never sent here. A completed
+ * sign-in records this origin beside the key it minted. Select another server
+ * with `skills login --url <origin>` or HASNA_SKILLS_API_URL.
+ *
+ * Typed as `string` so the emitted declaration carries no literal host.
+ */
+export declare const SKILLS_PRODUCT_DEFAULT_ORIGIN: string;

package/dist/lib/sign-in.d.ts

@@ -0,0 +1,213 @@
+/**
+ * Signing in and out, shared by `skills login` / `skills logout` / `skills
+ * whoami` and the interactive TUI's `/login`, `/logout` and `/whoami`.
+ *
+ * The flow follows the Codex CLI model the owner chose (2026-09-23): a browser
+ * sign-in by default, a printed device code for headless machines, an API key
+ * read from stdin, and a logout that revokes what the sign-in minted.
+ *
+ * Device authorization follows RFC 8628: poll no faster than the server's
+ * `interval`, add five seconds on every `slow_down`, and stop on
+ * `expired_token`, `invalid_device_code` or `access_denied`. A pending device
+ * session is saved beside the credentials file, owner-only, so a headless
+ * `skills login --device` can be finished later with `skills login --poll`
+ * instead of starting a new session and discarding the code the user approved.
+ *
+ * Nothing here decides WHERE to sign in: callers pass the origin from
+ * `resolveSkillsSignInOrigin()`, which never sends a legacy internal key to the
+ * product default.
+ */
+import { type StoredCredentialOrigin, type StoredKeyIssuer } from "./auth-store.js";
+import { type SkillsFleetOptions } from "./fleet-credentials.js";
+type Env = Record<string, string | undefined>;
+/** The CLI's device-authorization client label, recorded by the server. */
+export declare const SKILLS_CLI_DEVICE_CLIENT = "skills-cli";
+/** RFC 8628 §3.5: every slow_down adds five seconds to the polling interval. */
+export declare const SLOW_DOWN_INCREMENT_MS = 5000;
+export interface DeviceAuthorizationStart {
+    /** Bearer capability for the pending key. Never printed; stored owner-only. */
+    deviceCode: string;
+    userCode: string;
+    verificationUri: string;
+    verificationUriComplete?: string;
+    expiresIn: number;
+    interval: number;
+}
+/** What a successful sign-in returns: the key (or a session to mint one) and who signed in. */
+export interface SignInResult {
+    apiKey?: string;
+    token?: string;
+    user?: {
+        id?: string;
+        email?: string;
+        role?: string;
+    };
+    organization?: {
+        id?: string;
+        slug?: string;
+        name?: string;
+    };
+    firstLogin?: boolean;
+}
+export type DevicePollOutcome = {
+    status: "authorized";
+    result: SignInResult;
+} | {
+    status: "expired";
+} | {
+    status: "invalid";
+} | {
+    status: "denied";
+} | {
+    status: "timeout";
+} | {
+    status: "cancelled";
+};
+/** Validate the server's device-start answer; a malformed one is refused, never guessed at. */
+export declare function parseDeviceAuthorizationStart(body: unknown): DeviceAuthorizationStart;
+/** Ask the instance for a device code. Sends no credential. */
+export declare function startDeviceAuthorization(origin: string, client?: string): Promise<DeviceAuthorizationStart>;
+/** One poll of the token endpoint. Sends only the device code. */
+export declare function pollDeviceToken(origin: string, deviceCode: string): Promise<unknown>;
+export interface PollDeviceAuthorizationInput {
+    /** One token-endpoint request. Resolves with the body or throws HostedApiError. */
+    poll: () => Promise<unknown>;
+    intervalSeconds: number;
+    /** Epoch milliseconds after which polling stops with `timeout`. */
+    deadline: number;
+    signal?: AbortSignal;
+    /** Called with the new interval each time the server asks to slow down. */
+    onSlowDown?: (intervalMs: number) => void;
+    sleep?: (ms: number) => Promise<void>;
+    now?: () => number;
+}
+/**
+ * Poll until the user approves, the code expires, or the deadline passes.
+ *
+ * Transport failures and unexpected server errors are thrown, never read as
+ * "still pending": a sign-in that cannot reach its server must say so.
+ */
+export declare function pollDeviceAuthorization(input: PollDeviceAuthorizationInput): Promise<DevicePollOutcome>;
+export interface PendingDeviceSignIn {
+    origin: string;
+    deviceCode: string;
+    userCode: string;
+    verificationUri: string;
+    verificationUriComplete?: string;
+    interval: number;
+    /** Epoch milliseconds. */
+    expiresAt: number;
+}
+/**
+ * Beside the credentials file, one per profile AND instance:
+ * `device-login[-<profile>]-<origin hash>.json`. Keyed by origin so a sign-in
+ * started on one server never overwrites a pending session for another.
+ */
+export declare function pendingDeviceSignInPath(origin: string, env?: Env): string;
+export declare function savePendingDeviceSignIn(origin: string, start: DeviceAuthorizationStart, env?: Env, now?: number): string;
+/**
+ * The saved session for exactly this instance, if it has not expired. A session
+ * saved for a different instance is never returned, so its device code is only
+ * ever sent back to the server that issued it.
+ */
+export declare function loadPendingDeviceSignIn(origin: string, env?: Env, now?: number): PendingDeviceSignIn | null;
+/** The instances with an unexpired pending sign-in for this profile. */
+export declare function pendingDeviceSignInOrigins(env?: Env, now?: number): string[];
+/** Forget the pending session for one instance, or every pending session of this profile. */
+export declare function clearPendingDeviceSignIn(env?: Env, origin?: string): void;
+/**
+ * Store the key a sign-in produced, bound to the instance that issued it.
+ * A session-only answer (a token, no key) mints a CLI key first.
+ */
+export declare function persistSignIn(result: SignInResult, origin: string, env?: Env, issuedBy?: StoredKeyIssuer): Promise<string>;
+/**
+ * What happened to server-side revocation.
+ *
+ *   revoked        — the server confirmed it revoked the key.
+ *   already_ended  — the server no longer accepts the key (HTTP 401/403).
+ *   not_requested  — a user-brought key deleted without --revoke (still works).
+ *   skipped        — --no-revoke on a login-minted key (may still be live).
+ *   unsupported    — cannot be revoked: the server has no revoke route
+ *                    (404/405/501), the internal gateway has no login service,
+ *                    or an older sign-in left no record of how it was issued.
+ *   not_revoked    — the server answered without confirming revocation.
+ *   failed         — the request did not complete (network, 5xx, bad answer).
+ *   none           — no credential stored by `skills login` to revoke.
+ */
+export type RevocationOutcome = "revoked" | "already_ended" | "not_requested" | "skipped" | "unsupported" | "not_revoked" | "failed" | "none";
+/** A stable reason code plus one plain sentence. Never contains a credential. */
+export interface SignOutReason {
+    code: "revocation_failed" | "revocation_not_confirmed" | "revocation_unsupported" | "revocation_skipped" | "credential_not_from_login" | "credential_still_active" | "local_delete_failed";
+    message: string;
+}
+export interface SignOutResult {
+    /** Exit 0 when true: every reason list is empty. */
+    signedOut: boolean;
+    /** What happened to the active profile's stored credential. */
+    stored: "deleted" | "none" | "left_alone" | "delete_failed";
+    storedBy?: StoredCredentialOrigin;
+    /** The credentials file, when one holds a credential. */
+    file?: string;
+    /** The instance the stored credential belongs to. */
+    origin?: string;
+    revocation: RevocationOutcome;
+    /** Sentences for a human: what was done, in order. */
+    notes: string[];
+    /** Why the command must exit non-zero. Empty when signed out. */
+    reasons: SignOutReason[];
+}
+export interface SignOutOptions {
+    /**
+     * true: also revoke a user-brought or legacy key (`--revoke`).
+     * false: revoke nothing (`--no-revoke`); a login-minted key left live exits non-zero.
+     * undefined: the default — revoke only what login minted.
+     */
+    revoke?: boolean;
+    env?: Env;
+    /** Resolution controls (a fake Keychain in tests). */
+    fleet?: SkillsFleetOptions;
+    /**
+     * A profile the ENVIRONMENT selects that differs from the active one, e.g.
+     * `HASNA_PROFILE=b skills --profile a logout`. If it still holds a credential,
+     * the next plain command uses it, so logout names it and exits non-zero.
+     */
+    environmentProfile?: string;
+}
+/** Where a person revokes a key by hand. Never a composed URL. */
+export declare function manualRevocationHint(origin: string): string;
+export declare function signOut(options?: SignOutOptions): Promise<SignOutResult>;
+export type SignedInAccount = {
+    signedIn: false;
+    reason: string;
+} | {
+    signedIn: true;
+    apiOrigin: string;
+    source: string;
+    email?: string;
+    organization?: string;
+    error?: string;
+};
+/** The account in effect, for a compact display (the TUI's `/whoami`). */
+export declare function readSignedInAccount(env?: Env): Promise<SignedInAccount>;
+/**
+ * The verification page to open, or null when it must only be printed.
+ *
+ * The URL comes from the server's answer, so it is opened only when it is an
+ * https URL (http only on loopback) with no userinfo, on the sign-in origin
+ * itself or on `auth.<sign-in host>` — where rule global-product-auth-url-layout
+ * will move the identity endpoints. Anything else is printed for the user to
+ * judge and never handed to the operating system.
+ */
+export declare function verificationUrlToOpen(raw: string, signInOrigin: string): string | null;
+/**
+ * The opener argv for a platform. Never a shell: on Windows `cmd /c start`
+ * would re-parse `&`, `|` and `^` in a server-provided URL, so the URL goes to
+ * the URL protocol handler as one argument instead.
+ */
+export declare function browserCommand(url: string, platform?: NodeJS.Platform): string[];
+/**
+ * Best effort: the URL and code are always printed too, so a refusal or a
+ * failure here costs nothing. Returns whether a browser was asked to open it.
+ */
+export declare function openVerificationPage(url: string, signInOrigin: string): boolean;
+export {};

package/dist/lib/vendor-host-policy.d.ts

@@ -69,6 +69,32 @@ export declare const VENDOR_HOST_URL_EXCEPTIONS: readonly {
     url: string;
     reason: string;
 }[];
+/**
+ * The product default: the one vendor URL an UNCONFIGURED install may name.
+ *
+ * Owner rulings 2026-09-23 (Todos PLA8-00366) made the product the default place
+ * to SIGN IN, superseding R1 for that one path: with no URL and no credential,
+ * `skills login` targets this origin. Every data surface still fails closed with
+ * no URL at all, and a credential that already resolves keeps its own instance
+ * (see unconfigured-client-boundary.test.ts and skills-md-default.test.ts).
+ *
+ * Unlike {@link VENDOR_HOST_URL_EXCEPTIONS}, this exception is scoped to FILES as
+ * well as to the exact URL. The origin is declared once, in `src/lib/product-default.ts`;
+ * it may appear in the two bundles built from the CLI and MCP entry points that
+ * import it, and in the README that documents it. The same URL anywhere else —
+ * a server default, a skill, a split or folded literal — is still a finding, so
+ * a second copy cannot quietly become another default. The URL is not repeated
+ * in this file: it is the imported constant.
+ */
+export declare const PRODUCT_DEFAULT_URL_EXCEPTION: {
+    url: string;
+    files: readonly string[];
+    reason: string;
+};
+/** Is this exact URL excepted in this exact file? Global exceptions, then the scoped product default. */
+export declare function isExceptedVendorUrl(url: string, file: string): boolean;
+/** Every excepted URL for one file, for the value-independent token scan to strip. */
+export declare function exceptedVendorUrlsFor(file: string | undefined): string[];
 /** Reduce a hostname to its registrable domain (approximate eTLD+1). */
 export declare function registrableDomain(host: string): string;
 export declare function isLoopbackHost(host: string): boolean;

package/dist/lib/vendor-host-url.d.ts

@@ -65,7 +65,7 @@ export interface VendorHostFinding {
 /**
  * Find known vendor domains even when they do not appear in a complete URL.
  */
-export declare function findVendorDomainTokens(text: string): {
+export declare function findVendorDomainTokens(text: string, file?: string): {
     domain: string;
     index: number;
 }[];

package/dist/sdk/index.js

@@ -32373,7 +32373,7 @@ var init_event_sink = __esm(() => {
 // package.json
 var package_default = {
   name: "@hasna/skills",
-  version: "0.9.20",
+  version: "0.10.0",
   description: "Skills library for AI coding agents",
   type: "module",
   bin: {
@@ -33505,13 +33505,15 @@ var SKILLS_API_URL_ENV_KEYS = ENV_KEYS.apiUrlKeys;
 var SKILLS_API_KEY_ENV_KEYS = ENV_KEYS.apiKeyKeys;
 var SKILLS_API_URL_ENV = SKILLS_API_URL_ENV_KEYS[0];
 var SKILLS_API_KEY_ENV = SKILLS_API_KEY_ENV_KEYS[0];
-
 class SkillsFleetCredentialError extends Error {
   code;
-  constructor(message, code = "MISSING_API_CREDENTIAL") {
+  next;
+  constructor(message, code = "MISSING_API_CREDENTIAL", next) {
     super(message);
     this.name = "SkillsFleetCredentialError";
     this.code = code;
+    if (next)
+      this.next = next;
   }
 }
 function isCredentialResolutionError(error) {
@@ -33569,7 +33571,7 @@ function configuredSkillsApiUrl(env = process.env, keychain, profile) {
     if (!entry.value.trim() || /[\x00-\x1f\x7f]/.test(entry.value))
       throw new SkillsFleetCredentialError(`${entry.key} is blank or contains control characters`, "INVALID_API_URL");
   }
-  const normalized = declared.map((entry) => ({ value: normalizeSkillsApiOrigin(entry.value), source: entry.key }));
+  const normalized = declared.map((entry) => ({ value: normalizeSkillsApiOrigin(entry.value), source: entry.key, trust: "environment" }));
   if (new Set(normalized.map((entry) => entry.value)).size > 1)
     throw new SkillsFleetCredentialError("Skills API URL aliases disagree", "INVALID_API_URL");
   if (normalized[0])
@@ -33578,19 +33580,19 @@ function configuredSkillsApiUrl(env = process.env, keychain, profile) {
     for (const file of skillsProfileCredentialFiles(env, profile)) {
       const metadata = readSkillsInstanceMetadata(file);
       if (metadata.apiUrl || metadata.binding)
-        return { value: metadata.apiUrl ?? metadata.binding, source: file };
+        return { value: metadata.apiUrl ?? metadata.binding, source: file, trust: "file" };
     }
-    return { value: defaultFleetGatewayBaseUrl(SKILLS_APP), source: "default" };
+    return { value: defaultFleetGatewayBaseUrl(SKILLS_APP), source: "default", trust: "default" };
   }
   const fromKeychain = keychainConfigValue(SKILLS_APP, env, keychain);
   if (fromKeychain)
-    return { value: fromKeychain.value.trim(), source: fromKeychain.source };
+    return { value: fromKeychain.value.trim(), source: fromKeychain.source, trust: "keychain" };
   const fromDisk = appConfigDiskValue(SKILLS_APP, env, SKILLS_API_URL_ENV_KEYS);
   if (fromDisk?.unusable) {
     throw new SkillsFleetCredentialError(`${fromDisk.key} in ${fromDisk.path} is declared but blank or malformed; ` + `a Skills authority must be a valid https URL (or an exact loopback http URL).`, "INVALID_API_URL");
   }
   if (fromDisk)
-    return { value: fromDisk.value.trim(), source: fromDisk.path };
+    return { value: fromDisk.value.trim(), source: fromDisk.path, trust: "file" };
   return null;
 }
 function skillsCredentialFiles(env = process.env) {
@@ -33653,13 +33655,13 @@ function resolveSkillsFleetOrThrow(env, options) {
   const credential = resolveCredential(SKILLS_APP, env, options.credentials);
   if (!credential) {
     if (!configured) {
-      throw new SkillsFleetCredentialError(`No API key resolved and no Skills API URL is configured \u2014 failing closed ` + `(local mode is opt-in only: set ${SKILLS_LOCAL_OPT_IN_ENV_KEYS[0]}=1 to run on this machine). ` + `Looked in ${credentialLocations(env)}. Sign in with: skills auth login`);
+      throw new SkillsFleetCredentialError(`No API key resolved and no Skills API URL is configured \u2014 failing closed ` + `(local mode is opt-in only: set ${SKILLS_LOCAL_OPT_IN_ENV_KEYS[0]}=1 to run on this machine). ` + `Looked in ${credentialLocations(env)}. Sign in with: skills login`);
     }
-    throw new SkillsFleetCredentialError(`${configured.source} points this CLI at a Skills service but no API key resolved \u2014 refusing to run locally instead. ` + `Looked in ${credentialLocations(env)}. Sign in with: skills auth login`);
+    throw new SkillsFleetCredentialError(`${configured.source} points this CLI at a Skills service but no API key resolved \u2014 refusing to run locally instead. ` + `Looked in ${credentialLocations(env)}. Sign in with: skills login`);
   }
   const apiOrigin = normalizeSkillsApiOrigin(configured?.value ?? defaultFleetGatewayBaseUrl(SKILLS_APP));
   toV1BaseUrl(apiOrigin);
-  assertCredentialInstance(credential, apiOrigin, env, options);
+  assertCredentialInstancePairing(credential, configured, apiOrigin, env, options);
   assertFilesUnchanged();
   const base = {
     mode: "hosted",
@@ -33673,7 +33675,7 @@ function resolveSkillsFleetOrThrow(env, options) {
     return { ...base, apiKey: null, apiKeyPointer: credential };
   }
   if (!credential.apiKey.trim()) {
-    throw new SkillsFleetCredentialError(`The Skills API key from ${credential.source} is empty \u2014 refusing to send an unauthenticated request. ` + `Sign in with: skills auth login`);
+    throw new SkillsFleetCredentialError(`The Skills API key from ${credential.source} is empty \u2014 refusing to send an unauthenticated request. ` + `Sign in with: skills login`);
   }
   return { ...base, apiKey: credential.apiKey, apiKeyPointer: null };
 }
@@ -33681,17 +33683,49 @@ function credentialLocations(env) {
   const files = skillsCredentialFiles(env).join(" or ") || "no credentials file (HOME is unset)";
   return `hasna.credentials.${SKILLS_APP}.api-key (macOS Keychain, account HASNA_STATION or the host name), ${files}, and ${SKILLS_API_KEY_ENV}`;
 }
-function assertCredentialInstance(credential, apiOrigin, env, options) {
-  let bound;
-  if (credential.tier === "disk" || credential.tier === "profile" || credential.tier === "pointer" && credential.diskCandidates.includes(credential.source)) {
-    const metadata = readSkillsInstanceMetadata(credential.source);
-    bound = metadata.binding ?? metadata.apiUrl ?? defaultFleetGatewayBaseUrl(SKILLS_APP);
-  } else if (credential.tier === "keychain") {
-    bound = keychainConfigValue(SKILLS_APP, env, options.credentials?.keychain)?.value ?? defaultFleetGatewayBaseUrl(SKILLS_APP);
+function credentialPairing(credential, env, options = {}) {
+  const fileBinding = (file) => {
+    const metadata = readSkillsInstanceMetadata(file);
+    return { kind: "bound", instance: normalizeSkillsApiOrigin(metadata.binding ?? metadata.apiUrl ?? defaultFleetGatewayBaseUrl(SKILLS_APP)) };
+  };
+  const tier = credential.tier;
+  switch (tier) {
+    case "disk":
+    case "profile":
+      return fileBinding(credential.source);
+    case "pointer":
+      return credential.diskCandidates.includes(credential.source) ? fileBinding(credential.source) : { kind: "unbound" };
+    case "keychain":
+      return {
+        kind: "bound",
+        instance: normalizeSkillsApiOrigin(keychainConfigValue(SKILLS_APP, env, options.credentials?.keychain)?.value ?? defaultFleetGatewayBaseUrl(SKILLS_APP))
+      };
+    case "env":
+    case "override":
+    case "argument":
+      return { kind: "unbound" };
+    default: {
+      const unclassified = tier;
+      throw new SkillsFleetCredentialError(`The Skills credential from ${credential.source} has an unclassified tier (${String(unclassified)}); refusing to send it.`, "INSTANCE_CREDENTIAL_MISMATCH");
+    }
   }
-  if (bound && normalizeSkillsApiOrigin(bound) !== apiOrigin) {
+}
+function assertCredentialInstancePairing(credential, configured, apiOrigin, env, options) {
+  const pairing = credentialPairing(credential, env, options);
+  if (pairing.kind === "bound") {
+    if (pairing.instance === apiOrigin)
+      return;
     throw new SkillsFleetCredentialError("The selected Skills API does not match this credential's instance. Select its profile or sign in to the new instance; no credential was sent.", "INSTANCE_CREDENTIAL_MISMATCH");
   }
+  if (apiOrigin === normalizeSkillsApiOrigin(defaultFleetGatewayBaseUrl(SKILLS_APP)))
+    return;
+  if (configured?.trust === "environment")
+    return;
+  const next = [
+    `set ${SKILLS_API_URL_ENV} alongside ${credential.source}`,
+    `unset ${credential.source}, then run: skills login`
+  ];
+  throw new SkillsFleetCredentialError(`${credential.source} records no Skills server of its own, so it is only sent to the internal gateway or to a URL ` + `from the environment (${SKILLS_API_URL_ENV}); the Skills URL here comes from ${configured?.source ?? "nowhere"}. ` + `No credential was sent. To use your own server, ${next[0]}; otherwise ${next[1]}.`, "INSTANCE_CREDENTIAL_MISMATCH", next);
 }
 async function resolveSkillsApiKey(env = process.env, options = {}) {
   return (await resolveSkillsConnection(env, options))?.apiKey ?? null;
@@ -33708,7 +33742,7 @@ async function resolveSkillsConnection(env = process.env, options = {}) {
     return { ...fleet, apiKey: fleet.apiKey };
   const pointer = fleet.apiKeyPointer;
   if (!pointer) {
-    throw new SkillsFleetCredentialError(`A Skills authority resolved but no API key did. Sign in with: skills auth login`);
+    throw new SkillsFleetCredentialError(`A Skills authority resolved but no API key did. Sign in with: skills login`);
   }
   let completed;
   try {
@@ -33775,7 +33809,7 @@ function requireSkillsFleet(action = "This command", env = process.env, options
 class MissingSkillsFleetError extends Error {
   code = "MISSING_API_URL";
   constructor(action = "This command") {
-    super(`${action} requires a Skills API credential and none is configured \u2014 ` + `run: skills auth login, or set ${SKILLS_API_KEY_ENV} ` + `(add the Keychain item hasna.credentials.${SKILLS_APP}.api-key, or write ~/.hasna/skills/config/credentials). ` + `Point at your own instance with ${SKILLS_API_URL_ENV}, or run: skills setup --api-url <your Skills instance origin>`);
+    super(`${action} requires a Skills API credential and none is configured \u2014 ` + `run: skills login, or set ${SKILLS_API_KEY_ENV} ` + `(add the Keychain item hasna.credentials.${SKILLS_APP}.api-key, or write ~/.hasna/skills/config/credentials). ` + `Point at your own instance with ${SKILLS_API_URL_ENV}, or run: skills setup --api-url <your Skills instance origin>`);
     this.name = "MissingSkillsFleetError";
   }
 }
@@ -90557,7 +90591,7 @@ class RemoteSkillsAuthClient {
     return (await this.sessionClient(email4, code, context)).removeWorkspaceMember(captured.membershipId, captured.body);
   }
   request(path2, options) {
-    if (!["/api/auth/login", "/api/auth/verify", "/api/auth/device/start", "/api/auth/device/token", "/api/auth/keys", "/api/auth/whoami"].includes(path2))
+    if (!["/api/auth/login", "/api/auth/verify", "/api/auth/device/start", "/api/auth/device/token", "/api/auth/keys", "/api/auth/whoami", "/api/auth/logout"].includes(path2))
       throw new Error("Unsupported authentication operation");
     return requestAuthApi(this.apiOrigin, path2, options);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/skills",
-  "version": "0.9.20",
+  "version": "0.10.0",
   "description": "Skills library for AI coding agents",
   "type": "module",
   "bin": {