# Added `--fast` mode to deploy helper

Date: 2026-05-17 · Repo: islandflow · Task: make `./deploy main` faster for routine rollouts

## Summary

Added a new `--fast` flag to `./deploy` so operators can run a quicker deploy profile without manually combining multiple flags. In fast mode, default full-scope deploys switch to backend-services scope and skip expensive public route-suite checks.

## Changes Made

- Updated `scripts/deploy.ts` to parse and advertise `--fast`.
- Added effective-scope logic so `--fast` + default scope behaves like `--services-only`.
- Adjusted verification behavior in fast mode:
- Skipped Docker log tail dump during remote verification.
- Skipped verbose native `systemctl status` / `journalctl` output.
- Skipped public API route suite (`scripts/check-public-api-routes.ts`) in fast mode.
- Documented fast mode in `deployment/docker/README.md` and `deployment/native/README.md`.

## Context

The default `./deploy main` path is intentionally thorough and safe, but it can be slow because it rebuilds multiple service images and runs full verification. Fast mode provides an explicit, opt-in speed profile for routine operations.

## Important Implementation Details

Fast mode does not silently alter explicitly requested scopes. It only remaps scope when the caller leaves scope at default full-stack.

    function effectiveScope(scope: DeployScope, fast: boolean): DeployScope {
      if (fast && scope === "full") {
        return "services";
      }
      return scope;
    }

Public verification now keeps behavior explicit. In fast mode, it logs why API route checks were skipped and points operators to `DEPLOY_PUBLIC_API_HEALTH_URL` if they want a public API probe.

## Expected Impact for End-Users

Internal operators should see noticeably faster deploy completion in common backend-first rollouts. End-user-facing impact is indirect: faster operational iteration and quicker server refreshes when web changes are not required.

## Validation

- Ran `bun run scripts/deploy.ts --help` to validate CLI parsing/help output for the new flag.
- Ran full test suite with `bun test` (pass, 232 passing tests).

## Issues, Limitations, and Mitigations

- `--fast` intentionally reduces verification depth; it is not equivalent to the full rollout safety envelope.
- Fast mode defaults away from web rollout on full scope, so web changes should use explicit web/full scope deploys.
- Mitigation: behavior is opt-in, surfaced in help text, and documented in deployment READMEs.

## Follow-up Work

- No immediate follow-up required for this change.
- Optional future work: add an automatic changed-path-to-scope mapper to choose the smallest safe build set without operator guesswork.
- Beads issue: `islandflow-xod` (this task).