Edit, preview, run, and publish in Desktop

For a local project, the Desktop workspace works from the current directory: you can edit, save, preview, run, and publish it. An ordinary folder can use Files, Terminal, Browser, Developer Assistant, and Open Project tool tabs without gaining project-only capabilities. When you open a cloud project, the workspace uses the Server adapter. Files and project information are read-only, and structure, versions, run data, and Kanban configuration come from Workflow Server.

Open a Local Workspace from Home

The Home Local scope displays Workflow, Conversation, Kanban, and ordinary folders as one workspace card collection. They share name-or-path search, type filters, and name or recently edited sorting. A List or relationship-graph switch follows search. The graph connects relationships from the current scope, lays connected components out from left to right, and places unrelated workspaces at the bottom; searching retains the complete relationship chain around each match. Folder is a Desktop-local workspace type; it does not enter Workflow project types or appear in Cloud filters. A folder card shows its name, real path, and Folder type without inventing a project version, UUID, or package metadata.

Open folder lets Electron Main select, classify, and register a directory; the renderer receives only a typed ID and never submits an arbitrary path. Home also accepts multiple projects or folders in one drop. Main processes every available top-level directory in drop order, and one unavailable item does not block the others. A valid Workflow Code declaration follows the existing project import path. A directory with no Workflow declaration becomes an ordinary folder even when it contains a normal npm package.json. A directory that declares Workflow Code but fails current migration or structure validation also falls back to an ordinary folder, keeping Files, Terminal, and Developer Assistant available for direct source repairs. Canonical real paths deduplicate symbolic links and Windows case differences. Ordinary files do not trigger imports, and a filesystem root cannot be opened as a workspace.

An ordinary folder provides only Files, Terminal, Browser, Developer Assistant, and Open Project. Its file tree keeps the existing exclusions for .git, node_modules, caches, and sensitive .env files, plus the existing binary and oversized-file preview limits. Removing its card revokes Desktop registration and assistant authorization without deleting disk content. A hidden registry record retains the stable ID, so opening the same path restores the card and project links. Desktop never generates configuration in an ordinary folder, changes its directory structure, or synchronizes it to Server.

Projects that a user creates or imports are local user projects and can be edited, published, and removed. Open Edit Project Information from the Home project menu or open an Information tab in a project-detail dock to edit the root package.json.name default name and the manual multilingual/multiplatform declarations. Simplified Chinese and English names appear and become editable only after selecting Multilingual. Platform-agnostic or selected macOS/Windows/Web display platforms appear and become editable only after selecting Multiplatform. Clearing a declaration hides its configuration without deleting saved values or the current draft. Declarations and display platforms affect project cards and details only; they neither change version release targets nor verify the implementation. Home uses and searches localized names only while Multilingual is declared; otherwise it uses and searches the default name. Display platforms likewise appear only while Multiplatform is declared.

In a wide Information tab, the existing project information editor stays on the left and the project-root Markdown README preview appears on the right. A narrow tab stacks them in that order. The default and Simplified Chinese interfaces read README.md. After the project declares Multilingual, the English interface prefers README.en.md and falls back to README.md when that file is absent. Adding README.en.md alone does not declare multilingual support. Changing the interface language switches the preview immediately without modifying project files. Relative PNG, JPEG, WebP, and GIF images are read safely from the current project directory.

All five Desktop-managed built-ins explicitly declare multilingual support and provide both a Chinese README.md and an English README.en.md. The Chinese interface displays 对话助手, 智能体-Codex, 智能体-OpenCode, 桌面控制, and 小助手; the English interface displays Conversation, Codex, OpenCode, Desktop Control, and Project Assistant. Desktop Control and Project Assistant are hidden dependencies and do not appear in the Home project collection. Their names and declarations still come from each project's own package.json; Desktop does not special-case them by built-in project ID.

The same editor manages the Home card icon. Workflow and Conversation types derive from executor source, while Kanban comes from package.json.workflowCode.projectType; every type is read-only and its label follows the interface language. The Simplified Chinese interface displays 工作流, 对话, and 看板. The icon editor can select a local image and preview, crop, and zoom it at 1:1 before producing a 512x512 WebP. An unbound project writes directly to local package.json. A bound project must connect and sign in to its original Server; Desktop synchronizes the image and PUT /api/workflows/{id}/project-info before writing locally. Built-in projects remain Desktop-managed and read-only for source, project information, environment, remote source, and publication, but can still run, refresh, and create an editable copy.

The project TopBar keeps the bottom and right dock toggles plus applicable Environment, Pull, Publish, and project actions. Global Settings is in the project-actions menu. Save and Refresh appear only in each Files tab's own toolbar. At narrower widths, secondary project actions collapse by priority into icon buttons with tooltips.

Reload project state in the project-actions menu rereads the registered directory and runs complete project recognition. A repaired ordinary folder can become a Workflow, Conversation, or Kanban project in place. If the manifest still has unsupported fields, its entry remains invalid, or a previously valid project has become invalid, Desktop retains the original project registry record, safely opens the current directory as an ordinary folder, and shows the original validation error from this recognition attempt in Output. Reload returns failure instead of presenting the folder fallback as a successful project refresh, and it never deletes or rewrites project source.

Use Kanban Projects

Choose Kanban when creating a project to start from a parameter-free or parameterized example. Both create a complete board project with .workflowignore, a page, state and KV-storage modules, a README, and pure-logic tests. The page itself can create, edit, drag, and delete tasks. The parameter-free example does not create kanban.json, so the HTML canvas fills the preview. The parameterized example includes kanban.json with a title and accent color; the preview shows named configurations and a parameter form. The same HTML entry updates live as the active configuration changes, without creating a workflow run.

For a Vue, React, Vite, or similar project, configure artifactDir and an entry relative to that directory in package.json.workflowCode.kanban. The Desktop host does not install dependencies, run build scripts automatically, or connect to a dev server, port, or HMR. Once you build the project yourself, changes to the artifact directory refresh the preview; source-only changes do not. Existing projects without this configuration continue to use the root index.html.

For a local user Kanban project, Developer Assistant is available from either dock's New Tab catalog and defaults to the right. It can help edit HTML, CSS, JavaScript, and other files in the current Kanban project. After related projects are configured in an Information tab, it can also coordinate changes across other authorized local source projects. For framework projects configured with artifactDir and entry, it may run the existing one-time build command and check the entry artifact after source changes when dependencies are installed. It never starts a dev/watch server, opens a port or HMR, installs dependencies, or invents a build script. A failed build clearly states that the preview still shows the previous artifact. Kanban does not gain Send, Run, project conversation, Logs, or run history from this assistant; cloud Kanban and built-in projects omit it from the New Tab catalog.

