@meistrari/tela-skills 1.4.0 → 1.6.0

package/README.md

@@ -42,27 +42,33 @@ The CLI (`cli.ts`) is an interactive installer that sets up Tela Skills for Clau
 
 ### What it does
 
-1. **Environment selection** — Choose between Production (`api.tela.com`) or Staging (`staging.api.tela.com`).
+1. **Environment selection** — Choose between Production (`api.tela.com`), Staging (`api.telastaging.com`), or Localhost (Docker-based local development).
 2. **Skill installation** — Copies skill source files from `skill/` to `~/.claude/skills/tela/`.
 3. **Agent deployment** — Copies agent definitions from `agents/` to `~/.claude/agents/` (if available).
 4. **Dependency installation** — Installs `@meistrari/vault-sdk` into the skills directory via Bun.
-5. **Authentication** — Browser auth via a local callback after redirecting to the Tela backoffice.
-6. **Session persistence** — Saves credentials to `~/.tela/session.production` or `~/.tela/session.staging` and environment config to `~/.tela/environment` and `~/.tela/.env`.
+5. **Authentication** — Browser auth for Production/Staging; Docker discovery + JWT generation for Localhost.
+6. **Session persistence** — Saves credentials to `~/.tela/session.production`, `~/.tela/session.staging`, or `~/.tela/session.local` and environment config to `~/.tela/environment` and `~/.tela/.env`.
 
 ### Usage
 
 ```bash
-# Install and configure
+# Install and configure (interactive)
 bunx @meistrari/tela-skills
 
+# Non-interactive localhost setup
+bunx @meistrari/tela-skills --env localhost --repos-path /path/to/tela --workspace <slug-or-id> --yes
+
 # Test locally during development
 bun run cli.ts
 
 # Verify skill loads correctly
 bun --preload skill/preload.ts -e "console.log(Object.keys(tela))"
 
-# Localhost (API :4000, App :3000)
+# Run commands against localhost
 bun localhost.ts "console.log(await tela.listProjects())"
+
+# List available localhost workspaces
+bun list-workspaces.ts
 ```
 
 ### File layout after installation
@@ -75,10 +81,22 @@ bun localhost.ts "console.log(await tela.listProjects())"
 ~/.tela/
   session.production  # API token (production)
   session.staging     # API token (staging)
-  environment         # "production" or "staging"
+  session.local       # JWT token (localhost, 30-day expiry)
+  environment         # "production", "staging", or "localhost"
   .env                # TELA_API_URL, TELA_APP_URL
+  tela-repo-path      # Path to tela monorepo (localhost only, for key discovery)
 ```
 
+### Localhost environment
+
+For internal development against locally running Tela services:
+
+1. Start Docker services in the tela monorepo (`make dev`)
+2. Run `bunx @meistrari/tela-skills` and select "Localhost"
+3. The CLI discovers Docker ports, reads `AUTH_API_SECRET` from `packages/api/.env`, loads auth settings from `.repositories/auth-api/.env`, fetches workspaces, and generates a JWT through the local auth-api JWKS signing flow
+
+The localhost JWT has a 30-day expiry and is auto-regenerated when expired. Workspace selection is required during setup — use `bun list-workspaces.ts` to see available workspaces.
+
 ---
 
 ## Skills
@@ -100,14 +118,14 @@ bun --preload ~/.claude/skills/tela/preload.ts -e "
 
 **File:** `skill/canvas.ts`
 
-Canvas is Tela's core concept — a versioned AI prompt with messages, variables, configuration, and optional structured output.
+Canvas is Tela's core concept — a versioned AI prompt with a message, variables, configuration, and optional structured output.
 
 #### Types
 
 | Type | Description |
 |------|-------------|
 | `Canvas` | Top-level prompt object with metadata |
-| `CanvasVersion` | Versioned snapshot: messages, variables, config |
+| `CanvasVersion` | Versioned snapshot: message, variables, config |
 | `Variable` | Input/output definition (text, file, or mixed) |
 | `StructuredOutput` | JSON schema for enforcing response format |
 | `CanvasMessage` | Chat message (system, user, assistant, function) |
@@ -122,7 +140,7 @@ tela.createCanvas({
   title: "My Prompt",
   projectId: "proj-uuid",
   version: {
-    messages: [tela.createMessage("system", "You are a helpful assistant.")],
+    message: tela.createMessage("system", "You are a helpful assistant."),
     variables: [tela.createVariable("input", "text", { variableType: "input" })],
     configuration: { model: "gpt-5", temperature: 0 }
   }
@@ -294,7 +312,7 @@ Upload, download, and manage files using immutable `vault://` references.
 
 | Function | Description |
 |----------|-------------|
