@unoverse-platform/studio 0.1.48 → 0.1.49

package/local/sample-nodes/samples/README.md

@@ -0,0 +1,62 @@
+# Sample nodes
+
+Two worked examples of the Unoverse node format, one of each kind. They are real,
+working nodes: wire them into a workflow and they run.
+
+| Node | Kind | What it teaches |
+|---|---|---|
+| `nodes/SampleWeather` | `PromiseNode` | Two chained calls, a config form, computed outputs. No API key. |
+| `nodes/SampleChatStream` | `CallbackNode` | Streaming, and how credentials work. Needs an OpenAI key. |
+
+## Where to start
+
+Read `SampleWeather` first, file by file, in this order:
+
+1. `node.yaml` says what the node IS: its identity, its kind, and when a planner
+   should pick it.
+2. `interface.yaml` says what it CONNECTS TO: inputs, outputs. Output names become
+   what someone types in a template later, so they are named for what they carry.
+3. `config.yaml` is the settings form a builder sees on the canvas. It is a JSON
+   schema; the platform draws the form from it.
+4. `api/run.yaml` is the calls the node makes, always a list, each entry named.
+5. `api/events.yaml` is everything that leaves the node: one row per output.
+6. `test.yaml` is a fixture that runs against the real service.
+
+Then read `SampleChatStream` for the two things weather cannot show you: a reply
+that arrives as a stream of events rather than one body, and a call that has to
+prove itself to the service with a credential.
+
+## Running them
+
+Open Studio (`unoverse studio`) and go to the Nodes screen. Pick a node, load its
+sample, and run it. Running is the only proof: a node that lints but has never run
+is not done.
+
+`SampleWeather` runs as-is. `SampleChatStream` needs a key: credentials are read
+from your `.env` as `<CREDENTIAL>_<FIELD>` in upper snake case, so
+`openAICredential.apiKey` is:
+
+```
+OPENAI_API_KEY=sk-...
+```
+
+The credential FILE in this package (`credentials/openAICredential.yaml`) declares
+only the shape. No value ever lives in a node file, which is why the folder is safe
+to commit and to share.
+
+## Making your own
+
+Copy the closer of the two samples into a new folder under `nodes/<your-package>/`
+and change it one file at a time, running as you go. The guide behind every file:
+
+- The format in full: https://docs.unoverse.ai/nodes/manifest-nodes
+- One answer or many: https://docs.unoverse.ai/nodes/node-types
+- Credentials: https://docs.unoverse.ai/nodes/credentials
+- The settings form: https://docs.unoverse.ai/nodes/config-schema
+- Paging, batching, polling: https://docs.unoverse.ai/nodes/calls-that-loop
+- Getting picked by the planner: https://docs.unoverse.ai/nodes/node-discoverability
+- Testing: https://docs.unoverse.ai/nodes/testing-nodes
+- When something goes wrong: https://docs.unoverse.ai/nodes/troubleshooting
+
+The condensed rulebook, written for coding agents and just as useful to people:
+https://docs.unoverse.ai/nodes/CLAUDE.md

package/local/sample-nodes/samples/credentials/openAICredential.yaml

@@ -0,0 +1,36 @@
+# THE SHAPE OF A CREDENTIAL, NEVER ITS VALUE.
+#
+# This file declares what an OpenAI credential LOOKS LIKE: which fields it has, which
+# are secret, what to show in the form that collects it. It never holds a key. Values
+# live where they already live: encrypted in the database on a deployed universe, and
+# in your own .env when running locally.
+#
+# Locally the runner reads .env as <CREDENTIAL>_<FIELD> in upper snake case, so
+# openAICredential.apiKey is the .env line:
+#
+#   OPENAI_API_KEY=sk-...
+#
+# Nodes reference this shape BY NAME. At run time every credential in the workflow is
+# available keyed by name, and a call selects the one it means:
+#
+#   credential:
+#     scheme: bearer
+#     token: "{{ credentials.openAICredential.apiKey }}"
+#
+# Full guide: https://docs.unoverse.ai/nodes/credentials
+
+name: openAICredential
+displayName: OpenAI
+description: Credentials for the OpenAI API
+documentationUrl: https://platform.openai.com/api-keys
+
+properties:
+  - name: apiKey
+    displayName: API Key
+    type: string
+    required: true
+    # `secret: true` is what keeps the value write-only: it is stored encrypted and
+    # never echoed back into any form or log.
+    secret: true
+    description: Your OpenAI API key
+    placeholder: sk-...

package/local/sample-nodes/samples/nodes/SampleChatStream/api/events.yaml

@@ -0,0 +1,23 @@
+# ONE ROW PER OUTPUT, in interface.yaml order. On a streaming call each row names the
+# event type it fires on with `match`, and there are two rows here because a streaming
+# node answers twice: continuously while writing, and once when done.
+# https://docs.unoverse.ai/nodes/node-types
+
+# THE LIVE FEED. Two settings here are worth copying into any streaming node you
+# write. `accumulate: true` emits the reply SO FAR rather than the newest fragment: a
+# stream of single words is almost never what a consumer wants. `throttleMs` bounds
+# how often it emits, or a long answer becomes hundreds of events; nothing held back
+# is lost, whatever is pending is flushed when the run ends.
+- emit: stream
+  from: response
+  match: response.output_text.delta
+  value: "return response.delta"
+  accumulate: true
+  throttleMs: 200
+
+# THE SETTLED ANSWER. `from: complete` fires once at the end, over everything the
+# node emitted, which is how a streaming node also produces one finished value.
+# `.at(-1)` and not `.pop()`: expressions are sandboxed and nothing mutates.
+- emit: text
+  from: complete
+  value: "return events.filter(e => e.emit === 'stream').map(e => e.value).at(-1) ?? ''"

