@frontera-sdk/cli 1.52.28 → 1.52.29

package/package.json

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

package/src/commands/local/data.ts

@@ -0,0 +1,60 @@
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { UsageError } from '../../errors'
+import { localProject } from '../../local/local-project'
+import { addMissingBackings, generateSyntheticData, loadScenario, SCENARIO_TEMPLATE } from '../../local/local-synthetic-data'
+import { flagBool, flagString, type Command } from '../types'
+
+/**
+ * `frontera local data --synthetic`: sample rows for every object type in the
+ * project's Blueprint, written under `datasets/`, so a Blueprint pulled from
+ * a workspace (which brings no records) can be explored and used by Agents.
+ * `local dev` loads them like any dataset file. No real record is copied.
+ */
+export const localData: Command = {
+  meta: {
+    noun: 'local',
+    verb: 'data',
+    args: [],
+    flags: { synthetic: 'boolean', rows: 'string', seed: 'string' },
+    summary: "Generate sample data for the project's Blueprint (datasets/*.csv), with consistent links",
+    examples: ['frontera local data --synthetic', 'frontera local data --synthetic --rows 500 --seed 42'],
+    offline: true,
+    internal: true,
+  },
+  async run(ctx) {
+    if (!flagBool(ctx, 'synthetic')) throw new UsageError('say what to make', 'run `frontera local data --synthetic`')
+    const rows = Number(flagString(ctx, 'rows') ?? 200)
+    const seed = Number(flagString(ctx, 'seed') ?? 7)
+    if (!Number.isInteger(rows) || rows < 1 || rows > 100_000) throw new UsageError('--rows takes a whole number from 1 to 100000', 'e.g. `frontera local data --synthetic --rows 500`')
+    if (!Number.isInteger(seed)) throw new UsageError('--seed takes a whole number', 'e.g. `frontera local data --synthetic --seed 42`')
+    const project = localProject(ctx.cwd)
+    if (!existsSync(join(project.root, 'blueprint', 'object-types'))) {
+      throw new UsageError('this project has no Blueprint object types', 'pull them with `frontera local sync pull --kinds blueprint`, or add blueprint/object-types/<Name>.yaml')
+    }
+    // A scenario file to edit, the first time, so a coding agent finds it.
+    const scenarioFile = join(project.root, 'data', 'generate.ts')
+    let wroteScenario = false
+    if (!existsSync(scenarioFile)) {
+      mkdirSync(join(project.root, 'data'), { recursive: true })
+      writeFileSync(scenarioFile, SCENARIO_TEMPLATE)
+      wroteScenario = true
+    }
+    const backed = addMissingBackings(project.root)
+    const scenario = await loadScenario(project.root, seed)
+    const made = generateSyntheticData(project.root, { rows, seed, scenario: scenario ?? undefined })
+    const total = made.reduce((n, m) => n + m.rows, 0)
+    return {
+      data: { datasets: made, backings: backed, scenario: 'data/generate.ts', wroteScenario, rows: total, seed },
+      text: [
+        `Wrote ${total} sample rows for ${made.length} object types (seed ${seed}):`,
+        ...made.map((m) => `  ${m.objectType.padEnd(24)} ${String(m.rows).padStart(6)}  ${m.csvPath}`),
+        ...(backed.length ? ['', `Gave ${backed.length} object type${backed.length === 1 ? '' : 's'} a dataset to read: ${backed.join(', ')}`] : []),
+        '',
+        wroteScenario ? 'Adjust them in data/generate.ts (rows per type, values per property).' : 'Adjusted by data/generate.ts.',
+        '`frontera local dev` loads them into the runtime.',
+      ].join('\n'),
+    }
+  },
+}

package/src/commands/local/dev.ts

@@ -3,7 +3,10 @@ import { existsSync, lstatSync, readFileSync, rmSync, watch, writeFileSync } fro
 import { join, sep } from 'node:path'
 
 import { CliError } from '../../errors'
