ruby_everywhere 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b4e222fd8e74b0c921b4cdab9d681b0f06bad2d94aae8dbe999415824508a1f5
-  data.tar.gz: e3a49bb93e2e49924c70cb622943e02b9bb302ddb828d29fc4c2ee5064c01e0e
+  metadata.gz: 1c87aa5a2416d070a8047b790f28c7230882999b7df4f7f584256ee96852f066
+  data.tar.gz: 6fa25612acf17e6d90b3302a4e7f93a8d5ded79fd8ffb39aec318b908df32bcf
 SHA512:
-  metadata.gz: 5756a97bf1012daf2069fdb186de16f22a1bdbed9972ec42e384dc8b9b24a84b03b004568af26eeb6990b53336ceb3bfd6c4f3177ec9b0b43e2682db15b382a1
-  data.tar.gz: aba1e8c877b1ecd3b9b975a434c89831a9a0b302cbc2bea567472d650f28a442666735cfb9171a20aa615894c7e9bd5de52d2f9e334b7b9af00f750489fac14f
+  metadata.gz: 69fb1bdb659b8b886d9b602e09e21d8016caf140ac401ee371d4b0eaab2e06f3b342fb7742e2684570b80e71768fb2c5ede34dca3f1d5b9015185b93b176ba59
+  data.tar.gz: 450a804d3bf9765ea664e0728c66df31019e5633393680120ef9ec7ba40def7e69f163b9aaaf6b2d2fcec948e62c5d3821b26bb553924666dfb57b7d1c6b29cd

data/README.md

@@ -57,6 +57,7 @@ cd path/to/your/app
 
 every install          # remote mode: a native shell around your deployed app
 every install --local  # local mode: compile and ship the app itself
+every install --agents # ...plus an AGENTS.md guide for AI coding agents
 
 every doctor           # check the toolchain before your first build
 
@@ -76,6 +77,16 @@ in place. For Rails it does the surgery for you; for Sinatra and Hanami it
 vendors the bridge and prints the remaining wiring rather than guessing at your
 boot files.
 
+Working with an AI coding agent? `--agents` writes an `AGENTS.md` — the format
+Claude Code, Cursor, Copilot and Codex all read — covering the view helpers
+(`native_app?`, `everywhere_nav_button`, `everywhere_fab`, the menus and badges),
+`config/everywhere.yml`, the bridge API, and the `every` commands, so an agent
+reaches for the right helper instead of hand-rolling markup. It's framework- and
+mode-aware, and adds a one-line `CLAUDE.md` pointer if you don't already have
+one. If you already have an `AGENTS.md`, only the block between
+`<!-- rubyeverywhere:begin -->` and `<!-- rubyeverywhere:end -->` is written, so
+re-running refreshes our section and leaves your own notes alone.
+
 `every dev` never packages anything: it runs your ordinary dev server and points
 the native shells at it, so the edit-refresh loop is untouched Rails.
 
@@ -269,7 +280,7 @@ Plus `native_app?`, `native_platform`, `everywhere_badge`,
 
 | Command | What it does |
 | --- | --- |
-| `every install` | Prepare an app (boot stub, `config/everywhere.yml`, config tweaks) |
+| `every install` | Prepare an app (boot stub, `config/everywhere.yml`, config tweaks) — `--local`, `--agents` |
 | `every doctor` | Check the toolchain — Tebako, Rust, brew deps, Xcode, Android SDK/JDK |
 | `every dev` | Dev server with native shells on demand (`--desktop --ios --android --mobile --browser`) |
 | `every logs` | Stream shell logs from the Simulator or Android device |
@@ -324,6 +335,7 @@ bridge/                  @rubyeverywhere/bridge — the JS half
 support/desktop/         the Tauri desktop shell template
 support/mobile/ios/      the Hotwire Native iOS shell template
 support/mobile/android/  the Hotwire Native Android shell template
