# scenes

> Reference for the scenes tool of Author: scene text, with every action and the arguments you can pass.

Source: https://author.geenius.io/docs/reference/scenes/

A scene's text, in Markdown. A profile is mentioned as `@[Name](profile:<id>)`.

Call it as `geenius_author(tool: "scenes", action: "<action>", args: {...})` through Geenius OS.

## Actions

| Action | What it does |
|---|---|
| `read` | A scene's text, its rev and who wrote it last. Rules: scene_id, format? markdown\|plain: the text, rev, who wrote it last. |
| `write` | Replace a scene's text (Markdown). Rules: scene_id, markdown, expect_rev? (REQUIRED to replace text a person wrote in the app — read it first). |
| `append` | Add Markdown to the end of a scene. Rules: scene_id, markdown. |
| `patch` | Find and replace inside a scene's text. Rules: scene_id, find, replace, all?, expect_rev?. |

## Arguments we have checked

### scenes · read

A scene's text, its rev and who wrote it last. Rules: scene_id, format? markdown|plain: the text, rev, who wrote it last.

- `format`
- `scene_id` (required)

### scenes · write

Replace a scene's text (Markdown). Rules: scene_id, markdown, expect_rev? (REQUIRED to replace text a person wrote in the app — read it first).

- `expect_rev`
- `markdown` (required)
- `scene_id` (required)

### scenes · append

Add Markdown to the end of a scene. Rules: scene_id, markdown.

- `expect_rev`
- `markdown` (required)
- `scene_id` (required)

### scenes · patch

Find and replace inside a scene's text. Rules: scene_id, find, replace, all?, expect_rev?.

- `all`
- `expect_rev`
- `find` (required)
- `replace` (required)
- `scene_id` (required)

> [!TIP]
> Ask for the exact arguments of any action with `action: "help", of: "read"`. The server answers from its own definitions, so that answer is always current.

> [!WARNING]
> To replace text a person wrote in the app, read the scene first and pass its revision as expect_rev, so you never overwrite a newer edit.