On first opening a parameterized Kanban project, the Desktop creates a Default Configuration. The top of the left parameter panel switches or creates configurations; rename, duplicate, and delete are in the current configuration's action menu, and the final configuration cannot be deleted. Parameters use vertical labels and full-width controls, with short single-choice options rendered as compact segments. Changes save automatically and the title bar continuously reports save status. If a save fails, the current input and retry action remain. Configurations and the active configuration are stored in Desktop data on the current device, never written back to source or shown in another local project. A file parameter gives the page only a managed file reference, not a local absolute path.

The Kanban page runs in an isolated offline iframe. It can load only relative resources from the configured artifact directory plus data: and blob: content; it cannot reach the source directory, public network, Node, preload, or the parent-page DOM. Read the current configuration through window.workflowCodeKanban.getConfiguration() and listen to workflow-code:kanban-configuration-change. Use window.workflowCodeKanban.kv and .knowledge for data in the current project's fixed scope. Once both projects confirm a general relation, use window.workflowCodeKanban.relatedProjects.get(alias).kv.getValue/setValue/subscribe according to the target project's grant to the current project. The page can submit only an alias and key; it cannot override the target UUID, scope, or storage location. See Kanban HTML Projects for the complete API, persistence examples, and security boundary.

Local Dependencies

The Desktop never installs, updates, or removes dependencies for a local project, and never runs package-manager commands such as pnpm install or npm install. Before importing, use the project's own package manager in the project directory. The Desktop does not require pnpm or a pnpm-lock.yaml.

When a new template is written to disk, Desktop Main generates a UUID for package.json.id, writes exact workflow-code and @workflow-code/cli versions to devDependencies, and adds dev, inspect, run:json, workspace:upload, and workspace:publish scripts. After creating a project, you still need to run the package-manager install yourself in the project directory.

Before a local run, dynamic-parameter resolution, or recovery of a waiting run, the Desktop checks read-only that runtime dependencies and required peer dependencies from package.json resolve from the project's node_modules. Development dependencies, optional dependencies, and optional peer dependencies do not block a run.

When a dependency is missing, the Desktop stops the current operation and shows the project directory and package name. Install it manually in that directory and try again; the project remains available for opening and editing. Commit the lockfile used by your package manager so team and server builds remain reproducible, but remember that a lockfile does not mean dependencies are installed.

Complete a Local Run

Open Files and edit the source

Select Files from New Tab in the right or bottom dock and open a workflow source file. After you change it, the Desktop debounces a structural analysis of the in-memory file and updates input parameters, conversation mode, and tool configuration in the fixed Run main surface. Save in the tab toolbar then writes to the local directory and refreshes environment-variable data.

Fill in run parameters

Return to the fixed Run main surface. A Workflow shows a Swagger-style list of entry points in declaration order. The default entry point starts expanded, each entry has its own parameters, and its Run action appears only after expansion. A Conversation continues to show one session list and composer.

Click Run or Send

Expand the target entry point and click Run in its content area. The Desktop checks for unsaved changes, then runs that entry point directly in the local Electron environment; it does not run the default entry point first. A Conversation continues with Send.

View output and diagnostics

Output appears in the main Run view. Open Trace to inspect node links and Logs to troubleshoot stdout, stderr, or the report.

Main Surface and Tool Tabs

Project details no longer have left-side view navigation. Workflow and Conversation keep Run as the fixed main surface, while Kanban keeps Preview. Two buttons at the right of the project TopBar toggle the bottom and right docks. Both docks are closed when a new project is first opened, so the main surface is immediately available.

Both docks use the same New Tab catalog:

Tool tab	Purpose
Run / Preview	Opens another independent run or Kanban preview session for the target.
Schedules	Configures background timer runs for a Workflow entry point. Conversation and Kanban do not provide it.
Information	Edits project display metadata and previews the root README. When space is narrow, the editor and README stack in that order. Built-in and cloud projects are read-only.
Knowledge Base / KV Data	Manages data for the current project and selected local or server source.
Files	Edits local source or reads cloud-project files. Save and refresh live in this tab's toolbar.
MCP	Available only for a local Workflow; lists entrypoint tools and generates a copyable compact stdio client definition.
Terminal	Creates an independent terminal in a local project or ordinary folder. Cloud projects do not provide it.
Browser	Opens http/https pages in a restricted browser with an address bar, back, forward, refresh, and page status.
Developer Assistant	Maintains a normal local user project or available ordinary folder. Cloud and built-in projects do not provide it.
Logs / Diagram	Shows diagnostics bound to a project and run. Kanban and targets without run records do not provide them.
Open Project	Selects another local project, cloud project, or ordinary folder inside the current tab without nesting another dock shell.

An ordinary folder shows only Terminal / Browser / Files / Developer Assistant / Open Project. Other entries are filtered by Workflow, Conversation, or Kanban type, local or cloud source, and run availability. A legacy project that has not declared a data-storage mode can open only Information, Browser, Files, and another project. Knowledge and KV continue to use the explicit source of the tab's target; selecting another project globally cannot switch its adapter.

The MCP tab reads its connection definition through a narrow Electron Main IPC; Renderer cannot supply runtime paths or arbitrary project directories. The copied definition contains only the Workflow Code launcher and Desktop project ID. The AI client automatically starts a separate headless process when it connects, so there is no command to run first and the main Desktop window does not need to remain open. The launcher rereads the project directory and confirmed related projects from Desktop's registry, then resolves the real runtime, local data directories, and saved authentication internally. Those details never enter the copied definition.

Every MCP tool call made through this definition is saved to the current Desktop workspace's local run history. The original MCP input, CLI args, submitted interaction values, complete report, stdout, and stderr remain available as the same runId moves through its lifecycle. Open the record from Home recent tasks or project history to inspect Output, Diagram, and Logs. An open Desktop main window refreshes after the external write; closing it does not prevent the headless launcher from persisting the record.

A packaged definition has the following shape. Development definitions add the development app entry and one short profile argument, but still omit CLI, tsx-loader, project, data-directory, and related-project paths.

{
  "mcpServers": {
    "workflow-<PROJECT_UUID>": {
      "command": "<WORKFLOW_CODE_EXECUTABLE>",
      "args": ["--workflow-mcp", "<DESKTOP_PROJECT_ID>"]
    }
  }
}

The project must remain registered in the current Desktop workspace and its local directory must stay available. Reconnect the client after changing source, entrypoints, static parameters, or related projects to refresh the fixed tool catalog and launch context.

Opening an empty dock first creates a closable New Tab. Selecting a tool replaces it in place, and the new-tab action always follows the last tab; multiple instances of the same tool can coexist. The trailing header action hides the current dock. New Tab has no tab-actions menu, while actual tool tabs still provide Move Right / Move Bottom. Drag tabs to sort them within a dock or move them to the other dock, and use ArrowLeft / ArrowRight / Home / End to move focus through the current tablist. Terminal and Browser default to the bottom; other tools and contextual Logs, Diagram, Files, and Developer Assistant tabs default to the right.

