From 6d16619c594c7973a0eadde946178eed91817d21 Mon Sep 17 00:00:00 2001
From: Sal <59910950+ss-o@users.noreply.github.com>
Date: Sun, 20 Sep 2026 18:15:07 +0100
Subject: [PATCH 1/2] docs(readme): document setup apply events interface

Document the additive setup.sh apply --events DIR interface and add an
integrator note covering event directories and automation constraints.

Refs: z-shell/src#225
---
 README.md | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/README.md b/README.md
index c9b4746..a0a1fc6 100644
--- a/README.md
+++ b/README.md
@@ -53,6 +53,14 @@ sh -c "$(curl -fsSL get.zshell.dev)" --
 
 > Review the [installer source](https://raw.githubusercontent.com/z-shell/src/main/public/sh/install.sh) and its published [SHA-256 checksum](https://raw.githubusercontent.com/z-shell/src/main/public/checksum.txt) before running a remote installation script.
 
+Automated environments can drive the setup engine directly:
+
+```sh
+setup.sh apply --plan DIR --phase checkout|files [--result DIR] [--events DIR]
+```
+
+> [!NOTE] Integrator note: the `--events DIR` option is optional, creates a private new absolute directory, publishes atomic numbered `zi-setup-event-v1` event directories with started and terminal state, and human stdout/stderr must not drive automation.
+
 ### 2. Add your first plugins
 
 Add Zi commands to `.zshrc`. This example loads an Oh My Zsh snippet, command suggestions, and fast syntax highlighting:

From 1aa5634d1a49d448f93398ea69e98c0693383b34 Mon Sep 17 00:00:00 2001
From: Sal <59910950+ss-o@users.noreply.github.com>
Date: Sun, 20 Sep 2026 18:22:36 +0100
Subject: [PATCH 2/2] docs(readme): document cancellation behavior for setup
 apply events

Clarify in the integrator note that consumers must treat process
completion as authoritative and tolerate a missing terminal event
when cancellation interrupts publication. Note that staging cleanup
and exit code 6 still apply.

Refs: z-shell/src#225
---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index a0a1fc6..75f213a 100644
--- a/README.md
+++ b/README.md
@@ -59,7 +59,7 @@ Automated environments can drive the setup engine directly:
 setup.sh apply --plan DIR --phase checkout|files [--result DIR] [--events DIR]
 ```
 
-> [!NOTE] Integrator note: the `--events DIR` option is optional, creates a private new absolute directory, publishes atomic numbered `zi-setup-event-v1` event directories with started and terminal state, and human stdout/stderr must not drive automation.
+> [!NOTE] Integrator note: the `--events DIR` option is optional, creates a private new absolute directory, publishes atomic numbered `zi-setup-event-v1` event directories with started and terminal state, and human stdout/stderr must not drive automation. Consumers must treat process completion as authoritative and tolerate a missing terminal event if a cancellation signal interrupts event publication itself; staging cleanup and exit 6 still apply.
 
 ### 2. Add your first plugins