-import { contentHash, loadHashes, saveHashes } from '../../local/local-applied'
+import { adaptationOf, contentHash, loadBuild, loadHashes, oneLine, pruneBuild, recordBuild, recordSettingsDifferences, saveHashes, type BuildEntry } from '../../local/local-applied'
+import { deployActions, ensureActionDraft, localActionCalls, prepareActions, retireActions, staleActions, unpublishedActions, type ActionBuild } from '../../local/local-actions'
+import { agentIdentity, syncAgentName } from '../../local/local-agent-name'
+import { classify, itemNeeds, type BuiltInKind } from '../../local/local-portability'
 import { localProfileName } from '../../local/local-control'
 import {
   allTargets,
@@ -17,11 +20,29 @@ import {
   type SyncProfiles,
   type SyncTarget,
 } from '../../local/local-dev-sync'
+import { applyBindings, applyKnowledge, applyPlugin, blueprintWithout, editableSets, localDirectory, promoteWorkflow, resolveBlueprint, resolveTarget, type ObjectBuild } from '../../local/local-dev-references'
+import { applyObjectSets, namesObjectSet, objectSetCalls } from '../../local/local-object-sets'
+import { applyTheme, themeCalls } from '../../local/local-themes'
+import { ensureMediaSets } from '../../local/local-media-sets'
+import { applyChatApp } from '../../local/local-chat-apps'
+import { applyLessons } from '../../local/local-lessons'
+import { applyStandIn, platformOnlyNames, readStandIn, standInNames } from '../../local/local-stand-ins'
+import { projectProvides } from '../../local/local-adapt'
 import { applyOperatingConfig } from '../../local/local-operating'
+import { mirrorOrgSettings, settingsCalls } from '../../local/local-org-settings'
+import { readSnapshot } from '../../local/local-sync-snapshot'
+import { functionSlugOf, mirrorFunctionState } from '../../local/local-function-state'
+import { functionSecretNames, missingSecretLines, readProjectDoc, readProjectText, workflowSecretNames } from '../../local/local-secrets'
+import { decideStepNotes, mirrorWorkflowState } from '../../local/local-workflow-state'
+import type { Directory } from '../../local/local-sync-refs'
 import { localProject, type LocalProject } from '../../local/local-project'
 import { isAlive, readState, recordApplied } from '../../local/local-state'
 import { applyErrorText } from '../../local/local-apply-error'
 import { flagBool, type Command, type CommandContext } from '../types'
+import { isSharedFunctionFile } from '../../local/local-function-shared'
+import { applyApp } from '../../local/local-apps'
+import { applyBrand, brandUpload } from '../../local/local-brand'
+import { applyLibrary } from '../../local/local-library'
 
 /**
  * `frontera local dev`: the inner loop. Applies the whole project to the
@@ -37,6 +58,15 @@ const DEBOUNCE_MS = 300
 interface RunResult {
   ok: boolean
   output: string
+  /** Not applied because it names these (`workflow/x`, `action/y`), which the runtime does not have yet. */
+  missing?: string[]
+  unnamedActions?: number
+  /** The Blueprint: how the runtime holds each object type and governed Action. */
+  blueprint?: { objects: Record<string, ObjectBuild>; actions: Record<string, ActionBuild>; objectSets?: string[] }
+  /** Saved object sets made again here under a new id: what names them is applied again. */
+  objectSetsAgain?: string[]
+  /** Governed Actions authored again under new ids: what names them is applied again. */
+  authoredAgain?: string[]
 }
 
 /** The commands running now, so stopping `local dev` stops them too. */
