docs(deploy): Fly.io fly.toml and deployment instructions

examples/README.md

@@ -30,7 +30,7 @@ Use this as a **discoverability** pass for the **[ROADMAP.md](../ROADMAP.md)** s
 |------|---------|
 | [quickstart/](quickstart/) | Minimal workspace used by `flightdeck-quickstart-verify`. |
 | [ci/](ci/README.md) | Policy gate script, sample policy YAML, GitHub Actions job snippets. |
-| [deploy/](deploy/README.md) | Dockerfile and compose for `flightdeck serve`. |
+| [deploy/](deploy/README.md) | Dockerfile and compose for `flightdeck serve`; optional **Fly.io** (`fly.toml`). |
 | [integration/](integration/README.md) | Sample event emitter for HTTP ingest. |
 | [integration/adoption/](integration/adoption/README.md) | OpenAI, Anthropic, LangChain, Agents SDK, CrewAI-style totals, Temporal labels → `RunEvent`. |
 | [fleet/](fleet/README.md) | Multi-workspace naming, optional catalog path, approval workflow notes. |

examples/deploy/README.md

@@ -40,6 +40,43 @@ Inside the Compose stack, **`exec`** into the running container with **`/workspa
 
 Set **`FLIGHTDECK_LOCAL_API_TOKEN`** in your environment before `docker compose up` (or in an `.env` file beside `docker-compose.yml`). Clients must send **`Authorization: Bearer …`** for **ledger writes**: **`POST /v1/promote*`**, **`POST /v1/rollback`**, and **`POST /v1/events`**. With no token configured, those routes accept only **loopback** callers. **`POST /v1/diff`** stays unauthenticated (read-only); still treat network placement as a trust boundary.
 
+For **Fly.io** (public HTTPS demo or staging), see **[Fly.io](#flyio)** below.
+
+## Fly.io
+
+Deploy the same Docker image to [Fly Machines](https://fly.io/docs/machines/). This gives you a URL you can open from any browser; treat it as **trusted** or lock it down with **`FLIGHTDECK_LOCAL_API_TOKEN`** (see **[SECURITY.md](../../SECURITY.md)**).
+
+### One-time setup
+
+1. Install [`flyctl`](https://fly.io/docs/hands-on/install-flyctl/) and run **`fly auth login`**.
+2. From **`examples/deploy/`**:
+   - Edit **`fly.toml`**: set **`app`** to a unique name (or run **`fly apps create <name>`** and match).
+   - Optional **persistent ledger**: create a volume in the **same region** as **`primary_region`**:
+     ```bash
+     fly volumes create fd_workspace --region iad --size 1
+     ```
+     Uncomment the **`[mounts]`** block at the bottom of **`fly.toml`** (`source = "fd_workspace"`, `destination = "/workspace"`).
+3. **Secrets** (recommended once you expose the app on the internet):
+   ```bash
+   fly secrets set FLIGHTDECK_LOCAL_API_TOKEN="$(openssl rand -hex 24)"
+   ```
+   The server then expects **`Authorization: Bearer …`** for ledger writes from non-loopback clients. The stock **`examples/deploy` image** does not embed a browser token; use either **read-only UI** (`VITE_FLIGHTDECK_UI_READ_ONLY=true` in a custom image build — see **`docs/web-ui.md`**) or rebuild the image with **`VITE_FLIGHTDECK_LOCAL_API_TOKEN`** matching your secret so the bundled UI can call promote/diff when **`read_auth`** is bearer-gated.
+
+### Deploy
+
+```bash
+cd examples/deploy
+fly deploy --remote-only
+```
+
+Open **`https://<app>.fly.dev/`** — static UI and **`/v1/*`** on the same origin.
+
+### Notes
+
+- **Cold starts:** **`fly.toml`** allows **`min_machines_running = 0`**; first request may wake the Machine.
+- **Demo-only UI:** ship a build with **`VITE_FLIGHTDECK_UI_READ_ONLY=true`** if you only want read-only navigation (rebuild **`web/`** and static bundle per **`docs/web-ui.md`**).
+- **Maintainers:** this repo cannot run **`fly deploy`** for you; use your own Fly org and the steps above.
+
 ## Helm (optional single-replica chart)
 
 A minimal chart lives under **`chart/flightdeck/`**. It runs one replica of **`flightdeck serve`** with an **`emptyDir`** workspace (ephemeral); for a persistent ledger, replace the volume in **`templates/deployment.yaml`** with a PVC or mount your own image init.

examples/deploy/fly.toml

@@ -0,0 +1,44 @@
+# Fly.io — deploy `flightdeck serve` from this directory (`examples/deploy`).
+#
+# Prerequisites: `flyctl auth login`, then either:
+#   fly apps create <your-app-name>
+# and set `app` below to match, or run `fly launch` once and merge settings.
+#
+# Ephemeral ledger: omit [mounts] (data may reset when Fly replaces the Machine).
+# Persistent SQLite: create a volume and uncomment [mounts] (see README).
+
+app = "flightdeck-demo"
+primary_region = "iad"
+
+[build]
+  dockerfile = "Dockerfile"
+
+[env]
+  # Strongly recommended for any non-loopback deploy (see SECURITY.md):
+  #   fly secrets set FLIGHTDECK_LOCAL_API_TOKEN="$(openssl rand -hex 24)"
+  # Do not commit tokens; use Fly secrets only.
+
+[http_service]
+  internal_port = 8765
+  force_https = true
+  auto_stop_machines = true
+  auto_start_machines = true
+  min_machines_running = 0
+
+[[http_service.checks]]
+  grace_period = "20s"
+  interval = "30s"
+  method = "GET"
+  timeout = "5s"
+  path = "/health"
+
+[[vm]]
+  memory = "512mb"
+  cpu_kind = "shared"
+  cpus = 1
+
+# Uncomment after: fly volumes create fd_workspace --region iad --size 1
+# (region must match primary_region; size is GB)
+# [mounts]
+#   source = "fd_workspace"
+#   destination = "/workspace"