Workspace Studio

Workspace Studio is Core's browser surface for builders. It provides per-user branch-based editing, checkpoint releases, and merge controls. Organization-level configuration (agent profiles, channels, billing, integrations) lives in a separate Org Settings route.

Entry points

• /_host/app/workspace-studio — edit workspace source, review changes, merge to live
• /_host/app/org-settings — agent profiles, channels, MCP servers, billing, integrations, security

Branch-based authoring

Each builder gets an isolated git worktree at orgs/{orgId}/users/{userId}/workspace. Edits commit to the user's working branch. The branch picker in the top bar switches between preview branches and the live environment.

When a builder selects a preview branch, Workspace Studio:

1. Provisions an ephemeral Neon DB branch (forked from the preview branch, 7-day TTL)
2. Checks out the branch in the user's worktree
3. Loads the workspace source for that branch

If the DB branch has expired (TTL hit), it is automatically re-provisioned on the next checkout. The branch picker shows DB status badges: DB (active), DB expired, or nothing (not provisioned).

Tenant shell sidebar

In the live tenant workspace (outside Studio), the left sidebar groups navigation under two section labels — uppercase muted text, not clickable nav rows:

• Platform — host plugins shipped with Core
• Applications — tenant apps authored in workspace source

Labels are plain text only (no icon box on the label itself). Only the rows beneath them are clickable links.

Platform items use feature-colored icon wrappers from FEATURE_COLOR_STYLES:

• Agent — agents (brand)
• Workspace Studio — workspaceStudio (sky)
• Org Settings — accessControl (blue)

Applications are tenant Svelte apps discovered from src/apps/**/+<lower_snake_case>.svelte. Each filename owns its app ID, and each app row uses the customApps (slate) icon treatment.

Manifest view

Workspace Studio's Manifest browser summarizes the workspace contract without opening individual source files. Sections:

• Collections — data model modules
• Apps — registered tenant applications
• Automations — scheduled or event-driven jobs from src/automation/+<lower_snake_case>.ts. See Automations.
• Handlers — custom remote functions from src/remotes/+<lower_snake_case>.ts, called as api.invoke.<lower_snake_case>(…). Icon: function-square (custom function). See Handlers / remote functions.
• Environment — runtime configuration surfaced to the workspace

Use Manifest for orientation and quick counts; switch to the Editor tab to change source.

Checkpoints

Checkpoints are immutable, versioned workspace builds — a release capability of Workspace Studio, not a separate product surface. Each successful preview sync or merge-to-live produces a checkpoint: a frozen bundle (compiled apps, runtime, and migration SQL) stored in Core's artifact store. Preview branches track their latest built checkpoint in branch_db_map; production tracks the active checkpoint in tenant_workspace_head.

You manage checkpoints from the Review tab: inspect release history, compare source diffs, preview DDL, merge a preview branch to live, or roll production back to a prior checkpoint.

Release toolbar

Three toolbar actions drive the release loop:

1. Commit — persist open edits to the working branch, then run preview sync in one step: align the worktree to the branch tip, run a Vite build in an isolated sandbox, commit the built tree, apply DDL to the branch's preview Neon DB, and open or update a merge request. This creates or updates a preview checkpoint. Unsaved buffer edits must be saved before Commit runs.
2. Merge to live — rebase the preview branch onto main, run the unified deploy (build when needed, DDL validation, live migration), advance the live checkpoint, and mark the merge request as merged. Available from the toolbar or Review tab.
3. Rollback — restore production to a prior live checkpoint (Review → Checkpoints sidebar). Preview branches are not rolled back — Commit again from your branch if preview drifted.

On a successful merge, Core closes the preview branch (git ref + Neon dev DB), switches Studio back to Live, and production serves the merged checkpoint.

Review tab

The Review tab is where you inspect and ship checkpoints:

• Merge requests — open MRs with branch name, author, build status
• Diff viewer — side-by-side CodeMirror diff between working/preview/live/checkpoint sources
• DB migration preview — DDL that would be applied on merge-to-live
• Merge to live — disabled if the branch is not mergeable (main has diverged)
• Checkpoints — live release history with rollback action

Org Settings route

Organization-level configuration is separated from workspace source editing. The Org Settings route (/_host/app/org-settings) is not affected by branch switching. It contains:

• Agent — profiles (model, system prompt, tools, skills, default-for-web), channels (Telegram/WhatsApp), MCP servers
• General — organization settings
• Billing — subscription and usage
• Integrations — SSO and connectors
• Security — access control and audit

Release concurrency

Only one release operation runs per organization at a time. The merge-to-live button is disabled if main has diverged from the branch (the branch must be rebased first). Reload Studio if another builder synced or merged while you were editing.

Source edits vs org settings

Structural workspace changes — collections, apps, hooks, handlers, automations, seed policies — belong in workspace source (Workspace Studio). Organization-level configuration — agent personas, channel credentials, billing — belongs in Org Settings.