# Bundled Binary Distribution — Multi-Platform Plan

## Context

Users have asked for a way to run OxiCloud without Docker — a plain
binary. Today `release.yml` only creates a GitHub Release with notes;
no binary is attached. The Docker workflow (`docker-publish.yml`) ships
multi-arch images, but that's a separate audience.

The blocker for a "just download and run" experience is that the
`oxicloud` binary depends on the SvelteKit build output (`static-dist/`
under `<static_path>/static-dist/`, resolved by
`src/interfaces/web/mod.rs::resolve_static_path` at boot). Two files
to distribute per platform is friction; a single self-contained binary
is what users actually want.

The ask has two parts:

1. Ship **single-file binaries with frontend assets embedded**, for
   the common Linux targets and macOS.
2. Audit the current binary set — the crate produces 6+ binaries today,
   some of which are test-only. Strip anything that shouldn't ship to
   end users.

The intended outcome: a `v0.9.0` release attaches **4 musl-static
tarballs** (Linux amd64/arm64 + macOS Intel/Apple Silicon), each
~15-30 MB, containing a **single `oxicloud` binary** with assets +
operator tools + one-off migrations all baked in. User extracts the
tarball, sets `DATABASE_URL`, runs `./oxicloud` — server up.
Subcommands (`oxicloud opaque setup`, `oxicloud migrate
nfc-filenames --dry-run`) provide operator access to the same tools
currently split across `oxicloud-cli` and `migrate-nfc-filenames`.

Design shape (confirmed 2026-08-27):

- **musl-only Linux** — parity with the existing Docker image (Alpine
  base), no glibc-version fragmentation
- **Assets embedded via `rust-embed` with compile-time deflate
  compression** — smaller binary
- **`bundled-assets` is opt-in** — default `cargo build` unchanged;
  `just dev` still uses the filesystem `ServeDir` with Vite HMR
- **Single unified binary** — `oxicloud`, `oxicloud-cli`, and
  `migrate-nfc-filenames` collapse into one clap-driven executable
  with implicit-server default (backwards compat with existing Docker
  CMD / systemd units)

## Current binary inventory

From `Cargo.toml` + `src/bin/`:

| Binary | Path | Purpose | Ship to end users? |
|---|---|---|---|
| `oxicloud` | `src/main.rs` (implicit) | Server | **YES** |
| `oxicloud-cli` | `src/bin/oxicloud-cli.rs` | Operator toolbox (`opaque setup/reset`) | **MERGED** — absorbed into `oxicloud` per Deliverable 1b |
| `migrate-nfc-filenames` | `src/bin/migrate-nfc-filenames.rs` | One-off filename migration (historical, June 2026 fix) | **MERGED** — absorbed into `oxicloud migrate nfc-filenames` per Deliverable 1a→1b |
| `generate-openapi` | `src/bin/generate-openapi.rs` | Regenerate `resources/gen/openapi.json` | NO — dev tool, gate behind `dev_tools` feature |
| `opaque-hurl-helper` | `src/bin/opaque-hurl-helper.rs` | Hurl test companion (OPRF client) | NO — gate behind `test_utils` feature |
| `dpop-hurl-helper` | `src/bin/dpop-hurl-helper.rs` | Hurl test companion (ES256 DPoP proof) | NO — gate behind `test_utils` feature |
| `load-seed` | `src/bin/load-seed.rs` | Test fixture seeder | Already gated behind `load_seed_bin` feature ✅ |

After Deliverables 1 + 1a + 1b, `cargo build --release --bins`
produces exactly ONE binary: `oxicloud`. That single binary ships in
the tarball and in the Docker image.

## Deliverables

### 1. Squash test/dev binaries with `required-features`

Cargo respects `required-features` per `[[bin]]` — a binary is only
built when its listed features are active. This gates test helpers
out of `cargo build --release --bins` cleanly without needing custom
Cargo commands or shell trimming.

Edits to `Cargo.toml`:

```toml
[features]
# ... existing features ...
dev_tools = []             # NEW: gates ops tooling that shouldn't ship

[[bin]]
name = "opaque-hurl-helper"
path = "src/bin/opaque-hurl-helper.rs"
required-features = ["test_utils"]     # NEW gate

[[bin]]
name = "dpop-hurl-helper"
path = "src/bin/dpop-hurl-helper.rs"
required-features = ["test_utils"]     # NEW gate

[[bin]]
name = "generate-openapi"
path = "src/bin/generate-openapi.rs"
required-features = ["dev_tools"]      # NEW gate — `just openapi` flips it

# [[bin]] name = "migrate-nfc-filenames"    ← DELETED per Deliverable 1a
# [[bin]] name = "oxicloud-cli"             ← DELETED per Deliverable 1b
```

Existing invocations that need adjustment:

- `just openapi` recipe → add `--features dev_tools` to the underlying
  `cargo run --bin generate-openapi` call (currently `cargo run --bin
  generate-openapi` per justfile)
- `tests/api/run.sh` → add `--features test_utils` when building the
  two hurl helpers (shape confirmed: `cargo build [--release] --bin
  opaque-hurl-helper` / same for dpop in each helper's build-if-missing
  branch)

After these edits + Deliverables 1a + 1b: `cargo build --release --bins`
produces exactly ONE binary — `oxicloud`. Everything else falls out of
the default build set.

### 1a. Merge `migrate-nfc-filenames` into `oxicloud-cli`