-| `loadApiKey()` | Reads token from `~/.tela/session.production` or `~/.tela/session.staging` |
+| `loadApiKey()` | Reads token from `~/.tela/session.production`, `~/.tela/session.staging`, or `~/.tela/session.local` |
 | `getApiBaseUrl()` | Returns API URL from globals or defaults |
 | `getAppBaseUrl()` | Returns app URL for constructing viewer links |
 | `apiRequest<T>(method, path, body?)` | Generic HTTP client with Bearer auth |
@@ -375,7 +393,8 @@ Runtime:
        ├─→ prompts.ts     (list/get prompt metadata)
        ├─→ test-cases.ts  (create/run/manage evaluations)
        ├─→ tasks.ts       (human-in-the-loop validation)
-       └─→ vault.ts       (file upload/download/manage)
+       ├─→ vault.ts       (file upload/download/manage)
+       └─→ localhost-utils.ts (Docker discovery, JWT signing, workspace fetching)
 ```
 
 ---
@@ -388,7 +407,7 @@ Every message and variable has both **markdown** and **HTML** representations. T
 
 ### Vault references
 
-All files are referenced by immutable `vault://UUID` identifiers — never local paths. Upload files to Vault first, then use the returned reference in canvas messages, test cases, or task inputs.
+All files are referenced by immutable `vault://UUID` identifiers — never local paths. Upload files to Vault first, then use the returned reference in a canvas message, test cases, or task inputs.
 
 ### Smart merging
 

package/cli.ts