package/local/sample-nodes/samples/nodes/SampleChatStream/api/run.yaml

@@ -0,0 +1,53 @@
+# ONE CALL, MANY ANSWERS. `transport: sse` says the reply arrives as a stream of
+# events rather than one body, which is what makes this node a CallbackNode.
+# https://docs.unoverse.ai/nodes/node-types
+
+- name: generate
+  method: POST
+  url: https://api.openai.com/v1/responses
+
+  # HOW THE NODE PROVES ITSELF TO THE VENDOR. This is OUTBOUND authentication, and it
+  # is a different thing from node.yaml's `auth`, which is who may RUN the node.
+  #
+  # `scheme: bearer` is an executor capability: the executor attaches the header, so
+  # no manifest ever handles the secret itself. The token path selects the credential
+  # BY NAME from the shapes this package declares. Note also that api.openai.com is
+  # in package.yaml's allowedHosts; a manifest cannot send this token anywhere that
+  # list does not name. https://docs.unoverse.ai/nodes/credentials
+  credential:
+    scheme: bearer
+    token: "{{ credentials.openAICredential.apiKey }}"
+
+  body:
+    model: "{{ config.model }}"
+    # A REQUEST WHOSE SHAPE CHANGES WITH THE SETTINGS. The system message exists only
+    # when the builder wrote one: sending an empty message is a 400 from the vendor,
+    # so the body is built by an expression rather than a fixed template. A field
+    # that is one "{{ path }}" stays a template; a field that must DECIDE something
+    # is an expression.
+    input: >-
+      return [
+        config.systemPrompt
+          ? { type: "message", role: "system", content: config.systemPrompt }
+          : null,
+        { type: "message", role: "user", content: config.prompt }
+      ].filter(Boolean)
+    max_output_tokens: "{{ config.maxTokens }}"
+    stream: true
+
+  timeoutMs: 300000
+
+  retry:
+    attempts: 3
+    backoff: exponential
+    on: [429, 500, 502, 503, 504]
+
+  # The reply's framing belongs to the call: it streams server-sent events until the
+  # terminator line.
+  transport: sse
+  terminator: "[DONE]"
+
+  # A 200 carrying an error body must not read as success.
+  error:
+    when: "return response.type === 'response.failed'"
+    message: "return response.response.error.message"

package/local/sample-nodes/samples/nodes/SampleChatStream/config.yaml

@@ -0,0 +1,44 @@
+# THE SETTINGS FORM. https://docs.unoverse.ai/nodes/config-schema
+
+configSchema:
+  type: object
+  required: [model, prompt]
+
+  properties:
+    model:
+      type: string
+      title: Model
+      description: The model that writes the reply
+      enum: [gpt-5.6, gpt-5.6-terra, gpt-5.6-luna]
+      default: gpt-5.6-terra
+      "ui:widget": select
+
+    prompt:
+      type: string
+      title: Prompt
+      description: >-
+        What to ask. A template field, so values from earlier nodes compose in
+        directly, e.g. Summarize this update. {{signal.weather1.summary}}
+      default: ""
+      ui:field: template
+
+    systemPrompt:
+      type: string
+      title: System Prompt
+      description: >-
+        Standing instructions for every run: the model's role, tone and limits.
+        Optional. NEVER paste instruction text into a manifest file itself; shared
+        instruction copy belongs in the prompt block library and is referenced here
+        as {{prompt.<blockName>}}, so it keeps tracking the block when the block is
+        edited.
+      default: ""
+      ui:field: template
+
+    maxTokens:
+      type: number
+      title: Max output tokens
+      description: The ceiling on how long the reply may run
+      default: 1024
+      minimum: 16
+      maximum: 32768
+"ui:order": [model, prompt, systemPrompt, maxTokens]

package/local/sample-nodes/samples/nodes/SampleChatStream/interface.yaml

@@ -0,0 +1,29 @@
+# WHAT THIS NODE CONNECTS TO. Two outputs is the signature streaming pair: the live
+# feed for whoever wants to watch, and the settled answer for whoever wants the
+# result. Wire `stream` to a streaming text component and the reply appears as it is
+# written; wire `text` onward and downstream nodes get one finished string.
+
+inputs:
+  - name: signal
+    type: object
+    description: Data from previous nodes that can be referenced in templates
+
+outputs:
+  - name: stream
+    type: object
+    description: The reply so far, emitted repeatedly while the model writes
+
+  - name: text
+    type: string
+    description: The complete reply, emitted once at the end
+
+# THE CREDENTIAL THIS NODE NEEDS, referenced by NAME. The shape it points at is
+# credentials/openAICredential.yaml in this package: fields, which are secret, what
+# the collecting form shows. The VALUE is never in any file. On a universe it is
+# entered once and stored encrypted; locally it is read from .env as
+# OPENAI_API_KEY. https://docs.unoverse.ai/nodes/credentials
+credentials:
+  - name: openAICredential
+    required: true
+    displayName: OpenAI API
+    description: How this node authenticates to OpenAI

package/local/sample-nodes/samples/nodes/SampleChatStream/node.yaml

