@hasna/skills 0.2.0 → 0.3.0

package/dist/lib/api-url.d.ts

@@ -1,34 +1,43 @@
 /**
- * Single source of truth for resolving the Skills API endpoint.
+ * Where the Skills API lives, for this process, right now.
  *
- * Boundary rule (R1): an unconfigured install must never produce a URL on a
- * vendor-controlled host.
+ * This module is a thin reading of `fleet-credentials.ts`, which is itself a
+ * thin reading of `@hasna/contracts/client`. It exists only so the two failure
+ * MODES stay named:
  *
- *   - Read paths fail closed: `resolveApiUrl()` returns `undefined` and the
- *     caller keeps working against the bundled local registry.
- *   - Auth and write paths fail loudly: `requireApiUrl()` throws an error that
- *     names the missing configuration.
+ *   - Read paths fail closed: `resolveApiUrl()` returns `undefined` when nothing
+ *     is configured, and the caller keeps working against the bundled local
+ *     registry.
+ *   - Auth and write paths fail loudly: `requireApiUrl()` throws an error naming
+ *     the missing configuration.
  *
- * There is deliberately no fallback endpoint and no localhost default. An
- * unconfigured CLI has nothing sane to point a credential-bearing request at,
- * so it must say so rather than pick a host on the user's behalf.
+ * Boundary rule (R1), unchanged in substance: an install with NO credential
+ * produces no URL at all. The fleet gateway default in the shared seam applies
+ * only once a credential has resolved, so an unconfigured OSS install still
+ * names no host — see `resolveSkillsFleet`.
+ *
+ * A URL that IS configured while no credential resolves does not fall back to
+ * local: it throws (SkillsFleetCredentialError). Reading local data because
+ * authentication is unconfigured is the false green this ladder exists to
+ * remove.
  */
-import { type SkillsConfig } from "./config.js";
-export declare const API_URL_ENV_VAR = "SKILLS_API_URL";
-export declare const API_URL_CONFIG_KEY = "apiUrl";
+import { type SkillsFleetOptions } from "./fleet-credentials.js";
+/** The canonical env name. The unprefixed `SKILLS_API_URL` alias is still read. */
+export declare const API_URL_ENV_VAR: string;
 /** Hint shown wherever a Skills API URL is required but absent. */
 export declare const MISSING_API_URL_HINT: string;
-export declare class MissingApiUrlError extends Error {
-    readonly code = "MISSING_API_URL";
-    constructor(action?: string);
-}
+/** Kept under its old name: callers and tests match on this identity. */
+export { MissingSkillsFleetError as MissingApiUrlError } from "./fleet-credentials.js";
+type Env = Record<string, string | undefined>;
 /**
- * Resolve the configured Skills API origin, or `undefined` when the install has
- * not been pointed at an instance. `SKILLS_API_URL` wins over the config file.
+ * Resolve the Skills origin in effect, or `undefined` when this install has
+ * neither a credential nor an authority — i.e. runs on this machine.
+ *
+ * Throws when an authority IS configured and no credential resolves.
  */
-export declare function resolveApiUrl(config?: SkillsConfig, env?: Record<string, string | undefined>): string | undefined;
+export declare function resolveApiUrl(env?: Env, options?: SkillsFleetOptions): string | undefined;
 /**
- * Resolve the configured Skills API origin, or throw naming the missing
- * configuration. Use this on every auth and write path.
+ * Resolve the Skills origin, or throw naming what is missing. Use this on every
+ * auth and write path.
  */
-export declare function requireApiUrl(action?: string, config?: SkillsConfig, env?: Record<string, string | undefined>): string;
+export declare function requireApiUrl(action?: string, env?: Env, options?: SkillsFleetOptions): string;

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

