@frontera-sdk/cli 1.45.1 → 1.45.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frontera-sdk/cli",
-  "version": "1.45.1",
+  "version": "1.45.3",
   "description": "The frontera CLI — scaffold, pull, save and deploy Frontera apps and automations.",
   "keywords": [
     "frontera",
@@ -38,8 +38,8 @@
     "build:release": "bun run scripts/build-release.ts"
   },
   "dependencies": {
-    "@frontera-sdk/automation": "1.45.0",
-    "@frontera-sdk/core": "1.45.0",
+    "@frontera-sdk/automation": "1.45.2",
+    "@frontera-sdk/core": "1.45.2",
     "gray-matter": "^4.0.3",
     "yaml": "^2.9.0"
   },

package/src/api/platform-api.ts

@@ -38,10 +38,22 @@ export interface AgentDraft {
 export class PlatformApi {
   private readonly client: FronteraClient
 
-  constructor(apiBaseUrl: string, token: string) {
+  /**
+   * `workspaceId` is for an ORGANIZATION key, which spans a list of workspaces
+   * and is refused a workspace-scoped route until one is named — the service
+   * will not widen an unaddressed request to org scope. The SDK turns it into
+   * `x-workspace-id`.
+   *
+   * Not taken from the profile's `workspaceId`: that field is descriptive by
+   * design (`profiles.ts`), recorded at verify time and never re-derived, so
+   * treating it as authority would send a stale id as fact. This comes from
+   * `--workspace`, which the caller states now.
+   */
+  constructor(apiBaseUrl: string, token: string, workspaceId?: string) {
     this.client = new FronteraClient({
       apiBaseUrl,
       credential: { kind: 'apiKey', key: token },
+      ...(workspaceId ? { workspaceId } : {}),
     })
   }
 
@@ -278,7 +290,9 @@ export class PlatformApi {
         {
           code: body?.code ?? statusCode(res.status),
           ...(res.status === 401
-            ? { hint: 'set FRONTERA_TOKEN to a valid sk-ws- workspace key, or run `frontera login`' }
+            ? { hint: 'run `frontera auth current` to see which credential this resolves to — a '
+                + 'workspace key (sk-ws-…) serves agents, skills, plugins and knowledge; an '
+                + 'organization key (sk-org-…) serves Blueprint authoring, datasets and Sources' }
             : {}),
         },
       )

package/src/commands/agent/index-commands.ts

@@ -8,7 +8,7 @@ import { renderComposition, type Lookups } from './compose'
 import { resolveAgentRef, type AgentRow } from './resolve'
 
 function api(ctx: CommandContext): PlatformApi {
-  return new PlatformApi(ctx.apiUrl, ctx.token)
+  return new PlatformApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
 }
 
 async function target(ctx: CommandContext, verb: string): Promise<{ api: PlatformApi; id: string; ref: string }> {
@@ -510,7 +510,7 @@ const skillAttach: Command = {
     if (!ref) throw new UsageError('missing <agent>', 'frontera agent list')
     if (!skillId) throw new UsageError('missing <skill>', 'frontera skill list — then pass an id')
 
-    const api = new PlatformApi(ctx.apiUrl, ctx.token)
+    const api = new PlatformApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
     const result = await api.attachAgentSkill(await resolveAgentRef(api, ref), skillId)
 
     return {
@@ -538,7 +538,7 @@ const skillDetach: Command = {
     if (!ref) throw new UsageError('missing <agent>', 'frontera agent list')
     if (!skillId) throw new UsageError('missing <skill>', `frontera agent get ${ref} — lists what it loads`)
 
-    const api = new PlatformApi(ctx.apiUrl, ctx.token)
+    const api = new PlatformApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
     const result = await api.detachAgentSkill(await resolveAgentRef(api, ref), skillId)
 
     return { data: result, text: `Detached ${skillId} from ${ref}. The skill itself is untouched.` }
@@ -581,7 +581,7 @@ const revert: Command = {
       throw new UsageError('missing <version>', `frontera agent versions ${ref} — then pass a version id`)
     }
 
-    const api = new PlatformApi(ctx.apiUrl, ctx.token)
+    const api = new PlatformApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
     const result = await api.revertAgent(await resolveAgentRef(api, ref), versionId, {
       // The old snapshot can name a knowledge base that has since been
       // deleted. Refusing by default is right — silently reverting to an agent

package/src/commands/app/dev.ts

@@ -77,7 +77,7 @@ export const appDev: Command = {
 
     let broker: ReturnType<typeof createDevSessionBroker> | null = null
     if (framework === 'next') {
-      const identity = await new PlatformApi(ctx.apiUrl, ctx.token).whoami()
+      const identity = await new PlatformApi(ctx.apiUrl, ctx.token, ctx.workspaceId).whoami()
       if (!identity.workspaceId || !identity.orgId) {
         throw new UsageError(
           'App development requires a workspace-scoped credential',

package/src/commands/app/list.ts

@@ -29,7 +29,7 @@ export const appList: Command = {
   },
 
   async run(ctx) {
-    const rows = (await new PlatformApi(ctx.apiUrl, ctx.token).platformApps()) as AppRow[]
+    const rows = (await new PlatformApi(ctx.apiUrl, ctx.token, ctx.workspaceId).platformApps()) as AppRow[]
 
     return {
       data: rows,

package/src/commands/auth/current.ts

@@ -52,8 +52,20 @@ export const authCurrent: Command = {
       profile: selection.profile,
       profileSource: selection.source,
       ...(selection.path ? { profileSourcePath: selection.path } : {}),
-      apiUrl: metadata.apiUrl,
+      // The EFFECTIVE origin, not the profile's.
+      //
+      // Reporting `metadata.apiUrl` while `apiUrlSource` said "environment" was
+      // a contradiction in one object: the field named where the value came
+      // from and then showed a different value. This command exists to answer
+      // "which deployment am I about to write to", so it is the one place that
+      // must not be optimistic — an agent reading `acme` and writing to
+      // `globex` is the failure the whole profile model is built to prevent.
+      apiUrl: suppliedOrigin ?? metadata.apiUrl,
       apiUrlSource: suppliedOrigin ? (flagString(ctx, 'api-url') ? 'flag' : 'environment') : 'profile',
+      // Kept alongside so a mismatch is visible rather than merely absent.
+      ...(suppliedOrigin && suppliedOrigin !== metadata.apiUrl
+        ? { profileApiUrl: metadata.apiUrl }
+        : {}),
       credentialSource: envToken ? 'environment' : (located?.source ?? null),
       credentialKind: metadata.credentialKind,
       workspaceId: metadata.workspaceId,
@@ -76,6 +88,11 @@ export const authCurrent: Command = {
     if (envToken) {
       lines.push('  FRONTERA_TOKEN is set and takes precedence over this profile’s stored key')
     }
+    if (suppliedOrigin && suppliedOrigin !== metadata.apiUrl) {
+      lines.push(
+        `  the origin above is overridden — this profile's own origin is ${metadata.apiUrl}`,
+      )
+    }
 
     return { data, text: lines.join('\n') }
   },

package/src/commands/blueprint/generate-types.ts

@@ -26,7 +26,7 @@ export const blueprintGenerateTypes: Command = {
 
   async run(ctx) {
     const project = ctx.project!
-    const api = new PlatformApi(ctx.apiUrl, ctx.token)
+    const api = new PlatformApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
     const schema = parseBlueprintSchema(await api.blueprintSchema())
     const contents = generateBlueprintTypes(schema)
     const written = writeBlueprintTypesFile(

package/src/commands/blueprint/get.ts

@@ -83,7 +83,7 @@ export const blueprintGet: Command = {
       )
     }
 
-    const api = new PlatformApi(ctx.apiUrl, ctx.token)
+    const api = new PlatformApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
     const schema = parseBlueprintSchema(await api.blueprintSchema())
     const apiName = resolveApiName(schema.objectTypes, typed)
     const type = schema.objectTypes.find((objectType) => objectType.apiName === apiName) as BlueprintSchemaObject

package/src/commands/blueprint/list.ts

@@ -28,7 +28,7 @@ export const blueprintList: Command = {
   },
 
   async run(ctx) {
-    const api = new PlatformApi(ctx.apiUrl, ctx.token)
+    const api = new PlatformApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
     const types = parseBlueprintSchema(await api.blueprintSchema()).objectTypes
 
     return {

package/src/commands/blueprint/query.ts

@@ -19,8 +19,8 @@ import { flagString, type Command } from '../types'
  */
 
 /** Constructed per call: the credential is per-invocation, not per-process. */
-function api(ctx: { apiUrl: string; token: string }): PlatformApi {
-  return new PlatformApi(ctx.apiUrl, ctx.token)
+function api(ctx: { apiUrl: string; token: string; workspaceId?: string }): PlatformApi {
+  return new PlatformApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
 }
 
 /** `status:open` and `amount:>:1000` — the two forms worth typing by hand. */

package/src/commands/capability/index-commands.ts

@@ -74,7 +74,7 @@ const list: Command = {
     const ref = ctx.positional[0]
     if (!ref) throw new UsageError('missing <agent>', 'frontera agent list — then pass an id or slug')
 
-    const api = new PlatformApi(ctx.apiUrl, ctx.token)
+    const api = new PlatformApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
     const agentId = await resolveAgentRef(api, ref)
     const rows = (await api.agentCapabilities(agentId)) as CapabilityRow[]
 
@@ -119,7 +119,7 @@ const available: Command = {
     const installId = ctx.positional[0]
     if (!installId) throw new UsageError('missing <plugin>', 'frontera plugin list — then pass an install id')
 
-    const rows = (await new PlatformApi(ctx.apiUrl, ctx.token)
+    const rows = (await new PlatformApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
       .pluginCapabilities(installId)) as CapabilityRow[]
 
     return {
@@ -158,7 +158,7 @@ const grant: Command = {
       )
     }
 
-    const api = new PlatformApi(ctx.apiUrl, ctx.token)
+    const api = new PlatformApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
     const agentId = await resolveAgentRef(api, ref)
     const result = await api.grantAgentCapability(agentId, capabilityId)
 
@@ -196,7 +196,7 @@ const revoke: Command = {
       throw new UsageError('missing <capability>', `frontera capability list ${ref}`)
     }
 
-    const api = new PlatformApi(ctx.apiUrl, ctx.token)
+    const api = new PlatformApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
     const agentId = await resolveAgentRef(api, ref)
     const result = await api.revokeAgentCapability(agentId, capabilityId)
 
@@ -223,7 +223,7 @@ const installs: Command = {
     const ref = ctx.positional[0]
     if (!ref) throw new UsageError('missing <agent>', 'frontera agent list — then pass an id or slug')
 
-    const api = new PlatformApi(ctx.apiUrl, ctx.token)
+    const api = new PlatformApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
     const rows = (await api.agentInstalls(await resolveAgentRef(api, ref))) as Array<{
       install?: { installName?: string }
       catalog?: { name?: string; kind?: string }
@@ -281,7 +281,7 @@ const bind: Command = {
     // switching later does not migrate anything already connected.
     const accountMode = ctx.flags['end-user'] === true ? 'end_user' : 'agent_owned'
 
-    const api = new PlatformApi(ctx.apiUrl, ctx.token)
+    const api = new PlatformApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
     const agentId = await resolveAgentRef(api, ref)
     const result = await api.bindAgentInstall(agentId, installId, accountMode)
 
@@ -312,7 +312,7 @@ const unbind: Command = {
     if (!ref) throw new UsageError('missing <agent>', 'frontera agent list — then pass an id or slug')
     if (!installId) throw new UsageError('missing <plugin>', `frontera capability installs ${ref}`)
 
-    const api = new PlatformApi(ctx.apiUrl, ctx.token)
+    const api = new PlatformApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
     const agentId = await resolveAgentRef(api, ref)
     const result = await api.unbindAgentInstall(agentId, installId).catch((e: unknown) => {
       throw new CliError((e as Error).message, {

package/src/commands/knowledge/index-commands.ts

@@ -51,7 +51,7 @@ const list: Command = {
     examples: ['frontera knowledge list', 'frontera knowledge list --json'],
   },
   async run(ctx) {
-    const api = new PlatformApi(ctx.apiUrl, ctx.token)
+    const api = new PlatformApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
     // The route takes the workspace explicitly, and a key holder cannot see
     // its own workspace id from anywhere else — hence /v1/whoami.
     const workspaceId = await requireWorkspaceId(api)
@@ -86,7 +86,7 @@ const sources: Command = {
     const ref = ctx.positional[0]
     if (!ref) throw new UsageError('missing <base>', 'frontera knowledge list — then pass a name or id')
 
-    const client = new PlatformApi(ctx.apiUrl, ctx.token)
+    const client = new PlatformApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
     const id = await resolveKnowledgeRef(client, ref)
     const rows = (await client.knowledgeSources(id)) as Array<Record<string, unknown>>
 
@@ -124,7 +124,7 @@ const get: Command = {
     const ref = ctx.positional[0]
     if (!ref) throw new UsageError('missing <base>', 'frontera knowledge list — then pass a name or id')
 
-    const client = new PlatformApi(ctx.apiUrl, ctx.token)
+    const client = new PlatformApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
     const base = await client.knowledgeBase(await resolveKnowledgeRef(client, ref))
 
     return {
@@ -188,7 +188,7 @@ const search: Command = {
       throw new UsageError(`--threshold must be a number, not "${thresholdRaw}"`, 'try --threshold 0.7')
     }
 
-    const client = new PlatformApi(ctx.apiUrl, ctx.token)
+    const client = new PlatformApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
     const baseId = await resolveKnowledgeRef(client, ref)
     const result = await client.knowledgeSearch(baseId, {
       query,
@@ -258,7 +258,7 @@ const retry: Command = {
       throw new UsageError('missing <source>', `frontera knowledge sources ${ref} — the id column`)
     }
 
-    const client = new PlatformApi(ctx.apiUrl, ctx.token)
+    const client = new PlatformApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
     const baseId = await resolveKnowledgeRef(client, ref)
     const result = await client.retryKnowledgeSource(baseId, sourceId)
 
@@ -291,7 +291,7 @@ const create: Command = {
       throw new UsageError('missing <name>', 'frontera knowledge create <name> [--description <text>]')
     }
 
-    const api = new PlatformApi(ctx.apiUrl, ctx.token)
+    const api = new PlatformApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
     const workspaceId = await requireWorkspaceId(api)
 
     // Checked here rather than left to the unique constraint: the service
@@ -379,7 +379,7 @@ const upload: Command = {
       })
     }
 
-    const api = new PlatformApi(ctx.apiUrl, ctx.token)
+    const api = new PlatformApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
     const baseId = await resolveKnowledgeRef(api, ref)
     const outcomes = await uploadAll(api, baseId, plan.files, strategy)
     const summary = summarizeUploads(ref, baseId, outcomes, plan)
@@ -415,7 +415,7 @@ const attach: Command = {
     if (!baseRef) throw new UsageError('missing <base>', 'frontera knowledge list — then pass a name or id')
     if (!agentRef) throw new UsageError('missing <agent>', 'frontera agent list — then pass a slug or id')
 
-    const api = new PlatformApi(ctx.apiUrl, ctx.token)
+    const api = new PlatformApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
     const baseId = await resolveKnowledgeRef(api, baseRef)
     const agentId = await resolveAgentRef(api, agentRef)
     await api.attachKnowledgeAgent(baseId, agentId)
@@ -450,7 +450,7 @@ const detach: Command = {
     if (!baseRef) throw new UsageError('missing <base>', 'frontera knowledge list — then pass a name or id')
     if (!agentRef) throw new UsageError('missing <agent>', 'frontera agent list — then pass a slug or id')
 
-    const api = new PlatformApi(ctx.apiUrl, ctx.token)
+    const api = new PlatformApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
     const baseId = await resolveKnowledgeRef(api, baseRef)
     const agentId = await resolveAgentRef(api, agentRef)
     await api.detachKnowledgeAgent(baseId, agentId)
@@ -477,7 +477,7 @@ const agents: Command = {
     const ref = ctx.positional[0]
     if (!ref) throw new UsageError('missing <base>', 'frontera knowledge list — then pass a name or id')
 
-    const api = new PlatformApi(ctx.apiUrl, ctx.token)
+    const api = new PlatformApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
     const baseId = await resolveKnowledgeRef(api, ref)
     const rows = (await api.knowledgeAttachments(baseId)) as Array<Record<string, unknown>>
 

package/src/commands/pack/index-commands.ts

@@ -65,7 +65,7 @@ const list: Command = {
     examples: ['frontera pack list', 'frontera pack list --json'],
   },
   async run(ctx) {
-    const rows = (await new PlatformApi(ctx.apiUrl, ctx.token).packs()) as PackListEntry[]
+    const rows = (await new PlatformApi(ctx.apiUrl, ctx.token, ctx.workspaceId).packs()) as PackListEntry[]
 
     return {
       data: rows,
@@ -101,7 +101,7 @@ const get: Command = {
     const ref = ctx.positional[0]
     if (!ref) throw new UsageError('missing <pack>', 'frontera pack list — then pass a name or id')
 
-    const api = new PlatformApi(ctx.apiUrl, ctx.token)
+    const api = new PlatformApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
     const detail = (await api.pack(await resolvePackRef(api, ref))) as {
       pack?: PackRow
       install?: unknown
@@ -177,7 +177,7 @@ const push: Command = {
       throw new UsageError('the manifest has no `name`', 'a pack is addressed by name everywhere else')
     }
 
-    const api = new PlatformApi(ctx.apiUrl, ctx.token)
+    const api = new PlatformApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
     const rows = (await api.packs()) as PackListEntry[]
     const existing = rows.find(
       (r) => (r.pack?.name ?? '').toLowerCase() === manifest.name!.toLowerCase(),
@@ -222,7 +222,7 @@ const install: Command = {
     const ref = ctx.positional[0]
     if (!ref) throw new UsageError('missing <pack>', 'frontera pack list — then pass a name or id')
 
-    const api = new PlatformApi(ctx.apiUrl, ctx.token)
+    const api = new PlatformApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
     const id = await resolvePackRef(api, ref)
     const result = (await api.installPack(id)) as { skills?: unknown[] }
 
@@ -252,7 +252,7 @@ const uninstall: Command = {
     const ref = ctx.positional[0]
     if (!ref) throw new UsageError('missing <pack>', 'frontera pack list — then pass a name or id')
 
-    const api = new PlatformApi(ctx.apiUrl, ctx.token)
+    const api = new PlatformApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
     const id = await resolvePackRef(api, ref)
     const removeApps = flagBool(ctx, 'remove-apps')
     const result = await api.uninstallPack(id, removeApps)
@@ -285,7 +285,7 @@ const apply: Command = {
     if (!packRef) throw new UsageError('missing <pack>', 'frontera pack list — then pass a name or id')
     if (!agentRef) throw new UsageError('missing <agent>', 'frontera agent list — then pass a slug or id')
 
-    const api = new PlatformApi(ctx.apiUrl, ctx.token)
+    const api = new PlatformApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
     const packId = await resolvePackRef(api, packRef)
     const agentId = await resolveAgentRef(api, agentRef)
     const result = await api.applyPackToAgent(packId, agentId)
@@ -323,7 +323,7 @@ const detach: Command = {
     if (!packRef) throw new UsageError('missing <pack>', 'frontera pack list — then pass a name or id')
     if (!agentRef) throw new UsageError('missing <agent>', 'frontera agent list — then pass a slug or id')
 
-    const api = new PlatformApi(ctx.apiUrl, ctx.token)
+    const api = new PlatformApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
     const packId = await resolvePackRef(api, packRef)
     const agentId = await resolveAgentRef(api, agentRef)
     await api.removePackFromAgent(packId, agentId)
@@ -348,7 +348,7 @@ const remove: Command = {
     const ref = ctx.positional[0]
     if (!ref) throw new UsageError('missing <pack>', 'frontera pack list — then pass a name or id')
 
-    const api = new PlatformApi(ctx.apiUrl, ctx.token)
+    const api = new PlatformApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
     const id = await resolvePackRef(api, ref)
     await api.deletePack(id)
 

package/src/commands/plugin/index-commands.ts

@@ -34,7 +34,7 @@ const list: Command = {
     examples: ['frontera plugin list', 'frontera plugin list --json'],
   },
   async run(ctx) {
-    const rows = (await new PlatformApi(ctx.apiUrl, ctx.token).pluginInstalls()) as InstallRow[]
+    const rows = (await new PlatformApi(ctx.apiUrl, ctx.token, ctx.workspaceId).pluginInstalls()) as InstallRow[]
     return {
       data: rows,
       text:
@@ -63,7 +63,7 @@ const catalog: Command = {
     examples: ['frontera plugin catalog'],
   },
   async run(ctx) {
-    const rows = (await new PlatformApi(ctx.apiUrl, ctx.token).pluginCatalog()) as Array<{
+    const rows = (await new PlatformApi(ctx.apiUrl, ctx.token, ctx.workspaceId).pluginCatalog()) as Array<{
       kind?: string
       displayName?: string
       authType?: string
@@ -94,7 +94,7 @@ const get: Command = {
     const installId = ctx.positional[0]
     if (!installId) throw new UsageError('missing <plugin>', 'frontera plugin list')
 
-    const install = await new PlatformApi(ctx.apiUrl, ctx.token).plugin(installId)
+    const install = await new PlatformApi(ctx.apiUrl, ctx.token, ctx.workspaceId).plugin(installId)
     return {
       data: install,
       text: table(
@@ -143,7 +143,7 @@ const add: Command = {
       }
     }
 
-    const result = await new PlatformApi(ctx.apiUrl, ctx.token).createPluginInstall({
+    const result = await new PlatformApi(ctx.apiUrl, ctx.token, ctx.workspaceId).createPluginInstall({
       kind,
       ...(flagString(ctx, 'name') ? { installName: flagString(ctx, 'name')! } : {}),
       ...(config ? { config } : {}),
@@ -205,7 +205,7 @@ const configure: Command = {
       }
     }
 
-    const result = await new PlatformApi(ctx.apiUrl, ctx.token).updatePluginInstall(installId, {
+    const result = await new PlatformApi(ctx.apiUrl, ctx.token, ctx.workspaceId).updatePluginInstall(installId, {
       ...(name ? { installName: name } : {}),
       ...(config ? { config } : {}),
     })
@@ -270,7 +270,7 @@ const policy: Command = {
       throw new UsageError('nothing to change', 'pass --enable, --disable, --actions or --new-capability')
     }
 
-    const result = await new PlatformApi(ctx.apiUrl, ctx.token).patchPluginInstall(installId, {
+    const result = await new PlatformApi(ctx.apiUrl, ctx.token, ctx.workspaceId).patchPluginInstall(installId, {
       ...(enable ? { enabled: true } : {}),
       ...(disable ? { enabled: false } : {}),
       ...(actions ? { actionPolicy: actions as 'allow_all' | 'read_only' | 'custom' } : {}),
@@ -297,7 +297,7 @@ const verify: Command = {
     // A failed check still answers 200 — the verdict is in the body, the same
     // shape `dataset test-source` established. Exiting non-zero here would
     // make an unreachable plugin indistinguishable from an unreachable API.
-    const result = await new PlatformApi(ctx.apiUrl, ctx.token).verifyPluginInstall(installId)
+    const result = await new PlatformApi(ctx.apiUrl, ctx.token, ctx.workspaceId).verifyPluginInstall(installId)
 
     return {
       data: result,
@@ -326,7 +326,7 @@ const remove: Command = {
     const installId = ctx.positional[0]
     if (!installId) throw new UsageError('missing <plugin>', 'frontera plugin list')
 
-    const result = await new PlatformApi(ctx.apiUrl, ctx.token).deletePluginInstall(installId)
+    const result = await new PlatformApi(ctx.apiUrl, ctx.token, ctx.workspaceId).deletePluginInstall(installId)
     return {
       data: result,
       text: `Uninstalled ${installId}.\n`

package/src/commands/registry.ts

@@ -40,6 +40,7 @@ import { loginCommand } from './login'
 import { setupCommand } from './setup'
 import { authCommands } from './auth/index-commands'
 import { kitCommands } from './kit/index-commands'
+import { workspaceCommands } from './workspace/index-commands'
 
 /**
  * Flags every command accepts. Declared once so a caller never has to wonder
@@ -55,6 +56,10 @@ export const GLOBAL_FLAGS: FlagSpec = {
   // auth ones — a one-command escape hatch is useless if it exists on six
   // commands and the seventh is the one being diagnosed.
   profile: 'string',
+  // Organization keys only. A workspace key already names its workspace; an
+  // organization key spans a list, and the service refuses to guess — leaving
+  // an unaddressed request at org scope is WIDER than what was asked for.
+  workspace: 'string',
 }
 
 /** Additionally accepted by any command that resolves a project. */
@@ -68,6 +73,7 @@ export const COMMANDS: readonly Command[] = [
 
   ...authCommands,
   ...kitCommands,
+  ...workspaceCommands,
 
   appInit,
   appList,
@@ -142,6 +148,7 @@ const NOUN_SUMMARY: Readonly<Record<string, string>> = {
   capability: 'What an agent may DO — plugin operations granted to it',
   auth: 'Credential profiles — one per API key, selected by directory',
   kit: 'Optional project-local Frontera skills for Codex and Claude Code',
+  workspace: 'Workspaces here — the ids --workspace takes',
 }
 
 export function nounSummary(noun: string): string {
@@ -171,9 +178,6 @@ export const UNSUPPORTED: Readonly<Record<string, string>> = {
   channel:
     'channels have no CLI surface — create one and bind it to an agent in the Console, '
     + 'under the agent’s Channels tab',
-  workspace:
-    'workspace and member management is Console-only. `frontera login` selects which workspace '
-    + 'a key acts on; it cannot create one',
   key: 'API keys are minted in the Console, never by the CLI — a credential that mints credentials '
     + 'is the escalation that separation exists to prevent',
   sheet: 'sheets have no CLI surface and none is planned',

package/src/commands/secret/index-commands.ts

@@ -51,7 +51,7 @@ const list: Command = {
     examples: ['frontera secret list', 'frontera secret list --json'],
   },
   async run(ctx) {
-    const api = new PlatformApi(ctx.apiUrl, ctx.token)
+    const api = new PlatformApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
     const rows = (await api.workspaceSecrets(await requireWorkspaceId(api))) as SecretRow[]
 
     return {
@@ -129,7 +129,7 @@ const set: Command = {
       })
     }
 
-    const api = new PlatformApi(ctx.apiUrl, ctx.token)
+    const api = new PlatformApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
     const workspaceId = await requireWorkspaceId(api)
     const description = flagString(ctx, 'description')
 
@@ -179,7 +179,7 @@ const remove: Command = {
     const name = ctx.positional[0]
     if (!name) throw new UsageError('missing <name>', 'frontera secret list — then pass a name')
 
-    const api = new PlatformApi(ctx.apiUrl, ctx.token)
+    const api = new PlatformApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
     await api.deleteWorkspaceSecret(await requireWorkspaceId(api), name)
 
     // No `--force`. The service refuses while anything still resolves the

package/src/commands/skill/bundle-commands.ts

@@ -125,7 +125,7 @@ const pull: Command = {
     const ref = ctx.positional[0]
     if (!ref) throw new UsageError('missing <skill>', 'frontera skill pull <skill> [--dir <path>]')
 
-    const client = new PlatformApi(ctx.apiUrl, ctx.token)
+    const client = new PlatformApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
     const id = await resolveSkillRef(client, ref)
     const doc = (await client.workspaceSkill(id)) as SkillDoc
     if (!doc.name) throw new CliError('skill has no name', { code: 'INTERNAL_ERROR', hint: 'run `frontera skill list` and pull by id' })
@@ -320,8 +320,8 @@ const push: Command = {
 }
 
 // One PlatformApi per run is enough; a tiny helper keeps push readable.
-function client(ctx: { apiUrl: string; token: string }): PlatformApi {
-  return new PlatformApi(ctx.apiUrl, ctx.token)
+function client(ctx: { apiUrl: string; token: string; workspaceId?: string }): PlatformApi {
+  return new PlatformApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
 }
 
 export const skillBundleCommands: Command[] = [pull, push]

package/src/commands/skill/index-commands.ts

@@ -29,7 +29,7 @@ const list: Command = {
     examples: ['frontera skill list', 'frontera skill list --json'],
   },
   async run(ctx) {
-    const rows = (await new PlatformApi(ctx.apiUrl, ctx.token).workspaceSkills()) as SkillRow[]
+    const rows = (await new PlatformApi(ctx.apiUrl, ctx.token, ctx.workspaceId).workspaceSkills()) as SkillRow[]
     return {
       data: rows,
       text:
@@ -59,7 +59,7 @@ const get: Command = {
     const ref = ctx.positional[0]
     if (!ref) throw new UsageError('missing <skill>', 'frontera skill list — then pass a name or id')
 
-    const client = new PlatformApi(ctx.apiUrl, ctx.token)
+    const client = new PlatformApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
     // Name or id, like every other noun. `skill list` leads with the id but a
     // reader reaches for the name, and an id-only argument made this the one
     // command that refused the obvious input.
@@ -118,7 +118,7 @@ const remove: Command = {
     const ref = ctx.positional[0]
     if (!ref) throw new UsageError('missing <skill>', 'frontera skill list — then pass a name or id')
 
-    const client = new PlatformApi(ctx.apiUrl, ctx.token)
+    const client = new PlatformApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
     const id = await resolveSkillRef(client, ref)
     await client.deleteWorkspaceSkill(id)
 

package/src/commands/types.ts

@@ -63,6 +63,11 @@ export interface CommandContext {
   output: Output
   /** Present when `meta.needsProject`. */
   project: AppProject | null
+  /**
+   * `--workspace`, for an organization key that must name which workspace it is
+   * acting in. Undefined for a workspace key, which carries its own.
+   */
+  workspaceId?: string
 }
 
 /**

package/src/commands/workspace/index-commands.ts

@@ -0,0 +1,76 @@
+import { BlueprintAuthoringApi } from '../../api/blueprint-authoring-api'
+import { table } from '../../table'
+import type { Command } from '../types'
+
+/**
+ * Workspaces, read-only.
+ *
+ * This noun exists for one reason: `--workspace <id>` is how an organization
+ * key names where it is acting, and nothing in the CLI could tell you what to
+ * put there. The id had to come from the Console or a database, which made a
+ * flag that exists to unblock organization keys unusable without leaving the
+ * terminal.
+ *
+ * The read is organization-scoped (`organization: ['update']`), which is what
+ * an organization key carries — so the credential that needs the answer is the
+ * one that can ask. A workspace key already knows its own workspace and does
+ * not need this.
+ *
+ * Managing workspaces stays out. Creating, deleting and membership are
+ * Console-only, and the verbs below are declared rather than omitted so that
+ * reaching for one says why instead of "unknown verb".
+ */
+
+const list: Command = {
+  meta: {
+    noun: 'workspace',
+    verb: 'list',
+    args: [],
+    flags: {},
+    summary: 'List workspaces in this organization, with the ids --workspace takes',
+    examples: ['frontera workspace list', 'frontera workspace list --json'],
+  },
+  async run(ctx) {
+    const rows = await new BlueprintAuthoringApi(ctx.apiUrl, ctx.token).orgWorkspaces()
+
+    return {
+      data: rows,
+      text: rows.length === 0
+        ? 'No workspaces visible to this credential.\n'
+          + '  This read needs an organization key (sk-org-…) carrying organization:update.'
+        : // ID first: it is the value `--workspace` takes, and the reason to
+          // run this at all. Name and slug are for recognising which is which.
+          table(
+            ['id', 'name', 'slug'],
+            rows.map((w) => [w.id ?? '?', w.name ?? '', w.slug ?? '']),
+            [undefined, 34, undefined],
+          ),
+    }
+  },
+}
+
+const RESERVED = 'the CLI reads workspaces, it does not manage them — create, delete and '
+  + 'membership are Console-only'
+
+const reserved: Command[] = (
+  [
+    ['create', 'Create a workspace'],
+    ['delete', 'Delete a workspace'],
+    ['members', 'List or change who belongs to a workspace'],
+  ] as const
+).map(([verb, summary]) => ({
+  meta: {
+    noun: 'workspace',
+    verb,
+    args: [],
+    flags: {},
+    summary,
+    examples: [`frontera workspace ${verb}`],
+    reserved: RESERVED,
+  },
+  async run(): Promise<never> {
+    throw new Error(RESERVED)
+  },
+}))
+
+export const workspaceCommands: Command[] = [list, ...reserved]

package/src/exit.ts

@@ -44,6 +44,10 @@ const USAGE_CODES = new Set([
   'PROJECT_CONTEXT_NOT_FOUND',
   'PROJECT_CONTEXT_CORRUPT',
   'PROJECT_CONTEXT_UNTRUSTED',
+  // The directory cannot be written to. Fixed by binding somewhere else or by
+  // not binding at all — never by retrying, which is why it sits with USAGE
+  // rather than FAILURE.
+  'PROJECT_CONTEXT_UNWRITABLE',
   // Authoring kit. Both are resolved by running a named command, not by retry.
   'KIT_VERSION_MISMATCH',
   'GENERATED_FILE_CONFLICT',
@@ -82,7 +86,12 @@ const SERVICE_HINTS: Record<string, string> = {
   // which case they are in throw a CliError with a specific hint instead.
   CONFLICT: 'the message above names what conflicted — resolve that, then retry',
   VALIDATION_STALE: 're-fetch the resource and re-run validation against the current revision',
-  UNAUTHORIZED: 'set FRONTERA_TOKEN to a valid sk-ws- workspace key',
+  // Names neither kind. Both are valid here — a workspace key for agents,
+  // skills, plugins and knowledge; an organization key for Blueprint authoring,
+  // datasets and Sources — and naming only one sent holders of the other
+  // looking for a credential they already had.
+  UNAUTHORIZED: 'run `frontera auth current` to see which profile this resolves to, '
+    + 'then `frontera auth verify` — or set FRONTERA_TOKEN',
   FORBIDDEN: 'this credential lacks permission for that resource — ask an admin, or use a different key',
   NOT_FOUND: 'list the resource first to confirm the id',
   RATE_LIMITED: 'wait and retry',

package/src/flag-help.ts

@@ -43,6 +43,9 @@ export const FLAG_HELP: Readonly<Record<string, string>> = {
   help: 'show this help',
   'api-url': "API origin to use — must match the selected profile's origin",
   profile: 'credential profile to use for this command, overriding the directory selection',
+  workspace:
+    "workspace to act in, for an organization key (sk-org-…) — it must be on that key's own "
+    + 'list. A workspace key already names one and ignores this',
   output: 'project-relative .ts path for generated output',
   check: 'verify generated output is current without writing it',
 
@@ -152,6 +155,7 @@ export const FLAG_HELP: Readonly<Record<string, string>> = {
  */
 const PLACEHOLDER: Readonly<Record<string, string>> = {
   'api-url': 'origin',
+  workspace: 'id',
   profile: 'name',
   output: 'path',
   dataset: 'name',

package/src/main.ts

@@ -184,6 +184,61 @@ async function main(): Promise<number> {
           { cwd },
         )
 
+    const workspaceFlag = typeof flags.workspace === 'string' ? flags.workspace.trim() : undefined
+
+    /**
+     * Nouns whose commands build a `PlatformApi`, which is the only client that
+     * carries `x-workspace-id`.
+     *
+     * `--workspace` is global — same reasoning as `--profile`: an escape hatch
+     * that exists on six commands and not the seventh is useless when the
+     * seventh is the one being diagnosed. But global must not mean "silently
+     * ignored where it cannot work": passing it to `dataset rows` sent nothing
+     * and reported nothing, which is the plausible-wrong-answer shape this CLI
+     * refuses everywhere else.
+     *
+     * Listed rather than derived because the mapping is a fact about which
+     * client a command constructs, and a wrong entry should be a failing test
+     * rather than a silent no-op.
+     */
+    const WORKSPACE_ADDRESSABLE = new Set([
+      'agent', 'app', 'blueprint', 'capability', 'knowledge',
+      'pack', 'plugin', 'secret', 'skill',
+    ])
+
+    if (workspaceFlag && !WORKSPACE_ADDRESSABLE.has(command.meta.noun)) {
+      throw new UsageError(
+        `--workspace does nothing on \`${command.meta.noun}\``,
+        'these commands are organization-scoped, or need no credential at all. '
+        + '--workspace applies to: ' + [...WORKSPACE_ADDRESSABLE].sort().join(', '),
+      )
+    }
+
+    // An organization key with no workspace named runs at ORG scope, and a
+    // workspace-scoped read then answers with an empty list rather than a
+    // refusal — `agent list` said "No agents in this workspace" for a workspace
+    // holding thirty. A plausible wrong answer is worse than an error, so say
+    // so before the command runs.
+    //
+    // Exempt where org scope is the point: those nouns are correct as-is, and
+    // `workspace list` is the FIRST thing such a caller runs to find an id.
+    // Listed rather than inferred — there is no scope field on a command, and
+    // adding one to silence a note would be the wrong trade.
+    const ORG_SCOPED_NOUNS = new Set(['blueprint', 'dataset', 'source', 'workspace', 'auth', 'kit'])
+    if (
+      !command.meta.offline
+      && !workspaceFlag
+      && !ORG_SCOPED_NOUNS.has(command.meta.noun)
+      && credential.token.startsWith('sk-org-')
+    ) {
+      output.note(
+        'note: organization key with no --workspace. Organization-scoped commands '
+        + '(blueprint authoring, dataset, source) work as-is; workspace-scoped ones '
+        + '(agent, skill, plugin, capability, knowledge, pack, secret) will read nothing. '
+        + '`frontera workspace list` shows the ids.',
+      )
+    }
+
     const result = await command.run({
       cwd,
       apiUrl: credential.apiUrl,
@@ -192,6 +247,7 @@ async function main(): Promise<number> {
       flags,
       output,
       project,
+      ...(workspaceFlag ? { workspaceId: workspaceFlag } : {}),
     })
 
     output.render(result.data, () => result.text)

package/src/project-context.ts

@@ -139,7 +139,28 @@ export function resolveBindingRoot(
 export function writeContext(root: string, profile: string, env: Env = process.env): string {
   const path = contextPath(root)
   const body: ProjectContext = { schemaVersion: 1, profile }
-  writeFileAtomic(path, `${JSON.stringify(body, null, 2)}\n`, 0o600)
+  try {
+    writeFileAtomic(path, `${JSON.stringify(body, null, 2)}\n`, 0o600)
+  } catch (err) {
+    // A directory nobody owns is an ordinary place to be standing — `/Users` on
+    // macOS, `/` in a container, a read-only mount in CI. The raw ENOENT/EACCES
+    // escaped as `error [EACCES]: EACCES: permission denied, mkdir …`: a code
+    // outside the CLI's own set, no hint, and mapped to exit 1, which tells a
+    // caller to retry something no retry can fix.
+    //
+    // Named alternatives rather than just the refusal, because binding is not
+    // the only way to select a profile — and in a directory like this it is the
+    // wrong one anyway.
+    const code = (err as NodeJS.ErrnoException).code
+    if (code === 'EACCES' || code === 'EPERM' || code === 'EROFS' || code === 'ENOSPC') {
+      throw new CliError(`cannot write a profile binding into ${root}`, {
+        code: 'PROJECT_CONTEXT_UNWRITABLE',
+        hint: 'cd to a directory you own and run it there, or bind a different one with '
+          + '`--dir <path>` — or skip binding entirely with `--profile <name>` or FRONTERA_PROFILE',
+      })
+    }
+    throw err
+  }
   recordBinding(root, profile, env)
   return path
 }