@@ -0,0 +1,39 @@
+# WHAT THIS NODE IS: the second worked example, a CallbackNode.
+#
+# Read SampleWeather first. This node adds the two things weather cannot show you:
+# a reply that STREAMS in as many events instead of settling once, and a call that
+# must prove itself to the service with a CREDENTIAL.
+# https://docs.unoverse.ai/nodes/node-types
+
+type: SampleChatStream
+
+# A node that keeps answering. Lint checks this rather than trusting it: the LAST
+# call in api/run.yaml has `transport: sse`, so declaring PromiseNode here would be
+# an error naming exactly that contradiction.
+kind: CallbackNode
+
+name: Chat Stream Sample
+category: AI
+color: "#7C5CFF"
+
+description: A model reply streamed word by word as it is written, the simplest streaming shape
+
+# Ranked against the user's own words, so: outcome first, disqualifiers as
+# properties of the work, wiring fact last, and never the name of another node.
+# https://docs.unoverse.ai/nodes/node-discoverability
+whenToUse: >-
+  A worked example for learning the streaming node shape: send a prompt, watch the
+  reply arrive word by word, and read the manifest that made it happen. A single
+  pass with no tools and no memory, so real workloads that need tool calls,
+  reasoning control or multi-turn state want a fuller model node.
+
+# WHO MAY RUN THIS. Compulsory, and separate from the credential below: this block
+# is who may press the button, the credential is how the node proves itself to the
+# vendor once pressed. https://docs.unoverse.ai/nodes/who-can-run-it
+auth:
+  required: false
+
+capabilities:
+  # A model completion is non-deterministic: re-running is correct behaviour, and
+  # reusing a previous answer would be wrong, not thrifty.
+  cacheable: false

package/local/sample-nodes/samples/nodes/SampleChatStream/test.yaml

@@ -0,0 +1,21 @@
+# THE PROOF. This fixture calls the real API, so it needs your key in .env first:
+#
+#   OPENAI_API_KEY=sk-...
+#
+# (The name comes from the credential shape: openAICredential.apiKey, upper snake
+# case, so OPENAI_API_KEY.) Then run it from Studio's Nodes screen, or:
+#   unoverse node test SampleChatStream
+#
+# Assert the shape, never exact words: the model will not say the same thing twice.
+# https://docs.unoverse.ai/nodes/testing-nodes
+
+testData:
+  config:
+    model: gpt-5.6-luna
+    prompt: Say hello in one short sentence.
+    systemPrompt: ""
+    maxTokens: 64
+  inputs:
+    signal: {}
+  expect:
+    text: "return output.text.length > 0"

package/local/sample-nodes/samples/nodes/SampleWeather/api/events.yaml

@@ -0,0 +1,41 @@
+# EVERYTHING THAT LEAVES THIS NODE: one row per output connector, in the SAME ORDER
+# interface.yaml declares them. Lint holds the order and the coverage: an output with
+# no row here stays silently empty, which is the first thing to check when a
+# downstream template resolves to nothing.
+#
+# In these expressions `response` is the LAST call's reply (the forecast) and every
+# call is also readable by name as `calls.<name>`. The sandbox allows no mutation:
+# `.at(-1)` not `.pop()`, `.toSorted()` not `.sort()`.
+# https://docs.unoverse.ai/nodes/signal-routing
+
+# The full picture, shaped HERE so the component that shows it stays dumb. Anything
+# computed (rounding, pairing the daily arrays up, turning code 61 into "light rain")
+# is this node's job: definitions in design/ never compute.
+- emit: weather
+  value: >-
+    return {
+      place: calls.geocode.results[0].name,
+      country: calls.geocode.results[0].country || "",
+      unit: response.current_units.temperature_2m,
+      current: {
+        temperature: Math.round(response.current.temperature_2m),
+        feelsLike: Math.round(response.current.apparent_temperature),
+        humidity: response.current.relative_humidity_2m,
+        windSpeed: response.current.wind_speed_10m,
+        condition: helpers.describe(response.current.weather_code)
+      },
+      daily: response.daily.time.map((date, i) => ({
+        date: date,
+        high: Math.round(response.daily.temperature_2m_max[i]),
+        low: Math.round(response.daily.temperature_2m_min[i]),
+        condition: helpers.describe(response.daily.weather_code[i])
+      }))
+    }
+
+# The one-liner, for dropping straight into a sentence or a headline. Same facts,
+# second shape: emitting both is cheaper than making every consumer re-derive one.
+- emit: summary
+  value: >-
+    return Math.round(response.current.temperature_2m) + "° and " +
+      helpers.describe(response.current.weather_code) + " in " +
+      calls.geocode.results[0].name

package/local/sample-nodes/samples/nodes/SampleWeather/api/run.yaml

@@ -0,0 +1,51 @@
+# THE CALLS THIS NODE MAKES. Always a list, each entry named, even for one call.
+#
+# This node is the "two calls, where the second uses the first" shape: a person types
+# a city NAME, the forecast API wants COORDINATES, so the node looks the place up and
+# then asks about it. A later call reads an earlier reply as `calls.<name>`. The node
+# orchestrates both behind one clean answer; the workflow never sees the seam.
+# https://docs.unoverse.ai/nodes/manifest-nodes
+
+# CALL 1: the place, by name. Open-Meteo's geocoder, no key needed.
+- name: geocode
+  method: GET
+  url: https://geocoding-api.open-meteo.com/v1/search
+  # `transport: json` says the reply arrives as ONE body. The streaming sample next
+  # door uses `sse`, where the reply arrives as many events.
+  transport: json
+  query:
+    name: "{{ config.city }}"
+    count: "1"
+
+  # ALWAYS write `error` where the API can answer 200 with a failure body. An unknown
+  # place is a 200 with no results, and without this rule it would flow downstream as
+  # an empty forecast instead of failing here with the true reason.
+  error:
+    when: "return !(response.results && response.results.length)"
+    message: >-
+      return 'No place named "' + config.city + '" was found. Check the spelling, or
+      try a larger town nearby.'
+
+# CALL 2: the forecast, at the coordinates call 1 found. Dot paths into an earlier
+# reply, and array indexes are dot segments too: `results.0.latitude`, never brackets.
+- name: forecast
+  method: GET
+  url: https://api.open-meteo.com/v1/forecast
+  transport: json
+  query:
+    latitude: "{{ calls.geocode.results.0.latitude }}"
+    longitude: "{{ calls.geocode.results.0.longitude }}"
+    current: temperature_2m,apparent_temperature,relative_humidity_2m,wind_speed_10m,weather_code
+    daily: temperature_2m_max,temperature_2m_min,weather_code
+    forecast_days: "{{ config.days }}"
+    temperature_unit: "{{ config.units }}"
+    timezone: auto
+
+  timeoutMs: 30000
+
+  # Retry only what retrying can fix: rate limits and transient server errors. A 404
+  # or a bad request will fail identically every time, so it is not in the list.
+  retry:
+    attempts: 3
+    backoff: exponential
+    on: [429, 500, 502, 503, 504]

