@frontera-sdk/cli 1.52.39 → 1.52.41

package/src/commands/local/sync.ts

@@ -1,10 +1,12 @@
 import { existsSync, readFileSync, writeFileSync } from 'node:fs'
-import { basename } from 'node:path'
+import { basename, join } from 'node:path'
 
 import { CliError, UsageError } from '../../errors'
 import { canPrompt, promptSecret } from '../../prompt'
 import { allTargets } from '../../local/local-dev-sync'
 import { pullDocuments, type DocumentsPulled } from '../../local/local-knowledge-documents'
+import { appCodeLine, appCodeVersion, earlierPullShadows, pullAppCode, type AppCodePulled } from '../../local/local-app-code'
+import { remakeLines, remakeReason, remakeSampleData, type SampleRemake } from '../../local/local-sample-remake'
 import { lessonsToPropose, pullLessons, type LessonsPulled } from '../../local/local-lessons'
 import { analyticsNeeded, connectionsNeeded, documentationNeeded, standInPath, writePlatformOnly, writeStandIns } from '../../local/local-stand-ins'
 import { localProject, type LocalProject } from '../../local/local-project'
@@ -36,6 +38,8 @@ import { readWorkspace, type SyncSource } from '../../local/local-sync-remote'
 import { buildStatusText, projectBuildSummary } from '../../local/local-build-summary'
 import { kindTitle } from '../../local/local-sync-names'
 import { describeUnresolved } from '../../local/local-sync-refs'
