@work-shape/catalyst-cli 0.6.3 → 0.7.0

package/README.md

@@ -7,6 +7,8 @@ npm install --global @work-shape/catalyst-cli
 catalyst --help
 ```
 
+`catalyst setup <claude-code|codex|other> --instance <url>` connects an AI tool on your computer: it logs in by a code you confirm in the browser and writes the Catalyst skill the package ships to `~/.claude/skills/catalyst/` or `~/.agents/skills/catalyst/`.
+
 It needs Node 22 or later. The key is read from `CATALYST_API_KEY`, is sent only to the instance you name over HTTPS, and is never written into the working copy.
 
 MIT licence.

package/dist/index.d.ts

@@ -33,6 +33,11 @@ interface AgentConfig {
     maxSteps?: number;
     toolNames: string[];
     skillNames: string[];
+    /**
+     * The Knowledge Bases the agent answers from, by id. However many it lists, the agent has one
+     * tool over all of them, `knowledge.query`. Missing means none.
+     */
+    knowledgeBases?: string[];
     initialPrompts: AgentInitialPromptConfig[];
 }
 interface SkillConfig {
@@ -639,6 +644,7 @@ declare const apiOperations: {
                 }, zod_v4_core.$strip>;
                 release: zod.ZodObject<{
                     version: zod.ZodString;
+                    cliVersion: zod.ZodOptional<zod.ZodString>;
                 }, zod_v4_core.$strip>;
                 kinds: zod.ZodArray<zod.ZodObject<{
                     kind: zod.ZodString;
@@ -651,6 +657,10 @@ declare const apiOperations: {
                         config: "config";
                         files: "files";
                     }>;
+                    owners: zod.ZodArray<zod.ZodEnum<{
+                        instance: "instance";
+                        workspace: "workspace";
+                    }>>;
                     actions: zod.ZodObject<{
                         read: zod.ZodString;
                         write: zod.ZodString;
@@ -675,6 +685,16 @@ declare const apiOperations: {
                     displayName: zod.ZodString;
                     actions: zod.ZodArray<zod.ZodString>;
                 }, zod_v4_core.$strip>>;
+                workspaces: zod.ZodArray<zod.ZodObject<{
+                    id: zod.ZodString;
+                    name: zod.ZodString;
+                    kind: zod.ZodEnum<{
+                        personal: "personal";
+                        shared: "shared";
+                    }>;
+                    member: zod.ZodBoolean;
+                    actions: zod.ZodArray<zod.ZodString>;
+                }, zod_v4_core.$strip>>;
                 visibleSections: zod.ZodArray<zod.ZodEnum<{
                     workflows: "workflows";
                 }>>;
@@ -717,6 +737,32 @@ declare const apiOperations: {
                     max: "max";
                 }>>;
                 enabledToolNames: zod.ZodArray<zod.ZodString>;
+                tools: zod.ZodOptional<zod.ZodArray<zod.ZodObject<{
+                    name: zod.ZodString;
+                    title: zod.ZodOptional<zod.ZodObject<{
+                        en: zod.ZodString;
+                        de: zod.ZodString;
+                    }, zod_v4_core.$strip>>;
+                    summary: zod.ZodOptional<zod.ZodObject<{
+                        en: zod.ZodString;
+                        de: zod.ZodString;
+                    }, zod_v4_core.$strip>>;
+                    group: zod.ZodOptional<zod.ZodEnum<{
+                        instance: "instance";
+                        skills: "skills";
+                        files: "files";
+                        documents: "documents";
+                        web: "web";
+                        results: "results";
+                        platform: "platform";
+                    }>>;
+                    icon: zod.ZodOptional<zod.ZodString>;
+                    effect: zod.ZodOptional<zod.ZodEnum<{
+                        reading: "reading";
+                        changing: "changing";
+                    }>>;
+                    module: zod.ZodOptional<zod.ZodString>;
+                }, zod_v4_core.$strip>>>;
                 moduleOffTools: zod.ZodOptional<zod.ZodArray<zod.ZodObject<{
                     name: zod.ZodString;
                     module: zod.ZodString;
@@ -4048,6 +4094,246 @@ declare const apiOperations: {
             readonly response: readonly ["Operation-Run-Id", "Location", "Idempotent-Replayed"];
         };
     }>;
+    readonly "knowledge_bases.get": Operation<{
+        readonly id: "knowledge_bases.get";
+        readonly method: "GET";
+        readonly path: "/api/v1/knowledge-bases/:knowledgeBase";
+        readonly summary: "Read the state of one published Knowledge Base: whether its last check could read every table it describes";
+        readonly scope: "config_assets:read";
+        readonly effect: "reading";
+        readonly response: {
+            readonly kind: "json";
+            readonly schema: zod.ZodObject<{
+                id: zod.ZodString;
+                name: zod.ZodString;
+                status: zod.ZodEnum<{
+                    ok: "ok";
+                    unchecked: "unchecked";
+                    needs_attention: "needs_attention";
+                }>;
+                revision: zod.ZodOptional<zod.ZodNumber>;
+                checkedAt: zod.ZodOptional<zod.ZodString>;
+                tables: zod.ZodArray<zod.ZodObject<{
+                    name: zod.ZodString;
+                    readable: zod.ZodBoolean;
+                }, zod_v4_core.$strip>>;
+                problem: zod.ZodOptional<zod.ZodString>;
+            }, zod_v4_core.$strip>;
+        };
+        readonly errors: readonly ["NOT_FOUND"];
+        readonly rateClass: "read";
+        readonly tag: "Knowledge Bases";
+        readonly auth: "principal";
+        readonly requires: readonly [];
+    } & {
+        readonly headers: {
+            readonly response: readonly ["Operation-Run-Id"];
+        };
+    }>;
+    readonly "knowledge_bases.check": Operation<{
+        readonly id: "knowledge_bases.check";
+        readonly method: "POST";
+        readonly path: "/api/v1/knowledge-bases/:knowledgeBase/check";
+        readonly summary: "Check one published Knowledge Base now: whether every table it describes can be read. It reads no row";
+        readonly scope: "config_assets:write";
+        readonly effect: "changing";
+        readonly response: {
+            readonly kind: "json";
+            readonly schema: zod.ZodObject<{
+                id: zod.ZodString;
+                name: zod.ZodString;
+                status: zod.ZodEnum<{
+                    ok: "ok";
+                    unchecked: "unchecked";
+                    needs_attention: "needs_attention";
+                }>;
+                revision: zod.ZodOptional<zod.ZodNumber>;
+                checkedAt: zod.ZodOptional<zod.ZodString>;
+                tables: zod.ZodArray<zod.ZodObject<{
+                    name: zod.ZodString;
+                    readable: zod.ZodBoolean;
+                }, zod_v4_core.$strip>>;
+                problem: zod.ZodOptional<zod.ZodString>;
+            }, zod_v4_core.$strip>;
+        };
+        readonly rateClass: "write";
+        readonly tag: "Knowledge Bases";
+        readonly auth: "principal";
+        readonly requires: readonly [];
+        readonly errors: readonly ["NOT_FOUND", "CONFLICT", "TIMEOUT"];
+    } & {
+        readonly accepted: zod.ZodObject<{
+            id: zod.ZodString;
+            operation: zod.ZodString;
+            effect: zod.ZodEnum<{
+                reading: "reading";
+                changing: "changing";
+            }>;
+            status: zod.ZodEnum<{
+                failed: "failed";
+                running: "running";
+                done: "done";
+                pending_approval: "pending_approval";
+                pending_confirmation: "pending_confirmation";
+                denied: "denied";
+                expired: "expired";
+            }>;
+            actor: zod.ZodObject<{
+                kind: zod.ZodEnum<{
+                    user: "user";
+                    service_principal: "service_principal";
+                }>;
+                id: zod.ZodString;
+                label: zod.ZodString;
+            }, zod_v4_core.$strip>;
+            origin: zod.ZodDiscriminatedUnion<[zod.ZodObject<{
+                kind: zod.ZodLiteral<"agent">;
+                agentRunId: zod.ZodString;
+                conversationId: zod.ZodString;
+                agentName: zod.ZodString;
+                toolCallId: zod.ZodString;
+                toolName: zod.ZodString;
+                toolRevisionId: zod.ZodOptional<zod.ZodString>;
+            }, zod_v4_core.$strip>, zod.ZodObject<{
+                kind: zod.ZodLiteral<"user">;
+            }, zod_v4_core.$strip>, zod.ZodObject<{
+                kind: zod.ZodLiteral<"cli">;
+            }, zod_v4_core.$strip>, zod.ZodObject<{
+                kind: zod.ZodLiteral<"mcp">;
+                clientName: zod.ZodOptional<zod.ZodString>;
+            }, zod_v4_core.$strip>, zod.ZodObject<{
+                kind: zod.ZodLiteral<"app">;
+                appName: zod.ZodOptional<zod.ZodString>;
+                appRevisionId: zod.ZodString;
+                actionName: zod.ZodString;
+                pageSessionId: zod.ZodString;
+                conversationId: zod.ZodOptional<zod.ZodString>;
+                target: zod.ZodOptional<zod.ZodUnion<readonly [zod.ZodObject<{
+                    connection: zod.ZodString;
+                    operation: zod.ZodString;
+                }, zod_v4_core.$strip>, zod.ZodObject<{
+                    dataStore: zod.ZodString;
+                }, zod_v4_core.$strip>, zod.ZodObject<{
+                    workflow: zod.ZodString;
+                }, zod_v4_core.$strip>]>>;
+            }, zod_v4_core.$strip>, zod.ZodObject<{
+                kind: zod.ZodLiteral<"workflow">;
+                workflowRunId: zod.ZodString;
+                stepRunId: zod.ZodString;
+                boundBy: zod.ZodOptional<zod.ZodObject<{
+                    id: zod.ZodString;
+                    label: zod.ZodString;
+                }, zod_v4_core.$strip>>;
+            }, zod_v4_core.$strip>, zod.ZodObject<{
+                kind: zod.ZodLiteral<"schedule">;
+                scheduleId: zod.ZodString;
+            }, zod_v4_core.$strip>], "kind">;
+            target: zod.ZodEnum<{
+                dry_run: "dry_run";
+                live: "live";
+                test: "test";
+            }>;
+            app: zod.ZodOptional<zod.ZodObject<{
+                title: zod.ZodOptional<zod.ZodString>;
+                revision: zod.ZodOptional<zod.ZodNumber>;
+                deleted: zod.ZodBoolean;
+            }, zod_v4_core.$strip>>;
+            workspaceId: zod.ZodOptional<zod.ZodString>;
+            approvalRequestId: zod.ZodOptional<zod.ZodString>;
+            inputHash: zod.ZodString;
+            attempt: zod.ZodNumber;
+            decision: zod.ZodOptional<zod.ZodObject<{
+                mode: zod.ZodEnum<{
+                    direct: "direct";
+                    confirmed: "confirmed";
+                    approved: "approved";
+                    declined: "declined";
+                }>;
+                reason: zod.ZodOptional<zod.ZodEnum<{
+                    inherited_approval_not_applied: "inherited_approval_not_applied";
+                }>>;
+                by: zod.ZodString;
+                byLabel: zod.ZodOptional<zod.ZodString>;
+                at: zod.ZodISODateTime;
+                comment: zod.ZodOptional<zod.ZodString>;
+            }, zod_v4_core.$strip>>;
+            error: zod.ZodOptional<zod.ZodObject<{
+                code: zod.ZodString;
+                message: zod.ZodString;
+                reason: zod.ZodOptional<zod.ZodString>;
+            }, zod_v4_core.$strip>>;
+            usage: zod.ZodOptional<zod.ZodObject<{
+                modelCalls: zod.ZodNumber;
+                inputTokens: zod.ZodNumber;
+                outputTokens: zod.ZodNumber;
+                totalTokens: zod.ZodNumber;
+            }, zod_v4_core.$strip>>;
+            correlationId: zod.ZodString;
+            createdAt: zod.ZodISODateTime;
+            startedAt: zod.ZodOptional<zod.ZodISODateTime>;
+            finishedAt: zod.ZodOptional<zod.ZodISODateTime>;
+            expiresAt: zod.ZodOptional<zod.ZodISODateTime>;
+            href: zod.ZodString;
+        }, zod_v4_core.$strip>;
+        readonly headers: {
+            readonly request: readonly ["Idempotency-Key"];
+            readonly response: readonly ["Operation-Run-Id", "Location", "Idempotent-Replayed"];
+        };
+    }>;
+    readonly "knowledge_bases.query": Operation<{
+        readonly id: "knowledge_bases.query";
+        readonly method: "POST";
+        readonly path: "/api/v1/knowledge-bases/:knowledgeBase/query";
+        readonly summary: "Read rows of one published Knowledge Base with one read-only statement and bound parameters";
+        readonly scope: "data_store_rows:read";
+        readonly effect: "reading";
+        readonly body: zod.ZodObject<{
+            sql: zod.ZodString;
+            parameters: zod.ZodOptional<zod.ZodArray<zod.ZodUnion<readonly [zod.ZodUnion<readonly [zod.ZodUnion<readonly [zod.ZodString, zod.ZodNumber, zod.ZodBoolean, zod.ZodNull]>, zod.ZodArray<zod.ZodUnion<readonly [zod.ZodString, zod.ZodNumber, zod.ZodBoolean, zod.ZodNull]>>]>, zod.ZodObject<{
+                type: zod.ZodEnum<{
+                    number: "number";
+                    boolean: "boolean";
+                    date: "date";
+                    text: "text";
+                    integer: "integer";
+                    timestamp: "timestamp";
+                    "number[]": "number[]";
+                    "boolean[]": "boolean[]";
+                    "date[]": "date[]";
+                    "text[]": "text[]";
+                    "integer[]": "integer[]";
+                    "timestamp[]": "timestamp[]";
+                }>;
+                value: zod.ZodUnion<readonly [zod.ZodUnion<readonly [zod.ZodString, zod.ZodNumber, zod.ZodBoolean, zod.ZodNull]>, zod.ZodArray<zod.ZodUnion<readonly [zod.ZodString, zod.ZodNumber, zod.ZodBoolean, zod.ZodNull]>>]>;
+            }, zod_v4_core.$strict>]>>>;
+        }, zod_v4_core.$strict>;
+        readonly response: {
+            readonly kind: "json";
+            readonly schema: zod.ZodObject<{
+                columns: zod.ZodArray<zod.ZodObject<{
+                    name: zod.ZodString;
+                    type: zod.ZodString;
+                    nativeType: zod.ZodString;
+                }, zod_v4_core.$strip>>;
+                rows: zod.ZodArray<zod.ZodRecord<zod.ZodString, zod.ZodUnknown>>;
+                truncated: zod.ZodBoolean;
+                source: zod.ZodObject<{
+                    knowledgeBase: zod.ZodString;
+                    title: zod.ZodString;
+                    tables: zod.ZodArray<zod.ZodString>;
+                }, zod_v4_core.$strip>;
+            }, zod_v4_core.$strip>;
+        };
+        readonly rateClass: "read";
+        readonly tag: "Knowledge Bases";
+        readonly auth: "principal";
+        readonly requires: readonly [];
+        readonly errors: readonly ["NOT_FOUND", "CONFLICT", "TIMEOUT"];
+    } & {
+        readonly headers: {
+            readonly response: readonly ["Operation-Run-Id"];
+        };
+    }>;
     readonly "data_stores.query": Operation<{
         readonly id: "data_stores.query";
         readonly method: "POST";
@@ -5751,6 +6037,7 @@ declare const apiOperations: {
                         agent: "agent";
                         bridge: "bridge";
                         workflow: "workflow";
+                        outside: "outside";
                     }>>;
                     enabled: zod.ZodBoolean;
                     status: zod.ZodEnum<{
@@ -6196,7 +6483,7 @@ declare const apiOperations: {
         readonly id: "assets.sync";
         readonly method: "POST";
         readonly path: "/api/v1/assets/sync";
-        readonly summary: "Apply puts and deletes in one Namespace, all of them or none";
+        readonly summary: "Apply puts and deletes in one Namespace or workspace, all of them or none";
         readonly tag: "Assets";
         readonly auth: "principal";
         readonly scope: "config_assets:write";
@@ -6204,6 +6491,7 @@ declare const apiOperations: {
         readonly effect: "changing";
         readonly body: zod.ZodObject<{
             namespace: zod.ZodOptional<zod.ZodString>;
+            workspaceId: zod.ZodOptional<zod.ZodString>;
             items: zod.ZodArray<zod.ZodDiscriminatedUnion<[zod.ZodObject<{
                 type: zod.ZodLiteral<"put">;
                 kind: zod.ZodString;
@@ -6380,6 +6668,7 @@ declare const apiOperations: {
         readonly effect: "reading";
         readonly body: zod.ZodObject<{
             namespace: zod.ZodOptional<zod.ZodString>;
+            workspaceId: zod.ZodOptional<zod.ZodString>;
             items: zod.ZodArray<zod.ZodDiscriminatedUnion<[zod.ZodObject<{
                 type: zod.ZodLiteral<"put">;
                 kind: zod.ZodString;
@@ -7862,6 +8151,32 @@ declare const apiOperations: {
                         max: "max";
                     }>>;
                     enabledToolNames: zod.ZodArray<zod.ZodString>;
+                    tools: zod.ZodOptional<zod.ZodArray<zod.ZodObject<{
+                        name: zod.ZodString;
+                        title: zod.ZodOptional<zod.ZodObject<{
+                            en: zod.ZodString;
+                            de: zod.ZodString;
+                        }, zod_v4_core.$strip>>;
+                        summary: zod.ZodOptional<zod.ZodObject<{
+                            en: zod.ZodString;
+                            de: zod.ZodString;
+                        }, zod_v4_core.$strip>>;
+                        group: zod.ZodOptional<zod.ZodEnum<{
+                            instance: "instance";
+                            skills: "skills";
+                            files: "files";
+                            documents: "documents";
+                            web: "web";
+                            results: "results";
+                            platform: "platform";
+                        }>>;
+                        icon: zod.ZodOptional<zod.ZodString>;
+                        effect: zod.ZodOptional<zod.ZodEnum<{
+                            reading: "reading";
+                            changing: "changing";
+                        }>>;
+                        module: zod.ZodOptional<zod.ZodString>;
+                    }, zod_v4_core.$strip>>>;
                     moduleOffTools: zod.ZodOptional<zod.ZodArray<zod.ZodObject<{
                         name: zod.ZodString;
                         module: zod.ZodString;
@@ -10369,10 +10684,10 @@ declare const apiOperations: {
                     conversationId: zod.ZodString;
                     clientInstanceId: zod.ZodString;
                     role: zod.ZodEnum<{
+                        tool: "tool";
                         user: "user";
                         system: "system";
                         assistant: "assistant";
-                        tool: "tool";
                     }>;
                     text: zod.ZodString;
                     createdAt: zod.ZodISODateTime;
@@ -10694,10 +11009,10 @@ declare const apiOperations: {
                     conversationId: zod.ZodString;
                     clientInstanceId: zod.ZodString;
                     role: zod.ZodEnum<{
+                        tool: "tool";
                         user: "user";
                         system: "system";
                         assistant: "assistant";
-                        tool: "tool";
                     }>;
                     text: zod.ZodString;
                     createdAt: zod.ZodISODateTime;
@@ -11083,10 +11398,10 @@ declare const apiOperations: {
                     conversationId: zod.ZodString;
                     clientInstanceId: zod.ZodString;
                     role: zod.ZodEnum<{
+                        tool: "tool";
                         user: "user";
                         system: "system";
                         assistant: "assistant";
-                        tool: "tool";
                     }>;
                     text: zod.ZodString;
                     createdAt: zod.ZodISODateTime;
@@ -11265,10 +11580,10 @@ declare const apiOperations: {
                         conversationId: zod.ZodString;
                         clientInstanceId: zod.ZodString;
                         role: zod.ZodEnum<{
+                            tool: "tool";
                             user: "user";
                             system: "system";
                             assistant: "assistant";
-                            tool: "tool";
                         }>;
                         text: zod.ZodString;
                         createdAt: zod.ZodISODateTime;
@@ -11641,10 +11956,10 @@ declare const apiOperations: {
                     conversationId: zod.ZodString;
                     clientInstanceId: zod.ZodString;
                     role: zod.ZodEnum<{
+                        tool: "tool";
                         user: "user";
                         system: "system";
                         assistant: "assistant";
-                        tool: "tool";
                     }>;
                     text: zod.ZodString;
                     createdAt: zod.ZodISODateTime;
@@ -11823,10 +12138,10 @@ declare const apiOperations: {
                         conversationId: zod.ZodString;
                         clientInstanceId: zod.ZodString;
                         role: zod.ZodEnum<{
+                            tool: "tool";
                             user: "user";
                             system: "system";
                             assistant: "assistant";
-                            tool: "tool";
                         }>;
                         text: zod.ZodString;
                         createdAt: zod.ZodISODateTime;
@@ -14656,6 +14971,7 @@ declare const apiOperations: {
                             maxSteps: "maxSteps";
                             toolNames: "toolNames";
                             skillNames: "skillNames";
+                            knowledgeBases: "knowledgeBases";
                             initialPrompts: "initialPrompts";
                         }>>>;
                         allowAgentCreation: zod.ZodDefault<zod.ZodBoolean>;
@@ -15859,6 +16175,11 @@ interface ConfigApiOptions {
     fetchImpl?: typeof fetch;
     /** Waits between tries. Tests pass one that does not wait. */
     sleep?: (milliseconds: number) => Promise<void>;
+    /**
+     * The workspace whose own assets the working copy holds, for a root bound with
+     * `--workspace`. Left out, the instance's own. The reads of assets name it.
+     */
+    workspaceId?: string;
 }
 type FetchImpl = NonNullable<ConfigApiOptions["fetchImpl"]>;
 declare function createConfigApi(options: ConfigApiOptions): Promise<{
@@ -15968,15 +16289,34 @@ declare function canonicalizeSkillConfig(input: unknown): SkillConfig;
 declare function serializeSkillMarkdown(input: unknown, provenance?: AssetProvenance): string;
 declare function serializeSkillPackageForDisplay(input: unknown): string;
 
+/** The variables this package reads by a fixed name. */
+interface ConfigCliEnv {
+    /** A key provisioned for automation. It wins over a key `catalyst login` saved. */
+    readonly CATALYST_API_KEY?: string | undefined;
+    /** The folder of the saved keys, in place of `$XDG_CONFIG_HOME/catalyst`. */
+    readonly CATALYST_CONFIG_HOME?: string | undefined;
+    readonly XDG_CONFIG_HOME?: string | undefined;
+    /** The person's home folder, where `catalyst setup` writes the skill of their tool. */
+    readonly HOME?: string | undefined;
+    /** Claude Code's own folder in place of `~/.claude`, where `catalyst setup` writes its skill. */
+    readonly CLAUDE_CONFIG_DIR?: string | undefined;
+}
+
 declare const MANIFEST_FILENAME = "catalyst.yaml";
 declare const STATE_FILENAME = ".catalyst-state.json";
 interface ManifestInstance {
     url: string;
     /**
-     * The one Namespace this working copy writes in, such as `kai-`. A push names it, and leaves
+     * The one Namespace this working copy writes in, such as `tax-`. A push names it, and leaves
      * the instance's default agent alone, which only a release names.
      */
     namespace?: string;
+    /**
+     * The workspace this working copy is bound to, by its id: `catalyst config pull
+     * --workspace <id>` writes it. The root holds what that workspace owns, and everything it
+     * pushes is owned by that workspace. A root names a Namespace or a workspace, not both.
+     */
+    workspace?: string;
 }
 interface CatalystManifest {
     instances: Record<string, ManifestInstance>;
@@ -16037,7 +16377,17 @@ declare function parseManifest(contents: string, source?: string): CatalystManif
 declare function readManifest(workingDir: string): Promise<CatalystManifest>;
 /** The manifest of the folder, or none where the folder is no working copy. */
 declare function readManifestIfPresent(workingDir: string): Promise<CatalystManifest | undefined>;
-declare function resolveInstance(manifest: CatalystManifest, requestedInstance?: string): ResolvedInstance;
+/**
+ * The instance a command works on: `instance` as an instance of the manifest or as an address,
+ * else the manifest's default instance. A working copy that names neither is refused with the
+ * instances it names: it belongs to one of them, and a saved key never chooses among them.
+ * Outside a working copy (`manifest` undefined), the one instance a key is saved for is taken,
+ * unless `CATALYST_API_KEY` is set, whose instance a saved key does not tell.
+ */
+declare function resolveInstance(manifest: CatalystManifest | undefined, options?: {
+    instance?: string | undefined;
+    env?: ConfigCliEnv | undefined;
+}): Promise<ResolvedInstance>;
 declare function readStateFile(path: string): Promise<CatalystState>;
 declare function writeStateFile(path: string, state: CatalystState): Promise<void>;
 declare function readWorkingCopy(workingDir: string, manifest: CatalystManifest): Promise<WorkingCopyBundle>;
@@ -16049,6 +16399,13 @@ declare function guardrailAssetPath(workingDir: string, name: string): string;
 declare function readSkillResources(skillFilePath: string): Promise<SkillResourceConfig[]>;
 declare function removeStaleManifestAssets(workingDir: string, manifest: CatalystManifest, desiredPaths: Set<string>): Promise<void>;
 declare function updateManifestDefaultAgent(path: string, defaultAgentName: string | undefined): Promise<void>;
+/**
+ * Binds the working copy's instance to a workspace: writes `workspace: <id>` below the
+ * instance's `url` in catalyst.yaml and leaves every other line as it is. An instance that is
+ * not written as a block with its own `url:` line is not changed, and the caller is told to
+ * add the line itself.
+ */
+declare function bindManifestWorkspace(path: string, instanceKey: string, workspaceId: string): Promise<void>;
 /**
  * Every file below `directory`, by absolute path. `.git` and `node_modules` directly in `root`
  * are skipped.
@@ -16062,6 +16419,8 @@ interface ConfigCommandOptions {
     force?: boolean;
     prune?: boolean;
     only?: string[];
+    /** The workspace `pull` binds the working copy to, or finds it bound to. */
+    workspace?: string;
     assetKind?: AssetKindName;
     assetName?: string;
     fetchImpl?: typeof fetch;
@@ -16091,6 +16450,9 @@ interface DiffFile {
 }
 declare function createUnifiedDiff(oldFile: DiffFile, newFile: DiffFile): string;
 
+/** The skill file this CLI writes: the shipped skill with a mark of who wrote it. */
+declare function renderCatalystSkill(): Promise<string>;
+
 interface CliRuntimeOptions {
     cwd?: string;
     fetchImpl?: typeof fetch;
@@ -16099,7 +16461,9 @@ interface CliRuntimeOptions {
     stderr?: (text: string) => void;
     /** Waits between tries. Tests pass one that does not wait. */
     sleep?: (milliseconds: number) => Promise<void>;
+    /** Opens an address in a browser, as `setup` does. Tests pass one that opens nothing. */
+    openUrl?: (address: string) => void;
 }
 declare function runCli(argv: string[], runtime?: CliRuntimeOptions): Promise<number>;
 
-export { ApiKeyExchangeError, type AssetBaseline, type AssetProvenance, type CatalystManifest, type CatalystState, type CliRuntimeOptions, type ConfigApi, ConfigApiError, type ConfigApiOptions, type ConfigCommandName, type ConfigCommandOptions, type DeletedAssetBaseline, type DiffFile, type InstanceBaseline, MANIFEST_FILENAME, type ManifestInstance, type ResolvedInstance, STATE_FILENAME, type SyncBatch, type SyncOutcome, type SyncOutput, type WorkingCopyBundle, type WorkingCopyIssue, WorkingCopyValidationError, agentAssetPath, assertSafeApiKeyExchangeUrl, canonicalBundleFiles, canonicalizeAgentConfig, canonicalizeSkillConfig, createConfigApi, createUnifiedDiff, diffConfig, guardrailAssetPath, instanceFetch, listConfig, matchManifestFiles, matchesManifestPath, parseAgentYaml, parseManifest, parseSkillFile, pullConfig, pushConfig, readManifest, readManifestIfPresent, readSkillResources, readStateFile, readWorkingCopy, removeStaleManifestAssets, resolveInstance, resolveSkillResourceTarget, runCli, runConfigCommand, serializeAgentYaml, serializeSkillMarkdown, serializeSkillPackageForDisplay, showConfig, skillAssetPath, toConfigApiError, updateManifestDefaultAgent, validateConfig, walkFiles, writeStateFile };
+export { ApiKeyExchangeError, type AssetBaseline, type AssetProvenance, type CatalystManifest, type CatalystState, type CliRuntimeOptions, type ConfigApi, ConfigApiError, type ConfigApiOptions, type ConfigCommandName, type ConfigCommandOptions, type DeletedAssetBaseline, type DiffFile, type InstanceBaseline, MANIFEST_FILENAME, type ManifestInstance, type ResolvedInstance, STATE_FILENAME, type SyncBatch, type SyncOutcome, type SyncOutput, type WorkingCopyBundle, type WorkingCopyIssue, WorkingCopyValidationError, agentAssetPath, assertSafeApiKeyExchangeUrl, bindManifestWorkspace, canonicalBundleFiles, canonicalizeAgentConfig, canonicalizeSkillConfig, createConfigApi, createUnifiedDiff, diffConfig, guardrailAssetPath, instanceFetch, listConfig, matchManifestFiles, matchesManifestPath, parseAgentYaml, parseManifest, parseSkillFile, pullConfig, pushConfig, readManifest, readManifestIfPresent, readSkillResources, readStateFile, readWorkingCopy, removeStaleManifestAssets, renderCatalystSkill, resolveInstance, resolveSkillResourceTarget, runCli, runConfigCommand, serializeAgentYaml, serializeSkillMarkdown, serializeSkillPackageForDisplay, showConfig, skillAssetPath, toConfigApiError, updateManifestDefaultAgent, validateConfig, walkFiles, writeStateFile };