Turn document 2026-05-15 Issue: islandflow-4gj

# Clarify Docker-first deploy workflow

Updated deploy messaging and deployment docs so Docker is clearly the supported VPS path today, while the native runtime is labeled experimental and fails faster with clearer prerequisites.

## Summary

The deploy helper now warns when `--runtime native` is used, defaults native systemctl invocations to `sudo -n systemctl` so they fail fast instead of hanging for a password, and prints explicit precheck errors when Bun or systemd readiness is missing. Docs now describe Docker as the default and recommended VPS rollout path.

## Changes Made

- Updated `scripts/deploy.ts` help text to mark Docker as default and recommended, and native as experimental.
- Changed the native systemctl default from `sudo systemctl` to `sudo -n systemctl` to avoid interactive hangs.
- Added a runtime advisory banner for native deploy attempts.
- Improved native remote precheck failures for missing Bun, missing systemctl access, and missing systemd units.
- Updated `README.md`, `deployment/docker/README.md`, and `deployment/native/README.md` to reflect the live VPS reality: Docker plus Nginx Proxy Manager remains the supported deployment path.

## Context

Live inspection of the VPS showed that Nginx Proxy Manager routes `flow.deltaisland.io` and API traffic to the Docker `web` and `api` containers by container name on the shared Docker network. The host does not currently have Bun installed, passwordless `sudo systemctl` is not configured, and no Islandflow systemd units are present. Because of that, native deployment should be treated as future infrastructure work rather than the recommended day-to-day path.

## Important Implementation Details

- Native rollout prechecks now fail with actionable messages instead of a silent command failure or a hanging sudo prompt.
- The native docs now explicitly say the current VPS is not prepared for routine native rollouts.
- Docker deployment behavior itself was not changed. This was a clarity and guardrail pass, not a runtime migration.

    [deploy] Native runtime is experimental. Use --runtime docker for the current supported VPS path unless Bun, systemd units, and proxy routing have been prepared intentionally.

## Validation

- Passed: `./deploy --help`
- Passed: `bun run check:docker-workspace`
- Passed: `./deploy main --runtime native --no-build` now fails quickly with an explicit Bun-missing message on the live VPS

    ./deploy --help
    ./deploy main --runtime native --no-build
    bun run check:docker-workspace

## Issues, Limitations, and Mitigations

- Native deploy remains experimental. Mitigation: docs and CLI output now say so directly.
- The live VPS still depends on Docker-name routing through Nginx Proxy Manager. Mitigation: Docker remains the recommended deployment path.
- No systemd units or Bun install were added in this change. That work remains a separate follow-up.

## Follow-up Work

- Keep native deployment support available for future experimentation, but treat it as opt-in infrastructure work.
- Open follow-up: `islandflow-38p`, add native deployment unit templates and rollback helpers if the host-native path is revived later.