@frontera-sdk/cli 1.53.10 → 1.53.12

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

@@ -0,0 +1,363 @@
+import { PlatformApi } from '../../api/platform-api'
+import { CliError, UsageError } from '../../errors'
+import { table } from '../../table'
+import { resolveAgentRef } from '../agent/resolve'
+import { flagString, type Command, type CommandContext } from '../types'
+
+/**
+ * An Agent's phone numbers (the WhatsApp numbers people call to talk to it)
+ * and calls the Agent makes. The organization and workspace are the signed-in
+ * person's, never typed.
+ *
+ * Every verb acts as a person. The Voice application checks the person's own
+ * access to the Agent (and the Voice manager role for changes), so no API key
+ * reaches these routes; the dispatcher refuses a key before any request and
+ * names where a person does this in the platform.
+ *
+ * Voice sets a number up when it is added: the number's WhatsApp calls are
+ * pointed at the deployment's phone system through the workspace's WhatsApp
+ * channel. No credential passes through the CLI.
+ */
+
+interface NumberRow {
+  id: string
+  number: string
+  source: string
+  channelId: string | null
+  enabled: boolean
+  callHours: { timeZone: string; windows: { day: string; open: string; close: string }[] } | null
+  status: string
+  statusReason: string | null
+}
+
+const WHERE = 'the Agent → Voice → Phone numbers'
+const WEEK = ['MONDAY', 'TUESDAY', 'WEDNESDAY', 'THURSDAY', 'FRIDAY', 'SATURDAY', 'SUNDAY'] as const
+const DAY_ALIASES: Record<string, (typeof WEEK)[number]> = { mon: 'MONDAY', tue: 'TUESDAY', wed: 'WEDNESDAY', thu: 'THURSDAY', fri: 'FRIDAY', sat: 'SATURDAY', sun: 'SUNDAY' }
+
+function api(ctx: CommandContext): PlatformApi {
+  return new PlatformApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
+}
+
+async function agentOf(ctx: CommandContext, client: PlatformApi, usage: string): Promise<string> {
+  const ref = ctx.positional[0]
+  if (!ref) throw new UsageError('missing <agent>', `${usage} — see \`frontera agent list\``)
+  return resolveAgentRef(client, ref)
+}
+
+/** `628123456789` as `+628123456789`. */
+const shown = (digits: string) => `+${digits}`
+
+function hoursText(hours: NumberRow['callHours']): string {
+  if (!hours) return 'any time'
+  const first = hours.windows[0]
+  if (!first) return `closed (${hours.timeZone})`
+  const t = (hhmm: string) => `${hhmm.slice(0, 2)}:${hhmm.slice(2)}`
+  const days = new Set(hours.windows.map((w) => w.day)).size
+  return `${t(first.open)}-${t(first.close)} ${hours.timeZone}${days === 7 ? '' : `, ${days} days`}`
+}
+
+/**
+ * `--hours 08:00-17:00` (every day) or `--hours mon-fri@08:00-17:00`, with
+ * `--time-zone`. Absent means any time.
+ */
+export function parseHours(raw: string | undefined, timeZone: string | undefined): NumberRow['callHours'] {
+  if (!raw) return null
+  const m = /^(?:([a-z]{3})(?:-([a-z]{3}))?@)?([0-2][0-9]):?([0-5][0-9])-([0-2][0-9]):?([0-5][0-9])$/i.exec(raw.trim())
+  if (!m) throw new UsageError(`"${raw}" is not call hours`, 'write them as 08:00-17:00 (every day) or mon-fri@08:00-17:00')
+  const [, fromDay, toDay, oh, om, ch, cm] = m
+  const open = `${oh}${om}`
+  const close = `${ch}${cm}`
+  if (open > '2359' || (close > '2359' && close !== '2400')) throw new UsageError(`"${raw}" is not a time of day`, 'times run from 00:00 to 23:59; 24:00 closes at the end of the day')
+  if (open === close) throw new UsageError(`"${raw}" opens and closes at the same time`, 'give a window, e.g. 08:00-17:00; 22:00-06:00 runs past midnight')
+  let days: readonly (typeof WEEK)[number][] = WEEK
+  if (fromDay) {
+    const a = DAY_ALIASES[fromDay.toLowerCase()]
+    const b = DAY_ALIASES[(toDay ?? fromDay).toLowerCase()]
+    if (!a || !b) throw new UsageError(`"${raw}" names an unknown day`, 'days are mon, tue, wed, thu, fri, sat, sun')
+    days = WEEK.slice(WEEK.indexOf(a), WEEK.indexOf(b) + 1)
+    if (days.length === 0) throw new UsageError(`"${raw}" runs backwards through the week`, 'write the earlier day first, e.g. mon-fri')
+  }
+  return { timeZone: timeZone ?? 'Asia/Jakarta', windows: days.map((day) => ({ day, open, close })) }
+}
+
+async function numberOf(client: PlatformApi, agentId: string, ref: string | undefined, usage: string): Promise<NumberRow> {
+  if (!ref) throw new UsageError('missing <number>', usage)
+  const { numbers } = await client.voiceNumbers(agentId)
+  const digits = ref.replace(/[^0-9]/g, '')
+  const found = (numbers as NumberRow[]).find((n) => n.id === ref || (digits.length >= 7 && n.number === digits))
+  if (!found) throw new CliError(`this Agent has no number "${ref}"`, { code: 'NOT_FOUND', hint: 'run `frontera voice numbers <agent>` to see them' })
+  return found
+}
+
+const lineOf = (n: NumberRow) => [shown(n.number), n.status + (n.enabled ? '' : ' (off)'), n.source, hoursText(n.callHours), n.statusReason ?? '']
+
+const SESSION = { authLane: 'session' as const, sessionAlternative: WHERE }
+
+const list: Command = {
+  meta: {
+    noun: 'voice',
+    verb: 'numbers',
+    ...SESSION,
+    args: [{ name: 'agent', required: true, description: 'Agent id or slug' }],
+    flags: {},
+    summary: 'List the phone numbers an Agent answers',
+    examples: ['frontera voice numbers front-desk', 'frontera voice numbers front-desk --json'],
+  },
+  async run(ctx) {
+    const client = api(ctx)
+    const view = await client.voiceNumbers(await agentOf(ctx, client, 'frontera voice numbers <agent>'))
+    const rows = view.numbers as NumberRow[]
+    return {
+      data: view,
+      text: !view.available
+        ? 'Phone numbers are not set up on this deployment.'
+        : rows.length === 0
+          ? 'This Agent has no phone numbers.'
+          : table(['number', 'status', 'source', 'hours', 'note'], rows.map(lineOf), [undefined, undefined, undefined, 36, 50]),
+    }
+  },
+}
+
+const add: Command = {
+  meta: {
+    noun: 'voice',
+    verb: 'number-add',
+    ...SESSION,
+    args: [
+      { name: 'agent', required: true, description: 'Agent id or slug' },
+      { name: 'number', required: false, description: 'the phone number, international form (+62…); a WhatsApp number is read from its channel' },
+    ],
+    flags: { channel: 'string', hours: 'string', 'time-zone': 'string' },
+    summary: 'Add a WhatsApp number to an Agent and set it up',
+    examples: [
+      'frontera voice number-add front-desk +6281234567890 --channel <id>',
+      'frontera voice number-add desk <number> --channel <id> --hours 08:00-17:00',
+      'frontera voice number-add desk <number> --channel <id> --hours sat@0900-1200',
+    ],
+  },
+  async run(ctx) {
+    const usage = 'frontera voice number-add <agent> [<number>] --channel <whatsapp-channel-id>'
+    const client = api(ctx)
+    const agentId = await agentOf(ctx, client, usage)
+    const number = ctx.positional[1]
+    const channelId = flagString(ctx, 'channel')
+    if (!channelId) throw new UsageError('missing --channel', 'name the workspace’s WhatsApp channel the number belongs to')
+    // A WhatsApp number is the one its channel serves; a typed one is only checked against it.
+    const callHours = parseHours(flagString(ctx, 'hours'), flagString(ctx, 'time-zone'))
+    const { number: added } = await client.addVoiceNumber(agentId, { ...(number ? { number } : {}), source: 'whatsapp', channelId, callHours })
+    const n = added as NumberRow
+    return {
+      data: n,
+      text:
+        n.status === 'active'
+          ? `added ${shown(n.number)}: calls to it reach this Agent (${hoursText(n.callHours)})`
+          : `added ${shown(n.number)}, but it is not set up yet: ${n.statusReason ?? n.status}\n  try again: frontera voice number-apply ${ctx.positional[0]} ${shown(n.number)}`,
+    }
+  },
+}
+
+const apply: Command = {
+  meta: {
+    noun: 'voice',
+    verb: 'number-apply',
+    ...SESSION,
+    args: [
+      { name: 'agent', required: true, description: 'Agent id or slug' },
+      { name: 'number', required: true, description: 'the number, or its id' },
+    ],
+    flags: {},
+    summary: 'Set a phone number up again after it needed attention',
+    examples: ['frontera voice number-apply front-desk +6281234567890'],
+  },
+  async run(ctx) {
+    const usage = 'frontera voice number-apply <agent> <number>'
+    const client = api(ctx)
+    const line = await numberOf(client, await agentOf(ctx, client, usage), ctx.positional[1], usage)
+    const n = (await client.applyVoiceNumber(line.id)).number as NumberRow
+    return { data: n, text: n.status === 'active' ? `${shown(n.number)} is set up` : `${shown(n.number)} still needs attention: ${n.statusReason ?? n.status}` }
+  },
+}
+
+function toggle(verb: 'number-enable' | 'number-disable', enabled: boolean): Command {
+  return {
+    meta: {
+      noun: 'voice',
+      verb,
+      ...SESSION,
+      args: [
+        { name: 'agent', required: true, description: 'Agent id or slug' },
+        { name: 'number', required: true, description: 'the number, or its id' },
+      ],
+      flags: {},
+      summary: enabled ? 'Answer calls to a phone number again' : 'Refuse new calls to a phone number, keeping it',
+      examples: [`frontera voice ${verb} front-desk +6281234567890`],
+    },
+    async run(ctx) {
+      const usage = `frontera voice ${verb} <agent> <number>`
+      const client = api(ctx)
+      const line = await numberOf(client, await agentOf(ctx, client, usage), ctx.positional[1], usage)
+      const n = (await client.setVoiceNumberEnabled(line.id, enabled)).number as NumberRow
+      return { data: n, text: enabled ? `${shown(n.number)} answers calls again (${n.status})` : `${shown(n.number)} refuses new calls` }
+    },
+  }
+}
+
+const hoursCmd: Command = {
+  meta: {
+    noun: 'voice',
+    verb: 'number-hours',
+    ...SESSION,
+    args: [
+      { name: 'agent', required: true, description: 'Agent id or slug' },
+      { name: 'number', required: true, description: 'the number, or its id' },
+    ],
+    flags: { hours: 'string', 'time-zone': 'string' },
+    summary: 'Change when a phone number answers, and apply it again',
+    examples: ['frontera voice number-hours desk <number> --hours 08:00-17:00', 'frontera voice number-hours desk <number> --hours any'],
+  },
+  async run(ctx) {
+    const usage = 'frontera voice number-hours <agent> <number> --hours <08:00-17:00 | mon-fri@08:00-17:00 | any>'
+    const raw = flagString(ctx, 'hours')
+    if (!raw) throw new UsageError('missing --hours', usage)
+    const client = api(ctx)
+    const line = await numberOf(client, await agentOf(ctx, client, usage), ctx.positional[1], usage)
+    const callHours = raw === 'any' ? null : parseHours(raw, flagString(ctx, 'time-zone'))
+    const n = (await client.setVoiceNumberHours(line.id, callHours)).number as NumberRow
+    return { data: n, text: n.status === 'active' ? `${shown(n.number)} now answers ${hoursText(n.callHours)}` : `${shown(n.number)} saved ${hoursText(n.callHours)} but still needs attention: ${n.statusReason ?? n.status}` }
+  },
+}
+
+const remove: Command = {
+  meta: {
+    noun: 'voice',
+    verb: 'number-remove',
+    ...SESSION,
+    args: [
+      { name: 'agent', required: true, description: 'Agent id or slug' },
+      { name: 'number', required: true, description: 'the number, or its id' },
+    ],
+    flags: {},
+    summary: 'Remove a phone number: its calls stop reaching the Agent, its digits are free again',
+    examples: ['frontera voice number-remove front-desk +6281234567890'],
+  },
+  async run(ctx) {
+    const usage = 'frontera voice number-remove <agent> <number>'
+    const client = api(ctx)
+    const line = await numberOf(client, await agentOf(ctx, client, usage), ctx.positional[1], usage)
+    await client.removeVoiceNumber(line.id)
+    return { data: { id: line.id, number: line.number, removed: true }, text: `removed ${shown(line.number)}; its past calls keep their records` }
+  },
+}
+
+/** What a refusal means, in words. */
+const REFUSALS: Record<string, string> = {
+  not_enabled: 'Voice is not turned on for this organization',
+  not_available: 'Voice is not available in this workspace',
+  not_licensed: 'the licence does not include Voice',
+  read_only: 'Voice is read-only right now',
+  suspended: 'Voice is suspended for this organization',
+  agent_unpublished: 'the Agent is not published',
+  voice_off: 'voice calls are off for this Agent',
+  no_voice_chosen: 'the Agent has no speaking voice',
+  transcription_model_missing: 'the Agent has no transcription model',
+  usage_limit: 'this month’s call minutes are used up',
+  speech_provider_missing: 'the organization has no speech provider key',
+  concurrency_limit: 'too many calls are running; try again in a minute',
+  number_disabled: 'the number is turned off',
+  number_not_active: 'the number is not set up yet; run `frontera voice number-apply`',
+  no_call_permission: 'this person has not given the number permission to call on WhatsApp; run `frontera voice call-permission-request`',
+}
+
+const digitsOf = (raw: string | undefined, usage: string) => {
+  const digits = (raw ?? '').replace(/[^0-9]/g, '')
+  if (!raw) throw new UsageError('missing --to', usage)
+  if (digits.length < 7) throw new UsageError(`"${raw}" is not a phone number`, 'give it in international form, e.g. +628…')
+  return digits
+}
+
+const call: Command = {
+  meta: {
+    noun: 'voice',
+    verb: 'call',
+    ...SESSION,
+    args: [{ name: 'agent', required: true, description: 'Agent id or slug' }],
+    flags: { number: 'string', to: 'string' },
+    summary: 'Have an Agent phone a number, from one of its own numbers (signed-in person only; API keys are refused)',
+    examples: ['frontera voice call front-desk --number <id> --to +628…'],
+  },
+  async run(ctx) {
+    const usage = 'frontera voice call <agent> --number <number-id> --to <number>'
+    const client = api(ctx)
+    const agentId = await agentOf(ctx, client, usage)
+    const numberId = flagString(ctx, 'number')
+    if (!numberId) throw new UsageError('missing --number', 'the id of the Agent’s number to call from — see `frontera voice numbers`')
+    const to = digitsOf(flagString(ctx, 'to'), usage)
+    try {
+      const started = await client.startVoiceCall(agentId, { numberId, to })
+      return { data: started, text: `calling ${shown(to)}; the call is session ${started.callId} in the Agent’s Sessions` }
+    } catch (caught) {
+      // The SDK keeps the response body as `details`: `{ code: 'VOICE_CALL_REFUSED', reason, callId }`.
+      const reason = (caught as { details?: { reason?: string } }).details?.reason
+      if (reason && REFUSALS[reason]) throw new CliError(`the call was refused: ${REFUSALS[reason]}`, { code: 'REFUSED', hint: reason })
+      throw caught
+    }
+  },
+}
+
+const permissionText = (p: { status: string; expiresAt?: string; canCall: boolean; canRequest: boolean }) =>
+  p.canCall
+    ? `can call (${p.status}${p.expiresAt ? `, until ${p.expiresAt}` : ''})`
+    : `no permission${p.canRequest ? ': ask with `frontera voice call-permission-request` (WhatsApp allows 1 request a day, 2 a week)' : ' and a request cannot be sent right now'}`
+
+const callPermission: Command = {
+  meta: {
+    noun: 'voice',
+    verb: 'call-permission',
+    ...SESSION,
+    args: [{ name: 'numberId', required: true, description: 'the id of a WhatsApp number (see `frontera voice numbers`)' }],
+    flags: { to: 'string' },
+    summary: 'Check whether a WhatsApp number may call a person',
+    examples: ['frontera voice call-permission <number-id> --to +628…'],
+  },
+  async run(ctx) {
+    const usage = 'frontera voice call-permission <number-id> --to <number>'
+    const numberId = ctx.positional[0]
+    if (!numberId) throw new UsageError('missing <numberId>', usage)
+    const { permission } = await api(ctx).voiceCallPermission(numberId, digitsOf(flagString(ctx, 'to'), usage))
+    return { data: permission, text: permissionText(permission) }
+  },
+}
+
+const callPermissionRequest: Command = {
+  meta: {
+    noun: 'voice',
+    verb: 'call-permission-request',
+    ...SESSION,
+    args: [{ name: 'numberId', required: true, description: 'the id of a WhatsApp number (see `frontera voice numbers`)' }],
+    flags: { to: 'string', message: 'string' },
+    summary: 'Ask a person for permission to call them on WhatsApp',
+    examples: ['frontera voice call-permission-request <number-id> --to +628…', 'frontera voice call-permission-request <id> --to <n> --message Hi'],
+  },
+  async run(ctx) {
+    const usage = 'frontera voice call-permission-request <number-id> --to <number> [--message <text>]'
+    const numberId = ctx.positional[0]
+    if (!numberId) throw new UsageError('missing <numberId>', usage)
+    const message = flagString(ctx, 'message')
+    const to = digitsOf(flagString(ctx, 'to'), usage)
+    await api(ctx).requestVoiceCallPermission(numberId, { to, ...(message ? { message } : {}) })
+    return { data: { requested: true }, text: `asked ${shown(to)} for permission; WhatsApp allows 1 request a day and 2 a week. Check with \`frontera voice call-permission\`` }
+  },
+}
+
+export const voiceCommands: Command[] = [
+  list,
+  add,
+  apply,
+  toggle('number-enable', true),
+  toggle('number-disable', false),
+  hoursCmd,
+  remove,
+  call,
+  callPermission,
+  callPermissionRequest,
+]

