@frontera-sdk/cli 1.52.39 → 1.52.41

package/src/pack.ts

@@ -1,6 +1,7 @@
-import { collectSourceFiles, formatBytes } from './packaging'
+import { collectSourceFiles, formatBytes, type SourceFile } from './packaging'
 import { createTarGz } from './tar'
 import type { Output } from './output'
+import { tsconfigAsKept } from './local/local-app-sdk-paths'
 
 /**
  * Package a directory for upload, reporting its size.
@@ -10,8 +11,12 @@ import type { Output } from './output'
  * bill — but it moves to stderr via `note`. It is commentary about the work,
  * not the work's result, and mixing it into stdout broke piping.
  */
-export function packDirectory(dir: string, output: Output, label: string) {
-  const files = collectSourceFiles(dir)
+export function packDirectory(dir: string, output: Output, label: string, extra: SourceFile[] = []) {
+  // `extra`: files kept beside the directory's own (a Function's imports from outside its folder).
+  // A tsconfig.json whose SDK-copy paths a run still going (the App's dev server) set aside is packaged as it is the App's.
+  const kept = tsconfigAsKept(dir)
+  const own = collectSourceFiles(dir).map((f) => (kept && f.rel === 'tsconfig.json' ? { rel: f.rel, bytes: new Uint8Array(kept) } : f))
+  const files = [...own, ...extra]
   const totalBytes = files.reduce((n, f) => n + f.bytes.byteLength, 0)
   output.note(`  ${label} ${files.length} files, ${formatBytes(totalBytes)}`)
   return { tgz: createTarGz(files), fileCount: files.length, totalBytes }

package/src/packaging.ts

@@ -61,7 +61,7 @@ export function isExcluded(rel: string): boolean {
  * IGNORED for anything in the hard set, so a permissive `.gitignore` can never
  * widen packaging past §6.2.
  */
-function gitignoreMatcher(root: string): (rel: string) => boolean {
+export function gitignoreMatcher(root: string): (rel: string) => boolean {
   const path = join(root, '.gitignore')
   if (!existsSync(path)) return () => false
 

package/src/project-bootstrap.ts

@@ -1,7 +1,10 @@
-import { existsSync, readdirSync, rmSync } from 'node:fs'
+import { existsSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
 import { dirname, join } from 'node:path'
 
 import { UsageError } from './errors'
+import { copyInstallLine, repullRefFor, type SdkShadow } from './local/local-app-code'
+import { installFromLock, lockInstallLine } from './local/local-app-lock-install'
+import { copyInstallShadows, lockMismatchAdvice, vendoredShadows } from './local/local-app-sdk'
 
 /**
  * The steps between "files written" and "a project someone can work in".
@@ -74,6 +77,53 @@ export interface InstallResult {
   installed: boolean
   /** The last line bun printed — its own package count and timing. */
   summary: string
+  /** Installed from the lockfile as it is (`--frozen-lockfile`), and it disagreed with package.json: nothing was written. */
+  lockMismatch?: boolean
+  /**
+   * The install went as package.json says, the SDK from the App's own copy
+   * under src/frontera/ that shadows the release its bun.lock records,
+   * without writing either file (`bun install --no-save`; `installed` says
+   * whether it worked): those packages, with the release bun.lock records.
+   */
+  fromCopy?: SdkShadow[]
+  /**
+   * Installed as bun.lock records it, from npm, where package.json names the
+   * App's own SDK copy (`installFromLock`): those packages, with the release
+   * installed. Neither file was written.
+   */
+  fromLock?: SdkShadow[]
+}
+
+export interface InstallOptions {
+  /** Install exactly what the lockfile says, never rewriting it (`bun install --frozen-lockfile`). */
+  frozenLockfile?: boolean
+  /** Install as package.json says without writing package.json or the lockfile (`bun install --no-save`). */
+  noSave?: boolean
+}
+
+/** The files an install must leave as they are, as they are now. */
+const TRACKED_INSTALL_FILES = ['package.json', 'bun.lock', 'bun.lockb']
+function snapshotFiles(dir: string): Map<string, Buffer> {
+  const out = new Map<string, Buffer>()
+  for (const name of TRACKED_INSTALL_FILES) if (existsSync(join(dir, name))) out.set(name, readFileSync(join(dir, name)))
+  return out
+}
+/** Put each back that changed (removing one that appeared); the names put back. */
+function restoreFiles(dir: string, before: Map<string, Buffer>): string[] {
+  const restored: string[] = []
+  for (const name of TRACKED_INSTALL_FILES) {
+    const path = join(dir, name)
+    const was = before.get(name)
+    if (!was) {
+      if (!existsSync(path)) continue
+      rmSync(path, { force: true })
+      restored.push(name)
+    } else if (!existsSync(path) || !readFileSync(path).equals(was)) {
+      writeFileSync(path, was)
+      restored.push(name)
+    }
+  }
+  return restored
 }
 
 /**
@@ -85,9 +135,61 @@ export interface InstallResult {
  * rather than inherited because stdout carries command data and nothing else;
  * everything here is progress, which belongs on stderr.
  */
-export async function installDependencies(target: string): Promise<InstallResult> {
+/**
+ * An App's packages, installed when it has none yet (a pulled App comes
+ * without node_modules): `bun install` in its folder. Null when it already
+ * has them; otherwise what the install did, for the caller to say.
+ *
+ * With a lockfile, exactly what it records (`--frozen-lockfile`): a pulled
+ * App's bun.lock is the record of the SDK its code was written against, and
+ * an install that rewrote it to match a changed package.json would lose that
+ * record and change a tracked file behind the person's back. When the two
+ * disagree nothing is installed or written, and `summary` says why and what
+ * fixes it (`lockMismatchAdvice`).
+ *
+ * Except when they disagree because package.json names the App's own SDK
+ * copy under src/frontera/ where bun.lock installed a published release (an
+ * older pull's repair). Then what bun.lock records is installed from npm,
+ * the deployed App's actual dependencies, in a temporary folder whose copy
+ * of package.json names those releases (`installFromLock`); `fromLock` says
+ * so. Offline, or refused, and the copy is there (`copyInstallShadows`): the
+ * packages are installed as package.json says, the SDK from that copy, with
+ * `bun install --no-save`, so the App previews and checks while package.json
+ * and bun.lock stay as pulled (either put back if the install changed it).
+ * `fromCopy` names those packages and `summary` says so, with what brings the
+ * deployed source back.
+ */
+export async function ensureAppPackages(
+  appRoot: string,
+  install: (dir: string, options?: InstallOptions) => Promise<InstallResult> = installDependencies,
+): Promise<InstallResult | null> {
+  if (!existsSync(join(appRoot, 'package.json')) || existsSync(join(appRoot, 'node_modules'))) return null
+  if (!['bun.lock', 'bun.lockb'].some((f) => existsSync(join(appRoot, f)))) return install(appRoot)
+  // package.json names the SDK copy where bun.lock installed a release: what bun.lock records comes first, from npm.
+  const shadowed = vendoredShadows(appRoot)
+  const fromLock = shadowed.length ? await installFromLock(appRoot, shadowed, install) : null
+  if (fromLock?.installed) return { ...fromLock, summary: lockInstallLine(fromLock.fromLock, fromLock.summary) }
+  // Offline, or the registry refused it: the App's own SDK copy, as before.
+  const notFromLock = fromLock ? `the install of what bun.lock records from npm failed (${fromLock.summary}), so ` : ''
+  const fromCopy = copyInstallShadows(appRoot)
+  if (fromCopy.length) {
+    // Read before the install: whether the folder is still as an earlier pull left it.
+    const repull = repullRefFor(appRoot)
+    const before = snapshotFiles(appRoot)
+    const result = await install(appRoot, { noSave: true })
+    const putBack = restoreFiles(appRoot, before)
+    const restored = putBack.length ? `; the install changed ${putBack.join(' and ')}, put back as pulled` : ''
+    if (!result.installed) return { ...result, fromCopy, summary: `${notFromLock}\`bun install --no-save\` (from the App’s own SDK copy under src/frontera/, keeping bun.lock as pulled) failed: ${result.summary}${restored}` }
+    return { ...result, fromCopy, summary: `${notFromLock}${copyInstallLine(fromCopy, result.summary, { repull })}${restored}` }
+  }
+  const result = await install(appRoot, { frozenLockfile: true })
+  if (result.installed || !result.lockMismatch) return result
+  return { ...result, summary: lockMismatchAdvice(appRoot) }
+}
+
+export async function installDependencies(target: string, options: InstallOptions = {}): Promise<InstallResult> {
   try {
-    const child = Bun.spawn(['bun', 'install'], {
+    const child = Bun.spawn(['bun', 'install', ...(options.frozenLockfile ? ['--frozen-lockfile'] : []), ...(options.noSave ? ['--no-save'] : [])], {
       cwd: target,
       stdin: 'ignore',
       stdout: 'pipe',
@@ -104,7 +206,8 @@ export async function installDependencies(target: string): Promise<InstallResult
       .filter((line) => line.length > 0)
 
     if (exitCode !== 0) {
-      return { installed: false, summary: lines.at(-1) ?? `bun install exited with ${exitCode}` }
+      const lockMismatch = !!options.frozenLockfile && lines.some((line) => /lockfile had changes|lockfile is frozen|frozen.?lockfile/i.test(line))
+      return { installed: false, summary: lines.at(-1) ?? `bun install exited with ${exitCode}`, ...(lockMismatch ? { lockMismatch } : {}) }
     }
     const installed = lines.filter((line) => /packages installed|Checked \d+ install/.test(line))
     return { installed: true, summary: installed.at(-1) ?? lines.at(-1) ?? 'dependencies installed' }

package/src/project-context.ts

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync, statSync } from 'node:fs'
+import { existsSync, mkdirSync, readFileSync, statSync } from 'node:fs'
 import { dirname, join, resolve } from 'node:path'
 
 import { isTrustedBinding, recordBinding } from './binding-registry'
@@ -197,3 +197,20 @@ export function ensureGitignored(root: string): 'added' | 'present' | 'created'
   )
   return 'added'
 }
+
+/**
+ * Lines `.frontera/.gitignore` keeps out of git, each added once, the file's
+ * other lines left as they are. `context.json` is always among them: which
+ * profile a directory is bound to is this machine's choice, and a copy of the
+ * project (a clone, a pull, a folder copied) must not carry it to another
+ * machine or another directory, where it would name someone else's runtime.
+ */
+export function ignoreInFronteraDir(root: string, entries: readonly string[]): void {
+  const path = join(root, CONTEXT_DIR, '.gitignore')
+  mkdirSync(dirname(path), { recursive: true })
+  const text = existsSync(path) ? readFileSync(path, 'utf8') : ''
+  const have = new Set(text.split(/\r?\n/).map((l) => l.trim().replace(/^\//, '').replace(/\/$/, '')))
+  const missing = [...new Set([...entries, CONTEXT_FILE])].filter((e) => !have.has(e.replace(/^\//, '').replace(/\/$/, '')))
+  if (!missing.length) return
+  writeFileAtomic(path, `${text}${text && !text.endsWith('\n') ? '\n' : ''}${missing.join('\n')}\n`, 0o644)
+}

package/src/project.ts

@@ -11,7 +11,10 @@ export interface ProjectConfig {
   slug: string
   displayName: string
   description?: string
-  /** Version the working tree was pulled from — feeds parentVersion. */
+  /**
+   * The version a deploy names as its parent: the last deployment from this
+   * folder, else the version the working tree was pulled from.
+   */
   parentVersion?: string | null
   /** Origins the app may reach at runtime; become the served CSP. */
   connectDomains: string[]
@@ -84,7 +87,8 @@ export function readProject(dir: string): ProjectConfig {
     slug,
     displayName: config.displayName ?? pkg.frontera?.displayName ?? slug,
     description: config.description ?? pkg.frontera?.description,
-    parentVersion: state.parentVersion ?? null,
+    // A folder never deployed from keeps its lineage: the version it was pulled from is the parent.
+    parentVersion: state.parentVersion ?? state.pulledVersion ?? null,
     connectDomains: stringList(config.connectDomains ?? pkg.frontera?.connectDomains, 'connectDomains'),
     resourceDomains: stringList(config.resourceDomains ?? pkg.frontera?.resourceDomains, 'resourceDomains'),
     outputDirectory: safeOutputDirectory(
@@ -137,8 +141,29 @@ export function readPackageVersion(dir: string): string {
 }
 
 interface ProjectState {
+  /** The last deployment made from this folder (`app deploy`): what it was deployed as. */
   parentVersion?: string | null
   appId?: string
+  /**
+   * The version the working tree was pulled from (`app pull`, or a local
+   * project's pull of an App's code), kept apart from `parentVersion` so a
+   * pulled folder is not read as deployed from here.
+   */
+  pulledVersion?: string | null
+  /** The App it was pulled from, by its id where it was pulled. */
+  pulledFrom?: string | null
+  /**
+   * Each source file as the pull left it, by path in the folder, with its hash
+   * (`local-app-pulled.ts`): `local check` counts an App still like this as
+   * inherited from the workspace.
+   */
+  pulledFiles?: Record<string, string>
+  /**
+   * A deployment from here that a database restore took away
+   * (`local-app-restore.ts`): the next `frontera local dev` deploys again,
+   * and the deploy clears it.
+   */
+  restoredAway?: { deployment: string; restoredAt: string }
 }
 
 export function readState(dir: string): ProjectState {

package/src/provenance.ts

@@ -13,6 +13,16 @@ export interface AppBuildProvenance {
   lockfilePath?: string
   lockfileDigest?: string
   packagedAt: string
+  /** The Git branch the working copy is on, read locally. Informational, never authorization. */
+  branch?: string
+  /** The commit's author, `Name <email>`, read locally. */
+  commitAuthor?: string
+  /** The Forge session (and its harness) the deploy ran in, when it ran in one. */
+  session?: { id: string; harness: string | null }
+  /** What the CLI checked before uploading (design 2026-10-18 §6). */
+  checks?: { build: { status: 'passed' | 'failed' | 'skipped'; detail: string } }
+  /** What the App calls, for the platform's contract check. */
+  contract?: { digest?: string; objectTypes: Record<string, string[]>; actions: string[]; functions: string[] }
 }
 
 const LOCKFILES = ['bun.lock', 'bun.lockb', 'package-lock.json', 'pnpm-lock.yaml', 'yarn.lock'] as const
@@ -85,9 +95,24 @@ export function collectBuildProvenance(root: string): AppBuildProvenance {
         encoding: 'utf8',
         stdio: ['ignore', 'pipe', 'ignore'],
       }).trim().length > 0
+    const branch = execFileSync('git', ['rev-parse', '--abbrev-ref', 'HEAD'], { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim()
+    // A detached HEAD has no branch; its commit still identifies the source.
+    if (branch && branch !== 'HEAD') provenance.branch = branch
+    const author = execFileSync('git', ['log', '-1', '--format=%an <%ae>'], { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim()
+    if (author) provenance.commitAuthor = author
   } catch {
     // Source provenance is optional for projects outside Git.
   }
 
+  const session = forgeSessionOf(process.env)
+  if (session) provenance.session = session
+
   return provenance
 }
+
+/** The Forge session a command runs in: Forge puts `FORGE_SESSION` (and `FORGE_HARNESS`) in every session's environment. */
+export function forgeSessionOf(env: NodeJS.ProcessEnv): { id: string; harness: string | null } | null {
+  const id = env.FORGE_SESSION?.trim()
+  if (!id) return null
+  return { id: id.slice(0, 120), harness: env.FORGE_HARNESS?.trim() || null }
+}

package/src/render-evidence.ts

@@ -1,7 +1,7 @@
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs'
 import { join, relative, sep } from 'node:path'
 
-import { isExcluded } from './packaging'
+import { gitignoreMatcher, isExcluded } from './packaging'
 
 /**
  * Has anybody looked at this app before it goes live?
@@ -34,6 +34,12 @@ import { isExcluded } from './packaging'
  * tree; neither error matters here, because nothing is being enforced. The
  * cheap answer to a reported question beats the expensive answer to a blocked
  * one.
+ *
+ * The tooling's own temporary changes are not source changes, so they must
+ * not move an mtime: what `app dev` and `local check` rewrite for a run (the
+ * SDK copy's `paths` in `tsconfig.json`, what the dev server or a build
+ * writes) goes back byte for byte with the time it had (`putBackAsWas`). A
+ * put-back that left a new mtime made every render before it stale.
  */
 
 /** Written by `render_app`; see RENDER_EVIDENCE_RELATIVE_PATH in the service. */
@@ -59,6 +65,18 @@ export interface RenderEvidence {
   path?: string
   /** What the browser console said at render time, if the renderer recorded it. */
   consoleErrors?: number
+  /** Requests that failed at render time. */
+  failedRequests?: number
+  /** The basic accessibility scan, kept only for a fresh render: serious and critical findings are `violations`. */
+  a11y?: { violations: number; findings?: unknown[] }
+  /** What was rendered: the App's dev server or one of its previews, and the address. Absent on a render recorded before this was kept. */
+  of?: 'dev-server' | 'preview'
+  url?: string
+  /**
+   * The last render was not of this App (another address, or another App's
+   * page): it is not attached, and this deployment counts as not rendered.
+   */
+  notThisApp?: { url: string; why: string }
 }
 
 interface RenderRecord {
@@ -66,17 +84,31 @@ interface RenderRecord {
   renderedAtMs?: number
   path?: string
   consoleErrors?: number
+  failedRequests?: number
+  a11y?: { violations?: unknown; findings?: unknown[] }
+  target?: { of?: unknown; url?: unknown; app?: unknown }
+}
+
+/**
+ * Files a framework rewrites on every run, which nobody authors. `next dev`
+ * and `next build` each write `next-env.d.ts` with their own types folder, so
+ * building after a render made every render stale.
+ */
+export function isGeneratedFile(rel: string): boolean {
+  return rel === 'next-env.d.ts' || rel.endsWith('.tsbuildinfo')
 }
 
 /**
  * Newest mtime across the files that would be packaged.
  *
- * Same exclusion set as packaging, so `node_modules` churn and build output
- * cannot make a tree look edited — the ONE failure mode that would make this
- * report worthless, because it would report `stale` every single time and
- * everyone would stop reading it.
+ * Same exclusion set as packaging (the hard set and the project's
+ * `.gitignore`), so `node_modules` churn and build output cannot make a tree
+ * look edited — the ONE failure mode that would make this report worthless,
+ * because it would report `stale` every single time and everyone would stop
+ * reading it.
  */
 export function newestSourceChangeMs(root: string): number {
+  const ignored = gitignoreMatcher(root)
   let newest = 0
   const walk = (dir: string) => {
     let entries: string[]
@@ -102,6 +134,7 @@ export function newestSourceChangeMs(root: string): number {
         walk(full)
         continue
       }
+      if (ignored(rel) || isGeneratedFile(rel)) continue
       newest = Math.max(newest, stat.mtimeMs)
     }
   }
@@ -109,7 +142,13 @@ export function newestSourceChangeMs(root: string): number {
   return newest
 }
 
-export function readRenderEvidence(root: string): RenderEvidence {
+/**
+ * The last render, as evidence of this App's current source. With `app` (the
+ * App's slug), a render of an address that is not its dev server or one of
+ * its previews, or a render made for another App, is not evidence of it: it
+ * comes back unrendered, saying what it was of.
+ */
+export function readRenderEvidence(root: string, app?: string): RenderEvidence {
   const path = join(root, RENDER_EVIDENCE_PATH)
   if (!existsSync(path)) return { rendered: false, reason: 'none' }
 
@@ -126,13 +165,29 @@ export function readRenderEvidence(root: string): RenderEvidence {
   const renderedAtMs = record.renderedAtMs ?? (record.renderedAt ? Date.parse(record.renderedAt) : NaN)
   if (!Number.isFinite(renderedAtMs)) return { rendered: false, reason: 'none' }
 
+  const target = record.target
+  const url = typeof target?.url === 'string' ? target.url : undefined
+  if (app && target && url) {
+    const why = target.app !== undefined && target.app !== app
+      ? `it was rendered for ${String(target.app)}, not ${app}`
+      : target.of === 'elsewhere'
+        ? `it is not ${app}'s dev server or one of its previews`
+        : null
+    if (why) return { rendered: false, reason: 'none', notThisApp: { url, why } }
+  }
+  const of = target?.of === 'dev-server' || target?.of === 'preview' ? target.of : undefined
   const rendered = renderedAtMs >= newestSourceChangeMs(root)
   return {
     rendered,
+    ...(of ? { of } : {}),
+    ...(url ? { url } : {}),
     reason: rendered ? 'fresh' : 'stale',
     ...(record.renderedAt ? { renderedAt: record.renderedAt } : {}),
     ...(record.path ? { path: record.path } : {}),
     ...(typeof record.consoleErrors === 'number' ? { consoleErrors: record.consoleErrors } : {}),
+    ...(typeof record.failedRequests === 'number' ? { failedRequests: record.failedRequests } : {}),
+    // A scan of an earlier tree says nothing about this one.
+    ...(rendered && typeof record.a11y?.violations === 'number' ? { a11y: { violations: record.a11y.violations, findings: (record.a11y.findings ?? []).slice(0, 20) } } : {}),
   }
 }
 
@@ -167,9 +222,12 @@ export function readRenderThumbnail(root: string): Uint8Array | null {
  * moves on.
  */
 export function describeRenderEvidence(evidence: RenderEvidence): string {
+  if (evidence.notThisApp) {
+    return `  not attaching the last render, of ${evidence.notThisApp.url}: ${evidence.notThisApp.why}; render the App's dev server (app_render with no url) and deploy again`
+  }
   switch (evidence.reason) {
     case 'fresh':
-      return `  rendered ${evidence.path ?? '/'}${
+      return `  rendered ${evidence.url ? `${evidence.url}${evidence.of === 'preview' ? ' (a preview)' : ''}` : evidence.path ?? '/'}${
         evidence.consoleErrors ? ` (${evidence.consoleErrors} console error${evidence.consoleErrors === 1 ? '' : 's'} at render time)` : ''
       }`
     case 'stale':

package/src/scopes.ts

@@ -54,7 +54,7 @@ export function commandScope(meta: {
 
 /** For prose: the organization-scoped nouns that actually reach the service. */
 export function orgScopedServiceNouns(): string[] {
-  return [...ORG_SCOPED_NOUNS].filter((n) => n !== 'auth' && n !== 'kit').sort()
+  return [...ORG_SCOPED_NOUNS].filter((n) => n !== 'auth' && n !== 'kit').sort((a, b) => (String(a) < String(b) ? -1 : String(a) > String(b) ? 1 : 0))
 }
 
 /**

package/src/template.ts

@@ -574,14 +574,20 @@ const instance = useObjectInstance('SupportTicket', selectedId)
 const version = recordVersionOf(instance.data)
 \`\`\`
 
-**A list row does not carry the version.** It arrives as \`_meta.recordVersion\`
-from the INSTANCE route only, and only for an editable type. So a control that
-edits a row in a table fetches that row's instance first — selecting a row and
-submitting straight from \`useObjects\` data sends no version at all.
-
-That failure is silent: a missing version does not error, the compare-and-set
-is simply skipped, and two people overwrite each other with no refusal and no
-evidence. Use \`recordVersionOf\` rather than reaching into \`_meta\` yourself.
+**A row from \`useObjects\` does not carry the version.** It arrives as
+\`_meta.recordVersion\`, only for an editable type: always from the INSTANCE
+route, and on a query's rows only when the query asks for it (\`recordVersions\`,
+which Functions, workflows and the CLI ask for). The App SDK's queries do not
+ask, so a control that edits a row in a table fetches that row's instance first:
+selecting a row and submitting straight from \`useObjects\` data sends no
+version at all.
+
+An edit of an existing record always compares versions, so a missing version
+is refused, not skipped: the submit fails and nothing changes. The platform
+fills the key input and the \`expectedVersion\` input from the subject (the
+record and the version you submit against), and refuses the submit when the
+inputs you pass disagree with it. Use \`recordVersionOf\` rather than reaching
+into \`_meta\` yourself.
 
 A stale value IS refused, and that refusal is the feature — report it as
 "someone else changed this, reload" rather than retrying with a fresher version

package/src/templates/next-app-files.ts

@@ -20,6 +20,16 @@
  * build to be green.
  */
 
+import vendored from '../vendor/sdk-sources.json'
+
+/**
+ * The `@frontera-sdk/*` range a Next App depends on: the release of the SDK
+ * this CLI carries, so a new App starts on the SDK the CLI was tested with
+ * rather than on a floor several releases old. The packages are public npm
+ * packages; only the legacy Vite scaffold vendors their source.
+ */
+export const SDK_RANGE = `^${vendored.sdkVersion}`
+
 interface ScaffoldInput {
   /** Project name — the package name, the display name and the page title. */
   name: string
@@ -62,8 +72,8 @@ function projectFiles(name: string): Record<string, string> {
           deploy: 'bun run check && frontera app deploy',
         },
         dependencies: {
-          '@frontera-sdk/blueprint': '^1.43.10',
-          '@frontera-sdk/core': '^1.43.10',
+          '@frontera-sdk/blueprint': SDK_RANGE,
+          '@frontera-sdk/core': SDK_RANGE,
           '@tanstack/react-query': '^5.90.21',
           // Everything from here to `tailwind-merge` is what a shadcn
           // component imports. Every item in that registry declares NO
@@ -120,6 +130,11 @@ function projectFiles(name: string): Record<string, string> {
 
     'next.config.ts': `import type { NextConfig } from 'next'
 
+// This folder is the App's project, also when it sits inside a Frontera
+// solution that has a lockfile of its own: without this, Next picks the
+// outermost lockfile as the workspace root and warns on every run.
+const root = typeof __dirname === 'string' ? __dirname : process.cwd()
+
 const nextConfig: NextConfig = {
   output: 'export',
   trailingSlash: true,
@@ -127,6 +142,11 @@ const nextConfig: NextConfig = {
   // Current Frontera SDK packages publish TypeScript source. This is Next's
   // supported boundary for compiling those dependencies inside the App build.
   transpilePackages: ['@frontera-sdk/core', '@frontera-sdk/blueprint', '@frontera-sdk/agents'],
+  // AGENTS.md is this project's own. Left on, \`next dev\` rewrites it on every
+  // run, the tree is never clean, and a deploy refuses the build as stale.
+  agentRules: false,
+  turbopack: { root },
+  outputFileTracingRoot: root,
 }
 
 export default nextConfig
@@ -213,6 +233,9 @@ export default nextConfig
     '.gitignore': `node_modules/
 .next/
 out/
+# Written by \`next dev\` and \`next build\`, each with its own types folder.
+next-env.d.ts
+*.tsbuildinfo
 .frontera/
 .env
 .env.*
@@ -1032,16 +1055,22 @@ bun run check
 \`\`\`
 
 \`\`\`bash
-frontera app deploy --no-promote
+frontera app deploy
 \`\`\`
 
-Deploying without promoting publishes an immutable version and returns a
-preview URL. Promote it once it looks right:
+A deploy uploads an immutable preview deployment and returns its link, plus
+the links of this branch's and this session's previews. It never changes what
+users see. Promote it once it looks right (it needs the promote permission,
+and the workspace's required checks):
 
 \`\`\`bash
-frontera app promote <version>
+frontera app promote <deployment>
 \`\`\`
 
+\`frontera app deployments\` lists them; \`frontera app rollback --reason "…"\`
+returns production to the previous one and pins it until
+\`frontera app rollback --undo\`.
+
 ## Layout
 
 \`\`\`text