# Authoring Buttonizer Buttons - `.buttonize` Reference (for AI agents)

> Self-contained: an agent that reads ONLY this file can create valid,
> well-behaved buttons on a user's host. Reflects the app's actual parser
> (`ButtonDef` / `ParamDef`) as of 2026-09-13. For a **desktop or Windows**
> target, section 8 applies on top of everything else.

Deep dives (open only when needed): field reference (English) -
https://buttonizer.app/yaml · runnable examples - `examples/` · CLI appendix -
`docs/desktop-cli.md` · failure-repair wrapper - `docs/agent-wrapper-pattern.md`
· end-user manual - `Manual.md`

## 0. TL;DR

A button is a **directory** containing a **`button.yml`** file:

```
~/.buttonize/buttons/<folder...>/<button-id>/button.yml
```

Create that file under the desktop's `~/.buttonize/buttons/` tree and the paired
phone picks it up on its next list refresh (~10 seconds while the app is open).
No daemon, no restart. Minimum viable button:

```yaml
# ~/.buttonize/buttons/hello/button.yml
id: hello
title: Hello
command: echo "Hello from $(hostname)"
updated_at: "2026-09-13T00:00:00Z"
```

Rules that bite (details in the linked sections):

| # | Rule |
|---|---|
| 1 | The directory name MUST equal the `id` value. |
| 2 | Bump `updated_at` to the current UTC (`YYYY-MM-DDTHH:MM:SSZ`) on EVERY edit - the desktop records it on save and the phone compares it (§6). |
| 3 | Quote every hex color (`color: "#3B82F6"`) - an unquoted `#` starts a YAML comment and silently nulls the field. |
| 4 | Every `{{param}}` in `command` needs a matching `params:` entry (§3); a scheduled button needs a `default` for each one (§2.3). |
| 5 | `enabled: false` = drawn dimmed and **not run by any path** (manual, scheduled, service start, CLI); the run/start APIs refuse it with HTTP `409`; omit the key for a normal button (§2.2). |
| 6 | Never touch the app-managed run records inside a button bundle: `status.json` (last run state), `tail.log` (output tail) and `history/<YYYY-MM>.jsonl` (§1). |
| 7 | Commands are NOT always POSIX: a Windows desktop runs them through `cmd /C` (§8). |
| 8 | **Defaults are a promise.** Write a default (top-level key or `params[].default`) only when that value is certain to be used in almost every run, or when it was explicitly requested - otherwise omit it and let the run sheet ask (§2.6). |

---

## 1. `~/.buttonize/` layout

| Path | Role | Who writes it |
|---|---|---|
| `buttons/` | All buttons + folders. The desktop owns them; the paired phone reads/writes them over the channel RPC (`list_buttons` / `button_edit_full`). | You and the app |
| `buttons/<folder>/folder.yml` | Folder presentation attrs: `icon`, `order`. Optional — **a directory under `buttons/` is a folder whether or not this file exists**, and empty folders stay visible on the desktop and on every paired phone. Use `folder.yml` only to set an icon or a manual order. | You |
| `buttons/<folder...>/<id>/button.yml` | One button definition. | You |
| `buttons/<folder...>/<id>/<script>.py` ... | Helper scripts/resources of that button; reach them from `command` via `$BTZ_RES` (§4) / `%BTZ_RES%` (§8). | You |
| App-managed (never touch) | `buttons/<folder...>/<id>/status.json` (last run state/mode/pid/exit), `tail.log` (last output tail), `history/<YYYY-MM>.jsonl` (run history - only the newest `history_limit` records per button are kept, default 100, §2) · `settings.json` app settings + `binary_path` (this host's executable, §10). | App only |

- Folder nesting up to **8 levels** (`Demos/Web/Prod/...`). A bundle directory is
  never descended into; if the same directory name exists more than once the
  first one found in the walk wins (root-level bundles before subfolders, sibling
  folders in name order) and the others are **duplicates** - never create
  `<id>/<id>/`. A duplicate id is an **ERROR**: `--validate <id>` prints
  `duplicate id "<id>": N bundles share this directory name: <path1>, <path2>`
  (every candidate path is named) and exits `1`, and `--run <id>` **refuses to
  execute** an ambiguous id (exit `1`, candidates listed) instead of silently
  running the first match.
- A bundle that **cannot be loaded** (YAML syntax error, invalid `ButtonDef`, or a
  duplicate hidden by the winner) is **not silently dropped**: it is shown as a
  **broken entry** in the desktop library (reason + file path, not runnable) and
  the same entries are projected to paired phones (`list_buttons` result carries
  an additive `broken` array: `{name, folder, error, kind}`), so a button that
  does not appear is visibly explained. Broken bundles never enter the runnable
  button list, and `--validate <id>` still reports the underlying ERROR.
- Tree root: `$HOME/.buttonize` on macOS/Linux, `%USERPROFILE%\.buttonize` on
  Windows (`HOME` first, then `USERPROFILE`). The desktop app watches `buttons/`
  and picks up new/edited files live - no restart.

---

## 2. `button.yml` field reference

| Key | Type | Required | Default | Notes |
|---|---|---|---|---|
| `id` | string | yes | - | Must equal the bundle directory name. Use `[a-z0-9-]`. |
| `title` | string | yes | - | Shown on the button card. Any language; short reads better. |
| `description` | string | no | - | One-line summary. Desktop-only, see after the table. |
| `command` | string | yes | - | Shell command. Runs **locally on the desktop** that owns the button, wrapped in `cmd /C` (Windows) / `sh -c` (macOS+Linux) (§8). A phone-initiated run sends a `run` RPC over the WebRTC data channel and the desktop executes the same local path. Supports `{{param}}` (§3); `>-` block scalars are fine. |
| `params` | list | no | `[]` | Parameter definitions (§3). |
| `color` | hex string | yes* | `#3B82F6` | Center/base color. **Quote it.** *Omitted fields fall back to defaults, but set it explicitly. |
| `color_tl` `color_tr` `color_br` `color_bl` | hex string | no | nil | Corner colors. Center + >=2 corners = gradient; missing corners are blended automatically. |
| `size` | float | no | `1.0` | Fraction of one grid cell, clamp `0.5 ... 1.0`. YAML may render `1e+0`. |
| `shape` | enum | no | `rounded` | `rounded` \| `circle` \| `square`. |
| `icon` | string | no | `lucide:circle` | One string, three sources: `lucide:<kebab-name>` (e.g. `lucide:hard-drive`) - `res:<image beside button.yml>` (jpeg/png/svg/gif/webp, fetched like other resources) - `https://...` (downloaded + cached on first render). Unknown/empty → plain circle, never breaks (§8.2). |
| `show_log` | bool | no | `false` | `true` = pop the output panel after running. Turn ON when the output matters. |
| `enabled` | bool | no | `true` | The button's on/off switch. `false` = drawn **dimmed** on every client and it does not run at all - no manual run, no channel request, no scheduled run, no service start (`POST /api/service/start`) or supervised restart, no CLI `--run`, no editor entry from the card. The HTTP run/start paths refuse it with `409 {"error":"button is disabled","detail":"button \"<id>\" is disabled (enabled: false)"}`. Omit the key (or set `true`) for a normal button: apps write `enabled: false` only, so untouched files stay clean (§2.2). |
| `run_mode` | enum | no | `short` | `short` \| `long` \| `service` \| `scheduled` \| `detach` (displayed as **Immediate**, **Long Running**, **Service**, **Scheduled**, **Detach**). short = return the result immediately (default timeout 5s; on timeout the tree is killed and a timeout error is recorded) - long = return to the UI right away, notify on completion/timeout (default 600s) - service = run until explicitly stopped; on death notify and restart per `restart_on_exit` - scheduled = run at the times in `schedule` (§2.3); behaves like `long` when it does - **detach = fire and forget**: start it and stop tracking (no running badge, no timeout, no notification, no history); the output keeps going to the button's `tail.log`, which the log view shows. |
| `schedule` | string | no | - | **Only with `run_mode: scheduled`** (ignored otherwise; the validator WARNs). Cron: `"minute hour day-of-month month day-of-week"`, e.g. `"0 9 * * 1"` = every Monday 09:00 (§2.3). |
| `restart_on_exit` | bool | no | `true` | Long-running/**service** mode only (meaningless for `short`/`long`/`scheduled`). After the service process exits **on its own**, the desktop restarts it when `true`; `false` = notify only. Restarts are supervised with backoff **1s, 2s, 4s, 8s, 16s, then 30s** (capped); after **5 restarts inside 10 minutes** the supervisor treats it as a rapid-failure loop, gives up and reports the service as stopped with that reason. A stop the user initiated (UI stop or `POST /api/service/stop`) cancels supervision, and a disabled button is never restarted (§2.2). Supervised state is observable via `GET /api/services`: each running entry carries `restart_count` (restarts inside the current 10-minute window) and, after a give-up, `restart_stop_reason`. |
| `timeout` | int seconds | no | per-mode (short 5 / long 600 / service unlimited) | On expiry the whole process tree is killed: short = timeout error recorded - long = timeout notification - service = 0/unset = unlimited (a positive number is the only limit). |
| `history_limit` | int | no | `100` | Per-button **finished-run history retention**. Keep at most this many records in the button's `history/<YYYY-MM>.jsonl` (newest kept, oldest dropped; whole monthly files beyond the limit are deleted, the boundary file keeps only its newest surviving lines). The same cap applies to the phone's local history cache. `0` = keep no history records for the button - the run result is still returned to the caller and shown normally. Absent = 100, so buttons written before this key existed end up limited to the newest 100 (a one-time, idempotent startup sweep trims what is already on disk). Must be an integer `>= 0`: negative, non-integer (`1.5`) or a non-numeric type (`abc`, `true`) is a validation **ERROR**. No upper bound. |
| `service_log_seconds` | int seconds | no | `5` | **Startup-log delay for `run_mode: service`.** When a service is started, the app waits this many seconds, collects the output produced in that window (the host keeps the newest 100 KB) and shows it — the "did it come up?" check. `0` = no automatic log sheet (open the log view manually — the view always shows the recent 100 KB). Absent = **5**. Must be an integer `>= 0`: negative, non-integer (`1.5`) or a non-numeric type (`abc`, `true`) is a validation **ERROR**. No upper bound. See 2.5. |
| `output_path` | string | no | - | **Run artifact path** (optional; `{{param}}` substitution allowed). A relative path is resolved against the button's bundle folder; `~/…` and absolute paths must stay **under `$HOME`** - an absolute path that escapes it is a validation **ERROR**. After each run the file is **moved** (not copied) into the button's `history/` and recorded on that history line as `artifact: {orig, file, size, mtime}`. Only an allowlist of extensions is collected (see 2.4); anything else is a validation **WARN** and the file is left in place. |
| `output_auto_open` | bool | no | `false` | Open the collected artifact automatically when the run finishes. Applies **only when `run_mode: short` (Immediate) AND a present desktop client triggered the run** - `long`, `service` and `scheduled` never auto-open, nor do scheduled, service/restart, chain or other unattended runs. Must be a real boolean: a quoted `"true"` is a validation **ERROR**; `true` with a non-`short` effective mode is a validation **WARN** (the key is accepted but has no effect). See 2.4. |
| `span_cols` | int | no | `1` | How many grid **columns** this button fills - `1` or `2` (`2` = a wide button). Clamped to `1..2` when drawn; a value outside that range is a validation **WARN** (`--validate`, exit 0) - a bad number never breaks the layout. Presentation only. See 2.8. |
| `span_rows` | int | no | `1` | How many grid **rows** this button fills - `1` or `2` (`2` = a tall button; with `span_cols: 2` as well it is a **2×2 / four-cell** button). Same clamping/WARN rule as `span_cols`. Presentation only. See 2.8. |
| `icon_background` | bool | no | `false` | Use the **image** icon (`res:<file>` / `https://...`) as the **full-tile background** instead of a small glyph in the icon slot: the image is drawn behind the whole tile (cropped to fill), a dark scrim is laid over it and the text turns white. Ignored for glyph icons (`lucide:...`). Presentation only. See 2.8. |
| `tags` | list of strings | no | `[]` | Cross-folder grouping (`tags: [deploy, nightly]`). Normalized on decode: trimmed, lowercased, `/` `,` `@` stripped, deduped, sorted, max 20 x 32 chars; an empty list is OMITTED from YAML. UI pseudo-filters such as the "running" chip and `@host` are phone-local view state, never stored. |
| `created_at` | ISO8601 | no | - | `YYYY-MM-DDTHH:MM:SSZ`. Set once at creation. |
| `updated_at` | ISO8601 | **yes** | - | Bump on EVERY edit (§6). |

**Desktop-only fields.** `description` (button-level and per-param) is ignored by
the phone parser; the desktop editor Info tab, the run sheet and the per-button
operation description in the OpenAPI `/docs` show it. Warning: editing + saving
this button in the mobile app may DROP the key (iOS encodes known keys only).

### 2.1 Unknown (extra) top-level keys

A key the host does not know is **never deleted**: the value is kept exactly as
received (type included - nested maps, arrays, numbers, booleans, null), marked
with an inline comment, and written back on every save:

```yaml
title: Deploy
command: ./deploy.sh
my_future_key: 42   # unknown key — Buttonizer does not interpret it and preserves it as-is
```

- Only **top-level** keys are preserved; unknown keys inside `params:` entries or
  inside `schedule:` are dropped/regenerated. `--validate` reports both kinds, so
  a typo never passes unnoticed.
- The marker is generated on save; because YAML comments are not preserved when
  parsed, a marker on a key that has since become known is **removed** on the next
  save and never duplicated (hand-written comments are dropped on save).
- Every client (desktop, iOS, Android) preserves and re-sends unknown top-level
  keys it receives, so a new field later does not require every app to update in
  lockstep.

### 2.2 Disabled buttons (`enabled: false`)

`enabled` is the per-button on/off switch. It is **absent by default and a
missing key always means enabled**, so adding it to one button never disturbs the
others:

```yaml
enabled: false      # omit = true (enabled)
```

| Behaviour | Detail |
|---|---|
| Dimmed + inert | Drawn dimmed on every client; no manual run, no channel request (phone RPC), no scheduled run, no service start (`POST /api/service/start`), and no restart is ever attempted. The HTTP run/start paths refuse it with `409 {"error":"button is disabled","detail":"button \"<id>\" is disabled (enabled: false)"}` (`POST /api/run` and `POST /api/run/{id}`), and the phone-requested run returns the same reason string - run, phone run and service start now agree. The card's **Edit** menu item still opens the editor (the only way to re-enable) and property changes saved there apply normally. |
| Written only when off | Apps write the key only when it is `false`; choosing "Enabled" in the editor removes it, so a never-disabled button keeps a pristine `button.yml`. A missing key, `enabled: true` and any payload omitting the field are all enabled (old files/clients stay valid). |
| Live on hand-edit | The desktop watches `buttons/`, so flipping the value on disk hits the open window within a fraction of a second - no restart, no reload (the phone sees it on its next refresh, ~10 s). `--validate` accepts the key: it is known, not an "unknown key" ERROR. |
| Not a schedule pause | `enabled: false` stops every execution path; `schedule_enabled: false` (§2.3) only pauses automatic runs and leaves the button manually runnable. |

### 2.2b Fire and forget (`run_mode: detach`)

`detach` starts the command and **stops tracking it**: no running badge, no
timeout kill, no completion notification, no restart supervision, no history
entry. The process is started in its own process group with stdout/stderr going
straight to the bundle's `tail.log`, so it keeps running after the desktop quits
and **the log stays viewable** (tile menu → Run Log / History; the desktop's
`/api/status` returns the tail even when nothing is running).

Use `long` when you want a completion notification, `service` when you want
start/stop/restart supervision, and `detach` when you just want the command to
go. A `service` that dies **on its own** is announced (desktop notification +
push to the phone that started it) whenever it will not be supervised anymore —
`restart_on_exit: false` ("notify only"), disabled/removed button, failed
restart spawn, or the supervisor giving up after 5 restarts in 10 minutes. A
death that is about to be restarted is not announced (flapping services would
spam); a user-initiated stop never notifies. `timeout` is not enforced in this mode (like `service`). Unknown `run_mode`
values still fall back to `short`; `fire_and_forget` / `fire-and-forget` are
accepted as aliases of `detach`.

Monitoring at a glance:

| `run_mode` | waits for exit | default timeout | "Running" badge | notification | restart |
|---|---|---|---|---|---|
| `short` | yes | 5 s | while it runs | no | no |
| `long` | no | 600 s | while it runs | `notify_on_done` | no |
| `service` | no | none | until stopped | on unexpected exit (not restarted / gave up) | `restart_on_exit` |
| `scheduled` | no | 600 s | while it runs | `notify_on_done` | no |
| `detach` | no | none | **never** | no | no |

### 2.2d How fast does a change show up? (measured 2026-09-30)

The desktop watches `~/.buttonize/buttons` with the OS watcher (FSEvents/inotify,
no polling) and pushes changes to the app window (WS `/api/events`) and to paired
phones (channel push `{"t":"ev", scope, path, rev}`).

| Changed | Host detects | Desktop applies | Phone applies |
|---|---|---|---|
| `button.yml` / `folder.yml` | **13 ms** (12–14 ms measured) | next tick (grid reload) | next push → `list_buttons` refetch (RTT) |
| a `res:` resource | **12 ms** single write; **~166 ms** while rewritten every second (150 ms debounce) | that file only, swapped after decode (no flicker) | that file only (`scope:"res"` + path) — no list reload |
| `status.json` / `tail.log` | same watcher | running badge/tail | same |
| `access.json` | 1 s mtime poll | — | push → phone reloads list |

Also since 2026-09-30: the desktop tile is **16:9 per cell exactly like the
phones** (row height = column width × 9/16), so the covered area and the crop of
a background image are identical on desktop / iOS / Android. Before that the
desktop row height was content-driven (≈1.4–1.9:1) and cropped backgrounds
differently.

### 2.2c Where run logs are visible (host vs phone)

Runs are recorded on the **host**; the phones show a subset, and the button's
log sheet now shows both sides:

| What | Lives on | Visible from the phone? |
|---|---|---|
| Live output (newest 100 KB) | host `tail.log` | Yes (View log fetches the host tail; `detach` included) |
| Host-started runs — scheduled, desktop/web, tray, chain, service restarts | host `history/YYYY-MM.jsonl` | Yes — the same time-ordered list in the button log sheet, badge `scheduled`/`desktop` (`history` RPC) |
| Runs this phone started | phone-local store | Yes — the same list, badge `this phone` |
| Runs another phone started | host history (`phone` label) | Yes — same time-ordered list, badge `phone` |
| `detach` runs | host `tail.log` only (no status/history by design) | Yes — the tail |
| Service deaths / restart give-ups | host notification list + push | Yes — the inbox |

`history_limit` (default 100 per button) caps the host history, so the 100 most
recent runs are what every client sees. A button that never ran (invalid cron,
missing defaults, schedule not due yet) legitimately has an empty history.

### 2.3 Scheduled runs (`run_mode: scheduled`)

`run_mode: scheduled` runs the button **automatically** when the host's local
clock matches `schedule`; it stays manually runnable and behaves like `long` when
it runs (background, default timeout 600s, a notification on failure/timeout). A
button with `enabled: false` is skipped too.

```yaml
run_mode: scheduled
schedule: "0 9 * * 1"     # every Monday at 09:00
schedule_enabled: true    # omit = true (active). false = paused
```

`schedule` is a five-field **cron expression** - `minute hour day-of-month month
day-of-week`:

- **Ranges:** minute `0-59` (required) · hour `0-23` · day-of-month `1-31` ·
  month `1-12` (names `jan`...`dec`) · day-of-week `0-7`, where **0 and 7 are
  both Sunday** (names `sun`...`sat`).
- **Syntax:** `*` any (`?` is accepted as a synonym) · `5` single value · `1-5`
  range · `1,3,5` list · `*/15` every 15 · `1-10/2` 1...10 step 2 · `5/10` from
  5 to the field max step 10.
- **Macros:** `@yearly` (`0 0 1 1 *`) · `@monthly` (`0 0 1 * *`) · `@weekly`
  (`0 0 * * 0`) · `@daily`/`@midnight` (`0 0 * * *`) · `@hourly` (`0 * * * *`);
  `@reboot` is an ERROR.
- **Common:** `"0 9 * * *"` daily 09:00 · `"0 9 * * 1-5"` weekdays 09:00 ·
  `"*/30 * * * *"` every 30 min · `"15 * * * *"` hourly at :15 · `"0 0 1 * *"`
  1st of the month · `"0 8 1 * 1"` the 1st **or** any Monday 08:00.

A scheduled button is **active as soon as it is created** - there is no arming
step. `schedule_enabled: false` (or the button menu's **Pause schedule / Resume
schedule** item on any client) pauses it: the host keeps the schedule but skips
it silently and the Schedules view shows no next run; re-enabling resumes at the
next match. Validator-enforced rules:

| Rule | Detail |
|---|---|
| Day fields OR'ed | When both day fields are restricted the day matches if EITHER does: `"0 8 1 * 1"` fires on the 1st *and* every Monday. Restrict one for AND. |
| Local time, no replay | Times are the host's local time (no timezone field); one run per matching minute and a tick missed while the app was closed is not replayed. |
| Skips | A button whose previous run is still going is skipped (no pile-up), as is a disabled one (host log: `skipped (disabled)`). |
| Params need defaults | Unattended, so every `{{param}}` used in `command` must have a `default` (`type: device` is auto-filled; `type: command` params are NOT resolved - give them a default too). The scheduler re-checks before firing and skips with a notification instead of running with a missing value. |
| Bad cron = ERROR | An unparseable cron (`"61 9 * * *"`, `"0 9 * *"`) is an ERROR and the button does not run rather than firing at another time; the Schedules view warns. |
| Legacy block | `schedule: {minute: 0, hour: 9, weekday: mon}` is still read and converted to cron (saving rewrites it as a string, validator WARNs); unknown keys inside it are ERRORs. |
| No restart | Adding/removing `schedule` needs no app restart - the desktop re-reads `buttons/` before each check. |

### 2.4 Output artifacts (`output_path` / `output_auto_open`)

A button can declare the file it produces, so the host keeps it together with the
run record:

```yaml
output_path: ~/out/{{name}}.png   # omit = no artifact; {{param}} is substituted
output_auto_open: true            # default false - short (Immediate) + desktop-triggered runs only
```

- **Resolution.** `{{param}}` tokens are replaced with the values used for that
  run (a supplied value first, then the declared default; an unset token renders
  empty). A relative path is relative to the button's bundle folder
  (`buttons/<folder>/<id>/`); `~/…` and absolute paths are allowed **only inside
  the host's `$HOME`** - an absolute path that escapes `$HOME` is a validation
  **ERROR**. A `{{param}}` that names no declared parameter is also an **ERROR**.
- **Collection.** When the run finishes (success **or** failure) the host
  validates the file - it must exist, be a regular file (not a symlink), have a
  last extension in the allowlist, and canonicalize to a path under `$HOME` - and
  then **moves** it to `history/<YYYYMMDDTHHMMSSZ>-<run_id>-<basename>`
  (basenames are truncated to 80 characters, keeping the extension; a collision
  adds `-2`, `-3`, … before the extension). The original path no longer exists
  after a successful collection.
- **History record.** The move is recorded on that run's history line as an
  optional object: `"artifact": {"orig": "<resolved original path>", "file":
  "<unique name inside history/>", "size": <bytes>, "mtime": "<RFC3339 UTC>"}`.
  When `history_limit` trims a record, the artifact file that record references is
  deleted too - only a plain name inside that button's `history/` is ever removed.
- **Allowlist** (case-insensitive; the **last** extension decides):
  `png jpg jpeg gif webp heic pdf txt md log csv json yaml yml xml mp4 mov mp3 m4a`.
  A last extension outside this list is a validation **WARN** and the file is left
  where it is (never moved, never opened). A file with **no** extension is moved
  into history but cannot be opened. Scripts, executables and installers
  (`sh bash zsh command app scpt workflow dmg pkg jar py exe bat ps1 lnk`) are
  never collected.
- **Auto-open** (`output_auto_open: true`) opens the collected file with the
  host's default application. It applies **only** when **both** hold: the
  effective `run_mode` is `short` (the UI's **Immediate**) **and** a present
  desktop client triggered the run - so `long`, `service` and `scheduled` never
  open anything, and neither do chain/CLI/other unattended runs. `true` with a
  non-`short` effective mode is a validation **WARN** (including the legacy
  inference `run_mode` absent + `notify_on_done: true`, which is `long`); the
  key is accepted but has no effect. A non-boolean value (including a quoted
  `"true"`) is a validation **ERROR**.
- Both keys are optional; absent means "no artifact / do not auto-open", so
  buttons written before this feature keep working unchanged. When an
  `output_path` is declared the produced file is **moved into `history/`** rather
  than left in place.

### 2.5 Service startup log (`service_log_seconds`)

A `run_mode: service` button never "finishes", so there is no run result to read.
When the service is **started**, the app therefore waits `service_log_seconds`
(default **5**) and then shows the output produced in that window - the "did it
come up?" check:

```yaml
run_mode: service
service_log_seconds: 5   # seconds; omit = 5; 0 = no automatic log sheet
```

- The host keeps the newest 100 KB of the running process in the button's
  `tail.log`. The log sheet shows that window, and so does the manual log view
  (button menu → Run Log / History) at any time, running or finished.
- `0` turns the automatic sheet off - the log is still collected and available
  from the menu. Any other non-negative integer is accepted.
- A value that is not a non-negative integer (negative, `1.5`, `abc`, `true`, a
  list) is a validation **ERROR**; the app falls back to 5 seconds and the raw
  value is preserved verbatim, exactly like `history_limit`.
- Key absent ⇒ 5 seconds. Buttons that never declared the key keep their
  `button.yml` unchanged (the key is not written back).
- The phones (iOS/Android) read the same key and show the same startup log after
  starting a service.

### 2.6 Defaults: only when the value is certain (or was requested)

Most keys fall back to a built-in value when they are absent (`run_mode` →
`short`, `timeout` → per-mode, `history_limit` → 100, `service_log_seconds` → 5,
…). Those table defaults are not what this section is about - **what an author
writes into the file** is. A written default is a promise: it is the value the
app uses **without asking**, in every run that does not override it, on every
client.

So write a default only when one of these holds:

1. **It is certain that almost every run uses that value** — e.g. a `number`
   parameter whose range is fixed by the tool being wrapped, or a
   `service_log_seconds` / `timeout` value that this button always wants.
2. **It was explicitly requested** — a person asked for that value, or the
   button came from a spec/share/example that named it.

Otherwise **omit the key** (and `params[].default`). Omission is the honest
state: the run sheet shows an empty field the user must fill, and `--validate`
reports `Required before run: <name>` instead of silently running with a guess.

Corollaries:

- A default that "looks reasonable" but is usually wrong is an **authoring bug**:
  it hides a decision and produces runs that quietly do the wrong thing — worse
  than an empty field, because nothing on screen says a guess was made.
- Unattended runs are the exception that *requires* defaults: `run_mode:
  scheduled` (and any service restart path that re-runs the button) can only use
  values that exist without a human, so every referenced parameter needs a
  `default` (§2.3) - the desktop refuses to schedule otherwise.
- If a default is genuinely justified, say why where a human will read it: the
  button's `description`, or the parameter's `description`.

### 2.7 Service start asks for values

A service is started with the values from the run sheet (the same sheet the tile
menu's `Parameters & preview…` opens): declared defaults are prefilled, and what
the user changes is what the process receives. Two consequences:

- A `{{param}}` with **no value and no default** blocks the start: the apps open
  the sheet instead of starting, and `POST /api/service/start` answers
  `400 {"error":"missing params","params":[…]}`. A service never runs with a
  silently empty argument - it would keep running wrong until someone noticed.
- When every value is already known (all params have defaults), tapping the tile
  starts the service directly; open the sheet from `Parameters & preview…` when
  you want to change a value first. `POST /api/service/start {"id":…,"params":{…}}`
  is the same path for scripts.

### 2.8 Grid span and image background (`span_cols` / `span_rows` / `icon_background`)

A button can occupy more than one cell of the library grid, and an image icon can
be stretched across the whole tile:

```yaml
span_cols: 2          # 1..2 — grid columns this button fills (omit = 1)
span_rows: 2          # 1..2 — grid rows this button fills (omit = 1)
icon_background: true # image icon as the tile's full background (default false)
```

- **Cells.** `span_cols: 2` = wide (two-column), `span_rows: 2` = tall (two-row),
  both together = **2×2 (four cells)**. Each value is clamped to `1..2` when
  drawn; a value outside that range is a validation **WARN** (`--validate`, exit
  0) - a bad number never breaks the layout. Like `timeout`, the keys accept a
  number or quoted digits; a value that is not a number at all makes the bundle
  fail to load (`yaml_parse`), exactly like the other typed keys.
- **The rest of the grid flows around it.** The multi-cell tile lands on the
  first free cell (left to right, top to bottom) and the other buttons fill the
  cells around it, so a wide/tall button can leave the cells it skipped empty -
  the same result as a CSS grid without `dense` packing.
- **All three clients agree.** The desktop library is a CSS grid; iOS and
  Android compute the placement with the same greedy rule and draw the tile at
  `span_cols × span_rows` cells (a tall/wide tile is sized from the 16:9 cell
  plus the gaps it spans). Keep the keys small: they are for emphasis (a hero
  button, a wide "deploy" tile), not for building arbitrary layouts.
- **Defaults stay out of the file** (the §2.6 rule): absent means `1`, and the
  apps write the key only when it is `2`, so a button that does not use spans
  keeps its `button.yml` byte-for-byte identical.
- **`icon_background`** applies only when `icon` is an image (`res:<file>` or
  `https://...`): the image is drawn **behind** the whole tile (cropped to fill),
  a dark scrim is laid over it, and the title/status text is forced to white.
  A glyph icon (`lucide:...`) ignores the key and keeps the small icon slot. If
  the image fails to load the tile falls back to its normal colour/gradient
  background (never a giant placeholder glyph).
- All three keys are presentation-only: they never affect the command,
  parameters, execution, history or scheduling, and older clients that do not
  know them keep working unchanged (they are preserved on save).

#### Image fitting - exact aspect-ratio rules

An image icon is drawn in exactly one of two places, and the two places use
**different fitting rules**. The rules are identical on the desktop, iOS and
Android; only the box they apply to differs:

| Drawn as | Box (aspect) | Rule | When the image's ratio differs |
|---|---|---|---|
| **Icon slot** (default) | a **1:1 square** - desktop `30x30 px`, iOS `16x16 pt` (in a 22 pt slot), Android `20x20 dp` (in a 22 dp slot) | **contain**: `object-fit: contain` / `scaledToFit()` / `ContentScale.Fit` | the **whole** image is visible, ratio preserved: the shorter side leaves empty (transparent) bars - a 16:9 image is letterboxed top/bottom (each bar is about 21.9% of the slot), a portrait one is pillarboxed left/right. Never cropped, never stretched; the tile's colour/gradient shows through the bars. |
| **Tile background** (`icon_background: true`) | the **whole tile** (ratio below) | **cover**: `object-fit: cover` / `scaledToFill()` / `ContentScale.Crop` | ratio preserved, both sides filled, image centred, overflow **clipped** by the tile's rounded corners. No bars, no stretching. The visible share is `smaller ratio / larger ratio`: a **1:1** image in a 16:9 phone tile keeps only its middle **56%** of height; a **1.6:1** image in a 1.44:1 desktop tile keeps **90%** of width. |

The **box ratio** the background is cropped to:

- **iOS / Android**: one cell is exactly **16:9**; a spanning tile is
  `cols x cellW + gap x (cols-1)` wide and `rows x cellW x 9/16 + gap x (rows-1)`
  tall (gap = 12 pt/dp). A 1x1 tile is therefore exactly 16:9, while multi-cell
  tiles are a little wider than an exact multiple (measured on Android: 2x2 =
  1016x583 about 1.74:1, 1x2 = 495x583 about 0.85:1, 2x1 = 1016x278 about
  3.66:1).
- **Desktop**: the library is a CSS grid - `repeat(auto-fill, minmax(150px, 1fr))`
  with `grid-auto-rows: minmax(110px, auto)` and a 12 px gap - so the tile ratio
  **depends on the window width and on the content** (a longer title makes a row
  taller). Measured in the live UI: 1x1 = `158.8x110` (1.44:1) at a 1280 px
  window and `203x110` (1.85:1) at 900 px; 2x1 = 3.00:1 / 3.80:1; 1x2 =
  `...x232` (0.69:1 / 0.88:1); 2x2 = 1.42:1 / 1.80:1. The desktop tile is
  therefore **not** 16:9, so the same background image is cropped slightly
  differently there than on the phones.

Worked examples for a `1600x1000` (1.6:1) logo:

- **Icon slot** - desktop: a 30 px box letterboxes it to `30x18.75`; iOS:
  `16x10` inside the 16 pt slot; Android: `20x12.5` inside the 20 dp slot. Bars
  above and below on all three; the picture is never cut.
- **`icon_background` on a 1x1 tile** - the phone tile is 16:9, so the image is
  scaled to the tile height and **90% of its width** is visible (5% cut off on
  each side, centred). The desktop tile at 1280 px is 1.44:1 (also **90%**);
  at 900 px it is 1.85:1 (**86%**).
- **`icon_background` on a 1x2 (tall) tile** - the box is taller than it is
  wide, so the same 1.6:1 logo is scaled to the tile width and most of its
  **height** is cropped: only about 53% (Android) or 43% (desktop at a 1280 px
  window) of the height is visible.
- **SVG**: the ratio and the drawing scale come from `viewBox`, or - when there
  is none - from the root **`width`/`height`**, which all three platforms now
  treat like a `<img>`'s intrinsic size (a viewBox-less Inkscape file used to be
  drawn at 1:1 and end up as a small patch in a corner, or clipped to its
  top-left corner on Android). Still, **give every SVG a `viewBox`**: with
  neither a viewBox nor numeric `width`/`height` the platform default applies -
  Android **24x24 (square)**, iOS **1:1**, a browser **300x150**. iOS rasterizes
  the SVG once (longest side <= 1024 px, upright) and then applies the same
  contain/cover rules to that bitmap. On Android the SVG is rendered by
  **AndroidSVG** (`com.caverock:androidsvg`) - the same library Coil/Sketch use -
  which covers linear/radial gradients (with `gradientTransform` and
  `xlink:href` inheritance), `clipPath`, `mask`, `pattern`, `use`/`symbol`, and
  basic text. Limits on Android: `<filter>` is not rendered and radial gradients
  ignore the `fx`/`fy` focal point. An SVG with **no colours of its own**
  (`currentColor`/undeclared) is not rasterized: the built-in vector parser draws
  it and the app tint (the tile's text colour) is applied, so monochrome icon
  files stay visible on dark tiles. If AndroidSVG cannot parse the file, that
  built-in parser is the fallback (gradients approximated by their first stop,
  `style="fill: ..."`, `rgb()`/`rgba()`, `fill-opacity`, `xlink:href`, and the
  SVG default black for undeclared fills).
- **Animated GIF**: the desktop webview plays the animation; the phones decode a
  still bitmap, so only the **first frame** is shown.
- **A failed fetch or an undecodable file** never stretches and never leaves a
  giant placeholder: the icon slot falls back to a `circle` glyph (iOS/Android)
  or an emoji (desktop), and `icon_background` falls back to **nothing** on iOS
  (tile gradient + scrim), a small 32 dp `circle` on Android, or a small emoji
  above the title on the desktop.

---

## 3. Parameters (`params`)

Each entry has `name`; the command references it as `{{name}}`. Referencing an
undefined `{{token}}` makes the app refuse to save/run the button - keep names
consistent.

```yaml
params:
- name: target
  type: string         # string | number | boolean | select | file | upload | path | image | command | device | text
  description: "Which host to target (short name)"   # desktop-only: run sheet + /docs
  default: "~"         # key is literally  default:
- name: level
  type: select
  options: ["debug", "info", "warn"]
```

The file-ish types differ in **where the value lives**. `file` and `path` are
**host-side** - they name a **host (desktop) file/folder**: the desktop offers a
local picker, and a paired phone browses the **host** filesystem over the channel
(`file_list` RPC), so they ARE supported from the phone, not desktop-run only -
and both substitute an **absolute host path** (the host file root plus the path
picked in the browser). `upload` and `image` are **device-side on the phone**: the
phone's document picker (`upload`; `UIDocumentPicker` on iOS, SAF on Android) or
photo library (`image`) is the source, the bytes are uploaded to the desktop, and
the substituted value is the resulting **host** path
(`~/.buttonize/uploads/…`); on the desktop both are local pickers. `file`, `upload`
(with `multiple: true`) and `image` hold one or more newline-separated paths and
expand to one shell argument per path; `text` is multiline free text and
substitutes exactly ONE POSIX single-quoted argument with newlines preserved
(older clients fall back to a single-line input); `description` (any param) is
one-line help text, desktop-only (same mobile-save warning as §2).

**`type: file` / `type: upload` with `multiple: true` - several files.** The
desktop picker accepts several files and the value becomes newline-separated paths
that expand to **N single-quoted arguments**, one per path - the same rule `image`
always uses. `multiple` is a bool, default `false`; on any type other than
`file`/`upload` it is ignored (`--validate` WARNs).

**`type: number` bounds + slider: `min`, `max`, `step`.** All three are numbers
and `step` defaults to `1`. When **both** `min` and `max` are set the desktop UI
renders a **slider**; otherwise a plain number input. `min`/`max` are
**enforced at every entry point** - the desktop run sheet, the REST run
(`/api/run`), the phone channel request and the CLI `--run` - and an
out-of-range value is refused with
`parameter "<name>" value "<value>" is below the allowed minimum <min> (allowed range <min>..<max>)`
(or `... is above the allowed maximum <max> ...`); with only one bound the range
renders `<min>..` / `..<max>`. REST run answers
`400 {"error":"parameter out of range","detail":<message>,"param":"<name>","value":"<value>"}`;
the CLI `--run` prints the same message as an ERROR (exit 1). `step` is UI
granularity only and is **NOT** enforced. `--validate` errors on `min > max`
(`param "<name>" min <min> > max <max> (allowed range <min>..<max> is empty)`)
and `step <= 0` (`param "<name>" step <step> must be > 0`); `min`/`max`/`step`
on a non-`number` type are ignored with a WARN.

**`group` / `param_groups` - presentation only, no runtime effect.** A param may
carry `group: "Display name"`, and the button may declare
`param_groups: [{ title, collapsed }]`. This changes only how the run sheet lays
the fields out. Params **without** a group render first with no header; declared
groups follow in declared order (honouring `collapsed`); a group name used by a
param but not declared appears after them, in first-appearance order. Groups
never change the rendered command, and clients that do not know the keys ignore
them. A button author sets them by writing the keys in `button.yml`, or in the
desktop editor (a per-param `group` field and a button-level group list with
`title`/`collapsed`).

**`type: device` - no user input.** The app that RUNS the button fills its own
stable id: phone run → the phone's install uid (`du-...`, see
`docs/stable-device-identity.md`); desktop/HTTP (`/api/run`) run → that desktop's
desk id (`dsk-...` from `~/.buttonize/channel.json`). Run forms hide the field or
show it read-only and never prompt; `default`/`options` are unused.

