@hasna/skills 0.3.0 → 0.5.0

package/dist/lib/agent-sync.d.ts

@@ -29,9 +29,9 @@ export declare const SYNC_AGENTS: readonly SyncAgent[];
  */
 export declare const SKILLS_SOURCE_ENV = "SKILLS_SOURCE";
 /**
- * Ownership marker written beside every SKILL.md this tool syncs. Its presence is how a
- * re-sync tells "a skill I wrote, safe to update" from "a skill the user hand-authored,
- * do not touch". A hidden sidecar rather than a frontmatter field so the SKILL.md the
+ * Ownership marker written beside every SKILL.md this tool syncs. Its exact managedBy
+ * value tells a re-sync which directories this tool owns; a foreign or malformed
+ * marker grants no authority. A hidden sidecar rather than a frontmatter field so the SKILL.md the
  * agent loads stays exactly the adapted document and nothing else.
  */
 export declare const SYNC_MARKER_FILE = ".hasna-skills.json";
@@ -42,6 +42,10 @@ export interface SyncMarker {
     source: string;
     syncedAt: string;
 }
+/** Internal shared ownership predicate; not exported by the public package entrypoint. */
+export declare function isSkillsOwnershipMarker(marker: unknown): marker is Record<string, unknown>;
+/** Read only a regular ownership sidecar. */
+export declare function hasSkillsOwnershipMarker(dir: string): boolean;
 export declare function isSyncAgent(value: string): value is SyncAgent;
 export declare function resolveSyncAgents(arg?: string): SyncAgent[];
 /** The global skills directory for an agent, honouring a test-supplied home. */