Project Assistant can use workflow-desktop's open_dock_tool to open a tool tab for the workspace that owns the current run. This automation entry defaults to the right and can explicitly select the bottom; it does not inherit Terminal or Browser's manual-catalog default. Main fixes the host to the run-bound user home, editable local project, or ordinary folder, and call parameters cannot override that host. Renderer reuses the catalog above before navigation, so Home permits only Developer Assistant, Terminal, Browser, and Open Project and does not gain Files. An ordinary folder likewise cannot gain Information, Knowledge, or KV.

When a request already contains concrete context, Project Assistant passes the matching fields in the same call so the tab opens the requested content instead of stopping at an empty address bar, run selector, or project picker:

Field	Scope and effect
url	Browser only; accepts http/https and navigates immediately after the tab is created.
filePath	Files, or the Open Project Files view; must be a normalized path relative to the selected workspace.
runId	Run, Logs, Diagram, or the Open Project Run view; selects the corresponding run.
conversationId	Run, Developer Assistant, or the Open Project Run view; restores the corresponding conversation.
dataSource	Knowledge/KV, or the matching Open Project view; explicitly selects local or server.
openedProjectKind + openedProjectId	Open Project only; uses a local-project or ordinary-folder ID returned by list_projects and skips the picker.
openedProjectTool	Opens Run, Preview, Schedules, Information, OpenAI, Knowledge, KV, or Files inside the side project; folders support Files only.

An Open Project target stays embedded in the current Dock and does not change the Project Assistant run host; use open_project to switch the whole main workspace. Side targets do not accept cloud projects, arbitrary absolute paths, or unregistered directories. Main validates field combinations, URLs, relative paths, registration, and server data sources, while Renderer checks the current catalog again. Invalid context reports an error instead of silently falling back to an empty tab.

Project Assistant uses get_dock_state to read right/bottom visibility, sizes, active tabs, every exact tabId, restore context, available actions, and live run sessions. manage_dock reuses a precise tabId to show or hide a Dock, activate or move a tab, and update an existing tab's URL, file, run, conversation, data source, or side-project view; updating a Browser URL navigates immediately. close_dock_tab closes an eligible tab while retaining self-tab protection and unsaved-content confirmation. run_dock_project runs the registered local project represented by a Run or side-project tab: Workflow accepts arguments and an entrypoint, Conversation accepts a message and conversation, and the call immediately returns request, run, and conversation IDs while execution continues.

Desktop project-lifecycle tools do not substitute a dialog or adjacent action for the user's goal. Direct creation uses create_workflow_project, cloning a registered local project returned by list_projects uses clone_project, and import_project only validates and registers an already-existing absolute directory. open_new_project_dialog is reserved for an explicit request to operate the new-project form. Direct create, clone, and import calls return the project record for a later open or Dock operation.

Hiding a dock only hides its content. It does not close tabs, terminate terminals, or reload browsers, and the same instances remain when you return to the page. Only a tab's close action releases its instance; closing the last tab hides that dock automatically. Unsaved Files or Knowledge drafts require Desktop confirmation before closing. Each project or ordinary folder separately stores dock sizes, visibility, tab order, active tabs, and restorable URL, file, run, and conversation selections for page navigation and Desktop restarts. Browser restores its last URL and login session but not back/forward history. Terminal starts a new process for the same target rather than restoring a pre-restart process.

Drag a divider to resize its dock. Once focused, use arrow keys for fine adjustment and Home / End for the minimum or maximum. The bottom dock uses at most 50% of available height and the right dock at most 75% of available width. With both open, the main surface retains at least 320px of width and 240px of height. Global Settings is in the TopBar project-actions menu and returns to the current project when closed.

Kanban has no executor. Opening, saving, refreshing, publishing, or watching artifact changes never starts executor structure analysis, reads run history, or loads local execution environment variables. A dedicated Kanban preview path validates the HTML entry, static resources, and optional parameter manifest. You can still run workflow-code structure <project-dir> when needed to statically validate projectType, artifactDir, entry, and kanban.json; it never creates a run record.

Opening Logs or Diagram from a run result or message binds the new tab to that target and run. Opening either tool from the New Tab catalog first asks you to select a run record. Each run's stdout, stderr, runner diagnostics, and report.json start expanded in Logs and can still be collapsed manually. Long text and JSON remain in dedicated scroll regions without widening the dock.

Save Local Changes

The Files tool tab shows local project files, with Save and Refresh in the tab's own toolbar. A modified file has an Unsaved state. Clicking Save performs:

Save -> write local files -> reload structure -> update the environment-variable view

Structural preview does not wait for a save. After you edit inside the Desktop or an external editor writes to the project directory, the Desktop reanalyzes after changes settle. Consecutive changes are coalesced into one refresh, older analysis cannot overwrite newer file state, and the current usable run preview stays available until it is updated in place.

Save writes only to the local directory. It neither uploads a server draft nor publishes a version; use Publish to synchronize changes to the server. A Kanban artifact directory refreshes its preview only after a successful save or an external build write. Source changes outside a separate artifact directory do not refresh it. Unsaved Monaco content never enters the iframe, and an entry-configuration change in package.json reinitializes the preview.

The file tree distinguishes expanded directories, the current file, and unsaved files. Display of ordinary local files is not controlled by an extension allowlist or .workflowignore, so valid UTF-8 text files such as .vue and .svelte can be read and edited. .workflowignore still controls only the upload list. Binary files and files larger than 1 MB remain visible, but selecting one explains why it cannot be previewed and does not open or save it as text. To avoid scanning dependencies, version-control data, and sensitive environment configuration, .git, node_modules, cache directories, and .env files are excluded from the tree.

Use ArrowUp and ArrowDown for adjacent items, ArrowRight to expand a directory or enter its first child, ArrowLeft to collapse a directory or return to its parent, and Home or End for the first or last currently visible item. A file still loading has its own loading state; an empty search result is not presented as a project without files.

Run a Workflow

The Run view presents a flat, collapsible list in the executor's entrypoints declaration order. Each compact header shows the title, ID, and default marker. An optional description is right-aligned and omitted if space is tight. The header itself has no Run action: the default entry point starts open and is run from its content. Every entry point keeps its own Form/Raw mode, parameter, attachment, and tool-policy drafts scoped by project ID, exact resolved target, and entry-point ID. Collapsing or switching does not clear another entry point's drafts or reopen a collapsed one. A result appears only below the entry point that produced it.

On narrow windows, full run history becomes one selector at the top of the main area with a separate New action. Expanding it supports search and scrolling through loaded runs while retaining the current selection and running state. Closing it leaves the current input or result visible. The composer exposes the actionable Send control only; it does not duplicate an inactive input-and-send-icon control. Form/Raw, Advanced, and Quick controls remain available for structured parameters.