@@ -1,66 +1,135 @@
 /**
- * auth.json lives at the skills app root, beside config.json.
+ * The credential the CLI signs in with, and the identity it displays.
  *
- * Resolved through getDataDir() so that $HASNA_SKILLS_DIR relocates the
- * credential file along with the rest of the app's state. It used to be an
- * import-time constant composed from homedir(), so with the override set the
- * CLI stored its API key at ~/.hasna/skills/auth.json while config, corpus,
- * and database all moved — the same override-only-half-works split getDataDir()
- * documents for its own history.
+ * READING is not done here. Every read goes through `fleet-credentials.ts` →
+ * `@hasna/contracts/client`, so the argument, the env pointer, the macOS
+ * Keychain, `~/.hasna/skills/config/credentials` and `HASNA_SKILLS_API_KEY` are
+ * consulted in the fleet's one order, on every call. There is no cache: a
+ * credential is mutable state, and a value captured at process start is the
+ * defect the ladder exists to remove (a shell that outlives a key rotation).
  *
- * The legacy ~/.skills/auth.json stays a $HOME concern, exactly like
- * getDataDir()'s legacy merge (which is deliberately skipped for an overridden
- * dir): it is still read as a fallback and removed by clearAuthConfig(), but
- * never written when the override is set. Like getDataDir(), the home is read
- * from the environment at call time — os.homedir() caches its answer after the
- * first call, so a process that re-points $HOME would keep composing the old
- * path.
+ * WRITING lands in exactly one file — `~/.hasna/skills/config/credentials`,
+ * mode 0600, the shared seam's disk tier — so `skills auth login` on this
+ * machine and a station wrapper reading the same file cannot disagree.
+ * `HASNA_HOME` / `HASNA_CONFIG_HOME` relocate it; `$HASNA_SKILLS_DIR` does not,
+ * because that variable relocates this app's DATA (corpus, database, config),
+ * and the fleet credential is not app data — it is the machine's, shared with
+ * every other Hasna CLI.
+ *
+ * The display identity (`email`, org, user ids) is NOT a credential and lives
+ * beside it in `identity.json`. It is only ever what the server's `whoami`
+ * returned; nothing here invents a field.
+ *
+ * `~/.skills/auth.json` and `~/.hasna/skills/auth.json` are retired locations and
+ * are not read. `skills auth login` writes the credentials file; an operator
+ * still holding an old auth.json is told to sign in again.
  */
-export declare function getAuthFilePath(): string;
+import { type SkillsFleetOptions } from "./fleet-credentials.js";
+export { normalizeSkillsApiOrigin } from "./fleet-credentials.js";
+type Env = Record<string, string | undefined>;
+/** The credentials file this package writes and the shared seam reads. */
+export declare function getAuthFilePath(env?: Env): string;
 /**
- * Write-free credential path resolution for read-only paths (e.g. `sync --dry-run`).
+ * Write-free path resolution for read-only paths (e.g. `sync --dry-run`).
  *
- * getAuthFilePath() routes through getDataDir(), which WRITES (mkdirs the app dir,
- * merges legacy ~/.skills content, copies the legacy config). A dry run must read
- * the same credential file a real run would without performing any of that.
+ * Identical to getAuthFilePath(): nothing in the credential path writes as a
+ * side effect of resolving any more. Kept as a separate name so the read-only
+ * callers keep reading as read-only.
  */
-export declare function getAuthFilePathReadOnly(): string;
+export declare function getAuthFilePathReadOnly(env?: Env): string;
+/** The display identity file beside the credential. Never holds a secret. */
+export declare function getIdentityFilePath(env?: Env): string;
 /**
  * Stored credentials for a Skills API instance.
  *
- * `apiKey` is the only credential. The identity fields are display metadata
- * echoed back from the instance's `whoami`, so they are optional: an instance
- * that does not return them leaves them unset. They are never invented locally
- * — a placeholder written here is indistinguishable from a value the server
- * actually returned once it is read back out of `auth.json`.
+ * `apiKey` is the credential the ladder resolved — not necessarily one this CLI
+ * wrote. The identity fields are display metadata echoed back from the
+ * instance's `whoami`, so they are optional: an instance that does not return
+ * them leaves them unset. They are never invented locally — a placeholder
+ * written here is indistinguishable from a value the server actually returned.
  */
 export interface AuthConfig {
-    apiKey: string;
+    /**
+     * The credential the ladder resolved, or null when it is a vault POINTER that
+     * only the async path can complete (see {@link getApiKeyAsync}). Callers that
+     * need to SEND it must resolve it there; the display surfaces below only need
+     * to know that one is configured.
+     */
+    apiKey: string | null;
     email?: string;
     orgId?: string;
     orgSlug?: string;
     userId?: string;
 }
