@frontera-sdk/cli 1.52.43 → 1.52.45

package/package.json

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

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

@@ -26,6 +26,7 @@ import { agentFilesProblem, caseConcurrency, findCaseFiles, runCases, selectCase
 import { findWorkflowTestFiles, recordWorkflowTestRun, runWorkflowTests, workflowFileState } from '../../local/local-workflow-tests'
 import { vendoredSdkLine, vendoredSdkState } from '../../local/local-vendored-sdk'
 import { withFix } from '../../local/fix-words'
+import { runtimeKeyCustodianProblem } from '../../local/local-key-custodian'
 import { ensureAppPackages } from '../../project-bootstrap'
 import { flagBool, flagString, type Command, type CommandContext } from '../types'
 
@@ -53,8 +54,10 @@ import { flagBool, flagString, type Command, type CommandContext } from '../type
  * case with `realActions` or a `decision`), so after the apply the database
  * is kept as a baseline (`local-db-snapshot.ts`, taken again only when what
  * is applied changed), and after the tests it is restored: each check starts
- * from the data the project's files make. `--keep-state` keeps what the tests
- * wrote, to look at it.
+ * from the data the project's files make. The run history (conversations,
+ * runs, evaluations) is kept across it (`local-history-carry.ts`), so one
+ * check's results can be compared with the last. `--keep-state` keeps what the
+ * tests wrote, to look at it.
  *
  * Knowledge documents are read by a background job whose work lands in the
  * database: before the baseline and the tests, the check waits (bounded)
@@ -373,8 +376,13 @@ async function check(ctx: CommandContext) {
       continue
     }
     if (step === 'start') {
-      if (running(project)) record({ step, status: 'skipped', note: 'the runtime is already running', ms: 0 })
-      else await command(step, root, self(['local', 'start']), 'frontera local start')
+      if (running(project)) {
+        // Running, with keys it can't read: every later step would fail on a secret or an Action record.
+        const state = readState(project)!
+        const keyProblem = await runtimeKeyCustodianProblem(`http://127.0.0.1:${state.ports.service}`)
+        if (keyProblem) record({ step, status: 'failed', note: keyProblem, ms: 0 })
+        else record({ step, status: 'skipped', note: 'the runtime is already running', ms: 0 })
+      } else await command(step, root, self(['local', 'start']), 'frontera local start')
       continue
     }
     if (step === 'apply') {
@@ -560,10 +568,9 @@ async function check(ctx: CommandContext) {
       })
       recordRun(project, results)
       const bad = results.filter((r) => !r.passed && !r.notRun)
