# 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"
```

> 2026-09 갱신: SSH/SFTP·`ssh -R` 터널·릴레이/포트 레지스트리 세대는 제거됐고, 수신
> 대상 `host_ids`(멀티 호스트 fan-out)도 제거됐다. 현재 모델은 **허브 시그널링 +
> WebRTC 데이터채널**로 연결된 **데스크톱(들)** 이며, 폰은 여러 데스크톱과 동시에
> 페어링할 수 있다(동시 연결 수는 티어가 게이트 — 무료 1 / P1 3 / P2 5 / P3 10).
> 버튼은 소유한 데스크톱의 버튼을 채널 RPC로 조회·실행한다. 이 문서의
> "phone flow / sync" 서술은 그 기준으로 정정했다.

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). |

---

## 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; its presence keeps an empty folder alive. | 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, append-only) · `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 id exists at several depths the SHALLOWEST
  wins and the others are reported as duplicates - never create `<id>/<id>/`.
- 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` (displayed as **Immediate**, **Long Running**, **Service**, **Scheduled**). 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. |
| `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). |
| `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.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. |

---

## 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_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.

**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)

> 2026-09 갱신: `host_ids` 필드와 멀티 호스트 fan-out 모델은 제거됐다. 이 절은 그
> 제거 사실과 현재 모델만 기술한다.

- 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).
- The old `host_ids` key is gone from the product and from fresh button files.
  Do not author it, and do not copy it from old 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`), not over SSH/SFTP.
- 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 SSH, 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
- [ ] `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/`
- [ ] 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:** edit `button.yml` → `--validate <id>` (fix all ERRORs) → `--run <id>`
with values → repeat. `--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). `--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`**.