A workflow can set panel: "quick" to put common single- or multi-select controls beside Advanced. Multiple quick controls stay on one row and scroll horizontally when needed; their values populate real run parameters. Conversation quick selections are stored per local workflow and session and restored when you reopen the session. When a workflow defines resolveParams, the Desktop evaluates parameter dependencies at initialization and whenever a Form parameter changes in the main form, Advanced, or Quick. Dynamic visibility updates the Advanced count and Quick controls together. Main-input changes trigger evaluation only when the parameter declares resolveOnInput: true. Send is disabled while evaluation runs. On failure, the Desktop keeps the input, shows the error, and offers Retry without requiring you to close the project. Hiding a parameter does not clear its value; mutually exclusive cases must return both visible: false and value: null.

A type: "string" parameter can use control: "date" | "time" | "datetime" | "date-range". The Desktop reuses the shared date control. A date, 24-hour time, local date-time, and closed date range are stored as YYYY-MM-DD, HH:mm:ss, YYYY-MM-DDTHH:mm:ss, and YYYY-MM-DD/YYYY-MM-DD without time-zone conversion. These controls can appear in the main form or Advanced and in waiting user-input nodes; Quick remains limited to enumerations. Select the calendar heading to jump with year and month wheels. Confirming applies the selection; Cancel keeps the current month. A wide date range shows two independently navigable calendars. Reopening shows the selected start and end months, or the following month on the right when both values fall in one month. Navigating one calendar does not move the other. Narrow layouts use one calendar. A Workflow form does not show required or format errors when an entry point opens; it validates and blocks submission after the first Run attempt. Non-empty invalid defaults or resolver values remain visible, and Run becomes available again after correction.

The codex example, like conversation, reads Provider and Model from the system AI configuration of the current account. Its Quick parameters are Provider, Model, Reasoning effort, and Sandbox. It shows only OpenAI Responses configuration and permits gpt-5.6-sol, gpt-5.6-terra, gpt-5.6-luna, gpt-5.5, and gpt-5.4; gpt-5.6-terra is the fallback when there is no valid selection, and reasoning defaults to high. Invalid configuration or models follow the same fallback rules and are revalidated before each run; CLI input cannot bypass the model limit. The example does not use native codex login. It shows a clear parameter-area error when the account is not logged in or has no compatible configuration. The runtime gives the Codex child process only a temporary loopback address and placeholder key, with a dedicated loopback model provider. A Provider or base URL in the user's global Codex configuration cannot override Workflow Server forwarding, and a real upstream key never enters the project process.

JSON structured output is off by default in Advanced, so the assistant body streams directly. Enable JSON when you need title, branch, result, and path as structured data. The example accepts pasted, dropped, and uploaded images in the default composer as Codex SDK local_image input. After a run, Logs show the Thread ID used to restore the SDK session. Focusing or hovering the token badge reveals Input, Output, Reasoning, Cache read, Cache write, and Calls. Once SDK reconnection is exhausted, the example retries upstream disconnects, connection resets, timeouts, rate limits, and temporary 5xx errors once and displays retry state in Output. Authentication, parameter, permission, and user-cancellation errors are never retried.

The opencode built-in project starts an OpenCode server bound only to a random local port for each turn and saves its Session ID in conversation state for later messages. The temporary server closes after success, failure, cancellation, or pause. The Desktop waits for it to exit before ending the turn so a displayed final answer cannot leave the task running. Provider and Model come directly from the current account's system AI configuration; project LLM_* and OPENCODE_PROVIDER_* variables, global OpenCode configuration, and opencode auth login are not used. OpenAI Responses and Anthropic configurations are supported. OpenAI shows gpt-5.6-sol, gpt-5.6-terra, gpt-5.6-luna, gpt-5.5, and gpt-5.4, preferring gpt-5.6-terra; Anthropic keeps the upstream model and prefers claude-sonnet-5. OpenAI Effort normally offers low / medium / high / xhigh, while gpt-5.6-* additionally offers max / ultra. An extended level falls back to xhigh when switching to an older model. The default is high, and Effort is disabled for Anthropic.

The default composer accepts image attachments. OpenCode receives a unified text / image input and text output modalities configuration for the selected system AI model; the Desktop does not guess whether that model supports images. An unsupported model returns its own error. Advanced retains the working directory and Quick provides Provider, Model, Variant, and Permission. The OpenCode Agent is fixed to build, with no plan/build choice. The resolver atomically refreshes the compatible model list for the Provider, preserves still-valid choices, and falls back to the protocol default after a configuration or model failure. It keeps input and offers retry on failure. Before every turn, it rereads the system AI catalog and reapplies the same limits so disabled configurations and unsupported models cannot be reused. The child process receives only a random loopback address and placeholder key; real upstream keys and Workflow Server short-lived proxy credentials never enter the project, OpenCode configuration, or output.

Conversation model options show vision, web-search, reasoning, and tool-call capabilities. The web-search control is in Advanced and is available and enabled by default only when modelDetails[].capabilities.webSearch is true for the selected model. Unknown or undeclared capabilities switch it off and disable it. Provider and Model changes, and every send, revalidate capability so stale parameters cannot bypass server policy.

OpenCode does not use a sandbox tier named after Codex danger-full-access. It uses allow / ask / deny permissions and defaults to workspace: read-only blocks writes and commands; workspace automatically approves workspace edits and commands but blocks external directories and escalation loops; auto maps to OpenCode --auto and approves every permission not explicitly denied. Native ask is not enabled in headless workflows. Manual Knowledge-base and KV MCP approval continues through the workflow waiting-input protocol.

When the build Agent asks a question, the Desktop turns it into the current run's user-input node: single-select choices render as radio controls, multi-select choices as checkboxes, and custom answers include a text field. When the question panel appears, its question tool is immediately marked complete. The user-input panel alone represents waiting; the completed assistant message does not retain a spinner. An authorization question has its own line and options use the next line's available width. Narrow panels become one column and long Chinese text or absolute paths wrap fully. When automatic approval is disabled for a Knowledge or KV tool, the call immediately pauses the current OpenCode turn and shows approve or reject in place, independent of later model events. The run enters persistent waiting_for_input, and Desktop and Server continue that same run after the shared interface submits a response. On approval, the workflow deterministically executes the saved tool and arguments through the same approval gate, marks the original tool complete, and sends the actual result to the same OpenCode Session as follow-up. It neither resends the original user request nor relies on the model to infer a retry. Local Desktop coalesces duplicate approval submits by project, run, and input request. If Renderer briefly retains an old waiting snapshot after Main has advanced, retry synchronizes Main's authoritative run instead of cancelling the original resume or looping on a "run is not waiting" error. Because an OpenCode native pending question cannot survive a temporary server process, a paused question ends that turn; resuming sends the choice to the same Session as follow-up.

