@frontera-sdk/cli 1.52.44 → 1.52.46

package/src/commands/kit/vendor.ts

@@ -44,55 +44,8 @@ export const kitVendor: Command = {
     requireCompatible()
 
     const root = kitRoot(ctx)
-    const rendered = renderKit()
-    const lock = readLock(root)
     const force = flagBool(ctx, 'force')
-
-    const report = writeGenerated(root, rendered.generated, lock, { force })
-
-    const edited: string[] = []
-    const repaired: string[] = []
-
-    if (rendered.agentsMd !== null) {
-      const path = join(root, 'AGENTS.md')
-      const existing = existsSync(path) ? readFileSync(path, 'utf8') : null
-      const next = applyManagedBlock(existing, rendered.agentsMd)
-      if (next !== existing) {
-        writeFileSync(path, next)
-        edited.push('AGENTS.md')
-      }
-    }
-
-    if (rendered.claudeMd !== null) {
-      const path = join(root, 'CLAUDE.md')
-      const existing = existsSync(path) ? readFileSync(path, 'utf8') : null
-      const result = applyClaudeImport(existing, rendered.claudeMd)
-      if (result.content !== existing) {
-        writeFileSync(path, result.content)
-        edited.push('CLAUDE.md')
-      }
-      if (result.repaired) repaired.push('CLAUDE.md')
-    }
-
-    // The lock records what WAS written. A conflicted file keeps whatever digest
-    // it had, so the next run still reports it rather than adopting the local
-    // edit as ours.
-    const locked = Object.fromEntries(
-      Object.entries(rendered.generated).filter(([rel]) => !report.conflicts.includes(rel)),
-    )
-    writeLock(root, locked, cliVersion())
-
-    const data = {
-      root,
-      kitVersion: KIT.kitVersion,
-      hosts: KIT.hosts,
-      written: report.written,
-      unchanged: report.unchanged,
-      conflicts: report.conflicts,
-      edited,
-      repaired,
-      lock: LOCK_FILE,
-    }
+    const { data, report, edited, repaired } = vendorKit(root, { force })
 
     const lines = [
       ...report.written.map((f) => `  + ${f}`),
@@ -117,4 +70,65 @@ export const kitVendor: Command = {
   },
 }
 
+/**
+ * Write the kit into `root`: the skills in both host directories, the managed
+ * AGENTS.md block, the CLAUDE.md import and the lock.
+ *
+ * Shared with `frontera local init`, so a project folder Forge opens carries the
+ * whole kit, the solution skills included, rather than only the CLI skill.
+ */
+export function vendorKit(root: string, opts: { force?: boolean } = {}) {
+  const rendered = renderKit()
+  const lock = readLock(root)
+  const force = opts.force === true
+
+  const report = writeGenerated(root, rendered.generated, lock, { force })
+
+  const edited: string[] = []
+  const repaired: string[] = []
+
+  if (rendered.agentsMd !== null) {
+    const path = join(root, 'AGENTS.md')
+    const existing = existsSync(path) ? readFileSync(path, 'utf8') : null
+    const next = applyManagedBlock(existing, rendered.agentsMd)
+    if (next !== existing) {
+      writeFileSync(path, next)
+      edited.push('AGENTS.md')
+    }
+  }
+
+  if (rendered.claudeMd !== null) {
+    const path = join(root, 'CLAUDE.md')
+    const existing = existsSync(path) ? readFileSync(path, 'utf8') : null
+    const result = applyClaudeImport(existing, rendered.claudeMd)
+    if (result.content !== existing) {
+      writeFileSync(path, result.content)
+      edited.push('CLAUDE.md')
+    }
+    if (result.repaired) repaired.push('CLAUDE.md')
+  }
+
+  // The lock records what WAS written. A conflicted file keeps whatever digest
+  // it had, so the next run still reports it rather than adopting the local
+  // edit as ours.
+  const locked = Object.fromEntries(
+    Object.entries(rendered.generated).filter(([rel]) => !report.conflicts.includes(rel)),
+  )
+  writeLock(root, locked, cliVersion())
+
+  const data = {
+    root,
+    kitVersion: KIT.kitVersion,
+    hosts: KIT.hosts,
+    written: report.written,
+    unchanged: report.unchanged,
+    conflicts: report.conflicts,
+    edited,
+    repaired,
+    lock: LOCK_FILE,
+  }
+
+  return { data, report, edited, repaired }
+}
+
 export { CliError }

package/src/commands/local/check.ts

@@ -22,7 +22,8 @@ import { isAlive, readState } from '../../local/local-state'
 import { recordRun } from '../../local/local-test-baseline'
 import { notRunGroups, notRunWords } from '../../local/local-case-not-run'
 import { evidenceLine, failingCaseEvidence, type CaseEvidence } from '../../local/local-case-evidence'
-import { agentFilesProblem, caseConcurrency, findCaseFiles, runCases, selectCaseFiles, waitedWords } from '../../local/local-test-runner'
+import { agentFilesProblem, caseConcurrency, caseRepeat, findCaseFiles, judgedWords, passRateThreshold, repeatWords, runCases, selectCaseFiles, waitedWords } from '../../local/local-test-runner'
+import { agentScope, customerFacingAgents, customerFacingWords, modelSubstitutions, skippedCases, skippedWords, type AgentScope, type SkippedCases } from '../../local/local-test-scope'
 import { findWorkflowTestFiles, recordWorkflowTestRun, runWorkflowTests, workflowFileState } from '../../local/local-workflow-tests'
 import { vendoredSdkLine, vendoredSdkState } from '../../local/local-vendored-sdk'
 import { withFix } from '../../local/fix-words'
@@ -145,6 +146,14 @@ export interface CheckStep {
    * step does not pass, but these are not failures of the Agent.
    */
   couldNotRun?: Array<{ what: string; fix: string; cases: string[]; notSent?: number }>
+  /** agents: each Agent with cases, and why it is in the check (X1). */
+  agents?: AgentScope[]
+  /** agents: the cases the check left out, by reason. */
+  skipped?: SkippedCases[]
+  /** agents: Agents that run on another model here than their files name. */
+  modelSubstitutions?: string[]
+  /** agents: with --repeat, the cases that passed some runs and failed others. */
+  flaky?: string[]
 }
 
 /** Run a command in the project, its output on stderr so stdout stays the check's own result. */
@@ -319,12 +328,23 @@ async function check(ctx: CommandContext) {
   const strict = flagBool(ctx, 'strict')
   // How many Agent cases run at once (`--concurrency`), checked before anything starts.
   let concurrency: number | undefined
+  let repeat: number | undefined
+  let passRate: number | undefined
   try {
     concurrency = caseConcurrency(flagString(ctx, 'concurrency'))
+    repeat = caseRepeat(flagString(ctx, 'repeat'))
+    passRate = passRateThreshold(flagString(ctx, 'pass-rate'))
   } catch (err) {
-    throw new UsageError((err as Error).message, 'frontera local check --concurrency 1')
+    throw new UsageError((err as Error).message, 'frontera local check --repeat 3')
+  }
+  if (passRate !== undefined && !repeat) throw new UsageError('--pass-rate is the share of a repeated case’s runs that must pass: give --repeat too', 'frontera local check --repeat 5 --pass-rate 0.8')
+  // `--agent a,b`: only those Agents' cases (X1); every Agent's otherwise.
+  const namedAgents = (flagString(ctx, 'agent') ?? '').split(',').map((a) => a.trim()).filter(Boolean)
+  for (const a of namedAgents) {
+    if (!findCaseFiles(root, a).length) throw new UsageError(`no test cases for Agent ${a} (agents/${a}/evals/*.yaml)`, 'name an Agent that has cases, e.g. `frontera local check --agent <slug>`')
   }
   const unchanged = unchangedSincePull(root)
+  const customerFacing = customerFacingAgents(root)
   // The tests' writes: a baseline after the apply, restored after the tests unless `--keep-state`.
   const keepState = flagBool(ctx, 'keep-state')
   let testData: CheckTestData | null = null
@@ -337,7 +357,7 @@ async function check(ctx: CommandContext) {
   }
   /** Whether the Agent or workflow tests will run anything, and so may write. */
   const testsWillRun = () =>
-    (!skip.has('agents') && !blockedBy('agents', failedSteps, failFast) && findCaseFiles(root).some((f) => f.cases.length > 0))
+    (!skip.has('agents') && !blockedBy('agents', failedSteps, failFast) && findCaseFiles(root).some((f) => f.cases.length > 0 && (!namedAgents.length || namedAgents.includes(f.agent))))
     || (!skip.has('workflows') && !blockedBy('workflows', failedSteps, failFast) && findWorkflowTestFiles(root).some((f) => f.cases.length > 0))
 
   const say = (step: CheckStepName, line: string) => ctx.output.note(`── ${step}: ${line}`)
@@ -387,6 +407,8 @@ async function check(ctx: CommandContext) {
     }
     if (step === 'apply') {
       say(step, 'frontera local dev --once')
+      // Which Agents serve customers: an operating.json leaves an Agent out of the built-in Chat (X4).
+      if (customerFacing.length) ctx.output.note(`   note: ${customerFacingWords(customerFacing)}`)
       const started = Date.now()
       const code = await runIn(root, self(['local', 'dev', '--once']))
       // Which items did not apply, and whether each is still as the pull wrote it. `local dev --once` makes the
@@ -545,12 +567,20 @@ async function check(ctx: CommandContext) {
     }
     const serviceUrl = `http://127.0.0.1:${state.ports.service}`
     if (step === 'agents') {
-      const files = selectCaseFiles(root)
+      const files = selectCaseFiles(root).filter((f) => !namedAgents.length || namedAgents.includes(f.agent))
       if (!files.some((f) => f.cases.length || f.problem)) {
         record({ step, status: 'skipped', note: 'no Agent test cases (agents/<slug>/evals/*.yaml)', ms: 0 })
         continue
       }
-      say(step, 'frontera local test (Agents)')
+      say(step, `frontera local test (${namedAgents.length ? `Agent${namedAgents.length === 1 ? '' : 's'} ${namedAgents.join(', ')}` : 'Agents'})${repeat && repeat > 1 ? `, each case ${repeat} times` : ''}`)
+      // Why each Agent is in the check; one unchanged since the pull, or only renamed, has its failures inherited (X1).
+      const scope = agentScope(root, files, unchanged, namedAgents)
+      for (const a of scope) ctx.output.note(`   ${a.agent} (${a.cases} case${a.cases === 1 ? '' : 's'}): ${a.why}`)
+      const inheritedAgents = new Set(scope.filter((a) => a.inherited).map((a) => a.agent))
+      const skippedHere = skippedCases(root, namedAgents.length ? { agents: namedAgents } : {})
+      if (skippedHere.length) ctx.output.note(`   ${skippedWords(skippedHere)}`)
+      const models = modelSubstitutions(project, state.credentials.organizationId, files.map((f) => f.agent))
+      for (const line of models) ctx.output.note(`   note: ${line}`)
       const started = Date.now()
       const orgId = state.credentials.organizationId
       const results = await runCases({
@@ -559,15 +589,21 @@ async function check(ctx: CommandContext) {
         files,
         live: false,
         concurrency,
+        ...(repeat ? { repeat } : {}),
+        ...(passRate ? { passRate } : {}),
         staleDraft: (slug) => agentFilesProblem(project, orgId, slug),
         onResult: (r) => {
           // The cases not sent after the provider refused every one are said once, below.
           if (r.notRun?.skipped) return
-          ctx.output.note(`   ${r.passed ? '✓' : r.notRun ? '–' : '✕'} ${r.agent} · ${r.name}${r.passed ? '' : r.notRun ? ` — couldn’t run: ${r.notRun.what}` : ` — ${r.reason}`}${r.passed && r.retried ? ' (run twice: the provider refused the first try for its limits)' : ''}${r.waited?.length ? ` (${waitedWords(r.waited)})` : ''}`)
+          ctx.output.note(`   ${r.passed ? (r.repeat?.flaky ? '~' : '✓') : r.notRun ? '–' : '✕'} ${r.agent} · ${r.name}${r.passed ? '' : r.notRun ? ` — couldn’t run: ${r.notRun.what}` : ` — ${r.reason}`}${repeatWords(r)}${judgedWords(r)}${r.passed && r.retried ? ' (run twice: the provider refused the first try for its limits)' : ''}${r.waited?.length ? ` (${waitedWords(r.waited)})` : ''}`)
         },
       })
       recordRun(project, results)
-      const bad = results.filter((r) => !r.passed && !r.notRun)
+      const failing = results.filter((r) => !r.passed && !r.notRun)
+      // An inherited Agent's failures are listed and pass unless --strict, as every other step's are.
+      const inheritedFails = strict ? [] : failing.filter((r) => inheritedAgents.has(r.agent))
+      const bad = failing.filter((r) => !inheritedFails.includes(r))
+      const agentData = { agents: scope, ...(skippedHere.length ? { skipped: skippedHere } : {}), ...(models.length ? { modelSubstitutions: models } : {}), ...(results.some((r) => r.repeat?.flaky) ? { flaky: results.filter((r) => r.repeat?.flaky).map((r) => `${r.agent} · ${r.name}`) } : {}) }
       // Each failing case's conversation, last turn's trace and reply, read before the rollback (which keeps the conversation).
       const evidence = await failingCaseEvidence(project, results)
       for (const [i, e] of evidence) ctx.output.note(`     ${results[i]!.agent} · ${results[i]!.name}: ${evidenceLine(e)}`)
@@ -581,8 +617,10 @@ async function check(ctx: CommandContext) {
       record({
         step,
         status: bad.length || notRun.length ? 'failed' : 'passed',
-        command: 'frontera local test',
+        command: `frontera local test${namedAgents.length === 1 ? ` --agent ${namedAgents[0]}` : ''}${repeat && repeat > 1 ? ` --repeat ${repeat}` : ''}`,
         ms: Date.now() - started,
+        ...agentData,
+        ...(inheritedFails.length ? { inherited: inheritedFails.map((r) => `${r.agent} · ${r.name}: ${r.reason ?? 'failed'}`) } : {}),
         ...(note ? { note } : {}),
         ...(bad.length ? { failures: bad.map((r) => ({ name: `${r.agent} · ${r.name}`, reason: r.reason, ...(evidence.get(results.indexOf(r)) ?? {}) })) } : {}),
         ...(notRun.length ? { couldNotRun: notRun.map((g) => ({ what: `couldn’t run: ${g.what}`, fix: g.fix, cases: g.cases, ...(g.skipped ? { notSent: g.skipped } : {}) })) } : {}),
@@ -629,7 +667,7 @@ async function check(ctx: CommandContext) {
       }
     }
   } else if (testData?.kept && testsRan) ctx.output.note('── test data: the tests’ writes were kept (--keep-state); the next `frontera local check` rolls them back')
-  const testDataField = testData && testsRan ? { testData } : {}
+  const testDataField = { ...(testData && testsRan ? { testData } : {}), ...(customerFacing.length ? { customerFacing } : {}) }
 
   if (flagBool(ctx, 'stop')) {
     ctx.output.note('── frontera local stop')
@@ -676,9 +714,17 @@ export const localCheck: Command = {
     noun: 'local',
     verb: 'check',
     args: [],
-    flags: { stop: 'boolean', skip: 'string', 'fail-fast': 'boolean', strict: 'boolean', 'keep-state': 'boolean', concurrency: 'string' },
+    flags: { stop: 'boolean', skip: 'string', 'fail-fast': 'boolean', strict: 'boolean', 'keep-state': 'boolean', concurrency: 'string', agent: 'string', repeat: 'string', 'pass-rate': 'string' },
+    flagHelp: {
+      agent: 'check only these Agents’ test cases (a slug, or slugs separated by commas); the other steps run as always',
+      repeat: 'run each Agent case N times (1 to 10); a case that passes some runs is flaky, and passes at --pass-rate',
+      'pass-rate': 'with --repeat, the share of runs a flaky case must pass (default 0.8, or 80%)',
+    },
+    details: [
+      'The agents step says why each Agent is in it: named with `--agent`, every Agent with cases, or, in a pulled project, whether it changed since the pull. An Agent unchanged since the pull, or changed only in its name, has its failures listed as inherited: they pass unless `--strict`, as every other step\'s inherited failures do.',
+    ],
     summary: 'The whole gate with one exit code (start, apply, typecheck, unit tests, App checks, Agent and workflow tests): anything changed or added fails it, and failures only in items unchanged since the pull are listed as inherited and pass unless --strict',
-    examples: ['frontera local check', 'frontera local check --json', 'frontera local check --strict', 'frontera local check --skip typecheck,apps', 'frontera local check --fail-fast', 'frontera local check --keep-state', 'frontera local check --concurrency 1', 'frontera local check --stop'],
+    examples: ['frontera local check', 'frontera local check --json', 'frontera local check --agent claims-triage --repeat 3', 'frontera local check --strict', 'frontera local check --skip typecheck,apps', 'frontera local check --fail-fast', 'frontera local check --keep-state', 'frontera local check --concurrency 1', 'frontera local check --stop'],
     offline: true,
   },
   run: check,

package/src/commands/local/data.ts

@@ -1,8 +1,14 @@
 import { existsSync, mkdirSync, writeFileSync } from 'node:fs'
-import { join } from 'node:path'
+import { join, resolve } from 'node:path'
 
-import { UsageError } from '../../errors'
+import { GovernedActionApi } from '../../api/governed-action-api'
+import { CliError, UsageError } from '../../errors'
+import { loadViaActions, loadWords, readLoadFile } from '../../local/local-data-load'
+import { restoreBaseline, saveBaseline } from '../../local/local-db-snapshot'
+import { actAsLocalPersona, redact } from '../../local/local-personas'
 import { localProject } from '../../local/local-project'
+import { waitForDatabaseReady } from '../../local/local-runtime-health'
+import { readState } from '../../local/local-state'
 import { isoDay, SAMPLE_OPTIONS_FILE, writeSampleOptions } from '../../local/local-sample-remake'
 import { addMissingBackings, generateSyntheticData, loadScenario, parseRegion, projectRegion, REGION_CODES, SCENARIO_CONTRACT, SCENARIO_TEMPLATE } from '../../local/local-synthetic-data'
 import { flagBool, flagString, type Command } from '../types'
@@ -17,14 +23,27 @@ export const localData: Command = {
   meta: {
     noun: 'local',
     verb: 'data',
-    args: [],
-    flags: { synthetic: 'boolean', rows: 'string', seed: 'string', region: 'string', today: 'string' },
-    summary: "Generate sample data for the project's Blueprint (datasets/*.csv; media-backed types get none), with consistent links",
-    details: SCENARIO_CONTRACT,
-    examples: ['frontera local data --synthetic', 'frontera local data --synthetic --rows 500 --seed 42', 'frontera local data --synthetic --region ID', 'frontera local data --synthetic --region 1.29,103.85,20', 'frontera local data --synthetic --today 2026-10-18'],
+    args: [
+      { name: 'action', required: false, description: 'load, to load records through governed Actions' },
+      { name: 'file', required: false, description: 'with load: the JSON or YAML file of { action, records } groups' },
+    ],
+    flags: { synthetic: 'boolean', rows: 'string', seed: 'string', region: 'string', today: 'string', 'via-actions': 'boolean', 'no-snapshot': 'boolean', batch: 'string' },
+    flagHelp: {
+      'via-actions': 'with load: submit each record as the governed Action its group names, as the local submitter persona',
+      'no-snapshot': 'with load: don’t save the records first (by default a load saves them, and a failed load puts them back)',
+      batch: 'with load: how many records are submitted at once (1 to 16, default 4)',
+    },
+    summary: "Generate sample data for the project's Blueprint (datasets/*.csv; media-backed types get none), with consistent links, or load records through governed Actions",
+    details: [
+      ...SCENARIO_CONTRACT,
+      '`load <file> --via-actions` loads records through the project\'s governed Actions on the local runtime: the file is a list of groups, each `{ action: <apiName>, records: [...] }`, run in its order (put a group whose records name another\'s after it). A record is the Action\'s input, or `{ input, subject }` for an Action on an existing record. Each is submitted as the local `submitter` persona, in batches, with a key from the file and the record, so loading the same file again submits nothing twice. The records are saved first; when a record is refused, the load stops after its group and puts them back (`--no-snapshot` skips both). A record that waits on an approval step is said.',
+    ],
+    examples: ['frontera local data load data/customers.yaml --via-actions', 'frontera local data --synthetic', 'frontera local data --synthetic --rows 500 --seed 42', 'frontera local data --synthetic --region ID', 'frontera local data --synthetic --region 1.29,103.85,20', 'frontera local data --synthetic --today 2026-10-18'],
     offline: true,
   },
   async run(ctx) {
+    if (ctx.positional[0] === 'load') return loadCommand(ctx)
+    if (ctx.positional.length) throw new UsageError(`unknown data action \`${ctx.positional[0]}\``, '`frontera local data --synthetic`, or `frontera local data load <file> --via-actions`')
     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)
@@ -79,3 +98,52 @@ export const localData: Command = {
     }
   },
 }
+
+/** `local data load <file> --via-actions` (Forge improvement plan L2). */
+async function loadCommand(ctx: Parameters<Command['run']>[0]) {
+  const file = ctx.positional[1]
+  if (!file) throw new UsageError('name the file to load', 'frontera local data load data/customers.yaml --via-actions')
+  if (!flagBool(ctx, 'via-actions')) throw new UsageError('a load goes through governed Actions: say so with --via-actions', '`frontera local data load <file> --via-actions`; sample rows for datasets come from `frontera local data --synthetic`')
+  const batch = flagString(ctx, 'batch') === undefined ? 4 : Number(flagString(ctx, 'batch'))
+  if (!Number.isInteger(batch) || batch < 1 || batch > 16) throw new UsageError('--batch takes a whole number from 1 to 16', 'e.g. `--batch 4`')
+  const project = localProject(ctx.cwd)
+  const state = readState(project)
+  if (!state || state.phase !== 'ready' || !state.credentials) throw new CliError('the local runtime is not running', { code: 'LOCAL_NOT_RUNNING', hint: 'run `frontera local start` first' })
+  const serviceUrl = `http://127.0.0.1:${state.ports.service}`
+  const groups = readLoadFile(resolve(ctx.cwd, file))
+  const organizationId = state.credentials.organizationId
+  const snapshot = !flagBool(ctx, 'no-snapshot')
+  if (snapshot) {
+    const saved = await ctx.output.task('Saving the records first', () => saveBaseline(project, organizationId, { serviceAnswers: () => waitForDatabaseReady(serviceUrl) }, true))
+    if (!saved.ok) throw new CliError(`the records could not be saved first, so nothing was loaded: ${saved.note}`, { code: 'LOCAL_SNAPSHOT_FAILED', hint: '`--no-snapshot` loads without saving them' })
+  }
+  const persona = await actAsLocalPersona({ meta: { noun: 'action', verb: 'submit' }, cwd: ctx.cwd, apiUrl: serviceUrl, wanted: 'submitter' })
+  const client = new GovernedActionApi(serviceUrl, persona.token, persona.workspaceId)
+  const outcomes = []
+  try {
+    for (const group of groups) {
+      const [o] = await loadViaActions(file, [group], (action, invocation, key) => client.submit(action, invocation, key) as never, {
+        batch,
+        subjectType: async (action) => ((await client.publishedAction(action).catch(() => null))?.definition as { subject?: { objectTypeId?: string } } | undefined)?.subject?.objectTypeId ?? null,
+      })
+      outcomes.push(o!)
+      ctx.output.note(`  ${o!.refused.length ? '✕' : '✓'} ${loadWords(o!)}`)
+      for (const r of o!.refused.slice(0, 3)) ctx.output.note(`      record ${r.index + 1}: ${redact(r.reason, persona.token)}`)
+      if (o!.refused.length) break
+    }
+  } catch (err) {
+    throw redact(err, persona.token)
+  }
+  const stopped = outcomes.some((o) => o.refused.length)
+  let putBack: string | null = null
+  if (stopped && snapshot) {
+    const restored = await ctx.output.task('Putting the records back', () => restoreBaseline(project, organizationId, { serviceAnswers: () => waitForDatabaseReady(serviceUrl) }, { secrets: 'keep', history: 'keep' }))
+    putBack = restored.ok ? 'the records are as they were before the load' : `the records could not be put back: ${restored.note}`
+  }
+  const data = { file, groups: outcomes, ...(stopped ? { stopped: true, putBack } : {}) }
+  if (stopped) {
+    const at = outcomes[outcomes.length - 1]!
+    throw new CliError(`${at.action}: ${at.refused.length} record${at.refused.length === 1 ? '' : 's'} refused, so the load stopped${putBack ? `; ${putBack}` : ''}`, { code: 'LOCAL_LOAD_REFUSED', hint: 'fix the records (or the Action) and load the file again: what was applied is not submitted twice', details: data })
+  }
+  return { data, text: `Loaded ${file} through governed Actions as the local submitter:\n${outcomes.map((o) => `  ${loadWords(o)}`).join('\n')}` }
+}

package/src/commands/local/dev.ts

@@ -36,7 +36,7 @@ import { ensureMediaSets, mediaUpload } from '../../local/local-media-sets'
 import { fillPlaceholderMedia } from '../../local/local-media-placeholders'
 import { applyChatApp, keyCalls } from '../../local/local-chat-apps'
 import { applyLessons } from '../../local/local-lessons'
-import { applyStandIn, platformOnlyNames, readStandIn, standInNames } from '../../local/local-stand-ins'
+import { applyStandIn, missingGrantInstalls, platformOnlyNames, readStandIn, standInNames, standInPath, writeGrantStandIn } from '../../local/local-stand-ins'
 import { projectProvides } from '../../local/local-adapt'
 import { applyOperatingConfig } from '../../local/local-operating'
 import { localEmbeddingsReachable } from '../../local/local-keys'
@@ -51,15 +51,18 @@ import { decideStepNotes, keepLiveCurrent, mirrorWorkflowState } from '../../loc
 import type { Directory } from '../../local/local-sync-refs'
 import { localProject, type LocalProject } from '../../local/local-project'
 import { isAlive, readState, recordApplied, recordApplying, type LocalCredentials } from '../../local/local-state'
-import { applyErrorText } from '../../local/local-apply-error'
+import { applyErrorText, applyFailureReason } from '../../local/local-apply-error'
+import { sayInFull } from '../../local/local-said-once'
 import { applyFailures, inheritedApplyLine, splitApplyFailures } from '../../local/local-apply-summary'
 import { unchangedSincePull } from '../../local/local-check-inherited'
+import { unreadConfidential, unreadConfidentialLines } from '../../local/local-confidential'
+import { ungrantedReadLines, ungrantedReads } from '../../local/local-ungranted-reads'
 import { readWorkspaceGrants } from '../../local/local-workspace-grants'
 import { ApplyWatchdog, stoppedReapplyingLine } from '../../local/local-apply-watchdog'
 import { hasGeneratedSampleData, pulledSampleData, pulledSampleDataNote, remakeLines, remakeReason, remakeSampleData } from '../../local/local-sample-remake'
 import { appsAwayByRestore } from '../../local/local-app-restore'
 import { BASELINE_RECORD, readBaseline } from '../../local/local-db-snapshot'
-import { canChangeRuntime, filesChangedTrigger, recordApply } from '../../local/local-apply-history'
+import { canChangeRuntime, filesChangedTrigger, readApplies, recordApply } from '../../local/local-apply-history'
 import { failedForRuntime, RUNTIME_DOWN_ERROR, RUNTIME_STOPPED_LINE, runtimeAnswering } from '../../local/local-runtime-health'
 import { noticeLines, projectNotices } from '../../local/local-project-notices'
 import { refreshVendoredSdk, vendoredSdkState } from '../../local/local-vendored-sdk'
@@ -342,6 +345,27 @@ async function apply(project: LocalProject, target: SyncTarget, opts: ApplyOptio
       result = withNotes(await runCli(project, commandFor(target, profiles), opts.auth))
     }
   }
+  // A Function that grants itself a workspace Plugin this runtime has no install of: a stand-in of that
+  // name is written and installed, and the Function deployed again; its calls say "not connected" here (X2).
+  for (let n = 0; !result.ok && target.kind === 'function' && n < 5; n++) {
+    const missing = missingGrantInstalls(result.output)
+    if (!missing.length) break
+    const installs = [...new Set(missing.map((g) => g.install))]
+    const made: string[] = []
+    for (const install of installs) {
+      const wrote = writeGrantStandIn(project.root, install, missing.filter((g) => g.install === install).map((g) => g.capability))
+      if (!wrote && !readStandIn(project.root, install)) break
+      const added = await applyStandIn(project, install, profiles.workspace, (args) => runCli(project, args, opts.auth))
+      if (!added.ok) {
+        result = { ...result, output: `${result.output.trim()}\n  the stand-in ${standInPath(install)} could not be installed: ${oneLine(added.output)}` }
+        break
+      }
+      made.push(install)
+    }
+    if (made.length !== installs.length) break
+    notes = [notes, ...made.map((i) => `  warning: ${original.file} grants itself the Plugin ${i}, which this runtime doesn’t have: the stand-in ${standInPath(i)} stands in for it, and its calls answer “not connected” here (the workspace’s own install is used there)`)].filter(Boolean).join('\n')
+    result = withNotes(await runCli(project, command, opts.auth, bundleEnv))
+  }
   // A Function whose build cannot find a file it imports from beside its folder: said as that, first.
   if (!result.ok && target.kind === 'function') result = { ...result, output: missingImportsOutput(project, original.file, result.output) }
   if (!result.ok) return result
@@ -448,6 +472,14 @@ async function apply(project: LocalProject, target: SyncTarget, opts: ApplyOptio
   if (workspaceGrants?.problems.length) return { ok: false, output: workspaceGrants.problems.map((p) => `error [WORKSPACE_GRANTS]: ${p}`).join('\n') }
   const unknownTypes = (workspaceGrants?.grants ?? []).filter((g) => !objectTypes.includes(g.objectType)).map((g) => g.objectType)
   if (unknownTypes.length) result = { ...result, output: `${result.output}\n  warning: blueprint/workspace-grants.yaml names ${unknownTypes.join(', ')}, which the project's Blueprint doesn't hold here` }
+  // Confidential fields nothing here may read (X7): each reads as hidden, which looks like a mistake once an Agent says so.
+  if (target.kind === 'blueprint') {
+    const unread = unreadConfidentialLines(unreadConfidential(project.root))
+    if (unread.length) result = { ...result, output: [result.output, ...unread].join('\n') }
+    // What the project's workflows and Apps read that the linked workspace isn't granted (X2).
+    const ungranted = ungrantedReadLines(ungrantedReads(project.root))
+    if (ungranted.length) result = { ...result, output: [result.output, ...ungranted].join('\n') }
+  }
   for (const step of followUpsFor(target, profiles, { publish: opts.publish, workspaceId: opts.workspaceId, objectTypes, grants: workspaceGrants?.grants ?? [] })) {
     const done = await runCli(project, step.args, opts.auth)
     if (!done.ok && !step.alreadyDone?.test(done.output)) return done
@@ -807,7 +839,9 @@ async function dev(ctx: CommandContext) {
     const mirrored = await mirrorOrgSettings(synced, settingsCalls(serviceUrl, creds), { localEmbeddings: localEmbeddingsReachable() }).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}`)
+      // In full once per runtime start, then one line while the list is the same (N9).
+      if (sayInFull(project, 'settings-differ', mirrored.differences, state.startedAt)) for (const d of mirrored.differences) ctx.output.note(`  differs from the workspace: ${d}`)
+      else if (mirrored.differences.length) ctx.output.note(`  ${mirrored.differences.length} setting${mirrored.differences.length === 1 ? '' : 's'} differ from the workspace, as before (\`frontera local status\` lists them)`)
       recordSettingsDifferences(project, organizationId, mirrored.differences)
     }
   }
@@ -870,7 +904,7 @@ async function dev(ctx: CommandContext) {
     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 } : {}) }
     // A Blueprint published with an Action that didn't deploy keeps how each type and Action came out.
-    return { ...base, status: 'failed', error: oneLine(applyErrorText(result.output)), ...failureCodeAndHint(result.output), ...(result.blueprint ? blueprintRecord(result.blueprint) : {}) }
+    return { ...base, status: 'failed', error: applyFailureReason(result.output), ...failureCodeAndHint(result.output), ...(result.blueprint ? blueprintRecord(result.blueprint) : {}) }
   }
 
   const runOne = async (target: SyncTarget) => {
@@ -1296,6 +1330,30 @@ async function dev(ctx: CommandContext) {
       }
     })())
 
