@frontera-sdk/cli 1.53.5 → 1.53.6

package/package.json

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

package/src/api/apps-api.ts

@@ -159,8 +159,8 @@ export class AppsApi {
    * `pull` used `ensureApp`, so a typo or a slug the platform had since
    * renamed produced a brand new empty app instead of an error.
    */
-  resolveApp(slugOrId: string): Promise<{ id: string; slug: string; displayName: string }> {
-    return this.client.request<{ id: string; slug: string; displayName: string }>(
+  resolveApp(slugOrId: string): Promise<{ id: string; slug: string; displayName: string; kind?: 'code' | 'chat' }> {
+    return this.client.request<{ id: string; slug: string; displayName: string; kind?: 'code' | 'chat' }>(
       `/v1/platform-apps/resolve/${encodeURIComponent(slugOrId)}`,
     )
   }

package/src/api/platform-api.ts

@@ -4,6 +4,7 @@ import type { MetricQueryBody, MetricQueryResult } from '../blueprint/metric-que
 import { organizationHeaders, selectedOrganization } from '../organization'
 
 import { CliError } from '../errors'
+import type { SavedServer } from '../local/local-mcp-servers'
 import { BLUEPRINT_SCHEMA_CAPABILITIES } from '../blueprint-types'
 
 /**
@@ -291,6 +292,11 @@ export class PlatformApi {
     return this.get<{ server: unknown }>(`/v1/mcp-servers/${encodeURIComponent(slug)}`)
   }
 
+  /** Created, or replaced in place: `created` says which. */
+  saveMcpServer(slug: string, definition: Record<string, unknown>): Promise<SavedServer> {
+    return this.client.request<SavedServer>(`/v1/mcp-servers/${encodeURIComponent(slug)}`, { method: 'PUT', body: definition })
+  }
+
   /** Archived, not deleted: the Function runs its tools started still name it. */
   archiveMcpServer(slug: string): Promise<{ slug: string; archived: boolean }> {
     return this.client.request<{ slug: string; archived: boolean }>(`/v1/mcp-servers/${encodeURIComponent(slug)}`, { method: 'DELETE' })
@@ -721,6 +727,20 @@ export class PlatformApi {
 
   // ── Knowledge ─────────────────────────────────────────────────────────────
 
+  /**
+   * Whether the platform runs the Knowledge app. Its routes answer 404 before any sign-in check where it does not, so
+   * any other answer, a refusal of this key included, means it runs. No answer counts as not running.
+   */
+  async knowledgeAppRuns(): Promise<boolean> {
+    try {
+      await this.get<unknown>('/v1/knowledge-app/me')
+      return true
+    } catch (err) {
+      const status = (err as { status?: number }).status
+      return status !== undefined && status !== 404
+    }
+  }
+
   knowledgeBases(workspaceId: string) {
     return this.getList<unknown>(`/v1/workspace-knowledge?workspaceId=${encodeURIComponent(workspaceId)}`)
   }

package/src/commands/app/checks.ts

@@ -37,7 +37,7 @@ export const appChecks: Command = {
     if (!deployment) throw new UsageError('say which deployment', 'frontera app checks <deployment id or label>')
     const project = requireProjectFrom(ctx)
     const client = new AppsApi(ctx.apiUrl, ctx.token)
-    const app = await projectApp(client, project)
+    const app = await projectApp(ctx, client, project)
     const res = await client.checks(app.id, deployment)
     return { data: res, text: renderChecks(res.deployment, res.checks) }
   },

package/src/commands/app/deploy.ts

@@ -9,14 +9,14 @@ import { resolveManifest } from '../../manifest'
 import { collectSourceFiles, formatBytes } from '../../packaging'
 import { packDirectory } from '../../pack'
 import { collectAppContract } from '../../app-contract'
-import { writeAppId, writeState } from '../../project'
+import { writeState } from '../../project'
 import { collectBuildProvenance } from '../../provenance'
 import { validateStaticAppProject } from '../../static-app-validation'
 import { describeRenderEvidence, readRenderEvidence, readRenderThumbnail, type RenderEvidence } from '../../render-evidence'
 import { createTarGz } from '../../tar'
 import { keepBuildWrittenFiles } from '../../local/local-app-pulled'
 import { setAsideCopyPaths } from '../../local/local-app-sdk-paths'
-import { requireProjectFrom } from './shared'
+import { ensureProjectApp, requireProjectFrom } from './shared'
 import { canPrompt } from '../../prompt'
 import { flagBool, flagString, type Command } from '../types'
 
@@ -196,12 +196,14 @@ export const appDeploy: Command = {
     noun: 'app',
     verb: 'deploy',
     args: [],
-    flags: { label: 'string', version: 'string', prod: 'boolean', preview: 'boolean', 'no-promote': 'boolean', 'skip-build-check': 'boolean', build: 'boolean' },
+    flags: { label: 'string', version: 'string', prod: 'boolean', preview: 'boolean', 'no-promote': 'boolean', 'skip-build-check': 'boolean', build: 'boolean', app: 'string' },
+    flagHelp: { app: 'an App this workspace already has, by its slug: deploy to it, and keep this folder deploying to it here' },
     summary: 'Upload the build as a preview deployment; --build to build first, --prod to go live',
     details: [
       'A deploy is a preview unless --prod is given. A pipeline (a key, no terminal) must say which it wants: --prod or --preview. Without either it exits with an error, so a pipeline written when a deploy went live stops instead of silently making previews.',
+      'The folder deploys to the App it deployed to before in the same workspace, whatever its package.json name says now: a deploy never renames an App. In a workspace it has not deployed to, it deploys to the App named like the folder, and creates that App when there is none, which the output says.',
     ],
-    examples: ['frontera app deploy', 'frontera app deploy --build', 'frontera app deploy --label 1.4.0', 'frontera app deploy --prod', 'frontera app deploy --preview', 'frontera app deploy --prod --no-promote'],
+    examples: ['frontera app deploy', 'frontera app deploy --build', 'frontera app deploy --label 1.4.0', 'frontera app deploy --prod', 'frontera app deploy --preview', 'frontera app deploy --prod --no-promote', 'frontera app deploy --app acme-shipments'],
     needsProject: true,
   },
 
@@ -284,7 +286,7 @@ export const appDeploy: Command = {
     }
 
     const client = new AppsApi(ctx.apiUrl, ctx.token)
-    const app = await client.ensureApp(project.slug, project.displayName, project.appId, { icon: project.icon })
+    const app = await ensureProjectApp(ctx, client, project, flagString(ctx, 'app'))
 
     ctx.output.note(
       `  bundle ${distFiles.length} files, ${formatBytes(distFiles.reduce((n, f) => n + f.bytes.byteLength, 0))}`,
@@ -342,10 +344,7 @@ export const appDeploy: Command = {
     const deployment = res.deployment ?? res.version
 
     // On the runtime again: whatever a database restore had taken away is back.
-    writeState(project.root, { appId: app.id, parentVersion: deployment, restoredAway: undefined })
-    // Local environment binding: source remains portable and package.json
-    // remains ordinary package metadata.
-    writeAppId(project.root, app.id)
+    writeState(project.root, { parentVersion: deployment, restoredAway: undefined })
 
     // Where a person opens what was just made: its own link, and the moving
     // links of its branch and session. A preview was once described as one
@@ -360,6 +359,7 @@ export const appDeploy: Command = {
     const data = {
       app: app.slug,
       appId: app.id,
+      ...(app.created ? { created: app.created } : {}),
       deployment,
       // The same id, under its earlier name, for scripts that read `version`.
       version: deployment,

package/src/commands/app/deployments.ts

@@ -72,7 +72,7 @@ export const appDeployments: Command = {
   async run(ctx) {
     const project = requireProjectFrom(ctx)
     const client = new AppsApi(ctx.apiUrl, ctx.token)
-    const app = await projectApp(client, project)
+    const app = await projectApp(ctx, client, project)
     const ledger = await client.deployments(app.id)
     // The checks of the newest deployments that still have files; an older or
     // failed read falls back to the render evidence the ledger already carries.

package/src/commands/app/dev.ts

@@ -1,19 +1,31 @@
 import { existsSync } from 'node:fs'
-import { join } from 'node:path'
+import { join, relative } from 'node:path'
 
 import { AppsApi } from '../../api/apps-api'
 import { PlatformApi } from '../../api/platform-api'
 import { createDevSessionBroker, freeLoopbackPort, isLoopbackPortFree } from '../../dev-broker'
 import { CliError, UsageError } from '../../errors'
-import { DEV_OWNER_ENV, enclosingSolution, forgetDevServer, registerDevServer, watchOwner } from '../../mcp/mcp-apps'
+import {
+  DEV_OWNER_ENV,
+  devServerHome,
+  devServerLine,
+  enclosingSolution,
+  ensureDevServer,
+  forgetDevServer,
+  readDevServer,
+  registerDevServer,
+  stopDevServerAndSay,
+  watchOwner,
+} from '../../mcp/mcp-apps'
 import { ensureAppPackages } from '../../project-bootstrap'
 import { detectAppFramework } from '../../provenance'
-import { writeAppId } from '../../project'
+import type { AppProject } from '../../context'
+import { bindApp } from '../../project'
 import { mintDevSession, writeDevSessionState } from '../../local/local-app-dev-session'
 import { keepDevWrittenFiles, leftLine, putBackLine } from '../../local/local-app-dev-files'
 import { setAsideCopyPaths } from '../../local/local-app-sdk-paths'
-import { requireProjectFrom } from './shared'
-import { flagBool, flagString, type Command } from '../types'
+import { ensureProjectApp, requireProjectFrom } from './shared'
+import { flagBool, flagString, type Command, type CommandContext, type CommandResult } from '../types'
 
 const DEFAULT_PORT = 3000
 const READY_TIMEOUT_MS = 30_000
@@ -74,19 +86,69 @@ function withoutOwner(env: NodeJS.ProcessEnv): Record<string, string> {
   return rest as Record<string, string>
 }
 
+/**
+ * `--detach`: the same server, started by `ensureDevServer` in its own session with its output in a log, so it
+ * outlives the shell that started it (an agent's background command is killed at its time limit, with its whole
+ * process group). Recorded where `--stop`, `local stop`, MCP `app_dev` and Forge find it; a live one is reused.
+ */
+async function detach(ctx: CommandContext, project: AppProject): Promise<CommandResult> {
+  const raw = flagString(ctx, 'port')
+  const port = raw === undefined ? 0 : appPort(raw)
+  // Here, not in the server's log: a creation is said where the caller reads it, and a bad credential fails now.
+  const app = await ensureProjectApp(ctx, new AppsApi(ctx.apiUrl, ctx.token), project)
+  const home = devServerHome(project.root)
+  const ref = { slug: project.slug, name: project.displayName, root: project.root, path: relative(home.root, project.root) || '.', framework: detectAppFramework(project.root) }
+  let started: Awaited<ReturnType<typeof ensureDevServer>>
+  try {
+    started = await ensureDevServer(home, ref, { env: { FRONTERA_API_URL: ctx.apiUrl }, token: ctx.token, target: app.target }, { owner: 'detached', port })
+  } catch (error) {
+    throw new CliError((error as Error).message, { code: 'FAILURE', cause: error, hint: '`frontera app dev` without --detach runs the server in the foreground, where its output shows as it starts' })
+  }
+  const { server, reused, installed, trackedFiles } = started
+  if (installed) ctx.output.note(`[dev] ${installed}`)
+  for (const line of trackedFiles ?? []) ctx.output.note(`[dev] ${line}`)
+  const logFile = join(home.root, server.log)
+  const log = existsSync(logFile) ? relative(ctx.cwd, logFile) : server.log
+  return {
+    data: { appId: app.id, origin: server.url, port: server.port, pid: server.pid, log, reused },
+    text: [
+      reused ? `Reused the dev server already running: ${devServerLine(server)}.` : `${app.slug} runs at ${server.url} in its own session: it keeps running after this shell ends.`,
+      `  log: ${log}`,
+      '  stop it: `frontera app dev --stop` in this folder',
+    ].join('\n'),
+  }
+}
+
+/** `--stop`: the App's recorded dev server, however it was started, and what it put back as it stopped. */
+async function stopRecorded(ctx: CommandContext, project: AppProject): Promise<CommandResult> {
+  const home = devServerHome(project.root)
+  const server = readDevServer(home, project.slug)
+  const { stopped, trackedFiles } = await stopDevServerAndSay(home, project.slug)
+  for (const line of trackedFiles) ctx.output.note(`[dev] ${line}`)
+  if (!stopped || !server) return { data: { stopped: false }, text: `${project.slug} had no dev server running.` }
+  return { data: { stopped: true, port: server.port, pid: server.pid }, text: `Stopped ${project.slug}'s dev server (port ${server.port}).` }
+}
+
 export const appDev: Command = {
   meta: {
     noun: 'app',
     verb: 'dev',
     args: [],
-    flags: { port: 'string', 'no-open': 'boolean' },
+    flags: { port: 'string', 'no-open': 'boolean', detach: 'boolean', stop: 'boolean' },
+    flagHelp: { stop: 'stop this App\'s dev server, however it was started, and exit' },
     summary: 'Run an App locally with short-lived authenticated Blueprint access',
-    examples: ['frontera app dev', 'frontera app dev --port 3210 --no-open', 'frontera app dev --port 0'],
+    details: [
+      'Without --detach the server runs in the foreground until you stop it (Ctrl+C). With --detach it starts in its own session, returns once the App answers, and prints its URL, its log and how to stop it: use it from a coding agent, whose background commands end at a time limit. Run it again to get the same server back.',
+    ],
+    examples: ['frontera app dev', 'frontera app dev --detach', 'frontera app dev --stop', 'frontera app dev --port 3210 --no-open', 'frontera app dev --port 0'],
     needsProject: true,
   },
 
   async run(ctx) {
     const project = requireProjectFrom(ctx)
+    if (flagBool(ctx, 'detach') && flagBool(ctx, 'stop')) throw new UsageError('--detach and --stop do opposite things', 'start it with `frontera app dev --detach`, stop it with `frontera app dev --stop`')
+    if (flagBool(ctx, 'stop')) return stopRecorded(ctx, project)
+    if (flagBool(ctx, 'detach')) return detach(ctx, project)
     const asked = appPort(flagString(ctx, 'port'))
     // `--port 0`: one free on every loopback, said with the URL below.
     const port = asked === 0 ? await freeLoopbackPort() : asked
@@ -109,10 +171,10 @@ export const appDev: Command = {
     }
     if (installed) ctx.output.note(`[dev] ${installed.summary}`)
     const apps = new AppsApi(ctx.apiUrl, ctx.token)
-    const app = await apps.ensureApp(project.slug, project.displayName, project.appId, { icon: project.icon })
-    writeAppId(project.root, app.id)
+    const app = await ensureProjectApp(ctx, apps, project)
     // The solution this App is in, if any: where status reads how this server's sessions fare.
     const solution = enclosingSolution(project.root)
+    const home = devServerHome(project.root)
     // The id sessions are minted for: a restore to a baseline from before the App existed takes it away.
     let appId = app.id
 
@@ -132,12 +194,12 @@ export const appDev: Command = {
             appId,
             mint: (id) => apps.appToken(id),
             // Gone from the runtime (`local snapshot restore`): registered again by its slug, as `app dev` started.
-            reRegister: async () => (await apps.ensureApp(project.slug, project.displayName, null, { icon: project.icon })).id,
+            reRegister: async () => (await apps.ensureApp(app.slug, project.displayName, null, { icon: project.icon })).id,
             onReRegistered: (id) => {
               if (id === appId) return
               ctx.output.note(`[dev] the runtime no longer had ${app.slug} (a restore of its database?): registered it again as ${id}; \`frontera app deploy\` puts its code back`)
               appId = id
-              writeAppId(project.root, id)
+              bindApp(project.root, app.target, id)
             },
             record: solution ? (state) => writeDevSessionState(solution.stateDir, project.slug, state) : undefined,
           })
@@ -235,8 +297,11 @@ export const appDev: Command = {
       const back = putBackLine(kept.afterReady(), 'started')
       if (back) ctx.output.note(`[dev] ${back}`)
       ctx.output.note(`[dev] ready: ${targetUrl}`)
-      // In a solution, say so where its agents look, so they render this server instead of starting another.
-      if (solution && !owner) registerDevServer(solution, { slug: project.slug, pid: process.pid, port, url: targetUrl, startedAt: new Date().toISOString(), log: 'the terminal running frontera app dev' })
+      // Said where agents, Forge and `--detach` look, so they use this server instead of starting another. One
+      // `--detach` started is already recorded, with its log; a live one another process recorded stays.
+      if (!owner && !readDevServer(home, project.slug)) {
+        registerDevServer(home, { slug: project.slug, pid: process.pid, port, url: targetUrl, startedAt: new Date().toISOString(), log: 'the terminal running frontera app dev', ...(app.target ? { target: app.target } : {}) })
+      }
       if (!flagBool(ctx, 'no-open')) openBrowser(targetUrl)
       const exitCode = await child.exited
       if (!stopped && exitCode !== 0) {
@@ -253,7 +318,7 @@ export const appDev: Command = {
       unwatch?.()
       process.off('SIGINT', onSignal)
       process.off('SIGTERM', onSignal)
-      if (solution) forgetDevServer(solution, project.slug, process.pid)
+      forgetDevServer(home, project.slug, process.pid)
       stop()
       // Once the framework's server has exited (or after a while, whatever it does), what it wrote goes back.
       await Promise.race([child.exited, Bun.sleep(STOP_WAIT_MS)])

package/src/commands/app/promote.ts

@@ -35,7 +35,7 @@ export const appPromote: Command = {
     if (force && !reason?.trim()) throw new UsageError('--force needs --reason', 'frontera app promote <deployment> --force --reason "why the checks can wait"')
     const project = requireProjectFrom(ctx)
     const client = new AppsApi(ctx.apiUrl, ctx.token)
-    const app = await projectApp(client, project)
+    const app = await projectApp(ctx, client, project)
     try {
       const res = await client.promote(app.id, { deployment, ...(force ? { force: true, reason } : {}) })
       const name = res.label ?? res.promoted

package/src/commands/app/pull.ts

@@ -3,9 +3,10 @@ import { join } from 'node:path'
 import { AppsApi } from '../../api/apps-api'
 import { CliError, UsageError } from '../../errors'
 import { healProject } from '../../heal'
-import { dirtyFiles, writeState } from '../../project'
+import { bindApp, dirtyFiles, writeState } from '../../project'
 import { DEV_ENV_FILE, writeDevEnv } from '../../dev-env'
 import { flagBool, type Command } from '../types'
+import { credentialTarget } from './shared'
 import { unpackTo } from '../../untar'
 
 export const appPull: Command = {
@@ -96,7 +97,8 @@ export const appPull: Command = {
     const count = unpackTo(dir, bytes)
     // What was pulled, apart from a deployment from here: the folder is not read as deployed until `app deploy`,
     // whose parent is this version (`readProject`). A deployment recorded before this pull no longer describes the tree.
-    writeState(dir, { appId: app.id, parentVersion: null, pulledFrom: app.id, pulledVersion: parentVersion })
+    writeState(dir, { parentVersion: null, pulledFrom: app.id, pulledVersion: parentVersion })
+    bindApp(dir, await credentialTarget(ctx), app.id)
 
     // Pull's contract is "give me a working copy", and a copy that cannot
     // `bun install` is not one. Apps stored by an older toolchain carry

package/src/commands/app/rollback.ts

@@ -25,7 +25,7 @@ export const appRollback: Command = {
     if (!undo && !reason?.trim()) throw new UsageError('a rollback needs --reason', 'frontera app rollback --reason "what went wrong"')
     const project = requireProjectFrom(ctx)
     const client = new AppsApi(ctx.apiUrl, ctx.token)
-    const app = await projectApp(client, project)
+    const app = await projectApp(ctx, client, project)
     if (undo) {
       const res = await client.undoRollback(app.id)
       return {

package/src/commands/app/save.ts

@@ -1,7 +1,6 @@
 import { AppsApi } from '../../api/apps-api'
 import { packDirectory } from '../../pack'
-import { writeAppId, writeState } from '../../project'
-import { requireProjectFrom } from './shared'
+import { ensureProjectApp, requireProjectFrom } from './shared'
 import type { Command } from '../types'
 
 export const appSave: Command = {
@@ -21,15 +20,12 @@ export const appSave: Command = {
 
     // save and deploy are the only verbs that may bring an app into
     // existence; every read verb resolves instead.
-    const app = await client.ensureApp(project.slug, project.displayName, project.appId, { icon: project.icon })
+    const app = await ensureProjectApp(ctx, client, project)
     const { tgz } = packDirectory(project.root, ctx.output, 'packaged')
     const res = await client.saveDraft(app.id, tgz, project.parentVersion)
 
-    writeState(project.root, { appId: app.id })
-    writeAppId(project.root, app.id)
-
     return {
-      data: { app: app.slug, appId: app.id, fileCount: res.fileCount },
+      data: { app: app.slug, appId: app.id, ...(app.created ? { created: app.created } : {}), fileCount: res.fileCount },
       text: `Saved draft for ${app.slug} (${res.fileCount} files)`,
     }
   },

package/src/commands/app/shared.ts

@@ -1,5 +1,7 @@
 import { AppsApi } from '../../api/apps-api'
+import { PlatformApi } from '../../api/platform-api'
 import { UsageError } from '../../errors'
+import { appBinding, appTarget, bindApp } from '../../project'
 import type { AppProject } from '../../context'
 import type { CommandContext } from '../types'
 
@@ -13,6 +15,16 @@ export function requireProjectFrom(ctx: CommandContext): AppProject {
   return ctx.project
 }
 
+/**
+ * The target this credential reaches (`appTarget`): its workspace as `whoami`
+ * answers, asked the way `AppsApi` asks, so it is the workspace the App calls
+ * land in. Null when it cannot say; the folder's bindings are then left alone.
+ */
+export async function credentialTarget(ctx: CommandContext): Promise<string | null> {
+  const me = await new PlatformApi(ctx.apiUrl, ctx.token).whoami().catch(() => null)
+  return me?.workspaceId ? appTarget(ctx.apiUrl, me.workspaceId) : null
+}
+
 /**
  * The app this project belongs to, without creating one.
  *
@@ -20,6 +32,51 @@ export function requireProjectFrom(ctx: CommandContext): AppProject {
  * that ensured instead would turn a typo, or a slug the platform had since
  * renamed, into a brand new empty app.
  */
-export function projectApp(client: AppsApi, project: AppProject) {
-  return client.resolveApp(project.appId ?? project.slug)
+export async function projectApp(ctx: CommandContext, client: AppsApi, project: AppProject) {
+  const bound = appBinding(project.root, await credentialTarget(ctx)).id
+  return client.resolveApp(bound ?? project.fallbackAppId ?? project.slug)
+}
+
+/**
+ * The folder's App where the credential acts, created when it has none there
+ * (`save`, `deploy`, `app dev`), and bound to the folder for that target. A
+ * creation is said: a person who renamed the folder or moved it to another
+ * workspace must not learn of a second App from the gallery. `app` names an
+ * existing App to deploy to instead, which never creates one.
+ */
+export async function ensureProjectApp(
+  ctx: CommandContext,
+  client: AppsApi,
+  project: AppProject,
+  app?: string,
+): Promise<{ id: string; slug: string; created: string | null; target: string | null }> {
+  const target = await credentialTarget(ctx)
+  const known = appBinding(project.root, target)
+  const named = app ? await client.resolveApp(app) : null
+  // Refused before the folder is bound to it: every later deploy would send its id, and fail the same way.
+  if (named?.kind && named.kind !== 'code') {
+    throw new UsageError(`${named.slug} is a Chat App, and a folder deploys to a Custom App`, '`frontera app list` names the Apps; pass a Custom App\'s slug to `--app`, or leave `--app` out to deploy to the folder\'s own')
+  }
+  const ensured = named
+    ? { ...named, created: false }
+    : await client.ensureApp(project.slug, project.displayName, known.id ?? project.fallbackAppId, { icon: project.icon })
+  bindApp(project.root, target, ensured.id)
+  const created = ensured.created ? createdApp(ensured.slug, known.id ? 'gone' : known.elsewhere || project.fallbackAppId ? 'elsewhere' : 'first') : null
+  if (created) ctx.output.note(`  ${created}`)
+  // The platform owns the name once the App exists (App settings renames it); the folder's name only creates one.
+  else if (ensured.slug !== project.slug) ctx.output.note(`  bound to the App ${ensured.slug} here: this folder's own name, ${project.slug}, names an App only on its first deploy to a workspace and never renames one (rename it in Apps, App settings)`)
+  return { id: ensured.id, slug: ensured.slug, created, target }
+}
+
+/**
+ * What a creation says: plain for a folder's first deploy anywhere. A folder
+ * that has an App elsewhere, or had one here, gets the way back too, since
+ * this workspace may hold its App under another name.
+ */
+function createdApp(slug: string, before: 'first' | 'gone' | 'elsewhere'): string {
+  if (before === 'first') return `created the App ${slug} in this workspace`
+  const why = before === 'gone' ? ': the App this folder deployed to here is gone' : ', this folder\'s first deploy here (it has deployed to other workspaces)'
+  return `created a new App ${slug} in this workspace${why}. `
+    + 'If this workspace already had the App under another name, deploy to that one instead with `frontera app deploy --app <slug>` (`frontera app list` names them) '
+    + `and archive ${slug} in Apps. A deploy never renames an App: rename one in Apps, App settings.`
 }

package/src/commands/app/unpin.ts

@@ -20,7 +20,7 @@ export const appUnpin: Command = {
     if (!reason?.trim()) throw new UsageError('unpinning needs --reason', 'frontera app unpin --reason "why production may move again"')
     const project = requireProjectFrom(ctx)
     const client = new AppsApi(ctx.apiUrl, ctx.token)
-    const app = await projectApp(client, project)
+    const app = await projectApp(ctx, client, project)
     const res = await client.unpin(app.id, reason)
     return { data: { app: app.slug, appId: app.id, ...res }, text: `Unpinned ${app.slug}: production keeps serving ${res.productionLabel ?? res.production ?? 'what it serves'}, and promotion works again` }
   },

package/src/commands/app/versions.ts

@@ -17,7 +17,7 @@ export const appVersions: Command = {
   async run(ctx) {
     const project = requireProjectFrom(ctx)
     const client = new AppsApi(ctx.apiUrl, ctx.token)
-    const app = await projectApp(client, project)
+    const app = await projectApp(ctx, client, project)
     const versions = await client.listVersions(app.id)
 
     return {

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

@@ -26,6 +26,19 @@ interface KnowledgeRow {
 }
 
 
+/**
+ * These commands manage the knowledge bases Agents attach. The Knowledge app's
+ * bases (organization and workspace) are another thing with no command or
+ * project file, and no local runtime runs the app. Said only where the
+ * platform runs the app: elsewhere there is no such base to mistake for one.
+ */
+async function knowledgeAppNote(api: PlatformApi): Promise<string> {
+  return (await api.knowledgeAppRuns())
+    ? ' A knowledge base from the Knowledge app is not one of these: it runs on the platform only, not on a local runtime. '
+      + 'Choose it for an Agent on the platform, under the Agent\'s Knowledge page, and test that Agent there.'
+    : ''
+}
+
 /** Accept a base by name or id — `knowledge list` shows both. */
 async function resolveKnowledgeRef(client: PlatformApi, ref: string): Promise<string> {
   const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
@@ -38,7 +51,7 @@ async function resolveKnowledgeRef(client: PlatformApi, ref: string): Promise<st
 
   throw new CliError(`no knowledge base named "${ref}"`, {
     code: 'NOT_FOUND',
-    hint: `known bases: ${rows.map((k) => k.name).filter(Boolean).join(', ') || '(none)'}`,
+    hint: `known bases: ${rows.map((k) => k.name).filter(Boolean).join(', ') || '(none)'}.${await knowledgeAppNote(client)}`,
   })
 }
 
@@ -61,7 +74,7 @@ const list: Command = {
       data: rows,
       text:
         rows.length === 0
-          ? 'No knowledge bases in this workspace.'
+          ? `No knowledge bases in this workspace.${await knowledgeAppNote(api)}`
           : // NAME first: it is the value `knowledge sources` takes, not the id.
             // No `displayName` on these rows, so a column for it was always
             // blank and shifted the description out of alignment.

package/src/commands/local/check.ts

@@ -12,7 +12,7 @@ import { appPulledAsIs, keepBuildWrittenFiles } from '../../local/local-app-pull
 import { setAsideCopyPaths } from '../../local/local-app-sdk-paths'
 import { repullRefFor } from '../../local/local-app-code'
 import { customAppFolders } from '../../local/local-apps'
-import { readBaseline, restoreBaseline, saveBaseline } from '../../local/local-db-snapshot'
+import { endCheckBaseline, readBaseline, restoreBaseline, restoreCutOffCheck, saveBaseline } from '../../local/local-db-snapshot'
 import { localIngestApi, settleKnowledge, type KnowledgeSettle } from '../../local/local-knowledge-ingestion'
 import { localProject, type LocalProject } from '../../local/local-project'
 import { projectSecretLines } from '../../local/local-project-secrets'
@@ -53,12 +53,12 @@ import { flagBool, flagString, type Command, type CommandContext } from '../type
  *
  * The tests write for real (a workflow test always does, as does an Agent
  * case with `realActions` or a `decision`), so after the apply the database
- * is kept as a baseline (`local-db-snapshot.ts`, taken again only when what
- * is applied changed), and after the tests it is restored: each check starts
- * from the data the project's files make. The run history (conversations,
- * runs, evaluations) is kept across it (`local-history-carry.ts`), so one
- * check's results can be compared with the last. `--keep-state` keeps what the
- * tests wrote, to look at it.
+ * is kept as a baseline (`local-db-snapshot.ts`, a new copy every check), and
+ * after the tests it is restored: the tests' writes are rolled back, and what
+ * was written before the check (a person's sign-up, an App's records) stays.
+ * The run history (conversations, runs, evaluations) is kept across it
+ * (`local-history-carry.ts`), so one check's results can be compared with the
+ * last. `--keep-state` keeps what the tests wrote, to look at it.
  *
  * Knowledge documents are read by a background job whose work lands in the
  * database: before the baseline and the tests, the check waits (bounded)
@@ -104,10 +104,8 @@ export function blockedBy(step: CheckStepName, failed: ReadonlySet<CheckStepName
 /** What `--skip` may leave out: the runtime and the apply are the gate itself. */
 const SKIPPABLE: readonly CheckStepName[] = ['typecheck', 'unit', 'apps', 'agents', 'workflows']
 
-/** What became of the tests' writes: rolled back to the applied baseline, kept, or not rolled back and why. */
+/** What became of the tests' writes: rolled back to the baseline taken before them, kept, or not rolled back and why. */
 export interface CheckTestData {
-  /** taken: a new baseline after this apply; reused: the stored one is of this build. */
-  baseline?: 'taken' | 'reused'
   rolledBack: boolean
   /** --keep-state */
   kept?: boolean
@@ -406,6 +404,13 @@ async function check(ctx: CommandContext) {
       continue
     }
     if (step === 'apply') {
+      // A check cut off before its rollback left its tests' writes: its baseline goes back before this apply (within the hour).
+      const before = readState(project)
+      if (before?.credentials && running(project)) {
+        const cut = await restoreCutOffCheck(project, before.credentials.organizationId, { serviceAnswers: () => waitForDatabaseReady(`http://127.0.0.1:${before.ports.service}`) })
+        if (cut?.left) ctx.output.note(`── test data: ${cut.note}`)
+        else if (cut) ctx.output.note(`── test data: the last \`frontera local check\` stopped before it rolled back its tests’ writes, ${cut.ok ? 'so that is done first' : 'and they couldn’t be rolled back now'}: ${cut.note}`)
+      }
       say(step, 'frontera local dev --once')
       // Which Agents serve customers: an operating.json leaves an Agent out of the built-in Chat (X4).
       if (customerFacing.length) ctx.output.note(`   note: ${customerFacingWords(customerFacing)}`)
@@ -448,9 +453,9 @@ async function check(ctx: CommandContext) {
       if (state?.credentials && running(project) && testsWillRun()) {
         if (keepState) testData = { rolledBack: false, kept: true, note: 'kept what the tests write (--keep-state)' }
         else {
-          const saved = await saveBaseline(project, state.credentials.organizationId, { serviceAnswers: () => waitForDatabaseReady(`http://127.0.0.1:${state.ports.service}`) })
+          const saved = await saveBaseline(project, state.credentials.organizationId, { serviceAnswers: () => waitForDatabaseReady(`http://127.0.0.1:${state.ports.service}`) }, 'check')
           baselineReady = saved.ok
-          if (saved.ok) testData = { baseline: saved.took ? 'taken' : 'reused', rolledBack: false, note: saved.note }
+          if (saved.ok) testData = { rolledBack: false, note: saved.note }
           else testData = { rolledBack: false, note: `not rolled back: ${saved.note}` }
           ctx.output.note(`   test data: ${saved.ok ? saved.note : `couldn’t keep a baseline, so what the tests write stays: ${saved.note}`}`)
         }
@@ -666,7 +671,10 @@ async function check(ctx: CommandContext) {
         secretNotes.push(...lost)
       }
     }
-  } else if (testData?.kept && testsRan) ctx.output.note('── test data: the tests’ writes were kept (--keep-state); the next `frontera local check` rolls them back')
+  } else if (testData?.kept && testsRan) ctx.output.note('── test data: the tests’ writes were kept (--keep-state); they stay: the next `frontera local check` rolls back only its own tests’ writes')
+  // A baseline taken for tests that then did not run holds nothing of theirs to put back.
+  const ended = readState(project)
+  if (baselineReady && !testsRan && ended?.credentials) endCheckBaseline(project, ended.credentials.organizationId)
   const testDataField = { ...(testData && testsRan ? { testData } : {}), ...(customerFacing.length ? { customerFacing } : {}) }
 
   if (flagBool(ctx, 'stop')) {

package/src/commands/local/data.ts

@@ -114,7 +114,7 @@ async function loadCommand(ctx: Parameters<Command['run']>[0]) {
   const organizationId = state.credentials.organizationId
   const snapshot = !flagBool(ctx, 'no-snapshot')
   if (snapshot) {
-    const saved = await ctx.output.task('Saving the records first', () => saveBaseline(project, organizationId, { serviceAnswers: () => waitForDatabaseReady(serviceUrl) }, true))
+    const saved = await ctx.output.task('Saving the records first', () => saveBaseline(project, organizationId, { serviceAnswers: () => waitForDatabaseReady(serviceUrl) }, 'data'))
     if (!saved.ok) throw new CliError(`the records could not be saved first, so nothing was loaded: ${saved.note}`, { code: 'LOCAL_SNAPSHOT_FAILED', hint: '`--no-snapshot` loads without saving them' })
   }
   const persona = await actAsLocalPersona({ meta: { noun: 'action', verb: 'submit' }, cwd: ctx.cwd, apiUrl: serviceUrl, wanted: 'submitter' })

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

@@ -489,7 +489,7 @@ async function status(ctx: CommandContext) {
       docs: docsStatus(project, { mode: state.mode, platformVersion: state.platformVersion, platformSource: readConfig(project)?.platformSource }),
       notices: projectNotices(project.root),
       // The App dev servers running against this runtime, with their ports: `frontera local stop` stops them.
-      appDevServers: devServers.map((s) => ({ app: s.slug, port: s.port, url: s.url, pid: s.pid, startedAt: s.startedAt, startedBy: s.owner?.kind ?? 'hand', ...(s.owner ? { ownerPid: s.owner.pid } : {}) })),
+      appDevServers: devServers.map((s) => ({ app: s.slug, port: s.port, url: s.url, pid: s.pid, startedAt: s.startedAt, startedBy: s.owner?.kind ?? 'hand', ...(s.owner && 'pid' in s.owner ? { ownerPid: s.owner.pid } : {}) })),
       // Knowledge documents pending or processing with no ingestion behind them, each with its fix.
       ...(stuck.length ? { knowledgeStuck: stuck } : {}),
       // On the runtime, not in the files: each with what fixes it (`local dev` archives an Agent or workflow whose file was deleted).