@frontera-sdk/cli 1.52.38 → 1.52.40

package/src/flag-help.ts

@@ -40,7 +40,7 @@ export const FLAG_HELP: Readonly<Record<string, string>> = {
   remove: 'comma-separated property API names to drop from the current set',
   // Blueprint authoring (organization API key). `notes` is described further down
   // — this map is keyed by flag name across every command, so one entry serves both.
-  label: 'release label recorded on the published or rolled-back release',
+  label: 'release label recorded on the published or rolled-back release; for an App deployment, unique per App',
   report: 'validation report id to act on — the release publishes against it, the review is pinned to it',
   instruction: 'migration instruction applied to every change a rollback discards',
   // Global
@@ -71,7 +71,7 @@ export const FLAG_HELP: Readonly<Record<string, string>> = {
 
   // Writes
   file: 'read the document from this path, or `-` for stdin',
-  force: 'proceed past a refusal — overwrite existing files, or a dirty tree',
+  force: 'proceed past a refusal — overwrite existing files, a dirty tree, an App\'s or a change request\'s required checks (with --reason), a running local runtime',
   'expect-revision':
     'refuse the write unless the resource is still at this revision; exit 3 if it moved',
   notes: 'note recorded against the published version',
@@ -91,6 +91,19 @@ export const FLAG_HELP: Readonly<Record<string, string>> = {
   registry: 'the registry host and namespace image mode pulls the platform images from, such as registry.example.com/frontera',
   reapply: 'apply every file again, including those unchanged since they were last applied',
   stop: 'stop the local runtime when the check ends',
+  'keep-state': 'keep what the Agent and workflow tests wrote, instead of restoring the database as the apply left it',
+  exact: 'restore: put the baseline’s workspace secrets back too, instead of keeping the ones set now',
+  workflow: 'run only this workflow’s tests (workflows/tests/<slug>.yaml)',
+  skip: 'comma-separated check steps to leave out: typecheck, unit, apps, agents, workflows',
+  'object-type': 'the object type a new action acts on; its primary key names the key input',
+  body: 'the request body to send: a file, or - for standard input',
+  path: 'which webhook of the workflow, by its trigger path; needed when it has several',
+  method: 'the HTTP method to send; POST when the webhook takes it',
+  header: 'one header the sender would send, `Name: value` (the webhook’s own auth)',
+  query: 'a query string to send with the delivery, such as source=portal&urgent=1',
+  'fail-fast': 'stop the check at the first step that fails, instead of running and reporting every step',
+  strict: 'fail on inherited failures too: items and files unchanged since the pull, which otherwise are listed and do not fail the check',
+  concurrency: 'how many Agent test cases run at once (1–16, default 2); cases that change records for real still run one at a time. Lower it when the model provider refuses for requests in flight',
 
   // Apps
   framework: 'App scaffold to create: next (default) or react (legacy Vite)',
@@ -104,7 +117,7 @@ export const FLAG_HELP: Readonly<Record<string, string>> = {
   // choose which version to RUN, one chooses which to publish. The old text
   // described only the third, so `workflow run --help` and `function run
   // --help` both advertised package.json.
-  version: 'the version to act on — the one to run, or on a deploy the one to publish',
+  version: 'the version to act on — the one to run (`workflow run` also takes draft: the newest version not retired), or on a deploy the one to publish',
   input: "JSON object of the declared inputs — inline ('{\"key\": 1}') or @file.json",
   // The primary key alone. A subject-bound workflow takes exactly one, so the
   // flag spends no characters on the `{"pk": …}` the route models it as.
@@ -112,8 +125,11 @@ export const FLAG_HELP: Readonly<Record<string, string>> = {
   // Action requests.
   'subject-version': 'record version of --subject the request expects, so a stale read is refused',
   'idempotency-key': 'reuse a key to retry a submit and get the same request back; generated if omitted',
-  'no-promote': 'publish the version without moving the live pointer',
-  'skip-build-check': 'deploy even when the build output is older than the source',
+  'no-promote': 'publish the version without moving the live pointer; with app deploy --prod, stage it for production',
+  build: 'run bun run build first, so the deployment is built from the source as it is now',
+  'skip-build-check': 'deploy even when the build output is older than the source, and skip bun run check',
+  prod: 'go live once the required checks pass (a deploy is otherwise a preview)',
+  undo: 'undo the rollback: production serves what it did before, and is unpinned',
   'no-wait': 'return as soon as the run is queued instead of waiting for it to finish',
   // Named for what it RUNS, not where it runs: an author reads this to decide
   // between their working copy and what is deployed.
@@ -129,8 +145,8 @@ export const FLAG_HELP: Readonly<Record<string, string>> = {
 
   // Blueprint scaffolding
   template:
-    'starting rule for `blueprint new semantic-type`: non-negative, percentage, status-enum '
-    + 'or code-length (default)',
+    'starting shape: a semantic type\'s rule (non-negative, percentage, status-enum, '
+    + 'code-length, the default), or an action\'s (edit, the default, or create)',
 
   // Packs
   'remove-apps': 'also uninstall the apps the pack installed',
@@ -146,8 +162,9 @@ export const FLAG_HELP: Readonly<Record<string, string>> = {
   // Blueprint reads
   select: 'comma-separated property API names to return (default: whatever the service returns)',
   where:
-    'filter as <property>:<value>, <property>:<op>:<value>, or a JSON where-node for anything '
-    + 'with and/or in it',
+    'filter as <property>:<value>, <property>:<op>:<value>, <property>:in:<a>,<b> (also notIn and between; '
+    + 'a backslash before a comma keeps it in a value, or give a JSON array), or a JSON where-node for an '
+    + 'or/not; repeat it for conditions that must all hold',
   order: 'sort as <property>:asc or <property>:desc, comma-separated for more than one',
   // No number here on purpose. This map is keyed by flag NAME across every
   // command, and the three surfaces that take `--limit` cap a page at 1000,
@@ -155,6 +172,22 @@ export const FLAG_HELP: Readonly<Record<string, string>> = {
   // command's own refusal names its real ceiling.
   limit: 'maximum rows to return in one page; each surface has its own ceiling',
   'page-token': 'cursor from the previous response’s nextPageToken; omit for the first page',
+  as:
+    'on the local runtime only: act as a local persona (`submitter`, or an approval step such as '
+    + '`dispatch_lead`), as `frontera local status` lists them; refused anywhere else',
+  // A metric's query (`blueprint metric query`).
+  measure: 'comma-separated measures of the metric to return; all of them when absent',
+  'group-by': 'comma-separated dimensions of the metric to break the numbers down by',
+  grain: 'a series by hour, day, week, month, quarter or year over the metric’s timeseries dimension (added to the group-by)',
+  range: 'a time window as an ISO-8601 duration (P7D, PT12H, P3M), back from the newest value of the metric’s timeseries in the data, not from now',
+  start: 'the window’s start, an ISO date or timestamp (inclusive; a date is its midnight UTC)',
+  end: 'the window’s end, an ISO date or timestamp (exclusive; a date is its midnight UTC)',
+  compare: 'add the window before the one given: <measure>_prev, <measure>_delta and <measure>_pct',
+  only: 'live: only live runs; test: only test runs (from `local test`, Studio or a draft run)',
+  npm: 'with use-local: switch the App back to the published @frontera-sdk packages from npm, deleting vendor/frontera-sdk/ and any SDK copy under src/frontera/ (the output lists each file)',
+  'object-set':
+    'read a saved object set’s rows: its name, its reference (objectSet/<ref>) or its id, '
+    + 'from `frontera blueprint object-sets`',
   // Named for the field the response carries, which differs by surface —
   // Blueprint answers `nextPageToken`, data-integration answers `nextCursor`.
   // Matching each flag to its own response beats one name that is wrong half
@@ -184,8 +217,9 @@ export const FLAG_HELP: Readonly<Record<string, string>> = {
   // permissive and 0 matches nothing at all. Described the wrong way round
   // first, which made `--threshold 0` look like "return everything".
   threshold:
-    'maximum cosine distance a chunk may have; higher is more permissive (default 0.9). '
-    + 'Not the similarity score shown in the output — 0 matches nothing',
+    'maximum cosine distance a chunk may have, 0 to 2; higher is more permissive (default: the '
+    + 'base’s own match threshold, as an Agent’s retrieval uses it). Not the score shown in the '
+    + 'output: a score is 1 − distance / 2, so 0.5 keeps scores above 0.75',
   strategy:
     'text extraction to use per file: auto (default), text, or ocr; ocr needs an OCR engine on the base',
 
@@ -214,7 +248,7 @@ export const FLAG_HELP: Readonly<Record<string, string>> = {
   'org-key': '`-` to read an organization key (sk-org-…) from stdin, after the workspace key; widens the Blueprint to the whole model',
   blueprint: 'workspace (the slice granted to the workspace, default) or organization (the whole model; needs an organization key)',
   relink: 'point a project already linked to another workspace at this one',
-  preview: 'list what a pull would bring, or a push would propose, file by file, and change nothing',
+  preview: 'local sync: list what a pull would bring, or a push would propose, file by file, and change nothing; app deploy: make a preview deployment (the default), said explicitly as a pipeline must',
   kinds: 'comma-separated: blueprint, skills, functions, plugins, knowledge, workflows, agents, evaluations',
   drafts: 'comma-separated items (agent/<slug>, workflow/<slug>, function/<slug>, blueprint) to read as their draft instead of the live version; the Blueprint’s draft takes an organization key',
   'all-changed': 'pull every item the workspace changed since the last pull, and every clean merge; never one that conflicts or replaces local edits',
@@ -230,14 +264,25 @@ export const FLAG_HELP: Readonly<Record<string, string>> = {
   edited: 'take the files as you edited them; the workspace’s copies beside them go',
   title: 'the change request’s title; a push that opens a new one needs it',
   migration: 'for a Blueprint change that is not additive: what happens to existing records',
-  documents: 'comma-separated knowledge bases whose documents a pull brings, or a push proposes (`*` for every one); without it they stay as they are',
+  documents: 'comma-separated knowledge bases whose documents a pull brings (a base pulled now brings its own anyway), or a push proposes (`*` for every one)',
+  'no-documents': 'pull knowledge bases without their documents (by default a pulled base brings them)',
+  'no-app-code': 'pull Custom Apps without their code (by default a pulled App brings its deployed version into apps/<slug>/, unless that folder is there)',
+  release: 'Custom Apps the change request releases, comma-separated slug=deployment (the newest deployment when only the slug is given); Apply promotes each one last',
+  evals: 'run each Agent’s gated cases (gate: true) against the local runtime and attach the results, compared with its last applied run',
+  renders: 'attach each released App’s last render (its screenshot and console summary)',
+  screenshots: 'attach the newest screenshots a Forge session saved (its id; this session’s when run inside Forge)',
+  trace: 'attach a trace link (an http(s) address) to the change request',
   lessons: 'bring each Agent’s reviewed rules from customer feedback into agents/<slug>/lessons.yaml (never the feedback itself); off by default',
   conflicts: 'the conflicts the picks were chosen against, as `diff --json` names them; refused if they moved',
   'from-workspace': 'start the project from a platform workspace instead of the examples',
   'no-sample-data': 'do not generate sample rows for the pulled Blueprint',
+  'keep-sample-data': 'leave the sample datasets as they are; by default they are made again (same seed, rows and day) after a pull that brings Blueprint items, or when an older generator made them',
+  'remake-sample-data': 'make the sample datasets again with the newest sample rules (same seed, rows and day), even the ones a pull wrote, which local dev otherwise keeps as pulled',
   synthetic: 'generate sample rows for the Blueprint: values fit each property, links stay consistent',
   rows: 'rows per object type (default 200; types others link to get half)',
-  seed: 'the same seed writes the same rows (default 7)',
+  seed: 'the same seed writes the same rows on the same day; with --today, on any day (default 7)',
+  today: 'the day sample due dates are spread around, YYYY-MM-DD (default: today, UTC)',
+  region: 'where sample geopoints fall: a country code (ID, US, GB…) or `<lat>,<lon>[,<radius km>]` (default: the project’s `locale` in frontera.yaml, else the workspace’s timezone, else US)',
 }
 
 /**
@@ -259,6 +304,8 @@ const PLACEHOLDER: Readonly<Record<string, string>> = {
   // take an integer version number, and this map is keyed by flag name for all
   // three. `<version>` is the only placeholder true of every consumer.
   version: 'version',
+  body: 'file',
+  header: 'name: value',
   framework: 'next|react',
   port: 'number',
   origin: 'url',
@@ -279,6 +326,15 @@ const PLACEHOLDER: Readonly<Record<string, string>> = {
   order: 'prop:asc',
   limit: 'n',
   'page-token': 'cursor',
+  'object-set': 'name|ref|id',
+  measure: 'a,b',
+  'group-by': 'a,b',
+  grain: 'hour|day|week|month|quarter|year',
+  range: 'P7D',
+  start: 'iso',
+  end: 'iso',
+  only: 'live|test',
+  as: 'persona',
   cursor: 'cursor',
   lifecycle: 'state',
   actions: 'allow_all|read_only|custom',
@@ -288,7 +344,7 @@ const PLACEHOLDER: Readonly<Record<string, string>> = {
   markings: 'a,b',
   'max-distance': '0-2',
   permissions: 'read,write',
-  template: 'non-negative|percentage|status-enum|code-length',
+  template: 'non-negative|percentage|status-enum|code-length|edit|create',
   platform: 'url',
   'workspace-key': '-',
   'org-key': '-',
@@ -299,6 +355,9 @@ const PLACEHOLDER: Readonly<Record<string, string>> = {
   'delete-here': 'kind/name,…',
   'keep-local': 'kind/name,…',
   documents: 'name,…',
+  release: 'slug=deployment,…',
+  screenshots: 'session',
+  trace: 'url',
   keep: 'workspace|mine',
   picks: 'n=side,…',
   rows: 'n',
@@ -315,6 +374,7 @@ export function flagUsage(name: string, type: 'string' | 'boolean', alias?: stri
   return `${short}--${name} <${PLACEHOLDER[name] ?? 'value'}>`
 }
 
-export function describeFlag(name: string): string {
-  return FLAG_HELP[name] ?? ''
+/** A command's own wording for a flag (`meta.flagHelp`) wins: the one place a name means something else there. */
+export function describeFlag(name: string, own?: Readonly<Record<string, string>>): string {
+  return own?.[name] ?? FLAG_HELP[name] ?? ''
 }

package/src/forge/touches.ts

@@ -44,29 +44,31 @@ export const FORGE_ARTIFACT_KINDS = [
  * `search`, `runs`, `bindings` — is a read and is deliberately absent.
  */
 export const TOUCHING_VERBS: Record<ForgeArtifactKind, readonly string[]> = {
-  agent: ['apply', 'create', 'publish', 'revert', 'discard', 'skill-attach', 'skill-detach'],
+  agent: ['apply', 'create', 'publish', 'revert', 'discard', 'skill-attach', 'skill-detach', 'archive', 'restore'],
   automation: ['deploy', 'promote', 'enable', 'disable', 'init', 'bind', 'unbind', 'run'],
-  app: ['deploy', 'promote', 'save', 'add'],
+  app: ['deploy', 'promote', 'rollback', 'unpin', 'save', 'add'],
   blueprint: ['apply', 'publish', 'create', 'update', 'delete', 'rename', 'rollback', 'bind', 'grant', 'adopt', 'editable'],
   action: ['prepare', 'deploy', 'grant', 'review'],
   skill: ['push', 'delete'],
   source: ['create', 'update', 'revise', 'disable'],
-  dataset: ['create', 'upload', 'test-source'],
+  // `revise` cuts the dataset's next revision from its CSV.
+  dataset: ['create', 'upload', 'revise', 'test-source'],
   knowledge: ['create', 'attach', 'detach', 'upload', 'retry', 'delete'],
+  // `webhook-test` starts a run on the draft through its webhook, as `run` does.
   // `get`, `lineage`, `list`, `runs` and `validate` are reads — `validate` is
   // `push --dry-run` and writes nothing. `cancel` is deliberately absent: it
   // stops one in-flight run and leaves the definition, the versions and the
   // live pointer exactly as they were, and its positional is a RUN id, not a
   // slug, so it could not name the workflow page anyway. Same call
   // `automation` makes, which lists `run` and not `cancel`.
-  workflow: ['push', 'promote', 'run'],
+  workflow: ['push', 'promote', 'run', 'webhook-test', 'archive', 'restore'],
 }
 
 /** Verbs after which the artifact is LIVE, not merely changed. */
 const LIVE_VERBS: Partial<Record<ForgeArtifactKind, readonly string[]>> = {
   agent: ['publish'],
   automation: ['promote', 'enable'],
-  app: ['promote'],
+  app: ['promote', 'rollback'],
   blueprint: ['publish'],
   workflow: ['promote'],
 }
@@ -97,9 +99,9 @@ const FILE_POSITIONAL_VERBS: Partial<Record<ForgeArtifactKind, readonly string[]
   automation: ['deploy', 'init'],
   skill: ['push'],
   blueprint: ['create'],
-  // `app deploy` names nothing (the folder is the app); `app promote` names
-  // a VERSION. The app itself is the project's, which the pane knows.
-  app: ['deploy', 'promote', 'save', 'add'],
+  // `app deploy` names nothing (the folder is the app); `app promote` and
+  // `app rollback` name a DEPLOYMENT. The app itself is the project's, which the pane knows.
+  app: ['deploy', 'promote', 'rollback', 'unpin', 'save', 'add'],
 }
 
 /**
@@ -122,7 +124,7 @@ export const BOOLEAN_FLAGS = new Set([
   'accept-contract-change', 'accept-orphaned-knowledge', 'dry-run', 'end-user', 'no-activate',
   'no-components', 'no-git', 'no-input', 'no-install', 'no-open', 'no-promote', 'no-wait',
   'remove-apps', 'token-stdin', 'prune', 'dev', 'revoke', 'draft', 'check',
-  'skip-build-check',
+  'skip-build-check', 'prod', 'preview', 'undo', 'build',
 ])
 
 /**
@@ -401,9 +403,10 @@ export function parseFronteraCommands(line: string): ParsedFronteraCommand[] {
         : (rest[0] ?? null)
     const live =
       (LIVE_VERBS[kind] ?? []).includes(verb)
-      // `app deploy` and `function deploy` build and promote in one act
-      // unless told not to.
-      || ((kind === 'app' || kind === 'automation') && verb === 'deploy' && !flags.has('no-promote'))
+      // `function deploy` builds and promotes in one act unless told not to;
+      // `app deploy` makes a preview unless `--prod` (and `--prod --no-promote` stages it).
+      || (kind === 'automation' && verb === 'deploy' && !flags.has('no-promote'))
+      || (kind === 'app' && verb === 'deploy' && flags.has('prod') && !flags.has('no-promote'))
     out.push({ kind, verb, ref, live })
   }
   return out

package/src/function-outside-imports.ts

@@ -0,0 +1,89 @@
+import { existsSync, lstatSync, readFileSync } from 'node:fs'
+import { dirname, join, posix, relative, resolve, sep } from 'node:path'
+
+import { isExcluded, type SourceFile } from './packaging'
+
+/**
+ * The files a Function imports from outside its own project folder.
+ *
+ * A Function deployed from its folder (`functions/<slug>/`) may import a
+ * helper beside it (`../../shared/eligibility` from `src/index.ts`). The
+ * bundle holds that code, but its source archive is the folder alone, so a
+ * pull would bring a Function that no longer builds. Each such file travels
+ * in the archive under `frontera-imports/`, by its path from the folder with
+ * every `..` as `__up__` (`frontera-imports/__up__/shared/eligibility.ts`),
+ * and a pull writes it back where the import finds it.
+ *
+ * Only files the code imports, by relative path, and never above the
+ * solution (the nearest folder with `frontera.yaml`, else two folders above
+ * the Function's): the bundle already carries their code.
+ */
+
+export const OUTSIDE_DIR = 'frontera-imports'
+const UP = '__up__'
+
+const RELATIVE_IMPORT = /(?:from|import)\s*\(?\s*['"](\.{1,2}\/[^'"]+)['"]/g
+const CODE = /\.(ts|tsx|mts|cts|js|mjs|cjs|json)$/
+const EXTENSIONS = ['', '.ts', '.tsx', '.mts', '.js', '.mjs', '.json', '/index.ts', '/index.js']
+
+/** `../shared/x.ts` (from the folder) → `frontera-imports/__up__/shared/x.ts`. */
+export function outsidePath(fromFolder: string): string {
+  return `${OUTSIDE_DIR}/${posix.normalize(fromFolder).split('/').map((s) => (s === '..' ? UP : s)).join('/')}`
+}
+
+/** `frontera-imports/__up__/shared/x.ts` → `../shared/x.ts`; null for any other archive path. */
+export function fromOutsidePath(archivePath: string): string | null {
+  if (!archivePath.startsWith(`${OUTSIDE_DIR}/`)) return null
+  const rel = archivePath.slice(OUTSIDE_DIR.length + 1).split('/').map((s) => (s === UP ? '..' : s)).join('/')
+  return rel.startsWith('../') ? rel : null
+}
+
+function solutionRoot(projectRoot: string): string {
+  for (let dir = projectRoot; ; dir = dirname(dir)) {
+    if (existsSync(join(dir, 'frontera.yaml'))) return dir
+    if (dirname(dir) === dir) break
+  }
+  return dirname(dirname(projectRoot))
+}
+
+const within = (root: string, path: string) => path === root || path.startsWith(`${root}${sep}`)
+
+/**
+ * The files outside `projectRoot` that `entry` imports, followed through the
+ * files it imports inside it too, as archive entries under `frontera-imports/`.
+ */
+export function outsideImports(projectRoot: string, entry: string): SourceFile[] {
+  const root = resolve(projectRoot)
+  const bound = resolve(solutionRoot(root))
+  const seen = new Set<string>()
+  const out: SourceFile[] = []
+  const read = (path: string): string | null => {
+    try {
+      return existsSync(path) && lstatSync(path).isFile() ? readFileSync(path, 'utf8') : null
+    } catch {
+      return null
+    }
+  }
+  const visit = (file: string) => {
+    if (seen.has(file)) return
+    const text = read(file)
+    if (text === null) return
+    seen.add(file)
+    if (!within(root, file)) {
+      const rel = relative(root, file).split(sep).join('/')
+      if (CODE.test(file) && !isExcluded(rel.replace(/^(\.\.\/)+/, ''))) out.push({ rel: outsidePath(rel), bytes: new TextEncoder().encode(text) })
+    }
+    for (const m of text.matchAll(RELATIVE_IMPORT)) {
+      const base = resolve(dirname(file), m[1]!)
+      if (!within(bound, base) || base.split(sep).includes('node_modules')) continue
+      const found = EXTENSIONS.map((ext) => `${base}${ext}`).find((c) => read(c) !== null)
+      if (!found) continue
+      visit(found)
+      // A JavaScript file's types beside it travel with it (a module a pull recovered from a
+      // deployed bundle is a `.js` typed by its `.d.ts`), so the next pull still typechecks.
+      if (found.endsWith('.js')) visit(`${found.slice(0, -'.js'.length)}.d.ts`)
+    }
+  }
+  visit(resolve(entry))
+  return out
+}

package/src/harness.ts

@@ -25,6 +25,16 @@ description: Use when reading or changing anything on the Frontera platform from
 never out of date — read it instead of guessing, and instead of trusting this
 file for syntax.
 
+## In a project with the Frontera MCP server
+
+A project made by \`frontera local\` registers the \`frontera\` MCP server
+(\`.mcp.json\`). When its tools are offered (\`mcp__frontera__*\` in Claude
+Code), use them for the local loop instead of the shell: \`status\`,
+\`apply\`, \`test_run\`, \`logs\`, \`read_file_schema\` and the documentation
+tools. The person approves the server once, where every shell command can
+ask again. Run \`frontera local …\` only when the tools aren't offered, or
+for a step that has no tool (\`frontera local start\`, \`frontera local check\`).
+
 ## Preflight: know which customer you are about to change
 
 \`\`\`bash
@@ -63,7 +73,10 @@ Two fields decide whether a call can work at all:
   key: set \`FRONTERA_TOKEN\` to the session token and \`FRONTERA_API_URL\` (or
   pass \`--api-url\`). The CLI refuses an \`sk-ws-\`/\`sk-org-\` key on those
   before sending anything; \`frontera login\` stores keys only, so it cannot
-  supply the session.
+  supply the session. On a project's local runtime, never fetch a person's
+  session: \`--as <persona>\` runs \`action available\`, \`submit\`,
+  \`approve\` and \`reject\` as a local persona (\`--as submitter\`,
+  \`--as <approver>\`; \`frontera local status\` lists them).
 - \`available\` — \`false\` means the verb is named but unbuilt, and
   \`unavailableReason\` says why. Pick another route rather than retrying.
 
@@ -126,7 +139,7 @@ Pass \`--json\` for machine-readable output. The contract:
 | 0 | success | continue |
 | 1 | transient or remote failure | retry, then report |
 | 2 | usage, input, or profile selection | fix the command |
-| 3 | conflict — someone changed it first | re-fetch, reapply, retry |
+| 3 | conflict or refusal — someone changed it first, or the record's state refuses it | re-read, change the input or the record, then send it again; never retry it unchanged |
 | 4 | auth or permission | different credential, or ask an admin |
 
 Errors carry a \`hint\` naming the next command. Read it.
@@ -192,8 +205,9 @@ frontera blueprint instance <apiName> <pk>
   app or agent sees at runtime. Anything absent here is absent for them too.
 
 \`--where\` takes \`<property>:<value>\` or \`<property>:<op>:<value>\` for one
-condition; pass a JSON where-node for anything with and/or in it, or
-\`--file\` a whole query document for unions and link traversals.
+condition, and \`<property>:in:<a>,<b>\` (also \`notIn\`, \`between\`) for a list;
+repeat it for conditions that must all hold. Pass a JSON where-node for an
+or/not, or \`--file\` a whole query document for unions and link traversals.
 
 ## Configuring an agent
 
@@ -239,14 +253,13 @@ means someone else changed it: re-read and retry, never force.
 ## Building an app
 
 \`\`\`bash
-frontera app init <name>        # scaffold — installs with public npm only
-bun install
+frontera app init <name>        # Next.js static export — installs with public npm only
+cd <name>
 frontera blueprint list         # what data this workspace actually has
-frontera app add <component>    # registry source into the project
-bun run typecheck               # vite build does NOT type-check
-bun run build                   # the deploy gate — must succeed
-frontera app deploy --no-promote
-frontera app promote <version>
+frontera app dev                # the App against real data, with a short-lived token
+bun run check                   # typecheck, tests and build: the gate
+frontera app deploy --build     # build, then a preview deployment with its link
+frontera app promote <deployment>
 \`\`\`
 
 Read \`frontera blueprint list\` and \`frontera blueprint get <apiName>\` before
@@ -254,19 +267,24 @@ designing against data. What they return is the slice this workspace is granted,
 which is exactly what the app will be able to query at runtime — so anything
 absent there will be absent for the app too.
 
-\`src/frontera/\` in a scaffolded project is the SDK, copied in as source so the
-project installs anywhere. Read it; never edit it, never rewrite an
-\`@frontera-sdk/…\` import to a relative path, never add \`@frontera-sdk/*\` to
-\`package.json\`. The project's own \`using-frontera-sdk\` skill has the detail.
-
-\`bun run dev\` serves the app, but opening \`/\` directly renders "This app runs
-inside Frontera" instead of mounting: the handshake refuses an unknown parent,
-which is correct, not a broken build.
-
-Open **\`/dev-host.html\`** instead. It frames the app and plays the host side of
-the bridge, so the app mounts and reads real data. That is the URL to screenshot
-or click through when verifying your work — a screenshot of \`/\` is a screenshot
-of the refusal panel.
+The SDK depends on how the App was made:
+
+- **Next.js (the default).** \`@frontera-sdk/core\` and \`@frontera-sdk/blueprint\`
+  (and \`@frontera-sdk/agents\` when used) are public npm packages in
+  \`package.json\`, kept at the release \`frontera app init\` wrote and updated
+  with the package manager. Never copy SDK source into \`src/\`. Open the App
+  through \`frontera app dev\`: it serves on \`http://127.0.0.1:<port>\` and
+  hands the page its session; never write that session into \`.env\`.
+- **Vite (legacy, \`--framework react\`).** \`src/frontera/\` is the SDK, copied
+  in as source. Read it; never edit it, never rewrite an \`@frontera-sdk/…\`
+  import to a relative path, and never add \`@frontera-sdk/*\` to
+  \`package.json\` there. \`frontera app sdk sync\` refreshes the copy. Opening
+  \`/\` renders "This app runs inside Frontera" (the handshake refuses an
+  unknown parent); open **\`/dev-host.html\`** instead, which frames the app and
+  plays the host side of the bridge.
+
+The project's own skills (\`.agents/skills/\`) have the detail for its
+framework.
 `
 
 export const AGENTS_MD = `# Frontera

package/src/heal.ts

@@ -45,9 +45,10 @@
  * CLI (`src/vendor/sdk-sources.json`).
  */
 
-import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs'
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs'
 import { dirname, join } from 'node:path'
 
+import { lockedSdkVersions, lockedSpec, recordLockedRanges } from './app-lock'
 import {
   APP_SDK_PACKAGES,
   LEGACY_SDK_ALIASES,
@@ -102,6 +103,10 @@ export function healProject(dir: string): HealResult {
 
   const name = typeof manifest.name === 'string' && manifest.name ? manifest.name : 'app'
   let manifestChanged = false
+  // What the App's own lockfile installed from the registry: the SDK its code was written against.
+  const locked = lockedSdkVersions(dir)
+  // The specs restored to a locked release, recorded in the lockfile too so the two agree.
+  const restored: Record<string, string> = {}
 
   // Packages a legacy tree needs declared under their CURRENT name as well, so
   // the vendored copy resolves the siblings it imports internally.
@@ -131,6 +136,18 @@ export function healProject(dir: string): HealResult {
       if (typeof spec !== 'string' || !UNRESOLVABLE.test(spec)) continue
 
       const pkg = currentSdkPackage(dep)
+      // The lockfile installed a published version: that is the SDK the code was checked against, so
+      // the App goes back to it rather than to a copy of another SDK (a pulled App's typecheck depends on it).
+      const lockedAt = pkg && dep === pkg ? locked.get(pkg) : undefined
+      if (lockedAt) {
+        deps[dep] = lockedSpec(lockedAt)
+        restored[dep] = deps[dep]
+        repairs.push(`restored ${dep} to ${deps[dep]}, the published release its bun.lock installed (was ${truncate(spec)})`)
+        manifestChanged = true
+        // A copy left under src/frontera/ would still win through tsconfig paths: it goes.
+        if (unvendorSdkPackage(dir, pkg!)) repairs.push(`removed the vendored copy in ${APP_SDK_PACKAGES[pkg!].dir} and its tsconfig path`)
+        continue
+      }
       if (pkg) {
         // Already pointing at the copy in this tree — that is the shape this
         // function produces, so re-pulling must not rewrite it back over
@@ -188,6 +205,10 @@ export function healProject(dir: string): HealResult {
     // still carry a stale copy, which is the ordinary state of every app
     // scaffolded before the SDK grew a module.
     if (vendorCurrent(dir, pkg) && (declares(manifest, specifier) || specifier === pkg)) continue
+    // Declared with a published range (`^1.43.10`): the package manager installs it, and the code was written against
+    // that release. Vendoring this CLI's copy over it swaps the SDK under the code (a pulled Next.js App's case).
+    const spec = manifest.dependencies?.[specifier] ?? manifest.devDependencies?.[specifier]
+    if (typeof spec === 'string' && !UNRESOLVABLE.test(spec)) continue
     vendorSdkPackage(dir, pkg)
     manifest.dependencies ??= {}
     manifest.dependencies[specifier] = `file:./${APP_SDK_PACKAGES[pkg].dir}`
@@ -225,6 +246,8 @@ export function healProject(dir: string): HealResult {
   }
 
   if (manifestChanged) writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`)
+  // The lockfile's record of what package.json asks for follows, so a frozen install takes the restored package.json.
+  if (recordLockedRanges(dir, restored)) repairs.push(`recorded ${Object.entries(restored).map(([d, s]) => `${d} ${s}`).join(' and ')} in the lockfile, which already installed that release`)
 
   // Point the editor at the vendored copy directly. Without this TypeScript
   // reaches it through the `file:` link instead and reports every diagnostic
@@ -246,6 +269,94 @@ export function healProject(dir: string): HealResult {
   return { repairs }
 }
 
+/**
+ * Take a vendored SDK package out of an App that installs the published one:
+ * its directory under src/frontera/ and the tsconfig `paths` entries that
+ * point at it (which would otherwise resolve imports to the copy instead of
+ * node_modules). True when anything was removed. A Vite App whose config
+ * aliases the copy keeps it: the alias is how it resolves the SDK.
+ */
+/** Does the App's Vite config alias the vendored copy (a scaffolded Vite App resolves the SDK that way)? */
+export function viteAliasesSdk(dir: string, pkg: AppSdkPackage): boolean {
+  const rel = APP_SDK_PACKAGES[pkg].dir
+  return ['vite.config.ts', 'vite.config.js', 'vite.config.mts'].some((f) => {
+    try {
+      return readFileSync(join(dir, f), 'utf8').includes(rel)
+    } catch {
+      return false
+    }
+  })
+}
+
+export function unvendorSdkPackage(dir: string, pkg: AppSdkPackage): boolean {
+  const removed = unvendorSdkPackageDetail(dir, pkg)
+  return !!removed && (removed.files.length > 0 || removed.tsconfigPaths.length > 0)
+}
+
+/** What taking a vendored SDK package out of an App removed: the copy's files, and the tsconfig paths to it. */
+export interface Unvendored {
+  /** The copy's directory, relative to the App (`src/frontera/blueprint`). */
+  dir: string
+  /** Each file deleted with it, relative to that directory, sorted. */
+  files: string[]
+  /** The directory above it, when it was left empty and deleted too (`src/frontera`). */
+  parentRemoved?: string
+  /** Each `compilerOptions.paths` key removed from tsconfig.json because it pointed at the copy. */
+  tsconfigPaths: string[]
+}
+
+/** `unvendorSdkPackage`, saying what it removed; null when the App's Vite config aliases the copy, so it is kept. */
+export function unvendorSdkPackageDetail(dir: string, pkg: AppSdkPackage): Unvendored | null {
+  const rel = APP_SDK_PACKAGES[pkg].dir
+  if (viteAliasesSdk(dir, pkg)) return null
+  const out: Unvendored = { dir: rel, files: [], tsconfigPaths: [] }
+  if (existsSync(join(dir, rel))) {
+    out.files = filesUnder(join(dir, rel))
+    rmSync(join(dir, rel), { recursive: true, force: true })
+    const parent = dirname(join(dir, rel))
+    try {
+      if (readdirSync(parent).length === 0) {
+        rmSync(parent, { recursive: true })
+        out.parentRemoved = dirname(rel)
+      }
+    } catch {
+      // Gone already.
+    }
+  }
+  const tsconfig = join(dir, 'tsconfig.json')
+  try {
+    const config = JSON.parse(readFileSync(tsconfig, 'utf8')) as { compilerOptions?: { paths?: Record<string, string[]> } }
+    const paths = config.compilerOptions?.paths
+    if (paths) {
+      for (const [key, targets] of Object.entries(paths)) {
+        if (Array.isArray(targets) && targets.some((t) => t.replace(/^\.\//, '').startsWith(`${rel}/`) || t.replace(/^\.\//, '') === rel)) {
+          delete paths[key]
+          out.tsconfigPaths.push(key)
+        }
+      }
+      if (out.tsconfigPaths.length) writeFileSync(tsconfig, `${JSON.stringify(config, null, 2)}\n`)
+    }
+  } catch {
+    // No tsconfig, or JSON with comments: left as it is.
+  }
+  return out
+}
+
+/** Every file under a directory, by its path relative to it, sorted. */
+function filesUnder(root: string): string[] {
+  const out: string[] = []
+  const walk = (at: string, rel: string) => {
+    for (const name of readdirSync(at).sort()) {
+      const path = join(at, name)
+      const r = rel ? `${rel}/${name}` : name
+      if (statSync(path).isDirectory()) walk(path, r)
+      else out.push(r)
+    }
+  }
+  walk(root, '')
+  return out
+}
+
 function isSdkPackage(dep: string): dep is AppSdkPackage {
   return (SDK_PACKAGE_NAMES as string[]).includes(dep)
 }