**`type: command` - chained pickers.** A param can be fed from the output of
another command on the same host (session/window lists):

```yaml
params:
- name: session                       # helper: never appears in the final command
  type: command
  sourceCommand: tmux list-sessions -F '#{session_name}~~~#{session_windows} windows'
  outputMode: pick
  separator: "~~~"
  isInternal: true                    # referenced only by the chain below
- name: window
  type: command
  sourceCommand: >-
    tmux list-windows -t {{session}} -F '#{window_index}: #{window_name}~~~{{session}}:#{window_index}'
  outputMode: pick
  separator: "~~~"
```

- `sourceCommand` runs on the host; it may use `{{other_param}}` defined EARLIER
  in the list (chains flow top-down).
- `outputMode`: `pick` (user chooses one line) or `all` (entire output as value).
- Display/value split: with `separator: "<sep>"` split at the FIRST occurrence -
  left side shown, right side substituted (prefer a sequence unlikely to occur in
  content, e.g. `~~~`, not `|`); without `separator` the whole line is both;
  `tabSeparated: true` splits on TAB.
- `isInternal: true` marks helpers consumed by later params only; they are not
  appended to the button's command.

**Substitution quoting (verified 2026-09-05, Windows 10 + PowerShell 5.1):** each
`{{name}}` value is substituted **wrapped in POSIX single quotes** (`value` →
`'value'`). POSIX shells strip them, so this is invisible on macOS/Linux;
`cmd.exe` does NOT treat them as quoting characters (they arrive literally),
while PowerShell DOES understand them (§8.3).

