@frontera-sdk/cli 1.45.9 → 1.45.10

package/package.json

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

package/src/api/automation-api.ts

@@ -56,6 +56,13 @@ export interface AutomationRunSummary {
   startedAt: string
   finishedAt: string | null
   version: number
+  /**
+   * The frozen input this run was started with, or absent/null when the
+   * automation declares none. Optional in the type rather than required
+   * because an older service predating this field would omit it entirely —
+   * current ones serve it on both the list and the detail route.
+   */
+  input?: Record<string, unknown> | null
 }
 
 /** A row of `GET /v1/automations/runs/<id>/steps`. */
@@ -145,13 +152,26 @@ export class AutomationApi {
    * cron.
    */
   /** `version` omitted runs the live one — the behaviour every caller had before
-   *  the parameter existed, and the one the service still defaults to. */
+   *  the parameter existed, and the one the service still defaults to.
+   *
+   *  `input` rides in the same body for both the live and the dev shape, but
+   *  the service does NOT validate it against declared `inputs` either way:
+   *  for a live run it does (schema check, defaults applied, frozen onto the
+   *  row `startRun` produces); for `dev: true` this route only enforces the
+   *  size cap — schema validation of a dev run's input happens on the
+   *  author's own machine, in the dev worker, against the local file's
+   *  freshly built manifest (the live schema has no bearing on it). */
   run(
     slug: string,
     version?: number,
     dev?: boolean,
+    input?: Record<string, unknown>,
   ): Promise<{ slug: string; version: number | null; queued: boolean; dev?: boolean }> {
-    const body = dev ? { dev: true } : version === undefined ? undefined : { version }
+    const body = dev
+      ? { dev: true, ...(input !== undefined ? { input } : {}) }
+      : version === undefined && input === undefined
+        ? undefined
+        : { ...(version === undefined ? {} : { version }), ...(input === undefined ? {} : { input }) }
     return this.client.request(`/v1/automations/${encodeURIComponent(slug)}/run`, {
       method: 'POST',
       body,
@@ -195,7 +215,15 @@ export class AutomationApi {
     manifest: Record<string, unknown>,
   ): Promise<{
     held: boolean
-    run: { runId: string; runToken: string; grants: string[]; workspaceId: string } | null
+    run: {
+      runId: string
+      runToken: string
+      grants: string[]
+      workspaceId: string
+      /** The frozen input this run was started with, or absent/null when the
+       *  automation declares none — same shape as `AutomationRunSummary.input`. */
+      input?: Record<string, unknown> | null
+    } | null
   }> {
     const q = `sessionId=${encodeURIComponent(sessionId)}&holderId=${encodeURIComponent(holderId)}`
     return this.client.request(

package/src/automation-template.ts

@@ -35,6 +35,12 @@ export const AUTOMATION_SDK_FILES = [
   // in, shared with the runner.
   'frontera/automation/messages.ts',
   'frontera/automation/testing.ts',
+  // `inputs.ts` is authoring surface too: `validateInputValue` is what a
+  // handler's own tests and the Console call to check a value against the
+  // manifest's `inputs` schema, and `index.ts` re-exports it — so omitting it
+  // breaks a scaffolded project's typecheck the same way skipping `testing.ts`
+  // would.
+  'frontera/automation/inputs.ts',
   'frontera/blueprint/types.ts',
 ] as const
 

package/src/blueprint-types.ts

@@ -6,7 +6,11 @@ import { CliError, UsageError } from './errors'
 export const BLUEPRINT_TYPES_MARKER = '// Generated by `frontera blueprint generate-types`. Do not edit.'
 export const DEFAULT_BLUEPRINT_TYPES_OUTPUT = 'src/generated/frontera-blueprint.ts'
 
-export type BlueprintDataType = 'string' | 'number' | 'boolean' | 'date' | 'timestamp' | 'json'
+/** Mirrors the service's `DataType`. `media_reference` is first-class (spec
+ *  §4/§12): it generates a named struct rather than `unknown`, and the schema
+ *  publishes it as neither filterable nor sortable, so the generated
+ *  `BlueprintRegistry` cannot offer a predicate the query layer refuses. */
+export type BlueprintDataType = 'string' | 'number' | 'boolean' | 'date' | 'timestamp' | 'json' | 'media_reference'
 export type BlueprintPropertyType = 'attribute' | 'measure' | 'time'
 
 export interface BlueprintSchemaProperty {
@@ -33,7 +37,7 @@ export interface BlueprintSchemaResponse {
   objectTypes: BlueprintSchemaObject[]
 }
 
-const DATA_TYPES = new Set<BlueprintDataType>(['string', 'number', 'boolean', 'date', 'timestamp', 'json'])
+const DATA_TYPES = new Set<BlueprintDataType>(['string', 'number', 'boolean', 'date', 'timestamp', 'json', 'media_reference'])
 const PROPERTY_TYPES = new Set<BlueprintPropertyType>(['attribute', 'measure', 'time'])
 
 function schemaContractError(detail: string): never {
@@ -99,6 +103,29 @@ export function parseBlueprintSchema(input: unknown): BlueprintSchemaResponse {
   return input as BlueprintSchemaResponse
 }
 
+/**
+ * The canonical wire shape of a media reference (spec §3.3), emitted as a named
+ * type so an App reads `file.mediaItemId` rather than narrowing `unknown`.
+ *
+ * The set and item ids are strings, not a branded id type: the reference is an
+ * identity handle and nothing in the App may act on it except by handing it
+ * back to an authorized content route. `kind` is pinned to the literal so a
+ * hand-built object cannot masquerade as one.
+ */
+const MEDIA_REFERENCE_TYPE_NAME = 'FronteraMediaReference'
+
+const MEDIA_REFERENCE_TYPE_DECLARATION = [
+  '/** An opaque handle to one immutable item in a Media Set. Possessing it grants',
+  ' *  nothing: every preview or download reauthorizes. It cannot be filtered,',
+  ' *  sorted or compared — ask `!== null` to test presence. */',
+  `export interface ${MEDIA_REFERENCE_TYPE_NAME} {`,
+  "  kind: 'media'",
+  '  mediaSetId: string',
+  '  mediaItemId: string',
+  '  mimeType: string',
+  '}',
+]
+
 const TYPE_BY_DATA_TYPE: Readonly<Record<BlueprintDataType, string>> = {
   string: 'string',
   number: 'number',
@@ -106,6 +133,7 @@ const TYPE_BY_DATA_TYPE: Readonly<Record<BlueprintDataType, string>> = {
   date: 'string',
   timestamp: 'string',
   json: 'unknown',
+  media_reference: MEDIA_REFERENCE_TYPE_NAME,
 }
 
 function jsDoc(value: string | null): string[] {
@@ -224,6 +252,15 @@ export function generateBlueprintTypes(schema: BlueprintSchemaResponse): string
     '',
   ]
 
+  // Declared only when something uses it, so a Blueprint with no media field
+  // generates byte-identical output to what it generated before the type
+  // existed — a generated file that churns is a generated file nobody trusts.
+  if (objects.some((objectType) => objectType.properties.some(
+    (property) => property.dataType === 'media_reference',
+  ))) {
+    lines.push(...MEDIA_REFERENCE_TYPE_DECLARATION, '')
+  }
+
   for (const objectType of objects) {
     lines.push(...jsDoc(objectType.description), `export interface ${objectType.apiName} {`)
     for (const property of objectType.properties) {

package/src/commands/automation/dev.ts

@@ -6,7 +6,7 @@ import { buildContext } from '@frontera-sdk/automation/runtime'
 import { AutomationApi } from '../../api/automation-api'
 import { CliError, UsageError } from '../../errors'
 import { type Command, type CommandContext } from '../types'
-import { validateManifest } from '@frontera-sdk/automation'
+import { validateInputValue, validateManifest, type InputsSchema } from '@frontera-sdk/automation'
 import { buildAndExtract } from './build-entry'
 
 /**
@@ -37,7 +37,15 @@ const POLL_MS = 1_000
  *  of step with it. */
 export interface DevPollResult {
   held: boolean
-  run: { runId: string; runToken: string; grants: string[]; workspaceId: string } | null
+  run: {
+    runId: string
+    runToken: string
+    grants: string[]
+    workspaceId: string
+    /** The frozen input this run was started with, or absent/null when the
+     *  automation declares none — mirrors `AutomationApi.devPoll`'s return type. */
+    input?: Record<string, unknown> | null
+  } | null
 }
 
 /**
@@ -110,7 +118,10 @@ export function newDevStepState(): DevStepState {
  */
 export function localStepTools(
   state: DevStepState = newDevStepState(),
-): { run<T>(id: string, fn: () => Promise<T>): Promise<unknown> } {
+): {
+  run<T>(id: string, fn: () => Promise<T>): Promise<unknown>
+  sleep(id: string, ms: number): Promise<void>
+} {
   // Reset per EXECUTION, not per run: it counts what this pass has replayed, so
   // the next unmemoized name can be checked against the recorded order.
   let replayed = 0
@@ -166,6 +177,34 @@ export function localStepTools(
       // this exists to reproduce.
       throw new StepYield()
     },
+
+    async sleep(id: string, _ms: number): Promise<void> {
+      // Dev runs are DRY end to end — a real wait here would make the author
+      // sit through production pacing to test a branch. Recorded for the
+      // determinism check, resolved immediately.
+      //
+      // Same order/replay bookkeeping as `run`, above, storing `null` as the
+      // memoized value: there is no body result to round-trip, only a name to
+      // hold the position steady across resumptions.
+      const expected = state.order[replayed]
+      if (expected !== undefined && expected !== id) {
+        throw new Error(
+          `this automation is not deterministic: step ${replayed + 1} was `
+            + `"${expected}" on an earlier execution and is "${id}" now. The platform `
+            + 'replays completed steps by position, so the two runs would be handed '
+            + "each other's results. Move anything conditional INSIDE a step.",
+        )
+      }
+
+      if (state.memo.has(id)) {
+        replayed += 1
+        return
+      }
+
+      state.order.push(id)
+      state.memo.set(id, null)
+      throw new StepYield()
+    },
   }
 }
 
@@ -255,6 +294,32 @@ function mtimeOf(path: string): number {
   }
 }
 
+/**
+ * Applies the dev-run startup gate to a `validateManifest` result.
+ *
+ * Same "cron has nobody to ask" carve-out the poll applies at
+ * automation-router.ts (`/dev/session/poll`): that rule exists for an
+ * UNATTENDED fire — a cron trigger has nobody to prompt, so a required
+ * field with no default would fail every scheduled tick. A dev run is the
+ * opposite of unattended — it is a manual fire by definition, and the value
+ * the rule worries about missing is exactly what `--input` (or the
+ * Console's dev-run form) supplies at claim time.
+ *
+ * Without this carve-out HERE too — at the file this command reads before a
+ * session is even opened — the router-side exemption never gets a chance to
+ * matter: a local file that adds `trigger: { cron }` plus such a field could
+ * never START a dev worker at all, so `run --dev` just timed out with no
+ * session for it to claim against. Any OTHER manifest error still refuses to
+ * start, same as before.
+ */
+export function devStartupManifestGate(errors: string[]): { blocking: string[]; warning?: string } {
+  const blocking = errors.filter((e) => !e.includes('cron has nobody to ask'))
+  if (blocking.length === 0 && errors.length > 0) {
+    return { blocking, warning: errors.join('; ') }
+  }
+  return { blocking }
+}
+
 export const automationDev: Command = {
   meta: {
     noun: 'automation',
@@ -277,6 +342,7 @@ export const automationDev: Command = {
       throw new UsageError('missing <file>', 'frontera automation dev <file>')
     }
     const entry = resolve(file)
+    const out = ctx.output
 
     // Built once up front for its MANIFEST: the slug is what the session is
     // opened against, and building later would mean claiming a session for a
@@ -285,10 +351,14 @@ export const automationDev: Command = {
     let { manifest } = await buildAndExtract(entry)
     const invalid = validateManifest(manifest)
     if (!invalid.valid) {
-      throw new UsageError(
-        `${file} does not describe a valid automation:\n  ${invalid.errors.join('\n  ')}`,
-        'fix the manifest, then run the command again',
-      )
+      const gate = devStartupManifestGate(invalid.errors)
+      if (gate.blocking.length > 0) {
+        throw new UsageError(
+          `${file} does not describe a valid automation:\n  ${gate.blocking.join('\n  ')}`,
+          'fix the manifest, then run the command again',
+        )
+      }
+      out.note(`[dev] ${gate.warning} — allowed for a dev run, which is always manual`)
     }
     let lastMtime = mtimeOf(entry)
     // VALIDATED HERE, once, before a session is opened.
@@ -318,7 +388,6 @@ export const automationDev: Command = {
     const holderId = crypto.randomUUID()
     const session = await api.devSessionOpen(slug, entry, holderId)
 
-    const out = ctx.output
     out.note(`[dev] ${slug} — running from ${file}`)
     out.note(`[dev] connected to ${ctx.apiUrl}`)
     // The first question an author has is whether this disturbs production, and
@@ -332,7 +401,7 @@ export const automationDev: Command = {
     // and then watches runs scroll past; a caveat printed per run is noise, and
     // one printed nowhere is a surprise the first time they wonder why a query
     // came back empty.
-    out.note('[dev] runs are DRY — ctx.agent, ctx.http and ctx.blueprint return empty and send nothing')
+    out.note('[dev] runs are DRY — ctx.agent, ctx.plugin, ctx.http and ctx.blueprint return empty and send nothing')
     if (session.created) out.note(`[dev] created the automation "${slug}" (no version yet)`)
     out.note(`[dev] waiting — press Run dev in the Console, or \`frontera automation run ${slug} --dev\``)
 
@@ -417,6 +486,24 @@ export const automationDev: Command = {
           throw new Error(`${file} has no automation() default export`)
         }
 
+        // The rule this PR advertises — "the author's local file is the
+        // authority for a dev run" — is broken by anything short of running
+        // the SAME check live runs get, against THIS build's manifest. Without
+        // it a `default: false` field arrives as `false` live and `undefined`
+        // here, and there is nothing to catch it: this build never went
+        // through the run route's fast 400, only the poll's manifest check.
+        // Same validator, same wording as the run route / `startRun`
+        // (`Invalid run input: …`) — thrown so it lands in the catch below,
+        // which is the one place that already reports a handler failure back
+        // to both the terminal and the Console.
+        const inputCheck = validateInputValue(
+          (built.manifest as { inputs?: InputsSchema }).inputs,
+          run.input ?? undefined,
+        )
+        if (!inputCheck.ok) {
+          throw new Error(`Invalid run input: ${inputCheck.errors.join('; ')}`)
+        }
+
         // Entered once per step, not once per run — see `localStepTools`. A
         // fresh context each time, because production builds one per resumption
         // and its duplicate-name set is scoped to a single execution.
@@ -428,6 +515,9 @@ export const automationDev: Command = {
             grants: run.grants,
             step,
             serviceUrl: ctx.apiUrl,
+            // Validated and defaulted, not the raw claim — `inputCheck.value`
+            // is `{}` only when the automation truly declares no inputs.
+            input: inputCheck.value,
           }),
         )
         await finishDevRun(ctx.apiUrl, run.runId, run.runToken, { status: 'succeeded', result })
@@ -437,9 +527,10 @@ export const automationDev: Command = {
         out.note(`[dev] run ${run.runId.slice(0, 8)} finished (dry) in ${Date.now() - started}ms`)
       } catch (err) {
         const message = err instanceof Error ? err.message : String(err)
-        // A build error is reported as a FAILED RUN, not only here: the person
-        // who pressed Run is looking at the Console, and an error that appears
-        // only in a terminal they may not be watching reads as a hang.
+        // A build error, a bad input, or a handler throw is reported as a
+        // FAILED RUN, not only here: the person who pressed Run is looking at
+        // the Console, and an error that appears only in a terminal they may
+        // not be watching reads as a hang.
         await finishDevRun(ctx.apiUrl, run.runId, run.runToken, {
           status: 'failed',
           errorMessage: message,

package/src/commands/automation/run.ts

@@ -5,6 +5,7 @@ import {
   type AutomationRunSummary,
   type RegistryStatus,
 } from '../../api/automation-api'
+import { readSecretValue } from '../../secrets'
 import { flagBool, flagString, type Command, type CommandContext } from '../types'
 
 /**
@@ -135,6 +136,42 @@ export function parseVersionFlag(ctx: CommandContext): number | undefined {
   return parsed
 }
 
+/**
+ * `--input '<json>'`, `--input @file.json`, or `--input @-` (stdin), as the
+ * object the run starts with.
+ *
+ * Parsed and shape-checked here, before anything reaches the network, for the
+ * same reason `parseVersionFlag` rejects locally: forwarded as-is, malformed
+ * JSON or a non-object value would arrive at the service as a 400 whose
+ * message describes the WRONG thing — either a parse failure with no line the
+ * author can see, or a schema violation against a field that does not exist.
+ *
+ * `@…` reads through `readSecretValue` — the same helper `secret set` and
+ * `login` use to turn an unwrapped `readFileSync`'s raw ENOENT into a
+ * `UsageError` the dispatcher has a case for, rather than an internal error
+ * with no hint, for what is simply a typoed path. Reusing it rather than
+ * hand-rolling the read a second time is also what makes `--input @-` (stdin)
+ * work here at all: `readSecretValue` already treats `-` as the stdin
+ * convention, the same one the rest of the CLI's `@`-prefixed arguments use.
+ */
+export async function parseInputFlag(ctx: CommandContext): Promise<Record<string, unknown> | undefined> {
+  const raw = flagString(ctx, 'input')
+  if (raw === undefined) return undefined
+  const text = raw.startsWith('@') ? await readSecretValue(raw) : raw
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(text)
+  } catch {
+    throw new UsageError(
+      '--input must be a JSON object (or @file.json)',
+      '--input \'{"key": "value"}\'',
+    )
+  }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new UsageError('--input must be a JSON object', '--input \'{"key": "value"}\'')
+  }
+  return parsed as Record<string, unknown>
+}
 
 /**
  * Wait for the run this invoke started, and read its trail.
@@ -177,6 +214,15 @@ export function describeRun(run: AutomationRunSummary, steps: AutomationRunStep[
   const where = run.version === null ? 'from a dev session' : `v${run.version}`
   const lines = [`${run.status} — ${where}, ${run.ctxCalls} ctx call(s)`]
   if (run.errorMessage) lines.push(`  ${run.errorMessage}`)
+  // What the run STARTED with, alongside what it returned. Present only when
+  // the detail response carries one — an automation with no declared inputs,
+  // or a listing route that omits the field, prints nothing extra here.
+  // Emptiness, not presence: the service coalesces the column to {} on every
+  // row, so a presence check would print `input {}` on every run of every
+  // automation — the web run panel guards the same way.
+  if (run.input && Object.keys(run.input).length > 0) {
+    lines.push(`  input ${JSON.stringify(run.input)}`)
+  }
   // The trail is why an author ran this by hand: which steps executed, in what
   // order, and where the time went. Without it the CLI reported an outcome and
   // sent them to the Console to find out what happened.
@@ -206,13 +252,15 @@ export const automationRun: Command = {
     noun: 'automation',
     verb: 'run',
     args: [{ name: 'slug', required: true, description: 'automation slug' }],
-    flags: { 'no-wait': 'boolean', version: 'string', dev: 'boolean' },
+    flags: { 'no-wait': 'boolean', version: 'string', dev: 'boolean', input: 'string' },
     summary: 'Run the live version now — or a named one, or the dev session — and report what it did',
     examples: [
       'frontera automation run daily-digest',
       'frontera automation run daily-digest --dev',
       'frontera automation run daily-digest --version 7',
       'frontera automation run daily-digest --no-wait',
+      'frontera automation run ktp-extraction --input \'{"file_path":"files/…"}\'',
+      'frontera automation run ktp-extraction --input @input.json',
     ],
   },
 
@@ -224,6 +272,7 @@ export const automationRun: Command = {
     // service as `NaN` would come back as a schema error naming a field the
     // author never typed.
     const version = parseVersionFlag(ctx)
+    const input = await parseInputFlag(ctx)
     const dev = flagBool(ctx, 'dev')
     if (dev && version !== undefined) {
       throw new UsageError(
@@ -243,7 +292,7 @@ export const automationRun: Command = {
       // the dev run.
       const before = await client.runs(slug, 1, 'dev')
       const priorId = before[0]?.id ?? null
-      const queued = await client.run(slug, undefined, true)
+      const queued = await client.run(slug, undefined, true, input)
       if (flagBool(ctx, 'no-wait')) {
         return {
           data: queued,
@@ -289,7 +338,7 @@ export const automationRun: Command = {
     const before = await client.runs(slug, 1)
     const priorId = before[0]?.id ?? null
 
-    const queued = await client.run(slug, version)
+    const queued = await client.run(slug, version, undefined, input)
 
     if (flagBool(ctx, 'no-wait')) {
       return {

package/src/exit.ts

@@ -102,7 +102,84 @@ const SERVICE_HINTS: Record<string, string> = {
   SERVICE_UNAVAILABLE: 'the service is unavailable — retry shortly',
 }
 
-function isFronteraError(err: unknown): err is { code: string; message: string } {
+/**
+ * Hints for the organization-key lane's refusals, keyed by the `detail`
+ * discriminator the service attaches to a 403.
+ *
+ * These exist because the FORBIDDEN hint above is wrong for them, not merely
+ * vague. It sends the operator to an admin, and for a lane refusal there is no
+ * admin action and no other organization key that changes the answer: the
+ * refusal is a property of the ROUTE, not of the credential. Telling somebody
+ * to ask for a grant they may already hold costs a support round-trip and ends
+ * where it started.
+ *
+ * A grant refusal — `check-permission.ts`, the ordinary "this key was not
+ * granted that capability" — carries no `detail` at all, and for that one the
+ * existing hint is exactly right. So absence is meaningful here, and it must
+ * fall through to the FORBIDDEN hint untouched rather than acquire one of its
+ * own.
+ */
+const ORG_KEY_REFUSAL_HINTS: Record<string, string> = {
+  'org-key-route-closed':
+    'this route is not open to organization keys — use a session login or a workspace key, '
+    + 'or open the lane (docs/specs/2026-08-25-org-key-lane-coverage-spec.md)',
+  'org-key-route-ungated':
+    'this route performs no permission check an organization key can satisfy — '
+    + 'no grant and no admin changes that',
+  'org-key-workspace-not-listed':
+    '--workspace names a workspace this key does not list — name one it lists, '
+    + 'or drop the flag to run at organization scope',
+}
+
+/**
+ * Read the refusal discriminator out of a service error's body.
+ *
+ * TWO SHAPES, because the service states the same kind of fact through two
+ * mechanisms and they serialize differently. A lane refusal is a hook's
+ * `status(403, …)`, so `detail` sits at the top level of the body. The
+ * workspace refusal is an `AppError` carrying `details`, and the service's
+ * `createErrorResponse` nests whatever that was under a `details` key — so the
+ * same string arrives one level deeper. Reading only the shape one happened to
+ * test against silently loses the other, and the one it would lose is the
+ * header mistake, which is the most fixable of the three.
+ *
+ * `details` on a `FronteraError` is the parsed response body, whatever it was:
+ * `errorFromResponse` in the SDK and every construction site in `src/api` put
+ * the body there verbatim. It is therefore unenumerated and untrusted, which is
+ * why this checks shapes rather than casting.
+ */
+function refusalDetail(details: unknown): string | undefined {
+  if (typeof details !== 'object' || details === null) return undefined
+  const body = details as { detail?: unknown; details?: unknown }
+  if (typeof body.detail === 'string') return body.detail
+  const nested = body.details
+  if (typeof nested === 'object' && nested !== null) {
+    const inner = (nested as { detail?: unknown }).detail
+    if (typeof inner === 'string') return inner
+  }
+  return undefined
+}
+
+/**
+ * The best hint available for a service error: the refusal-specific one when
+ * the body names a refusal this CLI knows, the per-code one otherwise.
+ *
+ * An unrecognised `detail` falls through to the code's hint rather than to
+ * nothing, on the same reasoning `exitCodeFor` records: the service can add a
+ * discriminator without a CLI release, so "never seen it" has to stay ordinary.
+ */
+function hintFor(code: string, details: unknown): string | undefined {
+  const detail = refusalDetail(details)
+  if (detail !== undefined) {
+    const specific = ORG_KEY_REFUSAL_HINTS[detail]
+    if (specific) return specific
+  }
+  return SERVICE_HINTS[code]
+}
+
+function isFronteraError(
+  err: unknown,
+): err is { code: string; message: string; details?: unknown } {
   return (
     err instanceof Error &&
     'code' in err &&
@@ -122,7 +199,7 @@ export function toEnvelope(err: unknown): ErrorEnvelope {
   }
 
   if (isFronteraError(err)) {
-    const hint = SERVICE_HINTS[err.code]
+    const hint = hintFor(err.code, err.details)
     return { error: true, code: err.code, message: err.message, ...(hint ? { hint } : {}) }
   }
 

package/src/flag-help.ts

@@ -67,6 +67,7 @@ export const FLAG_HELP: Readonly<Record<string, string>> = {
   'no-git': 'scaffold without creating a repository and an initial commit',
   'no-components': 'scaffold without fetching the baseline shadcn components',
   version: 'version to publish, overriding the one in package.json',
+  input: "JSON object of the automation's declared inputs — inline ('{\"key\": 1}') or @file.json",
   'no-promote': 'publish the version without moving the live pointer',
   'no-wait': 'return as soon as the run is queued instead of waiting for it to finish',
   // Named for what it RUNS, not where it runs: an author reads this to decide