@frontera-sdk/cli 1.50.79 → 1.50.81

package/src/commands/registry.ts

@@ -31,8 +31,11 @@ import { capabilityCommands } from './capability/index-commands'
 import { datasetCommands } from './dataset/index-commands'
 import { sourceCommands } from './source/index-commands'
 import { knowledgeCommands } from './knowledge/index-commands'
+import { mediaCommands } from './media/index-commands'
 import { packCommands } from './pack/index-commands'
 import { secretCommands } from './secret/index-commands'
+import { chatAppCommands } from './chat-app/index-commands'
+import { markingCommands } from './marking/index-commands'
 import { automationCommands } from './automation/index-commands'
 import { workflowCommands } from './workflow/index-commands'
 import { completionCommand } from './completion'
@@ -102,8 +105,10 @@ export const COMMANDS: readonly Command[] = [
   ...datasetCommands,
   ...sourceCommands,
   ...knowledgeCommands,
+  ...mediaCommands,
   ...packCommands,
   ...secretCommands,
+  ...chatAppCommands,
   ...automationCommands,
   ...workflowCommands,
 
@@ -121,6 +126,7 @@ export const COMMANDS: readonly Command[] = [
   blueprintBind,
   blueprintEditable,
   blueprintGrant,
+  ...markingCommands,
 
   ...actionCommands,
 ]
@@ -164,9 +170,11 @@ const NOUN_SUMMARY: Readonly<Record<string, string>> = {
   knowledge: 'Knowledge bases and the sources inside them',
   pack: 'Reusable skill bundles — author once, install per workspace',
   secret: 'Workspace secrets — named here, never printed back',
+  'chat-app': 'Chat Apps — stage, publish and open an Agent roster',
   function: 'Functions — TypeScript deployed here, run on a schedule',
   workflow: 'Workflows — declared steps, versioned, promoted, then run',
   blueprint: 'The shared model of the organization — what an app can read',
+  marking: 'Security markings — who may see which marked Blueprint rows',
   action: 'Governed Actions — arm the write path a published Action runs',
   capability: 'What an agent may DO — plugin operations granted to it',
   auth: 'Credential profiles — one per API key, selected by directory',
@@ -179,6 +187,11 @@ export function nounSummary(noun: string): string {
   return NOUN_SUMMARY[noun] ?? ''
 }
 
+const KEYS_ARE_SETTINGS_ONLY =
+  'organization keys are managed in Organization settings → API Keys, workspace keys in '
+  + 'Workspace settings → API Keys — by a signed-in administrator, never by the CLI: a '
+  + 'credential that mints credentials is the escalation that separation exists to prevent'
+
 /**
  * Where the CLI ends, and what to do instead.
  *
@@ -202,8 +215,12 @@ export const UNSUPPORTED: Readonly<Record<string, string>> = {
   channel:
     'channels have no CLI surface — create one and bind it to an agent in the Console, '
     + 'under the agent’s Channels tab',
-  key: 'API keys are minted in the Console, never by the CLI — a credential that mints credentials '
-    + 'is the escalation that separation exists to prevent',
+  key: KEYS_ARE_SETTINGS_ONLY,
+  // The names a caller reaches for when the goal is provisioning or rotating an
+  // organization key. The service routes are session-only by construction, so
+  // there is nothing for a key-holding CLI to call.
+  'org-key': KEYS_ARE_SETTINGS_ONLY,
+  'api-key': KEYS_ARE_SETTINGS_ONLY,
   sheet: 'sheets have no CLI surface and none is planned',
   task: 'task and run history is Console-only; `frontera function runs` covers function runs',
   eval: 'the evaluation suite (datasets, scorers, judges, queues) is Console-only',
@@ -262,7 +279,7 @@ const GLOBAL_SECTION = [
     ['FRONTERA_API_URL', 'Frontera API origin'],
     // Upstream's key-kind detail, kept — profiles change where a key is stored,
     // not which kinds are valid.
-    ['FRONTERA_TOKEN', 'sk-ws-… or sk-org-… — requires FRONTERA_API_URL or --api-url'],
+    ['FRONTERA_TOKEN', 'sk-ws-… or sk-org-… key, or a session token for session-only commands — requires FRONTERA_API_URL or --api-url'],
     ['FRONTERA_PROFILE', 'profile to use, overriding the directory selection'],
     ['FRONTERA_SECRET_STORE', 'where keys are stored: keychain (default on macOS) or file'],
     ['NO_COLOR', 'set to disable colour'],
@@ -370,6 +387,12 @@ export function renderNounHelp(noun: string): string {
   return lines.join('\n')
 }
 
+/** The help line every session-lane command prints — see `SESSION_LANE_HINT`. */
+export const SESSION_LANE_HELP =
+  'Needs a person’s session, not an API key. Set FRONTERA_TOKEN to your session token '
+  + 'and FRONTERA_API_URL (or pass --api-url). sk-ws- and sk-org- keys are refused with '
+  + '401 or 403; `frontera login` stores keys only.'
+
 export function renderCommandHelp(meta: CommandMeta): string {
   const width = terminalWidth()
   const lines = [accent(usage(meta)), '', ...wrap(meta.summary, width)]
@@ -385,8 +408,7 @@ export function renderCommandHelp(meta: CommandMeta): string {
     lines.push(
       '',
       ...wrap(
-        'Needs a session credential: run `frontera login`. This command’s endpoints '
-        + 'refuse sk-ws- and sk-org- keys, and answer 401 rather than a permission error.',
+        SESSION_LANE_HELP,
         width,
       ).map(dim),
     )
@@ -456,7 +478,7 @@ export interface CommandDescriptor {
   requiresCredential: boolean
   /**
    * `api-key` — reachable with `sk-ws-`/`sk-org-` or a session.
-   * `session`  — reachable ONLY with a session token from `frontera login`.
+   * `session`  — reachable ONLY with a person's session token in `FRONTERA_TOKEN`.
    */
   authLane: 'api-key' | 'session'
 }

package/src/commands/types.ts

@@ -68,6 +68,12 @@ export interface CommandMeta {
    * that forgets to declare this is far more likely to be on it.
    */
   authLane?: 'api-key' | 'session'
+  /**
+   * Session-lane only: where a person does this in the product, e.g.
+   * `Blueprint → Access → Markings`. Appended to `SESSION_LANE_HINT` when a key
+   * is refused, so a noun names its way out without rewording the refusal.
+   */
+  sessionAlternative?: string
   /**
    * Present → the command is planned but unbuilt, and fails with this message.
    * Reserved in the table rather than omitted: a caller reading "unknown

package/src/commands/workflow/list.ts

@@ -16,7 +16,7 @@ export const workflowList: Command = {
     verb: 'list',
     args: [],
     flags: {},
-    summary: 'List workflows, their live version and what can start them',
+    summary: 'List workflows in service, their live version and what can start them. Archived workflows are left out',
     examples: ['frontera workflow list'],
   },
 

package/src/errors.ts

@@ -13,8 +13,9 @@ export class CliError extends Error {
   readonly code: string
   readonly hint?: string
 
-  constructor(message: string, opts: { code: string; hint?: string }) {
-    super(message)
+  /** `cause` keeps the original error — and its `details` — when one is reworded. */
+  constructor(message: string, opts: { code: string; hint?: string; cause?: unknown }) {
+    super(message, opts.cause === undefined ? undefined : { cause: opts.cause })
     this.name = 'CliError'
     this.code = opts.code
     if (opts.hint) this.hint = opts.hint

package/src/exit.ts

@@ -1,4 +1,6 @@
-import { CliError } from './errors'
+import { PERSON_FORBIDDEN_HINT } from './api/credential-failure'
+import { CliError, UsageError } from './errors'
+import { commandLabel, commandScope } from './scopes'
 
 /**
  * Exit codes, one per action the caller can take.
@@ -61,6 +63,11 @@ const AUTH_CODES = new Set([
   'FORBIDDEN',
   // The key is gone, not merely unselected — same recovery as a revoked one.
   'PROFILE_SECRET_MISSING',
+  // Policy refusals the service keeps its own code for: separation of duties,
+  // and rows behind a marking the caller is not cleared for. Neither ever
+  // succeeds on retry, which is what exit 1 would tell a script to do.
+  'ACTION_FORBIDDEN',
+  'DATASET_ROWS_COMPARTMENTED',
 ])
 
 /**
@@ -212,3 +219,121 @@ export function toEnvelope(err: unknown): ErrorEnvelope {
     message: err instanceof Error ? err.message : String(err),
   }
 }
+
+/**
+ * The one recovery for a key sent to a command that acts as a person.
+ *
+ * `frontera login` and `auth add` store only `sk-ws-`/`sk-org-` keys, so the
+ * session has to come from the environment. Worded once here because every
+ * session-lane noun meets the same refusal — 401 on session-only routers, 403
+ * on programmatic ones — and per-API copies of this sentence had started to
+ * drift apart.
+ */
+export const SESSION_LANE_HINT =
+  'this command acts as a person and refuses API keys — set FRONTERA_TOKEN to your session token '
+  + 'and FRONTERA_API_URL, then re-run; `frontera login` stores keys only'
+
+/** What a session-lane command needs to know about itself to word a refusal. */
+export interface SessionLaneMeta {
+  noun: string
+  verb: string
+  scope?: 'workspace' | 'organization'
+  authLane?: 'api-key' | 'session'
+  sessionAlternative?: string
+}
+
+/** The first line a key reads on a session-lane command. */
+export function sessionLaneKeyMessage(meta: { noun: string; verb: string }): string {
+  return `\`${commandLabel(meta)}\` acts as a person; API keys are refused`
+}
+
+/**
+ * The hint that replaces a failure's own on a session-lane command, or
+ * `undefined` to keep it.
+ *
+ * A key (`sk-…`) refused with 401/403 gets `SESSION_LANE_HINT`, plus where a
+ * person does the same thing in the product when the command names one. A
+ * person's session refused with 403 is told the person lacks the permission —
+ * the service's generic FORBIDDEN hint says "use a different key", which is
+ * the wrong fix for someone who holds no key. A session refused with 401 keeps
+ * its own hint: it has expired, and re-signing in is the fix. No token at all
+ * means the failure came before a credential resolved, so it is about neither.
+ */
+export function sessionLaneHint(
+  meta: Pick<SessionLaneMeta, 'authLane' | 'sessionAlternative'>,
+  token: string,
+  code: string,
+): string | undefined {
+  if (meta.authLane !== 'session' || !token) return undefined
+  if (!token.startsWith('sk-')) return code === 'FORBIDDEN' ? PERSON_FORBIDDEN_HINT : undefined
+  if (code !== 'UNAUTHORIZED' && code !== 'FORBIDDEN') return undefined
+  return meta.sessionAlternative
+    ? `${SESSION_LANE_HINT}; or do it in ${meta.sessionAlternative}`
+    : SESSION_LANE_HINT
+}
+
+/**
+ * Refused before the request, or `null` to let it go.
+ *
+ * Any key on a session-lane command, whatever its scope: every such route
+ * refuses every key, so nothing is lost by not asking. It also covers a route
+ * that answers a key with an empty 200 instead of a refusal, which would read
+ * as "you can do nothing here" and exit 0. This trusts `authLane`, so a
+ * command is tagged `session` only when EVERY route it calls refuses every
+ * key — by mounting session-only auth, or by an authority check no key
+ * principal can pass (the governed Action invoke routes join organization
+ * and workspace membership). `action deploy` and `action prepare` reach
+ * routes a key legitimately uses, and are `api-key`. Then a person's session on a
+ * workspace-scoped command that named no workspace, which the service answers
+ * with a bare 400. A missing argument outranks the workspace, as it does for
+ * the organization-key refusal.
+ */
+export function sessionLaneRefusal(opts: {
+  meta: SessionLaneMeta
+  token: string
+  workspace: string | undefined
+  missingArg: boolean
+}): CliError | null {
+  const { meta, token, workspace, missingArg } = opts
+  if (meta.authLane !== 'session') return null
+  if (token.startsWith('sk-')) {
+    return new CliError(sessionLaneKeyMessage(meta), {
+      code: 'FORBIDDEN',
+      hint: sessionLaneHint(meta, token, 'FORBIDDEN')!,
+    })
+  }
+  if (missingArg || workspace || commandScope(meta) !== 'workspace') return null
+  return new UsageError(
+    `\`${commandLabel(meta)}\` acts inside a workspace, and this command names none`,
+    'session commands name their workspace — pass --workspace <id>',
+  )
+}
+
+/**
+ * The failure a session-lane command reports, rewritten, or `null` to report
+ * it as it is. The original error rides along as `cause`, with its details.
+ *
+ * A key gets the key message too, not only the hint: an API client's own
+ * message names a revoked key or a missing capability, which contradicts the
+ * hint on the line below it. `sessionLaneRefusal` refuses keys before any
+ * request, so this branch is a guard for a failure raised on some other path.
+ *
+ * A person refused with the service's generic FORBIDDEN keeps the service
+ * message and gets the person hint, because the generic hint says "use a
+ * different key". A `CliError` is left alone: the CLI worded it for this
+ * command already — `credentialFailure` names the capability when it knows it.
+ */
+export function sessionLaneFailure(
+  meta: SessionLaneMeta,
+  token: string,
+  err: unknown,
+): CliError | null {
+  const failure = toEnvelope(err)
+  const hint = sessionLaneHint(meta, token, failure.code)
+  if (!hint) return null
+  if (token.startsWith('sk-')) {
+    return new CliError(sessionLaneKeyMessage(meta), { code: failure.code, hint, cause: err })
+  }
+  if (err instanceof CliError) return null
+  return new CliError(failure.message, { code: failure.code, hint, cause: err })
+}

package/src/flag-help.ts

@@ -31,7 +31,7 @@ export const FLAG_HELP: Readonly<Record<string, string>> = {
   'dry-run': 'derive and print the write path without building anything',
   'plan-id': 'reuse this mutation plan id instead of minting one, so a retry names the same artifact',
   'binding-id': 'reuse this Binding id instead of minting one, so a retry names the same artifact',
-  reason: 'reason recorded on the deployment transition',
+  reason: 'reason recorded with the deployment transition, request or approval decision',
   'no-activate': 'review the write path but leave it switched off',
   role: 'organization role the capability is held by',
   add: 'comma-separated property API names to add to the current set',
@@ -87,7 +87,10 @@ export const FLAG_HELP: Readonly<Record<string, string>> = {
   input: "JSON object of the declared inputs — inline ('{\"key\": 1}') or @file.json",
   // The primary key alone. A subject-bound workflow takes exactly one, so the
   // flag spends no characters on the `{"pk": …}` the route models it as.
-  subject: 'primary key of the object a subject-bound workflow runs for',
+  subject: 'primary key of the object a subject-bound workflow or Action acts on',
+  // Action requests.
+  'subject-version': 'record version of --subject the request expects, so a stale read is refused',
+  'idempotency-key': 'reuse a key to retry a submit and get the same request back; generated if omitted',
   'no-promote': 'publish the version without moving the live pointer',
   'skip-build-check': 'deploy even when the build output is older than the source',
   'no-wait': 'return as soon as the run is queued instead of waiting for it to finish',
@@ -95,6 +98,9 @@ export const FLAG_HELP: Readonly<Record<string, string>> = {
   // between their working copy and what is deployed.
   dev: 'run the file served by an `automation dev` session instead of a deployed version',
   draft: 'act on your saved draft rather than a published version',
+  // Chat Apps
+  accent: 'presentation accent: blue, violet, green, amber, rose, teal or slate',
+  validate: 'report what blocks publishing, without publishing',
 
   // Agents
   name: 'display name; defaults to the slug',
@@ -150,6 +156,7 @@ export const FLAG_HELP: Readonly<Record<string, string>> = {
 
   // Knowledge
   description: 'one-line description stored on the resource',
+  'display-name': 'human-readable name shown beside the identifier',
   'top-k': 'how many chunks to return (default 10)',
   // A DISTANCE cutoff, not the similarity the output column shows — the query
   // keeps chunks whose cosine distance is below it, so a HIGHER value is more
@@ -161,6 +168,17 @@ export const FLAG_HELP: Readonly<Record<string, string>> = {
   strategy:
     'text extraction to use per file: auto (default), text, or ocr; ocr needs an OCR engine on the base',
 
+  // Media Sets
+  markings: 'comma-separated security markings added to each uploaded item, on top of the set default',
+  ocr: 'extract text with OCR instead of reading the text layer — for scans and images',
+  'skip-embed': 'cut passages but do not embed them; search needs embeddings',
+  watch: 'poll until nothing is pending (up to 10 minutes), then print the final state',
+  'skip-existing':
+    'upload only paths the set does not already hold, so a re-run after a partial failure adds no versions. '
+    + 'A path held by an item above your clearance is not seen, and is uploaded again',
+  'max-distance': 'maximum cosine distance a passage may have; higher is more permissive',
+  permissions: 'comma-separated: read, write, manage, read_sensitive (default read; read is always included)',
+
   // Auth and setup
   // "key", not "workspace key": `login` verifies an organization key too, and
   // naming only one kind here was the last place the CLI still implied that a
@@ -196,6 +214,7 @@ const PLACEHOLDER: Readonly<Record<string, string>> = {
   'expect-revision': 'hash',
   notes: 'text',
   description: 'text',
+  'display-name': 'text',
   strategy: 'auto|text|ocr',
   from: '-|path',
   'password-from': '-|path',
@@ -212,6 +231,9 @@ const PLACEHOLDER: Readonly<Record<string, string>> = {
   'new-capability': 'enabled|disabled',
   'top-k': 'n',
   threshold: '0-2',
+  markings: 'a,b',
+  'max-distance': '0-2',
+  permissions: 'read,write',
   template: 'non-negative|percentage|status-enum|code-length',
 }
 

package/src/forge/touches.ts

@@ -167,6 +167,8 @@ export const MCP_READ_TOOLS = new Set([
   // what the copilot's tool search ranks on, and changing it to suit this
   // regex would cost reach on the surface people actually use.
   'workflow_list', 'workflow_inspect', 'workflow_resources', 'workflow_runs',
+  // Shows the steps about to be built as placeholders; writes nothing.
+  'workflow_plan',
   // Runs one step of a draft and changes no part of the definition. Same
   // call as `test_agent` two lines up, and for the same reason: an authoring
   // loop tests a step repeatedly, and each one would jerk the pane.

package/src/harness.ts

@@ -59,9 +59,11 @@ and it cannot drift, because both are projected from the same table.
 Two fields decide whether a call can work at all:
 
 - \`authLane\` — \`api-key\` reaches the command with \`sk-ws-\`/\`sk-org-\` or a
-  session. \`session\` reaches it with a session token ONLY: a valid key answers
-  401 there, which looks exactly like an expired credential. Run
-  \`frontera login\` before those.
+  session. \`session\` acts as a person and needs a person's session, not an API
+  key: set \`FRONTERA_TOKEN\` to the session token and \`FRONTERA_API_URL\` (or
+  pass \`--api-url\`). The CLI refuses an \`sk-ws-\`/\`sk-org-\` key on those
+  before sending anything; \`frontera login\` stores keys only, so it cannot
+  supply the session.
 - \`available\` — \`false\` means the verb is named but unbuilt, and
   \`unavailableReason\` says why. Pick another route rather than retrying.
 

package/src/main.ts

@@ -3,11 +3,11 @@ import { parseArgs } from './args'
 import { resolveCredential } from './config'
 import { findProjectRoot } from './context'
 import { CliError, UsageError } from './errors'
-import { EXIT } from './exit'
+import { EXIT, sessionLaneFailure, sessionLaneRefusal } from './exit'
 import { resolveOrganization, setSelectedOrganization } from './organization'
 import { createOutput, type OutputMode } from './output'
 import { readProject } from './project'
-import { commandScope } from './scopes'
+import { commandScope, unaddressedWorkspaceRefusal } from './scopes'
 import {
   aliasesFor,
   describeCommand,
@@ -142,6 +142,8 @@ async function main(): Promise<number> {
 
   const mode: OutputMode = flags.json === true ? 'json' : 'human'
   const output = createOutput(mode, { quiet: flags.quiet === true })
+  // Read by the failure path: which credential was refused decides the hint.
+  let token = ''
 
   try {
     // Reserved commands fail BEFORE anything else — no credential is
@@ -208,6 +210,7 @@ async function main(): Promise<number> {
           },
           { cwd },
         )
+    token = credential.token
 
     const workspaceFlag = typeof flags.workspace === 'string' ? flags.workspace.trim() : undefined
     const orgFlag = typeof flags.org === 'string' ? flags.org.trim() : undefined
@@ -241,41 +244,21 @@ async function main(): Promise<number> {
       )
     }
 
-    /**
-     * 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
-      // 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-')
-    ) {
-      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',
-        },
-      )
+    // 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.
+    if (!command.meta.offline) {
+      const refusal = sessionLaneRefusal({
+        meta: command.meta,
+        token: credential.token,
+        workspace: workspaceFlag,
+        missingArg: missingArg !== undefined,
+      })
+        ?? (missingArg
+          ? null
+          : unaddressedWorkspaceRefusal({ meta: command.meta, token: credential.token, workspace: workspaceFlag }))
+      if (refusal) throw refusal
     }
 
     /**
@@ -319,7 +302,9 @@ async function main(): Promise<number> {
     output.render(result.data, () => result.text)
     return EXIT.OK
   } catch (err) {
-    return output.fail(err)
+    // A key on a session-lane command: one recovery for every such noun,
+    // rather than each API client rewording its own 401/403.
+    return output.fail(sessionLaneFailure(command.meta, token, err) ?? err)
   }
 }
 

package/src/scopes.ts

@@ -1,3 +1,5 @@
+import { CliError } from './errors'
+
 /**
  * Which grain each noun acts at — stated once.
  *
@@ -54,3 +56,44 @@ export function commandScope(meta: {
 export function orgScopedServiceNouns(): string[] {
   return [...ORG_SCOPED_NOUNS].filter((n) => n !== 'auth' && n !== 'kit').sort()
 }
+
+/**
+ * The refusal for an organization key that named no workspace on a
+ * workspace-scoped command, or `null` to let the request go.
+ *
+ * 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.
+ */
+export function unaddressedWorkspaceRefusal(opts: {
+  meta: { noun: string; verb: string; scope?: 'workspace' | 'organization' }
+  token: string
+  workspace: string | undefined
+}): CliError | null {
+  const { meta, token, workspace } = opts
+  if (workspace || commandScope(meta) !== 'workspace' || !token.startsWith('sk-org-')) return null
+  return new CliError(
+    `\`${commandLabel(meta)}\` 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',
+    },
+  )
+}
+
+/** `noun verb`, as a reader typed it. */
+export function commandLabel(meta: { noun: string; verb: string }): string {
+  return `${meta.noun}${meta.verb ? ` ${meta.verb}` : ''}`
+}

package/src/template.ts

@@ -247,9 +247,10 @@ createFronteraApp(<App />, { providers: [blueprintProvider] })
 import { useFronteraApp } from '@frontera-sdk/core/create-frontera-app'
 
 /**
- * The object type this page reads.
+ * The object type this page reads. Optional.
  *
- * \`frontera blueprint list\` shows what this workspace exposes; put an API name
+ * Left empty, the App builds, deploys and runs without Blueprint data and sends
+ * no queries. To read records, \`frontera blueprint list\` shows what this workspace exposes; put an API name
  * here — \`Shipment\`, \`LoanApplication\`, whatever the deployment models — and
  * \`frontera blueprint get <apiName>\` lists its properties.
  *
@@ -275,8 +276,9 @@ export default function App() {
 
       {OBJECT_TYPE === '' ? (
         <div className="rounded-lg border border-border bg-card p-6 text-sm text-muted-foreground">
-          Set <code className="font-mono text-foreground">OBJECT_TYPE</code> in{' '}
-          <code className="font-mono text-foreground">src/App.tsx</code> to read live data. Run{' '}
+          Your App is running. Blueprint data is optional: to read records, set{' '}
+          <code className="font-mono text-foreground">OBJECT_TYPE</code> in{' '}
+          <code className="font-mono text-foreground">src/App.tsx</code>. Run{' '}
           <code className="font-mono text-foreground">frontera blueprint list</code> to see what
           this workspace exposes.
         </div>

package/src/templates/next-app-files.ts

@@ -349,9 +349,9 @@ export function cn(...inputs: ClassValue[]) {
     emptyHint: 'Clear the search, or widen the filter.',
     errorTitle: 'Could not load records',
     retry: 'Try again',
-    unconfiguredTitle: 'Point this App at an object type',
+    unconfiguredTitle: 'Your App is running',
     unconfiguredBody:
-      'Run \`frontera blueprint list\` to see what this workspace exposes, then set STARTER_OBJECT_TYPE in src/lib/blueprint/starter.ts.',
+      'Blueprint data is optional. To list records here, run \`frontera blueprint list\` and set STARTER_OBJECT_TYPE in src/lib/blueprint/starter.ts — or replace this page with your own.',
     previous: 'Previous',
     next: 'Next',
     range: (from: number, to: number, total: number | null) =>
@@ -361,8 +361,10 @@ export function cn(...inputs: ClassValue[]) {
 `,
 
     'src/lib/blueprint/starter.ts': `/**
- * The object type the starter page reads.
+ * The object type the starter page reads. Optional.
  *
+ * Left empty, the App builds, deploys and runs without Blueprint data; the
+ * starter page shows a welcome panel and sends no queries. To list records,
  * \`frontera blueprint list\` shows what this workspace exposes; put an API name
  * here — \`Shipment\`, \`LoanApplication\`, whatever the deployment models — and
  * \`frontera blueprint get <apiName>\` lists its properties.
@@ -1004,7 +1006,9 @@ frontera app dev
 with real, short-lived Blueprint access. \`bun run dev\` alone starts Next
 without a session — useful for pure layout work, not for data.
 
-## Point it at your data
+## Point it at your data (optional)
+
+The App runs without Blueprint data. To have the starter page list records:
 
 \`\`\`bash
 frontera blueprint list