---

## 4. Resources, env vars, notifications

Helper scripts belong INSIDE the button's bundle directory. These env vars are
exported for every run:

| Var | Value |
|---|---|
| `BTZ_ID` | The button id. |
| `BTZ_RES` | Absolute path of the button's own bundle directory. |
| `BTZ_HUB_URL` | Hub base URL the desktop is connected to (e.g. `https://buttonizer.app/hub`). |
| `BTZ_DEVICE_ID` | Device id of the phone that tapped this button (`du-...`). **Only for phone-requested runs**; unset for desktop-GUI/CLI/scheduler/chained runs. Pass it as `device_id` and let the desktop route. |
| `BTZ_PUSH_ID` | *(legacy, backward compatible)* Push address of that phone ("폰 메시지" inbox, `p_...`), same lifetime as `BTZ_DEVICE_ID`; kept working unchanged, new buttons do not need it. |
| `BTZ_PAIRED_DEVICES` | **Every phone paired to this desktop**, as a JSON array - **always present** (`[]` when none). `[{"dev_id":"du-...","name":"Buttonizer ios","paired_at":"2026-09-24T00:00:00Z"}, …]` (sorted by `dev_id`). Use the `dev_id`s to talk to one specific phone (a `POST /api/notify` with `device_id`, an `upload`/RPC of your own) or just report who is connected; the list is the last known one, so it also works offline. |
| `BTZ_NOTIFY_URL` | Local notification endpoint (`http://127.0.0.1:37921/api/notify`) - **always present**. |
| `BTZ_NOTIFY_TOKEN` | Bearer token for `BTZ_NOTIFY_URL`. |