package/src/flag-help.ts

@@ -22,6 +22,13 @@ export const FLAG_HELP: Readonly<Record<string, string>> = {
   'no-snapshot': 'don’t save the records first (by default a load saves them, and a refused record puts them back)',
   batch: 'how many records are submitted at once (1 to 16, default 4)',
   agent: 'agent slug this binding is for — one agent, no wildcard',
+  // Voice phone numbers.
+  channel: 'the workspace’s WhatsApp channel the number belongs to, by id',
+  hours: 'when the number answers: 08:00-17:00 (every day), mon-fri@08:00-17:00, or 22:00-06:00 past midnight; absent or `any` means any time',
+  'time-zone': 'the time zone of --hours, e.g. Asia/Jakarta (the default)',
+  number: 'the id of the Agent’s phone number to call from (see `frontera voice numbers`)',
+  to: 'the number being called, in international form',
+  message: 'text sent with the permission request',
   app: 'a Custom App by its slug: the App may start the Function as the person using it',
   apps: 'list the Custom Apps that may start it, instead of the agents',
   off: 'keep the binding, switched off',
@@ -267,6 +274,8 @@ export const FLAG_HELP: Readonly<Record<string, string>> = {
   'org-key': '`-` to read an organization key (sk-org-…) from stdin, after the workspace key; widens the Blueprint to the whole model',
   blueprint: 'workspace (the slice granted to the workspace, default) or organization (the whole model; needs an organization key)',
   relink: 'point a project already linked to another workspace at this one',
+  target: 'local sync: a named target of the project (sync.targets in frontera.yaml), matched exactly, to connect, propose to, apply on, diff or resolve against, or disconnect; without it, the project’s link',
+  production: 'local sync connect --target: mark the target as production in status and messages (every target is reached only by a command that names it)',
   preview: 'local sync: list what a pull would bring, or a push would propose, file by file, and change nothing; app deploy: make a preview deployment (the default), said explicitly as a pipeline must',
   kinds: 'comma-separated: blueprint, skills, functions, plugins, knowledge, workflows, agents, evaluations',
   drafts: 'comma-separated items (agent/<slug>, workflow/<slug>, function/<slug>, blueprint) to read as their draft instead of the live version; the Blueprint’s draft takes an organization key',
@@ -340,6 +349,15 @@ const PLACEHOLDER: Readonly<Record<string, string>> = {
   header: 'name: value',
   framework: 'next|react',
   port: 'number',
+  line: 'id',
+  host: 'host',
+  transport: 'udp|tcp',
+  address: 'ip[/bits]',
+  username: 'name',
+  realm: 'realm',
+  number: 'id',
+  to: 'number',
+  message: 'text',
   origin: 'url',
   'token-fd': 'fd',
   'expect-revision': 'hash',
@@ -381,6 +399,7 @@ const PLACEHOLDER: Readonly<Record<string, string>> = {
   'workspace-key': '-',
   'org-key': '-',
   blueprint: 'workspace|organization',
+  target: 'name',
   kinds: 'a,b',
   drafts: 'kind/name,…',
   snapshot: 'id',

package/src/forge/touches.ts

@@ -89,6 +89,8 @@ export const NOUN_ALIASES: Record<string, ForgeArtifactKind> = { function: 'auto
 export const AGENT_PROXY_NOUNS: Record<string, { verbs: readonly string[]; agentAt: number }> = {
   capability: { verbs: ['grant', 'revoke', 'bind', 'unbind'], agentAt: 0 },
   pack: { verbs: ['apply', 'detach'], agentAt: 1 },
+  // Phone numbers belong to the Agent they name; `call*` act on a number id (no Agent to name).
+  voice: { verbs: ['number-add', 'number-apply', 'number-enable', 'number-disable', 'number-hours', 'number-remove'], agentAt: 0 },
 }
 
 /**

package/src/local/local-blueprint-schemas.ts

@@ -85,7 +85,7 @@ const OBJECT_TYPE: JsonSchema = {
     properties: {
       type: 'array',
       minItems: 1,
-      description: 'Every field. Each names the column it reads in backing.mapping.',
+      description: 'Every field. Each names the column it reads in backing.mapping, except an edit-only one.',
       items: {
         type: 'object',
         properties: {
@@ -100,6 +100,10 @@ const OBJECT_TYPE: JsonSchema = {
           sharedField: { anyOf: [ref('The shared field it implements', 'shared-field'), { type: 'null' }], description: 'The shared field it implements, by apiName; null detaches it.' },
           semanticType: { anyOf: [ref('The semantic type it carries', 'semantic-type'), { type: 'null' }], description: 'The semantic type its values follow (allowed values, bounds), by apiName; null detaches it.' },
           calculation: { type: 'object', description: 'A calculated field. A location names its latitude and longitude fields: { kind: location, latitude, longitude }.' },
+          editOnly: {
+            type: 'boolean',
+            description: 'true: the field reads no column. Its values exist only where an Action writes them (data an App owns), and a record no Action has written reads it as empty. Leave it out of backing.mapping and list it in backing.editable. It is a string, number, boolean, date or timestamp, never required, unique, the primaryKey or the title, and the type reads a dataset. Set when the field is added: it cannot be switched on or off or given another value type later, because the values Actions wrote would not follow. renamedFrom renames it and keeps them. A field added under a removed one\'s name starts empty.',
+          },
           renamedFrom: {
             type: 'string',
             pattern: '^[a-z][A-Za-z0-9]{0,99}$',
@@ -126,7 +130,7 @@ const OBJECT_TYPE: JsonSchema = {
         dataset: text('The dataset’s apiName (datasets/<apiName>.json). Naming another dataset moves the type to it on `frontera blueprint apply` and in a change request’s Apply; each property keeps its column. A change request creates a new type bound to it, in the same release.'),
         mapping: {
           type: 'object',
-          description: 'property apiName → its column, or { column, field } for a field inside a column.',
+          description: 'property apiName → its column, or { column, field } for a field inside a column. An edit-only property has no entry.',
           additionalProperties: {
             anyOf: [
               { type: 'string', minLength: 1 },

package/src/local/local-person-steps.ts

@@ -4,7 +4,7 @@ import { dirname, join } from 'node:path'
 import { writeFileAtomic } from '../fs-atomic'
 import { getProfile } from '../profiles'
 import { localProject } from './local-project'
-import { readLink, targetOf, targetProfileName } from './local-sync-link'
+import { projectTargets, targetOf, targetProfileName } from './local-sync-link'
 
 /**
  * Person-steps (Forge improvement plan T4, N4): a step only the person may
@@ -133,8 +133,8 @@ export function readPersonSteps(root: string): PersonStep[] {
   } catch {
     return []
   }
-  const current = steps.some((s) => s.profile) ? currentTarget(root) : null
-  return current ? steps.map((s) => aimedAt(s, current)) : steps
+  const targets = steps.some((s) => s.profile) ? stepTargets(root) : []
+  return targets.length ? steps.map((s) => aimedAt(s, targets)) : steps
 }
 
 /**
@@ -143,9 +143,10 @@ export function readPersonSteps(root: string): PersonStep[] {
  * folder's path, so it changes when the folder is moved or renamed, while the
  * steps file moves with the folder.
  */
-function aimedAt(step: PersonStep, current: StepTarget): PersonStep {
+function aimedAt(step: PersonStep, targets: StepTarget[]): PersonStep {
   const was = step.profile
-  if (!was || step.target !== current.target || was === current.profile) return step
+  const current = targets.find((t) => t.target === step.target)
+  if (!was || !current || was === current.profile) return step
   const swap = (command: string) => command.split(' ')
     .map((word, i, words) => (word === was && words[i - 1] === '--profile' ? current.profile : word === `--profile=${was}` ? `--profile=${current.profile}` : word))
     .join(' ')
@@ -303,16 +304,15 @@ export function checkProblem(check: StepCheck, readOnly: readonly string[]): str
   return null
 }
 
-/** Where a folder's link points (`targetOf`), and the profile that reaches it (`targetProfileName`). */
+/** Where a folder's link or one of its named targets points (`targetOf`), and the profile that reaches it (`targetProfileName`). */
 export interface StepTarget {
   target: string
   profile: string
 }
 
-/** The folder's current target, or null when it links to no workspace. */
-export function currentTarget(root: string): StepTarget | null {
-  const link = readLink(root)
-  return link ? { target: targetOf(link), profile: targetProfileName(localProject(root), link) } : null
+/** The folder's link, then its named targets; none when it delivers nowhere. */
+export function stepTargets(root: string): StepTarget[] {
+  return projectTargets(localProject(root)).map((t) => ({ target: targetOf(t.link), profile: targetProfileName(t.owner, t.link) }))
 }
 
 /**
@@ -324,12 +324,13 @@ export function currentTarget(root: string): StepTarget | null {
  * is refused; adding a profile by hand would aim the step at a profile
  * nothing keeps in step with the link.
  */
-export function staleProblem(step: PersonStep, current: StepTarget | null): string | null {
-  if (step.target && step.target !== current?.target) {
-    return `it was recorded for ${step.target}, and this folder now links to ${current?.target ?? 'no workspace'}: link this folder back to it with \`frontera local sync connect --relink\`, or dismiss this step`
+export function staleProblem(step: PersonStep, targets: StepTarget[]): string | null {
+  const at = targets.find((t) => t.target === step.target)
+  if (step.target && !at) {
+    return `it was recorded for ${step.target}, and this folder now links to ${targets.map((t) => t.target).join(', ') || 'no workspace'}: link this folder back to it with \`frontera local sync connect --relink\`, or dismiss this step`
   }
   if (!step.profile) return null
-  if (step.profile !== current?.profile) {
+  if (!(at ? [at] : targets).some((t) => t.profile === step.profile)) {
     return `it names the profile ${step.profile}, which is not this folder's for its link, and it records no target to aim it at this folder's: dismiss this step`
   }
   if (!getProfile(step.profile)) {
@@ -415,13 +416,13 @@ export async function runStepChecks(
   now = new Date(),
 ): Promise<{ checked: number; done: PersonStep[]; problems: Array<{ id: string; problem: string }> }> {
   const steps = readPersonSteps(root)
-  const current = currentTarget(root)
+  const targets = stepTargets(root)
   const done: PersonStep[] = []
   const problems: Array<{ id: string; problem: string }> = []
   let checked = 0
   for (const step of steps) {
     if (step.status !== 'pending' || !step.check) continue
-    const problem = staleProblem(step, current) ?? checkProblem(step.check, readOnly)
+    const problem = staleProblem(step, targets) ?? checkProblem(step.check, readOnly)
     if (problem) {
       problems.push({ id: step.id, problem })
       continue

package/src/local/local-portability.ts

@@ -253,14 +253,16 @@ const MEDIA_CATALOG_COLUMNS = new Set(['media_item_id', 'path', 'mime_type', 'si
 /**
  * The Media Set whose catalog an object type reads, by its API name: the
  * catalog's dataset is `media_<set>`, and every column the type reads is one
- * the catalog publishes. Null for a type over a set's extracted text or
- * passages (other columns), or a dataset named otherwise.
+ * the catalog publishes (an edit-only field reads none). Null for a type over
+ * a set's extracted text or passages (other columns), or a dataset named
+ * otherwise.
  */
 export function mediaCatalogSet(doc: Doc): string | null {
   const m = typeof doc.backing?.dataset === 'string' ? /^media_([A-Za-z][A-Za-z0-9_]*)$/.exec(doc.backing.dataset) : null
   if (!m) return null
   const mapping = (doc.backing?.mapping ?? {}) as Record<string, unknown>
-  const properties = (Array.isArray(doc.properties) ? doc.properties : []) as Array<{ apiName?: string; column?: unknown }>
+  const properties = ((Array.isArray(doc.properties) ? doc.properties : []) as Array<{ apiName?: string; column?: unknown; editOnly?: unknown }>)
+    .filter((p) => p.editOnly !== true)
   const columns = properties.map((p) => (typeof p.column === 'string' ? p.column : typeof mapping[p.apiName ?? ''] === 'string' ? (mapping[p.apiName ?? ''] as string) : null))
   return columns.every((c) => c !== null && MEDIA_CATALOG_COLUMNS.has(c)) ? m[1]! : null
 }

package/src/local/local-schemas.ts

@@ -7,6 +7,7 @@ import type { LocalProject } from './local-project'
 import { isAlive, readState } from './local-state'
 import { PROCEDURE_TOOL_FORMS, PROCEDURE_TOOL_GROUPS } from './local-agent-checks'
 import { DEFAULT_HANDOVER_REASON_KEYS } from './local-operating'
+import { TARGET_NAME } from './local-sync-link'
 import { REF_KINDS, refPattern, type RefKind } from './local-sync-refs'
 
 /**
@@ -47,6 +48,7 @@ export const SCHEMA_KINDS = [
   'blueprint-object-set',
   'blueprint-workspace-grants',
   'secrets',
+  'sync',
 ] as const
 export type SchemaKind = (typeof SCHEMA_KINDS)[number]
 
@@ -66,6 +68,7 @@ export const SCHEMA_FILES: Record<SchemaKind, string> = {
   knowledge: 'knowledge/<name>/knowledge.json',
   skill: 'skills/<name>/SKILL.md (its front matter)',
   secrets: 'secrets.json',
+  sync: 'frontera.yaml (its sync block)',
   ...BLUEPRINT_SCHEMA_FILES,
 }
 
@@ -740,6 +743,43 @@ const SECRETS_SCHEMA: JsonSchema = {
   additionalProperties: false,
 }
 
+/** A workspace the project reaches, as `local-sync-link.ts` reads it. */
+const SYNC_LINK_PROPERTIES = {
+  platform: { type: 'string', description: 'The platform’s API origin, e.g. https://api.acme.frontera.example.' },
+  workspace: { type: 'string', description: 'The workspace’s id.' },
+  workspaceName: { type: 'string', description: 'Its name, shown by `sync status` and Forge; refreshed on connect.' },
+  organization: { type: 'string', description: 'The organization’s id, when an organization key was given.' },
+  organizationName: { type: 'string' },
+  blueprint: { enum: ['workspace', 'organization'], description: '`workspace`: the slice of the Blueprint granted to the workspace (default). `organization`: the whole model.' },
+  models: { type: 'object', additionalProperties: { type: 'string' }, description: 'A model only this computer has → the workspace’s model it goes as when proposed (`local sync map-model`).' },
+} as const
+
+/** `frontera.yaml`'s `sync` block: the project's link and its named targets (`local-sync-link.ts`). */
+const SYNC_SCHEMA: JsonSchema = {
+  $schema: DRAFT,
+  title: 'The workspaces a project pulls from and delivers to (frontera.yaml sync)',
+  description:
+    'Written by `frontera local sync connect`, which checks the keys and keeps them in this computer’s keychain, never in the file. The block’s own fields are the project’s link: what it pulls from, and where `push` and `request` act by default. `targets` are workspaces it delivers to by name (`local sync push --target <name>`, `request apply --target <name>`), each with its own keys, stored with `frontera local sync connect --target <name>`. A teammate who clones the project runs those connects to store their own keys.',
+  type: 'object',
+  properties: {
+    ...SYNC_LINK_PROPERTIES,
+    targets: {
+      type: 'object',
+      description: 'Named targets, by name: lowercase letters, digits and dashes, starting with a letter (staging, production). Each is another workspace than the link and than every other target. `platform` is an https address (the scheme may be left out); an entry the CLI cannot use is left out, and `sync status` says why.',
+      propertyNames: { pattern: TARGET_NAME.source },
+      additionalProperties: {
+        type: 'object',
+        // No `models`: a push to a target maps models with the project's own `sync.models`.
+        properties: {
+          ...Object.fromEntries(Object.entries(SYNC_LINK_PROPERTIES).filter(([key]) => key !== 'models')),
+          production: { type: 'boolean', description: 'Marks a production target in `sync status` and in messages, set with `connect --target <name> --production`. Every target, production or not, is reached only by a command that names it, and the link is never pointed at a target’s workspace.' },
+        },
+        required: ['platform', 'workspace'],
+      },
+    },
+  },
+}
+
 /** `apps/<slug>.json`, as a pull writes it (`appDocument` in `local-apps.ts`; `appSettingsCandidate` in the service). */
 const APP_SCHEMA: JsonSchema = {
   $schema: DRAFT,
@@ -788,6 +828,7 @@ export function cliSchema(kind: SchemaKind): JsonSchema | null {
   if (kind === 'knowledge') return KNOWLEDGE_SCHEMA
   if (kind === 'skill') return SKILL_SCHEMA
   if (kind === 'secrets') return SECRETS_SCHEMA
+  if (kind === 'sync') return SYNC_SCHEMA
   if (kind in BLUEPRINT_SCHEMAS) return BLUEPRINT_SCHEMAS[kind as keyof typeof BLUEPRINT_SCHEMAS]
   return null
 }