+support/agents/          the AGENTS.md guide `every install --agents` writes
 ```
 
 The shell templates have their own READMEs documenting the freeze rules — what

data/lib/everywhere/agents_guide.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require_relative "paths"
+require_relative "ui"
+
+module Everywhere
+  # The AGENTS.md guide `every install --agents` writes into an app, so AI coding
+  # agents (Claude Code, Cursor, Copilot, Codex) understand what RubyEverywhere is
+  # before they "fix" the config edits install made.
+  #
+  # The guide is prose, so it lives as markdown under support/agents/ rather than
+  # in a heredoc — code fences and #{} snippets are miserable to escape in Ruby,
+  # and the gemspec already globs support/**/*. Assembly is a shared body plus
+  # per-framework fragments (install notes, view helpers) and a mode fragment,
+  # joined by {{PLACEHOLDER}} gsub.
+  module AgentsGuide
+    module_function
+
+    # The generated section is fenced so a re-run can refresh it without touching
+    # anything the app's own authors wrote around it.
+    BEGIN_MARKER = "<!-- rubyeverywhere:begin -->"
+    END_MARKER   = "<!-- rubyeverywhere:end -->"
+
+    PLACEHOLDER = /\{\{([A-Z_]+)\}\}/
+    LABELS = { "rails" => "Rails", "sinatra" => "Sinatra", "hanami" => "Hanami" }.freeze
+
+    def template_dir = File.join(Paths.gem_root, "support", "agents")
+
+    # The guide body for one app, with no markers around it.
+    def render(framework:, mode:)
+      substitute(read("AGENTS.md"),
+        "FRAMEWORK" => LABELS.fetch(framework),
+        "MODE" => mode,
+        "FRAMEWORK_NOTES" => read("frameworks", "#{framework}.md").strip,
+        "FRAMEWORK_VIEWS" => read("frameworks", "#{framework}-views.md").strip,
+        "MODE_NOTES" => read("modes", "#{mode}.md").strip)
+    end
+
+    # The body wrapped in the markers, ready to splice into an AGENTS.md.
+    def block(framework:, mode:)
+      "#{BEGIN_MARKER}\n#{render(framework: framework, mode: mode).strip}\n#{END_MARKER}\n"
+    end
+
+    # fetch, not [], so a typo'd placeholder blows up in the test suite instead of
+    # shipping "{{MDOE}}" to somebody's repo.
+    def substitute(body, values)
+      body.gsub(PLACEHOLDER) { values.fetch(Regexp.last_match(1)) }
+    end
+
+    def read(*parts)
+      path = File.join(template_dir, *parts)
+      File.exist?(path) or UI.die!("couldn't find the bundled AGENTS.md template at #{path}; " \
+                                   "reinstall ruby_everywhere")
+      File.read(path)
+    end
+  end
+end

data/lib/everywhere/commands/install.rb

@@ -3,6 +3,8 @@
 require "dry/cli"
 require "fileutils"
 require_relative "../shellout"
+require_relative "../config"
+require_relative "../agents_guide"
 
 module Everywhere
   module Commands
@@ -13,8 +15,9 @@ module Everywhere
 
       option :root, default: ".", desc: "App root directory"
       option :local, type: :boolean, default: false, desc: "Configure local mode (compile & ship the app) instead of remote mode"
+      option :agents, type: :boolean, default: false, desc: "Write an AGENTS.md guide so AI coding agents understand this app"
 
-      def call(root: ".", local: false, **)
+      def call(root: ".", local: false, agents: false, **)
         @mode = local ? "local" : "remote"
         @framework = Framework.detect(root)
         @root = @framework.root
@@ -29,6 +32,13 @@ module Everywhere
         # Framework-specific config surgery.
         send("install_#{@framework.name}")
 
+        if agents
+          write_agents_guide
+          write_claude_pointer
+        else
+          UI.step(UI.dim("tip: `every install --agents` writes an AGENTS.md guide for AI coding agents"))
+        end
+
         UI.success("installed — run `every dev` to open the app, `every build` to package it")
       end
 
@@ -247,6 +257,68 @@ module Everywhere
         change("create native_boot.rb", true)
       end
 
+      # --- AGENTS.md (--agents) --------------------------------------------------
+
+      FRESH_HEADER = "# AGENTS.md\n\nGuidance for AI coding agents working in this repository.\n\n"
+
+      # AGENTS.md is the app's file, not ours — most apps that have one already
+      # have notes in it. So we own only what's between the markers, and a re-run
+      # refreshes that region in place.
+      def write_agents_guide
+        path = app_file("AGENTS.md")
+        block = AgentsGuide.block(framework: @framework.name, mode: guide_mode)
+
+        unless File.exist?(path)
+          File.write(path, FRESH_HEADER + block)
+          return change("create AGENTS.md", true)
+        end
+
+        existing = File.read(path)
+        updated = merge_agents_block(existing, block) or return # markers are broken; warned
+        File.write(path, updated) unless updated == existing
+        change("refresh the RubyEverywhere section of AGENTS.md", updated != existing)
+      end
+
+      # Returns the merged file, or nil when the markers are malformed — a lone
+      # BEGIN would make the next run's region match swallow everything the app's
+      # authors wrote after it, so we refuse rather than guess at a repair.
+      def merge_agents_block(existing, block)
+        begins = existing.scan(AgentsGuide::BEGIN_MARKER).size
+        ends = existing.scan(AgentsGuide::END_MARKER).size
+
+        if begins.zero? && ends.zero?
+          return existing.strip.empty? ? block : "#{existing.chomp}\n\n#{block}"
+        end
+
+        if begins != 1 || ends != 1 ||
+           existing.index(AgentsGuide::BEGIN_MARKER) > existing.index(AgentsGuide::END_MARKER)
+          UI.warn("AGENTS.md has unbalanced #{AgentsGuide::BEGIN_MARKER} / #{AgentsGuide::END_MARKER} " \
+                  "markers — leaving it alone; fix them by hand and re-run")
+          return nil
+        end
+
+        region = /^#{Regexp.escape(AgentsGuide::BEGIN_MARKER)}\n.*?^#{Regexp.escape(AgentsGuide::END_MARKER)}\n?/m
+        existing.sub(region) { block }
+      end
+
+      # Claude Code reads AGENTS.md on its own; the pointer is for the setups that
+      # only look at CLAUDE.md. An app that already has one has its own reasons for
+      # what's in it — leave it alone and let AGENTS.md be found the normal way.
+      def write_claude_pointer
+        claude = app_file("CLAUDE.md")
+        return change("create CLAUDE.md pointer", false) if File.exist?(claude)
+
+        File.write(claude, "See @AGENTS.md for how this app works and how RubyEverywhere packages it.\n")
+        change("create CLAUDE.md pointer", true)
+      end
+
+      # --local only describes what THIS run configured. Once config/everywhere.yml
+      # exists it is the truth, so a re-run without the flag can't mislabel a
+      # local-mode app as remote.
+      def guide_mode
+        File.exist?(app_file(Config::FILE)) ? Config.load(@root).mode : @mode
+      end
+
       def guard_bootsnap
         boot = app_file("config", "boot.rb")
         contents = File.read(boot)

data/lib/everywhere/version.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Everywhere
-  VERSION = "0.5.0"
+  VERSION = "0.6.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.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby_everywhere
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Andrea Fomera
@@ -65,8 +65,13 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.15'
-description: Packages a Rails (and one day Hanami) app into a single-file binary with
-  Tebako and wraps it in a Tauri desktop shell as a double-clickable app.
+description: RubyEverywhere gives a Rails (or Sinatra, or Hanami) app a native life
+  on desktop, iOS, and Android. Desktop is a Tauri shell — in local mode the whole
+  app is pressed into a single-file binary with Tebako and runs on-device with no
+  Ruby install; in remote mode the shell wraps your deployed app. iOS and Android
+  are Hotwire Native shells with a real tab bar, nav-bar buttons, menus, notifications,
+  haptics, biometrics, and deep links. One config file, one CLI, one JavaScript bridge,
+  with the web app staying the source of truth.
 email:
 - andrea.fomera@gmail.com
 executables:
@@ -86,6 +91,7 @@ files:
 - exe/every
 - exe/rbe
 - lib/everywhere.rb
+- lib/everywhere/agents_guide.rb
 - lib/everywhere/android_resources.rb
 - lib/everywhere/android_sdk.rb
 - lib/everywhere/asset_catalog.rb
@@ -151,6 +157,15 @@ files:
 - lib/everywhere/update_manifest.rb
 - lib/everywhere/version.rb
 - lib/ruby_everywhere.rb
+- support/agents/AGENTS.md
+- support/agents/frameworks/hanami-views.md
+- support/agents/frameworks/hanami.md
+- support/agents/frameworks/rails-views.md
+- support/agents/frameworks/rails.md
+- support/agents/frameworks/sinatra-views.md
+- support/agents/frameworks/sinatra.md
+- support/agents/modes/local.md
+- support/agents/modes/remote.md
 - support/desktop/README.md
 - support/desktop/splash/index.html
 - support/desktop/src-tauri/Cargo.lock
@@ -258,7 +273,11 @@ files:
 homepage: https://rubyeverywhere.com
 licenses:
 - MIT
-metadata: {}
+metadata:
+  homepage_uri: https://rubyeverywhere.com
+  source_code_uri: https://github.com/RubyEverywhere/gem
+  bug_tracker_uri: https://github.com/RubyEverywhere/gem/issues
+  rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
 - lib
@@ -275,6 +294,6 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.16
 specification_version: 4
-summary: RubyEverywhere — ship desktop apps from the Ruby web apps you already know
-  how to build
+summary: Ship desktop and mobile apps from the Ruby web apps you already know how
+  to build
 test_files: []