@frontera-sdk/cli 1.52.39 → 1.52.40

package/src/local/local-schemas.ts

@@ -2,8 +2,11 @@ import { existsSync, readFileSync, rmSync } from 'node:fs'
 import { join } from 'node:path'
 
 import { writeFileAtomic } from '../fs-atomic'
+import { BLUEPRINT_SCHEMA_FILES, BLUEPRINT_SCHEMAS } from './local-blueprint-schemas'
 import type { LocalProject } from './local-project'
 import { isAlive, readState } from './local-state'
+import { PROCEDURE_TOOL_FORMS, PROCEDURE_TOOL_GROUPS } from './local-agent-checks'
+import { REF_KINDS, refPattern, type RefKind } from './local-sync-refs'
 
 /**
  * The formats of a project's files, as JSON Schema, for the coding agents and
@@ -11,13 +14,37 @@ import { isAlive, readState } from './local-state'
  *
  * The service checks three of them, so their schemas come from the service
  * the runtime runs (`GET /v1/config/file-schemas/<kind>`), made from the same
- * zod schemas that check the files. The other two only this CLI reads, so it
- * describes them itself, beside the code that reads them. `local start` writes
- * all five into `.frontera/local/schemas/` once the service is up, so they can
- * be read while the runtime is stopped and always describe the release it ran.
+ * zod schemas that check the files, then widened where a project file names a
+ * resource by reference instead of id (`localizeServiceSchema`). The others
+ * (Agent and workflow tests, datasets, the Blueprint's files) only this CLI
+ * reads, so it describes them itself, beside the code that reads them. `local
+ * start` writes all of them into `.frontera/local/schemas/` once the service is
+ * up, so they can be read while the runtime is stopped and always describe the
+ * release it ran.
  */
 
-export const SCHEMA_KINDS = ['operating', 'agent', 'workflow', 'evals', 'dataset'] as const
+export const SCHEMA_KINDS = [
+  'operating',
+  'agent',
+  'workflow',
+  'evals',
+  'workflow-tests',
+  'dataset',
+  'bindings',
+  'theme',
+  'chat-app',
+  'knowledge',
+  'skill',
+  'blueprint-object-type',
+  'blueprint-link-type',
+  'blueprint-shared-field',
+  'blueprint-semantic-type',
+  'blueprint-metric',
+  'blueprint-action',
+  'blueprint-object-set',
+  'blueprint-workspace-grants',
+  'secrets',
+] as const
 export type SchemaKind = (typeof SCHEMA_KINDS)[number]
 
 /** Where each kind of file lives in a project. */
