@lunnoa/client 2.4.0 → 3.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunnoa/client",
-  "version": "2.4.0",
+  "version": "3.0.0",
   "description": "TypeScript SDK for building applications on top of Lunnoa Automate — typed client for the Public API (agents, workflows, executions, entities, knowledge, queues), SSE agent chat streaming, and deployment-specific codegen",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -24,7 +24,8 @@
   },
   "files": [
     "dist",
-    "skills"
+    "skills",
+    "schemas"
   ],
   "scripts": {
     "build": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\" && tsup",
@@ -34,6 +35,7 @@
     "typecheck": "tsc --noEmit",
     "check:codegen-sample": "node --experimental-strip-types scripts/check-codegen-sample.ts && tsc --noEmit -p scripts/tsconfig.codegen-sample.json",
     "test:acceptance": "tsx scripts/acceptance-soak.ts",
+    "test:sync-acceptance": "tsx scripts/sync-acceptance.ts",
     "prepare": "node -e \"for (const d of ['.cursor/skills', '.claude/skills']) require('fs').cpSync('skills', d, { recursive: true, force: true })\"",
     "prepublishOnly": "pnpm run build",
     "release": "semantic-release"

package/schemas/agent.schema.json

@@ -0,0 +1,128 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://lunnoa.com/schemas/agent.schema.json",
+  "title": "Lunnoa agent definition",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["kind", "slug", "name", "instructions"],
+  "properties": {
+    "$schema": { "type": "string" },
+    "kind": { "const": "agent" },
+    "slug": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" },
+    "name": { "type": "string" },
+    "description": { "type": "string" },
+    "model": { "type": "string" },
+    "aiConnection": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id"],
+      "properties": { "id": { "type": "string" } }
+    },
+    "instructions": {
+      "oneOf": [
+        { "type": "string" },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["file"],
+          "properties": { "file": { "type": "string" } }
+        }
+      ]
+    },
+    "settings": { "$ref": "#/$defs/settings" },
+    "tools": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/tool" }
+    },
+    "workflows": { "type": "array", "items": { "$ref": "#/$defs/slugOrId" } },
+    "agents": { "type": "array", "items": { "$ref": "#/$defs/slugOrId" } },
+    "connections": { "type": "array", "items": { "$ref": "#/$defs/idRef" } },
+    "knowledge": { "type": "array", "items": { "$ref": "#/$defs/idRef" } },
+    "variables": { "type": "array", "items": { "$ref": "#/$defs/idRef" } },
+    "objects": { "type": "array", "items": { "$ref": "#/$defs/idRef" } },
+    "objectTypes": { "type": "array", "items": { "$ref": "#/$defs/idRef" } },
+    "mcpServers": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id"],
+        "properties": {
+          "id": { "type": "string" },
+          "connectionId": { "type": "string" }
+        }
+      }
+    },
+    "a2aAgents": { "type": "array", "items": { "$ref": "#/$defs/idRef" } }
+  },
+  "$defs": {
+    "idRef": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id"],
+      "properties": { "id": { "type": "string" } }
+    },
+    "slugOrId": {
+      "type": "object",
+      "additionalProperties": false,
+      "minProperties": 1,
+      "properties": {
+        "slug": { "type": "string" },
+        "id": { "type": "string" }
+      }
+    },
+    "tool": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["key", "id", "name", "input"],
+      "properties": {
+        "key": { "type": "string" },
+        "id": { "type": "string" },
+        "appId": { "type": "string" },
+        "connection": { "$ref": "#/$defs/idRef" },
+        "name": { "type": "string" },
+        "description": { "type": "string" },
+        "input": { "type": "object" }
+      }
+    },
+    "settings": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "temperature": { "type": "number" },
+        "topP": { "type": "number" },
+        "maxOutputTokens": { "type": ["number", "null"] },
+        "frequencyPenalty": { "type": "number" },
+        "presencePenalty": { "type": "number" },
+        "seed": { "type": ["number", "null"] },
+        "maxRetries": { "type": "number" },
+        "maxToolRoundtrips": { "type": "number" },
+        "messageLookbackLimit": { "type": "number" },
+        "taskNamingInstructions": { "type": ["string", "null"] },
+        "enabledBuiltInTools": { "type": "array", "items": { "type": "string" } },
+        "enabledPlatformTools": { "type": "array", "items": { "type": "string" } },
+        "enabledToolPolicies": { "type": "array", "items": { "type": "string" } },
+        "forcedTools": {},
+        "suggestedPrompts": { "type": "array", "items": { "type": "string" } },
+        "dynamicActionDiscoveryEnabled": { "type": "boolean" },
+        "dynamicMcpDiscoveryEnabled": { "type": "boolean" },
+        "dynamicSelfInstructionsEnabled": { "type": "boolean" },
+        "memoryEnabled": { "type": "boolean" },
+        "memoryScope": { "type": "string" },
+        "memoryRetentionDays": { "type": "number" },
+        "enablePlanning": { "type": "boolean" },
+        "requirePlanApproval": { "type": "boolean" },
+        "enableToolResultOffload": { "type": "boolean" },
+        "toolResultOffloadThresholdBytes": { "type": "number" },
+        "longHorizonMode": { "type": "boolean" },
+        "longHorizonMaxSteps": { "type": ["number", "null"] },
+        "longHorizonMaxTokensPerRun": { "type": ["number", "null"] },
+        "piiRoutingMode": { "type": "string" },
+        "piiFallbackConnectionId": { "type": ["string", "null"] },
+        "piiFallbackModelId": { "type": ["string", "null"] },
+        "webAccess": { "type": ["boolean", "null"] },
+        "phoneAccess": { "type": ["boolean", "null"] }
+      }
+    }
+  }
+}

