@frontera-sdk/cli 1.52.39 → 1.52.40

package/src/local/local-scaffold.ts

@@ -4,12 +4,13 @@ import { dirname, join } from 'node:path'
 import { AUTOMATION_SDK_FILES } from '../automation-template'
 import { AGENTS_MD } from '../harness'
 import vendored from '../vendor/sdk-sources.json'
+import { SDK_MANIFEST, sdkManifestText } from './local-vendored-sdk'
 
 /**
  * A new project in the layout `frontera local dev` applies: one Agent with a
- * test case, one workflow, one Function, and a Blueprint object type with the
- * dataset it reads. Each is small enough to read in a minute and works
- * against the keyless local model as written.
+ * test case, one workflow with its test, one Function with its unit test, and
+ * a Blueprint object type with the dataset it reads. Each is small enough to
+ * read in a minute; the Agent's test case holds for any capable model.
  *
  * The Functions SDK is vendored into `vendor/frontera/` and resolved by the
  * `paths` in `tsconfig.json`, the way `frontera function init` does it: the
@@ -41,7 +42,8 @@ const AGENT = (name: string, modelSlug?: string) =>
 const OPERATING = JSON.stringify(
   {
     version: 1,
-    execution: { harness: 'open-ended' },
+    // `tool:blueprint` is the query tools alone; the Action tools are their own choice.
+    execution: { harness: 'open-ended', toolScopes: 2 },
     variables: [
       {
         key: 'customer_name',
@@ -57,16 +59,61 @@ const OPERATING = JSON.stringify(
   2,
 ) + '\n'
 
+/**
+ * What the starter Agent may use: the word-count Function, called on its own
+ * (no approval), and the Ticket records through its Blueprint tools. The
+ * workflows it may start go in `workflows`, the same way.
+ */
+const BINDINGS = JSON.stringify(
+  {
+    functions: [{ function: 'function/word-count', requiresApproval: false }],
+    workflows: [],
+    blueprint: [{ objectType: 'objectType/Ticket', permissions: ['read'] }],
+  },
+  null,
+  2,
+) + '\n'
+
+/**
+ * What the starter case accepts as offering help: the ways a reply offers it
+ * ("I can look up support tickets for you… Tell me what you're looking for"
+ * matched none of help, assist or question). Each word starts a word, so
+ * "ask" does not match "task".
+ */
+export const STARTER_OFFER_PATTERN = String.raw`\b(help|assist|answer|question|ask|support|look up|find|explain|tell me|let me know|happy to|glad to|I can|able to|what would you like|how can)`
+
 const EVALS = `# Test cases for the assistant. Each case: a conversation, then what a good reply does.
 # \`frontera local test\` (or Evaluations in Studio) runs them against the draft.
 #
-# This one passes with the keyless local model, which repeats what it was told.
-# Once the Agent uses a real model, write expectations about the answer instead.
+# This one checks what any capable model does with a greeting: it offers help.
+# A reply says so in many ways ("I can look up…", "happy to help", "tell me what
+# you need"), so the pattern takes each of them, not one word.
+# Write expectations about what the reply does, not its exact words.
 cases:
-  - name: replies-to-a-greeting
+  - name: offers-help-when-greeted
     conversation:
-      - user: Hello from a new project
-    expectedContains: [Hello from a new project]
+      - user: Hello! What can you help me with?
+    checks:
+      - { type: regex, value: '${STARTER_OFFER_PATTERN}', text: offers help }
+`
+
+const WORKFLOW_TESTS = `# Test cases for workflows/hello.yaml. \`frontera local test --workflow hello\`
+# runs each one on the workflow's draft, waits for the run, then checks it.
+# \`frontera local schema workflow-tests\` is this file's format.
+cases:
+  - name: greets-by-name
+    input: { name: Sam }
+    expect:
+      status: succeeded
+      output:
+        - { path: steps.greet.output, equals: 'Hello, Sam' }
+`
+
+const FIXTURES_README = `# Fixtures
+
+Sample inputs for tests: a payload a workflow test sends, a document an
+Agent's test case refers to, the input a Function's unit test reads. Nothing
+here is applied to the runtime; tests read these files by path.
 `
 
 const WORKFLOW = `apiVersion: workflow/v1
@@ -112,8 +159,10 @@ import wordCount from './word-count'
 // A Function is a handler, so it is tested without a runtime: \`bun test\`.
 // The context refuses what the platform refuses (a grant the manifest does not
 // declare, a step name used twice), so a passing test means something.
+// \`replay: true\` runs it as the platform does, again from the top after each
+// step, so code outside a step that a step changes is caught here too.
 test('counts the words', async () => {
-  const { ctx, logs } = createTestContext({ input: { text: 'four words right here' } })
+  const { ctx, logs } = createTestContext({ replay: true, input: { text: 'four words right here' } })
   expect(await wordCount.handler(ctx)).toEqual({ words: 4 })
   expect(logs.map((l) => l.message)).toEqual(['counted'])
 })
@@ -128,11 +177,17 @@ A Frontera project. Every file here is applied to a local runtime by
 |---|---|
 | \`agents/<slug>/agent.json\` | An Agent's draft: model, instructions, tools |
 | \`agents/<slug>/operating.json\` | Its behavior: procedures, variables, focus, reply checks |
+| \`agents/<slug>/bindings.json\` | What it may use: Functions, workflows, Blueprint object types |
 | \`agents/<slug>/evals/*.yaml\` | Its test cases |
 | \`workflows/<slug>.yaml\` | A workflow |
+| \`workflows/tests/<slug>.yaml\` | A workflow's test cases |
 | \`functions/<name>.ts\` | A Function |
 | \`datasets/<apiName>.json\` + \`.csv\` | Sample data the Blueprint reads |
-| \`blueprint/\` | The Blueprint: object types, links, metrics, actions |
+| \`blueprint/\` | The Blueprint: object types, links, metrics, actions, saved object sets |
+| \`knowledge/<name>/knowledge.json\` | A knowledge base, its documents beside it |
+| \`themes/<name>/theme.json\` | A slide theme, its images beside it |
+| \`chat-apps/<slug>.json\` | A Chat App |
+| \`data/generate.ts\` | How \`frontera local data --synthetic\` makes sample data |
 | \`fixtures/\` | Sample data for tests |
 
 ## Develop
@@ -141,9 +196,9 @@ A Frontera project. Every file here is applied to a local runtime by
 frontera local start   # the runtimes, on this machine
 frontera local dev     # apply each file as you save it
 frontera local ui      # open Studio
-frontera local test    # run the Agents' test cases
-bun test               # run the Functions' unit tests, no runtime needed
-frontera local check   # start, apply and test in one command, before pushing
+frontera local test    # run the Agents' and workflows' test cases
+bun test               # run the Functions' unit tests (functions/), no runtime needed
+frontera local check   # the whole gate in one command, before pushing
 \`\`\`
 
 An Agent's model is the catalog slug in \`modelSlug\` in its \`agent.json\`.
@@ -188,6 +243,13 @@ T-2,Invoice total is wrong,closed
 T-3,Refund not received,open
 `
 
+/**
+ * The sample rows the scaffold writes, by dataset: while a file still holds
+ * exactly these, it is sample data `frontera local data --synthetic` may
+ * remake. Once someone edits it, it is theirs and is kept.
+ */
+export const SCAFFOLD_SAMPLE_ROWS: Readonly<Record<string, string>> = { tickets: DATASET_ROWS }
+
 const OBJECT_TYPE = `apiName: Ticket
 displayName: Ticket
 pluralDisplayName: Tickets
@@ -226,9 +288,8 @@ backing:
 `
 
 /**
- * The CLI's AGENTS.md, plus what a coding agent needs for this project. The
- * \`local\` commands are internal and absent from \`frontera help\`, so an
- * agent following the generic text alone would never find the loop.
+ * The CLI's AGENTS.md, plus what a coding agent needs for this project: the
+ * generic text does not describe the local loop.
  */
 const SOLUTION_AGENTS_MD = `${AGENTS_MD}
 ## This project
@@ -241,50 +302,168 @@ Frontera deployment.
 |---|---|
 | \`agents/<slug>/agent.json\` | An Agent's draft: model, instructions, tools |
 | \`agents/<slug>/operating.json\` | Its behavior: procedures, variables, focus, reply checks |
+| \`agents/<slug>/bindings.json\` | What it may use: the Functions and workflows it may start, the Blueprint object types it may query |
 | \`agents/<slug>/evals/*.yaml\` | Its test cases: a conversation and what a good reply does |
 | \`workflows/<slug>.yaml\` | A workflow |
+| \`workflows/tests/<slug>.yaml\` | Its test cases: an input and what the run must end with |
 | \`functions/<name>.ts\` | A Function (the SDK is vendored in \`vendor/\`) |
 | \`datasets/<apiName>.json\` + \`.csv\` | Sample data the Blueprint reads |
-| \`blueprint/\` | The Blueprint: object types, links, metrics, actions |
+| \`blueprint/\` | The Blueprint: object-types/, link-types/, shared-fields/, semantic-types/, metrics/, actions/, object-sets/ |
+| \`knowledge/<name>/knowledge.json\` | A knowledge base, its documents beside it |
+| \`skills/<name>/SKILL.md\` | A skill |
+| \`themes/<name>/theme.json\` | A slide theme, its images beside it |
+| \`chat-apps/<slug>.json\` | A Chat App |
+| \`apps/<name>/\` | A Custom App's code (\`frontera app init\` from inside apps/) |
+| \`data/generate.ts\` | How \`frontera local data --synthetic\` makes sample data |
+
+\`frontera local dev\` says which files in these folders it does not apply
+and where they belong; a file it skips is never applied.
+
+### What goes where
+
+- An Agent's tools are not in \`agent.json\`. The Functions and workflows it
+  may start and the object types it may query are in \`bindings.json\`
+  (\`frontera local schema bindings\`); without a \`blueprint\` entry it has no
+  Blueprint tools. A procedure that keeps its own tools (\`tools.inherit:
+  false\`) lists them in \`tools.ids\` as \`function:<slug>\`,
+  \`workflow:<slug>\` or \`tool:plugins\` / \`tool:blueprint\` (query tools
+  only) / \`tool:blueprint-actions\` (governed Action tools: list, submit,
+  read a request) / \`tool:web\`, each bound in \`bindings.json\`. That
+  meaning needs \`"toolScopes": 2\` in \`execution\` (new Agents have it);
+  without it \`tool:blueprint\` keeps the Action tools too. Its knowledge is \`knowledgeAttachments:
+  [{ "knowledgeConfigId": "knowledge/<name>" }]\` in \`agent.json\`.
+- A governed Action that writes Blueprint records names
+  \`effect.authoritySourceSystem: active-catalog\`, the source system the
+  Blueprint's own records have (\`frontera blueprint new action <name>\`
+  writes it).
+- A saved object set is \`blueprint/object-sets/<name>.yaml\`
+  (\`frontera local schema blueprint-object-set\`); other files name it
+  \`objectSet/<name>\`, by its name as people say it ("Open work orders") or
+  its file's name.
+- A dataset's first load fixes its columns: declare \`nullable: true\` in its
+  \`columns\` for every column a later CSV may leave empty
+  (\`frontera local data --synthetic\` does). When a CSV has empty values a
+  column did not allow, \`local dev\` cuts a new revision that allows them; a
+  column added, dropped or retyped is a new dataset (another apiName, or
+  \`frontera local reset\`).
+- \`frontera local data --synthetic\` writes sample data that keeps links and
+  states consistent; \`data/generate.ts\` adjusts it, and
+  \`frontera local data --help\` describes both (a field function is
+  \`(row, index, ctx) => value\`, \`row\` holding the whole generated row
+  and \`ctx.rowsOf(type)\` / \`ctx.lookup(type, key)\` the rows of the types
+  it links to; a function that reads another's value runs after it).
+
+When your harness offers the \`frontera\` MCP server's tools (Claude Code
+lists them as \`mcp__frontera__*\`), use them for the loop rather than the
+shell: \`status\` rather than \`frontera local status --json\`, \`apply\`
+rather than \`frontera local dev --once\`, \`test_run\` rather than
+\`frontera local test\`, \`logs\` rather than \`frontera local logs\`, and
+\`read_file_schema\` rather than \`frontera local schema\`. The person
+approves the server once; each shell command can ask them again. The CLI
+below is the fallback: when the tools aren't offered (the server isn't
+connected, or the person chose not to use it), and for what has no tool
+(\`local start\`, \`local check\`, \`local data\`, snapshots).
 
 The loop:
 
 1. \`frontera local start\` brings the runtime up (once; needs Docker).
 2. Edit files. Then run \`frontera local dev --once\`: it applies what
    changed and prints each refused file's error and validation messages.
-   Fix those before going on. (A person may keep \`frontera local dev\`
-   running instead; it applies on save.)
-3. \`frontera local test\` runs the Agents' test cases and exits non-zero
-   when one fails. \`bun test\` runs the Functions' unit tests offline.
+   Fix those before going on. It exits 0 when everything changed or added
+   applied: an item still as the pull wrote it that fails is listed apart,
+   as inherited from the workspace (\`inheritedFailures\` with \`--json\`).
+   (A person may keep \`frontera local dev\` running instead; it applies
+   on save.)
+3. \`frontera local test\` runs the Agents' and the workflows' test cases and
+   exits non-zero when one fails (\`--json\` lists each case's result either
+   way). \`bun test\` here runs the Functions' unit tests offline: the
+   project's \`bunfig.toml\` keeps it to \`functions/\`. An App's own tests
+   run in its folder (\`bun run test\` in \`apps/<name>/\`, part of its
+   \`check\`).
 4. Before handing work back, run \`frontera local check\`: it starts the
-   runtime if needed, applies everything and runs the test cases, and exits
-   non-zero at the first failure.
-5. \`frontera local status -o env\` prints the API URL and keys for scripts.
-
-\`frontera local <verb> --help\` documents each command; they are not
-listed by \`frontera help\`.
-
-## Documentation
-
-Frontera's documentation for the platform this project runs on is an MCP
-server here: \`frontera-docs\` in \`.mcp.json\` (Claude Code) and
-\`.cursor/mcp.json\` (Cursor); for Codex, add the command
-\`frontera local docs-mcp\` as an MCP server. Its tools search and read the
-same pages as the documentation in the platform, for the release the local
-runtime runs. Before writing or changing an \`agent.json\`, an
+   runtime if needed, applies everything, typechecks, runs the Functions'
+   unit tests, each App's own \`check\` script, and the Agent and workflow
+   test cases. Every step runs and is reported (the Agent and workflow
+   tests run on what applied; \`--json\` gives each step's result). What
+   fails the gate:
+   - A failure in anything you changed or added (a governed Action of
+     yours that does not deploy, a type error in your file, your test)
+     fails it: it exits non-zero, naming the first step that failed.
+   - A failure only in items or files unchanged since the pull
+     (\`frontera.lock\`) is listed as inherited from the workspace
+     (\`inherited\` in \`--json\`) and passes, unless \`--strict\`, which
+     fails on those too.
+   When you report back, give the gate's result (passed or failed, and
+   whether with \`--strict\`) and list every inherited failure with the fix
+   the check printed for it: the workspace has the same problem, and the
+   person decides whether it is fixed here.
+5. \`frontera local status\` says what each item came to and why;
+   \`frontera local status -o env\` prints the API URL and keys for scripts.
+
+The loop's commands are listed under Local development in \`frontera help\`;
+\`frontera local <verb> --help\` documents each one. In this folder,
+Blueprint and Action commands use the runtime's organization key, and every
+other command its workspace key, with no \`--profile\`.
+
+## The Frontera MCP server
+
+\`frontera mcp\` gives you this project's local runtime, Frontera's
+documentation, its Apps and, when the project is open in Forge, a browser
+the person watches. It is registered as \`frontera\` in \`.mcp.json\`
+(Claude Code), \`.cursor/mcp.json\` (Cursor), \`opencode.json\` (OpenCode)
+and \`.codex/config.toml\` (Codex). Its documentation tools search and read
+the same pages as the documentation in the platform, for the release the
+local runtime runs. Before writing or changing an \`agent.json\`, an
 \`operating.json\` (procedures, variables), a workflow, a Function or the
 Blueprint, search the documentation for it and follow what it says; do not
-guess a field or a step kind. It reads the documentation that
-\`frontera local start\` keeps for the runtime's release, so start the runtime
-once; after that it needs no key and works while the runtime is stopped.
+guess a field or a step kind. Start the runtime once so the documentation is
+here; after that it needs no key and works while the runtime is stopped.
+
+## See what you built
+
+Check the part you changed, not everything:
+
+- After changing an Agent: \`apply\`, then \`agent_chat\` with it and read
+  the trace (\`trace_get\`). \`test_run\` its cases: \`newlyFailing\` lists
+  what your change broke; \`couldNotRun\` lists cases the model provider or
+  the runtime kept from running (not a regression): tell the person its fix.
+- After changing an App: \`app_render\` the pages you touched and read the
+  console and failed requests; \`browser_open\` to click through a flow.
+- When you report back, attach the screenshot path or the trace link.
+
+What you run here changes the local runtime's records, never the
+workspace's: a workflow run (\`workflow_run\`, \`frontera workflow run\`),
+a Function run, an App and an Agent conversation with real Actions submit
+governed Actions for real here, whether from an \`action\` step or from a
+Function's code, and an Action that creates, updates or deletes Blueprint
+records changes them. An Action whose effect would reach another system (a
+transition or a command) is switched off here and does not run. Those writes
+stay: \`frontera local snapshot save\` before and \`frontera local snapshot
+restore\` after take them back (\`frontera local check\` does this around its
+own tests).
+
+A change request runs each Agent's cases marked \`gate: true\` before it
+applies, against the last applied run; the workspace can require them. Mark
+the cases that guard an Agent's behavior \`gate: true\`, and run them with
+\`test_run\` (\`gate: true\`) before you say a change is ready. Screenshots
+you take are saved under \`.frontera/evidence/<session>/\`, where the
+person can attach them to the request.
+
+You cannot promote a deployment, apply a change request or read secrets.
+Say what is ready and let the person decide.
 
 The guides describe the product and its concepts, mostly through its
 screens. The exact format of each file is a JSON Schema for the release the
 runtime runs: \`frontera local schema <kind>\` prints it, for \`operating\`,
-\`agent\`, \`workflow\`, \`evals\` and \`dataset\` (\`frontera local schema\`
-lists which file each one is), \`frontera local start\` keeps them in
-\`.frontera/local/schemas/\`, and the documentation server's
-\`read_file_schema\` tool returns them too. Read the schema before you write
+\`agent\`, \`bindings\`, \`workflow\`, \`evals\`, \`workflow-tests\`,
+\`dataset\`, \`theme\` and each Blueprint file (\`blueprint-object-type\`,
+\`blueprint-action\`, \`blueprint-object-set\`…;
+\`frontera local schema\` lists which file each one is). Where a file names
+another resource the schema takes its reference (\`function/<slug>\`,
+\`model/<slug>\` for an \`llm\` step), which \`local dev\` resolves to the
+runtime's id; \`frontera local start\` keeps them in
+\`.frontera/local/schemas/\`, and the MCP server's \`read_file_schema\`
+tool returns them too. Read the schema before you write
 a file, rather than guessing a field or reading Frontera's source, and do
 not add a \`$schema\` key to a file: most files refuse a key they do not
 know. A schema checks a file's shape; what the file refers to (the action a
@@ -300,22 +479,114 @@ the person's to set (\`frontera local key-set\`, \`provider-add\`,
 \`model-add\`, or Forge's Models page): ask them rather than doing it, and
 never handle a key yourself.
 
-Change the files, not the runtime: \`local dev\` keeps the two in step, and
-a change made only on the runtime is lost on the next reset. A changed CSV
-must keep its dataset's columns.
+Change the files, not the runtime: \`local dev\` keeps the two in step (delete
+an Agent's folder or a workflow's file and it is archived on the runtime, a
+Function's and it is switched off; \`status\` lists what the runtime holds
+with no file), and a change made only on the runtime is lost on the next
+reset. A changed CSV must keep its dataset's columns.
 `
 
 /**
- * Frontera's documentation for the coding agents working in the project:
- * a stdio MCP server the harness launches. It reads the copy `local start`
- * keeps, so there is no key and nothing secret in this file.
+ * The Frontera MCP server for the coding agents working in the project, one
+ * entry per harness: a stdio server the harness launches. It reads the
+ * runtime's state file for everything else, so there is no key and nothing
+ * secret in these files.
+ */
+export const MCP_ENTRY = { command: 'frontera', args: ['mcp'] } as const
+const MCP_JSON = `${JSON.stringify({ mcpServers: { frontera: MCP_ENTRY } }, null, 2)}\n`
+const OPENCODE_JSON = `${JSON.stringify({ $schema: 'https://opencode.ai/config.json', mcp: { frontera: { type: 'local', command: [MCP_ENTRY.command, ...MCP_ENTRY.args], enabled: true } } }, null, 2)}\n`
+/**
+ * The project's own Claude Code settings: they approve the project's
+ * `frontera` server from `.mcp.json` (`enabledMcpjsonServers`), so a new
+ * session asks only once, to trust the folder; Claude Code applies a
+ * project's approvals after that. Nothing is written to the person's own
+ * settings (`~/.claude.json`, `~/.claude/settings.json`).
  */