@@ -99,13 +129,82 @@ interface ApplyOptions {
 
 async function apply(project: LocalProject, target: SyncTarget, opts: ApplyOptions): Promise<RunResult> {
   const { profiles } = opts
+  const creds = readState(project)?.credentials
+  // Names in the file (`function/refund-eligibility`) become this runtime's ids in a resolved copy.
+  let directory: Promise<Directory> | null = null
+  const lookup = () => (directory ??= creds ? localDirectory(opts.serviceUrl, creds) : Promise.resolve({}))
+  const resolved = await resolveTarget(project, target, lookup, creds?.workspaceId, creds?.organizationId)
+  // The project's own file, before a resolved copy takes its place.
+  const original = target as Extract<SyncTarget, { file: string }>
+  if (!resolved.ok) return { ok: false, output: resolved.output, missing: resolved.missing, unnamedActions: resolved.unnamedActions }
+  let notes = resolved.output
+  const withNotes = (r: RunResult): RunResult => (notes ? { ...r, output: `${notes}\n${r.output}`.trim() } : r)
   if (target.kind === 'operating') {
     // Read fresh: the owner session is renewed on every runtime start.
-    const creds = readState(project)?.credentials
     if (!creds) return { ok: false, output: 'error [LOCAL_NOT_SEEDED]: the runtime is not seeded yet' }
-    return applyOperatingConfig({ serviceUrl: opts.serviceUrl, creds, slug: target.slug, file: join(project.root, target.file) })
+    return withNotes(await applyOperatingConfig({ serviceUrl: opts.serviceUrl, creds, slug: target.slug, file: join(project.root, target.file), document: resolved.doc }))
   }
-  let result = await runCli(project, commandFor(target, profiles), opts.auth)
+  if (target.kind === 'bindings') {
+    if (!creds) return { ok: false, output: 'error [LOCAL_NOT_SEEDED]: the runtime is not seeded yet' }
+    return applyBindings(project, target, opts.serviceUrl, creds)
+  }
+  if (target.kind === 'knowledge') return applyKnowledge(project, target, profiles, (args) => runCli(project, args, opts.auth), creds ? { serviceUrl: opts.serviceUrl, creds } : undefined)
+  if (target.kind === 'theme') {
+    if (!creds?.session) return { ok: false, output: 'error [LOCAL_NOT_SEEDED]: the runtime is not seeded yet' }
+    return applyTheme(project.root, target.name, themeCalls(opts.serviceUrl, creds))
+  }
+  if (target.kind === 'chat-app') {
+    if (!creds?.session) return { ok: false, output: 'error [LOCAL_NOT_SEEDED]: the runtime is not seeded yet' }
+    // The owner's session, as the platform's Chat App editor writes; the roster's Agents by this runtime's ids.
+    return applyChatApp(project.root, target.name, themeCalls(opts.serviceUrl, creds), lookup, projectProvides(project, creds.organizationId))
+  }
+  if (target.kind === 'app') {
+    if (!creds?.session) return { ok: false, output: 'error [LOCAL_NOT_SEEDED]: the runtime is not seeded yet' }
+    return applyApp(project.root, target.name, themeCalls(opts.serviceUrl, creds), projectProvides(project, creds.organizationId))
+  }
+  if (target.kind === 'brand') {
+    if (!creds?.session) return { ok: false, output: 'error [LOCAL_NOT_SEEDED]: the runtime is not seeded yet' }
+    // The owner's session, as an administrator sets the brand in Settings.
+    return applyBrand(project.root, creds.organizationId, themeCalls(opts.serviceUrl, creds), brandUpload(opts.serviceUrl, creds))
+  }
+  if (target.kind === 'library') {
+    if (!creds?.session) return { ok: false, output: 'error [LOCAL_NOT_SEEDED]: the runtime is not seeded yet' }
+    return applyLibrary(project.root, themeCalls(opts.serviceUrl, creds))
+  }
+  if (target.kind === 'lessons') {
+    if (!creds?.session) return { ok: false, output: 'error [LOCAL_NOT_SEEDED]: the runtime is not seeded yet' }
+    return applyLessons(project.root, target.slug, themeCalls(opts.serviceUrl, creds))
+  }
+  if (target.kind === 'plugin' && (target.file.endsWith('.stand-in.json') || target.file.endsWith('.platform.json'))) return applyStandIn(project, target.name, profiles.workspace, (args) => runCli(project, args, opts.auth))
+  if (target.kind === 'plugin') return applyPlugin(project, target, profiles, (args) => runCli(project, args, opts.auth), creds ? { serviceUrl: opts.serviceUrl, creds } : undefined)
+  if (resolved.file) target = { ...target, file: resolved.file } as SyncTarget
+  let command = commandFor(target, profiles)
+  // Where the applied Blueprint lives: the runtime's copy when it needed one.
+  let blueprintRoot = project.root
+  const blueprint = target.kind === 'blueprint' ? resolveBlueprint(project) : null
+  // Governed Actions are deployed on this runtime only (D3): calls to it, with the project's own keys.
+  const actionCalls = blueprint?.actions.length && creds && opts.publish ? localActionCalls(opts.serviceUrl, creds) : null
+  if (blueprint) {
+    // The Blueprint as this runtime can hold it; see `resolveBlueprint`.
+    if (blueprint.dir) {
+      command = [...command, '--dir', join(project.root, blueprint.dir)]
+      blueprintRoot = join(project.root, blueprint.dir, '..')
+    }
+    notes = [notes, ...blueprint.warnings].filter(Boolean).join('\n')
+    // A media-backed type over a set's catalog binds to an empty Media Set of that name, made first.
+    if (blueprint.mediaSets) {
+      if (!creds?.session) return { ok: false, output: 'error [LOCAL_NOT_SEEDED]: the runtime is not seeded yet' }
+      const why = await ensureMediaSets(blueprint.mediaSets, themeCalls(opts.serviceUrl, creds))
+      if (why) return { ok: false, output: `error [BLUEPRINT_MEDIA]: ${why}` }
+    }
+    if (actionCalls) {
+      // A draft on the first schema cannot hold Actions.
+      const draft = await ensureActionDraft(actionCalls)
+      if (!draft.ok) return { ok: false, output: `error [BLUEPRINT_ACTIONS]: ${draft.note}` }
+      if (draft.note) notes = [notes, `  warning: ${draft.note}`].filter(Boolean).join('\n')
+    }
+  }
+  let result = withNotes(await runCli(project, command, opts.auth))
   const fallback = fallbackFor(target, profiles, project.root)
   if (!result.ok && fallback?.when.test(result.output)) {
     // An empty fallback means there was nothing more to do.
@@ -116,14 +215,158 @@ async function apply(project: LocalProject, target: SyncTarget, opts: ApplyOptio
     }
   }
   if (!result.ok) return result
-  const objectTypes = target.kind === 'blueprint' ? blueprintObjectTypes(project.root) : []
+  if (target.kind === 'workflow' && creds) {
+    // Live in the workspace: live here too, with its triggers as they are there where that is safe.
+    const lines = [
+      ...(await mirrorWorkflowState(project, target.slug, original.file, opts.serviceUrl, creds)),
+      ...decideStepNotes(project, original.file, creds),
+      // The secrets its HTTP steps and webhook name: placeholders until set on this computer.
+      ...(await missingSecretLines(workflowSecretNames(readProjectDoc(project, original.file)), `workflow ${target.slug}`, opts.serviceUrl, creds)),
+    ]
+    if (lines.length) result = { ...result, output: `${result.output}\n${lines.join('\n')}`.trim() }
+  }
+  if (target.kind === 'function' && creds) {
+    // Switched off in the workspace: off here too; and the secrets it is granted, until set here.
+    const source = readProjectText(project, original.file)
+    const lines = [
+      ...(await mirrorFunctionState(project, target.key, opts.serviceUrl, creds)),
+      ...(await missingSecretLines(functionSecretNames(source), `Function ${functionSlugOf(target.key) ?? original.file}`, opts.serviceUrl, creds)),
+    ]
+    if (lines.length) result = { ...result, output: `${result.output}\n${lines.join('\n')}`.trim() }
+  }
+  if (target.kind === 'agent' && creds) {
+    // Agents stay drafts here, so the row keeps the name it was created with unless set from the file.
+    const named = await syncAgentName({ slug: target.slug, identity: agentIdentity(project.root, target.file), serviceUrl: opts.serviceUrl, creds })
+    if (named) result = { ...result, output: `${result.output}\n${named}`.trim() }
+  }
+  let authoredAgain: string[] = []
+  if (actionCalls && blueprint) {
+    const names = blueprint.actions.map((a) => a.apiName)
+    // A decision pins the Action's contract, its object type's fields included, and a first
+    // apply can leave the draft short of the files: apply once more before deciding.
+    if ((await unpublishedActions(actionCalls, names)).length) {
+      const again = await runCli(project, command, opts.auth)
+      if (!again.ok) return again
+    }
+    // What each Action may write (`backing.editable`): `blueprint apply` leaves backings to `bind`.
+    const appliedDir = blueprint.dir ? join(project.root, blueprint.dir) : join(project.root, 'blueprint')
+    const subjects = new Set(blueprint.actions.flatMap((a) => (a.fit.subject ? [a.fit.subject] : [])))
+    for (const [type, props] of editableSets(appliedDir, subjects)) {
+      const set = await runCli(project, ['blueprint', 'editable', type, '--set', props.join(','), '--profile', profiles.organization], opts.auth)
+      if (!set.ok && !/no change|already|unchanged/i.test(set.output)) notes = [notes, `  warning: ${type}'s editable fields (${props.join(', ')}) could not be declared: ${oneLine(applyErrorText(set.output))}`].filter(Boolean).join('\n')
+    }
+    // An Action whose contract moved after its decision here blocks the publish, and a decision
+    // cannot follow a new contract. On this runtime it is authored again under a new id: out of
+    // the draft (`--prune` over a copy without it), then back from the files.
+    const { stale, consumed } = await staleActions(actionCalls, names)
+    authoredAgain = stale.filter((n) => names.includes(n))
+    // A release may not drop a contract a live deployment runs: that deployment is retired first.
+    const live = await retireActions(actionCalls, [...new Set([...authoredAgain, ...consumed])])
+    if (live.size) return { ok: false, output: `error [BLUEPRINT_ACTIONS]: governed Action ${[...live].map(([name, why]) => `${name}: ${why}`).join('; ')}` }
+    // Retired here, so authored again: what names it is applied again too.
+    for (const name of consumed) if (!authoredAgain.includes(name)) authoredAgain.push(name)
+    if (stale.length) {
+      const dir = blueprint.dir ? join(project.root, blueprint.dir) : join(project.root, 'blueprint')
+      const without = await runCli(project, ['blueprint', 'apply', '--yes', '--prune', '--dir', blueprintWithout(project, dir, stale), '--profile', profiles.organization], opts.auth)
+      if (!without.ok) return without
+      const back = await runCli(project, command, opts.auth)
+      if (!back.ok) return back
+      notes = [notes, `  warning: governed Action ${stale.join(', ')} changed since it was deployed here, so it was authored again on this runtime`].filter(Boolean).join('\n')
+      result = withNotes(back)
+    }
+    // Publishing refuses an Action with no deployment decision: each gets "ships switched off" first.
+    const refused = await prepareActions(actionCalls, names, new Set(authoredAgain))
+    if (refused.size) return { ok: false, output: `error [BLUEPRINT_ACTIONS]: governed Action ${[...refused].map(([name, why]) => `${name}: ${why}`).join('; ')}` }
+  }
+  const objectTypes = target.kind === 'blueprint' ? blueprintObjectTypes(blueprintRoot) : []
   for (const step of followUpsFor(target, profiles, { publish: opts.publish, workspaceId: opts.workspaceId, objectTypes })) {
     const done = await runCli(project, step.args, opts.auth)
     if (!done.ok && !step.alreadyDone?.test(done.output)) return done
   }
+  if (blueprint) {
+    // After the publish: what writes only the Blueprint's records runs here; the rest stays switched off.
+    const actions: Record<string, ActionBuild> = actionCalls ? await deployActions(actionCalls, blueprint.actions) : {}
+    for (const [name, why] of Object.entries(blueprint.leftOffActions)) actions[name] = { status: 'left-off', reason: why }
+    for (const [name, a] of Object.entries(actions)) {
+      if (a.status === 'runs') result = { ...result, output: `${result.output}\n  governed Action ${name} runs on this runtime` }
+      else if (a.status !== 'left-off') result = { ...result, output: `${result.output}\n  warning: governed Action ${name} ${a.status === 'failed' ? 'didn’t deploy' : 'is switched off here'}: ${a.reason}` }
+    }
+    // Saved object sets, once the object types they read are published here.
+    let objectSets: string[] = []
+    let objectSetsAgain: string[] = []
+    if (creds && opts.publish) {
+      const leftOff = new Set(Object.entries(blueprint.objects).flatMap(([name, o]) => (o.status === 'left-off' ? [name] : [])))
+      const sets = await applyObjectSets(project.root, objectSetCalls(opts.serviceUrl, creds), leftOff)
+      if (sets.lines.length || sets.warnings.length) result = { ...result, output: [result.output, ...sets.lines, ...sets.warnings].join('\n').trim() }
+      objectSets = sets.warnings.map(adaptationOf)
+      objectSetsAgain = sets.recreated
+    }
+    result = {
+      ...result,
+      blueprint: { objects: blueprint.objects, actions, ...(objectSets.length ? { objectSets } : {}) },
+      ...(authoredAgain.length ? { authoredAgain } : {}),
+      ...(objectSetsAgain.length ? { objectSetsAgain } : {}),
+    }
+  }
   return result
 }
 
+/**
+ * What a target was applied with, in words: the warnings the apply printed
+ * (a Plugin it went without, a model swapped) and what it needs that the
+ * runtime gives it differently (no computer; a governed Action switched off
+ * here, as the last Blueprint build left it).
+ */
+function adaptationsFor(project: LocalProject, target: SyncTarget, output: string, organizationId: string): { adaptations: string[]; stubbed: boolean } {
+  const fromOutput = output.split('\n').filter((l) => /^\s*warning: /.test(l)).map(adaptationOf)
+  if (target.kind === 'blueprint' || target.kind === 'dataset') return { adaptations: [...new Set(fromOutput)], stubbed: false }
+  let files: Record<string, string> = {}
+  try {
+    if ('file' in target) files = { [target.file]: readFileSync(join(project.root, target.file), 'utf8') }
+  } catch {
+    // Read for its needs only; a file that vanished has none.
+  }
+  const deployed = loadBuild(project, organizationId).blueprint?.actions ?? {}
+  const actions = new Map(Object.entries(deployed).map(([name, a]) => [name, { runsLocally: a.status === 'runs', reason: a.reason, subject: null }] as const))
+  const kind = target.kind === 'operating' || target.kind === 'bindings' || target.kind === 'lessons' ? 'agent' : target.kind
+  // A built-in connection the project has a stand-in for is Stubbed: its tools answer "not connected".
+  // The Documentation plugin's stand-in serves the runtime's documentation, and the workspace's
+  // analytics stays on the platform: neither is Stubbed.
+  const standIns = standInNames(project.root)
+  const platformOnly = platformOnlyNames(project.root)
+  const titles = new Map([...standIns].map((n) => [n, readStandIn(project.root, n)?.connection ?? n] as const))
+  const builtIns = new Map<string, BuiltInKind>([
+    ...[...standIns].flatMap((n) => (readStandIn(project.root, n)?.serves === 'documentation' ? [[n, 'documentation'] as const] : [])),
+    ...[...platformOnly].map((n) => [n, 'analytics'] as const),
+  ])
+  const portability = classify(itemNeeds(kind, files, new Set([...standIns, ...platformOnly]), builtIns), { actions, titles })
+  const judged = portability.adaptations.map((a) => a.charAt(0).toUpperCase() + a.slice(1))
+  const stubbed = portability.class === 'stubbed' || (target.kind === 'plugin' && target.file.endsWith('.stand-in.json') && readStandIn(project.root, target.name)?.serves !== 'documentation')
+  return { adaptations: [...new Set([...judged, ...fromOutput])], stubbed }
+}
+
+/** The Blueprint's own adaptations, one line each: what is left off, and the Actions that do not run here. */
+function blueprintAdaptations(b: NonNullable<RunResult['blueprint']>): string[] {
+  const out: string[] = []
+  // "Receipt’s files stay on the platform…", "FieldJob location is left off…".
+  for (const [name, o] of Object.entries(b.objects)) for (const a of o.adaptations ?? []) out.push(a.startsWith('its ') ? `${name}’s ${a.slice('its '.length)}` : `${name} ${a}`)
+  for (const [name, a] of Object.entries(b.actions)) {
+    if (a.status === 'switched-off') out.push(`Governed Action ${name} is switched off here: ${a.reason}`)
+    if (a.status === 'failed') out.push(`Governed Action ${name} didn’t deploy: ${a.reason}`)
+    if (a.status === 'left-off') out.push(`Governed Action ${name} is left off: ${a.reason}`)
+  }
+  out.push(...(b.objectSets ?? []))
+  return out
+}
+
+/**
+ * The bindings an Agent could not get because the Function, workflow or
+ * object type (its Context and data) is not on the runtime yet.
+ */
+export function missingFromBindings(output: string): string[] {
+  return [...new Set([...output.matchAll(/^\s+((?:function|workflow|objectType)\/[A-Za-z0-9._-]+): (?:404|.*(?:not found|no live version|does not exist|not on the runtime yet))/gim)].map((m) => m[1]!))]
+}
+
 async function dev(ctx: CommandContext) {
   const project = localProject(ctx.cwd)
   const state = readState(project)
@@ -148,21 +391,74 @@ async function dev(ctx: CommandContext) {
 
   const organizationId = state.credentials!.organizationId
   const applied = flagBool(ctx, 'reapply') ? new Map<string, string | null>() : loadHashes(project, organizationId)
+
+  // The organization's settings as the last fetch read them: the timezone is taken, every
+  // other difference is said here and in the build summary.
+  // Read again when a fetch records new settings (`.frontera/sync/remote.json`), so the build summary follows the workspace.
+  let settingsSeen: string | null = null
+  const mirrorSettings = async () => {
+    const synced = readSnapshot(project.root)?.settings
+    if (!synced || !creds.session) return
+    const seen = JSON.stringify(synced)
+    if (seen === settingsSeen) return
+    settingsSeen = seen
+    const mirrored = await mirrorOrgSettings(synced, settingsCalls(serviceUrl, creds)).catch(() => null)
+    if (mirrored) {
+      for (const line of mirrored.lines) ctx.output.note(line)
+      for (const d of mirrored.differences) ctx.output.note(`  differs from the workspace: ${d}`)
+      recordSettingsDifferences(project, organizationId, mirrored.differences)
+    }
+  }
+  await mirrorSettings()
   let unchanged = 0
   const pending = new Map<string, SyncTarget>()
   // Files refused while something they depend on was missing; tried again after the next success.
   const failed = new Map<string, SyncTarget>()
+  // Workflows applied again for an Action authored again: their live version held the old id.
+  const promoteAfter = new Set<string>()
+  // Agents whose row name was checked against their file in this session.
+  const named = new Set<string>()
   let failures = 0
+  // Whether anything applied since the failed targets were last tried.
+  let progressed = false
   let busy = false
   let stopping = false
   let timer: ReturnType<typeof setTimeout> | null = null
 
+  /** What one apply came to, for the build record Forge and Studio read (design §9). */
+  const buildEntry = (target: SyncTarget, hash: string | null, result: RunResult): BuildEntry => {
+    const base = { what: describeTarget(target), hash, at: new Date().toISOString() }
+    if (result.ok) {
+      // A Blueprint with a media-backed type over an empty Media Set is Stubbed, as an item with a stand-in is.
+      const { adaptations, stubbed } = result.blueprint ? { adaptations: [...new Set([...blueprintAdaptations(result.blueprint)])], stubbed: Object.values(result.blueprint.objects).some((o) => o.status === 'stubbed') } : adaptationsFor(project, target, result.output, organizationId)
+      return {
+        ...base,
+        status: stubbed ? 'stubbed' : adaptations.length ? 'adapted' : 'built',
+        ...(adaptations.length ? { adaptations } : {}),
+        ...(result.blueprint ? { objects: result.blueprint.objects, actions: result.blueprint.actions } : {}),
+      }
+    }
+    const missing = result.missing?.length ? result.missing : target.kind === 'bindings' ? missingFromBindings(result.output) : []
+    if (missing.length || result.unnamedActions) return { ...base, status: 'blocked', needs: missing, ...(result.unnamedActions ? { unnamedActions: result.unnamedActions } : {}) }
+    return { ...base, status: 'failed', error: oneLine(applyErrorText(result.output)) }
+  }
+
   const runOne = async (target: SyncTarget) => {
     if (stopping) return
     if (target.kind !== 'blueprint' && !existsSync(join(project.root, target.file))) return
     const hash = contentHash(project, target)
     if (hash && applied.get(target.key) === hash) {
       unchanged += 1
+      // An Agent applied before names were set from its file still reads its slug: set it once.
+      if (target.kind === 'agent' && !named.has(target.slug)) {
+        named.add(target.slug)
+        const line = await syncAgentName({ slug: target.slug, identity: agentIdentity(project.root, target.file), serviceUrl, creds })
+        if (line) ctx.output.note(line)
+        // The runtime changed: say so as an apply does, so Studio's lists and the Agent's page refetch.
+        if (line && !/warning:/.test(line)) recordApplied(project, { at: new Date().toISOString(), what: describeTarget(target), ok: true })
+      }
+      // Applied before builds were recorded: it is built as it is.
+      if (!loadBuild(project, organizationId)[target.key]) recordBuild(project, organizationId, target.key, { what: describeTarget(target), status: 'built', hash, at: new Date().toISOString() })
       return
     }
     const started = Date.now()
@@ -170,6 +466,7 @@ async function dev(ctx: CommandContext) {
     if (stopping) return
     const ms = Date.now() - started
     recordApplied(project, { at: new Date().toISOString(), what: describeTarget(target), ok: result.ok })
+    recordBuild(project, organizationId, target.key, buildEntry(target, hash, result))
     if (result.ok) {
       // A draft-only Blueprint is not what a plain `local dev` would leave, so it is not recorded as applied.
       if (target.kind === 'blueprint' && !options.publish) applied.delete(target.key)
@@ -177,28 +474,68 @@ async function dev(ctx: CommandContext) {
       saveHashes(project, organizationId, applied)
       failed.delete(target.key)
       ctx.output.note(`  ✓ ${describeTarget(target)} applied (${ms} ms)`)
-      for (const [key, retry] of failed) if (!pending.has(key)) pending.set(key, retry)
-      failed.clear()
+      if (target.kind === 'workflow' && promoteAfter.delete(target.key)) {
+        const promoted = await promoteWorkflow(serviceUrl, creds, target.slug)
+        if (promoted) ctx.output.note(`  promoted workflow ${target.slug} v${promoted}: its live version ran the Action's old id`)
+      }
+      // What it was applied without, or with instead (a missing model), said once here.
+      for (const line of result.output.split('\n')) if (/^\s+warning: /.test(line)) ctx.output.note(`  ${line.trim()}`)
+      progressed = true
+      // Workflows and Agents hold the runtime's id of each Action they run: a new id means applying them again.
+      if (result.authoredAgain?.length || result.objectSetsAgain?.length) {
+        const names = result.authoredAgain ?? []
+        for (const t of allTargets(project.root)) {
+          if (t.kind !== 'workflow' && t.kind !== 'agent' && t.kind !== 'operating' && t.kind !== 'bindings') continue
+          let text = ''
+          try {
+            text = readFileSync(join(project.root, t.file), 'utf8')
+          } catch {
+            continue
+          }
+          if (names.some((n) => text.includes(`action/${n}`) || text.includes(`action:${n}`)) || namesObjectSet(text, result.objectSetsAgain ?? [])) {
+            applied.delete(t.key)
+            pending.set(t.key, t)
+            if (t.kind === 'workflow') promoteAfter.add(t.key)
+          }
+        }
+      }
     } else {
-      failures += 1
       failed.set(target.key, target)
-      ctx.output.note(`  ✕ ${describeTarget(target)}: ${applyErrorText(result.output)}`)
+      // A retry that fails the same way is not said (or counted) again in the same round of changes.
+      const text = applyErrorText(result.output)
+      if (said.get(target.key) !== text) {
+        failures += 1
+        said.set(target.key, text)
+        ctx.output.note(`  ✕ ${describeTarget(target)}: ${text}`)
+      }
     }
   }
 
+  /** What each failure last said in this drain, so a retry failing the same way is said once. */
+  const said = new Map<string, string>()
+
   /** Apply what is queued, dependencies first, one at a time. Never throws: a bad file must not end the loop. */
   const drain = async () => {
     if (busy) return
     busy = true
+    said.clear()
     try {
-      while (pending.size && !stopping) {
-        const next = [...pending.values()].sort(byApplyOrder)[0]!
-        pending.delete(next.key)
-        try {
-          await runOne(next)
-        } catch (err) {
-          ctx.output.note(`  ✕ ${describeTarget(next)}: ${(err as Error).message}`)
+      for (;;) {
+        while (pending.size && !stopping) {
+          const next = [...pending.values()].sort(byApplyOrder)[0]!
+          pending.delete(next.key)
+          try {
+            await runOne(next)
+          } catch (err) {
+            ctx.output.note(`  ✕ ${describeTarget(next)}: ${(err as Error).message}`)
+          }
         }
+        // What failed is tried again once the queue is empty, and only while a round applied
+        // something it may have been waiting for; otherwise it waits for its own file to change.
+        if (stopping || !progressed || !failed.size) break
+        progressed = false
+        for (const [key, retry] of failed) pending.set(key, retry)
+        failed.clear()
       }
     } finally {
       busy = false
@@ -212,6 +549,8 @@ async function dev(ctx: CommandContext) {
 
   /** What a changed path means: one file, every Function (a helper or the SDK changed), or a moved folder. */
   const queuePath = (rel: string) => {
+    // Forge's state and the runtime's resolved copies are written under `.frontera/`: never a reason to apply.
+    if (rel.split(sep).some((p) => p === '.frontera' || p === 'node_modules' || p === '.git')) return
     const absolute = join(project.root, rel)
     const direct = targetFor(project.root, absolute)
     if (direct) {
@@ -226,7 +565,8 @@ async function dev(ctx: CommandContext) {
         return false
       }
     })()
-    const helper = (top === 'functions' || top === 'vendor') && /\.ts$/.test(rel) && !rel.endsWith('.test.ts')
+    // A helper in functions/, the SDK, or a shared file a Function imports from outside functions/.
+    const helper = ((top === 'functions' || top === 'vendor') && /\.ts$/.test(rel) && !rel.endsWith('.test.ts')) || isSharedFunctionFile(rel.split(sep).join('/'))
     if (!isDir && !helper) return
     for (const target of allTargets(project.root)) {
       const path = target.kind === 'blueprint' ? 'blueprint' : target.file
@@ -252,11 +592,14 @@ async function dev(ctx: CommandContext) {
     ? null
     : watch(project.root, { recursive: true }, (_event, filename) => {
         if (!filename || stopping) return
+        if (filename.toString() === join('.frontera', 'sync', 'remote.json')) void mirrorSettings()
         queuePath(filename.toString())
         if (!busy) schedule()
       })
 
   const targets = allTargets(project.root)
+  // Outcomes of files that are gone are forgotten, so the home lists what the project holds.
+  pruneBuild(project, organizationId, new Set(targets.map((t) => t.key)))
   ctx.output.note(targets.length ? `Applying ${targets.length} item${targets.length === 1 ? '' : 's'} to the local runtime` : 'Nothing to apply yet')
   for (const target of targets) pending.set(target.key, target)
   await drain()
@@ -268,7 +611,7 @@ async function dev(ctx: CommandContext) {
     return { data: { applied: done, unchanged }, text: `Applied ${done}${unchanged ? `, ${unchanged} unchanged` : ''}` }
   }
 
-  ctx.output.note('Watching datasets/, blueprint/, functions/, workflows/ and agents/ (Ctrl+C to stop)')
+  ctx.output.note('Watching datasets/, blueprint/, knowledge/, skills/, mcp/, themes/, functions/, workflows/, agents/, chat-apps/, apps/, brand/ and library.json (Ctrl+C to stop)')
   if (pending.size) schedule()
 
   await new Promise<void>((resolve) => {

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

@@ -26,12 +26,14 @@ import { DEFAULT_REGISTRY, runSupervisor } from '../../local/local-supervisor'
 import { findCaseFiles, runCases } from '../../local/local-test-runner'
 import { flagBool, flagString, type Command, type CommandContext } from '../types'
 import { localCheck } from './check'
+import { localData } from './data'
 import { localDev } from './dev'
 import { localDocsMcp } from './docs-mcp'
 import { localInit } from './init'
 import { localKeyList, localKeyRemove, localKeySet } from './key'
 import { localModelAdd, localModelDefault, localModelRemove, localModelsAvailable, localProviderAdd, localProviderRemove, localProviders } from './providers'
 import { localSchema } from './schema'
+import { localSync } from './sync'
 
 /**
  * `frontera local …`: Frontera's runtimes on this machine, for internal FDEs.
@@ -388,8 +390,12 @@ async function test(ctx: CommandContext) {
   if (!state || state.phase !== 'ready' || !state.credentials?.session) {
     throw new CliError('the local runtime is not running', { code: 'LOCAL_NOT_RUNNING', hint: 'run `frontera local start` first' })
   }
-  const files = findCaseFiles(project.root, flagString(ctx, 'agent'))
+  // `--regression`: only the Agents' regression datasets, as the workspace chose them.
+  const files = findCaseFiles(project.root, flagString(ctx, 'agent')).filter((f) => !flagBool(ctx, 'regression') || f.regression)
   const total = files.reduce((n, f) => n + f.cases.length, 0)
+  if (total === 0 && flagBool(ctx, 'regression')) {
+    return { data: { passed: 0, failed: 0, results: [] }, text: 'No regression datasets. A pull marks the dataset each Agent is tested on before publishing in the workspace (`regression: true`).' }
+  }
   if (total === 0) {
     return {
       data: { passed: 0, failed: 0, results: [] },
@@ -419,9 +425,9 @@ export const localTest: Command = {
     noun: 'local',
     verb: 'test',
     args: [],
-    flags: { agent: 'string', live: 'boolean' },
+    flags: { agent: 'string', live: 'boolean', regression: 'boolean' },
     summary: 'Run the project\'s saved Agent test cases against the local runtime',
-    examples: ['frontera local test', 'frontera local test --agent claims-triage', 'frontera local test --live'],
+    examples: ['frontera local test', 'frontera local test --agent claims-triage', 'frontera local test --live', 'frontera local test --regression'],
     offline: true,
     internal: true,
   },
@@ -473,5 +479,7 @@ export const localCommands: readonly Command[] = [
   localModelDefault,
   localDocsMcp,
   localSchema,
+  localData,
+  localSync,
   localDaemon,
 ]