@frontera-sdk/cli 1.52.28 → 1.52.29

package/src/commands/local/sync.ts

@@ -0,0 +1,941 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { basename } from 'node:path'
+
+import { CliError, UsageError } from '../../errors'
+import { canPrompt, promptSecret } from '../../prompt'
+import { allTargets } from '../../local/local-dev-sync'
+import { pullDocuments, type DocumentsPulled } from '../../local/local-knowledge-documents'
+import { lessonsToPropose, pullLessons, type LessonsPulled } from '../../local/local-lessons'
+import { analyticsNeeded, connectionsNeeded, documentationNeeded, standInPath, writePlatformOnly, writeStandIns } from '../../local/local-stand-ins'
+import { localProject, type LocalProject } from '../../local/local-project'
+import { normalizeOrigin, syncClient, type SyncClient } from '../../local/local-sync-client'
+import { getSyncKey, projectFile, readLink, removeSyncKey, setSyncKey, writeLink, type SyncLink } from '../../local/local-sync-link'
+import { describeRepair, repairBases, type BaseRepair } from '../../local/local-sync-base'
+import { conflictsId, mergeItemFiles, type Choice, type Conflict, type Side } from '../../local/local-sync-merge'
+import {
+  applyItems,
+  baseFiles,
+  computePlan,
+  forgetItems,
+  itemHash,
+  KIND_LABEL,
+  localFiles,
+  readLock,
+  refreshConflict,
+  resolveItem,
+  summarize,
+  SYNC_KINDS,
+  WORKSPACE_SUFFIX,
+  type ItemStatus,
+  type PlanItem,
+  type RemoteItem,
+  type Resolution,
+  type SyncKind,
+} from '../../local/local-sync-plan'
+import { readWorkspace, type SyncSource } from '../../local/local-sync-remote'
+import { buildStatusText, projectBuildSummary } from '../../local/local-build-summary'
+import { kindTitle } from '../../local/local-sync-names'
+import { describeUnresolved } from '../../local/local-sync-refs'
+import {
+  directoryOf,
+  dropBase,
+  fetchWorkspace,
+  knownGone,
+  markCleared,
+  readBase,
+  readCleared,
+  readSnapshot,
+  snapshotId,
+  snapshotItems,
+  usesGovernedActions,
+  writeBase,
+  type ClearedConflicts,
+  type FetchResult,
+  type RemoteSnapshot,
+} from '../../local/local-sync-snapshot'
+import { flagBool, flagString, type Command, type CommandContext } from '../types'
+import { currentRequest, readRequests } from '../../local/local-sync-push'
+import { syncPush, syncRequest } from './sync-request'
+
+/**
+ * `frontera local sync`: a local project's link to one platform workspace.
+ *
+ *   connect     check a workspace key (and an organization key) and record the link
+ *   fetch       record what the workspace holds now (`.frontera/sync/`), reading only what changed
+ *   status      offline: the last pull against the files and the last fetch (`--fetch` fetches first)
+ *   pull        the plan (`--preview`), or bring the chosen items in: fast-forward, or a three-way merge
+ *   diff        one item's base, local and workspace versions, file by file, and how they merge
+ *   resolve     settle an item both sides changed: a side per conflict, or the files as edited
+ *   push        propose what changed here as a change request (`sync-request.ts`)
+ *   request     the current change request: show it, apply it, or close it
+ *   disconnect  forget the keys, and with `--forget-link` the link too
+ *
+ * Only fetch (and pull, when the snapshot is missing or old) calls the
+ * platform; status and the plan read the recorded snapshot. Only `push`
+ * and `request apply` write to the workspace, through a change request.
+ * Keys arrive on stdin or at a hidden prompt and go to the keychain; the
+ * link is in `frontera.yaml`.
+ */
+
+/** A snapshot this recent is used as it is by pull; an older one is fetched again first. */
+const FRESH_MS = 5 * 60 * 1000
+
+const STATUS_WORD: Record<ItemStatus, string> = {
+  new: 'new',
+  // The words Forge's Pull dialog uses.
+  changed: 'incoming',
+  same: 'same',
+  edited: 'changed here',
+  conflict: 'both changed',
+  unresolved: 'conflicted',
+  'local-only': 'only here',
+  'deleted-remote': 'deleted in workspace',
+  'deleted-local': 'deleted here',
+}
+
+function needLink(project: LocalProject): SyncLink {
+  const link = readLink(project.root)
+  if (!link) throw new CliError('this project is not linked to a workspace', { code: 'SYNC_NOT_LINKED', hint: 'run `frontera local sync connect --platform <url>` with a workspace key' })
+  return link
+}
+
+export function sourceFor(project: LocalProject, link: SyncLink): SyncSource {
+  const key = getSyncKey(project, 'workspace')
+  if (!key) throw new CliError('no workspace key for this project on this machine', { code: 'SYNC_NO_KEY', hint: 'run `frontera local sync connect` to store one (the link is in frontera.yaml; keys are per machine)' })
+  const org = getSyncKey(project, 'organization')
+  return {
+    workspace: syncClient(link.platform, key),
+    organization: org ? syncClient(link.platform, org) : undefined,
+    workspaceId: link.workspace,
+  }
+}
+
+/** Items the project holds that the workspace may not: for the plan's "only here". */
+function localItems(project: LocalProject): Array<{ ref: string; kind: SyncKind; name: string; files: string[] }> {
+  return allTargets(project.root).flatMap((t): Array<{ ref: string; kind: SyncKind; name: string; files: string[] }> => {
+    if (t.kind === 'agent') return [{ ref: `agent/${t.slug}`, kind: 'agent', name: t.slug, files: [t.file] }]
+    if (t.kind === 'workflow') return [{ ref: `workflow/${t.slug}`, kind: 'workflow', name: t.slug, files: [t.file] }]
+    if (t.kind === 'function') {
+      const name = basename(t.file).replace(/\.ts$/, '')
+      return [{ ref: `function/${name}`, kind: 'function', name, files: [t.file] }]
+    }
+    return []
+  })
+}
+
+function kindsFlag(ctx: CommandContext): Set<SyncKind> | undefined {
+  const raw = flagString(ctx, 'kinds')
+  if (!raw) return undefined
+  const aliases: Record<string, SyncKind> = { agents: 'agent', workflows: 'workflow', functions: 'function', skills: 'skill', plugins: 'plugin', evaluations: 'evaluation', evals: 'evaluation', datasets: 'dataset', themes: 'theme', 'chat-apps': 'chat-app', chatapps: 'chat-app', apps: 'app' }
+  const out = new Set<SyncKind>()
+  for (const part of raw.split(',').map((s) => s.trim()).filter(Boolean)) {
+    const kind = (aliases[part] ?? part) as SyncKind
+    if (kind === 'lessons') throw new UsageError('lessons are brought with `--lessons`, not as a kind', 'pull with `frontera local sync pull --lessons`')
+    if (!(SYNC_KINDS as readonly string[]).includes(kind)) throw new UsageError(`unknown kind \`${part}\``, `use any of: ${SYNC_KINDS.filter((k) => k !== 'lessons').join(', ')}`)
+    out.add(kind)
+  }
+  return out
+}
+
+/** What a fetch did to items pulled with conflicts: redone against the newer version, or cleared by it. */
+export interface ConflictsSettled {
+  /** Still conflicted: `.workspace` copies rewritten, conflicts renumbered. */
+  refreshed: Array<{ ref: string; conflicts: number }>
+  /** The newer version merged cleanly with the files here: the merge is written. */
+  cleared: string[]
+  bases: BaseRepair[]
+}
+
+/**
+ * Items pulled with conflicts whose workspace version moved since: merge
+ * them again with the version the snapshot holds now, so the `.workspace`
+ * copies, the numbering and the lock follow the workspace. A newer version
+ * that merges cleanly ends the conflict and finishes the pull it came from.
+ */
+export async function settleConflicts(project: LocalProject, link: SyncLink, snapshot: RemoteSnapshot, source?: SyncSource): Promise<ConflictsSettled> {
+  const out: ConflictsSettled = { refreshed: [], cleared: [], bases: [] }
+  let lock = readLock(project.root)
+  if (!lock || lock.workspace !== link.workspace) return out
+  const items = new Map(snapshotItems(project.root, snapshot).map((i) => [i.ref, i]))
+  const moved = Object.entries(lock.items).filter(([ref, e]) => e.conflict && items.has(ref) && e.conflict.remote !== itemHash(items.get(ref)!.files))
+  if (!moved.length) return out
+  out.bases = await repairBases(project.root, moved.map(([ref, entry]) => ({ ref, entry, remote: items.get(ref)!.files })), { source, capabilities: snapshot.capabilities, directory: directoryOf(snapshot) })
+  const cleared: ClearedConflicts = {}
+  for (const [ref] of moved) {
+    const item = items.get(ref)!
+    const before = lock
+    const r = refreshConflict(project.root, link.workspace, item, lock, (p) => readBase(project.root, p))
+    lock = r.lock
+    if (r.outcome === 'renumbered') out.refreshed.push({ ref, conflicts: r.conflicts })
+    if (r.outcome === 'cleared') {
+      writeBase(project.root, [item], before)
+      cleared[ref] = { at: r.lock.items[ref]!.pulledAt, base: r.lock.items[ref]!.remote }
+      out.cleared.push(ref)
+    }
+  }
+  markCleared(project.root, cleared)
+  return out
+}
+
+/** Fetch into the snapshot with the project's keys, then bring conflicted items up to the newer version. */
+export async function fetchFor(project: LocalProject, link: SyncLink, opts: { full?: boolean } = {}): Promise<FetchResult & { conflicts: ConflictsSettled }> {
+  const source = sourceFor(project, link)
+  const result = await fetchWorkspace(project.root, source, { blueprint: link.blueprint, full: opts.full })
+  await nameLink(project, link, source)
+  return { ...result, conflicts: await settleConflicts(project, link, result.snapshot, source) }
+}
+
+/**
+ * A link made while the platform could not say the workspace's name (or
+ * before it could) learns it on the next fetch, so the project shows the
+ * workspace by its name rather than its id. The link passed in is named too.
+ */
+async function nameLink(project: LocalProject, link: SyncLink, source: SyncSource): Promise<void> {
+  if (link.workspaceName && link.organizationName) return
+  const identity = await source.workspace.find<{ workspace?: { name?: unknown }; organization?: { name?: unknown } }>('/v1/sync/identity').catch(() => null)
+  const name = (v: unknown) => (typeof v === 'string' && v.trim() ? v.trim() : undefined)
+  const workspaceName = link.workspaceName ?? name(identity?.workspace?.name)
+  const organizationName = link.organizationName ?? name(identity?.organization?.name)
+  if (workspaceName === link.workspaceName && organizationName === link.organizationName) return
+  Object.assign(link, { workspaceName, organizationName })
+  writeLink(project.root, link)
+}
+
+/** The snapshot for this link, when one was fetched for it. */
+function snapshotFor(project: LocalProject, link: SyncLink): RemoteSnapshot | null {
+  const snap = readSnapshot(project.root)
+  return snap && snap.workspace === link.workspace ? snap : null
+}
+
+/** The platform with the project's keys, or nothing when this machine has no workspace key. */
+function sourceIfKeyed(project: LocalProject, link: SyncLink): SyncSource | undefined {
+  try {
+    return sourceFor(project, link)
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * The plan from the recorded snapshot. `fetch`: `auto` fetches first when
+ * there is no snapshot or it is older than a few minutes, `always` first,
+ * `never` not at all (no snapshot: no plan). Items asked for as drafts are
+ * read live, since the snapshot holds what is live.
+ *
+ * `repair`: before merges are counted, a both-changed item whose base is
+ * missing gets it back where it can (`local-sync-base.ts`): `offline` from
+ * unchanged copies only, `online` from the platform too, at the lock's
+ * revision. `bases` says what was found and what was not.
+ */
+export async function planFor(project: LocalProject, link: SyncLink, opts: { kinds?: Set<SyncKind>; drafts?: Set<string>; fetch?: 'auto' | 'always' | 'never'; repair?: 'offline' | 'online' } = {}) {
+  const local = localItems(project).filter((l) => !opts.kinds || opts.kinds.has(l.kind))
+  const readFromBase = (path: string) => readBase(project.root, path)
+  const noBases: BaseRepair[] = []
+  if (opts.drafts?.size) {
+    const lock = readLock(project.root)
+    const base = lock?.workspace === link.workspace ? lock : null
+    const remote = await readWorkspace(sourceFor(project, link), { kinds: opts.kinds, drafts: opts.drafts, blueprint: link.blueprint })
+    return { remote, plan: computePlan(project.root, remote.items, base, local, { base: readFromBase, directory: remote.directory }), lock, snapshot: null, fetched: null, bases: noBases }
+  }
+  let snapshot = snapshotFor(project, link)
+  let fetched: Awaited<ReturnType<typeof fetchFor>> | null = null
+  const stale = !snapshot || Date.now() - Date.parse(snapshot.fetchedAt) > FRESH_MS
+  if (opts.fetch === 'always' || (opts.fetch !== 'never' && stale)) {
+    fetched = await fetchFor(project, link)
+    snapshot = fetched.snapshot
+  }
+  // Read after the fetch: settling conflicts may have moved it.
+  const lock = readLock(project.root)
+  const base = lock?.workspace === link.workspace ? lock : null
+  if (!snapshot) return { remote: { items: [], warnings: [], notes: [] }, plan: null, lock, snapshot: null, fetched, bases: noBases }
+  const items = snapshotItems(project.root, snapshot).filter((i) => !opts.kinds || opts.kinds.has(i.kind))
+  const planOpts = { remoteKnownGone: knownGone(snapshot), base: readFromBase, directory: directoryOf(snapshot) }
+  let plan = computePlan(project.root, items, base, local, planOpts)
+  let bases = noBases
+  if (opts.repair && base) {
+    const byRef = new Map(items.map((i) => [i.ref, i]))
+    const targets = plan.flatMap((p) => (p.status === 'conflict' || p.status === 'unresolved') && base.items[p.ref] ? [{ ref: p.ref, entry: base.items[p.ref]!, remote: byRef.get(p.ref)?.files }] : [])
+    if (targets.length) {
+      bases = await repairBases(project.root, targets, { source: opts.repair === 'online' ? sourceIfKeyed(project, link) : undefined, capabilities: snapshot.capabilities, directory: directoryOf(snapshot) })
+      if (bases.some((b) => b.restored.length)) plan = computePlan(project.root, items, base, local, planOpts)
+    }
+  }
+  // A conflict a later workspace change cleared says so while its base is the one that change left.
+  const cleared = readCleared(project.root)
+  for (const p of plan) if (cleared[p.ref] && base?.items[p.ref] && !base.items[p.ref]!.conflict && base.items[p.ref]!.remote === cleared[p.ref]!.base) p.cleared = true
+  return { remote: { items, warnings: snapshot.warnings, notes: snapshot.notes }, plan, lock, snapshot, fetched, bases }
+}
+
+/** The counts Forge's card and `status` show, by what they mean for a pull. */
+export function statusCounts(plan: PlanItem[]) {
+  const counts = summarize(plan)
+  const nowNamed = plan.filter((p) => p.namesOnly).length
+  const clashing = plan.filter((p) => p.status === 'conflict' && (p.merge?.conflicts ?? 0) > 0).length
+  return {
+    counts,
+    // Only the workspace moved; an item that only gained names is counted apart.
+    incoming: counts.changed - nowNamed,
+    nowNamed,
+    newInWorkspace: counts.new,
+    changedHere: counts.edited,
+    bothChanged: counts.conflict,
+    /** Both changed and a merge would come out clean. */
+    mergeable: counts.conflict - clashing,
+    /** Items with conflicts: pulled and not resolved, or both changed in a way a merge cannot settle. */
+    conflicts: counts.unresolved + clashing,
+    unresolved: counts.unresolved,
+    /** Were conflicted until a later workspace change merged cleanly with them. */
+    clearedByWorkspace: plan.filter((p) => p.cleared).length,
+    deletedInWorkspace: counts['deleted-remote'],
+    deletedHere: counts['deleted-local'],
+    onlyHere: counts['local-only'],
+  }
+}
+
+/**
+ * Each item that differs from the workspace, by reference, in the words of
+ * Forge's card: what a pull brings (`incoming`), what Propose changes sends
+ * (`outgoing`), a `conflict`, or `deleted-remote`. The same grouping as
+ * `statusCounts`, so a row's mark adds up with the card's counts.
+ */
+export function itemStates(plan: PlanItem[]): Record<string, 'incoming' | 'outgoing' | 'conflict' | 'deleted-remote'> {
+  const out: Record<string, 'incoming' | 'outgoing' | 'conflict' | 'deleted-remote'> = {}
+  for (const p of plan) {
+    if (p.status === 'same' || p.namesOnly) continue
+    if (p.status === 'unresolved' || (p.status === 'conflict' && (p.merge?.conflicts ?? 0) > 0)) out[p.ref] = 'conflict'
+    else if (p.status === 'changed' || p.status === 'new' || p.status === 'conflict') out[p.ref] = 'incoming'
+    else if (p.status === 'edited' || p.status === 'local-only' || p.status === 'deleted-local') out[p.ref] = 'outgoing'
+    else if (p.status === 'deleted-remote') out[p.ref] = 'deleted-remote'
+  }
+  return out
+}
+
+function platformOf(snapshot: RemoteSnapshot | null) {
+  if (!snapshot) return null
+  return { version: snapshot.platformVersion, capabilities: snapshot.capabilities, older: snapshot.full }
+}
+
+function planText(link: SyncLink, plan: PlanItem[], warnings: string[], notes: string[]): string {
+  const visible = plan.filter((p) => p.status !== 'same')
+  const lines = [`${link.workspaceName ?? link.workspace} — ${visible.length ? `${visible.length} to look at` : 'the project matches the workspace'}`]
+  for (const kind of SYNC_KINDS) {
+    const rows = visible.filter((p) => p.kind === kind)
+    if (!rows.length) continue
+    lines.push('', KIND_LABEL[kind])
+    for (const p of rows) {
+      // How it runs locally, as Forge's pill says it: nothing for portable.
+      const runs = p.portability && p.portability.class !== 'portable' ? ` · ${p.portability.class.replace('-', ' ')}` : ''
+      lines.push(`  ${p.selected ? '[x]' : '[ ]'} ${(statusWord(p) + runs).padEnd(28)} ${kindTitle(p.ref, p.title)}  (${p.ref})`)
+      for (const u of describeUnresolved(p.unresolved)) lines.push(`      ! ${u}`)
+      for (const n of p.notes) lines.push(`      · ${n}`)
+    }
+  }
+  for (const n of notes) lines.push('', `Note: ${n}`)
+  for (const w of warnings) lines.push('', `Could not read ${w}`)
+  lines.push('', 'Pull with `frontera local sync pull <kind/name>…`, `--kinds <kinds>` or `--all-changed`.')
+  if (visible.some((p) => p.merge?.conflicts)) lines.push('See a conflict with `frontera local sync diff <kind/name>`; settle it with `resolve`.')
+  return lines.join('\n')
+}
+
+const plural = (n: number, word: string) => `${n} ${word}${n === 1 ? '' : 's'}`
+
+/** "2 min ago (2026-10-17 12:03)": how fresh first, as Forge says it, then the time. */
+export function when(iso: string, now = Date.now()): string {
+  const t = Date.parse(iso)
+  if (!Number.isFinite(t)) return iso
+  const s = Math.max(0, Math.round((now - t) / 1000))
+  const m = Math.round(s / 60)
+  const h = Math.round(m / 60)
+  const d = Math.round(h / 24)
+  const rel = s < 45 ? 'just now' : m < 60 ? `${m} min ago` : h < 24 ? `${h} h ago` : d === 1 ? 'yesterday' : `${d} days ago`
+  const at = new Date(t)
+  const pad = (n: number) => String(n).padStart(2, '0')
+  return `${rel} (${at.getFullYear()}-${pad(at.getMonth() + 1)}-${pad(at.getDate())} ${pad(at.getHours())}:${pad(at.getMinutes())})`
+}
+
+/** What an item's row says: its status, and for a merge how it comes out. */
+function statusWord(p: PlanItem): string {
+  if (p.cleared) return `${STATUS_WORD[p.status]} (conflict cleared by a workspace change)`
+  if (p.namesOnly) return 'now named'
+  if (p.status === 'conflict') return p.merge?.conflicts ? plural(p.merge.conflicts, 'conflict') : 'merges cleanly'
+  if (p.status === 'unresolved') return `conflicted (${p.merge?.conflicts ?? 0})`
+  return STATUS_WORD[p.status]
+}
+
+/** Comma-separated refs from a flag. */
+function refsFlag(ctx: CommandContext, name: string): string[] {
+  return (flagString(ctx, name) ?? '').split(',').map((s) => s.trim()).filter(Boolean)
+}
+
+async function readKeys(ctx: CommandContext, wantOrg: boolean): Promise<{ workspace: string; organization: string | null }> {
+  const fromStdin = flagString(ctx, 'workspace-key') === '-' || flagString(ctx, 'org-key') === '-'
+  if (fromStdin) {
+    const lines = readFileSync(0, 'utf8').split(/\r?\n/).map((l) => l.trim()).filter(Boolean)
+    return { workspace: lines[0] ?? '', organization: wantOrg ? (lines[1] ?? null) : null }
+  }
+  if (!canPrompt()) throw new UsageError('no key given', 'pass `--workspace-key -` and the key on stdin')
+  const workspace = (await promptSecret('Workspace key (sk-ws-…): ')).trim()
+  const organization = wantOrg ? (await promptSecret('Organization key (sk-org-…): ')).trim() || null : null
+  return { workspace, organization }
+}
+
+interface WhoAmI { orgId: string | null; workspaceId: string | null; authKind: string }
+
+async function checkKeys(platform: string, keys: { workspace: string; organization: string | null }) {
+  if (!keys.workspace.startsWith('sk-ws-')) throw new UsageError('that is not a workspace key', 'a workspace key starts with sk-ws- (Settings → API keys in the workspace)')
+  const ws = syncClient(platform, keys.workspace)
+  const me = await ws.get<WhoAmI>('/v1/whoami')
+  if (me.authKind !== 'workspace-key' || !me.workspaceId || !me.orgId) throw new CliError('the platform did not accept it as a workspace key', { code: 'UNAUTHORIZED', hint: 'create one in the workspace (Settings → API keys) and connect again' })
+  const identity = await ws.find<{ workspace: { name: string }; organization: { name: string } }>('/v1/sync/identity').catch(() => null)
+  let org: SyncClient | null = null
+  if (keys.organization) {
+    if (!keys.organization.startsWith('sk-org-')) throw new UsageError('that is not an organization key', 'an organization key starts with sk-org-')
+    org = syncClient(platform, keys.organization)
+    const orgMe = await org.find<WhoAmI>('/v1/whoami').catch(() => null)
+    if (orgMe?.orgId && orgMe.orgId !== me.orgId) throw new CliError('the organization key belongs to another organization than the workspace', { code: 'USAGE', hint: 'use a key from the organization that owns the workspace' })
+    // The lifecycle is what an organization key is for here; reading it proves the key.
+    await org.get('/v1/blueprint/lifecycle')
+  }
+  return { me, identity }
+}
+
+const connect = async (ctx: CommandContext) => {
+  const project = localProject(ctx.cwd)
+  const previous = readLink(project.root)
+  const platformRaw = flagString(ctx, 'platform') ?? previous?.platform
+  if (!platformRaw) throw new UsageError('give the platform address', 'frontera local sync connect --platform https://api.acme.frontera.example')
+  const platform = normalizeOrigin(platformRaw)
+  const wantOrg = flagString(ctx, 'org-key') !== undefined
+  const keys = await readKeys(ctx, wantOrg)
+  if (!keys.workspace) throw new UsageError('no workspace key given', 'pass `--workspace-key -` with the key on stdin, or run in a terminal to be prompted')
+  const { me, identity } = await checkKeys(platform, keys)
+  if (previous && previous.workspace !== me.workspaceId && !flagBool(ctx, 'relink')) {
+    throw new CliError(`this project is linked to another workspace (${previous.workspaceName ?? previous.workspace})`, { code: 'CONFLICT', hint: 'a project links to one workspace; pass --relink to point it at this one' })
+  }
+  const blueprintFlag = flagString(ctx, 'blueprint')
+  if (blueprintFlag && blueprintFlag !== 'workspace' && blueprintFlag !== 'organization') throw new UsageError('--blueprint is workspace or organization', '`--blueprint organization` reads the whole model and needs an organization key')
+  const link: SyncLink = {
+    platform,
+    workspace: me.workspaceId!,
+    workspaceName: identity?.workspace.name ?? previous?.workspaceName,
+    organization: keys.organization ? me.orgId! : previous?.organization,
+    organizationName: identity?.organization.name ?? previous?.organizationName,
+    blueprint: (blueprintFlag as SyncLink['blueprint'] | undefined) ?? (previous?.blueprint === 'organization' && keys.organization ? 'organization' : 'workspace'),
+  }
+  // A folder that is not a project yet gets the project file the link lives in.
+  if (!existsSync(projectFile(project.root))) writeFileSync(projectFile(project.root), `# A Frontera project. \`frontera local dev\` applies agents/, workflows/, functions/ and blueprint/.\nname: ${basename(project.root)}\n`)
+  setSyncKey(project, 'workspace', keys.workspace)
+  if (keys.organization) setSyncKey(project, 'organization', keys.organization)
+  writeLink(project.root, link)
+  return {
+    data: { link, keys: { workspace: true, organization: !!(keys.organization || getSyncKey(project, 'organization')) } },
+    text: [
+      `Linked to ${link.workspaceName ?? link.workspace}${link.organizationName ? ` (${link.organizationName})` : ''} on ${new URL(platform).host}.`,
+      'Keys are in your keychain; the link is in frontera.yaml.',
+      'See what you can pull: `frontera local sync pull --preview`.',
+    ].join('\n'),
+  }
+}
+
+const fetchCommand = async (ctx: CommandContext) => {
+  const project = localProject(ctx.cwd)
+  const link = needLink(project)
+  const result = await fetchFor(project, link, { full: flagBool(ctx, 'full') })
+  const snap = result.snapshot
+  const count = Object.keys(snap.items).length
+  const what = result.changed.length || result.removed.length
+    ? [result.changed.length ? `${result.changed.length} changed` : '', result.removed.length ? `${result.removed.length} removed` : ''].filter(Boolean).join(', ')
+    : 'nothing changed'
+  return {
+    data: { fetchedAt: snap.fetchedAt, changed: result.changed, removed: result.removed, fullIndex: result.fullIndex, items: count, platform: platformOf(snap), warnings: snap.warnings, refreshed: result.conflicts.refreshed, cleared: result.conflicts.cleared },
+    text: [
+      `Fetched ${link.workspaceName ?? link.workspace}: ${snap.full ? `read all ${count} items` : what}.`,
+      ...result.conflicts.refreshed.map((r) => `The workspace changed ${r.ref} again: its conflicts are redone against the newer version (${plural(r.conflicts, 'conflict')}); the .workspace copies are updated.`),
+      ...result.conflicts.cleared.map((r) => `Conflict cleared by a workspace change: ${r} now merges cleanly, and the merge is written.`),
+      ...result.conflicts.bases.filter((b) => b.missing.length).map((b) => describeRepair(b)),
+      ...(snap.full ? ['This platform is older: fast checks aren’t available, so every fetch reads the whole workspace.'] : []),
+      ...snap.warnings.map((w) => `Could not read ${w}`),
+      'See where the project stands: `frontera local sync status`.',
+    ].join('\n'),
+  }
+}
+
+const status = async (ctx: CommandContext) => {
+  const project = localProject(ctx.cwd)
+  const link = readLink(project.root)
+  const keys = { workspace: !!getSyncKey(project, 'workspace'), organization: !!getSyncKey(project, 'organization') }
+  const lock = readLock(project.root)
+  const lastPull = lock && link && lock.workspace === link.workspace ? lock.pulledAt ?? null : null
+  const none = { fetchedAt: null, platform: null, incoming: 0, nowNamed: 0, newInWorkspace: 0, changedHere: 0, bothChanged: 0, mergeable: 0, conflicts: 0, unresolved: 0, clearedByWorkspace: 0, deletedInWorkspace: 0, deletedHere: 0, onlyHere: 0 }
+  if (!link) return { data: { link: null, keys, lastPull: null, counts: null, error: null, ...none }, text: 'Not linked to a workspace. Connect one with `frontera local sync connect --platform <url>`.' }
+  let error: string | null = null
+  let snapshot = snapshotFor(project, link)
+  // `--fetch` asks the platform first; `--offline` is the default now and kept for older callers.
+  if (flagBool(ctx, 'fetch') && !flagBool(ctx, 'offline')) {
+    if (!keys.workspace) error = 'No workspace key on this machine; connect again to store one.'
+    else {
+      try {
+        snapshot = (await fetchFor(project, link)).snapshot
+      } catch (err) {
+        error = (err as Error).message
+      }
+    }
+  }
+  const { plan } = snapshot ? await planFor(project, link, { fetch: 'never' }) : { plan: null }
+  // An Agent's lessons edited here are never in the plan; they are proposed all the same, so they count as changed here.
+  const lessons = plan ? lessonsToPropose(project.root, link.workspace) : []
+  const counted = plan ? statusCounts(plan) : null
+  const tally = counted ? { ...counted, changedHere: counted.changedHere + lessons.length } : null
+  const parts = tally
+    ? [
+        tally.incoming ? `${tally.incoming} incoming` : '',
+        tally.nowNamed ? `${tally.nowNamed} now named` : '',
+        tally.newInWorkspace ? `${tally.newInWorkspace} new` : '',
+        // Conflicts before what merges, as Forge's card says it.
+        tally.conflicts ? plural(tally.conflicts, 'conflict') : '',
+        tally.mergeable ? `${tally.mergeable} to merge` : '',
+        tally.clearedByWorkspace ? `${plural(tally.clearedByWorkspace, 'conflict')} cleared by a workspace change` : '',
+        tally.changedHere ? `${tally.changedHere} changed here` : '',
+        tally.deletedInWorkspace ? `${tally.deletedInWorkspace} deleted in the workspace` : '',
+        tally.deletedHere ? `${tally.deletedHere} deleted here` : '',
+        tally.onlyHere ? `${tally.onlyHere} only here` : '',
+      ].filter(Boolean)
+    : []
+  const fetchedAt = snapshot?.fetchedAt ?? null
+  // Governed Actions are read only with an organization key (§15.1): ask for one when the workspace uses them.
+  const organizationKeyFor = !keys.organization && usesGovernedActions(snapshot) ? 'actions' : null
+  // The project's change request, as Forge's card line says it.
+  const kept = currentRequest(readRequests(project.root, link.workspace))
+  // How the last `local dev` left the project, counted as Forge's home counts it.
+  const build = projectBuildSummary(project.root, project.id)
+  const request = kept ? `${kept.state === 'merged' ? 'Applied' : kept.applied && !kept.applied.ok && kept.state !== 'closed' ? 'Apply failed' : kept.state === 'closed' ? 'Closed' : 'Proposed'} · ${plural(kept.refs.length, 'item')} · ${kept.title}` : null
+  return {
+    data: { link, keys, lastPull, ...none, ...(tally ?? { counts: null }), ...(plan ? { items: { ...itemStates(plan), ...Object.fromEntries(lessons.map((slug) => [`lessons/${slug}`, 'outgoing' as const])) } } : {}), fetchedAt, platform: platformOf(snapshot), error, organizationKeyFor, build },
+    text: [
+      `Linked to ${link.workspaceName ?? link.workspace}${link.organizationName ? ` (${link.organizationName})` : ''} on ${new URL(link.platform).host}`,
+      `  Last pull   ${lastPull ? when(lastPull) : 'never'}`,
+      `  Fetched     ${fetchedAt ? when(fetchedAt) : 'never: run `frontera local sync fetch`'}`,
+      `  Keys        workspace ${keys.workspace ? 'stored' : 'missing'}, organization ${keys.organization ? 'stored' : 'none'}`,
+      tally ? `  Workspace   ${parts.length ? parts.join(', ') : 'matches the project'}` : `  Workspace   ${error ?? 'not fetched yet'}`,
+      ...(tally && error ? [`  Fetch       ${error}`] : []),
+      ...(snapshot?.full ? ['  Platform    older: fast checks aren’t available, so each fetch reads the whole workspace'] : []),
+      ...(request ? [`  Request     ${request}`] : []),
+      ...(build ? [`  Build       ${buildStatusText(build)}`] : []),
+      ...(organizationKeyFor ? ['  Actions     this workspace’s workflows use governed Actions: run `frontera local sync connect` again with an organization key to bring them'] : []),
+    ].join('\n'),
+  }
+}
+
+const pull = async (ctx: CommandContext) => {
+  const project = localProject(ctx.cwd)
+  const link = needLink(project)
+  const kinds = kindsFlag(ctx)
+  const drafts = new Set((flagString(ctx, 'drafts') ?? '').split(',').map((s) => s.trim()).filter(Boolean))
+  const fetchMode = flagBool(ctx, 'offline') ? 'never' : flagBool(ctx, 'fetch') ? 'always' : 'auto'
+  const repair = fetchMode === 'never' ? 'offline' : 'online'
+  let { remote, plan, lock, snapshot, bases } = await planFor(project, link, { kinds, drafts, fetch: fetchMode, repair })
+  // A conflicted item whose workspace version moved by a fetch that did not settle it (an older CLI's):
+  // settle it before pulling, and plan again. A preview writes nothing, so it only plans.
+  if (snapshot && !flagBool(ctx, 'preview')) {
+    const settled = await settleConflicts(project, link, snapshot, repair === 'online' ? sourceIfKeyed(project, link) : undefined)
+    if (settled.refreshed.length || settled.cleared.length) ({ remote, plan, lock, snapshot, bases } = await planFor(project, link, { kinds, drafts, fetch: 'never', repair }))
+  }
+  if (!plan) throw new CliError('nothing fetched from the workspace yet', { code: 'SYNC_NOT_FETCHED', hint: 'run `frontera local sync fetch`, or pull without --offline' })
+  const planId = snapshot ? snapshotId(snapshot) : null
+  const preview = { link, items: plan, counts: summarize(plan), warnings: remote.warnings, notes: remote.notes, fetchedAt: snapshot?.fetchedAt ?? null, snapshot: planId, bases }
+  const baseLines = bases.length ? ['', 'Merge bases:', ...bases.map((b) => `  ${describeRepair(b)}`)] : []
+  if (flagBool(ctx, 'preview')) return { data: preview, text: [planText(link, plan, remote.warnings, remote.notes), ...baseLines].join('\n') }
+  // A plan made from an older snapshot is not applied: the workspace moved since it was shown (Terraform's stale plan).
+  const expected = flagString(ctx, 'snapshot')
+  if (expected && planId && expected !== planId) {
+    return {
+      data: { ...preview, stale: true, pulled: [], written: [], removed: [] },
+      text: ['The workspace changed since that preview; nothing was written. The plan now:', '', planText(link, plan, remote.warnings, remote.notes)].join('\n'),
+    }
+  }
+  const named = ctx.positional.slice(1)
+  const byRef = new Map(remote.items.map((i) => [i.ref, i]))
+  // Knowledge bases whose documents come too: opt-in, as documents can be large and sensitive.
+  const documents = refsFlag(ctx, 'documents').map((r) => r.replace(/^knowledge\//, ''))
+  const noBase = documents.filter((n) => !byRef.has(`knowledge/${n}`))
+  if (noBase.length) throw new UsageError(`no knowledge base ${noBase.join(', ')} in the workspace`, '--documents takes knowledge base names, as `--preview` lists them (knowledge/<name>)')
+  const byPlan = new Map(plan.map((p) => [p.ref, p]))
+  const status = new Map(plan.map((p) => [p.ref, p.status]))
+  const clean = (p: PlanItem) => p.status === 'changed' || (p.status === 'conflict' && p.merge?.conflicts === 0)
+  // What the workspace deleted: delete it here, or keep it as this project's own. Never by default.
+  const deleteHere = refsFlag(ctx, 'delete-here')
+  const keepLocal = refsFlag(ctx, 'keep-local')
+  const notDeleted = [...deleteHere, ...keepLocal].filter((r) => status.get(r) !== 'deleted-remote')
+  if (notDeleted.length) throw new UsageError(`not deleted in the workspace: ${notDeleted.join(', ')}`, '--delete-here and --keep-local take items the workspace deleted; `--preview` lists them')
+  let chosen: string[]
+  if (named.length) {
+    const unknown = named.filter((r) => !byRef.has(r))
+    const gone = unknown.filter((r) => status.get(r) === 'deleted-remote')
+    if (gone.length) throw new UsageError(`deleted in the workspace: ${gone.join(', ')}`, 'say what to do with it: `--delete-here <ref>` or `--keep-local <ref>`')
+    if (unknown.length) throw new UsageError(`not in the workspace: ${unknown.join(', ')}`, 'list what is there with `frontera local sync pull --preview`')
+    chosen = named
+  } else if (flagBool(ctx, 'all-changed')) {
+    chosen = plan.filter(clean).map((p) => p.ref)
+  } else if (kinds) {
+    // A kind pulls what is new, changed or merges cleanly; it never replaces local edits unasked.
+    chosen = plan.filter((p) => p.status === 'new' || clean(p)).map((p) => p.ref)
+  } else if (deleteHere.length || keepLocal.length || documents.length || flagBool(ctx, 'lessons')) {
+    chosen = []
+  } else {
+    throw new UsageError('say what to pull', 'name items (`agent/support-concierge`), kinds (`--kinds workflows`), or `--all-changed`; `--preview` lists them')
+  }
+  // A knowledge base not in the project yet comes with its documents.
+  for (const n of documents) if (status.get(`knowledge/${n}`) === 'new' && !chosen.includes(`knowledge/${n}`)) chosen.push(`knowledge/${n}`)
+  // An item pulled with conflicts waits for `resolve`: a pull writes nothing else for it.
+  const waiting = chosen.filter((r) => status.get(r) === 'unresolved')
+  chosen = chosen.filter((r) => status.get(r) !== 'unresolved')
+  // Bring what the chosen items name and the project does not have yet, so they work locally.
+  const queue = [...chosen]
+  const take = new Set(chosen)
+  const brought: string[] = []
+  while (queue.length) {
+    const ref = queue.shift()!
+    for (const dep of byRef.get(ref)?.requires ?? []) {
+      if (take.has(dep) || !byRef.has(dep) || status.get(dep) !== 'new') continue
+      take.add(dep)
+      brought.push(dep)
+      queue.push(dep)
+    }
+  }
+  // Items already matching the workspace are recorded too, so the next plan knows them.
+  const adopt = plan.filter((p) => p.status === 'same' && !lock?.items[p.ref]).map((p) => p.ref)
+  const items: RemoteItem[] = [...take, ...adopt].map((r) => byRef.get(r)!).filter(Boolean)
+  const replaced = [...take].filter((r) => status.get(r) === 'edited' || status.get(r) === 'deleted-local')
+  const merge = new Set([...take].filter((r) => status.get(r) === 'conflict'))
+  let base = lock?.workspace === link.workspace ? lock : null
+  const readFromBase = (path: string) => readBase(project.root, path)
+  const removedDeleted: string[] = []
+  for (const [refs, deleteFiles] of [[deleteHere, true], [keepLocal, false]] as const) {
+    if (!refs.length) continue
+    const gone = forgetItems(project.root, link.workspace, refs, base, deleteFiles)
+    dropBase(project.root, Object.values(gone.forgotten).flat())
+    removedDeleted.push(...gone.removed)
+    base = gone.lock
+  }
+  const result = applyItems(project.root, link.workspace, items, base, { merge, base: readFromBase })
+  // What was pulled is the base the next merge starts from; a conflicted item keeps its old base.
+  const conflictedRefs = new Set(result.conflicted.map((c) => c.ref))
+  writeBase(project.root, items.filter((i) => !conflictedRefs.has(i.ref)), base)
+  const pulled = [...take].filter((r) => !conflictedRefs.has(r))
+  // Documents asked for land beside each base's knowledge.json; `local dev` uploads them.
+  const docs: Record<string, DocumentsPulled> = {}
+  if (documents.length) {
+    const client = sourceFor(project, link).workspace
+    for (const n of documents) {
+      const id = byRef.get(`knowledge/${n}`)?.id
+      docs[n] = id ? await pullDocuments(project.root, client, { name: n, id }) : { written: [], present: [], skipped: [], failed: ['its id is not in the fetched snapshot: fetch again'] }
+    }
+  }
+  // Built-in connections the project's items use get a declared stand-in (`local-stand-ins.ts`).
+  const held = new Set(Object.keys(readLock(project.root)?.items ?? {}))
+  const heldItems = remote.items.filter((i) => held.has(i.ref))
+  const needs = connectionsNeeded(heldItems)
+  const documentation = documentationNeeded(heldItems)
+  const standIns = needs.length ? await writeStandIns(project.root, needs, fetchMode === 'never' ? undefined : sourceIfKeyed(project, link)?.workspace, documentation) : { written: [], replaced: [] }
+  // The workspace's analytics stays on the platform: declared, so the build says it on each Agent that uses it.
+  const platformOnly = writePlatformOnly(project.root, analyticsNeeded(heldItems))
+  const connectionStandIns = standIns.written.filter((n) => !documentation.has(n))
+  const docsStandIns = standIns.written.filter((n) => documentation.has(n))
+  const standInLines = [
+    ...(connectionStandIns.length ? ['', `Stand-ins for connections signed in on the platform (their tools answer “not connected” locally; never proposed back): ${connectionStandIns.map((n) => standInPath(n)).join(', ')}`] : []),
+    ...(docsStandIns.length ? ['', `Frontera’s documentation for Agents (served locally from the runtime’s documentation; never proposed back): ${docsStandIns.map((n) => standInPath(n)).join(', ')}`] : []),
+    ...(platformOnly.length ? ['', `Analytics tools stay on the platform (a local runtime has no analytics; never proposed back): ${platformOnly.join(', ')}`] : []),
+  ]
+  // Lessons asked for: each Agent's reviewed rules, for every Agent the project now holds that the workspace has.
+  let lessons: LessonsPulled | null = null
+  if (flagBool(ctx, 'lessons')) {
+    const agents = Object.keys(readLock(project.root)?.items ?? {}).flatMap((r) => (r.startsWith('agent/') ? [r.slice('agent/'.length)] : []))
+    lessons = await pullLessons(project.root, link.workspace, sourceFor(project, link).workspace, agents)
+  }
+  const lessonLines = !flagBool(ctx, 'lessons')
+    ? []
+    : !lessons
+      ? ['', 'Lessons: this platform doesn’t give them yet.']
+      : [
+          '',
+          `Lessons (reviewed rules from customer feedback; \`frontera local dev\` gives them to the local Agents): ${lessons.rules ? `${plural(lessons.rules, 'rule')} for ${plural(lessons.written.length + lessons.kept.length, 'Agent')}` : 'none'}`,
+          ...lessons.written.map((a) => `  ${a}: agents/${a}/lessons.yaml written`),
+          ...lessons.kept.map((a) => `  ${a}: agents/${a}/lessons.yaml changed here since the last pull, so kept`),
+          ...lessons.removed.map((a) => `  ${a}: no reviewed rules in the workspace any more; agents/${a}/lessons.yaml removed`),
+        ]
+  const docLines = Object.entries(docs).flatMap(([n, d]) => [
+    `  ${n}: ${plural(d.written.length, 'document')} written${d.present.length ? `, ${d.present.length} already here` : ''}${d.skipped.length ? `, ${d.skipped.length} not a kind local dev uploads (${d.skipped.join(', ')})` : ''}`,
+    ...d.failed.map((f) => `      could not read ${f}`),
+  ])
+  // The workspace's copies beside conflicted files are not project files; `local dev` ignores them.
+  const projectWritten = result.written.filter((p) => !p.endsWith(WORKSPACE_SUFFIX))
+  const conflictLines = result.conflicted.flatMap((c) => [
+    `  ${byPlan.get(c.ref) ? `${kindTitle(c.ref, byPlan.get(c.ref)!.title)}  (${c.ref})` : c.ref}  ${plural(c.conflicts, 'conflict')}`,
+    ...c.files.map((f) => `      ${f}${WORKSPACE_SUFFIX}`),
+  ])
+  return {
+    data: {
+      stale: false,
+      pulled,
+      brought,
+      replaced,
+      merged: result.merged,
+      conflicted: result.conflicted,
+      waiting,
+      deleted: deleteHere,
+      keptLocal: keepLocal,
+      written: result.written,
+      removed: [...removedDeleted, ...result.removed],
+      warnings: remote.warnings,
+      bases,
+      documents: docs,
+      ...(lessons ? { lessons } : {}),
+      ...(standIns.written.length ? { standIns: standIns.written } : {}),
+    },
+    text: [
+      pulled.length ? `Pulled ${plural(pulled.length, 'item')} from ${link.workspaceName ?? link.workspace}:` : result.conflicted.length || waiting.length || deleteHere.length || keepLocal.length || lessons ? '' : 'Nothing to pull.',
+      ...pulled.map((r) => `  ${r}${brought.includes(r) ? '  (needed by another item)' : ''}${replaced.includes(r) ? '  (replaced your local edits)' : ''}${result.merged.includes(r) ? '  (merged with your changes)' : ''}`),
+      ...(result.conflicted.length
+        ? [
+            '',
+            `Changed on both sides, with conflicts. The files keep your version; the workspace’s is beside each:`,
+            ...conflictLines,
+            'See them with `frontera local sync diff <ref>`; settle with `resolve <ref> --keep workspace|mine`, or edit the file and `resolve <ref> --edited`.',
+          ]
+        : []),
+      ...(waiting.length ? ['', `Not pulled, conflicts to resolve first: ${waiting.join(', ')}`] : []),
+      ...(deleteHere.length ? ['', `Deleted here, as in the workspace: ${deleteHere.join(', ')}`] : []),
+      ...(keepLocal.length ? ['', `Kept as this project’s own: ${keepLocal.join(', ')}`] : []),
+      ...(projectWritten.length ? ['', `Wrote ${plural(projectWritten.length, 'file')}; \`frontera local dev\` applies them.`] : []),
+      ...(docLines.length ? ['', 'Documents (uploaded to the local knowledge base by `frontera local dev`):', ...docLines] : []),
+      ...lessonLines,
+      ...standInLines,
+      ...remote.warnings.map((w) => `Could not read ${w}`),
+      ...baseLines,
+    ]
+      .join('\n')
+      .replace(/^\n+/, ''),
+  }
+}
+
+/** Everything about one item for `diff` and `resolve`: the plan row, the workspace's version, and the three-way merge. */
+async function itemState(project: LocalProject, link: SyncLink, ref: string) {
+  // Offline, as diff and resolve are: a lost base comes back only from an unchanged copy here (pull reads the platform).
+  const { remote, plan, lock, snapshot } = await planFor(project, link, { fetch: 'never', repair: 'offline' })
+  if (!plan || !snapshot) throw new CliError('nothing fetched from the workspace yet', { code: 'SYNC_NOT_FETCHED', hint: 'run `frontera local sync fetch`' })
+  const row = plan.find((p) => p.ref === ref)
+  const item = remote.items.find((i) => i.ref === ref) ?? null
+  const entry = lock?.workspace === link.workspace ? lock.items[ref] : undefined
+  if (!row && !item && !entry) throw new UsageError(`not in the workspace or the project: ${ref}`, 'list items with `frontera local sync pull --preview`')
+  const paths = [...new Set([...Object.keys(item?.files ?? {}), ...Object.keys(entry?.files ?? {}), ...(entry?.conflict?.files ?? [])])].sort()
+  const base = baseFiles(entry, (p) => readBase(project.root, p))
+  const local = localFiles(project.root, paths)
+  const theirs = item?.files ?? {}
+  return { row, item, lock, snapshot, paths, base, local, theirs, entry }
+}
+
+const SIDE_FLAG: Record<string, Side> = { workspace: 'theirs', mine: 'ours' }
+
+function sideFor(value: string): Side {
+  const side = SIDE_FLAG[value]
+  if (!side) throw new UsageError(`keep \`${value}\`?`, 'keep `workspace` or `mine`')
+  return side
+}
+
+/** A pick: a side, or `both` (mine, then the workspace's) where the conflict offers it. */
+function choiceFor(value: string): Choice {
+  if (value === 'both') return 'both'
+  const side = SIDE_FLAG[value]
+  if (!side) throw new UsageError(`pick \`${value}\`?`, 'pick `workspace`, `mine` or `both`')
+  return side
+}
+
+/** A conflict's version, as a line or a block. */
+function showValue(v: unknown): string[] {
+  if (v === undefined) return ['(none)']
+  if (typeof v === 'string') return v === '' ? ['(nothing)'] : v.split('\n')
+  return JSON.stringify(v, null, 2).split('\n')
+}
+
+function conflictText(c: Conflict): string[] {
+  const where = c.path ? `${c.path}${c.line ? `, line ${c.line}` : ''}` : c.line ? `line ${c.line}` : 'the whole file'
+  const side = (label: string, v: unknown) => showValue(v).map((l, i) => `      ${i ? ''.padEnd(10) : label.padEnd(10)} ${l}`)
+  return [`    ${c.index}. ${where}${c.both !== undefined ? ' (both can be kept)' : ''}`, ...side('base', c.base), ...side('mine', c.ours), ...side('workspace', c.theirs)]
+}
+
+const diff = async (ctx: CommandContext) => {
+  const project = localProject(ctx.cwd)
+  const link = needLink(project)
+  const ref = ctx.positional[1]
+  if (!ref) throw new UsageError('name the item', 'frontera local sync diff agent/support-concierge')
+  const s = await itemState(project, link, ref)
+  const result = mergeItemFiles(s.base, s.local, s.theirs)
+  const files = result.files.map((f) => {
+    const base = s.base[f.path] ?? null
+    const local = s.local[f.path] ?? null
+    const workspace = s.theirs[f.path] ?? null
+    const state = f.conflicts.length ? 'conflict' : local === workspace ? 'same' : base === local ? 'incoming' : base === workspace ? 'changed-here' : 'merges'
+    return { path: f.path, state, base, local, workspace, merged: f.merged, conflicts: f.conflicts }
+  })
+  const WORD: Record<string, string> = { same: 'the same', incoming: 'only the workspace changed it', 'changed-here': 'only changed here', merges: 'both changed it; merges cleanly' }
+  return {
+    data: { ref, title: s.row?.title ?? ref, status: s.row?.status ?? null, snapshot: snapshotId(s.snapshot), conflicts: result.conflicts, conflictsId: conflictsId(result.files), cleared: !!s.row?.cleared, baseMissing: Object.values(s.base).some((b) => b === null), files },
+    text: [
+      `${s.row ? `${kindTitle(ref, s.row.title)} (${ref})` : ref}: ${s.row ? statusWord(s.row) : 'not in the plan'}`,
+      ...files.flatMap((f) => [
+        '',
+        `  ${f.path}: ${f.conflicts.length ? plural(f.conflicts.length, 'conflict') : WORD[f.state]}`,
+        ...f.conflicts.flatMap(conflictText),
+      ]),
+      ...(result.conflicts
+        ? [
+            '',
+            `Settle with \`frontera local sync resolve ${ref} --keep workspace|mine\` (or \`--picks 1=workspace,2=mine\`), or edit and \`--edited\`.`,
+            ...(result.files.some((f) => f.conflicts.some((c) => c.both !== undefined)) ? ['A conflict that can keep both takes `=both`: mine, then the workspace’s.'] : []),
+          ]
+        : []),
+    ].join('\n'),
+  }
+}
+
+const resolve = async (ctx: CommandContext) => {
+  const project = localProject(ctx.cwd)
+  const link = needLink(project)
+  const ref = ctx.positional[1]
+  if (!ref) throw new UsageError('name the item', 'frontera local sync resolve agent/support-concierge --keep workspace')
+  const s = await itemState(project, link, ref)
+  // Picks are by number: they apply only to the conflicts they were chosen for (`conflictsId` from
+  // `diff`). Checked first, so a conflict a workspace change cleared reads as stale, not as an error.
+  const chosenFor = flagString(ctx, 'conflicts')
+  if (chosenFor && chosenFor !== conflictsId(mergeItemFiles(s.base, s.local, s.theirs).files)) {
+    throw new CliError('the conflicts changed since they were chosen: the workspace moved, and they are numbered again', { code: 'SYNC_CONFLICTS_STALE', hint: 'look again with `frontera local sync diff <ref>` and choose again' })
+  }
+  if (!s.row || (s.row.status !== 'conflict' && s.row.status !== 'unresolved')) {
+    throw new UsageError(`nothing to resolve in ${ref}: ${s.row ? statusWord(s.row) : 'it is not in the workspace'}`, 'resolve settles an item changed here and in the workspace')
+  }
+  if (!s.item) throw new UsageError(`the workspace no longer has ${ref}`, 'pull with `--delete-here` or `--keep-local` instead')
+  const expected = flagString(ctx, 'snapshot')
+  if (expected && expected !== snapshotId(s.snapshot)) throw new CliError('the workspace changed since you looked at this conflict', { code: 'SYNC_PLAN_STALE', hint: 'look again with `frontera local sync diff <ref>`' })
+  const keep = flagString(ctx, 'keep')
+  const picksRaw = flagString(ctx, 'picks')
+  const edited = flagBool(ctx, 'edited')
+  if (edited && (keep || picksRaw)) throw new UsageError('--edited takes the files as they are', 'use it alone, or choose sides with --keep / --picks')
+  if (!edited && !keep && !picksRaw) throw new UsageError('say how to resolve it', '`--keep workspace`, `--keep mine`, `--picks 1=workspace,2=mine,3=both`, or `--edited` after editing the file')
+  const picks = new Map<number, Choice>()
+  for (const part of (picksRaw ?? '').split(',').map((p) => p.trim()).filter(Boolean)) {
+    const [n, side] = part.split('=')
+    if (!n || !/^\d+$/.test(n) || !side) throw new UsageError(`\`${part}\` is not a pick`, 'a pick is <conflict number>=workspace|mine|both, as `diff` numbers them')
+    picks.set(Number(n), choiceFor(side))
+  }
+  const how: Resolution = edited ? { edited: true } : { keep: keep ? sideFor(keep) : undefined, picks }
+  const lock = s.lock?.workspace === link.workspace ? s.lock : null
+  let result
+  try {
+    result = resolveItem(project.root, link.workspace, s.item, lock, how, (p) => readBase(project.root, p))
+  } catch (err) {
+    throw new UsageError((err as Error).message, 'choose every conflict with --picks, or a side for the rest with --keep')
+  }
+  writeBase(project.root, [s.item], lock)
+  return {
+    data: { ref, resolved: true, written: result.written, removed: result.removed },
+    text: [`Resolved ${ref}: ${edited ? 'your edited files are kept' : 'merged with the sides you chose'}; the base is now the workspace’s.`, ...(result.written.length ? [`Wrote ${plural(result.written.length, 'file')}.`] : [])].join('\n'),
+  }
+}
+
+const disconnect = async (ctx: CommandContext) => {
+  const project = localProject(ctx.cwd)
+  const link = readLink(project.root)
+  removeSyncKey(project, 'workspace')
+  removeSyncKey(project, 'organization')
+  const forget = flagBool(ctx, 'forget-link')
+  if (forget && link) writeLink(project.root, null)
+  return {
+    data: { keysRemoved: true, linkRemoved: forget && !!link },
+    text: forget ? 'Removed the keys and the link. Pulled files stay in the project.' : 'Removed the keys from this machine. The link stays in frontera.yaml for your teammates; `--forget-link` removes it too.',
+  }
+}
+
+const SUBCOMMANDS: Record<string, (ctx: CommandContext) => Promise<{ data: unknown; text: string }>> = {
+  connect,
+  fetch: fetchCommand,
+  status,
+  pull,
+  diff,
+  resolve,
+  disconnect,
+  // Called through, not referenced: `sync-request.ts` imports this module back.
+  push: (ctx) => syncPush(ctx),
+  request: (ctx) => syncRequest(ctx),
+}
+
+export const localSync: Command = {
+  meta: {
+    noun: 'local',
+    verb: 'sync',
+    args: [
+      { name: 'action', required: true, description: 'connect | fetch | status | pull | diff | resolve | push | request | disconnect' },
+      { name: 'items', required: false, description: 'kind/name … to pull or push, the one to diff or resolve, or show | apply | close after request' },
+    ],
+    flags: {
+      platform: 'string',
+      'workspace-key': 'string',
+      'org-key': 'string',
+      blueprint: 'string',
+      relink: 'boolean',
+      preview: 'boolean',
+      kinds: 'string',
+      drafts: 'string',
+      'all-changed': 'boolean',
+      offline: 'boolean',
+      fetch: 'boolean',
+      full: 'boolean',
+      snapshot: 'string',
+      conflicts: 'string',
+      'delete-here': 'string',
+      'keep-local': 'string',
+      keep: 'string',
+      picks: 'string',
+      edited: 'boolean',
+      'forget-link': 'boolean',
+      title: 'string',
+      description: 'string',
+      migration: 'string',
+      documents: 'string',
+      lessons: 'boolean',
+    },
+    aliases: { t: 'title', d: 'description' },
+    summary: 'Link the project to a platform workspace, pull and merge what you choose, and propose changes back',
+    examples: [
+      'frontera local sync connect --platform $URL --workspace-key -',
+      'frontera local sync fetch',
+      'frontera local sync status',
+      'frontera local sync status --fetch',
+      'frontera local sync pull --preview',
+      'frontera local sync pull agent/support-concierge workflow/return-label',
+      'frontera local sync pull --kinds blueprint,workflows',
+      'frontera local sync pull knowledge/faq --documents faq',
+      'frontera local sync pull agent/support-concierge --lessons',
+      'frontera local sync diff agent/support-concierge',
+      'frontera local sync resolve agent/support-concierge --keep workspace',
+      'frontera local sync resolve agent/desk --picks 1=mine --conflicts <id>',
+      'frontera local sync pull --delete-here workflow/old-label',
+      'frontera local sync push --preview',
+      'frontera local sync push -t "Tighten the refund procedure"',
+      'frontera local sync push agent/support-concierge -t "New greeting"',
+      'frontera local sync push --documents faq -t "Updated returns policy"',
+      'frontera local sync request',
+      'frontera local sync request apply',
+      'frontera local sync request close',
+      'frontera local sync disconnect --forget-link',
+    ],
+    offline: true,
+    internal: true,
+  },
+  async run(ctx) {
+    const action = ctx.positional[0]
+    const run = action ? SUBCOMMANDS[action] : undefined
+    const named = action ? `\`${action}\`` : '(none given)'
+    if (!run) throw new UsageError(`unknown sync action ${named}`, 'use connect, fetch, status, pull, diff, resolve, push, request or disconnect')
+    return run(ctx)
+  },
+}