Assistant text streams directly. Reasoning, tool calls, task lists, file changes, agents and subtasks, attachments, context compaction, retry recovery, and errors appear as compact active rows with semantic icons. There is no extra vertical gap between assistant text, tools, adjacent tools, or other active rows. Every activity type has a final icon, natural-language summary, and structured layout from its first frame, then updates in place. It never flashes an icon-free placeholder or raw JSON. Read, search, directory, command, edit, question, Knowledge, and storage tools retain distinct icons. A long summary truncates only when space is insufficient and is available on hover. Expanding a row exposes only value-bearing Input, Result, Error, Files, Tasks, Agent, Prompt, and Reasoning; call IDs, protocol status, and full-layer metadata stay hidden. Task lists, retries, and questions converge to completed state after resumption, failure, pause, or turn completion, leaving no permanent spinner. Empty session.diff and bookkeeping-only steps or snapshots produce no visual noise. Streaming text and tool output preserve Unicode through segmented transfers. The Token badge uses the Input, Output, Reasoning, and cache statistics returned by OpenCode.

OpenCode automatically continues a Session up to ten times for nested upstream outages, SDK errors explicitly marked retryable, or output-length failures. Output shows the current n/10 attempt with the same recovery detail and ends in success or failure after recovery or exhaustion. Continuation never repeats the original user request; it first verifies the Session, tool results, and real workspace state to avoid repeating a completed edit or write. Authentication errors, user cancellation, parameter or permission errors, content filtering, context overflow, and tool business errors are never retried.

Use the Developer Assistant in a Local Workspace

Desktop Home, a normal local user project including Kanban, or an available ordinary folder can open Developer Assistant from either dock's New Tab catalog. Context actions and recent-task recovery default to the right. It is a normal tool tab and does not replace the fixed Run or Preview main surface or another tab. You can sort it, drag it to the bottom, or move it from the tab menu. Hiding a dock, navigating to another project page, or moving the tab preserves its session and background output; explicitly closing the tab alone releases that view instance. The dock's shared divider controls available width or height, so Developer Assistant no longer has a dedicated fixed-width panel or separate width preference.

The tab follows the page's light or dark theme without recoloring the page. Once an assistant for a workspace prepares successfully, showing the retained tab again during the same Desktop session avoids another preparation state. Reinstallation or update still reruns built-in-assistant checks. A narrow dock collapses the topic rail by default; its top current-topic control opens a searchable, scrollable topic panel that can load older records. Messages and the new-conversation description scroll above a permanently bottom-aligned composer. OpenCode, the coordinated modification scope across the current workspace root and authorized related roots, and stable preference or decision memory are described only in an empty new conversation, not after a message is sent. Remote and built-in projects omit the assistant from New Tab, including through recent tasks. In Chinese, the built-in project's localized name is 小助手, while the English interface uses its English declaration.

A normal local user project's Information view lists related projects and assistant folders under Related resources, retains unavailable IDs with warning styling, and refreshes immediately after save or drop. Manage related resources opens the matching dialog. Related projects are general to every project type and are written to package.json.workflowCode.projectInfo.relatedProjects. When the target is editable, Desktop writes both packages transactionally. When it cannot edit or reach the target, only the current declaration remains and the relation is Pending confirmation. A new reciprocal relation explicitly defaults both grants to read: all and write: none; the panel can configure what each side allows the other to read or write in its own KV. A pending relation grants no KV access but can still enter the assistant's code workspace.

A local directory can be dropped into the dialog through the same detection path as Home Open folder. Desktop imports a Workflow Code project and adds a general project relation, or registers an ordinary folder as a local assistant-only folder; ordinary files do not start an import. Folder IDs stay only in Desktop's local project record and are never written to a package or Server. An ordinary folder is always a leaf. Search filters imported projects and registered folders, while the header reports direct links, recursively accessible roots excluding the current primary workspace, and unavailable items. An unavailable reference can be retained or removed, and importing the same project UUID or reopening the same folder path restores availability.

Desktop sends Electron Main only the typed targets { kind: "home" }, { kind: "project", projectId }, or { kind: "folder", folderId } and never accepts a renderer-supplied directory. With Home as primary, Main uses the canonical operating-system user home directory as the only root and does not infer imported projects, ordinary folders, or related resources from its contents. With a project as primary, every new run, waiting-input resume, and latest-task recovery traverses each project's general declarations breadth-first without scanning parent or child directories or imposing a fixed depth. Confirmed and pending relations both enter the code workspace, and each reached project contributes its assistant folders. Project and folder IDs handle cycles and deduplicate targets, while normalized real paths prevent duplicate authorization. Only imported, user-owned, source-editable projects with valid directories and registered folders with valid directories enter the workspace. A missing project, unavailable directory, built-in or non-editable project, unavailable folder, or invalid project declaration stops that branch with a warning while other valid branches continue. An ordinary folder used as primary authorizes only itself and never infers another directory.

When an ordinary folder contains Workflow Code declarations, Project Assistant combines those files with the current primaryTarget.kind: "folder" state and treats the directory as a possible failed project import instead of promoting it on its own. It first repairs obsolete package fields, source, documentation, and verifiable artifacts inside the current root, reporting source migration separately from Desktop project recognition. After source checks, it directs the user to use Project actions -> Reload project state and continues from the original validation error shown in Output. When another project is required, it never scans adjacent directories or broadens its own access. It directs the user to let Desktop recognize the current directory again, then select the project and configure both directions under Information -> Manage Related Resources. A later run started from the project workspace receives the new related roots. Code-workspace inclusion and KV confirmation remain separate: a pending relation can authorize an imported source directory, while KV still requires reciprocal UUID declarations and a grantToRelatedProject from the target that permits the current project.

The current target root remains the OpenCode workdir. For the current run, Desktop writes a temporary V2 workspace manifest whose roots[] distinguish Home, project, and folder targets. Project Assistant accepts V2 only and no longer converts legacy V1 manifests. Under read-only and workspace, other listed roots and their descendants plus runtime-injected Skill directories enter the precise external_directory allowlist so referenced Skill files can be read, while every other unlisted path remains denied. auto does not apply that directory allowlist. A Skill path remains an instruction source supplied by the caller and is never treated by the system prompt as a writable workspace root. The manifest is removed after normal completion, cancellation, or failure, and conversation parameters cannot supply or override paths. Main also creates a random, short-lived, 127.0.0.1-only host capability for every assistant run. A parameterized Kanban target adds named-configuration operations bound only to the primary project through the same capability, which closes when the run ends.

The assistant reuses the installed OpenCode command and applies the same Workflow Server system-AI Provider, Model, and Variant logic. First use installs both OpenCode and Desktop Control; later turns automatically use their current versions. The assistant uses the build Agent. Its Permission quick parameter offers read-only, workspace, and auto, defaulting to auto (Auto approve), which approves every OpenCode permission not explicitly denied. read-only blocks edits and commands. workspace denies every external_directory when no related project exists, permits only directory trees in the Desktop manifest when projects are related, and always denies escalation-loop permissions. Edit, command, Knowledge, KV, question, global memory, and the fixed workflow-desktop MCP are universal capabilities. Kanban host configuration joins the tool list and current run only when the assistant opens a local Kanban project. Workflow and Conversation projects never display, load, or obtain that Kanban capability.

workflow-desktop is the hidden Desktop Control Workflow injected as a standard stdio MCP server. The assistant can read Desktop, update, launch-at-login, built-in-project, local-project, and ordinary-folder state; switch theme or language; change launch at login; navigate or open the new-project dialog; open right or bottom Dock tools for the current target; create a minimal Workflow or import an existing project; read or change editable project information; operate project KV and Knowledge individually or in batches; and check, download, or install updates and maintain built-in projects. KV batch reads and writes and Knowledge batch queries and mutations accept up to 100 items. A request validates every item first, executes in input order, and returns succeeded, failed, and per-item results. Batch writes are not transactional: a runtime failure neither rolls back successful items nor prevents later valid items. OpenCode connects only to the controlled MCP proxy in its parent Workflow: undeclared or disabled tools are hidden, while update management, launch-at-login changes, project creation or import, project-information changes, project KV writes, project-Knowledge mutations, and built-in-project management wait for user approval by default and execute the original call once after resume. Calls can use only IDs and registered absolute paths returned by Desktop. Main revalidates fields, project capabilities, paths, JSON KV values, KV scope, Knowledge boundaries, and operation prerequisites. Installing an update additionally requires explicit restart authorization in the current request. The original stdio environment and run-scoped host token never enter OpenCode or its shell; the MCP worker receives no SQLite path, Electron object, or account key, and a normal copied Workflow MCP definition never contains this host capability. Project deletion, arbitrary database access, and arbitrary Electron operations are not exposed.

host_project_configuration creates, reads, updates, and deletes Kanban named configurations. The assistant first reads parameter definitions and the current values of each configuration. Creation can specify a name and initial parameters. An update can rename and submit partial parameters by configuration ID, name, or the active configuration. Delete must specify an ID or name and cannot remove the final configuration. Writes continue through Main manifest validation and SQLite storage. After a successful write, the right parameter panel and preview update live without changing source or rebuilding. The tool cannot target another project, access the database directly, change file parameters, or write host configuration back to kanban.json. When automatic approval is disabled, approval executes once deterministically through the new bridge created when the run resumes, then continues the same OpenCode Session.

Each assistant session receives the complete writable-root manifest, non-blocking warnings, and the project-scoped workflow-code-generator skill. Before entering a root, it must read local instructions; project repair also requires every generator-designated repair reference to be read completely. If a required Skill or reference is missing, denied, or only partially available, that repair stops and reports its unverified stages. It cannot continue editing, pivot to unrelated optimization, or claim completion from an older CLI success. It checks Git state only when that root is a Git repository and runs tests only when the workspace has applicable project tests. After a multi-workspace change, it reports changes, verification, and applicable Git state separately. That is the assistant's default skill and can be invoked directly while planning or implementing Workflow Code work; an ordinary document folder does not become a Workflow project because the skill is available. OpenCode-discovered skills are not used by default; the smallest relevant set is selected only when the current user request requires it. This is a system-prompt boundary, not a physical isolation from OpenCode skill discovery. The project skill is provided with the assistant and is not installed into a user's global skills directory. New projects use Simplified Chinese by default and do not automatically generate translation resources, a language switch, or locale detection. The assistant adds those adaptations only when the user explicitly requests internationalization or multilingual support and identifies the target languages.

Assistant sessions are isolated by typed target. Home uses a fixed Home context key, projects retain their existing project context key, and an ordinary folder uses folder:<id>, so active conversations and quick parameters from one workspace never appear in another. Existing project sessions and recent tasks remain recoverable. The assistant's KV, Knowledge, OpenCode Session, and global memory use stable built-in namespaces that remain readable after an internal-project version update. global_memory can list, read, search, remember, and forget stable user preferences or workspace decisions. It is stored only in Developer Assistant Knowledge on the current device, never synchronized to the server or another device, and rejects content that appears to be a key or credential. The model records memory when appropriate; it does not force a summary after every turn.

While a run is active:

• The run action enters loading to prevent duplicate submissions.
• A Workflow workspace focuses on one live run at a time. Starting any entry point disables Run for the others; only the active entry point shows loading, Cancel, and its result. This does not limit server API project-level concurrency.
• Cancel aborts a running record. Streaming output and tool calls receive the abort signal immediately. When waiting for input, it ends the related input request and marks the run aborted.
• Output already shown remains visible. A failure appends its error to the result rather than replacing existing content.
• The Desktop incrementally saves visible in-progress Output and Conversation replies in local SQLite. After a force refresh or normal exit, the last saved visible content remains as an interrupted record. Reopening the Workflow automatically opens that record; a Conversation restores its original session without waiting for the workflow to finish.

Run a Cloud Project Remotely

When you open a project from the home page's Cloud mode, the Run main view uses a server streaming API for the current draft or published version. Workflow entry-point ID, parameter resolution, tool permissions, cancel signals, and wait-input submit or cancel calls all go to the same server project. A Conversation sends only its parameters and conversationId. Neither path calls the local workflow runtime.

Remote Output appears live in the Desktop, while the server owns final run records and Conversation content. The Desktop retains only the temporary memory needed by the current workspace. It does not write cloud runs, sessions, knowledge-base content, or KV bodies to Desktop SQLite or localStorage. Switching to a local project with the same UUID still reads local files, name, run history, and data through the independent local adapter.

To edit cloud-project source, choose Download to Local or Copy to Local Project in the cloud project menu. Download retains the UUID and server association; copy creates a new UUID and independent local project. Both require a published version that retained original source, and dependencies must still be installed manually in the project directory after writing files locally.

Cloud Kanban does not use the remote-run path. The Desktop reads a static preview for the fixed draft, latest, or specified version along with the current user's configuration. A preview must use a short-lived capability URL on the active Workflow Server origin and continues to run in a sandboxed iframe with an offline CSP. The HTML entry and its JavaScript, CSS, image, and font subresources use that capability as a temporary credential, so the Desktop does not pass its login cookie or API key into the iframe. The capability remains scoped to the current project, user, target version, and expiration time, while all other Server APIs still require login. Binary resources are restored byte-for-byte when downloading or copying. Remote Run, JSON report, Webhook, and external-run calls for Kanban return an execution-not-supported error.

Schedule Workflow Runs

The local Workflow Schedules tool tab can create an independent plan for any entry point. Rules support an IANA time zone with weekday, multiple time windows, and every-N-minutes options, as well as five-field Cron. Before saving, the Desktop validates the entry point and static parameters against current dev source and displays the next five triggers. If the project declares workflowCode.schedulePresets, presets appear as reusable suggestions; a plan is created only after you explicitly confirm and save one.

Desktop plans always execute the current local project's dev source and reread Structure before every fire. If an entry point was removed or parameters become invalid, the plan records a skip reason rather than falling back to the default entry point. Run history includes the plan name, original trigger time, and fire ID. A scheduled run waiting for user input remains active; later triggers for the same plan are skipped according to overlap rules.

