> ## Documentation Index
> Fetch the complete documentation index at: https://docs.livlive.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> This is livlive's documentation. An agent reaches livlive from outside through the `livlive` CLI or the livlive MCP server (see /developers/install, /developers/cli and /developers/mcp). The person links it to livlive once, in the browser: `livlive login`, the local MCP's `livlive_login` tool, or the remote MCP at https://backstage.livlive.ai/api/mcp signing in by OAuth; a personal token made in livlive's settings is for CI. Pages marked 準備中 describe parts not decided yet: do not guess their behaviour.

# stage-package

> How an agent builds a livlive stage on the person's own PC and hands it in — any tools, a package folder checked against the engine reference, `livlive stage push`, the gate's coded answer, then a rehearsal on the real road. Read before making or changing a stage package outside the backstage.

> [!NOTE]
>
> このページは、エージェントが読む skill「stage-package」の本文です。

> [!WARNING]
>
> いまは招待制βの準備中です。CLI と MCP は npm から入れられますが、使うには livlive のアカウント(招待制)が要ります。スキル(`npx skills add`)は、livlive-kit の公開とともに使えるようになります。

This skill is the build: how a stage is made, checked and handed in. The conversation with the person — what they want, what to propose, when
to show it, where the work stands — is `stage-lead`; read it first when a person has asked for a stage or a game.

## What a stage is for

A stage is the place a character enters. It holds what can be done there — the things, where a body may walk and sit, what can be
switched or opened, the events, a game of its own — and the characters choose among those as they go. The stage leads; the motions and
the words follow from what it offers. So a stage is good when a character has something real to do in it, and when it reads as one place.
Build for that first, and for the picture second.

## The package

A stage is handed in as one folder: the package. Its layers are named in the engine reference (`reference/engine.json` in livlive-kit,
the MCP resource `livlive://reference/engine`):

* `layers` — each layer's files, its version, the layers it needs, and what it adds. The room is always there; the others come only when
  the stage uses them. Read the folder's shape from here, never from memory: a layer added later is one more entry.
