# Steward playbook conventions (quick reference)

What Steward reads from a playbook in this subsystem. Full guide:
`docs/reference/playbook-authoring.md`. Parser:
`steward/ansible/sources.py` — `discover_playbook_meta()` and
`discover_playbook_variables()`.

## Magic comments (metadata)

```yaml
---
# description: One line on what this playbook does.   # shown on selection
# steward:category: maintenance                       # grouping badge
# steward:confirm: true                               # require confirm to run
- name: …            # used as the description if no `# description:` comment
  hosts: all         # Steward generates the inventory from the chosen target/group
```

- `# description:` — first match wins; case-insensitive; falls back to first
  play `name:`.
- `# steward:<key>: <value>` — namespaced metadata. Implemented keys:
  - `category` — free-text grouping label (badge in browse + run form).
  - `confirm` — `true`/`yes`/`1`/`on` → run form requires a confirmation tick.
  - `description` — alias for `# description:` (unprefixed wins if both present).
  - Unknown `# steward:*` keys are ignored (namespace reserved for future use).

## Structural cues (no comments needed)

- **`vars:` scalars** → editable run-time fields (default shown as placeholder;
  blank = keep default; values sent as highest-precedence extra-vars).
- **`vars_prompt:`** → run-time fields (required when no default; `private: true`
  → masked).
- **Secret naming** — a var whose name contains `password`/`passwd`/`secret`/
  `token`/`api_key`/`private_key`/`credential` is masked **and not persisted**.
- **`hosts: all`** — target via the run form's scope; don't hardcode hosts.
- **Credentials** — never embed them. Steward connects as the managed `steward`
  account (passwordless sudo; use `become: true`) or one-time bootstrap creds.

Be idempotent — Steward re-runs playbooks (updates, schedules, retries).