feat(bos_build): --show-plan, --skip, --from and modules profiles (#1502)

* feat(bos_build): add skip switch subtracting steps from composed plans

* feat(bos_build): add slice_from for --from resume semantics

* feat(bos_build): profiles carry skip lists and opt-in modules pipelines

* feat(bos_build): add --show-plan, --skip and --from to build CLI

* docs(bos_build): document --show-plan, --skip, --from and modules profiles

* ci(bos_build): smoke --show-plan without a chromium checkout

* fix(bos_build): tighten plan projection validation from review

Author: shadowfax92

.github/workflows/bos-build-tests.yml

@@ -38,6 +38,9 @@ jobs:
       - name: CLI smoke
         run: |
           uv run browseros build --list > /dev/null
+          # Runner has no chromium checkout — this smoke IS the
+          # no-checkout regression test for --show-plan.
+          uv run browseros build --preset release --show-plan
           uv run browseros product doctor
 
       - name: Run vendor_uploads tests

packages/browseros/bos_build/README.md

@@ -17,7 +17,8 @@ bos_build/
               batch-apply, features.yaml IO (interactive apply/sync
               lives in the Go tool: tools/patch, `bpatch`)
   products/   one package per product: define() call + server bundles
-  profiles/   saved switch sets for CI (flat yaml, no module lists)
+  profiles/   saved switch sets (flat yaml; a local profile may opt into
+              an explicit modules: list — shipped profiles never do)
   config/     data: gn flags, resource yamls, appcast templates, offset
 ```
 
@@ -52,6 +53,53 @@ browseros build --profile nightly-ci --arch x64
 browseros build --modules clean,compile,sign_macos --product browseros
 ```
 
+### Seeing and tweaking a plan
+
+The composed plan is always a projection of `plan()` — generated, never
+hand-copied, so it can't drift:
+
+```bash
+# Print the composed steps + required env vars and exit
+# (works without a chromium checkout)
+browseros build --preset release --show-plan
+
+# Comment out steps, as an operation: subtract from the composed plan
+browseros build --preset release --skip upload,series_patches
+
+# Resume the tail after a failure without recompiling
+browseros build --preset release --from sign_macos
+```
+
+- `--skip` (and a `skip:` list in profiles) subtracts **after**
+  composition — it never re-triggers composition rules. CLI `--skip`
+  and profile `skip:` union. Unknown step names fail loudly; a valid
+  step absent from this plan is a no-op, so a saved `skip:` keeps
+  working as presets evolve — subtraction from the canonical plan,
+  never a copy of it.
+- `--from` resumes the composed (post-skip) run timeline at a step:
+  earlier runs are dropped, the first run containing the step is
+  sliced, later runs stay whole. A failed universal merge resumes with
+  just `--arch universal --from merge_universal` — no recompiles.
+  CLI-only: resume is a one-off, so there is no `from:` profile key.
+
+### Modules profiles — "you own this list now"
+
+For the rare run that genuinely wants an arbitrary sequence, a profile
+may carry `modules:` as an explicit opt-in — a local, commentable file
+that bypasses the planner entirely:
+
+```yaml
+# my-tail.yaml (local only — never shipped)
+modules: [compile, sign_macos, package_macos]
+build_type: release   # only valid with modules:; defaults to debug
+arch: arm64           # single arch only
+```
+
+Planner-owned keys (`preset`, `clean`, `provision`, `download`, `sign`,
+`upload`, `skip`) and the `--skip`/`--from` flags are rejected alongside
+`modules:` — you own the list, edit it directly. Shipped profiles stay
+switch-based (drift-tested).
+
 ## Remote / ephemeral runners
 
 A fresh machine needs nothing outside this package: