docs(zi-install): document setup apply events interface

.github/skills/zi-install/SKILL.md

@@ -89,16 +89,17 @@ User dotfiles stay readable and minimal. Implementation details, path checks, er
 
 ## Machine interface
 
-For a source revision that provides `zi-setup-describe-v1` and `zi-setup-result-v1` (introduced by [z-shell/src#224](https://github.com/z-shell/src/pull/224)), use the versioned machine interface rather than parsing human stdout or stderr. Routine installs and older source revisions continue to use the verified `install.sh` flow above; do not assume the machine artifacts exist.
+For a source revision that provides `zi-setup-describe-v1` and `zi-setup-result-v1` (the baseline introduced by [z-shell/src#224](https://github.com/z-shell/src/pull/224)), use the versioned machine interface rather than parsing human stdout or stderr, while `zi-setup-event-v1` is explicitly an optional additive capability from [z-shell/src#225](https://github.com/z-shell/src/issues/225). Routine installs and older source revisions continue to use the verified `install.sh` flow above; do not assume the machine artifacts exist.
 
 Drive the engine only from a local `src` tree or a same-revision companion bundle containing `setup.sh`, `init.zsh`, `profiles.tsv`, and `checksum.txt` after verifying the published checksums. For a fetched bundle, pass the explicit `--profiles` path to `describe`, and the explicit `--init`, `--profiles`, and `--checksum` paths to `plan`.
 
 - **Directory artifacts:** Commands communicate through private directory artifacts with fixed relative paths containing raw bytes or restricted tokens (avoiding shell-level JSON escaping). Each destination must not exist, and its immediate parent must already exist and be writable:
   - `setup.sh describe --output DIR`: Publishes a `zi-setup-describe-v1` artifact containing `facts/` and `profiles/` (`loader` and `annex`; legacy `zunit` is marked `selectable=no` if detected). Exits 3 if all profiles are blocked.
   - `setup.sh plan --plan DIR`: Publishes a deterministic `zi-setup-plan-v1` artifact containing `plan.id`, `plan.meta`, `checkout/`, `targets/`, `operations/`, and `warnings/`.
-  - `setup.sh apply --plan DIR --phase checkout|files [--expect SHA256] [--result DIR]`: Applies the plan phase-by-phase.
+  - `setup.sh apply --plan DIR --phase checkout|files [--expect SHA256] [--result DIR] [--events DIR]`: Applies the plan phase-by-phase.
 - **Exact plan-id approval:** The plan hash covers all artifact files except `plan.id`. Clients must record the reviewed `plan.id` and pass it via `--expect` for both checkout and files phases. Changed artifact content produces `plan-changed`; changed live checkout or file preconditions produce `checkout-drift` or `target-drift`.
 - **Result artifacts:** Passing `--result DIR` to `apply` publishes a `zi-setup-result-v1` artifact containing `format`, `plan.id`, `phase`, `status` (`succeeded`, `failed`, `cancelled`), and `operations/`. Failures also contain `error/code` and `error/detail`, plus `error/operation` when attributable to one operation. A successful files phase contains `receipt/path`.
+- **Event artifacts:** Passing optional `--events DIR` to `apply` (introduced by [z-shell/src#225](https://github.com/z-shell/src/issues/225)) publishes streaming progress for active operations into a private absolute new directory created by the engine with mode `0700` (the path must be absolute, must not already exist, must not be a symlink, and its immediate parent must already exist and be writable). The engine publishes atomic six-digit `zi-setup-event-v1` directories (`000001`, `000002`, ...) containing `format`, `phase`, `operation`, `status` (`started`, `succeeded`, `failed`), and safe `detail` text. Each event is staged under a hidden temporary directory (`.tmp-event.*`) and renamed into place atomically. The engine emits `started` immediately before executing an active operation and a terminal `succeeded` or `failed` upon completion or error (duplicate terminal events are prevented). If a failure occurs before an operation begins, no event directories are published. Clients must treat process completion as authoritative and tolerate a missing terminal event when a cancellation signal interrupts event publication itself; staging cleanup and exit 6 still apply. Events are observational and do not change plan IDs, result contracts, exit codes, stdout, stderr, mutation order, or rollback behavior.
 - **Stable exit statuses and error codes:**
   - Exit statuses: `0` (success), `2` (invocation or unsupported version), `3` (non-actionable discovery/plan), `4` (reviewed state or lock precondition changed, including plan, checkout, target drift, or lock contention), `5` (apply operation began but did not complete), `6` (cancelled).
   - Error codes (`error/code`): stable ASCII identifiers including `unsupported-version`, `plan-changed`, `target-drift`, `checkout-drift`, `lock-held`, `network-failed`, `checkout-failed`, `write-failed`, and `cancelled`.