+  /**
+   * An Agent whose operating.json was deleted while its agent.json stays: its behavior settings are
+   * taken away on the runtime too, as a change request takes them away in the workspace (X4). Before,
+   * the runtime kept them, and the Agent stayed out of the built-in Chat here.
+   */
+  const clearDeletedBehavior = async (): Promise<void> => {
+    if (!creds?.session) return
+    const known = loadHashes(project, organizationId)
+    const present = new Set(allTargets(project.root).map((t) => t.key))
+    for (const key of [...known.keys()].filter((k) => k.startsWith('operating:') && !present.has(k))) {
+      const slug = key.slice('operating:'.length)
+      if (!present.has(`agent:${slug}`)) continue
+      const cleared = await applyOperatingConfig({ serviceUrl, creds, slug, file: join(project.root, 'agents', slug, 'operating.json'), document: null })
+      if (!cleared.ok) {
+        ctx.output.note(`  warning: agents/${slug}/operating.json was deleted, and its behavior settings couldn’t be taken away here: ${oneLine(cleared.output)}`)
+        continue
+      }
+      ctx.output.note(`  ✓ Agent ${slug}: behavior settings taken away (agents/${slug}/operating.json was deleted); publish it and the built-in Chat offers it again`)
+      applied.delete(key)
+      known.delete(key)
+      saveHashes(project, organizationId, known)
+    }
+  }
+
   // Watch from the start, so a save during the first sync is not missed.
   const once = flagBool(ctx, 'once')
   // One watcher per project (Forge keeps one running; a second would apply every change twice). `--once` is always allowed.
