@frontera-sdk/cli 1.52.39 → 1.52.41

package/src/local/local-dev-sync.ts

@@ -2,6 +2,7 @@ import { existsSync, lstatSync, readdirSync, readFileSync } from 'node:fs'
 import { basename, dirname, join, relative, resolve, sep } from 'node:path'
 
 import { agentIdentity, createFlags } from './local-agent-name'
+import { widerGrants, type WorkspaceGrant } from './local-workspace-grants'
 
 /**
  * What `frontera local dev` applies when a file in the solution changes.
@@ -196,7 +197,9 @@ export function allTargets(root: string): SyncTarget[] {
     if (depth > 6 || !existsSync(dir)) return
     let names: string[]
     try {
-      names = readdirSync(dir)
+      // Sorted: the order a directory lists its files in is the file system's (macOS sorts, Linux does not),
+      // and items of one kind are applied, and listed, in this order.
+      names = readdirSync(dir).sort()
     } catch {
       return
     }
@@ -296,10 +299,10 @@ export function commandFor(target: SyncTarget, profiles: SyncProfiles): string[]
   }
 }
 
-/** When the first command fails with `when`, run `then` instead. */
+/** When the first command fails with `when`, run `steps` instead. */
 export interface Fallback {
   when: RegExp
-  then: string[][]
+  steps: string[][]
 }
 
 /**
@@ -307,22 +310,26 @@ export interface Fallback {
  * Agent applied for the first time is created, then applied (`agent apply`
  * stages onto an existing draft); a dataset that exists already gets its CSV
  * as a new snapshot (`dataset create` refuses a name in use). A dataset with
- * no CSV that exists already has nothing more to load: an empty `then`.
+ * no CSV that exists already has nothing more to load: an empty `steps`.
  *
- * Only rows reach an existing dataset. A changed definition (columns, keys)
- * is a new revision of the dataset, which `local dev` does not make; after a
- * `frontera local reset` the definition is created as written.
+ * Only rows reach an existing dataset. A CSV with empty values a column of its
+ * revision does not allow is refused; `local dev` then cuts the dataset's next
+ * revision from it (`dataset revise`, which only widens nullability), binds the
+ * object types reading it to that revision and applies the Blueprint again. A
+ * column added, dropped or retyped is a new dataset, and stays refused.
  */
 export function fallbackFor(target: SyncTarget, profiles: SyncProfiles, root: string): Fallback | null {
   if (target.kind === 'agent') {
     // Created with its name, or every list reads the slug until it is published.
     const named = createFlags(agentIdentity(root, target.file))
-    return { when: /NOT_FOUND/, then: [['agent', 'create', target.slug, ...named, '--profile', profiles.workspace], commandFor(target, profiles)] }
+    return { when: /NOT_FOUND/, steps: [['agent', 'create', target.slug, ...named, '--profile', profiles.workspace], commandFor(target, profiles)] }
   }
+  // A workflow archived on the runtime takes no new version: restored, then pushed (the files say it is in service).
+  if (target.kind === 'workflow') return { when: /is archived, so it cannot/i, steps: [['workflow', 'restore', target.slug, '--profile', profiles.workspace], commandFor(target, profiles)] }
   if (target.kind === 'dataset') {
     const doc = datasetDocument(root, target)
     const upload = doc?.csv ? [['dataset', 'upload', doc.apiName, doc.csv, '--profile', profiles.organization]] : []
-    return { when: /already in use/i, then: upload }
+    return { when: /already in use/i, steps: upload }
   }
   return null
 }
