Workspaces

A workspace is a record that carries a complete interactive surface. It describes what a screen looks like, how its regions are laid out, which records feed it, and what the surface is allowed to do on your behalf. Your instance interprets that description at render time and shows you a working page.

Because a workspace is a record, you do not install software to get one. You emit the record — or someone shares it with you — and the surface is live. There is no build step, no plugin to compile, no runtime to restart. A new workspace is one core.workspace.v1 record away.

Every fresh instance boots with a Tasks workspace already installed, so your instance is never a blank screen. Everything below — the shape, the catalog, the lifecycle — is the same whether you are looking at that starter workspace or one you wrote yourself.

The shape

A workspace body is a record of kind core.workspace.v1. It has three parts: meta (what the workspace is), regions (what it shows), and lifecycle (where it is in its life).

{
  "kind": "core.workspace.v1",
  "schema_version": "2.0.0",
  "meta": {
    "slug": "tasks",
    "title": "Tasks",
    "icon": "check-square",
    "rail": true,
    "shell": "workspace",
    "defaults": { "bucket": "all" },
    "capabilities": {
      "emit": [ { "act": "INTEND", "kind": "core.task" } ],
      "navigate": "same-origin"
    }
  },
  "regions": {
    "header": { "srp": "0.7", "root": { } },
    "body":   { "srp": "0.7", "root": { } }
  },
  "lifecycle": "published"
}

meta — what the workspace is

regions — what it shows

regions is a map. Each key is a slot in the layout — header, body, rail, browse, status, aside — and each value is a projection document: a declarative description of UI built from a small set of nodes (tables, forms, text, charts, and so on). See Projections for the document format and React components for the nodes a host renders.

A projection document carries query bindings, not baked-in data. The workspace record stays static and content-addressed; the live records it displays are resolved when the surface renders. The same workspace, opened by two different people, shows each of them their own records folded the same way.

lifecycle — where it is in its life

One of draft, published, or archived. Lifecycle is declared by whoever emits the record. Changing it means emitting a new record — see Installing & managing workspaces.

Viewing in Studio

Open a workspace — or any content thread, such as a note — in Studio and it renders its content directly. A view switcher lets you read the same thread three ways without changing anything:

• Document — the rendered document: the workspace's regions, or a note's formatted text. This is the default.
• Outline — just the heading hierarchy, for jumping around a long document.
• Records — the underlying records the document is folded from, shown unreduced. The document is a view of these records; this lens shows the ground truth behind it.

Switching views never edits the thread — each is a different reading of the same records. A thread someone else has made public renders the same way for you, read-only.

Capabilities

meta.capabilities is the ceiling on what a workspace may do. It is part of the record body, so it is fixed the moment the workspace is content- addressed — a workspace cannot quietly grant itself new powers.

Anything a workspace tries that is not declared here is refused by the host. This is what makes it safe to install a workspace someone else wrote: you can read its capabilities block before you install it and know exactly what it can touch.

How workspaces relate to records

Records are the foundation. Threads are coordination contexts. Workspaces sit on top — a workspace says "gather records like this, lay them out like that, and let me do these things."

A workspace does not store data. It describes how to view and act on data. This is why a workspace is content-addressed: its identity is the SHA-256 of its canonical JSON. Two people running the "same" workspace are running literally the same description, byte-for-byte verified.

What is deliberately not in a workspace body:

• A process model — a workspace does not run; your instance interprets it.
• Storage configuration — your records live wherever you keep them.
• Authentication wiring — handled by the instance's identity layer.
• Secrets — a workspace never carries keys.

The catalog

Every instance keeps its workspaces on a single well-known thread — the workspace catalog. Installing a workspace emits its record there; listing your workspaces folds that thread.

Discovery is an ordinary query: ask your instance for records of kind core.workspace.v1. The catalog is not a separate service or a gatekept app store — it is records, queried like any other records.

spl workspace list

A workspace published on another instance reaches yours over the Graph — Syncropel's cross-instance discovery pattern. The Graph carries a workspace between instances; your catalog is where it lands once you install it.

See Installing & managing workspaces for the full command surface.

What's next

• Instance chrome — the navigation rail, side panels, and footer that frame your workspaces, also carried as a record.
• Installing & managing workspaces — install, list, show, update, archive, and the lifecycle field.
• Authoring a workspace — write your own core.workspace.v1 document from scratch.
• Tutorial: Build your first workspace — install the starter, then write and install one of your own.
• Projections — the projection-document format the regions are written in.
• core.workspace.v1 schema — the machine-readable body schema.