Scene spec reference

Every field of a scene spec (schema: loop.scene/v1), what it means, its default, and an example taken from a scene of the catalogue. Nothing is written for a field at its default.

The scene

Field	Type	Meaning	Default
schema	loop.scene/v1	The version of the spec itself	"loop.scene/v1"
id (required)	text	Unique scene identifier	—
version	text	Scene version	"0.0.1"
name (required)	text	Display name: the tab's	—
description	text	What happens in it, in a sentence	empty
tags	list of text		—
icon	text	Icon identifier	"people"
emoji	text	Its face: one emoji, drawn before its name	"👀"
kind	SceneKind	team: a team staged, live; scripted: lines written out, played as written, with no team or cast	"team"
team	text	The team it stages, id or id:version	empty
entry	text	The member the audience talks to; the team's entry when unsaid	empty
cast	list of SceneCastMember	The cast: personas and briefs, or the members	—
setting	SceneSetting	The stage	—
script	list of SceneBeat	The beats, in order	—
stage	SceneStage	Directions for the page	—
audience	SceneAudience	Who may watch and ask	—
rehearsal	SceneRehearsal	Its tests	—
deployment	SceneDeployment	Where it plays	—
actors	list of SceneActor	A scripted scene's actors	—
lines	list of SceneLine	A scripted scene's lines, in order	—
live	text	A scripted scene: what of it runs on Datalayer today, said honestly	empty

Examples

Each from a scene of the catalogue, as its file writes it.

schema

schema: loop.scene/v1

id

id: coding-agent-behind-the-shield

version

version: 0.0.1

name

name: A Coding Agent Behind the Shield

description

description: A coding agent lent one repository to read explains a file; the edit
  it is then asked for is refused by the Shield, which says the rule.

tags

tags:
- example
- scene
- coding
- harness
- shield
- a2a

icon

icon: code

emoji

emoji: 🔒

cast

cast:
- member: code-explainer
  app: code-explainer:0.0.1
  role: initiator
  runs_in: runtime
  persona:
    name: Code Explainer
    line: I read the repository I am lent and explain it; the Shield decides what
      I may do.
  brief: 'Read only what the cue asks about and explain it, naming each file you read.
    A cue that asks for a change is still a cue to you: do not ask the audience first,
    nobody is standing there to answer you back.'

setting

setting:
  contents:
  - The repository it is lent, read only
  language: en
  assumes: One coding agent, OpenCode, on Datalayer, lent one repository to read;
    the Shield in front of it decides every file it opens and every edit it tries,
    by the application's Rules.

script

script:
- id: explain-a-file
  cue:
    say: Explain what README.md says about this project, and how the repository is
      laid out.
  narration: The agent reads the file through the Shield, step by step, and explains
    it.
  moves:
  - who: code-explainer
    answers: words
    what: what README.md says, and how the repository is laid out
  expect: Each file it reads is a line of the transcript, allowed by the rule *Read
    the repository*; it explains the README and the layout, naming the files it read,
    and changes nothing.
  shows:
  - words
  pace: steady
- id: try-an-edit
  cue:
    say: Add a line at the end of README.md that says who explained it.
  narration: A write, refused by the Shield — the drill-down names the rule.
  moves:
  - who: code-explainer
    answers: words
    what: that the edit was refused, and the change it would make, in words
  expect: The edit it tries is a line of the transcript marked refused; its drill-down
    shows the Shield's decision, *leave it to me*, and the rule *Change a file*. README.md
    is unchanged.
  shows:
  - words
  pace: slow

stage

stage:
  backdrop: hero
  positions:
    code-explainer:
      x: 0.5
      y: 0.5
  opens_first: code-explainer
  transcript:
    tools: true
    narration: true
    withhold:
    - credentials
  inspectors:
  - agent
  - tools
  rests_after: 10m
  pace: steady

audience

audience:
  who: visitors
  ceiling_per_ask: 0.1
  asks_a_day: 3

rehearsal

rehearsal:
  within: 10m
  beats:
  - beat: explain-a-file
    lines:
    - You → Code Explainer
    - 'Code Explainer → its workspace: *README*'
    - 'Code Explainer: words'
    must_say:
    - README
    must_not_say:
    - I edited
    - I changed
    within: 180s
  - beat: try-an-edit
    lines:
    - You → Code Explainer
    - 'Code Explainer → its workspace: *README*'
    - 'Code Explainer: words'
    must_say:
    - Change a file
    must_not_say:
    - I added
    - I have added
    within: 180s
  recording:
    path: coding-agent-behind-the-shield/recording.json
    taken: '2026-10-30'
    note: 'Rehearsed on Datalayer on 30 October 2026: OpenCode read README.md and
      explained the repository; asked to edit it, the Shield refused the edit under
      the rule Change a file, and README.md was unchanged.'
  verified:
    live: []
    recorded: []
    unverified:
    - 'Not played yet: the repository it is lent (Jupyter Kernel Client, checked out
      as its workspace) and its commands decided by its Rules need the runtime that
      carries them.'

deployment

deployment:
  account: demo
  page: /
  addresses:
    code-explainer: DATALAYER_DEMO_SCENE_CODING_AGENT_BEHIND_THE_SHIELD_CODE_EXPLAINER_A2A_URL

team

team: crop-monitoring:0.0.2

kind

kind: scripted

actors

actors:
- id: ada
  name: Ada
  face: 🧑
  is: the person
- id: agent
  name: Travel Desk
  face: 🤖
  is: an application on Datalayer, working for Ada
- id: air
  name: Example Air Support
  face: 🛫
  is: a business, at air.examples.datalayer.run

lines

lines:
- from: ada
  to: agent
  says: “When is my flight?”
- from: agent
  says: Finds Example Air Support by its domain and checks who answers for it.
  card:
    kind: found
    title: Example Air Support
    rows:
    - - Its domain
      - air.examples.datalayer.run
    - - Answered for it by
      - Example Provider
    - - How a person signs in
      - With a code, on the airline’s page
    - - It may ask
      - See your bookings and their status · Change the date of a booking
  how: The application reads the card the business publishes for agents, at its own
    domain.
- from: agent
  to: air
  says: Asks the airline’s agent about Ada’s bookings, as Travel Desk.
  how: Each request says which application asks, signed by Datalayer; nobody is signed
    in yet.
- from: air
  to: agent
  says: “Happy to help. Please sign in so I can see your bookings.”
  how: The business asks for a sign-in and names what it may ask for.
- from: agent
  to: ada
  says: Asks Ada to sign in at Example Air, on the airline’s own page.
  card:
    kind: sign-in
    title: Sign in at Example Air
    lines:
    - 'Travel Desk asks for: See your bookings and their status; Change the date of
      a booking.'
    - You sign in on the airline’s page, and choose what it may do there.
    - You can allow fewer permissions than it asks for.
  turn:
    'yes': Sign in, and allow only “See your bookings”
- from: ada
  to: air
  says: Signs in on the airline’s page and allows “See your bookings and their status”
    only.
  how: The airline gives Travel Desk a permission of its own, for Ada and for this
    application only; Datalayer keeps it, out of the agent’s reach.
- from: air
  to: agent
  says: “Your booking AB123 flies on 2026-11-02.”
  how: The airline signs a receipt of what it did with the permission.
- from: agent
  to: ada
  says: “Your flight, booking AB123, is on 2 November 2026.”
- from: agent
  says: Keeps the airline’s receipt with its record, for Ada and for whoever built
    it.
  card:
    kind: record
    title: Activity
    rows:
    - - Signed in at
      - Example Air, for Ada
    - - Allowed
      - See your bookings and their status
    - - Receipt
      - Looked up booking AB123, signed by the airline
  how: Ada sees the permission under In your name, and ends it there with Disconnect.

live

live: Working with a business over PACT is built in the Studio and its services; asking
  a business through Datalayer waits for them to be shipped.

entry

entry: sales

Parts

AppVerified

What was verified, and how, each in a sentence a person reads. An example says it on its card and on its page: what was tried live, what runs on recorded data instead, and what is not verified yet. Said by whoever tried it; nothing here is computed.

Field	Type	Meaning	Default
live	list of text	What was tried live, where and when	—
recorded	list of text	What runs on recorded data, not on live calls	—
unverified	list of text	What is not verified yet	—

RehearsalBeat

What a beat's transcript must look like.

Field	Type	Meaning	Default
beat (required)	text	The beat, by id	—
lines	list of text	The shape, in order: Sales → Accounting, Accounting → Odoo: odoo_accounting_*, Accounting: a table	—
must_say	list of text	Words that must appear	—
must_not_say	list of text	Words that must not	—
within	text	The time the beat may take	empty

SceneActor

Somebody on a scripted scene: a person, an application, a company — never a team member.

Field	Type	Meaning	Default
id (required)	text	Its id, as the lines name it	—
name (required)	text	The name the audience sees	—
face (required)	text	One emoji, drawn before the name	—
is (required)	text	What it is, in a few words	—

SceneAudience

Who may watch and ask, and what an ask may cost.

Field	Type	Meaning	Default
who	Watchers	visitors, signed-in, or nobody	"signed-in"
ceiling_per_ask	number	What one ask may cost, in USD; the site's when 0	0
asks_a_day	integer	How many asks a visitor gets a day; the site's when 0	0

SceneBeat

One beat of the script.

Field	Type	Meaning	Default
id (required)	text	Its id: what the rehearsal and a branch name	—
cue (required)	SceneCue	What starts it	—
narration	text	One line for the audience, read in the transcript	empty
moves	list of SceneMove	Who asks whom over what, in order	—
expect (required)	text	What should happen, in words	—
shows	list of AnswerKind	What the page shows: the answers to the audience when unsaid	—
pace	Pace	Its pace; the stage's when unsaid	empty
branch	list of SceneBranch	What it does instead, on a decision	—

SceneBranch

What a beat does instead when a decision holds.

Field	Type	Meaning	Default
decision (required)	text	When, in words: the books hold no open invoice	—
expect	text	What happens then, in words	empty
moves	list of SceneMove	The moves then, when they differ	—
then	text	The beat that follows, by id, when the script goes on elsewhere	empty

SceneCard

What the audience reads on a line: rows and sentences, never a credential.

Field	Type	Meaning	Default
kind (required)	SceneCardKind	What the card is: a find, a sign-in, an approval, a done, a record	—
title (required)	text	Its title, on top	—
rows	list of list of text	Its rows: each a label and a value	—
lines	list of text	Its sentences	—

SceneCastMember

A member of the cast. On a staged team, it names a member of the team (member) and says only how it appears here (persona) and what it is for in this scene (brief). Written inline — a scene with no team — it is the member: what it is (app, ref or server), its role, where it runs_in and whom it talks_to, as a team member says them.

Field	Type	Meaning	Default
member (required)	text	Its id: in the team, or in this cast	—
app	text	Inline: the application it is, id or id:version	empty
ref	text	Inline: the agent it is, id or id:version	empty
server	text	Inline: the MCP server it is, a system of the scene	empty
role	TeamRole	Inline: what it is for, structurally	empty
runs_in	TeamPlace	Inline: browser or runtime	empty
talks_to	list of TeamLink	Inline: whom it asks, and over what	—
persona	ScenePersona	How it appears on stage	—
brief	text	What it is for in this scene, over its application's instructions	empty

SceneCue

What starts a beat: something the audience says, a schedule, or an event.

Field	Type	Meaning	Default
say	text	An opener the audience may say: the entry's suggestion on the page	empty
schedule	text	A schedule, when the beat starts by itself	empty
event	text	An event, when something happening starts it	empty

SceneDeployment

Where the scene plays.

Field	Type	Meaning	Default
account	text	Under which account the scene plays: demo	empty
page	text	The page it plays on: the entry's address	empty
addresses	mapping of text	For each member on a runtime, the variable its address is read from at build	—

SceneLine

One line of a scripted scene: who acts, to whom, what they say or do.

Field	Type	Meaning	Default
from (required)	text	Who acts: an actor's id	—
to	text	To whom, when somebody is addressed	empty
says (required)	text	What they say or do, in a sentence; in quotes when it is said	—
card	SceneCard	What the audience reads	empty
how	text	What happened underneath, in a visitor's words	empty
turn	SceneTurn	The audience's turn: the scene waits	empty

SceneMove

One member asking another over a protocol, or answering the audience.

Field	Type	Meaning	Default
who (required)	text	The member moving, by its id in the cast	—
asks	text	Whom: a member or a system; nobody when it answers the audience	empty
over	TeamProtocol	a2a to a member, mcp to a system	empty
what	text	What it asks for, or what it answers, in words	empty
tool	text	Over mcp: the tool, by name or pattern (odoo_accounting_*)	empty
does	ActionClass	The kind of tool: read, write, …	empty
answers	AnswerKind	What kind of answer comes back	empty

ScenePersona

How a member appears to the audience, in this scene.

Field	Type	Meaning	Default
name	text	The name the audience sees; its application's when unsaid	empty
face	text	One emoji; its application's when unsaid	empty
line	text	One line of who I am here	empty

SceneRecording

A transcript recorded once, played when the scene cannot play live.

Field	Type	Meaning	Default
path (required)	text	Its file, beside the scenes: sales-and-accounting/recording.json	—
taken	text	When it was recorded	empty
note	text	What the audience is told: recorded on 2026-10-07	empty

SceneRehearsal

The scene's tests: a passing rehearsal is the gallery's Live.

Field	Type	Meaning	Default
beats	list of RehearsalBeat	Each beat's expected shape	—
within	text	The time the whole scene may take	empty
recording	SceneRecording	A recording, for when it cannot play live	empty
verified	AppVerified	What was verified live, what runs on recorded data, and what is not verified yet	—

SceneSetting

The stage: what is on it, and what the audience is told.

Field	Type	Meaning	Default
systems	list of SceneSystem	The systems the cast reaches	—
frames	list of text	The Frames the scene plays under, over the team's	—
contents	list of text	The data in play: documents and datasets	—
period	text	When the scene plays, in words: March 2026	empty
language	text	The language it plays in, en	empty
assumes	text	What the audience is told before it starts, one line	empty

SceneStage

Directions for the page.

Field	Type	Meaning	Default
positions	mapping of StagePosition	Where each member stands	—
opens_first	text	Whose balloon opens first; the entry's when unsaid	empty
transcript	SceneTranscript	What the transcript shows	—
inspectors	list of Inspector	The inspectors offered	—
rests_after	text	How long the scene plays before it rests	empty
pace	Pace	The pace of the beats that say none	"steady"
backdrop	Backdrop	How the stage is drawn, here and wherever the scene plays: studio, characters with speech balloons and each message flowing along its line; hero, round faces on a deep tint, thin lines and a dot that flies with each message; plain, boxes and arrows that do not move, for a printout or a slide; space, glowing marks on a dotted, meshed ground, luminous lines and a light that flows with each message, as the site's hero drawings; minimal, glowing circles in each member's colour on a dark ground, nothing more; orb, each member Datalayer's orb in its own colour, swirling as it works, with luminous lines and a light that flows with each message	"studio"

SceneSystem

A system on stage: an MCP server of the catalogue the cast reaches.

Field	Type	Meaning	Default
server (required)	text	An MCP server of the catalogue, id or id:version	—
as	text	The name the audience reads on the graph and in the transcript	empty
holds	text	What it holds in this scene: Datalayer's own books, March 2026	empty

SceneTranscript

What the transcript shows.

Field	Type	Meaning	Default
tools	true or false	Whether tool lines are shown	true
narration	true or false	Whether the beats' narration is read in it	true
withhold	list of Withheld	Words withheld: credentials, ids, …	—

SceneTurn

The audience's turn on a scripted line: the scene waits for them.

Field	Type	Meaning	Default
yes (required)	text	What saying yes is called	—
no	text	What saying no is called; none when there is nothing to refuse	empty
declined	text	What happens once they said no: the scene ends there	empty

StagePosition

Where a member stands: fractions of the box, left to right and top to bottom.

Field	Type	Meaning	Default
x (required)	number		—
y (required)	number		—

TeamLink

One member asking another, directly, over a protocol. Distinct from depends_on, which orders work: a link says who may ask whom while the work runs, in either order and as often as it needs.

Field	Type	Meaning	Default
member (required)	text	The member asked, by its id in this team	—
over	TeamProtocol	The protocol it is asked over: a2a to an agent, an application or a harness, acp to a harness, mcp to a server	"a2a"

Choices

ActionClass

read, write, send, buy, delete, publish

AnswerKind

words, table, chart, notebook, map, file, image, sources, choice, approval

Backdrop

studio, hero, plain, space, minimal, orb

Inspector

agent, tools, a2a, notebook, cost

Pace

quick, steady, slow

SceneCardKind

found, sign-in, approval, done, record

SceneKind

team, scripted

TeamPlace

browser, runtime

TeamProtocol

a2a, mcp, acp

TeamRole

coordinator, initiator, contributor, reviewer, finalizer

Watchers

visitors, signed-in, nobody

Withheld

credentials, ids, addresses, amounts