-export declare function getAuthConfig(): AuthConfig | null;
-export declare function saveAuthConfig(config: AuthConfig): void;
-export declare function clearAuthConfig(): void;
-export declare function getApiKey(): string | null;
+/** The identity half, on its own: what `whoami` said, with no credential. */
+export type AuthIdentity = Omit<AuthConfig, "apiKey">;
+/**
+ * What `saveAuthConfig` is handed: a key this CLI actually holds.
+ *
+ * Distinct from {@link AuthConfig}, whose `apiKey` may be null for a vault
+ * pointer — there is nothing to write to disk in that case, and writing an
+ * empty line would masquerade as a stored credential.
+ */
+export type StoredAuthConfig = AuthIdentity & {
+    apiKey: string;
+};
+export declare function getAuthIdentity(env?: Env): AuthIdentity;
+/**
+ * The credential in effect plus whatever identity was recorded for it, or null
+ * when no credential resolves anywhere on the ladder.
+ */
+export declare function getAuthConfig(env?: Env, options?: SkillsFleetOptions): AuthConfig | null;
+/** Alias kept for the read-only callers; resolution never writes. */
+export declare function getAuthConfigReadOnly(env?: Env, options?: SkillsFleetOptions): AuthConfig | null;
 /**
- * Write-free credential read for read-only paths (e.g. `sync --dry-run`).
+ * Persist the credential (and any identity the server returned) for this user.
  *
- * getAuthConfig() resolves through getAuthFilePath() -> getDataDir(), which
- * writes. Reads the same files (canonical auth.json, then the legacy ~/.skills
- * fallback) without creating or migrating anything, and without touching the
- * write path's module-level cache.
+ * Returns the file it wrote, so the CLI can name the real path rather than a
+ * path it assumed.
+ */
+export declare function saveAuthConfig(config: StoredAuthConfig, env?: Env): 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. */
+export declare function readStoredApiUrl(env?: Env): string | null;
+/**
+ * Remove the credential this CLI wrote.
+ *
+ * Only the file is cleared: a key injected from the environment or held in the
+ * Keychain belongs to the machine, not to this command, and silently appearing
+ * to remove it would be a lie. The caller is told whether one still resolves.
+ */
+export declare function clearAuthConfig(env?: Env): {
+    stillResolves: boolean;
+};
+/**
+ * The credential in effect, resolved fresh through the shared ladder.
+ *
+ * SYNCHRONOUS, so it cannot complete a vault pointer
+ * (`HASNA_SKILLS_API_KEY_REF`): for that tier it returns null, because the
+ * pointer's own value is the empty string and handing THAT back as a key is how
+ * `Authorization: Bearer ` reached the wire. Any path that is about to SEND the
+ * key must use {@link getApiKeyAsync} (or `resolveSkillsApiKey`), which fetches
+ * the vault item and refuses loudly when it cannot.
+ */
+export declare function getApiKey(env?: Env, options?: SkillsFleetOptions): string | null;
+/**
+ * The credential in effect, completing a vault pointer through the secrets
+ * vault. Null only in local mode; throws when a configured credential cannot
+ * be produced. Use this wherever the key is about to be sent.
  */
-export declare function getAuthConfigReadOnly(): AuthConfig | null;
-export declare function getApiKeyReadOnly(): string | null;
-export declare function normalizeSkillsApiOrigin(apiUrl: string): string;
+export declare function getApiKeyAsync(env?: Env, options?: SkillsFleetOptions): Promise<string | null>;
+/** Identical to getApiKey(): resolution has no write side effects. */
+export declare function getApiKeyReadOnly(env?: Env, options?: SkillsFleetOptions): string | null;
 /**
  * Origin every credential-bearing request is sent to.
  *
- * Throws `MissingApiUrlError` when the install has not been pointed at an
- * instance. There is no fallback endpoint: an unconfigured CLI must not decide
- * on the user's behalf where their email address, login code, or API key goes.
+ * The AUTHORITY, not the whole hosted resolution: `skills auth login` runs
+ * before there is a credential, and requiring one here would make signing in
+ * impossible. Throws when nothing names a service: an install that named none
+ * must not decide on the user's behalf where their email address, login code,
+ * or API key goes.
  */
