Turn document 2026-05-15 Issue: islandflow-qh7

# Dual-runtime deploy workflow

Updated the root deploy flow so it can target either the existing Docker Compose VPS runtime or a new host-native Bun + systemd runtime, while also adding partial deploy scopes for faster iteration.

## Summary

The deploy helper now supports `--runtime docker` and `--runtime native`, keeps Docker as the default, and adds `--web-only`, `--api-only`, `--services-only`, and `--no-build`. Documentation now clearly separates fast local development from VPS rollout options.

## Changes Made

- Refactored `scripts/deploy.ts` into shared git/publish logic plus runtime-specific precheck, rollout, and verification paths.
- Fixed the repo-root `deploy` wrapper to forward flags such as `--runtime native` through Bun correctly.
- Removed Docker verification’s dependence on hardcoded container names and switched to `docker compose exec`.
- Added native deployment support that assumes Bun plus systemd-managed units on the VPS.
- Added a new operator guide at `deployment/native/README.md`.
- Updated `README.md` to emphasize the preferred fast local loop: Docker infra only, native Bun services, native web dev.
- Updated `deployment/docker/README.md` to document Docker as the default runtime and show new partial rollout examples.

## Context

The repo already separated local infra from application processes: the root `docker-compose.yml` is infra-only, while services and the web app run through Bun scripts. The old deploy helper still assumed every server rollout was Docker-only. This change makes the deploy workflow match the new operating model: fast native iteration locally, Docker still available in production, and a native VPS path available during transition.

## Important Implementation Details

- Docker remains the default runtime, so `./deploy main` still works without extra flags.
- Native rollouts are invoked with `./deploy main --runtime native` or `./deploy current-branch --runtime native`.
- Partial scopes are mutually exclusive and intentionally simple:

    ./deploy main --runtime docker --web-only
    ./deploy main --runtime native --api-only
    ./deploy current-branch --runtime docker --services-only
    ./deploy main --runtime native --web-only --no-build

- Docker workspace snapshot validation now runs only when a Docker rollout will build images.
- Native rollouts assume systemd unit names like `islandflow-web` and `islandflow-api`, but those names can be overridden with environment variables such as `DEPLOY_NATIVE_WEB_UNIT`.
- The native path also allows overriding the systemctl wrapper via `DEPLOY_NATIVE_SYSTEMCTL_PREFIX`, which is useful for `systemctl --user` setups.

## Validation

- Passed: `./deploy --help`
- Passed: `bun run scripts/deploy.ts --help`
- Passed: `bun run check:docker-workspace`
- Passed: invalid-flag guard for `--runtime native --force-recreate`
- Passed: conflicting-scope guard for `--web-only --api-only`

    bun run scripts/deploy.ts --help
    bun run check:docker-workspace
    bun run scripts/deploy.ts main --runtime native --force-recreate
    bun run scripts/deploy.ts main --web-only --api-only

## Issues, Limitations, and Mitigations

- Native deploys assume server-side systemd units already exist. Mitigation: added `deployment/native/README.md` documenting expected unit names and override variables.
- Rollback is still manual. Mitigation: both Docker and native docs now frame runtime selection as a transition path, with Docker preserved as a fallback.
- No native service unit files were added in this change. This keeps the scope focused on the deploy workflow itself.
- Public verification still centers on the hosted app URL. API verification remains local-to-runtime unless `DEPLOY_PUBLIC_API_HEALTH_URL` is configured.

## Follow-up Work

- Implementation tracked in `islandflow-qh7` is complete for the deploy helper itself.
- Open follow-up: `islandflow-38p`, add checked-in native deployment unit templates and rollback helpers.