<!-- GENERATED by starlens/site/tools/reference_pages.py from the engine's sources: do not edit; run it. -->

[[nav: reference | here=verbs]]

<div class="doc">

<!-- GENERATED by love-shared/scripts/verb_sheet.py from the app's registry (scripts/verb_inventory.lua): do not edit; run it. -->

# launcher · the verbs

<p class="plain"><a href="../../verbs/launcher.md">this page as plaintext</a></p>

*The desk's WORKSPACE wall and the in-app UI editor. 65 verbs in 5 categories: 0 undoable, 14 read-only. The app-verbs protocol (`love-shared/docs/app-verbs.md`): `staros-tap launcher verbs` lists them live, `staros-tap launcher verb <name> '<json>'` runs one, `activity --since N` reads the journal. Loaded headless from `launcher` by `scripts/verb_inventory.lua`.*

## fleet

### `fleet.op` — medium, palette word `op`

Sign an op for a host (the fleet's signed ops, docs/ops.md): service.start, service.stop or service.restart (target: the service's id), app.launch (target: the app), task.handoff (target: project/slug, handed to this box). The host's applier decides it within its tick and its fold carries the receipt; the house shows it pending until then.

| argument | type | notes |
|---|---|---|
| `host` | string | required |
| `kind` | string | required; one of service.start, service.stop, service.restart, app.launch, task.handoff |
| `reason` | string |  |
| `target` | string | required |

    staros-tap launcher verb fleet.op '{"host": "…", "kind": "service.start", "target": "…"}'

### `fleet.ops` — low, read-only

The ops this desk signed and where each stands: pending, applied, refused, expired or unanswered (from the receipts every fold carries).

    staros-tap launcher verb fleet.ops '{}'

## media

### `library.close` — low

Close the open book: back to the shelves.

    staros-tap launcher verb library.close '{}'

### `library.locate` — low

Open an epub:// passage (a reading note's locator): the book found on the shelves by its id, the passage at the top and selected.

| argument | type | notes |
|---|---|---|
| `uri` | string | required |

    staros-tap launcher verb library.locate '{"uri": "…"}'

### `library.open` — low

Show the room MEDIA and open an item: by its 1-based index on a shelf (books by default; library, documents), its path, or a registered work's key (the bibliography's).

| argument | type | notes |
|---|---|---|
| `index` | integer |  |
| `key` | string |  |
| `path` | string |  |
| `shelf` | string | one of library, books, documents |

    staros-tap launcher verb library.open '{}'

### `library.shelf` — low

LIBRARY's corpus (all, or one of the bibliography's) and filter (words in the title, author, key, corpus or year); the shelf focused.

| argument | type | notes |
|---|---|---|
| `corpus` | string |  |
| `filter` | string |  |

    staros-tap launcher verb library.shelf '{}'

### `library.state` — low, read-only

The media library's state: the shelf in focus, its item, the shelves' counts, the open book's reader state, the last note sent.

    staros-tap launcher verb library.state '{}'

### `reader.clip` — low