@@ -26,7 +53,15 @@ export const SCHEMA_FILES: Record<SchemaKind, string> = {
   agent: 'agents/<slug>/agent.json',
   workflow: 'workflows/<slug>.yaml',
   evals: 'agents/<slug>/evals/*.yaml',
+  'workflow-tests': 'workflows/tests/<slug>.yaml',
   dataset: 'datasets/<apiName>.json',
+  bindings: 'agents/<slug>/bindings.json',
+  theme: 'themes/<name>/theme.json',
+  'chat-app': 'chat-apps/<slug>.json',
+  knowledge: 'knowledge/<name>/knowledge.json',
+  skill: 'skills/<name>/SKILL.md (its front matter)',
+  secrets: 'secrets.json',
+  ...BLUEPRINT_SCHEMA_FILES,
 }
 
 export function isSchemaKind(value: string): value is SchemaKind {
@@ -37,6 +72,51 @@ const DRAFT = 'https://json-schema.org/draft/2020-12/schema'
 
 type JsonSchema = Record<string, unknown>
 
+/**
+ * One check on a case's last reply, by its `type` (`runCheck` in `local-test-runner.ts`).
+ * Open to other keys: a check pulled from the platform may carry the platform's own.
+ */
+function CHECK(type: 'contains' | 'regex' | 'tool_called' | 'tool_not_called'): JsonSchema {
+  const text = { type: 'string', description: 'What the check means, in words; shown when it fails.' }
+  if (type === 'contains') {
+    return {
+      title: 'contains',
+      type: 'object',
+      properties: { type: { const: 'contains' }, value: { type: 'string', minLength: 1, description: 'The phrase the reply must hold, ignoring case. Text: quote a number (`"12"`).' }, text },
+      required: ['type', 'value'],
+    }
+  }
+  if (type === 'regex') {
+    return {
+      title: 'regex',
+      type: 'object',
+      properties: {
+        type: { const: 'regex' },
+        value: { type: 'string', minLength: 1, maxLength: 500, description: 'The pattern the reply must match (JavaScript syntax); a nested quantifier such as `(a+)+` is refused.' },
+        flags: { type: 'string', pattern: '^[dgimsuvy]*$', description: 'Regex flags; `i` when absent.' },
+        text,
+      },
+      required: ['type', 'value'],
+    }
+  }
+  return {
+    title: type,
+    type: 'object',
+    properties: {
+      type: { const: type },
+      tool: { type: 'string', minLength: 1, description: 'The tool’s name as the trace shows it (`function_<slug>` for a Function, `searchKnowledge`; a Plugin’s tool by its capability name, `mcp__…`, never its bare name).' },
+      argsSubset: { type: 'object', description: 'The arguments the call must carry.' },
+      turn: { enum: ['all', 'last'], description: 'Which turns’ calls the check reads: every turn of the case (`all`, the default) or only the last one, the turn whose reply the case grades.' },
+      mode: { enum: ['exact', 'ignore', 'subset', 'superset'], description: 'How argsSubset is compared; superset when absent. The `action` narration an Agent may add to any call is left out of the comparison unless argsSubset names it.' },
+      text,
+    },
+    required: ['type', 'tool'],
+  }
+}
+
+/** The longest wait before one turn of an Agent case (`waitSeconds` in the evals format). */
+export const MAX_TURN_WAIT_SECONDS = 300
+
 /** `agents/<slug>/evals/*.yaml`, as `local test` and Studio read it (`local-test-runner.ts`). */
 const EVALS_SCHEMA: JsonSchema = {
   $schema: DRAFT,
@@ -54,13 +134,27 @@ const EVALS_SCHEMA: JsonSchema = {
           conversation: {
             type: 'array',
             minItems: 1,
-            description: 'One turn per item. Only the user turns are sent; an assistant turn is kept for whoever reads the case.',
+            description: 'One turn per item. Only the user turns are sent, in order, each as soon as the reply before it ends; an assistant turn is kept for whoever reads the case. `waitSeconds` on a user turn keeps a gap before it (`- { user: "Still there?", waitSeconds: 60 }` sends it a minute after the reply before).',
             items: {
               type: 'object',
-              properties: { user: { type: 'string' }, assistant: { type: 'string' } },
+              properties: {
+                user: { type: 'string', description: 'What the person says; sent.' },
+                assistant: { type: 'string', description: 'A reply, kept for whoever reads the case; not sent and not checked.' },
+                waitSeconds: {
+                  type: 'integer',
+                  minimum: 1,
+                  maximum: MAX_TURN_WAIT_SECONDS,
+                  description: `With \`user\`: how long to wait, in seconds, before sending this turn (at most ${MAX_TURN_WAIT_SECONDS}), so the case keeps a gap such as "turn 2 a minute after turn 1". The case takes that much longer, and its result says it waited (\`waited 60 s before turn 2\`).`,
+                },
+              },
               minProperties: 1,
-              maxProperties: 1,
+              maxProperties: 2,
               additionalProperties: false,
+              // A turn is one person's message (with its wait) or one reply, never both.
+              anyOf: [
+                { properties: { user: { type: 'string' }, waitSeconds: { type: 'integer' } }, required: ['user'], additionalProperties: false },
+                { properties: { assistant: { type: 'string' } }, required: ['assistant'], additionalProperties: false },
+              ],
             },
           },
           expected: { type: 'string', description: 'The last reply, word for word; differences in whitespace are ignored.' },
@@ -72,23 +166,31 @@ const EVALS_SCHEMA: JsonSchema = {
           },
           checks: {
             type: 'array',
-            description: 'Checks on the last reply and the tools the Agent called, graded as the platform grades them; every one must pass.',
-            items: {
-              type: 'object',
-              properties: {
-                type: { enum: ['contains', 'regex', 'tool_called', 'tool_not_called'] },
-                value: { type: 'string', description: 'contains: the phrase; regex: the pattern.' },
-                flags: { type: 'string', description: 'regex flags; i when absent.' },
-                tool: { type: 'string', description: 'tool_called, tool_not_called: the tool’s name.' },
-                argsSubset: { type: 'object', description: 'The arguments the call must carry.' },
-                mode: { enum: ['exact', 'ignore', 'subset', 'superset'], description: 'How argsSubset is compared; superset when absent.' },
-                text: { type: 'string', description: 'What the check means, in words.' },
-              },
-              required: ['type'],
-            },
+            description: 'Checks on the last reply and the tools the Agent called, graded as the platform grades them; every one must pass. `type` says which keys a check takes.',
+            items: { oneOf: [CHECK('contains'), CHECK('regex'), CHECK('tool_called'), CHECK('tool_not_called')] },
           },
           judged: { type: 'array', items: { type: 'string' }, description: 'Expectations only the platform’s judge grades; kept, not graded locally.' },
           gold: { type: 'boolean', description: 'Human-certified on the platform.' },
+          decision: {
+            enum: ['approve', 'deny', 'expect'],
+            description:
+              'What the case does when a turn stops on a decision a person makes (a tool that needs approval, a confirmation): approve or deny a tool approval and read the reply on, or expect it (the case passes by waiting, its checks run on the reply so far, and the tool call waiting on the approval counts for `tool_called`, with the arguments it was called with: test that the Agent asks before it acts without approving anything). Without it, a turn that waits fails the case with "waited for a decision: <tool>". A confirmation card cannot be answered here. A case with a decision runs real actions (see realActions): it changes records on the local runtime.',
+          },
+          realActions: {
+            type: 'boolean',
+            description:
+              'Run the tools that change something for real, as `agent_chat` with realActions does: the case changes records on the local runtime (a governed Action is submitted, a Function or workflow runs). Without it, and without `decision`, they are simulated: each answers as a success with an empty result and none asks for approval, even one whose binding requires it; only a case with real actions stops on an approval. A case with `decision` (approve, deny or expect) runs real actions whether or not it says so, since only a real action waits for approval; with `expect` the tool waiting on the approval never runs (the case ends there), though tools the Agent called before it did.',
+          },
+          variables: {
+            type: 'object',
+            additionalProperties: { type: ['string', 'number', 'boolean'] },
+            description: 'The conversation’s variables for this case, by name (`customer_id: CST-00060`), as a channel would set them: what the instructions read as {{customer_id}} and what operating.json `dataScopes` narrow reads by. Without it the case’s conversation has none. Not for a scenario case: the evaluation runner gives a scenario no variables yet.',
+          },
+          gate: {
+            type: 'boolean',
+            description:
+              "Guards the Agent's behavior: a change request runs the Agent's `gate: true` cases before it applies, against the last applied run, and the workspace can require them to pass. `test_run` with `gate: true` (the MCP server) runs only these.",
+          },
           scenario: {
             type: 'object',
             description: 'A conversation with a simulated customer (persona, goal, opening, maxTurns, verified, results, note), run on the local runtime’s evaluation runner.',
@@ -113,6 +215,63 @@ const EVALS_SCHEMA: JsonSchema = {
   additionalProperties: false,
 }
 
+/** One output check of a workflow test case (`local-workflow-tests.ts`). */
+const WORKFLOW_OUTPUT_CHECK = {
+  type: 'object',
+  properties: {
+    path: {
+      type: 'string',
+      minLength: 1,
+      description: 'A dot path into what the run returned (`decision`, `items.0.id`). A leading `output.` also names what it returned (`output.decision` reads `decision`), except when what it returned has a key named `output` (a workflow whose `output` is a Function step’s whole result, `{ runId, output: { … } }`): then the path reads that key, so `output.withdrawn` reads `{ "output": { "withdrawn": true } }`. `steps.<stepId>.output.<path>` reads one step’s output, `steps.<stepId>.status` its status. A forEach step’s output is the list of its iterations, as `$steps` gives it; each iteration holds every inner step’s output under the inner step’s id (`{ "<innerStepId>": { …its output } }`), so read one with `steps.<stepId>.output.0.<innerStepId>.<path>` (for example `steps.escalate_each.output.0.escalate.lifecycle`), and the count with `steps.<stepId>.output.length` (the run’s own view, `.results.0…`, `.count`, reads too).',
+    },
+    equals: { description: 'The value there, exactly (types count: 120 is not "120").' },
+    contains: { description: 'Text there holds this (ignoring case); a list there has an item equal to it; a mapping there holds these keys and values.' },
+    exists: { type: 'boolean', description: 'Something is there (true) or nothing is (false).' },
+  },
+  required: ['path'],
+  anyOf: [{ required: ['equals'] }, { required: ['contains'] }, { required: ['exists'] }],
+  additionalProperties: false,
+}
+
+/** `workflows/tests/<slug>.yaml`, as `local test` and `local check` read it (`local-workflow-tests.ts`). */
+const WORKFLOW_TESTS_SCHEMA: JsonSchema = {
+  $schema: DRAFT,
+  title: 'Workflow test cases (workflows/tests/<slug>.yaml)',
+  description:
+    "`frontera local test` (`--workflow <slug>` for one) and `frontera local check` run each case on exactly the version `local dev` pushed workflows/<slug>.yaml as (a test run while it is a draft; a run of the live version once an Agent's binding promoted it): the input (and subject) sent, the run waited for, then its status, failed step and output checked. When the file changed since it was applied, or its apply failed, the cases fail with what to run instead of testing other code.",
+  type: 'object',
+  properties: {
+    workflow: { type: 'string', minLength: 1, description: 'The workflow’s slug (workflows/<slug>.yaml); the file’s name when absent.' },
+    cases: {
+      type: 'array',
+      minItems: 1,
+      items: {
+        type: 'object',
+        properties: {
+          name: { type: 'string', minLength: 1, description: 'Names the case in results.' },
+          input: { type: 'object', description: 'The run’s input, as the workflow’s `input` declares it.' },
+          subject: { type: 'string', minLength: 1, description: 'The primary key of the record a record-bound workflow runs on.' },
+          timeoutSeconds: { type: 'integer', minimum: 1, maximum: 900, description: 'How long to wait for the run; 120 when absent.' },
+          expect: {
+            type: 'object',
+            properties: {
+              status: { enum: ['succeeded', 'failed', 'canceled'], description: 'How the run must end; succeeded when absent (failed when failedStep or failedCode is set).' },
+              failedStep: { type: 'string', minLength: 1, description: 'The id of the step that must fail; a `stop` step with `status: failed` counts as the step that failed its run.' },
+              failedCode: { type: 'string', minLength: 1, description: 'The error code a failed step (or the run) must carry, such as CONFIRM_UNAVAILABLE for a confirm step with `onUnavailable: fail`.' },
+              output: { type: 'array', items: WORKFLOW_OUTPUT_CHECK, description: 'Checks on what the run returned; every one must pass.' },
+            },
+            additionalProperties: false,
+          },
+        },
+        required: ['name'],
+        additionalProperties: false,
+      },
+    },
+  },
+  required: ['cases'],
+  additionalProperties: false,
+}
+
 /** The column types `dataset create` accepts (`commands/dataset/index-commands.ts`). */
 const COLUMN_TYPES = ['text', 'numeric', 'boolean', 'date', 'timestamptz']
 
@@ -187,6 +346,23 @@ const DATASET_SCHEMA: JsonSchema = {
         kind: { const: 'file' },
         path: { type: 'string', minLength: 1, description: 'The CSV, relative to this file.' },
         includedColumns: COLUMN_NAMES,
+        columns: {
+          type: 'array',
+          minItems: 1,
+          description:
+            "What the file declares of a column instead of taking it from the first CSV: its nullability, its type, or both (the rest come from the CSV). The first load fixes the dataset's column contract, and a later CSV must fit it, so declare `nullable: true` on every column that may be empty in any CSV you will load (an optional field, a time set only later in a record's life). With `columns`, the CSV holds exactly the included columns. When a later CSV has empty values a column did not allow, `frontera local dev` cuts a new revision of the dataset that allows them and binds its object types to it; a column added, dropped or retyped is a new dataset (another apiName, or `frontera local reset`).",
+          items: {
+            type: 'object',
+            properties: {
+              name: { type: 'string', minLength: 1, description: 'One of includedColumns.' },
+              nullable: { type: 'boolean' },
+              databaseType: { type: 'string', enum: COLUMN_TYPES },
+            },
+            required: ['name'],
+            anyOf: [{ required: ['nullable'] }, { required: ['databaseType'] }],
+            additionalProperties: false,
+          },
+        },
       },
       required: ['apiName', 'kind', 'path', 'includedColumns'],
       additionalProperties: false,
@@ -208,13 +384,553 @@ const DATASET_SCHEMA: JsonSchema = {
   ],
 }
 
+/** `agents/<slug>/bindings.json`, as `local dev` applies it (`applyBindings` in `local-dev-references.ts`). */
+const BINDINGS_SCHEMA: JsonSchema = {
+  $schema: DRAFT,
+  title: 'What an Agent may use (agents/<slug>/bindings.json)',
+  description:
+    "The Functions and workflows the Agent may start, and the Blueprint object types it may read (its Context and data). `frontera local dev` applies it after the Agent, its Functions, workflows and the Blueprint: each Function and workflow is bound to the Agent with these settings, and the object types are granted to it (a grant this file does not list is withdrawn). A procedure's `tools.ids` and actions may only name what is bound here, and without `blueprint` the Agent has neither the Blueprint query tools (`tool:blueprint`) nor the governed Action tools (`tool:blueprint-actions`). None of this belongs in agent.json.",
+  type: 'object',
+  properties: {
+    functions: {
+      type: 'array',
+      description: 'The Functions the Agent may call, as its tools (`function_<slug>` in a trace).',
+      items: {
+        type: 'object',
+        properties: {
+          function: { type: 'string', pattern: refPattern(['function']), description: '`function/<slug>`: functions/<slug>.ts, or functions/<slug>/.' },
+          enabled: { type: 'boolean', description: 'true when absent.' },
+          requiresApproval: { type: 'boolean', description: 'A person approves each call before it runs; true when absent. false lets the Agent call it on its own.' },
+          waitSeconds: { type: 'integer', minimum: 5, maximum: 300, description: 'How long the Agent waits for the run before it answers; 90 when absent.' },
+        },
+        required: ['function'],
+        additionalProperties: false,
+      },
+    },
+    workflows: {
+      type: 'array',
+      description: 'The workflows the Agent may start or read. An Agent runs a workflow’s live version, so `local dev` promotes the version it pushed the workflow’s file as when one bound here has no live version, and after that promotes each new push of it, so the live version stays what the file says.',
+      items: {
+        type: 'object',
+        properties: {
+          workflow: { type: 'string', pattern: refPattern(['workflow']), description: '`workflow/<slug>`: workflows/<slug>.yaml.' },
+          access: { enum: ['run', 'read'], description: 'run (the default): the Agent may start runs; read: it may only read them.' },
+          enabled: { type: 'boolean', description: 'true when absent.' },
+          requiresApproval: { type: 'boolean', description: 'A person approves each run before it starts.' },
+          waitSeconds: { type: 'integer', minimum: 5, maximum: 300, description: 'How long the Agent waits for the run before it answers; 90 when absent.' },
+        },
+        required: ['workflow'],
+        additionalProperties: false,
+      },
+    },
+    blueprint: {
+      type: 'array',
+      description: 'Its Context and data: the object types it may query through its Blueprint tools.',
+      items: {
+        type: 'object',
+        properties: {
+          objectType: { type: 'string', pattern: refPattern(['objectType']), description: '`objectType/<ApiName>`: blueprint/object-types/<ApiName>.yaml.' },
+          permissions: {
+            type: 'array',
+            items: { enum: ['read', 'read_sensitive', 'act'] },
+            description: 'The grant’s whole list. read (always included) sees the records; read_sensitive also sees their confidential and restricted fields; act lets the Agent submit governed Actions on the type (Submit Actions; it implies read). Without act on a type the Agent is offered no Action on it, and the person it works for still needs the Action’s capability. Leaving a permission out takes it away, here and when a change request is applied, so removing act from a pulled list turns Submit Actions off. An entry without permissions is read plus what the Agent’s grant already holds (act and read_sensitive kept).',
+          },
+        },
+        required: ['objectType'],
+        additionalProperties: false,
+      },
+    },
+    blueprintUnread: { const: true, description: 'Written by a pull that could not read the Agent’s grants: locally it reads every object type the project holds. Not written by hand.' },
+  },
+  additionalProperties: false,
+}
+
+/** The colors and type of a theme (`SlideThemeTokens` in the service). */
+const HEX = { type: 'string', pattern: '^#[0-9A-Fa-f]{6}$' }
+
+/** `themes/<name>/theme.json`, as `local dev` saves it (`applyTheme` in `local-themes.ts`, `POST /v1/slide-themes`). */
+const THEME_SCHEMA: JsonSchema = {
+  $schema: DRAFT,
+  title: 'Slide theme (themes/<name>/theme.json)',
+  description:
+    "A slide theme an Agent's decks and images are made in (`createSlides`, `createImage`): its colors and fonts, the style the model follows, and optional layouts and images. The file is `themes/<name>/theme.json`, with every image it names beside it in `themes/<name>/`; `frontera local dev` saves it on the runtime, replacing the copy of the same name. A file elsewhere in themes/ is not applied.",
+  type: 'object',
+  properties: {
+    name: { type: 'string', minLength: 1, maxLength: 200, description: 'How the theme is listed and named in a request.' },
+    styleDescription: { type: 'string', maxLength: 20_000, description: 'The look in words; the model reads this most. Say the mood, the layout habits, what to avoid.' },
+    source: { enum: ['custom', 'imported'], description: 'custom for one written by hand; imported for one made from a deck.' },
+    tokens: {
+      type: 'object',
+      description: 'The palette and type the slides are built from.',
+      properties: {
+        mode: { enum: ['light', 'dark'] },
+        bg: { ...HEX, description: 'The slide background.' },
+        ink: { ...HEX, description: 'The text.' },
+        accent: { ...HEX, description: 'The one accent: bars, highlights.' },
+        accent2: { ...HEX, description: 'A second accent for charts.' },
+        neutral: { ...HEX, description: 'Cards, panels and dividers.' },
+        fontHeading: { type: 'string', minLength: 1, description: 'A web-safe font stack, so a .pptx export keeps it ("Arial, Helvetica, sans-serif").' },
+        fontBody: { type: 'string', minLength: 1, description: 'A web-safe font stack.' },
+        headingWeight: { type: 'integer', minimum: 100, maximum: 900 },
+        radius: { type: 'string', description: 'Card corner radius: "12px", or "0" for a flat look.' },
+      },
+      required: ['mode', 'bg', 'ink', 'accent', 'neutral', 'fontHeading', 'fontBody', 'headingWeight', 'radius'],
+    },
+    slideCount: { type: 'integer', minimum: 0 },
+    layouts: {
+      type: 'array',
+      maxItems: 200,
+      description: 'Page shapes the model maps content onto, each with an optional reference image.',
+      items: {
+        type: 'object',
+        properties: {
+          kind: { enum: ['cover', 'section', 'content', 'kpi', 'chart', 'quote', 'grid', 'closing'] },
+          hint: { type: 'string', minLength: 1, description: 'The layout in one line.' },
+          image: { type: 'string', pattern: '^[A-Za-z0-9][A-Za-z0-9._-]{0,199}$', description: 'A file beside theme.json.' },
+        },
+        required: ['kind', 'hint'],
+        additionalProperties: false,
+      },
+    },
+    assets: {
+      type: 'array',
+      maxItems: 200,
+      description: 'Reusable images (backgrounds, logos, art), each a file beside theme.json.',
+      items: {
+        type: 'object',
+        properties: {
+          name: { type: 'string', minLength: 1 },
+          mime: { type: 'string', minLength: 1, description: 'image/png, image/jpeg, image/svg+xml…' },
+          file: { type: 'string', pattern: '^[A-Za-z0-9][A-Za-z0-9._-]{0,199}$' },
+        },
+        required: ['name', 'mime', 'file'],
+        additionalProperties: false,
+      },
+    },
+    thumbnail: { type: 'string', pattern: '^[A-Za-z0-9][A-Za-z0-9._-]{0,199}$', description: 'A preview image beside theme.json.' },
+  },
+  required: ['name', 'tokens'],
+  additionalProperties: false,
+}
+
+const UUID_PATTERN = '^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$'
+
+/** The experience features a Chat App can offer (`CHAT_APP_FEATURES` in the service's `chat-app-config.ts`). */
+export const CHAT_APP_FEATURES = ['fileUpload', 'webBrowsing', 'voice', 'artifacts', 'canvas', 'followUps', 'workDetails', 'overview', 'fork', 'share', 'export', 'schedule', 'labels', 'feedback', 'humanHandoff'] as const
+
+const FEATURE_WORDS: Record<(typeof CHAT_APP_FEATURES)[number], string> = {
+  fileUpload: 'people may attach files',
+  webBrowsing: 'its Agents may search the web',
+  voice: 'voice input',
+  artifacts: 'its Agents may make files (documents, decks, sheets)',
+  canvas: 'the canvas',
+  followUps: 'suggested follow-up questions',
+  workDetails: 'people may open the details of the work an Agent did (the steps it takes; a step that starts a procedure shows its name, never its guidance). Off unless set to true: leave it out, or false, for an App customers use',
+  overview: 'the conversation overview',
+  fork: 'people may fork a Session',
+  share: 'people may share a Session',
+  export: 'people may export a conversation',
+  schedule: 'scheduled tasks',
+  labels: 'Session labels',
+  feedback: 'thumbs up and down on replies',
+  humanHandoff: 'an Agent may hand the conversation to a person (stored as intent; shown where the surface has a control)',
+}
+
+/** `chat-apps/<slug>.json`, as `local dev` saves it (`applyChatApp` in `local-chat-apps.ts`; `chatAppConfigSchema` in the service). */
+const CHAT_APP_SCHEMA: JsonSchema = {
+  $schema: DRAFT,
+  title: 'Chat App (chat-apps/<slug>.json)',
+  description:
+    'The experience people use an Agent in: what they see first, the roster of Agents, which features it offers, and its conversation and memory behaviour. `frontera local dev` creates the App by its file name (the slug) and saves the rest as its draft; every section is optional and a key left out keeps its default. A key the platform does not know is dropped, and `local dev` warns about it. Each feature is a request: it is also limited by what the Agent itself allows. Who may open the App and its addresses are set on the platform.',
+  type: 'object',
+  properties: {
+    name: { type: 'string', minLength: 1, description: 'The App’s name; the file name when absent.' },
+    description: { type: 'string', description: 'One line about it, on its card.' },
+    schemaVersion: { const: 1 },
+    presentation: {
+      type: 'object',
+      description: 'What people see first.',
+      properties: {
+        welcomeTitle: { type: 'string', maxLength: 120 },
+        welcomeMessage: { type: 'string', maxLength: 2000 },
+        suggestedPrompts: { type: 'array', maxItems: 8, items: { type: 'string', minLength: 1, maxLength: 300 }, description: 'Starters shown under the welcome.' },
+        context: { type: 'string', maxLength: 4000, description: 'The situation the App puts its Agents in ("Customers writing from the portal"): added to each turn, not a system prompt.' },
+        accent: { anyOf: [{ enum: ['blue', 'violet', 'green', 'amber', 'rose', 'teal', 'slate'] }, { type: 'null' }] },
+      },
+      additionalProperties: false,
+    },
+    roster: {
+      type: 'object',
+      description: 'The Agents people talk to in it.',
+      properties: {
+        mode: { enum: ['single', 'multiple'] },
+        defaultAgentConfigId: { anyOf: [{ type: 'string', pattern: refPattern(['agent']) }, { type: 'string', pattern: UUID_PATTERN }, { type: 'null' }], description: '`agent/<slug>`: the Agent a new Session starts with; the first on the roster when absent.' },
+        agents: {
+          type: 'array',
+          maxItems: 20,
+          items: {
+            type: 'object',
+            properties: {
+              agentConfigId: { anyOf: [{ type: 'string', pattern: refPattern(['agent']) }, { type: 'string', pattern: UUID_PATTERN }], description: '`agent/<slug>`: agents/<slug>/ (or a platform id a pull could not name). `local dev` resolves it to this runtime’s Agent.' },
+              label: { anyOf: [{ type: 'string', maxLength: 80 }, { type: 'null' }], description: 'The name people see here; the Agent’s own when absent.' },
+              description: { anyOf: [{ type: 'string', maxLength: 300 }, { type: 'null' }], description: 'The line people see here; the Agent’s own when absent.' },
+            },
+            required: ['agentConfigId'],
+            additionalProperties: false,
+          },
+        },
+        allowSwitching: { type: 'boolean', description: 'People may pick another roster Agent for a new Session (mode multiple).' },
+        allowMentions: { type: 'boolean', description: '`@Agent` mentions in Agent mode.' },
+        agentModeEnabled: { type: 'boolean', description: 'Offer the persistent Agent conversation for roster Agents that allow it.' },
+      },
+      additionalProperties: false,
+    },
+    features: {
+      type: 'object',
+      description: 'Which features the App offers; false withholds one. A feature left out keeps the platform default: on for fileUpload, webBrowsing, artifacts, canvas, followUps, overview, export and feedback; off for voice, workDetails, fork, share, schedule, labels and humanHandoff.',
+      properties: Object.fromEntries(CHAT_APP_FEATURES.map((f) => [f, { type: 'boolean', description: FEATURE_WORDS[f] }])),
+      additionalProperties: false,
+    },
+    conversation: {
+      type: 'object',
+      properties: {
+        multipleSessions: { type: 'boolean', description: 'Offer many Sessions, or only the standing Agent conversation.' },
+        history: { type: 'boolean', description: 'Show the App’s Session history.' },
+        allowClear: { type: 'boolean', description: 'A person may clear their own history.' },
+        defaultApprovalMode: { enum: ['ask', 'auto', 'full'], description: 'Never wider than what the person, the Agent or the workspace permits.' },
+      },
+      additionalProperties: false,
+    },
+    variables: {
+      type: 'object',
+      description: "Values the App gives a new conversation's variables, by the Agent's variable name, from the signed-in person. A draft preview uses each variable's testValue instead.",
+      propertyNames: { pattern: '^[a-z][a-z0-9_]{0,63}$' },
+      maxProperties: 20,
+      additionalProperties: {
+        type: 'object',
+        properties: {
+          from: { enum: ['user.id', 'user.email'], description: 'The signed-in person’s id, or their email (used only once it is verified).' },
+          lookup: {
+            anyOf: [
+              {
+                type: 'object',
+                description: 'Find the one record of objectType whose matchProperty equals the value; the variable takes its property.',
+                properties: {
+                  objectType: { type: 'string', minLength: 1, description: 'The Blueprint object type, e.g. Customer.' },
+                  matchProperty: { type: 'string', minLength: 1, description: 'The property that holds the person’s id or email, e.g. email.' },
+                  property: { type: 'string', minLength: 1, description: 'The property the variable takes, e.g. id.' },
+                },
+                required: ['objectType', 'matchProperty', 'property'],
+                additionalProperties: false,
+              },
+              { type: 'null' },
+            ],
+          },
+        },
+        required: ['from'],
+        additionalProperties: false,
+      },
+    },
+    memory: {
+      type: 'object',
+      properties: {
+        enabled: { type: 'boolean', description: 'Keep long-term memory for this App (only for an Agent that has memory).' },
+        userCanInspect: { type: 'boolean' },
+        userCanClear: { type: 'boolean' },
+      },
+      additionalProperties: false,
+    },
+  },
+  additionalProperties: false,
+}
+
+/** `knowledge/<name>/knowledge.json`, as `local dev` applies it (`applyKnowledge` in `local-dev-references.ts`). */
+const KNOWLEDGE_SCHEMA: JsonSchema = {
+  $schema: DRAFT,
+  title: 'Knowledge base (knowledge/<name>/knowledge.json)',
+  description:
+    'A knowledge base: the folder’s documents (Markdown, text, PDF, Word, HTML, in subfolders too) beside this file are uploaded into it by `frontera local dev`, which creates the base by `name` when the runtime has none and sets the settings given here; a setting left out keeps the platform’s default. An Agent searches it once its agent.json lists `{ "knowledgeConfigId": "knowledge/<name>" }` in knowledgeAttachments. Quality checks go in quality-checks.yaml beside it.',
+  type: 'object',
+  properties: {
+    name: { type: 'string', minLength: 1, description: 'How the base is named, and how `knowledge/<name>` finds it; the folder name when absent.' },
+    description: { type: 'string', description: 'What it holds, in a sentence: an Agent reads it when deciding to search.' },
+    retrieval: { enum: ['contextual', 'always'], description: 'contextual (the default): searched when a turn needs it; always: searched on every turn.' },
+    chunker: { enum: ['paragraph', 'sentence', 'markdown', 'manual', 'laws', 'qa', 'spreadsheet'], description: 'How documents are split; paragraph when absent.' },
+    chunkSize: { type: 'integer', minimum: 1, description: 'Characters per chunk; 2048 when absent.' },
+    chunkOverlap: { type: 'integer', minimum: 0, description: 'Characters shared by neighbouring chunks; 200 when absent.' },
+    topK: { type: 'integer', minimum: 1, description: 'How many passages a search returns; 4 when absent.' },
+    similarityThreshold: {
+      type: 'number',
+      minimum: 0,
+      maximum: 2,
+      description:
+        'The match threshold, as a maximum cosine distance from 0 to 2: a passage is found when its distance is at most this, so lower is stricter. 0.5 when absent. A search\'s score is 1 − distance / 2, so a threshold t keeps scores ≥ 1 − t / 2: 0.5 keeps scores ≥ 0.75, 0.75 keeps ≥ 0.625, 1 keeps ≥ 0.5. `frontera knowledge search <base> "<question>"` shows each passage\'s score and distance and the cutoff the base applies.',
+    },
+    hybridConfig: {
+      anyOf: [{ type: 'null' }, {
+        type: 'object',
+        description: 'Keyword search beside meaning search, and reranking.',
+        properties: { enabled: { type: 'boolean' }, rerank: { type: 'boolean' }, rerankerModel: { type: 'string' }, finalTopK: { type: 'integer', minimum: 1 } },
+      }],
+    },
+    extractorConfig: { anyOf: [{ type: 'null' }, { type: 'object', description: 'Reads structure out of documents with a model.', properties: { enabled: { type: 'boolean' }, model: { type: 'string' } } }] },
+    ocrConfig: { anyOf: [{ type: 'null' }, { type: 'object', description: 'Reads scanned PDFs with a vision model.', properties: { enabled: { type: 'boolean' }, model: { type: 'string' }, threshold: { type: 'number' }, batchSize: { type: 'integer', minimum: 1 } } }] },
+  },
+  additionalProperties: false,
+}
+
+/** The front matter of `skills/<name>/SKILL.md`, as `skill push` reads it (`bundle-commands.ts`; the service's skill import). */
+const SKILL_SCHEMA: JsonSchema = {
+  $schema: DRAFT,
+  title: 'Skill (the front matter of skills/<name>/SKILL.md)',
+  description:
+    'A skill: instructions an Agent loads when a task calls for them. SKILL.md opens with YAML front matter between `---` lines (described here), then the instructions in Markdown. Files beside it travel with it: refs/ or references/ (Markdown the skill reads), scripts/ (text scripts, never run by the platform) and assets (images, fonts, sheets). `frontera local dev` pushes the folder; an Agent uses it once its agent.json binds it. A key not listed here is ignored.',
+  type: 'object',
+  properties: {
+    name: { type: 'string', minLength: 1, description: 'The skill’s identity in the workspace, lowercase with hyphens by convention (`dispatch-triage`): what agent.json binds as `skill/<name>`. Keep it the same as the folder name.' },
+    description: { type: 'string', minLength: 1, description: 'What it does and when to use it, in a sentence or two: the Agent reads this to decide whether to load the skill.' },
+    displayName: { type: 'string', description: 'The name people see; the name when absent.' },
+    trigger: { enum: ['manual', 'auto', 'keyword'], description: 'manual (the default): loaded when the Agent chooses it; auto: offered on every turn; keyword: loaded when a message holds one of `keywords`.' },
+    keywords: { type: 'array', items: { type: 'string', minLength: 1 }, description: 'With trigger keyword: the words that load it.' },
+    enabled: { type: 'boolean', description: 'true when absent.' },
+    sortOrder: { type: 'integer', description: 'Its place among the workspace’s skills.' },
+    visibleAssets: { type: 'array', items: { type: 'string' }, description: 'Paths of assets (beside SKILL.md) people may see and download, not only the Agent.' },
+  },
+  required: ['name', 'description'],
+}
+
+const SECRETS_SCHEMA: JsonSchema = {
+  $schema: DRAFT,
+  title: 'The secrets a project needs (secrets.json)',
+  description:
+    'Names and descriptions only, never values: a value is set on each computer with `frontera secret set NAME` and stays on that runtime. `frontera local dev` and `frontera local check` say each listed secret the local runtime has no value for, and each secret a Function or workflow names that the file leaves out. A `value` is refused and ignored.',
+  type: 'object',
+  properties: {
+    secrets: {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: {
+          name: { type: 'string', pattern: '^[A-Z][A-Z0-9_]*$', description: 'The secret’s name, as a Function’s `secret:NAME` grant or a workflow’s `auth.secret` names it.' },
+          description: { type: 'string', description: 'What it is for and where its value comes from, for the person setting it.' },
+        },
+        required: ['name'],
+        additionalProperties: false,
+      },
+    },
+  },
+  required: ['secrets'],
+  additionalProperties: false,
+}
+
 /** The schema this CLI owns for a kind, or null when the service owns it. */
 export function cliSchema(kind: SchemaKind): JsonSchema | null {
   if (kind === 'evals') return EVALS_SCHEMA
+  if (kind === 'workflow-tests') return WORKFLOW_TESTS_SCHEMA
   if (kind === 'dataset') return DATASET_SCHEMA
+  if (kind === 'bindings') return BINDINGS_SCHEMA
+  if (kind === 'theme') return THEME_SCHEMA
+  if (kind === 'chat-app') return CHAT_APP_SCHEMA
+  if (kind === 'knowledge') return KNOWLEDGE_SCHEMA
+  if (kind === 'skill') return SKILL_SCHEMA
+  if (kind === 'secrets') return SECRETS_SCHEMA
+  if (kind in BLUEPRINT_SCHEMAS) return BLUEPRINT_SCHEMAS[kind as keyof typeof BLUEPRINT_SCHEMAS]
   return null
 }
 
+// ── The service's formats, as a project file may write them ─────────────────
+
+/**
+ * Where a project file names another resource, the runtime's schema wants
+ * its id (a uuid), and `local dev` accepts the project's reference instead
+ * (`kind/name`, read by `parseRef`, resolved by `local-dev-references.ts`
+ * before the file is applied). These say which kinds each place may name.
+ */
+
+/** A workflow step's (or trigger's) `resourceId`, by its `kind`. */
+const STEP_REFS: Record<string, { kinds: RefKind[]; words: string }> = {
+  blueprint: { kinds: ['objectType'], words: 'the object type it reads: `objectType/<ApiName>`' },
+  function: { kinds: ['function'], words: 'the Function it runs: `function/<slug>`' },
+  llm: { kinds: ['model'], words: 'the model it asks: `model/<slug>`, a slug from the runtime’s model catalog (`frontera local models-available`); a model the runtime lacks is swapped for its default, and `local dev` says so' },
+  action: { kinds: ['action'], words: 'the governed Action it runs: `action/<apiName>`' },
+  agent: { kinds: ['agent'], words: 'the Agent it asks: `agent/<slug>`' },
+  plugin: { kinds: ['plugin'], words: 'the Plugin it calls: `plugin/<name>`' },
+}
+
+/** A uuid field elsewhere, by its key. */
+const KEY_REFS: Record<string, RefKind[]> = {
+  objectTypeId: ['objectType'],
+  objectSetId: ['objectSet'],
+  functionId: ['function'],
+  workflowId: ['workflow'],
+  agentId: ['agent'],
+  actionId: ['action'],
+  knowledgeBaseId: ['knowledge'],
+  skillId: ['skill'],
+}
+
+const isRecord = (v: unknown): v is Record<string, unknown> => !!v && typeof v === 'object' && !Array.isArray(v)
+
+/** A uuid field that also takes the project's reference to one of these kinds. */
+function refOrId(node: Record<string, unknown>, kinds: readonly RefKind[], words?: string): Record<string, unknown> {
+  const { description, ...id } = node
+  const said = words ?? `${kinds.length === REF_KINDS.length ? 'a resource' : kinds.map((k) => `\`${k}/<name>\``).join(' or ')}`
+  return {
+    description: `${typeof description === 'string' ? `${description} ` : ''}In a project file: ${said}, which \`frontera local dev\` resolves to this runtime's id; or the id itself.`,
+    anyOf: [{ type: 'string', pattern: refPattern(kinds) }, id],
+    'x-frontera-reference': [...kinds],
+  }
+}
+
+/** A property's schema with a description added (or replaced), and optionally more of its shape. */
+function describe(props: Record<string, unknown>, key: string, description: string, extra: Record<string, unknown> = {}): void {
+  const node = props[key]
+  if (!isRecord(node)) return
+  props[key] = { ...node, ...extra, description }
+}
+
+/**
+ * agent.json `config.features.computerAvailability`, as the service reads it
+ * (`AGENT_COMPUTER_AVAILABILITY` and `resolveComputerRuntimePolicy` in
+ * `computer-runtime-policy.ts`): the service's schema keeps `features` an open
+ * map, so the key the CLI's own fix names is said here.
+ */
+const COMPUTER_AVAILABILITY = {
+  type: 'string',
+  enum: ['none', 'on-demand', 'eager'],
+  description:
+    'The Agent’s Computer availability (the Agent’s Advanced page, Computer): `none` gives it no computer (no shell, files or artifacts; an attachment goes to the model directly); `on-demand` starts one the first time a turn needs it (a tool, an attachment to put on it, its memory); `eager` keeps one ready before every turn. When absent, an Agent with behavior set up (agents/<slug>/operating.json) has none and any other Agent has `eager`; a value not listed counts as `none`. An Agent with behavior is offered its Plugins (agent.json `plugins`) only with `on-demand` or `eager`. A runtime with no computers to start (most local runtimes) runs the Agent without one whatever this says, and `frontera local status` says so; the setting still applies where the Agent is published.',
+}
+
+/**
+ * What the service's schemas leave unsaid about a project file, said where an
+ * editor and a coding agent read it: the forms a procedure's tool list takes,
+ * how an Agent names its knowledge, and which agent.json lists do not hold
+ * what an Agent may start or read (that is bindings.json). Recognized by the
+ * properties around them, so it holds for any release that has them.
+ * Idempotent.
+ */
+function describeProjectFields(props: Record<string, unknown>): void {
+  // A procedure (operating.json `procedures[]`): its own tools and knowledge.
+  if ('tools' in props && 'knowledge' in props && 'actions' in props) {
+    const tools = props.tools
+    if (isRecord(tools) && isRecord(tools.properties)) {
+      const inner = { ...tools.properties }
+      describe(inner, 'ids', `With \`inherit: false\`, the only tools the procedure keeps, each one of: ${PROCEDURE_TOOL_FORMS}. \`frontera local dev\` resolves a slug to this runtime's id, refuses another form, and warns about a Function or workflow the Agent is not bound to.`, {
+        items: { type: 'string', minLength: 1, maxLength: 64, pattern: `^(function:[A-Za-z0-9][A-Za-z0-9._-]*|workflow:[A-Za-z0-9][A-Za-z0-9._-]*|tool:(${PROCEDURE_TOOL_GROUPS.join('|')}))$` },
+      })
+      props.tools = { ...tools, properties: inner, description: 'The tools while the procedure is active: the Agent’s own (`inherit: true`, the default), or only those in `ids`.' }
+    }
+    const knowledge = props.knowledge
+    if (isRecord(knowledge) && isRecord(knowledge.properties)) {
+      const inner = { ...knowledge.properties }
+      describe(inner, 'ids', 'With `inherit: false`, the only knowledge bases the procedure searches: `knowledge/<name>` each, attached to the Agent in agent.json `knowledgeAttachments`.')
+      props.knowledge = { ...knowledge, properties: inner }
+    }
+  }
+  // How an Agent runs (operating.json `execution`): whether it has the governed Action tools.
+  if ('harness' in props && 'toolScopes' in props) {
+    describe(props, 'toolScopes', 'Optional; 2 when present. With it, `tool:blueprint` is the Blueprint query tools only, the governed Action tools need `tool:blueprint-actions`, and `blueprintActions` decides whether the Agent has them outside a procedure that lists its own tools. Without it the file is read as before Actions were their own choice: `tool:blueprint` keeps the Action tools, and a service Agent has them outside procedures. New Agents are scaffolded with it; `frontera local dev` warns about a file without it.', { const: 2 })
+  }
+  if ('harness' in props && 'blueprintActions' in props) {
+    describe(props, 'blueprintActions', 'With `toolScopes: 2`: whether the Agent has the governed Action tools (list Actions, submit one, read a request) outside a procedure that lists its own tools: on when absent for an open-ended Agent, off for a service (customer-facing) one. A procedure that keeps its own tools offers them only with `tool:blueprint-actions` in `tools.ids`. `tool:blueprint` is the query tools alone. Either needs an object type granted in bindings.json.')
+  }
+  // Behavior settings (operating.json): which records a conversation reads.
+  if ('dataScopes' in props && 'variables' in props) {
+    describe(props, 'dataScopes', 'Optional. Narrows what the Agent reads of an object type to the records of the conversation: `[{ "objectType": "WorkOrder", "property": "customerId", "equals": "{{customer_id}}" }]`, at most one per object type. Every read of that type (query, fetch, aggregate, saved sets, links, media and metrics) sees only rows whose property equals the conversation variable; a conversation without the variable sees none. The variable is one in `variables`, and the property and variable are text or numbers. The object type must be granted in bindings.json `blueprint`. In an eval case, `variables` gives the conversation its values.')
+  }
+  // An Agent (agent.json): the lists that name other resources.
+  if ('modelConfigs' in props && 'knowledgeAttachments' in props) {
+    describe(props, 'knowledgeAttachments', 'The knowledge bases the Agent searches: `[{ "knowledgeConfigId": "knowledge/<name>" }]`, one per base in knowledge/<name>/knowledge.json (`retrievalOverride` optional). `local dev` resolves each to this runtime’s id. When the key is present it is the Agent’s whole list (a base it leaves out is detached); leave the key out to keep the attachments made with `frontera knowledge attach`.', {
+      items: {
+        type: 'object',
+        properties: {
+          knowledgeConfigId: { type: 'string', description: '`knowledge/<name>`: the base’s name as knowledge/<name>/knowledge.json gives it (words allowed), or its id.' },
+          retrievalOverride: { description: 'How this Agent retrieves from the base, when not the base’s own setting.' },
+        },
+        required: ['knowledgeConfigId'],
+      },
+    })
+    describe(props, 'objectBindings', 'Object definitions (the workspace’s objects, not Blueprint object types) the Agent reads and writes through its object tools: each row `objectDefinitionId: object/<slug>` with its `definition` (name, fields). The Blueprint object types it may query are granted in agents/<slug>/bindings.json `blueprint`, not here.')
+    describe(props, 'functions', 'Not applied: these rows are no longer run. The Functions and workflows the Agent may start are its bindings, in agents/<slug>/bindings.json (`frontera local schema bindings`).')
+    // `config.features`: the Agent's own Computer availability, kept beside the on/off switches (the service's `computer-runtime-policy.ts`).
+    const config = props.config
+    const features = isRecord(config) && isRecord(config.properties) ? config.properties.features : undefined
+    if (isRecord(config) && isRecord(config.properties) && isRecord(features) && !(isRecord(features.properties) && 'computerAvailability' in features.properties)) {
+      props.config = {
+        ...config,
+        properties: {
+          ...config.properties,
+          features: {
+            ...features,
+            description: 'On/off switches (`true` or `false` each, such as `autoTitle`), and the Agent’s Computer availability in `computerAvailability`.',
+            properties: { ...(isRecord(features.properties) ? features.properties : {}), computerAvailability: COMPUTER_AVAILABILITY },
+          },
+        },
+      }
+    }
+    // A project file's form of `appCapabilities`: capability ids belong to one install, so a pull names each by Plugin and tool.
+    if ('appCapabilities' in props && !('pluginTools' in props)) {
+      props.pluginTools = {
+        type: 'array',
+        description: 'The Agent’s own settings for its Plugins’ tools, by Plugin and tool name: each row gives the Agent a tool its Plugin marks sensitive, or sets whether a call to it needs approval. A pull writes it from the platform’s `appCapabilities`, whose capability ids belong to one install. `frontera local dev` turns each row into this runtime’s capability; a row whose Plugin the runtime doesn’t have is left off, and a tool the Plugin doesn’t list here is left off with a warning. When present it replaces `appCapabilities`. The Plugin itself is attached in `appInstalls`.',
+        items: {
+          type: 'object',
+          properties: {
+            plugin: { type: 'string', pattern: '^plugin/.+', description: '`plugin/<name>`: the Plugin, by the name its file in mcp/ gives it (mcp/<name>.plugin.json, or a stand-in, mcp/<name>.stand-in.json).' },
+            tool: { type: 'string', description: 'The tool’s name, as the Plugin lists it.' },
+            accountMode: { type: 'string', enum: ['agent_owned', 'end_user'], description: 'Whose connection the tool uses: the Agent’s own (`agent_owned`, the default) or the person in the conversation’s (`end_user`).' },
+            requiresApprovalOverride: { type: ['boolean', 'null'], description: 'Whether a call needs approval, in place of the Plugin’s own setting; leave it out to keep that setting.' },
+          },
+          required: ['plugin', 'tool'],
+        },
+      }
+    }
+  }
+}
+
+/**
+ * A service schema as a project file may be written: every id field also
+ * takes the reference `local dev` resolves (per step kind for a workflow's
+ * `resourceId`, per key elsewhere, any kind otherwise), and a skill binding's
+ * `workspaceId` is optional, since `local dev` fills in the runtime's own.
+ * Idempotent: a field it already widened is left as it is.
+ */
+export function localizeServiceSchema(schema: JsonSchema): JsonSchema {
+  const visit = (node: unknown, key: string, stepKind: string | null): unknown => {
+    if (Array.isArray(node)) return node.map((n) => visit(n, key, stepKind))
+    if (!isRecord(node)) return node
+    if (node['x-frontera-reference']) return node
+    if (node.format === 'uuid' && (node.type === 'string' || node.type === undefined)) {
+      const step = key === 'resourceId' && stepKind ? STEP_REFS[stepKind] : undefined
+      if (step) return refOrId(node, step.kinds, step.words)
+      return refOrId(node, KEY_REFS[key] ?? REF_KINDS)
+    }
+    const props = isRecord(node.properties) ? node.properties : null
+    const kindConst = props && isRecord(props.kind) && typeof props.kind.const === 'string' ? props.kind.const : null
+    const out: Record<string, unknown> = {}
+    for (const [k, v] of Object.entries(node)) {
+      if (k === 'properties' && props) {
+        out.properties = Object.fromEntries(Object.entries(props).map(([name, child]) => [name, visit(child, name, kindConst ?? stepKind)]))
+        continue
+      }
+      // Keywords that hold schemas of the same value (anyOf, oneOf, items…) keep the key they describe.
+      out[k] = visit(v, k === '$defs' || k === 'definitions' ? '' : ['anyOf', 'oneOf', 'allOf', 'items', 'additionalProperties', 'not', 'prefixItems'].includes(k) ? key : k, k === '$defs' ? null : stepKind)
+    }
+    // A skill binding: the workspace it lives in is this runtime's own, filled in by `local dev`.
+    if (props && 'workspaceId' in props && 'workspaceSkillId' in props && Array.isArray(out.required)) {
+      out.required = (out.required as unknown[]).filter((r) => r !== 'workspaceId')
+      const ws = (out.properties as Record<string, unknown>).workspaceId
+      if (isRecord(ws)) (out.properties as Record<string, unknown>).workspaceId = { ...ws, description: 'Leave it out in a project file: `frontera local dev` fills in the runtime’s workspace.' }
+      const skill = (out.properties as Record<string, unknown>).workspaceSkillId
+      if (isRecord(skill) && !skill.description) (out.properties as Record<string, unknown>).workspaceSkillId = { ...skill, description: 'In a project file: `skill/<slug>`, or the id.' }
+    }
+    if (props) describeProjectFields(out.properties as Record<string, unknown>)
+    return out
+  }
+  return visit(schema, '', null) as JsonSchema
+}
+
 export function schemasDir(project: LocalProject): string {
   return join(project.stateDir, 'schemas')
 }
