rails_mind 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: '087e7d8cc40b60a6ed2ab02feb5ffac9f7a6f1592eac30c964b792482630349f'
+  data.tar.gz: 1f073cdb04f317e08a486b14361f12faf84ebfdd0c785c075436896eecbc720c
+SHA512:
+  metadata.gz: 95b65914e0d950384712582cb3f4b294e4a04a99ec62c42db53fe2252424932879940997815e7bc3fdaab51689866376cf42a9a3bafb107e2c66e9d335d38adc
+  data.tar.gz: 848479498910d94b0f73529eacddb16639f8364585dfef7687d4711229a560e6b1a0e25b5654506d69650ff136acb14f5416883b74a44d694708374c875fdd5b

data/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+## 0.1.0 — 2026-09-25
+
+Initial public release of the RailsMind client under the MIT license.
+
+- Collect Rails request, error, and ActiveJob telemetry with bounded buffering,
+  redaction, retries, and best-effort delivery.
+- Track explicit business events and propagate visitor, user, account, and trace
+  context through supported request and job integrations.
+- Integrate with existing Ahoy, Flipper, and OpenTelemetry installations, plus
+  an optional Ahoy/Turbo browser adapter.
+- Install with a Rails generator, inspect configuration with `rails_mind:doctor`,
+  and check ingestion with `rails_mind:verify`.
+- Default to `https://railsmind.com` and detect deployed Git revisions from
+  supported hosting metadata or a `REVISION` file.
+
+This is an early release. See [compatibility](docs/compatibility.md) and
+[delivery and privacy limits](docs/sdk.md#bounds-privacy-and-outages) before use.
+The separate hosted RailsMind service remains proprietary.

data/CONTRIBUTING.md

@@ -0,0 +1,81 @@
+# Developing RailsMind
+
+This repository owns the MIT-licensed client SDK, browser adapter, tests, and SDK
+documentation. The hosted RailsMind application and its internal integration
+sample are maintained separately and remain proprietary.
+
+## Setup
+
+Use Ruby 4.0.6 and Node 22 for the currently verified combination.
+
+```sh
+git clone https://github.com/cmartyn/rails_mind.git
+cd rails_mind
+bundle install
+bundle exec rake test
+node --test javascript/rails_mind.test.js
+bundle exec ruby script/package_smoke.rb
+```
+
+No database or hosted service is required for this repository's tests. See
+[compatibility](docs/compatibility.md) for coverage and limits.
+
+## Testing a development revision
+
+Applications normally install a released version from RubyGems.org. To evaluate
+an unreleased change, use a reviewed full commit SHA:
+
+```ruby
+gem "rails_mind", git: "https://github.com/cmartyn/rails_mind.git", ref: "<full commit SHA>"
+```
+
+Commit the application's lockfile and run its integration tests when upgrading.
+A local `path:` dependency can be used temporarily while developing both
+projects; do not commit that override. GitHub credentials are not required to
+read this public repository.
+
+## Packaging and releases
+
+`bundle exec ruby script/package_smoke.rb` builds a temporary gem and exercises its
+packaged installer and browser files. `bundle exec rake build` writes the gem to
+`pkg/`. Neither command publishes anything.
+
+Publishing uses [RubyGems trusted publishing](https://guides.rubygems.org/trusted-publishing/)
+from `.github/workflows/release.yml`, with no stored RubyGems API key. The gem's
+owner configures these values on RubyGems.org:
+
+| Field | Value |
+| --- | --- |
+| Gem name | `rails_mind` |
+| Repository owner | `cmartyn` |
+| Repository name | `rails_mind` |
+| Workflow filename | `release.yml` |
+| GitHub environment | `release` |
+
+For the first release, create a pending trusted publisher under the intended
+owner's RubyGems.org profile. A successful first push registers the gem and assigns
+that account ownership. The repository's `release` environment must allow release
+tags; configure required reviewers when additional approval is desired.
+
+Before releasing, update `lib/rails_mind/version.rb` and `CHANGELOG.md`, run the
+checks above, complete staging validation appropriate to the documented
+compatibility promise, and merge the release commit into `main`. Keep known
+limitations explicit; a passing unit test suite does not certify a deployed
+customer application.
+
+Create an annotated tag matching the gem version and push it:
+
+```sh
+git tag -a v0.1.0 -m "Release rails_mind 0.1.0"
+git push origin v0.1.0
+```
+
+The workflow verifies the tag/version, reruns the Ruby, JavaScript, and package
+checks, then publishes to RubyGems.org. Confirm the published version can be
+installed before announcing the release. Published version numbers cannot be
+reused; fixes need a new version.
+
+## Origin
+
+The SDK was extracted into its own repository on 2026-09-15. Its earlier history
+remains in the private application repository; only the client is licensed here.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 RailsMind contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,59 @@
+# RailsMind SDK
+
+The MIT-licensed Ruby client for [RailsMind](https://railsmind.com). One bounded
+collector for Rails requests, errors, jobs, Ahoy events, Flipper observations,
+and selected OpenTelemetry spans. Version 0.1.0 is an early release; see
+[compatibility and validation limits](docs/compatibility.md).
+
+```ruby
+gem "rails_mind", "~> 0.1.0"
+```
+
+Install from RubyGems.org and commit your application's `Gemfile.lock` to pin the
+resolved version. This repository contains the open-source client library. The
+hosted RailsMind service is a separate, proprietary application; its source is
+not included or licensed by this repository. See [development](CONTRIBUTING.md)
+and [release notes](CHANGELOG.md).
+
+```sh
+bundle install
+bin/rails generate rails_mind:install --plan
+bin/rails generate rails_mind:install
+bin/rails rails_mind:doctor
+```
+
+Set **`RAILS_MIND_KEY`** for the destination application environment. It is the only
+required setting; collection stays off without it. The endpoint defaults to
+`https://railsmind.com`. Release IDs are detected from hosting metadata or the
+app's deployed `REVISION` file; telemetry still works when none is available.
+`RAILS_MIND_ENDPOINT` and `RAILS_MIND_RELEASE` are optional overrides. See
+[configuration and release detection](docs/sdk.md#configuration-and-release-detection).
+
+After setting the key, run `bin/rails rails_mind:verify` on the app's
+server. Match its check ID in RailsMind **Setup** and wait for **Check processed**.
+Then visit the app to confirm real traffic. This command sends one labeled
+diagnostic check, consumes one event of quota, and leaves business/performance
+metrics alone. It requires a hosted app with installation-check support;
+`rails_mind:doctor` remains read-only. See the
+[verification guide](docs/sdk.md#verify-the-connection) for failure states
+and the limits of this check.
+
+```ruby
+RailsMind.with_context(user_id: current_user.id.to_s, account_id: current_account.id.to_s) do
+  RailsMind.track("Invoice paid", invoice_id: invoice.id, amount_cents: invoice.amount_cents)
+end
+```
+
+See [installation and privacy](docs/sdk.md) and [compatibility](docs/compatibility.md).
+
+Tests:
+
+```sh
+bundle install
+bundle exec rake test
+node --test javascript/rails_mind.test.js
+bundle exec ruby script/package_smoke.rb
+ruby script_benchmark.rb
+```
+
+Business/request/error events are unsampled, but delivery is best effort. Check `RailsMind.stats` for losses. The SDK does not guarantee durable business-event counts; use a transactional outbox when that is required.

data/docs/compatibility.md

@@ -0,0 +1,66 @@
+# Compatibility and dependency decisions
+
+Verified on 2026-09-14. Version numbers come from RubyGems release metadata and the actual installed libraries used in tests. The initial promise is narrow: coexistence with current versions, not importing historical data or replacing existing services.
+
+| Foundation | Verified version / license | Current coverage |
+| --- | --- | --- |
+| Ruby / Rails | 4.0.6 / 8.1.3.1; Ruby / MIT | Real Rails sample and notification/error/ActiveJob tests. Gem allows Ruby ≥3.3, Rails ≥7.2 and <9; older combinations are candidates, not yet certified. |
+| Ahoy | [5.5.0, MIT](https://rubygems.org/gems/ahoy_matey) | Actual custom store and mirror tests; default store data/return value preserved; stable IDs; no hosted-only analytics tables. |
+| Flipper | [1.4.2, MIT](https://rubygems.org/gems/flipper) | Actual group targeting and adapter identity preserved; ActiveSupport observation only. No managed flag mode. |
+| OpenTelemetry SDK | [1.13.0, Apache-2.0](https://rubygems.org/gems/opentelemetry-sdk) | Existing exporter/provider and sampler coexistence tested; sampled-out traces do not suppress errors/business events. |
+| OTel Rails components | [0.42.0 aggregate, Apache-2.0](https://rubygems.org/gems/opentelemetry-instrumentation-rails) | Sample selects Rack 0.31.1, ActionPack 0.18.1, ActionView 0.13.0, ActiveJob 0.13.0. Request/SQL/job telemetry through actual libraries. |
+| OTel PG / Net::HTTP | [0.37.0](https://rubygems.org/gems/opentelemetry-instrumentation-pg) / [0.29.0](https://rubygems.org/gems/opentelemetry-instrumentation-net_http), Apache-2.0 | PG statements omitted; exporter allowlist discards raw SQL/HTTP payloads. Net::HTTP auto-instrumentation installed in the sample; external HTTP service interaction not required for the demo. |
+| GoodJob | [4.19.2, MIT](https://rubygems.org/gems/good_job) | Hosted/sample backend; ActiveJob context integration. Sample uses inline execution, so multi-process GoodJob queue/retry behavior needs staging verification. |
+| Turbo | [turbo-rails 2.0.23, MIT](https://rubygems.org/gems/turbo-rails) | Browser adapter contract tests and a real Chromium navigation check cover visits, cached previews, back/forward restoration, Frames, repeat installation, late start, and explicit events. See the release verification below for scope. |
+| Other error reporters | Rails error interface; no mandatory SDK | Subscriber coexistence tested with a second subscriber. Sentry/Honeybadger/Bugsnag/Rollbar detection only; no vendor-specific version certification. |
+| Sidekiq, Solid Queue, Delayed Job | Detection only | ActiveJob jobs inherit the shared integration when used through Rails; backend-specific APIs/direct jobs are not covered. |
+| Bullet / Prosopite | Optional, deferred dependency | Use in development/isolated reproduction. No automatic production scans or forks. |
+| Field Test | Optional, deferred dependency | Detect installed version; no assignment/exposure/import or experiment analysis in this release. |
+
+Current Ahoy 5.5 and OTel 1.13 require Ruby ≥3.3. No integration gems are mandatory at SDK runtime beyond Rails and Net::HTTP. Customers select optional dependencies; the installer does not silently add them. MIT/Apache licenses allow this extension strategy without maintaining forks.
+
+The preferred foundations remain suitable for the pilot. Ahoy's store model provides a supported buffered-delivery seam but its database associations do not exist in hosted-only mode. Flipper's authoritative configuration remains in the customer's existing adapter; managed flags need an explicit future mode. OTel Ruby tracing supplies the useful mature signal here; broad metrics/logs/exporter parity is deliberately outside this prototype. [Ahoy store contract](https://github.com/ankane/ahoy#data-stores), [Flipper observation contract](https://www.flippercloud.io/docs/instrumentation), [OpenTelemetry Ruby](https://opentelemetry.io/docs/languages/ruby/).
+
+Tests are in `test` and browser lifecycle tests in `javascript`. Historical
+end-to-end Rails checks used a separate internal sample application that is not
+part of this public repository. Re-run the matrix when bumping dependencies.
+No external telemetry service, vendor account, historical migration, production
+overhead budget, or published gem installation has been verified by those checks.
+
+The local sample-to-hosted HTTP/GoodJob path was exercised with 101 accepted and processed events across all seven signal kinds, zero SDK losses, matched error/request account+trace correlation, and filtered credential probes. This verifies the local wire contract as well as isolated adapters; it does not certify a deployed customer application.
+
+## Run the checks
+
+```sh
+bundle install
+bundle exec rake test
+node --test javascript/rails_mind.test.js
+bundle exec ruby script/package_smoke.rb
+```
+
+CI runs Ruby 4.0.6 / Rails 8.1.3.1 on Linux, plus browser adapter contract tests
+on Node 22. The package smoke check builds and installs a gem in a temporary directory, loads that copy,
+and runs the installer against its packaged templates and browser adapter.
+The sample app remains in the hosted application's repository with its own lockfile.
+
+## 0.1.0 release verification
+
+Rechecked on 2026-09-25 with Ruby 4.0.6, the locked Rails 8.1.3.1 dependencies,
+and Node 22:
+
+- Ruby suite: 40 tests, 377 assertions, no failures or skips.
+- Browser adapter contract suite: 3 tests passed.
+- Built-gem installation smoke check: 2 tests, 13 assertions; the installed gem
+  loaded its own code, generator templates, and browser adapter.
+- A localhost fixture using the actual JavaScript distributed with
+  `turbo-rails` 2.0.23 passed in Chromium: initial load, repeated installation,
+  completed visits, cached previews, back/forward restoration, labeled and
+  unlabeled Frames, form navigation, explicit business outcomes, pageview
+  opt-out, stopping listeners, and late initialization. Cached previews and
+  Frame loads produced no extra pageviews; form navigation inferred no business
+  outcome. Ahoy was a recording stub, so this check validates browser lifecycle
+  behavior rather than Ahoy's server endpoint, cookies, or CSRF handling.
+
+These checks cover the client package and its documented integrations locally.
+They do not certify other browsers, every allowed Ruby/Rails combination,
+production delivery guarantees, or a deployed customer application's setup.

data/docs/sdk.md

@@ -0,0 +1,225 @@
+# Customer SDK
+
+The gem is `rails_mind`, namespace `RailsMind`. Install the MIT-licensed client
+from RubyGems.org and commit the application lockfile to retain the selected
+version. The hosted RailsMind service is a separate, proprietary application.
+Version 0.1.0 is an early release with the [documented compatibility limits](compatibility.md).
+
+## Install
+
+```ruby
+# Customer Gemfile
+gem "rails_mind", "~> 0.1.0"
+```
+
+```sh
+bundle install
+bin/rails generate rails_mind:install --plan
+bin/rails generate rails_mind:install
+bin/rails rails_mind:doctor
+```
+
+The plan inspects `Gemfile.lock` and prints selected versions, coexistence decisions, and missing options. Installation adds one initializer, preserves an existing initializer even with `--force`, and does not change migrations, dependencies, Ahoy stores, Flipper adapters, or OpenTelemetry providers. The doctor is read-only and does not contact the server or print credentials.
+
+## Configuration and release detection
+
+Set only the environment-scoped ingest key on the customer's server:
+
+```sh
+RAILS_MIND_KEY=<environment-scoped-credential>
+```
+
+The endpoint defaults to `https://railsmind.com`. To use a local or self-hosted
+RailsMind instance, set `RAILS_MIND_ENDPOINT` (for example,
+`http://127.0.0.1:3000`). An unset or whitespace-only override uses the hosted
+default. HTTPS is required except for localhost/loopback development. The key
+controls application/environment scope; never give it to browser JavaScript.
+Collection stays off without a nonblank key. `apm`, `errors`, `analytics`, and
+`flags` can each be disabled in the initializer.
+
+Release detection uses the first nonblank value in this order:
+
+1. `RAILS_MIND_RELEASE` — optional explicit override.
+2. `GIT_REVISION` — existing deployment convention.
+3. `RENDER_GIT_COMMIT` — [Render's automatic runtime commit](https://render.com/docs/environment-variables).
+4. `RAILWAY_GIT_COMMIT_SHA` — [Railway deployments triggered by GitHub](https://docs.railway.com/variables/reference).
+5. `HEROKU_BUILD_COMMIT`, then `HEROKU_SLUG_COMMIT` — [Heroku dyno metadata](https://devcenter.heroku.com/articles/dyno-metadata); metadata features must be enabled, and the slug variable is deprecated.
+6. `KAMAL_VERSION` — [Kamal's application-container version](https://github.com/basecamp/kamal/blob/master/lib/kamal/commands/app.rb), only when it is a full 40- or 64-character Git commit SHA.
+7. The `REVISION` file inside `Rails.root` — for [Hatchbox deployments](https://jumpstartrails.com/discussions/appsignal-deploy-tracking) and other deployers that write this file.
+
+Values are trimmed. The revision file is read once when configuration is created,
+with a 500-byte limit; absent, blank, oversized, unreadable, or invalidly encoded
+files are ignored. Detection does not run Git or inspect the working directory.
+If no release is available, it remains unset and telemetry is still delivered.
+Provider-specific metadata availability depends on the deployment type; there
+is no universal runtime variable. Build-only and instance-specific IDs are not
+used automatically. `HEROKU_RELEASE_VERSION`, arbitrary Kamal version labels,
+and [Fly.io's `FLY_IMAGE_REF`](https://fly.io/docs/machines/runtime-environment/)
+are also ignored: they can identify deployments or images rather than Git
+revisions, while Assist uses releases to locate the corresponding code. Explicit
+release overrides should identify a commit or ref in the connected repository. For DigitalOcean App Platform, commit metadata is a
+[bindable value](https://docs.digitalocean.com/products/app-platform/how-to/use-environment-variables/),
+not an automatically named runtime variable; optionally bind it to `GIT_REVISION`.
+
+Explicit `config.endpoint` and `config.release` assignments still take precedence.
+When upgrading an existing generated initializer, remove the old endpoint/release
+assignments that directly read `ENV` so they do not overwrite the new defaults
+with `nil` or bypass platform detection. The installer preserves existing files.
+The doctor reports whether the effective endpoint, key, and release are present,
+without printing credential values or contacting the server.
+
+## Verify the connection
+
+From the customer app's server, using the same environment settings as the running app:
+
+```sh
+bin/rails rails_mind:verify
+```
+
+This sends one labeled installation check through the SDK's redaction, collector,
+HTTP transport, and the normal ingestion queue. It prints a check ID and exits
+successfully only when delivery is confirmed without drops. It has a ten-second
+delivery deadline; a timeout can still mean the server received the check, so look
+for its ID before retrying. Credentials are never printed. `before_send` may
+suppress the check; changing its kind or ID is rejected. The optional signal
+switches do not disable this explicitly requested check.
+
+Open **Setup** in RailsMind, select the environment that owns the key, and match
+the ID under **Latest installation check**. **Check processed** confirms the path
+through the background worker. HTTP delivery alone does not confirm processing.
+Then visit a page in your app and confirm **Recent telemetry** under app activity:
+the command runs in its own process and cannot certify the configuration of an
+already-running web or job process.
+
+The check uses one event of the daily quota and expires with normal retention.
+Its dedicated `check` signal carries the SDK version without customer identity,
+trace, or release fields. It does not add business events, request measurements,
+errors, or releases. Update the hosted app and run its migrations before using
+this command with an older deployment that does not yet accept `check` signals.
+
+Setup refreshes connection health every five seconds while visible, without
+replacing unfinished setup forms. It shows active key use, first/latest retained
+event arrival, processing backlog, and app activity. Arrival times come from the
+server, so an old occurrence timestamp does not make a newly received event look
+undelivered. A pending event older than two minutes needs investigation; app
+traffic absent for fifteen minutes is shown as quiet, which may be normal.
+Installation checks do not reset the app-activity clock. The panel reports the
+environment's retained data, not lifetime history or SDK loss counters.
+
+If a check fails, inspect the endpoint, active key, outbound HTTPS, and daily
+quota. A delivered check missing from Setup may belong to a different environment.
+If it remains pending, the RailsMind operator should inspect the telemetry worker
+and failed jobs. Ingest keys remain write-only; viewing the confirmation requires
+a signed-in workspace member.
+
+## Identity and explicit outcomes
+
+```ruby
+# ApplicationController: a before_action inside the SDK request boundary.
+RailsMind.identify(
+  visitor_id: ahoy.visitor_token,
+  user_id: current_user&.id,
+  account_id: current_account&.id
+)
+
+# Record an outcome after it commits, or inside an application after_commit.
+RailsMind.track("Invoice paid", invoice_id: invoice.id, amount_cents: invoice.amount_cents)
+
+# Explicit reporting also works when the current trace is not retained.
+RailsMind.capture_exception(error, handled: true)
+```
+
+Context is fiber-local and restored around requests/jobs. `identify` replaces the three identity values, so call it with all available values; passing nil clears that value. Preserve Ahoy's visitor ID when a visitor logs in, and emit `$identify` through Ahoy authentication to connect later events. Account IDs represent the current tenant, never a guessed company from email. Logout/account switching must update identity; a new request starts clean. Historical anonymous events are not rewritten or merged across accounts by the SDK.
+
+ActiveJob serializes only the context identifier allowlist under `rails_mind_context`, then restores it while executing. Arguments are not inspected. This covers GoodJob through ActiveJob; direct Sidekiq jobs require a future explicit integration. Distributed trace propagation belongs to the existing OpenTelemetry library; choose ActiveJob `propagation_style: :child` for a linked trace tree when configuring a new provider.
+
+## Ahoy
+
+Ahoy's documented store extension points preserve existing `ahoy.track` calls. Choose one mode explicitly. [Ahoy custom stores](https://github.com/ankane/ahoy#data-stores).
+
+For an established installation, keep the current `Ahoy::Store` definition, storage, ID generator, user method, and cookies, then add this after its configuration:
+
+```ruby
+require "rails_mind/integrations/ahoy"
+RailsMind::Integrations.mirror_ahoy!(Ahoy::Store)
+```
+
+The existing store runs first with its original hash. Its return value and exceptions survive. RailsMind then mirrors visits/events/authentication without modifying the data. Repeated installation does not add another wrapper. Existing event IDs remain stable on transport retries; non-UUID Ahoy IDs map deterministically into UUIDv8 values.
+
+For a new hosted-only installation:
+
+```ruby
+require "rails_mind/integrations/ahoy"
+Ahoy.api = true # Only when using the optional browser adapter.
+Ahoy.geocode = false
+class Ahoy::Store < RailsMind::Integrations::AhoyStore
+end
+```
+
+This store requires no growing analytics tables. It does not offer database-backed `Ahoy::Visit` objects, `visitable` associations, geocoding storage, historical import, or cookie-free persisted visit lookup. Applications using those behaviors should keep their current store and mirror. Disable an existing duplicate pageview handler only as a deliberate customer configuration change.
+
+## OpenTelemetry
+
+Use selected tracing libraries, not `use_all`. The locally verified setup uses
+Rack, ActionPack, ActionView, ActiveJob, PG, and Net::HTTP, with PG configured as
+`db_statement: :omit`. Avoid additionally instrumenting the same SQL operation
+at both ActiveRecord and PG layers. The Rails aggregate instrumentation package
+loads component libraries; selecting only the Rails package itself does not
+activate the child integrations. Follow the public
+[Ruby instrumentation guide](https://opentelemetry.io/docs/languages/ruby/instrumentation/)
+and [PG instrumentation documentation](https://github.com/open-telemetry/opentelemetry-ruby-contrib/tree/main/instrumentation/pg)
+for your application's setup.
+
+An existing provider remains authoritative:
+
+```ruby
+# Run after your existing OpenTelemetry::SDK.configure block.
+require "rails_mind/integrations/open_telemetry"
+RailsMind::Integrations::OpenTelemetry.attach!
+```
+
+Attachment adds one idempotent processor; it does not replace the global provider, sampler, propagator, instrumentation, or other exporters. Its exporter only sanitizes and enqueues locally; the shared worker performs network I/O. Span context is attached at start so identity survives later export. Known safe attributes are allowlisted. Raw span names, exception span events, HTTP bodies/headers, SQL statements, and bind values are not exported to RailsMind. Existing third-party exporters retain their own behavior and privacy settings. [OpenTelemetry exporters](https://opentelemetry.io/docs/languages/ruby/exporters/).
+
+Request durations/counts and error reports come independently from Rails notifications/error reporting, even when detailed traces are sampled out. Request measurements cover controller actions, not assets/health checks rejected before ActionController or streaming-body completion. Repeated-query evidence contains only normalized-query hashes and counts; it is a suspicion, not proof of an N+1. Hash normalization handles common literals, not every SQL grammar. Use Bullet/Prosopite or an explicit query-bound test in development to verify fixes. No production object scans are installed.
+
+Jobs record duration, failure/retry/discard lifecycle, execution count, queue name, and enqueue-to-start delay where ActiveJob exposes it. Scheduled delay is included in the enqueue-to-start number. Signals do not include arguments. Full metrics/logs SDK integration is deferred; v0.1 computes hosted aggregates from unsampled request events and does not capture application logs.
+
+## Flipper and browser behavior
+
+The SDK subscribes to `feature_operation.flipper`. It observes names, operations, boolean results, and duration without changing adapters, groups, actors, rollout logic, or cache. Flipper's existing Rails instrumentation emits these events; applications with a custom instrumenter must deliberately opt into ActiveSupport notifications. Actor IDs are not collected. An evaluation is not experiment exposure. Managed flags and experiments are not implemented in this SDK. [Flipper instrumentation](https://www.flippercloud.io/docs/instrumentation).
+
+Run `bin/rails generate rails_mind:install --browser` to copy the optional module. Importmap users pin it, then pass their existing Ahoy instance:
+
+```javascript
+import ahoy from "ahoy"
+import { start } from "rails_mind"
+const analytics = start({ ahoy, frames: true })
+```
+
+Add `<meta name="rails-mind-page" content="Invoices#index">` to supply a stable page label. The adapter transmits no URL or query string. It counts the initial page and each completed Turbo visit once, ignores cached preview renders, and keeps `turbo:frame-load` as a separate `$frame_view` only for Frames with `data-analytics-frame`. It does not infer payment/signup success from forms or HTTP responses. Set `pageviews: false` if the application already counts pageviews. Repeated installation returns the same adapter. Browser delivery uses Ahoy's same-origin endpoint/cookies and existing CSRF policy; there is no browser ingestion credential. [Turbo events](https://turbo.hotwired.dev/reference/events).
+
+## Bounds, privacy, and outages
+
+Defaults are one lazy worker per process, 1,000 queued/in-flight events, 16 KiB per event, at most 100 events and 256 KiB per batch, and a two-second flush interval. Overflow drops the newest event. Retries retain the same encoded bytes/UUIDs; only HTTP 429, 5xx, and transient transport failures retry, at most three retries with bounded backoff. Other 4xx responses drop the batch. Redirects are not followed. Shutdown gets two seconds by default, then discards outstanding telemetry; forks start a fresh child queue rather than resending the parent's buffer.
+
+```ruby
+RailsMind.stats
+# => { enqueued:, delivered:, dropped:, retried:, queued:, in_flight:,
+#      losses: { "event.overflow" => 3, "error.delivery" => 1 } }
+RailsMind.flush(timeout: 2)
+```
+
+These are per-process counters. The doctor prints them for its process; inspect running app stats through your existing operational tooling. The hosted app does not currently receive loss counters. Request/business/error signals are unsampled, but process crashes, rejected payloads, redaction hooks, exhausted retries, or queue pressure can still undercount. This is best-effort monitoring, not an accounting ledger. A future transactional outbox can provide durable business-event delivery; the current implementation does not claim that guarantee.
+
+Redaction occurs before buffering and again after custom `before_send`. Sensitive property names are filtered, nesting/string/collection sizes are capped, emails and common credential forms are scrubbed, exception messages are omitted by default, and backtraces drop machine-home prefixes. Bodies, cookies, credentials, SQL binds, and job arguments are never selected by integrations. Arbitrary user-provided text may contain sensitive content that generic redaction cannot recognize: use small, explicitly reviewed business properties. Opting into exception messages requires reviewing `capture_exception_message` and your custom scrubbing policy.
+
+The final local synthetic burst benchmark on Ruby 4.0.6 processed 10,000 calls in 1.7612 seconds (176.12 μs/call), delivering all 10,000 with zero drops/retries at the 1,000-event queue bound. This measures local sanitization/enqueue with a no-op transport, not production request overhead or network delivery. Earlier runs did overflow; thread scheduling and downstream speed affect the result. Deterministic tests separately verify overflow losses and bounded shutdown during a hung transport. Run `ruby script_benchmark.rb` on the deployment hardware before setting a production budget.
+
+## Verified local pipeline
+
+On 2026-09-14 the real sample Rails application sent 101 events through this SDK's HTTP transport to the local hosted ingestion API; GoodJob processed all 101. They included 90 spans, 3 requests, 3 business events, 2 Flipper observations, 1 visit, 1 error, and 1 job. There were no collector drops or retries. The intentional error shared its request's trace and account IDs. Every request/business/error/flag/job event had account context; the visit and some early spans preceded identity and therefore did not. The list reported seven repeated queries. Credential-key privacy probes arrived as `[FILTERED]` without their secret values.
+
+This historical check used an internal sample application that is not included
+in the public client repository. To verify your own installation, follow
+[Verify the connection](#verify-the-connection). External hosted deployment and
+published-gem installation remain unverified by that historical check.

data/javascript/rails_mind.js

@@ -0,0 +1,49 @@
+// Uses the application's Ahoy endpoint/cookies. Never put the server token here.
+// Do not run alongside another automatic pageview handler.
+const installations = new WeakMap()
+
+export function start({ ahoy, document: doc = document, turbo = true, pageviews = true, frames = false,
+  page = () => doc.querySelector('meta[name="rails-mind-page"]')?.content || "page" } = {}) {
+  if (!ahoy || typeof ahoy.track !== "function") throw new TypeError("Pass the existing Ahoy instance")
+  if (installations.has(doc)) return installations.get(doc)
+  const listeners = []
+  let visit = 0
+  let trackedVisit = -1
+
+  function on(name, listener) {
+    doc.addEventListener(name, listener)
+    listeners.push([name, listener])
+  }
+
+  function trackPage() {
+    if (!pageviews || trackedVisit === visit || doc.documentElement.hasAttribute("data-turbo-preview")) return
+    trackedVisit = visit
+    ahoy.track("$pageview", { page: String(page()).slice(0, 160), navigation: turbo ? "turbo" : "document" })
+  }
+
+  if (turbo) {
+    on("turbo:visit", () => { visit += 1 })
+    on("turbo:load", trackPage)
+  } else {
+    on("DOMContentLoaded", trackPage)
+  }
+  // Supports loading the adapter after the initial page load, without duplicating
+  // a subsequent turbo:load for that same initial navigation.
+  if (doc.readyState === "complete") trackPage()
+
+  if (frames) on("turbo:frame-load", (event) => {
+    const label = event.target?.dataset?.analyticsFrame
+    if (label) ahoy.track("$frame_view", { frame: String(label).slice(0, 100), page: String(page()).slice(0, 160) })
+  })
+
+  const api = {
+    // The caller records a business outcome only after it actually succeeds.
+    track: (name, properties = {}) => ahoy.track(name, properties),
+    stop() {
+      listeners.forEach(([name, listener]) => doc.removeEventListener(name, listener))
+      installations.delete(doc)
+    }
+  }
+  installations.set(doc, api)
+  return api
+}

data/lib/generators/rails_mind/install/install_generator.rb

@@ -0,0 +1,37 @@
+require "rails/generators"
+require "rails_mind/diagnostic"
+
+module RailsMind
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+      class_option :plan, type: :boolean, default: false, desc: "Print the integration plan without writing files"
+      class_option :browser, type: :boolean, default: false, desc: "Copy the optional Ahoy/Turbo adapter without enabling it"
+
+      def inspect_application
+        say JSON.pretty_generate(Diagnostic.new(root: destination_root).report)
+      end
+
+      def add_initializer
+        return if options[:plan]
+        path = "config/initializers/rails_mind.rb"
+        if File.exist?(File.join(destination_root, path))
+          say_status :skip, "#{path} already exists", :yellow
+        else
+          template "initializer.rb.tt", path
+        end
+      end
+
+      def add_browser_adapter
+        return if options[:plan] || !options[:browser]
+        path = "app/javascript/rails_mind.js"
+        if File.exist?(File.join(destination_root, path))
+          say_status :skip, "#{path} already exists", :yellow
+        else
+          copy_file File.expand_path("../../../../javascript/rails_mind.js", __dir__), path
+        end
+        say "Pin rails_mind in importmap.rb and start it with your existing Ahoy instance. See docs/sdk.md."
+      end
+    end
+  end
+end

data/lib/generators/rails_mind/install/templates/initializer.rb.tt

@@ -0,0 +1,20 @@
+RailsMind.configure do |config|
+  config.token = ENV["RAILS_MIND_KEY"] # Environment-scoped server credential. Never expose to browsers.
+
+  # Endpoint defaults to https://railsmind.com; RAILS_MIND_ENDPOINT overrides it.
+  # Release is detected from hosting metadata or Rails.root/REVISION when available.
+  # RAILS_MIND_RELEASE is an optional override. Neither variable is required.
+
+  # Optional capabilities can be switched off independently.
+  # config.apm = false
+  # config.errors = false
+  # config.analytics = false
+  # config.flags = false
+
+  # Exception messages are omitted by default. Review before enabling.
+  # config.capture_exception_message = true
+  # config.before_send = ->(event) { event } # Return nil to drop an event.
+end
+
+# No existing Ahoy store, Flipper adapter, or OpenTelemetry provider is changed.
+# Run `bin/rails rails_mind:doctor` and follow docs/sdk.md for opt-in integrations.