-export declare function getApiUrl(action?: string): string;
+export declare function getApiUrl(action?: string, env?: Env, options?: SkillsFleetOptions): string;
+/** Permission bits of the credentials file, for `skills auth status`-style output. */
+export declare function credentialFileMode(env?: Env): number | null;

package/dist/lib/config.d.ts

@@ -16,29 +16,29 @@
  */
 export { DATA_DIR_ENV } from "./app-home.js";
 /**
- * There is no deployment "mode" key.
+ * There is no deployment "mode" key, and no service address here either.
  *
  * Skills has one deployment story: you run it. Whether this CLI talks to a
- * server is not a product variant, it is one fact — whether an API origin is
- * configured (apiUrl here, or $SKILLS_API_URL). Nothing else may be derived
- * from a declared label, because a label can disagree with the configuration
- * it claims to describe.
+ * server is not a product variant, it is one fact — whether a fleet credential
+ * resolves. Nothing may be derived from a declared label, because a label can
+ * disagree with the configuration it claims to describe.
  *
- * One caveat, true at the time of writing and tracked separately: getApiUrl()
- * in auth-store.ts still falls back to a built-in origin when neither is set,
- * so "no origin configured" is not yet the same as "sends nothing anywhere" on
- * the auth path. Removing that fallback belongs to the no-vendor-defaults work,
- * not here; remote-registry.ts already fails closed and is the model.
+ * `apiUrl` used to live here as a sixth URL tier of this package's own. It is
+ * retired (owner ruling 2026-09-04, hasna/apps#1720): the authority ladder is
+ * `HASNA_SKILLS_API_URL` → the Keychain `api-url` item →
+ * `~/.hasna/skills/config/credentials` → the fleet gateway, and it belongs to
+ * @hasna/contracts so every Hasna CLI resolves it identically.
+ * `skills setup --api-url <origin>` still writes it — into the credentials file.
  *
- * Configs written by older versions may still carry a "mode" key on disk. That is
- * refused rather than ignored - see lib/retired-settings.ts for why silence is
- * the worse of the two failures - and `skills config unset mode` removes it.
+ * Configs written by older versions may still carry a "mode" or "apiUrl" key on
+ * disk. Those are refused rather than ignored — see lib/retired-settings.ts for
+ * why silence is the worse of the two failures — and `skills config unset <key>`
+ * removes them.
  */
 export interface SkillsConfig {
     defaultAgent?: "claude" | "codex" | "gemini" | "pi" | "opencode" | "all";
     defaultScope?: "global" | "project";
     format?: "compact" | "json" | "csv";
-    apiUrl?: string;
     extensionsDir?: string;
 }
 export type ConfigScope = "global" | "project";
