shipeasy-sdk 2.0.0 → 2.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 97efde389fa7a5adc1ffdab3951d09837f435bd529d8f6c3b7e3d45387472628
-  data.tar.gz: 46f183776d94ccbddd8781e39d3ea5e56e6795cf26f3292f1482c2886b7d0836
+  metadata.gz: 434e056f9f0849c73316e812f9ff8918ad838d9161283db0b3a8c9c7450b1077
+  data.tar.gz: beb6a893abc08ec7463a64fb2ec22f7df014f4da147b824a5f7b8d70ed3f34a0
 SHA512:
-  metadata.gz: 010654d1322131ab21b467fdff8176914e427558a5a620762c4417378f68c5cc5f3b189e7b0cdb8de6b741d2232e7c1552b8fd551bc3fce19b09e91263e18d12
-  data.tar.gz: 24730826e8f2de0ac3f1546ab4f42b2301bcd8f83bdaea0b9c50487d7b90d5b445470827199de73c4794bc16b2ddeed3e18fc44079c2000cd0c92aeb07f50e55
+  metadata.gz: 17339d55c4ed50599d3cc2cfa04f2f5a53e57a5478fb626bbf999ac6297da3a35a47e9a139150b4cfcce209c6e29f1b033180c9f5cc64923f106f5c1379adff8
+  data.tar.gz: 57fb7a408683111fd2f0aee2b389c97f5de038b22b2b6bbf0ff757c193220740a766951a7cda8baa59c58fc83bc26ea7e1103a07944e9206555a22970d071b19

data/README.md

@@ -1,10 +1,40 @@
+<!--
+  This file is GENERATED by scripts/gen_readme.rb from docs/.
+  Do NOT edit by hand — edit the docs, then run: ruby scripts/gen_readme.rb
+-->
+
 # shipeasy-sdk (Ruby)
 