**Notify the device that pressed it - one lane, no branching.** POST to
`$BTZ_NOTIFY_URL` with only `device_id`; **the desktop decides** where it goes: a
phone paired to this desktop is delivered through the hub (which resolves that
phone's APNs/FCM credential), anything else is shown locally.

```sh
command: |
  curl -s -X POST "$BTZ_NOTIFY_URL" \
    -H "Authorization: Bearer $BTZ_NOTIFY_TOKEN" \
    -H 'Content-Type: application/json' \
    -d "{\"device_id\":\"$BTZ_DEVICE_ID\",\"button_id\":\"$BTZ_ID\",\"title\":\"작업 완료\",\"body\":\"…\"}"
```

Body fields: `device_id?` (target), `title` (required, ≤200 chars), `body`
(≤4000), `subtitle?`, `button_id?`, `category_id?`, `banner?` (`false` records
without an OS banner). Always send `button_id` (`$BTZ_ID`): it is the button's
provenance and, when routed to the phone, that phone's **inbox grouping key**, so
the alert lands in the button's own "알림 보기" list. `category_id` overrides that
grouping when present (several buttons can share one group; an empty string
forces the uncategorised bucket); with neither field the alert is grouped by the
recipient address's own category.

**Targets.** `device_id` selects who gets it:

| `device_id` | Where it goes |
|---|---|
| a `du-...` id (`$BTZ_DEVICE_ID`) | that phone, if it is paired to this desktop — the desktop asks the hub, which resolves the phone's APNs/FCM credential. A `du-...` that is **not** this desktop's phone (or a desktop that never paired) falls back to a local notification (`200` + `routed:"local"`). |
| `"*"` | **every phone paired to this desktop** (broadcast) — see below. |
| omitted / empty | local only (desktop banner + list); no phone is involved. |

**Broadcast to all paired phones (`device_id: "*"`).** The desktop fans out to
each phone in its paired list (`BTZ_PAIRED_DEVICES`) and reports per-device
results:

```sh
curl -s -X POST "$BTZ_NOTIFY_URL" \
  -H "Authorization: Bearer $BTZ_NOTIFY_TOKEN" -H 'Content-Type: application/json' \
  -d "{\"device_id\":\"*\",\"button_id\":\"$BTZ_ID\",\"title\":\"점검 끝\",\"body\":\"모든 폰으로\"}"
```

```json
{"ok":true,"routed":"hub","broadcast":true,"sent":1,"failed":1,
 "devices":[{"dev_id":"du-…","name":"Buttonizer ios","ok":true,"msg_id":"…","sent":1},
            {"dev_id":"du-…","name":"sdk_gphone64 (android)","ok":false,"error":"device has no registered push address"}]}
```

- **200** = at least one phone got it (`sent` ≥ 1); **502** = every phone failed
  (`sent` 0, `error:"device routing failed"`) - a broken path is never reported as
  success. Per-device errors are in `devices[].error` (hub unreachable, phone not
  paired any more, no registered push address, …).
- **No phones paired** (or the channel has not started yet) → local notification
  fallback: `200` + `routed:"local"`, `broadcast:true`, `sent:0`, `failed:0`,
  `devices:[]` — having nobody to send to is not an error.
- Notifications delivered to phones are **not** added to the desktop list (same as
  the single-device hub path); the response JSON is the record. The local fallback
  *is* recorded.
- `"*"` is the only wildcard. Any other unknown `device_id` keeps the old
  single-device rule (local fallback), so a typo never broadcasts.

**Size limits — bytes, not just characters.** `title` ≤200 chars and `body`
≤4000 chars, **and** the serialized APNs/FCM payload must be ≤ **4096 bytes**
(APNs' `PayloadTooLarge` ceiling; FCM v1 uses the same). `/api/notify` measures
the real UTF-8 JSON bytes before sending and returns `400` with the computed
size when the message is too large — the desktop refuses *before* it hands
anything to the hub, so an oversized notification is never silently dropped
(and a hub-delivered message can no longer fail silently at Apple).

Non-ASCII text is 1–4 bytes per character, so the effective body cap depends on
the charset. Measured with the real payload builder (empty title,
`category_id:"inbox"`, standard `btz` envelope):

| Body content | Bytes/char | Max body (empty title) | Max body (200-char ASCII title) |
|---|---|---|---|
| ASCII | 1 | 3955 chars | 3755 chars |
| Korean (Hangul) | 3 | 1318 chars | 1251 chars |
| Emoji (e.g. 🚀) | 4 | 988 chars | 938 chars |

The fixed envelope is 119 bytes (141 with a `category_id`; a `subtitle` adds
21), so the 4096-byte ceiling binds before the 4000-character body cap in every
charset: 200 ASCII title chars + a 4000-char ASCII body already serializes to
4341 bytes (Korean: 12341, emoji: 16341) and is rejected. Shorten the body or
the title until the reported size fits 4096.

**Omitting `category_id` costs 256 bytes.** With no `category_id` the hub groups
by the recipient address's category, which the desktop cannot know, so it reserves
the hub's worst case (64 chars × 4 B = 256 B) and rejects up to 256 bytes (~85
Korean chars) earlier than the exact size would. On that path a 1-char title
leaves ASCII 3703 / Korean 1234 / emoji 925 body chars; pass `category_id`
explicitly to use the full budget above.

A `device_id` that is **not** this desktop's phone (including a desktop with no
`channel.json`, i.e. never paired) is not an error: it falls back to a local
notification and still returns `200` with `"routed":"local"`. The command never
sees the phone's push key or APNs/FCM tokens, and the outcome is **never
silently dropped** — an over-limit message is refused with `400` before it is
sent, and a hub-delivered message Apple rejects is reported in the hub's
`errors` count instead of vanishing:

| Status | Meaning |
|---|---|
| `200` | Recorded locally (`"routed":"local"` when `device_id` was sent) or forwarded via the hub to the phone (`"routed":"hub"` with `msg_id`/`sent`). |
| `400` | Bad body (`title` missing or >200 chars, `body` >4000 chars, or the serialized APNs/FCM payload >4096 bytes — the error reports the computed byte size), or `device_id` mixed with the hub's `to`/`from`/`token`. |
| `401` | Missing/incorrect `Authorization: Bearer $BTZ_NOTIFY_TOKEN`. |
| `502` | `device_id` named this desktop's phone but delivery failed (hub unreachable, or no registered push address) - `{"error":"device routing failed",…}`. |

A `device_id` that is **not** this desktop's phone (including a desktop with no
`channel.json`, i.e. never paired) is not an error: it falls back to a local
notification and still returns `200` with `"routed":"local"`. Windows (cmd +
PowerShell) forms and the **legacy direct `$BTZ_PUSH_ID` branch** (unchanged, `to=`
lane unchanged) live in `examples/notify/`.

Reference syntax depends on the executing shell - `$BTZ_ID`/`$BTZ_RES` (sh, bash),
`%BTZ_ID%`/`%BTZ_RES%` (cmd.exe), `$env:BTZ_ID`/`$env:BTZ_RES` (PowerShell); the
wrapper table and worked forms are in §8.2.

### 4.1 How resource changes propagate