* `schemas` — each JSON file's definition, by layer and file, with what every field means.
* `limits` and `package` — sizes, counts and the GLB features the platform draws.
* `frames` — the units and directions the engine reads positions and headings in.
* `kinds`, `looks`, `can`, `acts` — the words the engine knows for things and what they let a character do.
* `keeper` — the protocol and the entry points of a game of the stage's own.
* `hold` — the shared ways to hold a thing, by name (a thing's `hold.pose`). A thing none of them fits brings its own row as `hold.arm` in
  place of `pose` (the hand, its arm's bones, the grip point — the shape `schemas` describes); the gate lays it on a test body and refuses
  one whose hand enters the torso, whose elbow rises over the shoulder, or that lands differently on a VRM 0.x body (`problems`).
  What a character can still do with her hands full, and what can change how a thing she holds looks, is `hold.whileHeld`: read it
  before a wish or a game puts something in a hand.
* `problems` — every code the gate can answer, with its words and the scope it is checked in.

The reference is generated from the engine. When it and anything else disagree, the reference is right. `livlive reference` prints the one
livlive serves now; the copy a kit carries can be older, and the CLI says so when it is.

A stage can also be kept as a source folder, which the CLI packs whenever it checks or hands the stage in:

* `stage.mjs` — the world, the package's manifest, and the room's GLB by its path in the folder;
* `src/` — the rules, in TypeScript, typed by `@livlive/game` (`import type` only);
* `keeper.json` — what the rules declare. An act the game owns (`acts`) names the motion it shows from the reference's
  `keeper.motions`, and only a name listed there.

`keeper.json` also says how many play: `players { min, max }`, whole numbers, 1 ≤ min ≤ max ≤ 4 (the reference's `schemas` has the words).
Below `min` no game opens — the stage dev page and the studio say why, and the stage runs as a room alone; above `max` the first `max` in
seat order play and the others watch and talk. Registration tries the game with `min` performers and with `max`; a game that says nothing is
tried with two, and every performer plays it.

`livlive stage new <folder>` makes these empty shapes. `livlive room-kit` gives the room kit's folder, for a room built in Blender.

`livlive stage new <folder> --name <name>`, run at the proposal's yes (`stage-lead`), also makes the stage itself on livlive by that name when
the CLI is logged in, and writes `livlive.json` at the folder's top: `{ "stage": "<id>" }`, the stage the folder is for. Every push and check
of the folder goes to that stage with no flag, so keep the file with the folder and never write it by hand. Logged out, `stage new` makes the
folder only and says so, and the first push with `--name` makes the stage. No layer names `livlive.json`: it is never handed in.

## The stage's face

What the stage's page and the person's list of stages show of it, and what its performers read, are its face. It is kept beside the package
and handed in with it:

* `face/picture.png` (or `.jpg`, `.webp`) — its 一枚絵, one picture of the whole stage;
* `face/face.json` — `{ "note": "<ひとこと>", "tone": "<色>" }`: its one line, and its colour, one word of the stage page's list;
* `world/*.md` — its 世界観 documents, which the performers read: one Markdown file each, named in letters, digits, `.`, `_` and `-`.

`world/world.md` is the stage's own document, and its place is the chapter `## 舞台`: what is seen there, its air and its colour. When the
stage is a place in a world, that chapter is all its performers read of these documents; when it is not, they read every document whole. So
keep each chapter to a few lines, and use only the names the person gave. The ひとこと says where, who and what, in one line.

Their bounds and the 色's words are in `stage.face`'s entry of the ops reference (`livlive ops`); `livlive stage check` checks the files that
are there, on the PC, and says each problem as livlive would. It also warns when no document in `world/` has a `## 舞台` chapter. The face is
not required: a folder without `face/` and `world/` hands in the space alone, and the stage's page says what is missing. `stage new` writes none of it. Each part is shown to the person and goes in only on
their yes (`stage-lead`).

## The stage's own skill (SKILL.md)

A stage may carry one skill: how to make a show on it. It is the `skill` layer — a `SKILL.md` at the top of the package folder. Whenever a
content is set on the stage, the writer (ツヅリ) is given it whole beside the other skills, so a show made here follows it.

* Its frontmatter is flat `key: value` lines, as every livlive skill; a list is its key alone on a line and then one `- item` line for
  each item, indented under it (an item line that starts at the margin is refused as a key out of shape). The keys: `name` (40
  characters at most), `description` (when to read it), `title` (16), `summary` (60), `guide` (a list of 1–3 lines, 50 each). No other
  key is taken.
* Write what only this stage knows: what is played for, how one round runs, which rules a viewer needs and when, where the moments are.
  Say only what the stage does — its rules, its acts and its settings as the package makes them; nothing it cannot do.
* The `guide` lines are checked against every draft of a sheet made on the stage: write each as something a finished sheet visibly does.
* No concrete examples, no sample lines: they are copied.
* `stage check` refuses a SKILL.md out of these bounds, with its words, before anything is kept.

## Build with any tool

Blender, a script, another model's output, a hand-written glTF — the tools are free. The gate checks only the package. Keep the sources
of the build beside the package if the person wants to change it later; they are not handed in.

Make the room's shape the shape the characters meet: what they walk on, what stands in the way, where they sit. Name what a character can
use, and describe it in the person's language. A thing brought as its own file is placed by the world's rows, as the `things` layer says.

## What the bodies and the cameras need

The engine walks, seats and frames the characters by the room's shape itself — every shape grown by about a body's radius. A room that
looks right can still leave a body nowhere to stand. Check these on what you built, and again on the real road:

* **A seat is reached and sat in.** The place a body stands to sit — in front of the seat, toward where it faces — and the way to it from
  the floor stay clear once every shape is grown by a body's radius. A piece larger than the seat it serves can close that way: size it or
  set it back until the way is clear, and judge by the way, not by the picture alone. Its seat's top is the height the seat declares (`states`, seat\_height).
* **What is reached across stays reachable.** What a seated hand reaches over keeps its edge and rail below the hand's path; a reach
  whose hand or forearm meets the room's shape is not made.
* **The cameras see the faces.** Nothing tall stands between the camera's room (`camera.volume`) and the face of a body in a seat
  or at a place it acts from. Anything tall belongs behind the bodies as the cameras see them. A face is also seen only from its
  own side: a body at a thing stands facing it, so at a thing against a wall she turns her back on a camera room that lies behind
  her. The camera's room has to reach beside her there — level with her or ahead of her. Every row of `objects` is a place a
  character may walk up to unless the reference means otherwise for it (the `can` list's go\_to row: a seat and a floor she stands
  on are never offered a walk), so each other row needs such a place for a camera. A row with nowhere to stand beside it is no
  exception: it is a fault, and the patrol reports it. What cannot have a place for a camera is better told in the `about` of a
  thing that can than given a row of its own.
* **What is high is out of the picture.** The programme's shots are framed on the people through a narrow view, so anything meant
  to be seen in a picture stands within it: the world schema's `camera` says how high that reaches. Read it before
  placing anything far above the people.
* **A thing invites a word.** A thing a character can look at and talk about carries its `about` in the person's language. That is what a
  character takes up in talk, and its words come back as the characters' lines. In a place to live in, it keeps what is curious about the
  thing: its story, a habit of the place, something left unexplained. On a stage made for a programme that wants dense talk, it keeps to
  what the thing is and what it is for, with no atmosphere and no little story.
* **A drawn look is declared, not baked in.** Outlines and light in steps (`look.ink`) and a glow around what is bright (`look.glow`) are
  the space's own words, within the ranges `limits` names; what glows is what the room's materials light from themselves.

## Check before handing in

Before a push, check what you can on the PC:

1. Every JSON file against its schema in `schemas` (any JSON Schema validator).
2. Every GLB with a glTF validator (the Khronos glTF-Validator): no errors, and only the features `package` lists.
3. The counts and sizes against `limits`.
4. Positions and headings in `frames`' units and directions, and the rules each schema states for its own file (a thing's origin is
   in thing.json's).
5. `livlive game check <folder>` — the rules translated on this PC, checked on livlive's side and played on the stage's world, as registration plays them.
6. `livlive stage dev <folder>` — the stage drawn by livlive's engine on its dev page, read from the folder on this PC; each saved file
   shows again in seconds. A saved rule file is translated again on this PC; a problem of the translation prints at once as
   `<code> — <words>` (the `game.*` codes of scope `translate` in the reference's `problems`). The dev page tells this terminal, in
   registration's codes, when a game does not open, and the terminal prints each as `<code> — <words>` in every mode. Silence means only
   that no refusal was heard — a page that is not open tells nothing — and is no OK. A game without `reset` or `step` is shown on the
   page, but this terminal does not name it; `livlive game check` says it as `keeper.js_functions`. The dev page has three ways to move the
   characters: 乗り移り, 巡回 (the one `--patrol` asks for) and キャラに任せる. The first two stay free. 乗り移り lets the person take a
   character's place: the rows offered are what that character may do now, in the words the character reads; on a stage with a game the
   page casts the game's players as the patrol does (below). A character the person does not play moves only on a turn the game asks
   of her — rows its `offers` mark `due`, which leave no 「いまのまま」 on her menu — and then by a seeded draw, so the game moves while
   the person plays the lead; a game a character starts by her own act, with no turn asked, leaves the others standing on this page.
   Every body in the cast is loaded before the stage plays, so each character more is time the person waits. The picture follows the
   character the person plays: another character of the cast is in the stage and takes her turns, but she is seen only when she
   comes into that picture. To look at the stage as her, the person makes her the lead; a body once read stays with the open page,
   so only a body not yet read is downloaded then. Two characters are seen together in the rehearsal. The dev page has no button for
   a stage's event (`rules.happenings`): an event is raised only in the studio, on the 出来事 tab, during 本編 of a rehearsal or a 本番,
   so the rehearsal is where an event is first seen — do not ask the person to look for its button on this page.
   `--patrol` walks the person's lead
   character through every seat and every thing and uses each switch once; on a stage with a game it does this first with the game left out,
   then plays the game with up to as many characters as `players.max` says (two when it says none) — the person's chosen 二人目, 三人目 and
   四人目, the places left empty filled from their other characters, which the page names — and judges the seats the game gives. It prints
   each finding as `<code> — <words>` (the `patrol.*` codes are in the reference's `problems`, scope `patrol`) and exits 1 for trouble, 3
   when it found none but could not check every place, 0 when nothing was found. The page must be open and signed in to livlive: the command
   opens it (with `--no-open`, open the address it prints). A page that cannot patrol (no character, a stage it cannot draw) says why and
   exits 2, as does no report within `--wait` seconds (900). `patrol.not_covered` names what the patrol could not check (no answer in time,
   a face never counted, 「ゲーム」 when the game never got going — often too few characters: a person with fewer than `min` (two when it
   says none) must welcome more, since the page fills the places only from the characters they have, and says how many; or a game
   that never asks a turn: the patrol counts a game as going by the first turn it asks (rows its `offers` mark `due`, not only
   seats to sit in), so a game whose acts stay open to anyone at any time is reported this way however well it plays — say so to
   the person; `livlive game check` and the rehearsal speak for such a game): a gap in the check, not a fault of the stage. Exit 3
   is an incomplete check, not a wrong stage: read why before changing anything, and never change a game only to let the patrol
   through. A clean patrol is still no OK: the rehearsal decides.
   キャラに任せる hands the characters to their own judgment, run by livlive's runtime with no voice and no lines — only their picks — so a
   game moves by what they pick. A rehearsal in the studio is still the last word. It uses the person's credits, for the characters'
   judgment and for the minutes of the live room it runs in. The page says so
   (「任せている間、クレジットを使います(キャラの判断と部屋の分)」). Only the person's press on 「キャラに任せて動かす」 starts it. With no
   credits the press is refused (「クレジットを使い切りました。」). The CLI and the MCP never start it and stay unpaid. Ask the person to
   press. A run ends when:
   * the person presses 「止める」 or chooses another way;
   * the page draws the stage again, which it does on every save (a save that fails to read keeps the run), so finish the edits before
     asking the person to press, or tell the person that a save ends the run;
   * the characters chosen on the page change;
   * the page is closed or left;
   * the page has been out of sight for five minutes (「しばらく見えていなかったので止めました。」), so keep it in view;
   * 30 minutes have passed since the start (「30分たったので止めました。」), so a run left open does not keep using credits;
   * the stage cannot be drawn (「ステージを描けませんでした。」);
   * the characters' judgment stops or leaves the room (「キャラの判断が止まりました。」) or does not arrive within a minute of the press
     (「始められませんでした。もう一度押してください。」): that is livlive's runtime not answering, not a fault of the stage;
   * a newer start comes: there is one run per person, so a start from another tab ends the older one.
7. `livlive stage check <folder>` (with `--name <name>` or `--stage <id>` only when the folder has no `livlive.json`) — before replacing a
   stage's space: every check a push runs, on a stage you have, which it leaves as it is, and the face's files against their bounds. A new
   stage is simply pushed, since a refused push changes nothing. The GLBs a check uploads stay for the push. A live rehearsal or 本番 on that
   stage refuses the upload, so check between runs.

A check answers for the folder as it stood when the check ran. After a change made because of a finding, run that check again
before the push: a push after an unchecked change hands in a guess. The hand-in waits for a patrol that ends without trouble — 0,
or 3 with what it could not check said to the person. A finding you would rather leave is the person's to accept: say which, why
it stays and what they will see because of it, and push only on their yes.

These catch most refusals early. The gate still decides; a clean local check is not an OK.

## Hand it in

```
livlive stage push <folder>                  # the stage the folder's livlive.json names
livlive stage push <folder> --stage <id>     # a stage you have (livlive stage list), when the folder names none
livlive stage push <folder> --name <name>    # your stage of that name, made when there is none, when the folder names none
```

These are the CLI's commands for the `stage.*` ops (`livlive ops` lists them). The CLI reads the folder by the reference's layers, sends each GLB once, and registers the package as the stage's space. A push replaces
the stage's space at once, and prints the address of the stage's page. A push is refused while a rehearsal or a 本番 runs on that
stage; push again when it ends. `livlive stage read <id>` shows the registered space as the engine reads it: its things; its seats (where, and the
height a body sits at) and placements in the room's frame, as world.json writes them; its switches and how each starts; the walk in the
engine's frame (placed by the spawn). Compare them with what you wrote.

With `face/` or `world/` in the folder, the push then sends the stage's face. It fills only what is empty on the stage: a field the person
set on the stage's page, or an earlier push set, is kept as it is, and the push says what it set and what it kept. To replace a kept field,
and only when the person asks for it, push with `--replace` naming those fields (`picture`, `note`, `tone`, `world`, joined by commas);
never add it on your own. A push cut part way says what it set first: push the same again, and what was set is kept while the rest is
filled.

A folder the CLI cannot read (a missing required file, a JSON that does not parse) stops before anything is sent.

## Read the gate's answer

A refusal changes nothing: the stage keeps the space it had. Each problem comes as `<code> — <words>`:

* The code says which rule failed: its first part names the layer or the door it belongs to. Look it up in the reference's `problems`:
  each code is listed with its words, the parts that vary shown as 「…」. Then find that rule in the layer's schema or in `limits`.
* The words are what a person reads on the stage page; they say what and where.
* Fix every problem the answer lists, then push again. Fix the cause in the build, not in the exported file, so the next export stays
  fixed.

## The real road decides

A registered space is not yet a working stage. The person (or the backstage's road check) runs a rehearsal on it from the studio, with a
character on it: walking, sitting, using what the stage offers, its game if it has one. What goes wrong there is fixed in the package and
pushed again. A stage is done when it worked in a rehearsal — never because the gate took it.

A game a character starts by her own act begins whenever she happens to take it — from the first moments of 本編, not at the stretch the
programme means for it — and can be over before that stretch comes. A game that must begin at a chosen point of the programme starts
from something that happens there: today that is an operator's press of one of the stage's events (how a game hears it: the reference's
`keeper.contract`, its `step` row).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.