-Ruby gem for the [Shipeasy](https://shipeasy.ai) hosted service. Server-side
-gate evaluation, runtime configs, experiments, and metric ingestion.
+[![Tests](https://github.com/shipeasy-ai/sdk-ruby/actions/workflows/test.yml/badge.svg)](https://github.com/shipeasy-ai/sdk-ruby/actions/workflows/test.yml)
+[![Gem](https://img.shields.io/gem/v/shipeasy-sdk.svg)](https://rubygems.org/gems/shipeasy-sdk)
+[![Ruby](https://img.shields.io/badge/ruby-%3E%3D%203.0-CC342D.svg)](https://www.ruby-lang.org/)
+
+Server SDK for [Shipeasy](https://shipeasy.ai) — **feature flags, dynamic
+configs, kill switches, A/B experiments, and metric tracking**, with Rails i18n
+view helpers. Server-key only; never embed in a browser.
+
+> 📚 **Full documentation:** **<https://shipeasy-ai.github.io/sdk-ruby/>** — also browsable under
+> [`docs/`](https://github.com/shipeasy-ai/sdk-ruby/blob/main/docs). This README is generated from those docs.
 
 > Source-available under the [Shipeasy-SAL 1.0](./LICENSE).
 
+## 🤖 Using an AI agent?
+
+This SDK ships an installable **agent skill** — a copy-paste-ready guide to
+`Shipeasy.configure` + `Client.new(user)`, testing, experiments, error
+reporting, and more, with links the agent can pull for deeper docs:
+
+- **Skill:** [`docs/skill/SKILL.md`](https://github.com/shipeasy-ai/sdk-ruby/blob/main/docs/skill/SKILL.md) · raw:
+  `https://shipeasy-ai.github.io/sdk-ruby/skill/SKILL.md`
+- **Install it** (ships with the gem — no network):
+  `shipeasy-skill install` → `.claude/skills/shipeasy-ruby/SKILL.md`
+  (or via the Shipeasy CLI: `shipeasy docs skill --sdk ruby --install`)
+
+**Humans:** you can copy that skill straight into your own project's agent skills
+directory (e.g. `.claude/skills/shipeasy-ruby/SKILL.md`) so your coding agent
+always uses the correct Shipeasy patterns. Every doc page and snippet is also
+fetchable by URL — start from the manifest at `https://shipeasy-ai.github.io/sdk-ruby/manifest.json`.
+
 ## Install
 
 ```ruby
@@ -12,324 +42,87 @@ gate evaluation, runtime configs, experiments, and metric ingestion.
 gem "shipeasy-sdk"
 ```
 
-## Quickstart (Rails)
+Requires Ruby 3.0+. Per-framework setup (Rails / Sinatra / serverless) and the
+anon-id middleware are on the [Installation](https://github.com/shipeasy-ai/sdk-ruby/blob/main/docs/pages/installation.md) page.
 
-Two parts: **configure once** at boot, then build a **user-bound
-`Shipeasy::Client`** per request via its constructor.
-
-`config/initializers/shipeasy.rb`:
+## Quickstart — `configure` once, then `Client.new(user)` per request
 
 ```ruby
+# boot (config/initializers/shipeasy.rb)
 Shipeasy.configure do |c|
   c.api_key    = ENV.fetch("SHIPEASY_SERVER_KEY")
-
-  # Optional: map YOUR user object → the Shipeasy attribute hash. Runs once,
-  # in the Shipeasy::Client constructor. Omit it and the object you pass to
-  # Shipeasy::Client.new IS the attribute hash (identity).
   c.attributes = ->(u) { { "user_id" => u.id, "plan" => u.plan } }
-
-  c.public_key = ENV.fetch("SHIPEASY_CLIENT_KEY")  # for i18n view helpers
-  c.profile    = "default"
-end
-```
-
-`configure` builds the single global engine for you and kicks off a one-shot
-fetch (fire-and-forget). Anywhere in your app, construct a bound client and call
-the getters with **no user argument** — the user is bound at construction:
-
-```ruby
-flags = Shipeasy::Client.new(current_user)   # runs the attributes transform once
-
-if flags.get_flag("new_checkout")            # NO user arg
-  # ship it
 end
 
-color  = flags.get_config("button_color")
-result = flags.get_experiment("checkout_cta", { label: "Buy now" })
-panic  = flags.get_killswitch("payments")
-```
+# per request — construct once per callsite (cheap; binds the user)
+flags = Shipeasy::Client.new(current_user)
 
-`Shipeasy::Client` is **cheap**: it delegates evaluation to the single engine
-built by `configure` — it never opens its own connection, fetches, or polls.
-Construct one per user / per request.
-
-Event ingestion (`track`) lives on the engine — `Shipeasy.engine` is the global
-one `configure` registered:
-
-```ruby
-Shipeasy.engine.track(current_user.id.to_s, "checkout_completed", { revenue: 49.99 })
+flags.get_flag("new_checkout")                       # NO user arg — bound at construction
+flags.get_config("button_color")
+result = flags.get_experiment("checkout_cta", { label: "Buy" })
+flags.log_exposure("checkout_cta")                   # at the decision point
+flags.track("purchase", { revenue: 49 })             # on conversion
+flags.get_killswitch("payments")
 ```
 
-> **Upgrading from 1.x?** The heavyweight client was renamed
-> `Shipeasy::SDK::FlagsClient` → `Shipeasy::Engine`, and `Shipeasy::Client` is
-> now the lightweight user-bound handle. The legacy `Shipeasy.flags.get_flag(name, user)`
-> singleton still works.
+Constructing `Shipeasy::Client.new(user)` before `Shipeasy.configure` raises
+`Shipeasy::Error`.
 
-In a Rails view (the railtie auto-mounts these helpers when Rails is loaded):
-
-```erb
-<%= i18n_head_tags %>
-<h1><%= i18n_t("hero.title", name: current_user.name) %></h1>
-```
-
-### Anonymous visitors (zero-config bucketing)
-
-For logged-out traffic you need a *stable* unit so a fractional rollout buckets
-the same on the server and in the browser. In Rails this is automatic: a Railtie
-mounts `Shipeasy::SDK::RackMiddleware`, which mints the shared `__se_anon_id`
-first-party cookie (read + written by every Shipeasy SDK, including the browser)
-for any request without one. Evaluations then default to it with **no per-call
-wiring** — `get_flag` on an anonymous request just works:
-
-```ruby
-# current_user is nil → buckets on the __se_anon_id cookie automatically
-Shipeasy::Client.new({}).get_flag("new_checkout")
-```
-
-An explicit `user_id` / `anonymous_id` always wins. If you prefer to read the id
-yourself it's also on the Rack env as `request.env["shipeasy.anon_id"]`. The
-cookie is non-`HttpOnly` by design so the browser SDK can bucket identically. A
-request with **no** unit still resolves a fully-rolled (100%) gate as on; only
-fractional gates need the id. Cookie name + format are a cross-SDK contract —
-see `18-identity-bucketing.md`.
-
-For **Sinatra / Hanami / bare Rack** (no Railtie), mount it yourself:
-
-```ruby
-use Shipeasy::SDK::RackMiddleware
-```
-
-## Quickstart (plain Ruby / Sinatra / Hanami / scripts)
-
-Same pattern, just without `config/initializers`:
-
-```ruby
-require "shipeasy-sdk"
-
-Shipeasy.configure { |c| c.api_key = ENV.fetch("SHIPEASY_SERVER_KEY") }
-
-# With no `attributes` transform, the hash you pass IS the attribute map.
-Shipeasy::Client.new({ "user_id" => "u_1" }).get_flag("new_checkout")
-```
-
-The Rails view helpers (`i18n_*`) are not loaded outside Rails, so the
-gem doesn't pull Rails into Sinatra/Hanami apps.
-
-## Lambda / Cloud Run / serverless
-
-Skip the auto-init facade — it spawns a poll thread you don't want in a
-short-lived function. Build the client explicitly and call `init_once`
-for a single synchronous fetch:
-
-```ruby
-engine = Shipeasy::Engine.new(api_key: ENV.fetch("SHIPEASY_SERVER_KEY"))
-engine.init_once
-engine.get_flag("new_checkout", user)
-```
-
-## Lifecycle escape hatch
-
-If you want explicit shutdown control in a long-running worker, build the
-client yourself and skip the singleton:
-
-```ruby
-client = Shipeasy::SDK.new_client     # reads api_key + base_url from Shipeasy.config
-client.init
-at_exit { client.destroy }
-```
-
-## Server-side rendering (SSR)
-
-Emit the request's evaluated flags as a declarative `<script>` tag so the
-browser SDK has them on first paint. `bootstrap_script_tag` carries the payload
-in `data-*` attributes (**no key**); the static `se-bootstrap.js` loader
-hydrates `window.__SE_BOOTSTRAP` and writes the `__se_anon_id` cookie so the
-browser buckets identically to the server.
-
-```ruby
-user = { "user_id" => "u_123" }
-
-# Two tags for the document <head>. The PUBLIC client key (not the server
-# key) goes on the i18n loader tag.
-head = client.bootstrap_script_tag(user, anon_id: anon_id) +
-       client.i18n_script_tag(client_key, profile: "en:prod")
-
-# …or get the raw payload ({ "flags", "configs", "experiments", "killswitches" }):
-boot = client.evaluate(user)
-```
-
-`bootstrap_script_tag` also accepts `i18n_profile:` and `base_url:` (defaults to
-`https://cdn.shipeasy.ai`). In **Rails**, the existing
-`Shipeasy::I18n::ViewHelpers#i18n_script_tag` view helper still renders the i18n
-loader tag from your app config.
-
-## Default values
-
-`get_flag` and `get_config` take an optional `default:` returned **only when the
-value cannot be resolved** — never when a flag genuinely evaluates to `false`.
-
-```ruby
-# Flag: default is returned only when the client isn't ready yet (no blob
-# fetched) or the gate doesn't exist. A gate that evaluates to false (disabled,
-# or outside its rollout) returns false, NOT the default.
-Shipeasy.flags.get_flag("new_checkout", user, default: true)
-
-# Config: default is returned when the config key is absent. A decode proc still
-# runs on a present value.
-Shipeasy.flags.get_config("button_color", default: "blue")
-Shipeasy.flags.get_config("limits", ->(v) { v["max"] }, default: 0)
-```
-
-## Evaluation detail
-
-`get_flag_detail(name, user)` returns the boolean **and the reason** it was
-reached, as a `FlagDetail` struct (`.value`, `.reason`). `get_flag` is built on
-top of it. The reason is one of the `REASON_*` constants:
-
-| Reason             | Meaning                                              |
-| ------------------ | --------------------------------------------------- |
-| `OVERRIDE`         | answered by a local `override_flag` (no telemetry)  |
-| `CLIENT_NOT_READY` | no flag blob fetched/loaded yet                     |
-| `FLAG_NOT_FOUND`   | blob present, but this gate isn't in it             |
-| `OFF`              | gate present but disabled or killswitched           |
-| `RULE_MATCH`       | evaluated to `true`                                 |
-| `DEFAULT`          | evaluated to `false` (rollout/rule)                 |
-
-```ruby
-detail = Shipeasy.flags.get_flag_detail("new_checkout", user)
-detail.value   # => true / false
-detail.reason  # => "RULE_MATCH" / "DEFAULT" / "OFF" / ...
-```
-
-The `gate` usage beacon fires exactly once per `get_flag_detail` call (never on
-the `OVERRIDE` short-circuit).
-
-## Change listeners
-
-`on_change` registers a callback fired after a background poll fetches **new**
-flag/config data (HTTP 200, not a 304). It accepts a block or any callable and
-returns an unsubscribe proc. Listeners never fire in test/offline mode (there is
-no poll thread). A raising listener is isolated and logged, not propagated.
-
-```ruby
-unsubscribe = Shipeasy.flags.on_change { reload_local_cache! }
-# ... later
-unsubscribe.call
-```
-
-## Offline snapshot
-
-For CI, air-gapped runs, or reproducing a production decision from a captured
-blob, build a **no-network** client that still runs the real evaluator against a
-snapshot. The snapshot JSON holds the raw response bodies of the two SDK
-endpoints:
-
-```json
-{ "flags": <body of /sdk/flags>, "experiments": <body of /sdk/experiments> }
-```
-
-```ruby
-client = Shipeasy::Engine.from_file("snapshot.json")
-# or, from already-parsed blobs:
-client = Shipeasy::Engine.from_snapshot(flags: flags_body, experiments: exps_body)
-
-client.get_flag("new_checkout", user)        # real evaluation, no network
-client.get_experiment("checkout_cta", user, {})
-```
-
-`init` / `init_once` / `track` are no-ops and telemetry is off (it reuses the
-`for_testing` plumbing). Local `override_*` setters still apply on top of the
-snapshot.
-
-## Evaluation details
+## Documentation
 
-- **Gates** — rules matched in order; rollout bucket =
-  `murmur3("#{salt}:#{uid}") % 10000 < rollout_pct`.
-- **Experiments** — `status == "running"`, optional targeting gate,
-  universe holdout range, allocation bucket, then group assignment by
-  weight.
-- **MurmurHash3** — pure-Ruby x86_32 variant, seed 0.
-- **ETag caching** — each poll sends `If-None-Match`; a 304 skips the
-  JSON parse.
-- **Poll interval** — defaults to 30 s; overridden by the
-  `X-Poll-Interval` header from the flags endpoint.
+| Page | What |
+| --- | --- |
+| [Overview](https://github.com/shipeasy-ai/sdk-ruby/blob/main/docs/pages/overview.md) | The `Shipeasy.configure` + `Client.new(user)` model. |
+| [Installation](https://github.com/shipeasy-ai/sdk-ruby/blob/main/docs/pages/installation.md) | Install, frameworks (Rails / Sinatra / serverless), `configure` wiring. |
+| [Configuration](https://github.com/shipeasy-ai/sdk-ruby/blob/main/docs/pages/configuration.md) | Keys, `attributes`, one-shot vs poll, every option. |
+| [Feature flags](https://github.com/shipeasy-ai/sdk-ruby/blob/main/docs/pages/flags.md) | `get_flag`, `get_flag_detail`, defaults. |
+| [Dynamic configs](https://github.com/shipeasy-ai/sdk-ruby/blob/main/docs/pages/configs.md) | `get_config`, typed decode, defaults. |
+| [Kill switches](https://github.com/shipeasy-ai/sdk-ruby/blob/main/docs/pages/killswitches.md) | `get_killswitch`, named switches. |
+| [Experiments](https://github.com/shipeasy-ai/sdk-ruby/blob/main/docs/pages/experiments.md) | `get_experiment`, `log_exposure`, `track`. |
+| [Internationalization](https://github.com/shipeasy-ai/sdk-ruby/blob/main/docs/pages/i18n.md) | Rails view helpers + the SSR loader tag. |
+| [Error reporting](https://github.com/shipeasy-ai/sdk-ruby/blob/main/docs/pages/error-reporting.md) | `see()` structured error reporting. |
+| [Testing](https://github.com/shipeasy-ai/sdk-ruby/blob/main/docs/pages/testing.md) | `configure_for_testing` / `configure_for_offline`, overrides. |
+| [OpenFeature](https://github.com/shipeasy-ai/sdk-ruby/blob/main/docs/pages/openfeature.md) | `Shipeasy::OpenFeature::Provider` (OpenFeature server provider). |
+| [Advanced](https://github.com/shipeasy-ai/sdk-ruby/blob/main/docs/pages/advanced.md) | Anon-id middleware, private attributes, sticky bucketing, SSR. |
+| [Admin API client](https://github.com/shipeasy-ai/sdk-ruby/blob/main/docs/pages/admin-api.md) | Optional `Shipeasy::Admin::Client` for administering resources (generated from the Open… |
+
+Copy-paste snippets live under [`docs/snippets/`](https://github.com/shipeasy-ai/sdk-ruby/blob/main/docs/snippets)
+(release · metrics · i18n · ops); an installable agent skill is at
+[`docs/skill/SKILL.md`](https://github.com/shipeasy-ai/sdk-ruby/blob/main/docs/skill/SKILL.md).
 
 ## Testing
 
-For unit/integration tests you want a client that does **zero network** and
-returns exactly the values you seed — no api_key, no fetch, no poll thread, no
-telemetry, no metric ingestion. Build one with `Shipeasy::Engine.for_testing` and
-seed each entity with the `override_*` setters (Statsig-style local overrides).
-An override always wins over the fetched blob, so the getters answer
-deterministically:
+Use **`Shipeasy.configure_for_testing`** — the test-mode sibling of [`Shipeasy.configure`](https://github.com/shipeasy-ai/sdk-ruby/blob/main/docs/pages/configuration.md). It does **zero network**, needs no api key, and seeds the values your code under test should see via override arguments. Then read through the ordinary `Shipeasy::Client.new(user)` — the *same* call your production code uses.
 
 ```ruby
 require "shipeasy-sdk"
 
-client = Shipeasy::Engine.for_testing
-# init / init_once are no-ops here — nothing is ever fetched.
-
-# Flags (boolean)
-client.override_flag("new_checkout", true)
-client.get_flag("new_checkout", { user_id: "u_1" })   # => true
+Shipeasy.configure_for_testing(
+  flags:       { "new_checkout" => true },
+  configs:     { "billing_copy" => { "title" => "Welcome" } },
+  experiments: { "checkout_button" => ["treatment", { "color" => "green" }] },
+)
 
-# Configs (any value; an optional decode proc still runs)
-client.override_config("button_color", "blue")
-client.get_config("button_color")                     # => "blue"
-client.override_config("limits", { "max" => 10 })
-client.get_config("limits", ->(v) { v["max"] })       # => 10
+# construct once per callsite (cheap; binds the user)
+client = Shipeasy::Client.new({ "user_id" => "u_123" })
 
-# Experiments — returns an in-experiment Eval::ExperimentResult
-client.override_experiment("checkout_cta", "treatment", { label: "Buy now" })
-r = client.get_experiment("checkout_cta", { user_id: "u_1" }, { label: "default" })
-r.in_experiment   # => true
-r.group           # => "treatment"
-r.params          # => { label: "Buy now" }
+client.get_flag("new_checkout")              # => true
+client.get_config("billing_copy")            # => { "title" => "Welcome" }
 
-# track is a no-op (no thread, no network) — assert call counts without stubbing.
-client.track("u_1", "checkout_completed", { revenue: 49.99 })  # => nil
+result = client.get_experiment("checkout_button", { "color" => "blue" })
+result.in_experiment                         # => true
+result.group                                 # => "treatment"
+result.params                                # => { "color" => "green" }
 
-# Reset between examples
-client.clear_overrides
+# track / log_exposure are no-ops in test mode — safe to call, send nothing
+client.track("purchase", { amount: 49 })
 ```
 
-The same `override_flag` / `override_config` / `override_experiment` /
-`clear_overrides` setters also work on a **normal** live client (built with
-`Shipeasy::Engine.new(...)`), so you can pin one value in local development while the
-rest comes from the fetched blob.
-
-### Global engine / bound client
-
-`Shipeasy.engine` (registered by `configure`) and `Shipeasy.flags` (legacy
-singleton) both fetch over the network, so in tests stub them to a
-`for_testing` engine. `Shipeasy::Client.new(user)` reads `Shipeasy.engine`, so
-stubbing the engine also covers the bound-client path:
-
-```ruby
-# RSpec
-before do
-  test_engine = Shipeasy::Engine.for_testing
-  test_engine.override_flag("new_checkout", true)
-  allow(Shipeasy).to receive(:engine).and_return(test_engine)
-  allow(Shipeasy).to receive(:flags).and_return(test_engine) # legacy path
-
-  # Shipeasy::Client.new(user).get_flag("new_checkout") now => true
-end
-```
-
-## Configuration
-
-| Parameter    | Default                       | Description                                                         |
-| ------------ | ----------------------------- | ------------------------------------------------------------------- |
-| `api_key`    | (required)                    | SDK key from the Shipeasy dashboard                                 |
-| `base_url`   | `https://edge.shipeasy.dev`   | Override for local dev / staging                                    |
-| `attributes` | identity (`->(u) { u }`)      | Callable mapping your user object → the Shipeasy attribute hash     |
-
-## Documentation
-
-[docs.shipeasy.ai](https://docs.shipeasy.ai)
+More — the on-the-spot override helpers and a working example
+`shipeasy-snapshot.json` — on the [Testing](https://github.com/shipeasy-ai/sdk-ruby/blob/main/docs/pages/testing.md) page.
 
 ## License
 
-[Shipeasy-SAL 1.0](./LICENSE) — source-available, non-commercial-use,
-permitted as a Shipeasy client.
+[Shipeasy-SAL 1.0](./LICENSE) — source-available, non-commercial-use, permitted
+as a Shipeasy client. Evaluation is tested against the cross-language
+MurmurHash3 vectors in `experiment-platform/04-evaluation.md`.

data/bin/shipeasy-skill

@@ -0,0 +1,8 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Opt-in installer for the bundled Shipeasy agent skill. See
+# lib/shipeasy/sdk/skill.rb.
+require "shipeasy/sdk/skill"
+
+exit Shipeasy::SDK::Skill.main(ARGV)

data/docs/skill/SKILL.md

@@ -0,0 +1,152 @@
+---
+name: shipeasy-ruby
+description: Use Shipeasy (feature flags, configs, kill switches, A/B experiments, i18n) from Ruby. Covers Shipeasy.configure + Client.new(user), get_flag/get_config/get_experiment/get_killswitch, track, testing, OpenFeature.
+---
+
+# Shipeasy Ruby SDK
+
+Server-side Ruby gem (`shipeasy-sdk`) for Shipeasy: feature gates, dynamic
+configs, kill switches, A/B experiments, metrics, `see()` error reporting, and
+Rails i18n view helpers. Server-key only — never embed in a browser. Ruby 3.0+.
+
+Two things only: **`Shipeasy.configure`** once at boot, then
+**`Shipeasy::Client.new(user)`** per request.
+
+> **Pulling deeper docs.** Each section below links its full reference page and
+> copy-paste snippets — fetch any of them as raw Markdown when you need more than
+> this summary. Discover the whole tree from the manifest:
+> `https://shipeasy-ai.github.io/sdk-ruby/manifest.json` (lists every
+> `pages/<key>.md` and `snippets/<group>/<leaf>.md`). All URLs below are
+> `https://shipeasy-ai.github.io/sdk-ruby/…`.
+
+## Configure once (boot)
+
+```ruby
+# config/initializers/shipeasy.rb
+Shipeasy.configure do |c|
+  c.api_key    = ENV.fetch("SHIPEASY_SERVER_KEY")
+  # Optional: map your user object → the attribute hash (runs once in Client.new).
+  c.attributes = ->(u) { { "user_id" => u.id, "plan" => u.plan } }
+  # i18n only (public client key + profile):
+  c.public_key = ENV.fetch("SHIPEASY_CLIENT_KEY")
+  c.profile    = "default"
+end
+```
+
+Omit `c.attributes` if your user object is already the attribute hash. For a
+long-running server set `c.poll = true` to keep the blob fresh in the background;
+the default (one-shot fetch, no thread) is serverless-friendly.
+
+**Rails:** don't write the initializer by hand — run the generator:
+`bin/rails generate shipeasy:install` (add `--i18n` to also inject
+`<%= i18n_head_tags %>` into the app layout, `--no-poll` for serverless).
+
+→ More: `pages/installation.md` (per-framework setup + generator),
+`pages/configuration.md` (every option).
+
+## Evaluate (bound `Client.new(user)` — NO user arg)
+
+Bind the user once per request, then call without re-passing it — `track` and
+`log_exposure` are on the bound client too, so experiments are end-to-end here:
+
+```ruby
+flags = Shipeasy::Client.new(current_user)   # runs the attributes transform once
+
+flags.get_flag("new_checkout")               # bool; default: only when unresolved
+flags.get_config("button_color", default: "blue")
+flags.get_killswitch("payments")             # true = killed; optional switch_key
+result = flags.get_experiment("checkout_cta", { label: "Buy now" })
+# result.in_experiment / result.group / result.params
+
+flags.log_exposure("checkout_cta")           # at the decision point
+flags.track("purchase", { revenue: 49 })     # conversion / metric event
+```
+
+`get_flag_detail` returns a `FlagDetail` (`.value`, `.reason`: `RULE_MATCH`,
+`DEFAULT`, `OFF`, `OVERRIDE`, `FLAG_NOT_FOUND`, `CLIENT_NOT_READY`).
+
+→ More: pages `pages/flags.md` · `pages/configs.md` · `pages/killswitches.md`
+(incl. named switches) · `pages/experiments.md`. Snippets
+`snippets/release/{flags,configs,killswitches,experiments}.md` and
+`snippets/metrics/track.md`.
+
+## Testing (no network)
+
+Use the `configure` siblings — seed overrides, read through the same `Client`:
+
+```ruby
+Shipeasy.configure_for_testing(
+  flags:       { "new_checkout" => true },
+  configs:     { "billing_copy" => { "title" => "Welcome" } },
+  experiments: { "checkout_button" => ["treatment", { "color" => "green" }] },
+)
+Shipeasy::Client.new({ "user_id" => "u_123" }).get_flag("new_checkout") # => true
+
+# flip a value on the spot, mid-test:
+Shipeasy.override_flag("new_checkout", false)
+Shipeasy.clear_overrides
+```
+
+Offline (real rules from a snapshot / file):
+
+```ruby
+Shipeasy.configure_for_offline(path: "snapshot.json")
+# or snapshot: { "flags" => {...}, "experiments" => {...} }, plus optional overrides
+```
+
+→ More: `pages/testing.md` (override helpers + a working example
+`shipeasy-snapshot.json`).
+
+## OpenFeature
+
+```ruby
+require "open_feature/sdk"          # optional dep: gem "openfeature-sdk" (Ruby ≥ 3.4)
+require "shipeasy/sdk/openfeature"
+
+Shipeasy.configure { |c| c.api_key = ENV.fetch("SHIPEASY_SERVER_KEY"); c.poll = true }
+OpenFeature::SDK.configure { |c| c.set_provider(Shipeasy::OpenFeature::Provider.new) } # uses the global
+```
+
+Boolean → gate; string/number/object → config.
+
+→ More: `pages/openfeature.md` (reason mapping, type routing).
+
+## Error reporting — see()
+
+```ruby
+begin
+  charge_card(order)
+rescue => e
+  Shipeasy.see(e).causes_the("checkout").to("use the backup processor")
+end
+```
+
+`Shipeasy.see_violation(name)` for non-exception problems;
+`Shipeasy.control_flow_exception(e).because(...)` marks expected control flow
+(reports nothing).
+
+→ More: `pages/error-reporting.md` · snippets `snippets/ops/see.md`
+(`.extras`, violations, control-flow exceptions).
+
+## i18n (Rails)
+
+```erb
+<%= i18n_head_tags %>
+<h1><%= i18n_t("hero.title", name: current_user.name) %></h1>
+```
+
+Outside Rails: `Shipeasy.i18n_script_tag(client_key, profile: "en:prod")` emits
+the loader tag (public client key).
+
+→ More: `pages/i18n.md` · snippets `snippets/i18n/{setup,render}.md`.
+
+## Other surfaces
+
+- Anon bucketing: `Shipeasy::SDK::RackMiddleware` mints the shared `__se_anon_id`
+  cookie (Rails Railtie auto-mounts it); anonymous `get_flag` then just works.
+- `c.private_attributes = ["email"]` strips keys from outbound events.
+- `c.sticky_store = Shipeasy::SDK::InMemoryStickyStore.new` pins experiment assignment.
+- SSR: `Shipeasy.bootstrap_script_tag(user)` + `Shipeasy.i18n_script_tag(client_key, "en:prod")`.
+- `Shipeasy.on_change { ... }` (requires `c.poll = true`) fires after a poll fetches new data.
+
+→ More: `pages/advanced.md`.

data/lib/generators/shipeasy/install/USAGE

@@ -0,0 +1,24 @@
+Description:
+    Install Shipeasy into a Rails app. Creates the config/initializers/shipeasy.rb
+    initializer that calls `Shipeasy.configure` once at boot. With --i18n it also
+    sets the public client key and injects `<%= i18n_head_tags %>` into your
+    application layout's <head>.
+
+    The gem's Railties already auto-mount the anon-id Rack middleware and the i18n
+    view helpers, so this generator only creates what your app must own — the
+    initializer, the (optional) layout tag, and a reminder to set your keys.
+
+Example:
+    rails generate shipeasy:install
+
+        Creates:
+            config/initializers/shipeasy.rb   (server key + background poll)
+
+    rails generate shipeasy:install --i18n
+
+        Also sets the public client key in the initializer and injects
+        <%= i18n_head_tags %> into app/views/layouts/application.html.erb
+
+    rails generate shipeasy:install --no-poll
+
+        One-shot fetch instead of the background poll (serverless / Lambda).