package/local/sample-nodes/samples/nodes/SampleWeather/config.yaml

@@ -0,0 +1,39 @@
+# THE SETTINGS FORM. This is a JSON schema; the platform draws the canvas form
+# from it. A `description` says what the setting DOES, not what it is called.
+# Every field type, and the run context that resolves them:
+# https://docs.unoverse.ai/nodes/config-schema
+
+configSchema:
+  type: object
+  required: [city]
+
+  properties:
+    city:
+      type: string
+      title: City
+      description: >-
+        The place to report on. A city or town name, in any language. This is a
+        template field, so a value from an earlier node works here too, e.g.
+        {{signal.inputtrigger1.output.city}}
+      default: ""
+      # `ui:field: template` is what lets a workflow supply the value at run time
+      # instead of it being fixed at build time. Every value the workflow supplies
+      # needs it.
+      ui:field: template
+
+    days:
+      type: number
+      title: Forecast days
+      description: How many days of outlook to fetch, today included
+      default: 3
+      minimum: 1
+      maximum: 7
+
+    units:
+      type: string
+      title: Units
+      description: The temperature scale everything is reported in
+      enum: [celsius, fahrenheit]
+      default: celsius
+      "ui:widget": select
+"ui:order": [city, days, units]

package/local/sample-nodes/samples/nodes/SampleWeather/interface.yaml

@@ -0,0 +1,24 @@
+# WHAT THIS NODE CONNECTS TO: the sockets on the box a builder sees on the canvas.
+#
+# Output names become what someone types in a template later
+# ("{{signal.weather1.summary}}"), so they are named for what they CARRY.
+# https://docs.unoverse.ai/nodes/signal-routing
+
+inputs:
+  - name: signal
+    type: object
+    description: Data from previous nodes that can be referenced in templates
+
+outputs:
+  # The full picture, for binding into a component field by field.
+  - name: weather
+    type: object
+    description: Place, current conditions and the daily outlook, as one object
+
+  # The one-line version, for dropping straight into text.
+  - name: summary
+    type: string
+    description: A single sentence, like "18° and partly cloudy in Lisbon"
+
+# No credentials block: Open-Meteo asks for no key. See SampleChatStream for a node
+# that needs one.

package/local/sample-nodes/samples/nodes/SampleWeather/node.yaml

@@ -0,0 +1,56 @@
+# WHAT THIS NODE IS. The one required file.
+#
+# A worked example of a PromiseNode: it makes its calls, settles once, and hands on
+# one answer. Read this folder in order: node.yaml (identity), interface.yaml
+# (connections), config.yaml (the settings form), api/run.yaml (the calls),
+# api/events.yaml (what leaves), test.yaml (the proof).
+# Format in full: https://docs.unoverse.ai/nodes/manifest-nodes
+
+# The IDENTITY a saved workflow stores. Renaming it orphans every workflow that
+# uses the node, so never rename lightly.
+type: SampleWeather
+
+# One answer or many? A node that calls, settles and hands on ONE reply is a
+# PromiseNode. Lint checks this against the transport of the LAST call in
+# api/run.yaml (json settles; sse or ws streams).
+# https://docs.unoverse.ai/nodes/node-types
+kind: PromiseNode
+
+name: Weather Sample
+# The JOB, not the implementation, and from the platform's closed list: lint
+# refuses an invented category, because the canvas palette groups by these.
+category: Storage & Data
+color: "#4A90D9"
+
+description: Current conditions and a short forecast for any city, from Open-Meteo, no API key needed
+
+# WHENTOUSE DECIDES WHETHER THIS NODE IS EVER OFFERED. A planner ranks nodes by
+# embedding this text against the user's own words: outcome first, then what
+# disqualifies it as a property of the work, never the name of another node.
+# Read https://docs.unoverse.ai/nodes/node-discoverability before writing yours.
+whenToUse: >-
+  Get the weather for a named place: current temperature, wind, humidity and a
+  day-by-day outlook, ready to show to a person or hand to a model. Takes a city or
+  town name, not coordinates. It reports observed forecasts only; it cannot answer
+  historical climate questions.
+
+# WHO MAY RUN THIS. Compulsory on every node. `required: false` adds no requirement
+# of its own: the node runs for whoever the workflow's trigger admitted. It does NOT
+# mean public; the trigger still owns the door.
+# https://docs.unoverse.ai/nodes/who-can-run-it
+auth:
+  required: false
+  # Role-based access is one line, and naming a role implies required: true. But a
+  # role HERE is only for a claim the platform itself defines (marketplace:publish),
+  # because a published node cannot know what roles a stranger's identity provider
+  # mints. A business role like finance:approve belongs to the workflow builder: the
+  # platform puts a "Require sign-in" / "Require role" section on every node's
+  # settings form, so the person who knows their deployment's role names sets one
+  # per box. You never author those fields.
+  # role: marketplace:publish
+
+capabilities:
+  # A forecast changes hour to hour, so re-running is the correct behaviour and a
+  # cached answer would be stale, not thrifty. `cacheable: true` is ONLY for
+  # idempotent, side-effect-free reads of stable data.
+  cacheable: false