+import { blockers, type Blocker, type Need } from '../../local/local-portability'
+import { hardCodedIdLine, hardCodedObjectTypeIds, platformObjectTypeIds } from '../../local/local-function-ids'
 import {
   directoryOf,
   dropBase,
@@ -555,8 +559,11 @@ const pull = async (ctx: CommandContext) => {
   }
   const named = ctx.positional.slice(1)
   const byRef = new Map(remote.items.map((i) => [i.ref, i]))
-  // Knowledge bases whose documents come too: opt-in, as documents can be large and sensitive.
+  // Knowledge bases whose documents come too: every base this pull writes (a pulled Agent answers from them),
+  // unless --no-documents; --documents names more, already in the project, to bring theirs again.
+  const noDocuments = flagBool(ctx, 'no-documents')
   const documents = refsFlag(ctx, 'documents').map((r) => r.replace(/^knowledge\//, ''))
+  if (noDocuments && documents.length) throw new UsageError('--documents and --no-documents ask opposite things', 'leave one out: --no-documents pulls no documents; --documents <name> pulls those bases\' documents')
   const noBase = documents.filter((n) => !byRef.has(`knowledge/${n}`))
   if (noBase.length) throw new UsageError(`no knowledge base ${noBase.join(', ')} in the workspace`, '--documents takes knowledge base names, as `--preview` lists them (knowledge/<name>)')
   const byPlan = new Map(plan.map((p) => [p.ref, p]))
@@ -608,6 +615,9 @@ const pull = async (ctx: CommandContext) => {
   const replaced = [...take].filter((r) => status.get(r) === 'edited' || status.get(r) === 'deleted-local')
   const merge = new Set([...take].filter((r) => status.get(r) === 'conflict'))
   let base = lock?.workspace === link.workspace ? lock : null
+  // An App folder an earlier pull left unchanged with package.json and bun.lock disagreeing (an older CLI's repair):
+  // told now, before this pull rewrites its frontera.lock entry, so its code is brought again in its place below.
+  const earlierPull = new Set([...take].filter((r) => r.startsWith('app/') && earlierPullShadows(project.root, r.slice('app/'.length)).length))
   const readFromBase = (path: string) => readBase(project.root, path)
   const removedDeleted: string[] = []
   for (const [refs, deleteFiles] of [[deleteHere, true], [keepLocal, false]] as const) {
@@ -622,7 +632,8 @@ const pull = async (ctx: CommandContext) => {
   const conflictedRefs = new Set(result.conflicted.map((c) => c.ref))
   writeBase(project.root, items.filter((i) => !conflictedRefs.has(i.ref)), base)
   const pulled = [...take].filter((r) => !conflictedRefs.has(r))
-  // Documents asked for land beside each base's knowledge.json; `local dev` uploads them.
+  // Documents land beside each base's knowledge.json; `local dev` uploads them. The bases pulled now bring theirs.
+  if (!noDocuments) for (const r of pulled) if (r.startsWith('knowledge/') && !documents.includes(r.slice('knowledge/'.length))) documents.push(r.slice('knowledge/'.length))
   const docs: Record<string, DocumentsPulled> = {}
   if (documents.length) {
     const client = sourceFor(project, link).workspace
@@ -631,6 +642,34 @@ const pull = async (ctx: CommandContext) => {
       docs[n] = id ? await pullDocuments(project.root, client, { name: n, id }) : { written: [], present: [], skipped: [], failed: ['its id is not in the fetched snapshot: fetch again'] }
     }
   }
+  // Each pulled Custom App's code comes too, into apps/<slug>/, unless --no-app-code; a folder already there is kept,
+  // except one an earlier pull left unchanged whose package.json and bun.lock disagree: the deployed source replaces it.
+  const appCode: AppCodePulled[] = []
+  if (!flagBool(ctx, 'no-app-code')) {
+    const wantCode = pulled.flatMap((r) => {
+      if (!r.startsWith('app/')) return []
+      const slug = r.slice('app/'.length)
+      const it = byRef.get(r)
+      const version = appCodeVersion(project.root, slug, it?.version)
+      const replaceEarlierPull = earlierPull.has(r)
+      return it?.id && version && (replaceEarlierPull || !existsSync(join(project.root, 'apps', slug))) ? [{ slug, id: it.id, version, ...(replaceEarlierPull ? { replaceEarlierPull } : {}) }] : []
+    })
+    if (wantCode.length) {
+      const client = sourceFor(project, link).workspace
+      for (const app of wantCode) appCode.push(await pullAppCode(project.root, client, app))
+    }
+  }
+  // Sample data made again when the pull brought Blueprint items, or an older generator made it, unless --keep-sample-data.
+  let sampleData: SampleRemake | null = null
+  let sampleDataError: string | null = null
+  const remakeWhy = flagBool(ctx, 'keep-sample-data') ? null : remakeReason(project.root, pulled.some((r) => r.startsWith('blueprint/')))
+  if (remakeWhy) {
+    try {
+      sampleData = await remakeSampleData(project.root, remakeWhy, new Date(), 'pull')
+    } catch (err) {
+      sampleDataError = (err as Error).message.slice(0, 200)
+    }
+  }
   // Built-in connections the project's items use get a declared stand-in (`local-stand-ins.ts`).
   const held = new Set(Object.keys(readLock(project.root)?.items ?? {}))
   const heldItems = remote.items.filter((i) => held.has(i.ref))
@@ -667,6 +706,11 @@ const pull = async (ctx: CommandContext) => {
     `  ${n}: ${plural(d.written.length, 'document')} written${d.present.length ? `, ${d.present.length} already here` : ''}${d.skipped.length ? `, ${d.skipped.length} not a kind local dev uploads (${d.skipped.join(', ')})` : ''}`,
     ...d.failed.map((f) => `      could not read ${f}`),
   ])
+  // What won't run locally as pulled, with the reason and whose fix it is: the checks `local dev` applies.
+  const wontRun = wontRunLocally(project.root, pulled.map((r) => byRef.get(r)!).filter(Boolean))
+  // Functions whose code names an object type by the workspace's id (`local dev` adapts their bundle here).
+  const platformIds = platformObjectTypeIds(directoryOf(snapshot))
+  const hardCoded = pulled.flatMap((r) => (r.startsWith('function/') && byRef.get(r) ? hardCodedObjectTypeIds(byRef.get(r)!.files, platformIds) : []))
   // The workspace's copies beside conflicted files are not project files; `local dev` ignores them.
   const projectWritten = result.written.filter((p) => !p.endsWith(WORKSPACE_SUFFIX))
   const conflictLines = result.conflicted.flatMap((c) => [
@@ -689,8 +733,12 @@ const pull = async (ctx: CommandContext) => {
       warnings: remote.warnings,
       bases,
       documents: docs,
+      appCode,
+      ...(sampleData ? { sampleData: { why: sampleData.why, options: sampleData.options, datasets: sampleData.written.map((d) => d.dataset), kept: sampleData.kept.map((d) => d.dataset) } } : {}),
       ...(lessons ? { lessons } : {}),
       ...(standIns.written.length ? { standIns: standIns.written } : {}),
+      ...(wontRun.length ? { wontRunLocally: wontRun } : {}),
+      ...(hardCoded.length ? { hardCodedIds: hardCoded } : {}),
     },
     text: [
       pulled.length ? `Pulled ${plural(pulled.length, 'item')} from ${link.workspaceName ?? link.workspace}:` : result.conflicted.length || waiting.length || deleteHere.length || keepLocal.length || lessons ? '' : 'Nothing to pull.',
@@ -703,11 +751,28 @@ const pull = async (ctx: CommandContext) => {
             'See them with `frontera local sync diff <ref>`; settle with `resolve <ref> --keep workspace|mine`, or edit the file and `resolve <ref> --edited`.',
           ]
         : []),
+      ...(wontRun.length
+        ? [
+            '',
+            `Won’t run locally as pulled (${plural(wontRun.length, 'item')}; \`local dev\` leaves ${wontRun.length === 1 ? 'it' : 'them'} out and says so):`,
+            ...wontRun.flatMap((w) => [`  ${w.ref}: ${w.reason}`, `      fix: ${w.fix} — ${w.owner}`]),
+          ]
+        : []),
+      ...(hardCoded.length
+        ? [
+            '',
+            'Object type ids hard-coded in Function code (the workspace’s ids; `local dev` deploys these Functions here with this runtime’s ids in their place and leaves the files as they are):',
+            ...hardCoded.map((h) => `  warning: ${hardCodedIdLine(h)}`),
+          ]
+        : []),
       ...(waiting.length ? ['', `Not pulled, conflicts to resolve first: ${waiting.join(', ')}`] : []),
       ...(deleteHere.length ? ['', `Deleted here, as in the workspace: ${deleteHere.join(', ')}`] : []),
       ...(keepLocal.length ? ['', `Kept as this project’s own: ${keepLocal.join(', ')}`] : []),
       ...(projectWritten.length ? ['', `Wrote ${plural(projectWritten.length, 'file')}; \`frontera local dev\` applies them.`] : []),
       ...(docLines.length ? ['', 'Documents (uploaded to the local knowledge base by `frontera local dev`):', ...docLines] : []),
+      ...(sampleData ? ['', ...remakeLines(sampleData)] : []),
+      ...(sampleDataError ? ['', `Sample data couldn’t be made again (${sampleDataError}); \`frontera local data --synthetic\` tries again`] : []),
+      ...(appCode.length ? ['', 'App code (built by `frontera local dev`; `app_dev` runs it against the local runtime):', ...appCode.map(appCodeLine)] : []),
       ...lessonLines,
       ...standInLines,
       ...remote.warnings.map((w) => `Could not read ${w}`),
@@ -718,6 +783,23 @@ const pull = async (ctx: CommandContext) => {
   }
 }
 
+/**
+ * The pulled items that won't run on the local runtime as they are, each with
+ * why, the fix and whose fix it is. A file a Function imports that the project
+ * now has (written by hand, or by another pull) no longer counts.
+ */
+export function wontRunLocally(root: string, items: ReadonlyArray<Pick<RemoteItem, 'ref' | 'portability'>>): Array<Blocker & { ref: string }> {
+  const present = (stem: string) => ['', '.ts', '.tsx', '.mts', '.js', '.mjs', '/index.ts', '/index.js'].some((ext) => existsSync(join(root, `${stem}${ext}`)))
+  return items.flatMap((it) => {
+    const needs = (it.portability?.needs ?? []).flatMap((n): Need[] => {
+      if (n.kind !== 'imports-missing') return [n]
+      const paths = n.paths.filter((p) => !present(p))
+      return paths.length ? [{ kind: 'imports-missing', paths }] : []
+    })
+    return blockers(needs).map((b) => ({ ref: it.ref, ...b }))
+  })
+}
+
 /** Everything about one item for `diff` and `resolve`: the plan row, the workspace's version, and the three-way merge. */
 async function itemState(project: LocalProject, link: SyncLink, ref: string) {
   // Offline, as diff and resolve are: a lost base comes back only from an unchanged copy here (pull reads the platform).
@@ -727,7 +809,7 @@ async function itemState(project: LocalProject, link: SyncLink, ref: string) {
   const item = remote.items.find((i) => i.ref === ref) ?? null
   const entry = lock?.workspace === link.workspace ? lock.items[ref] : undefined
   if (!row && !item && !entry) throw new UsageError(`not in the workspace or the project: ${ref}`, 'list items with `frontera local sync pull --preview`')
-  const paths = [...new Set([...Object.keys(item?.files ?? {}), ...Object.keys(entry?.files ?? {}), ...(entry?.conflict?.files ?? [])])].sort()
+  const paths = [...new Set([...Object.keys(item?.files ?? {}), ...Object.keys(entry?.files ?? {}), ...(entry?.conflict?.files ?? [])])].sort((a, b) => (String(a) < String(b) ? -1 : String(a) > String(b) ? 1 : 0))
   const base = baseFiles(entry, (p) => readBase(project.root, p))
   const local = localFiles(project.root, paths)
   const theirs = item?.files ?? {}
@@ -901,7 +983,17 @@ export const localSync: Command = {
       description: 'string',
       migration: 'string',
       documents: 'string',
+      'no-documents': 'boolean',
+      'no-app-code': 'boolean',
+      'keep-sample-data': 'boolean',
       lessons: 'boolean',
+      release: 'string',
+      force: 'boolean',
+      reason: 'string',
+      evals: 'boolean',
+      renders: 'boolean',
+      screenshots: 'string',
+      trace: 'string',
     },
     aliases: { t: 'title', d: 'description' },
     summary: 'Link the project to a platform workspace, pull and merge what you choose, and propose changes back',
@@ -913,7 +1005,10 @@ export const localSync: Command = {
       'frontera local sync pull --preview',
       'frontera local sync pull agent/support-concierge workflow/return-label',
       'frontera local sync pull --kinds blueprint,workflows',
-      'frontera local sync pull knowledge/faq --documents faq',
+      'frontera local sync pull knowledge/faq',
+      'frontera local sync pull --kinds knowledge --no-documents',
+      'frontera local sync pull --documents faq',
+      'frontera local sync pull app/ops-console --no-app-code',
       'frontera local sync pull agent/support-concierge --lessons',
       'frontera local sync diff agent/support-concierge',
       'frontera local sync resolve agent/support-concierge --keep workspace',
@@ -924,12 +1019,14 @@ export const localSync: Command = {
       'frontera local sync push agent/support-concierge -t "New greeting"',
       'frontera local sync push --documents faq -t "Updated returns policy"',
       'frontera local sync request',
+      'frontera local sync push --release desk=1.4.0 -t "Release the desk"',
+      'frontera local sync request evidence --evals --renders',
       'frontera local sync request apply',
+      'frontera local sync request apply --force --reason "hotfix, checked by hand"',
       'frontera local sync request close',
       'frontera local sync disconnect --forget-link',
     ],
     offline: true,
-    internal: true,
   },
   async run(ctx) {
     const action = ctx.positional[0]

package/src/commands/mcp/serve.ts

@@ -0,0 +1,34 @@
+import { localProject } from '../../local/local-project'
+import { stopStartedDevServers } from '../../mcp/mcp-apps'
+import { serveMcp } from '../../mcp/mcp-protocol'
+import { MCP_INFO, mcpTools } from '../../mcp/mcp-server'
+import type { Command } from '../types'
+
+/**
+ * Frontera as one MCP server on stdio for the coding agents working in a
+ * project: the local runtime (status, apply, chat with an Agent, traces,
+ * tests, workflows, records), the documentation, App rendering and, with
+ * Forge open, a browser the person watches. Registered once per project as
+ * `frontera` in `.mcp.json`, `.cursor/mcp.json`, `opencode.json` and
+ * `.codex/config.toml`. Every tool takes an optional `project` folder, so
+ * one connection also serves the other projects the agent works in. Nothing
+ * but protocol goes to stdout.
+ */
+export const mcpServe: Command = {
+  meta: {
+    noun: 'mcp',
+    verb: '',
+    args: [],
+    flags: {},
+    summary: 'Serve Frontera to coding agents over MCP (stdio): runtime, docs, Apps and the Forge browser',
+    examples: ['frontera mcp'],
+    offline: true,
+  },
+  async run(ctx) {
+    await serveMcp({ info: MCP_INFO, tools: mcpTools(localProject(ctx.cwd), ctx.cwd) })
+    // The connection closed: the App dev servers this session started stop with it (each also watches this process).
+    stopStartedDevServers()
+    // The stream is the protocol: exit here, before the CLI renders a result onto it.
+    process.exit(0)
+  },
+}

package/src/commands/registry.ts

@@ -12,11 +12,17 @@ import { appSave } from './app/save'
 import { appDeploy } from './app/deploy'
 import { appPromote } from './app/promote'
 import { appVersions } from './app/versions'
+import { appChecks } from './app/checks'
+import { appDeployments } from './app/deployments'
+import { appRollback } from './app/rollback'
+import { appUnpin } from './app/unpin'
 import { appSdk } from './app/sdk'
 import { appDev } from './app/dev'
 import { blueprintList } from './blueprint/list'
 import { blueprintGet } from './blueprint/get'
+import { blueprintObjectSetsList } from './blueprint/object-sets'
 import { blueprintInstance, blueprintQuery } from './blueprint/query'
+import { blueprintMetric } from './blueprint/metric'
 import { blueprintGenerateTypes } from './blueprint/generate-types'
 import { blueprintAuthoringCommands } from './blueprint/authoring'
 import { blueprintDeclarativeCommands } from './blueprint/declarative'
@@ -47,6 +53,8 @@ import { kitCommands } from './kit/index-commands'
 import { workspaceCommands } from './workspace/index-commands'
 import { forgeCommands } from './forge/index-commands'
 import { localCommands } from './local/index-commands'
+import { localSnapshot } from './local/snapshot'
+import { mcpServe } from './mcp/serve'
 
 /**
  * Flags every command accepts. Declared once so a caller never has to wonder
@@ -88,6 +96,8 @@ export const COMMANDS: readonly Command[] = [
   ...workspaceCommands,
   ...forgeCommands,
   ...localCommands,
+  localSnapshot,
+  mcpServe,
 
   appInit,
   appList,
@@ -96,6 +106,10 @@ export const COMMANDS: readonly Command[] = [
   appSave,
   appDeploy,
   appPromote,
+  appRollback,
+  appUnpin,
+  appDeployments,
+  appChecks,
   appVersions,
   appSdk,
   appDev,
@@ -119,7 +133,9 @@ export const COMMANDS: readonly Command[] = [
   // Reads, next to the other two reads: the authoring verbs below all report
   // success without proving anything came back, and these are what prove it.
   blueprintQuery,
+  blueprintMetric,
   blueprintInstance,
+  blueprintObjectSetsList,
   blueprintGenerateTypes,
   // Authoring is no longer reserved: the organization API key (`sk-org-`) reaches the
   // organization-level shared draft, which is what these verbs were waiting on.
@@ -151,8 +167,21 @@ export function findCommand(noun: string, verb: string | undefined): Command | n
   )
 }
 
+/**
+ * The local loop: `frontera local …` (a runtime on this machine, applying the
+ * project, its tests and its gate) and `frontera mcp` (the same for a coding
+ * agent). Listed together in help, under one heading, after the platform's
+ * nouns.
+ */
+export const LOCAL_DEVELOPMENT_NOUNS = ['local', 'mcp'] as const
+
+/** Whether a command is in the top-level help, `help --json` and the generated reference. */
+export function isListed(meta: CommandMeta): boolean {
+  return !meta.internal
+}
+
 export function nouns(includeInternal = false): string[] {
-  return [...new Set(COMMANDS.filter((c) => includeInternal || !c.meta.internal).map((c) => c.meta.noun))]
+  return [...new Set(COMMANDS.filter((c) => includeInternal || isListed(c.meta)).map((c) => c.meta.noun))]
 }
 
 /**
@@ -183,6 +212,8 @@ const NOUN_SUMMARY: Readonly<Record<string, string>> = {
   kit: 'Optional project-local Frontera skills for Codex and Claude Code',
   workspace: 'Workspaces here — the ids --workspace takes',
   forge: 'Forge — the local daemon the desktop app talks to',
+  mcp: 'Frontera for coding agents — runtime, docs, Apps, browser',
+  local: 'A runtime on this machine — apply, test and check the project',
 }
 
 export function nounSummary(noun: string): string {
@@ -308,8 +339,9 @@ export function renderHelp(): string {
   ]
 
   // Setup first and ungrouped: these are the two commands someone runs before
-  // any noun makes sense.
-  const setup = COMMANDS.filter((c) => c.meta.verb === '' && !c.meta.internal)
+  // any noun makes sense. `frontera mcp` is listed with the local loop instead.
+  const local = new Set<string>(LOCAL_DEVELOPMENT_NOUNS)
+  const setup = COMMANDS.filter((c) => c.meta.verb === '' && isListed(c.meta) && !local.has(c.meta.noun))
   if (setup.length > 0) {
     lines.push('', heading('Getting started'))
     lines.push(
@@ -317,8 +349,8 @@ export function renderHelp(): string {
     )
   }
 
-  for (const noun of nouns()) {
-    const group = COMMANDS.filter((c) => c.meta.noun === noun && c.meta.verb !== '')
+  for (const noun of nouns().filter((n) => !local.has(n))) {
+    const group = COMMANDS.filter((c) => c.meta.noun === noun && c.meta.verb !== '' && isListed(c.meta))
     if (group.length === 0) continue
 
     lines.push('', `${heading(accent(`frontera ${noun}`))}  ${dim(nounSummary(noun))}`.trimEnd())
@@ -340,6 +372,13 @@ export function renderHelp(): string {
     }
   }
 
+  // The local loop, as one group: every `frontera local` verb, then `frontera mcp`.
+  const localGroup = COMMANDS.filter((c) => local.has(c.meta.noun) && isListed(c.meta) && !c.meta.reserved)
+  if (localGroup.length > 0) {
+    lines.push('', `${heading('Local development')}  ${dim('a runtime on this machine, for you and your coding agent')}`)
+    lines.push(...definitions(localGroup.map((c) => [usage(c.meta).replace(/^frontera /, ''), c.meta.summary] as const), { indent: 4 }))
+  }
+
   lines.push(
     ...GLOBAL_SECTION,
     '',
@@ -398,6 +437,8 @@ export const SESSION_LANE_HELP =
 export function renderCommandHelp(meta: CommandMeta): string {
   const width = terminalWidth()
   const lines = [accent(usage(meta)), '', ...wrap(meta.summary, width)]
+  // A paragraph that starts indented is code, printed as written.
+  for (const paragraph of meta.details ?? []) lines.push('', ...(paragraph.startsWith('  ') ? paragraph.split('\n') : wrap(paragraph, width)))
 
   if (meta.reserved) {
     lines.push('', ...wrap(`Not available yet: ${meta.reserved}`, width).map(dim))
@@ -435,7 +476,7 @@ export function renderCommandHelp(meta: CommandMeta): string {
   // Command flags first, then the ones every command shares — what is specific
   // to this command is what the reader came for.
   const shared = new Set(Object.keys(GLOBAL_FLAGS))
-  const own = Object.keys(spec).filter((f) => !shared.has(f)).sort()
+  const own = Object.keys(spec).filter((f) => !shared.has(f)).sort((a, b) => (String(a) < String(b) ? -1 : String(a) > String(b) ? 1 : 0))
   const short = Object.entries(aliasesFor(meta)).reduce<Record<string, string>>((acc, [s, long]) => {
     acc[long] = s
     return acc
@@ -445,7 +486,7 @@ export function renderCommandHelp(meta: CommandMeta): string {
     lines.push('', heading('Flags'))
     lines.push(
       ...definitions(
-        own.map((f) => [flagUsage(f, spec[f]!, short[f]), describeFlag(f)] as const),
+        own.map((f) => [flagUsage(f, spec[f]!, short[f]), describeFlag(f, meta.flagHelp)] as const),
       ),
     )
   }
@@ -471,6 +512,8 @@ export interface CommandDescriptor {
   verb: string
   usage: string
   summary: string
+  /** The paragraphs `--help` prints under the summary. */
+  details?: string[]
   available: boolean
   unavailableReason?: string
   args: Array<{ name: string; required: boolean; description: string }>
@@ -497,16 +540,17 @@ export function describeCommand(meta: CommandMeta): CommandDescriptor {
     verb: meta.verb,
     usage: usage(meta),
     summary: meta.summary,
+    ...(meta.details?.length ? { details: [...meta.details] } : {}),
     available: !meta.reserved,
     ...(meta.reserved ? { unavailableReason: meta.reserved } : {}),
     args: meta.args.map((a) => ({ ...a })),
     flags: Object.keys(spec)
-      .sort()
+      .sort((a, b) => (String(a) < String(b) ? -1 : String(a) > String(b) ? 1 : 0))
       .map((name) => ({
         name,
         type: spec[name]!,
         ...(short[name] ? { short: short[name]! } : {}),
-        description: describeFlag(name),
+        description: describeFlag(name, meta.flagHelp),
       })),
     examples: [...meta.examples],
     needsProject: Boolean(meta.needsProject),
@@ -516,7 +560,7 @@ export function describeCommand(meta: CommandMeta): CommandDescriptor {
 }
 
 export function describeCommands(noun?: string): CommandDescriptor[] {
-  return COMMANDS.filter((c) => (noun ? c.meta.noun === noun : !c.meta.internal)).map((c) => describeCommand(c.meta))
+  return COMMANDS.filter((c) => (noun ? c.meta.noun === noun : isListed(c.meta))).map((c) => describeCommand(c.meta))
 }
 
 /** Levenshtein distance, iterative with one row — enough for a typo check. */

package/src/commands/types.ts

@@ -21,9 +21,21 @@ export interface CommandMeta {
   verb: string
   args: readonly ArgSpec[]
   flags: FlagSpec
+  /**
+   * This command's wording for a flag whose shared description (`FLAG_HELP`)
+   * would mislead here: `local test --file` names a case file to run, not a
+   * document to send. Rare by design; a flag still needs its `FLAG_HELP` entry.
+   */
+  flagHelp?: Readonly<Record<string, string>>
   /** Short forms, e.g. `{ f: 'file' }` for `-f`. */
   aliases?: Readonly<Record<string, string>>
   summary: string
+  /**
+   * Paragraphs `--help` prints under the summary: a contract the command reads
+   * that no flag describes (the file it runs, the order it fills things in).
+   * Agents read --help before documentation, so what they must know is here.
+   */
+  details?: readonly string[]
   /** At least one, copy-pasteable. Agents read --help before documentation. */
   examples: readonly string[]
   /**
@@ -96,6 +108,8 @@ export interface CommandContext {
   token: string
   positional: string[]
   flags: Record<string, string | boolean>
+  /** Every value of a string flag given more than once (`flags` holds the last). */
+  repeated?: Record<string, string[]>
   output: Output
   /** Present when `meta.needsProject`. */
   project: AppProject | null
@@ -104,6 +118,8 @@ export interface CommandContext {
    * acting in. Undefined for a workspace key, which carries its own.
    */
   workspaceId?: string
+  /** Whether a person is at a terminal; `canPrompt()` when absent. Set by tests. */
+  interactive?: boolean
 }
 
 /**
@@ -114,6 +130,11 @@ export interface CommandContext {
 export interface CommandResult {
   data: unknown
   text: string
+  /**
+   * The exit code when it is not 0: a command whose result is a verdict (`local check --json`) renders it on
+   * stdout and still exits non-zero when the verdict is a failure. Errors are thrown, never returned.
+   */
+  exitCode?: number
 }
 
 export interface Command {
@@ -126,6 +147,14 @@ export function flagString(ctx: CommandContext, name: string): string | undefine
   return typeof v === 'string' ? v : undefined
 }
 
+/** Every value of a string flag, in the order given: `[]` when absent. */
+export function flagStrings(ctx: CommandContext, name: string): string[] {
+  const all = ctx.repeated?.[name]
+  if (all?.length) return [...all]
+  const one = flagString(ctx, name)
+  return one === undefined ? [] : [one]
+}
+
 export function flagBool(ctx: CommandContext, name: string): boolean {
   return ctx.flags[name] === true
 }

package/src/commands/workflow/archive.ts

@@ -0,0 +1,46 @@
+import { WorkflowApi } from '../../api/workflow-api'
+import type { Command } from '../types'
+import { requireSlug } from './push'
+
+/**
+ * Archive and restore: the reversible way a workflow leaves service. Every
+ * version and run stays; an archived workflow is left out of `workflow list`,
+ * nothing starts it (Agents, webhooks, schedules) and it takes no new version
+ * until it is restored. The slug stays taken while it is archived.
+ */
+export const workflowArchive: Command = {
+  meta: {
+    noun: 'workflow',
+    verb: 'archive',
+    args: [{ name: 'slug', required: true, description: 'workflow slug' }],
+    flags: {},
+    summary: 'Archive a workflow: nothing starts it, its versions and runs are kept (`workflow restore` puts it back)',
+    examples: ['frontera workflow archive hello'],
+  },
+
+  async run(ctx) {
+    const slug = requireSlug(ctx)
+    const result = await new WorkflowApi(ctx.apiUrl, ctx.token, ctx.workspaceId).archive(slug)
+    return {
+      data: result,
+      text: [`Archived workflow ${slug}: nothing starts it now; its versions and runs are kept.`, `  \`frontera workflow restore ${slug}\` puts it back`].join('\n'),
+    }
+  },
+}
+
+export const workflowRestore: Command = {
+  meta: {
+    noun: 'workflow',
+    verb: 'restore',
+    args: [{ name: 'slug', required: true, description: 'workflow slug' }],
+    flags: {},
+    summary: 'Put an archived workflow back into service, as it was',
+    examples: ['frontera workflow restore hello'],
+  },
+
+  async run(ctx) {
+    const slug = requireSlug(ctx)
+    const result = await new WorkflowApi(ctx.apiUrl, ctx.token, ctx.workspaceId).restore(slug)
+    return { data: result, text: `Restored workflow ${slug}.` }
+  },
+}

package/src/commands/workflow/get.ts

@@ -39,7 +39,8 @@ export const workflowGet: Command = {
       // Only when bound. An unbound workflow has no subject line to print, and
       // an empty one reads as a missing value rather than an absent concept.
       workflow.subjectApiName ? `  subject    ${workflow.subjectLabel ?? workflow.subjectApiName}` : '',
-      `  runs       ${workflow.runCount ?? 0}${workflow.lastRunStatus ? `, last ${workflow.lastRunStatus}` : ''}`,
+      // Live runs and test runs apart: a workflow tested twenty times and never live has 0 runs that count.
+      `  runs       ${workflow.runCount ?? 0} live${workflow.lastRunStatus ? `, last ${workflow.lastRunStatus}` : ''}${typeof workflow.testRunCount === 'number' ? ` · ${workflow.testRunCount} test` : ''}`,
     ].filter(Boolean)
 
     const versionTable = versions.length === 0

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

@@ -1,3 +1,4 @@
+import { workflowArchive, workflowRestore } from './archive'
 import { workflowCancel } from './cancel'
 import { workflowGet } from './get'
 import { workflowLineage } from './lineage'
@@ -6,6 +7,7 @@ import { workflowPromote } from './promote'
 import { workflowPush, workflowValidate } from './push'
 import { workflowRun } from './run'
 import { workflowRuns } from './runs'
+import { workflowWebhookTest } from './webhook-test'
 import type { Command } from '../types'
 
 /**
@@ -37,5 +39,8 @@ export const workflowCommands: readonly Command[] = [
   workflowRun,
   workflowRuns,
   workflowCancel,
+  workflowArchive,
+  workflowRestore,
   workflowLineage,
+  workflowWebhookTest,
 ]