@@ -342,7 +349,7 @@ export interface FollowUp {
 export function followUpsFor(
   target: SyncTarget,
   profiles: SyncProfiles,
-  opts: { publish: boolean; workspaceId: string; objectTypes: string[] },
+  opts: { publish: boolean; workspaceId: string; objectTypes: string[]; grants?: WorkspaceGrant[] },
 ): FollowUp[] {
   if (target.kind !== 'blueprint' || !opts.publish) return []
   const steps: FollowUp[] = [{
@@ -357,8 +364,24 @@ export function followUpsFor(
     ],
     alreadyDone: /no unpublished changes/i,
   }]
-  if (opts.objectTypes.length) {
-    steps.push({ args: ['blueprint', 'grant', 'workspace', opts.workspaceId, ...opts.objectTypes, '--profile', profiles.organization] })
+  // `blueprint/workspace-grants.yaml`: a type granted more than `read` is granted that, after the
+  // plain grants (each grant sets its whole permission list, so the plain one would undo it). A
+  // plain grant keeps what the type's grant already holds; a type the file lists as `[read]` is
+  // granted exactly that, which is how the file takes `read_sensitive` away.
+  const wider = widerGrants(opts.grants ?? [])
+  const widened = new Set([...wider.values()].flat())
+  const onlyRead = new Set((opts.grants ?? []).filter((g) => g.permissions.length <= 1).map((g) => g.objectType))
+  const plain = opts.objectTypes.filter((t) => !widened.has(t) && !onlyRead.has(t))
+  if (plain.length) {
+    steps.push({ args: ['blueprint', 'grant', 'workspace', opts.workspaceId, ...plain, '--profile', profiles.organization] })
+  }
+  const exactlyRead = opts.objectTypes.filter((t) => onlyRead.has(t) && !widened.has(t))
+  if (exactlyRead.length) {
+    steps.push({ args: ['blueprint', 'grant', 'workspace', opts.workspaceId, ...exactlyRead, '--permissions', 'read', '--profile', profiles.organization] })
+  }
+  for (const [permissions, types] of wider) {
+    const present = types.filter((t) => opts.objectTypes.includes(t))
+    if (present.length) steps.push({ args: ['blueprint', 'grant', 'workspace', opts.workspaceId, ...present, '--permissions', permissions, '--profile', profiles.organization] })
   }
   return steps
 }
@@ -418,3 +441,109 @@ export function describeTarget(target: SyncTarget): string {
       return 'the library installations'
   }
 }
+
+/** The Blueprint's folders: `blueprint apply` reads the model's, `local dev` saves the object sets. */
+const BLUEPRINT_FOLDERS = new Set(['object-types', 'link-types', 'shared-fields', 'semantic-types', 'metrics', 'actions', 'object-sets'])
+
+/** What an Agent's folder holds that something reads: `local dev` applies the files, `local test` the cases. */
+const AGENT_FILES = new Set(['agent.json', 'operating.json', 'bindings.json', 'lessons.yaml'])
+
+/**
+ * Why a file in one of the folders `local dev` applies is not applied, or null
+ * when it is (or is read by something else: test cases, fixtures, a
+ * Function's helpers, a knowledge base's documents). Said instead of ignoring
+ * the file in silence: `themes/acme.json` is not a theme, `themes/acme/theme.json` is.
+ */
+export function unappliedReason(root: string, rel: string): string | null {
+  const parts = rel.split(sep)
+  if (parts.some((p) => IGNORED_DIRS.has(p) || isIgnoredName(p))) return null
+  const [top, second, third] = parts
+  const name = parts[parts.length - 1]!
+  if (/^(readme|agents|claude)\.md$/i.test(name)) return null
+  // Any YAML under blueprint/ queues a Blueprint apply, which reads only the kinds' folders.
+  if (top !== 'blueprint' && targetFor(root, join(root, rel))) return null
+  switch (top) {
+    case 'themes':
+      if (parts.length === 2) return `a slide theme is themes/<name>/theme.json, with its images beside it (\`frontera local schema theme\`): move it to themes/${name.replace(/\.(json|ya?ml)$/, '')}/theme.json`
+      return `themes/${second}/ has no theme.json, so nothing in it is applied (\`frontera local schema theme\`)`
+    case 'agents':
+      if (parts.length === 2) return 'an Agent is a folder: agents/<slug>/agent.json'
+      if (third === 'evals' || third === 'fixtures') return null
+      if (parts.length === 3 && !AGENT_FILES.has(name)) {
+        return `an Agent's files are agent.json, operating.json, bindings.json (the Functions and workflows it may start, the object types it may read) and lessons.yaml, with its test cases in evals/`
+      }
+      return null
+    case 'blueprint':
+      // The workspace's own grants beyond read, applied after each publish (`local-workspace-grants.ts`).
+      if (parts.length === 2 && name === 'workspace-grants.yaml') return null
+      if (parts.length === 2) return 'a Blueprint file lives in its kind’s folder: blueprint/object-types/, link-types/, shared-fields/, semantic-types/, metrics/, actions/ or object-sets/, or is blueprint/workspace-grants.yaml (`frontera local schema` lists each)'
+      if (!BLUEPRINT_FOLDERS.has(second!)) return `blueprint/${second}/ is not a Blueprint folder; the folders are ${[...BLUEPRINT_FOLDERS].join(', ')}`
+      if (!/\.(ya?ml|json)$/.test(name)) return 'a Blueprint file is YAML or JSON'
+      if (parts.length > 3) return `a Blueprint file sits directly in blueprint/${second}/`
+      return null
+    case 'workflows':
+      if (second === 'tests') return null
+      if (parts.length > 2) return 'a workflow is workflows/<slug>.yaml, directly in workflows/ (its tests go in workflows/tests/)'
+      return 'a workflow is workflows/<slug>.yaml (or .yml, .json)'
+    case 'datasets':
+      if (parts.length > 2) return 'a dataset is datasets/<apiName>.json with its CSV beside it, directly in datasets/'
+      return 'a dataset is datasets/<apiName>.json, with datasets/<apiName>.csv beside it for a file dataset'
+    case 'knowledge':
+      if (parts.length === 2) return 'a knowledge base is a folder: knowledge/<name>/knowledge.json ({ "name": "…", "description": "…" }) with its documents beside it'
+      return `knowledge/${second}/ has no knowledge.json ({ "name": "…", "description": "…" }), so its documents are not uploaded`
+    case 'skills':
+      if (parts.length === 2) return 'a skill is a folder: skills/<name>/SKILL.md'
+      return `skills/${second}/ has no SKILL.md, so it is not pushed`
+    case 'chat-apps':
+      return 'a Chat App is chat-apps/<slug>.json, directly in chat-apps/'
+    case 'mcp':
+      return 'a Plugin is mcp/<name>.plugin.json (a stand-in mcp/<name>.stand-in.json)'
+    default:
+      return null
+  }
+}
+
+/** Every file in the applied folders that `local dev` does not apply, with why: one line each. */
+export function unappliedFiles(root: string): string[] {
+  const out: string[] = []
+  const walk = (dir: string, depth: number) => {
+    if (depth > 4 || !existsSync(dir)) return
+    let names: string[]
+    try {
+      names = readdirSync(dir).sort()
+    } catch {
+      return
+    }
+    for (const name of names) {
+      if (IGNORED_DIRS.has(name) || isIgnoredName(name)) continue
+      const path = join(dir, name)
+      let stat
+      try {
+        stat = lstatSync(path)
+      } catch {
+        continue
+      }
+      if (stat.isDirectory()) {
+        const rel = relative(root, path)
+        const [top, second] = rel.split(sep)
+        // Folders whose files are not each applied: a Function's helpers, a knowledge base's documents, an App's code.
+        if (top === 'functions' || top === 'apps' || (top === 'knowledge' && second && existsSync(join(root, 'knowledge', second, 'knowledge.json')))) continue
+        if (top === 'skills' && second && existsSync(join(root, 'skills', second, 'SKILL.md'))) continue
+        if (top === 'themes' && second && existsSync(join(root, 'themes', second, 'theme.json'))) continue
+        if (top === 'knowledge' || top === 'skills' || top === 'themes') {
+          // One line for the folder, not one per document in it.
+          const why = unappliedReason(root, join(rel, '_'))
+          if (why && rel.split(sep).length === 2) out.push(`${rel}/: ${why}`)
+          continue
+        }
+        walk(path, depth + 1)
+      } else if (stat.isFile()) {
+        const rel = relative(root, path)
+        const why = unappliedReason(root, rel)
+        if (why) out.push(`${rel}: ${why}`)
+      }
+    }
+  }
+  for (const top of ['agents', 'blueprint', 'chat-apps', 'datasets', 'knowledge', 'mcp', 'skills', 'themes', 'workflows']) walk(join(root, top), 1)
+  return out
+}

package/src/local/local-docker.ts

@@ -29,7 +29,18 @@ export interface DockerRunSpec {
 
 export class DockerError extends Error {}
 
-function docker(args: string[], opts: { input?: string } = {}): { ok: boolean; out: string; err: string } {
+export type DockerResult = { ok: boolean; out: string; err: string }
+export type DockerExec = (args: string[], opts: { input?: string }) => DockerResult
+
+let dockerExec: DockerExec | null = null
+
+/** Answer every docker call with `exec` instead of the docker CLI; null restores it. For tests. */
+export function setDockerExecForTests(exec: DockerExec | null): void {
+  dockerExec = exec
+}
+
+function docker(args: string[], opts: { input?: string } = {}): DockerResult {
+  if (dockerExec) return dockerExec(args, opts)
   const res = spawnSync('docker', args, { encoding: 'utf8', input: opts.input })
   if (res.error) {
     throw new DockerError(
@@ -133,6 +144,12 @@ export function execInContainer(name: string, cmd: string[]): boolean {
   return docker(['exec', name, ...cmd]).ok
 }
 
+/** As `execInContainer`, with `input` on the command's stdin when given, and what it printed. */
+export function queryInContainer(name: string, cmd: string[], input?: string): { ok: boolean; out: string } {
+  const res = docker(['exec', ...(input === undefined ? [] : ['-i']), name, ...cmd], input === undefined ? {} : { input })
+  return { ok: res.ok, out: res.out }
+}
+
 /** Follow a container's logs into a file for as long as the container lives. */
 export function followLogs(name: string, logFile: string): void {
   const fd = openSync(logFile, 'a')
@@ -144,3 +161,20 @@ export function containersForProject(projectId: string): string[] {
   const r = docker(['ps', '-a', '--filter', `label=${PROJECT_LABEL}=${projectId}`, '--format', '{{.Names}}'])
   return r.ok && r.out ? r.out.split('\n') : []
 }
+
+/** A local runtime's database volume, by its id (the key of its port block). */
+export const dbVolumeName = (projectId: string) => `frontera-${projectId}-db`
+
+/** A local runtime's file storage volume, by its id. */
+export const storageVolumeName = (projectId: string) => `frontera-${projectId}-storage`
+
+/**
+ * Delete a local runtime's containers and volumes, by its id: the containers
+ * labelled for it, running or not, and its database and storage volumes. Its
+ * data is gone afterwards.
+ */
+export function removeRuntimeResources(projectId: string): void {
+  for (const name of containersForProject(projectId)) removeContainer(name)
+  removeVolume(dbVolumeName(projectId))
+  removeVolume(storageVolumeName(projectId))
+}

package/src/local/local-docs-search.ts

@@ -1,5 +1,5 @@
 /**
- * Full-text search over a documentation publication, for `local docs-mcp`.
+ * Full-text search over a documentation publication, for `frontera mcp`.
  * The same ranking the platform's documentation search uses (title, aliases,
  * description, the best matching section, prefix matches), kept here because
  * the CLI is published on its own and cannot import the service.

package/src/local/local-docs.ts

@@ -1,4 +1,5 @@
-import { copyFileSync, existsSync, mkdirSync, readFileSync, renameSync, statSync } from 'node:fs'
+import { spawn } from 'node:child_process'
+import { appendFileSync, copyFileSync, existsSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs'
 import { dirname, join } from 'node:path'
 import { createInterface } from 'node:readline'
 
@@ -10,7 +11,7 @@ import { isSchemaKind, SCHEMA_FILES, SCHEMA_KINDS, type SchemaKind } from './loc
  * Frontera's documentation for the coding agents working in a project
  * (Claude Code, Codex, Cursor). `local start` copies the customer publication
  * of the release the runtime runs into the runtime's state, and
- * `frontera local docs-mcp` serves it over MCP on stdio, straight from that
+ * `frontera mcp` serves it over MCP on stdio, straight from that
  * file: no key, no request to the runtime, and it keeps working while the
  * runtime is stopped. The formats of the project's files (`local-schemas.ts`)
  * are served the same way, from the copies `local start` keeps.
@@ -28,6 +29,284 @@ export function customerDocsBundle(platformSource: string | undefined): string |
   return existsSync(path) ? path : null
 }
 
+/** What `local status` says about the documentation a project's coding agents read. */
+export interface DocsStatus {
+  /** The copy is there and readable. */
+  present: boolean
+  /** The product version the copy documents (`productVersion`). */
+  version: string | null
+  /** The runtime's version: the checkout's in source mode, the release's in image mode. */
+  runtimeVersion: string
+  builtAt: string | null
+  /** The copy documents another version, or (source mode) the checkout's guides changed since it was built. */
+  stale: boolean
+  /** `local start` is rebuilding the checkout's documentation now; the copy is refreshed when it is done. */
+  rebuilding?: boolean
+  /** The last rebuild at start failed: the copy stays as it was. */
+  rebuildFailed?: boolean
+  /** In words, when there is something to say: why it is stale, or that there is none. */
+  note: string | null
+}
+
+/**
+ * The version a platform checkout is at (its root `package.json`): what a
+ * runtime started from it runs, recorded as the runtime's version at start.
+ */
+export function checkoutVersion(platformSource: string): string | null {
+  return readVersion(join(platformSource, 'package.json'))
+}
+
+/**
+ * The version a runtime records at start, which the Runtime page, `local
+ * status` and the Docs note all say: from a checkout, the checkout's version
+ * at this start, never one kept from an earlier start (run 8: started from a
+ * 1.52.33 checkout, the runtime said 1.52.31, its first start's version); from
+ * a release image, the release asked for, else the one an earlier image start
+ * used, else this CLI's.
+ */
+export function versionAtStart(o: { checkout: string | null; flag: string | undefined; previous: { mode: 'source' | 'image'; platformVersion: string } | null; cli: string }): string {
+  if (o.checkout) return o.checkout
+  return o.flag ?? (o.previous?.mode === 'image' ? o.previous.platformVersion : undefined) ?? o.cli
+}
+
+function readVersion(path: string): string | null {
+  try {
+    const v = (JSON.parse(readFileSync(path, 'utf8')) as { version?: unknown }).version
+    return typeof v === 'string' ? v : null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * The guides' sources the customer publication is built from. The internal
+ * pages (`content/internal`) ship only in the internal distribution, so a
+ * change there never makes the customer copy out of date.
+ */
+const GUIDE_PATHS = ['packages/docs-content/content', 'packages/docs-content/catalog', 'packages/docs-content/identity', ':(exclude)packages/docs-content/content/internal']
+
+/**
+ * Whether the guides in a platform checkout changed since the commit a
+ * publication was built from (committed or not, new files included). A
+ * build reads the working tree, not the commit, so with `builtAt` a file
+ * that differs from the commit counts only when it changed after the build
+ * (by its modification time): an edit already in the build is not a reason
+ * to say the copy is behind. Null when it cannot tell (no git, a commit the
+ * checkout does not have).
+ */
+export function guidesChangedSince(platformSource: string, commit: string, builtAt?: string | null): boolean | null {
+  if (!/^[0-9a-f]{7,64}$/i.test(commit)) return null
+  const known = Bun.spawnSync(['git', '-C', platformSource, 'cat-file', '-e', `${commit}^{commit}`], { stdout: 'ignore', stderr: 'ignore' })
+  if (known.exitCode !== 0) return null
+  const diff = Bun.spawnSync(['git', '-C', platformSource, 'diff', '--name-only', commit, '--', ...GUIDE_PATHS], { stdout: 'pipe', stderr: 'ignore' })
+  if (diff.exitCode !== 0) return null
+  const added = Bun.spawnSync(['git', '-C', platformSource, 'ls-files', '--others', '--exclude-standard', '--', ...GUIDE_PATHS], { stdout: 'pipe', stderr: 'ignore' })
+  const paths = [...diff.stdout.toString().split('\n'), ...(added.exitCode === 0 ? added.stdout.toString().split('\n') : [])].map((l) => l.trim()).filter(Boolean)
+  if (!paths.length) return false
+  const built = builtAt ? Date.parse(builtAt) : NaN
+  if (!Number.isFinite(built)) return true
+  return paths.some((rel) => changedAfter(join(platformSource, rel), built))
+}
+
+/** A file changed after `at` (ms): its modification time, or, removed, its folder's. */
+function changedAfter(path: string, at: number): boolean {
+  try {
+    return statSync(path).mtimeMs > at
+  } catch {
+    try {
+      return statSync(dirname(path)).mtimeMs > at
+    } catch {
+      return true
+    }
+  }
+}
+
+/** Where `local start` says how its rebuild of the checkout's documentation is going: building, or failed. */
+export function docsBuildMarkerPath(project: LocalProject): string {
+  return join(project.stateDir, 'docs', 'rebuild.json')
+}
+
+export interface DocsBuildMarker {
+  state: 'building' | 'failed'
+  /** When the rebuild started, or failed. */
+  at: string
+  /** The process building it (the runtime's supervisor): a marker whose process is gone is not building. */
+  pid?: number
+  /** Why it was rebuilt. */
+  why?: string
+}
+
+export function readDocsBuildMarker(project: LocalProject): DocsBuildMarker | null {
+  try {
+    const m = JSON.parse(readFileSync(docsBuildMarkerPath(project), 'utf8')) as DocsBuildMarker
+    return m && (m.state === 'building' || m.state === 'failed') && typeof m.at === 'string' ? m : null
+  } catch {
+    return null
+  }
+}
+
+/** Say a rebuild is under way or failed; null clears it (it built). Never throws: the marker is only for what status says. */
+export function writeDocsBuildMarker(project: LocalProject, marker: DocsBuildMarker | null): void {
+  const path = docsBuildMarkerPath(project)
+  try {
+    if (!marker) return rmSync(path, { force: true })
+    mkdirSync(dirname(path), { recursive: true })
+    writeFileSync(path, `${JSON.stringify(marker)}\n`)
+  } catch {
+    // Status falls back to what the copy says.
+  }
+}
+
+function processAlive(pid: number | undefined): boolean {
+  if (!pid) return false
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch (err) {
+    return (err as NodeJS.ErrnoException).code === 'EPERM'
+  }
+}
+
+/**
+ * A current build in the checkout that is newer than the project's copy
+ * (someone ran `bun run docs:build` there after the runtime started): copy
+ * it in, as the next start would, so the copy and its status follow the
+ * checkout. Returns whether it copied.
+ */
+export function refreshDocsFromCheckout(project: LocalProject, platformSource: string | undefined, changedSince: typeof guidesChangedSince = guidesChangedSince): boolean {
+  const bundle = customerDocsBundle(platformSource)
+  if (!bundle || !platformSource) return false
+  const builtAtOf = (path: string): number => {
+    try {
+      const at = (JSON.parse(readFileSync(path, 'utf8')) as { builtAt?: unknown }).builtAt
+      return typeof at === 'string' ? Date.parse(at) : NaN
+    } catch {
+      return NaN
+    }
+  }
+  const theirs = builtAtOf(bundle)
+  const ours = builtAtOf(docsCopyPath(project))
+  if (!Number.isFinite(theirs) || (Number.isFinite(ours) && theirs <= ours)) return false
+  if (checkoutDocsStale(platformSource, changedSince)) return false
+  return copyDocs({ project, bundle }) === null
+}
+
+/**
+ * The documentation copy against the runtime it was copied for. `local
+ * start` copies what the checkout last built and, when that build is
+ * behind the checkout, rebuilds it in the background and copies it again;
+ * this says plainly when the copy documents another version, or guides
+ * changed since, instead of serving it silently, and whether that rebuild
+ * is running or failed. A newer current build in the checkout is copied in
+ * first (`refreshDocsFromCheckout`). The fix it names fits the runtime: a
+ * platform checkout's build only in source mode. Versions compare like with
+ * like: the copy's against the version the running runtime recorded at start.
+ */
+export function docsStatus(project: LocalProject, runtime: { mode: 'source' | 'image'; platformVersion: string; platformSource?: string }, changedSince: typeof guidesChangedSince = guidesChangedSince): DocsStatus {
+  // The runtime's version is the one it recorded when it started (`state.platformVersion`), as the Runtime page and
+  // `local status` say it: never the checkout's version now, which a pull can move while the runtime runs (run 8 said
+  // "the runtime is 1.52.33" beside a Runtime page saying 1.52.31).
+  const runtimeVersion = runtime.platformVersion
+  if (runtime.mode === 'source') refreshDocsFromCheckout(project, runtime.platformSource, changedSince)
+  const publication = loadDocs(docsCopyPath(project)) as (DocsPublication & { productVersion?: string; sourceCommit?: string; builtAt?: string }) | null
+  const marker = runtime.mode === 'source' ? readDocsBuildMarker(project) : null
+  const rebuilding = marker?.state === 'building' && processAlive(marker.pid)
+  const rebuildFailed = marker?.state === 'failed'
+  const restart = '`frontera local stop`, then `frontera local start`'
+  if (!publication) {
+    return {
+      present: false,
+      version: null,
+      runtimeVersion,
+      builtAt: null,
+      stale: false,
+      ...(rebuilding ? { rebuilding: true } : {}),
+      note: rebuilding
+        ? 'rebuilding — `frontera local start` is building it in the background; it is here when that is done'
+        : runtime.mode === 'source'
+          ? `none: build it in the platform checkout (\`bun run docs:build\`), then ${restart}`
+          : 'none: this release’s service image carries no documentation',
+    }
+  }
+  const version = typeof publication.productVersion === 'string' ? publication.productVersion : null
+  const builtAt = typeof publication.builtAt === 'string' ? publication.builtAt : null
+  const reasons: string[] = []
+  if (version && version !== runtimeVersion) reasons.push(`it documents ${version}, and the runtime is ${runtimeVersion}`)
+  if (runtime.mode === 'source' && runtime.platformSource && typeof publication.sourceCommit === 'string' && changedSince(runtime.platformSource, publication.sourceCommit, builtAt)) {
+    reasons.push(`the checkout’s guides changed since it was built (from ${publication.sourceCommit.slice(0, 9)})`)
+  }
+  const stale = reasons.length > 0
+  if (stale && rebuilding) {
+    return { present: true, version, runtimeVersion, builtAt, stale, rebuilding: true, note: `rebuilding — ${reasons.join('; ')}: \`frontera local start\` is building it in the background and refreshes the copy when it is done; the copy here serves until then` }
+  }
+  const fix =
+    runtime.mode === 'image'
+      ? `: ${restart} copies this release’s documentation`
+      : rebuildFailed
+        ? `: the rebuild at start failed (\`frontera local logs service\` shows why); run \`bun run docs:build\` in the platform checkout, then ${restart}`
+        : `: ${restart} rebuilds it in the background and refreshes the copy (see \`frontera local logs service\`), or run \`bun run docs:build\` in the platform checkout`
+  return { present: true, version, runtimeVersion, builtAt, stale, ...(stale && rebuildFailed ? { rebuildFailed: true } : {}), note: stale ? `out of date — ${reasons.join('; ')}${fix}` : null }
+}
+
+/**
+ * Why a platform checkout's customer publication is behind the checkout, or
+ * null when it is current (or that cannot be told): no build yet, guides
+ * changed since the commit it was built from, or another version.
+ */
+export function checkoutDocsStale(platformSource: string, changedSince: typeof guidesChangedSince = guidesChangedSince): string | null {
+  const bundle = join(platformSource, 'packages', 'docs-content', 'dist', 'customer', 'publication.json')
+  if (!existsSync(bundle)) return 'the checkout has no documentation build'
+  let publication: { productVersion?: unknown; sourceCommit?: unknown; builtAt?: unknown } | null = null
+  try {
+    publication = JSON.parse(readFileSync(bundle, 'utf8')) as { productVersion?: unknown; sourceCommit?: unknown; builtAt?: unknown }
+  } catch {
+    return 'the checkout’s documentation build could not be read'
+  }
+  const version = readVersion(join(platformSource, 'package.json'))
+  if (typeof publication?.productVersion === 'string' && version && publication.productVersion !== version) return `the checkout’s documentation build documents ${publication.productVersion}, and the checkout is ${version}`
+  if (typeof publication?.sourceCommit === 'string' && changedSince(platformSource, publication.sourceCommit, typeof publication.builtAt === 'string' ? publication.builtAt : null)) return `the checkout’s guides changed since its documentation was built (from ${publication.sourceCommit.slice(0, 9)})`
+  return null
+}
+
+/** Marks a documentation build in a checkout, so two runtimes started from it don't build at once. */
+const DOCS_BUILD_LOCK = ['packages', 'docs-content', 'dist', '.frontera-docs-build']
+
+function lockHolder(path: string): number | null {
+  try {
+    const pid = Number(readFileSync(path, 'utf8').trim())
+    if (!Number.isInteger(pid) || pid <= 0) return null
+    process.kill(pid, 0)
+    return pid
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Build the checkout's documentation at low priority (`nice -n 10 bun run
+ * docs:build`), logging to `logFile`; resolves whether it built. Resolves
+ * false at once when another build of this checkout is running.
+ */
+export function buildDocs(platformSource: string, logFile: string): Promise<boolean> {
+  const lock = join(platformSource, ...DOCS_BUILD_LOCK)
+  if (lockHolder(lock)) {
+    appendFileSync(logFile, '[docs] another runtime is building this checkout’s documentation; the copy is refreshed at the next start\n')
+    return Promise.resolve(false)
+  }
+  mkdirSync(dirname(lock), { recursive: true })
+  return new Promise((done) => {
+    const fd = openSync(logFile, 'a')
+    const child = spawn('nice', ['-n', '10', 'bun', 'run', 'docs:build'], { cwd: platformSource, stdio: ['ignore', fd, fd] })
+    if (child.pid) writeFileSync(lock, String(child.pid))
+    const finish = (ok: boolean) => {
+      rmSync(lock, { force: true })
+      done(ok)
+    }
+    child.on('error', () => finish(false))
+    child.on('exit', (code) => finish(code === 0))
+  })
+}
+
 /** Where the service image carries its customer publication. */
 export const IMAGE_DOCS_PATH = '/app/documentation/publication.json'