package/local/sample-nodes/samples/nodes/SampleWeather/test.yaml

@@ -0,0 +1,24 @@
+# A FIXTURE THAT RUNS, against the real service. Every node needs one: a node that
+# lints but has never run is not done, because only a run proves the manifest
+# describes the real API rather than something merely coherent.
+#
+# Run it from Studio's Nodes screen (Load sample, then Run), or:
+#   unoverse node test SampleWeather
+#
+# Assert the SHAPE, never exact words: the temperature in Lisbon is not a constant.
+# https://docs.unoverse.ai/nodes/testing-nodes
+
+testData:
+  config:
+    city: Lisbon
+    days: 3
+    units: celsius
+  inputs:
+    signal: {}
+  expect:
+    weather: >-
+      return output.weather.place === "Lisbon" &&
+        typeof output.weather.current.temperature === "number" &&
+        typeof output.weather.current.condition === "string" &&
+        output.weather.daily.length === 3
+    summary: "return output.summary.length > 0 && output.summary.includes('Lisbon')"

package/local/sample-nodes/samples/package.yaml

@@ -0,0 +1,41 @@
+# THE PACKAGE ENVELOPE. Every node package has exactly one of these.
+#
+# A node is a folder of YAML that the platform interprets. There is no TypeScript,
+# no package.json, no build step and no publish step. The full format:
+# https://docs.unoverse.ai/nodes/package-marketplace
+#
+# This package holds two worked examples, one of each node kind:
+#
+#   nodes/SampleWeather/     a PromiseNode.  Two chained calls, one settled answer.
+#   nodes/SampleChatStream/  a CallbackNode. A reply that streams in as it is written.
+#
+# Read them in that order. Then read the guide they follow:
+# https://docs.unoverse.ai/nodes/overview
+
+name: samples
+displayName: Sample Nodes
+description: Two worked examples for learning the node format, one PromiseNode and one CallbackNode
+version: 0.1.0
+category: productivity
+
+features:
+  - Weather for any city, no API key needed
+  - Streaming chat completion, showing how credentials work
+
+# THE ONLY HOSTS THIS PACKAGE'S NODES MAY CALL. Deny by default, https only.
+#
+# A manifest cannot execute code, but without this list it could still say "send this
+# credential to evil.example", which is exfiltration with no code at all. One short
+# reviewable list is what makes a node package safe to accept from someone else.
+# The executor refuses any request to a host not named here.
+allowedHosts:
+  - geocoding-api.open-meteo.com
+  - api.open-meteo.com
+  - api.openai.com
+
+# EXECUTOR CAPABILITIES these manifests depend on. A deploy is refused if the target
+# universe's executor cannot satisfy them, so a manifest can never name a capability
+# that only exists on a newer executor.
+requires:
+  credential: [bearer]
+  transport: [json, sse]

package/local/sample-nodes/samples/shared/helpers.yaml

@@ -0,0 +1,27 @@
+# NAMED HELPERS. Any expression in this package can call these as helpers.<name>.
+#
+# An expression past a few lines gets a name here instead. A helper sees ONLY its
+# arguments and its sibling helpers, never config or credentials or the caller's
+# scope: same sandbox, no extra authority.
+# https://docs.unoverse.ai/nodes/manifest-nodes
+
+helpers:
+  # WMO weather interpretation codes, as words. Open-Meteo answers with a numeric
+  # `weather_code`; a person (and a component) wants "light rain". This mapping is
+  # LOGIC, and logic lives in the node: a definition in design/ must never compute,
+  # so the node sends words and the component just shows them.
+  describe:
+    args: [code]
+    body: >-
+      return ({
+        0: "clear skies", 1: "mainly clear", 2: "partly cloudy", 3: "overcast",
+        45: "fog", 48: "freezing fog",
+        51: "light drizzle", 53: "drizzle", 55: "heavy drizzle",
+        56: "freezing drizzle", 57: "heavy freezing drizzle",
+        61: "light rain", 63: "rain", 65: "heavy rain",
+        66: "freezing rain", 67: "heavy freezing rain",
+        71: "light snow", 73: "snow", 75: "heavy snow", 77: "snow grains",
+        80: "light showers", 81: "showers", 82: "heavy showers",
+        85: "snow showers", 86: "heavy snow showers",
+        95: "a thunderstorm", 96: "a thunderstorm with hail", 99: "a thunderstorm with heavy hail"
+      })[code] || "changeable weather"

package/local/scaffold.mjs

