@work-shape/catalyst-cli 0.6.3 → 0.7.0

package/dist/index.js

@@ -5,11 +5,6 @@ import { realpathSync } from "fs";
 import { parseArgs as parseArgs2 } from "util";
 import { pathToFileURL } from "url";
 
-// src/asset-commands.ts
-import { readFile as readFile5 } from "fs/promises";
-import { resolve as resolve5 } from "path";
-import { parseArgs } from "util";
-
 // ../asset-schemas/src/asset-types.ts
 var REASONING_EFFORTS = ["none", "low", "medium", "high", "xhigh", "max"];
 var SKILL_STARTERS_MAX = 2;
@@ -77,7 +72,7 @@ var PROVIDER_CHECK_ERROR_CLASSES = [
 ];
 var CONNECTION_NAME_PATTERN = /^[a-z][a-z0-9]*([_-][a-z0-9]+)*$/u;
 var CONNECTION_NAME_MAX_LENGTH = 64;
-var CONNECTION_EXPOSURES = ["agent", "bridge", "workflow"];
+var CONNECTION_EXPOSURES = ["agent", "bridge", "workflow", "outside"];
 var CONNECTION_HEALTH_STATES = [
   "unknown",
   "ok",
@@ -282,6 +277,9 @@ var agentConfigSchema = z.object({
   maxSteps: z.number().int().positive().optional(),
   toolNames: z.array(z.string().min(1)).default([]),
   skillNames: z.array(skillNameSchema).default([]),
+  knowledgeBases: z.array(z.string().min(1)).refine((names) => new Set(names).size === names.length, {
+    message: "A Knowledge Base is listed once"
+  }).optional(),
   initialPrompts: z.array(
     z.object({
       title: localizedStringSchema,
@@ -939,6 +937,69 @@ function buildPath(pathTemplate, queryParamNames, options = {}) {
   return queryString ? `${path}?${queryString}` : path;
 }
 
+// ../api-contract/src/openapi.ts
+import { z as z37 } from "zod";
+
+// ../api-contract/package.json
+var package_default = {
+  name: "@vivd-catalyst/api-contract",
+  version: "0.7.0",
+  license: "MIT",
+  repository: {
+    type: "git",
+    url: "git+https://github.com/vivd-solutions/vivd-catalyst.git",
+    directory: "packages/api-contract"
+  },
+  type: "module",
+  sideEffects: false,
+  engines: {
+    node: ">=22"
+  },
+  files: [
+    "dist",
+    "openapi.json"
+  ],
+  main: "./dist/index.js",
+  types: "./dist/index.d.ts",
+  exports: {
+    ".": {
+      types: "./dist/index.d.ts",
+      development: "./src/index.ts",
+      import: "./dist/index.js"
+    },
+    "./openapi.json": "./openapi.json"
+  },
+  publishConfig: {
+    access: "restricted",
+    registry: "https://registry.npmjs.org/",
+    exports: {
+      ".": {
+        types: "./dist/index.d.ts",
+        import: "./dist/index.js"
+      },
+      "./openapi.json": "./openapi.json"
+    }
+  },
+  scripts: {
+    build: "tsup src/index.ts --format esm --dts",
+    "check:contract": "tsx scripts/check-contract.ts",
+    "check:openapi": "tsx scripts/check-openapi.ts",
+    "generate:openapi": "tsx scripts/write-openapi.ts",
+    typecheck: "tsc -p tsconfig.json --noEmit"
+  },
+  dependencies: {
+    "@vivd-catalyst/asset-schemas": "workspace:*",
+    zod: "^4.4.3"
+  },
+  devDependencies: {
+    "@redocly/openapi-core": "^2.62.1",
+    "@types/node": "^24.13.1",
+    tsup: "^8.5.1",
+    tsx: "^4.22.4",
+    typescript: "^6.0.3"
+  }
+};
+
 // ../api-contract/src/errors.ts
 import { z as z6 } from "zod";
 var appErrorCodeSchema = z6.enum([
@@ -1498,6 +1559,7 @@ var agentEditableFieldSchema = z9.enum([
   "maxSteps",
   "toolNames",
   "skillNames",
+  "knowledgeBases",
   "initialPrompts"
 ]);
 var editableAgentFieldsSchema = z9.preprocess((value) => {
@@ -1731,6 +1793,28 @@ var configAssetRevisionSchema = z9.object({
   globalVersion: z9.number().int().positive(),
   createdAt: timestampSchema
 });
+var toolGroupSchema = z9.enum([
+  "documents",
+  "web",
+  "files",
+  "results",
+  "skills",
+  "platform",
+  "instance"
+]);
+var toolTextSchema = z9.object({ en: z9.string(), de: z9.string() });
+var agentToolReferenceSchema = z9.object({
+  name: z9.string(),
+  title: toolTextSchema.optional(),
+  summary: toolTextSchema.optional(),
+  group: toolGroupSchema.optional(),
+  /** A key of the icon registry of the UI library. */
+  icon: z9.string().optional(),
+  /** Missing for a tool the instance enables and no code registers. */
+  effect: z9.enum(["reading", "changing"]).optional(),
+  /** The module whose switch governs the tool. A core tool has none. */
+  module: z9.string().optional()
+});
 var configAssetReferencesSchema = z9.object({
   modelProviderIds: z9.array(z9.string()),
   modelBindingIds: z9.array(z9.string()),
@@ -1745,6 +1829,8 @@ var configAssetReferencesSchema = z9.object({
   fastModeModelBindingIds: z9.array(z9.string()),
   reasoningEfforts: z9.array(reasoningEffortSchema),
   enabledToolNames: z9.array(z9.string()),
+  /** The tools of `enabledToolNames`, in their order, with what each tells people. */
+  tools: z9.array(agentToolReferenceSchema).optional(),
   /**
    * Tools the instance enables whose module is off. No agent can use one. An agent that
    * still names one shows it as unavailable, so it can be removed.
@@ -2866,6 +2952,14 @@ var syncAssetsRequestSchema = z14.object({
    * instance.
    */
   namespace: nameText(z14.string().min(1)).optional(),
+  /**
+   * The workspace that owns every asset the batch names, as a CLI root bound with
+   * `--workspace` sends it. Left out, the batch names the instance's own assets. A batch
+   * names a Namespace or a workspace, never both, and one that names a workspace is no
+   * release: its agents start hidden and its writer holds the rights on what the workspace
+   * owns.
+   */
+  workspaceId: workspaceIdSchema,
   /**
    * At most `ASSET_SYNC_MAX_ITEMS` items, or `ASSET_RELEASE_SYNC_MAX_ITEMS` for a holder of
    * the release right. A batch without items names the default agent.
@@ -2964,7 +3058,7 @@ var assetOperations = {
     id: "assets.sync",
     method: "POST",
     path: "/api/v1/assets/sync",
-    summary: "Apply puts and deletes in one Namespace, all of them or none",
+    summary: "Apply puts and deletes in one Namespace or workspace, all of them or none",
     tag: "Assets",
     auth: "principal",
     scope: "config_assets:write",
@@ -5732,8 +5826,99 @@ var jobOperations = {
   })
 };
 
-// ../api-contract/src/operations/operations.ts
+// ../api-contract/src/operations/knowledge.ts
 import { z as z30 } from "zod";
+var SCALAR_TYPES2 = ["text", "integer", "number", "boolean", "date", "timestamp"];
+var scalarSchema2 = z30.union([z30.string(), z30.number(), z30.boolean(), z30.null()]);
+var valueSchema2 = z30.union([scalarSchema2, z30.array(scalarSchema2)]);
+var knowledgeQueryRequestSchema = z30.strictObject({
+  /** One read-only SELECT or WITH statement with positional placeholders. */
+  sql: z30.string().min(1),
+  /** A bare value, or a value with the type it is bound as. Never part of the statement. */
+  parameters: z30.array(
+    z30.union([
+      valueSchema2,
+      z30.strictObject({
+        type: z30.enum(SCALAR_TYPES2.flatMap((type) => [type, `${type}[]`])),
+        value: valueSchema2
+      })
+    ])
+  ).optional()
+});
+var knowledgeQueryResponseSchema = z30.object({
+  /** `type` is the product's name of the type, `nativeType` the database's. */
+  columns: z30.array(z30.object({ name: z30.string(), type: z30.string(), nativeType: z30.string() })),
+  rows: z30.array(z30.record(z30.string(), z30.unknown())),
+  /** Whether a cap ended the result before its last row. */
+  truncated: z30.boolean(),
+  /** What a citation names: the Knowledge Base and the tables it describes. */
+  source: z30.object({
+    knowledgeBase: z30.string(),
+    title: z30.string(),
+    tables: z30.array(z30.string())
+  })
+});
+var knowledgeStateResponseSchema = z30.object({
+  /** The id of the Knowledge Base's asset. */
+  id: z30.string(),
+  /** The id operations and routes name the Knowledge Base by. */
+  name: z30.string(),
+  /** `unchecked` until the published revision was first checked. */
+  status: z30.enum(["unchecked", "ok", "needs_attention"]),
+  /** The revision the last check was of. */
+  revision: z30.number().int().optional(),
+  checkedAt: z30.string().optional(),
+  /** Each described table, and whether the last check could read it. */
+  tables: z30.array(z30.object({ name: z30.string(), readable: z30.boolean() })),
+  /** Why the backend could not be asked at all, as a sentence. */
+  problem: z30.string().optional()
+});
+var BASE = {
+  tag: "Knowledge Bases",
+  auth: "principal",
+  requires: [],
+  errors: ["NOT_FOUND", "CONFLICT", "TIMEOUT"]
+};
+var knowledgeOperations = {
+  "knowledge_bases.get": defineRegisteredOperation({
+    ...BASE,
+    id: "knowledge_bases.get",
+    method: "GET",
+    path: "/api/v1/knowledge-bases/:knowledgeBase",
+    summary: "Read the state of one published Knowledge Base: whether its last check could read every table it describes",
+    scope: "config_assets:read",
+    effect: "reading",
+    response: json(knowledgeStateResponseSchema),
+    errors: ["NOT_FOUND"],
+    rateClass: "read"
+  }),
+  "knowledge_bases.check": defineRegisteredOperation({
+    ...BASE,
+    id: "knowledge_bases.check",
+    method: "POST",
+    path: "/api/v1/knowledge-bases/:knowledgeBase/check",
+    summary: "Check one published Knowledge Base now: whether every table it describes can be read. It reads no row",
+    scope: "config_assets:write",
+    effect: "changing",
+    response: json(knowledgeStateResponseSchema),
+    rateClass: "write"
+  }),
+  "knowledge_bases.query": defineRegisteredOperation({
+    ...BASE,
+    id: "knowledge_bases.query",
+    method: "POST",
+    path: "/api/v1/knowledge-bases/:knowledgeBase/query",
+    summary: "Read rows of one published Knowledge Base with one read-only statement and bound parameters",
+    scope: "data_store_rows:read",
+    effect: "reading",
+    body: knowledgeQueryRequestSchema,
+    response: json(knowledgeQueryResponseSchema),
+    rateClass: "read"
+  })
+};
+
+// ../api-contract/src/operations/operations.ts
+import { z as z31 } from "zod";
 var operationRunOperations = {
   "operations.get_run": defineOperation({
     id: "operations.get_run",
@@ -5762,14 +5947,14 @@ var operationRunOperations = {
     requires: ["audit.view"],
     effect: "reading",
     query: listQuerySchema.extend({
-      operation: z30.string().min(1).optional(),
+      operation: z31.string().min(1).optional(),
       /** Only reading calls or only changing ones. Without it the list holds both. */
-      effect: z30.enum(["reading", "changing"]).optional(),
+      effect: z31.enum(["reading", "changing"]).optional(),
       status: operationRunStatusSchema.optional(),
       /** The id of the user or service principal that called. */
-      actor: z30.string().min(1).optional(),
-      origin: z30.enum(["agent", "user", "cli", "mcp", "app", "workflow", "schedule"]).optional(),
-      workspaceId: z30.string().min(1).optional(),
+      actor: z31.string().min(1).optional(),
+      origin: z31.enum(["agent", "user", "cli", "mcp", "app", "workflow", "schedule"]).optional(),
+      workspaceId: z31.string().min(1).optional(),
       /** Runs created at or after this moment. */
       since: timestampSchema.optional()
     }),
@@ -5841,74 +6026,74 @@ var pageOperations = {
 };
 
 // ../api-contract/src/operations/personal-api-keys.ts
-import { z as z32 } from "zod";
+import { z as z33 } from "zod";
 
 // ../api-contract/src/personal-api-keys.ts
-import { z as z31 } from "zod";
-var personalApiKeyScopeSchema = z31.string().min(1).max(200);
-var personalApiKeySchema = z31.object({
-  id: z31.string(),
-  ownerUserId: z31.string(),
+import { z as z32 } from "zod";
+var personalApiKeyScopeSchema = z32.string().min(1).max(200);
+var personalApiKeySchema = z32.object({
+  id: z32.string(),
+  ownerUserId: z32.string(),
   /** The owner's name, in the instance's list of every person's keys. */
-  ownerDisplayLabel: z31.string().optional(),
-  name: z31.string(),
+  ownerDisplayLabel: z32.string().optional(),
+  name: z32.string(),
   /** The start of the key, which a person compares with the key they hold. Never the key. */
-  keyPrefix: z31.string(),
-  scopes: z31.array(personalApiKeyScopeSchema),
+  keyPrefix: z32.string(),
+  scopes: z32.array(personalApiKeyScopeSchema),
   createdAt: timestampSchema,
   expiresAt: timestampSchema,
   revokedAt: timestampSchema.optional(),
   lastUsedAt: timestampSchema.optional()
 });
-var keyFieldsSchema = z31.object({
-  name: z31.string().trim().min(1).max(100),
-  scopes: z31.array(personalApiKeyScopeSchema).min(1).max(64),
+var keyFieldsSchema = z32.object({
+  name: z32.string().trim().min(1).max(100),
+  scopes: z32.array(personalApiKeyScopeSchema).min(1).max(64),
   /** At most a year ahead. */
   expiresAt: timestampSchema
 });
 var createPersonalApiKeyRequestSchema = keyFieldsSchema;
-var createPersonalApiKeyResponseSchema = z31.object({
+var createPersonalApiKeyResponseSchema = z32.object({
   key: personalApiKeySchema,
   /** The key, shown this once. Only its hash is stored. */
-  secret: z31.string()
+  secret: z32.string()
 });
-var startConnectCodeRequestSchema = z31.object({
+var startConnectCodeRequestSchema = z32.object({
   /** What the CLI calls itself, shown to the person who confirms. Attribution, never authority. */
-  clientLabel: z31.string().trim().min(1).max(100).optional()
+  clientLabel: z32.string().trim().min(1).max(100).optional()
 });
-var startConnectCodeResponseSchema = z31.object({
+var startConnectCodeResponseSchema = z32.object({
   /** The code the person confirms in Settings, as `ABCD-EFGH`. */
-  userCode: z31.string(),
+  userCode: z32.string(),
   /** The CLI's own code to collect the key with. It never leaves the CLI. */
-  deviceCode: z31.string(),
+  deviceCode: z32.string(),
   expiresAt: timestampSchema,
   /** How long the CLI waits between two collection tries. */
-  intervalSeconds: z31.number().int().positive(),
+  intervalSeconds: z32.number().int().positive(),
   /** Where the person confirms the code, relative to the interface's address. */
-  confirmPath: z31.string()
+  confirmPath: z32.string()
 });
-var redeemConnectCodeRequestSchema = z31.object({
-  deviceCode: z31.string().min(1).max(200)
+var redeemConnectCodeRequestSchema = z32.object({
+  deviceCode: z32.string().min(1).max(200)
 });
-var redeemConnectCodeResponseSchema = z31.discriminatedUnion("status", [
+var redeemConnectCodeResponseSchema = z32.discriminatedUnion("status", [
   /** Not yet confirmed: try again after the interval. */
-  z31.object({ status: z31.literal("pending") }),
-  z31.object({
-    status: z31.literal("issued"),
+  z32.object({ status: z32.literal("pending") }),
+  z32.object({
+    status: z32.literal("issued"),
     key: personalApiKeySchema,
     /** The key, answered this once. Only its hash is stored. */
-    secret: z31.string()
+    secret: z32.string()
   })
 ]);
-var connectCodeSchema = z31.object({
-  clientLabel: z31.string().optional(),
+var connectCodeSchema = z32.object({
+  clientLabel: z32.string().optional(),
   createdAt: timestampSchema,
   expiresAt: timestampSchema
 });
 var confirmConnectCodeRequestSchema = keyFieldsSchema;
 
 // ../api-contract/src/operations/personal-api-keys.ts
-var confirmedConnectCodeSchema = z32.object({ confirmed: z32.literal(true) });
+var confirmedConnectCodeSchema = z33.object({ confirmed: z33.literal(true) });
 var personalApiKeyOperations = {
   "me.api_keys.list": defineOperation({
     id: "me.api_keys.list",
@@ -6044,73 +6229,99 @@ var personalApiKeyOperations = {
 };
 
 // ../api-contract/src/platform.ts
-import { z as z33 } from "zod";
-var platformAssetKindSchema = z33.object({
-  kind: z33.string(),
-  plural: z33.string(),
+import { z as z34 } from "zod";
+var platformAssetKindSchema = z34.object({
+  kind: z34.string(),
+  plural: z34.string(),
   /**
    * `active`: the newest write is what the kind's users are served. `draft_published`: a write
    * moves a draft, and `assets.publish` moves what its users are served.
    */
-  lifecycle: z33.enum(["active", "draft_published"]),
+  lifecycle: z34.enum(["active", "draft_published"]),
   /** `config`: a revision is its config. `files`: a revision holds a set of files beside it. */
-  representation: z33.enum(["config", "files"]),
-  actions: z33.object({
-    read: z33.string(),
-    write: z33.string(),
-    delete: z33.string(),
+  representation: z34.enum(["config", "files"]),
+  /**
+   * Who may own an asset of the kind: the instance, a workspace, or either. An asset a
+   * workspace owns is read and written by naming that workspace.
+   */
+  owners: z34.array(z34.enum(["instance", "workspace"])),
+  actions: z34.object({
+    read: z34.string(),
+    write: z34.string(),
+    delete: z34.string(),
     /** Named by a kind with the lifecycle `draft_published`. */
-    publish: z33.string().optional(),
+    publish: z34.string().optional(),
     /**
      * Only for a kind whose assets are used through a right of their own: a Connection, or a
      * kind whose published revision has users of its own.
      */
-    use: z33.string().optional()
+    use: z34.string().optional()
   }),
   /**
    * The rights of the kind a service principal can be granted, each on one named asset. Left
    * out for a kind that has none. `permissions.grant` hands out these and no other.
    */
-  principalActions: z33.array(z33.string()).optional(),
+  principalActions: z34.array(z34.string()).optional(),
   /** The file of a `files` kind that holds its manifest. */
-  manifestFile: z33.string().optional(),
+  manifestFile: z34.string().optional(),
   /** What a write of a `files` kind is held to, by the names of the limits. */
-  limits: z33.object({
-    FILE_SET_MAX_FILES: z33.number().int().positive(),
-    FILE_SET_MAX_FILE_BYTES: z33.number().int().positive(),
-    FILE_SET_MAX_TOTAL_BYTES: z33.number().int().positive(),
-    ASSET_PUT_FILES_MAX_BYTES: z33.number().int().positive(),
-    ASSET_GET_FILES_MAX_BYTES: z33.number().int().positive()
+  limits: z34.object({
+    FILE_SET_MAX_FILES: z34.number().int().positive(),
+    FILE_SET_MAX_FILE_BYTES: z34.number().int().positive(),
+    FILE_SET_MAX_TOTAL_BYTES: z34.number().int().positive(),
+    ASSET_PUT_FILES_MAX_BYTES: z34.number().int().positive(),
+    ASSET_GET_FILES_MAX_BYTES: z34.number().int().positive()
   }).optional()
 });
-var platformContextNamespaceSchema = z33.object({
-  prefix: z33.string(),
-  displayName: z33.string(),
-  actions: z33.array(z33.string())
+var platformContextNamespaceSchema = z34.object({
+  prefix: z34.string(),
+  displayName: z34.string(),
+  actions: z34.array(z34.string())
 });
-var platformContextSchema = z33.object({
-  instance: z33.object({ id: z33.string(), name: z33.string() }),
-  release: z33.object({ version: z33.string() }),
-  kinds: z33.array(platformAssetKindSchema),
+var platformContextWorkspaceSchema = z34.object({
+  id: z34.string(),
+  name: z34.string(),
+  kind: z34.enum(["personal", "shared"]),
+  /** The caller is a member: a new agent it makes there starts offered there. */
+  member: z34.boolean(),
+  actions: z34.array(z34.string())
+});
+var platformContextSchema = z34.object({
+  instance: z34.object({ id: z34.string(), name: z34.string() }),
+  release: z34.object({
+    version: z34.string(),
+    /**
+     * The version of `@work-shape/catalyst-cli` on npm that connects a local agent to this
+     * instance. Absent while none is published for it.
+     */
+    cliVersion: z34.string().optional()
+  }),
+  kinds: z34.array(platformAssetKindSchema),
   /**
    * The actions of the listed kinds the caller can use on the instance's own assets as a
    * whole, whatever their names. A right in one Namespace or on one asset is not among them.
    */
-  actions: z33.array(z33.string()),
+  actions: z34.array(z34.string()),
   /**
    * The read actions of the listed kinds a grant allows the caller on one asset or on what one
    * workspace owns. Which assets those are, the kind's list says: a deny or a deleted asset can
    * leave it empty.
    */
-  assetActions: z33.array(z33.string()),
-  namespaces: z33.array(platformContextNamespaceSchema),
+  assetActions: z34.array(z34.string()),
+  namespaces: z34.array(platformContextNamespaceSchema),
+  /**
+   * The workspaces whose own assets the caller can use an action of a listed kind on, each
+   * with those actions: through a membership, a grant on the workspace or a right on the
+   * whole instance. A workspace where the caller can use none is left out.
+   */
+  workspaces: z34.array(platformContextWorkspaceSchema),
   /**
    * The section rows of the interface's sidebar that are there for the caller, of those that
    * belong to no workspace. `workflows`: the module is on, and the caller is listed at least
    * one Workflow by `workflows.list` or holds `workflow.write` on the instance, in a Namespace
    * or on one Workflow. A member is never shown an empty row; whoever may build one is.
    */
-  visibleSections: z33.array(z33.enum(["workflows"]))
+  visibleSections: z34.array(z34.enum(["workflows"]))
 });
 
 // ../api-contract/src/operations/platform.ts
@@ -6184,32 +6395,32 @@ var referenceOperations = {
 };
 
 // ../api-contract/src/system.ts
-import { z as z34 } from "zod";
-var healthSchema = z34.object({
-  status: z34.literal("ok"),
-  clientInstanceId: z34.string(),
+import { z as z35 } from "zod";
+var healthSchema = z35.object({
+  status: z35.literal("ok"),
+  clientInstanceId: z35.string(),
   time: timestampSchema
 });
-var readySchema = z34.object({
-  status: z34.literal("ready"),
+var readySchema = z35.object({
+  status: z35.literal("ready"),
   /** The newest migration of this release. */
-  migration: z34.string()
+  migration: z35.string()
 });
-var notReadySchema = z34.object({
-  status: z34.literal("not_ready"),
-  reason: z34.enum(["database_unreachable", "database_behind"]),
-  missing: z34.array(z34.string()).optional()
+var notReadySchema = z35.object({
+  status: z35.literal("not_ready"),
+  reason: z35.enum(["database_unreachable", "database_behind"]),
+  missing: z35.array(z35.string()).optional()
 });
-var readinessSchema = z34.discriminatedUnion("status", [readySchema, notReadySchema]);
-var capturedMailSchema = z34.object({
-  id: z34.string(),
-  to: z34.object({
-    email: z34.string(),
-    displayLabel: z34.string().optional()
+var readinessSchema = z35.discriminatedUnion("status", [readySchema, notReadySchema]);
+var capturedMailSchema = z35.object({
+  id: z35.string(),
+  to: z35.object({
+    email: z35.string(),
+    displayLabel: z35.string().optional()
   }),
-  subject: z34.string(),
-  text: z34.string(),
-  html: z34.string(),
+  subject: z35.string(),
+  text: z35.string(),
+  html: z35.string(),
   sentAt: timestampSchema
 });
 
@@ -6442,9 +6653,9 @@ var userOperations = {
 };
 
 // ../api-contract/src/operations/workflows.ts
-import { z as z35 } from "zod";
+import { z as z36 } from "zod";
 var WORKFLOW_RUN_OUTPUT_PREVIEW_MAX_CHARS = 2e3;
-var runStatusSchema = z35.enum([
+var runStatusSchema = z36.enum([
   "queued",
   "running",
   "waiting",
@@ -6453,8 +6664,8 @@ var runStatusSchema = z35.enum([
   "cancelled",
   "limit_reached"
 ]);
-var stepRunStatusSchema = z35.enum(["queued", "running", "waiting", "done", "failed", "cancelled"]);
-var stepTypeSchema = z35.enum([
+var stepRunStatusSchema = z36.enum(["queued", "running", "waiting", "done", "failed", "cancelled"]);
+var stepTypeSchema = z36.enum([
   "trigger",
   "operation",
   "loop",
@@ -6466,50 +6677,50 @@ var stepTypeSchema = z35.enum([
   "condition",
   "parallel"
 ]);
-var countsSchema = z35.object({
-  total: z35.number().int().min(0),
-  done: z35.number().int().min(0),
-  failed: z35.number().int().min(0),
-  running: z35.number().int().min(0)
+var countsSchema = z36.object({
+  total: z36.number().int().min(0),
+  done: z36.number().int().min(0),
+  failed: z36.number().int().min(0),
+  running: z36.number().int().min(0)
 });
-var workflowRunErrorSchema = z35.object({
+var workflowRunErrorSchema = z36.object({
   /** A code of the engine, or the code of the refusal or failure of the step's operation. */
-  code: z35.string(),
+  code: z36.string(),
   /** A sentence of the product. Never a value of the run and never text of an outside system. */
-  message: z35.string(),
+  message: z36.string(),
   /** Where the run's principal was refused for a right it does not hold: that right. */
-  action: z35.string().optional(),
+  action: z36.string().optional(),
   /** On a run: the step run it ended at. */
-  stepRunId: z35.string().optional()
+  stepRunId: z36.string().optional()
 });
-var workflowOutputPreviewSchema = z35.object({
+var workflowOutputPreviewSchema = z36.object({
   /** The start of the value as JSON. */
-  text: z35.string().max(WORKFLOW_RUN_OUTPUT_PREVIEW_MAX_CHARS),
-  truncated: z35.boolean()
+  text: z36.string().max(WORKFLOW_RUN_OUTPUT_PREVIEW_MAX_CHARS),
+  truncated: z36.boolean()
 });
-var workflowRunSchema = z35.object({
-  id: z35.string(),
-  workflow: z35.string(),
+var workflowRunSchema = z36.object({
+  id: z36.string(),
+  workflow: z36.string(),
   /** The revision of the definition the run started on and keeps to its end. */
-  definitionRevisionId: z35.string(),
-  mode: z35.enum(["live", "test"]),
-  trigger: z35.enum(["manual", "schedule", "parent"]),
+  definitionRevisionId: z36.string(),
+  mode: z36.enum(["live", "test"]),
+  trigger: z36.enum(["manual", "schedule", "parent"]),
   status: runStatusSchema,
   /**
    * The service principal the run acts as. Its rights are the rights of every step. A test run
    * (`mode: test`) acts as the person who started it, bounded by this principal.
    */
-  principal: z35.object({ id: z35.string(), name: z35.string(), displayLabel: z35.string() }),
-  startedBy: z35.object({
-    kind: z35.enum(["user", "service_principal"]),
-    id: z35.string(),
-    label: z35.string()
+  principal: z36.object({ id: z36.string(), name: z36.string(), displayLabel: z36.string() }),
+  startedBy: z36.object({
+    kind: z36.enum(["user", "service_principal"]),
+    id: z36.string(),
+    label: z36.string()
   }),
   /** The due time of the schedule that started the run. Missing on every other run. */
   scheduledFor: timestampSchema.optional(),
   /** The Operation Run of the call that started the run. */
-  operationRunId: z35.string().optional(),
-  stepRunCount: z35.number().int().min(0),
+  operationRunId: z36.string().optional(),
+  stepRunCount: z36.number().int().min(0),
   /** After this moment no further step starts and the run ends as `limit_reached`. */
   deadlineAt: timestampSchema,
   error: workflowRunErrorSchema.optional(),
@@ -6518,7 +6729,7 @@ var workflowRunSchema = z35.object({
   startedAt: timestampSchema.optional(),
   finishedAt: timestampSchema.optional(),
   /** The person who cancelled the run. Missing where a service principal did, and on a run nobody cancelled. */
-  cancelledBy: z35.string().optional(),
+  cancelledBy: z36.string().optional(),
   cancelledAt: timestampSchema.optional(),
   /**
    * When the values of the run were removed: its input and result, and the inputs and outputs
@@ -6526,98 +6737,98 @@ var workflowRunSchema = z35.object({
    */
   dataPrunedAt: timestampSchema.optional()
 });
-var workflowStepRunSchema = z35.object({
-  id: z35.string(),
-  runId: z35.string(),
-  stepId: z35.string(),
+var workflowStepRunSchema = z36.object({
+  id: z36.string(),
+  runId: z36.string(),
+  stepId: z36.string(),
   stepType: stepTypeSchema,
   /** The step's path in the run, such as `each_client[3].bookings`. */
-  key: z35.string(),
+  key: z36.string(),
   /** The step run of the block that holds the step: today a loop. */
-  containerStepRunId: z35.string().optional(),
+  containerStepRunId: z36.string().optional(),
   /** The branch of that block the step stands in. No block with branches runs yet. */
-  branch: z35.string().optional(),
+  branch: z36.string().optional(),
   /** Which item of that loop, from 0, and what the loop's `itemLabel` field holds for it. */
-  iteration: z35.object({ index: z35.number().int().min(0), label: z35.string().optional() }).optional(),
+  iteration: z36.object({ index: z36.number().int().min(0), label: z36.string().optional() }).optional(),
   /** On the step run of a loop: how many items it has and how far they are. */
   loop: countsSchema.optional(),
   /** On the step run of a loop: how the step runs of each step directly inside it stand, by step id. */
-  bodyCounts: z35.record(z35.string(), countsSchema).optional(),
+  bodyCounts: z36.record(z36.string(), countsSchema).optional(),
   /**
    * On the step run of a loop: how many of its items run at once. `asked` is the loop's
    * `concurrency`, an upper bound; `ranWith` is what one process runs of it, which the step
    * slots of a process bound.
    */
-  concurrency: z35.object({ asked: z35.number().int().min(1), ranWith: z35.number().int().min(1) }).optional(),
+  concurrency: z36.object({ asked: z36.number().int().min(1), ranWith: z36.number().int().min(1) }).optional(),
   /** On the step run of an operation step: what its operation does and what it belongs to. */
-  effect: z35.enum(["reading", "changing"]).optional(),
-  source: z35.string().optional(),
+  effect: z36.enum(["reading", "changing"]).optional(),
+  source: z36.string().optional(),
   /**
    * On the step run of an operation step: where its call went (ADR-0031). `live` on every step
    * of a run of the published revision; in a test run `dry_run` for a changing step that was
    * simulated, `test` for a call to a test target, `live` for a read and for "Run live once".
    */
-  target: z35.enum(["live", "test", "dry_run"]).optional(),
+  target: z36.enum(["live", "test", "dry_run"]).optional(),
   /**
    * On a step run of a test run: the tester's start satisfied the step's `confirm`, and a run
    * of the published revision asks for an approval here.
    */
-  publishedWouldAsk: z35.enum(["approval"]).optional(),
+  publishedWouldAsk: z36.enum(["approval"]).optional(),
   /**
    * On the step run of a code step that ran: what its script wrote to its output and error
    * streams beside its result, each cut to 16 KiB.
    */
-  log: z35.object({ stdout: z35.string(), stderr: z35.string(), truncated: z35.boolean() }).optional(),
+  log: z36.object({ stdout: z36.string(), stderr: z36.string(), truncated: z36.boolean() }).optional(),
   status: stepRunStatusSchema,
-  attempt: z35.number().int().min(0),
+  attempt: z36.number().int().min(0),
   /** The Operation Run of the call an operation step made. */
-  operationRunId: z35.string().optional(),
+  operationRunId: z36.string().optional(),
   error: workflowRunErrorSchema.optional(),
   outputPreview: workflowOutputPreviewSchema.optional(),
   createdAt: timestampSchema,
   startedAt: timestampSchema.optional(),
   finishedAt: timestampSchema.optional()
 });
-var startWorkflowRunRequestSchema = z35.object({
+var startWorkflowRunRequestSchema = z36.object({
   /** The input of the run, checked against the `inputs` of the Workflow's definition. */
-  input: z35.record(z35.string(), z35.unknown()).optional()
+  input: z36.record(z36.string(), z36.unknown()).optional()
 });
 var listWorkflowStepRunsQuerySchema = listQuerySchema.extend({
-  topLevel: z35.enum(["true", "false"]).optional(),
-  containerStepRunId: z35.string().min(1).optional(),
+  topLevel: z36.enum(["true", "false"]).optional(),
+  containerStepRunId: z36.string().min(1).optional(),
   status: stepRunStatusSchema.optional(),
-  iteration: z35.coerce.number().int().min(0).optional()
+  iteration: z36.coerce.number().int().min(0).optional()
 });
-var workflowStartIssueSchema = z35.object({
-  code: z35.string(),
+var workflowStartIssueSchema = z36.object({
+  code: z36.string(),
   /** A sentence of the product. Never a value of a run. */
-  message: z35.string(),
+  message: z36.string(),
   /** Where in the definition it is, such as `steps.check.type`. */
-  path: z35.string().optional()
+  path: z36.string().optional()
 });
-var workflowSummarySchema = z35.object({
-  id: z35.string(),
-  name: z35.string(),
-  description: z35.string().optional(),
+var workflowSummarySchema = z36.object({
+  id: z36.string(),
+  name: z36.string(),
+  description: z36.string().optional(),
   /** The published revision: what a run started now has as its `definitionRevisionId`. */
-  definitionRevisionId: z35.string(),
+  definitionRevisionId: z36.string(),
   /** Whether a start by hand is accepted now, as far as that is known before its input. */
-  runnable: z35.boolean(),
+  runnable: z36.boolean(),
   /** Why not. Empty exactly where `runnable` is true. */
-  reasons: z35.array(workflowStartIssueSchema),
+  reasons: z36.array(workflowStartIssueSchema),
   /**
    * The published revision's `inputs`: the JSON Schema a start's `input` is checked against,
    * from which a page builds its start form. Missing where the definition cannot be read.
    */
-  inputs: z35.record(z35.string(), z35.unknown()).optional(),
+  inputs: z36.record(z36.string(), z36.unknown()).optional(),
   /**
    * What the caller may do with this Workflow, of `workflow.read` (its runs) and `workflow.use`
    * (a start). Never empty: a Workflow the caller holds neither on is not listed.
    */
-  actions: z35.array(z35.string()),
+  actions: z36.array(z36.string()),
   /** The latest run of the Workflow. Missing on one that never ran. */
-  lastRun: z35.object({
-    id: z35.string(),
+  lastRun: z36.object({
+    id: z36.string(),
     status: runStatusSchema,
     startedAt: timestampSchema.optional(),
     endedAt: timestampSchema.optional()
@@ -6634,7 +6845,7 @@ var workflowOperations = {
     scope: "config_assets:read",
     requires: [],
     effect: "reading",
-    response: json(z35.object({ items: z35.array(workflowSummarySchema) })),
+    response: json(z36.object({ items: z36.array(workflowSummarySchema) })),
     errors: [],
     rateClass: "read"
   }),
@@ -6747,6 +6958,7 @@ var apiOperations = {
   ...guardrailOperations,
   ...workflowOperations,
   ...dataStoreOperations,
+  ...knowledgeOperations,
   ...userOperations,
   ...apiAccessOperations,
   ...personalApiKeyOperations,
@@ -6757,11 +6969,20 @@ var apiOperations = {
   ...systemOperations
 };
 
+// ../api-contract/src/openapi.ts
+var RELEASE_VERSION = package_default.version;
+var API_ERROR_CODE_ORDER = appErrorCodeSchema.options;
+
+// src/asset-commands.ts
+import { readFile as readFile5 } from "fs/promises";
+import { resolve as resolve5 } from "path";
+import { parseArgs } from "util";
+
 // src/api.ts
 import { randomUUID } from "crypto";
 
 // ../api-client/src/errors.ts
-import { z as z36 } from "zod";
+import { z as z38 } from "zod";
 var ApiError = class extends Error {
   status;
   code;
@@ -6828,7 +7049,7 @@ function readCorrelationId(payload) {
   return error && "correlationId" in error && typeof error.correlationId === "string" ? error.correlationId : void 0;
 }
 function readRetryAfterSeconds(payload) {
-  const parsed = z36.object({ error: z36.object({ details: rateLimitedDetailsSchema }) }).safeParse(payload);
+  const parsed = z38.object({ error: z38.object({ details: rateLimitedDetailsSchema }) }).safeParse(payload);
   return parsed.success ? parsed.data.error.details.retryAfterSeconds : void 0;
 }
 
@@ -7091,6 +7312,7 @@ async function createConfigApi(options) {
     fetchImpl
   });
   const sleep = options.sleep ?? defaultSleep;
+  const scope = options.workspaceId === void 0 ? {} : { workspaceId: options.workspaceId };
   const change = async (request, unanswered) => {
     const idempotencyKey2 = randomUUID();
     for (let attempt = 1; ; attempt += 1) {
@@ -7132,7 +7354,11 @@ async function createConfigApi(options) {
           sleep,
           () => client.assets.list({
             params: { kind },
-            query: { limit: MAX_LIST_LIMIT, ...cursor === void 0 ? {} : { cursor } }
+            query: {
+              limit: MAX_LIST_LIMIT,
+              ...scope,
+              ...cursor === void 0 ? {} : { cursor }
+            }
           })
         );
         assets.push(...page2.items);
@@ -7143,7 +7369,10 @@ async function createConfigApi(options) {
     /** One asset with its content, or nothing where the instance holds none of that name. */
     getAsset: async (kind, name) => {
       try {
-        return await read(sleep, () => client.assets.get({ params: { kind, name } }));
+        return await read(
+          sleep,
+          () => client.assets.get({ params: { kind, name }, query: { ...scope } })
+        );
       } catch (error) {
         if (isMissingAsset(error)) return void 0;
         throw error;
@@ -7153,7 +7382,7 @@ async function createConfigApi(options) {
     getLatestRevision: async (kind, name) => {
       const page2 = await read(
         sleep,
-        () => client.assets.revisions.list({ params: { kind, name }, query: { limit: 1 } })
+        () => client.assets.revisions.list({ params: { kind, name }, query: { limit: 1, ...scope } })
       );
       return page2.items[0];
     },
@@ -7222,8 +7451,8 @@ function withoutRedirects(fetchImpl) {
 function instanceFetch(fetchImpl) {
   return withoutRedirects(fetchImpl ?? fetch);
 }
-function isLoopbackHostname(hostname2) {
-  return hostname2 === "localhost" || hostname2 === "::1" || hostname2 === "[::1]" || /^127(?:\.\d{1,3}){3}$/u.test(hostname2);
+function isLoopbackHostname(hostname3) {
+  return hostname3 === "localhost" || hostname3 === "::1" || hostname3 === "[::1]" || /^127(?:\.\d{1,3}){3}$/u.test(hostname3);
 }
 async function exchangeApiKey(fetchImpl, baseUrl, apiKey) {
   try {
@@ -7278,8 +7507,8 @@ function redactSecret(message, secret) {
 }
 
 // src/asset-sources.ts
-import { readFile as readFile3, stat as stat2 } from "fs/promises";
-import { basename, dirname as dirname2, extname, join as join2, relative as relative2, resolve as resolve2, sep as sep2 } from "path";
+import { readFile as readFile4, stat as stat3 } from "fs/promises";
+import { basename, dirname as dirname3, extname, join as join3, relative as relative2, resolve as resolve3, sep as sep2 } from "path";
 
 // src/guardrail-files.ts
 import { readFile, stat } from "fs/promises";
@@ -7353,9 +7582,90 @@ function isRecord2(value) {
 }
 
 // src/working-copy.ts
-import { mkdir, readFile as readFile2, readdir, rename, rm, rmdir, writeFile } from "fs/promises";
-import { dirname, isAbsolute, relative, resolve, sep } from "path";
+import { mkdir as mkdir2, readFile as readFile3, readdir, rename as rename2, rm, rmdir, writeFile as writeFile2 } from "fs/promises";
+import { dirname as dirname2, isAbsolute, relative, resolve as resolve2, sep } from "path";
 import yaml3 from "js-yaml";
+
+// src/credentials.ts
+import { chmod, mkdir, readFile as readFile2, rename, stat as stat2, writeFile } from "fs/promises";
+import { homedir } from "os";
+import { dirname, join as join2, resolve } from "path";
+var CREDENTIALS_FILENAME = "credentials.json";
+function credentialsPath(env) {
+  const folder = env.CATALYST_CONFIG_HOME ?? join2(env.XDG_CONFIG_HOME ?? join2(homedir(), ".config"), "catalyst");
+  return resolve(folder, CREDENTIALS_FILENAME);
+}
+function credentialOrigin(url) {
+  return new URL(url).origin;
+}
+async function readStoredCredential(env, url) {
+  return (await readCredentialFile(credentialsPath(env))).instances[credentialOrigin(url)];
+}
+async function savedInstanceOrigins(env) {
+  return Object.keys((await readCredentialFile(credentialsPath(env))).instances);
+}
+async function saveCredential(env, url, credential) {
+  const path = credentialsPath(env);
+  const file = await readCredentialFile(path);
+  file.instances[credentialOrigin(url)] = credential;
+  await writeCredentialFile(path, file);
+  return path;
+}
+async function removeCredential(env, url) {
+  const path = credentialsPath(env);
+  const file = await readCredentialFile(path);
+  const origin = credentialOrigin(url);
+  if (file.instances[origin] === void 0) return false;
+  delete file.instances[origin];
+  await writeCredentialFile(path, file);
+  return true;
+}
+async function readCredentialFile(path) {
+  let contents;
+  try {
+    contents = await readFile2(path, "utf8");
+  } catch (error) {
+    if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+      return { version: 1, instances: {} };
+    }
+    throw error;
+  }
+  if (process.platform !== "win32" && ((await stat2(path)).mode & 63) !== 0) {
+    throw new Error(
+      `${path} can be read by other users of this machine. Run 'chmod 600 ${path}', or remove it and run 'catalyst login' again.`
+    );
+  }
+  const parsed = JSON.parse(contents);
+  if (!isCredentialFile(parsed)) {
+    throw new Error(`${path} is not a credentials file of this CLI. Remove it and log in again.`);
+  }
+  return parsed;
+}
+async function writeCredentialFile(path, file) {
+  await mkdir(dirname(path), { recursive: true, mode: 448 });
+  const temporary = `${path}.${process.pid}.tmp`;
+  await writeFile(temporary, `${JSON.stringify(file, null, 2)}
+`, { mode: 384 });
+  await chmod(temporary, 384);
+  await rename(temporary, path);
+}
+function isCredentialFile(value) {
+  if (typeof value !== "object" || value === null) return false;
+  if (!("version" in value) || value.version !== 1) return false;
+  if (!("instances" in value) || typeof value.instances !== "object" || value.instances === null) {
+    return false;
+  }
+  return Object.values(value.instances).every(
+    (entry) => typeof entry === "object" && entry !== null && "apiKey" in entry && typeof entry.apiKey === "string" && "keyId" in entry && typeof entry.keyId === "string" && "name" in entry && typeof entry.name === "string" && "expiresAt" in entry && typeof entry.expiresAt === "string" && "savedAt" in entry && typeof entry.savedAt === "string"
+  );
+}
+
+// src/env.ts
+function readConfigCliEnv(env) {
+  return env ?? process.env;
+}
+
+// src/working-copy.ts
 var MANIFEST_FILENAME = "catalyst.yaml";
 var STATE_FILENAME = ".catalyst-state.json";
 var WorkingCopyValidationError = class extends Error {
@@ -7383,12 +7693,19 @@ function parseManifest(contents, source = MANIFEST_FILENAME) {
     const namespace = readOptionalString(value, "namespace", `${source} instance '${name}'`);
     if (namespace !== void 0 && !NAMESPACE_PREFIX_PATTERN.test(namespace)) {
       throw new Error(
-        `${source} instance '${name}' names no Namespace prefix: '${namespace}'. A prefix is lowercase words joined by '-' and ends in '-', such as 'kai-'.`
+        `${source} instance '${name}' names no Namespace prefix: '${namespace}'. A prefix is lowercase words joined by '-' and ends in '-', such as 'tax-'.`
+      );
+    }
+    const workspace = readOptionalString(value, "workspace", `${source} instance '${name}'`);
+    if (namespace !== void 0 && workspace !== void 0) {
+      throw new Error(
+        `${source} instance '${name}' names a Namespace and a workspace. A working copy belongs to one of them.`
       );
     }
     instances[name] = {
       url: normalizeUrl(value.url, `${source} instance '${name}'`),
-      ...namespace === void 0 ? {} : { namespace }
+      ...namespace === void 0 ? {} : { namespace },
+      ...workspace === void 0 ? {} : { workspace }
     };
   }
   const defaultInstance = readOptionalString(input, "defaultInstance", source);
@@ -7403,8 +7720,8 @@ function parseManifest(contents, source = MANIFEST_FILENAME) {
   };
 }
 async function readManifest(workingDir) {
-  const path = resolve(workingDir, MANIFEST_FILENAME);
-  return parseManifest(await readFile2(path, "utf8"), path);
+  const path = resolve2(workingDir, MANIFEST_FILENAME);
+  return parseManifest(await readFile3(path, "utf8"), path);
 }
 async function readManifestIfPresent(workingDir) {
   try {
@@ -7414,24 +7731,38 @@ async function readManifestIfPresent(workingDir) {
     throw error;
   }
 }
-function resolveInstance(manifest, requestedInstance) {
-  const key = requestedInstance ?? manifest.defaultInstance;
-  if (!key) {
+async function resolveInstance(manifest, options = {}) {
+  const key = options.instance ?? manifest?.defaultInstance;
+  if (key !== void 0 && key !== "") {
+    const configured = manifest?.instances[key];
+    if (configured) return { key, ...configured };
+    return { key, url: normalizeUrl(key, `Instance '${key}'`) };
+  }
+  const refusal = `No instance selected; pass --instance or set defaultInstance in ${MANIFEST_FILENAME}.`;
+  if (manifest !== void 0) {
+    const names = Object.keys(manifest.instances);
     throw new Error(
-      `No instance selected; pass --instance or set defaultInstance in ${MANIFEST_FILENAME}`
+      names.length === 0 ? refusal : `${refusal} ${MANIFEST_FILENAME} names ${names.join(", ")}.`
     );
   }
-  const configured = manifest.instances[key];
-  if (configured) {
-    return { key, ...configured };
+  if (readConfigCliEnv(options.env).CATALYST_API_KEY) {
+    throw new Error(`${refusal} CATALYST_API_KEY is set: name the instance it belongs to.`);
+  }
+  const saved = await savedInstanceOrigins(readConfigCliEnv(options.env));
+  const [origin, ...more] = saved;
+  if (origin === void 0) {
+    throw new Error(
+      `${refusal} No key is saved; 'catalyst login --instance <https-url>' saves one.`
+    );
   }
-  return { key, url: normalizeUrl(key, `Instance '${key}'`) };
+  if (more.length > 0) throw new Error(`${refusal} Keys are saved for ${saved.join(", ")}.`);
+  return { key: origin, url: origin };
 }
 var ASSET_KEY_PATTERN = /^(agent|skill|guardrail):.+$/u;
 async function readStateFile(path) {
   let contents;
   try {
-    contents = await readFile2(path, "utf8");
+    contents = await readFile3(path, "utf8");
   } catch (error) {
     if (isNodeError(error) && error.code === "ENOENT") {
       return { instances: {} };
@@ -7491,11 +7822,11 @@ async function readStateFile(path) {
   return { instances };
 }
 async function writeStateFile(path, state) {
-  await mkdir(dirname(path), { recursive: true });
+  await mkdir2(dirname2(path), { recursive: true });
   const temporaryPath = `${path}.${process.pid}.tmp`;
-  await writeFile(temporaryPath, `${JSON.stringify(state, null, 2)}
+  await writeFile2(temporaryPath, `${JSON.stringify(state, null, 2)}
 `, "utf8");
-  await rename(temporaryPath, path);
+  await rename2(temporaryPath, path);
 }
 async function readWorkingCopy(workingDir, manifest) {
   const [agentFiles, skillFiles, guardrailFiles] = await Promise.all([
@@ -7510,7 +7841,7 @@ async function readWorkingCopy(workingDir, manifest) {
   for (const path of agentFiles) {
     const file = toRelativePath(workingDir, path);
     try {
-      const input = loadYamlData(await readFile2(path, "utf8"), file);
+      const input = loadYamlData(await readFile3(path, "utf8"), file);
       const parsed = agentConfigSchema.safeParse(input);
       if (parsed.success) {
         agents.push(parsed.data);
@@ -7524,7 +7855,7 @@ async function readWorkingCopy(workingDir, manifest) {
   for (const path of skillFiles) {
     const file = toRelativePath(workingDir, path);
     try {
-      const contents = await readFile2(path, "utf8");
+      const contents = await readFile3(path, "utf8");
       const parsedMarkdown = parseSkillMarkdown(contents, file, toPosixPath(path));
       const resources = await readSkillResources(path);
       const parsed = skillConfigSchema.safeParse(
@@ -7543,7 +7874,7 @@ async function readWorkingCopy(workingDir, manifest) {
   for (const path of guardrailFiles) {
     const file = toRelativePath(workingDir, path);
     try {
-      guardrails.push(await readGuardrailFolder(dirname(path)));
+      guardrails.push(await readGuardrailFolder(dirname2(path)));
     } catch (error) {
       const extracted = extractErrorIssues(file, error);
       issues.push(...extracted.length > 0 ? extracted : [{ file, message: errorMessage(error) }]);
@@ -7583,18 +7914,18 @@ function matchesManifestPath(root, path, patterns) {
 }
 function agentAssetPath(workingDir, name) {
   assertSafeAssetName(name);
-  return resolve(workingDir, "agents", `${name}.agent.yaml`);
+  return resolve2(workingDir, "agents", `${name}.agent.yaml`);
 }
 function skillAssetPath(workingDir, name) {
   assertSafeAssetName(name);
-  return resolve(workingDir, "skills", name, "SKILL.md");
+  return resolve2(workingDir, "skills", name, "SKILL.md");
 }
 function guardrailAssetPath(workingDir, name) {
   assertSafeAssetName(name);
-  return resolve(workingDir, "guardrails", name, GUARDRAIL_FILE);
+  return resolve2(workingDir, "guardrails", name, GUARDRAIL_FILE);
 }
 async function readSkillResources(skillFilePath) {
-  const skillDirectory = dirname(skillFilePath);
+  const skillDirectory = dirname2(skillFilePath);
   const files = [];
   await walkFiles(skillDirectory, skillDirectory, files);
   const resources = [];
@@ -7609,7 +7940,7 @@ async function readSkillResources(skillFilePath) {
         `Unsupported skill resource '${resourcePath}'; supported extensions are .md, .txt, .json, .yaml, and .yml`
       );
     }
-    const bytes = await readFile2(path);
+    const bytes = await readFile3(path);
     let content;
     try {
       content = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
@@ -7634,11 +7965,11 @@ async function removeStaleManifestAssets(workingDir, manifest, desiredPaths) {
       continue;
     }
     if (path.endsWith("/SKILL.md") || path.endsWith(`/${GUARDRAIL_FILE}`)) {
-      await rm(dirname(path), { recursive: true, force: true });
+      await rm(dirname2(path), { recursive: true, force: true });
       continue;
     }
     await rm(path);
-    const parent = dirname(path);
+    const parent = dirname2(path);
     if (parent !== workingDir) {
       try {
         await rmdir(parent);
@@ -7651,7 +7982,7 @@ async function removeStaleManifestAssets(workingDir, manifest, desiredPaths) {
   }
 }
 async function updateManifestDefaultAgent(path, defaultAgentName) {
-  const contents = await readFile2(path, "utf8");
+  const contents = await readFile3(path, "utf8");
   const linePattern = /^defaultAgentName:[^\r\n]*(?:\r?\n|$)/mu;
   let updated;
   if (defaultAgentName === void 0) {
@@ -7669,7 +8000,37 @@ ${line}
 `;
     }
   }
-  await writeFile(path, updated, "utf8");
+  await writeFile2(path, updated, "utf8");
+}
+async function bindManifestWorkspace(path, instanceKey, workspaceId) {
+  const contents = await readFile3(path, "utf8");
+  const lines = contents.split("\n");
+  const keyLine = lines.findIndex((line) => {
+    const match = /^(\s+)(["']?)([^"':]+)\2:\s*(?:#.*)?$/u.exec(line.trimEnd());
+    return match?.[3] === instanceKey;
+  });
+  const keyIndent = keyLine < 0 ? -1 : indentOf(lines[keyLine] ?? "");
+  let urlLine = -1;
+  for (let index = keyLine + 1; keyLine >= 0 && index < lines.length; index += 1) {
+    const line = lines[index] ?? "";
+    if (line.trim() === "" || line.trim().startsWith("#")) continue;
+    if (indentOf(line) <= keyIndent) break;
+    if (/^\s+url:/u.test(line)) {
+      urlLine = index;
+      break;
+    }
+  }
+  if (urlLine < 0) {
+    throw new Error(
+      `Cannot bind instance '${instanceKey}' in ${MANIFEST_FILENAME}: add 'workspace: ${workspaceId}' to that instance yourself, beside its url.`
+    );
+  }
+  const entry = yaml3.dump({ workspace: workspaceId }, { lineWidth: -1 }).trimEnd();
+  lines.splice(urlLine + 1, 0, `${" ".repeat(indentOf(lines[urlLine] ?? ""))}${entry}`);
+  await writeFile2(path, lines.join("\n"), "utf8");
+}
+function indentOf(line) {
+  return line.length - line.trimStart().length;
 }
 async function walkFiles(root, directory, output) {
   let entries;
@@ -7682,7 +8043,7 @@ async function walkFiles(root, directory, output) {
     throw error;
   }
   for (const entry of entries) {
-    const path = resolve(directory, entry.name);
+    const path = resolve2(directory, entry.name);
     if (entry.isDirectory()) {
       if (directory === root && [".git", "node_modules"].includes(entry.name)) {
         continue;
@@ -7697,7 +8058,7 @@ function globSearchRoot(root, pattern) {
   const wildcardIndex = pattern.search(/[?*]/u);
   const fixedPart = wildcardIndex === -1 ? pattern : pattern.slice(0, wildcardIndex);
   const slashIndex = fixedPart.lastIndexOf("/");
-  return resolve(root, slashIndex === -1 ? "." : fixedPart.slice(0, slashIndex));
+  return resolve2(root, slashIndex === -1 ? "." : fixedPart.slice(0, slashIndex));
 }
 function globPatternToRegExp(pattern) {
   let source = "^";
@@ -7799,9 +8160,9 @@ async function readAssetSource(path, representation) {
   return representation === "files" ? { files: await readFileSet(path) } : { config: await readDefinition(path) };
 }
 async function readDefinition(path) {
-  const folder = (await stat2(path)).isDirectory();
-  const guardrailFolder = folder ? path : basename(path) === GUARDRAIL_FILE ? dirname2(path) : void 0;
-  if (guardrailFolder !== void 0 && await stat2(join2(guardrailFolder, GUARDRAIL_FILE)).then(
+  const folder = (await stat3(path)).isDirectory();
+  const guardrailFolder = folder ? path : basename(path) === GUARDRAIL_FILE ? dirname3(path) : void 0;
+  if (guardrailFolder !== void 0 && await stat3(join3(guardrailFolder, GUARDRAIL_FILE)).then(
     (found) => found.isFile(),
     () => false
   )) {
@@ -7811,8 +8172,8 @@ async function readDefinition(path) {
       );
     });
   }
-  const file = folder ? join2(path, SKILL_FILE) : path;
-  const { size } = await stat2(file).catch(() => {
+  const file = folder ? join3(path, SKILL_FILE) : path;
+  const { size } = await stat3(file).catch(() => {
     throw new Error(
       `'${path}' is a folder without a ${SKILL_FILE}. Name the YAML or JSON file of the definition.`
     );
@@ -7822,7 +8183,7 @@ async function readDefinition(path) {
       `'${file}' has ${size} bytes, and a definition holds at most ${ASSET_SYNC_ITEM_MAX_BYTES}.`
     );
   }
-  const contents = await readFile3(file, "utf8");
+  const contents = await readFile4(file, "utf8");
   const definition = await parseDefinition(file, contents).catch((error) => {
     throw new Error(
       `'${file}' cannot be read: ${error instanceof Error ? error.message : String(error)}`
@@ -7843,7 +8204,7 @@ function definitionOfShown(value) {
 async function parseDefinition(file, contents) {
   if (basename(file) === SKILL_FILE) {
     const skill = parseSkillMarkdown(contents, file, file.split(sep2).join("/"));
-    const resources = await readSkillResources(resolve2(file));
+    const resources = await readSkillResources(resolve3(file));
     return resources.length === 0 || typeof skill !== "object" ? skill : { ...skill, resources };
   }
   switch (extname(file).toLowerCase()) {
@@ -7859,7 +8220,7 @@ async function parseDefinition(file, contents) {
   }
 }
 async function readFileSet(directory) {
-  if (!(await stat2(directory)).isDirectory()) {
+  if (!(await stat3(directory)).isDirectory()) {
     throw new Error(
       `'${directory}' is not a folder. An asset of files is written from its folder.`
     );
@@ -7875,7 +8236,7 @@ async function readFileSet(directory) {
     );
   }
   let total = 0;
-  for (const path of paths) total += (await stat2(path)).size;
+  for (const path of paths) total += (await stat3(path)).size;
   if (total > ASSET_PUT_FILES_MAX_BYTES) {
     throw new Error(
       `'${directory}' holds ${total} bytes, and one write carries at most ${ASSET_PUT_FILES_MAX_BYTES}.`
@@ -7883,7 +8244,7 @@ async function readFileSet(directory) {
   }
   const files = [];
   for (const path of paths.sort()) {
-    const bytes = await readFile3(path);
+    const bytes = await readFile4(path);
     const relativePath = relative2(directory, path).split(sep2).join("/");
     const text = utf8Text(bytes);
     files.push(
@@ -7913,6 +8274,10 @@ function formatContext(context) {
     ...context.namespaces.map(
       (namespace) => `  ${namespace.prefix}  ${namespace.displayName}: ${list(namespace.actions)}`
     ),
+    context.workspaces.length === 0 ? "Workspaces: none" : "Workspaces:",
+    ...context.workspaces.map(
+      (workspace) => `  ${workspace.id}  ${workspace.name}: ${list(workspace.actions)}`
+    ),
     `Kinds: ${context.kinds.map((kind) => kind.kind).join(", ")}`
   ].join("\n");
 }
@@ -8052,82 +8417,6 @@ function isRecord4(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
-// src/credentials.ts
-import { chmod, mkdir as mkdir2, readFile as readFile4, rename as rename2, stat as stat3, writeFile as writeFile2 } from "fs/promises";
-import { homedir } from "os";
-import { dirname as dirname3, join as join3, resolve as resolve3 } from "path";
-var CREDENTIALS_FILENAME = "credentials.json";
-function credentialsPath(env) {
-  const folder = env.CATALYST_CONFIG_HOME ?? join3(env.XDG_CONFIG_HOME ?? join3(homedir(), ".config"), "catalyst");
-  return resolve3(folder, CREDENTIALS_FILENAME);
-}
-function credentialOrigin(url) {
-  return new URL(url).origin;
-}
-async function readStoredCredential(env, url) {
-  return (await readCredentialFile(credentialsPath(env))).instances[credentialOrigin(url)];
-}
-async function saveCredential(env, url, credential) {
-  const path = credentialsPath(env);
-  const file = await readCredentialFile(path);
-  file.instances[credentialOrigin(url)] = credential;
-  await writeCredentialFile(path, file);
-  return path;
-}
-async function removeCredential(env, url) {
-  const path = credentialsPath(env);
-  const file = await readCredentialFile(path);
-  const origin = credentialOrigin(url);
-  if (file.instances[origin] === void 0) return false;
-  delete file.instances[origin];
-  await writeCredentialFile(path, file);
-  return true;
-}
-async function readCredentialFile(path) {
-  let contents;
-  try {
-    contents = await readFile4(path, "utf8");
-  } catch (error) {
-    if (error instanceof Error && "code" in error && error.code === "ENOENT") {
-      return { version: 1, instances: {} };
-    }
-    throw error;
-  }
-  if (process.platform !== "win32" && ((await stat3(path)).mode & 63) !== 0) {
-    throw new Error(
-      `${path} can be read by other users of this machine. Run 'chmod 600 ${path}', or remove it and run 'catalyst login' again.`
-    );
-  }
-  const parsed = JSON.parse(contents);
-  if (!isCredentialFile(parsed)) {
-    throw new Error(`${path} is not a credentials file of this CLI. Remove it and log in again.`);
-  }
-  return parsed;
-}
-async function writeCredentialFile(path, file) {
-  await mkdir2(dirname3(path), { recursive: true, mode: 448 });
-  const temporary = `${path}.${process.pid}.tmp`;
-  await writeFile2(temporary, `${JSON.stringify(file, null, 2)}
-`, { mode: 384 });
-  await chmod(temporary, 384);
-  await rename2(temporary, path);
-}
-function isCredentialFile(value) {
-  if (typeof value !== "object" || value === null) return false;
-  if (!("version" in value) || value.version !== 1) return false;
-  if (!("instances" in value) || typeof value.instances !== "object" || value.instances === null) {
-    return false;
-  }
-  return Object.values(value.instances).every(
-    (entry) => typeof entry === "object" && entry !== null && "apiKey" in entry && typeof entry.apiKey === "string" && "keyId" in entry && typeof entry.keyId === "string" && "name" in entry && typeof entry.name === "string" && "expiresAt" in entry && typeof entry.expiresAt === "string" && "savedAt" in entry && typeof entry.savedAt === "string"
-  );
-}
-
-// src/env.ts
-function readConfigCliEnv(env) {
-  return env ?? process.env;
-}
-
 // src/command-support.ts
 import { createHash } from "crypto";
 import { mkdir as mkdir3, mkdtemp, rename as rename3, rm as rm2, writeFile as writeFile3 } from "fs/promises";
@@ -8264,7 +8553,16 @@ function workingCopyKinds(manifest) {
 }
 var PULL_CONCURRENCY = 8;
 async function readInstanceOverview(api, instance) {
-  return instance.namespace === void 0 ? api.getOverview() : {};
+  return holdsWholeInstance(instance) ? api.getOverview() : {};
+}
+function batchScope(instance) {
+  return {
+    ...instance.namespace === void 0 ? {} : { namespace: instance.namespace },
+    ...instance.workspace === void 0 ? {} : { workspaceId: instance.workspace }
+  };
+}
+function holdsWholeInstance(instance) {
+  return instance.namespace === void 0 && instance.workspace === void 0;
 }
 async function listRemoteAssets(api, kinds) {
   const assets = /* @__PURE__ */ new Map();
@@ -8519,7 +8817,7 @@ function isNodeError2(error) {
 function commandEnv(options) {
   return readConfigCliEnv(options.env);
 }
-async function connectApi(url, options) {
+async function connectApi(url, options, bound = {}) {
   const apiKey = commandEnv(options).CATALYST_API_KEY || (await readStoredCredential(commandEnv(options), url))?.apiKey;
   if (!apiKey) {
     throw new Error(
@@ -8530,7 +8828,8 @@ async function connectApi(url, options) {
     baseUrl: url,
     apiKey,
     ...options.fetchImpl === void 0 ? {} : { fetchImpl: options.fetchImpl },
-    ...options.sleep === void 0 ? {} : { sleep: options.sleep }
+    ...options.sleep === void 0 ? {} : { sleep: options.sleep },
+    ...bound.workspace === void 0 ? {} : { workspaceId: bound.workspace }
   });
 }
 function assetHash(contents) {
@@ -8724,18 +9023,19 @@ var VERBS = {
     }
   },
   validate: {
-    usage: "validate --from <file>",
-    summary: "Check a definition against the instance without writing it (assets.validate)",
+    usage: "validate --from <file-or-folder>",
+    summary: "Check a definition against the instance without writing it (assets.validate); a folder of files is checked against the limits of one write",
     named: false,
     flags: ["from"],
     prepare: (values, _name, cwd) => {
-      const from = fromPath(values, cwd, "--from <file>");
+      const from = fromPath(values, cwd, "--from <file-or-folder>");
       return async (session2) => {
-        const config = await readDefinition(from);
+        const source = await readAssetSource(from, session2.kind.representation);
+        if ("files" in source) return filesRead(session2, from, source.files.length);
         const result = await session2.api.read(
           (client) => client.assets.validate({
             params: { kind: session2.kind.kind },
-            body: { config, ...session2.scope }
+            body: { config: source.config, ...session2.scope }
           })
         );
         writeOut(
@@ -9103,13 +9403,14 @@ ${assetHelpText}`);
       throw new UsageError(`Unexpected argument '${extra[0] ?? name}'.`);
     }
     const call2 = verb.prepare(values, name, options.cwd);
-    const api = await openInstance(options);
+    const { api, workspace } = await openInstance(options);
     const context = await api.read((client) => client.platform.context.get());
+    const workspaceId = values.workspace ?? workspace;
     return await call2({
       api,
       kind: findKind(context.kinds, noun),
       values,
-      scope: values.workspace === void 0 ? {} : { workspaceId: values.workspace },
+      scope: workspaceId === void 0 ? {} : { workspaceId },
       options
     });
   } catch (error) {
@@ -9125,7 +9426,7 @@ ${assetHelpText}`);
   }
 }
 async function runInstanceCommand(command, values, options) {
-  const api = await openInstance(options);
+  const { api } = await openInstance(options);
   const json2 = values.json;
   const out = (value, text) => writeOut(options, json2 ? JSON.stringify(value, null, 2) : text());
   if (command === "references") {
@@ -9140,11 +9441,8 @@ async function runInstanceCommand(command, values, options) {
 }
 async function openInstance(options) {
   const manifest = await readManifestIfPresent(resolveWorkingDir(options));
-  const instance = resolveInstance(
-    manifest ?? { instances: {}, agents: [], skills: [] },
-    options.instance
-  );
-  return connectApi(instance.url, options);
+  const instance = await resolveInstance(manifest, options);
+  return { api: await connectApi(instance.url, options), workspace: instance.workspace };
 }
 function findKind(kinds, noun) {
   const wanted = noun.replaceAll("-", "_");
@@ -9156,6 +9454,18 @@ function findKind(kinds, noun) {
   }
   return kind;
 }
+function filesRead(session2, from, files) {
+  const noun = kindNoun(session2.kind);
+  const draft = session2.kind.lifecycle === "draft_published" ? " as a draft" : "";
+  return print(
+    session2,
+    { files, checkedByInstance: false },
+    () => [
+      `Read ${files} files from '${from}', within what one write carries.`,
+      `The instance checks the files of a ${session2.kind.kind} as it writes them: 'catalyst ${noun} put <name> --from ${from} --if-revision <n|new>' writes them${draft}.`
+    ].join("\n")
+  );
+}
 function settle(session2, outcome, lines) {
   if (outcome.status === "pending_approval") {
     const text = `Waits for an approval on the instance; nothing has changed yet (Operation Run ${outcome.run.id}).`;
@@ -9221,9 +9531,12 @@ ${Object.values(VERBS).map((verb) => `  catalyst <kind> ${verb.usage}
       ${verb.summary}`).join("\n")}
 
 Options:
-  --instance <name-or-url>  An instance of catalyst.yaml, or its URL
+  --instance <name-or-url>  An instance of catalyst.yaml, or its URL. Left out: the
+                            defaultInstance of catalyst.yaml; outside a working copy,
+                            the one instance a key is saved for
   --dir <working-copy-dir>  Directory containing catalyst.yaml (default: .)
-  --workspace <id>          Address the assets one workspace owns
+  --workspace <id>          Address the assets one workspace owns. Left out in a working
+                            copy bound to a workspace: that workspace
   --json                    Print the instance's answer as JSON
   --help                    Show this help
 
@@ -9338,7 +9651,7 @@ import { resolve as resolve6 } from "path";
 async function pushConfig(options) {
   const workingDir = resolveWorkingDir(options);
   const manifest = await readManifest(workingDir);
-  const instance = resolveInstance(manifest, options.instance);
+  const instance = await resolveInstance(manifest, options);
   const local = await readWorkingCopy(workingDir, manifest);
   const selectors = parseOnlySelectors(options.only);
   if (options.prune && selectors.length > 0) {
@@ -9360,7 +9673,7 @@ async function pushConfig(options) {
     );
   }
   const baselineAssets = baseline.assets;
-  const api = await connectApi(instance.url, options);
+  const api = await connectApi(instance.url, options, instance);
   const listing = await listRemoteAssets(api, workingCopyKinds(manifest));
   const touched = assetEntries(bundle).filter(
     (asset) => baselineAssets[asset.key]?.hash !== assetHash(asset.contents)
@@ -9368,7 +9681,7 @@ async function pushConfig(options) {
   const touchedKeys = new Set(touched.map((asset) => asset.key));
   const localKeys = new Set(assetEntries(local).map((asset) => asset.key));
   const deleteAssets = options.prune ? [...listing.values()].filter((asset) => !localKeys.has(asset.key)) : [];
-  const changesDefault = instance.namespace === void 0 && selectors.length === 0 && (bundle.defaultAgentName ?? null) !== baseline.defaultAgentName;
+  const changesDefault = holdsWholeInstance(instance) && selectors.length === 0 && (bundle.defaultAgentName ?? null) !== baseline.defaultAgentName;
   if (changesDefault && baseline.defaultAgentName === void 0) {
     throw new Error(
       "No default-agent baseline is recorded. Run 'catalyst config pull' before changing the default agent."
@@ -9447,7 +9760,7 @@ async function pushConfig(options) {
   }
   if (items.length > 0 || changesDefault) {
     const batch = {
-      ...instance.namespace === void 0 ? {} : { namespace: instance.namespace },
+      ...batchScope(instance),
       items,
       ...changesDefault ? {
         defaultAgentName: bundle.defaultAgentName ?? null,
@@ -9499,6 +9812,7 @@ async function pushConfig(options) {
     baseOf,
     listing,
     afterSync: items.length > 0 || changesDefault,
+    ...instance.workspace === void 0 ? {} : { workspaceId: instance.workspace },
     options
   });
 }
@@ -9538,6 +9852,7 @@ async function syncBatch(api, batch, options) {
 }
 async function writeGuardrails(api, input) {
   const { options } = input;
+  const owner = input.workspaceId === void 0 ? {} : { workspaceId: input.workspaceId };
   let written = input.afterSync;
   const record = (asset, revisions, tombstones = {}) => recordBaseline(
     input.workingDir,
@@ -9555,7 +9870,11 @@ async function writeGuardrails(api, input) {
       const outcome = await api.change(
         (client, idempotencyKey2) => client.assets.put({
           params: { kind: asset.kind, name: asset.name },
-          body: { config: { ...asset.config }, expectedRevision: base?.revision ?? null },
+          body: {
+            config: { ...asset.config },
+            expectedRevision: base?.revision ?? null,
+            ...owner
+          },
           idempotencyKey: idempotencyKey2
         }),
         "It may have been written: run 'catalyst config diff' before pushing again."
@@ -9580,7 +9899,7 @@ async function writeGuardrails(api, input) {
       const outcome = await api.change(
         (client, idempotencyKey2) => client.assets.delete({
           params: { kind: asset.kind, name: asset.name },
-          body: { expectedRevision: base.revision },
+          body: { expectedRevision: base.revision, ...owner },
           idempotencyKey: idempotencyKey2
         }),
         "It may have been applied: run 'catalyst config diff' before pushing again."
@@ -9819,9 +10138,8 @@ async function runConfigCommand(command, options) {
 }
 async function pullConfig(options) {
   const workingDir = resolveWorkingDir(options);
-  const manifest = await readManifest(workingDir);
-  const instance = resolveInstance(manifest, options.instance);
-  const api = await connectApi(instance.url, options);
+  const { manifest, instance } = await bindWorkspace(workingDir, options);
+  const api = await connectApi(instance.url, options, instance);
   const overview = await readInstanceOverview(api, instance);
   const listing = await listRemoteAssets(api, workingCopyKinds(manifest));
   const selectors = parseOnlySelectors(options.only);
@@ -9894,7 +10212,7 @@ async function pullConfig(options) {
       force: true
     });
   }
-  const fullInstancePull = selectors.length === 0 && instance.namespace === void 0;
+  const fullInstancePull = selectors.length === 0 && holdsWholeInstance(instance);
   if (selectors.length === 0) {
     await removeStaleManifestAssets(workingDir, manifest, desiredPaths);
   }
@@ -9921,6 +10239,43 @@ async function pullConfig(options) {
   );
   return 0;
 }
+async function bindWorkspace(workingDir, options) {
+  const manifest = await readManifest(workingDir);
+  const instance = await resolveInstance(manifest, options);
+  const wanted = options.workspace;
+  if (wanted === void 0 || instance.workspace === wanted) return { manifest, instance };
+  if (instance.workspace !== void 0) {
+    throw new Error(
+      `This working copy is bound to workspace '${instance.workspace}'. Pull another workspace into a directory of its own.`
+    );
+  }
+  if (instance.namespace !== void 0) {
+    throw new Error(
+      `This working copy belongs to Namespace '${instance.namespace}'. Pull a workspace into a directory of its own.`
+    );
+  }
+  const baseline = (await readStateFile(resolve7(workingDir, STATE_FILENAME))).instances[instance.key];
+  if (baseline !== void 0) {
+    throw new Error(
+      `This working copy holds the instance's own assets of '${instance.key}'. Pull a workspace into a directory of its own.`
+    );
+  }
+  if (manifest.instances[instance.key] === void 0) {
+    throw new Error(
+      `Name the instance in ${MANIFEST_FILENAME} to bind it to a workspace: '${instance.key}' is not one of its instances.`
+    );
+  }
+  await bindManifestWorkspace(resolve7(workingDir, MANIFEST_FILENAME), instance.key, wanted);
+  const bound = await readManifest(workingDir);
+  const boundInstance = await resolveInstance(bound, options);
+  if (boundInstance.workspace !== wanted) {
+    throw new Error(
+      `Could not bind instance '${instance.key}' in ${MANIFEST_FILENAME}: add 'workspace: ${wanted}' to that instance yourself, beside its url.`
+    );
+  }
+  writeOutput(options, `Bound this working copy to workspace '${wanted}'.`);
+  return { manifest: bound, instance: boundInstance };
+}
 function assetPath(workingDir, kind, name) {
   switch (kind) {
     case "agent":
@@ -9954,9 +10309,9 @@ function assertPullTargetsMatchManifest(workingDir, manifest, targets) {
 async function diffConfig(options) {
   const workingDir = resolveWorkingDir(options);
   const manifest = await readManifest(workingDir);
-  const instance = resolveInstance(manifest, options.instance);
+  const instance = await resolveInstance(manifest, options);
   const local = await readWorkingCopy(workingDir, manifest);
-  const api = await connectApi(instance.url, options);
+  const api = await connectApi(instance.url, options, instance);
   const overview = await readInstanceOverview(api, instance);
   const remoteAssets = await listRemoteAssets(api, workingCopyKinds(manifest));
   const baseline = (await readStateFile(resolve7(workingDir, STATE_FILENAME))).instances[instance.key];
@@ -10015,9 +10370,9 @@ async function diffConfig(options) {
 async function validateConfig(options) {
   const workingDir = resolveWorkingDir(options);
   const manifest = await readManifest(workingDir);
-  const instance = resolveInstance(manifest, options.instance);
+  const instance = await resolveInstance(manifest, options);
   const bundle = await readWorkingCopy(workingDir, manifest);
-  const api = await connectApi(instance.url, options);
+  const api = await connectApi(instance.url, options, instance);
   const listing = await listRemoteAssets(api, workingCopyKinds(manifest));
   const deleted = (await readStateFile(resolve7(workingDir, STATE_FILENAME))).instances[instance.key]?.deleted;
   const items = assetEntries(bundle).filter((asset) => asset.kind !== "guardrail").map((asset) => ({
@@ -10031,6 +10386,7 @@ async function validateConfig(options) {
   try {
     if (items.length > 0 || bundle.defaultAgentName !== void 0) {
       await checkSyncOnThisRelease(api, {
+        ...batchScope(instance),
         items,
         ...bundle.defaultAgentName === void 0 ? {} : { defaultAgentName: bundle.defaultAgentName }
       });
@@ -10049,9 +10405,9 @@ async function validateConfig(options) {
 async function listConfig(options) {
   const workingDir = resolveWorkingDir(options);
   const manifest = await readManifest(workingDir);
-  const instance = resolveInstance(manifest, options.instance);
+  const instance = await resolveInstance(manifest, options);
   const local = await readWorkingCopy(workingDir, manifest);
-  const api = await connectApi(instance.url, options);
+  const api = await connectApi(instance.url, options, instance);
   const version = String((await readInstanceOverview(api, instance)).version ?? "-");
   const remote = await listRemoteAssets(api, workingCopyKinds(manifest));
   const localKeys = new Set(assetEntries(local).map((asset) => asset.key));
@@ -10078,8 +10434,8 @@ async function showConfig(options) {
   }
   const workingDir = resolveWorkingDir(options);
   const manifest = await readManifest(workingDir);
-  const instance = resolveInstance(manifest, options.instance);
-  const api = await connectApi(instance.url, options);
+  const instance = await resolveInstance(manifest, options);
+  const api = await connectApi(instance.url, options, instance);
   const remote = await fetchRemoteAsset(api, options.assetKind, options.assetName);
   if (!remote) {
     throw new Error(`Remote ${options.assetKind} '${options.assetName}' was not found.`);
@@ -10109,61 +10465,75 @@ import { hostname } from "os";
 async function loginCommand(options) {
   try {
     const url = await resolveInstanceUrl(options);
-    assertSafeApiKeyExchangeUrl(url, "receive an API key");
-    const sleep = options.sleep ?? defaultSleep2;
-    const client = createApiClient({
-      baseUrl: url,
-      fetchImpl: instanceFetch(options.fetchImpl)
-    });
-    const started = await call(
-      () => client.connect_codes.start({ body: { clientLabel: `catalyst CLI on ${hostname()}` } })
-    );
+    const key = await loginByConnectCode(options, url, `catalyst CLI on ${hostname()}`);
+    if (key === void 0) {
+      writeError(options, "The code expired before it was confirmed. Run 'catalyst login' again.");
+      return 1;
+    }
     writeOutput(
       options,
       [
-        `Open ${url}${started.confirmPath}`,
-        `and confirm the code ${started.userCode} with the scopes this key may use.`,
-        `Waiting for the confirmation until ${formatTime(started.expiresAt)}\u2026`
+        `Logged in to ${credentialOrigin(url)} with the key '${key.name}' (${key.keyPrefix}\u2026).`,
+        `It may: ${key.scopes.join(", ")}, as far as your rights reach, until ${formatTime(key.expiresAt)}.`,
+        `Saved in ${key.path}. See and revoke it at ${apiKeysAddress(url)}.`
       ].join("\n")
     );
-    const deadline = Date.parse(started.expiresAt);
-    while (Date.now() < deadline) {
-      await sleep(started.intervalSeconds * 1e3);
-      const answer = await call(
-        () => client.connect_codes.redeem({ body: { deviceCode: started.deviceCode } })
-      );
-      if (answer.status === "pending") continue;
-      const path = await saveCredential(readConfigCliEnv(options.env), url, {
-        apiKey: answer.secret,
-        keyId: answer.key.id,
-        name: answer.key.name,
-        expiresAt: answer.key.expiresAt,
-        savedAt: (/* @__PURE__ */ new Date()).toISOString()
-      });
-      writeOutput(
-        options,
-        [
-          `Logged in to ${credentialOrigin(url)} with the key '${answer.key.name}' (${answer.key.keyPrefix}\u2026).`,
-          `It may: ${answer.key.scopes.join(", ")}, as far as your rights reach, until ${formatTime(answer.key.expiresAt)}.`,
-          `Saved in ${path}. Revoke it in Settings, API keys.`
-        ].join("\n")
-      );
-      return 0;
-    }
-    writeError(options, "The code expired before it was confirmed. Run 'catalyst login' again.");
-    return 1;
+    return 0;
   } catch (error) {
     writeError(options, formatCommandError(error));
     return 1;
   }
 }
+async function loginByConnectCode(options, url, clientLabel, openUrl) {
+  assertSafeApiKeyExchangeUrl(url, "receive an API key");
+  const sleep = options.sleep ?? defaultSleep2;
+  const client = createApiClient({
+    baseUrl: url,
+    fetchImpl: instanceFetch(options.fetchImpl)
+  });
+  const started = await call(() => client.connect_codes.start({ body: { clientLabel } }));
+  const address = `${url}${started.confirmPath}`;
+  writeOutput(
+    options,
+    [
+      `Open ${address}`,
+      `and confirm the code ${started.userCode} with the scopes this key may use.`,
+      `Waiting for the confirmation until ${formatTime(started.expiresAt)}\u2026`
+    ].join("\n")
+  );
+  openUrl?.(address);
+  const deadline = Date.parse(started.expiresAt);
+  while (Date.now() < deadline) {
+    await sleep(started.intervalSeconds * 1e3);
+    const answer = await call(
+      () => client.connect_codes.redeem({ body: { deviceCode: started.deviceCode } })
+    );
+    if (answer.status === "pending") continue;
+    const path = await saveCredential(readConfigCliEnv(options.env), url, {
+      apiKey: answer.secret,
+      keyId: answer.key.id,
+      name: answer.key.name,
+      scopes: answer.key.scopes,
+      expiresAt: answer.key.expiresAt,
+      savedAt: (/* @__PURE__ */ new Date()).toISOString()
+    });
+    return {
+      name: answer.key.name,
+      keyPrefix: answer.key.keyPrefix,
+      scopes: answer.key.scopes,
+      expiresAt: answer.key.expiresAt,
+      path
+    };
+  }
+  return void 0;
+}
 async function logoutCommand(options) {
   try {
     const url = await resolveInstanceUrl(options);
     const removed = await removeCredential(readConfigCliEnv(options.env), url);
     writeOutput(
       options,
-      removed ? `Removed the saved key of ${credentialOrigin(url)}. It stays valid until you revoke it in Settings, API keys.` : `No key is saved for ${credentialOrigin(url)}.`
+      removed ? `Removed the saved key of ${credentialOrigin(url)}. It stays valid until you revoke it at ${apiKeysAddress(url)}.` : `No key is saved for ${credentialOrigin(url)}.`
     );
     return 0;
   } catch (error) {
@@ -10176,16 +10546,11 @@ async function resolveInstanceUrl(options) {
   if (requested !== void 0 && /^https?:\/\//u.test(requested)) {
     return requested.replace(/\/+$/u, "");
   }
-  try {
-    return resolveInstance(await readManifest(resolveWorkingDir(options)), requested).url;
-  } catch (error) {
-    if (error instanceof Error && "code" in error && error.code === "ENOENT") {
-      throw new Error(
-        `No ${MANIFEST_FILENAME} here to name the instance. Pass --instance <https-url>.`
-      );
-    }
-    throw error;
-  }
+  const manifest = await readManifestIfPresent(resolveWorkingDir(options));
+  return (await resolveInstance(manifest, options)).url;
+}
+function apiKeysAddress(url) {
+  return `${url}/settings/you/api-keys`;
 }
 async function call(request) {
   try {
@@ -10201,17 +10566,185 @@ function defaultSleep2(milliseconds) {
   return new Promise((resolveSleep) => setTimeout(resolveSleep, milliseconds));
 }
 
+// src/setup.ts
+import { spawn } from "child_process";
+import { createHash as createHash2 } from "crypto";
+import { lstat, mkdir as mkdir5, readFile as readFile6, rename as rename4, rm as rm4, writeFile as writeFile5 } from "fs/promises";
+import { homedir as homedir2, hostname as hostname2 } from "os";
+import { dirname as dirname6, join as join4 } from "path";
+var LOCAL_AGENT_TOOLS = {
+  "claude-code": { label: "Claude Code", skillsFolder: [".claude", "skills"] },
+  // Codex reads `~/.agents/skills`, the shared place for tools other than Claude Code.
+  codex: { label: "Codex", skillsFolder: [".agents", "skills"] },
+  other: { label: "Local agent", skillsFolder: [".agents", "skills"] }
+};
+function isLocalAgentTool(value) {
+  return value !== void 0 && Object.hasOwn(LOCAL_AGENT_TOOLS, value);
+}
+var SETUP_USAGE = "Usage: catalyst setup <claude-code|codex|other> --instance <url> [--force]";
+var SHIPPED_SKILL = new URL("../skills/catalyst/SKILL.md", import.meta.url);
+var MARK = /\n<!-- Written by catalyst setup \(@work-shape\/catalyst-cli [^,]+, sha256 ([0-9a-f]{64})\)\. -->\n$/u;
+function sha256(text) {
+  return createHash2("sha256").update(text).digest("hex");
+}
+async function renderCatalystSkill() {
+  const body = await readFile6(SHIPPED_SKILL, "utf8");
+  return `${body}
+<!-- Written by catalyst setup (@work-shape/catalyst-cli ${RELEASE_VERSION}, sha256 ${sha256(body)}). -->
+`;
+}
+function writtenBySetup(contents) {
+  const mark2 = MARK.exec(contents);
+  return mark2 !== null && sha256(contents.slice(0, mark2.index)) === mark2[1];
+}
+function catalystSkillPath(tool, env) {
+  const folder = tool === "claude-code" && env.CLAUDE_CONFIG_DIR ? join4(env.CLAUDE_CONFIG_DIR, "skills") : join4(env.HOME || homedir2(), ...LOCAL_AGENT_TOOLS[tool].skillsFolder);
+  return join4(folder, "catalyst", "SKILL.md");
+}
+async function setupCommand(options) {
+  try {
+    const url = await resolveInstanceUrl(options);
+    const tool = LOCAL_AGENT_TOOLS[options.tool];
+    const saved = await workingSavedKey(options, url);
+    let keyLine;
+    if (saved) {
+      keyLine = `Kept the saved key '${saved.name}'${scopesOf(saved.scopes)}, valid until ${formatTime(saved.expiresAt)}.`;
+    } else {
+      const key = await loginByConnectCode(
+        options,
+        url,
+        `${tool.label} on ${hostname2()}`,
+        options.openUrl ?? openInBrowser(url)
+      );
+      if (key === void 0) {
+        writeError(
+          options,
+          `The code expired before it was confirmed. Run 'catalyst setup ${options.tool} --instance ${url}' again.`
+        );
+        return 1;
+      }
+      keyLine = `Logged in with the key '${key.name}'${scopesOf(key.scopes)}, valid until ${formatTime(key.expiresAt)}.`;
+    }
+    const path = catalystSkillPath(options.tool, readConfigCliEnv(options.env));
+    const skill = await renderCatalystSkill();
+    const existing = await readSkillFile(path);
+    const lines = [`Instance: ${credentialOrigin(url)}`, keyLine];
+    if (existing === skill) {
+      lines.push(`The Catalyst skill at ${path} is current.`);
+    } else if (existing === void 0 || existing !== NOT_A_FILE && writtenBySetup(existing)) {
+      await replaceFile(path, skill);
+      lines.push(`Wrote the Catalyst skill to ${path}.`);
+    } else if (options.force) {
+      const backup = await freeBackupPath(path);
+      await rename4(path, backup);
+      await replaceFile(path, skill);
+      lines.push(`Wrote the Catalyst skill to ${path}; the file that was there is ${backup}.`);
+    } else {
+      writeOutput(options, lines.join("\n"));
+      writeError(
+        options,
+        `Kept ${path}: it is not the skill this CLI writes. Run the command again with --force to replace it; the file that is there is then kept as ${await freeBackupPath(path)}.`
+      );
+      return 1;
+    }
+    if (options.tool === "other") {
+      lines.push("Point your tool at that file, or copy it to where your tool reads skills.");
+    }
+    lines.push(`See and revoke the key at ${apiKeysAddress(url)}.`);
+    writeOutput(options, lines.join("\n"));
+    return 0;
+  } catch (error) {
+    writeError(options, formatCommandError(error));
+    return 1;
+  }
+}
+var NOT_A_FILE = /* @__PURE__ */ Symbol("not a file");
+async function readSkillFile(path) {
+  const entry = await lstat(path).catch((error) => {
+    if (isMissing(error)) return void 0;
+    throw error;
+  });
+  if (entry === void 0) return void 0;
+  return entry.isFile() ? readFile6(path, "utf8") : NOT_A_FILE;
+}
+async function replaceFile(path, contents) {
+  await mkdir5(dirname6(path), { recursive: true });
+  const temporary = `${path}.${process.pid}.tmp`;
+  await writeFile5(temporary, contents, { flag: "wx" });
+  try {
+    await rename4(temporary, path);
+  } catch (error) {
+    await rm4(temporary, { force: true });
+    throw error;
+  }
+}
+async function freeBackupPath(path) {
+  for (let number = 0; ; number += 1) {
+    const candidate = number === 0 ? `${path}.bak` : `${path}.bak.${number}`;
+    const taken = await lstat(candidate).then(
+      () => true,
+      (error) => {
+        if (isMissing(error)) return false;
+        throw error;
+      }
+    );
+    if (!taken) return candidate;
+  }
+}
+function isMissing(error) {
+  return error instanceof Error && "code" in error && error.code === "ENOENT";
+}
+async function workingSavedKey(options, url) {
+  const saved = await readStoredCredential(readConfigCliEnv(options.env), url);
+  if (saved === void 0 || Date.parse(saved.expiresAt) <= Date.now()) return void 0;
+  try {
+    const api = await createConfigApi({
+      baseUrl: url,
+      apiKey: saved.apiKey,
+      ...options.fetchImpl === void 0 ? {} : { fetchImpl: options.fetchImpl },
+      ...options.sleep === void 0 ? {} : { sleep: options.sleep }
+    });
+    await api.read((client) => client.platform.context.get());
+    return saved;
+  } catch (error) {
+    if (error instanceof ApiKeyExchangeError && (error.status === 401 || error.status === 403)) {
+      return void 0;
+    }
+    throw error;
+  }
+}
+function scopesOf(scopes) {
+  return scopes === void 0 ? "" : ` (${scopes.join(", ")})`;
+}
+function openInBrowser(url) {
+  return (address) => {
+    if (new URL(address).origin !== credentialOrigin(url)) return;
+    const [command, args] = process.platform === "darwin" ? ["open", [address]] : process.platform === "win32" ? ["rundll32", ["url.dll,FileProtocolHandler", address]] : ["xdg-open", [address]];
+    try {
+      const child = spawn(command, args, { detached: true, stdio: "ignore" });
+      child.on("error", () => void 0);
+      child.unref();
+    } catch {
+    }
+  };
+}
+
 // src/index.ts
 var helpText = `Usage: catalyst config <command> [options]
        catalyst login --instance <name-or-url>
        catalyst logout --instance <name-or-url>
+       catalyst setup <claude-code|codex|other> --instance <url> [--force]
 
 Sync local config assets with a live Catalyst instance.
 
 Login:
-  login      Show a connect code, wait until you confirm it in Settings, API keys, and
-             save the personal API key it issues, readable by you alone
-  logout     Forget the saved key of an instance; revoke it in Settings
+  login      Show a connect code, wait until you confirm it on the instance at
+             /settings/you/api-keys, and save the personal API key it issues, readable by
+             you alone
+  logout     Forget the saved key of an instance; revoke it at /settings/you/api-keys
+  setup      Connect a local agent: log in as 'login' does unless a working key is saved,
+             then write the Catalyst skill for Claude Code, Codex or another tool. --force
+             replaces a different skill file there and keeps it as SKILL.md.bak
 
 Commands:
   pull       Sync remote config assets into the local working copy
@@ -10222,13 +10755,18 @@ Commands:
   show       Print a remote asset: show <agent|skill|guardrail> <name>
 
 Options:
-  --instance <name-or-url>  Manifest instance name or direct URL
+  --instance <name-or-url>  Manifest instance name or direct URL. Left out: the
+                            manifest's defaultInstance; outside a working copy, the
+                            one instance a key is saved for
   --dir <working-copy-dir>  Directory containing catalyst.yaml (default: .)
   --prune                   Mirror on push, deleting the remote-only assets the last pull
                             saw
   --only <agent:name|skill:name|guardrail:name>
                             Sync selected assets; repeatable on push/pull
+  --workspace <id>          On pull: bind the working copy to the workspace and hold
+                            what it owns
   --help                    Show this help
+  --version                 Print the version of this CLI
 
 Environment:
   CATALYST_API_KEY      API key exchanged for a short-lived access token. It wins over
@@ -10236,10 +10774,16 @@ Environment:
   CATALYST_CONFIG_HOME  Folder of the saved keys (default: ~/.config/catalyst)
 
 A working copy that belongs to one Namespace names it beside the instance's url in
-catalyst.yaml, as 'namespace: kai-'. Its push names that Namespace, as the instance asks
+catalyst.yaml, as 'namespace: tax-'. Its push names that Namespace, as the instance asks
 of everyone but the holder of the release right; its pull, diff and list read only the
 assets the key may read, never the instance's version or default agent.
 
+A working copy bound to a workspace names it the same way, as 'workspace: <id>', which the
+first 'catalyst config pull --workspace <id>' writes. It holds what that workspace owns, and
+everything its push creates is owned by that workspace, guardrails included. Its push is never
+a release: a new agent starts hidden until an instance admin offers it. A working copy without
+either holds the instance's own assets.
+
 Guardrails join the working copy where catalyst.yaml lists their globs under 'guardrails',
 such as 'guardrails/*/guardrail.yaml'. Each is a folder with its guardrail.yaml and, for a
 model_judge check, its instruction in check.md. Guardrails are no part of a release: a push
@@ -10254,7 +10798,12 @@ async function runCli(argv, runtime = {}) {
 ${helpText}`);
     return 0;
   }
-  if (argv[0] === "login" || argv[0] === "logout") {
+  if (argv[0] === "--version") {
+    stdout(`${RELEASE_VERSION}
+`);
+    return 0;
+  }
+  if (argv[0] === "login" || argv[0] === "logout" || argv[0] === "setup") {
     return runLoginCommand(argv[0], argv.slice(1), runtime, stdout, stderr);
   }
   if (argv[0] !== "config") {
@@ -10292,6 +10841,7 @@ ${helpText}`);
         force: { type: "boolean", default: false },
         prune: { type: "boolean", default: false },
         only: { type: "string", multiple: true },
+        workspace: { type: "string" },
         help: { type: "boolean", short: "h", default: false }
       },
       allowPositionals: true,
@@ -10313,6 +10863,12 @@ ${helpText}`);
       stderr("--only is only valid with 'catalyst config push' or 'catalyst config pull'.\n");
       return 2;
     }
+    if (parsed.values.workspace !== void 0 && command !== "pull") {
+      stderr(
+        "--workspace is only valid with 'catalyst config pull', which binds the working copy.\n"
+      );
+      return 2;
+    }
     if (parsed.values.prune && parsed.values.only) {
       stderr("--prune cannot be combined with --only.\n");
       return 2;
@@ -10334,6 +10890,7 @@ ${helpText}`);
       ...parsed.values.force ? { force: true } : {},
       ...parsed.values.prune ? { prune: true } : {},
       ...parsed.values.only === void 0 ? {} : { only: parsed.values.only },
+      ...parsed.values.workspace === void 0 ? {} : { workspace: parsed.values.workspace },
       ...command === "show" && isShownKind(parsed.positionals[0]) ? { assetKind: parsed.positionals[0], assetName: parsed.positionals[1] } : {},
       ...runtime.fetchImpl === void 0 ? {} : { fetchImpl: runtime.fetchImpl },
       ...runtime.env === void 0 ? {} : { env: runtime.env },
@@ -10355,8 +10912,10 @@ async function runLoginCommand(command, args, runtime, stdout, stderr) {
       options: {
         instance: { type: "string" },
         dir: { type: "string" },
+        force: { type: "boolean", default: false },
         help: { type: "boolean", short: "h", default: false }
       },
+      allowPositionals: command === "setup",
       strict: true
     });
   } catch (error) {
@@ -10368,6 +10927,11 @@ async function runLoginCommand(command, args, runtime, stdout, stderr) {
     stdout(helpText);
     return 0;
   }
+  if (parsed.values.force && command !== "setup") {
+    stderr(`--force is not an option of 'catalyst ${command}'.
+`);
+    return 2;
+  }
   const options = {
     cwd: runtime.cwd ?? process.cwd(),
     ...parsed.values.dir === void 0 ? {} : { dir: parsed.values.dir },
@@ -10378,6 +10942,20 @@ async function runLoginCommand(command, args, runtime, stdout, stderr) {
     stdout,
     stderr
   };
+  if (command === "setup") {
+    const [tool, ...extra] = parsed.positionals;
+    if (!isLocalAgentTool(tool) || extra.length > 0 || parsed.values.instance === void 0) {
+      stderr(`${SETUP_USAGE}
+`);
+      return 2;
+    }
+    return setupCommand({
+      ...options,
+      tool,
+      ...parsed.values.force ? { force: true } : {},
+      ...runtime.openUrl === void 0 ? {} : { openUrl: runtime.openUrl }
+    });
+  }
   return command === "login" ? loginCommand(options) : logoutCommand(options);
 }
 function isShownKind(value) {
@@ -10398,6 +10976,7 @@ export {
   WorkingCopyValidationError,
   agentAssetPath,
   assertSafeApiKeyExchangeUrl,
+  bindManifestWorkspace,
   canonicalBundleFiles,
   canonicalizeAgentConfig,
   canonicalizeSkillConfig,
@@ -10420,6 +10999,7 @@ export {
   readStateFile,
   readWorkingCopy,
   removeStaleManifestAssets,
+  renderCatalystSkill,
   resolveInstance,
   resolveSkillResourceTarget,
   runCli,