@@ -109,9 +109,8 @@ export declare function getConfigPathReadOnly(scope: ConfigScope): string;
  * This mirrors that FILE-LEVEL precedence, never field-level merging: canonical
  * config.json, when present, is the whole global config; legacy ~/.skillsrc is read
  * only in the exact situation the write path would copy it (no canonical file, no
- * override). Field-level merging would inherit a stale legacy origin beneath a
- * canonical config that omits apiUrl — and the client sends its stored credential to
- * whatever origin resolves, so divergence from the write path is credential-bearing.
+ * override). Field-level merging would inherit stale legacy values beneath a
+ * canonical config that omits them, so the two paths must agree exactly.
  */
 export declare function loadConfigReadOnly(): SkillsConfig;
 /**
@@ -129,10 +128,9 @@ export declare function saveConfig(key: string, value: string, scope?: ConfigSco
 /**
  * Remove a single config key from the specified scope.
  *
- * This is the counterpart that makes "no deployment mode" workable. Running on
- * this machine is the absence of a configured apiUrl, so there has to be a way
- * to get back to that state; previously the only way to express the intent was
- * to set mode=local, and that key is gone.
+ * This is also how a retired key written by an older version is removed: a file
+ * carrying one is refused by every read, so refusing to unset it would leave an
+ * operator with a config every command rejects and no supported repair.
  *
  * Returns whether the key was actually present, so callers can distinguish
  * "removed" from "there was nothing to remove" instead of guessing.

package/dist/lib/feedback.d.ts

@@ -21,8 +21,13 @@ export interface FeedbackResult {
 export declare function getFeedbackDbPath(): string;
 export declare function saveFeedback(input: FeedbackInput): FeedbackResult;
 /**
- * True when this install is pointed at a Skills instance: the env var, its HASNA_-prefixed
- * alias, or the config file written by `skills setup --api-url` / `skills login`. The check
- * never throws - a broken config file means local mode, not a crash in `skills feedback`.
+ * True when this install talks to a Skills instance — i.e. a credential resolves
+ * on the shared fleet ladder (lib/fleet-credentials.ts).
+ *
+ * The check never throws: `skills feedback` must not crash because the ladder is
+ * half-configured. A configured authority with no credential is treated as
+ * api mode here on purpose — the operator meant to be hosted, so feedback goes
+ * to the forwardable JSONL file rather than opening a local database that the
+ * hosted install has no business creating.
  */
 export declare function isApiMode(env?: Record<string, string | undefined>): boolean;

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