@@ -1322,6 +1380,7 @@ async function dev(ctx: CommandContext) {
         if (filename.toString() === BASELINE_RECORD) afterRestore()
         // An Agent's folder, a workflow's or a Function's file deleted: what the runtime holds follows.
         if (/^(agents|workflows|functions)([\\/]|$)/.test(filename.toString()) && !existsSync(join(project.root, filename.toString()))) void sweepOrphans()
+        if (/^agents[\\/][^\\/]+[\\/]operating\.json$/.test(filename.toString()) && !existsSync(join(project.root, filename.toString()))) void clearDeletedBehavior()
         // Only a change that queued an item starts a round: the watcher's own writes under `.frontera/`,
         // a screenshot, a coding agent's settings or a note in docs/ never do.
         if (queuePath(filename.toString()) && !busy) schedule()
@@ -1332,6 +1391,7 @@ async function dev(ctx: CommandContext) {
   pruneBuild(project, organizationId, new Set(targets.map((t) => t.key)))
   // An Agent, workflow or Function whose file was deleted is taken out of service here, as the files now say.
   await sweepOrphans()
+  await clearDeletedBehavior()
   ctx.output.note(targets.length ? `Applying ${targets.length} item${targets.length === 1 ? '' : 's'} to the local runtime` : 'Nothing to apply yet')
   // Files in the applied folders that match no kind: said, not skipped in silence.
   for (const line of unappliedFiles(project.root)) {
@@ -1377,13 +1437,21 @@ async function dev(ctx: CommandContext) {
       throw new CliError(message, { code: 'LOCAL_APPLY_FAILED', hint: 'fix the files above and run again; `frontera local status` lists each item that didn’t apply', details: { failed: made, ...inheritedField } })
     }
     const done = targets.length - unchanged
+    // Nothing new here, but the watcher (or another `local dev`) applied these files already: said when, and why (N9).
+    const already = done === 0 ? readApplies(project.stateDir).filter((r) => r.applied > 0).at(-1) : undefined
+    const alreadyField = already ? { alreadyApplied: { at: already.finished, trigger: already.trigger } } : {}
+    const alreadyText = already ? `; already applied by \`frontera local dev\` at ${new Date(already.finished).toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' })} (${already.trigger})` : ''
     if (inherited.length) {
       const summary = inheritedApplyLine(inherited.length)
-      ctx.output.note(`  ${summary}:`)
-      for (const f of inherited) ctx.output.note(`    ${f.ref ?? f.item}: ${oneLine(f.error)}`)
-      return { data: { applied: done, unchanged, failed: 0, ...inheritedField, summary, ...(warned.size ? { warnings: [...warned.values()] } : {}) }, text: `Applied ${done}${unchanged ? `, ${unchanged} unchanged` : ''}; ${summary}` }
+      // Each inherited failure in full once per runtime start, then the one line while they stay the same.
+      const lines = inherited.map((f) => `${f.ref ?? f.item}: ${oneLine(f.error)}`)
+      if (sayInFull(project, 'inherited-failures', lines, state.startedAt)) {
+        ctx.output.note(`  ${summary}:`)
+        for (const l of lines) ctx.output.note(`    ${l}`)
+      } else ctx.output.note(`  ${summary}, as before (\`frontera local status\` lists them)`)
+      return { data: { applied: done, unchanged, failed: 0, ...inheritedField, summary, ...alreadyField, ...(warned.size ? { warnings: [...warned.values()] } : {}) }, text: `Applied ${done}${unchanged ? `, ${unchanged} unchanged` : ''}${alreadyText}; ${summary}` }
     }
-    return { data: { applied: done, unchanged, ...(warned.size ? { warnings: [...warned.values()] } : {}) }, text: `Applied ${done}${unchanged ? `, ${unchanged} unchanged` : ''}` }
+    return { data: { applied: done, unchanged, ...alreadyField, ...(warned.size ? { warnings: [...warned.values()] } : {}) }, text: `Applied ${done}${unchanged ? `, ${unchanged} unchanged` : ''}${alreadyText}` }
   }
 
   ctx.output.note('Watching datasets/, blueprint/, knowledge/, skills/, mcp/, themes/, functions/, workflows/, agents/, chat-apps/, apps/, brand/ and library.json (Ctrl+C to stop)')

package/src/commands/local/embeddings.ts

@@ -0,0 +1,74 @@
+import { CliError, UsageError } from '../../errors'
+import { embeddingKeyOptions, embeddingNextStep, EMBEDDING_KEY_SOURCES, recommendedEmbeddingKey } from '../../local/local-embedding-setup'
+import { configuredProviders, setKey } from '../../local/local-keys'
+import { PLATFORM_DEFAULT_EMBEDDING } from '../../local/local-org-settings'
+import { localProject } from '../../local/local-project'
+import { readSnapshot } from '../../local/local-sync-snapshot'
+import { readState } from '../../local/local-state'
+import { type Command } from '../types'
+
+/**
+ * `frontera local embeddings [use <provider>]` (Forge improvement plan L9):
+ * what the local runtime embeds knowledge with, and real embeddings from a
+ * key the person already has. A key is read from the environment and stored
+ * as `local key-set` stores one; it is never printed.
+ */
+export const localEmbeddings: Command = {
+  meta: {
+    noun: 'local',
+    verb: 'embeddings',
+    args: [
+      { name: 'use', required: false, description: '`use` to store a key from this shell for the runtime’s embeddings' },
+      { name: 'provider', required: false, description: EMBEDDING_KEY_SOURCES.map((s) => s.provider).join(' | ') },
+    ],
+    flags: {},
+    summary: 'Say what the local runtime embeds knowledge with, and use a key you already have for real embeddings',
+    details: [
+      'Without a key the runtime embeds with approximate local vectors (passages found by shared words). An OpenAI, OpenRouter or Gemini key gives a provider’s embedding model; the one that embeds as the workspace does is recommended.',
+      '`use <provider>` reads its key from this shell’s environment (OPENAI_API_KEY, OPENROUTER_API_KEY, or GOOGLE_GENERATIVE_AI_API_KEY, GEMINI_API_KEY, GOOGLE_API_KEY), stores it in the keychain and never prints it. The runtime takes it at its next start.',
+    ],
+    examples: ['frontera local embeddings', 'frontera local embeddings use openai'],
+    offline: true,
+  },
+  async run(ctx) {
+    const [sub, provider] = ctx.positional
+    const project = localProject(ctx.cwd)
+    const state = readState(project)
+    const keyless = !!state?.credentials?.modelProviders?.includes('local-embeddings')
+    const workspace = readSnapshot(project.root)?.settings?.embedding ?? PLATFORM_DEFAULT_EMBEDDING
+    const options = embeddingKeyOptions(process.env, configuredProviders(), workspace)
+
+    if (sub === undefined) {
+      const recommended = recommendedEmbeddingKey(options)
+      const next = embeddingNextStep(options, keyless)
+      const row = (o: (typeof options)[number]) => `  ${o.label.padEnd(14)} ${o.stored ? 'key stored' : o.envVar ? `key in ${o.envVar}` : 'no key'}${o.matchesWorkspace ? ', embeds as the workspace does' : ''}`
+      return {
+        data: { running: state?.phase === 'ready', keyless, workspaceEmbedding: workspace, options, recommended: recommended?.provider ?? null, next },
+        text: [
+          state?.phase === 'ready' ? (keyless ? 'The runtime embeds with the approximate local vectors (no key).' : 'The runtime embeds with a provider’s model.') : 'The local runtime is not running.',
+          'Providers that can embed here:',
+          ...options.map(row),
+          `Next: ${next}`,
+        ].join('\n'),
+      }
+    }
+    if (sub !== 'use') throw new UsageError(`\`local embeddings\` takes \`use <provider>\`, not "${sub}"`, 'frontera local embeddings use openai')
+    const option = options.find((o) => o.provider === provider)
+    if (!option) throw new UsageError(provider ? `${provider} gives no embeddings here` : 'name the provider', `one of: ${EMBEDDING_KEY_SOURCES.map((s) => s.provider).join(', ')}`)
+    if (!option.envVar) {
+      throw new CliError(`no ${option.label} key is in this shell’s environment`, {
+        code: 'USAGE',
+        hint: `set ${EMBEDDING_KEY_SOURCES.find((s) => s.provider === option.provider)!.vars.join(' or ')} and run it again, or store one at a prompt: \`frontera local key-set ${option.provider}\``,
+      })
+    }
+    setKey(option.provider, process.env[option.envVar]!.trim())
+    return {
+      data: { provider: option.provider, stored: true, from: option.envVar, matchesWorkspace: option.matchesWorkspace, restart: true },
+      text: [
+        `Stored the ${option.label} key from ${option.envVar} for the local runtime (its value is not shown).`,
+        `The runtime embeds with it from its next start: \`frontera local stop\`, then \`frontera local start\`; the next \`frontera local dev\` sets each knowledge base’s threshold for that model.`,
+        ...(option.matchesWorkspace ? [] : ['The workspace embeds with another model, so retrieval here ranks a little differently from the workspace’s.']),
+      ].join('\n'),
+    }
+  },
+}