ruby_everywhere 0.5.0 → 0.7.0

data/lib/everywhere/platform/snapshot.rb

@@ -4,6 +4,7 @@ require "rubygems/package"
 require "zlib"
 require "digest"
 require_relative "../ignore"
+require_relative "../ui"
 
 module Everywhere
   module Platform
@@ -38,10 +39,19 @@ module Everywhere
 
       def add(tar, root, rel)
         abs = File.join(root, rel)
+        # lstat first: File.stat follows the link, so a dangling symlink (a
+        # deleted bundle path, a checked-in link to an absent sibling repo)
+        # would raise Errno::ENOENT and abort the whole snapshot.
+        return Everywhere::UI.warn("skipping dangling symlink #{rel}") if File.lstat(abs).symlink? && !File.exist?(abs)
+
         stat = File.stat(abs)
         tar.add_file_simple(rel, stat.mode & 0o777, stat.size) do |io|
           File.open(abs, "rb") { |f| IO.copy_stream(f, io) }
         end
+      rescue Errno::ENOENT, Errno::EACCES => e
+        # The listing is a snapshot in time; a dev server or watcher can delete a
+        # tmp/ file between the glob and here. Losing it beats losing the build.
+        Everywhere::UI.warn("skipping #{rel} (#{e.class.name.split("::").last})")
       end
     end
   end

data/lib/everywhere/receipt.rb

@@ -5,6 +5,7 @@ require "digest"
 require_relative "version"
 require_relative "shellout"
 require_relative "ignore"
+require_relative "paths"
 
 module Everywhere
   # Builds the machine-readable build receipt (release.json) — the same shape
@@ -22,14 +23,20 @@ module Everywhere
   class Receipt
     SCHEMA = 1
 
-    def initialize(root:, config:, framework:, ruby:, target:, channel:, shell_dir: nil)
+    # source_checksum/lockfile_checksum are optional so a caller building one
+    # receipt per target hashes the tree ONCE and threads the digest through the
+    # rest — they describe the source, which is identical for every target.
+    def initialize(root:, config:, framework:, ruby:, target:, channel:, shell_dir: nil,
+                   source_checksum: nil, lockfile_checksum: nil)
       @root = File.expand_path(root)
       @config = config
       @framework = framework
       @ruby = ruby
-      @target_str = target                     # raw "os-arch" — selects platforms: overrides
+      @target_str = target                     # bare "os-arch" — selects platforms: overrides
       @target = parse_target(target, channel)
       @shell_dir = shell_dir
+      @source_checksum = source_checksum
+      @lockfile_checksum = lockfile_checksum
     end
 
     # The deterministic build request.
@@ -48,7 +55,9 @@ module Everywhere
           "lockfile_checksum" => lockfile_checksum
         },
         "target" => @target,
-        "permissions" => @config.permissions
+        "permissions" => @config.permissions,
+        "mode" => @config.mode,
+        "remote" => { "url" => @config.remote_url }.compact
       }
     end
 
@@ -105,10 +114,15 @@ module Everywhere
         "cli" => Everywhere::VERSION,
         "bridge" => bridge_version,
         "shell" => shell_version,
-        "tebako" => tebako_version
+        # Only macOS targets are tebako-pressed; spawning rbe-tebako for a
+        # mobile receipt would cost a process to learn nothing.
+        "tebako" => macos? ? tebako_version : nil,
+        "hotwire_native" => hotwire_native_version
       }
     end
 