The standalone `migrate-nfc-filenames` binary is a June-2026 one-off:
it cleans up NFD/NFC filename collisions in databases populated
before the write-time fix (`normalize_storage_name()` at
`src/domain/services/path_service.rs:36`, called from
`src/infrastructure/repositories/pg/file_blob_read_repository.rs:1062`).
New installs never need it; only pre-June 2026 databases do.

`oxicloud-cli`'s header docstring (`src/bin/oxicloud-cli.rs:20-23`)
already documents the growth pattern for absorbing tools like this:

> *"each new domain gets its own module below (e.g. `mod opaque`)
> with a `#[derive(Subcommand)]` enum for its actions and a
> `run(args) -> ExitCode` entrypoint. Keep each module self-contained
> so a future extraction is a file move."*

Note: this Deliverable is an intermediate step. Deliverable 1b then
absorbs `oxicloud-cli` itself into `oxicloud`, so the final CLI form
becomes `oxicloud migrate nfc-filenames --dry-run` — but 1a lands
first so the migration logic is proven inside the clap subcommand
tree before the main-binary merge.

Edits:

- **New `mod migrate` in `src/bin/oxicloud-cli.rs`** — moves the ~149
  non-boilerplate lines from `migrate-nfc-filenames.rs::main()` into
  a `run_nfc_filenames(dry_run: bool) -> ExitCode` function.
  `env::args()` parsing goes away; clap handles it.
- **Delete `src/bin/migrate-nfc-filenames.rs`**.
- **Delete the `[[bin]]` entry** in `Cargo.toml`.
- **Update `Dockerfile`** — 6 references to `migrate-nfc-filenames`
  (build commands at :46, :49, :89, `cp` steps at :130, :143, doc
  comment at :170, `COPY --chmod=755 --from=app` at :173).
- **Update `docs/plan/benchmake-and-performance-tracking.md`** — 2
  references to `migrate-nfc-filenames` at lines :44 and :161. Reword
  to reference `oxicloud-cli migrate nfc-filenames` (or, after 1b,
  `oxicloud migrate nfc-filenames`) and update the Cargo.toml
  placement example.
- **Any operator runbook** that documents `docker exec <container>
  migrate-nfc-filenames --dry-run` becomes `docker exec <container>
  oxicloud-cli migrate nfc-filenames --dry-run` (intermediate) then
  `docker exec <container> oxicloud migrate nfc-filenames --dry-run`
  after 1b.

Effort: ~1.5 hours mechanical. Extracts the "should the tarball ship
migrate-nfc-filenames?" question entirely — everything now ships as
one operator toolbox binary that also happens to include the
historical migration.

Future v1.0 removal path (deferred): delete `mod migrate` block + one
enum variant + docs. Much cleaner than removing a whole `.rs` file +
Cargo entry + Dockerfile refs.

### 1b. Merge `oxicloud-cli` into `oxicloud`

Single binary — server + operator tools + migrations — with an
**implicit-server** subcommand tree. `oxicloud` with no arguments
starts the server (backwards compat with existing Docker CMD /
systemd units / user configs). Subcommands add operator actions on
top.

After merge, the CLI shape is:

```
$ oxicloud --help
Usage: oxicloud [OPTIONS] [COMMAND]

Commands:
    opaque      OPAQUE aPAKE substrate management
    migrate     One-time data migrations

If no command is given, oxicloud starts the server (see docs/config).
```

Concrete forms:

- `oxicloud` — start server (unchanged)
- `oxicloud opaque setup` — was `oxicloud-cli opaque setup`
- `oxicloud opaque reset --user alice --dry-run` — was `oxicloud-cli
  opaque reset ...`
- `oxicloud migrate nfc-filenames --dry-run` — was
  `migrate-nfc-filenames --dry-run` (via Deliverable 1a)

**Backwards-compat guarantee**: `oxicloud` with no args continues to
start the server. Every existing `CMD ["oxicloud"]`, `ExecStart=/usr/local/bin/oxicloud`,
docker-compose entry, and k8s Deployment keeps working unchanged.
Users updating to v0.9.0 see no surprise.

**Migration impact**: the user-visible break is that `oxicloud-cli
opaque setup` (etc.) no longer exists as a separate binary. Given the
current audience for `oxicloud-cli` is very small (essentially only
the maintainer), the migration cost is trivial. Any user who had
scripted it can adapt with a one-line find/replace.

Edits:

- **`src/main.rs`** — top of `main()`, before the current server
  init, parse args via clap. If a subcommand is provided, dispatch
  to it and exit; otherwise fall through to the existing server-init
  path. Zero-arg startup cost stays ≤ microseconds (clap parse of
  empty args).
- **`src/cli/mod.rs`** — NEW module. Contains the `Domain` enum + the
  `opaque` and `migrate` submodules moved from
  `src/bin/oxicloud-cli.rs`. Each subcommand module keeps its
  self-contained shape per the growth pattern documented in the
  old `oxicloud-cli.rs` header.
- **Delete `src/bin/oxicloud-cli.rs`** entirely.
- **Delete the `[[bin]] name = "oxicloud-cli"` block** in `Cargo.toml`.
- **`Dockerfile`** — drop all 4 references to `oxicloud-cli` (build
  target lines + COPY steps). Simplified build command becomes
  `cargo build --release --bin oxicloud` — single-binary.
- **Docs** — all `docker exec <container> oxicloud-cli <domain>
  <action>` become `docker exec <container> oxicloud <domain>
  <action>`. Same shape, one fewer word.

Effort: ~2 hours mechanical. Comparable to Deliverable 1a but with
slightly more care at the `main.rs` entry point for the args-vs-server
branch.

**Tarball layout simplification** — the tarball now ships exactly
ONE binary:

