@frontera-sdk/cli 1.52.44 → 1.52.46

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frontera-sdk/cli",
-  "version": "1.52.44",
+  "version": "1.52.46",
   "description": "The frontera CLI — scaffold, pull, save and deploy Frontera apps and automations.",
   "keywords": [
     "frontera",
@@ -40,8 +40,8 @@
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.3.251",
     "@faker-js/faker": "10.6.0",
-    "@frontera-sdk/core": "1.52.44",
-    "@frontera-sdk/functions": "1.52.44",
+    "@frontera-sdk/core": "1.52.46",
+    "@frontera-sdk/functions": "1.52.46",
     "ai": "^6.0.116",
     "axe-core": "4.12.1",
     "gray-matter": "^4.0.3",
@@ -49,7 +49,7 @@
     "yaml": "^2.9.0"
   },
   "devDependencies": {
-    "@frontera-sdk/forge-contracts": "1.52.44",
+    "@frontera-sdk/forge-contracts": "1.52.46",
     "@types/bun": "^1.3.14",
     "typescript": "^5.9.3"
   }

package/src/api/apps-api.ts

@@ -144,10 +144,12 @@ export class AppsApi {
     slug: string,
     displayName: string,
     appId?: string | null,
+    /** Used only when this creates the App: its icon from `frontera.config.json` (X6). */
+    opts: { icon?: string } = {},
   ): Promise<{ id: string; slug: string; created: boolean }> {
     return this.client.request<{ id: string; slug: string; created: boolean }>('/v1/platform-apps/ensure', {
       method: 'POST',
-      body: appId ? { slug, displayName, appId } : { slug, displayName },
+      body: { ...(appId ? { slug, displayName, appId } : { slug, displayName }), ...(opts.icon ? { icon: opts.icon } : {}) },
     })
   }
 

package/src/api/automation-api.ts

@@ -29,6 +29,19 @@ export interface AutomationVersionSummary {
 }
 
 /** One agent↔automation binding, as the bindings routes return it. */
+/** A Custom App bound to a Function: it may start the Function as the person using it. */
+export interface AppFunctionBinding {
+  appId: string
+  appSlug: string
+  appDisplayName: string
+  enabled: boolean
+  createdBy: string
+  createdAt: string
+  /** Whether it would start anything now: false while the Function has nothing live or the binding is off. */
+  projects?: boolean
+  inertReason?: 'no_live_version' | 'disabled' | null
+}
+
 export interface AgentAutomationBinding {
   agentId: string
   agentSlug: string
@@ -387,6 +400,25 @@ export class AutomationApi {
     )
   }
 
