@frontera-sdk/cli 1.45.6 → 1.45.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frontera-sdk/cli",
-  "version": "1.45.6",
+  "version": "1.45.7",
   "description": "The frontera CLI — scaffold, pull, save and deploy Frontera apps and automations.",
   "keywords": [
     "frontera",

package/src/api/automation-api.ts

@@ -101,10 +101,20 @@ export interface RegistryStatus {
 export class AutomationApi {
   private readonly client: FronteraClient
 
-  constructor(apiBaseUrl: string, token: string) {
+  /**
+   * `workspaceId` because every automation belongs to one — the rows carry a
+   * `workspace_id` and the router refuses a request without the header.
+   *
+   * It was omitted, which left `automation` unreachable by an organization key
+   * in both directions: without the flag the service answered "Workspace
+   * context required", and with it the CLI answered "--workspace does nothing
+   * on automation". Two refusals and no way through.
+   */
+  constructor(apiBaseUrl: string, token: string, workspaceId?: string) {
     this.client = new FronteraClient({
       apiBaseUrl,
       credential: { kind: 'apiKey', key: token },
+      ...(workspaceId ? { workspaceId } : {}),
     })
   }
 

package/src/api/blueprint-authoring-api.ts

@@ -1,4 +1,5 @@
 import { CliError } from '../errors'
+import { credentialFailure } from './credential-failure'
 import type { DefinitionBundle } from '../blueprint/model'
 
 /**
@@ -40,30 +41,12 @@ export class BlueprintAuthoringApi {
     if (!res.ok) {
       // The credential failures worth telling apart, because each has a different
       // fix and a generic "request failed" sends the reader to the wrong one.
-      if (res.status === 401) {
-        throw new CliError(
-          'The credential was refused. An organization key that has been revoked or has ' +
-          'expired reads exactly like this — mint or rotate one in Settings → API keys.',
-          { code: 'UNAUTHORIZED', hint: 'frontera login --api-url <url>' },
-        )
-      }
-      if (res.status === 403) {
-        throw new CliError(
-          payload?.message
-            ? `${payload.message} — the key may not carry the capability this route needs, its `
-              + `creator's role may have changed, or the row is in a workspace the key does not list`
-            : "The key is not permitted to author this organization's Blueprint.",
-          {
-            code: 'FORBIDDEN',
-            // Three distinct causes with three distinct fixes, and the service cannot
-            // tell them apart for us. Naming all three beats naming the wrong one:
-            // a workspace-addressed route refuses a key whose workspace list omits
-            // that workspace, which has nothing to do with organization:update.
-            hint: 'Check the key carries the capability, and — for a workspace- or '
-              + 'agent-addressed route — that its workspace list includes that workspace.',
-          },
-        )
-      }
+      // Shared with the other clients so the three of them cannot drift again.
+      const credential = credentialFailure(res.status, payload?.message, {
+        token: this.token,
+        whenSilent: "The key is not permitted to author this organization's Blueprint.",
+      })
+      if (credential) throw credential
       if (res.status === 409) {
         throw new CliError(
           payload?.message

package/src/api/credential-failure.ts

@@ -0,0 +1,77 @@
+import { CliError } from '../errors'
+import { orgScopedServiceNouns } from '../scopes'
+
+/**
+ * The two credential failures, worded once.
+ *
+ * Every HTTP client here mapped its own 401/403, and they drifted: an audit of
+ * the read surface found `workspace list` and `blueprint status` explaining a
+ * 403 and naming a route out, while `dataset list`, `source list` and
+ * `action list` answered the same status with a bare "Insufficient
+ * permissions". Same error class, unequal help — and the bare form lands on
+ * exactly the nouns a workspace key is most likely to be refused by.
+ *
+ * A generic "request failed" sends the reader to the wrong fix, so the causes
+ * are named. The service cannot tell them apart for us, and naming all of them
+ * beats naming the wrong one.
+ *
+ * `PlatformApi` is deliberately NOT routed through here, and adding it would be
+ * a regression rather than a completion: it reads the workspace's granted
+ * slice, where a workspace key is the correct credential. The lane note below
+ * would then tell a caller holding the right kind of key to go and find the
+ * wrong one. What a 403 there usually means is an organization key that never
+ * named a workspace — which the dispatcher already warns about before the
+ * request leaves.
+ */
+
+/** The lane split, which is the first thing to check and the easiest to miss. */
+function laneNote(token: string): string {
+  // A workspace key is refused organization scope BY DESIGN — it is not a
+  // narrower version of an organization key, it is a different lane. Reading
+  // that refusal as "my key lacks a capability" sends someone to mint a second
+  // workspace key, which fails identically.
+  return token.startsWith('sk-ws-')
+    ? `This is a workspace key (sk-ws-). Organization-scoped commands (${orgScopedServiceNouns().join(', ')}) `
+      + 'refuse one by design; they need an organization key (sk-org-). '
+      + '`frontera auth list` shows which kind each profile holds.'
+    : 'Check the key carries the capability, and — for a workspace- or agent-addressed '
+      + 'route — that its workspace list includes that workspace.'
+}
+
+/**
+ * A `CliError` for 401 and 403, or `null` for every other status.
+ *
+ * Returning null rather than throwing keeps each client's own mapping for the
+ * statuses it genuinely treats differently — a 409 on the shared Blueprint
+ * draft means "re-read the revision", which is nothing to do with credentials.
+ */
+export function credentialFailure(
+  status: number,
+  message: string | undefined,
+  opts: { token: string; capability?: string; whenSilent?: string },
+): CliError | null {
+  if (status === 401) {
+    return new CliError(
+      'The credential was refused. An organization key that has been revoked or has '
+      + 'expired reads exactly like this — mint or rotate one in Settings → API keys.',
+      { code: 'UNAUTHORIZED', hint: 'frontera auth verify — then `frontera login --api-url <url>`' },
+    )
+  }
+
+  if (status === 403) {
+    return new CliError(
+      message
+        ? `${message} — the key may not carry the capability this route needs, its `
+          + `creator's role may have changed, or the row is in a workspace the key does not list`
+        : (opts.whenSilent ?? 'The key is not permitted to reach that resource.'),
+      {
+        code: 'FORBIDDEN',
+        hint: opts.capability
+          ? `the credential needs ${opts.capability}. ${laneNote(opts.token)}`
+          : laneNote(opts.token),
+      },
+    )
+  }
+
+  return null
+}

package/src/api/dataset-api.ts

@@ -2,6 +2,7 @@ import { readFileSync } from 'node:fs'
 import { basename } from 'node:path'
 
 import { CliError } from '../errors'
+import { credentialFailure } from './credential-failure'
 
 /**
  * Datasets, from the CLI.
@@ -99,6 +100,11 @@ export class DatasetApi {
     const text = await response.text()
     const payload = text ? JSON.parse(text) : {}
     if (!response.ok) {
+      // Datasets and sources are organization-scoped, so a workspace key is
+      // refused here by design — and this client used to answer that with a
+      // bare "Insufficient permissions" and no route out.
+      const credential = credentialFailure(response.status, payload?.message, { token: this.token })
+      if (credential) throw credential
       throw new CliError(payload?.message ?? `Request failed (${response.status}).`, {
         code: payload?.code ?? 'FAILURE',
         ...(payload?.details ? { hint: JSON.stringify(payload.details) } : {}),

package/src/api/governed-action-api.ts

@@ -1,4 +1,5 @@
 import { CliError } from '../errors'
+import { credentialFailure } from './credential-failure'
 import type { ObjectTypeShape, PublishedActionDefinition } from '../blueprint/ontology-edit-plan'
 
 /**
@@ -37,15 +38,30 @@ export interface ActionRequestSummary {
 }
 
 export class GovernedActionApi {
-  constructor(private readonly apiUrl: string, private readonly token: string) {}
+  /**
+   * `workspaceId` for the one verb on this plane that needs it: the deployment
+   * routes are organization-grain, but `GET /requests` is refused without a
+   * workspace, so `action requests` could not run on an organization key.
+   */
+  constructor(
+    private readonly apiUrl: string,
+    private readonly token: string,
+    private readonly workspaceId?: string,
+  ) {}
+
+  /** Every call carries the workspace when one was named. */
+  private headers(extra: Record<string, string> = {}): Record<string, string> {
+    return {
+      authorization: `Bearer ${this.token}`,
+      ...(this.workspaceId ? { 'x-workspace-id': this.workspaceId } : {}),
+      ...extra,
+    }
+  }
 
   private async call<T>(path: string, init: { method?: string; body?: unknown } = {}): Promise<T> {
     const response = await fetch(`${this.apiUrl}${path}`, {
       method: init.method ?? 'GET',
-      headers: {
-        authorization: `Bearer ${this.token}`,
-        ...(init.body === undefined ? {} : { 'content-type': 'application/json' }),
-      },
+      headers: this.headers(init.body === undefined ? {} : { 'content-type': 'application/json' }),
       ...(init.body === undefined ? {} : { body: JSON.stringify(init.body) }),
     })
     const text = await response.text()
@@ -54,6 +70,8 @@ export class GovernedActionApi {
 
     if (!response.ok) {
       const body = payload as { message?: string; code?: string; details?: unknown } | null
+      const credential = credentialFailure(response.status, body?.message, { token: this.token })
+      if (credential) throw credential
       throw new CliError(body?.message ?? `${response.status} from ${path}`, {
         code: body?.code ?? 'FAILURE',
         ...(body?.details ? { hint: JSON.stringify(body.details) } : {}),
@@ -94,7 +112,7 @@ export class GovernedActionApi {
 
     const response = await fetch(
       `${this.apiUrl}/v1/blueprint/governed-actions/requests${suffix}`,
-      { headers: { authorization: `Bearer ${this.token}` } },
+      { headers: this.headers() },
     )
     const text = await response.text()
     let payload: unknown
@@ -102,11 +120,16 @@ export class GovernedActionApi {
 
     if (!response.ok) {
       const body = payload as { message?: string; code?: string } | null
+      // The capability is named here because this route knows which one it
+      // needs; the shared mapper adds the lane note the bare hint was missing.
+      const credential = credentialFailure(response.status, body?.message, {
+        token: this.token,
+        capability: 'actionRequest:read',
+      })
+      if (credential) throw credential
       throw new CliError(body?.message ?? `${response.status} from /governed-actions/requests`, {
         code: body?.code ?? 'FAILURE',
-        ...(response.status === 403
-          ? { hint: 'the credential needs actionRequest:read — mint a key that carries it' }
-          : {}),
+        hint: 'frontera action list — to confirm which Actions this credential can see',
       })
     }
 

package/src/api/platform-api.ts

@@ -49,7 +49,18 @@ export class PlatformApi {
    * treating it as authority would send a stale id as fact. This comes from
    * `--workspace`, which the caller states now.
    */
+  /**
+   * The workspace this client addresses, when one was named.
+   *
+   * Kept as a field as well as a header because two nouns put the workspace in
+   * the URL rather than in `x-workspace-id`, and they were resolving it from
+   * `whoami` — which an organization key cannot call — while the answer was
+   * already sitting in this constructor.
+   */
+  readonly workspaceId: string | undefined
+
   constructor(apiBaseUrl: string, token: string, workspaceId?: string) {
+    this.workspaceId = workspaceId
     this.client = new FronteraClient({
       apiBaseUrl,
       credential: { kind: 'apiKey', key: token },

package/src/commands/action/deploy.ts

@@ -16,7 +16,7 @@ import { flagBool, flagString, type Command, type CommandContext } from '../type
  */
 
 function api(ctx: CommandContext): GovernedActionApi {
-  return new GovernedActionApi(ctx.apiUrl, ctx.token)
+  return new GovernedActionApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
 }
 
 export const actionDeploy: Command = {

package/src/commands/action/grant.ts

@@ -49,7 +49,7 @@ export const actionGrant: Command = {
     }
 
     const revoke = flagBool(ctx, 'revoke')
-    const client = new GovernedActionApi(ctx.apiUrl, ctx.token)
+    const client = new GovernedActionApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
     const result = await client.setCapabilityGrant(capability, role, revoke)
 
     const held = result.actions.length > 0 ? result.actions.join(', ') : '(none)'

package/src/commands/action/list.ts

@@ -21,7 +21,7 @@ export const actionList: Command = {
   },
 
   async run(ctx) {
-    const client = new GovernedActionApi(ctx.apiUrl, ctx.token)
+    const client = new GovernedActionApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
     const actions = await client.listPublishedActions()
 
     if (actions.length === 0) {

package/src/commands/action/prepare.ts

@@ -31,7 +31,7 @@ export const actionPrepare: Command = {
     const apiName = ctx.positional[0]
     if (!apiName) throw new UsageError('missing <action>', 'frontera action prepare escalateTicket')
 
-    const client = new GovernedActionApi(ctx.apiUrl, ctx.token)
+    const client = new GovernedActionApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
     const decision = await client.recordDeploymentDecision(
       apiName,
       flagString(ctx, 'reason') ?? 'Published before anything could be bound to it.',

package/src/commands/action/requests.ts

@@ -19,6 +19,9 @@ export const actionRequests: Command = {
   meta: {
     noun: 'action',
     verb: 'requests',
+    // Reads the slice granted to ONE workspace, unlike the rest of this
+    // noun — see `scope` on CommandMeta.
+    scope: 'workspace' as const,
     args: [
       {
         name: 'requestId',
@@ -36,7 +39,7 @@ export const actionRequests: Command = {
   },
 
   async run(ctx) {
-    const client = new GovernedActionApi(ctx.apiUrl, ctx.token)
+    const client = new GovernedActionApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
     const requestId = ctx.positional[0]
 
     if (requestId) {

package/src/commands/action/review.ts

@@ -19,7 +19,7 @@ import { flagString, type Command, type CommandContext } from '../types'
  */
 
 function api(ctx: CommandContext): GovernedActionApi {
-  return new GovernedActionApi(ctx.apiUrl, ctx.token)
+  return new GovernedActionApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
 }
 
 export const actionReview: Command = {

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

@@ -4,6 +4,7 @@ import { PlatformApi } from '../../api/platform-api'
 import { CliError, UsageError } from '../../errors'
 import { table } from '../../table'
 import { flagBool, flagString, type Command, type CommandContext } from '../types'
+import { resolveWorkspaceId } from '../workspace-id'
 import { renderComposition, type Lookups } from './compose'
 import { resolveAgentRef, type AgentRow } from './resolve'
 
@@ -33,7 +34,10 @@ async function buildLookups(
 ): Promise<Lookups> {
   const [plugins, knowledge, skills] = await Promise.all([
     client.pluginInstalls().catch(() => [] as unknown[]),
-    client.whoami().then((me) => (me.workspaceId ? client.knowledgeBases(me.workspaceId) : [])).catch(() => [] as unknown[]),
+    // Resolves `--workspace` first: this used to ask `whoami`, which an
+    // organization key cannot call, so the knowledge column silently rendered
+    // ids instead of names for every organization-key caller.
+    resolveWorkspaceId(client).then((ws) => client.knowledgeBases(ws)).catch(() => [] as unknown[]),
     client.workspaceSkills().catch(() => [] as unknown[]),
   ])
 

package/src/commands/app/promote.ts

@@ -7,7 +7,12 @@ export const appPromote: Command = {
   meta: {
     noun: 'app',
     verb: 'promote',
-    args: [{ name: 'version', required: true, description: 'version to make live' }],
+    args: [{
+      name: 'version',
+      required: true,
+      description: 'version to make live, from `frontera app versions`',
+      producer: 'frontera app versions — then `frontera app promote <version>`',
+    }],
     flags: {},
     summary: 'Move the live pointer to an already-published version',
     examples: ['frontera app promote 1.4.0'],

package/src/commands/app/sdk.ts

@@ -7,7 +7,7 @@ export const appSdk: Command = {
   meta: {
     noun: 'app',
     verb: 'sdk',
-    args: [{ name: 'action', required: true, description: 'sync' }],
+    args: [{ name: 'action', required: true, description: 'sync', producer: 'frontera app sdk sync' }],
     flags: {},
     summary: 'Refresh the generated SDK tree in a legacy vendored App',
     examples: ['frontera app sdk sync'],

package/src/commands/automation/dev.ts

@@ -308,7 +308,7 @@ export const automationDev: Command = {
       )
     }
 
-    const api = new AutomationApi(ctx.apiUrl, ctx.token)
+    const api = new AutomationApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
     // Identity of THIS process, minted once and sent with every dev call.
     //
     // The session id cannot serve: take-over is an upsert on the automation, so

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

@@ -132,7 +132,7 @@ const deploy: Command = {
       )
     }
 
-    const client = new AutomationApi(ctx.apiUrl, ctx.token)
+    const client = new AutomationApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
     const result = await client.deploy(slug, {
       manifest,
       bundle,
@@ -173,7 +173,7 @@ const list: Command = {
   },
 
   async run(ctx) {
-    const rows = await new AutomationApi(ctx.apiUrl, ctx.token).list()
+    const rows = await new AutomationApi(ctx.apiUrl, ctx.token, ctx.workspaceId).list()
 
     return {
       data: rows,
@@ -209,7 +209,7 @@ const versions: Command = {
 
   async run(ctx) {
     const slug = requireSlug(ctx)
-    const client = new AutomationApi(ctx.apiUrl, ctx.token)
+    const client = new AutomationApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
 
     // Which version is LIVE is on the automation row, not on any version, so
     // it takes a second read. Worth it: "which one is running" is the question
@@ -268,7 +268,7 @@ const promote: Command = {
       )
     }
 
-    const result = await new AutomationApi(ctx.apiUrl, ctx.token).promote(slug, version)
+    const result = await new AutomationApi(ctx.apiUrl, ctx.token, ctx.workspaceId).promote(slug, version)
     return { data: result, text: `Promoted ${slug} to v${result.version}` }
   },
 }
@@ -292,7 +292,7 @@ function enabledCommand(verb: 'enable' | 'disable', summary: string): Command {
 
     async run(ctx) {
       const slug = requireSlug(ctx)
-      const result = await new AutomationApi(ctx.apiUrl, ctx.token).setEnabled(slug, enabled)
+      const result = await new AutomationApi(ctx.apiUrl, ctx.token, ctx.workspaceId).setEnabled(slug, enabled)
       return {
         data: result,
         text: `${enabled ? 'Enabled' : 'Disabled'} ${slug}`,

package/src/commands/automation/pull.ts

@@ -85,7 +85,7 @@ export const automationPull: Command = {
     if (!raw) throw new UsageError('missing <slug>', 'frontera automation pull <slug>[@version]')
     const { slug, version } = parseTarget(raw)
 
-    const client = new AutomationApi(ctx.apiUrl, ctx.token)
+    const client = new AutomationApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
 
     // "Latest" is resolved against the version list rather than by inventing a
     // server endpoint for it — `versions` already exists and is authoritative.

package/src/commands/automation/run.ts

@@ -218,7 +218,7 @@ export const automationRun: Command = {
 
   async run(ctx) {
     const slug = requireSlug(ctx)
-    const client = new AutomationApi(ctx.apiUrl, ctx.token)
+    const client = new AutomationApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
     // Parsed here rather than passed through as a string: a typo should fail
     // before the registry wait, not after it, and `--version abc` reaching the
     // service as `NaN` would come back as a schema error naming a field the
@@ -364,7 +364,7 @@ export const automationRuns: Command = {
     // where it is explained, so the two belong under one name.
     const runId = ctx.positional[1]
     if (runId) {
-      const api = new AutomationApi(ctx.apiUrl, ctx.token)
+      const api = new AutomationApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
       const [detail, steps] = await Promise.all([
         api.runById(slug, runId),
         // A run that failed before its first step has none, and that is a fact
@@ -393,7 +393,7 @@ export const automationRuns: Command = {
     // without this a dev run is invisible from the CLI — the same blind spot
     // that made `run --dev` wait out its timeout.
     const dev = flagBool(ctx, 'dev')
-    const rows = await new AutomationApi(ctx.apiUrl, ctx.token).runs(
+    const rows = await new AutomationApi(ctx.apiUrl, ctx.token, ctx.workspaceId).runs(
       slug,
       undefined,
       dev ? 'dev' : 'live',

package/src/commands/blueprint/authoring.ts

@@ -79,12 +79,21 @@ function readDocument(ctx: CommandContext, positionalIndex = 0): Record<string,
 const KINDS = ['object-type', 'link-type', 'metric', 'action', 'object-set'] as const
 type Kind = (typeof KINDS)[number]
 
-function readKind(ctx: CommandContext): Kind {
+/**
+ * `create`, `update` and `delete` all start with a kind, so they all land here
+ * — and the hint named `create` for all three. Someone who mistyped
+ * `blueprint update` was sent to a different verb's help, whose shape is not
+ * the one they need: update and delete take an apiName that create does not.
+ *
+ * The caller's own verb is passed in, and the hint is that verb's first
+ * example, which shows every argument rather than only the one that failed.
+ */
+function readKind(ctx: CommandContext, verb: string, example: string): Kind {
   const kind = ctx.positional[0] as Kind
   if (!KINDS.includes(kind)) {
     throw new CliError(
       `Unknown kind "${ctx.positional[0] ?? ''}". Expected one of: ${KINDS.join(', ')}.`,
-      { code: 'USAGE', hint: 'frontera blueprint create --help' },
+      { code: 'USAGE', hint: `${example} — see \`frontera blueprint ${verb} --help\`` },
     )
   }
   return kind
@@ -121,7 +130,7 @@ export const blueprintCreate: Command = {
     ],
   },
   async run(ctx) {
-    const kind = readKind(ctx)
+    const kind = readKind(ctx, 'create', 'frontera blueprint create object-type --file customer.json')
     const client = api(ctx)
     const document = readDocument(ctx, 1)
     const revision = await client.revision()
@@ -152,7 +161,7 @@ export const blueprintUpdate: Command = {
     examples: ['frontera blueprint update object-type Customer --file customer.json'],
   },
   async run(ctx) {
-    const kind = readKind(ctx)
+    const kind = readKind(ctx, 'update', 'frontera blueprint update object-type Customer --file customer.json')
     const apiName = ctx.positional[1]
     if (!apiName) {
       throw new CliError('An apiName is required.', {
@@ -188,7 +197,7 @@ export const blueprintDelete: Command = {
     examples: ['frontera blueprint delete metric revenuePerCustomer'],
   },
   async run(ctx) {
-    const kind = readKind(ctx)
+    const kind = readKind(ctx, 'delete', 'frontera blueprint delete metric revenuePerCustomer')
     const apiName = ctx.positional[1]
     if (!apiName) {
       throw new CliError('An apiName is required.', {

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

@@ -13,6 +13,9 @@ export const blueprintGenerateTypes: Command = {
   meta: {
     noun: 'blueprint',
     verb: 'generate-types',
+    // Reads the slice granted to ONE workspace, unlike the rest of this
+    // noun — see `scope` on CommandMeta.
+    scope: 'workspace' as const,
     args: [],
     flags: { output: 'string', check: 'boolean' },
     summary: 'Generate App-local TypeScript types from this workspace Blueprint',

package/src/commands/blueprint/get.ts

@@ -62,6 +62,9 @@ export const blueprintGet: Command = {
   meta: {
     noun: 'blueprint',
     verb: 'get',
+    // Reads the slice granted to ONE workspace, unlike the rest of this
+    // noun — see `scope` on CommandMeta.
+    scope: 'workspace' as const,
     args: [
       {
         name: 'apiName',

package/src/commands/blueprint/list.ts

@@ -21,6 +21,9 @@ export const blueprintList: Command = {
   meta: {
     noun: 'blueprint',
     verb: 'list',
+    // Reads the slice granted to ONE workspace, unlike the rest of this
+    // noun — see `scope` on CommandMeta.
+    scope: 'workspace' as const,
     args: [],
     flags: {},
     summary: 'List the object types this workspace can read',

package/src/commands/blueprint/query.ts

@@ -123,6 +123,9 @@ export const blueprintQuery: Command = {
   meta: {
     noun: 'blueprint',
     verb: 'query',
+    // Reads the slice granted to ONE workspace, unlike the rest of this
+    // noun — see `scope` on CommandMeta.
+    scope: 'workspace' as const,
     args: [
       {
         name: 'apiName',
@@ -254,6 +257,9 @@ export const blueprintInstance: Command = {
   meta: {
     noun: 'blueprint',
     verb: 'instance',
+    // Reads the slice granted to ONE workspace, unlike the rest of this
+    // noun — see `scope` on CommandMeta.
+    scope: 'workspace' as const,
     args: [
       { name: 'apiName', required: true, description: 'object type, from `frontera blueprint list`' },
       { name: 'pk', required: true, description: 'primary key value of the record to read' },

package/src/commands/kit/status.ts

@@ -5,6 +5,28 @@ import { checkCompatibility, digest, findDuplicateSources, KIT, LOCK_FILE, readL
 import type { Command } from '../types'
 import { cliVersion, kitRoot } from './shared'
 
+/**
+ * A drift list, counted and capped.
+ *
+ * `modified` was summarised with a count and `missing` was not, so a tree short
+ * of a whole skill printed fifty bare paths under a headline reading
+ * "(current)" — and the two lines that actually needed acting on, the
+ * duplicate-source and compatibility warnings, scrolled off the top.
+ *
+ * Truncation is stated rather than silent, and `--json` still carries every
+ * path, because the full list is what `sync` is judged against.
+ */
+export function driftLines(files: string[], what: string, bullet: string, shown = 8): string[] {
+  if (files.length === 0) return []
+  return [
+    `  ${files.length} generated file(s) ${what}:`,
+    ...files.slice(0, shown).map((f) => `    ${bullet} ${f}`),
+    ...(files.length > shown
+      ? [`    … and ${files.length - shown} more — \`frontera kit status --json\` lists them all`]
+      : []),
+  ]
+}
+
 /**
  * What this repository has, what this CLI carries, and whether they agree.
  *
@@ -73,9 +95,8 @@ export const kitStatus: Command = {
       lines.push(`  bundled kit ${KIT.kitVersion}; run \`frontera kit vendor\` to commit it to this repository`)
     } else {
       lines.push(`kit ${lock.kitVersion} vendored${outdated ? ` — this CLI carries ${KIT.kitVersion}` : ' (current)'}`)
-      if (modified.length > 0) lines.push(`  ${modified.length} generated file(s) edited locally:`)
-      lines.push(...modified.map((f) => `    · ${f}`))
-      if (missing.length > 0) lines.push(...missing.map((f) => `    - ${f} (missing)`))
+      lines.push(...driftLines(modified, 'edited locally', '·'))
+      lines.push(...driftLines(missing, 'missing — run `frontera kit sync`', '-'))
     }
     if (claudeImportsAgents === false) {
       lines.push('  ! CLAUDE.md does not import @AGENTS.md — run `frontera kit vendor` to repair it')

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

@@ -3,6 +3,7 @@ import { CliError, UsageError } from '../../errors'
 import { table } from '../../table'
 import { resolveAgentRef } from '../agent/resolve'
 import { flagString, type Command } from '../types'
+import { resolveWorkspaceId } from '../workspace-id'
 import { renderUploadSummary, summarizeUploads, uploadAll } from './upload-batch'
 import { planUploads } from './upload-plan'
 
@@ -13,24 +14,13 @@ interface KnowledgeRow {
   description?: string
 }
 
-/** The workspace a `sk-ws-` key is scoped to. Not visible from anywhere else. */
-async function requireWorkspaceId(api: PlatformApi): Promise<string> {
-  const me = await api.whoami()
-  if (!me.workspaceId) {
-    throw new CliError('this credential is not scoped to a workspace', {
-      code: 'FORBIDDEN',
-      hint: 'use a workspace key (sk-ws-…) created for the workspace you mean',
-    })
-  }
-  return me.workspaceId
-}
 
 /** Accept a base by name or id — `knowledge list` shows both. */
 async function resolveKnowledgeRef(client: PlatformApi, ref: string): Promise<string> {
   const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
   if (UUID.test(ref)) return ref
 
-  const workspaceId = await requireWorkspaceId(client)
+  const workspaceId = await resolveWorkspaceId(client)
   const rows = (await client.knowledgeBases(workspaceId)) as KnowledgeRow[]
   const match = rows.find((k) => (k.name ?? '').toLowerCase() === ref.toLowerCase())
   if (match?.id) return match.id
@@ -54,7 +44,7 @@ const list: Command = {
     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)
+    const workspaceId = await resolveWorkspaceId(api)
     const rows = (await api.knowledgeBases(workspaceId)) as KnowledgeRow[]
     return {
       data: rows,
@@ -292,7 +282,7 @@ const create: Command = {
     }
 
     const api = new PlatformApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
-    const workspaceId = await requireWorkspaceId(api)
+    const workspaceId = await resolveWorkspaceId(api)
 
     // Checked here rather than left to the unique constraint: the service
     // answers a duplicate with a bare CONFLICT, whose generic hint ("resolve

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

@@ -3,6 +3,7 @@ import { CliError, UsageError } from '../../errors'
 import { readSecretValue } from '../../secrets'
 import { table } from '../../table'
 import { flagString, type Command } from '../types'
+import { resolveWorkspaceId } from '../workspace-id'
 
 /**
  * Workspace secrets.
@@ -30,16 +31,6 @@ interface SecretRow {
   dependents?: Array<{ kind?: string; displayName?: string; name?: string }>
 }
 
-async function requireWorkspaceId(api: PlatformApi): Promise<string> {
-  const me = await api.whoami()
-  if (!me.workspaceId) {
-    throw new CliError('this credential is not scoped to a workspace', {
-      code: 'FORBIDDEN',
-      hint: 'use a workspace key (sk-ws-…) created for the workspace you mean',
-    })
-  }
-  return me.workspaceId
-}
 
 const list: Command = {
   meta: {
@@ -52,7 +43,7 @@ const list: Command = {
   },
   async run(ctx) {
     const api = new PlatformApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
-    const rows = (await api.workspaceSecrets(await requireWorkspaceId(api))) as SecretRow[]
+    const rows = (await api.workspaceSecrets(await resolveWorkspaceId(api))) as SecretRow[]
 
     return {
       data: rows,
@@ -130,7 +121,7 @@ const set: Command = {
     }
 
     const api = new PlatformApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
-    const workspaceId = await requireWorkspaceId(api)
+    const workspaceId = await resolveWorkspaceId(api)
     const description = flagString(ctx, 'description')
 
     // List, then create or replace. The service has no upsert, and choosing by
@@ -180,7 +171,7 @@ const remove: Command = {
     if (!name) throw new UsageError('missing <name>', 'frontera secret list — then pass a name')
 
     const api = new PlatformApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
-    await api.deleteWorkspaceSecret(await requireWorkspaceId(api), name)
+    await api.deleteWorkspaceSecret(await resolveWorkspaceId(api), name)
 
     // No `--force`. The service refuses while anything still resolves the
     // secret and says what, and an override here would only move the outage

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

@@ -6,6 +6,7 @@ import matter from 'gray-matter'
 import { PlatformApi } from '../../api/platform-api'
 import { CliError, UsageError } from '../../errors'
 import { flagBool, flagString, type Command } from '../types'
+import { resolveWorkspaceId } from '../workspace-id'
 import { resolveSkillRef } from './resolve'
 
 /**
@@ -123,7 +124,9 @@ const pull: Command = {
 
   async run(ctx) {
     const ref = ctx.positional[0]
-    if (!ref) throw new UsageError('missing <skill>', 'frontera skill pull <skill> [--dir <path>]')
+    // `skill get` and `skill delete` both name the producer; pull restated its
+    // own form, which tells a caller nothing they did not already have.
+    if (!ref) throw new UsageError('missing <skill>', 'frontera skill list — then pass a name or id')
 
     const client = new PlatformApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
     const id = await resolveSkillRef(client, ref)
@@ -152,21 +155,16 @@ const pull: Command = {
       written.push(script.path)
     }
 
-    // Assets need the workspace segment for the download route; a workspace
-    // key resolves its own scope, so whoami is authoritative.
+    // Assets need the workspace segment for the download route. `--workspace`
+    // answers it for an organization key, which cannot call whoami at all; a
+    // workspace key still falls back to its own scope.
     const assets = doc.assets ?? []
     if (assets.length > 0) {
-      const who = await client.whoami()
-      if (!who.workspaceId) {
-        throw new CliError('cannot download assets without a workspace scope', {
-          code: 'FORBIDDEN',
-          hint: 'use a workspace-scoped API key',
-        })
-      }
+      const workspaceId = await resolveWorkspaceId(client)
       for (const asset of assets) {
         const filename = assetFilename(asset.storageKey)
         if (!filename) continue
-        const bytes = await client.downloadSkillAsset(who.workspaceId, filename)
+        const bytes = await client.downloadSkillAsset(workspaceId, filename)
         writeBundleFile(dir, asset.path, bytes)
         written.push(`${asset.path}${asset.visible ? ' *' : ''}`)
       }

package/src/commands/types.ts

@@ -6,6 +6,14 @@ export interface ArgSpec {
   name: string
   required: boolean
   description: string
+  /**
+   * What to run to obtain this value, when the dispatcher reports it missing.
+   *
+   * Only read for `needsProject` commands, whose own `run` never executes when
+   * an argument is absent. Everywhere else the command raises its own error and
+   * names its own producer, which is strictly better than anything general.
+   */
+  producer?: string
 }
 
 export interface CommandMeta {
@@ -18,6 +26,21 @@ export interface CommandMeta {
   summary: string
   /** At least one, copy-pasteable. Agents read --help before documentation. */
   examples: readonly string[]
+  /**
+   * The grain this VERB acts at, when it differs from its noun's.
+   *
+   * Scope was tracked per noun, and several nouns span both grains: Blueprint
+   * AUTHORING edits one draft shared by the organization while Blueprint
+   * READING returns the slice granted to one workspace, and `action list` is
+   * organization-wide while `action requests` is not. A per-noun map cannot be
+   * right about either — it produced a warning that named the wrong commands,
+   * and let `agent list` answer "No agents in this workspace" for a request
+   * that had never named a workspace.
+   *
+   * Omit it and the noun's own grain applies. See `scopes.ts`.
+   */
+  scope?: 'workspace' | 'organization'
+
   /** Resolve an app project before running, and fail if there is none. */
   needsProject?: boolean
   /**

package/src/commands/workspace-id.ts

@@ -0,0 +1,38 @@
+import type { PlatformApi } from '../api/platform-api'
+import { CliError } from '../errors'
+
+/**
+ * Which workspace a command is acting in.
+ *
+ * `knowledge` and `secret` name a workspace in the URL, so they have to resolve
+ * one before they can call anything. Both asked `whoami`, which is right for a
+ * workspace key — it carries its own workspace and nothing else names it — and
+ * wrong for an organization key in two compounding ways:
+ *
+ *   `/v1/whoami` answers 403 to an organization key, so the resolution failed
+ *   before it could report what was actually missing. The caller read
+ *   "Insufficient permissions" and went looking for a capability, when the key
+ *   held every one the route needed.
+ *
+ *   `--workspace` was already on the command line. The flag exists precisely so
+ *   an organization key can say which workspace it means, and these two nouns
+ *   are in the addressable set — so the CLI accepted the answer and then went
+ *   and asked someone else.
+ *
+ * The flag wins when present. `whoami` stays as the fallback, because a
+ * workspace key does not pass `--workspace` and should not have to.
+ */
+export async function resolveWorkspaceId(api: PlatformApi): Promise<string> {
+  if (api.workspaceId) return api.workspaceId
+
+  const me = await api.whoami().catch(() => null)
+  if (me?.workspaceId) return me.workspaceId
+
+  throw new CliError('this credential does not name a workspace', {
+    code: 'FORBIDDEN',
+    // Both routes out, because both are real: an organization key names one per
+    // invocation, and a workspace key carries one permanently.
+    hint: 'pass --workspace <id> (see `frontera workspace list`), '
+      + 'or use a workspace key (sk-ws-…) created for the workspace you mean',
+  })
+}

package/src/main.ts

@@ -6,6 +6,7 @@ import { CliError, UsageError } from './errors'
 import { EXIT } from './exit'
 import { createOutput, type OutputMode } from './output'
 import { readProject } from './project'
+import { commandScope } from './scopes'
 import {
   aliasesFor,
   describeCommand,
@@ -154,6 +155,29 @@ async function main(): Promise<number> {
     const dirFlag = typeof flags.dir === 'string' ? flags.dir : undefined
     const cwd = dirFlag ?? process.cwd()
 
+    /**
+     * A missing argument outranks a missing project directory.
+     *
+     * `needsProject` is enforced here, before `run`, so a command that
+     * validates its own arguments never got to speak: `frontera app promote`
+     * with no version reported "not in a Frontera app directory" and never
+     * mentioned `<version>` or `app versions`. Two things were wrong and the
+     * caller was told the one they had not asked about.
+     *
+     * Scoped to `needsProject` deliberately. Every other command reaches its
+     * own check, and those checks name the command that PRODUCES the missing
+     * value — better than anything derivable here, and worth not preempting.
+     */
+    const missingArg = command.meta.args.find((arg, i) => arg.required && positional[i] === undefined)
+
+    if (command.meta.needsProject && missingArg) {
+      throw new UsageError(
+        `missing <${missingArg.name}>`,
+        missingArg.producer ?? command.meta.examples[0]
+          ?? `frontera ${command.meta.noun} ${command.meta.verb} <${missingArg.name}>`,
+      )
+    }
+
     let project: AppProject | null = null
     if (command.meta.needsProject || command.meta.optionalProject) {
       const root = findProjectRoot(cwd)
@@ -187,9 +211,6 @@ async function main(): Promise<number> {
     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
@@ -197,45 +218,61 @@ async function main(): Promise<number> {
      * 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.
+     * Judged per VERB, not per noun: `blueprint status` edits the shared draft
+     * and has no workspace to name, while `blueprint list` reads the slice
+     * granted to one. A noun-level refusal was wrong about both.
      */
-    const WORKSPACE_ADDRESSABLE = new Set([
-      'agent', 'app', 'blueprint', 'capability', 'knowledge',
-      'pack', 'plugin', 'secret', 'skill',
-    ])
-
-    if (workspaceFlag && !WORKSPACE_ADDRESSABLE.has(command.meta.noun)) {
+    // `offline` as well as organization grain: `init` and `setup` write files
+    // and never open a connection, so a workspace means nothing to them. They
+    // are not organization-scoped either, so scope alone would have let the
+    // flag through — `frontera init --workspace <id>` scaffolded a directory
+    // and ignored the flag in silence.
+    const label = `${command.meta.noun}${command.meta.verb ? ` ${command.meta.verb}` : ''}`
+    if (workspaceFlag && (command.meta.offline || commandScope(command.meta) === 'organization')) {
       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(', '),
+        `--workspace does nothing on \`${label}\``,
+        command.meta.offline
+          ? 'this command touches no service, so there is no request to address.'
+          : 'this command acts on the whole organization. '
+            + '--workspace applies to workspace-scoped commands — '
+            + `try \`frontera ${command.meta.noun} --help\``,
       )
     }
 
-    // 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'])
+    /**
+     * An organization key that named no workspace cannot run a
+     * workspace-scoped command, so it is refused rather than warned.
+     *
+     * This was a note, and a note was not enough. The request still went out,
+     * ran at organization scope, matched nothing, and `agent list` printed
+     * "No agents in this workspace." and exited 0 — for a request that had
+     * never looked at a workspace. Every sibling already refused (`app` and
+     * `pack` with 400, `skill` with 403, `knowledge` and `secret` with advice);
+     * `agent` was the one that answered a plausible lie with a success code.
+     *
+     * The wording is `knowledge`'s, because both routes out are real: an
+     * organization key names a workspace per invocation, a workspace key
+     * carries one permanently.
+     */
     if (
       !command.meta.offline
       && !workspaceFlag
-      && !ORG_SCOPED_NOUNS.has(command.meta.noun)
+      // A missing argument outranks a missing workspace, for the reason the
+      // project gate above gives: `skill pull` with no skill named has a
+      // better error waiting inside the command, and it names the command
+      // that produces the value. Let it be raised.
+      && !missingArg
+      && commandScope(command.meta) === 'workspace'
       && 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.',
+      throw new CliError(
+        `\`${label}\` acts inside a workspace, `
+        + 'and this organization key names none',
+        {
+          code: 'FORBIDDEN',
+          hint: 'pass --workspace <id> (see `frontera workspace list`), '
+            + 'or use a workspace key (sk-ws-…) created for the workspace you mean',
+        },
       )
     }
 

package/src/scopes.ts

@@ -0,0 +1,56 @@
+/**
+ * Which grain each noun acts at — stated once.
+ *
+ * This map had grown three copies: the dispatcher's unaddressed-organization-key
+ * note, the list of nouns `--workspace` can reach, and the hint a 403 carries.
+ * They had already disagreed — `action` appeared in none of them, so an
+ * organization key running `action list` was warned about workspace scope by a
+ * sentence that did not mention `action`, and refused by a hint that called
+ * Actions organization-scoped.
+ *
+ * The noun map is a DEFAULT, not the answer: `commandScope` below lets a verb
+ * override it, because several nouns span both grains.
+ *
+ * There is no scope field on a command to derive this from, and adding one to
+ * silence a note would be the wrong trade — the grain is a fact about the
+ * SERVICE's routes, not about the command that calls them. So it is listed, and
+ * listed here only.
+ */
+
+/**
+ * Nouns whose routes answer at organization grain.
+ *
+ * A workspace key is refused these BY DESIGN — it is not a narrower
+ * organization key, it is a different lane. `auth` and `kit` are here because
+ * naming a workspace means nothing to them, not because they reach the service.
+ */
+export const ORG_SCOPED_NOUNS = new Set([
+  'auth',
+  'kit',
+  'workspace',
+  'blueprint',
+  'dataset',
+  'source',
+  // Governed Actions live under `/v1/blueprint/governed-actions` and carry the
+  // Blueprint's grain, which is why a workspace key is refused `action list`.
+  'action',
+])
+
+/**
+ * The grain one command acts at.
+ *
+ * The verb's own declaration wins; otherwise the noun's. Most nouns are
+ * uniform, so declaring all 129 would be noise that rots — and the ones that
+ * are not uniform are precisely the ones a per-noun map gets wrong.
+ */
+export function commandScope(meta: {
+  noun: string
+  scope?: 'workspace' | 'organization'
+}): 'workspace' | 'organization' {
+  return meta.scope ?? (ORG_SCOPED_NOUNS.has(meta.noun) ? 'organization' : 'workspace')
+}
+
+/** For prose: the organization-scoped nouns that actually reach the service. */
+export function orgScopedServiceNouns(): string[] {
+  return [...ORG_SCOPED_NOUNS].filter((n) => n !== 'auth' && n !== 'kit').sort()
+}