```
oxicloud-0.9.0-<triple>/
├── oxicloud              (single file, server + tools + embedded assets)
├── example.env
├── LICENSE
└── README-install.md
```

That's the "just download and run" ethos in physical form: one file,
one command, done.

### 2. Add `bundled-assets` cargo feature

Purpose: at compile time, choose between filesystem-served static
assets (current behaviour — filesystem `ServeDir`) and
embedded-into-binary assets (via `rust-embed`). Feature is
**opt-in** — the default `cargo build --release` still produces a
filesystem-based binary, matching the current Docker image behaviour
(where assets are separate volume layers). Release tarballs are built
with `--features bundled-assets`.

**Dev mode is untouched.** `just dev` runs `PROFILE=dev cargo run` +
`npm run dev`, neither of which activates `bundled-assets`. The dev
workflow continues to:

- Serve from `frontend/` via Vite's dev server with HMR
- Backend reads static assets from `<static_path>/static-dist/` via the
  usual `ServeDir` (or falls back to `frontend/static/` when the
  build hasn't been run)
- No rebuild required to change locales, styles, or vendor JS

The `bundled-assets` code paths only compile when the feature is
explicitly enabled — under a `#[cfg(feature = "bundled-assets")]` gate.
The non-feature build's binary shape, ergonomics, and dev loop stay
identical to today.

Measured footprint (2026-08-27):

| Slice | Size | Notes |
|---|---|---|
| Total `static-dist/` uncompressed | **9.8 MB** | 499 files |
| `_app/` (SvelteKit bundle) | 3.3 MB | JS + CSS chunks |
| `vendors/` | 3.6 MB | maplibre-gl 1.0 MB, pdf.worker 1.0 MB, others |
| `locales/` | 2.2 MB | 16 locales, ru.json + hi.json largest at ~116-140 KB |
| `logo/`, `geo/`, `basemaps/`, `workers/`, misc | ~600 KB | |
| **`.tar.gz` compressed** | **4.65 MB** | realistic embed cost after brotli/gzip inside binary |
| **`.tar.xz` compressed** | **4.22 MB** | not what rust-embed uses; reference only |

Expected release-binary size with embed: `oxicloud` today ships in
the 30-60 MB range (stripped, LTO). Add ~5-10 MB for embedded
static-dist. Tarball compression on top → ~20-30 MB shipped per
platform. Four platforms × ~25 MB = ~100 MB per release. Well within
GitHub Releases limits.

Cargo.toml additions:

```toml
[features]
bundled-assets = ["dep:rust-embed", "dep:mime_guess"]

[dependencies]
rust-embed = { version = "8", features = ["compression"], optional = true }
mime_guess = { version = "2", optional = true }
```

Runtime shape — a new module `src/interfaces/web/embedded.rs`:

```rust
#[cfg(feature = "bundled-assets")]
#[derive(rust_embed::RustEmbed)]
#[folder = "static-dist/"]   // ← repo-root, matches SvelteKit adapter-static output
#[include = "*"]
#[exclude = "*.br"]      // Vite's precompressed sibling — response compression handles on wire
#[exclude = "*.gz"]      // ditto
pub struct EmbeddedAssets;
```

The `#[folder]` path is relative to Cargo.toml (repo root), where the
SvelteKit adapter-static config in `frontend/svelte.config.js` emits:

```js
adapter: adapter({
    pages: '../static-dist',
    assets: '../static-dist',
    ...
})
```

The current filesystem shape (at `src/interfaces/web/mod.rs:47-106`)
is more than one `ServeDir` — the embed swap replaces FOUR sites, all
downstream of `resolve_static_path()`:

1. **`spa` ServeDir** (`mod.rs:60-63`) — root fallback with
   `precompressed_br().precompressed_gzip()` and SPA-shell fallback
   pointing at `<static>/index.html`. Under embed: an axum handler
   that resolves the request path against `EmbeddedAssets::get()`,
   200 with correct MIME (via `mime_guess`) if hit, otherwise return
   the embedded `index.html` bytes with `text/html` for SPA client-routing.
2. **`app_immutable` ServeDir** (`mod.rs:66-77`) — nested at
   `/_app/immutable` with `Cache-Control: public, max-age=31536000,
   immutable`. Under embed: same handler shape as (1), scoped to
   the `_app/immutable/` prefix, plus a `.layer()` that stamps the
   immutable cache header.
3. **`ServeFile::new(index.html)`** SPA fallback (`mod.rs:63`) —
   folds into (1)'s not-found path.
4. **CSP inline-script scan** (`mod.rs:163-233`) — currently reads
   every `.html` file in the resolved static dir via
   `std::fs::read_dir` + `std::fs::read_to_string` at boot to compute
   SHA-256 CSP source expressions for every inline `<script>`. Under
   embed: iterate `EmbeddedAssets::iter()` filtered to `.html`
   extensions, pull bytes via `::get()`, hash the same way. Same
   arithmetic, different source. Boot-time only.

All four flow through `resolve_static_path()` at `src/interfaces/web/mod.rs:25-35`
— that helper is the natural pivot. Add a returned enum:

```rust
#[cfg(feature = "bundled-assets")]
pub enum StaticSource {
    Filesystem(PathBuf),       // OXICLOUD_STATIC_PATH points at a real dir
    Embedded,                  // fall through to compiled-in bytes
}
```

Then the four callsites (`create_web_routes` + CSP scan) match on
`StaticSource` and pick their implementation. Under the default
feature set (no `bundled-assets`), the enum degrades to a bare
`PathBuf` — zero runtime cost, no cfg pollution across the wider
codebase.

**Locale loading — also needs embed treatment.** Two callsites read
locales at runtime:

- `src/main.rs:599-615` — resolves `<static_path>/locales/` at boot
  and passes it to `LocaleRegistry::discover()` at
  `src/common/locale.rs:150-221`, which does `fs::read_dir` +
  `fs::read_to_string` + `serde_json::from_str` on each of 16 files.
  Currently fail-fast panics if the directory is missing.
- `src/infrastructure/services/file_system_i18n_service.rs` — the
  runtime translator, `translations_dir: PathBuf` field, does
  `tokio::fs::read_to_string` on `<dir>/<code>.json` per lazy-load
  miss (cached in `RwLock<HashMap<Locale, Value>>`).

Under `bundled-assets`, both get an alternative implementation that
reads from `EmbeddedAssets` (locale files are at
`static-dist/locales/*.json`, picked up by the same folder embed).
Recommended shape: constructor pair —
`LocaleRegistry::discover_filesystem(path)` and
`#[cfg(feature = "bundled-assets")] LocaleRegistry::discover_embedded()`.
`main.rs` picks based on the resolved `StaticSource`. Simpler than a
trait-based indirection for two static sources with the same interface.

Frontend at runtime ALSO fetches `/locales/*.json` for client-side
i18n — this path is served by the same static router in (1) above,
so no separate work; the embed already covers it.

Precedence rule: even in a bundled build, honour `OXICLOUD_STATIC_PATH`
when it points at an existing directory. Lets ops override embedded
assets for locale patches / theming without a full rebuild. The
`resolve_static_path` return value is checked at boot; a real directory
wins over embedded fallback. If the resolved directory does NOT exist,
fall through to the embedded handler cleanly (log at info level:
"OXICLOUD_STATIC_PATH points at <path> which doesn't exist; serving
embedded assets").

Build-time invariant: `cargo build --features bundled-assets` requires
`static-dist/` to exist AND be non-empty. Add a `build.rs` check that
emits a clear error if missing, pointing at `just fe-build` /
`(cd frontend && npm run build)`.

**Precompression + embed strategy**: minimize binary size by storing
assets compressed inside the binary, and use axum's response
compression on the wire.

`rust-embed`'s `compression` feature deflate-compresses each embedded
file at compile time. Files are decompressed lazily on first access
and cached in a per-file `OnceCell` for the remainder of the process.
Warms up quickly under real traffic — the first user's page load
touches ~30 files, all cached from then on.

On the wire, response compression is handled by axum's
`CompressionLayer` (tower-http) applied to the static router
subtree. Browsers get `Content-Encoding: br` when they Accept-Encoding
brotli; gzip fallback; identity for clients that ask for neither.

Projected embed size after excludes + rust-embed deflate compression:
**~4-5 MB**. Matches the `.tar.xz` reference size and roughly halves
what raw-embed-plus-siblings would cost. Runtime CPU: negligible under
any real load; the compressed variants would benefit from a
reverse-proxy cache in front for CPU-tight hosts (Pi 4/5).

Consequence for the `nginx`/reverse-proxy story users will run in
front: the binary responds correctly to `Accept-Encoding: br, gzip`
without configuration. Users terminating TLS at their proxy get
compressed responses either way (proxy passes through or re-compresses
its cache).

### 3. Target matrix — musl-only Linux

Three triples cover the practical need:

| Triple | Runner + toolchain | Notes |
|---|---|---|
| `x86_64-unknown-linux-musl` | `ubuntu-22.04` + `musl-tools` + `rustup target add` | Static, no glibc dep, runs on ANY Linux distro from Alpine to CentOS 7 to Debian 10 to Ubuntu 25.04. Cross-compiled natively with glibc host + musl target; produces same output as the alpine-container path we originally planned. |
| `aarch64-unknown-linux-musl` | `ubuntu-22.04-arm` + `musl-tools` + `rustup target add` | Same shape as the amd64 twin. Native ARM64 runner (no QEMU). Pi 4/5, ARM servers, Graviton. |
| `aarch64-apple-darwin` | `macos-latest` | Apple Silicon, native |

**Historical note — Intel macOS dropped 2026-08-29** (Apple phasing
out `macos-13`; runner-availability tax exceeded value). Intel Mac
users fall back to `cargo install`, Docker `--platform linux/amd64`,
or one of the Linux musl tarballs inside a Linux VM.

**Historical note — Alpine-container approach abandoned 2026-08-29**
in favour of native cross-compile. Original plan built inside the
Dockerfile's `rust:1.96-alpine3.24` for byte-for-byte parity with
Docker; broke on `ubuntu-22.04-arm` because JS-based GitHub Actions
(checkout, artifact steps, setup-node) can't run inside Alpine on
ARM64 (Node.js binary requires glibc; the x64-Alpine workaround
doesn't extend to arm64). Native `ubuntu-22.04` + `musl-tools` +
`rustup target add` produces the same `--target *-musl` output
without the container gymnastics.

**Rationale for musl-only Linux**:

1. **Parity with Docker.** The Docker image is already Alpine/musl —
   users get identical runtime behaviour whether they pull the
   container or the tarball. One build shape, one test surface.
2. **Face-indexing regression is a NON-issue.** `faces-onnx` requires
   glibc-only `libonnxruntime.so`; it's already unavailable on the
   Docker image. Users who want face indexing build from source with
   `--features faces-onnx` on a glibc host — same as today, no
   change from musl-only tarballs.
3. **Zero glibc-version fragmentation.** No `GLIBC_2.35 not found`
   errors on older distros. One binary works everywhere.
4. **Simpler install docs.** "Download this file, run it" without
   a "which glibc do you have?" branch.
5. **Marginal perf hit is invisible under I/O-bound OxiCloud workloads.**
   Musl's `malloc` and DNS resolver quirks matter for allocation-heavy
   / DNS-heavy servers; OxiCloud is neither.

**External runtime dependencies** — complete list. Codebase audit
2026-08-27 confirmed `ffmpeg` is the ONLY `Command::new` invocation
in `src/`; no other subprocess deps exist.

| Category | Dep | Required? | Notes |
|---|---|---|---|
| Subprocess | `ffmpeg` | Optional | Video thumbnails. Kill switch: `OXICLOUD_ENABLE_VIDEO_THUMBNAILS=false`. Path override: `OXICLOUD_FFMPEG_PATH` |
| System lib | `ca-certificates` | Required | Outbound HTTPS (OIDC, S3, webhooks). Pre-installed on nearly every distro |
| System lib | `tzdata` | Required | Timezone DB for chrono. Pre-installed on nearly every distro |
| External service | PostgreSQL 13+ | Required | With `pg_trgm` + `ltree` extensions. TCP/loopback only — no libpq client lib needed |
| Runtime dylib | `libonnxruntime.so` + ONNX models | N/A for tarball | Face indexing (glibc-only, requires build from source with `--features faces-onnx`). Not shipped in musl tarballs — Docker/tarball users don't have this feature |

**Explicit non-deps** (worth documenting to preempt questions):

- **No libpq** — sqlx uses pure-Rust tokio-postgres
- **No git** — only build-time metadata via `build.rs`, never runtime
- **No ImageMagick / libvips** — image thumbnails via pure-Rust `image` crate
- **No pandoc / rst2html / etc.** — no document conversion
- **No systemd/launchd** — daemon lifecycle user-managed
- **No sendmail / SMTP CLI** — email via pure-Rust SMTP client

**Per-distro install command** (for `README-install.md`):

| Distro | Command |
|---|---|
| Alpine | `apk add ca-certificates tzdata ffmpeg` |
| Debian / Ubuntu | `apt install ca-certificates tzdata ffmpeg` |
| Fedora / RHEL | `dnf install ca-certificates tzdata ffmpeg` (RPMFusion for full codec set) |
| Arch | `pacman -S ca-certificates tzdata ffmpeg` |
| macOS | `brew install ffmpeg` (ca-certificates + tzdata built in) |
| Portable Linux | Static ffmpeg from https://github.com/BtbN/FFmpeg-Builds/releases + `OXICLOUD_FFMPEG_PATH=<path>` |

Postgres install is documented separately (project docs) since it's a
per-distro-per-version story with per-extension setup.

**Windows deliberately deferred** — sqlx feature set, some C deps,
testing story on Windows are all extra work.

**Pi 2 / 32-bit ARM (`armv7-unknown-linux-gnueabihf`) excluded** —
1 GB RAM is below OxiCloud's practical floor even with face indexing
disabled.

**Building strategy for Linux musl targets** — run the compilation
inside the `rust:1.96-alpine3.24` container image the Dockerfile
already uses. Guarantees byte-for-byte parity with what ends up in
the published Docker image; zero new toolchain to maintain. Runner
just needs Docker (all GitHub-hosted Linux runners have it). No
`rustup target add`, no `apt install musl-tools`.

**CPU baseline** — the repo sets `-C target-cpu=native` for x86_64 and
aarch64 hosts (`.cargo/config.toml:11-12`). That flag makes the binary
use every CPU feature the BUILDER exposes — great for local dev,
catastrophic for distributed binaries: a runner with AVX-512 produces
a binary that segfaults on any older CPU. Precedent for the fix at
`.github/workflows/load-smoke.yml:28`, which already overrides with
`RUSTFLAGS="-C target-cpu=x86-64-v3"` for load tests.

Per-target baseline for `release-binaries.yml`:

| Triple | `RUSTFLAGS` |
|---|---|
| `x86_64-unknown-linux-musl` | `-C target-cpu=x86-64-v2` |
| `aarch64-unknown-linux-musl` | `-C target-cpu=generic` (safe ARMv8-A baseline) |
| `aarch64-apple-darwin` | `-C target-cpu=apple-m1` |

`x86-64-v2` covers ~2010+ processors (Nehalem, Bulldozer). Widest
realistic install base for a "runs everywhere" tarball. Notably
different from Docker's `x86-64-v3` (per `load-smoke.yml:28`) — Docker
targets performance-tuned deployments, tarballs target maximum
compatibility.

Trade-off left on the table: BLAKE3 SIMD + image codecs run somewhat
slower on v2 than v3. For a self-hosted personal cloud workload this
is invisible; for anyone who wants max perf, the Docker image is
still their better option.

### 4. Tarball layout

One archive per platform. **Four files inside**, all rooted under a
per-version-per-triple directory so extraction lands cleanly:

```
oxicloud-0.9.0-<triple>/
├── oxicloud              ← the single binary (server + tools + embedded assets)
├── example.env           ← copied verbatim from repo root (50 KB, all env vars documented)
├── LICENSE               ← copied verbatim from repo root
└── README-install.md     ← NEW, ~100 lines, tarball-audience-specific
```

Deliberate exclusions:

- **`README.md`** (repo root, 10 KB) — the GitHub landing page: features,
  screenshots, tech stack, contribution guide. Wrong orientation for a
  downloaded tarball. Users get `README-install.md` instead — shorter,
  focused on "how do I run this thing on this box?"
- **`oxicloud.service` systemd unit** — inlined as a copy-paste block in
  `README-install.md`. Users have to customize `User=` /
  `WorkingDirectory=` anyway; a documented example beats a shipped file
  that pretends to be canonical.
- **`CHANGELOG.md`** — the GitHub Release page carries the notes.
  Duplicating invites drift.
- **`docs/`** — full documentation stays on GitHub, linked from
  `README-install.md`.

`README-install.md` content shape (~100 lines):

- **Quickstart** — required env vars, one-command run
- **PostgreSQL setup** — link to project docs; note `pg_trgm` + `ltree`
  extensions
- **Optional: video thumbnails** — mention ffmpeg + the
  `OXICLOUD_ENABLE_VIDEO_THUMBNAILS=false` kill switch (first
  user-facing surface for this env var, closing the discoverability
  gap flagged in memory `bug_env_docs_video_thumbnails_missing`)
- **Systemd unit example** — inline copy-paste block, references
  `/etc/oxicloud/oxicloud.env` for env vars
- **First-run** — direct to `/setup` for admin account creation
- **Verification** — `sha256sum -c ../SHA256SUMS` for tarball integrity
- **Upgrading** — replace binary in place, restart service; migrations
  run automatically on boot per `sqlx::migrate!()`
- **Support links** — GitHub Issues, docs site
- **Docker note** — for users who want the container path instead

Tarball name: `oxicloud-<version>-<triple>.tar.gz`.

macOS tarballs stay `.tar.gz` too (not `.zip`) — Homebrew formulas
handle either, and it keeps the CI packaging step uniform. Same
extraction UX cross-platform (`tar xzf`).

`SHA256SUMS` file lists all archives with hashes at the release-level
(next to the tarballs, not inside them) — standard OSS practice.
Users verify via `sha256sum -c SHA256SUMS` before extraction.

### 5. New workflow: `.github/workflows/release-binaries.yml`

Three-stage pipeline, shared frontend build:

```
1. frontend-build       (ubuntu-latest, single job)
   - checkout
   - Node 26 setup
   - npm ci && npm run build     (writes static-dist/ at repo root)
   - upload static-dist/ as artifact "static-dist"

2. binary-build         (matrix over 4 targets, needs: frontend-build)
   - checkout
   - download static-dist artifact into repo-root static-dist/
   - Linux targets: docker run rust:1.96-alpine3.24, cargo build inside
   - macOS targets: rustup target add + native cargo build
   - cargo build --release --features bundled-assets --bin oxicloud
   - tar czf oxicloud-<version>-<triple>.tar.gz oxicloud-<version>-<triple>/
   - upload tarball as per-platform artifact

3. release              (ubuntu-latest, needs: binary-build)
   - download all tarball artifacts
   - compute SHA256SUMS
   - softprops/action-gh-release@v2 with files: dist/*
```

Triggers: `push: tags: v*` (real releases) + `workflow_dispatch` with
`dry_run: true` toggle (build tarballs, upload as workflow artifacts,
skip attaching to a release).

Interaction with existing `release.yml`: **new file**, because the
current `release.yml` is tiny (create release + notes) and mixing
concerns would clutter it. `release.yml` stays as "make the GitHub
Release exist"; `release-binaries.yml` stacks binaries into it. Both
trigger on `push: tags: v*`.

**Parallel-fire behaviour on tag push** — on `git push origin v0.9.0`,
three workflows fire simultaneously:

```
tag push v0.9.0
     │
     ├─── release.yml            (~1 min)      Release + notes
     ├─── docker-publish.yml     (~30-45 min)  multi-arch Docker → GHCR + DockerHub
     └─── release-binaries.yml   (~25-30 min)  4 tarballs → attach to Release
```

Total wall-clock: ~30-45 min (dominated by whichever build is slower).
No sequencing between the three — each has a single responsibility
and runs independently.

Race with `release.yml` is **benign** because `release-binaries.yml`
uses `softprops/action-gh-release@v2`, which:
- **Adds files** to an existing Release if one exists for the tag.
- **Creates** the Release (with default settings, no notes) if
  `release.yml` hasn't finished yet.

Worst case: `release-binaries.yml` finishes first on a tiny tag, creates
a bare Release, `release.yml` catches up and fills in the notes. Users
see the Release progressively; nothing breaks. If this becomes annoying
in practice (unlikely — `release.yml` is ~1 min), flip
`release-binaries.yml` to `on: workflow_run: { workflows: ["Release"],
types: [completed] }` to serialize.

Concurrency: same `${{ github.workflow }}-${{ github.ref }}` group as
`docker-publish.yml`, but `cancel-in-progress: false` — every tag is
unique and immutable, so a superseded release build has nothing to
cancel.

Publish gate: same fork-friendly pattern as `docker-publish.yml` —
`if: github.repository == 'AtalayaLabs/OxiCloud' ||
vars.ENABLE_BINARY_RELEASE == 'true'`. Prevents forks from
auto-attaching binaries to their own tag pushes.

### 6. Docs

- **`docs/install/binary.md`** — quickstart per platform, verify
  SHA256SUMS, minimum env vars (`DATABASE_URL`), systemd unit
  example, Pi-specific advice (link to the "verified on" hardware
  table). Prose only — no code snippets that could go stale.
  Include a "server-side video thumbnails" callout naming the
  `OXICLOUD_ENABLE_VIDEO_THUMBNAILS=false` kill switch — this is
  the first user-facing surface where the env var is discoverable
  (per memory `bug_env_docs_video_thumbnails_missing`, it's not
  in `example.env` nor `docs/env.md` today). Consider fixing the
  underlying gap in `example.env` + `docs/env.md` as a companion
  edit to this PR — small win, high visibility.
- **`README.md`** — add a one-line pointer under Installation:
  "Binary releases attached to each GitHub Release — see
  [docs/install/binary.md]". Do NOT list per-triple download links
  by hand; they'd rot.
- **This file** — the design record. Kept alongside other
  `docs/plan/*.md` docs so the next maintainer sees the rationale
  before touching `release-binaries.yml` or the embed layer.

### 7. `Cargo.toml` `[package.metadata.binstall]` block

Free win: `cargo binstall oxicloud` starts working once the tarballs
land on GitHub Releases with predictable names. Two-line metadata
block declares the URL template:

```toml
[package.metadata.binstall]
pkg-url = "{ repo }/releases/download/v{ version }/oxicloud-{ version }-{ target }.tar.gz"
bin-dir = "oxicloud-{ version }-{ target }/{ bin }{ binary-ext }"
```

No CI change; the tarballs already follow this shape from Deliverable 4.

## Critical files

- `Cargo.toml` — add `bundled-assets` + `dev_tools` features,
  `required-features` on gated bins, `rust-embed` optional dep,
  `[package.metadata.binstall]` block. Delete the
  `[[bin]] name = "oxicloud-cli"` and `[[bin]] name = "migrate-nfc-filenames"`
  blocks (Deliverables 1a + 1b).
- `src/main.rs` — add clap parsing at the top of `main()`. If a
  subcommand is present → dispatch via new `src/cli/` module; otherwise
  fall through to the existing server-init path (backwards-compat
  implicit-server mode).
- `src/cli/mod.rs` — NEW. Root of the operator-tools tree; contains
  `Domain` enum + submodules moved from `src/bin/oxicloud-cli.rs`.
- `src/cli/opaque.rs` — NEW. `opaque setup` + `opaque reset` moved
  from the old `oxicloud-cli.rs`.
- `src/cli/migrate.rs` — NEW. `migrate nfc-filenames` — the ~149
  non-boilerplate lines from the old `migrate-nfc-filenames.rs`,
  wrapped as a clap subcommand.
- `src/bin/oxicloud-cli.rs` — DELETE (contents absorbed into `src/cli/`).
- `src/bin/migrate-nfc-filenames.rs` — DELETE (contents absorbed
  into `src/cli/migrate.rs`).
- `src/interfaces/web/mod.rs` — 400-line file, owns the static-serving
  surface. Four sites gain a `#[cfg(feature = "bundled-assets")]`
  alternative:
  - `resolve_static_path()` (`:25-35`) — returns a `StaticSource`
    enum under bundled mode; a bare `PathBuf` otherwise
  - `create_web_routes()` (`:47-106`) — swap the two `ServeDir`
    constructions for embedded-asset handlers
  - `content_security_policy()` + `inline_script_csp_hashes()`
    (`:163-233`) — iterate `EmbeddedAssets::iter()` instead of
    `fs::read_dir`
  - Import block + type imports for the new source enum
- `src/interfaces/web/embedded.rs` — NEW: `#[derive(RustEmbed)]` struct
  + two axum handlers (root/SPA-fallback + `_app/immutable`-prefixed
  with cache header) + shared MIME helper. ~100 lines.
- `src/main.rs:599-615` — locale-source resolution. Under bundled
  mode, call `LocaleRegistry::discover_embedded()` instead of the
  filesystem variant when `resolve_static_path()` returns
  `StaticSource::Embedded`.
- `src/common/locale.rs:150-221` — add `LocaleRegistry::discover_embedded()`
  under `#[cfg(feature = "bundled-assets")]`. Same parse + registry
  build, source is `EmbeddedAssets::iter()` filtered to `locales/*.json`.
- `src/infrastructure/services/file_system_i18n_service.rs` — either
  extend to accept an `EmbeddedLocales` source alongside the
  filesystem one, OR ship a second `EmbeddedI18nService` impl of the
  same trait. Latter avoids polluting the fast filesystem path with
  cfg gates.
- `build.rs` — EXISTS today (injects `GIT_HASH`/`GIT_BRANCH` from git).
  Extend with a second block: when the `bundled-assets` feature is
  enabled (`env::var("CARGO_FEATURE_BUNDLED_ASSETS").is_ok()`),
  check that repo-root `static-dist/` exists and contains at least
  `index.html`. Emit a clear compile error pointing at
  `just fe-build` / `(cd frontend && npm run build)` if missing.
  Also emit `cargo:rerun-if-changed=static-dist/` so a rebuild of
  the frontend re-triggers rust-embed's compile-time embed step.
- `.cargo/config.toml` — NO CHANGES. The dev-preserving default of
  `-C target-cpu=native` stays. Release CI overrides via per-job
  `RUSTFLAGS` env var, per the load-smoke.yml precedent.
- `.github/workflows/release-binaries.yml` — NEW: three-stage pipeline.
- `justfile` — thread `--features dev_tools` into the `openapi` recipe.
- `tests/api/run.sh` — thread `--features test_utils` into the two
  hurl-helper build lines.
- `docs/install/binary.md` — NEW: user-facing installation guide.

## Verification

1. **Local squash check**: after Cargo.toml + `src/cli/` edits, run
   `cargo build --release --bins` and confirm exactly ONE binary
   appears in `target/release/` (`oxicloud`). Run `cargo build --release
   --bins --features test_utils` and confirm the two hurl helpers
   appear. `cargo build --release --bins --features dev_tools`
   should surface `generate-openapi`. Confirm subcommand shape via:
   - `target/release/oxicloud --help` — shows `opaque` + `migrate`
     domains
   - `target/release/oxicloud opaque setup` — prints a fresh
     ServerSetup base64 line (unchanged behaviour vs the old
     `oxicloud-cli opaque setup`)
   - `target/release/oxicloud migrate nfc-filenames --dry-run`
     (against a sandbox DB) — same behaviour as the old
     `migrate-nfc-filenames --dry-run`
   - `target/release/oxicloud` (no args) — starts the server exactly
     as today, no clap-related output surprises before the server
     init banner.

2. **Local bundled-assets smoke**:
   ```
   (cd frontend && npm ci && npm run build)     # writes ../static-dist/
   cargo build --release --features bundled-assets --bin oxicloud
   # Wipe static-dist/ or point OXICLOUD_STATIC_PATH somewhere
   # nonexistent to force the embedded path to be exercised.
   mv static-dist/ static-dist.hidden/
   OXICLOUD_STATIC_PATH=/tmp/nonexistent DATABASE_URL=... target/release/oxicloud
   # Hit http://localhost:8086 — SPA shell + locales must load.
   # Restore afterward: mv static-dist.hidden/ static-dist/
   ```

3. **Filesystem fallback still works in bundled build**: with the
   same binary, point `OXICLOUD_STATIC_PATH` at a real static-dist,
   confirm files served from disk (change a file, no rebuild → change
   visible in browser). Verifies the precedence rule from Deliverable 2.

4. **Non-bundled build still works**: `cargo build --release`
   (without `--features bundled-assets`) → binary boots + serves from
   `./static/static-dist/` as today. Zero regression on the Docker
   image path.

5. **CI dry-run**: dispatch `release-binaries.yml` with `dry_run: true`
   from a fork. Confirms all four matrix entries build successfully,
   tarballs land in the run's artifact list, no release is created.

6. **Manual extraction test**: download one tarball, extract, run
   `./oxicloud` with just `DATABASE_URL` set (against a local
   Postgres). Log in, upload a file, check that locale switching
   works, confirm `/api/status` returns healthy. Then repeat on a Pi 5
   for the `aarch64-unknown-linux-musl` variant if convenient.

## Not in scope

- **Windows target** — separate work when demand appears.
- **glibc Linux tarballs** — musl covers the Linux audience per the
  design shape above; users wanting glibc-specific features
  (`faces-onnx`) build from source.
- **32-bit ARM (`armv7`)** — hardware below the workload floor.
- **Debian/RPM packages** — post-tarball layer, adds repo-hosting burden.
- **Homebrew tap** — trivial once tarballs exist; separate decision.
- **Signing (Sigstore/GPG)** — worth adding but scope-creeping;
  SHA256SUMS is the minimum table stakes for this PR.

## Delivery order

1. **Feature-flag squash** (Deliverable 1). Cargo.toml edits +
   `just openapi` / `tests/api/run.sh` invocation fixes. Verify
   `cargo build --release --bins` no longer builds hurl helpers.
2. **Merge migrate-nfc-filenames into oxicloud-cli** (Deliverable 1a).
   Move logic to `mod migrate` submodule. Delete standalone bin.
   Verify `oxicloud-cli migrate nfc-filenames --dry-run` works.
3. **Merge oxicloud-cli into oxicloud** (Deliverable 1b). Move
   `src/bin/oxicloud-cli.rs` contents into new `src/cli/` module,
   wire clap into `main.rs` with implicit-server default. Delete
   `src/bin/oxicloud-cli.rs`. Verify `oxicloud` (no args) still
   starts the server; `oxicloud opaque setup` + `oxicloud migrate
   nfc-filenames --dry-run` work.
4. **Add `bundled-assets` feature** (Deliverable 2). `rust-embed` +
   `build.rs` guard + `src/interfaces/web/embedded.rs` + locale
   loader alt + CSP scan alt. Verify locally with the smoke sequence
   in Verification §2.
5. **Add `.github/workflows/release-binaries.yml`** (Deliverable 5).
   Dry-run on a fork. Iterate until all 4 targets green.
6. **Write docs** (Deliverable 6) — `docs/install/binary.md`. Prose
   only, no snippets that will rot. Include the
   `OXICLOUD_ENABLE_VIDEO_THUMBNAILS=false` callout for tarball users
   without ffmpeg.
7. **Add `[package.metadata.binstall]` block** (Deliverable 7).
   One-line change enabling `cargo binstall oxicloud`.
8. **Fix the `OXICLOUD_ENABLE_VIDEO_THUMBNAILS` doc gap** — add to
   `example.env` + `docs/env.md` per memory
   `bug_env_docs_video_thumbnails_missing`. Small companion edit
   surfaced by the binary-install docs work.
9. **Cut a test tag** (`v0.9.0-rc1`?) on a fork with
   `vars.ENABLE_BINARY_RELEASE=true`. Confirm tarballs attach to the
   Release, SHA256SUMS present, `cargo binstall oxicloud` works.
10. **When happy, cut on canonical.**

Total scope: ~2.5 days of careful work.
- Deliverables 1 + 1a + 1b: ~5 hours mechanical (Cargo config, CLI
  merge, subcommand tree)
- Deliverable 2: ~1 day — the only piece with real design surface
  (embed swap, four cfg sites, locale + CSP loaders)
- Deliverable 5: ~4 hours workflow authoring + iteration
- Deliverables 6-8: ~4 hours docs + small edits
- Verification + iteration: ~4 hours