@hasna/skills 0.9.20 → 0.10.1

package/dist/index.js

@@ -9611,7 +9611,7 @@ import { isAbsolute as isAbsolute11, join as join23, resolve as resolve11 } from
 // package.json
 var package_default = {
   name: "@hasna/skills",
-  version: "0.9.20",
+  version: "0.10.1",
   description: "Skills library for AI coding agents",
   type: "module",
   bin: {
@@ -10569,9 +10569,17 @@ var AUTHORITY_OVERRIDE_HEADERS = new Set([
 
 // src/lib/instance-credentials.ts
 import { closeSync as closeSync5, constants as constants2, fstatSync as fstatSync5, lstatSync as lstatSync8, openSync as openSync5, readSync as readSync2 } from "fs";
+
+// src/lib/cli-credential-profile.ts
+var cliCredentialProfile;
+function selectedCliSkillsCredentialProfile() {
+  return cliCredentialProfile;
+}
+
+// src/lib/instance-credentials.ts
 var SKILLS_BOUND_API_URL = "HASNA_SKILLS_BOUND_API_URL";
 function selectedSkillsProfile(env, explicit) {
-  const selected = explicit ?? env.HASNA_PROFILE;
+  const selected = explicit ?? selectedCliSkillsCredentialProfile() ?? env.HASNA_PROFILE;
   if (selected === undefined)
     return null;
   const profile = selected.trim();
@@ -10684,13 +10692,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) {
@@ -10748,7 +10758,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])
@@ -10757,19 +10767,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) {
@@ -10817,11 +10827,13 @@ function snapshotSkillsEnvironment(env) {
   return Object.freeze(snapshot);
 }
 function snapshotSkillsOptions(env, options) {
+  const profile = options.credentials?.profile ?? selectedCliSkillsCredentialProfile();
+  const credentials = profile === undefined ? options.credentials : { ...options.credentials, profile };
   if (env !== process.env)
-    return options;
-  return { ...options, credentials: { ...options.credentials, keychain: {
-    ...options.credentials?.keychain,
-    enabled: options.credentials?.keychain?.enabled ?? true
+    return credentials === options.credentials ? options : { ...options, credentials };
+  return { ...options, credentials: { ...credentials, keychain: {
+    ...credentials?.keychain,
+    enabled: credentials?.keychain?.enabled ?? true
   } } };
 }
 function resolveSkillsFleetOrThrow(env, options) {
@@ -10832,13 +10844,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",
@@ -10852,7 +10864,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 };
 }
@@ -10860,25 +10872,58 @@ 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;
 }
 async function resolveSkillsConnection(env = process.env, options = {}) {
   const snapshotEnv = snapshotSkillsEnvironment(env);
-  const assertFilesUnchanged = selectsSkillsLocalMode(snapshotEnv) ? () => {} : captureSkillsCredentialFiles(skillsProfileCredentialFiles(snapshotEnv, options.credentials?.profile));
-  const fleet = resolveSkillsFleet(snapshotEnv, snapshotSkillsOptions(env, options));
+  const resolvedOptions = snapshotSkillsOptions(env, options);
+  const assertFilesUnchanged = selectsSkillsLocalMode(snapshotEnv) ? () => {} : captureSkillsCredentialFiles(skillsProfileCredentialFiles(snapshotEnv, resolvedOptions.credentials?.profile));
+  const fleet = resolveSkillsFleet(snapshotEnv, resolvedOptions);
   if (fleet.mode === "local" && env === process.env)
     noticeLocalSkillsMode();
   if (fleet.mode !== "hosted")
@@ -10887,7 +10932,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 {
@@ -10954,7 +10999,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";
   }
 }
@@ -36498,7 +36543,7 @@ function date4(params) {
 }
 // src/lib/api-url.ts
 var API_URL_ENV_VAR = SKILLS_API_URL_ENV;
-var MISSING_API_URL_HINT = `run: skills auth login, or set ${API_URL_ENV_VAR}=<your Skills instance origin>, ` + `or run: skills setup --api-url <your Skills instance origin>`;
+var MISSING_API_URL_HINT = `run: skills login, or set ${API_URL_ENV_VAR}=<your Skills instance origin>, ` + `or run: skills setup --api-url <your Skills instance origin>`;
 function resolveApiUrl(env = process.env, options = {}) {
   const fleet = resolveSkillsFleet(env, options);
   return fleet.mode === "hosted" ? fleet.apiOrigin : undefined;
@@ -40659,7 +40704,7 @@ class RemoteSkillsAuthClient {
     return (await this.sessionClient(email4, code, context)).removeWorkspaceMember(captured.membershipId, captured.body);
   }
   request(path, options) {
-    if (!["/api/auth/login", "/api/auth/verify", "/api/auth/device/start", "/api/auth/device/token", "/api/auth/keys", "/api/auth/whoami"].includes(path))
+    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(path))
       throw new Error("Unsupported authentication operation");
     return requestAuthApi(this.apiOrigin, path, options);
   }

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/cli-credential-profile.d.ts

@@ -0,0 +1,2 @@
+export declare function selectCliSkillsCredentialProfile(profile: string | undefined): void;
+export declare function selectedCliSkillsCredentialProfile(): string | undefined;

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;