@@ -268,7 +984,8 @@ export function readKeptSchema(project: LocalProject, kind: SchemaKind): JsonSch
   if (!existsSync(path)) return null
   try {
     const value = JSON.parse(readFileSync(path, 'utf8')) as unknown
-    return value && typeof value === 'object' && !Array.isArray(value) ? (value as JsonSchema) : null
+    // One kept by an earlier CLI, before references were described, is described as it is read.
+    return value && typeof value === 'object' && !Array.isArray(value) ? (cliSchema(kind) ? (value as JsonSchema) : localizeServiceSchema(value as JsonSchema)) : null
   } catch {
     return null
   }
@@ -287,7 +1004,7 @@ export async function keepSchemas(project: LocalProject, source: SchemaSource):
       let schema = cliSchema(kind)
       if (!schema) {
         const fetched = await fetchServiceSchema(source, kind)
-        if (fetched.ok) schema = fetched.schema
+        if (fetched.ok) schema = localizeServiceSchema(fetched.schema)
         else problems.push(`${kind}: ${fetched.reason}`)
       }
       if (schema) writeFileAtomic(schemaPath(project, kind), `${JSON.stringify(schema, null, 2)}\n`, 0o644)
@@ -320,7 +1037,7 @@ export async function resolveSchema(project: LocalProject, kind: SchemaKind, sou
     }
   }
   const fetched = await fetchServiceSchema(source, kind)
-  if (fetched.ok) return { ok: true, schema: fetched.schema, from: 'runtime' }
+  if (fetched.ok) return { ok: true, schema: localizeServiceSchema(fetched.schema), from: 'runtime' }
   if (kept) return { ok: true, schema: kept, from: 'kept', note: `The local runtime did not answer (${fetched.reason}): this is the format its last start kept.` }
   return {
     ok: false,