@@ -142,12 +146,12 @@ export interface WriteManagedAgentSkillParams {
 /**
  * Write one skill into one agent's global folder, non-clobbering.
  *
- * A directory this tool has written before carries the marker file and is replaced with
+ * A directory this tool has written before carries our exact ownership marker and is replaced with
  * an exact mirror — except that a managed home holding full content is never silently
  * replaced with an executable pointer stub (that would be data loss; it is refused
- * unless `force` is passed). A directory with a SKILL.md but no marker is the user's
- * own skill and is skipped unless `force` explicitly adopts it. Any other pre-existing
- * unmarked directory is always left untouched. A fresh directory is created.
+ * unless `force` is passed). A directory with a SKILL.md but no valid Skills marker is
+ * skipped unless `force` explicitly adopts it. Any other pre-existing unmanaged
+ * directory is always left untouched. A fresh directory is created.
  */
 export declare function writeManagedAgentSkill(params: WriteManagedAgentSkillParams): AgentSyncAction;
 export interface ManagedDirWriteResult {
@@ -173,6 +177,7 @@ export interface ManagedDirWriteOptions {
 export declare function writeManagedSkillDir(dir: string, skillMd: string, options: ManagedDirWriteOptions): ManagedDirWriteResult;
 /**
  * Remove a skill this tool synced from an agent folder. Refuses to delete a directory it
- * did not write (no marker), so it can never remove a user's hand-authored skill.
+ * did not write (no valid Skills ownership marker). Foreign or malformed markers
+ * grant no deletion authority, and removal has no force override.
  */
 export declare function removeManagedAgentSkill(skill: string, agent: SyncAgent, homeDir?: string): boolean;

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

@@ -5,9 +5,10 @@
  * thin reading of `@hasna/contracts/client`. It exists only so the two failure
  * MODES stay named:
  *
- *   - Read paths fail closed: `resolveApiUrl()` returns `undefined` when nothing
- *     is configured, and the caller keeps working against the bundled local
- *     registry.
+ *   - Read paths fail closed: `resolveApiUrl()` returns `undefined` only under
+ *     the explicit local opt-in (`HASNA_SKILLS_LOCAL=1`, alias `SKILLS_LOCAL=1`),
+ *     and the caller keeps working against the bundled local registry. Without
+ *     the opt-in, an install with nothing configured is a refusal, not a URL.
  *   - Auth and write paths fail loudly: `requireApiUrl()` throws an error naming
  *     the missing configuration.
  *

package/dist/lib/app-home.d.ts

@@ -17,7 +17,6 @@
  * Nothing moves on disk in this phase — the package just resolves the new
  * paths.
  */
-export type PathKind = "config" | "data" | "state" | "cache";
 export interface PathsResolverOptions {
     app: string;
     internal?: boolean;

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

@@ -87,7 +87,7 @@ export declare function getAuthConfigReadOnly(env?: Env, options?: SkillsFleetOp
  * 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;
+export declare function saveAuthConfig(config: StoredAuthConfig, env?: Env, authenticatedOrigin?: string): 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/client-types.d.ts

@@ -0,0 +1,75 @@
+/**
+ * The @hasna/contracts client types that cross this package's published
+ * boundary, spelled locally.
+ *
+ * WHY THIS FILE EXISTS. `bun build --target bun` inlines @hasna/contracts into
+ * every shipped bundle, so the runtime never needs it installed alongside
+ * @hasna/skills and it is correctly a build-time devDependency. `tsc
+ * --emitDeclarationOnly` inlines nothing: the moment a PUBLIC declaration names
+ * a type from `@hasna/contracts/client`, the published `.d.ts` imports it, and
+ * a consumer who installed only this package's declared runtime dependencies
+ * fails type-checking (7 x TS2307 before #1782 fixed the same shape in
+ * @hasna/secrets).
+ *
+ * This file is NOT the vendored resolver returning: it has no imports, no
+ * runtime statement, no tier, no Keychain read, no URL ladder — only the
+ * shapes, copied from the @hasna/contracts/@1.0.2 declarations. Its sibling
+ * `client-types.test.ts` asserts each one is mutually assignable with the real
+ * declaration, in the direction it actually crosses, so a drifted shape fails
+ * `tsc` in the same build step that emits the declarations it protects.
+ *
+ * `src/lib/fleet-credentials.ts` keeps importing the resolver and its VALUE
+ * exports from @hasna/contracts/client (inlined at runtime); only the types it
+ * re-exports or names in its own public signatures come from here.
+ *
+ * Do not add an import. Do not add a value. This file must stay a leaf.
+ */
+/** Which link of the chain supplied the credential. */
+export type CredentialTier = "argument" | "override" | "pointer" | "profile" | "keychain" | "disk" | "env";
+export interface ResolvedCredential {
+    /** The secret. Property access and destructuring work; it is never enumerated or serialized. */
+    readonly apiKey: string;
+    readonly tier: CredentialTier;
+    /** Where it came from: an env key NAME, an absolute file path, or a Keychain item reference. Never a value. */
+    readonly source: string;
+    /** True for tiers an operator sets on purpose. These never fall through. */
+    readonly deliberate: boolean;
+    /** When tier === "pointer", the vault ITEM KEY to resolve at request time. Never a credential value. */
+    readonly pointerVaultKey?: string;
+    /** The disk paths consulted before this credential was chosen. */
+    readonly diskCandidates: readonly string[];
+    /** Human-readable advisory. Never contains key material. */
+    readonly warning: string | null;
+}
+/** The captured outcome of one `security` invocation. `stdout` IS the secret; it is never logged. */
+export interface KeychainCommandResult {
+    /** Exit status; null when the tool could not be started or was killed. */
+    status: number | null;
+    stdout: string;
+    stderr: string;
+}
+/** Runs `/usr/bin/security` with the given argv — no shell. Injected by tests. */
+export type KeychainCommandRunner = (argv: readonly string[]) => KeychainCommandResult;
+/** Tier 3 controls. Every field is optional; production callers pass nothing. */
+export interface KeychainTierOptions {
+    /**
+     * Whether the Keychain is consulted for a caller-built env object. The tier
+     * is AMBIENT: by default it runs only for the live `process.env`. Injecting
+     * `run` implies `true`.
+     */
+    enabled?: boolean;
+    /** Defaults to `process.platform`; the tier exists only on `"darwin"`. */
+    platform?: string;
+    /** The machine's host name, used as the account when `HASNA_STATION` is unset. */
+    hostname?: () => string;
+    /** The `security` runner. Defaults to spawning `/usr/bin/security` by argv. */
+    run?: KeychainCommandRunner;
+}
+export interface CredentialChainOptions {
+    /** Tier 1: an explicit key, e.g. from `--api-key`. */
+    apiKey?: string;
+    /** Tier 1: an explicit profile name, e.g. from `--profile`. Beats `HASNA_PROFILE`. */
+    profile?: string;
+    /** Tier 3: Keychain controls — a fake `security` runner in tests, an opt-out on CI. */
+    keychain?: KeychainTierOptions;
+}

package/dist/lib/credential-state.d.ts

@@ -0,0 +1,12 @@
+export interface CredentialState {
+    /** `misconfigured` is the ladder's refusal carried as data; `error` says why. */
+    mode: "hosted" | "local" | "misconfigured";
+    apiUrl: string | null;
+    apiUrlSource: string | null;
+    apiKeySource: string | null;
+    apiKeyTier: string | null;
+    credentialsFile: string | null;
+    credentialsFileMode: string | null;
+    error: string | null;
+}
+export declare function describeCredentialState(): CredentialState;

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

@@ -36,8 +36,14 @@
  * 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:
+ * THIRD: the local run is opt-in only (owner ruling 2026-09-04, hasna/apps#1720;
+ * class-patch order 2026-09-06). `HASNA_SKILLS_LOCAL=1` (alias `SKILLS_LOCAL=1`)
+ * selects the on-machine run when the ENVIRONMENT configures no authority; it is
+ * answered before the resolver runs, so opting in never reads the Keychain or
+ * the credentials file. A configured environment always outranks it. The
+ * outcomes, and no fourth:
  *
+ *   - the local opt-in selected        → LOCAL, announced once on stderr.
  *   - a credential resolves            → HOSTED. The authority is the configured
  *                                        URL, else the fleet gateway. A credential
  *                                        that cannot produce a usable key — a
@@ -51,14 +57,18 @@
  *                                        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.
+ *   - neither a credential nor a URL, and no opt-in
+ *                                      → LOUD failure, exit non-zero, no SQLite,
+ *                                        no *-local-fallback event. Running on
+ *                                        this machine is a deliberate choice now,
+ *                                        not the silence that follows a missing
+ *                                        credential.
  */
-import { type CredentialChainOptions, type CredentialTier, type KeychainTierOptions, type ResolvedCredential } from "@hasna/contracts/client";
+import type { CredentialChainOptions, CredentialTier, KeychainTierOptions, ResolvedCredential } from "./client-types.js";
 /** The app slug: the Keychain service, the `~/.hasna/<app>` folder, the gateway path. */
 export declare const SKILLS_APP = "skills";
+/** The deliberate unhosted opt-in env names. Re-exported for the surfaces that have to name them. */
+export { SKILLS_LOCAL_OPT_IN_ENV_KEYS, isSkillsLocalOptIn, selectsSkillsLocalMode } from "./local-opt-in.js";
 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[];
@@ -114,7 +124,7 @@ export interface LocalSkillsFleet {
 }
 export type SkillsFleet = HostedSkillsFleet | LocalSkillsFleet;
 /** Machine-readable reasons a hosted resolution was refused. */
-export type SkillsFleetErrorCode = "MISSING_API_CREDENTIAL" | "INVALID_API_URL";
+export type SkillsFleetErrorCode = "MISSING_API_CREDENTIAL" | "INVALID_API_URL" | "INSTANCE_CREDENTIAL_MISMATCH";
 /**
  * A configured install could not produce a usable hosted client.
  *
@@ -129,6 +139,14 @@ export declare class SkillsFleetCredentialError extends Error {
     readonly code: SkillsFleetErrorCode;
     constructor(message: string, code?: SkillsFleetErrorCode);
 }
+/**
+ * True for this package's own refusal, across bundle boundaries.
+ *
+ * Exported for the surfaces that turn the refusal into data (an MCP tool's
+ * `AUTH_REQUIRED` result, a CLI handler's one-line stderr exit) so they match
+ * on the error's NAME rather than on a class identity a bundle may not share.
+ */
+export declare function isSkillsFleetCredentialError(error: unknown): error is SkillsFleetCredentialError;
 /**
  * Normalize a configured Skills authority to the origin the client dials.
  *
@@ -151,7 +169,7 @@ export interface ConfiguredSkillsApiUrl {
  * 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;
+export declare function configuredSkillsApiUrl(env?: Env, keychain?: KeychainTierOptions, profile?: string): ConfiguredSkillsApiUrl | null;
 /** The credential file paths consulted, for a message that has to name them. */
 export declare function skillsCredentialFiles(env?: Env): string[];
 /**
@@ -164,10 +182,12 @@ 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.
+ * Local mode is legitimate for Skills: the corpus ships in the package. It is a
+ * deliberate choice now, though: it is reachable only through the explicit
+ * opt-in (`HASNA_SKILLS_LOCAL=1`), and 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. */
@@ -193,22 +213,29 @@ export declare function resolveSkillsFleet(env?: Env, options?: SkillsFleetOptio
  * when a credential is configured and cannot be produced — never a fallback.
  */
 export declare function resolveSkillsApiKey(env?: Env, options?: SkillsFleetOptions): Promise<string | null>;
+/** Resolve the URL and credential once, including any asynchronous vault lookup. */
+export declare function resolveSkillsConnection(env?: Env, options?: SkillsFleetOptions): Promise<(HostedSkillsFleet & {
+    apiKey: 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.
+ * `reason` is the ladder's own message when a hosted resolution is refused — an
+ * authority with no key, or an unconfigured install without the local opt-in
+ * (fail-closed ruling) — a refusal carried as a value, NOT a fallback: the
+ * caller must still refuse. It is null only when the explicit local opt-in
+ * selected the on-machine run, the ordinary "not signed in" case.
  */
 export declare function skillsCredentialOrReason(env?: Env, options?: SkillsFleetOptions): Promise<{
     apiKey: string;
+    apiOrigin: string;
     reason: null;
 } | {
     apiKey: null;
+    apiOrigin: null;
     reason: string | null;
 }>;
 /**
@@ -219,6 +246,12 @@ export declare function skillsCredentialOrReason(env?: Env, options?: SkillsFlee
  * 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.
+ *
+ * The fail-closed refusal an unconfigured install now raises on every DATA
+ * surface is swallowed here and reported as plain "no authority": for a flow
+ * whose purpose is to acquire a credential, "nothing is configured" and "local
+ * mode is opted in" have the same two-step way out (configure an origin, then
+ * sign in).
  */
 export declare function resolveSkillsApiOrigin(env?: Env, options?: SkillsFleetOptions): {
     origin: string;
@@ -243,4 +276,3 @@ export declare class MissingSkillsFleetError extends Error {
     readonly code = "MISSING_API_URL";
     constructor(action?: string);
 }
-export {};

package/dist/lib/home-adoption.d.ts

@@ -30,6 +30,8 @@ export interface AdoptionScan {
 }
 export interface AdoptionOptions extends PortableSkillOptions {
     agents?: SyncAgent[];
+    /** Optional selected home/corpus names; omitted means all names. */
+    names?: string[];
     /** Write markers and the conflicts ledger. Without it, scan only. */
     apply?: boolean;
 }

package/dist/lib/home-census.d.ts

@@ -23,4 +23,6 @@ export interface DriftCensus {
     managed: number;
     clean: boolean;
 }
-export declare function censusHomeDrift(options?: AdoptionOptions): DriftCensus;
+export declare function censusHomeDrift(options?: AdoptionOptions & {
+    names?: string[];
+}): DriftCensus;

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

@@ -0,0 +1,13 @@
+export declare const SKILLS_BOUND_API_URL = "HASNA_SKILLS_BOUND_API_URL";
+type Env = Record<string, string | undefined>;
+/** Match the shared resolver's profile syntax before using its path helper. */
+export declare function selectedSkillsProfile(env: Env, explicit?: string): string | null;
+export declare function skillsProfileCredentialFiles(env: Env, explicit?: string): string[];
+/** Fence the released credential reader and this package's routing reads together. */
+export declare function captureSkillsCredentialFiles(files: string[]): () => void;
+/** Read only known non-secret routing fields, never export an API key or an arbitrary field. */
+export declare function readSkillsInstanceMetadata(file: string): {
+    apiUrl?: string;
+    binding?: string;
+};
+export {};

package/dist/lib/local-opt-in.d.ts

@@ -0,0 +1,24 @@
+/** The deliberate unhosted opt-in, canonical name first. */
+export declare const SKILLS_LOCAL_OPT_IN_ENV_KEYS: readonly ["HASNA_SKILLS_LOCAL", "SKILLS_LOCAL"];
+export type SkillsLocalOptInEnv = Record<string, string | undefined>;
+/** True when the operator deliberately asked for the unhosted on-machine run. */
+export declare function isSkillsLocalOptIn(env?: SkillsLocalOptInEnv): boolean;
+/** Every env name that can configure a Skills authority or credential, resolver-derived. */
+export declare function skillsAuthorityEnvKeys(): string[];
+/**
+ * Does the ENVIRONMENT itself configure a Skills authority or credential?
+ *
+ * Deliberately narrower than "does a credential resolve": answering it must not
+ * touch the Keychain or the filesystem, because doing so would defeat the
+ * isolation the opt-in short-circuit exists to provide. It reads the env
+ * dictionary and nothing else.
+ *
+ * A DECLARED-BUT-BLANK variable counts as absent HERE — a blank has always been
+ * this package's spelling for "not configured", and helpers in the wild blank
+ * rather than delete. It is NOT absent once we do go hosted: the resolver
+ * refuses a blank loudly rather than falling through to another identity, which
+ * is the behaviour that matters at that point.
+ */
+export declare function hasSkillsEnvAuthorityIntent(env?: SkillsLocalOptInEnv): boolean;
+/** True when this environment should be served by the on-box local run. */
+export declare function selectsSkillsLocalMode(env?: SkillsLocalOptInEnv): boolean;

package/dist/lib/mcp-contracts.d.ts

@@ -9,6 +9,10 @@ export interface JsonSchemaObject {
     default?: unknown;
     format?: string;
     minimum?: number;
+    maximum?: number;
+    pattern?: string;
+    maxItems?: number;
+    maxLength?: number;
     items?: JsonSchemaObject;
     properties?: Record<string, JsonSchemaObject>;
     required?: string[];

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

@@ -9,7 +9,11 @@ export declare function defaultRuntimeContract(entrypoint?: string): PortableSki
 /** Provenance defaults; content_hash is filled at write time over the bundle. */
 export declare function defaultProvenance(sourceCommit?: string): PortableSkillProvenance;
 export declare function normalizePortableSkillName(name: string): string;
+/** New local identities use hyphens; legacy lookups and command names keep their grammar. */
+export declare function normalizeNewPortableSkillName(name: string): string;
 export declare function readPortableSkillManifest(skillPath: string, fallbackName?: string): PortableSkillManifest;
+/** Import needs the original spelling before the legacy reader discards case boundaries. */
+export declare function readPortableSkillManifestForImport(skillPath: 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:
@@ -22,10 +26,14 @@ export declare function parseSkillKind(value: string | undefined): SkillKind | u
 export declare function readDeclaredSkillVersion(skillPath: string): string | undefined;
 export declare function createInstructionManifest(name: string, options: {
     description: string;
+    category?: string;
+    tags?: string[];
 }): PortableSkillManifest;
 export declare function writeInstructionSkillTemplate(skillPath: string, manifest: PortableSkillManifest): void;
 export declare function createPortableManifest(name: string, options: {
     description: string;
+    category?: string;
+    tags?: string[];
 }): PortableSkillManifest;
 export declare function writePortableSkillTemplate(skillPath: string, manifest: PortableSkillManifest): void;
 /**
@@ -42,8 +50,8 @@ export declare function ensurePortableSkillFiles(skillPath: string, manifest: Po
 /**
  * Instruction (prose) skills are consumed by agent renderers/MCP docs, not run
  * locally, so `port` must never fabricate executable stubs (package.json, bin,
- * src/index.ts, tsconfig.json, AGENTS.md). It keeps the copied SKILL.md verbatim
- * and writes a minimal skill.json declaring `kind: "instruction"`.
+ * src/index.ts, tsconfig.json, AGENTS.md). Apart from aligning declared names
+ * after an import rename, it preserves the copied prose and metadata.
  */
 export declare function ensureInstructionSkillFiles(skillPath: string, manifest: PortableSkillManifest): PortableSkillManifest;
 export declare function copySkillDirectory(source: string, destination: string): void;

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

@@ -98,6 +98,8 @@ export interface PortableSkillOptions {
 }
 export interface ScaffoldPortableSkillOptions extends PortableSkillOptions {
     description?: string;
+    category?: string;
+    tags?: string[];
     overwrite?: boolean;
     kind?: SkillKind;
 }

package/dist/lib/read-access.d.ts

@@ -0,0 +1,83 @@
+/**
+ * The gate every DATA surface runs before it answers from the bundled corpus,
+ * and the one registry those surfaces show.
+ *
+ * `skills list` has resolved through the fleet ladder since the fail-closed
+ * ruling (owner directive 2026-09-04, hasna/apps#1720): with no credential, no
+ * authority and no `HASNA_SKILLS_LOCAL=1` opt-in it exits 1 naming the refusal,
+ * opens nothing and serves nothing. `skills info` / `docs` / `requires`, the
+ * bare non-TTY listing and the MCP discovery tools (`list_skills`,
+ * `search_skills`, `get_skill_info`, `get_skill_docs`, `list_categories`,
+ * `list_tags`, `get_requirements`) did NOT — they read `loadRegistry()` and
+ * answered from the bundled catalog plus `~/.hasna/skills/installed` at exit 0
+ * with no notice, on the very machine `skills list` had just refused (#1720
+ * validation, round 1). Two surfaces that disagree about whether an install is
+ * configured is the false green the ruling removed, so they now share this one
+ * gate with the browsing commands.
+ *
+ *   - refused (nothing configured, no opt-in; an authority with no key; a
+ *     deliberate selection that cannot be honoured) → `SkillsFleetCredentialError`
+ *     from the shared ladder, carried to the caller unchanged: the CLI prints
+ *     its one line and exits 1, an MCP tool answers `AUTH_REQUIRED`.
+ *   - the explicit local opt-in → `{ mode: "local" }`; the ladder has announced
+ *     local mode once on stderr, and the caller serves the on-machine answer.
+ *   - a credential resolves → `{ mode: "hosted", apiOrigin }`. The key is
+ *     deliberately NOT returned here: a surface that only reads local data has
+ *     no business holding it, and the surfaces that send it resolve it again
+ *     at request time (`remoteRequestHeaders`, per call, completing a vault
+ *     pointer if that is the tier).
+ *
+ * Resolved fresh on every call — the resolver contract — so a credential that
+ * appears, rotates or disappears mid-process is honoured by the next call.
+ */
+import { type SkillsFleetOptions } from "./fleet-credentials.js";
+import { type SkillMeta } from "./registry.js";
+type Env = Record<string, string | undefined>;
+/** Where a read surface stands, once the ladder has let it through. Never carries a key. */
+export type SkillsReadAccess = {
+    mode: "hosted";
+    apiOrigin: string;
+} | {
+    mode: "local";
+};
+/**
+ * Run the fail-closed routing preamble for a read surface.
+ *
+ * Throws {@link SkillsFleetCredentialError} when the ladder refuses; the
+ * caller must let that refusal out (as a non-zero exit or a structured error),
+ * never swallow it into a local answer.
+ */
+export declare function requireSkillsReadAccess(env?: Env, options?: SkillsFleetOptions): Promise<SkillsReadAccess>;
+/**
+ * The registry a browsing surface should show — the CLI's `list` / `search` /
+ * `categories` / `tags` and the MCP discovery tools, from ONE implementation.
+ *
+ * The default read path is folder UNION cloud: whenever the install is pointed
+ * at a hosted instance (a resolved credential, and HASNA_SKILLS_API_URL for your
+ * own instance) the authenticated remote registry joins the local listing even
+ * without `--remote`. The explicit local opt-in keeps today's exact local
+ * output; an unconfigured or auth-missing install is a refusal, thrown from the
+ * shared ladder (fail-closed R1 — see mergeRemoteRegistry()).
+ *
+ * `--remote` used to REPLACE the local registry: `skills list --remote` returned exactly
+ * what the instance served and nothing else, so the bundled corpus and every skill the
+ * operator had written locally disappeared from the listing the moment they pointed the
+ * CLI at their own server. It now MERGES, under the precedence documented in
+ * src/lib/registry-merge.ts: custom > extension > local > remote > official, "whichever
+ * copy this machine would actually use wins the listing".
+ *
+ * The profile (`all` vs the curated basic set) applies to the local half only. The
+ * instance's skills are never filtered by it: the basic profile is a hand-written list of
+ * ten bundled names, so applying it to remote entries would drop every published skill
+ * from `skills list --remote` - the same disappearance this change exists to fix.
+ *
+ * A remote failure is still fatal. An explicit `--remote` request (and a configured,
+ * authenticated default read) that fails surfaces a clear error, and silently returning
+ * the local half of a merge the user asked to include the remote half in would report
+ * success for a listing that is missing entries.
+ */
+export declare function getBrowseRegistry(options?: {
+    all?: boolean;
+    remote?: boolean;
+}): Promise<SkillMeta[]>;
+export {};

package/dist/lib/remote-account.d.ts

@@ -0,0 +1,42 @@
+import type { RemoteInputFileDescriptor } from "./remote-files.js";
+/** Optional account APIs supplied by a configured Skills server. No local prices or provider policy. */
+export interface RemoteRunQuote {
+    skill: string;
+    pricing: {
+        costCents: number;
+        formattedCost: string;
+        [key: string]: unknown;
+    };
+    [key: string]: unknown;
+}
+export interface RemoteRunApproval {
+    /** Preferred public spelling: maximum integer credits approved by the caller. */
+    maxCredits?: number;
+    /** Maximum integer credits approved by the caller (legacy wire spelling). */
+    maxCostCents?: number;
+    idempotencyKey?: string;
+    inputFiles?: RemoteInputFileDescriptor[];
+}
+export interface RemoteCreditPack {
+    id: string;
+    credits: number;
+    expiresInDays?: number;
+}
+export declare class RemoteCreditApprovalError extends Error {
+    readonly requiredCredits: number;
+    readonly maximumCredits: number;
+    readonly code = "CREDIT_APPROVAL_REQUIRED";
+    constructor(requiredCredits: number, maximumCredits: number);
+}
+export declare function creditCount(value: unknown): number;
+export declare function parseRemoteRunQuote(value: unknown): RemoteRunQuote;
+export declare function parseRemoteCreditPacks(value: unknown): RemoteCreditPack[];
+export declare function parseRemoteBillingStatus(value: unknown): {
+    hasPaymentMethod?: boolean | undefined;
+    plan?: string | undefined;
+    creditBalance: number;
+    formattedCreditBalance: string;
+};
+export declare function parseRemoteCheckout(value: unknown): {
+    url: string;
+};

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

@@ -0,0 +1,46 @@
+import { type RemoteWorkspaceMembersOptions } from "./remote-workspace.js";
+import { type SetRemoteWorkspaceMemberRole, type RemoveRemoteWorkspaceMember } from "./remote-workspace.js";
+import { type UpdateRemoteProfile, type UpdateRemoteWorkspace } from "./remote-profile.js";
+export declare class HostedApiError extends Error {
+    readonly status?: number;
+    readonly code?: string;
+    readonly detail?: string;
+    readonly endpoint?: string;
+    readonly apiUrl?: string;
+    constructor(message: string, options?: {
+        status?: number;
+        code?: string;
+        detail?: string;
+        endpoint?: string;
+        apiUrl?: string;
+    });
+}
+/** Passwordless auth transport for an explicitly selected instance. It never writes credentials. */
+export declare class RemoteSkillsAuthClient {
+    readonly apiOrigin: string;
+    constructor(apiUrl: string);
+    requestCode(email: string): Promise<any>;
+    verifyCode(email: string, code: string): Promise<any>;
+    startDevice(): Promise<any>;
+    pollDevice(deviceCode: string): Promise<any>;
+    private sessionClient;
+    createApiKey(email: string, code: string, name: string, scopes?: string[]): Promise<{
+        [field: string]: unknown;
+        key: string;
+    }>;
+    listApiKeys(email: string, code: string): Promise<Record<string, unknown>[]>;
+    revokeApiKey(email: string, code: string, keyId: string): Promise<Record<string, unknown>>;
+    /** Reauthentication is ephemeral: it never replaces a saved key or profile. */
+    updateProfile(email: string, code: string, input: UpdateRemoteProfile): Promise<{
+        user: import("./remote-profile.js").RemoteCustomerProfile;
+    }>;
+    updateCurrentWorkspace(email: string, code: string, input: UpdateRemoteWorkspace): Promise<{
+        organization: import("./remote-profile.js").RemoteCurrentWorkspace;
+    }>;
+    /** Fresh owner/admin session; no saved credential or profile is replaced. */
+    listWorkspaceMembers(email: string, code: string, options?: RemoteWorkspaceMembersOptions): Promise<import("./remote-workspace.js").RemoteWorkspaceMembersPage>;
+    setWorkspaceMemberRole(email: string, code: string, membershipId: string, input: SetRemoteWorkspaceMemberRole): Promise<import("./remote-workspace.js").RemoteWorkspaceMemberRoleResult>;
+    removeWorkspaceMember(email: string, code: string, membershipId: string, input: RemoveRemoteWorkspaceMember): Promise<import("./remote-workspace.js").RemoteWorkspaceMemberRemovalResult>;
+    /** Common auth transport used by CLI login, preserving the selected instance through awaits. */
+    request(path: string, options?: RequestInit): Promise<any>;
+}