@@ -7,10 +7,9 @@ import { fileURLToPath } from 'node:url'
 import open from 'open'
 import {
     discoverLocalhostServices,
-    parseApiGatewayKeys,
     readAuthApiSecret,
-    signLocalhostJwt,
     fetchWorkspaces,
+    generateLocalhostJwt,
     saveLocalhostSession,
     writeLocalhostEnv,
     readSavedReposPath,
@@ -23,7 +22,7 @@ const OPEN_ISSUE_SKILLS_DIR = join(homedir(), '.claude', 'skills', 'tela-open-is
 const LOCALHOST_SKILLS_DIR = join(homedir(), '.claude', 'skills', 'tela-localhost')
 const SESSION_DIR = join(homedir(), '.tela')
 const BACKOFFICE_URL = 'https://backoffice.tela.com'
-const STAGING_BACKOFFICE_URL = 'https://staging-backoffice.tela.com'
+const STAGING_BACKOFFICE_URL = 'https://backoffice.telastaging.com'
 
 // --- CLI Flag Parsing ---
 function parseFlags(argv: string[]): Record<string, string | true> {
@@ -126,8 +125,13 @@ async function handleLocalhostSetup() {
         p.log.error('Could not find tela-api Docker container. Make sure local services are running.')
         process.exit(1)
     }
+    if (!services.authApiDbPort) {
+        discoverSpinner.stop('auth-postgres container not found')
+        p.log.error('Could not find auth-postgres Docker container. Make sure local auth services are running.')
+        process.exit(1)
+    }
 
-    discoverSpinner.stop(`Found services — auth-api :${services.authApiPort}, tela-api :${services.telaApiPort}${services.telaAppPort ? `, tela-app :${services.telaAppPort}` : ''}`)
+    discoverSpinner.stop(`Found services — auth-api :${services.authApiPort}, auth-postgres :${services.authApiDbPort}, tela-api :${services.telaApiPort}${services.telaAppPort ? `, tela-app :${services.telaAppPort}` : ''}`)
 
     // 2. Ask for meistrari repos path
     const savedPath = readSavedReposPath()
@@ -161,18 +165,16 @@ async function handleLocalhostSetup() {
     const resolvedPath = reposPath.replace(/^~/, homedir())
     saveReposPath(resolvedPath)
 
-    // 3. Read RSA keys and auth secret
+    // 3. Read auth-api access secret
     const keysSpinner = p.spinner()
-    keysSpinner.start('Reading RSA keys from api-gateway...')
+    keysSpinner.start('Reading auth-api configuration...')
 
-    let keys: ReturnType<typeof parseApiGatewayKeys>
     let authApiSecret: string
     try {
-        keys = parseApiGatewayKeys(resolvedPath)
         authApiSecret = readAuthApiSecret(resolvedPath)
-        keysSpinner.stop('RSA keys loaded')
+        keysSpinner.stop('Auth-api configuration loaded')
     } catch (err) {
-        keysSpinner.stop('Failed to read keys')
+        keysSpinner.stop('Failed to read auth-api configuration')
         p.log.error(err instanceof Error ? err.message : String(err))
         process.exit(1)
     }
@@ -234,16 +236,22 @@ async function handleLocalhostSetup() {
     const tokenSpinner = p.spinner()
     tokenSpinner.start('Generating authentication token...')
 
-    const token = signLocalhostJwt({
-        workspace: { id: workspace.id, title: workspace.title },
-        privateKey: keys.privateKey,
-        kid: keys.kid,
-    })
+    try {
+        const token = generateLocalhostJwt({
+            reposPath: resolvedPath,
+            workspace: { id: workspace.id, title: workspace.title },
+            authApiDbPort: services.authApiDbPort,
+        })
 
-    saveLocalhostSession(token)
-    writeLocalhostEnv(services.telaApiPort, services.telaAppPort)
+        saveLocalhostSession(token)
+        writeLocalhostEnv(services.telaApiPort, services.telaAppPort)
 
-    tokenSpinner.stop('Token generated and saved')
+        tokenSpinner.stop('Token generated and saved')
+    } catch (err) {
+        tokenSpinner.stop('Failed to generate token')
+        p.log.error(err instanceof Error ? err.message : String(err))
+        process.exit(1)
+    }
 
     // 7. Install skills (reuse existing logic)
     if (YES) {
@@ -474,8 +482,8 @@ async function main() {
 
     const ENV_PATH = join(SESSION_DIR, '.env')
     const isStaging = env === 'staging'
-    const apiUrl = isStaging ? 'https://staging.api.tela.com' : 'https://api.tela.com'
-    const appUrl = isStaging ? 'https://staging.tela.com' : 'https://app.tela.com'
+    const apiUrl = isStaging ? 'https://api.telastaging.com' : 'https://api.tela.com'
+    const appUrl = isStaging ? 'https://app.telastaging.com' : 'https://app.tela.com'
 
     mkdirSync(SESSION_DIR, { recursive: true })
     writeFileSync(ENV_PATH, `TELA_API_URL=${apiUrl}\nTELA_APP_URL=${appUrl}\n`, { mode: 0o600 })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meistrari/tela-skills",
-  "version": "1.4.0",
+  "version": "1.6.0",
   "description": "Tela API skills for Claude Code",
   "type": "module",
   "bin": {

package/skill/TELA_LOCALHOST_SKILL.md

@@ -9,7 +9,7 @@ Manage your local Tela development environment. Switch between workspaces, check
 
 ## Prerequisites
 
-- Docker running with tela services (auth-api, tela-api)
+- Docker running with tela services (auth-api, auth-postgres, tela-api)
 - Localhost environment configured via `bunx @meistrari/tela-skills` (select "Localhost")
 - Tela monorepo path saved at `~/.tela/tela-repo-path`
 
@@ -31,7 +31,7 @@ bun list-workspaces.ts
 
 ### Switch Workspace
 
-Switch to a different workspace by generating a new JWT token.
+Switch to a different workspace by generating a new JWT token through the local auth-api signing flow.
 
 Replace `WORKSPACE_ID` and `WORKSPACE_TITLE` with the target workspace values from "List Workspaces".
 
@@ -42,12 +42,13 @@ const { homedir } = await import('node:os')
 const lu = await import(join(homedir(), '.claude', 'skills', 'tela', 'localhost-utils.ts'))
 const reposPath = lu.readSavedReposPath()
 if (!reposPath) { console.error('No tela repo path saved. Run CLI setup first.'); process.exit(1) }
+const services = lu.discoverLocalhostServices()
+if (!services.authApiDbPort) { console.error('auth-postgres Docker container not found.'); process.exit(1) }
 
-const keys = lu.parseApiGatewayKeys(reposPath)
-const token = lu.signLocalhostJwt({
+const token = lu.generateLocalhostJwt({
+    reposPath,
     workspace: { id: 'WORKSPACE_ID', title: 'WORKSPACE_TITLE' },
-    privateKey: keys.privateKey,
-    kid: keys.kid,
+    authApiDbPort: services.authApiDbPort,
 })
 lu.saveLocalhostSession(token)
 console.log('Switched to workspace: WORKSPACE_TITLE')
@@ -101,6 +102,7 @@ try {
 ## Troubleshooting
 
 - **"auth-api not running"**: Start Docker services in the tela monorepo (`make dev`)
+- **"auth-postgres not running"**: Make sure the local auth database container is up and exposes its host port
 - **"No tela repo path saved"**: Run `bunx @meistrari/tela-skills` and select Localhost to configure
 - **"Connection: FAILED"**: Check that tela-api Docker container is running (`docker ps | grep tela-api`)
 - **Token expired**: Tokens are auto-regenerated when expired. If auto-regeneration fails, use "Switch Workspace" to regenerate manually

package/skill/TELA_SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: tela
-description: Skills for interacting with Tela - view, create, and update prompts/canvas. Upload and download files via Vault (vault:// references). Use this skill when user shares a Tela URL (app.tela.com or staging.tela.com) or asks about canvas/prompts. Do NOT use WebFetch for Tela URLs.
+description: Skills for interacting with Tela - view, create, and update prompts/canvas. Upload and download files via Vault (vault:// references). Use this skill when user shares a Tela URL (app.tela.com or app.telastaging.com) or asks about canvas/prompts. Do NOT use WebFetch for Tela URLs.
 ---
 
 # Tela API Skills
@@ -9,7 +9,7 @@ Skills for interacting with the Tela API. Note: Prompts are called "Canvas" in T
 
 **IMPORTANT**: When the user shares a Tela URL like `https://app.tela.com/prompt/{id}/craft`, use these skills to fetch and modify the canvas - do NOT use WebFetch.
 
-**Workflows**: For workflow authoring and execution, use the `workflow.md` skill which provides version-safe orchestration (v2/v3), graph validation, and bundled reference docs.
+**Workflows**: For workflow authoring and execution, use the `workflow.md` skill. Current graph authoring is the only supported path.
 
 ## Installation
 
@@ -19,7 +19,13 @@ bunx @meistrari/tela-skills
 
 ## Authentication
 
-The API uses Bearer token authentication. The token is stored at `~/.tela/session.production` or `~/.tela/session.staging`, depending on the configured environment.
+The API uses token authentication via the `x-data-token` header. The token is stored at:
+
+- `~/.tela/session.production` — Production environment
+- `~/.tela/session.staging` — Staging environment
+- `~/.tela/session.local` — Localhost environment (JWT, 30-day expiry, auto-regenerated when expired)
+
+The active environment is determined by the `TELA_API_URL` in `~/.tela/.env`. When the URL contains `localhost`, the localhost session is used automatically. All session files are created with `0o600` permissions (user read/write only).
 
 ## Using These Skills
 
@@ -50,10 +56,8 @@ bun --preload ~/.claude/skills/tela/preload.ts -e "console.log(await tela.listPr
 
 ### Workflow Operations
 
-- `tela.createWorkflowVersionV2(payload)` - Create workflow prompt-version in v2 compatibility mode
-- `tela.createWorkflowVersionV3(payload)` - Create workflow prompt-version in v3 compatibility mode
-- `tela.updateWorkflowVersionV2(versionId, payload)` - Update workflow prompt-version in v2 compatibility mode
-- `tela.updateWorkflowVersionV3(versionId, payload)` - Update workflow prompt-version in v3 compatibility mode
+- `tela.createWorkflowVersion(payload)` - Create workflow prompt-version with graph validation
+- `tela.updateWorkflowVersion(versionId, payload)` - Update workflow prompt-version with graph validation
 - `tela.runWorkflow(payload)` - Run workflow via `/workflow/test`
 - `tela.getWorkflowRun(runId)` - Get workflow run by ID
 - `tela.waitForWorkflowRun(runId, options?)` - Poll until terminal status
@@ -61,10 +65,14 @@ bun --preload ~/.claude/skills/tela/preload.ts -e "console.log(await tela.listPr
 - `tela.listWorkflowRuns(options)` - List workflow runs by prompt
 - `tela.getWorkflowVariables(promptId, payload?)` - Get available variables for graph/input context
 - `tela.getWorkflowVariablesByStep(promptId, stepId, payload?)` - Get step-targeted compatibility variables
-- `tela.validateWorkflowGraph(graph, { version })` - Validate graph/ports/references by version
-- `tela.assertWorkflowGraphValid(graph, { version })` - Throw on validation errors
-- `tela.getWorkflowV2Url(promptId)` - Get legacy UI URL (`/prompt/:id/workflow`)
-- `tela.getWorkflowV3Url(promptId)` - Get DAG UI URL (`/workflows/:id`)
+- `tela.validateWorkflowGraph(graph)` - Local pre-save graph shape checks (synchronous)
+- `tela.assertWorkflowGraphValid(graph, { version })` - Throw on local validation errors
+- `tela.validateWorkflowGraphServer(promptId, graph)` - Server-side validation with full inference (compatibility, condition branch visibility) — requires the prompt to exist
+- `tela.getWorkflowActions()` - Catalog of all workflow actions with config/output schemas, reference field metadata, and public methods
+- `tela.getWorkflowDependencies(promptId, versionId)` - All variables visible across a saved workflow version, with schemas
+- `tela.getStepDependencies(promptId, versionId, stepId)` - Variables visible at a specific step, including per-reference-field format compatibility — use this instead of guessing what `?format=` values an action supports
+- `tela.getStepTypes(promptId, versionId, stepId)` - TypeScript declarations (`.d.ts`) for the `TelaInput` shape inside a `codeExecutionNode` — use to author `input["..."]` accesses with confidence
+- `tela.getWorkflowUrl(promptId)` - Get workflow UI URL (`/workflows/:id`)
 
 ### Export
 
@@ -153,9 +161,7 @@ const canvas = await tela.createCanvas({
         keyPoints: { type: 'array', items: { type: 'string' } }
       })
     },
-    messages: [
-      tela.createMessage('system', '## Task\n\nAnalyze the document.\n\n## Input\n\n{document}', 0)
-    ],
+    message: tela.createMessage('system', '## Task\n\nAnalyze the document.\n\n## Input\n\n{document}', 0),
     variables: [tela.createVariable('document', 'file', { allowMultimodal: true })]
   }
 })
@@ -283,29 +289,51 @@ Referenced in content as `{variableName}` (single braces)
 }
 ```
 
-### Messages
+### Message
 ```typescript
 { role: 'system' | 'user' | 'assistant', content: 'Message content', index: 0 }
 ```
 
 ## Environment Variables
 
-- `TELA_API_URL` - Override the API base URL (default: `https://api.tela.com` or `https://staging.api.tela.com` for staging)
-- `TELA_APP_URL` - Override the app base URL (default: `https://app.tela.com` or `https://staging.tela.com` for staging)
+Configured automatically by the CLI installer in `~/.tela/.env`:
+
+- `TELA_API_URL` - API base URL (production: `https://api.tela.com`, staging: `https://api.telastaging.com`, localhost: `http://localhost:<port>`)
+- `TELA_APP_URL` - App base URL (production: `https://app.tela.com`, staging: `https://app.telastaging.com`, localhost: `http://localhost:<port>`)
+
+For localhost, ports are auto-discovered from Docker containers (`auth-api`, `tela-api`, `tela-app`). If `tela-app` is not running, `TELA_APP_URL` defaults to `http://localhost:3000`.
+
+## Localhost Environment
+
+For developing against locally running Tela services, use the localhost environment:
+
+```bash
+bunx @meistrari/tela-skills    # Select "Localhost" during setup
+```
+
+Prerequisites: Docker running with tela services (`auth-api`, `auth-postgres`, `tela-api`), with auth settings available in `.repositories/auth-api/.env` and `AUTH_API_SECRET` in `packages/api/.env`. The CLI discovers ports, reads the local auth configuration, and generates a JWT token through the auth-api JWKS signing flow.
+
+For workspace management after setup, see the `tela-localhost` skill (switch workspaces, check status, regenerate tokens).
+
+Run commands against localhost with the helper script:
+```bash
+bun localhost.ts "console.log(await tela.listProjects())"
+```
 
 ## File Structure
 
 ```
 ~/.claude/skills/tela/
-├── SKILL.md          # This file
-├── preload.ts        # Preload script - makes `tela` globally available
-├── index.ts          # Barrel export
-├── common.ts         # Shared utilities (loadApiKey, apiRequest)
-├── projects.ts       # Project functions
-├── prompts.ts        # Prompt/Canvas list functions
-├── canvas.ts         # Canvas create/update functions
-├── workflows.ts      # Workflow create/update/run/validation functions
-├── test-cases.ts     # Test case functions
-├── tasks.ts          # Task management functions
-└── vault.ts          # Vault file management functions
+├── SKILL.md              # This file
+├── preload.ts            # Preload script - makes `tela` globally available
+├── index.ts              # Barrel export
+├── common.ts             # Shared utilities (loadApiKey, apiRequest, env detection)
+├── projects.ts           # Project functions
+├── prompts.ts            # Prompt/Canvas list functions
+├── canvas.ts             # Canvas create/update functions
+├── workflows.ts          # Workflow create/update/run/validation functions
+├── test-cases.ts         # Test case functions
+├── tasks.ts              # Task management functions
+├── vault.ts              # Vault file management functions
+└── localhost-utils.ts    # Docker discovery, JWT signing, workspace fetching (internal, not on tela global)
 ```

package/skill/canvas.test.ts

@@ -0,0 +1,149 @@
+import { beforeEach, describe, expect, mock, test } from 'bun:test'
+
+const apiRequest = mock(async (_endpoint: string, _options?: RequestInit): Promise<unknown> => ({ id: 'canvas-id' }))
+
+void mock.module('./common.ts', () => ({
+    apiRequest,
+}))
+
+describe('canvas', () => {
+    const legacyMessagesError = 'Use message instead of messages (pass a single CanvasMessage object, not an array)'
+
+    beforeEach(() => {
+        apiRequest.mockClear()
+    })
+
+    test('creates canvases with the canvas layout version', async () => {
+        const { createCanvas } = await import('./canvas.ts')
+
+        await createCanvas({
+            title: 'Canvas',
+            projectId: 'project-id',
+            workspaceId: 'workspace-id',
+            version: {
+                title: 'v1',
+                configuration: { model: 'gpt-5', type: 'chat' },
+            },
+        })
+
+        const [, options] = apiRequest.mock.calls[0]!
+        const body = JSON.parse(String(options?.body))
+
+        expect(body.layoutVersion).toBe('v1')
+        expect(body.version.isWorkflow).toBe(false)
+    })
+
+    test('rejects legacy message arrays when creating a canvas', async () => {
+        const { createCanvas } = await import('./canvas.ts')
+
+        const create = createCanvas({
+            title: 'Canvas',
+            projectId: 'project-id',
+            workspaceId: 'workspace-id',
+            version: {
+                title: 'v1',
+                configuration: { model: 'gpt-5', type: 'chat' },
+                // @ts-expect-error Legacy JavaScript callers can still send this field at runtime.
+                messages: [{ role: 'system', content: 'Legacy', index: 0 }],
+            },
+        })
+
+        let error: Error | undefined
+        try {
+            await create
+        }
+        catch (caught) {
+            error = caught as Error
+        }
+
+        expect(error?.message).toContain(legacyMessagesError)
+        expect(apiRequest).not.toHaveBeenCalled()
+    })
+
+    test('rejects legacy message arrays when updating a canvas version', async () => {
+        const { updateCanvasVersion } = await import('./canvas.ts')
+
+        const update = updateCanvasVersion('version-id', {
+            title: 'v2',
+            // @ts-expect-error Legacy JavaScript callers can still send this field at runtime.
+            messages: [{ role: 'system', content: 'Legacy', index: 0 }],
+        })
+
+        let error: Error | undefined
+        try {
+            await update
+        }
+        catch (caught) {
+            error = caught as Error
+        }
+
+        expect(error?.message).toContain(legacyMessagesError)
+        expect(apiRequest).not.toHaveBeenCalled()
+    })
+
+    test('rejects legacy message arrays when creating a canvas version', async () => {
+        const { createCanvasVersion } = await import('./canvas.ts')
+
+        const create = createCanvasVersion('canvas-id', {
+            title: 'v2',
+            configuration: { model: 'gpt-5', type: 'chat' },
+            // @ts-expect-error Legacy JavaScript callers can still send this field at runtime.
+            messages: [{ role: 'system', content: 'Legacy', index: 0 }],
+        })
+
+        let error: Error | undefined
+        try {
+            await create
+        }
+        catch (caught) {
+            error = caught as Error
+        }
+
+        expect(error?.message).toContain(legacyMessagesError)
+        expect(apiRequest).not.toHaveBeenCalled()
+    })
+
+    test('preserves the current message when updating a canvas', async () => {
+        const { updateCanvas } = await import('./canvas.ts')
+
+        apiRequest.mockImplementation(async (endpoint: string) => {
+            if (endpoint === '/prompt/canvas-id') {
+                return { id: 'canvas-id', title: 'Canvas' }
+            }
+
+            if (endpoint === '/prompt-version?promptId=canvas-id') {
+                return [
+                    {
+                        id: 'version-id',
+                        promptId: 'canvas-id',
+                        title: 'v1',
+                        content: null,
+                        markdownContent: null,
+                        configuration: { model: 'gpt-5', type: 'chat' },
+                        variables: [],
+                        promoted: false,
+                        draft: false,
+                        isWorkflow: false,
+                        workspaceId: 'workspace-id',
+                        createdBy: 'user-id',
+                        updatedBy: 'user-id',
+                        createdAt: '2026-06-22T10:00:00.000Z',
+                        updatedAt: '2026-06-22T10:00:00.000Z',
+                        deletedAt: null,
+                        message: { role: 'system', content: 'Current', markdownContent: 'Current', index: 0 },
+                    },
+                ]
+            }
+
+            return { id: 'new-version-id' }
+        })
+
+        await updateCanvas('canvas-id', { title: 'v2' })
+
+        const [, options] = apiRequest.mock.calls[2]!
+        const body = JSON.parse(String(options?.body))
+
+        expect(body.message).toEqual({ role: 'system', content: 'Current', markdownContent: 'Current', index: 0 })
+        expect('messages' in body).toBe(false)
+    })
+})