After all windows close, the Desktop stays in the system tray and runs local plans. Choosing Quit, shutting down, or suspending the device stops the scheduler. On resume, it does not replay every missed trigger from downtime or sleep: it records one skipped_missed entry and advances to the first future time. The System Preferences Launch at login option is off by default; when enabled, the Desktop enters the tray after system login without opening a window. See Workflow schedules for complete rules.

Local Run Records

The Desktop retains recent local run records for each workflow. Workflow summaries and full records store the actual entrypointId, a snapshot of the entry-point title, and the exact resolved target. History lists and read-only replay always use the snapshot title; old records without entry-point data show Default / legacy entry point. Startup and history read lightweight summaries first and restore a full report only when you select a run. During execution, only the current run and current Conversation messages update incrementally, avoiding a full-session rewrite for every streamed token. Once the final report is written, a late in-progress snapshot cannot overwrite it.

stdio MCP definitions generated by Desktop write into the same local history and mark their source as mcp. Waiting, consecutive resumes, failures, cancellation, and completion update one runId. An external MCP call never switches the current page or takes focus from a different run you are inspecting.

When compact references genuinely reduce UTF-8 storage and a report stays within the local operation budget, SQLite merges identical output JSON and stores an explicit mapping to its original report position. Within the full deduplication budget, duplicate objects and visible structured-output content can refer to the same authoritative value, while Trace output from different nodes remains unchanged. Very large reports or reports with unusually many output positions retain their original structure to avoid affecting local execution. Logs for a saved run show the stored report.json; Logs for an in-progress run show the current in-memory report. Output, Diagram, and error diagnostics use fully restored run data and behave the same. Opening Conversation Logs reads each currently loaded run report as an expanded section; collapsing one changes only the current viewing state. Local reports never travel to the server with project upload or publishing. When upgrading to a new local-report storage format, older local records are cleared; released SQLite pages are reused by new reports rather than compacting the full database at startup. Local run-exclusive attachments removed or cropped are reclaimed in the background, while project files, attachments still referenced by a session, and newly uploaded but unsent attachments are preserved.

Use Conversation

A workflow with Conversation enabled shows a session list and composer. Conversation retains a single-entry executor: it does not show an entry-point list or accept entry-point selection. Its session ID, queueing, recovery, and internal workflow.runWorkflow() semantics do not change because Workflow supports multiple entry points.

• Every topic uses a stable conversation_id.
• A workflow can set the title, or a user can rename it.
• A user can lock a title; workflow-supplied title updates cannot overwrite a locked title.
• The left topic list shows its loaded range at the bottom. Continue scrolling or select the load-more area for older topics; a failed load can be retried in place.
• A narrow panel uses a compact current-topic control and an icon-only new action at the top. Expanding the topic control supports search, scrolling, and loading older records for long topic lists.
• A narrow Project Assistant tab and the main Conversation surface share a 44px top target row, separator, and composer baseline. Narrow mode reduces only horizontal padding; the bottom edge of top navigation and the bottom input area stay aligned.
• Images and files enter local file storage first, then reach the workflow as file references.
• After a message completes, open Trace or Logs below it or copy its content.
• Streaming body text and consecutive tool calls auto-follow only while the message area remains at the bottom. Manual upward scrolling preserves position until you scroll back to the bottom.
• Waiting input added during a session run appears as a compact one-line summary. Images, attachment count, and other details do not consume composer space; hover for full text, and continue to drag, guide, edit, or delete as needed.
• Tool enablement and automatic-approval state are saved per session. Switching sessions restores only that session's overrides; new or unconfigured sessions use the workflow-registered defaults.
• The bottom-right composer action is a single fixed slot. While a session runs with empty input, it shows Cancel. Typing text or adding an attachment replaces it with Send in place; clearing input restores Cancel. The UI never shows two large controls together.
• Cancel during a session run stops streaming output, tool calls, and recovered execution. If the workflow waits for user input, Cancel ends that waiting run rather than leaving a resumable task.

Session attachments store file references only. Do not put raw base64 content into KV or Conversation history.

When you open a Conversation run from home-page recent tasks, the Desktop opens the project and session first, then selects the run so you can review Output, Trace, and Logs. Project Assistant tasks also carry the target project identity and revalidate that it remains an available normal local project before recovery. A running assistant task opens or activates a Developer Assistant tab in the target project's right dock at that task's conversation without waiting for a run record to enter local history. If older saved records lack a target-project marker, the Desktop restores the target from the related assistant session context rather than falling back to OpenCode's ordinary project interface. When a local session record no longer exists, it still opens the project, attempts to select the run, and shows a non-blocking notice.

Configure Local Environment Variables

The Environment action manages variables for local Desktop runs only. It does not synchronize them to the server.

When a remote run after publishing needs the same variable, configure the server environment variable from the project detail page in Server Web.

The environment-variable dialog independently represents loading, editable content, and error states. It prevents repeated submissions while reading or saving. On failure, it keeps entered variables and shows an error in the relevant area.

Manage Project Knowledge and KV

Knowledge Base and KV Data are project-level tool tabs that strictly follow workflowCode.projectInfo.dataStorage.mode. A local project shows only local data, a server project shows only server data, and a both project exposes a Local / Server segmented selection in each tab and remembers the two selections independently. When only one source is allowed, Desktop selects it before the first load instead of attempting the other backend and then reporting an error. A local project can therefore switch directly to cloud data for the same UUID; a project opened from home-page Cloud mode starts on server data.

• The local entry uses a hard-drive icon, teal color, and Local text. Knowledge uses project-isolated PersistentValue storage and local KV uses a separate ordinary KV store. The internal Knowledge namespace derives stably from the project directory, so rebinding a server project ID or changing a workflow display name never loses local content.
• The server entry uses a cloud icon, information blue, and Server text. Server Knowledge, KV, and PersistentValue use the same-UUID project's server database and contain no local data.
• The first Server selection from a local project opens sign-in when there is no valid session. Desktop then creates or recovers the same-UUID binding, synchronizes the complete declaration, and continues the switch. Failure keeps the original data source and clears this server cache.
• A Kanban iframe's kv and knowledge bridge uses the backend allowed by the current declaration. relatedProjects.get(alias).kv reaches only mutually confirmed direct projects and checks the target's read or write grant to the current project on every call. A page cannot change to another project, scope, or storage location.
• Switching never copies, merges, or deletes data at the other location. Migrate data explicitly through an import or export appropriate for the business need.

A legacy project with no dataStorage.mode is blocked before any user module executes or data is accessed, and Desktop exposes only Information. Saving a declaration updates the exact Core and CLI dependencies to 0.2.0; existing KV, Knowledge, and PersistentValue data is not migrated automatically.

Knowledge lists page through summaries and load full Markdown only after you select a document; search results are paged too. KV lists page through key, scope, type, summary, size, and update time and read a full value only after you select a row. This keeps the workspace responsive for projects with large documents or JSON values. Local and server KV both contain only project and conversation scopes, and KV and PersistentValue use separate storage domains.

