@frontera-sdk/cli 1.52.44 → 1.52.46

package/src/exit.ts

@@ -43,10 +43,14 @@ const USAGE_CODES = new Set([
   'VALIDATION_ERROR',
   'BAD_REQUEST',
   'NOT_FOUND',
+  // A Blueprint file that doesn't parse, named with its line and column: fixed in the file.
+  'BLUEPRINT_FILE_INVALID',
   // Profile selection. Every one of these is fixed by changing the command or
   // the directory binding — never by retrying, which is what separates them
   // from AUTH below: a wrong profile is a usage mistake, a revoked key is not.
   'PROFILE_NOT_FOUND',
+  // A change from a local project bound for another deployment, not said with --profile (X3).
+  'REMOTE_FROM_LOCAL_PROJECT',
   'PROFILE_NOT_SELECTED',
   'PROFILE_ORIGIN_MISMATCH',
   'PROFILE_INVALID',
@@ -314,6 +318,28 @@ export function withRefusedNames(message: string, details: unknown): string {
   return names.length ? `${message}: ${names.join(', ')}` : message
 }
 
+/**
+ * The blockers a refusal carries in its details (`RELEASE_BLOCKED`'s
+ * `blockers`: code, path, message), said under its message, at most five
+ * (Forge improvement plan N9). Before, `blueprint publish` and `local dev`
+ * printed "Blueprint validation is blocked." and nothing about why.
+ */
+export function withBlockers(message: string, details: unknown): string {
+  if (typeof details !== 'object' || details === null) return message
+  const body = details as { blockers?: unknown; details?: { blockers?: unknown } }
+  const list = Array.isArray(body.blockers) ? body.blockers : Array.isArray(body.details?.blockers) ? body.details.blockers : []
+  const lines = list.flatMap((b): string[] => {
+    if (typeof b !== 'object' || b === null) return []
+    const { code, path, message: why } = b as { code?: unknown; path?: unknown; message?: unknown }
+    const text = typeof why === 'string' ? why : typeof code === 'string' ? code : ''
+    if (!text) return []
+    return [`${typeof code === 'string' ? `[${code}] ` : ''}${typeof path === 'string' && path ? `${path}: ` : ''}${text}`]
+  })
+  if (!lines.length) return message
+  const shown = lines.slice(0, 5)
+  return [`${message.replace(/[.:]\s*$/, '')}:`, ...shown.map((l) => `  ✕ ${l}`), ...(lines.length > shown.length ? [`  … and ${lines.length - shown.length} more`] : [])].join('\n')
+}
+
 function isFronteraError(
   err: unknown,
 ): err is { code: string; message: string; details?: unknown } {
@@ -346,7 +372,7 @@ export function toEnvelope(err: unknown): ErrorEnvelope {
     }
     const hint = hintFor(err.code, err.details)
     const reason = reasonOf(err.details)
-    return { error: true, code: err.code, message: withRefusedNames(err.message, err.details), ...(hint ? { hint } : {}), ...(reason ? { details: { reason } } : {}) }
+    return { error: true, code: err.code, message: withBlockers(withRefusedNames(err.message, err.details), err.details), ...(hint ? { hint } : {}), ...(reason ? { details: { reason } } : {}) }
   }
 
   return {
@@ -359,15 +385,17 @@ export function toEnvelope(err: unknown): ErrorEnvelope {
 /**
  * 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.
+ * `frontera auth add` stores only `sk-ws-`/`sk-org-` keys; a person's session
+ * comes from `frontera auth login --browser`, approved in the browser (Forge
+ * improvement plan N5). Before, this told people to set FRONTERA_TOKEN to a
+ * session token, which they could only copy out of the browser's developer
+ * tools. 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'
+  'this command acts as a person and refuses API keys — sign in as yourself with '
+  + '`frontera auth login --browser` (approved in your browser, lasts 12 hours), then re-run'
 
 /** What a session-lane command needs to know about itself to word a refusal. */
 export interface SessionLaneMeta {

package/src/flag-help.ts

@@ -15,7 +15,16 @@
 export const FLAG_HELP: Readonly<Record<string, string>> = {
   // Agent↔automation bindings. `agent` is deliberately singular: a binding
   // names one agent, and there is no wildcard form.
+  envelope: 'JSON as one document on stdout whatever happens (implies --json): { ok, data, warnings }, or { ok: false, error, warnings } on a failure (FRONTERA_JSON_ENVELOPE=1 sets it for every command)',
+  model: 'a catalog model to run on instead of the Agents’ own (their drafts are put back after)',
+  baseline: 'a kept test run to compare with: last, last-own, last-<model>, or a run id',
+  'via-actions': 'submit each record as the governed Action its group names, as the local submitter persona',
+  'no-snapshot': 'don’t save the records first (by default a load saves them, and a refused record puts them back)',
+  batch: 'how many records are submitted at once (1 to 16, default 4)',
   agent: 'agent slug this binding is for — one agent, no wildcard',
+  app: 'a Custom App by its slug: the App may start the Function as the person using it',
+  apps: 'list the Custom Apps that may start it, instead of the agents',
+  off: 'keep the binding, switched off',
   approval: '"required" (default) asks a human before each call; "auto" does not',
   wait: 'seconds the agent waits for the run before it is told the run is still going (5–300)',
   // Declarative Blueprint authoring — the file tree, and what applying it may do.
@@ -31,6 +40,12 @@ 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',
+  attach: 'the media reference property an attachment Action fills with the file it is given',
+  like: 'start from another Agent’s files, by its slug',
+  customer: 'the Agent serves customers: write behavior settings (operating.json)',
+  'attach-item-id': 'the text property that keeps the attached file\'s Media Item id (a link key)',
+  'file-input': 'the Action input the file arrives in: a staged upload id (`frontera media stage`) or a run\'s file',
+  'media-set': 'the Media Set the attached file joins; defaults to the media reference property\'s own set',
   reason: 'reason recorded with the deployment transition, request or approval decision; the reason of a rejection in an approval chain is shown to whoever raised the request',
   stage: 'approval-chain step being decided: required for a request approved in steps, and refused if another step is waiting by then',
   'no-activate': 'review the write path but leave it switched off',
@@ -103,6 +118,9 @@ export const FLAG_HELP: Readonly<Record<string, string>> = {
   query: 'a query string to send with the delivery, such as source=portal&urgent=1',
   'fail-fast': 'stop the check at the first step that fails, instead of running and reporting every step',
   strict: 'fail on inherited failures too: items and files unchanged since the pull, which otherwise are listed and do not fail the check',
+  'org-profile': 'the organization profile organization-scoped commands use in this directory, beside a workspace profile on the same deployment',
+  repeat: 'run each Agent test case N times (1–10) and report its pass rate; a case that passes some runs and fails others is flaky',
+  'pass-rate': 'with --repeat, the share of runs a flaky case must pass to pass (default 0.8, or 80%); below it, it fails',
   concurrency: 'how many Agent test cases run at once (1–16, default 2); cases that change records for real still run one at a time. Lower it when the model provider refuses for requests in flight',
 
   // Apps
@@ -263,6 +281,18 @@ export const FLAG_HELP: Readonly<Record<string, string>> = {
   picks: 'a side per conflict, numbered as `diff` shows them: 1=workspace,2=mine; =both keeps mine then the workspace’s where `diff` says both can be kept',
   edited: 'take the files as you edited them; the workspace’s copies beside them go',
   title: 'the change request’s title; a push that opens a new one needs it',
+  why: 'a person-step: why it is needed now, in a sentence',
+  changes: 'a person-step: what it changes, in the workspace’s words',
+  credential: 'a person-step: who or what it needs (workspace-key, organization-key, steward, admin, second-person, person)',
+  delivery: 'a person-step: the delivery it belongs to; steps with the same one show as one card',
+  all: 'list the settled ones too',
+  browser: 'sign in by approving a code in the browser, as yourself',
+  'no-traces': 'leave out what each turn’s trace says',
+  tests: 'only what test runs started',
+  brief: 'the short form, without inputs and outputs',
+  conversation: 'only this conversation’s',
+  errors: 'only those with an error',
+  transcripts: 'include each case’s whole conversation, turn by turn',
   migration: 'for a Blueprint change that is not additive: what happens to existing records',
   documents: 'comma-separated knowledge bases whose documents a pull brings (a base pulled now brings its own anyway), or a push proposes (`*` for every one)',
   'no-documents': 'pull knowledge bases without their documents (by default a pulled base brings them)',
@@ -276,6 +306,7 @@ export const FLAG_HELP: Readonly<Record<string, string>> = {
   conflicts: 'the conflicts the picks were chosen against, as `diff --json` names them; refused if they moved',
   'from-workspace': 'start the project from a platform workspace instead of the examples',
   'no-sample-data': 'do not generate sample rows for the pulled Blueprint',
+  'no-kit': 'leave out the Frontera skills (the kit) that local init vendors into the project; for a machine that uses the installed plugin instead',
   'keep-sample-data': 'leave the sample datasets as they are; by default they are made again (same seed, rows and day) after a pull that brings Blueprint items, or when an older generator made them',
   'remake-sample-data': 'make the sample datasets again with the newest sample rules (same seed, rows and day), even the ones a pull wrote, which local dev otherwise keeps as pulled',
   synthetic: 'generate sample rows for the Blueprint: values fit each property, links stay consistent',

package/src/forge/claude-adapter.ts

@@ -6,6 +6,7 @@ import { ApprovalBroker, type ApprovalDecision, type Emit, type HostAdapter, typ
 import { ClaudeEventTranslator } from './claude-translator'
 import { forgeEnv, forgePath } from './env'
 import type { Logger } from './log'
+import { fronteraPermissionRules, runsPersonStep } from './permission-rules'
 
 /**
  * Claude Code as a Forge host, driven through `@anthropic-ai/claude-agent-sdk`.
@@ -48,6 +49,15 @@ export function autoAllows(mode: string, toolName: string): boolean {
   return false
 }
 
+/**
+ * A call the mode never answers on its own: a shell command that runs a
+ * person-step (`blueprint apply`, `app promote`, …). It always gets a card,
+ * even under Full access, where every other call is approved upstream.
+ */
+export function asksThePerson(toolName: string, input: Record<string, unknown>): boolean {
+  return toolName === 'Bash' && typeof input.command === 'string' && runsPersonStep(input.command)
+}
+
 /** The thread's effort, when the SDK would accept it. */
 export function claudeEffort(effort: string | null): Options['effort'] | undefined {
   if (!effort || !EFFORT_LEVELS.has(effort)) return undefined
@@ -95,7 +105,7 @@ export class ClaudeAdapter implements HostAdapter {
 
     const mode = ctx.thread.mode
     const canUseTool: CanUseTool = async (toolName, input, options) => {
-      if (autoAllows(mode, toolName)) return { behavior: 'allow', updatedInput: input }
+      if (autoAllows(mode, toolName) && !asksThePerson(toolName, input)) return { behavior: 'allow', updatedInput: input }
       const toolCallId = options.toolUseID ?? crypto.randomUUID()
       flush(translator.ensureToolCall(toolCallId, toolName, input))
       const decision = await this.approvals.request(ctx, emit, toolCallId, toolName, input)
@@ -117,10 +127,13 @@ export class ClaudeAdapter implements HostAdapter {
       ...(ctx.thread.hostSessionId ? { resume: ctx.thread.hostSessionId } : {}),
       includePartialMessages: true,
       settingSources: ['user', 'project', 'local'],
+      // The same rules as a terminal session: read-only `frontera` commands
+      // run without a card, delivery commands always raise one.
+      settings: { permissions: fronteraPermissionRules() },
       additionalDirectories: [ctx.project.root],
-      // Under bypassPermissions the SDK never consults the callback and warns
-      // loudly that it was given one.
-      ...(mode === 'bypassPermissions' ? {} : { canUseTool }),
+      // An ask rule reaches the callback in every mode, Full access included,
+      // so a delivery command is still a card there.
+      canUseTool,
       env: forgeEnv(ctx.project.profile ? { FRONTERA_PROFILE: ctx.project.profile } : {}),
       ...(await this.mcpServers(ctx)),
     }

package/src/forge/permission-rules.ts

@@ -0,0 +1,158 @@
+/**
+ * The Claude Code permission rules Forge gives every Claude Code session it
+ * starts, in its terminal (`--settings`) and in its in-app chat (the Agent
+ * SDK's `settings`).
+ *
+ * Without rules, every `frontera` command went to Claude Code's auto-mode
+ * classifier: it denied `blueprint apply` and `app promote` outright, and a
+ * classifier outage ended the turn even on `--help`. With them:
+ *
+ * - commands that only read are allowed, so they never wait on a classifier
+ *   or a prompt;
+ * - commands that make something live, or act with a person's authority,
+ *   always ask. An ask rule prompts in every mode, Auto and Full access
+ *   included, so no mode turns a delivery step into one the agent takes on
+ *   its own.
+ *
+ * The lists name exact command paths, never a wildcard across arguments: an
+ * allow rule `frontera * list` would also match a write whose last argument
+ * is "list". Claude Code checks each part of a compound command (`&&`, `|`,
+ * `;`) on its own, so `frontera status && <anything>` is not allowed by the
+ * first part.
+ */
+
+/** Commands that only read: help, status, lists, single items, diffs and previews. */
+export const FRONTERA_READ_ONLY_COMMANDS: readonly string[] = [
+  '--help',
+  '--version',
+  'help',
+  'auth list',
+  'auth current',
+  'kit status',
+  'kit doctor',
+  'workspace list',
+  'local status',
+  'local logs',
+  'local schema',
+  'local providers',
+  'local models-available',
+  'local key-list',
+  'local sync status',
+  'local sync diff',
+  'local sync push --preview',
+  'local sync pull --preview',
+  'local sync request show',
+  'app list',
+  'app versions',
+  'app checks',
+  'app deployments',
+  'agent list',
+  'agent get',
+  'agent diff',
+  'agent versions',
+  'skill list',
+  'skill get',
+  'plugin list',
+  'plugin get',
+  'plugin catalog',
+  'capability list',
+  'capability available',
+  'capability installs',
+  'dataset list',
+  'dataset get',
+  'dataset sources',
+  'source list',
+  'source get',
+  'knowledge list',
+  'knowledge get',
+  'knowledge sources',
+  'knowledge agents',
+  'media list',
+  'media status',
+  'pack list',
+  'pack get',
+  'secret list',
+  'chat-app list',
+  'chat-app get',
+  'function list',
+  'function versions',
+  'function runs',
+  'function bindings',
+  'workflow list',
+  'workflow get',
+  'workflow validate',
+  'workflow runs',
+  'workflow lineage',
+  'blueprint list',
+  'blueprint get',
+  'blueprint status',
+  'blueprint plan',
+  'blueprint object-sets',
+  'marking list',
+  'action list',
+  'action requests',
+  'action available',
+  'conversation get',
+  'conversation search',
+  'trace get',
+  'trace list',
+  'local steps check',
+]
+
+/**
+ * Commands that make something live, decide for the workspace or set a
+ * secret. They are the person's calls: the agent prepares them, the person
+ * says yes to each one.
+ */
+export const FRONTERA_PERSON_COMMANDS: readonly string[] = [
+  'blueprint apply',
+  'blueprint publish',
+  'blueprint rollback',
+  'blueprint grant',
+  'app promote',
+  'app rollback',
+  'agent publish',
+  'chat-app publish',
+  'function promote',
+  'workflow promote',
+  'local sync request apply',
+  'action deploy',
+  'action review',
+  'action retire',
+  'action grant',
+  'action approve',
+  'action reject',
+  'capability grant',
+  'media grant',
+  'marking grant',
+  'secret set',
+  // Stores a provider key from the shell (L9); not on the read-only list, whose rule would match it by prefix.
+  'local embeddings use',
+  'secret delete',
+]
+
+const rule = (path: string) => `Bash(frontera ${path}:*)`
+
+/** The `permissions` block for a Claude Code session Forge starts. */
+export function fronteraPermissionRules(): { allow: string[]; ask: string[] } {
+  return { allow: FRONTERA_READ_ONLY_COMMANDS.map(rule), ask: FRONTERA_PERSON_COMMANDS.map(rule) }
+}
+
+/** `FOO=1 frontera …`: assignments before the command name it doesn't. */
+const ASSIGNMENT = /^[A-Za-z_][A-Za-z0-9_]*=\S*$/
+
+/**
+ * Whether a shell command runs a person-step: any part of it, split the way
+ * Claude Code splits a compound command, that starts with `frontera` and one
+ * of the person-step paths. The in-app chat asks for these on a card in every
+ * mode, Full access included, as the ask rules do in the terminal.
+ */
+export function runsPersonStep(command: string): boolean {
+  return command.split(/&&|\|\||[;|&\n]/).some((part) => {
+    const words = part.trim().split(/\s+/).filter(Boolean)
+    while (words.length && ASSIGNMENT.test(words[0]!)) words.shift()
+    if (words[0] !== 'frontera' && !/\/frontera$/.test(words[0] ?? '')) return false
+    const rest = words.slice(1).join(' ')
+    return FRONTERA_PERSON_COMMANDS.some((path) => rest === path || rest.startsWith(`${path} `))
+  })
+}

package/src/forge/touches.ts

@@ -44,11 +44,12 @@ export const FORGE_ARTIFACT_KINDS = [
  * `search`, `runs`, `bindings` — is a read and is deliberately absent.
  */
 export const TOUCHING_VERBS: Record<ForgeArtifactKind, readonly string[]> = {
-  agent: ['apply', 'create', 'publish', 'revert', 'discard', 'skill-attach', 'skill-detach', 'archive', 'restore'],
+  // `behavior clear <agent>` stages the Agent's behavior settings away (X4); its Agent is the second positional.
+  agent: ['apply', 'create', 'publish', 'revert', 'discard', 'skill-attach', 'skill-detach', 'archive', 'restore', 'behavior'],
   automation: ['deploy', 'promote', 'enable', 'disable', 'init', 'bind', 'unbind', 'run'],
   app: ['deploy', 'promote', 'rollback', 'unpin', 'save', 'add'],
   blueprint: ['apply', 'publish', 'create', 'update', 'delete', 'rename', 'rollback', 'bind', 'grant', 'adopt', 'editable'],
-  action: ['prepare', 'deploy', 'grant', 'review'],
+  action: ['prepare', 'deploy', 'grant', 'review', 'retire'],
   skill: ['push', 'delete'],
   source: ['create', 'update', 'revise', 'disable'],
   // `revise` cuts the dataset's next revision from its CSV.
@@ -119,12 +120,12 @@ const BLUEPRINT_KINDED_VERBS = new Set(['update', 'delete', 'rename'])
  */
 export const BOOLEAN_FLAGS = new Set([
   // Global.
-  'json', 'quiet', 'yes', 'help', 'force',
+  'json', 'envelope', 'quiet', 'yes', 'help', 'force',
   // Every `'boolean'` FlagSpec a command declares (`grep "'boolean'" src/commands`).
   'accept-contract-change', 'accept-orphaned-knowledge', 'dry-run', 'end-user', 'no-activate',
   'no-components', 'no-git', 'no-input', 'no-install', 'no-open', 'no-promote', 'no-wait',
-  'remove-apps', 'token-stdin', 'prune', 'dev', 'revoke', 'draft', 'check',
-  'skip-build-check', 'prod', 'preview', 'undo', 'build',
+  'customer', 'remove-apps', 'token-stdin', 'prune', 'dev', 'revoke', 'draft', 'check',
+  'skip-build-check', 'prod', 'preview', 'undo', 'build', 'off',
 ])
 
 /**
@@ -398,7 +399,7 @@ export function parseFronteraCommands(line: string): ParsedFronteraCommand[] {
     if (!TOUCHING_VERBS[kind].includes(verb)) continue
     const ref = (FILE_POSITIONAL_VERBS[kind] ?? []).includes(verb)
       ? null
-      : kind === 'blueprint' && BLUEPRINT_KINDED_VERBS.has(verb)
+      : (kind === 'blueprint' && BLUEPRINT_KINDED_VERBS.has(verb)) || (kind === 'agent' && verb === 'behavior')
         ? (rest[1] ?? null)
         : (rest[0] ?? null)
     const live =

package/src/function-outside-imports.ts

@@ -53,10 +53,20 @@ const within = (root: string, path: string) => path === root || path.startsWith(
  * files it imports inside it too, as archive entries under `frontera-imports/`.
  */
 export function outsideImports(projectRoot: string, entry: string): SourceFile[] {
+  return importGraph(projectRoot, entry).outside
+}
+
+/**
+ * Every file `entry` reaches by relative import, followed file to file:
+ * `inside` the project folder (absolute paths, the entry included), and the
+ * ones `outside` it as archive entries under `frontera-imports/`.
+ */
+export function importGraph(projectRoot: string, entry: string): { inside: string[]; outside: SourceFile[] } {
   const root = resolve(projectRoot)
   const bound = resolve(solutionRoot(root))
   const seen = new Set<string>()
   const out: SourceFile[] = []
+  const inside: string[] = []
   const read = (path: string): string | null => {
     try {
       return existsSync(path) && lstatSync(path).isFile() ? readFileSync(path, 'utf8') : null
@@ -69,7 +79,8 @@ export function outsideImports(projectRoot: string, entry: string): SourceFile[]
     const text = read(file)
     if (text === null) return
     seen.add(file)
-    if (!within(root, file)) {
+    if (within(root, file)) inside.push(file)
+    else {
       const rel = relative(root, file).split(sep).join('/')
       if (CODE.test(file) && !isExcluded(rel.replace(/^(\.\.\/)+/, ''))) out.push({ rel: outsidePath(rel), bytes: new TextEncoder().encode(text) })
     }
@@ -85,5 +96,5 @@ export function outsideImports(projectRoot: string, entry: string): SourceFile[]
     }
   }
   visit(resolve(entry))
-  return out
+  return { inside, outside: out }
 }

package/src/function-source.ts

@@ -0,0 +1,90 @@
+import { existsSync, readFileSync, statSync } from 'node:fs'
+import { join, relative, resolve, sep } from 'node:path'
+
+import { importGraph } from './function-outside-imports'
+import { collectSourceFiles, formatBytes, gitignoreMatcher, isExcluded, type SourceFile } from './packaging'
+
+/**
+ * What a Function's source archive carries (Forge improvement plan L7; P4
+ * 2.9, P5 A14: a one-file Function in a project carried the whole project,
+ * 424 files and 8.3 MB, as its source).
+ *
+ * - A Function with a project of its own (`functions/<slug>/package.json`,
+ *   or a project `frontera function init` made) keeps that project's files.
+ * - A Function in a solution project's own package (`functions/<slug>.ts`,
+ *   whose nearest `package.json` is the project's, beside `frontera.yaml`)
+ *   keeps only what it reaches: its entry, every file the entry imports by
+ *   relative path, and the package files it builds with.
+ * - `.fronteraignore` at the packed folder's root, in `.gitignore` form,
+ *   leaves more out. The hard exclusions (`.env`, `node_modules`, build
+ *   output, `.frontera/`) always apply.
+ * - Past `SOURCE_WARN_BYTES` or `SOURCE_WARN_FILES`, the deploy warns and
+ *   names the largest files.
+ */
+
+export const SOURCE_WARN_BYTES = 2 * 1024 * 1024
+export const SOURCE_WARN_FILES = 150
+export const IGNORE_FILE = '.fronteraignore'
+
+/** The files a one-file Function builds with, beside what it imports. */
+const PACKAGE_FILES = ['package.json', 'tsconfig.json', 'bun.lock', 'bun.lockb', 'package-lock.json', 'bunfig.toml', IGNORE_FILE]
+
+const posixRel = (root: string, path: string) => relative(root, path).split(sep).join('/')
+
+/** `.fronteraignore`'s rules at `root`, in `.gitignore` form; nothing ignored without one. */
+function fronteraIgnore(root: string): (rel: string) => boolean {
+  const path = join(root, IGNORE_FILE)
+  if (!existsSync(path)) return () => false
+  // The `.gitignore` matcher, read from the other file.
+  const rules = readFileSync(path, 'utf8')
+    .split('\n')
+    .map((l) => l.trim())
+    .filter((l) => l && !l.startsWith('#') && !l.startsWith('!'))
+    .map((l) => l.replace(/\/$/, ''))
+  return (rel) => {
+    const segments = rel.split('/')
+    return rules.some((rule) => (rule.startsWith('*.') ? rel.endsWith(rule.slice(1)) : segments.includes(rule) || rel === rule || (rule.includes('/') && (rel === rule || rel.startsWith(`${rule}/`)))))
+  }
+}
+
+export interface FunctionSource {
+  files: SourceFile[]
+  /** True when only the files the entry reaches were kept (a one-file Function in a solution project). */
+  reachedOnly: boolean
+  /** How many files `.fronteraignore` left out. */
+  ignored: number
+}
+
+/** The source of the Function at `entry`, packed from `packageRoot` (its nearest package.json's folder). */
+export function functionSourceFiles(packageRoot: string, entry: string): FunctionSource {
+  const root = resolve(packageRoot)
+  const graph = importGraph(root, resolve(entry))
+  const reachedOnly = existsSync(join(root, 'frontera.yaml'))
+  let own: SourceFile[]
+  if (reachedOnly) {
+    const gitignored = gitignoreMatcher(root)
+    const paths = new Set([...graph.inside, ...PACKAGE_FILES.map((f) => join(root, f)).filter((p) => existsSync(p) && statSync(p).isFile())])
+    own = [...paths]
+      .map((p) => ({ path: p, rel: posixRel(root, p) }))
+      .filter(({ rel }) => !isExcluded(rel) && !gitignored(rel))
+      .sort((a, b) => a.rel.localeCompare(b.rel))
+      .map(({ path, rel }) => ({ rel, bytes: new Uint8Array(readFileSync(path)) }))
+  } else {
+    own = collectSourceFiles(root)
+  }
+  const ignore = fronteraIgnore(root)
+  const kept = own.filter((f) => !ignore(f.rel))
+  return { files: [...kept, ...graph.outside], reachedOnly, ignored: own.length - kept.length }
+}
+
+/** The warning for a source past the limits, naming its largest files; null under them. */
+export function sourceSizeWarning(name: string, files: SourceFile[]): string | null {
+  const bytes = files.reduce((n, f) => n + f.bytes.byteLength, 0)
+  if (bytes <= SOURCE_WARN_BYTES && files.length <= SOURCE_WARN_FILES) return null
+  const largest = [...files]
+    .sort((a, b) => b.bytes.byteLength - a.bytes.byteLength)
+    .slice(0, 3)
+    .map((f) => `${f.rel} (${formatBytes(f.bytes.byteLength)})`)
+    .join(', ')
+  return `the source of ${name} is ${files.length} files, ${formatBytes(bytes)} (largest: ${largest}). Every version keeps it, and a pull brings it back: leave out what the Function doesn't need with ${IGNORE_FILE} (.gitignore form) beside its package.json`
+}

package/src/harness.ts

@@ -70,10 +70,10 @@ 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\` 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. On a project's local runtime, never fetch a person's
+  key: the person signs in with \`frontera auth login --browser\` (approved in
+  their browser, 12 hours), and those commands use it. The CLI refuses an
+  \`sk-ws-\`/\`sk-org-\` key on those before sending anything. Never ask the
+  person for a session token: prepare the step for them instead. On a project's local runtime, never fetch a person's
   session: \`--as <persona>\` runs \`action available\`, \`submit\`,
   \`approve\` and \`reject\` as a local persona (\`--as submitter\`,
   \`--as <approver>\`; \`frontera local status\` lists them).

package/src/key-reach.ts

@@ -0,0 +1,64 @@
+import { BlueprintAuthoringApi } from './api/blueprint-authoring-api'
+import { PlatformApi } from './api/platform-api'
+
+/**
+ * What an organization key can reach (Forge improvement plan X3, T7; P2 F6,
+ * P5 A16): workspace-scoped commands run with the organization key were
+ * refused, and nothing said which workspaces the key may act in.
+ *
+ * An organization key carries a list of workspaces, and the service refuses
+ * an `x-workspace-id` that is not on it before anything else runs. So the
+ * key's own `whoami`, asked once per workspace, answers whether it may act
+ * there without the CLI reading the key's row or guessing.
+ */
+
+export interface ReachedWorkspace {
+  id: string
+  name: string
+  slug: string
+  /** The key may act in it (`--workspace <id>`). */
+  actsIn: boolean
+}
+
+/** At most this many workspaces are asked about; the rest are listed without the mark. */
+export const MAX_REACH_PROBES = 50
+
+/** Whether the key may act in the workspace: its `whoami` there answers with it. */
+export async function actsInWorkspace(apiUrl: string, token: string, workspaceId: string): Promise<boolean> {
+  try {
+    const me = await new PlatformApi(apiUrl, token, workspaceId).whoami()
+    return me.workspaceId === workspaceId
+  } catch {
+    return false
+  }
+}
+
+/**
+ * The organization's workspaces, each marked with whether this key may act
+ * in it. Null when the key can't list them (a workspace key, or one without
+ * `organization:update`).
+ */
+export async function keyReach(
+  apiUrl: string,
+  token: string,
+  deps: { list?: () => Promise<Array<{ id?: string; name?: string; slug?: string }>>; acts?: (workspaceId: string) => Promise<boolean> } = {},
+): Promise<ReachedWorkspace[] | null> {
+  const list = deps.list ?? (() => new BlueprintAuthoringApi(apiUrl, token).orgWorkspaces())
+  const acts = deps.acts ?? ((id: string) => actsInWorkspace(apiUrl, token, id))
+  let rows: Array<{ id?: string; name?: string; slug?: string }>
+  try {
+    rows = await list()
+  } catch {
+    return null
+  }
+  const named = rows.filter((w): w is { id: string; name?: string; slug?: string } => typeof w.id === 'string' && w.id !== '')
+  return Promise.all(named.map(async (w, i) => ({ id: w.id, name: w.name ?? '', slug: w.slug ?? '', actsIn: i < MAX_REACH_PROBES ? await acts(w.id) : false })))
+}
+
+/** The reach in one line: `may act in 2 of 5 workspaces: Ops, Claims`. */
+export function reachWords(reach: readonly ReachedWorkspace[]): string {
+  const acting = reach.filter((w) => w.actsIn)
+  if (!reach.length) return 'the organization has no workspaces it can list'
+  if (!acting.length) return `may act in none of the organization's ${reach.length} workspace${reach.length === 1 ? '' : 's'}: its workspace-scoped commands are refused`
+  return `may act in ${acting.length} of ${reach.length} workspace${reach.length === 1 ? '' : 's'}: ${acting.map((w) => w.name || w.slug || w.id).join(', ')} (\`--workspace <id>\`; \`frontera workspace list\` marks them)`
+}

package/src/local/local-actions.ts

@@ -251,7 +251,7 @@ interface DeployFailure {
 }
 
 /** The write path for one Action that writes the Blueprint's records: built, validated, reviewed, activated. */
-async function deployOne(call: Call, published: Deployable): Promise<string | DeployFailure | null> {
+async function deployOne(call: Call, published: Deployable, attachment?: LocalAction['attachment']): Promise<string | DeployFailure | null> {
   const { definition, contractDigest } = published
   const types = data<Array<{ id?: string; apiName?: string }>>(await call('org', 'GET', '/v1/blueprint/object-types')) ?? []
   const subject = (Array.isArray(types) ? types : []).find((t) => t.id === definition.subject.objectTypeId)?.apiName
@@ -260,9 +260,19 @@ async function deployOne(call: Call, published: Deployable): Promise<string | De
     await call('org', 'GET', `/v1/blueprint/object-types/${encodeURIComponent(subject)}`),
   )
   if (!shape?.objectType?.id) return `${subject} is not published here`
+  // A Media Set named in the file is found by its API name among this runtime's sets (the stand-ins included).
+  let mediaSetId: string | undefined
+  if (attachment?.mediaSet) {
+    const sets = data<Array<{ id?: string; apiName?: string }>>(await call('session', 'GET', '/v1/media/sets')) ?? []
+    mediaSetId = (Array.isArray(sets) ? sets : []).find((m) => m.apiName === attachment.mediaSet || m.id === attachment.mediaSet)?.id
+    if (!mediaSetId) return `its attachment names the Media Set ${attachment.mediaSet}, which this runtime has no set of`
+  }
+  const choice = attachment
+    ? { uploadInput: attachment.fileInput, ...(attachment.property ? { property: attachment.property } : {}), ...(attachment.itemIdProperty ? { itemIdProperty: attachment.itemIdProperty } : {}), ...(mediaSetId ? { mediaSetId } : {}) }
+    : undefined
   let plan
   try {
-    plan = deriveOntologyEditPlan(definition, { id: shape.objectType.id, apiName: shape.objectType.apiName ?? subject, primaryKeyPropertyId: shape.objectType.primaryKeyPropertyId ?? null, properties: shape.properties ?? [] })
+    plan = deriveOntologyEditPlan(definition, { id: shape.objectType.id, apiName: shape.objectType.apiName ?? subject, primaryKeyPropertyId: shape.objectType.primaryKeyPropertyId ?? null, properties: shape.properties ?? [] }, choice)
   } catch (err) {
     if (err instanceof PlanDerivationError) return err.message
     throw err
@@ -309,6 +319,8 @@ export interface LocalAction {
   fit: ActionFit
   /** The capability that lets a role invoke it (`governance.invokeCapability`). */
   invokeCapability?: string
+  /** How its deployment attaches the file it takes: its file's `attachment` (L6). */
+  attachment?: { fileInput: string; property?: string; itemIdProperty?: string; mediaSet?: string }
 }
 
 /**
@@ -338,7 +350,7 @@ export async function deployActions(call: Call, actions: LocalAction[]): Promise
     // Not active, or active on a write path whose validation no longer holds: built again.
     if (published.deploymentStatus !== 'active' || published.reason === 'ACTION_BINDING_VALIDATION_STALE') {
       try {
-        const why = await deployOne(call, published)
+        const why = await deployOne(call, published, action.attachment)
         failure = typeof why === 'string' ? { reason: why } : why
       } catch (err) {
         failure = { reason: (err as Error).message }