Clip the selection to another page: to = lore (a StarLore note), board (a card on the board: the Scratch room's stack when no board pane is open) or both. A passage is a note (and on a board its card); a region is a picture.

| argument | type | notes |
|---|---|---|
| `comment` | string |  |
| `to` | string | required; one of lore, board, both |

    staros-tap launcher verb reader.clip '{"to": "lore"}'

### `reader.goto` — low

Show a chapter of the open book (1-based); with block, that block at the top.

| argument | type | notes |
|---|---|---|
| `block` | integer |  |
| `chapter` | integer | required |

    staros-tap launcher verb reader.goto '{"chapter": 0}'

### `reader.note` — low

Send the selection (else the block at the top) to StarLore as a reading note: its tap when StarLore answers, else its notes folder. Returns the note's slug, its locator and the route taken.

| argument | type | notes |
|---|---|---|
| `comment` | string |  |

    staros-tap launcher verb reader.note '{}'

### `reader.region` — low

Select a region of a PDF page: x, y, w, h fractions of the page (its top-left the origin); page defaults to the one at the top.

| argument | type | notes |
|---|---|---|
| `h` | number | required |
| `page` | integer |  |
| `w` | number | required |
| `x` | number | required |
| `y` | number | required |

    staros-tap launcher verb reader.region '{"x": 0, "y": 0, "w": 0, "h": 0}'

### `reader.scroll` — low

Scroll the open book by pixels (by), or to a pixel offset (to).

| argument | type | notes |
|---|---|---|
| `by` | number |  |
| `to` | number |  |

    staros-tap launcher verb reader.scroll '{}'

### `reader.select` — low

Select whole blocks of the open chapter, block..to (to defaults to block): the passage a note quotes.

| argument | type | notes |
|---|---|---|
| `block` | integer | required |
| `to` | integer |  |

    staros-tap launcher verb reader.select '{"block": 0}'

### `reader.state` — low, read-only

The open book: its title, chapter, the block at the top, the zoom, the scroll, the selection.

    staros-tap launcher verb reader.state '{}'

### `reader.zoom` — low

Set the open book's type size (12..44), or change it by `by`; the reading position is kept.

| argument | type | notes |
|---|---|---|
| `by` | number |  |
| `size` | number |  |

    staros-tap launcher verb reader.zoom '{}'

## omni

### `omni.act` — medium

Do a verb on a thing in Ctrl+K, as a person's Tab, then Enter: key (from omni.find), verb (an id from omni.verbs; none: the first, what Enter does), args (a verb that asks), query (what was typed, for a verb that uses it: an alias). Learned as a person's pick is. Another app's verb is refused: call that app's own tap.

| argument | type | notes |
|---|---|---|
| `args` | object |  |
| `key` | string | required |
| `query` | string |  |
| `verb` | string |  |

    staros-tap launcher verb omni.act '{"key": "…"}'

### `omni.find` — low, read-only, palette word `find`

Ctrl+K's rows for a query, in the order a person sees them (the one bar: every source scored together, the learned boost, each kind capped, then the fallbacks): key, kind, title, detail. An empty query gives the empty bar's sections (pinned, running, today, recent), each row with its section. The sidecar's files are the SEARCH tab's and are not listed.

| argument | type | notes |
|---|---|---|
| `limit` | integer | minimum 1; maximum 50 |
| `query` | string |  |
| `scope` | string |  |

    staros-tap launcher verb omni.find '{}'

### `omni.pin` — low

Pin a thing to the top of the empty Ctrl+K (PINNED), or unpin it (on = false). Kept in the save dir's omni.json, across restarts.

| argument | type | notes |
|---|---|---|
| `key` | string | required |
| `on` | boolean |  |

    staros-tap launcher verb omni.pin '{"key": "…"}'

### `omni.verbs` — low, read-only

What a thing in Ctrl+K can do: its action panel (Tab on its row), in order, the first being what Enter does: id, label, chord (the key that runs it from the list), asks (it takes arguments), confirm (a person is asked first), stay (the bar stays open).

| argument | type | notes |
|---|---|---|
| `key` | string | required |
| `query` | string |  |

    staros-tap launcher verb omni.verbs '{"key": "…"}'

## ui

### `ui.close` — low

Close the UI editor's overlay.

    staros-tap launcher verb ui.close '{}'

### `ui.get` — low, read-only

A colour's value and its hex, a house table's ([theme.color], [base.color]) or one the app registered; or a named motion's value (motion.toast.slide ms); or a layout token's step and px ([theme.corner] button).

| argument | type | notes |
|---|---|---|
| `key` | string | required |
| `table` | string | required; one of aesthetic.panel, aesthetic.substrate, aesthetic.themed, app_accent, base.color, base.radius, base.space, launcher.color, motion.card.enter, motion.card.exit, motion.card.flash, motion.card.reveal, motion.caret.blink, motion.feed.follow, motion.list.scroll, motion.overlay.fade_in, motion.overlay.fade_out, motion.panel.slide, motion.prompt.pulse, motion.toast.fade, motion.toast.life, motion.toast.pulse, motion.toast.slide, palette, starboard.color, starlore.color, starsaga.color, startune.color, startune.phone, startune.section, theme.color, theme.corner, theme.inset, theme.pad, theme.radius |

    staros-tap launcher verb ui.get '{"table": "aesthetic.panel", "key": "…"}'

### `ui.inspect` — low, read-only

The widgets the last frame drew while the overlay is open: kind, rect, and each colour role with its owner.

| argument | type | notes |
|---|---|---|
| `limit` | integer | minimum 1 |

    staros-tap launcher verb ui.inspect '{}'

### `ui.open` — low

Open the in-app UI editor's overlay (the widgets note what they draw while it is open).

    staros-tap launcher verb ui.open '{}'

### `ui.ops` — low, read-only

The unsaved changes as the writer's ops (token ops, and the shell document when it was edited).

    staros-tap launcher verb ui.ops '{}'

### `ui.revert` — low

Put every unsaved change back as it was.

    staros-tap launcher verb ui.revert '{}'

### `ui.save` — medium

Write the unsaved changes through scripts/ui_edit.py: tokens.toml (the floors checked first) and the shell document (the format checked first; dry_run reports without writing).

| argument | type | notes |
|---|---|---|
| `dry_run` | boolean |  |

    staros-tap launcher verb ui.save '{}'

### `ui.set` — low

Change a colour live, a house table's or one the app registered (hex or [r, g, b, a] in 0..1): the next frame draws it. Or a named motion's value (a number, or a name: an easing, a law, a shape): the next motion that starts takes it. Or a layout token's step ("radius.2" for [theme.corner] button): the next frame draws it. Unsaved until ui.save.

| argument | type | notes |
|---|---|---|
| `key` | string | required |
| `table` | string | required; one of aesthetic.panel, aesthetic.substrate, aesthetic.themed, app_accent, base.color, base.radius, base.space, launcher.color, motion.card.enter, motion.card.exit, motion.card.flash, motion.card.reveal, motion.caret.blink, motion.feed.follow, motion.list.scroll, motion.overlay.fade_in, motion.overlay.fade_out, motion.panel.slide, motion.prompt.pulse, motion.toast.fade, motion.toast.life, motion.toast.pulse, motion.toast.slide, palette, starboard.color, starlore.color, starsaga.color, startune.color, startune.phone, startune.section, theme.color, theme.corner, theme.inset, theme.pad, theme.radius |
| `value` | any | required |

    staros-tap launcher verb ui.set '{"table": "aesthetic.panel", "key": "…", "value": "…"}'

### `ui.shell` — low, read-only

The app's shell document as the editor holds it (docs/formats/shell.md): its file, identity, panes, toolbar rows, sheet, seed, keys, docks and rooms, and whether it is unsaved.

    staros-tap launcher verb ui.shell '{}'

### `ui.shell_insert` — low

Insert a row before row i of a list (the path ends in [i]: toolbar[2], sheet[1], panes[17]); the value is the row. Checked first; unsaved until ui.save.

| argument | type | notes |
|---|---|---|
| `path` | string | required |
| `value` | any | required |

    staros-tap launcher verb ui.shell_insert '{"path": "…", "value": "…"}'

### `ui.shell_move` — low

Move a row of a list (toolbar, sheet, panes, rooms.order) from one position to another. Unsaved until ui.save.

| argument | type | notes |
|---|---|---|
| `from` | integer | required; minimum 1 |
| `list` | string | one of toolbar, sheet, panes, rooms.order |
| `to` | integer | required; minimum 1 |

    staros-tap launcher verb ui.shell_move '{"from": 0, "to": 0}'

### `ui.shell_remove` — low

Remove what a path names: a row (toolbar[3]), a key (keys.zoom), a dock or a room (docks.library, rooms.list.loop). Checked first; unsaved until ui.save.

| argument | type | notes |
|---|---|---|
| `path` | string | required |

    staros-tap launcher verb ui.shell_remove '{"path": "…"}'

### `ui.shell_set` — low

Set what a path into the shell document names, live (toolbar[3].label, sheet[2].action, panes[17], keys.close, docks.terminal.ratio, rooms.active, rooms.list.loop.title, seed.first.ratio; a name on the way is made, an index is not); the format's check runs on a copy first. Unsaved until ui.save.

| argument | type | notes |
|---|---|---|
| `path` | string | required |
| `value` | any | required |

    staros-tap launcher verb ui.shell_set '{"path": "…", "value": "…"}'

## wall

### `board.boards` — low, read-only

The boards the wall's board pane can show (the stacks in its folder) and the one it shows.

    staros-tap launcher verb board.boards '{}'

### `board.compose` — low, palette word `compose`

Lay the wall out as the board's cards are arranged (shared/board/compose.lua): the workspace board-<stack>, switched to.

    staros-tap launcher verb board.compose '{}'

### `board.fire` — low

An event for the playing board's cards (StarScript step 4): every card with `label on.<event>` runs it, the event's words in kv event.* (a handler reads them with when). A board not playing hears none.

| argument | type | notes |
|---|---|---|
| `event` | string | required |
| `words` | object |  |

    staros-tap launcher verb board.fire '{"event": "…"}'

### `board.pick` — low

Pick choice n (1-based) of the line Play shows, and play on to the next say.

| argument | type | notes |
|---|---|---|
| `n` | integer | required |

    staros-tap launcher verb board.pick '{"n": 0}'

### `board.pin` — low, palette word `pin`

Pin a thing to the board on the wall (the Scratch room's stack when no board pane is open): a run://, task:, app:, pane:, room: or note: ref becomes a card; `image` (a picture's path) makes an image card, with its caption and its locator (the way back to where it was cut).

| argument | type | notes |
|---|---|---|
| `caption` | string |  |
| `image` | string |  |
| `locator` | string |  |
| `uri` | string | required |

    staros-tap launcher verb board.pin '{"uri": "…"}'

### `board.play` — low

Play the selected card's script (its openCard, else its first line) to its first say; `stop` stops.

| argument | type | notes |
|---|---|---|
| `stop` | boolean |  |

    staros-tap launcher verb board.play '{}'

### `board.script` — low

The script drawer under the board: open (the selected card's script) or closed; with `text`, the card's script set (one undoable edit).

| argument | type | notes |
|---|---|---|
| `open` | boolean |  |
| `text` | string |  |

    staros-tap launcher verb board.script '{}'

### `board.select` — low

Select a card on the board: by its 1-based index in the stack, or its id.

| argument | type | notes |
|---|---|---|
| `id` | string |  |
| `index` | integer |  |

    staros-tap launcher verb board.select '{}'

### `board.state` — low, read-only

The board on the wall: its stack, cards, links, the selected card, and Play's state (the card it is at, the line, the kv, the tells).

    staros-tap launcher verb board.state '{}'

### `board.switch` — low

Show another board in the wall's board pane (its switcher, B): a board in its folder by name, or a new one (`new`: letters, digits, - and _). A flow pane on the old board follows.

| argument | type | notes |
|---|---|---|
| `name` | string | required |
| `new` | boolean |  |

    staros-tap launcher verb board.switch '{"name": "…"}'

### `board.template` — low

Lay a template's cards on the board, under what it holds (StarScript starter, Kanban, Storyboard, Mindmap).

| argument | type | notes |
|---|---|---|
| `name` | string | required |

    staros-tap launcher verb board.template '{"name": "…"}'

### `tour.take` — medium, palette word `tour`

Take the guided tour (scripts/tour/tour.py --demo): scratch copies of each app come onto the screen and make a thing each, handed on to the next, paced; each step is said on the run it writes, which the activity list follows. Nothing of yours is touched. `legs` takes some (L1 …), `pace` the seconds a step stands.

| argument | type | notes |
|---|---|---|
| `legs` | array |  |
| `pace` | number |  |
| `scenario` | string |  |

    staros-tap launcher verb tour.take '{}'

### `wall.action` — low, palette word `press`

Press a toolbar or sheet button by its action id (wall.json: exit, pane_picker, new_term, new_agent, new_log, new_search, new_screen, new_ssh, new_remote, osk, ws_cycle, …).

| argument | type | notes |
|---|---|---|
| `id` | string | required; one of rooms, pane_picker, split_h, split_v, close, osk, room:desk, room:work, room:keepers, room:time, room:apps, room:find, room:media, room:scratch, room:greenkeeper, room:warden, room:scribe, room:stoker, room:herald, room:busker, room:porter, room:atelier, rooms:keeper, add_sheet, pane_prev, pane_next, ws_cycle |

    staros-tap launcher verb wall.action '{"id": "rooms"}'

### `wall.add_pane` — low, palette word `pane`

Open a pane by its registry id (native_terminal, remote_terminal, note, log, search, agent, ladder, kanban, screen_share, programme, services, grove, planets, journal, s2ar) beside the focused one.

| argument | type | notes |
|---|---|---|
| `id` | string | required |
| `params` | object |  |

    staros-tap launcher verb wall.add_pane '{"id": "…"}'

### `wall.backdrop` — medium, palette word `backdrop`

The desk as the backdrop (on) or a window again (off): borderless over its display and under every window the wall arranges, forward only while Ctrl+K or a picker is open. Kept for the next boot; it takes effect once a window manager answers.

| argument | type | notes |
|---|---|---|
| `on` | boolean | required |

    staros-tap launcher verb wall.backdrop '{"on": true}'

### `wall.close` — low, palette word `close`

Close the focused pane (a task's terminal detaches; its session keeps running).

    staros-tap launcher verb wall.close '{}'

### `wall.focus` — low, palette word `focus`

Focus a pane: by its task (project/slug) or by its registry id (the first pane of that id).

| argument | type | notes |
|---|---|---|
| `id` | string |  |
| `task` | string |  |

    staros-tap launcher verb wall.focus '{}'

### `wall.launch_into` — low, palette word `launch`

Launch an app INTO the wall: a WINDOW leaf beside the focused pane (side right, left, top, bottom or tab) holds its window once it opens. Without a window manager answering, the app simply opens.

| argument | type | notes |
|---|---|---|
| `app` | string | required |
| `side` | string | one of right, left, top, bottom, tab |

    staros-tap launcher verb wall.launch_into '{"app": "…"}'

### `wall.open_task` — low, palette word `task`

Open (or focus) a task's terminal: the bridge session task/<project>/<slug> on the task's host, the agent started in it on first creation (claude, guide, code, shell, or a named worlding agent such as greenkeeper).

| argument | type | notes |
|---|---|---|
| `agent` | string | one of claude, guide, code, shell, greenkeeper, warden, stoker, scribe, herald, busker, porter |
| `project` | string | required |
| `slug` | string | required |

    staros-tap launcher verb wall.open_task '{"project": "…", "slug": "…"}'

### `wall.panes` — low, read-only

The workspace wall's open panes: id, title, which is focused, and for a task's terminal its task, session and link status.

    staros-tap launcher verb wall.panes '{}'

### `wall.room_back` — low, palette word `back`

Go back to the room this one was opened from (what Esc does when the focused pane has no use for it).

    staros-tap launcher verb wall.room_back '{}'

### `wall.room_forget` — low, palette word `forget`

Forget a room another box sent (only those; never one of wall.json's, never while it is open).

| argument | type | notes |
|---|---|---|
| `id` | string | required |

    staros-tap launcher verb wall.room_forget '{"id": "…"}'

### `wall.room_open` — low, palette word `room`

Open a room: the arrangement on screen is saved to its workspace, the room's own restored (its seed the first time), its main view focused.

| argument | type | notes |
|---|---|---|
| `id` | string | required |

    staros-tap launcher verb wall.room_open '{"id": "…"}'

### `wall.room_receive` — medium

Keep a room another box sent (this box's applier calls it for a verified room.open op): listed among the rooms as '<title> (from <box>)', opened only when the user opens it.

| argument | type | notes |
|---|---|---|
| `doc` | string | required |
| `from` | string | required |
| `room` | string | required |
| `title` | string |  |

    staros-tap launcher verb wall.room_receive '{"room": "…", "doc": "…", "from": "…"}'

### `wall.room_reset` — low, palette word `reset`

A room back to its seed (wall.json): the open room rebuilt in place, another's arrangement set aside for its next open; wall.room_restore brings the arrangement back.

| argument | type | notes |
|---|---|---|
| `id` | string |  |

    staros-tap launcher verb wall.room_reset '{}'

### `wall.room_restore` — low, palette word `restore`

Bring back the arrangement a room's new seed (or a reset) set aside (the newest kept).

| argument | type | notes |
|---|---|---|
| `id` | string |  |

    staros-tap launcher verb wall.room_restore '{}'

### `wall.room_save` — medium, palette word `keep`

Save the arrangement on screen as a room in wall.json (the tree as its seed, the focused view as its main): through the editor, the format's check first, then the one writer. title, key (a chord), stage, active are optional; write=false keeps it unsaved.

| argument | type | notes |
|---|---|---|
| `active` | boolean |  |
| `id` | string | required |
| `key` | string |  |
| `stage` | string |  |
| `title` | string |  |
| `write` | boolean |  |

    staros-tap launcher verb wall.room_save '{"id": "…"}'

### `wall.room_send` — medium, palette word `send`

Send the room on screen to another box (a fleet host's name): its layout travels as ONE signed room.open op; that box's desk keeps it among its rooms, our apps' windows launching into their leaves when it is opened there.

| argument | type | notes |
|---|---|---|
| `to` | string | required |

    staros-tap launcher verb wall.room_send '{"to": "…"}'

### `wall.rooms` — low, read-only

The rooms the wall's document names (wall.json rooms): id, title, key, main, which is active, which is open.

    staros-tap launcher verb wall.rooms '{}'

### `wall.split` — low, palette word `split`

Split the focused pane with a new local terminal, to the right or below.

| argument | type | notes |
|---|---|---|
| `side` | string | one of right, bottom |

    staros-tap launcher verb wall.split '{}'

### `wall.window_open` — low, palette word `window`

Put a window the window manager lists (its wid, mac:<pid>:<n>) into a WINDOW leaf beside the focused pane.

| argument | type | notes |
|---|---|---|
| `side` | string | one of right, left, top, bottom, tab |
| `wid` | string | required |

    staros-tap launcher verb wall.window_open '{"wid": "…"}'

### `wall.workspace` — low, palette word `ws`

Switch to a named workspace (its saved tile layout).

| argument | type | notes |
|---|---|---|
| `name` | string | required |

    staros-tap launcher verb wall.workspace '{"name": "…"}'

### `wall.workspaces` — low, read-only

The named workspaces (tile layouts) and which is active.

    staros-tap launcher verb wall.workspaces '{}'

<details class="changes">
<summary>The work on this page: the commits of the last 30 days on its sources, the work open against them, its checks</summary>

[[timeline: src=love-shared/docs/verbs/launcher.md | kinds=commit | days=30]]

[[work: open | src=love-shared/docs/verbs/launcher.md]]

[[work: checks | rows=lint/web-reference,lint/verb-sheets]]

</details>

<nav class="pager"><span></span><a href="../../">The reference</a><span></span></nav>

*Generated by `tools/reference_pages.py` from `love-shared/docs/verbs/launcher.md`; the twin `bfaad079a7ce` (434093 bytes). The words are a draft.*

</div>