@@ -84,6 +84,16 @@ export function createFirstProject(home, name) {
   const root = createProject(home, name);
   for (const d of ["prompts/skills", "prompts/blocks", "nodes"]) mkdirSync(join(home, d), { recursive: true });
 
+  // Two worked example nodes (sample-nodes/samples: a PromiseNode and a CallbackNode,
+  // heavily commented, linking docs.unoverse.ai/nodes), so `nodes/` is never an empty
+  // folder with no hint of what goes in it. Copied only when absent: these are the
+  // developer's files to edit or delete, and a later scaffold run must never put back
+  // what they threw away or overwrite what they changed.
+  const samples = join(dirname(fileURLToPath(import.meta.url)), "sample-nodes/samples");
+  if (existsSync(samples) && !existsSync(join(home, "nodes/samples"))) {
+    cpSync(samples, join(home, "nodes/samples"), { recursive: true });
+  }
+
   // The Claude Code authoring skills, so "open the folder and describe what you want"
   // works in every Studio project from its first minute. Vendored into the published
   // app (vendor/skills, written by prepack from the monorepo's .claude/skills, the one

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unoverse-platform/studio",
-  "version": "0.1.48",
+  "version": "0.1.49",
   "type": "module",
   "description": "Unoverse Studio: the local authoring app. Reads your own rx/ folder, no backend.",
   "scripts": {

package/screens/AtomsView.tsx

@@ -127,17 +127,27 @@ export function AtomsView({ theme }: { theme: ResolvedTheme }) {
   const uri = useMemo(() => (selected ? `unoverse://atoms/${slug(selected)}` : ""), [selected]);
 
   return (
-    <div className="grid min-h-0 flex-1 grid-cols-[190px_1fr] overflow-hidden">
+    <div className="grid min-h-0 flex-1 grid-cols-[240px_1fr] overflow-hidden">
       {/* NAVIGATOR */}
       <nav className="flex min-h-0 min-w-0 flex-col overflow-auto border-r border-gray-700 bg-[#1b2129] p-2">
         {atoms.length === 0 && (
           <div className="p-2 text-xs text-gray-400">No atoms — restart the Unoverse server so /dev/atoms is available.</div>
         )}
+        {/* Atoms are ALL base tier (the one shared home): say so once at the top,
+            matching the Components sidebar's Base divider. */}
+        {atoms.length > 0 && (
+          <div className="mb-1 px-2 pt-1 text-[10px] font-semibold uppercase tracking-wider text-gray-300">
+            Base <span className="font-normal normal-case tracking-normal text-gray-500">· installed, read-only</span>
+          </div>
+        )}
         {groups.map((g) => (
           <div key={g.label} className="mb-2">
-            <div className="px-2 py-1 text-[10px] font-semibold uppercase tracking-wider text-gray-400">
-              {g.label}
-              <span className="ml-1.5 font-normal text-gray-500">{g.atoms.length}</span>
+            <div className="mb-1 mt-1 flex items-center gap-2 px-2">
+              <span className="text-[10px] font-medium uppercase tracking-[0.14em] text-gray-400">
+                {g.label}
+                <span className="ml-1.5 font-normal lowercase tracking-normal text-gray-500">{g.atoms.length}</span>
+              </span>
+              <span className="h-px flex-1 bg-gradient-to-r from-gray-500/40 to-transparent" />
             </div>
             {g.atoms.map((a) => (
               <button

package/screens/ComponentsView.tsx

@@ -368,15 +368,21 @@ export function ComponentsView({ theme, org = "all" }: { theme: ResolvedTheme; o
     store.apply({ type: "COMPONENT_DATA", chatId: CHAT_ID, nodeId: selected, data: { [key]: val } });
   };
 
+  // ONE catalog, grouped by CATEGORY — a project's card variants belong beside the
+  // base cards, where someone looking for "a card" will look. OWNERSHIP is a per-item
+  // mark, not a section: the org tag says "yours, editable"; untagged means base
+  // (installed, read-only — the Code view's badge carries the detail). Within a
+  // category the developer's own components list first.
   const byCategory = Object.entries(
     components.reduce<Record<string, ComponentDef[]>>((acc, c) => {
       (acc[c.category ?? "Uncategorized"] ??= []).push(c);
       return acc;
     }, {}),
   ).sort(([a], [b]) => a.localeCompare(b));
+  for (const [, items] of byCategory) items.sort((a, b) => (a.org ? 0 : 1) - (b.org ? 0 : 1));
 
   return (
-    <div className="grid min-h-0 flex-1 grid-cols-[190px_1fr] overflow-hidden">
+    <div className="grid min-h-0 flex-1 grid-cols-[240px_1fr] overflow-hidden">
       {/* NAVIGATOR */}
       <nav className="flex min-h-0 min-w-0 flex-col overflow-auto border-r border-gray-700 bg-[#2c2c2e] p-2">
         {components.length === 0 && (
@@ -384,7 +390,12 @@ export function ComponentsView({ theme, org = "all" }: { theme: ResolvedTheme; o
         )}
         {byCategory.map(([cat, items]) => (
           <div key={cat} className="mb-3">
-            <div className="px-2 py-1 text-[10px] font-semibold uppercase tracking-wider text-gray-400">{cat}</div>
+            {/* A hairline that fades right lifts the group header without adding weight —
+                wider tracking + lighter weight reads as a label, not another item. */}
+            <div className="mb-1 mt-1 flex items-center gap-2 px-2">
+              <span className="text-[10px] font-medium uppercase tracking-[0.14em] text-gray-400">{cat}</span>
+              <span className="h-px flex-1 bg-gradient-to-r from-gray-500/40 to-transparent" />
+            </div>
             {items.map((c) => (
               <div key={refOf(c)}>
                 <button
@@ -394,7 +405,9 @@ export function ComponentsView({ theme, org = "all" }: { theme: ResolvedTheme; o
                   }`}
                 >
                   {c.name}
-                  {c.org ? <span className="ml-1.5 text-[10px] text-gray-500">{c.org}</span> : null}
+                  {/* Ownership mark: tagged = the developer's own (editable); untagged =
+                      base, installed and read-only. Emerald so "mine" reads at a glance. */}
+                  {c.org ? <span className="ml-1.5 text-[10px] text-emerald-400/80">{c.org}</span> : null}
                 </button>
                 {/* The component's OWN states (its states/ folder) live HERE in the rail.
                     The two MASTER states (inline/focused — the `defaultState` face switch,

package/screens/DesignSystemView.tsx

@@ -279,7 +279,7 @@ export function DesignSystemView({
     <div className="flex h-full" style={{ background: theme.color["surface.sunken"] ?? "#f9fafb", color: ink }}>
       {/* LEFT NAV — jump between token groups; badge = how many tokens THIS project overrides */}
       <nav className="w-56 shrink-0 overflow-auto border-r p-5" style={{ borderColor: borderC, background: surface, fontFamily: bodyFont }}>
-        <h1 className="mb-1 text-lg font-bold">Design System</h1>
+        <h1 className="mb-1 text-lg font-bold">Styles</h1>
         <p className="mb-5 text-[11px] leading-snug" style={{ color: sub }}>
           {foundation ? (
             <>Viewing <b style={{ color: ink }}>{org}</b></>

package/src/App.tsx

@@ -33,7 +33,7 @@ const NAV: { key: View; label: string; group: string }[] = [
   { key: "apps", label: "Apps", group: "Build" },
   { key: "components", label: "Components", group: "Build" },
   { key: "atoms", label: "Atoms", group: "Build" },
-  { key: "tokens", label: "Design System", group: "Build" },
+  { key: "tokens", label: "Styles", group: "Build" },
   { key: "skills", label: "Skills", group: "AI" },
   { key: "prompts", label: "Prompt Blocks", group: "AI" },
   { key: "nodes", label: "Nodes", group: "Code" },

package/vendor/skills/unoverse-create/SKILL.md

@@ -23,13 +23,15 @@ that is the workspace folder itself; in the platform monorepo it is `apps/unover
    "org"). If the workspace has more than one, or the only one looks like a placeholder,
    ask which project the artifact belongs to. Never invent a new project folder to hold
    one artifact.
-2. **The design system is installed, not on disk.** A developer workspace holds only the
-   developer's own projects; the marketplace design system (shared atoms, components,
-   the token foundation) resolves from the installed platform. See it through Studio's
-   authoring MCP: `listDefinitions` (kind `atom` / `component`, org `marketplace`),
-   `readDefinition` for a full definition, `getVocabulary` for the closed node/style
-   vocabulary. Compose those atoms; never hand-roll a shape the design system already
-   ships. (In the platform monorepo the same material is on disk at `design/marketplace/`.)
+2. **The base design system is public. Read it before you write.** A developer
+   workspace holds only the developer's own projects; the base components, atoms, and
+   the token foundation the platform installs are all published at
+   [marketplace/definitions](https://github.com/unoverse-platform/marketplace/tree/main/definitions)
+   ([components](https://github.com/unoverse-platform/marketplace/tree/main/definitions/components), [atoms](https://github.com/unoverse-platform/marketplace/tree/main/definitions/atoms), [styles](https://github.com/unoverse-platform/marketplace/tree/main/definitions/styles)).
+   Study the closest exemplar there, then compose those atoms and reference those
+   components; never hand-roll a shape the base already ships. Everything is plain
+   YAML files — no connection, no running platform needed. (In the platform monorepo
+   the same material is on disk at `design/marketplace/`.)
 
 ## Step 1: Identify the artifact, read its playbook
 

package/vendor/skills/unoverse-create/references/brand.md

@@ -87,9 +87,12 @@ Its theme is then served at `unoverse://theme/<neworg>/light`, and a template po
 
 ## 4. Anatomy of an org pack (`design/<org>/styles/`)
 
-Read an installed org pack as the worked example (Studio MCP `listOrgs` →
-`listDefinitions`; in the platform monorepo, `design/bpp/styles/`). Every file in a healthy
-pack carries a `$description` explaining its own job, and those descriptions are the spec.
+The foundation's token contract is public — read
+[marketplace/definitions/styles](https://github.com/unoverse-platform/marketplace/tree/main/definitions/styles) (`base/`, `semantic/`, `themes/`); its
+`themes/light.yaml` is the file §3 tells you to copy as your starting theme. (A worked
+client pack lives in the platform monorepo at `design/bpp/styles/`.) Every file in a
+healthy pack carries a `$description` explaining its own job, and those descriptions are
+the spec.
 
 | File | Holds | Rule |
 |---|---|---|

package/vendor/skills/unoverse-create/references/component.md

@@ -6,10 +6,11 @@ model). Deep law: [UNOVERSE_AUTHORING](https://docs.unoverse.ai/unoverse/UNOVERS
 [UNOVERSE_STATE_MODEL](https://docs.unoverse.ai/unoverse/UNOVERSE_STATE_MODEL.md) §5 (the six rules),
 [UNOVERSE_LAYERS](https://docs.unoverse.ai/unoverse/UNOVERSE_LAYERS.md) (states own layouts).
 **Study an exemplar before writing.** The canonical State Model v2 state tree is inlined
-below; for a full worked component, read an installed one through Studio's MCP
-(`listDefinitions` kind `component`, then `readDefinition`), and prefer a rich
-multi-state one over a starter stub. (In the platform monorepo the canonical exemplar
-is on disk: `design/sab/components/product-card`.)
+below. For full worked components, read the published base set at
+[marketplace/definitions/components](https://github.com/unoverse-platform/marketplace/tree/main/definitions/components) — flat single-drawing components
+throughout, and [document](https://github.com/unoverse-platform/marketplace/tree/main/definitions/components/document) for the manifest + local-partials
+folder shape. (In the platform monorepo the richest multi-state exemplar is on disk:
+`design/sab/components/product-card`.)
 
 ## The anatomy
 
@@ -141,8 +142,8 @@ The rules, in the order they bite:
    of bound fields). Same shape, different values = ONE state, data-driven: seven wizard
    questions sharing one shape are one `question` state whose data changes, never seven
    files (LAYERS §4, §7).
-5. **Atoms** (the installed design system's shared shapes, used via `Ref`; list them with
-   Studio's MCP `listDefinitions` kind `atom`, or on disk at `design/marketplace/atoms/` in the
+5. **Atoms** (the base design system's shared shapes, used via `Ref`; browse them at
+   [marketplace/definitions/atoms](https://github.com/unoverse-platform/marketplace/tree/main/definitions/atoms), or on disk at `design/marketplace/atoms/` in the
    platform monorepo) are for shapes shared across components, authoring-time
    only (the server expands them before serving; no Studio view). `Ref props` remaps FIELDS;
    **`Ref with` passes LITERALS**: `{ "type": "Ref", "ref": "button", "with": { "label":
@@ -270,7 +271,7 @@ component. Its key nouns/verbs must appear in `whenToUse`'s first sentence.
 
 ## Workflow
 
-1. Study the closest installed exemplar (Studio MCP `listDefinitions` → `readDefinition`;
+1. Study the closest published exemplar ([marketplace/definitions/components](https://github.com/unoverse-platform/marketplace/tree/main/definitions/components);
    monorepo: `design/sab/components/product-card`); copy its folder shape.
 2. Declare the state tree first: public states on top, steps nested, each state owning
    its layout (same-name default, `layout:` only when the filename differs).

package/vendor/skills/unoverse-create/references/node.md

@@ -89,27 +89,12 @@ package only for a new integration.
 3. **Write `interface.yaml`.** Name outputs for what they carry, because those names become
    what someone types in a template.
 4. **Write `config.yaml`.** Every value the workflow supplies needs `ui:field: template`. A
-   `description` says what the setting does, not what it is called. Then add the two
-   run-authorization fields, which every node carries identically:
-
-   ```yaml
-   authRequired:
-     type: boolean
-     title: Require sign-in
-     default: false
-     "ui:widget": toggle
-   authRole:
-     type: string
-     title: Require role
-     default: ""
-     "ui:dependencies": { authRequired: true }
-   ```
-
-   These are the workflow BUILDER's control, per box on a canvas, separate from
-   `node.yaml`'s `auth`, which is your floor. The executor takes the stricter of the two. A
-   role usually belongs here rather than in the manifest: `finance:approve` is a claim one
-   deployment's identity provider mints, and a published node cannot know it. Add both to
-   `ui:order`.
+   `description` says what the setting does, not what it is called. NEVER declare
+   `authRequired` or `authRole`: they are reserved names, injected by the platform into
+   every runnable node's form as the workflow builder's per-box access controls, and lint
+   refuses a manifest carrying its own copy. Your floor stays in `node.yaml`'s `auth`; the
+   executor takes the stricter of the two. A node with no settings at all needs no
+   config.yaml.
 5. **Write `api/run.yaml`.** A list, each entry named. Include `error` wherever the service
    can answer 200 with a failure body. Where one call is really many, name the capability on
    the call rather than trying to express a loop: `paginate`, `chunk`, `poll` or `state`.

package/vendor/skills/unoverse-create/references/template.md

@@ -6,9 +6,10 @@
 [UNOVERSE_STATE_MODEL](https://docs.unoverse.ai/unoverse/UNOVERSE_STATE_MODEL.md) §5
 (the six rules), [UNOVERSE_LAYERS](https://docs.unoverse.ai/unoverse/UNOVERSE_LAYERS.md).
 Everything in the component playbook (closed vocabulary, tokens, scale steps) applies
-here too. **Study an exemplar before writing**: read the closest installed template
-through Studio's MCP (`listDefinitions` kind `template` → `readDefinition`); the
-canonical manifest tree is inlined below. (Monorepo: `design/sab/templates/sab-chat-layout`.)
+here too. **Study an exemplar before writing**: templates are always a project's own
+(none ship in the base set), so your references are the canonical manifest tree inlined
+below, [design/templates](https://docs.unoverse.ai/design/templates.md), and any template
+already in the workspace. (Monorepo: `design/sab/templates/sab-chat-layout`.)
 
 ## THE model: the component drives; the template reacts by name
 

package/vendor/skills/unoverse-create/references/workflow.md

@@ -1,5 +1,11 @@
 # Playbook: Build a workflow (via the builder MCP)
 
+**A DIFFERENT JOURNEY.** Everything else in this skill is file authoring in the
+developer's own workspace: no connection, no running platform, no pairing code.
+Workflows alone are built on a RUNNING universe's Canvas through the builder MCP, and
+only here does a pairing code exist. Do not carry this playbook's ceremony into any
+other artifact.
+
 Workflows are NOT files in the carve-out. They live in the platform and are built
 through the **builder MCP** (`canvas`, auto-registered by this repo's
 `.mcp.json`). You drive the platform's own authoring tools; the canvas updates live

package/vendor/skills/unoverse-prompt-component/SKILL.md

@@ -32,9 +32,8 @@ It prints every part the agent can fill, its description, and its limits. Read t
 output, not the YAML. Then run the design lint
 (`node -e "import('./packages/base/src/lint/design/index.mjs').then(m=>{const r=m.lintDefinitions();console.log(r.problems.length);r.problems.forEach(p=>console.log(p.level,p.file,p.msg))})"`).
 
-In a **Studio developer workspace**, the same linter runs as Studio's publish lint (or
-the authoring MCP's `lintProject` tool); it catches two of the five traps below by
-name. Read what it says rather than silencing it, and always do the final proof in
+In a **Studio developer workspace**, the same linter runs as Studio's publish lint; it
+catches two of the five traps below by name. Read what it says rather than silencing it, and always do the final proof in
 Step 6: one real fill.
 
 ---