+    def macos? = @target["os"] == "macos"
+
     def bridge_version
       # Package installs: read the version straight from package.json.
       [
@@ -145,11 +159,40 @@ module Everywhere
       out[/version\s+([\d.]+)/i, 1]
     end
 
+    # Which Hotwire Native the bundled mobile template pins. Read straight off
+    # the frozen templates in the gem (no spawn): iOS from the SPM lockfile,
+    # Android from the Gradle dependency line. Best-effort — a receipt is worth
+    # writing even when the template is missing or reshaped.
+    def hotwire_native_version
+      case @target["os"]
+      when "ios"     then hotwire_native_ios_revision
+      when "android" then hotwire_native_android_version
+      end
+    end
+
+    def hotwire_native_ios_revision
+      dir = Paths.ios_dir or return nil
+      resolved = File.join(dir, "App.xcodeproj", "project.xcworkspace", "xcshareddata", "swiftpm", "Package.resolved")
+      pin = JSON.parse(File.read(resolved))["pins"].find { |p| p["identity"].to_s.include?("hotwire-native-ios") }
+      pin&.dig("state", "revision")&.slice(0, 12)
+    rescue StandardError
+      nil
+    end
+
+    def hotwire_native_android_version
+      dir = Paths.android_dir or return nil
+      File.read(File.join(dir, "app", "build.gradle.kts"))[/dev\.hotwire:core:([\d.]+)/, 1]
+    rescue StandardError
+      nil
+    end
+
     # ---- checksums -----------------------------------------------------------
 
     def lockfile_checksum
-      lock = File.join(@root, "Gemfile.lock")
-      File.exist?(lock) ? "sha256:#{Digest::SHA256.file(lock).hexdigest}" : nil
+      @lockfile_checksum ||= begin
+        lock = File.join(@root, "Gemfile.lock")
+        File.exist?(lock) ? "sha256:#{Digest::SHA256.file(lock).hexdigest}" : nil
+      end
     end
 
     def lockfile_gem_version(gem_name)
@@ -164,11 +207,13 @@ module Everywhere
     # Uses the SAME ignore rules as the (future) snapshot, so the checksum
     # describes exactly what ships.
     def source_checksum
-      digest = Digest::SHA256.new
-      Ignore.for(@root).files(@root).each do |rel|
-        digest << rel << "\0" << Digest::SHA256.file(File.join(@root, rel)).hexdigest << "\n"
+      @source_checksum ||= begin
+        digest = Digest::SHA256.new
+        Ignore.for(@root).files(@root).each do |rel|
+          digest << rel << "\0" << Digest::SHA256.file(File.join(@root, rel)).hexdigest << "\n"
+        end
+        "sha256:#{digest.hexdigest}"
       end
-      "sha256:#{digest.hexdigest}"
     end
 
     # ---- helpers -------------------------------------------------------------

data/lib/everywhere/shellout.rb

@@ -40,9 +40,27 @@ module Everywhere
 
     def run!(env, *cmd, chdir: Dir.pwd)
       success = system(child_env(env), *cmd, chdir: chdir)
+      # nil means the command never ran (missing binary), false that it failed.
+      UI.die!("#{cmd.first} not found — is it installed and on your PATH?") if success.nil?
       UI.die!("command failed: #{cmd.join(" ")}") unless success
     end
 
+    # Whether `name` resolves as an executable on the PATH children get (the
+    # unbundled one — a Bundler binstub visible to the CLI doesn't count).
+    def tool?(name)
+      return File.executable?(name) && !File.directory?(name) if name.include?("/")
+
+      path = (unbundled_base["PATH"] || ENV["PATH"]).to_s
+      exts = Gem.win_platform? ? [".exe", ".bat", ".cmd", ""] : [""]
+      path.split(File::PATH_SEPARATOR).any? do |dir|
+        exts.any? { |ext| File.executable?(File.join(dir, name + ext)) && !File.directory?(File.join(dir, name + ext)) }
+      end
+    end
+
+    def ensure_tool!(name, hint)
+      tool?(name) or UI.die!("#{name} not found — #{hint}")
+    end
+
     # quiet also detaches stdin. A quiet command is by definition one that has
     # nothing to say to the terminal, and `every dev` reads single keystrokes
     # from that same terminal — a child left holding stdin silently eats the
@@ -78,6 +96,7 @@ module Everywhere
     # ChildProcesses instead.
     def run_logged!(env, cmd, log:, filter: nil)
       require "open3"
+      ensure_tool!(cmd.first, "is it installed and on your PATH?")
       success = false
       File.open(log, "w") do |logf|
         # Inside an `every dev` worker the build leads its own process group,

data/lib/everywhere/simulator.rb

@@ -56,11 +56,22 @@ module Everywhere
       out, status = Shellout.capture("xcrun", "simctl", "list", "devices", "available", "-j")
       return [] unless status&.success?
 
-      JSON.parse(out).fetch("devices", {}).sort.flat_map { |_runtime, list| list }
+      JSON.parse(out).fetch("devices", {})
+          .sort_by { |runtime, _list| runtime_order(runtime) }
+          .flat_map { |_runtime, list| list }
     rescue JSON::ParserError
       []
     end
 
+    # Runtimes are keyed by identifier ("com.apple.CoreSimulator.SimRuntime.iOS-17-0"),
+    # so a plain string sort puts iOS-9-3 AFTER iOS-17-0 and "newest last" hands
+    # back the oldest runtime installed. Compare the version numerically, with
+    # the family (iOS/watchOS/…) as the primary key so the grouping is stable.
+    def runtime_order(runtime)
+      family, *version = runtime.to_s.split(".").last.to_s.split("-")
+      [family.to_s.downcase, version.map(&:to_i)]
+    end
+
     def wait_until_booted(udid, timeout: 60)
       deadline = Time.now + timeout
       until Time.now > deadline

data/lib/everywhere/version.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Everywhere
-  VERSION = "0.5.0"
+  VERSION = "0.7.0"
 
   # Version of the @rubyeverywhere/bridge JS this gem ships. bridge/ in the
   # gem IS the npm package (served to Rails apps by Everywhere::Engine,

data/support/agents/AGENTS.md

@@ -0,0 +1,90 @@
+## RubyEverywhere
+
+This is a {{FRAMEWORK}} app that also ships as a native desktop and mobile app, via the
+[`ruby_everywhere`](https://rubyeverywhere.com) gem. The desktop shell is Tauri, the mobile
+shells are Hotwire Native, and all three are driven from one config file
+(`config/everywhere.yml`), one CLI (`every`, aliased `rbe`), and one JavaScript API
+(`Everywhere`) with server-side helpers to match.
+
+**The web app is the source of truth.** You do not edit the shells — you edit the app, its
+views, and the config. Full docs: <https://rubyeverywhere.com/docs>.
+
+### How this app reaches its users: {{MODE}} mode
+
+{{MODE_NOTES}}
+
+{{FRAMEWORK_VIEWS}}
+
+### config/everywhere.yml
+
+Everything native is declared here: tabs, path rules, permissions, window chrome, menus,
+tray items, colors, deep links, auto-updates. Top-level keys: `app`, `remote`, `appearance`,
+`tabs`, `rules`, `permissions`, `menu`, `tray`, `window`, `native`, `auth`, `deep_linking`,
+`build`, `updates`, `platforms`. Full reference:
+<https://rubyeverywhere.com/docs/shared/everywhere-yml>.
+
+Things that bite:
+
+- **`app.bundle_id` is identity, not cosmetics.** It names the app-data directory on every
+  platform (and the macOS bundle id). Renaming it orphans users' local data and settings.
+- **Permissions gate everything on mobile.** A permission that isn't declared under
+  `permissions:` resolves to `undeclared` and never prompts. `camera` and `location` must carry
+  the sentence iOS shows when asking, or the build fails.
+- **`tabs:` and `rules:` deploy with the web app.** They're baked into the bundle *and* served
+  live from `/everywhere/ios_v1.json` and `/everywhere/android_v1.json`, so changing a tab or a
+  presentation rule ships with your next deploy — no app-store release.
+- Most other keys (`window`, `menu`, `tray`, `permissions`, `appearance`) are read at build
+  time and do need a new build.
+
+### The JavaScript bridge
+
+One API across browser, desktop, and mobile. It degrades gracefully in a plain browser, so
+you can call it unconditionally.
+
+```js
+import Everywhere from "@rubyeverywhere/bridge"
+window.Everywhere = Everywhere
+```
+
+Surface: `platform` (`"desktop" | "mobile" | "browser"`), `os`, `native`, `version`,
+`notify()`, `confirm()`, `on()`, `visit()`, `menu()`, `reloadTabs()`, `resetApp()`, and the
+namespaces `auth`, `clipboard`, `haptics`, `permissions`, `biometrics`, `instance`, `storage`,
+`badge`, `desktop` (`desktop.invoke`), `window` (`minimize`/`maximize`/`close`/`startDragging`/…),
+and `updates` (`check`/`install`/`setChannel`/`on`).
+
+Reach for the bridge when something has to happen in response to JS. For anything you can
+render, prefer the markup above — it's CSP-safe, correct on first paint, and works in a
+browser without a code path of its own.
+
+### Commands
+
+Run these from the app root.
+
+| Command | What it does |
+| --- | --- |
+| `every dev` | Dev server plus native shells on demand, live reload (`--desktop --ios --android --mobile --browser`) |
+| `every doctor` | Check the toolchain before a first build |
+| `every build` | Build the native shells — desktop, or `--ios` / `--android` |
+| `every logs` | Stream shell logs from the iOS Simulator or an Android device |
+| `every icon` | Generate `.icns` / `.ico` / Linux icons from a source PNG |
+| `every release` | Sign, notarize, staple, and emit `dist/release.json` |
+| `every publish` | Publish a release to the app's update bucket |
+| `every clean` | Remove the shell build caches |
+
+`every dev` never packages anything — it runs the ordinary dev server and points the shells
+at it, so the edit-refresh loop is unchanged.
+
+Two directories are build output, never source: `dist/` (artifacts) and `~/.rubyeverywhere`
+(stamped shell projects and caches). Don't commit them, don't hand-edit them — the next build
+overwrites both.
+
+### Config `every install` touched
+
+These exist so this codebase can also be compiled and shipped on-device, and several of them
+look like mistakes if you don't know that. Leave them in place — full rationale at
+<https://rubyeverywhere.com/docs>.
+
+{{FRAMEWORK_NOTES}}
+
+Re-running `every install` is idempotent and skips anything already in place, so it's the
+right way to restore one of these if it goes missing.

data/support/agents/frameworks/hanami-views.md

@@ -0,0 +1,26 @@
+### Native chrome from your views
+
+The ERB helpers (`native_app?`, `everywhere_nav_button`, `everywhere_fab`, …) ship with the
+Rails engine, so they aren't available here. The markup contract behind them is public,
+though, and the shell watches for it on every Turbo visit — write it directly:
+
+- `data-everywhere-nav-button` (+ `-nav-title`, `-nav-icon`, `-nav-icon-ios`,
+  `-nav-icon-android`, `-nav-style`, `side`) — lifts a link or submit button into the top
+  navigation bar. Tapping the native control clicks your element.
+- `data-everywhere-nav-menu` with `data-everywhere-menu-item` children (+ `-menu-title`,
+  `-menu-style`) — a native pull-down menu.
+- `data-everywhere-menu` + `-menu-trigger` + `-menu-items` — an in-content action sheet.
+- `data-everywhere-haptic` — a tap haptic.
+- `data-everywhere-biometric-lock` (+ `-content`, `-locked`, `-unlock`, `-reason`,
+  `-passcode`) — the Face ID / Touch ID gate.
+- `<meta name="everywhere:badge">` and `<meta name="everywhere:tab-badge">` (JSON
+  `{path, count}`) — app-icon and tab badges, CSP-safe and correct on first paint.
+
+Detect the shell server-side from the User-Agent: the shells prepend
+`RubyEverywhere/<version> (<os>)` to Hotwire Native's own marker. Client-side, use
+`Everywhere.platform` / `Everywhere.native`.
+
+`public/native.css`, served via `Rack::Static`, carries the styling helpers — including
+`.everywhere-titlebar-inset` for `window.title_bar: overlay`. Hanami's CSP forbids inline
+scripts, so every bit of this has to be attributes and external files; that's the same reason
+the markup contract exists in the first place.

data/support/agents/frameworks/hanami.md

@@ -0,0 +1,10 @@
+- `native_boot.rb` — the packaged-app entry point. Keep it thin and keep it at the app root.
+- `public/bridge.js` and `public/native.css` — the bridge, vendored and refreshed on each
+  `every install`. Serve `public/` via `Rack::Static` and load `/bridge.js` as an **external**
+  module; Hanami's CSP forbids inline scripts.
+
+Rack apps vary too much for the CLI to auto-edit their boot files, so the rest is by hand and
+`every install` prints it rather than guessing: override `DATABASE_URL` from
+`ENV["NATIVE_STORAGE_DIR"]` in `config.ru` when `NATIVE_PACKAGED` is set, and migrate before
+Hanami finalizes (`Hanami.prepare`, run the ROM migrations, then `require "hanami/boot"`).
+Both only matter for on-device packaging.

data/support/agents/frameworks/rails-views.md

@@ -0,0 +1,98 @@
+### Native chrome from your views
+
+`Everywhere::Engine` mixes a set of helpers into every view. **Prefer these over hand-written
+markup or JavaScript.** They render a real link or button that works in a browser, and carry
+the `data-everywhere-*` attributes the shell lifts into native chrome — tapping the native
+control just clicks the element it mirrors, so behavior is defined once and CSP is never an
+issue.
+
+Icons are per-platform, like tabs: `icon:` is the shared fallback, `icons: { ios:, android: }`
+names an SF Symbol and a Material Symbol respectively.
+
+**Where am I?** Pick the narrowest predicate that's true of what you're branching on.
+
+| Helper | |
+| --- | --- |
+| `native_app?` | any shell — iOS, Android, or desktop. "Not a browser tab." |
+| `mobile_app?` | a phone: safe-area insets, the native tab bar, biometrics, the OAuth handoff |
+| `desktop_app?` | the desktop window: title bar, menu bar, pointer |
+| `native_platform` | `:ios`, `:android`, `:desktop`, or `nil` in a browser |
+| `mobile_platform` | `:ios`, `:android`, or `nil` (including on desktop) |
+| `native_version` | the shell's version as a `Gem::Version` — gate features that need a newer shell |
+
+Detection is by User-Agent, so it's correct on the server before the JS bridge has booted.
+Hiding a web nav in favor of native chrome is usually `mobile_app?`, not `native_app?` — the
+desktop shell has no native navigation to replace it with.
+
+**Navigation bar.** Renders in the page for browsers; the shell hides the in-page copy and
+puts it in the top bar.
+
+```erb
+<%= everywhere_nav_button "New", new_note_path, icons: { ios: "plus", android: "add" } %>
+<%= everywhere_nav_button "Back", notes_path, side: "left" %>
+
+<%= form_with model: @note do |f| %>
+  <%= everywhere_submit_button "Save" %>   <%# mirrors the form's submit into the nav bar %>
+<% end %>
+
+<%= everywhere_nav_menu do %>              <%# ⋯ pull-down; a native UIMenu in the shell %>
+  <%= everywhere_menu_item "Share", share_path, icons: { ios: "square.and.arrow.up" } %>
+  <%= everywhere_menu_item "Delete", note_path(@note), method: :delete, style: "destructive" %>
+<% end %>
+```
+
+`everywhere_nav_button` takes `side:` (`"right"` / `"left"`), `style:` (`"done"`,
+`"destructive"`), and `type: :submit`. `everywhere_menu_item` is a link by default; `method:`
+makes it a Turbo method link, `type: :submit` with `form:` submits a form, and
+`style: "destructive"` tints it natively.
+
+**In-content controls.**
+
+```erb
+<%# floating action button — fixed, safe-area-aware, tap haptic in the shell %>
+<%= everywhere_fab new_note_path, icon: :plus, label: "New note" %>
+<%= everywhere_fab compose_path, icon: :pencil, label: "Compose", extended: true %>
+
+<%# action sheet: native sheet in the shell, inline menu in a browser %>
+<%= everywhere_menu "Options" do %>
+  <%= everywhere_menu_item "Edit", edit_post_path(@post) %>
+  <%= everywhere_menu_item "Delete", post_path(@post), method: :delete, style: "destructive" %>
+<% end %>
+```
+
+`everywhere_fab` accepts `icon:` (a built-in line glyph), `label:` (accessible name, plus a
+visible pill with `extended: true`), `side:`, and `haptic:` — or a block for custom content.
+
+**Badges.** Server-rendered meta tags the bridge applies on every Turbo visit; `0` clears.
+
+```erb
+<%= everywhere_badge Current.user.unread_count %>          <%# app icon %>
+<%= everywhere_tab_badge "/inbox", Current.user.unread_count %>  <%# a tab, by its everywhere.yml path %>
+```
+
+**Biometric gate.** Keeps sensitive markup hidden until Face ID / Touch ID passes, and only
+when the user has turned the device-local lock on. Browsers and the desktop shell render the
+content plainly. Needs `biometrics` under `permissions:` in `config/everywhere.yml`.
+
+```erb
+<%= everywhere_biometric_lock reason: "Unlock account settings" do %>
+  <%# profile, password, sessions… %>
+<% end %>
+
+<div data-everywhere-biometric-toggle-row hidden>
+  <label>Require Face ID <%= everywhere_biometric_toggle %></label>
+</div>
+```
+
+**Auth redirects.** In a controller, route post-sign-in redirects through the reset page so a
+phone shell rebuilds its web views and re-fetches its tab bar:
+
+```ruby
+redirect_to everywhere_auth_redirect(after_authentication_url)
+```
+
+**Tab bar, per request.** `Everywhere.filter_tabs { |tabs, request| … }` in an initializer
+varies the mobile tab bar — it shares the app's session; return `[]` to hide the bar.
+
+Styling helpers live in `everywhere/native.css`, including `.everywhere-titlebar-inset` for
+`window.title_bar: overlay`.

data/support/agents/frameworks/rails.md

@@ -0,0 +1,16 @@
+- `native_boot.rb` — the packaged-app entry point. Keep it thin and keep it at the app root.
+- `config/initializers/everywhere.rb` — packaged-only public-path and session-store setup.
+- `config/boot.rb` — bootsnap guarded with `unless ENV["NATIVE_PACKAGED"]` (its cache dir is
+  read-only when packaged).
+- `config/environments/production.rb` — `force_ssl` and `assume_ssl` are `false`, because a
+  packaged app's webview talks plain HTTP to `127.0.0.1`.
+- `config/puma.rb` — keep-alives off when packaged; WebKit reuses connections Puma has closed.
+- `config/database.yml` — the production SQLite path reads
+  `<%= ENV.fetch("NATIVE_STORAGE_DIR", "storage") %>`. Any database you add should use the same
+  lookup.
+- `app/javascript/application.js` — imports the bridge and exposes it as `window.Everywhere`.
+
+One rule that matters in every mode: the bridge is served and importmap-pinned by
+`Everywhere::Engine` straight from the gem, so it updates with `bundle update ruby_everywhere`.
+Don't vendor it into `vendor/javascript/` or pin it in `config/importmap.rb` — a local copy
+shadows the engine's and freezes the app on an old bridge.

data/support/agents/frameworks/sinatra-views.md

@@ -0,0 +1,24 @@
+### Native chrome from your views
+
+The ERB helpers (`native_app?`, `everywhere_nav_button`, `everywhere_fab`, …) ship with the
+Rails engine, so they aren't available here. The markup contract behind them is public,
+though, and the shell watches for it on every Turbo visit — write it directly:
+
+- `data-everywhere-nav-button` (+ `-nav-title`, `-nav-icon`, `-nav-icon-ios`,
+  `-nav-icon-android`, `-nav-style`, `side`) — lifts a link or submit button into the top
+  navigation bar. Tapping the native control clicks your element.
+- `data-everywhere-nav-menu` with `data-everywhere-menu-item` children (+ `-menu-title`,
+  `-menu-style`) — a native pull-down menu.
+- `data-everywhere-menu` + `-menu-trigger` + `-menu-items` — an in-content action sheet.
+- `data-everywhere-haptic` — a tap haptic.
+- `data-everywhere-biometric-lock` (+ `-content`, `-locked`, `-unlock`, `-reason`,
+  `-passcode`) — the Face ID / Touch ID gate.
+- `<meta name="everywhere:badge">` and `<meta name="everywhere:tab-badge">` (JSON
+  `{path, count}`) — app-icon and tab badges, CSP-safe and correct on first paint.
+
+Detect the shell server-side from the User-Agent: the shells prepend
+`RubyEverywhere/<version> (<os>)` to Hotwire Native's own marker. Client-side, use
+`Everywhere.platform` / `Everywhere.native`.
+
+`public/native.css` carries the styling helpers, including `.everywhere-titlebar-inset` for
+`window.title_bar: overlay`.

data/support/agents/frameworks/sinatra.md

@@ -0,0 +1,9 @@
+- `native_boot.rb` — the packaged-app entry point. Keep it thin and keep it at the app root.
+- `public/bridge.js` and `public/native.css` — the bridge, vendored and refreshed on each
+  `every install`. Load it with `<script type="module" src="/bridge.js"></script>`.
+
+Rack apps vary too much for the CLI to auto-edit their boot files, so the rest is by hand and
+`every install` prints it rather than guessing: point the production SQLite path at
+`ENV.fetch("NATIVE_STORAGE_DIR", "storage")`, and call
+`Everywhere::Database.prepare!(__dir__)` from `config.ru` after loading the app. Both only
+matter for on-device packaging.

data/support/agents/modes/local.md

@@ -0,0 +1,12 @@
+The app itself is compiled into the shipped binary and runs on the user's machine, rather than
+the shells pointing at a deployed site. Shipping a change means cutting a new build and
+release.
+
+That trade brings constraints the docs cover properly — a read-only application filesystem
+with a separate writable data directory, SQLite only, desktop only — so read
+<https://rubyeverywhere.com/docs> before changing anything that writes to disk, boots the app,
+or touches `native_boot.rb`. The short version: anything written at runtime belongs under
+`ENV.fetch("NATIVE_STORAGE_DIR", "storage")`, and `ENV["NATIVE_PACKAGED"]` is the guard for
+packaged-only behavior.
+
+Everything below applies the same way in either mode.

data/support/agents/modes/remote.md

@@ -0,0 +1,14 @@
+The native shells are a thin wrapper around the deployed site at `remote.url` in
+`config/everywhere.yml`. Nothing about the app is compiled into them.
+
+**So you are working on an ordinary web app.** Ship a change by deploying as you always have,
+and users see it on their next launch — no rebuild, no app-store review. Normal databases,
+background jobs, and hosting all apply, unchanged.
+
+Only three things are native-specific, and they're all covered below: what
+`config/everywhere.yml` declares, the view markup that becomes native chrome, and the
+`Everywhere` JavaScript API. Of those, tab and path-rule changes deploy with the app; the rest
+of `config/everywhere.yml` needs a new build of the shells.
+
+Remote is also the only mode mobile supports — iOS and Android are always a shell around a
+deployed app.

data/support/mobile/android/app/build.gradle.kts

@@ -18,6 +18,15 @@ val everywhere = Properties().apply {
 fun stamped(key: String, default: String): String =
     everywhere.getProperty("everywhere.$key")?.takeIf { it.isNotBlank() } ?: default
 
+// Release signing and the versionCode override arrive as environment, never as
+// stamped properties: everywhere.properties lives in the work dir for the life
+// of the app, and a keystore password written there outlives the build that
+// needed it. `every build` resolves and passes these; a direct Gradle
+// invocation can export them itself.
+fun env(name: String): String? = System.getenv("EVERY_ANDROID_$name")?.takeIf { it.isNotBlank() }
+
+val releaseKeystore = env("KEYSTORE")?.let { file(it) }
+
 android {
     // The namespace is the R class / BuildConfig package and is frozen. It is
     // deliberately NOT the applicationId: apps rename their bundle id freely,
@@ -28,7 +37,7 @@ android {
     defaultConfig {
         applicationId = stamped("applicationId", "com.rubyeverywhere.app")
         versionName = stamped("versionName", "0.1.0")
-        versionCode = stamped("versionCode", "1").toInt()
+        versionCode = (env("VERSION_CODE") ?: stamped("versionCode", "1")).toInt()
 
         // minSdk 28 is Hotwire Native Android's floor and is not negotiable.
         // It also clears API 26 for Typeface.Builder.setFontVariationSettings,
@@ -63,11 +72,30 @@ android {
         getByName("main") { res.srcDir("src/stamped/res") }
     }
 
+    signingConfigs {
+        // Created only when a keystore is in the environment: the default build
+        // is an unsigned release, and a signingConfig with a null storeFile is
+        // a configuration-time failure rather than an unsigned APK.
+        releaseKeystore?.let { keystore ->
+            create("release") {
+                storeFile = keystore
+                storePassword = env("KEYSTORE_PASSWORD")
+                keyAlias = env("KEY_ALIAS")
+                // keytool -genkeypair without -keypass gives the key the store's
+                // password; the CLI resolves the same fallback before it gets here.
+                keyPassword = env("KEY_PASSWORD") ?: env("KEYSTORE_PASSWORD")
+            }
+        }
+    }
+
     buildTypes {
         getByName("debug") {
             isDebuggable = true
         }
         release {
+            if (releaseKeystore != null) {
+                signingConfig = signingConfigs.getByName("release")
+            }
             isMinifyEnabled = false
             proguardFiles(
                 getDefaultProguardFile("proguard-android-optimize.txt"),

data/support/mobile/ios/App/EverywhereConfig.swift

@@ -145,20 +145,31 @@ struct EverywhereConfig: Decodable {
     /// relaunches; release builds never read it.
     private static let devOverrideURL: URL? = {
         let key = "EverywhereDevURL"
-        if let dev = ProcessInfo.processInfo.environment["EVERYWHERE_DEV_URL"], let url = URL(string: dev) {
+        if let dev = ProcessInfo.processInfo.environment["EVERYWHERE_DEV_URL"], let url = rootWorthy(dev) {
             #if DEBUG
-            UserDefaults.standard.set(dev, forKey: key)
+            UserDefaults.standard.set(url.absoluteString, forKey: key)
             #endif
             return url
         }
         #if DEBUG
-        if let saved = UserDefaults.standard.string(forKey: key), let url = URL(string: saved) {
+        if let saved = UserDefaults.standard.string(forKey: key), let url = rootWorthy(saved) {
             return url
         }
         #endif
         return nil
     }()
 
+    /// A string as an app ROOT: everything derived from a root (path config,
+    /// tab URLs) is built by appending paths, so a root carrying a query or
+    /// fragment would smear them onto every derived URL. Paths are kept —
+    /// dev URLs legitimately carry entry_path.
+    private static func rootWorthy(_ string: String) -> URL? {
+        guard var components = URLComponents(string: string) else { return nil }
+        components.query = nil
+        components.fragment = nil
+        return components.url
+    }
+
     // MARK: Instance override (multi-instance apps)
 
     /// UserDefaults key holding the user-chosen instance root. Multi-instance
@@ -186,9 +197,10 @@ struct EverywhereConfig: Decodable {
             return true
         }
         guard let scheme = url.scheme?.lowercased(), ["https", "http"].contains(scheme),
-              url.host != nil
+              url.host != nil,
+              let root = rootWorthy(url.absoluteString)
         else { return false }
-        UserDefaults.standard.set(url.absoluteString, forKey: instanceKey)
+        UserDefaults.standard.set(root.absoluteString, forKey: instanceKey)
         return true
     }