@frontera-sdk/cli 1.45.6 → 1.45.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frontera-sdk/cli",
-  "version": "1.45.6",
+  "version": "1.45.8",
   "description": "The frontera CLI — scaffold, pull, save and deploy Frontera apps and automations.",
   "keywords": [
     "frontera",
@@ -38,13 +38,13 @@
     "build:release": "bun run scripts/build-release.ts"
   },
   "dependencies": {
-    "@frontera-sdk/automation": "1.45.2",
-    "@frontera-sdk/core": "1.45.2",
+    "@frontera-sdk/automation": "1.45.7",
+    "@frontera-sdk/core": "1.45.7",
     "gray-matter": "^4.0.3",
     "yaml": "^2.9.0"
   },
   "devDependencies": {
-    "@types/bun": "latest",
+    "@types/bun": "^1.3.14",
     "typescript": "^5.9.3"
   }
 }

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,6 @@
 import { CliError } from '../errors'
+import { credentialFailure } from './credential-failure'
+import { formatValidationDetails } from './validation-detail'
 import type { DefinitionBundle } from '../blueprint/model'
 
 /**
@@ -40,30 +42,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
@@ -77,7 +61,16 @@ export class BlueprintAuthoringApi {
           hint: 'frontera blueprint status',
         })
       }
-      throw new CliError(payload?.message ?? `${res.status} ${text.slice(0, 200)}`, { code: 'FAILURE', hint: 'frontera blueprint status' })
+      // The service's refusal often carries a TypeBox details array naming the
+      // exact fields — `/pluralName`, a valueType outside the enum — and this
+      // path used to flatten all of it to "Validation failed". On the verb that
+      // WRITES the draft, that reasonless refusal was the whole error a caller
+      // saw, and the audit read it as an unusable write path.
+      const detail = formatValidationDetails(payload?.details)
+      throw new CliError(payload?.message ?? `${res.status} ${text.slice(0, 200)}`, {
+        code: (payload?.code as string) ?? 'FAILURE',
+        hint: detail ?? 'frontera blueprint status',
+      })
     }
 
     return (payload?.data ?? payload) as T
@@ -330,7 +323,15 @@ export class BlueprintAuthoringApi {
 
   // ── release lifecycle ─────────────────────────────────────────────────────
 
-  validate(): Promise<{ id?: string; reportId?: string }> {
+  validate(): Promise<{
+    id?: string
+    reportId?: string
+    draftRevision?: number
+    draftDigest?: string
+    baseReleaseDigest?: string
+    catalogProjection?: { objectTypes?: unknown[]; linkTypes?: unknown[] }
+    evolution?: { changes?: unknown[] }
+  }> {
     return this.call('/v1/blueprint/lifecycle/validate', { method: 'POST', body: {} })
   }
 

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,8 @@ import { readFileSync } from 'node:fs'
 import { basename } from 'node:path'
 
 import { CliError } from '../errors'
+import { credentialFailure } from './credential-failure'
+import { formatValidationDetails } from './validation-detail'
 
 /**
  * Datasets, from the CLI.
@@ -99,9 +101,24 @@ 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
+      // `details` is TypeBox's own error array. Stringified it was unreadable,
+      // and this is the last gate before a Source exists.
+      const detail = formatValidationDetails(payload?.details)
       throw new CliError(payload?.message ?? `Request failed (${response.status}).`, {
         code: payload?.code ?? 'FAILURE',
-        ...(payload?.details ? { hint: JSON.stringify(payload.details) } : {}),
+        // A refused CONNECTION is not a malformed document, and telling someone
+        // to re-read their file sends them to the wrong place entirely: the
+        // service dials the database itself, from wherever it runs.
+        hint: detail
+          ?? (response.status === 409
+            ? 'the service dials the database itself — check host and port are reachable '
+              + 'from where the service runs, and that the password on stdin is current'
+            : 'check the document against `frontera source create --help`'),
       })
     }
     return (payload?.data ?? payload) as T
@@ -282,6 +299,28 @@ export class DatasetApi {
     return this.call<DatasetSummary>('/v1/data-integration/datasets/from-file', { form })
   }
 
+  /**
+   * Rows into a dataset that already exists, as a new snapshot.
+   *
+   * `createFromFile` is CREATE-time only. A blank dataset — declared columns,
+   * no rows, and the common first step — had no way to receive data afterwards
+   * through the CLI, so an agent told its user the capability did not exist.
+   * It does: the service republishes against the CURRENT column contract and
+   * repoints the dataset atomically, keeping the prior snapshot on any failure.
+   *
+   * The file must match that contract exactly — names, types, nullability. A
+   * schema change is refused here by design; it is a new revision, not a
+   * re-upload.
+   */
+  uploadSnapshot(datasetId: string, path: string): Promise<DatasetSummary> {
+    const form = new FormData()
+    form.append('file', new Blob([readFileSync(path)]), basename(path))
+    return this.call<DatasetSummary>(
+      `/v1/data-integration/datasets/${encodeURIComponent(datasetId)}/snapshots`,
+      { form },
+    )
+  }
+
   createBlank(payload: {
     apiName: string
     displayName: string

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/api/validation-detail.ts

@@ -0,0 +1,87 @@
+/**
+ * Turn the service's validation `details` into something a person can act on.
+ *
+ * The service answers a rejected document with TypeBox's own error array, and
+ * the CLI put it on screen with `JSON.stringify`:
+ *
+ *   [{"summary":"Expected 'virtual'","type":32,"schema":{"const":"virtual",
+ *   "type":"string"},"path":"/datasets/0/mode","message":"Expected 'virtual'",
+ *   "errors":[]}]
+ *
+ * Every fact a caller needs is in there, and none of it is legible. The path is
+ * buried mid-line, the schema fragment is noise, and `type: 32` is an internal
+ * enum. `source create` was unusable through this: it is the last gate before a
+ * Source exists, and it answered with a machine's notes.
+ */
+
+interface TypeBoxError {
+  path?: string
+  message?: string
+  summary?: string
+  value?: unknown
+}
+
+/** `/datasets/0/mode` reads better as `datasets[0].mode`. */
+export function readablePath(path: string | undefined): string {
+  if (!path || path === '/') return '(document root)'
+  return path
+    .replace(/^\//, '')
+    .split('/')
+    .map((segment) => (/^\d+$/.test(segment) ? `[${segment}]` : `.${segment}`))
+    .join('')
+    .replace(/^\./, '')
+    .replace(/\.\[/g, '[')
+}
+
+/**
+ * Whether these errors all point at a discriminator.
+ *
+ * A discriminated union reports the field it switches on when ANY branch fails,
+ * so `mode: "virtual"` is rejected with "Expected 'virtual'" while the real
+ * defect is somewhere else in that branch entirely. Silently correct and
+ * completely misleading, and it cost an audit an afternoon — so when the shape
+ * matches, the hint says so rather than letting the caller stare at a field
+ * that is already right.
+ */
+export function looksLikeDiscriminator(errors: TypeBoxError[]): boolean {
+  return (
+    errors.length > 0
+    && errors.every((e) => /^Expected '.*'$/.test(e.message ?? e.summary ?? ''))
+  )
+}
+
+/**
+ * One line per error, plus a note when the paths cannot be trusted.
+ *
+ * Returns `undefined` when there is nothing structured to say, so the caller
+ * keeps whatever hint it already had rather than showing an empty one.
+ */
+export function formatValidationDetails(details: unknown): string | undefined {
+  const errors = Array.isArray(details) ? (details as TypeBoxError[]) : null
+  if (!errors || errors.length === 0) return undefined
+
+  const lines = errors
+    .filter((e) => e && typeof e === 'object')
+    .map((e) => {
+      const message = e.message ?? e.summary ?? 'is not valid'
+      return `${readablePath(e.path)} — ${message}`
+    })
+  if (lines.length === 0) return undefined
+
+  // Capped: a document with fifty problems produces fifty lines, and the first
+  // few are the ones anybody reads. The count says what was left out rather
+  // than letting the list end without saying so.
+  const SHOWN = 5
+  const shown = lines.slice(0, SHOWN)
+  if (lines.length > SHOWN) shown.push(`… and ${lines.length - SHOWN} more`)
+
+  if (looksLikeDiscriminator(errors)) {
+    shown.push(
+      'that field may already be correct — a discriminated union reports the '
+      + 'field it switches on when any part of that branch fails, so look at '
+      + 'the rest of the same object',
+    )
+  }
+
+  return shown.join('\n  ')
+}

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[]),
   ])
 
@@ -364,13 +368,26 @@ const diff: Command = {
   },
   async run(ctx) {
     const t = await target(ctx, 'diff')
-    const draft = await t.api.agentDraft(t.id)
+    // Both, before either branch answers: "the live version is current" is as
+    // wrong for an agent that has never published as "matches the live
+    // version" is, and that branch used to answer without ever looking.
+    const [draft, live] = await Promise.all([
+      t.api.agentDraft(t.id),
+      t.api.agent(t.id) as Promise<Record<string, unknown>>,
+    ])
+    const published = Boolean(live.currentVersion ?? live.currentVersionId)
 
     if (!draft) {
-      return { data: { hasDraft: false, changed: [] }, text: 'No draft staged — the live version is current.' }
+      return {
+        data: { hasDraft: false, published, changed: [] },
+        text: published
+          ? 'No draft staged — the live version is current.'
+          : 'No draft staged, and nothing is published — this agent has no configuration '
+            + 'of its own yet.\n'
+            + `  Stage one with \`frontera agent apply ${t.ref} --file <path>\`.`,
+      }
     }
 
-    const live = (await t.api.agent(t.id)) as Record<string, unknown>
     const liveConfig = (live.config ?? live) as Record<string, unknown>
     const draftConfig = (draft.snapshot.config ?? {}) as Record<string, unknown>
 
@@ -417,11 +434,15 @@ const diff: Command = {
     ].sort()
 
     return {
-      data: { hasDraft: true, revision: draft.revision, changed },
+      data: { hasDraft: true, revision: draft.revision, published, changed },
       text:
-        changed.length === 0
-          ? `Draft revision ${draft.revision} matches the live version.`
-          : [`Draft revision ${draft.revision} differs in:`, ...changed.map((k) => `  ${k}`)].join('\n'),
+        changed.length > 0
+          ? [`Draft revision ${draft.revision} differs in:`, ...changed.map((k) => `  ${k}`)].join('\n')
+          : published
+            ? `Draft revision ${draft.revision} matches the live version.`
+            : `Draft revision ${draft.revision}. Nothing is published yet, so there is `
+              + 'nothing to compare against — the draft IS the whole configuration.\n'
+              + `  Publish it with \`frontera agent publish ${t.ref}\`.`,
     }
   },
 }

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