@hasna/skills 0.4.0 → 0.5.1

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/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[];
@@ -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.
  *
@@ -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. */
@@ -203,10 +223,11 @@ export declare function requireSkillsApiKey(action?: string, env?: Env, options?
  * 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;
@@ -225,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;
@@ -249,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/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/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:
@@ -46,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/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-auth.d.ts

@@ -1,3 +1,7 @@
+import { type RemoteWorkspaceContext, type RemoteWorkspaceSession, type RemoteAccountWorkspaceDiscovery } from "./remote-workspace-selection.js";
+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;
@@ -21,12 +25,28 @@ export declare class RemoteSkillsAuthClient {
     startDevice(): Promise<any>;
     pollDevice(deviceCode: string): Promise<any>;
     private sessionClient;
-    createApiKey(email: string, code: string, name: string, scopes?: string[]): Promise<{
+    /** Discover memberships with fresh sign-in. No key or session is saved. */
+    listAccountWorkspaces(email: string, code: string, expectedUserId?: string): Promise<RemoteAccountWorkspaceDiscovery>;
+    /** Contains a secret session token. Selection never creates or stores an API key. */
+    switchWorkspace(email: string, code: string, context: RemoteWorkspaceContext): Promise<RemoteWorkspaceSession>;
+    private workspaceLogin;
+    createApiKey(email: string, code: string, name: string, scopes?: string[], context?: RemoteWorkspaceContext): 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>>;
+    listApiKeys(email: string, code: string, context?: RemoteWorkspaceContext): Promise<Record<string, unknown>[]>;
+    revokeApiKey(email: string, code: string, keyId: string, context?: RemoteWorkspaceContext): Promise<Record<string, unknown>>;
+    /** Reauthentication is ephemeral: it never replaces a saved key or profile. */
+    updateProfile(email: string, code: string, input: UpdateRemoteProfile, context?: RemoteWorkspaceContext): Promise<{
+        user: import("./remote-profile.js").RemoteCustomerProfile;
+    }>;
+    updateCurrentWorkspace(email: string, code: string, input: UpdateRemoteWorkspace, context?: RemoteWorkspaceContext): Promise<{
+        organization: import("./remote-profile.js").RemoteCurrentWorkspace;
+    }>;
+    /** Fresh owner/admin session; explicit context survives default-workspace OTP selection. */
+    listWorkspaceMembers(email: string, code: string, options?: RemoteWorkspaceMembersOptions, context?: RemoteWorkspaceContext): Promise<import("./remote-workspace.js").RemoteWorkspaceMembersPage>;
+    setWorkspaceMemberRole(email: string, code: string, membershipId: string, input: SetRemoteWorkspaceMemberRole, context?: RemoteWorkspaceContext): Promise<import("./remote-workspace.js").RemoteWorkspaceMemberRoleResult>;
+    removeWorkspaceMember(email: string, code: string, membershipId: string, input: RemoveRemoteWorkspaceMember, context?: RemoteWorkspaceContext): 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>;
 }

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

@@ -1,6 +1,10 @@
+import { type RemoteWorkspaceContext, type RemoteAccountWorkspaces, type RemoteWorkspaceSession, type RemoteWorkspaceSelectionErrorCode } from "./remote-workspace-selection.js";
+import { type RemoteWorkspaceMembersOptions, type RemoteWorkspaceMembersPage } from "./remote-workspace.js";
+import { type RemoteWorkspaceMemberErrorCode, type SetRemoteWorkspaceMemberRole, type RemoveRemoteWorkspaceMember, type RemoteWorkspaceMemberRoleResult, type RemoteWorkspaceMemberRemovalResult } from "./remote-workspace.js";
 import { type RemoteSkillRunContract } from "./remote-run-contract.js";
 import { type RemoteCreditPack, type RemoteRunApproval, type RemoteRunQuote } from "./remote-account.js";
 import { type RemoteInputFile } from "./remote-files.js";
+import { type UpdateRemoteProfile, type UpdateRemoteWorkspace } from "./remote-profile.js";
 /**
  * A server that predates this client's pin/tag/incremental-sync routes answered
  * 404/405 for them. The caller must never mistake that for "no pins" or "empty
@@ -17,7 +21,22 @@ export declare class RemoteRouteUnsupportedError extends Error {
 export declare class RemoteRequestError extends Error {
     readonly path: string;
     readonly status: number;
-    constructor(path: string, status: number, statusText: string);
+    constructor(path: string, status: number, _statusText?: string);
+}
+/** A recognized membership refusal, with fixed text and no server payload. */
+export declare class RemoteWorkspaceMemberError extends RemoteRequestError {
+    readonly code: RemoteWorkspaceMemberErrorCode;
+    constructor(path: string, code: RemoteWorkspaceMemberErrorCode);
+}
+/** Fixed text for recognized workspace refusals; no reflected server error payload. */
+export declare class RemoteWorkspaceSelectionError extends RemoteRequestError {
+    readonly code: RemoteWorkspaceSelectionErrorCode;
+    constructor(path: string, code: RemoteWorkspaceSelectionErrorCode);
+}
+/** A recognized unavailable capability; all displayed text is client-owned. */
+export declare class RemoteCapabilityUnavailableError extends RemoteRequestError {
+    readonly code: "SUBSCRIPTION_CHECKOUT_UNAVAILABLE";
+    constructor();
 }
 /**
  * A remote pin on a skill, matching the hosted-pins wire shape
@@ -106,6 +125,26 @@ export declare class RemoteSkillsClient {
     /** Quote first and fail closed when the caller has not approved the required credits. */
     submitQuotedRun(slug: string, input?: Record<string, unknown>, args?: string[], approval?: RemoteRunApproval): Promise<RemoteSkillRunContract>;
     getIdentity(): Promise<Record<string, unknown>>;
+    /** List memberships with the current interactive session; never writes credentials. */
+    listAccountWorkspaces(expectedUserId?: string): Promise<RemoteAccountWorkspaces>;
+    /** Return a new ephemeral session; this client and any saved key/profile stay unchanged. */
+    switchWorkspace(context: RemoteWorkspaceContext): Promise<RemoteWorkspaceSession>;
+    private requestWorkspaceSelection;
+    /** Requires a customer session; API keys and support impersonation cannot edit names. */
+    updateProfile(input: UpdateRemoteProfile): Promise<{
+        user: import("./remote-profile.js").RemoteCustomerProfile;
+    }>;
+    /** Owner/admin session only; the current workspace identity and slug stay fixed. */
+    updateCurrentWorkspace(input: UpdateRemoteWorkspace): Promise<{
+        organization: import("./remote-profile.js").RemoteCurrentWorkspace;
+    }>;
+    /** Current owner/admin customer session only; the server refuses API keys and impersonation. */
+    listWorkspaceMembers(options?: RemoteWorkspaceMembersOptions): Promise<RemoteWorkspaceMembersPage>;
+    /** Exact incarnation and expected role; no refresh or retry. Server enforces current authority. */
+    setWorkspaceMemberRole(membershipId: string, input: SetRemoteWorkspaceMemberRole): Promise<RemoteWorkspaceMemberRoleResult>;
+    /** Removes only this incarnation. A successful tombstone replay is returned unchanged. */
+    removeWorkspaceMember(membershipId: string, input: RemoveRemoteWorkspaceMember): Promise<RemoteWorkspaceMemberRemovalResult>;
+    private requestWorkspaceMember;
     listApiKeys(): Promise<Record<string, unknown>[]>;
     createApiKey(name: string, scopes?: string[]): Promise<{
         key: string;
@@ -211,11 +250,12 @@ export declare class RemoteSkillsClient {
 }
 /**
  * The client for the configured instance, or null when this install runs on
- * this machine (no credential and no authority).
+ * this machine — which is now the explicit local opt-in only
+ * (`HASNA_SKILLS_LOCAL=1`); with no credential, no authority and no opt-in the
+ * shared ladder throws (fail-closed ruling), so the caller fails loudly instead
+ * of quietly reading the bundled corpus while authentication is unconfigured.
  *
- * A configured authority with no credential does NOT return null: the shared
- * ladder throws, so the caller fails loudly instead of quietly reading the
- * bundled corpus while authentication is unconfigured.
+ * A configured authority with no credential also throws for the same reason.
  *
  * ASYNC because the credential ladder is: a vault pointer
  * (`HASNA_SKILLS_API_KEY_REF`) is completed through the secrets vault before a

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

@@ -0,0 +1,26 @@
+export type RemoteCustomerRole = "owner" | "admin" | "member" | "viewer";
+export type RemoteCustomerProfile = {
+    id: string;
+    email: string;
+    displayName: string | null;
+    role: RemoteCustomerRole;
+};
+export type RemoteCurrentWorkspace = {
+    id: string;
+    slug: string;
+    name: string;
+};
+export type UpdateRemoteProfile = {
+    displayName: string;
+};
+export type UpdateRemoteWorkspace = {
+    name: string;
+};
+/** Client input checks do not grant authority; the selected server owns policy. */
+export declare function customerNamePatch(input: unknown, field: "displayName" | "name"): Record<string, string>;
+export declare function parseUpdatedProfile(value: unknown): {
+    user: RemoteCustomerProfile;
+};
+export declare function parseUpdatedWorkspace(value: unknown): {
+    organization: RemoteCurrentWorkspace;
+};

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

@@ -45,9 +45,13 @@ export declare function loadRemoteRegistry(options?: RemoteRegistryOptions): Pro
  * origin sees the folder UNION cloud in the plain `list`/`search` path, while
  * every other install keeps today's exact local behavior.
  *
- *   - Nothing configured (no credential, no authority) -> the local list is
- *     returned unchanged and no request is attempted. An install running on
- *     this machine must stay byte-identical to the pre-merge output.
+ *   - Nothing configured, local opted in -> the local list is returned
+ *     unchanged and no request is attempted. An install running on this
+ *     machine must stay byte-identical to the pre-merge output.
+ *   - Nothing configured and NO local opt-in -> this throws, from the shared
+ *     ladder (MISSING_API_CREDENTIAL, naming `HASNA_SKILLS_LOCAL` as the
+ *     deliberate way out): local mode is opt-in only, and an unconfigured
+ *     install is a refusal rather than a silent local listing.
  *   - An authority configured with NO credential -> this throws, from the
  *     shared ladder. It used to return the local half silently, which is the
  *     false green the 2026-09-04 ruling removes: an operator who pointed this