Publish to Workflow Server

Confirm login and server connection

Publish requires a valid account, reachable Workflow Server, and bound project UUID. A project with no ID is blocked and guided to create a cloud project from the home project menu or Information view first.

Save local files

Before uploading, the Desktop saves current local files so it cannot send stale content. You still need to complete a Kanban project's own frontend build first.

Choose version release targets

Select Server cloud execution and local execution on the current device for this immutable version. macOS Desktop can select only macOS, Windows Desktop can select only Windows, and the other platform remains visible but unavailable. Workflow and Conversation require at least one target. Selecting the current-device target locks source retention. Kanban keeps Server disabled, but can select the current device or leave it empty and continue as a Server-hosted static Web release.

Confirm Kanban related projects

When a Kanban declares workflowCode.projectInfo.relatedProjects, choose whether each mutually declared project uploads with the group or remains external, and check source permission and Server data-initialization state. A pending relation can be saved and published, but cannot be included and grants no KV access.

Upload and wait for server preparation

Desktop uploads according to .workflowignore; .gitignore is ignored. Server installs Workflow/Conversation dependencies and builds a runtime only when Server execution is enabled. A Desktop-only version only unpacks, validates, and hashes source. Kanban validates and stores static artifacts. Stopping the wait or temporarily closing Desktop does not cancel the server task.

Create the version

Server publishes included projects first, then activates the Kanban root version and pins the exact dependency lock. Any dependency failure keeps the root version offline.

Create Cloud Project and publishing are separate actions. Creating sends only the project name, source-derived projectType, workflowCode.projectCard, and private visibility; it does not send the full package.json or source. Only after the server returns a UUID does the Desktop atomically update local package identity, registry, SQLite sessions and run records, and current route. The first upload of an empty-ID project must match the type supplied at creation. Once a draft or version exists, later uploads update the server-derived type from the executor's new declaration. When binding fails, both the local project and pending UUID remain and can be retried on the same server.

The Kanban publish dialog reads the currently edited workflowCode.projectInfo.relatedProjects directly. It neither relies on executor Structure nor asks for a second dependency declaration. For each relation it shows the local project with the same UUID, the Server project, reciprocal-confirmation status, source-download permission, and Server KV initialization. A confirmed project available locally but missing on Server defaults to Upload together. Choosing included means authorized users can download that project's exact source; when source cannot be distributed, clear it and leave it external. KV permission always comes from both projects' current projectInfo; publishing creates no separate data grant. Pending relations are clearly marked and may stay in a draft or version, but cannot be selected as included.

When a project already has a published version, the dialog reconfirms latest with Server and reads that exact version's Server/Desktop targets, source-retention mode, and dependency lock. The Server target, current operating-system target, and source preference become the new defaults. Desktop targets for other operating systems are not inherited and must be published from their matching systems. A first Workflow/Conversation publication defaults to Server only; Kanban defaults to static Web only. If a relation alias, project UUID, or confirmation status changed, safe defaults apply instead of inheriting an old binding. Release notes always start empty. The Publish action is disabled during the read; an error retains input and blocks publication so delivery cannot change under unknown settings.

A project group transfers source files only. Desktop rejects .env*, KV, schedules, run history, SQLite data, and host-user configuration both while packaging and downloading. Local KV is never uploaded to Server, and Server KV never arrives with a local download. If publication finishes before Server KV is initialized, the UI calls that out and provides access to the source Workflow run or schedule page. It never runs synchronization or enables a schedule automatically.

The publish dialog shows four stages: save, upload, server preparation, and create version. A server-preparation failure identifies the failed stage and reason. Reopening the project queries and restores the latest unfinished or failed task state.

Retain original source defaults off for a first Server-only publication, so the version keeps only its Server runtime. Enabling it also stores an original-source snapshot. Selecting local execution on the current device, publishing Kanban, or including a project-group dependency locks retention on for that publication without rewriting the user's prior choice; removing the forcing condition restores that value. Both source mode and release targets are pinned to the version and cannot change afterward.

Publishing locks duplicate publication and accidental close while keeping stage state current. When it fails, the version and release-note inputs remain so you can correct the reported issue and resubmit.

Pull Remote Source

Pull downloads latest, a draft, or a specified version from Server and fully replaces locally editable source. Published downloads carry the current system platform: macOS accepts only macos, Windows accepts only windows, and latest resolves to the newest compatible online version for that platform. Other operating systems have no implicit compatibility. Desktop asks you to save or confirm unsaved local changes first. The top toolbar shows Pull only when an editable local user project has a remote version and Server is connected; built-in projects do not provide this action.

When downloading a published Kanban project, the Desktop strictly reads the dependency lock pinned by the root version. It writes permitted included sources to separate sibling directories under the same parent and retains every project UUID. Before writing, Main verifies the root version, each dependency's exact version and source hash, and recomputes SHA-256 for every source package from its file paths and original bytes. Any mismatch stops the whole group write. A same-UUID project already in the parent directory is considered satisfied and is not overwritten; a directory occupied by another UUID blocks the write to avoid mixing projects. Included dependencies without source permission appear in the completion dialog. Submit a reason through the short-lived application link, then select Complete dependencies after approval. A local Kanban project shows Source project not downloaded for missing sources rather than pretending the source has no data.

Copy to Local Project requires every included dependency to be downloadable. Copying assigns new UUIDs to the entire group and atomically rewrites workflowCode.projectInfo.relatedProjects[].projectId between all copied projects. The option stays disabled while any dependency is missing. External relationships are not downloaded and keep their original UUIDs.

Theme and Layout

The workspace supports light, dark, and system themes. Right and bottom dock sizes, visibility, tab order, active tabs, and parts of input layout are local UI preferences isolated to each host project or ordinary folder on the current device. They are never written to project source or the remote server.

When parameter initialization or pre-send resolution fails, the workspace shows the full reason and relevant recovery guidance in the conversation content area. An old built-in Workflow Runtime suggests updating the Desktop; a missing project dependency suggests installing that package; a server-credential 401 suggests signing in again; a temporarily unavailable system AI service suggests checking the connection. Other resolver errors retain their original summary for troubleshooting. The error area has Retry, disables repeated clicks while retrying, and restores the current input and Send after success without closing or reopening the project.

At narrow widths, secondary top actions collapse to icon buttons with tooltips while the primary Publish action and both dock toggles remain available. Each Terminal tab owns an independent session and shows connection text plus a status indicator. After selecting output by drag, copy it with the header action or Ctrl+C / Cmd+C. Switching tabs, hiding a dock, moving a tab, or navigating away from the project page does not interrupt the terminal task; return to keep reading output. Only closing that Terminal tab ends its process. Restarting Desktop creates a new terminal for the same target rather than restoring the old process.

Next Step

After publication, open the Server Web console to manage versions, environment variables, Embed, Webhooks, and run logs from project details.