-const DOCS_MCP = `${JSON.stringify({ mcpServers: { 'frontera-docs': { command: 'frontera', args: ['local', 'docs-mcp'] } } }, null, 2)}\n`
+export const CLAUDE_SETTINGS_JSON = `${JSON.stringify({ enabledMcpjsonServers: ['frontera'] }, null, 2)}\n`
+/** Codex reads a project's own `.codex/config.toml` once the person trusts the project. */
+export const CODEX_MCP_TOML = `# The Frontera MCP server for this project (\`frontera mcp\`).\n[mcp_servers.frontera]\ncommand = "frontera"\nargs = ["mcp"]\n`
+
+/** The command projects registered before \`frontera mcp\` (the documentation server alone). */
+const OLD_MCP_ARGS = ['local', 'docs-mcp']
+
+const sameArgs = (a: unknown, b: readonly string[]) => Array.isArray(a) && a.length === b.length && a.every((x, i) => x === b[i])
+
+/**
+ * Point the project's coding-agent configs that still launch \`frontera local
+ * docs-mcp\` at \`frontera mcp\` instead, leaving every other server and
+ * setting in them as it is. Returns the files changed; never throws.
+ */
+export function migrateMcpConfigs(root: string): string[] {
+  const changed: string[] = []
+  const edit = (rel: string, change: (text: string) => string | null) => {
+    const full = join(root, rel)
+    if (!existsSync(full)) return
+    try {
+      const before = readFileSync(full, 'utf8')
+      const after = change(before)
+      if (after !== null && after !== before) {
+        writeFileSync(full, after)
+        changed.push(rel)
+      }
+    } catch {
+      // A config that is not ours to read is left alone.
+    }
+  }
+  for (const rel of ['.mcp.json', '.cursor/mcp.json']) {
+    edit(rel, (text) => {
+      const doc = JSON.parse(text) as { mcpServers?: Record<string, { command?: string; args?: unknown }> }
+      let moved = false
+      for (const server of Object.values(doc.mcpServers ?? {})) {
+        if (server?.command === 'frontera' && sameArgs(server.args, OLD_MCP_ARGS)) {
+          server.args = [...MCP_ENTRY.args]
+          moved = true
+        }
+      }
+      return moved ? `${JSON.stringify(doc, null, 2)}\n` : null
+    })
+  }
+  edit('opencode.json', (text) => {
+    const doc = JSON.parse(text) as { mcp?: Record<string, { command?: unknown }> }
+    let moved = false
+    for (const server of Object.values(doc.mcp ?? {})) {
+      if (sameArgs(server?.command, ['frontera', ...OLD_MCP_ARGS])) {
+        server.command = [MCP_ENTRY.command, ...MCP_ENTRY.args]
+        moved = true
+      }
+    }
+    return moved ? `${JSON.stringify(doc, null, 2)}\n` : null
+  })
+  edit('.codex/config.toml', (text) => text.replace(/^(args\s*=\s*)\[\s*"local"\s*,\s*"docs-mcp"\s*\]/m, '$1["mcp"]'))
+  return changed
+}
 
 const GITIGNORE = `node_modules/
 .env
 `
 