+  /** Which Custom Apps may start this Function (X6): the App lane's own permission, beside the agent bindings. */
+  appBindings(slug: string): Promise<AppFunctionBinding[]> {
+    return this.client.request<AppFunctionBinding[]>(`/v1/functions/${encodeURIComponent(slug)}/app-bindings`)
+  }
+
+  bindApp(slug: string, appSlug: string, options: { enabled?: boolean } = {}): Promise<AppFunctionBinding> {
+    return this.client.request<AppFunctionBinding>(
+      `/v1/functions/${encodeURIComponent(slug)}/app-bindings/${encodeURIComponent(appSlug)}`,
+      { method: 'PUT', body: options },
+    )
+  }
+
+  unbindApp(slug: string, appSlug: string): Promise<{ unbound: boolean }> {
+    return this.client.request<{ unbound: boolean }>(
+      `/v1/functions/${encodeURIComponent(slug)}/app-bindings/${encodeURIComponent(appSlug)}`,
+      { method: 'DELETE' },
+    )
+  }
+
   setEnabled(slug: string, enabled: boolean): Promise<{ slug: string; enabled: boolean }> {
     return this.client.request<{ slug: string; enabled: boolean }>(
       `/v1/functions/${encodeURIComponent(slug)}/enabled`,

package/src/api/credential-failure.ts

@@ -66,7 +66,7 @@ export function credentialFailure(
     return person
       ? new CliError('The session token was refused — it has expired or been signed out.', {
         code: 'UNAUTHORIZED',
-        hint: 'sign in again, then set FRONTERA_TOKEN to the new session token',
+        hint: 'sign in again with `frontera auth login --browser`',
       })
       : new CliError(
         'The credential was refused. An organization key that has been revoked or has '

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

@@ -478,6 +478,30 @@ export class GovernedActionApi {
     )
   }
 
+  /** The Action's definition id: on the draft first, where an Action lives before it has ever published, else the release. */
+  async actionDefinitionId(apiName: string): Promise<string | null> {
+    const drafted = (await this.listDraftActions().catch(() => [])).find((a) => a.apiName === apiName)
+    if (typeof drafted?.id === 'string') return drafted.id
+    const published = await this.publishedAction(apiName).catch(() => null)
+    return (published?.definition as { id?: string } | undefined)?.id ?? null
+  }
+
+  /** The Action's current deployment decision, or null when it has none. */
+  async currentDeployment(actionDefinitionId: string): Promise<{ stateId: string; state: string; generation: number; bindingRevisionId: string | null } | null> {
+    const page = await this.call<{ entries?: Array<{ stateId: string; state: string; generation: number; bindingRevisionId: string | null }> }>(
+      `/v1/blueprint/governed-actions/admin/deployments?actionDefinitionId=${encodeURIComponent(actionDefinitionId)}`,
+    )
+    return page?.entries?.[0] ?? null
+  }
+
+  /** Stand a deployment decision down: one that was never bound, or a draining one (the service refuses the rest). */
+  retireDeployment(stateId: string, expectedGeneration: number, reason: string): Promise<{ stateId?: string; state?: string; generation?: number }> {
+    return this.call(`/v1/blueprint/governed-actions/admin/deployments/${encodeURIComponent(stateId)}/retire`, {
+      method: 'POST',
+      body: { expectedGeneration, reason },
+    })
+  }
+
   /**
    * Bindings at their newest revision, each with `deployment`: the CURRENT
    * state of the Action it binds (null when the Action has none). Every

package/src/api/media-api.ts

@@ -29,6 +29,15 @@ export interface MediaSet {
   itemCount?: number
 }
 
+/** A file staged for an Action: its preallocated item id is the Action's upload input. */
+export interface StagedUpload {
+  mediaItemId: string
+  path: string
+  mimeType: string
+  sizeBytes: number
+  state: string
+}
+
 export interface MediaItem {
   mediaItemId: string
   path: string
@@ -140,6 +149,21 @@ export class MediaApi {
     return (await this.call<{ item: MediaItem }>(`${this.set(mediaSetId)}/items`, { form })).item
   }
 
+  /**
+   * One file staged for an Action to attach (L6): nothing is in the set until
+   * an Action request that carries the returned id as its upload input applies.
+   */
+  async stage(
+    mediaSetId: string,
+    file: { bytes: Uint8Array; filename: string; mime: string; logicalPath: string; markings?: string },
+  ): Promise<StagedUpload> {
+    const form = new FormData()
+    form.set('file', new File([new Blob([file.bytes.buffer as ArrayBuffer])], file.filename, { type: file.mime }))
+    form.set('logicalPath', file.logicalPath)
+    if (file.markings) form.set('markings', file.markings)
+    return (await this.call<{ upload: StagedUpload }>(`${this.set(mediaSetId)}/uploads`, { form })).upload
+  }
+
   extraction(mediaSetId: string): Promise<ExtractionStatus> {
     return this.call(`${this.set(mediaSetId)}/extraction`)
   }

package/src/api/platform-api.ts

@@ -359,6 +359,19 @@ export class PlatformApi {
     })
   }
 
+  /** The Agent's behavior settings as its draft and live version hold them (`operating.json`'s source). */
+  agentOperatingConfig(id: string) {
+    return this.client.request<{ draft?: unknown; live?: unknown } | null>(`/v1/config/agents/${encodeURIComponent(id)}/operating`)
+  }
+
+  /** Stage the Agent's behavior settings on its draft; `null` takes them all away. They take effect when it is published. */
+  stageAgentOperatingConfig(id: string, operatingConfig: Record<string, unknown> | null) {
+    return this.client.request<unknown>(`/v1/config/agents/${encodeURIComponent(id)}/operating`, {
+      method: 'PUT',
+      body: { operatingConfig },
+    })
+  }
+
   discardAgentDraft(id: string) {
     return this.client.request<unknown>(`/v1/config/agents/${encodeURIComponent(id)}/draft-v2`, {
       method: 'DELETE',

package/src/binding-registry.ts

@@ -28,6 +28,8 @@ import { configDir, type Env } from './paths'
 
 export interface Binding {
   profile: string
+  /** The organization profile bound beside it for organization-scoped commands (X3). */
+  organizationProfile?: string
   boundAt: string
 }
 
@@ -59,9 +61,9 @@ function read(env: Env): BindingFile {
   }
 }
 
-export function recordBinding(root: string, profile: string, env: Env = process.env): void {
+export function recordBinding(root: string, profile: string, env: Env = process.env, organizationProfile?: string): void {
   const file = read(env)
-  file.roots[key(root)] = { profile, boundAt: new Date().toISOString() }
+  file.roots[key(root)] = { profile, ...(organizationProfile ? { organizationProfile } : {}), boundAt: new Date().toISOString() }
   writeFileAtomic(bindingsPath(env), `${JSON.stringify(file, null, 2)}\n`, 0o600)
 }
 
@@ -85,3 +87,8 @@ export function forgetBinding(root: string, env: Env = process.env): void {
 export function isTrustedBinding(root: string, profile: string, env: Env = process.env): boolean {
   return bindingFor(root, env)?.profile === profile
 }
+
+/** This machine bound `organizationProfile` beside the root's profile (`auth use --org-profile`, X3). */
+export function isTrustedOrganizationBinding(root: string, organizationProfile: string, env: Env = process.env): boolean {
+  return bindingFor(root, env)?.organizationProfile === organizationProfile
+}

package/src/blueprint/compile.ts

@@ -446,6 +446,8 @@ export function declaredPropertyType(property: Record<string, unknown>, sharedPr
 }
 
 export function actionWithoutMintedIds(document: Record<string, unknown>): Record<string, unknown> {
+  // `attachment` is the project's deployment choice for the local runtime (L6), not part of the Action's contract.
+  const { attachment: _deployment, ...contract } = document
   const drop = (value: unknown): unknown => {
     if (Array.isArray(value)) return value.map(drop)
     if (!value || typeof value !== 'object') return value
@@ -459,7 +461,7 @@ export function actionWithoutMintedIds(document: Record<string, unknown>): Recor
     }
     return out
   }
-  return drop(document) as Record<string, unknown>
+  return drop(contract) as Record<string, unknown>
 }
 
 export function actionBody(file: AuthoredFile): Record<string, unknown> {

package/src/blueprint/ontology-edit-plan.ts

@@ -31,7 +31,22 @@ export interface ObjectTypeShape {
   id: string
   apiName: string
   primaryKeyPropertyId: string | null
-  properties: Array<{ id?: string; apiName?: string }>
+  properties: Array<{ id?: string; apiName?: string; valueType?: string; mediaSetId?: string | null }>
+}
+
+/**
+ * What an attachment Action fills (L6): the file arrives in `uploadInput` (a
+ * staged upload's id, or a run's `{ fileId }`), and the Media write gate puts
+ * it in `mediaSetId` and fills `property` (a media reference), `itemIdProperty`
+ * (a string that keeps the item's id), or both. Stated at deploy, because an
+ * Action's own contract has no input kind that says "this is a file".
+ */
+export interface MediaAttachmentChoice {
+  property?: string
+  itemIdProperty?: string
+  uploadInput: string
+  /** Defaults to the media reference property's own set. */
+  mediaSetId?: string
 }
 
 export interface OntologyEditPlan {
@@ -45,6 +60,7 @@ export interface OntologyEditPlan {
   set: Record<string, string>
   pkParameter: string
   expectedVersionParameter?: string
+  mediaAttachment?: { propertyApiName?: string; itemIdProperty?: string; mediaSetId: string; uploadParameter: string }
   impactBounds: { maxAffectedRows: number; maxTouchedRows: number }
   capabilities: Record<string, unknown>
 }
@@ -87,6 +103,7 @@ const OP_FOR_EFFECT: Readonly<Record<string, OntologyEditPlan['op']>> = {
 export function deriveOntologyEditPlan(
   action: PublishedActionDefinition,
   objectType: ObjectTypeShape,
+  attachment?: MediaAttachmentChoice,
 ): OntologyEditPlan {
   const op = OP_FOR_EFFECT[action.effect.kind]
   if (!op) {
@@ -132,8 +149,13 @@ export function deriveOntologyEditPlan(
     }
   }
 
-  // The plan must map at least one parameter, so constants alone cannot be deployed.
-  if (op !== 'delete' && Object.keys(set).length === 0) {
+  const mediaAttachment = attachment ? attachmentOf(action, objectType, attachment, set) : undefined
+  if (mediaAttachment && op === 'delete') {
+    throw new PlanDerivationError(`Action "${action.apiName}" deletes its record, so it has nothing to attach a file to.`, 'Attach the file with an Action that creates or updates the record.')
+  }
+
+  // The plan must map at least one parameter (or attach a file), so constants alone cannot be deployed.
+  if (op !== 'delete' && Object.keys(set).length === 0 && !mediaAttachment) {
     throw new PlanDerivationError(
       constants.length
         ? `Action "${action.apiName}" sets only constants (${constants.join(', ')}), and its write path needs at least one property set from an input.`
@@ -199,6 +221,12 @@ export function deriveOntologyEditPlan(
       'Add a required input { apiName: expectedVersion, valueType: { kind: number, integer: true, minimum: 0 } }: the record version the change was decided on (a query row\'s _meta.recordVersion).',
     )
   }
+  if (mediaAttachment && [pkParameter, expectedVersionParameter].includes(mediaAttachment.uploadParameter)) {
+    throw new PlanDerivationError(
+      `Action "${action.apiName}" takes the file in ${mediaAttachment.uploadParameter}, which already ${mediaAttachment.uploadParameter === pkParameter ? 'addresses the record' : 'carries the record version'}.`,
+      'Give the file its own input: every mapped parameter carries exactly one role.',
+    )
+  }
   if (expectedVersionParameter && Object.values(set).includes(expectedVersionParameter)) {
     throw new PlanDerivationError(
       `Action "${action.apiName}" writes a property from expectedVersion, which carries the record version.`,
@@ -211,9 +239,10 @@ export function deriveOntologyEditPlan(
     kind: 'ontology_edit',
     targetCompatibility: {
       kind: 'ontology_edit',
+      // The attachment's properties count as used, as the service's `ontologyEditUsedProperties` counts them.
       expectedFingerprint: ontologyEditCompatibilityFingerprint(
         objectType.id,
-        Object.keys(set),
+        [...Object.keys(set), ...(mediaAttachment?.propertyApiName ? [mediaAttachment.propertyApiName] : []), ...(mediaAttachment?.itemIdProperty ? [mediaAttachment.itemIdProperty] : [])],
       ),
     },
     objectTypeId: objectType.id,
@@ -222,6 +251,7 @@ export function deriveOntologyEditPlan(
     set,
     pkParameter,
     ...(expectedVersionParameter ? { expectedVersionParameter } : {}),
+    ...(mediaAttachment ? { mediaAttachment } : {}),
     // One subject, because the Action itself declares `impact.maxSubjects: 1`
     // and the schema admits no other value.
     impactBounds: { maxAffectedRows: 1, maxTouchedRows: 1 },
@@ -237,3 +267,40 @@ export function deriveOntologyEditPlan(
     },
   }
 }
+
+/** The plan's `mediaAttachment` for this choice, checked against the Action and its object type. */
+function attachmentOf(
+  action: PublishedActionDefinition,
+  objectType: ObjectTypeShape,
+  choice: MediaAttachmentChoice,
+  set: Record<string, string>,
+): NonNullable<OntologyEditPlan['mediaAttachment']> {
+  if (!choice.property && !choice.itemIdProperty) {
+    throw new PlanDerivationError('An attachment fills a media reference property, an item id property, or both.', 'Pass --attach <media property>, --attach-item-id <text property>, or both.')
+  }
+  if (!action.inputs.some((i) => i.apiName === choice.uploadInput)) {
+    throw new PlanDerivationError(`Action "${action.apiName}" takes no "${choice.uploadInput}" input for the file.`, 'Add a string input for the staged upload (`frontera media stage` prints its id), publish, then deploy.')
+  }
+  if (Object.values(set).includes(choice.uploadInput)) {
+    throw new PlanDerivationError(`Action "${action.apiName}" already writes a property from ${choice.uploadInput}.`, 'Give the file its own input: every mapped parameter carries exactly one role.')
+  }
+  const property = (name: string) => objectType.properties.find((p) => p.apiName === name)
+  for (const name of [choice.property, choice.itemIdProperty]) {
+    if (!name) continue
+    if (!property(name)) throw new PlanDerivationError(`Object type "${objectType.apiName}" has no property "${name}".`, 'Name a property of the Action\'s object type.')
+    if (Object.prototype.hasOwnProperty.call(set, name)) throw new PlanDerivationError(`Action "${action.apiName}" already sets ${name} from an input, so the attachment can't fill it.`, 'Remove that change from the Action, or attach into another property.')
+  }
+  if (choice.property && choice.property === choice.itemIdProperty) {
+    throw new PlanDerivationError('The media reference and the item id cannot be the same property.', 'Name two properties, or one of them.')
+  }
+  const mediaSetId = choice.mediaSetId ?? (choice.property ? property(choice.property)?.mediaSetId ?? undefined : undefined)
+  if (!mediaSetId) {
+    throw new PlanDerivationError('The attachment names no Media Set.', 'Pass --media-set <id> (`frontera media list` shows the ids).')
+  }
+  return {
+    ...(choice.property ? { propertyApiName: choice.property } : {}),
+    ...(choice.itemIdProperty ? { itemIdProperty: choice.itemIdProperty } : {}),
+    mediaSetId,
+    uploadParameter: choice.uploadInput,
+  }
+}

package/src/blueprint/org-name-check.ts

@@ -0,0 +1,64 @@
+import { localProject } from '../local/local-project'
+import { syncClient, unwrap, type SyncClient } from '../local/local-sync-client'
+import { getSyncKey, readLink } from '../local/local-sync-link'
+import type { ArtifactKind } from './model'
+
+/**
+ * Whether a new Blueprint artifact's API name is already the organization's
+ * (Forge improvement plan X11). A workspace sees only its slice of the
+ * organization's Blueprint, so `blueprint new object-type Activity` wrote a
+ * file a change request then refused: the organization had an `Activity`
+ * outside the slice (P5 A9). Read with the project's organization key from
+ * `frontera local sync connect`; without a link or that key it is not
+ * checked, and says so.
+ */
+export type NameCheck =
+  | { checked: false; why: string }
+  | { checked: true; taken: false }
+  | { checked: true; taken: true; as: string }
+
+/** Where each kind's names are in the organization's Blueprint definition. */
+const KEYS: Record<ArtifactKind, string> = {
+  'object-type': 'objects',
+  'link-type': 'relationships',
+  'shared-field': 'sharedProperties',
+  'semantic-type': 'semanticTypes',
+  metric: 'metrics',
+  action: 'actions',
+}
+
+/** The API names a definition holds for a kind. */
+export function namesIn(definition: Record<string, unknown> | null | undefined, kind: ArtifactKind): string[] {
+  const list = definition?.[KEYS[kind]]
+  return Array.isArray(list) ? list.flatMap((e) => (typeof (e as { apiName?: unknown })?.apiName === 'string' ? [(e as { apiName: string }).apiName] : [])) : []
+}
+
+export async function orgNameCheck(root: string, kind: ArtifactKind, apiName: string, deps: { client?: SyncClient | null } = {}): Promise<NameCheck> {
+  let client = deps.client ?? null
+  if (!client) {
+    const project = localProject(root)
+    const link = readLink(project.root)
+    if (!link) return { checked: false, why: 'the project is linked to no workspace' }
+    const key = getSyncKey(project, 'organization')
+    if (!key) return { checked: false, why: 'the project has no organization key (`frontera local sync connect --org-key -`)' }
+    client = syncClient(link.platform, key)
+  }
+  try {
+    const found = await client.find<unknown>('/v1/blueprint/lifecycle')
+    if (!found) return { checked: true, taken: false }
+    const lifecycle = unwrap<{ draft?: { definition?: Record<string, unknown> } | null; activeRelease?: { definition?: Record<string, unknown> } | null }>(found)
+    const names = new Set([...namesIn(lifecycle.activeRelease?.definition, kind), ...namesIn(lifecycle.draft?.definition, kind)])
+    // The same name in other letters is the same name to a reader, and to a URL.
+    const as = [...names].find((n) => n.toLowerCase() === apiName.toLowerCase())
+    return as ? { checked: true, taken: true, as } : { checked: true, taken: false }
+  } catch (err) {
+    return { checked: false, why: `the organization's Blueprint couldn't be read (${(err as Error).message})` }
+  }
+}
+
+/** What `blueprint new` says about the check, or null when there is nothing to say. */
+export function nameCheckWords(kind: ArtifactKind, apiName: string, check: NameCheck): string | null {
+  if (!check.checked || !check.taken) return null
+  const word = kind.replace('-', ' ')
+  return `warning: the organization already has a ${word} ${check.as}${check.as === apiName ? '' : ` (the same name to a reader)`}. If it is outside this workspace's Blueprint, a change request refuses a new one of that name: give this one a more specific API name (Sales${apiName[0]!.toUpperCase()}${apiName.slice(1)}), or ask a Blueprint Steward to grant the workspace the organization's`
+}

package/src/blueprint/tree.ts

@@ -22,7 +22,35 @@ import {
 
 const READABLE = new Set(['.yaml', '.yml', '.json'])
 
+/**
+ * Where a file fails to parse, as an editor jumps to it: `path:line:col: why`
+ * (Forge improvement plan N9). One YAML error used to fail every item in the
+ * Blueprint with no file name. Null when the text parses.
+ */
+export function parseProblem(path: string, text: string): string | null {
+  try {
+    if (extname(path) === '.json') JSON.parse(text)
+    else parseYaml(text)
+    return null
+  } catch (err) {
+    const e = err as { message?: string; linePos?: Array<{ line: number; col: number }> }
+    const at = e.linePos?.[0] ?? (() => {
+      // JSON: "… at position 41" (or "line 3 column 5").
+      const lc = /line (\d+) column (\d+)/.exec(e.message ?? '')
+      if (lc) return { line: Number(lc[1]), col: Number(lc[2]) }
+      const pos = /position (\d+)/.exec(e.message ?? '')
+      if (!pos) return null
+      const before = text.slice(0, Number(pos[1])).split('\n')
+      return { line: before.length, col: before[before.length - 1]!.length + 1 }
+    })()
+    const why = (e.message ?? 'does not parse').split('\n')[0]!.replace(/ at line \d+, column \d+:?$/, '').trim()
+    return `${path}${at ? `:${at.line}:${at.col}` : ''}: ${why}`
+  }
+}
+
 export function parseDocument(path: string, text: string): Record<string, unknown> {
+  const problem = parseProblem(path, text)
+  if (problem) throw new CliError(problem, { code: 'BLUEPRINT_FILE_INVALID', hint: 'fix the file at that line; nothing in the Blueprint was applied' })
   const parsed = extname(path) === '.json' ? JSON.parse(text) : parseYaml(text)
   if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
     throw new CliError(`${path} does not contain a mapping.`, {

package/src/commands/action/deploy.ts

@@ -29,11 +29,12 @@ export const actionDeploy: Command = {
     // organization key carrying `actionMutationPlan`/`actionBinding` runs this.
     authLane: 'api-key',
     args: [{ name: 'action', required: true, description: 'The published Action’s API name' }],
-    flags: { 'dry-run': 'boolean', 'plan-id': 'string', 'binding-id': 'string' },
+    flags: { 'dry-run': 'boolean', 'plan-id': 'string', 'binding-id': 'string', attach: 'string', 'attach-item-id': 'string', 'file-input': 'string', 'media-set': 'string' },
     summary: 'Build and validate the write path for a published Action',
     examples: [
       'frontera action deploy escalateTicket --dry-run',
       'frontera action deploy escalateTicket',
+      'frontera action deploy attachPhoto --attach photo --file-input upload',
     ],
   },
 
@@ -55,9 +56,24 @@ export const actionDeploy: Command = {
       })
     }
 
+    // An attachment Action (L6): the file arrives in --file-input, and the write fills --attach and/or --attach-item-id.
+    const attachProperty = flagString(ctx, 'attach')
+    const attachItemId = flagString(ctx, 'attach-item-id')
+    const fileInput = flagString(ctx, 'file-input')
+    const mediaSet = flagString(ctx, 'media-set')
+    if ((attachProperty || attachItemId || mediaSet) && !fileInput) {
+      throw new UsageError('an attachment needs the input the file arrives in', `frontera action deploy ${apiName} --attach <media property> --file-input <input>`)
+    }
+    if (fileInput && !attachProperty && !attachItemId) {
+      throw new UsageError('--file-input names where the file arrives, and nothing says what it fills', `add --attach <media property> or --attach-item-id <text property>`)
+    }
+    const attachment = fileInput
+      ? { uploadInput: fileInput, ...(attachProperty ? { property: attachProperty } : {}), ...(attachItemId ? { itemIdProperty: attachItemId } : {}), ...(mediaSet ? { mediaSetId: mediaSet } : {}) }
+      : undefined
+
     let plan
     try {
-      plan = deriveOntologyEditPlan(definition, objectType)
+      plan = deriveOntologyEditPlan(definition, objectType, attachment)
     } catch (err) {
       if (err instanceof PlanDerivationError) {
         throw new CliError(err.message, { code: 'VALIDATION_ERROR', hint: err.hint })
@@ -65,9 +81,10 @@ export const actionDeploy: Command = {
       throw err
     }
 
-    const writes = Object.entries(plan.set)
-      .map(([property, parameter]) => `${property} ← ${parameter}`)
-      .join(', ')
+    const writes = [
+      ...Object.entries(plan.set).map(([property, parameter]) => `${property} ← ${parameter}`),
+      ...(plan.mediaAttachment ? [`${[plan.mediaAttachment.propertyApiName, plan.mediaAttachment.itemIdProperty].filter(Boolean).join(' and ')} ← the file in ${plan.mediaAttachment.uploadParameter} (Media Set ${plan.mediaAttachment.mediaSetId})`] : []),
+    ].join(', ')
 
     if (flagBool(ctx, 'dry-run')) {
       return {

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

@@ -6,6 +6,7 @@ import { actionGrant } from './grant'
 import { actionList } from './list'
 import { actionPrepare } from './prepare'
 import { actionRequests } from './requests'
+import { actionRetire } from './retire'
 import { actionReview } from './review'
 import { actionSubmit } from './submit'
 import type { Command } from '../types'
@@ -41,6 +42,7 @@ export const actionCommands: readonly Command[] = [
   actionReject,
   actionCancel,
   actionPrepare,
+  actionRetire,
   actionDeploy,
   actionReview,
   actionGrant,

package/src/commands/action/retire.ts

@@ -0,0 +1,60 @@
+import { GovernedActionApi } from '../../api/governed-action-api'
+import { CliError, UsageError } from '../../errors'
+import { flagString, type Command } from '../types'
+
+/**
+ * Retire an Action's deployment decision (Forge improvement plan X11).
+ *
+ * `action prepare` records that a drafted Action ships switched off, and the
+ * decision pins the Action's contract as it was then: editing the drafted
+ * Action after preparing it left it stranded, since publish refuses the
+ * changed contract and a second prepare refuses a second decision. Retiring
+ * the decision stands it down, so `action prepare` can record one for the
+ * contract as it is now.
+ *
+ * Only a decision that was never bound, or one already draining, retires:
+ * the service refuses an active deployment, which is switched off first. It
+ * arms nothing and removes nothing from the Blueprint. It takes a signed-in
+ * person with `actionBinding: retire`.
+ */
+export const actionRetire: Command = {
+  meta: {
+    noun: 'action',
+    verb: 'retire',
+    authLane: 'session',
+    args: [{ name: 'action', required: true, description: 'The Action’s API name' }],
+    flags: { reason: 'string' },
+    summary: 'Retire an Action’s deployment decision, so a changed draft can be prepared again',
+    details: [
+      'For an Action prepared before its draft changed: retire, then `frontera action prepare <action>` records a decision for the contract as it is now.',
+      'An active deployment is refused: switch it off in Console first.',
+    ],
+    examples: [
+      'frontera action retire escalateTicket --reason "draft changed"',
+      'frontera action prepare escalateTicket',
+    ],
+  },
+
+  async run(ctx) {
+    const apiName = ctx.positional[0]
+    if (!apiName) throw new UsageError('missing <action>', 'frontera action retire escalateTicket --reason "…"')
+    const reason = flagString(ctx, 'reason')?.trim()
+    if (!reason) throw new UsageError('say why with --reason', 'the reason is kept with the deployment’s history: frontera action retire escalateTicket --reason "the draft changed after it was prepared"')
+
+    const client = new GovernedActionApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
+    const definitionId = await client.actionDefinitionId(apiName)
+    if (!definitionId) throw new CliError(`No Action "${apiName}" on the draft or in the release.`, { code: 'ACTION_NOT_FOUND', hint: 'frontera action list' })
+    const current = await client.currentDeployment(definitionId)
+    if (!current) {
+      return { data: { action: apiName, retired: false }, text: `"${apiName}" carries no deployment decision: nothing to retire. \`frontera action prepare ${apiName}\` records one.` }
+    }
+    if (current.state === 'active') {
+      throw new CliError(`"${apiName}" is deployed and switched on; an active deployment isn't retired.`, { code: 'CONFLICT', hint: 'switch it off in Console (the Action’s deployment) first, then retire it' })
+    }
+    const retired = await client.retireDeployment(current.stateId, current.generation, reason)
+    return {
+      data: { action: apiName, retired: true, from: current.state, deployment: retired },
+      text: `Retired the ${current.state} deployment decision of "${apiName}".\n\nNext:\n  frontera action prepare ${apiName}`,
+    }
+  },
+}

package/src/commands/agent/compose.ts

@@ -57,6 +57,7 @@ export function renderComposition(snapshot: Row, lookups: Lookups): string {
     ['id', str(config, 'id') || (lookups.identity?.id ?? '')],
     ['status', str(config, 'lifecycleStatus')],
     ['default mode', str(config, 'defaultMode')],
+    ['fallback mode', str(config, 'fallbackMode')],
     ['live version', lookups.identity?.version ? String(lookups.identity.version) : ''],
   ] as Array<[string, string]>) {
     if (v) lines.push(`${k.padEnd(14)}${v}`)