| Where | Detail |
|---|---|
| Phone | `$BTZ_RES` is always the button's own bundle directory **on the desktop**. A phone-initiated run sends the `run` RPC over the WebRTC data channel; when the client does not have a bundle file it fetches it with the `get_resource` RPC. There is no `/tmp/btz-res` staging step. |
| Desktop | `$BTZ_RES` is the button's own directory (`%USERPROFILE%\.buttonize\buttons\<folder>\<id>`); put the helper next to `button.yml`. |
| Freshness | The desktop watches `buttons/` and picks up a `button.yml` edit live (no restart, no reload). The phone sees the change on its next list refresh (~10 s while the app is open); a resource-only change rides along with it. |
| Icons | `res:` icons are bundle resources like any other; a phone-picked icon is uploaded into the bundle dir over the `bulk` channel (5 MB cap). |
| Edge cases | If the phone has not cached a bundle resource, it requests it with `get_resource` on demand. |
| Hard rule | Resources MUST live in the bundle dir and be referenced via `$BTZ_RES`; absolute `~/.buttonize/bin/...` paths are NOT supported (no shared `bin/`). |

---

## 5. Where a button runs (the desk that owns it)

- A button **belongs to the desk that owns it** (the desktop machine holding its
  `button.yml`). The phone runs the buttons of the desktops it is paired with; a
  button is not fanned out to other machines, and there is no per-button host list.
  A phone may stay paired with several desktops at once (connection count is
  tier-gated: Free 1 / P1 3 / P2 5 / P3 10).
- Do not author a `host_ids` key: a button belongs to exactly one desk and is
  never fanned out. Do not copy one from older examples.

---

## 6. Desktop/phone consistency you must respect

- The desktop is the **source of truth**: it owns `button.yml` and the run
  records. The phone reads and edits buttons over the WebRTC data-channel RPC
  (`list_buttons` / `button_edit_full`).
- The desktop watches `buttons/` and picks up an edit live. The phone sees the
  change on its next list refresh (~10 s while the app is open).
- Keep bumping `updated_at` to now (UTC) on every edit, and do not backdate: the
  phone compares `updated_at` when it merges what it holds with what the desktop
  reports.
- **Write to the desktop that owns the button.** There is no multi-host fan-out
  and no cross-host sync to rely on; a second machine does not receive the file
  automatically.

---

## 7. Worked examples

Three canonical shapes stay here, plus the schema-v1 param-model extensions
(§7.4); longer ones are real files under `examples/`.

### 7.1 Minimal (no params) - POSIX

```yaml
# ~/.buttonize/buttons/disk-report/button.yml
id: disk-report
title: Disk Report
command: df -h / | tail -1
color: "#334155"
icon: lucide:hard-drive
show_log: true
updated_at: "2026-08-22T13:40:00Z"
```

### 7.2 Parametrized - Windows-safe pattern (verified)

```yaml
id: greet
title: Greet (param demo)
description: Proves {{param}} substitution works on Windows when routed through PowerShell
command: powershell -NoProfile -Command Write-Output {{name}}
params:
- name: name
  type: string
  default: "world"
color: "#B91C1C"
icon: lucide:message-square
show_log: true
run_mode: short
timeout: 30
updated_at: "2026-08-22T14:10:00Z"
```

The renderer substitutes the value as `'value'` (single quotes); `cmd /C` passes
them through and PowerShell parses the single-quoted token as a string, so
`Write-Output 'world'` prints `world`. Do NOT wrap the placeholder in double
quotes inside the command (§8.3).

### 7.3 Folder with icon + a button inside (nested)

```bash
mkdir -p ~/.buttonize/buttons/Demos/Web/Prod/deploy-demo
printf 'icon: "globe"\n'       > ~/.buttonize/buttons/Demos/Web/folder.yml
printf 'icon: "server.rack"\n' > ~/.buttonize/buttons/Demos/Web/Prod/folder.yml
```

Then write `deploy-demo/button.yml` normally; the phone renders breadcrumb chips
`All > Demos > Web > Prod`. Desktop folders work the same; folder icons may use
`lucide:` names there.

### 7.4 Param-model extensions (`text`, multi-file, slider bounds, groups)

```yaml
# multiline free text - exactly ONE quoted arg, newlines preserved
params:
- name: body
  type: text
  description: "Commit message body"
command: git commit -m {{body}}
```

```yaml
# pick several files - N newline-separated paths, one quoted arg per path
params:
- name: inputs
  type: file
  multiple: true
command: ffmpeg -i {{inputs}} out.mkv
```

```yaml
# number with BOTH bounds set -> the desktop run sheet renders a slider
params:
- name: retries
  type: number
  min: 0
  max: 10
  step: 1          # slider granularity only - never enforced
  default: "3"
command: ./retry.sh {{retries}}
```

```yaml
# grouped params - presentation only, the rendered command is unchanged
param_groups:
- title: Connection
  collapsed: false
- title: Advanced
  collapsed: true
params:
- name: host
  type: string
  group: Connection
- name: user
  type: string
  group: Connection
- name: flags
  type: string
  group: Advanced      # stays collapsed until the user opens it
- name: note
  type: text           # no group -> renders first, with no header
```

Delivery order in the run sheet: ungrouped params first, then `Connection`,
then `Advanced`; groups affect presentation only and never the rendered command.

More, as copyable files: `examples/windows/win-info.yaml` (minimal Windows
button) · `examples/windows/disk-usage.yaml` +
`examples/windows/disk.ps1` (PowerShell resource by bare file name, UTF-8 first
line) · `examples/send-to-session.yaml` (chained pickers + resource script).

---

## 8. Platform notes - the desktop app & Windows authoring

`buttonizer-desktop` is the **host**: it owns the YAML tree and executes
every command on the machine it runs on. A paired phone reaches it over the
WebRTC data channel (hub signaling + `rpc`); there is no per-button host
gating and no file-level sync. Several desktops may be paired at once (tier-gated).

### 8.1 Desktop deltas

| Topic | Rule |
|---|---|
| Root | `$HOME/.buttonize` / `%USERPROFILE%\.buttonize`; buttons under `<root>/buttons/<folder...>/<id>/button.yml`, watched live. |
| `updated_at` / `description` | Keep bumping `updated_at` (§6); `description` (button + params) is rendered by the editor and the OpenAPI `/docs`. |

### 8.2 Shell wrapper, env syntax, common rules

| Platform | Wrapper | Env syntax |
|---|---|---|
| macOS / Linux | `sh -c "<command>"` | `$BTZ_ID`, `$BTZ_RES` |
| Windows | `cmd /C "<command>"` | `%BTZ_ID%`, `%BTZ_RES%` |
| Windows via PowerShell | `powershell -NoProfile ...` | `$env:BTZ_ID`, `$env:BTZ_RES` |

- The run's working directory is ALWAYS the button's bundle dir, set directly on
  the spawned process (not via `cd`) - so reference resources by BARE FILE NAME
  (`powershell ... -File disk.ps1`) and read the bundle path inside the script
  (`%BTZ_RES%` for cmd, `$env:BTZ_RES` inside PowerShell).
- The runner kills the whole process tree on stop/timeout (taskkill on Windows,
  process-group kill on Unix) - do not rely on orphaned children surviving.
- Icons: one vocabulary everywhere - `lucide:<kebab-name>` (`lucide:monitor`,
  `lucide:hard-drive`, `lucide:wifi`, `lucide:zap`); `res:<file>` bundle images
  and `https://...` URLs work too. Unknown/empty values fall back to a plain
  circle and never break the button.

### 8.3 Windows delta (verified 2026-09-05, Windows 10 + Windows PowerShell 5.1)