+/**
+ * The project's `bunfig.toml`: `bun test` at its root runs the Functions'
+ * unit tests and nothing else. Without it Bun sweeps every folder, Apps'
+ * tests included, which need the App's own packages and run in its folder.
+ */
+export const PROJECT_BUNFIG = `# \`bun test\` here runs the Functions' unit tests (functions/), offline.
+# An App's own tests run in its folder: \`bun run test\` in apps/<name>/.
+[test]
+root = "./functions"
+`
+
+/**
+ * Write the project's `bunfig.toml` when it has none (an older CLI's
+ * project, or a pull): true when it wrote one. One that is there is the
+ * person's, never changed.
+ */
+export function ensureProjectBunfig(root: string): boolean {
+  const path = join(root, 'bunfig.toml')
+  if (existsSync(path) || !existsSync(join(root, 'package.json'))) return false
+  writeFileSync(path, PROJECT_BUNFIG)
+  return true
+}
+
 /** `samples: false` leaves out the example Agent, workflow, Function and object type: a project started from a workspace gets the workspace's own. */
 export function solutionScaffoldFiles(name: string, opts: { agentModel?: string; samples?: boolean } = {}): Record<string, string> {
   const sdk = vendored.files as Record<string, string>
@@ -325,18 +596,27 @@ export function solutionScaffoldFiles(name: string, opts: { agentModel?: string;
     if (content === undefined) throw new Error(`vendored SDK is missing ${rel} — run \`bun run sync:sdk\` in packages/frontera-cli`)
     out[`vendor/${rel}`] = content
   }
+  // What the CLI wrote there, by hash: `local dev` keeps the copies nobody edited current (`local-vendored-sdk.ts`).
+  out[SDK_MANIFEST] = sdkManifestText(Object.fromEntries(Object.entries(out).filter(([rel]) => rel.startsWith('vendor/'))))
 
   out['frontera.yaml'] = `# A Frontera project. \`frontera local dev\` applies agents/, workflows/, functions/ and blueprint/.\nname: ${name}\n`
   out['README.md'] = README(name)
   out['AGENTS.md'] = SOLUTION_AGENTS_MD
   out['.gitignore'] = GITIGNORE
-  out['.mcp.json'] = DOCS_MCP
-  out['.cursor/mcp.json'] = DOCS_MCP
+  out['.mcp.json'] = MCP_JSON
+  out['.claude/settings.json'] = CLAUDE_SETTINGS_JSON
+  out['.cursor/mcp.json'] = MCP_JSON
+  out['opencode.json'] = OPENCODE_JSON
+  out['.codex/config.toml'] = CODEX_MCP_TOML
+  out['fixtures/README.md'] = FIXTURES_README
+  out['bunfig.toml'] = PROJECT_BUNFIG
   if (opts.samples !== false) {
     out['agents/assistant/agent.json'] = AGENT(name, opts.agentModel)
     out['agents/assistant/operating.json'] = OPERATING
+    out['agents/assistant/bindings.json'] = BINDINGS
     out['agents/assistant/evals/regression.yaml'] = EVALS
     out['workflows/hello.yaml'] = WORKFLOW
+    out['workflows/tests/hello.yaml'] = WORKFLOW_TESTS
     out['functions/word-count.ts'] = FUNCTION
     out['functions/word-count.test.ts'] = FUNCTION_TEST
     out['datasets/tickets.json'] = DATASET
@@ -392,8 +672,11 @@ export function solutionScaffoldFiles(name: string, opts: { agentModel?: string;
 export function writeSolutionScaffold(target: string, name: string, force: boolean, opts: { agentModel?: string; samples?: boolean } = {}): { written: string[]; skipped: string[] } {
   const written: string[] = []
   const skipped: string[] = []
+  // A vendored SDK an older CLI wrote has no manifest, and one written now would vouch for files it didn't write.
+  const olderSdk = !force && existsSync(join(target, 'vendor', 'frontera')) && !existsSync(join(target, SDK_MANIFEST))
   for (const [rel, content] of Object.entries(solutionScaffoldFiles(name, opts))) {
     const full = join(target, rel)
+    if (rel === SDK_MANIFEST && olderSdk) continue
     const generic = rel === 'AGENTS.md' && existsSync(full) && readFileSync(full, 'utf8') === AGENTS_MD
     if (existsSync(full) && !force && !generic) {
       skipped.push(rel)