package/schemas/workflow.schema.json

@@ -0,0 +1,156 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://lunnoa.com/schemas/workflow.schema.json",
+  "title": "Lunnoa workflow definition",
+  "oneOf": [
+    { "$ref": "#/$defs/steps" },
+    { "$ref": "#/$defs/graph" }
+  ],
+  "$defs": {
+    "idRef": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id"],
+      "properties": { "id": { "type": "string" } }
+    },
+    "retrySettings": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["enabled", "maxAttempts", "delaySeconds"],
+      "properties": {
+        "enabled": { "type": "boolean" },
+        "maxAttempts": { "type": "number" },
+        "delaySeconds": { "type": "number" }
+      }
+    },
+    "continueOnFailure": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["enabled"],
+      "properties": { "enabled": { "type": "boolean" } }
+    },
+    "use": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id"],
+      "properties": {
+        "id": { "type": "string" },
+        "appId": { "type": "string" },
+        "connection": { "$ref": "#/$defs/idRef" }
+      }
+    },
+    "step": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["key", "name", "use", "input"],
+      "properties": {
+        "key": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]*$" },
+        "name": { "type": "string" },
+        "description": { "type": "string" },
+        "use": { "$ref": "#/$defs/use" },
+        "input": { "type": "object" },
+        "retrySettings": { "$ref": "#/$defs/retrySettings" },
+        "continueOnFailure": { "$ref": "#/$defs/continueOnFailure" },
+        "paths": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["label", "steps"],
+            "properties": {
+              "label": { "type": "string" },
+              "when": { "type": "array" },
+              "steps": {
+                "type": "array",
+                "items": { "$ref": "#/$defs/step" }
+              }
+            }
+          }
+        }
+      }
+    },
+    "steps": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "format", "slug", "name", "trigger", "steps"],
+      "properties": {
+        "$schema": { "type": "string" },
+        "kind": { "const": "workflow" },
+        "format": { "const": "steps" },
+        "slug": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" },
+        "name": { "type": "string" },
+        "description": { "type": "string" },
+        "trigger": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["id", "name"],
+          "properties": {
+            "id": { "type": "string" },
+            "appId": { "type": "string" },
+            "connection": { "$ref": "#/$defs/idRef" },
+            "input": { "type": "object" },
+            "inputs": { "type": "array" },
+            "name": { "type": "string" },
+            "description": { "type": "string" }
+          }
+        },
+        "steps": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "$ref": "#/$defs/step" }
+        }
+      }
+    },
+    "graphNode": {
+      "type": "object",
+      "required": ["key", "nodeType", "appId", "name", "value"],
+      "properties": {
+        "id": { "type": "string" },
+        "key": { "type": "string" },
+        "nodeType": { "enum": ["trigger", "action"] },
+        "appId": { "type": "string" },
+        "actionId": { "type": "string" },
+        "triggerId": { "type": "string" },
+        "name": { "type": "string" },
+        "description": { "type": "string" },
+        "value": { "type": "object" },
+        "retrySettings": { "type": "object" },
+        "continueOnFailure": { "type": "object" }
+      }
+    },
+    "graph": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "format", "slug", "name", "nodes", "edges"],
+      "properties": {
+        "$schema": { "type": "string" },
+        "kind": { "const": "workflow" },
+        "format": { "const": "graph" },
+        "slug": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" },
+        "name": { "type": "string" },
+        "description": { "type": "string" },
+        "nodes": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "$ref": "#/$defs/graphNode" }
+        },
+        "edges": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["source", "target"],
+            "properties": {
+              "id": { "type": "string" },
+              "source": { "type": "string" },
+              "target": { "type": "string" },
+              "sourceHandle": { "type": "string" },
+              "targetHandle": { "type": "string" },
+              "type": { "type": "string" }
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/skills/lunnoa-client/SKILL.md

@@ -4,7 +4,7 @@ description: >-
   Builds custom frontends and backends on top of a Lunnoa Automate deployment
   using the @lunnoa/client TypeScript SDK. App login is always a Lunnoa user
   (createBrowserClient + lunnoa.auth.login / refresh / SSO). lna_ API keys are
-  for the CLI only (discovery, codegen, deploy), never for the app session and
+  for the CLI only (discovery, codegen, deploy, pull, push), never for the app session and
   never in a browser. Covers discovery of the deployment's agents, workflows, and entity
   types, running the deployment codegen first for typed accessors, querying
   and creating entities, triggering workflows and polling executions,
@@ -52,7 +52,7 @@ Run these before inventing resources or shipping UI code:
 1. **Auth** — Lunnoa user JWT via `createBrowserClient` + `lunnoa.auth.login`
    (or SSO). **Never** call Lunnoa as the app's users with an `lna_` key, and
    **never** put `lna_` in the browser (SDK throws when `window` exists).
-   `lna_` keys are for CLI discovery, codegen, and deploy only.
+   `lna_` keys are for CLI discovery, codegen, deploy, pull, and push only.
 2. **Codegen** — When building typed UIs, run
    `npx @lunnoa/client codegen` against the deployment first.
 3. **Discover before inventing** — prefer the CLI (JSON for agents), then
@@ -67,10 +67,16 @@ Run these before inventing resources or shipping UI code:
    Do not invent catalogue action ids or model ids. `connections list` is
    app connections (Gmail, HTTP). `ai-connections list` is the model
    provider connection and the `models[].id` values `defineAgent` accepts.
-4. **Run vs deploy** — Ad-hoc: `actions.run` / `runs.start` /
-   `workflows.execute`. Durable shared automation: CLI
-   `npx @lunnoa/client workflows|agents deploy`. Upsert is by slug
-   inside the workspace on the API key. URL and API key are enough.
+4. **Run vs save** — Ad-hoc: `actions.run` / `runs.start` /
+   `workflows.execute`. Durable agents and workflows default to JSON in
+   `lunnoa/` (`npx lunnoa-client status`, then `pull`, then `push`).
+   That sets `codeSource: synced`. TypeScript
+   `npx @lunnoa/client workflows|agents deploy` is only for a definition
+   that needs code. That sets `codeSource: generated` and locks the UI.
+   A `.json` deploy is a push. `codeSource` replaces `managedByCode` on
+   agents and workflows. Tables and entity types still use
+   `managedByCode`. Upsert is by slug inside the workspace on the API
+   key. See section 5d.
 5. **Toolkit boundary** — Client `defineAction` ≠ toolkit `createAction`.
 
 ---
@@ -85,7 +91,7 @@ app does not keep its own user directory and does not call Lunnoa with an
 | Caller | Credential |
 |---|---|
 | **Person using the app** | `createBrowserClient({ baseUrl })` + `lunnoa.auth.login` (password, 2FA, or SSO). Permissions, agent shares, and task history are that user's. |
-| **CLI (codegen, discovery, deploy)** | `lna_` API key in `.env` / `--api-key`. Not the app session. |
+| **CLI (codegen, discovery, deploy, pull, push)** | `lna_` API key in `.env` / `--api-key`. Not the app session. |
 
 Hard rules:
 
@@ -455,6 +461,42 @@ Wire step settings in code with `ref`. Do not leave them for the builder.
   node id across deploys, so run history and builder mappings stay attached.
   The trigger keeps its id while its type and settings stay the same.
 
+### Branches (paths)
+
+Put `paths` on the **last** step of a list. Steps after the branch go inside
+each path. Paths do not merge back together.
+
+```ts
+const approval = defineAction({ id: 'flow-control_action_request-approval', input: { /* from tools get */ } });
+const split = defineAction({ id: 'flow-control_action_conditional-paths' });
+
+steps: [
+  { key: 'review', use: approval, paths: [
+    { label: 'Approved', steps: [{ key: 'apply', use: applyChange }] },
+    { label: 'Rejected', steps: [{ use: notify, input: { text: ref.step('review', 'comment') } }] },
+  ] },
+]
+
+// Conditional Paths: groups in `when` are OR-ed, conditions in a group AND-ed.
+{ key: 'route', use: split, paths: [
+  { label: 'Large', when: [[{ field: ref.step('load', 'amount'), condition: 'is_greater_than', value: '1000' }]], steps: [...] },
+  { label: 'Other', steps: [...] }, // no `when`: always taken
+] }
+```
+
+- `paths` works on Request Approval (at most two: approved first, then
+  rejected; labels `Approved` / `Rejected`), Conditional Paths (with `when`),
+  and Manually Decide Path (no `when`).
+- `when` conditions: `field` is exactly one `ref.trigger` / `ref.step`.
+  `condition` is one of `PATH_CONDITIONS` (equals, contains, is_empty,
+  is_true, is_greater_than, is_less_than, matches_regex, is_in_the_past, ...).
+  `value` is text; omit it for exists / is_empty / is_true style conditions.
+- Conditional Paths takes every path whose `when` matches. A path without
+  `when` always runs. For if/else, give the else path the opposite condition.
+- Steps on a path can `ref.step` the branching step and earlier steps on
+  the same path, not steps on another path.
+- `runs.start` rejects `paths`. Deploy, then execute the workflow.
+
 Discover the catalogue **before** writing `defineAction` (do not guess ids):
 
 ```bash
@@ -486,11 +528,138 @@ npx @lunnoa/client workflows deploy ./ping.ts --url … --api-key …
 npx @lunnoa/client agents deploy ./triage.ts --url … --api-key …
 ```
 
+Those two commands deploy TypeScript and set `codeSource: generated`
+(locked in the UI). For the JSON round-trip, use section 5d. The binary
+name is `lunnoa-client`, so `npx lunnoa-client` and `npx @lunnoa/client`
+are the same command.
+
 `defineAction` binds catalogue actions only. Toolkit `createAction` is a
 different job (in-platform apps).
 
 ---
 
+## 5d. Sync JSON definitions with the UI
+
+Default for a saved agent or workflow: a JSON file in `lunnoa/`, then
+`push`. Use a TypeScript `defineAgent` / `defineWorkflow` file only when
+the definition needs code (you also pass it to `runs.start`, or the
+tools are built in code). TypeScript deploy sets `codeSource: generated`
+and the UI badge **Managed by code**. The UI will not edit it. Deploy
+the TypeScript file again to change it.
+
+`codeSource` (`none` | `synced` | `generated`) replaces `managedByCode`
+on agents and workflows. Tables and entity types still use
+`managedByCode`.
+
+Folder (default `./lunnoa`, or `definitionsDir` in `lunnoa.config.*`, or
+`--dir`):
+
+```text
+lunnoa/agents/<slug>.json
+lunnoa/agents/<slug>.instructions.md
+lunnoa/workflows/<slug>.json
+lunnoa/lunnoa.lock.json
+```
+
+The JSON holds `"instructions": { "file": "<slug>.instructions.md" }`.
+`pull` writes that split. A hand-written file may use a string. Every
+JSON file starts with `$schema`, a relative path to
+`node_modules/@lunnoa/client/schemas/agent.schema.json` or
+`workflow.schema.json` (draft 2020-12). The CLI strips `$schema` before
+sending and checks the file shape (slug, instructions, `use.id`, unique
+keys, one trigger on a graph). Commit `lunnoa.lock.json`. It stores id,
+revision, and file hash per deployment key
+`<base url>#<workspace id>`.
+
+Not in the file, and push does not change them: credentials (connection
+ids only), canvas positions, the workflow on/off switch (`isActive`),
+profile image, shares, memories, skills. Pull warns, and still writes
+the file, when an input field name looks like a secret
+(`authorization`, `token`, `secret`, `password`, `apiKey`, `bearer`,
+`cookie`, `privateKey`, …) and the value is a literal string. Keep that
+value on a Lunnoa connection.
+
+Workflow pull writes `"format": "steps"` when a trigger plus a step list
+round-trips. It writes `"format": "graph"` when steps would drop
+something (paths that join, a for-each loop). Edit the format pull
+wrote.
+
+Commands (reads `LUNNOA_URL` and `LUNNOA_API_KEY` from the environment
+or `./.env`):
+
+```bash
+npx lunnoa-client status
+npx lunnoa-client status --json
+npx lunnoa-client pull
+npx lunnoa-client pull <slug>
+npx lunnoa-client pull agents/<slug>
+npx lunnoa-client pull workflows/<slug>
+npx lunnoa-client pull --all
+npx lunnoa-client push
+npx lunnoa-client push <path-or-slug>
+```
+
+Run `status` before editing. Run `pull` before `push` when the UI has
+moved. `pull` with no slug updates lock entries for this deployment.
+`pull --all` fetches every agent and workflow in the workspace. `push`
+with no path sends every JSON file, workflows first, then agents, with
+`codeSource: synced` and `baseRevision` from the lock. On success it
+rewrites the file from the stored definition and updates the lock.
+
+`status` columns: `LOCAL` is `unchanged`, `modified`, `new`, or
+`missing`. `REMOTE` is `unchanged`, `changed in UI`, or
+`missing in Lunnoa`. `CONFLICT` is true when both sides differ from the
+lock. `--json` prints `{ kind, slug, local, remote, conflict }`.
+`remote` uses the words `changed in UI`.
+
+How to read a conflict:
+
+- Pull exits 1 before it writes anything. The message starts with
+  `Local and server both changed. Run pull --force to overwrite.` Then
+  a diff: `--- local` / `+++ server`. `-` lines are the file. `+` lines
+  are the server. Secret values in that diff are `***`.
+- Push exits 1 and prints the server text. Stale lock:
+  `Changed in the UI since your last pull. Run pull first. (currentRevision: …)`.
+  First push of a file whose slug already exists and is not in the lock:
+  `A workflow with slug "<slug>" already exists in Lunnoa. Run pull first, or push with --force.`
+  Agents use `agent` in that sentence. Pull that slug, then push.
+- Ask the human before `--force`. `pull --force` overwrites the local
+  edit with the UI. `push --force` overwrites the UI with the file.
+  `agents deploy file.ts --force` does not send the flag. A `.json`
+  deploy is a push and does.
+
+To turn a generated resource into a synced one: `pull` the slug, then
+`push` the JSON. After that the UI can edit it, unless the workspace
+switch **Lock code-synced resources** is on (Admin Panel, workspace,
+Settings, LLM Audit Policy card). That switch makes synced resources
+read-only and shows **Managed by code**. Badges: **Synced with code**,
+**Changed in UI, not yet in code**, **Managed by code**. A successful
+push clears **Changed in UI, not yet in code**. The docs CI recipe runs
+that push on main.
+
+App code may pass a parsed file to the factories. `$schema` is stripped.
+`defineAgent` keeps `instructions: { file }` as that object. The CLI
+reads the markdown on push. Do not upsert from the app for this loop.
+
+```typescript
+import { readFileSync } from 'node:fs';
+import { defineAgent, defineWorkflow } from '@lunnoa/client';
+
+const agent = defineAgent(
+  JSON.parse(readFileSync('lunnoa/agents/triage.json', 'utf8')),
+);
+const workflow = defineWorkflow(
+  JSON.parse(readFileSync('lunnoa/workflows/sync-orders.json', 'utf8')),
+);
+```
+
+Human detail: Lunnoa Docs, Develop, TypeScript client SDK, Sync with the
+UI (`/guides/develop/client/sync`), including the CI pull request and
+the main-branch push. Do not add that workflow to a brand-new repo that
+has no secrets.
+
+---
+
 ## 6. Recipe: resume a NEEDS_INPUT execution from a custom form
 
 Workflows can pause for human input. The waiting step appears in
@@ -532,7 +701,7 @@ for await (const chunk of stream) {
 }
 ```
 
-A turn from an app runs in **preview**: 10 model rounds, so the agent can call tools a few times and still send a final reply. The SDK sends `chatMode: 'preview'` for you. Do not pass `chatMode: 'builder'` from an app. That is the agent-editor interview: 4 rounds, and it stops a tool-using agent halfway. The workflow then fails with "Agent did not generate a response" even when a tool already saved the data. A workflow Message Agent step uses the same preview budget. For a job that chains many tool calls (read every record, then write a result), turn on **Long-horizon mode** on that agent in Lunnoa. That raises the budget to 50 rounds. `defineAgent` cannot set the switch, and a later deploy leaves it as you set it.
+A turn from an app runs in **preview**: 10 model rounds, so the agent can call tools a few times and still send a final reply. The SDK sends `chatMode: 'preview'` for you. Do not pass `chatMode: 'builder'` from an app. That is the agent-editor interview: 4 rounds, and it stops a tool-using agent halfway. The workflow then fails with "Agent did not generate a response" even when a tool already saved the data. A workflow Message Agent step uses the same preview budget. For a job that chains many tool calls (read every record, then write a result), turn on **Long-horizon mode** on that agent in Lunnoa. That raises the budget to 50 rounds. A JSON definition includes `settings.longHorizonMode`, and a push writes it. A TypeScript `defineAgent` does not set the switch, and a later TypeScript deploy leaves it as you set it.
 
 - **React apps:** prefer `useAgentChat` from `@lunnoa/client/react`, which wraps AI SDK `useChat` + `DefaultChatTransport`
   pointed at
@@ -630,7 +799,7 @@ with emails (capped; not Azure object IDs).
 3. Call `discovery.enabledFeatures()` and hide unsupported areas.
 4. Build forms/tables from `attributeSchema` / `customInputConfig` (or the generated types).
 5. Render workflow progress from `executionPath`; handle `NEEDS_INPUT` with `submitInput`.
-6. For single-action calls, use `actions.run`; for linear multi-step, use `runs.start` / `defineWorkflow`. Deploy with `npx @lunnoa/client workflows|agents deploy`. Discover actions via `npx @lunnoa/client tools list|get|search` (or `workflowApps.list()`). Discover triggers via `apps get <appId> --json` and pass `defineTrigger` on `defineWorkflow` (omit it for Manually Run with no fields). `runs.start` does not save the trigger. Pass trigger inputs and earlier step outputs into step settings with `ref.trigger` / `ref.step` (key the source step). Discover agent models via `npx @lunnoa/client ai-connections list --json` (or `aiConnections.list()`).
+6. For single-action calls, use `actions.run`; for linear multi-step, use `runs.start` / `defineWorkflow`. Save agents and workflows as JSON in `lunnoa/` and use `npx lunnoa-client status`, then `pull`, then `push` (section 5d). Ask the human before `--force`. Use `npx @lunnoa/client workflows|agents deploy` for a TypeScript file that needs code (`codeSource: generated`). Discover actions via `npx @lunnoa/client tools list|get|search` (or `workflowApps.list()`). Discover triggers via `apps get <appId> --json` and pass `defineTrigger` on `defineWorkflow` (omit it for Manually Run with no fields). `runs.start` does not save the trigger. Pass trigger inputs and earlier step outputs into step settings with `ref.trigger` / `ref.step` (key the source step). Branch with `paths` on Request Approval or Conditional Paths (last step only). Discover agent models via `npx @lunnoa/client ai-connections list --json` (or `aiConnections.list()`).
 7. For Request Approval nodes, use `approvals.inbox` / `approvals.decide` (or `executions.submitApproval`).
 8. Chat: stream via SSE, handle resume (reconnects) and stop, load history from the task.
 9. Handle `LunnoaApiError`: 401 → re-auth; 403 → hide the capability; 429 → back off.

package/skills/lunnoa-solution-design/SKILL.md

@@ -74,7 +74,7 @@ interrogation.
 | End users | Auth |
 |---|---|
 | People using the app | Lunnoa user JWT: `createBrowserClient` + `lunnoa.auth.login` (or SSO). Provision missing people with invite, SSO, or SCIM first. |
-| Coding agent / CLI | `LUNNOA_API_KEY` for discovery, codegen, and deploy. Not the app session. |
+| Coding agent / CLI | `LUNNOA_API_KEY` for discovery, codegen, deploy, pull, and push. Not the app session. |
 | Anonymous embed chat (no full login) | Out of scope for v1 client path; scoped embed tokens are a later platform bet |
 
 ---
@@ -86,7 +86,7 @@ interrogation.
 | One catalogue call | `actions.run` | One-step Execution (`source: SDK`) |
 | Linear multi-step, experiment | `runs.start` / `defineWorkflow` then run | One Execution; optional later deploy |
 | Reusable automation + triggers | Saved **Workflow** (`defineWorkflow` + `defineTrigger`, or the UI) | Discover trigger ids with `apps get <appId> --json`. Omit `trigger` for Manually Run with no fields. `runs.start` ignores the trigger. Wire step settings to trigger fields and earlier steps with `ref.trigger` / `ref.step`. |
-| Branches (approve / reject, if/else) | Builder in Lunnoa | Code deploys build straight lines only. A later code deploy replaces builder edits. |
+| Branches (approve / reject, if/else) | `defineWorkflow` with `paths` on Request Approval or Conditional Paths | The steps format does not merge paths. Repeat shared steps in each path, or build the join in the UI and `pull`: the file becomes graph JSON and `push` keeps the join. A TypeScript deploy (`codeSource: generated`) replaces the stored graph and locks the UI. |
 | Reasoning + tools + conversation | **Agent** | Tools = workflows, actions, knowledge |
 | Structured CRUD / portals | **Entities** + schemas | Codegen for typed accessors |
 | Reference / lookup data | **Tables** | `tables.upsertBySlug`; workflows use the Tables Lookup action |
@@ -131,8 +131,13 @@ interrogation.
    as a fixed value, "from trigger `caseId`", or "from step `load` →
    `rows.0.status`". The build uses `ref.trigger` / `ref.step` for these, so
    "connect it in the builder" is not a fallback for data wiring.
-5. **Durable vs ephemeral:** experiments → `runs.start`; shared production
-   automation → CLI `workflows deploy` / `agents deploy` by slug.
+5. **Durable vs ephemeral:** experiments → `runs.start`. Shared production
+   agents and workflows → JSON in `lunnoa/` (`npx lunnoa-client status`,
+   `pull`, `push`), `codeSource: synced`. TypeScript
+   `workflows deploy` / `agents deploy` only when the definition needs
+   code (`codeSource: generated`, locked in the UI). A `.json` deploy is
+   a push. `codeSource` replaces `managedByCode` on agents and workflows.
+   Ask the human before `--force`. Commit `lunnoa/lunnoa.lock.json`.
 6. **UI is headless.** `@lunnoa/client` has no design system. Optional React
    hooks in `@lunnoa/client/react`. Partners bring their own UI.
 7. **Reuse before create.** Before proposing any new entity type, table,
@@ -176,6 +181,7 @@ can execute. Use this shape:
 - [ ] `npx @lunnoa/client ai-connections list --json` before choosing an agent model
 - [ ] agents / workflows / entity-types / tables list — reuse before create
 - [ ] codegen — if building typed entity/workflow accessors
+- [ ] `npx lunnoa-client status` before editing `lunnoa/`, then `pull` before `push`
 
 ### Resources (every row says REUSED or CREATED)
 | Kind | Slug / id | Reused / created | Notes |
@@ -188,7 +194,8 @@ can execute. Use this shape:
 
 ### Runtime paths
 - Ad-hoc: actions.run / runs.start / workflows.execute
-- Deploy: npx @lunnoa/client workflows|agents deploy …
+- Sync: JSON in `lunnoa/`. `npx lunnoa-client status`, then pull, then push. Commit `lunnoa/lunnoa.lock.json`. No `--force` without a yes from the human.
+- TypeScript deploy (generated, locked in the UI): npx lunnoa-client workflows|agents deploy …
 - Chat: agent stream-message / useAgentChat
 
 ### UI surfaces (headless)