| Topic | Rule |
|---|---|
| Shell choice | Write for cmd.exe (or PowerShell), not bash. No `python3` by default - use PowerShell for anything non-trivial. `cmd /C` does not expand `$VAR`; use `%VAR%`. |
| No quoted paths | NEVER build a double-quoted path into the command: `-File "%BTZ_RES%\disk.ps1"` breaks, because the desktop spawns `cmd.exe /C` with the whole rendered line as ONE argv and cmd re-parses embedded double quotes (verified: fails even for paths with no spaces and no non-ASCII characters). |
| Placeholder quoting | cmd.exe does NOT strip the single quotes of §3: `echo {{name}}` with `name=world` renders `echo 'world'` and prints `'world'`, so avoid bare placeholders in raw cmd. PowerShell parses them as string delimiters, so route placeholders through PowerShell WITHOUT double quotes around `-Command` (`powershell -NoProfile -Command Write-Output {{name}}` prints `world`, verified including values with spaces). The double-quoted form FAILS with spaces (prints the literal text). |
| `-File` parameters | `powershell -File script.ps1 -Param {{value}}` delivers the argument WITH the quotes (`-Name 'world'` arrives as `'world'`). For the unquoted value use `powershell ... -Command "& '%BTZ_RES%\tool.ps1' -Name {{value}}"` - which embeds a double-quoted path, so it only works when the bundle path has no spaces. Simplest robust choice: pass no parameters to `-File` and read inputs inside the script. |
| Unsafe characters | Keep values free of `'`, `"` and `%` where possible - each has meaning in one of the shells in the chain. |
| Services | `run_mode: service` + a looping PowerShell command works; put the loop in a `.ps1` resource and reference it by bare name. |
| UTF-8 output | Start every `.ps1` resource with `[Console]::OutputEncoding = [System.Text.Encoding]::UTF8`: PowerShell 5.1 writes redirected pipes in the OEM/ANSI code page, not UTF-8, which garbles non-ASCII output (and the startup banner). Plain cmd one-liners need no special handling. |
| Output decoding | The runner decodes as UTF-8 and, when the bytes are NOT valid UTF-8, falls back to the Windows OEM then ANSI code page (CP949 on Korean systems). You do NOT need ASCII-only output or `?` replacements - Korean (or any local language) text from cmd one-liners, native tools and `.ps1` resources is preserved end to end. Keep the `.ps1` UTF-8 line anyway so history files stay uniformly UTF-8. |
| Console windows | Every Windows command is spawned with `CREATE_NO_WINDOW`, so no cmd/console window pops up while a button runs - output goes only to the app's log. Nothing to do. |

### 8.4 Desktop REST: who resolves `type: command` chains

REST clients drive the desktop app's local API with
`Authorization: Bearer <token from ~/.buttonize/desktop_token>`.

**`POST /api/run/{id}` deliberately does NOT resolve `type: command` params.**
Its body is `{"params": {"name": "value"}, "invoked_by": "…"}`; the handler
fills `device` params from the desktop's own id, rejects any `{{token}}` used in
`command` that has neither a supplied value nor a `default` with
`400 {"error":"missing params","params":[…]}` (a `type: command` param is no
exception - supply its value or give it a default), renders `command` from the
values it was given, and runs it. It never executes a `sourceCommand`: the
calling sub/client is expected to fetch the candidate values and pass the
selected one in - that is the design, not an omission. A caller who expects the
server to walk the chain gets the raw/empty value (or the 400 above) by design.

Fetch those candidates from the param-options sub-API (Bearer auth, 30 s
`sourceCommand` timeout):

```sh
TOKEN=$(cat ~/.buttonize/desktop_token)
# candidates for a chained param; earlier params it references are passed in
curl -s -X POST -H "Authorization: Bearer $TOKEN" -d '{"params":{"session":"work"}}' \
  http://127.0.0.1:37921/api/run/tmux-open/params/window
# → {"options":[{"display":"0: editor","value":"0: editor"}, …]}
# then run the button WITH the chosen value
curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  -d '{"params":{"session":"work","window":"0: editor"}}' \
  http://127.0.0.1:37921/api/run/tmux-open
```

`POST /api/run/{id}/params/{name}` runs that param's `sourceCommand` with
earlier values substituted and returns `{"options":[{"display":…,"value":…}]}`,
lines split by `separator`/`tabSeparated`; `outputMode: all` returns one option
whose `value` is the whole stdout. `POST /api/param_options` with
`{"id":…,"name":…,"params":{…}}` is the same operation without the per-button
path, and `GET /api/buttons` returns every button's full `def` so a client can
read param `type`/`default`/`options` up front. The desktop GUI and the CLI
`--run` DO walk chains stage by stage; only the REST run path leaves resolution
to the caller.

---

## 9. Pre-flight checklist (agent self-check)

- [ ] Bundle dir name == `id`; under `buttons/` (<=8 levels deep); no nested
      duplicate copies of the same id
- [ ] `title` and `command` non-empty; all colors quoted; hex `#RRGGBB`
- [ ] `icon` is a valid `lucide:<kebab-name>`, an existing `res:` bundle file, or
      an `https://` URL
- [ ] `tags` (if any) lowercase, no `/` `,` `@`, <=20 x 32 chars
- [ ] Every `{{placeholder}}` in `command`/`sourceCommand` has a matching
      `params:` entry (or is intentionally internal-only)
- [ ] `separator` cannot occur inside real content
- [ ] `show_log: true` when output is the point
- [ ] If `output_auto_open: true`, the effective `run_mode` is `short` (Immediate)
      - `long`/`service`/`scheduled` (and a missing mode with `notify_on_done: true`,
      which infers `long`) are a validator WARN and never auto-open at run time
- [ ] If `span_cols`/`span_rows` are present they are `1` or `2` (omit them for
      `1`); if `icon_background: true`, `icon` is an image (`res:`/`https:`) -
      glyph icons ignore the key (§2.8)
- [ ] `updated_at` bumped to current UTC
- [ ] If `run_mode: scheduled`: 5-field cron that parses, every value in range,
      and every `{{param}}` used in `command` has a `default`
- [ ] Disabled on purpose? `enabled: false` stops manual, scheduled and CLI runs
      alike (§2.2); delete the key to re-enable
- [ ] Did NOT touch the app-managed `status.json`, `tail.log`, `history/`
- [ ] Defaults justified: every `params[].default` (and every written top-level
      key) is either certain to be used in almost every run or was explicitly
      requested - otherwise it is omitted (§2.6)
- [ ] Windows/desktop target: §8.3 passes (cmd-valid command, bare-file-name
      resources, PowerShell-safe placeholders, `.ps1` UTF-8 first line)
- [ ] (optional) failure-repair button → wrapper pattern
      (`docs/agent-wrapper-pattern.md`)

---

## 10. Desktop CLI: `--validate` / `--run` (agent verification loop)

The desktop binary (`buttonizer-desktop`, Rust; run on the host holding
`~/.buttonize`) exposes two non-interactive debug verbs that share the app's own
parser/runner, so a green result here matches what the app would do:

```sh
BTZ=$(python3 -c 'import json,os;print(json.load(open(os.path.expanduser("~/.buttonize/settings.json")))["binary_path"])')
"$BTZ" --validate my-button      # static check only, never executes commands
"$BTZ" --run my-button k=v       # executes exactly like the app
```

**Loop (a required gate, not a suggestion):** edit `button.yml` →
`--validate <id>` → **fix all ERRORs** → `--run <id>` with values → repeat.
Validation is **MANDATORY**: after creating or editing any button you **MUST** run
`--validate <id>` and reach **0 ERRORs** before you consider the button done and
before you run or ship it — a button with remaining ERRORs is **not "complete"**.
This applies to humans and to agents/automation alike; a green `--run` alone does
not substitute for it. `--validate` exit `0` = no ERRORs (WARNs allowed), `1` =
any ERROR; `--run` exit `0` only when the run finished `exit=0` and not timed out,
and a disabled button is refused (exit 1). A **duplicate id** (two bundle
directories with the same name anywhere under `buttons/`) is an ERROR:
`--validate <id>` lists every candidate path and `--run <id>` refuses to execute
the ambiguous id (exit 1) rather than running the first match. `--run` HAS real
side effects on the host - never run with an intent you would not send from the UI.

`--run <button-id> name=value …` takes the button id as its first positional
argument, auto-fills `type: device` params with the desktop's own id (same as
REST) and validates supplied values strictly: an unknown parameter name, a
non-numeric value for a `number` param, a `number` value outside its `min`/`max`
(the error names the param, the value and the allowed range), or a value outside
`options` for a `select` param is refused (exit 1). `--validate` also errors on
`min > max` and `step <= 0`, and WARNs when `multiple` is set on a type other
than `file`/`upload`. It resolves `type: command` chains itself,
stage by stage (§8.4), but it does NOT set `BTZ_NOTIFY_URL`, so a button's notify
branch is skipped under `--run` (that env exists only in GUI mode). `--run` with
no button id prints the usage line and exits `2`.

Full verb list, ERROR/WARN catalog and the param-resolution walkthrough:
`docs/desktop-cli.md`. User-facing manual: `Manual.md`.

---

## 11. Error recovery: wrapper + agent auto-repair

Some buttons exist to be *fixed by an agent when they break* (a remote API
changes, a parser assumption rots, a host quirk appears). For those, keep repair
logic OUT of the task script and put it in a thin wrapper (`command: sh
"$BTZ_RES/run.sh"` → `task.sh`), invoked through a pluggable `$BTZ_AGENT_CMD`
with guards, a cooldown stamp and a non-recursive verification rule.

Full contract, agent prompt requirements and checklist:
**`docs/agent-wrapper-pattern.md`**.