-      // Each failing case's conversation, last turn's trace and reply, read before the rollback takes the conversation.
+      // 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)
-      const rollsBack = baselineReady && !!testData && !testData.kept
-      for (const [i, e] of evidence) ctx.output.note(`     ${results[i]!.agent} · ${results[i]!.name}: ${evidenceLine(e, { rolledBack: rollsBack })}`)
+      for (const [i, e] of evidence) ctx.output.note(`     ${results[i]!.agent} · ${results[i]!.name}: ${evidenceLine(e)}`)
       const notRun = notRunGroups(results)
       for (const g of notRun) {
         if (g.skipped) ctx.output.note(`   – ${g.skipped} more case${g.skipped === 1 ? '' : 's'} not sent: ${g.what}`)
@@ -604,9 +611,10 @@ async function check(ctx: CommandContext) {
     const state = readState(project)
     if (state?.credentials && running(project)) {
       const restored = await restoreBaseline(project, state.credentials.organizationId, { serviceAnswers: () => waitForDatabaseReady(`http://127.0.0.1:${state.ports.service}`) })
-      // Traces live outside the platform database: a failing case's trace outlives the rollback, its conversation does not.
+      // The run history is kept across the rollback; when it couldn't be, a failing case's conversation went with it (its trace stays: traces live outside the database).
       const traced = steps.some((st) => st.failures?.some((f) => f.traceId))
-      testData = { ...testData, rolledBack: restored.ok, ms: restored.ms, note: restored.ok ? `the tests’ writes were rolled back: ${restored.note}${traced ? '; the failing cases’ conversations went with them, their traces stay (trace_get, Studio’s Traces)' : ''}` : `the tests’ writes were not rolled back: ${restored.note}` }
+      const historyLost = restored.history?.mode === 'keep' && !restored.history.ok
+      testData = { ...testData, rolledBack: restored.ok, ms: restored.ms, note: restored.ok ? `the tests’ writes were rolled back: ${restored.note}${traced && historyLost ? '; the failing cases’ conversations went with them, their traces stay (trace_get, Studio’s Traces)' : ''}` : `the tests’ writes were not rolled back: ${restored.note}` }
       ctx.output.note(`── test data: ${testData.note}${restored.ok ? ' (`--keep-state` keeps them)' : ''}`)
       // The documents the baseline holds unread are read again: their reading went with the database the restore replaced.
       const ingest = restored.ok ? localIngestApi(`http://127.0.0.1:${state.ports.service}`, state.credentials) : null

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

@@ -59,6 +59,7 @@ import { localSchema } from './schema'
 import { localSync } from './sync'
 import { keylessEmbeddingsStatus, KEYLESS_RETRIEVAL_NOTE } from '../../local/local-org-settings'
 import { withFix } from '../../local/fix-words'
+import { isKeyCustodianProblem, KEY_CUSTODIAN_FIX, runtimeKeyCustodianProblem } from '../../local/local-key-custodian'
 
 /**
  * `frontera local …`: Frontera's runtimes on this machine, for FDEs and the coding agents working with them.
@@ -302,7 +303,8 @@ async function start(ctx: CommandContext): Promise<{ data: unknown; text: string
   if (state.phase !== 'ready') {
     throw new CliError(`the local runtime did not start: ${state.error ?? state.phase}`, {
       code: 'LOCAL_START',
-      hint: 'see `frontera local logs <component>`; fix the cause and run `frontera local start` again',
+      // Keys a restart can't bring back: the error carries its fix, a reset.
+      hint: isKeyCustodianProblem(state.error) ? KEY_CUSTODIAN_FIX : 'see `frontera local logs <component>`; fix the cause and run `frontera local start` again',
     })
   }
   const profile = await registerLocalProfile(project, state)
@@ -411,6 +413,8 @@ async function status(ctx: CommandContext) {
   const stuck = (state.phase === 'ready' && isAlive(state.supervisorPid) && state.credentials ? await stuckKnowledge(`http://127.0.0.1:${state.ports.service}`, state.credentials, readBaseline(project, state.credentials.organizationId)?.restoredAt) : null) ?? []
   // What the runtime holds with no file in the project (an Agent whose folder was deleted): said with its fix.
   const orphans = (state.phase === 'ready' && isAlive(state.supervisorPid) && state.credentials ? await projectOrphans(project, `http://127.0.0.1:${state.ports.service}`, state.credentials).catch(() => null) : null) ?? []
+  // Encryption keys the runtime can't read (data keys a hosted OpenBao locked): every secret and governed Action record fails until a reset.
+  const keyProblem = state.phase === 'ready' && isAlive(state.supervisorPid) ? await runtimeKeyCustodianProblem(`http://127.0.0.1:${state.ports.service}`) : null
   return {
     data: {
       ...rest,
@@ -431,9 +435,11 @@ async function status(ctx: CommandContext) {
       ...(stuck.length ? { knowledgeStuck: stuck } : {}),
       // On the runtime, not in the files: each with what fixes it (`local dev` archives an Agent or workflow whose file was deleted).
       ...(orphans.length ? { notInProject: orphans } : {}),
+      ...(keyProblem ? { keyCustodian: { problem: keyProblem, fix: KEY_CUSTODIAN_FIX } } : {}),
     },
     text: [
       renderStatus({ ...state, components }, project, undefined, live, setIds, personas, secrets, liveApps ?? null, down),
+      ...(keyProblem ? ['', 'Encryption keys', `  ✕ ${keyProblem}`] : []),
       ...(stuck.length ? ['', 'Knowledge', ...stuck.map((k) => `  warning: ${k.problem}`)] : []),
       ...(orphans.length ? ['', 'On the runtime, not in the project', ...orphans.map((o) => `  warning: ${orphanLine(o)}`)] : []),
       ...(devServers.length ? ['', 'App dev servers', ...devServers.map((s) => `  ${devServerLine(s)}`)] : []),

package/src/commands/local/init.ts

@@ -10,6 +10,9 @@ import { readLink } from '../../local/local-sync-link'
 import { generateSyntheticData, addMissingBackings, loadScenario, SCENARIO_TEMPLATE } from '../../local/local-synthetic-data'
 import { isoDay, writeSampleOptions } from '../../local/local-sample-remake'
 import { migrateMcpConfigs, writeSolutionScaffold } from '../../local/local-scaffold'
+import { checkCompatibility } from '../../kit'
+import { cliVersion } from '../kit/shared'
+import { vendorKit } from '../kit/vendor'
 import { flagBool, flagString, type Command, type CommandContext } from '../types'
 import { localSync } from './sync'
 
@@ -39,6 +42,7 @@ export const localInit: Command = {
       kinds: 'string',
       'no-sample-data': 'boolean',
       'no-app-code': 'boolean',
+      'no-kit': 'boolean',
       rows: 'string',
       seed: 'string',
     },
@@ -80,9 +84,25 @@ export const localInit: Command = {
       const at = scaffold.skipped.indexOf(file)
       if (at >= 0) scaffold.skipped.splice(at, 1)
     }
+    // The whole authoring kit, after the scaffold so its managed block lands in
+    // the project's AGENTS.md: the solution skills (delivery, Agents, workflows,
+    // Functions, Apps, embeds, review) reach every coding agent working here,
+    // not only the CLI skill. `--no-kit` leaves it out, for a machine that uses
+    // the installed plugin instead (`frontera kit doctor` finds duplicates).
+    const kit = { written: [] as string[], skipped: [] as string[] }
+    if (!flagBool(ctx, 'no-kit')) {
+      const compat = checkCompatibility(cliVersion())
+      if (compat.compatible) {
+        const vendored = vendorKit(target, { force })
+        kit.written.push(...vendored.report.written, ...vendored.edited)
+        kit.skipped.push(...vendored.report.conflicts)
+      } else {
+        ctx.output.note(`  the Frontera skills were not added: ${compat.reason}; run \`frontera kit vendor\` after updating the CLI`)
+      }
+    }
     const listed = (files: string[]) => files.filter((f) => !f.startsWith('vendor/'))
-    const written = [...new Set(listed([...scaffold.written, ...harness.written]))]
-    const skipped = listed([...scaffold.skipped, ...harness.skipped]).filter((f) => !written.includes(f))
+    const written = [...new Set(listed([...scaffold.written, ...harness.written, ...kit.written]))]
+    const skipped = listed([...scaffold.skipped, ...harness.skipped, ...kit.skipped]).filter((f) => !written.includes(f))
 
     let installed: boolean | null = null
     if (!flagBool(ctx, 'no-install') && scaffold.written.includes('package.json')) {

package/src/commands/local/snapshot.ts

@@ -1,6 +1,7 @@
 import { CliError, UsageError } from '../../errors'
 import { appsLostWords } from '../../local/local-app-restore'
 import { BASELINE_DB, readBaseline, restoreBaseline, saveBaseline, secretsWords } from '../../local/local-db-snapshot'
+import { historyWords } from '../../local/local-history-carry'
 import { localIngestApi, settleKnowledge } from '../../local/local-knowledge-ingestion'
 import { localProject } from '../../local/local-project'
 import { projectSecretLines } from '../../local/local-project-secrets'
@@ -15,7 +16,8 @@ import { flagBool, type Command } from '../types'
  * same, by hand: save after setting up data to come back to, restore to throw
  * away what was written since. The catalog of managed datasets, object
  * storage and local traces are not part of it. Workspace secrets are
- * configuration, not data: a restore keeps them as they are now, unless
+ * configuration, not data, and the run history (conversations, runs,
+ * evaluations) is what happened: a restore keeps both as they are now, unless
  * `--exact` puts the baseline's back too.
  */
 
@@ -31,6 +33,7 @@ export const localSnapshot: Command = {
     details: [
       'save keeps the database as it is now as the baseline, replacing the one before. restore puts the database back as the baseline holds it; the service, job engine and runner keep running and reconnect, and the command returns once the service reaches the database again (it waits up to 30 seconds).',
       'Workspace secrets are configuration, not data: restore keeps them as they are now (set, changed or deleted since the baseline), and `local check` keeps them across its rollback too. `--exact` puts the baseline\'s secrets back as well.',
+      'The run history is kept the same way: conversations (an Agent test case\'s included), Agent sessions and runs, workflow and Function runs and evaluation runs are as they were before the restore, so results can be compared across runs; the records those runs wrote are rolled back. A history row that names a record the restore took away is left out and counted. `--exact` puts the baseline\'s history back as well.',
       'Items applied after the baseline count as not applied once it is restored: the next `frontera local dev` applies them again (a running one does so at once).',
       'Knowledge documents are read by a background job. save waits (up to two minutes) until no document is still being read, so the baseline never holds one half-read; restore queues any document the baseline holds unread to be read again, and waits for it.',
     ],
@@ -64,7 +67,7 @@ export const localSnapshot: Command = {
     }
     const exact = flagBool(ctx, 'exact')
     const restored = await ctx.output.task('Restoring the database from the baseline', () =>
-      restoreBaseline(project, organizationId, { serviceAnswers: () => waitForDatabaseReady(`http://127.0.0.1:${state.ports.service}`) }, { secrets: exact ? 'baseline' : 'keep' }),
+      restoreBaseline(project, organizationId, { serviceAnswers: () => waitForDatabaseReady(`http://127.0.0.1:${state.ports.service}`) }, { secrets: exact ? 'baseline' : 'keep', history: exact ? 'baseline' : 'keep' }),
     )
     if (!restored.ok) throw new CliError(restored.note, { code: 'LOCAL_SNAPSHOT_FAILED', hint: 'see `frontera local logs postgres` and `frontera local logs service`' })
     // The documents the baseline holds unread are read again: their reading went with the database the restore replaced.
@@ -85,6 +88,8 @@ export const localSnapshot: Command = {
         ...(lost.length ? { appsLost: lost.map((a) => ({ app: a.name, dir: a.dir, deployment: a.lost, baselineDeployment: a.back })) } : {}),
         // Names and counts only: what became of the workspace secrets.
         workspaceSecrets: restored.secrets?.mode === 'keep' ? { kept: restored.secrets.ok, count: restored.secrets.kept, setAgain: restored.secrets.notKept, ...(restored.secrets.problem ? { problem: restored.secrets.problem } : {}) } : { kept: false, exact: exact },
+        // Counts only: what became of the run history.
+        runHistory: restored.history?.mode === 'keep' ? { kept: restored.history.ok, rows: restored.history.rows, notKept: restored.history.notKept, ...(restored.history.problem ? { problem: restored.history.problem } : {}) } : { kept: false, exact },
         ...(secrets.length ? { secrets } : {}),
         ...(knowledge.length ? { knowledge: knowledge.map((l) => l.replace(/^warning:\s*/, '')) } : {}),
       },
@@ -92,6 +97,7 @@ export const localSnapshot: Command = {
         `Restored the database from the baseline: what was written since is gone (${restored.ms} ms).${items ? ` ${items} item${items === 1 ? '' : 's'} applied after the baseline will apply again on the next \`frontera local dev\`.` : ''}`,
         ...(lost.length ? [`  ${appsLostWords(lost).replace(/^./, (c) => c.toUpperCase())}.`] : []),
         ...(restored.secrets ? [`  ${secretsWords(restored.secrets).replace(/^./, (c) => c.toUpperCase())}${restored.secrets.mode === 'keep' && restored.secrets.ok && !restored.secrets.notKept.length ? ': secrets are configuration, not test data (`--exact` restores the baseline’s).' : '.'}`] : []),
+        ...(restored.history ? [`  ${historyWords(restored.history).replace(/^./, (c) => c.toUpperCase())}.`] : []),
         ...secrets.map((l) => `  warning: ${l}`),
         ...knowledge.map((l) => `  ${l}`),
       ].join('\n'),

package/src/commands/local/sync-request.ts

@@ -12,8 +12,10 @@ import { adoptProposedLessons } from '../../local/local-lessons'
 import { localProject, type LocalProject } from '../../local/local-project'
 import { HISTORY_KINDS, projectAtRevision } from '../../local/local-sync-base'
 import { normalizeOrigin, unwrap } from '../../local/local-sync-client'
-import { getSyncKey, readLink, type SyncLink } from '../../local/local-sync-link'
+import { getSyncKey, readLink, setModelMapping, type SyncLink } from '../../local/local-sync-link'
 import { itemTitle } from '../../local/local-sync-names'
+import { checkBody, markMissingModels, markRefused, type WorkspaceModel } from '../../local/local-sync-precheck'
+import { rows } from '../../local/local-sync-remote'
 import { evalsDetail, evalsLine, lastRender, sessionScreenshots } from '../../local/local-request-evidence'
 import { readAppliedRun, readLastRun, recordApplied, recordRun } from '../../local/local-test-baseline'
 import { agentFilesProblem, runCases, selectCaseFiles } from '../../local/local-test-runner'
@@ -330,6 +332,9 @@ function itemJson(item: PushItem) {
     proposable: item.proposable,
     blocked: item.blocked,
     reason: item.reason,
+    ...(item.fix ? { fix: item.fix } : {}),
+    ...(item.sample ? { sample: true } : {}),
+    ...(item.missingModels?.length ? { missingModels: item.missingModels } : {}),
     files: item.diff,
     notes: item.notes,
     ...(item.assets ? { assets: item.assets.map((a) => ({ path: a.path, bytes: a.bytes, change: a.change })) } : {}),
@@ -404,8 +409,41 @@ async function deletionUsers(project: LocalProject, link: SyncLink, items: PushI
   }
 }
 
+/**
+ * The workspace's checks for what would be proposed, run before anything is
+ * sent (`POST /v1/change-requests/check`); each item they refuse is blocked
+ * with its reason and fix. A platform without the check leaves them to
+ * Propose: `checked` says which.
+ */
+async function precheck(api: Platform, items: PushItem[]): Promise<{ checked: boolean; refused: string[]; problem?: string }> {
+  const body = checkBody(items)
+  if (!body.length) return { checked: true, refused: [] }
+  try {
+    const answer = await api.call<{ checks?: unknown[] }>('POST', '/v1/change-requests/check', { items: body }, { timeoutMs: 120_000 })
+    return { checked: true, refused: markRefused(items, checksOf(answer)) }
+  } catch (err) {
+    if (err instanceof CliError && (err.code === 'NOT_FOUND' || err.code === 'SYNC_CHECKS')) {
+      // An older platform has no check; a refusal of the check itself names the items as the push would.
+      if (err.code === 'SYNC_CHECKS') return { checked: true, refused: markRefused(items, checksOf(err.details)) }
+      return { checked: false, refused: [] }
+    }
+    return { checked: false, refused: [], problem: (err as Error).message.split('\n')[0] }
+  }
+}
+
+/** The workspace's chat models, offered in place of one only this computer has; empty when the platform can't list them. */
+async function workspaceModels(api: Platform): Promise<WorkspaceModel[]> {
+  try {
+    const answer = await api.call<unknown>('GET', '/v1/sync/models')
+    return rows<{ slug?: string; name?: string; kind?: string }>(answer).flatMap((m) => (m.slug && (m.kind ?? 'text') === 'text' ? [{ slug: m.slug, name: m.name ?? m.slug, kind: m.kind ?? 'text' }] : []))
+  } catch {
+    return []
+  }
+}
+
 function previewText(link: SyncLink, items: PushItem[], kept: { title: string } | null, orgNote: string | null, available: boolean, usedBy: Map<string, string[]> = new Map()): string {
-  const ok = items.filter((i) => i.proposable)
+  const ok = items.filter((i) => i.proposable && !i.sample)
+  const samples = items.filter((i) => i.proposable && i.sample)
   const not = items.filter((i) => !i.proposable)
   const name = link.workspaceName ?? link.workspace
   const lines = [
@@ -413,7 +451,8 @@ function previewText(link: SyncLink, items: PushItem[], kept: { title: string }
     // Each item's notes under it.
     ...ok.flatMap((i) => [`  [x] ${pushItemLine(i)}`, ...(usedBy.has(i.ref) ? [`      ! Still used by ${usedBy.get(i.ref)!.join(', ')}: applying would be refused`] : []), ...i.notes.map((n) => `      · ${n}`)]),
   ]
-  if (not.length) lines.push('', 'Not proposed:', ...not.map((i) => `  [ ] ${KIND_WORD[i.kind]} ${i.title}: ${i.reason}`))
+  if (samples.length) lines.push('', 'Samples from setting up the project, left out unless named:', ...samples.map((i) => `  [ ] ${KIND_WORD[i.kind]} ${i.title}`))
+  if (not.length) lines.push('', 'Not proposed:', ...not.flatMap((i) => [`  [ ] ${KIND_WORD[i.kind]} ${i.title}: ${i.reason}`, ...(i.fix ? [`      Fix: ${i.fix}`] : [])]))
   if (orgNote) lines.push('', orgNote)
   if (!available) lines.push('', 'This platform does not take change requests yet.')
   if (ok.length && available) lines.push('', 'Propose with `frontera local sync push -t "<title>"`, or name items to propose only those.')
@@ -443,6 +482,36 @@ async function releaseItems(api: Platform, asked: Array<{ slug: string; deployme
   return out
 }
 
+/**
+ * `frontera local sync map-model <local model> <workspace model>`: the
+ * workspace's model a model only this computer has goes as when proposed
+ * (`sync.models` in frontera.yaml); the files keep naming the local one.
+ * `--remove` stops mapping it; with no model, the mappings are listed.
+ */
+export async function syncMapModel(ctx: CommandContext): Promise<{ data: unknown; text: string }> {
+  const project = localProject(ctx.cwd)
+  const link = needLink(project)
+  const [local, workspace] = ctx.positional.slice(1)
+  const name = link.workspaceName ?? link.workspace
+  if (!local) {
+    const models = link.models ?? {}
+    const lines = Object.entries(models).map(([from, to]) => `  ${from} → ${to}`)
+    return { data: { models }, text: lines.length ? [`Models proposed to ${name} as the workspace’s:`, ...lines].join('\n') : `No models mapped. \`frontera local sync push --preview\` names any model ${name} doesn’t have.` }
+  }
+  if (flagBool(ctx, 'remove')) {
+    setModelMapping(project.root, local, null)
+    return { data: { local, workspace: null }, text: `${local} is no longer mapped: an item that names it isn’t proposed until it is mapped again.` }
+  }
+  if (!workspace) throw new UsageError('name the workspace model it goes as', `frontera local sync map-model ${local} <workspace model>; \`push --preview\` lists ${name}’s models`)
+  const offered = await workspaceModels(platformFor(project, link))
+  if (offered.length && !offered.some((m) => m.slug === workspace)) {
+    throw new UsageError(`${name} has no chat model ${workspace}`, `choose one of: ${offered.map((m) => m.slug).slice(0, 12).join(', ')}${offered.length > 12 ? ', …' : ''}`)
+  }
+  setModelMapping(project.root, local, workspace)
+  const label = offered.find((m) => m.slug === workspace)?.name ?? workspace
+  return { data: { local, workspace }, text: `${local} goes to ${name} as ${label} when proposed; the project keeps using ${local} here (sync.models in frontera.yaml).` }
+}
+
 export async function syncPush(ctx: CommandContext): Promise<{ data: unknown; text: string }> {
   const project = localProject(ctx.cwd)
   const link = needLink(project)
@@ -462,6 +531,11 @@ export async function syncPush(ctx: CommandContext): Promise<{ data: unknown; te
     ? { names: new Set(documentNames), pulled: readPulledDocuments(project.root, link.workspace).bases, platform: await platformDocuments(platformFor(project, link), documentNames, remote.items) }
     : undefined
   const all = pushCandidates({ root: project.root, plan, lock, snapshot, remote: remote.items, ...(documents ? { documents } : {}) })
+  // Before anything is sent: models only this computer has, then the workspace's own checks.
+  const known = snapshot.names?.model ? new Set(Object.keys(snapshot.names.model)) : null
+  const missing = known ? markMissingModels(all, known) : new Map<string, string[]>()
+  const api = platformFor(project, link)
+  const checked = available ? await precheck(api, all) : { checked: false, refused: [] as string[] }
   const kept = currentRequest(readRequests(project.root, link.workspace))
   const updating = kept && isOpen(kept.state) ? kept : null
   const orgStored = !!getSyncKey(project, 'organization')
@@ -474,6 +548,8 @@ export async function syncPush(ctx: CommandContext): Promise<{ data: unknown; te
     if (unknown.length) throw new UsageError(`nothing to propose in ${unknown.join(', ')}: ${unknown.length === 1 ? 'it matches' : 'they match'} the workspace, or the project has no such item`, 'list what can be proposed with `frontera local sync push --preview`')
     chosen = named.map((r) => byRef.get(r)!)
   } else chosen = all
+  // Samples from setting up the project go only when named.
+  const leftSamples = named.length ? [] : chosen.filter((i) => i.proposable && i.sample)
   const orgNote = needsOrganizationKey(chosen) ? (orgStored ? 'Blueprint changes are applied with the organization key stored for this project.' : 'Blueprint changes need the organization key to apply: connect again with `--org-key -` before applying.') : null
 
   if (preview) {
@@ -484,7 +560,15 @@ export async function syncPush(ctx: CommandContext): Promise<{ data: unknown; te
         available,
         request: updating ? { id: updating.id, title: updating.title, state: updating.state, items: updating.refs.length, refs: updating.refs } : null,
         items: chosen.map((i) => ({ ...itemJson(i), ...(usedBy.has(i.ref) ? { usedBy: usedBy.get(i.ref) } : {}) })),
-        counts: { proposable: chosen.filter((i) => i.proposable).length, blocked: chosen.filter((i) => !i.proposable).length },
+        counts: { proposable: chosen.filter((i) => i.proposable && !i.sample).length, samples: leftSamples.length, blocked: chosen.filter((i) => !i.proposable).length },
+        // Whether the workspace's checks ran before proposing; a platform without them checks at Propose.
+        checked: checked.checked,
+        ...(('problem' in checked && checked.problem) ? { checkProblem: checked.problem } : {}),
+        models: {
+          missing: [...missing].map(([slug, refs]) => ({ slug, refs })),
+          workspace: missing.size ? await workspaceModels(api) : [],
+          mapped: link.models ?? {},
+        },
         organizationKey: { needed: needsOrganizationKey(chosen), stored: orgStored },
         fetchedAt: snapshot.fetchedAt,
       },
@@ -503,12 +587,11 @@ export async function syncPush(ctx: CommandContext): Promise<{ data: unknown; te
       details: { blocked: stopping.map((i) => ({ ref: i.ref, code: i.blocked, message: i.reason })) },
     })
   }
-  const going = chosen.filter((i) => i.proposable)
+  const going = chosen.filter((i) => i.proposable && !leftSamples.includes(i))
   const releaseAsks = parseReleases(flagString(ctx, 'release'))
   if (!going.length && !releaseAsks.length) throw new CliError('nothing to propose: nothing changed here since the last pull', { code: 'SYNC_NOTHING_TO_PUSH', hint: 'change an item in the project first; `frontera local sync status` shows where it stands' })
   const title = flagString(ctx, 'title')?.trim()
   const description = flagString(ctx, 'description')
-  const api = platformFor(project, link)
   // The current request still taking pushes is updated; one applied or closed (here or on the platform) is not.
   let target = updating
   if (target) {
@@ -554,14 +637,16 @@ export async function syncPush(ctx: CommandContext): Promise<{ data: unknown; te
       request: { id: view.request.id, title: view.request.title, state: view.request.state, items: view.items.length, refs: view.items.map((i) => i.ref) },
       pushed: [...going.map((i) => i.ref), ...releases.map((r) => r.ref)],
       releases: releases.map((r) => ({ ref: r.ref, deployment: r.deployment })),
-      notProposed: notProposed.map((i) => ({ ref: i.ref, code: i.blocked, message: i.reason })),
+      notProposed: notProposed.map((i) => ({ ref: i.ref, code: i.blocked, message: i.reason, ...(i.fix ? { fix: i.fix } : {}) })),
+      samples: leftSamples.map((i) => i.ref),
       organizationKey: { needed: needsOrganizationKey(view.items), stored: orgStored },
     },
     text: [
       `${target ? `Updated “${view.request.title}” in` : `Proposed “${view.request.title}” to`} ${link.workspaceName ?? link.workspace}: ${plural(view.items.length, 'item')}.`,
       ...going.map((i) => `  ${pushItemLine(i)}`),
       ...releases.map((r) => `  Custom App ${r.slug}: release ${r.deployment}${r.chosen ? ' (its newest deployment)' : ''}; Apply promotes it last`),
-      ...(notProposed.length ? ['', 'Not proposed:', ...notProposed.map((i) => `  ${KIND_WORD[i.kind]} ${i.title}: ${i.reason}`)] : []),
+      ...(notProposed.length ? ['', 'Not proposed:', ...notProposed.flatMap((i) => [`  ${KIND_WORD[i.kind]} ${i.title}: ${i.reason}`, ...(i.fix ? [`    Fix: ${i.fix}`] : [])])] : []),
+      ...(leftSamples.length ? ['', `Left out: ${plural(leftSamples.length, 'sample')} from setting up the project (${leftSamples.map((i) => i.title).join(', ')}); name ${leftSamples.length === 1 ? 'it' : 'them'} to propose`] : []),
       ...(orgNote ? ['', orgNote] : []),
       '',
       'Apply it with `frontera local sync request apply`; see it with `frontera local sync request`.',
@@ -812,7 +897,8 @@ async function apply(ctx: CommandContext) {
   if (force && !reason) throw new UsageError('--force needs --reason', 'frontera local sync request apply --force --reason "why it applies without its required checks"')
   let answer: View
   try {
-    answer = await platformFor(project, link).call<View>('POST', `/v1/change-requests/${view.request.id}/apply`, { ...(migration ? { migrationInstruction: migration } : {}), ...(force ? { force: { reason } } : {}) }, { organizationKey, timeoutMs: 15 * 60_000 })
+    // The key in the body: the platform's edge strips `x-frontera-*` headers a client sends. The header stays for an older platform.
+    answer = await platformFor(project, link).call<View>('POST', `/v1/change-requests/${view.request.id}/apply`, { ...(migration ? { migrationInstruction: migration } : {}), ...(force ? { force: { reason } } : {}), ...(organizationKey ? { organizationKey } : {}) }, { organizationKey, timeoutMs: 15 * 60_000 })
   } catch (err) {
     if (err instanceof CliError && err.code === 'SYNC_APPLY_GATED') {
       const gate = (err.details as { gate?: Gate } | undefined)?.gate