@@ -0,0 +1,246 @@
+/**
+ * The one place this package decides WHICH Skills service it talks to and WITH
+ * WHICH credential.
+ *
+ * Everything here delegates to the shared client seam in `@hasna/contracts/client`
+ * (owner rulings 2026-09-04 — hasna/apps#1720, #1668, #1690, #1613, #1599). This
+ * package owns no second copy of the ladder, and no alias env name of its own.
+ *
+ * CREDENTIAL, resolved fresh on every call (contracts `resolveCredential`):
+ *
+ *   1. an explicit argument            — `--api-key`, `--profile`
+ *   2. a deliberate env pointer        — `HASNA_SKILLS_API_KEY_OVERRIDE`,
+ *                                        `HASNA_PROFILE`, `HASNA_SKILLS_API_KEY_REF`
+ *
+ *      `HASNA_SKILLS_API_KEY_REF` names a VAULT ITEM rather than a key, so it
+ *      resolves in two steps: the synchronous chain yields the pointer, and
+ *      `resolveSkillsApiKey()` (async) fetches the value through the secrets
+ *      SDK on each call. Never treat the pointer's own `apiKey` — the empty
+ *      string — as a credential; `resolveSkillsFleet` reports null for it.
+ *   3. the macOS Keychain              — generic-password `hasna.credentials.skills.api-key`,
+ *                                        account `HASNA_STATION`, else `hostname -s`, else `USER`
+ *   4. disk, read at call time         — `~/.hasna/skills/config/credentials`
+ *                                        (`HASNA_HOME` / `HASNA_CONFIG_HOME` relocate it; XDG never)
+ *   5. `HASNA_SKILLS_API_KEY` in the environment — a legitimate tier, below disk,
+ *                                        and carrying no deprecation notice
+ *
+ * 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).
+ *
+ * The unprefixed `SKILLS_API_URL` / `SKILLS_API_KEY` spellings are still
+ * accepted, silently, because the shared seam accepts `<APP>_API_URL` /
+ * `<APP>_API_KEY` as documented aliases one rung below the canonical
+ * `HASNA_SKILLS_*` names. They are documented in the README for one release and
+ * are not read anywhere else in this package. `SKILL_API_KEY` (singular) is
+ * gone: it shadowed nothing canonical and was never documented.
+ *
+ * THREE OUTCOMES, and no fourth:
+ *
+ *   - a credential resolves            → HOSTED. The authority is the configured
+ *                                        URL, else the fleet gateway. A credential
+ *                                        that cannot produce a usable key — a
+ *                                        deliberate selection contracts refuses, a
+ *                                        pointer whose vault item is missing, any
+ *                                        tier that yields a blank value — is a LOUD
+ *                                        failure, never a demotion to local.
+ *   - no credential, but a URL is configured
+ *                                      → LOUD failure. The caller exits non-zero
+ *                                        with one line naming what is missing.
+ *                                        There is no local fallback here: serving
+ *                                        local results while authentication is
+ *                                        unconfigured is a false green.
+ *   - neither a credential nor a URL   → LOCAL. Skills is an OSS tool with a
+ *                                        bundled corpus, so running on this
+ *                                        machine is a real mode — and it says so,
+ *                                        once, on stderr.
+ */
+import { type CredentialChainOptions, type CredentialTier, type KeychainTierOptions, type ResolvedCredential } from "@hasna/contracts/client";
+/** The app slug: the Keychain service, the `~/.hasna/<app>` folder, the gateway path. */
+export declare const SKILLS_APP = "skills";
+type Env = Record<string, string | undefined>;
+/** `HASNA_SKILLS_API_URL`, then the accepted `SKILLS_API_URL` alias. */
+export declare const SKILLS_API_URL_ENV_KEYS: readonly string[];
+/** `HASNA_SKILLS_API_KEY`, then the accepted `SKILLS_API_KEY` alias. */
+export declare const SKILLS_API_KEY_ENV_KEYS: readonly string[];
+/** The canonical spellings, for messages that have to name exactly one. */
+export declare const SKILLS_API_URL_ENV: string;
+export declare const SKILLS_API_KEY_ENV: string;
+export interface SkillsFleetOptions {
+    /** Tier-1 credential inputs and the Keychain-tier controls (a fake runner in tests). */
+    credentials?: CredentialChainOptions;
+}
+/** A hosted resolution: an authority to call and a credential to call it with. */
+export interface HostedSkillsFleet {
+    mode: "hosted";
+    /** Origin the CLI/SDK sends requests to. Never carries a trailing slash. */
+    apiOrigin: string;
+    /**
+     * The resolved key, or null when the credential is a vault POINTER
+     * (`HASNA_SKILLS_API_KEY_REF` / a `credential_ref` line) that only the async
+     * path can complete — see {@link apiKeyPointer} and {@link resolveSkillsApiKey}.
+     *
+     * It is NEVER the empty string: a blank key would produce
+     * `Authorization: Bearer ` on the wire, and — read as falsy by a caller
+     * looking for "is there a token" — a silent drop back to local data. Both
+     * are refused at resolution time instead.
+     *
+     * Never logged, never written anywhere but the header.
+     */
+    apiKey: string | null;
+    /**
+     * The unresolved vault pointer, when tier === "pointer"; null otherwise.
+     *
+     * `resolveCredential` returns a TRUTHY credential for the pointer tier whose
+     * `apiKey` is empty and whose `pointerVaultKey` names the vault item;
+     * fetching that item is a separate async step. Carrying the pointer (rather
+     * than its empty key) is what keeps the sending paths honest.
+     */
+    apiKeyPointer: ResolvedCredential | null;
+    /** WHERE the URL came from: an env key NAME, a Keychain reference, a path, or "default". */
+    apiUrlSource: string;
+    /** WHERE the key came from: an env key NAME, a Keychain reference, or a path. Never a value. */
+    apiKeySource: string;
+    apiKeyTier: CredentialTier;
+    /** Advisory from the shared seam (never secret), or null. */
+    warning: string | null;
+}
+/** Nothing is configured: this install runs on this machine. */
+export interface LocalSkillsFleet {
+    mode: "local";
+    apiOrigin: null;
+    apiKey: null;
+}
+export type SkillsFleet = HostedSkillsFleet | LocalSkillsFleet;
+/** Machine-readable reasons a hosted resolution was refused. */
+export type SkillsFleetErrorCode = "MISSING_API_CREDENTIAL" | "INVALID_API_URL";
+/**
+ * A configured install could not produce a usable hosted client.
+ *
+ * `code` is stable so JSON callers can branch on it, and distinguishes the two
+ * refusals that are NOT the same fault: an authority with no credential
+ * (MISSING_API_CREDENTIAL) versus an authority that is declared but unusable
+ * (INVALID_API_URL). MISSING_API_URL stays the code for "nothing configured at
+ * all" (see MissingSkillsFleetError), which is a third, non-error state for the
+ * commands that may run locally.
+ */
+export declare class SkillsFleetCredentialError extends Error {
+    readonly code: SkillsFleetErrorCode;
+    constructor(message: string, code?: SkillsFleetErrorCode);
+}
+/**
+ * Normalize a configured Skills authority to the origin the client dials.
+ *
+ * The Skills server serves its API under `/api/v1`, so the client composes
+ * `<origin>/api/v1/...` itself. An operator who pasted the full API base — the
+ * URL printed by every error message — must not end up with `/api/v1/api/v1`.
+ */
+export declare function normalizeSkillsApiOrigin(apiUrl: string): string;
+/** One configured authority: its value and the source that decided it. */
+export interface ConfiguredSkillsApiUrl {
+    value: string;
+    /** An env key NAME, a `keychain:<service>@<account>` reference, or an absolute path. */
+    source: string;
+}
+/**
+ * The authority an operator configured, in the shared seam's precedence order —
+ * environment, then the Keychain `api-url` item, then the credentials file.
+ *
+ * Returns null when nothing configures one, which is what lets the gateway
+ * default apply for a credentialled install and what keeps an install with no
+ * credential from naming a host at all.
+ */
+export declare function configuredSkillsApiUrl(env?: Env, keychain?: KeychainTierOptions): ConfiguredSkillsApiUrl | null;
+/** The credential file paths consulted, for a message that has to name them. */
+export declare function skillsCredentialFiles(env?: Env): string[];
+/**
+ * Where a credential should be written, and the only file this package writes.
+ *
+ * Throws when neither HOME nor HASNA_HOME anchors a root, because there is then
+ * no correct place to put a secret and guessing one is worse than refusing.
+ */
+export declare function skillsCredentialFilePath(env?: Env): string;
+/**
+ * Say — once per process, on stderr — that this install is running locally.
+ *
+ * Local mode is legitimate for Skills: the corpus ships in the package. It is
+ * still announced, because "no credential resolved" and "deliberately offline"
+ * look identical in the output otherwise, and the first one is usually a
+ * misconfiguration the operator wants to hear about.
+ */
+export declare function noticeLocalSkillsMode(write?: (line: string) => void): void;
+/** Test seam: forget that the local-mode line was printed. */
+export declare function resetLocalSkillsModeNotice(): void;
+/**
+ * Resolve the service this process should use, fresh.
+ *
+ * Never returns a hosted resolution without a credential, and never degrades a
+ * configured authority to local mode.
+ */
+export declare function resolveSkillsFleet(env?: Env, options?: SkillsFleetOptions): SkillsFleet;
+/**
+ * The usable API key for this process, completing a vault pointer if that is
+ * the tier that won.
+ *
+ * ASYNC because the pointer tier is: the value is fetched from the secrets
+ * vault at call time, so a rotated item is picked up without a restart. Every
+ * path that is about to SEND the key resolves it here; the synchronous
+ * `resolveSkillsFleet` is for reporting (which tier, which source, which
+ * origin), and its `apiKey` is deliberately null for a pointer.
+ *
+ * Returns null only in local mode. Throws {@link SkillsFleetCredentialError}
+ * when a credential is configured and cannot be produced — never a fallback.
+ */
+export declare function resolveSkillsApiKey(env?: Env, options?: SkillsFleetOptions): Promise<string | null>;
+/** The usable API key, or throw naming what is missing. Use on every send path. */
+export declare function requireSkillsApiKey(action?: string, env?: Env, options?: SkillsFleetOptions): Promise<string>;
+/**
+ * The credential for a surface that reports refusals as data (an MCP tool, a
+ * `--json` command) rather than as an exception.
+ *
+ * `reason` is the ladder's own message when an authority is configured and no
+ * key resolved — a refusal carried as a value, NOT a fallback: the caller must
+ * still refuse. It is null only when nothing at all is configured, which is the
+ * ordinary "not signed in" case.
+ */
+export declare function skillsCredentialOrReason(env?: Env, options?: SkillsFleetOptions): Promise<{
+    apiKey: string;
+    reason: null;
+} | {
+    apiKey: null;
+    reason: string | null;
+}>;
+/**
+ * The authority alone, for a flow that is ACQUIRING a credential.
+ *
+ * `skills auth login` cannot require a credential — obtaining one is the point —
+ * so it resolves the AUTHORITY on its own: the configured URL (environment,
+ * Keychain, credentials file), else the authority a resolved credential implies.
+ * With neither, this returns null and the caller fails loudly: R1 still holds,
+ * an install that named no service does not get to send an email address to one.
+ */
+export declare function resolveSkillsApiOrigin(env?: Env, options?: SkillsFleetOptions): {
+    origin: string;
+    source: string;
+} | null;
+/** The authority for an auth flow, or throw naming what is missing. */
+export declare function requireSkillsApiOrigin(action?: string, env?: Env, options?: SkillsFleetOptions): string;
+/**
+ * The hosted resolution, or throw. Use on every auth and write path.
+ *
+ * `action` names the caller so the message says what was refused.
+ */
+export declare function requireSkillsFleet(action?: string, env?: Env, options?: SkillsFleetOptions): HostedSkillsFleet;
+/**
+ * Nothing at all is configured and the caller needed a service.
+ *
+ * The message names the environment variable, the Keychain item, the credential
+ * file and the command — and deliberately contains no URL, so an "error" can
+ * never hand a caller an endpoint it refused to resolve.
+ */
+export declare class MissingSkillsFleetError extends Error {
+    readonly code = "MISSING_API_URL";
+    constructor(action?: string);
+}
+export {};

