@frontera-sdk/cli 1.52.28 → 1.52.30

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

@@ -0,0 +1,1482 @@
+import { spawnSync } from 'node:child_process'
+import { mkdtempSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join, posix, relative } from 'node:path'
+
+import { parse as parseYaml, stringify as stringifyYaml } from 'yaml'
+
+import { toFiles } from '../blueprint/projection'
+import { serialize } from '../blueprint/tree'
+import { assetFilename, toSkillMd, type SkillDoc } from '../commands/skill/bundle-commands'
+import { CliError } from '../errors'
+import { editorFunctionModule } from './local-function-draft'
+import { slugify } from './local-project'
+import { MASKED, NON_SECRET_HEADERS, pluginSecretInputs, SECRETISH } from './local-secrets'
+import type { SyncClient } from './local-sync-client'
+import type { RemoteItem, SyncKind } from './local-sync-plan'
+import { actionFit, portabilityOf, type BuiltInKind } from './local-portability'
+import { readThemes, type ThemeRow } from './local-themes'
+import { readChatApps, type ChatAppRow } from './local-chat-apps'
+import { readApps, type AppRow as CustomAppRow } from './local-apps'
+import { readBrand, type BrandRow } from './local-brand'
+import { readLibrary, type LibraryRow } from './local-library'
+import { isSharedFunctionFile } from './local-function-shared'
+import { attachDefinitions, type ObjectDefinitionRow } from './local-objects'
+import { checksFromFixtures, fixtureRows, qualityChecksPath, qualityChecksText, sourcePaths, sourceRows } from './local-quality-checks'
+import { readableName } from './local-sync-names'
+import { governedActionIds, invert, itemRef, referencesIn, toNames, type Directory, type RefKind } from './local-sync-refs'
+
+/**
+ * Reading a workspace as the files a project holds. Each kind lists what the
+ * workspace has, reads each item's live version (a draft only when asked),
+ * rewrites ids to `kind/name` with the workspace's own directory, and lays it
+ * out the way `frontera local dev` applies it. The same directory builder
+ * serves the local runtime when `local dev` turns names back into ids.
+ */
+
+export interface SyncSource {
+  /** The workspace key's client. */
+  workspace: SyncClient
+  /** The organization key's client, when one was given. */
+  organization?: SyncClient
+  workspaceId: string
+}
+
+/** Envelopes come single (`{data}`) or double (`{data:{data}}`); lists are what is inside. */
+export function rows<T>(body: unknown): T[] {
+  let v = body
+  for (let i = 0; i < 3 && v && !Array.isArray(v) && typeof v === 'object' && 'data' in (v as object); i++) v = (v as { data: unknown }).data
+  // Paged lists put their rows under `items`.
+  if (v && !Array.isArray(v) && typeof v === 'object' && Array.isArray((v as { items?: unknown }).items)) v = (v as { items: unknown[] }).items
+  return Array.isArray(v) ? (v as T[]) : []
+}
+
+function one<T>(body: unknown): T {
+  let v = body
+  for (let i = 0; i < 3 && v && typeof v === 'object' && !Array.isArray(v) && Object.keys(v as object).length <= 3 && 'data' in (v as object); i++) v = (v as { data: unknown }).data
+  return v as T
+}
+
+/** A resource's name as a reference can hold it: knowledge bases are named in words. */
+export function refName(name: string): string {
+  return /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(name) ? name : slugify(name) || 'unnamed'
+}
+
+async function quietly<T>(warnings: string[], what: string, read: () => Promise<T>, empty: T): Promise<T> {
+  try {
+    return await read()
+  } catch (err) {
+    warnings.push(`${what}: ${(err as Error).message}`)
+    return empty
+  }
+}
+
+interface AgentRow {
+  id: string
+  agentId: string
+  name: string
+  description?: string | null
+  currentVersionId?: string | null
+  operatingConfig?: unknown
+  /** Its Context and data, where the platform's `/v1/sync/agents` gives it (`agent-context`). */
+  contextAndData?: Array<{ objectTypeApiName?: string; permissions?: string[] }>
+}
+interface WorkflowRow { id: string; slug: string; displayName?: string | null; liveVersion?: number | null; latestDraftNumber?: number | null; archivedAt?: string | null; enabled?: boolean | null }
+interface FunctionRow { id: string; slug: string; description?: string | null; liveVersion?: number | null; enabled?: boolean | null }
+interface KnowledgeRow {
+  id: string
+  name: string
+  description?: string | null
+  retrieval?: unknown
+  chunker?: string | null
+  chunkSize?: number | null
+  chunkOverlap?: number | null
+  similarityThreshold?: number | null
+  topK?: number | null
+  hybridConfig?: unknown
+  extractorConfig?: unknown
+  ocrConfig?: unknown
+}
+interface AppRow {
+  install?: { id: string; installName: string; config?: Record<string, unknown> | null; enabled?: boolean | null; actionPolicy?: string | null; newCapabilityDefault?: string | null; description?: string | null; iconUrl?: string | null }
+  catalog?: { kind?: string; name?: string; displayName?: string }
+}
+/** One tool of an installed Plugin, with its own setting on the install when it has one (newer platforms). */
+interface ToolRow { id: string; name: string; kind?: string; policy?: { enabled?: boolean | null; requiresApprovalOverride?: boolean | null; paramConstraints?: Record<string, unknown> | null } | null }
+
+/** Each installed Plugin's tools, by install id: read once, for the Plugin files and the Agents' tool settings. */
+export type PluginTools = Map<string, ToolRow[]>
+
+async function readPluginTools(source: SyncSource, apps: AppRow[], warnings: string[]): Promise<PluginTools> {
+  const out: PluginTools = new Map()
+  for (const a of apps) {
+    if (!a.install) continue
+    const install = a.install
+    out.set(install.id, await quietly(warnings, `Plugin ${install.installName} tools`, async () => rows<ToolRow>(await source.workspace.get(`/v1/apps/${encodeURIComponent(install.id)}/capabilities`)), []))
+  }
+  return out
+}
+interface SkillRow { id: string; name: string; displayName?: string | null }
+interface ActionRow { id: string; apiName: string }
+/** A saved object set, as `/v1/sync/object-sets` lists it: a definition over one object type, or a static list of its records by key. */
+export interface ObjectSetRow {
+  id: string
+  name: string
+  description?: string | null
+  kind: 'dynamic' | 'static'
+  objectType: string
+  definition?: unknown
+  staticPks?: Array<string | number> | null
+}
+
+/**
+ * Each saved set's name in a reference (`objectSet/open-cases`): its name as
+ * a reference can hold it, numbered when two sets would share one. The same
+ * rule on the workspace and on the local runtime, so a name means one set.
+ */
+export function objectSetNames(sets: ObjectSetRow[]): Map<string, string> {
+  const out = new Map<string, string>()
+  const taken = new Set<string>()
+  for (const set of [...sets].sort((a, b) => a.name.localeCompare(b.name) || a.id.localeCompare(b.id))) {
+    const base = refName(set.name)
+    let name = base
+    for (let n = 2; taken.has(name); n++) name = `${base}-${n}`
+    taken.add(name)
+    out.set(set.id, name)
+  }
+  return out
+}
+
+/**
+ * Governed Actions by id and API name, so a workflow node that runs one names
+ * it `action/<apiName>`. Only the names: the Actions themselves are not pulled.
+ * Reading Action definitions is organization-grain (a workspace key is refused
+ * them), so this asks with the organization key. The draft holds every Action,
+ * published or not; the published list adds any the draft has since dropped.
+ */
+async function listActions(org: SyncClient): Promise<ActionRow[]> {
+  const pick = (row: unknown): ActionRow[] => {
+    const d = ((row as { definition?: unknown } | null)?.definition ?? row) as Partial<ActionRow> | null
+    return d && typeof d.id === 'string' && typeof d.apiName === 'string' ? [{ id: d.id, apiName: d.apiName }] : []
+  }
+  const draft = rows<unknown>(await org.get('/v1/blueprint/actions?view=draft')).flatMap(pick)
+  const published = rows<unknown>(await org.get('/v1/blueprint/actions').catch(() => null)).flatMap(pick)
+  return [...new Map([...published, ...draft].map((a) => [a.id, a])).values()]
+}
+
+/**
+ * The workspace's Agents with those not yet published, which `/v1/config/agents`
+ * leaves out; a platform without `/v1/sync/agents` answers with the published ones.
+ */
+async function listAgents(ws: SyncSource['workspace']): Promise<AgentRow[]> {
+  const all = await ws.find('/v1/sync/agents')
+  return rows<AgentRow>(all ?? (await ws.get('/v1/config/agents')))
+}
+
+/** Every list a reference may point into, name → id, for one runtime. */
+export async function buildDirectory(source: SyncSource, warnings: string[] = []): Promise<{ directory: Directory; lists: Lists }> {
+  const ws = source.workspace
+  const [agents, workflows, functions, knowledge, apps, skills, objectTypes, models, actions, objectSets, objectDefinitions] = await Promise.all([
+    quietly(warnings, 'Agents', () => listAgents(ws), []),
+    quietly(warnings, 'Workflows', async () => rows<WorkflowRow>(await ws.get('/v1/workflows')).filter((w) => !w.archivedAt), []),
+    quietly(warnings, 'Functions', async () => rows<FunctionRow>(await ws.get('/v1/functions')), []),
+    quietly(warnings, 'Knowledge', async () => rows<KnowledgeRow>(await ws.get(`/v1/workspace-knowledge?workspaceId=${encodeURIComponent(source.workspaceId)}`)), []),
+    quietly(warnings, 'Plugins', async () => rows<AppRow>(await ws.get('/v1/apps')), []),
+    quietly(warnings, 'Skills', async () => rows<SkillRow>(await ws.get('/v1/config/workspace-skills')), []),
+    quietly(warnings, 'Blueprint object types', async () => rows<{ id: string; apiName: string }>(await ws.get('/v1/blueprint/object-types')), []),
+    // The model catalog is organization-grain: a workspace key reads its names only, where the platform offers them.
+    source.organization
+      ? quietly(warnings, 'Models', async () => rows<{ id: string; slug: string }>(await source.organization!.get('/v1/config/models/catalog')), [])
+      : quietly(warnings, 'Models', async () => rows<{ id: string; slug: string }>(await ws.find<unknown>('/v1/sync/models')), []),
+    // So are governed Actions' definitions: without the organization key they are not listed.
+    source.organization ? quietly<ActionRow[] | null>(warnings, 'Governed Actions', () => listActions(source.organization!), null) : Promise.resolve(null),
+    // A platform without the route has none to name: absent, as for Actions.
+    quietly<ObjectSetRow[] | null>(warnings, 'Saved object sets', async () => {
+      const found = await ws.find<unknown>('/v1/sync/object-sets')
+      return found === null ? null : rows<ObjectSetRow>(found)
+    }, null),
+    // The object definitions an Agent's object tools work on; null on a platform that doesn't list them.
+    quietly<ObjectDefinitionRow[] | null>(warnings, 'Object definitions', async () => {
+      const found = await ws.find<unknown>('/v1/sync/object-definitions')
+      return found === null ? null : rows<ObjectDefinitionRow>(found)
+    }, null),
+  ])
+  const setNames = objectSetNames(objectSets ?? [])
+  const directory: Directory = {
+    agent: new Map(agents.map((a) => [a.agentId, a.id])),
+    workflow: new Map(workflows.map((w) => [w.slug, w.id])),
+    function: new Map(functions.map((f) => [f.slug, f.id])),
+    knowledge: new Map(knowledge.map((k) => [refName(k.name), k.id])),
+    plugin: new Map(apps.flatMap((a) => (a.install ? [[a.install.installName, a.install.id] as [string, string]] : []))),
+    skill: new Map(skills.map((s) => [s.name, s.id])),
+    objectType: new Map(objectTypes.map((o) => [o.apiName, o.id])),
+    model: new Map(models.map((m) => [m.slug, m.id])),
+    // Absent, not empty, when they could not be listed, so "none" and "unknown" differ.
+    ...(actions ? { action: new Map(actions.map((a) => [a.apiName, a.id])) } : {}),
+    ...(objectSets ? { objectSet: new Map((objectSets ?? []).map((o) => [setNames.get(o.id)!, o.id])) } : {}),
+    ...(objectDefinitions ? { object: new Map(objectDefinitions.map((o) => [o.slug, o.id])) } : {}),
+  }
+  return { directory, lists: { agents, workflows, functions, knowledge, apps, skills, objectSets: objectSets ?? [], objectDefinitions } }
+}
+
+export interface Lists {
+  agents: AgentRow[]
+  workflows: WorkflowRow[]
+  functions: FunctionRow[]
+  knowledge: KnowledgeRow[]
+  apps: AppRow[]
+  skills: SkillRow[]
+  /** The saved object sets on the workspace's Blueprint. */
+  objectSets?: ObjectSetRow[]
+  /** The object definitions an Agent's object tools work on; null when the platform doesn't list them. */
+  objectDefinitions?: ObjectDefinitionRow[] | null
+}
+
+export interface ReadOptions {
+  /** Items to read as their draft instead of the live version, by ref. */
+  drafts?: Set<string>
+  /** Only these kinds. */
+  kinds?: Set<SyncKind>
+  /** `organization` reads the whole Blueprint with the organization key. */
+  blueprint?: 'workspace' | 'organization'
+  /**
+   * Only these refs, for the kinds read item by item: a fetch reads what the
+   * sync index says changed. The Blueprint and evaluations are read whole.
+   */
+  only?: Set<string>
+}
+
+const wanted = (opts: ReadOptions, ref: string) => !opts.only || opts.only.has(ref)
+
+const json = (value: unknown) => `${JSON.stringify(value, null, 2)}\n`
+
+function item(kind: SyncKind, name: string, title: string, files: Record<string, string>, extra: Partial<RemoteItem> = {}): RemoteItem {
+  return { ref: `${kind}/${name}`, kind, name, title, files, unresolved: [], notes: [], ...extra }
+}
+
+/** Row bookkeeping a relation row carries on the platform, meaningless in a project. */
+const ROW_KEYS = new Set(['id', 'agentId', 'workspaceId', 'orgId', 'createdAt', 'updatedAt', 'createdBy', 'updatedBy'])
+
+function stripRow(row: Record<string, unknown>): Record<string, unknown> {
+  return Object.fromEntries(Object.entries(row).filter(([k, v]) => !ROW_KEYS.has(k) && v !== null && v !== undefined))
+}
+
+/**
+ * The settings an Agent's file keeps. A key left out falls back to the local
+ * default when applied, never to the workspace's value, so each that changes
+ * how the Agent behaves is here: its tool permission rules (by role), its
+ * Function guardrails, the model modes its utilities use, its audit and QA
+ * evaluator settings, and its work-item statuses and labels.
+ */
+const AGENT_CONFIG_KEYS = [
+  'name', 'description', 'avatarSeed', 'avatarConfig', 'defaultMode', 'utilityMode', 'utilityOverrides', 'agentType', 'agentModeEnabled', 'disableWebBrowsing',
+  'plugins', 'features', 'memory', 'voice', 'compression', 'streaming', 'upload', 'planning', 'delegation', 'modelRouting', 'toolPhasing', 'stopConditions',
+  'maxCostPerRun', 'permissions', 'functionGuardrails', 'audit', 'harness', 'statuses', 'defaultStatus', 'defaultLabels',
+]
+
+/**
+ * An Agent's snapshot cut down to what a project file holds: its settings,
+ * instructions, model modes, and the Knowledge, Skills and Plugins it uses by
+ * name. Its behavior settings go to `operating.json`; channels and
+ * applied packs belong to the platform.
+ */
+export function projectAgent(snapshot: Record<string, unknown>, notes: string[], tools?: { apps: AppRow[]; tools: PluginTools }): Record<string, unknown> {
+  const config = (snapshot.config ?? {}) as Record<string, unknown>
+  const out: Record<string, unknown> = {
+    config: Object.fromEntries(AGENT_CONFIG_KEYS.flatMap((k) => {
+      const v = config[k]
+      if (v === null || v === undefined) return []
+      if (typeof v === 'object' && !Array.isArray(v) && Object.keys(v as object).length === 0) return []
+      return [[k, v]]
+    })),
+  }
+  const list = (key: string) => (Array.isArray(snapshot[key]) ? (snapshot[key] as Array<Record<string, unknown>>) : [])
+  if (list('modelConfigs').length) out.modelConfigs = list('modelConfigs').map(stripRow)
+  if (list('prompts').length) out.prompts = list('prompts').map(stripRow)
+  const skills = ((snapshot.skills as { workspaceBindings?: Array<Record<string, unknown>> } | undefined)?.workspaceBindings ?? []).map(stripRow)
+  if (skills.length) out.skills = { workspaceBindings: skills }
+  if (list('knowledgeAttachments').length) out.knowledgeAttachments = list('knowledgeAttachments').map(stripRow)
+  // `functions` (the legacy `agent_automations` rows) is left out: nothing runs them any more. The
+  // Functions an Agent may call are its Function bindings, in `bindings.json`.
+  if (list('appInstalls').length) out.appInstalls = list('appInstalls').map(stripRow)
+  if (list('objectBindings').length) out.objectBindings = list('objectBindings').map(stripRow)
+  if (list('mcpServers').length) {
+    out.mcpServers = list('mcpServers').map((s) => {
+      const { headers, ...rest } = stripRow(s)
+      if (headers && Object.keys(headers as object).length) notes.push(`MCP server ${String(s.name)}: its headers were left out; locally they come from its Plugin, mcp/${String(s.name)}.plugin.json`)
+      return rest
+    })
+  }
+  // Its tool settings on each Plugin (a sensitive tool granted to it, an approval it overrides),
+  // by Plugin and tool name: capability ids are the install's own.
+  if (list('appCapabilities').length) {
+    const named = tools ? toolNames(tools) : new Map<string, { plugin: string; tool: string }>()
+    const rows = list('appCapabilities').flatMap((row) => {
+      const at = named.get(String(row.capabilityId))
+      if (!at) return []
+      const { capabilityId: _id, ...rest } = stripRow(row)
+      return [{ plugin: at.plugin, tool: at.tool, ...rest }]
+    })
+    if (rows.length) out.pluginTools = rows.sort((a, b) => `${a.plugin}/${a.tool}`.localeCompare(`${b.plugin}/${b.tool}`))
+    const lost = list('appCapabilities').length - rows.length
+    if (lost) notes.push(`${lost} Plugin tool setting${lost === 1 ? '' : 's'} could not be named and stay${lost === 1 ? 's' : ''} on the platform; locally the Agent uses ${lost === 1 ? 'that tool' : 'those tools'} as the Plugin allows`)
+  }
+  if (list('channelBindings').length) notes.push('Channels stay on the platform')
+  // Which resource packs set it up is the platform's record; what they brought comes as its own items.
+  const packs = list('appliedPacks').length
+  if (packs) notes.push(`Set up from ${packs} resource pack${packs === 1 ? '' : 's'} on the platform; the skills and Plugins ${packs === 1 ? 'it' : 'they'} brought come as the project's own`)
+  return out
+}
+
+/** Capability id → its Plugin (`plugin/<install name>`) and tool name. */
+function toolNames(t: { apps: AppRow[]; tools: PluginTools }): Map<string, { plugin: string; tool: string }> {
+  const out = new Map<string, { plugin: string; tool: string }>()
+  for (const a of t.apps) {
+    if (!a.install) continue
+    for (const tool of t.tools.get(a.install.id) ?? []) out.set(tool.id, { plugin: `plugin/${a.install.installName}`, tool: tool.name })
+  }
+  return out
+}
+
+/**
+ * The Agent list leaves out Agents never published; an id a document names
+ * that the directory does not know is looked up as an Agent before it is
+ * reported, so a workflow's step that runs a draft Agent is still named.
+ */
+async function nameUnknownAgents(source: SyncSource, directory: Directory, docs: Array<{ doc: unknown }>): Promise<void> {
+  directory.agent ??= new Map()
+  const known = new Set([...directory.agent.values()])
+  for (const { doc } of docs) {
+    for (const u of toNames(doc, directory).unresolved) {
+      if (known.has(u.value)) continue
+      known.add(u.value)
+      const found = await source.workspace.find<{ agentId?: string }>(`/v1/config/agents/${u.value}`).catch(() => null)
+      if (found?.agentId) directory.agent.set(found.agentId, u.value)
+    }
+  }
+}
+
+function finish(it: RemoteItem, directory: Directory, docs: Array<{ path: string; doc: unknown; format: 'json' | 'yaml' }>): RemoteItem {
+  const self = it.ref
+  const requires = new Set<string>()
+  for (const { path, doc, format } of docs) {
+    const { doc: named, unresolved } = toNames(doc, directory)
+    it.unresolved.push(...unresolved.map((u) => ({ ...u, path: `${path}: ${u.path}` })))
+    for (const r of referencesIn(named)) {
+      // An object definition travels inside the Agent's file: nothing to bring along.
+      if (r.kind === 'object') continue
+      const ref = itemRef(r.kind, r.name)
+      if (ref !== self) requires.add(ref)
+    }
+    it.files[path] = format === 'json' ? json(named) : stringifyYaml(named, { lineWidth: 0 })
+  }
+  it.requires = [...requires].sort()
+  return it
+}
+
+interface BindingRow { agentSlug?: string; enabled?: boolean; requiresApproval?: boolean; waitSeconds?: number; access?: string }
+
+export interface AgentBindings {
+  functions: Array<{ function: string; enabled?: boolean; requiresApproval?: boolean; waitSeconds?: number }>
+  workflows: Array<{ workflow: string; access?: string; enabled?: boolean; requiresApproval?: boolean; waitSeconds?: number }>
+  /**
+   * Its Context and data: the object types it may read through its Blueprint
+   * tools (`objectType/Incident`), with the permissions granted. Absent when
+   * it has none, or they could not be read (no organization key).
+   */
+  blueprint?: Array<{ objectType: string; permissions: string[] }>
+  /**
+   * Its Context and data could not be read on the platform with the project's
+   * keys. `local dev` then gives it read access to the object types the
+   * project holds, as an adaptation, until a pull can read it. Never sent
+   * back as grants: a change request leaves the Agent's grants as they are.
+   */
+  blueprintUnread?: true
+}
+
+type Grants = NonNullable<AgentBindings['blueprint']>
+
+/** What a pull knows of an Agent's Context and data: its grants, or why they could not be read. */
+export type AgentContext = { grants: Grants; note?: string } | { unread: string }
+
+const asGrants = (granted: Array<{ objectTypeApiName?: string; permissions?: string[] }>): Grants =>
+  granted
+    .flatMap((g) => (typeof g.objectTypeApiName === 'string' ? [{ objectType: `objectType/${g.objectTypeApiName}`, permissions: [...(g.permissions?.length ? g.permissions : ['read'])].sort() }] : []))
+    .sort((a, b) => a.objectType.localeCompare(b.objectType))
+
+const STEWARD_FIX = 'An organization key made by a Blueprint Steward with organization update reads it, and so does the workspace key on a newer platform'
+
+/** "Insufficient permissions" in words a person can act on. */
+function unreadWhy(err: unknown): string {
+  const code = err instanceof CliError ? err.code : null
+  if (code === 'FORBIDDEN' || code === 'UNAUTHORIZED') return `the organization key may not read it. ${STEWARD_FIX}`
+  return `the platform did not answer for it (${(err as Error).message}). Fetch again`
+}
+
+/**
+ * An Agent's Context and data (its Blueprint grants), by object type name,
+ * read the first way the platform allows:
+ * 1. the workspace's Agent list (`/v1/sync/agents`), which gives them to the
+ *    workspace key, read-only;
+ * 2. on an older platform, the Blueprint's grant route with the organization
+ *    key, which only a Steward with organization update may read;
+ * 3. the object types the Agent may use (`granted-object-types`), which the
+ *    workspace key reads too; their permissions beyond read are not given.
+ * When none answers, `unread` says why in words.
+ */
+export async function readAgentContext(source: SyncSource, row: AgentRow): Promise<AgentContext> {
+  if (Array.isArray(row.contextAndData)) return { grants: asGrants(row.contextAndData) }
+  let refused: string | null = null
+  if (source.organization) {
+    try {
+      return { grants: asGrants(rows(await source.organization.get(`/v1/blueprint/grants/agent/${encodeURIComponent(row.id)}`))) }
+    } catch (err) {
+      refused = unreadWhy(err)
+    }
+  }
+  const names = await source.workspace.find<unknown>(`/v1/blueprint/agents/${encodeURIComponent(row.id)}/granted-object-types`).catch(() => null)
+  const listed = (Array.isArray(names) ? names : rows<unknown>(names ?? [])).filter((n): n is string => typeof n === 'string')
+  // An empty answer may only mean the key can't see the Agent there, so it is not taken for "none".
+  if (listed.length) {
+    return {
+      grants: listed.map((n) => ({ objectType: `objectType/${n}`, permissions: ['read'] })).sort((a, b) => a.objectType.localeCompare(b.objectType)),
+      note: 'Its Context and data was read as the object types it may use: this platform doesn’t give their permissions to this key, so read is taken for each',
+    }
+  }
+  return { unread: refused ?? `this platform gives it only to an organization key. ${STEWARD_FIX}` }
+}
+
+/**
+ * Which Functions and workflows each Agent may start. They are kept beside
+ * the Agent on the platform, not in its snapshot, and its procedures refuse
+ * to run without them; both are named by slug, so they travel as they are.
+ */
+async function readBindings(source: SyncSource, lists: Lists, warnings: string[]): Promise<Map<string, AgentBindings>> {
+  const out = new Map<string, AgentBindings>()
+  const at = (agent: string) => {
+    if (!out.has(agent)) out.set(agent, { functions: [], workflows: [] })
+    return out.get(agent)!
+  }
+  const clean = (row: BindingRow) => Object.fromEntries(Object.entries({ enabled: row.enabled, requiresApproval: row.requiresApproval, waitSeconds: row.waitSeconds }).filter(([, v]) => v !== undefined))
+  for (const fn of lists.functions) {
+    const rowsFor = await quietly(warnings, `Function ${fn.slug} bindings`, async () => rows<BindingRow>(await source.workspace.get(`/v1/functions/${encodeURIComponent(fn.slug)}/bindings`)), [])
+    for (const b of rowsFor) if (b.agentSlug) at(b.agentSlug).functions.push({ function: `function/${fn.slug}`, ...clean(b) })
+  }
+  for (const wf of lists.workflows) {
+    const rowsFor = await quietly(warnings, `Workflow ${wf.slug} bindings`, async () => rows<BindingRow>(await source.workspace.get(`/v1/workflows/${encodeURIComponent(wf.slug)}/bindings`)), [])
+    for (const b of rowsFor) if (b.agentSlug) at(b.agentSlug).workflows.push({ workflow: `workflow/${wf.slug}`, ...(b.access ? { access: b.access } : {}), ...clean(b) })
+  }
+  for (const b of out.values()) {
+    b.functions.sort((x, y) => x.function.localeCompare(y.function))
+    b.workflows.sort((x, y) => x.workflow.localeCompare(y.workflow))
+  }
+  return out
+}
+
+async function readAgents(source: SyncSource, lists: Lists, directory: Directory, opts: ReadOptions, warnings: string[], tools: () => Promise<PluginTools>): Promise<RemoteItem[]> {
+  const out: RemoteItem[] = []
+  const agents = lists.agents.filter((row) => wanted(opts, `agent/${row.agentId}`))
+  if (!agents.length) return out
+  const bindings = await readBindings(source, lists, warnings)
+  for (const row of agents) {
+    const ref = `agent/${row.agentId}`
+    const wantDraft = opts.drafts?.has(ref) || !row.currentVersionId
+    const it = item('agent', row.agentId, row.name, {}, { id: row.id })
+    let snapshot: Record<string, unknown> | null = null
+    try {
+      if (wantDraft) {
+        const draft = one<{ snapshot?: Record<string, unknown>; revision?: number } | null>(await source.workspace.get(`/v1/config/agents/${row.id}/draft-v2`))
+        snapshot = draft?.snapshot ?? null
+        if (!row.currentVersionId) it.notes.push('Not published on the platform: its draft was read')
+        else it.notes.push('Read from its draft, as asked')
+        if (draft?.revision !== undefined) it.version = `draft ${draft.revision}`
+      }
+      if (!snapshot) {
+        snapshot = one<Record<string, unknown>>(await source.workspace.get(`/v1/config/agents/${row.id}/snapshot/live`))
+        const detail = one<{ currentVersion?: { versionNumber?: number } | null }>(await source.workspace.get(`/v1/config/agents/${row.id}`))
+        if (detail?.currentVersion?.versionNumber) it.version = `v${detail.currentVersion.versionNumber}`
+      }
+    } catch (err) {
+      warnings.push(`Agent ${row.agentId}: ${(err as Error).message}`)
+      continue
+    }
+    const operating = ((snapshot.config as Record<string, unknown> | undefined)?.operatingConfig ?? (wantDraft ? null : row.operatingConfig)) as Record<string, unknown> | null
+    const toolSettings = Array.isArray(snapshot.appCapabilities) && snapshot.appCapabilities.length ? { apps: lists.apps, tools: await tools() } : undefined
+    const agentDoc = projectAgent(snapshot, it.notes, toolSettings)
+    // Its object tools carry the definitions they work on, named by slug below.
+    it.notes.push(...attachDefinitions(agentDoc, lists.objectDefinitions ?? null))
+    const docs: Array<{ path: string; doc: unknown; format: 'json' }> = [{ path: `agents/${row.agentId}/agent.json`, doc: agentDoc, format: 'json' }]
+    if (operating && typeof operating === 'object' && Object.keys(operating).length) docs.push({ path: `agents/${row.agentId}/operating.json`, doc: operating, format: 'json' })
+    const bound: AgentBindings = { ...(bindings.get(row.agentId) ?? { functions: [], workflows: [] }) }
+    // Context and data comes as the Agent's dependency: each object type it names is pulled with it.
+    const context = await readAgentContext(source, row)
+    if ('grants' in context) {
+      if (context.grants.length) bound.blueprint = context.grants
+      if (context.note) it.notes.push(context.note)
+    } else {
+      bound.blueprintUnread = true
+      it.notes.push(`Its Context and data couldn’t be read on the platform: ${context.unread}. Until it can be read, local dev gives it read access to the object types the project holds, as an adaptation, so locally it may read more than on the platform`)
+    }
+    if (bound.functions.length || bound.workflows.length || bound.blueprint?.length || bound.blueprintUnread) docs.push({ path: `agents/${row.agentId}/bindings.json`, doc: bound, format: 'json' })
+    await nameUnknownAgents(source, directory, docs)
+    out.push(finish(it, directory, docs))
+  }
+  return out
+}
+
+async function readWorkflows(source: SyncSource, lists: Lists, directory: Directory, opts: ReadOptions, warnings: string[]): Promise<RemoteItem[]> {
+  const out: RemoteItem[] = []
+  for (const row of lists.workflows) {
+    const ref = `workflow/${row.slug}`
+    if (!wanted(opts, ref)) continue
+    const n = opts.drafts?.has(ref) || !row.liveVersion ? row.latestDraftNumber ?? row.liveVersion : row.liveVersion
+    if (!n) continue
+    // Live, and its triggers on or off: `local dev` makes the runtime's copy the same (where that is safe there).
+    const it = item('workflow', row.slug, row.displayName || readableName(row.slug), {}, { version: `v${n}`, id: row.id, state: { live: n === row.liveVersion, enabled: row.enabled !== false } })
+    if (n !== row.liveVersion) it.notes.push(row.liveVersion ? `Read from draft version ${n}, as asked` : 'Not live on the platform: its draft was read')
+    else if (row.enabled === false) it.notes.push('Live on the platform with its triggers switched off; it is the same locally')
+    try {
+      const version = one<{ definition?: Record<string, unknown>; layout?: unknown }>(await source.workspace.get(`/v1/workflows/${encodeURIComponent(row.slug)}/versions/${n}`))
+      if (!version?.definition) continue
+      const doc = version.layout ? { ...version.definition, layout: version.layout } : version.definition
+      await nameUnknownAgents(source, directory, [{ doc }])
+      noteUnnamedActions(it, doc, directory)
+      out.push(finish(it, directory, [{ path: `workflows/${row.slug}.yaml`, doc, format: 'yaml' }]))
+    } catch (err) {
+      warnings.push(`Workflow ${row.slug}: ${(err as Error).message}`)
+    }
+  }
+  return out
+}
+
+const TEXT_LIMIT = 1_000_000
+const SKIP_DIRS = new Set(['.frontera', 'node_modules', '.git', 'dist', '.next', 'coverage'])
+
+/** Unpack a Function's source archive into memory: path → text, binary and tool state left out. */
+function unpack(bytes: Uint8Array): Map<string, string> {
+  const dir = mkdtempSync(join(tmpdir(), 'frontera-sync-fn-'))
+  try {
+    const archive = join(dir, 'src.tgz')
+    writeFileSync(archive, bytes)
+    const out = join(dir, 'out')
+    spawnSync('mkdir', ['-p', out])
+    const res = spawnSync('tar', ['-xzf', archive, '-C', out], { stdio: 'ignore' })
+    if (res.status !== 0) throw new Error('the source archive could not be unpacked')
+    const files = new Map<string, string>()
+    const walk = (d: string) => {
+      for (const name of readdirSync(d)) {
+        const full = join(d, name)
+        const rel = relative(out, full).split('\\').join('/')
+        const st = statSync(full)
+        if (st.isDirectory()) {
+          if (!SKIP_DIRS.has(name)) walk(full)
+        } else if (st.isFile() && st.size <= TEXT_LIMIT) {
+          const buf = readFileSync(full)
+          if (!buf.includes(0)) files.set(rel, buf.toString('utf8'))
+        }
+      }
+    }
+    walk(out)
+    return files
+  } finally {
+    rmSync(dir, { recursive: true, force: true })
+  }
+}
+
+/** The file and the relative files it imports, transitively, within the archive. */
+function withImports(files: Map<string, string>, entry: string): string[] {
+  const seen = new Set<string>()
+  const visit = (path: string) => {
+    if (seen.has(path) || !files.has(path)) return
+    seen.add(path)
+    for (const m of files.get(path)!.matchAll(/from\s+['"](\.{1,2}\/[^'"]+)['"]/g)) {
+      const base = posix.normalize(posix.join(posix.dirname(path), m[1]!))
+      for (const candidate of [base, `${base}.ts`, `${base}/index.ts`]) if (files.has(candidate)) visit(candidate)
+    }
+  }
+  visit(entry)
+  return [...seen]
+}
+
+/**
+ * A Function from the Functions editor: its saved draft as a project file
+ * (`editorFunctionModule`). `null` when nobody saved one, or its handler
+ * cannot be joined to its manifest in a file.
+ */
+async function readEditorDraft(source: SyncSource, row: FunctionRow, it: RemoteItem, warnings: string[]): Promise<boolean> {
+  try {
+    const draft = one<{ saved?: boolean; manifest?: Record<string, unknown>; handler?: string }>(await source.workspace.get(`/v1/functions/${encodeURIComponent(row.slug)}/draft`))
+    if (!draft?.saved || typeof draft.handler !== 'string') return false
+    const module = editorFunctionModule(row.slug, draft.manifest ?? {}, draft.handler)
+    if (!module) {
+      warnings.push(`Function ${row.slug}: its editor draft's handler has no plain \`export default\`, so it was not pulled`)
+      return false
+    }
+    it.files[`functions/${row.slug}.ts`] = module
+    return true
+  } catch (err) {
+    warnings.push(`Function ${row.slug}: ${(err as Error).message}`)
+    return false
+  }
+}
+
+async function readFunctions(source: SyncSource, lists: Lists, opts: ReadOptions, warnings: string[]): Promise<RemoteItem[]> {
+  const out: RemoteItem[] = []
+  for (const row of lists.functions) {
+    const ref = `function/${row.slug}`
+    if (!wanted(opts, ref)) continue
+    // Switched off in the workspace: off here too (`local dev`), as a workflow is.
+    const state = { live: !!row.liveVersion, enabled: row.enabled !== false }
+    if (!row.liveVersion || opts.drafts?.has(ref)) {
+      // Never deployed, or its draft asked for: what the Functions editor holds.
+      const it = item('function', row.slug, readableName(row.slug), {}, { version: row.liveVersion ? `v${row.liveVersion}` : 'draft', id: row.id, state: { ...state, live: false } })
+      if (!(await readEditorDraft(source, row, it, warnings))) continue
+      it.notes.push(row.liveVersion ? 'Read from its draft in the Functions editor, as asked' : 'Never deployed in the workspace: its draft in the Functions editor was read')
+      if (!state.enabled) it.notes.push('Switched off in the workspace; it is off here too')
+      it.requires = []
+      out.push(it)
+      continue
+    }
+    const it = item('function', row.slug, readableName(row.slug), {}, { version: `v${row.liveVersion}`, id: row.id, state })
+    if (!state.enabled) it.notes.push('Switched off in the workspace; it is off here too')
+    let files: Map<string, string>
+    try {
+      files = unpack(await source.workspace.getBytes(`/v1/functions/${encodeURIComponent(row.slug)}/versions/${row.liveVersion}/source`))
+    } catch (err) {
+      // A version deployed from the Functions editor keeps no source archive: its source is the editor's draft.
+      if (await readEditorDraft(source, row, it, [])) {
+        it.notes.push('Deployed from the Functions editor; its draft there was read')
+        it.requires = []
+        out.push(it)
+        continue
+      }
+      warnings.push(`Function ${row.slug}: ${(err as Error).message}`)
+      continue
+    }
+    const single = `functions/${row.slug}.ts`
+    if (files.has(single)) {
+      // A Function written in a project: its file, the helpers it imports and its test, and the
+      // shared files it imports from outside functions/, where its source keeps them.
+      const imported = withImports(files, single)
+      const keep = imported.filter((p) => p.startsWith('functions/'))
+      const test = `functions/${row.slug}.test.ts`
+      if (files.has(test)) keep.push(test)
+      const beyond = imported.filter((p) => !p.startsWith('functions/') && !p.startsWith('vendor/')).sort()
+      const shared = beyond.filter(isSharedFunctionFile)
+      const outside = beyond.filter((p) => !isSharedFunctionFile(p))
+      for (const p of [...keep, ...shared]) it.files[p] = files.get(p)!
+      const list = (paths: string[]) => (paths.length > 3 ? `${paths.slice(0, 3).join(', ')} and ${paths.length - 3} more` : paths.length > 1 ? `${paths.slice(0, -1).join(', ')} and ${paths[paths.length - 1]}` : paths.join(''))
+      if (shared.length) it.notes.push(`Brings ${list(shared)}, which it imports from outside functions/, where its source keeps ${shared.length === 1 ? 'it' : 'them'}, so it builds as in the workspace`)
+      if (outside.length) {
+        it.notes.push(`Imports ${list(outside)}, in a folder that holds the project’s own items: ${outside.length === 1 ? 'it is' : 'they are'} not pulled, so local dev can’t build it until the project has ${outside.length === 1 ? 'that file' : 'those files'}`)
+        warnings.push(`Function ${row.slug}: imports ${list(outside)}, which a pull does not write into a folder of the project’s own items`)
+      }
+    } else {
+      // A Function deployed from its own folder: the folder, under functions/<slug>/.
+      for (const [p, content] of files) if (!p.startsWith('.')) it.files[`functions/${row.slug}/${p}`] = content
+      if (!Object.keys(it.files).length) continue
+      it.notes.push('Deployed from its own folder; pulled as functions/' + row.slug + '/')
+    }
+    // Functions name other resources only in their code, if at all; nothing to rewrite.
+    it.requires = []
+    out.push(it)
+  }
+  noteSharedFunctionFiles(out, warnings)
+  return out
+}
+
+/**
+ * Two Functions whose sources hold the same file (a helper both import, or
+ * one Function's own file another imports) share one copy in the project.
+ * The same contents work for both; different contents mean one of them
+ * would run with the other's, so each says so, and the fetch warns.
+ */
+export function noteSharedFunctionFiles(items: RemoteItem[], warnings: string[]): void {
+  const holders = new Map<string, RemoteItem[]>()
+  for (const it of items) for (const path of Object.keys(it.files)) holders.set(path, [...(holders.get(path) ?? []), it])
+  for (const [path, list] of holders) {
+    if (list.length < 2 || new Set(list.map((i) => i.files[path])).size < 2) continue
+    const names = list.map((i) => i.name).sort()
+    const and = (words: string[]) => (words.length < 2 ? words.join('') : `${words.slice(0, -1).join(', ')} and ${words[words.length - 1]}`)
+    for (const it of list) {
+      const others = names.filter((n) => n !== it.name)
+      it.notes.push(`${path} is in ${others.length === 1 ? 'Function' : 'Functions'} ${and(others)} too, with different contents: the project holds one copy, so they can’t all run as the workspace has them. Give each its own file`)
+    }
+    warnings.push(`Functions ${and(names)} each hold ${path} with different contents; the project can keep only one`)
+  }
+}
+
+/** An asset larger than this stays on the platform, named in the skill's notes. */
+const ASSET_LIMIT = 20 * 1024 * 1024
+
+/**
+ * A skill's assets (images, fonts, templates), each at the path the skill
+ * gives it: from the sync route, which serves them to the project's workspace
+ * key by the storage key the skill names; on a platform without it, from the
+ * skill-asset download route `frontera skill pull` reads (sessions only).
+ * They travel beside the skill's text files, not among them
+ * (`RemoteItem.assets`): a pull writes the ones the project does not have, and
+ * `skill push` uploads them again on the local runtime.
+ */
+async function readSkillAsset(source: SyncSource, skillId: string, storageKey: string, filename: string): Promise<Uint8Array> {
+  try {
+    return await source.workspace.getBytes(`/v1/sync/skills/${encodeURIComponent(skillId)}/asset?key=${encodeURIComponent(storageKey)}`)
+  } catch (err) {
+    if (!(err instanceof CliError) || err.code !== 'NOT_FOUND') throw err
+    // An older platform has no such route; the download route then answers, or says why not.
+    return await source.workspace.getBytes(`/v1/skill-assets/${encodeURIComponent(source.workspaceId)}/${encodeURIComponent(filename)}`).catch((older: unknown) => {
+      throw older instanceof CliError && older.code === 'UNAUTHORIZED'
+        ? new CliError('this platform gives skill assets to a signed-in person only, so it stays there; a newer platform gives them to the workspace key', { code: 'FORBIDDEN', hint: 'download it from the skill on the platform, or fetch again once the platform is newer', cause: older })
+        : older
+    })
+  }
+}
+
+async function readSkillAssets(source: SyncSource, name: string, skillId: string, assets: NonNullable<SkillDoc['assets']>, it: RemoteItem, warnings: string[]): Promise<void> {
+  const left: string[] = []
+  it.assets = []
+  for (const asset of assets) {
+    const filename = assetFilename(asset.storageKey)
+    if (!filename || !asset.path || (asset.bytes ?? 0) > ASSET_LIMIT) {
+      left.push(asset.path || asset.storageKey)
+      continue
+    }
+    try {
+      const bytes = await readSkillAsset(source, skillId, asset.storageKey, filename)
+      it.assets.push({ path: `skills/${name}/${asset.path}`, bytes })
+    } catch (err) {
+      warnings.push(`Skill ${name}: asset ${asset.path}: ${(err as Error).message}`)
+      left.push(asset.path)
+    }
+  }
+  if (it.assets.length) it.notes.push(`${it.assets.length} asset${it.assets.length === 1 ? '' : 's'} (images, fonts, templates) come too; one the project already has is kept`)
+  if (left.length) it.notes.push(`Not brought, so the skill works without ${left.length === 1 ? 'it' : 'them'} here: ${left.join(', ')}`)
+}
+
+async function readSkills(source: SyncSource, lists: Lists, opts: ReadOptions, warnings: string[]): Promise<RemoteItem[]> {
+  const out: RemoteItem[] = []
+  for (const row of lists.skills) {
+    if (!wanted(opts, `skill/${row.name}`)) continue
+    try {
+      const doc = one<SkillDoc>(await source.workspace.get(`/v1/config/workspace-skills/${row.id}`))
+      const it = item('skill', row.name, doc.displayName || row.displayName || readableName(row.name), { [`skills/${row.name}/SKILL.md`]: toSkillMd(doc) }, { id: row.id })
+      for (const ref of doc.references ?? []) it.files[`skills/${row.name}/refs/${ref.filename}`] = ref.content
+      for (const script of doc.scripts ?? []) it.files[`skills/${row.name}/${script.path}`] = script.content
+      if (doc.assets?.length) await readSkillAssets(source, row.name, row.id, doc.assets, it, warnings)
+      out.push(it)
+    } catch (err) {
+      warnings.push(`Skill ${row.name}: ${(err as Error).message}`)
+    }
+  }
+  return out
+}
+
+async function readKnowledge(source: SyncSource, lists: Lists, opts: ReadOptions, warnings: string[]): Promise<RemoteItem[]> {
+  const out: RemoteItem[] = []
+  for (const k of lists.knowledge.filter((x) => wanted(opts, `knowledge/${refName(x.name)}`))) {
+    const name = refName(k.name)
+    const doc = Object.fromEntries(Object.entries({
+      name: k.name,
+      description: k.description ?? undefined,
+      retrieval: k.retrieval ?? undefined,
+      chunker: k.chunker ?? undefined,
+      chunkSize: k.chunkSize ?? undefined,
+      chunkOverlap: k.chunkOverlap ?? undefined,
+      similarityThreshold: k.similarityThreshold ?? undefined,
+      topK: k.topK ?? undefined,
+      // How it searches and reads documents: hybrid search and reranking, extraction, OCR.
+      hybridConfig: k.hybridConfig ?? undefined,
+      extractorConfig: k.extractorConfig ?? undefined,
+      ocrConfig: k.ocrConfig ?? undefined,
+    }).filter(([, v]) => v !== undefined))
+    const it = item('knowledge', name, k.name, { [`knowledge/${name}/knowledge.json`]: json(doc) }, {
+      notes: ['Its documents stay on the platform: add them as Markdown or text files in this folder and `local dev` uploads them'],
+      requires: [],
+      id: k.id,
+    })
+    // Its quality checks come with it, their documents named by path; their runs stay on the platform.
+    const checks = await quietly(warnings, `Knowledge ${k.name} quality checks`, async () => {
+      const fixtures = fixtureRows(await source.workspace.get(`/v1/workspace-knowledge/${encodeURIComponent(k.id)}/eval/fixtures`))
+      if (!fixtures.length) return null
+      const named = fixtures.some((f) => f.expectedSourceIds?.length)
+      // Loaded here: the documents module reads this one's helpers.
+      const { readFolders } = await import('./local-knowledge-documents')
+      const paths = named
+        ? sourcePaths(sourceRows(await source.workspace.get(`/v1/workspace-knowledge/${encodeURIComponent(k.id)}/sources`)), await readFolders(source.workspace, k.id))
+        : new Map<string, string>()
+      return checksFromFixtures(fixtures, paths)
+    }, null)
+    if (checks) {
+      it.files[qualityChecksPath(name)] = qualityChecksText(checks.checks)
+      if (checks.unnamed) it.notes.push(`${checks.unnamed} of its quality checks’ expected documents ${checks.unnamed === 1 ? 'is' : 'are'} no longer in the knowledge base, so ${checks.unnamed === 1 ? 'it is' : 'they are'} left out of the file`)
+    }
+    out.push(it)
+  }
+  return out
+}
+
+/**
+ * What a Plugin may do on the workspace, as `policy` in its file: whether it
+ * is on, its Action policy (`read_only` refuses every tool that changes
+ * something), what a tool found later starts as, and each tool's own setting
+ * (on or off, an approval it needs, limits on its inputs). The local runtime
+ * applies the same, so an Agent cannot call a tool there that the workspace
+ * keeps from it.
+ */
+export function pluginPolicy(install: NonNullable<AppRow['install']>, tools: ToolRow[] | undefined, notes: string[]): Record<string, unknown> {
+  const own: Record<string, Record<string, unknown>> = {}
+  let readable = !!tools?.length
+  for (const t of tools ?? []) {
+    if (!('policy' in t)) readable = false
+    if (!t.policy) continue
+    const setting = Object.fromEntries(Object.entries({ enabled: t.policy.enabled, requiresApproval: t.policy.requiresApprovalOverride, paramConstraints: t.policy.paramConstraints }).filter(([, v]) => v !== null && v !== undefined))
+    if (Object.keys(setting).length) own[t.name] = setting
+  }
+  const actions = install.actionPolicy ?? 'read_only'
+  if (tools?.length && !readable && actions === 'custom') notes.push('Each tool’s own setting could not be read from this platform; locally its tools stay off until set in Studio → Plugins')
+  return {
+    enabled: install.enabled ?? true,
+    actions,
+    newTools: install.newCapabilityDefault ?? 'disabled',
+    ...(Object.keys(own).length ? { tools: Object.fromEntries(Object.entries(own).sort(([a], [b]) => a.localeCompare(b))) } : {}),
+  }
+}
+
+/** The image types a Plugin's icon may be uploaded as, by extension. */
+const ICON_TYPES: Record<string, string> = { 'image/png': 'png', 'image/jpeg': 'jpg', 'image/webp': 'webp', 'image/gif': 'gif', 'image/svg+xml': 'svg' }
+
+/**
+ * A Plugin's icon, read from the short-lived link the Plugin list gives
+ * (`iconUrl`), as `mcp/<name>.icon.<ext>` beside its file. Null when it has
+ * none or it could not be read (said in its notes).
+ */
+async function readPluginIcon(name: string, url: string | null | undefined, notes: string[]): Promise<{ path: string; bytes: Uint8Array } | null> {
+  if (!url) return null
+  try {
+    const res = await fetch(url, { signal: AbortSignal.timeout(30_000) })
+    if (!res.ok) throw new Error(`answered ${res.status}`)
+    const type = (res.headers.get('content-type') ?? '').split(';')[0]!.trim().toLowerCase()
+    const ext = ICON_TYPES[type] ?? /\.(png|jpe?g|webp|gif|svg)(?:\?|$)/i.exec(new URL(url).pathname)?.[1]?.toLowerCase().replace('jpeg', 'jpg')
+    if (!ext) throw new Error(`not an image (${type || 'no type'})`)
+    const bytes = new Uint8Array(await res.arrayBuffer())
+    if (bytes.byteLength > 2 * 1024 * 1024) throw new Error('over 2 MB')
+    return { path: `mcp/${name}.icon.${ext}`, bytes }
+  } catch (err) {
+    notes.push(`Its icon stays on the platform: ${(err as Error).message}`)
+    return null
+  }
+}
+
+async function readPlugins(lists: Lists, opts: ReadOptions, tools: PluginTools): Promise<RemoteItem[]> {
+  const out: RemoteItem[] = []
+  for (const a of lists.apps) {
+    if (!a.install || (a.catalog?.kind ?? '').toLowerCase() !== 'mcp' || !wanted(opts, `plugin/${a.install.installName}`)) continue
+    const config = (a.install.config ?? {}) as Record<string, unknown>
+    const notes: string[] = []
+    // Its own words and icon in the Plugin list, before its connection settings.
+    const doc: Record<string, unknown> = a.install.description?.trim() ? { description: a.install.description.trim() } : {}
+    const icon = await readPluginIcon(a.install.installName, a.install.iconUrl, notes)
+    if (icon) doc.icon = icon.path
+    for (const [k, v] of Object.entries(config)) {
+      if (k === 'headers' && v && typeof v === 'object' && !Array.isArray(v)) {
+        // A header that carries no credential keeps its value; the others come down declared and
+        // empty, as placeholders: their values are never pulled (they come back masked anyway).
+        doc.headers = Object.fromEntries(Object.entries(v as Record<string, unknown>).map(([h, value]) =>
+          [h, NON_SECRET_HEADERS.has(h.toLowerCase()) && typeof value === 'string' && !MASKED.test(value) ? value : '']))
+        continue
+      }
+      doc[k] = SECRETISH.test(k) || (typeof v === 'string' && MASKED.test(v)) ? '' : v
+    }
+    const inputs = pluginSecretInputs(a.install.installName, doc)
+    if (inputs.length) notes.push(`Secrets come down empty, never with their values: ${inputs.map((i) => `${i.header ? 'header ' : ''}${i.field} (\`frontera secret set ${i.secret}\`)`).join(', ')}; \`local dev\` fills each from that secret on this computer`)
+    if (typeof doc.url === 'string' && !/^https?:\/\/(127\.0\.0\.1|localhost)/.test(doc.url)) notes.push(`Points at ${doc.url}; the local runtime must be able to reach it`)
+    doc.policy = pluginPolicy(a.install, tools.get(a.install.id), notes)
+    const it = item('plugin', a.install.installName, a.catalog?.displayName || readableName(a.install.installName), { [`mcp/${a.install.installName}.plugin.json`]: json(doc) }, { notes, requires: [], id: a.install.id })
+    if (icon) it.assets = [icon]
+    out.push(it)
+  }
+  return out
+}
+
+interface BundleAnswer { definition: Parameters<typeof toFiles>[0] | null; datasetNames: Record<string, string> }
+
+/**
+ * The saved object sets as Blueprint files (`blueprint/object-sets/<name>.yaml`):
+ * the object type each returns and its definition, or, for a static set, the
+ * keys of the records it lists. A set naming another (`reference`) names it
+ * `objectSet/<name>`. `local dev` saves them on the local runtime after the
+ * Blueprint is published there.
+ */
+export function objectSetItems(sets: ObjectSetRow[], directory: Directory, objectTypes?: Set<string>): RemoteItem[] {
+  const names = new Map([...(directory.objectSet ?? new Map<string, string>())].map(([name, id]) => [id, name]))
+  return sets.flatMap((set) => {
+    const name = names.get(set.id)
+    // A set on an object type this read did not bring cannot apply: the type is not in the project.
+    if (!name || (objectTypes && !objectTypes.has(set.objectType))) return []
+    const doc: Record<string, unknown> = {
+      name: set.name,
+      ...(set.description ? { description: set.description } : {}),
+      objectType: set.objectType,
+      kind: set.kind,
+      ...(set.kind === 'static' ? { records: set.staticPks ?? [] } : { definition: set.definition ?? null }),
+    }
+    const it = item('blueprint', `object-sets/${name}`, set.name, {}, { id: set.id })
+    const { doc: named, unresolved } = toNames(doc, directory)
+    it.unresolved.push(...unresolved.map((u) => ({ ...u, path: `blueprint/object-sets/${name}.yaml: ${u.path}` })))
+    it.files[`blueprint/object-sets/${name}.yaml`] = stringifyYaml(named, { lineWidth: 0 })
+    const others = referencesIn(named).filter((r) => r.kind === 'objectSet' && r.name !== name).map((r) => itemRef(r.kind, r.name))
+    it.requires = [itemRef('objectType', set.objectType), ...new Set(others)].sort()
+    if (set.kind === 'static') {
+      const n = set.staticPks?.length ?? 0
+      it.notes.push(`Lists ${n} ${set.objectType} record${n === 1 ? '' : 's'} by key; locally it holds those of them this runtime’s data has`)
+    }
+    return [it]
+  })
+}
+
+type Lifecycle = { draft?: { definition?: BundleAnswer['definition'] } | null; activeRelease?: { definition?: BundleAnswer['definition'] } | null }
+
+/**
+ * The organization's unpublished Blueprint draft cut to what the workspace's
+ * slice holds: its object types (by API name, as the workspace is granted
+ * them now), the relations between them and their metrics, with the draft's
+ * Actions on them. Read with the organization key: the draft is a
+ * steward's, so a workspace key does not read it.
+ */
+export function sliceDraft(draft: Bundle, granted: ReadonlySet<string>): Bundle {
+  const def = draft as unknown as { objects: Array<{ id: string; apiName: string }>; relationships: Array<{ fromObjectId: string; toObjectId: string }>; metrics: Array<{ objectId: string }>; actions?: Array<Record<string, any>> }
+  const objects = def.objects.filter((o) => granted.has(o.apiName))
+  const ids = new Set(objects.map((o) => o.id))
+  const actions = (def.actions ?? []).filter((a) => {
+    const changes = (Array.isArray(a.businessOutcomes) ? a.businessOutcomes : []).flatMap((o: Record<string, any>) => (Array.isArray(o?.expectedChanges) ? o.expectedChanges : [])) as Array<Record<string, any>>
+    return [a.subject?.objectTypeId, ...changes.map((c) => c?.objectTypeId)].filter((v): v is string => typeof v === 'string').every((id) => ids.has(id))
+  })
+  return {
+    ...def,
+    objects,
+    relationships: def.relationships.filter((r) => ids.has(r.fromObjectId) && ids.has(r.toObjectId)),
+    metrics: def.metrics.filter((m) => ids.has(m.objectId)),
+    ...('actions' in def ? { actions } : {}),
+  } as unknown as Bundle
+}
+
+async function readBlueprint(
+  source: SyncSource,
+  mode: 'workspace' | 'organization',
+  warnings: string[],
+  notes: string[],
+  sets: { lists: Lists; directory: Directory } = { lists: { agents: [], workflows: [], functions: [], knowledge: [], apps: [], skills: [] }, directory: {} },
+  opts: { draft?: boolean } = {},
+): Promise<RemoteItem[]> {
+  let answer: BundleAnswer | null = null
+  // The draft read in place of the release, already holding its Actions.
+  let fromDraft = false
+  if (mode === 'organization' && source.organization) {
+    const lifecycle = one<Lifecycle>(await source.organization.get('/v1/blueprint/lifecycle'))
+    fromDraft = !!lifecycle.draft?.definition && (!!opts.draft || !lifecycle.activeRelease?.definition)
+    answer = { definition: (fromDraft ? lifecycle.draft?.definition : lifecycle.activeRelease?.definition) ?? null, datasetNames: await datasetNames(source.organization) }
+    if (fromDraft) notes.push(opts.draft ? 'The Blueprint was read from its unpublished draft, as asked' : 'The Blueprint has no published release; its draft was read')
+  } else {
+    const sliced = await source.workspace.find<unknown>('/v1/sync/blueprint')
+    if (sliced) answer = one<BundleAnswer>(sliced)
+    else if (source.organization) {
+      notes.push('This platform cannot cut the Blueprint to the workspace yet; the organization key read the whole model')
+      return readBlueprint(source, 'organization', warnings, notes, sets, opts)
+    } else {
+      warnings.push('Blueprint: this platform cannot export a workspace’s Blueprint yet; connect an organization key to pull it')
+      return []
+    }
+    if (opts.draft && !source.organization) notes.push('Reading the Blueprint’s unpublished draft takes an organization key; its published release was read')
+    if (opts.draft && source.organization && answer) {
+      // The draft, cut to the object types the workspace's slice holds now.
+      const lifecycle = one<Lifecycle>(await source.organization.get('/v1/blueprint/lifecycle'))
+      const granted = new Set(((answer.definition as { objects?: Array<{ apiName: string }> } | null)?.objects ?? []).map((o) => o.apiName))
+      if (lifecycle.draft?.definition) {
+        answer = { definition: sliceDraft(lifecycle.draft.definition, granted), datasetNames: { ...(answer.datasetNames ?? {}), ...(await datasetNames(source.organization)) } }
+        fromDraft = true
+        notes.push('The Blueprint was read from its unpublished draft, as asked, cut to the object types this workspace is granted')
+      }
+    }
+  }
+  if (!answer?.definition) return []
+  // The workspace's slice carries no governed Actions: reading them is organization-grain.
+  // With the organization key, the published Actions on the slice's object types come along.
+  const definition = mode === 'workspace' && source.organization && !fromDraft ? await withActions(source.organization, answer.definition, warnings, notes) : answer.definition
+  const model = toFiles(definition, new Map(Object.entries(answer.datasetNames ?? {})))
+  const objectTypes = new Set(model.files.flatMap((f) => (f.path.startsWith('object-types/') ? [f.apiName] : [])))
+  const saved = objectSetItems(sets.lists.objectSets ?? [], sets.directory, objectTypes)
+  return [...model.files.map((file) => {
+    const name = file.path.replace(/\.(ya?ml|json)$/, '')
+    // Named by its display name; its kind ("Action", "Object type") goes before it where it is said.
+    const shown = (file.document as { displayName?: unknown }).displayName
+    const it = { ...item('blueprint', name, typeof shown === 'string' && shown.trim() ? shown.trim() : file.apiName, { [`blueprint/${file.path}`]: serialize(file.path, file.document as Record<string, unknown>) }), requires: [] as string[] }
+    if (file.path.startsWith('actions/')) {
+      // An Action brings the object types it acts on, and says what it does on the local runtime.
+      const doc = file.document as Record<string, any>
+      const fit = actionFit(doc)
+      if (fit.subject) it.requires = [itemRef('objectType', fit.subject)]
+      it.notes.push(fit.runsLocally ? `Deployed on the local runtime when it applies: it writes ${fit.subject ?? 'its object'}’s records there` : `Published switched off on the local runtime: ${fit.reason}`)
+    }
+    return it
+  }), ...saved]
+}
+
+type Bundle = NonNullable<BundleAnswer['definition']>
+
+/**
+ * The organization's published Actions whose subject, and every object type
+ * they change, is in the workspace's slice. Read with the organization key;
+ * a refusal leaves them out and says so.
+ */
+async function withActions(org: SyncClient, sliced: Bundle, warnings: string[], notes: string[]): Promise<Bundle> {
+  const def = sliced as Bundle & { schemaVersion?: number; objects: Array<{ id: string }>; actions?: unknown[] }
+  if ((def.schemaVersion ?? 1) < 2) return sliced
+  let published: Array<Record<string, any>> = []
+  try {
+    const lifecycle = one<{ activeRelease?: { definition?: { actions?: Array<Record<string, any>> } } | null }>(await org.get('/v1/blueprint/lifecycle'))
+    published = lifecycle.activeRelease?.definition?.actions ?? []
+  } catch (err) {
+    warnings.push(`Governed Actions: ${(err as Error).message}`)
+    return sliced
+  }
+  const ids = new Set(def.objects.map((o) => o.id))
+  const kept: Array<Record<string, any>> = []
+  const outside: string[] = []
+  for (const action of published) {
+    const changes = (Array.isArray(action.businessOutcomes) ? action.businessOutcomes : []).flatMap((o: Record<string, any>) => (Array.isArray(o?.expectedChanges) ? o.expectedChanges : [])) as Array<Record<string, any>>
+    const touched = [action.subject?.objectTypeId, ...changes.map((c) => c?.objectTypeId)].filter((v): v is string => typeof v === 'string')
+    if (touched.every((id) => ids.has(id))) kept.push(action)
+    else outside.push(String(action.apiName))
+  }
+  if (outside.length) notes.push(`${outside.length} governed Action${outside.length === 1 ? ' acts' : 's act'} on object types this workspace isn’t granted, so ${outside.length === 1 ? 'it stays' : 'they stay'} out: ${outside.join(', ')}`)
+  return { ...def, actions: kept } as Bundle
+}
+
+async function datasetNames(org: SyncClient): Promise<Record<string, string>> {
+  const out: Record<string, string> = {}
+  try {
+    // The list pages at 100; follow its cursor.
+    let cursor: string | null = null
+    for (let page = 0; page < 50; page++) {
+      const listed: { items?: Array<{ id: string; apiName: string }>; nextCursor?: string | null } = one(await org.get(`/v1/data-integration/datasets?limit=100${cursor ? `&cursor=${encodeURIComponent(cursor)}` : ''}`))
+      for (const d of listed.items ?? []) {
+        const revisions = rows<{ id: string }>(await org.get(`/v1/data-integration/datasets/${d.id}/revisions`))
+        for (const r of revisions) out[r.id] = d.apiName
+      }
+      cursor = listed.nextCursor ?? null
+      if (!cursor) break
+    }
+  } catch {
+    // Without dataset access the model is pulled without its backings.
+  }
+  return out
+}
+
+interface EvalItem {
+  id: string
+  input: unknown
+  expectedOutput: unknown
+  expectations: unknown
+  agentName: string | null
+  /** authored, scenario, message …; absent on an older platform. */
+  subjectKind?: string
+  isGold?: boolean
+  /** The case's name in the project that proposed it; absent on an older platform. */
+  caseName?: string | null
+}
+interface EvalDataset { name: string; description?: string | null; totalItems: number; items: EvalItem[] }
+interface EvalSettings { regressionDatasets?: Record<string, string>; judgeModelSlug?: string | null; judgePanel?: string[] }
+
+const textOf = (v: unknown): string | null => {
+  if (typeof v === 'string') return v
+  if (v && typeof v === 'object') {
+    const o = v as Record<string, unknown>
+    for (const k of ['query', 'expected', 'text', 'message', 'output', 'answer']) if (typeof o[k] === 'string') return o[k] as string
+  }
+  return null
+}
+
+/** Datasets per page and items per dataset page, as `/v1/sync/evaluations` pages them. */
+const EVAL_DATASETS_PAGE = 50
+const EVAL_ITEMS_PAGE = 200
+/** Pages read at most: 10,000 items a dataset, 2,500 datasets. */
+const EVAL_PAGES = 50
+
+/**
+ * Every dataset and every item, a page at a time. A platform that does not
+ * page answers every page with the first; a page holding nothing new ends
+ * the reading there.
+ */
+async function readEvalDatasets(ws: SyncClient, first: unknown): Promise<EvalDataset[]> {
+  const datasets = rows<EvalDataset>(first)
+  const names = new Set(datasets.map((d) => d.name))
+  for (let page = 2, last = datasets.length; last >= EVAL_DATASETS_PAGE && page <= EVAL_PAGES; page++) {
+    const more = rows<EvalDataset>(await ws.get(`/v1/sync/evaluations?page=${page}`)).filter((d) => !names.has(d.name))
+    for (const d of more) names.add(d.name)
+    datasets.push(...more)
+    last = more.length
+  }
+  for (const ds of datasets) {
+    const seen = new Set(ds.items.map((i) => i.id))
+    for (let page = 2; ds.items.length < ds.totalItems && page <= EVAL_PAGES; page++) {
+      const [next] = rows<EvalDataset>(await ws.get(`/v1/sync/evaluations?dataset=${encodeURIComponent(ds.name)}&itemsPage=${page}`))
+      const fresh = (next?.items ?? []).filter((i) => !seen.has(i.id))
+      if (!fresh.length) break
+      for (const i of fresh) seen.add(i.id)
+      ds.items.push(...fresh)
+      if ((next?.items.length ?? 0) < EVAL_ITEMS_PAGE) break
+    }
+  }
+  return datasets
+}
+
+/** The check types the local runner grades in code, as the platform's expectation grading does. */
+const LOCAL_CHECKS = new Set(['contains', 'regex', 'tool_called', 'tool_not_called'])
+
+/**
+ * A scenario's simulated results and expected actions name Functions and
+ * workflows by id or slug; a project names them by slug (`refund-eligibility`),
+ * which the local runtime takes too.
+ */
+function scenarioNames(value: unknown, byId: Map<string, { kind: RefKind; name: string }>, unnamed: Set<string>, named: Set<string>): unknown {
+  const name = (id: string) => {
+    const known = byId.get(id)
+    if (known && (known.kind === 'function' || known.kind === 'workflow')) {
+      named.add(`${known.kind}/${known.name}`)
+      return known.name
+    }
+    if (/^[0-9a-f]{8}-[0-9a-f]{4}-/i.test(id)) unnamed.add(id)
+    return id
+  }
+  const v = value as { scenario?: Record<string, unknown>; expect?: Record<string, unknown> }
+  const results = v.scenario?.results && typeof v.scenario.results === 'object' ? (v.scenario.results as Record<string, unknown>) : null
+  const actions = Array.isArray(v.expect?.actions) ? (v.expect!.actions as Array<Record<string, unknown>>) : null
+  return {
+    ...v,
+    ...(v.scenario ? { scenario: { ...v.scenario, ...(results ? { results: Object.fromEntries(Object.entries(results).map(([k, r]) => [k === '*' ? k : name(k), r])) } : {}) } } : {}),
+    ...(v.expect ? { expect: { ...v.expect, ...(actions ? { actions: actions.map((a) => (typeof a.resource === 'string' ? { ...a, resource: name(a.resource) } : a)) } : {}) } } : {}),
+  }
+}
+
+export interface EvalCaseOut {
+  name: string
+  conversation?: Array<{ user: string }>
+  expected?: string
+  expectedContains?: string[]
+  checks?: Array<Record<string, unknown>>
+  judged?: string[]
+  gold?: true
+  scenario?: Record<string, unknown>
+  expect?: Record<string, unknown>
+}
+
+/**
+ * One dataset item as a local test case, or why it stays on the platform:
+ * - a question with its expected answer and checks: `contains` as
+ *   `expectedContains`, a pattern or a tool call (made or not) as `checks`,
+ *   which the local runner grades the way the platform does; an expectation
+ *   only the platform's judge grades is kept in `judged`, in words;
+ * - a scenario (a conversation with a simulated customer) with its spec and
+ *   what it expects, which `local test` runs on the local runtime's own
+ *   evaluation runner;
+ * - an item that replays a real conversation stays on the platform: its
+ *   turns are the workspace's records (design §8).
+ * A gold item says so (`gold: true`).
+ */
+export function evalCase(item: EvalItem, name: string, byId: Map<string, { kind: RefKind; name: string }> = new Map()): { case: EvalCaseOut | null; why?: 'conversation' | 'no-question'; judged: number; unnamed: string[]; requires?: string[] } {
+  const input = (item.input ?? null) as Record<string, unknown> | null
+  const gold = item.isGold ? { gold: true as const } : {}
+  if (item.subjectKind === 'scenario' || (input && typeof input.opening === 'string' && typeof input.goal === 'string')) {
+    const { name: _name, ...spec } = (input ?? {}) as Record<string, unknown>
+    const unnamed = new Set<string>()
+    const refs = new Set<string>()
+    const named = scenarioNames({ scenario: spec, expect: (item.expectations ?? {}) as Record<string, unknown> }, byId, unnamed, refs) as { scenario: Record<string, unknown>; expect: Record<string, unknown> }
+    return { case: { name, ...named, ...gold }, judged: 0, unnamed: [...unnamed], requires: [...refs] }
+  }
+  if (item.subjectKind === 'message' || (input && typeof input.conversationId === 'string')) return { case: null, why: 'conversation', judged: 0, unnamed: [] }
+  const question = textOf(item.input)
+  if (!question) return { case: null, why: 'no-question', judged: 0, unnamed: [] }
+  const expectations = Array.isArray(item.expectations) ? (item.expectations as Array<{ text?: unknown; check?: Record<string, unknown> }>) : []
+  const contains: string[] = []
+  const checks: Array<Record<string, unknown>> = []
+  const judged: string[] = []
+  for (const e of expectations) {
+    const type = String(e.check?.type ?? e.check?.kind ?? '')
+    if (e.check && LOCAL_CHECKS.has(type)) {
+      if (type === 'contains' && typeof e.check.value === 'string' && e.check.value) contains.push(e.check.value)
+      else if (type !== 'contains') checks.push({ ...(typeof e.text === 'string' && e.text ? { text: e.text } : {}), ...e.check, type })
+    } else if (typeof e.text === 'string' && e.text.trim()) judged.push(e.text.trim())
+  }
+  const expected = textOf(item.expectedOutput)
+  return {
+    case: {
+      name,
+      conversation: [{ user: question }],
+      ...(contains.length ? { expectedContains: contains } : expected ? { expected } : {}),
+      ...(checks.length ? { checks } : {}),
+      ...(judged.length ? { judged } : {}),
+      ...gold,
+    },
+    judged: judged.length,
+    unnamed: [],
+  }
+}
+
+/**
+ * Each item's case name: the one the project that proposed it gave it (a
+ * change request records it), so names survive a round trip and a reordered
+ * list; otherwise, or when two items claim one name, `<dataset>-<n>` by
+ * position, as before.
+ */
+export function caseNames(items: Array<Pick<EvalItem, 'caseName'>>, prefix: string): string[] {
+  const recorded = items.map((it) => (typeof it.caseName === 'string' && it.caseName.trim() ? it.caseName.trim() : null))
+  const claimed = new Map<string, number>()
+  for (const n of recorded) if (n) claimed.set(n, (claimed.get(n) ?? 0) + 1)
+  const used = new Set(recorded.filter((n): n is string => !!n && claimed.get(n) === 1))
+  return items.map((_, i) => {
+    const own = recorded[i]
+    if (own && claimed.get(own) === 1) return own
+    let name = `${prefix}-${String(i + 1).padStart(3, '0')}`
+    for (let k = 2; used.has(name); k++) name = `${prefix}-${String(i + 1).padStart(3, '0')}-${k}`
+    used.add(name)
+    return name
+  })
+}
+
+/**
+ * Evaluation datasets as local test cases, one file per dataset under the
+ * Agent its items were made for (`evalCase` says what a case keeps). Every
+ * dataset and item is read, a page at a time. A dataset that is an Agent's
+ * regression dataset in the workspace says so (`regression: true`), and
+ * `local test --regression` runs only those.
+ */
+async function readEvaluations(source: SyncSource, lists: Lists, directory: Directory, warnings: string[]): Promise<RemoteItem[]> {
+  const found = await source.workspace.find<unknown>('/v1/sync/evaluations')
+  if (!found) {
+    warnings.push('Evaluations: this platform cannot export evaluation datasets yet')
+    return []
+  }
+  const datasets = await readEvalDatasets(source.workspace, found)
+  const settings = one<EvalSettings | null>(await source.workspace.find<unknown>('/v1/sync/evaluations/settings').catch(() => null))
+  const regression = settings?.regressionDatasets ?? {}
+  const byId = invert(directory)
+  const slugByName = new Map(lists.agents.map((a) => [a.name, a.agentId]))
+  const out: RemoteItem[] = []
+  for (const ds of datasets) {
+    const byAgent = new Map<string, EvalItem[]>()
+    for (const it of ds.items) {
+      const slug = (it.agentName && slugByName.get(it.agentName)) || lists.agents.find((a) => ds.name.toLowerCase().includes(a.agentId))?.agentId
+      if (!slug) continue
+      byAgent.set(slug, [...(byAgent.get(slug) ?? []), it])
+    }
+    const unplaced = ds.items.length - [...byAgent.values()].reduce((n, l) => n + l.length, 0)
+    for (const [slug, items] of byAgent) {
+      const notes: string[] = []
+      let noQuestion = 0
+      let conversations = 0
+      let judged = 0
+      let gold = 0
+      const unnamed = new Set<string>()
+      const requires = new Set<string>([`agent/${slug}`])
+      const names = caseNames(items, slugify(ds.name))
+      const cases = items.flatMap((it, i) => {
+        const made = evalCase(it, names[i]!, byId)
+        if (!made.case) {
+          if (made.why === 'conversation') conversations++
+          else noQuestion++
+          return []
+        }
+        judged += made.judged
+        if (made.case.gold) gold++
+        for (const id of made.unnamed) unnamed.add(id)
+        for (const r of made.requires ?? []) requires.add(r)
+        return [made.case]
+      })
+      if (conversations) notes.push(`${conversations} case${conversations === 1 ? ' replays' : 's replay'} a real conversation from the workspace, so ${conversations === 1 ? 'it stays' : 'they stay'} on the platform`)
+      if (noQuestion) notes.push(`${noQuestion} item${noQuestion === 1 ? '' : 's'} had no question the local runner can send`)
+      if (judged) notes.push(`${judged} expectation${judged === 1 ? ' is' : 's are'} graded by the platform’s judge; ${judged === 1 ? 'it is' : 'they are'} kept in the file (\`judged\`) and not graded locally`)
+      if (gold) notes.push(`${gold} gold case${gold === 1 ? '' : 's'} (human-certified)`)
+      if (unnamed.size) notes.push(`A scenario names ${unnamed.size} Function${unnamed.size === 1 ? ' or workflow' : 's or workflows'} by a platform id the workspace no longer has`)
+      if (ds.totalItems > ds.items.length) notes.push(`The first ${ds.items.length} of ${ds.totalItems} items were read`)
+      if (unplaced) notes.push(`${unplaced} item${unplaced === 1 ? '' : 's'} not tied to an Agent stayed on the platform`)
+      const isRegression = regression[slug] === ds.name
+      if (isRegression) notes.push(`${slug}’s regression dataset in the workspace: \`local test --regression\` runs it`)
+      const file = `agents/${slug}/evals/${slugify(ds.name)}.yaml`
+      const header = `# Test cases from the platform's evaluation dataset "${ds.name}" (frontera local sync).\n`
+      const doc = { ...(isRegression ? { regression: true } : {}), cases }
+      out.push(item('evaluation', `${slug}.${slugify(ds.name)}`, `${ds.name} → ${slug}`, { [file]: header + stringifyYaml(doc, { lineWidth: 0 }) }, { notes, requires: [...requires].sort() }))
+    }
+  }
+  return out
+}
+
+/**
+ * Everything the workspace has, as the project would hold it. `warnings`
+ * collects what could not be read (a kind the key may not see, a platform
+ * too old for an export), so the plan says so instead of failing.
+ */
+export async function readWorkspace(source: SyncSource, opts: ReadOptions = {}): Promise<{ items: RemoteItem[]; warnings: string[]; notes: string[]; directory: Directory }> {
+  const warnings: string[] = []
+  const notes: string[] = []
+  const { directory, lists } = await buildDirectory(source, warnings)
+  const want = (k: SyncKind) => !opts.kinds || opts.kinds.has(k)
+  // Each Plugin's tools, read once and only when a Plugin file or an Agent's tool settings need them.
+  let toolsRead: Promise<PluginTools> | null = null
+  const tools = () => (toolsRead ??= readPluginTools(source, lists.apps, warnings))
+  const pluginsWanted = want('plugin') && lists.apps.some((a) => a.install && (a.catalog?.kind ?? '').toLowerCase() === 'mcp' && wanted(opts, `plugin/${a.install.installName}`))
+  const groups = await Promise.all([
+    want('blueprint')
+      ? quietly(warnings, 'Blueprint', () => readBlueprint(source, opts.blueprint ?? 'workspace', warnings, notes, { lists, directory }, { draft: [...(opts.drafts ?? [])].some((r) => r === 'blueprint' || r.startsWith('blueprint/')) }), [])
+      : [],
+    want('skill') ? readSkills(source, lists, opts, warnings) : [],
+    want('function') ? readFunctions(source, lists, opts, warnings) : [],
+    pluginsWanted ? tools().then((t) => readPlugins(lists, opts, t)) : [],
+    want('knowledge') ? readKnowledge(source, lists, opts, warnings) : [],
+    want('workflow') ? readWorkflows(source, lists, directory, opts, warnings) : [],
+    want('agent') ? readAgents(source, lists, directory, opts, warnings, tools) : [],
+    want('evaluation') ? quietly(warnings, 'Evaluations', () => readEvaluations(source, lists, directory, warnings), []) : [],
+    // Slide themes: the workspace's own; a platform without the route has none to bring.
+    want('theme')
+      ? quietly(warnings, 'Slide themes', async () => {
+          const found = await source.workspace.find<unknown>('/v1/sync/slide-themes')
+          return found === null ? [] : readThemes(source.workspace, rows<ThemeRow>(found), (ref) => wanted(opts, ref), warnings)
+        }, [])
+      : [],
+    // Chat Apps: the experience an Agent is used in; a platform without the route has none to bring.
+    want('chat-app')
+      ? quietly(warnings, 'Chat Apps', async () => {
+          const found = await source.workspace.find<unknown>('/v1/sync/chat-apps')
+          return found === null ? [] : readChatApps(rows<ChatAppRow>(found), directory, (ref) => wanted(opts, ref), notes)
+        }, [])
+      : [],
+    // Custom Apps: what each is and the Functions it may start; their code is their own project.
+    want('app')
+      ? quietly(warnings, 'Apps', async () => {
+          const found = await source.workspace.find<unknown>('/v1/sync/apps')
+          return found === null ? [] : readApps(rows<CustomAppRow>(found), (ref) => wanted(opts, ref))
+        }, [])
+      : [],
+    // The organization's brand, read-only here; one item read whole, as the Blueprint is.
+    want('brand')
+      ? quietly(warnings, 'the organization’s brand', async () => {
+          const found = await source.workspace.find<BrandRow>('/v1/sync/brand')
+          return found === null ? [] : readBrand(source.workspace, (found as { data?: BrandRow }).data ?? found, warnings)
+        }, [])
+      : [],
+    // What the workspace installed from the library: a record of where its items came from.
+    want('library')
+      ? quietly(warnings, 'library installations', async () => {
+          const found = await source.workspace.find<unknown>('/v1/sync/library')
+          return found === null ? [] : readLibrary(rows<LibraryRow>(found), directory)
+        }, [])
+      : [],
+  ])
+  const items = groups.flat()
+  noteConnections(items, lists)
+  noteActions(items, directory)
+  // What each item needs against what the local runtime can do (§8), with the Actions this read brought.
+  const actions = new Map(items.filter((i) => i.kind === 'blueprint' && i.name.startsWith('actions/')).flatMap((i) => Object.values(i.files).map((text) => [i.name.slice('actions/'.length), actionFit((parseYaml(text) ?? {}) as Record<string, unknown>)] as const)))
+  const titles = new Map(lists.apps.flatMap((a) => (a.install && a.catalog?.displayName ? [[a.install.installName, a.catalog.displayName] as const] : [])))
+  for (const it of items) it.portability = portabilityOf(it.kind, it.files, { connections: connectionNames(lists), builtIns: builtInKinds(lists), context: { actions, titles } })
+  if (!source.organization && items.some((i) => i.unresolved.length)) {
+    notes.push(directory.model?.size
+      ? 'Governed Actions are named only with an organization key (they are organization-wide); an Action step shows as an id until you connect one'
+      : 'Models and governed Actions are named only with an organization key (both are organization-wide); an LLM step’s model or an Action step shows as an id until you connect one')
+  }
+  return { items, warnings, notes, directory }
+}
+
+/**
+ * A built-in connection (Google Sheets, BigQuery, GitHub …) is signed in on
+ * the platform with OAuth or a service account, so it is never pulled as a
+ * Plugin file. Say so on each Agent and workflow that uses one, rather than
+ * leaving a reference the pull silently could not bring.
+ */
+/** The install names of the built-in connections (every installed Plugin that is not an MCP server). */
+export function connectionNames(lists: Pick<Lists, 'apps'>): Set<string> {
+  return new Set(lists.apps.flatMap((a) => (a.install && (a.catalog?.kind ?? '').toLowerCase() !== 'mcp' ? [a.install.installName] : [])))
+}
+
+/**
+ * The built-in Plugins that are not connections to another system, by install
+ * name: the Documentation plugin, which a local runtime serves from its own
+ * documentation, and the workspace's analytics, which stays on the platform.
+ */
+export function builtInKinds(lists: Pick<Lists, 'apps'>): Map<string, BuiltInKind> {
+  const out = new Map<string, BuiltInKind>()
+  for (const a of lists.apps) {
+    const kind = (a.catalog?.kind ?? '').toLowerCase()
+    if (!a.install) continue
+    if (kind === 'frontera_documentation') out.set(a.install.installName, 'documentation')
+    if (kind === 'rill') out.set(a.install.installName, 'analytics')
+  }
+  return out
+}
+
+export function noteConnections(items: RemoteItem[], lists: Pick<Lists, 'apps'>): void {
+  const builtIns = builtInKinds(lists)
+  const connections = new Map(
+    lists.apps.flatMap((a) => (a.install && (a.catalog?.kind ?? '').toLowerCase() !== 'mcp' ? [[`plugin/${a.install.installName}`, a.install.installName] as [string, string]] : [])),
+  )
+  for (const it of items) {
+    const all = (it.requires ?? []).flatMap((r) => (connections.has(r) ? [connections.get(r)!] : []))
+    const used = all.filter((n) => !builtIns.has(n))
+    if (all.some((n) => builtIns.get(n) === 'documentation')) it.notes.push('Uses Frontera’s documentation: locally its documentation tools read the documentation of the local runtime’s release')
+    if (all.some((n) => builtIns.get(n) === 'analytics')) {
+      it.notes.push(it.kind === 'workflow'
+        ? 'Uses the workspace’s analytics tools, which stay on the platform: a local runtime has no analytics, so locally a step on them stops and says so'
+        : 'Uses the workspace’s analytics tools, which stay on the platform: a local runtime has no analytics, so locally it runs without them')
+    }
+    if (!used.length) continue
+    const names = used.join(', ')
+    it.notes.push(`Uses ${names}: ${used.length === 1 ? 'a connection' : 'connections'} signed in on the platform, not pulled; locally a stand-in answers ${used.length === 1 ? 'its' : 'their'} tools with “not connected”`)
+  }
+}
+
+/**
+ * A governed Action comes down with the Blueprint when an organization key is
+ * connected, and the local runtime deploys it (D3), so a workflow or Agent
+ * naming one (`action/<apiName>`) runs locally. Without the organization key
+ * the Actions cannot be read: say which this item needs and how to bring
+ * them. More than three are counted, with the names after the sentence.
+ */
+export function noteActions(items: RemoteItem[], directory?: Directory): void {
+  for (const it of items) {
+    const names = [...new Set((it.requires ?? []).flatMap((r) => (r.startsWith('action/') ? [r.slice('action/'.length)] : r.startsWith('blueprint/actions/') ? [r.slice('blueprint/actions/'.length)] : [])))]
+    // Named and in the organization's Blueprint: it comes with the Blueprint and runs locally.
+    const missing = directory?.action ? names.filter((n) => !directory.action!.has(n)) : names
+    if (!missing.length) continue
+    const many = missing.length > 3
+    const list = missing.join(', ')
+    const subject = it.kind === 'workflow' ? 'this workflow' : 'this Agent'
+    if (directory?.action) {
+      it.notes.push(many ? `Runs ${missing.length} governed Actions that aren’t in the organization’s Blueprint: ${list}` : `Runs governed Action${missing.length === 1 ? '' : 's'} ${list}, not in the organization’s Blueprint`)
+      continue
+    }
+    const what = many ? `${missing.length} governed Actions` : `governed Action${missing.length === 1 ? '' : 's'} ${list}`
+    it.notes.push(`${subject.charAt(0).toUpperCase()}${subject.slice(1)} runs ${what}: add an organization key to bring ${missing.length === 1 ? 'it' : 'them'} with the Blueprint${many ? `: ${list}` : ''}`)
+  }
+}
+
+/**
+ * A workflow node whose Action could not be named keeps its platform id; say
+ * how many, and why, so the plan does not leave an id nobody can place.
+ */
+export function noteUnnamedActions(it: RemoteItem, doc: unknown, directory: Directory): void {
+  const known = new Set(directory.action?.values() ?? [])
+  const unnamed = new Set(governedActionIds(doc).flatMap((a) => (known.has(a.id) ? [] : [a.id])))
+  if (!unnamed.size) return
+  const why = directory.action ? 'they are not among the organization’s Blueprint Actions' : 'naming them takes an organization key that may read Blueprint Actions'
+  it.notes.push(`Runs ${unnamed.size} governed Action${unnamed.size === 1 ? '' : 's'} left as platform ids (${why}), so this workflow does not run locally until ${unnamed.size === 1 ? 'it is' : 'they are'} named`)
+}
+
+/** The kinds a reference names, as items a pull can bring along. */
+export const REF_TO_KIND: Partial<Record<RefKind, SyncKind>> = {
+  function: 'function',
+  workflow: 'workflow',
+  agent: 'agent',
+  knowledge: 'knowledge',
+  plugin: 'plugin',
+  skill: 'skill',
+}
+