docs(readme)+ci: WI-4 selective-install docs + flag e2e/validate smoke steps (#468)

.github/workflows/e2e-install.yml

@@ -97,6 +97,13 @@ jobs:
             echo "All Linux assertions passed"
           '
 
+      # -- Flag smoke tests --
+      - name: Flag smoke - --list (Linux)
+        run: bash setup.sh --list
+
+      - name: Flag smoke - --only (Linux)
+        run: bash setup.sh --only=zsh
+
       # -- Step 3: Idempotency --
       - name: Idempotency (second run)
         run: |
@@ -238,6 +245,13 @@ jobs:
             echo "All macOS assertions passed"
           '
 
+      # -- Flag smoke tests --
+      - name: Flag smoke - --list (macOS)
+        run: bash setup.sh --list
+
+      - name: Flag smoke - --only (macOS)
+        run: bash setup.sh --only=zsh
+
       # -- Step 3: Idempotency --
       - name: Idempotency (second run)
         run: |
@@ -393,6 +407,13 @@ jobs:
             Write-Host "`nAll Windows assertions passed"
           }
 
+      # -- Flag smoke tests --
+      - name: Flag smoke - -List (Windows)
+        run: .\setup.ps1 -List
+
+      - name: Flag smoke - -Only (Windows)
+        run: .\setup.ps1 -Only 'vim'
+
       # -- Step 3: Idempotency --
       - name: Idempotency (second run)
         run: |

.github/workflows/validate.yml

@@ -100,6 +100,12 @@ jobs:
       - name: Run tool version tests
         run: bash tests/test_tool_versions.sh
 
+      - name: Flag test - --list (Linux)
+        run: bash setup.sh --list
+
+      - name: Flag test - --only (Linux)
+        run: bash setup.sh --only=zsh
+
   validate-macos:
     name: Validate macOS Setup
     runs-on: macos-latest
@@ -194,6 +200,9 @@ jobs:
       - name: Run pre-commit hygiene tests
         run: bash tests/test_precommit_hygiene.sh
 
+      - name: Flag smoke - --list (macOS)
+        run: bash setup.sh --list
+
   lint-shell-scripts:
     name: Lint Shell Scripts
     runs-on: ubuntu-latest
@@ -264,6 +273,9 @@ jobs:
       - name: Run sprint-end labels tests
         run: pwsh tests/test_sprint_end_labels.ps1
 
+      - name: Flag test - -List (PowerShell)
+        run: .\setup.ps1 -List
+
   validate-ps51:
     name: Validate PowerShell 5.1 Compatibility
     runs-on: windows-latest
@@ -352,3 +364,9 @@ jobs:
         shell: powershell
         run: |
           powershell -ExecutionPolicy Bypass -File tests\test_sprint_end_labels_pwsh.ps1
+
+      - name: Flag test - -List (PS 5.1)
+        shell: powershell
+        run: |
+          .\setup.ps1 -List
+          Write-Host "Flag -List OK (PS 5.1)"

README.md

@@ -51,6 +51,71 @@ powershell -ExecutionPolicy Bypass -File setup.ps1
 
 No action needed. Setup runs automatically on container creation via the `postCreateCommand` hook.
 
+## Selective Install
+
+By default, `setup.sh` / `setup.ps1` installs all tools in the defined order. Use flags to control
+which tools run without editing the scripts.
+
+### Available Flags
+
+| Flag | Linux / macOS / WSL | Windows |
+|------|---------------------|---------|
+| List available tools, exit (no install) | `--list` | `-List` |
+| Print usage, exit | `--help` | `-Help` |
+| Install only the named tools | `--only=a,b,c` | `-Only 'a,b,c'` |
+| Install all defaults except named tools | `--skip=a,b,c` | `-Skip 'a,b,c'` |
+
+### Linux / macOS / WSL Examples
+
+```bash
+# List all selectable tool names
+./setup.sh --list
+
+# Print usage
+./setup.sh --help
+
+# Install only zsh and uv
+./setup.sh --only=zsh,uv
+
+# Install everything except auth and copilot-cli
+./setup.sh --skip=auth,copilot-cli
+```
+
+### Windows Examples
+
+```powershell
+# List all selectable tool names
+.\setup.ps1 -List
+
+# Print usage
+.\setup.ps1 -Help
+
+# Install only vim and gh
+.\setup.ps1 -Only 'vim,gh'
+
+# Install everything except auth and copilot-cli
+.\setup.ps1 -Skip 'auth,copilot-cli'
+```
+
+### Caveats
+
+**`--only` / `-Only` does not auto-include prerequisites.** Selecting `--only=nvm` installs
+only nvm -- its prerequisite tools (`prereqs`, `zsh`, `uv`) are not pulled in automatically.
+If a tool depends on earlier steps, list all required tools explicitly:
+
+```bash
+# Correct: include prereqs before nvm
+./setup.sh --only=prereqs,uv,nvm
+```
+
+**`--only` and `--skip` are mutually exclusive.** Combining both flags exits with an error.
+
+**`--list` takes precedence.** If `--list` is passed alongside `--only` or `--skip`, the tool
+list is printed and setup exits without installing anything.
+
+Tool names are validated against the available list. An unknown name exits with an error and
+prints the available tools. Use `--list` / `-List` to see valid names before running.
+
 ## Post-Setup Steps
 
 After running setup, complete these steps to activate your tools: