diff --git a/assets/hooks/pre-commit b/assets/hooks/pre-commit
index 263214d..aaee541 100755
--- a/assets/hooks/pre-commit
+++ b/assets/hooks/pre-commit
@@ -79,8 +79,10 @@ for f in "${STAGED[@]}"; do
   esac
 done
 
-# -------- future orchestration (non-blocking status) ----------
-# Run workflow status check if available, but don't block commit if it fails
+# -------- orchestration (non-blocking status) ----------
+# NOTE: automation/workflow.py provides non-blocking vote status reporting.
+# It parses VOTE: lines from staged discussion files and prints a summary.
+# Run workflow status check if available, but don't block commit if it fails.
 if [ -x "automation/workflow.py" ]; then
   python3 automation/workflow.py --status || true
 fi
diff --git a/tools/build_installer.py b/tools/build_installer.py
index 9260200..748ae10 100644
--- a/tools/build_installer.py
+++ b/tools/build_installer.py
@@ -41,11 +41,46 @@ def main():
     copy_tree(ROOT / "assets" / "templates" / "process", BUNDLE / "assets" / "templates" / "process")
     copy_tree(ROOT / "assets" / "templates" / "rules", BUNDLE / "assets" / "templates" / "rules")
 
+    # copy automation directory (workflow.py and future orchestration scripts)
+    automation_src = ROOT / "automation"
+    if automation_src.exists():
+        copy_tree(automation_src, BUNDLE / "automation")
+
     # write installer entrypoint
     shutil.copy2(ROOT / "src" / "cascadingdev" / "setup_project.py",
                  BUNDLE / "setup_cascadingdev.py")
 
-    (BUNDLE / "INSTALL.md").write_text("Unzip, then run:\n\n  python3 setup_cascadingdev.py\n", encoding="utf-8")
+    install_doc = """# CascadingDev Installer
+
+## Requirements
+- Python 3.10+ and git
+- (Optional) PySide6 or PyQt5 for the Ramble GUI
+
+## Quick Start
+```bash
+python setup_cascadingdev.py --target /path/to/your-project
+```
+
+### Options
+- `--target PATH`: directory to create or reuse for the repo
+- `--no-ramble`: skip the Ramble GUI and answer prompts in the terminal
+- `--provider {mock,claude}`: select the Ramble provider (default: mock)
+- `--claude-cmd CMD`: command to invoke when provider is `claude`
+
+### Steps Performed
+1. Creates the standard CascadingDev folder layout in the target.
+2. Copies templates, policies, rules, and runtime scripts into place.
+3. Initializes git (if needed) and installs the pre-commit hook.
+4. Launches Ramble unless `--no-ramble` is provided.
+5. Seeds initial feature discussions, summaries, and rules.
+6. Commits the bootstrap state so the repo starts clean.
+
+### Troubleshooting
+- If the GUI fails, activate a virtualenv then `pip install PySide6`, or rerun with `--no-ramble`.
+- Ensure `git` is available on PATH; the installer runs `git init` and `git commit`.
+- Remove or empty the target directory if rerunning into conflicting files.
+"""
+    (BUNDLE / "INSTALL.md").write_text(install_doc.strip() + "\n", encoding="utf-8")
     (BUNDLE / "VERSION").write_text(VER, encoding="utf-8")
     print(f"[✓] Built installer → {BUNDLE}")