package/dist/lib/portable-skills-files.d.ts

@@ -11,6 +11,15 @@ export declare function defaultProvenance(sourceCommit?: string): PortableSkillP
 export declare function normalizePortableSkillName(name: string): string;
 export declare function readPortableSkillManifest(skillPath: string, fallbackName?: string): PortableSkillManifest;
 export declare function parseSkillKind(value: string | undefined): SkillKind | undefined;
+/**
+ * The version a skill EXPLICITLY declares, or undefined when none of the sources do:
+ * skill.json first, then the SKILL.md frontmatter, then package.json.
+ *
+ * Distinct from `readPortableSkillManifest().version`, which falls back to
+ * PORTABLE_SKILL_DEFAULT_VERSION: callers that must not invent a version (publishing,
+ * version pinning) use this and refuse when it is undefined.
+ */
+export declare function readDeclaredSkillVersion(skillPath: string): string | undefined;
 export declare function createInstructionManifest(name: string, options: {
     description: string;
 }): PortableSkillManifest;

package/dist/lib/portable-skills.d.ts

@@ -1,8 +1,8 @@
 import type { SkillKind, SkillMeta } from "./registry-types.js";
 import { type SkillValidationResult } from "./skill-validation.js";
-import { normalizePortableSkillName, readPortableSkillManifest } from "./portable-skills-files.js";
+import { normalizePortableSkillName, readDeclaredSkillVersion, readPortableSkillManifest } from "./portable-skills-files.js";
 import type { BulkPortPortableSkillOptions, BulkPortResult, PortableSkillOptions, PortableSkillRunOptions, PortableSkillRunResult, PortableSkillSummary, PortableSkillWriteResult, PortPortableSkillOptions, ScaffoldPortableSkillOptions } from "./portable-skills-types.js";
-export { normalizePortableSkillName, readPortableSkillManifest, };
+export { normalizePortableSkillName, readDeclaredSkillVersion, readPortableSkillManifest, };
 export * from "./portable-skills-types.js";
 /**
  * Resolve the corpus: the directory holding one folder per installed skill.