Flow Mesh — Distribution Grid

How to get Flow Mesh into other people's hands.


Binary Facts

Property Value
Language Go (pure, no CGO)
Binary size (stripped) ~13 MB
Platforms linux/darwin/windows × amd64/arm64 (6 targets)
Dependencies at runtime None (SQLite embedded via modernc.org) — see Beads Dependency below
Linux release binary Fully static (musl), no glibc floor — verified running on glibc 2.28 (2026-09-26)
Min Go version to build 1.23+ (no post-1.21 language features used)
Config config.yaml + env vars
Data Single SQLite file (WAL mode)
Ports 127.0.0.1:8300 (default, loopback only)

Authentication

Built-in multi-user auth with bcrypt password hashing and HMAC-signed session cookies.

Environment Variables

Variable Required Description
FLOW_MESH_AUTH No on / off — force auth state. Default: smart detection
FLOW_MESH_USER No Bootstrap username (upserted into DB on startup)
FLOW_MESH_PASS No Bootstrap password (upserted into DB on startup)

Smart Activation (default behavior)

Listen Address Auth Active Reason
127.0.0.1:8300 No Loopback only — safe
localhost:8300 No Loopback only — safe
0.0.0.0:8300 Yes Network-exposed
Any + FLOW_MESH_AUTH=on Yes Explicit override (use with CF tunnel)

Credential Sources (priority order)

  1. Env vars: FLOW_MESH_USER + FLOW_MESH_PASS → upserts bcrypt hash into DB on every startup
  2. DB kv table: auth_user:<username> → bcrypt hash (created via wizard or env vars)
  3. First-run wizard: If no users exist, /login shows "Create Account" form

Session Cookies

  • Format: username|timestamp|HMAC-SHA256-signature
  • Signing key: 32-byte random, auto-generated on first run, stored in DB kv table (auth_hmac_secret)
  • TTL: 7 days
  • Flags: HttpOnly, SameSite=Lax, Path=/
  • No server-side session state: validation is pure HMAC check (stateless)

Exempt Paths

