Workspaces, types and packages

Workspaces

A workspace is a named tree of nodes with its own allowed node types and its own access control. Studio ships with, among others:

A trigger always names the workspace it watches. Paths are workspace-relative: the mail at /support-desk/mail/inbox/ABC in workplace is written workplace:/support-desk/mail/inbox/ABC when both are needed.

Node types, archetypes, element types

• A node type is the schema: which properties exist and how they are typed and indexed. raisin:Mail declares subject, from_address, conversation_id, body_text and so on.
• An archetype is a page template on top of a node type: which fields the editor shows, in what layout, and which frontend component renders it.
• An element type is a composable block placed inside a page’s content sections.

For automations the practical point is: fields are declared, so the editor can offer them. When a trigger watches studio:Page, the Insert menu in every later step offers the page’s real fields — title, description, slug — with their titles and types. You never guess a property name.

Packages

Studio is a RaisinDB application package: a folder with a manifest.yaml that declares node types, archetypes, element types, workspaces, functions, triggers, agents and seed content, installed into a repository with the raisindb CLI.

Your own work is a package too, installed beside Studio in the same repository. The relevant folders:

my-package/
├── manifest.yaml
├── nodetypes/                 # your schemas
├── archetypes/                # your page templates
├── content/
│   ├── automations/<slug>/.node.yaml      # automations, one folder each
│   └── functions/
│       ├── agents/<slug>/.node.yaml       # AI agents
│       └── lib/<your-ns>/<name>/          # server functions (index.js + .node.yaml)
└── .raisin-sync.yaml          # which content you own on re-sync

Two commands matter:

# schema, functions, agents, new content — registers types and creates what is missing
raisindb deploy ./my-package --repo <repo> --install

# content you edited after the first install (automations, agents, function bodies)
cd my-package && raisindb sync . --push --force --yes --repo <repo> --server <url>

deploy --install creates what does not exist and updates schemas. Whether it replaces content that already exists is decided by the package’s .raisin-sync.yaml policy, so name the roots you own there with mode: replace and leave everything else on skip. That is also what protects a customer’s edits made in Studio from being overwritten by your next release.

What an automation can rely on

• The subject: the node whose event started the run, resolved by a prelude step every automation gets for free. It exposes the node’s fields, its path, its workspace and its type.
• Function output schemas: every library step and every function you ship with an output_schema has its fields offered to later steps by name.
• Agent answers: an agent step that declares “what it must return” has those fields offered too.
• Durable runs: a run that waits for a person keeps waiting across deploys and restarts, and resumes exactly where it stopped.