Path Reason
/login Login page itself
/logout Cookie clear + redirect
/api/health Health checks (monitoring, load balancers)
/webhooks/* Asana webhook delivery (uses own auth)

Per-Deployment Configuration

Deployment Auth Setup
Docker environment: [FLOW_MESH_AUTH=on, FLOW_MESH_USER=admin, FLOW_MESH_PASS=...]
systemd Environment="FLOW_MESH_AUTH=on" + Environment="FLOW_MESH_USER=..."
Tauri desktop First-run wizard (loopback, auth optional)
Behind CF/nginx FLOW_MESH_AUTH=on (exposed via tunnel)
Local dev No config needed (loopback auto-disables auth)

Multi-User Support

  • Users stored as auth_user:<username> in kv table
  • Add users via env vars (one at startup) or future admin UI
  • Each session cookie identifies the user (X-Auth-User header set for downstream)
  • User management API planned for Settings page

Invisible Dependency: Beads (bd)

Flow Mesh's "source" layer has a silent contract:

  • Reading .beads/ directories works with no external tool — Flow Mesh scans the filesystem directly, polls for event changes, and ingests them into the ledger.
  • Writing beads (creating issues, closing tasks, adding comments) requires bd — a separate Go binary that must be independently installed.

A new user can install Flow Mesh, connect Asana, connect Discord, discover repos... and the source layer is half-broken unless they also have bd. Nothing in the current setup wizard warns about this. The README doesn't list it as a prerequisite.

Options

Approach Pros Cons
Bundle bd in the mesh binary Single binary, zero extra installs Couples release cycles; bd is its own project
mesh bd subcommand Self-contained; users learn one tool Not implemented. bd is a separate binary today; offering a pass-through is an option, not a feature
Document as prerequisite Honest, simple Two install steps; friction for new users
Make beads optional Source provider works for git-only repos; Asana↔Discord sync still works without beads Loses the local event layer; "beads" is in the product name
Auto-detect and prompt Setup wizard checks which bd, shows install link if missing Polite but doesn't solve the underlying dependency
Provider declares deps Clean architecture — git-beads provider says "needs bd ≥ v1.0", git-plain provider has no such requirement Requires hook/provider system (see docs/HOOKS.md)

Recommendation

Short term: auto-detect + prompt in the setup wizard. The /setup page already checks Asana/Discord connectivity — add a bd check too. Show install instructions when missing.

Long term: provider declares deps. When the hook system exists, the git-beads source provider declares bd as a dependency. A git-plain provider works without it. The Tauri desktop app (see below) can bundle bd alongside mesh in the app bundle.

Impact on Distribution Channels

Channel Beads Impact
GitHub Releases Document bd as optional prerequisite in release notes
Docker Bundle bd in the container image (add to Dockerfile)
npm wrapper Include bd binary alongside mesh in platform packages
Tauri app Bundle in .app/Contents/Resources/
Homebrew Add depends_on "beads" or bundle

Distribution Channels

Tier 1 — Do First

0. flowme.sh direct download (LIVE since 2026-09-26)

Effort Done — tarball served from WordPress uploads, 301 redirect in place
Reach Any developer with a browser; linked from the site's Download CTAs and install terminal
Prerequisites None for the visitor (repo stays private; no GitHub account needed)
User experience curl + tar + run

Live layout (verified 2026-11-01):

  • https://flowme.sh/mesh.tgz → 301 → /wp-content/uploads/mesh.tgz (13.8 MB)
  • Tarball contains flow-mesh/mesh-linux-amd64, flow-mesh/mesh-darwin-arm64, flow-mesh/checksums.txt, and README.txt with quick-start + license activation
  • The binaries are the published release artifacts for 1.0.0, not a separate build: mesh-linux-amd64 prints flow-mesh 1.0.0 and its digest matches the release tarball
  • https://flowme.sh/install.sh serves the installer described below
  • Theme source of record: landing/wp-theme/flowmesh/ (Gutenberg block theme, mobile-first, visually verified at 395 / 760 / 1024 / 1440 px)

User install (matches the on-site terminal):

curl -fsSL https://flowme.sh/install.sh | sh
mesh config init && mesh serve
# → http://localhost:8300 — setup wizard connects Asana + Discord

The previous on-site one-liner (curl -LO .../mesh.tgz && tar xzf mesh.tgz && ./mesh serve) never worked: the archive's binary lives under flow-mesh/, and ./mesh did not exist. The download now carries checksums.txt so a hand-extracted copy can be verified with sha256sum -c flow-mesh/checksums.txt.

The pre-1.0.0 tarball is preserved at mesh.tgz.rollback-20261101-dev in the same uploads directory; its binaries reported flow-mesh dev, which is why it was replaced.

Static rebuild recipe (still valid if a musl-only deployment is needed): CGO_ENABLED=1 CC=musl-gcc go build -ldflags "-linkmode external -extldflags -static" ./cmd/mesh

1. GitHub Releases (goreleaser)

Effort ~30 min
Reach Any developer on any OS
Prerequisites Tag a version, goreleaser installed or use GitHub Actions
User experience curl + tar + run

Prove the matrix before a tag exists. A tag is the one release step that cannot be quietly undone, so the six targets are built and recorded first:

./scripts/release-proof.sh           # builds all six, writes deploy/release/release-proof.v1.json
./scripts/release-proof.sh --check   # fails if the proof and VERSION/matrix disagree

Verified 2026-11-01 from canonical source at version 1.0.0: all six targets build, each carries the stamp, and the native linux/amd64 binary reports flow-mesh 1.0.0 when executed. Digests and sizes are recorded per target in the proof file, which also names what it did not establish — archive assembly, SBOM emission and checksum-file naming — because goreleaser is not installed on the build host. Those steps are configured, not exercised.

Setup:

# Tagging publishes to the canonical repository (private).
git tag v1.0.0
git push --tags

# .github/workflows/release.yml runs goreleaser on tag push.
# Local alternative, if goreleaser is installed:
goreleaser release --clean

User install:

# Linux amd64 (asset name template: flow-mesh_<version>_<os>_<arch>)
curl -Lo flow-mesh.tar.gz \
  https://github.com/Startempire-Wire/flow-mesh/releases/latest/download/flow-mesh_1.0.0_linux_amd64.tar.gz
tar xzf flow-mesh.tar.gz
sudo mv mesh /usr/local/bin/
mesh config init
mesh serve

Install script — verbs, state, and verification

curl -fsSL https://flowme.sh/install.sh | sh                  # install (default verb)
curl -fsSL https://flowme.sh/install.sh | sh -s -- upgrade    # newer release
curl -fsSL https://flowme.sh/install.sh | sh -s -- rollback   # back to the previous one
curl -fsSL https://flowme.sh/install.sh | sh -s -- status     # what is installed, from the manifest
curl -fsSL https://flowme.sh/install.sh | sh -s -- uninstall  # remove the command and version store

Two channels, because the product surface and the source repository are different things. FLOW_MESH_CHANNEL=public (default) fetches the flowme.sh bundle, which carries the two platforms the site advertises. FLOW_MESH_CHANNEL=github resolves the published release through the API with GITHUB_TOKEN and covers the platforms the bundle omits (linux/arm64, darwin/amd64, windows/amd64, windows/arm64). A platform the chosen channel does not serve is named explicitly rather than downloaded and left to fail at exec time.

Every path verifies a digest. The public bundle carries checksums.txt inside the archive, so the list and the payload arrive together; the github channel fetches the release's published checksums.txt. An installer that runs an unverified download is a supply-chain hole, not a convenience.

Layout and rerun safety:

Command ${INSTALL_DIR}/mesh (default /usr/local/bin/mesh) — a symlink
Version store ${FLOW_MESH_STATE_DIR:-~/.local/state/flow-mesh}/versions/<version>/mesh
Manifest .../flow-mesh/install.json — version, previous, channel, asset, digest, paths, time
Data platform data dir (~/.local/share/flow-mesh on Linux, ~/Library/Application Support/flow-mesh on macOS), FLOW_MESH_DATA_DIR to relocate
Config ./config.yaml relative to where mesh runs, FLOW_MESH_CONFIG to relocate

Versions are kept side by side and the command is a symlink into that store, so upgrade and rollback are pointer swaps rather than overwrites, and rollback is itself reversible (the manifest swaps version and previous). Rerunning the same version re-verifies the installed digest and changes nothing; if the installed binary no longer matches, it says so and points at upgrade instead of silently re-downloading. uninstall removes the command and the version store and names the data directory and config it deliberately left alone — an uninstall that deletes a database is a foot-gun, not a feature.

FLOW_MESH_BUNDLE_FILE=<path> stages a local bundle for offline installs; the digest check still runs, so it is not a bypass.

Proven by internal/e2e/installer_lifecycle_test.go, which drives the verbs: install, rerun-is-a-no-op, upgrade keeps both versions, rollback returns to the previous and records the swap, uninstall removes the command and store while naming what it preserved, a tampered bundle is refused with no command left on PATH, rollback with no history refuses and changes nothing, and an unknown verb is refused.

A guard test keeps install.sh's REPO equal to the release owner and name in .goreleaser.yaml, and keeps the asset name derived from version/os/arch, so the one-liner cannot start pointing somewhere the release never publishes.

Status (2026-11-01): published. Tag v1.0.0 (commit 812840e) is live with 14 assets; releases/latest resolves it; flowme.sh/mesh.tgz is rebuilt from those assets and verified end to end through the public installer.

This release could not be built by CI. Every Actions run on the Startempire-Wire organisation fails at workflow startup with BuildFailed and zero jobs, including plain master pushes, so a tag push publishes nothing. The assets were therefore assembled by scripts/release-build.sh from a clean checkout of the tag — the same six targets and archive shape .goreleaser.yaml declares, plus checksums.txt, per-binary module inventories, and release-artifacts.v1.json recording the commit and digests. It records goreleaser_used: false and states that SBOMs are Go module inventories rather than SPDX, because syft is not installed on the build host. The workflow itself is fixed and ready (container namespace, README URL); it will produce the same release once Actions runs again. That is a hosting/billing question for the owner, not a code defect.


2. Docker and Compose

Effort Done — Dockerfile + docker-compose.yml + .env.example
Reach Anyone with Docker or Podman
Prerequisites A container runtime; no account, because the Compose path builds the checkout
User experience copy .env.example, set two secrets, docker compose up -d
cp .env.example .env          # set FM_PASS and FLOW_MESH_SECRET (openssl rand -hex 32)
docker compose up -d
docker compose ps             # wait for (healthy)
curl -s localhost:8300/healthz

What the file guarantees, and why each line is there

Property How Why it matters
Versioned image: ghcr.io/startempire-wire/flow-mesh:${FLOW_MESH_VERSION:-1.0.0} a :latest tag deploys whatever happens to be latest on the day of the rerun
Stamped the same value goes to build.args.VERSION → -X main.version a build context has no .git, so git describe labelled every image dev
Loopback by default "${FLOW_MESH_BIND:-127.0.0.1}:${FLOW_MESH_PORT:-8300}:8300" publishing a service is a decision, not a default
No invented secrets FLOW_MESH_PASS and FLOW_MESH_SECRET use ${VAR:?reason} the stack refuses to start rather than coming up with changeme on a reachable port
Encryptable credentials FLOW_MESH_SECRET required without it the server can store no provider credential and reports every provider unconfigured
No invented providers provider tokens pass through as ${VAR:-} an unset token stays unset and is reported as "not configured"
Real health probe wget --spider 127.0.0.1:8300/healthz probing a path the router does not serve marks a dead container healthy
Durable data named volume at /data, FLOW_MESH_DB=/data/flow-mesh.db a rerun must not lose the database
Hardened runs as the image's non-root mesh user, no-new-privileges

FLOW_MESH_LISTEN=0.0.0.0:8300 inside the container is correct and unrelated to exposure: that is the container's own interface, and the port mapping is what decides who can reach it.

Verified 2026-11-01 from a clean directory on the execution host (archive extract, no .env, no prior images for this project): build → docker compose up -d → Up (healthy) → mesh version prints flow-mesh 1.0.0 → /healthz returns {"status":"ok","encryption":true,"version":"1.0.0"} → listener is 127.0.0.1:8398 only → a second up -d converges to Running without recreating → removing FM_PASS refuses to start with the reason → down -v leaves nothing behind.

internal/e2e/compose_contract_test.go keeps those properties honest: it decodes the file and asserts the namespace, the pinned tag, the version stamp reaching the build, the loopback default, the required-secret form, that no provider token is fabricated, and that the probe path is a route the router actually serves.

The published image is not available yet. GHCR push happens in the Release workflow, which cannot run on this organisation (every Actions run fails at startup with zero jobs). Compose therefore builds the checkout locally, which is why the file keeps build: beside image:. Once Actions runs, docker compose up -d will pull the pinned image instead.


Tier 2 — High Impact, Medium Effort

3. npm Binary Wrapper

Effort ~2 hours
Reach Widest — anyone with Node.js
Prerequisites npm account, platform binary builds
User experience npx flow-mesh serve or npm i -g flow-mesh

Uses the esbuild/turbo pattern: platform-specific optional dependencies.

Package structure:

@flow-mesh/linux-x64/       → contains linux amd64 binary
@flow-mesh/linux-arm64/     → contains linux arm64 binary
@flow-mesh/darwin-x64/      → contains macOS amd64 binary
@flow-mesh/darwin-arm64/    → contains macOS arm64 binary (Apple Silicon)
@flow-mesh/win32-x64/       → contains windows amd64 .exe
flow-mesh/                   → main package, picks correct platform

Main package.json:

{
  "name": "flow-mesh",
  "version": "0.1.0",
  "bin": { "flow-mesh": "bin/flow-mesh", "mesh": "bin/flow-mesh" },
  "optionalDependencies": {
    "@flow-mesh/linux-x64": "0.1.0",
    "@flow-mesh/linux-arm64": "0.1.0",
    "@flow-mesh/darwin-x64": "0.1.0",
    "@flow-mesh/darwin-arm64": "0.1.0",
    "@flow-mesh/win32-x64": "0.1.0"
  }
}

Launcher script (bin/flow-mesh):

#!/usr/bin/env node
const { execFileSync } = require("child_process");
const path = require("path");
const os = require("os");

const PLATFORMS = {
  "linux-x64": "@flow-mesh/linux-x64",
  "linux-arm64": "@flow-mesh/linux-arm64",
  "darwin-x64": "@flow-mesh/darwin-x64",
  "darwin-arm64": "@flow-mesh/darwin-arm64",
  "win32-x64": "@flow-mesh/win32-x64",
};

const key = `${os.platform()}-${os.arch()}`;
const pkg = PLATFORMS[key];
if (!pkg) { console.error(`Unsupported platform: ${key}`); process.exit(1); }

const bin = require.resolve(`${pkg}/mesh${os.platform() === "win32" ? ".exe" : ""}`);
execFileSync(bin, process.argv.slice(2), { stdio: "inherit" });

Pros: Broadest reach, npx just works, agents already have Node.
Cons: 6 packages to maintain, npm publish on every release, ~13MB per platform package.

Automation: Add to goreleaser post-hooks or GitHub Actions release workflow.

Status: Not started. Requires npm org @flow-mesh.


4. Tauri Desktop + Mobile App

Effort ~1–2 weeks
Reach macOS menubar users, iOS, Android
Prerequisites GitHub Releases for the Go binary; Rust toolchain; Xcode (iOS); Android SDK
User experience Native app — double-click install, menubar icon, zero terminal

Tauri 2.0 (stable since Oct 2024) supports macOS, Linux, Windows, iOS, and Android from a single codebase. The frontend is a webview — Flow Mesh's existing htmx UI runs inside it unchanged.

Architecture:

┌──────────────────────────────────────────────────┐
│  Flow Mesh.app  (Tauri 2.0)                       │
│                                                    │
│  ┌────────────┐  ┌─────────────────────────────┐  │
│  │ Rust core  │  │ Webview (system)             │  │
│  │            │  │                              │  │
│  │ • spawn Go │  │  Existing htmx dark UI      │  │
│  │   binary   │  │  pointed at 127.0.0.1:PORT  │  │
│  │ • tray     │  │                              │  │
│  │   icon     │  │  No changes needed —         │  │
│  │ • menu     │  │  same templates, same CSS,   │  │
│  │ • auto-    │  │  same htmx interactions      │  │
│  │   start    │  │                              │  │
│  │ • notify   │  └─────────────────────────────┘  │
│  └─────┬──────┘                                    │
│        │ spawns child process                      │
│  ┌─────▼──────┐                                    │
│  │ mesh serve │  ← Go binary bundled in app        │
│  │ :0 (random)│  ← reports actual port to Rust     │
│  │ + bd       │  ← beads binary also bundled       │
│  └────────────┘                                    │
└──────────────────────────────────────────────────┘

macOS Menubar:

                              ┌──┐
  Menu Bar                    │⬡ │ ← woven flow icon
                              └──┘
                                │
  ┌─────────────────────────────▼───────┐
  │  Flow Mesh                          │
  │  ● 3 meshes active                 │
  │  ● 2 events pending                │
  │  ● Asana ✓  Discord ✓  Beads ✓    │
  │                                     │
  │  ┌───────────────────────────────┐  │
  │  │ Open Dashboard           ⌘D  │  │
  │  │ Pause All Sync           ⌘P  │  │
  │  │ Force Sync Now           ⌘S  │  │
  │  │ ─────────────────────────────│  │
  │  │ Settings...              ⌘,  │  │
  │  │ View Logs...                 │  │
  │  │ ─────────────────────────────│  │
  │  │ Quit                     ⌘Q  │  │
  │  └───────────────────────────────┘  │
  └─────────────────────────────────────┘

What changes in Flow Mesh for Tauri:

Area Change Why
Listen port Support :0 (random port), print actual port to stdout Multiple instances, no port clash
Data dir Respect FLOW_MESH_DATA_DIR → ~/Library/Application Support/Flow Mesh/ (macOS), %APPDATA%\Flow Mesh\ (Windows) Standard OS paths
Shutdown Already done (graceful SIGTERM) Tauri sends SIGTERM on quit
Health /api/health already exists Tauri polls for tray icon status
UI No changes — htmx UI works as-is in a webview That's the whole point
Bundled bins mesh + bd in app resources Solves the beads dependency

Mobile (iOS + Android):

Tauri 2.0 compiles to native mobile apps from the same codebase. The webview renders the existing htmx UI. Key differences for mobile:

Concern Desktop Mobile
Go binary Bundled, runs as child process Cross-compile to arm64, run as background service or embed via gomobile
SQLite File on disk Same — app sandbox storage
Notifications Tray icon + OS notifications Push notifications (Tauri plugin)
Background sync Always running while app open OS-managed background tasks (limited on iOS)
UI Already mobile-first (375px+) Works as-is — that's why we built mobile-first
Distribution .dmg / .msi / .AppImage App Store / Google Play / TestFlight / APK sideload

iOS specifics:

  • Go binary cross-compiles to darwin/arm64 (same target as Apple Silicon Mac)
  • Can use gomobile to produce .framework callable from Swift, or run as embedded subprocess
  • Background App Refresh for sync (limited to ~30s per wake, but sufficient for polling)
  • App Store distribution requires Apple Developer account ($99/yr)

Android specifics:

  • Go binary cross-compiles to linux/arm64 (Android NDK)
  • Can use gomobile to produce .aar callable from Kotlin, or run as foreground service
  • Foreground service keeps sync alive (shows persistent notification)
  • Google Play or direct APK distribution

Tauri project structure:

flow-mesh-app/
  src-tauri/
    src/main.rs          # Rust: spawn mesh binary, tray, menu
    tauri.conf.json      # Window config, bundle settings
    resources/
      mesh               # Go binary (per-platform)
      bd                 # Beads binary (per-platform)
    Cargo.toml
  src/
    index.html           # Just an iframe/redirect to localhost:PORT
                         # Or: proxy through Tauri's asset protocol
  package.json

Build matrix:

Target Build Command Output
macOS (universal) cargo tauri build --target universal-apple-darwin .dmg + .app
Windows cargo tauri build --target x86_64-pc-windows-msvc .msi + .exe
Linux cargo tauri build --target x86_64-unknown-linux-gnu .AppImage + .deb
iOS cargo tauri ios build .ipa (TestFlight/App Store)
Android cargo tauri android build .apk / .aab (Play Store)

Size estimates:

Component Size
Tauri runtime (Rust + system webview) ~2–4 MB
mesh binary (stripped, compressed) ~6 MB
bd binary (stripped, compressed) ~3 MB
Total app ~11–13 MB

Compared to Electron (~150 MB), this is tiny.

Distribution for Tauri builds:

Channel Method
macOS .dmg on GitHub Releases + brew install --cask flow-mesh
Windows .msi on GitHub Releases + winget manifest
Linux .AppImage + .deb on GitHub Releases
iOS TestFlight → App Store
Android GitHub Releases .apk + Google Play

Status: Not started. Requires Tauri project scaffold + Go cross-compilation CI.


5. go install (Public Repo)

Effort 5 min (flip repo visibility)
Reach Go developers
Prerequisites Make repo public
User experience go install github.com/Startempire-Wire/flow-mesh/cmd/mesh@latest

Decided (owner, 2026-09-26): repo stays private and closed-source — this channel is closed. Distribution runs through flowme.sh direct download (§0) and licensed binaries, which need no GitHub account and no GOPRIVATE.

Status: Closed. Reopen only on explicit owner direction.


Tier 3 — Polish

6. Homebrew Tap

Effort ~1 hour
Reach macOS + Linux Homebrew users
Prerequisites GitHub Releases (Tier 1)
User experience brew install startempire-wire/tap/flow-mesh

Setup:

# Create repo: github.com/Startempire-Wire/homebrew-tap
# Add formula:

Formula (Formula/flow-mesh.rb):

class FlowMesh < Formula
  desc "Bidirectional Asana ⇄ Beads ⇄ Discord sync engine"
  homepage "https://flowme.sh"
  version "0.1.0"

  on_macos do
    on_arm do
      url "https://github.com/Startempire-Wire/flow-mesh/releases/download/v0.1.0/flow-mesh_0.1.0_darwin_arm64.tar.gz"
      sha256 "PLACEHOLDER"
    end
    on_intel do
      url "https://github.com/Startempire-Wire/flow-mesh/releases/download/v0.1.0/flow-mesh_0.1.0_darwin_amd64.tar.gz"
      sha256 "PLACEHOLDER"
    end
  end

  on_linux do
    on_arm do
      url "https://github.com/Startempire-Wire/flow-mesh/releases/download/v0.1.0/flow-mesh_0.1.0_linux_arm64.tar.gz"
      sha256 "PLACEHOLDER"
    end
    on_intel do
      url "https://github.com/Startempire-Wire/flow-mesh/releases/download/v0.1.0/flow-mesh_0.1.0_linux_amd64.tar.gz"
      sha256 "PLACEHOLDER"
    end
  end

  def install
    bin.install "mesh"
  end

  test do
    assert_match "flow-mesh", shell_output("#{bin}/mesh version")
  end
end

Can automate once the tap exists. goreleaser's brews block is currently commented out in .goreleaser.yaml: it pointed at Philoveracity/homebrew-tap, a repository under the redirecting owner that the canonical release cannot write to. Creating Startempire-Wire/homebrew-tap is a new remote repository and needs explicit owner authorization, so the block stays disabled and this channel stays honestly "not started" rather than publishing to the wrong owner. The intended configuration, for when the tap exists:

brews:
  - repository:
      owner: Startempire-Wire
      name: homebrew-tap
    homepage: https://flowme.sh
    description: "Bidirectional Asana ⇄ Beads ⇄ Discord sync engine"

Status: Not started. Depends on Tier 1.


7. Install Script

Effort ~30 min
Reach curl-pipe-sh crowd
Prerequisites GitHub Releases (Tier 1)
User experience curl -fsSL .../install.sh | sh

Script auto-detects OS/arch, downloads correct binary, installs to /usr/local/bin.

Status: Not started. Depends on Tier 1.


CI/CD Pipeline

Everything above triggers from one action: push a git tag.

git tag v0.1.0 && git push --tags
          │
          ▼
┌─────────────────────────────────┐
│  GitHub Actions Release Workflow │
├─────────────────────────────────┤
│                                 │
│  1. goreleaser build            │
│     → 6 binaries (tar.gz/zip)  │
│     → GitHub Release + assets  │
│     → checksums.txt             │
│                                 │
│  2. Docker build + push         │
│     → ghcr.io/startempire-wire/ │
│       flow-mesh:v1.0.0          │
│     → ghcr.io/startempire-wire/ │
│       flow-mesh:latest          │
│                                 │
│  3. Homebrew tap update         │
│     → auto-PR to homebrew-tap   │
│                                 │
│  4. npm publish (optional)      │
│     → 5 platform packages       │
│     → 1 main package            │
│                                 │
│  5. Tauri builds (separate CI)  │
│     → .dmg (macOS universal)    │
│     → .msi (Windows x64)       │
│     → .AppImage/.deb (Linux)   │
│     → .ipa (iOS TestFlight)    │
│     → .apk (Android)           │
│                                 │
└─────────────────────────────────┘

Workflow file needed: .github/workflows/release.yml


Week 1:  Tag v0.1.0 → GitHub Releases + Docker (GHCR)
         ↳ Covers: curl install, docker run, docker compose
         ↳ Effort: ~1 hour including CI workflow

Week 2:  Homebrew tap + install script + npm wrapper
         ↳ Covers: brew install, curl | sh, npx flow-mesh serve
         ↳ Effort: ~3 hours

Week 3–4: Tauri desktop app (macOS menubar first)
         ↳ Covers: .dmg, menubar icon, zero-terminal experience
         ↳ Effort: ~1 week (scaffold + cross-compile CI + test)

Week 5:  Tauri mobile (iOS + Android)
         ↳ Covers: TestFlight, APK, eventually App Store + Play Store
         ↳ Effort: ~1 week (gomobile integration + mobile-specific testing)

Ongoing: go install (when/if repo goes public)

Why Tauri Before npm

The Tauri app is higher priority than the npm wrapper because:

  1. Mac users are the primary audience — developers on MacBooks want a menubar app
  2. Mobile unlocks a new user class — check mesh status from your phone
  3. Solves the beads dependency — bundle bd in the app, no extra install
  4. One codebase → 5 platforms — macOS, Windows, Linux, iOS, Android
  5. npm wrapper serves developers who already have a terminal — they can use GitHub Releases just fine

Pre-Release Checklist

Week 1: Core Release

  • [ ] Lower go.mod to go 1.23 (wider compatibility, no 1.25 features used)
  • [ ] Add bd version check to setup wizard (invisible dependency fix)
  • [ ] Add mesh serve --port 0 support (random port, print to stdout — needed for Tauri)
  • [ ] Add FLOW_MESH_DATA_DIR env var support (OS-appropriate paths)
  • [ ] Tag v0.1.0
  • [ ] Create .github/workflows/release.yml
  • [ ] Test Docker build locally: docker build -t flow-mesh . (include bd in image)
  • [ ] Test goreleaser dry-run: goreleaser release --snapshot --clean
  • [x] Decide: public or private repo? — Decided 2026-09-26: private, closed-source per owner
  • [ ] Write install.sh auto-detect script
  • [ ] Create docker-compose.yml example in repo root

Week 2: Package Managers

  • [ ] If npm: register @flow-mesh org on npmjs.com
  • [ ] Create Startempire-Wire/homebrew-tap repo
  • [ ] Add goreleaser Homebrew tap config
  • [ ] Test brew install startempire-wire/tap/flow-mesh

Week 3–4: Tauri Desktop

  • [ ] Scaffold Tauri project (flow-mesh-app/ directory or separate repo)
  • [ ] Rust sidecar: spawn mesh serve --port 0, capture port from stdout
  • [ ] Tray icon + menu (Open Dashboard, Pause, Force Sync, Quit)
  • [ ] Health polling → tray icon color (green/amber/red)
  • [ ] Bundle mesh + bd binaries in app resources
  • [ ] macOS: .dmg build + test on Apple Silicon
  • [ ] macOS: auto-start on login (Login Items)
  • [ ] brew install --cask flow-mesh formula
  • [ ] Windows: .msi build + test
  • [ ] Linux: .AppImage + .deb build + test

Week 5: Tauri Mobile

  • [ ] Cross-compile Go to darwin/arm64 (iOS) and linux/arm64 (Android NDK)
  • [ ] Evaluate: gomobile framework vs embedded subprocess
  • [ ] iOS: background sync strategy (Background App Refresh)
  • [ ] Android: foreground service for persistent sync
  • [ ] iOS: TestFlight build + internal testing
  • [ ] Android: APK build + sideload testing
  • [ ] Apple Developer account ($99/yr) if pursuing App Store
  • [ ] Google Play Developer account ($25 one-time) if pursuing Play Store

Release rollback

A release is reversible at three layers, in increasing blast radius. Roll back only as far as the fault requires, and verify the installed version after each step.

1. Reinstall the previous version (default). The installer is version-pinned and leaves the data directory alone:

curl -fsSL https://flowme.sh/install.sh | VERSION=1.0.0 sh
mesh version

Binaries are replaced atomically per target, so an interrupted reinstall leaves either the old or the new binary, never a partial file. The database schema is forward-migrated; see layer 3 before downgrading across a schema change.

2. Restore the previous binary from a preserved copy. A deployment that keeps its own rollback copy (the reference deployment keeps the prior binary beside the service) can swap back without network access:

systemctl stop flow-mesh
cp /path/to/mesh.previous /usr/local/bin/mesh
systemctl start flow-mesh
curl -fsS http://127.0.0.1:8300/healthz

3. Restore data (only when the schema moved). Downgrading a binary against a newer schema is unsupported. Restore the database and configuration from the encrypted backup taken before the upgrade, using the isolated restore drill first so the restore itself is proven:

deploy/backup/restore-drill.sh --archive <backup> --key <passphrase-file> --parent /tmp/drill

The drill refuses protected production paths and reports production_mutated: false. Promote a drilled restore only after it reports database_integrity: ok and content_hashes: verified.

Order matters: verify assets before trusting a release, verify the installed version after installing, and verify the restore before replacing production.

Generated from the Flow Mesh repository by scripts/build-docs-site.sh. If a page is wrong here, the file it was rendered from is wrong.