railwatch 0.9.4 → 1.0.0

data/docs/faq.md

@@ -51,26 +51,25 @@ A second gate, `bench/no_db_writes.rb`, drives 200 requests and a job with
 a `sql.active_record` subscriber watching for any `INSERT`/`UPDATE`/
 `DELETE` issued from a frame inside `lib/railwatch`, and fails if it finds
 one. **Railwatch never writes to your application's database.** Records
-live in memory and are delivered by a background thread, to the cloud or
-to the embedded writer process, which owns its own two SQLite files. That
+live in memory and are delivered by a background thread over HTTP to the
+Railwatch server, which owns its own storage. That
 is not a nicety: instrumentation that takes a write lock is what turns a
 single-writer SQLite app into a "database is locked" incident.
 
 ## Where does the data go, and how long is it kept?
 
-Embedded (the default): into the app's own `railwatch_telemetry` SQLite
-database under `storage/`, written by one writer process Puma forks.
-Raw rows are pruned nightly to `retention_days` (7 by default), and
-hourly rollups back the charts. Nothing leaves the machine unless you
-turn on export. See [Embedded mode](embedded.md).
+One gzip-NDJSON POST to `{ingest_url}/ingest` per batch, to Railwatch
+Cloud, a self-hosted railwatch-rs, or the server the `railwatch-server`
+gem runs next to the app. The gem keeps nothing on disk itself.
 
-Railwatch Cloud: one gzip-NDJSON POST to `{ingest_url}/ingest` per
-batch. The platform stores each monitored environment's telemetry in its
+Railwatch Cloud stores each monitored environment's telemetry in its
 own database, prunes raw rows on a retention window, and keeps hourly
 rollups for the charts. Retention there is set by the account's plan
-tier, not by the gem — 7, 30, or 90 days depending on the plan. For a
-self-hosted platform, retention, backups, and pruning are the operator's
-responsibility.
+tier, not by the gem — 7, 30, or 90 days depending on the plan. For
+railwatch-rs, self-hosted or through railwatch-server, retention and
+backups are server settings
+([railwatch-rs SELF-HOST.md](https://github.com/Rebulk/railwatch-rs/blob/main/docs/SELF-HOST.md),
+[railwatch-server README](https://github.com/Rebulk/railwatch-server#readme)).
 
 ## What about PII?
 
@@ -125,15 +124,13 @@ Yes, on both sides, and it's the first-class target.
 
 **In your app:** the gem does no I/O on the request path and never writes
 to the app database, so there is no contention with SQLite's single
-writer. Embedded mode's own two databases are separate SQLite files,
-whatever the app runs on. SQL normalization is per adapter, so SQLite,
+writer. SQL normalization is per adapter, so SQLite,
 Postgres, MySQL, and Trilogy all group correctly.
 
-**On the platform:** telemetry is stored one SQLite database per
-monitored environment. That is what makes retention pruning, backup, and
-restore per-environment operations rather than one enormous table, and
-it's why log search gets FTS5 with snippet highlighting. The platform
-runs unchanged on Postgres if that's what's configured.
+**On the server:** telemetry is stored in SQLite per monitored
+environment. That is what makes retention pruning, backup, and restore
+per-environment operations rather than one enormous table, and it's why
+log search gets FTS5 with snippet highlighting.
 
 ## One database per environment — what does that mean for me?
 
@@ -168,12 +165,7 @@ Two features are Solid Queue-specific, because they read its tables:
 with `task_key`, `schedule`, and `drift`) and the queue depth and
 oldest-job age on `health` records.
 
-## What happens when the platform is unreachable?
-
-This section is about the cloud transport. In embedded mode the
-equivalent is the writer process being down, covered in
-[Embedded mode](embedded.md#the-writer-process), and export keeps its
-own durable queue.
+## What happens when the server is unreachable?
 
 Nothing, from your app's point of view. This is the property everything
 else is built around: **delivery never raises into application code.**

data/docs/getting-started.md

@@ -1,8 +1,19 @@
 # Getting started
 
-Two commands on a Rails 8 app, then a dashboard at `/railwatch`.
-Everything below is the gem's own generator and rake tasks; nothing else
-has to be wired by hand.
+Two commands on a Rails 8 app, a token, and the app reports to
+Railwatch. Everything below is the gem's own generator and rake tasks;
+nothing else has to be wired by hand.
+
+The `railwatch` gem is the agent: it instruments the app and sends what
+it records over HTTPS to a Railwatch server. The server is one of:
+
+- **Railwatch Cloud** at <https://railwatch.rebulk.com>, the default.
+- **Your own [railwatch-rs](https://github.com/Rebulk/railwatch-rs)**,
+  one static binary that serves many apps
+  ([Self-hosting](self-hosting.md)).
+- **The [`railwatch-server`](https://github.com/Rebulk/railwatch-server)
+  gem**, which runs railwatch-rs next to Puma for this one app and serves
+  the dashboard at `/railwatch` ([below](#embedded-railwatch-server)).
 
 ## Install
 
@@ -14,89 +25,6 @@ bin/rails generate railwatch:install
 The gem, its Ruby namespace, and its require path share one name:
 `railwatch`, `Railwatch::*`, `require "railwatch"`.
 
-With no flags the install is [embedded](embedded.md): telemetry stays in
-two SQLite databases the app owns, Puma forks one writer process for
-them (`plugin :railwatch` in `config/puma.rb`), and the dashboard is
-served from the app. No token, no cloud, no job worker. The generator
-creates and migrates both databases before it returns. On a PostgreSQL
-or MySQL app without the `sqlite3` gem it adds the gem instead; run
-`bundle install` and `bin/rails db:prepare` to finish.
-
-Restart the app and open `/railwatch`. In development it is open; every
-other environment answers 401 until you give it a password:
-
-```sh
-RAILS_ENV=production bin/rails railwatch:authentication:configure
-```
-
-[Embedded mode](embedded.md#authentication) covers using your own
-admin authentication instead.
-
-### What the generator writes
-
-In every mode:
-
-- `config/initializers/railwatch.rb`, with every option commented out at
-  its default (embedded: `c.transport = :local`).
-- `mount Railwatch::Engine, at: "/railwatch"` in `config/routes.rb`: the
-  embedded dashboard and the beacon endpoint the browser client posts to.
-- `.kamal/hooks/post-deploy` — only if `config/deploy.yml` already
-  exists.
-- `app/frontend/lib/railwatch.ts` plus the `startRailwatch()` call in your
-  Inertia entrypoint — only if `app/frontend/` exists. If it can't find
-  an entrypoint it prints the two lines to add.
-- `require "railwatch/rspec"` in `spec/rails_helper.rb`, or
-  `require "railwatch/minitest"` in `test/test_helper.rb`.
-
-Embedded adds the two databases to `config/database.yml` and the Puma
-plugin line; see [Embedded mode](embedded.md#your-applications-own-database).
-
-### Check the wiring
-
-```sh
-bin/rails railwatch:doctor
-```
-
-With the app running, the embedded checklist starts like this:
-
-```
-✓ transport: local (telemetry stays in this app; dashboard at the engine mount)
-✓ railwatch database: storage/development_railwatch.sqlite3
-✓ railwatch_telemetry database: storage/development_railwatch_telemetry.sqlite3
-✓ railwatch_telemetry migrations: up to date
-✓ railwatch migrations: up to date
-✓ telemetry disk: auto_vacuum=incremental; the nightly prune returns freed pages
-✓ writer process: listening at /app/tmp/sockets/railwatch-writer.sock
-✓ last write: 12 seconds ago
-✓ dashboard access: open in development. Production stays closed until you run `RAILS_ENV=production bin/rails railwatch:authentication:configure`
-✓ request middleware: Railwatch::Middleware::Request at position 0
-✓ engine mounted: POST /railwatch/beacon -> railwatch/beacon#create
-```
-
-With the app stopped, `writer process` and `maintenance` are `✗`, and say
-so. Every line and what to do about a `✗` is in
-[`troubleshooting.md`](troubleshooting.md).
-
-### Adding Railwatch Cloud
-
-Railwatch Cloud delivers alerts to Slack, email, webhooks or Linear
-(embedded mode only records them), serves the [MCP server](ai-and-mcp.md)
-to your AI assistant, and puts many apps and servers in one place. An
-embedded install can mirror every record to it and keep `/railwatch`:
-set a token ([below](#where-the-token-comes-from)) and
-`c.export_enabled = true`. See
-[Embedded mode](embedded.md#three-ways-to-run-it).
-
-## Railwatch Cloud instead
-
-To send telemetry only to Railwatch Cloud, with no local databases, run
-the same generator with `--cloud`:
-
-```sh
-bundle add railwatch
-bin/rails generate railwatch:install --cloud
-```
-
 With the token already in hand, let the generator read it without placing the
 secret in shell history or process arguments:
 
@@ -109,25 +37,34 @@ bin/rails generate railwatch:install \
 
 - `--prompt-token` reads without echo. `--token-stdin` is available for a
   secret-manager pipe; an already exported `RAILWATCH_TOKEN` is also detected.
-- Any of `--prompt-token`, `--token-stdin`, `--url=` and `--kamal-secrets`
-  means the cloud, so none of them needs `--cloud` as well. An exported
-  `RAILWATCH_TOKEN` on its own does not: without one of these flags the
-  install is embedded.
 - A token is written to `.env` only when Git confirms that `.env` is ignored.
   A tracked or non-ignored dotenv file is refused; use Rails credentials, a
   deployment secret manager, or add `.env` to `.gitignore` first. Token values
   are never printed by the generator.
-- `--url=` sets `RAILWATCH_INGEST_URL`, for a self-hosted platform. Leave
+- `--url=` sets `RAILWATCH_INGEST_URL`, for a self-hosted server. Leave
   it off to use the default, `https://railwatch.rebulk.com`.
 - `--kamal-secrets` appends `RAILWATCH_TOKEN=$RAILWATCH_TOKEN` to
   `.kamal/secrets` and adds `RAILWATCH_TOKEN` under `env: secret:` in
   `config/deploy.yml`, which is the pair of edits Kamal needs to pass a
   secret through to the containers.
+- `--no-doctor` skips the `railwatch:doctor` run at the end.
 
-It writes the same files as the embedded install
-([above](#what-the-generator-writes)) minus the databases and the Puma
-plugin, and finishes by running `railwatch:doctor`, so the install either
-ends in a clean checklist or tells you what is still missing.
+### What the generator writes
+
+- `config/initializers/railwatch.rb`, with every option commented out at
+  its default.
+- `mount Railwatch::Engine, at: "/railwatch"` in `config/routes.rb`: the
+  beacon endpoint the browser client posts to (`POST /railwatch/beacon`).
+- `.kamal/hooks/post-deploy` — only if `config/deploy.yml` already
+  exists.
+- `app/frontend/lib/railwatch.ts` plus the `startRailwatch()` call in your
+  Inertia entrypoint — only if `app/frontend/` exists. If it can't find
+  an entrypoint it prints the two lines to add.
+- `require "railwatch/rspec"` in `spec/rails_helper.rb`, or
+  `require "railwatch/minitest"` in `test/test_helper.rb`.
+
+It finishes by running `railwatch:doctor`, so the install either ends in
+a clean checklist or tells you what is still missing.
 
 ### Where the token comes from
 
@@ -135,18 +72,18 @@ In Railwatch Cloud, create an application, then an environment inside it
 (`production`, `staging`, one token each). The token is shown once, on
 the page you land on right after creating the environment — copy it
 then. If you lose it, rotate it from the environment's settings and
-update `RAILWATCH_TOKEN`.
+update `RAILWATCH_TOKEN`. A self-hosted railwatch-rs creates tokens the
+same way (or with `railwatch env create`; see its docs).
 
 ```sh
 bin/rails railwatch:token   # prints the URL to create/copy a token
 ```
 
-A token looks like `rw_` followed by 40 characters. A cloud install is
-inert without one: with `transport = :http`, `Railwatch.enabled?` is
-`config.enabled && token.present?`, so an app with no token installs no
-subscribers and ships nothing.
+A token looks like `rw_` followed by 40 characters. The gem is inert
+without one: `Railwatch.enabled?` is `config.enabled && token.present?`,
+so an app with no token installs no subscribers and ships nothing.
 
-### Check the cloud wiring
+### Check the wiring
 
 ```sh
 bin/rails railwatch:doctor
@@ -169,11 +106,67 @@ It exits non-zero on three lines: `token` (missing), `token storage`
 (a plaintext token in a tracked file), and `ingest reachable`. The rest
 of the checklist is informational. Run it after the token is in place:
 `ingest reachable` sends the token, so a missing or wrong token makes
-the platform answer 401 and that line is `✗` as well.
+the server answer 401 and that line is `✗` as well. Every line and what
+to do about a `✗` is in [`troubleshooting.md`](troubleshooting.md).
 
 `bin/rails railwatch:status` is the one-line version: it pings
 `{ingest_url}/ingest/ping` and prints the ingest URL, deploy, and server.
 
+## Embedded: railwatch-server
+
+To keep telemetry inside the app instead, add the
+[`railwatch-server`](https://github.com/Rebulk/railwatch-server) gem
+next to this one. It bundles the railwatch-rs binary for your platform,
+runs it as its own process beside Puma, and points this agent at it:
+
+```ruby
+# Gemfile
+gem "railwatch"
+gem "railwatch-server"
+```
+
+```ruby
+# config/puma.rb
+plugin :railwatch_server
+```
+
+On first boot it provisions `storage/railwatch/<env>` and sets the
+agent's token and ingest URL itself, so no `RAILWATCH_TOKEN` is needed.
+When `RAILWATCH_TOKEN` is set, it leaves the agent alone and only serves
+the dashboard. The dashboard at `/railwatch` is behind this gem's gate
+settings: HTTP Basic, on and closed (401) until credentials exist, except
+in development when none are configured:
+
+```sh
+RAILS_ENV=production bin/rails railwatch:authentication:configure
+```
+
+To use your own admin authentication instead, turn Basic off and name a
+base controller ([Configuration](configuration.md#dashboard-gate-railwatch-server)).
+Everything else about it (ports, data directory, email, backups) is in
+the [railwatch-server README](https://github.com/Rebulk/railwatch-server#readme).
+
+### Coming from 0.x embedded mode
+
+Railwatch 0.x could keep telemetry in two SQLite databases of the app's
+own, written by a Puma writer process, with the dashboard served from the
+gem. 1.0 removes that mode. To move:
+
+1. Remove `c.transport = :local` (or `RAILWATCH_TRANSPORT=local`) from
+   the initializer and environment.
+2. Remove `plugin :railwatch` from `config/puma.rb`. Puma refuses to boot
+   with a plugin it cannot find.
+3. Remove the `railwatch` and `railwatch_telemetry` entries from
+   `config/database.yml`.
+4. Add `railwatch-server` as above, or point the app at Railwatch Cloud
+   or a self-hosted railwatch-rs.
+
+The old files (`storage/<env>_railwatch.sqlite3`,
+`storage/<env>_railwatch_telemetry.sqlite3`) are not migrated, and
+railwatch-rs has no import for them: its `railwatch import-rails` reads a
+Railwatch Cloud (Rails) install, not these files. History starts again
+in the new server. Delete the files once you no longer want them.
+
 ## Make one request
 
 ```sh
@@ -183,8 +176,9 @@ curl http://localhost:3000/
 
 Records are batched in-process and flushed every `flush_interval`
 (2 seconds by default) or every 500 records, whichever comes first, so
-the request shows up on the **Requests** page (`/railwatch`, or the
-environment in Railwatch Cloud) a couple of seconds after you make it —
+the request shows up on the **Requests** page (the environment in
+Railwatch Cloud or your own server, or `/railwatch` with
+railwatch-server) a couple of seconds after you make it —
 with its queries, cache reads, view renders, and log lines already
 attached to it.
 
@@ -266,14 +260,11 @@ up, on the account.
 
 ## Deploying
 
-An embedded install deploys like the rest of the app: the two databases
-are files under `storage/`, which the Rails 8 Kamal template already
-mounts as a volume, and the Rails 8 Docker entrypoint's
-`bin/rails db:prepare` migrates them. Give the
-dashboard a password first ([Install](#install)). For deploy markers
-from the Kamal hook, set `RAILWATCH_TRANSPORT=local` in the deployer's
-environment ([Embedded mode](embedded.md#deploys)). The token steps
-below are for a cloud install or export.
+With railwatch-server, the server's data lives under
+`storage/railwatch/<env>`, which has to be on a volume that survives
+deploys (the Rails 8 Kamal template mounts `storage/`); its README covers
+deploys and two containers sharing a volume. The token steps below are
+for Railwatch Cloud or a self-hosted server.
 
 ### Kamal
 
@@ -352,12 +343,9 @@ one — the deploy is still recorded.
   `sentry-rails`.
 - [`replacing-nightwatch.md`](replacing-nightwatch.md) — for people
   coming from Laravel.
-- [`embedded.md`](embedded.md) — authentication, the writer process,
-  maintenance, disk, and export to the cloud.
 - [`self-hosting.md`](self-hosting.md) — pointing the gem at your own
-  platform install.
+  railwatch-rs server.
 - [`troubleshooting.md`](troubleshooting.md) — every `railwatch:doctor`
   line and what a failure means.
 - [`faq.md`](faq.md) — overhead, retention, PII, unreachable platform.
-- [`ai-and-mcp.md`](ai-and-mcp.md) — asking an AI assistant what broke
-  (Railwatch Cloud).
+- [`ai-and-mcp.md`](ai-and-mcp.md) — asking an AI assistant what broke.

data/docs/replacing-nightwatch.md

@@ -3,10 +3,11 @@
 Railwatch is the same product shape for Rails: one package instruments the
 framework end to end, records are grouped under the execution that
 produced them, and a dashboard turns them into routes, jobs, queries,
-issues, and alerts. Unlike Nightwatch, that dashboard runs inside your
-app by default ([embedded mode](embedded.md)); Railwatch Cloud is the
-hosted option. If you know Nightwatch, you already know how to read
-Railwatch — this page maps the vocabulary and points out the three
+issues, and alerts. Railwatch Cloud is the hosted option; unlike
+Nightwatch, the server can also be self-hosted
+([railwatch-rs](self-hosting.md)) or run inside your app with the
+[`railwatch-server`](getting-started.md#embedded-railwatch-server) gem.
+If you know Nightwatch, you already know how to read Railwatch — this page maps the vocabulary and points out the three
 places the Rails answer is genuinely different.
 
 Railwatch is an independent product and is not affiliated with Laravel or
@@ -21,8 +22,8 @@ separate daemon POSTs them.
 Puma and Solid Queue workers *are* long-lived, so Railwatch skips that
 tier. A single reporter thread per process holds a bounded buffer
 (16 MiB and 10,000 records by default, oldest dropped and counted) and
-flushes batches every 2 seconds or every 500 records: to the embedded
-writer process Puma forks, or as gzip-NDJSON POSTs to Railwatch Cloud.
+flushes batches every 2 seconds or every 500 records, as gzip-NDJSON
+POSTs to the Railwatch server.
 There is no daemon to install, supervise, or forget to restart.
 
 The thread is re-armed after `fork`, so clustered Puma workers and
@@ -184,7 +185,7 @@ every setting still has an env var — `NIGHTWATCH_*` becomes `RAILWATCH_*`.
 | `nightwatch:agent` | Nothing — the reporter thread lives in the app process. |
 | `nightwatch:status` | `bin/rails railwatch:status` |
 | `nightwatch:deploy {deploy} --ref --name --url` | `bin/rails railwatch:deploy[ref,name,url]`, or the generated `.kamal/hooks/post-deploy` |
-| — | `bin/rails railwatch:doctor`, which checks the whole install and exits non-zero if the embedded databases, the token, or the ingest host is wrong |
+| — | `bin/rails railwatch:doctor`, which checks the whole install and exits non-zero if the token or the ingest host is wrong |
 
 ## The three things worth knowing about Rails
 

data/docs/replacing-sentry.md

@@ -8,10 +8,9 @@ depends on a conditional row.
 
 Install Railwatch first ([`getting-started.md`](getting-started.md)); you
 can run both for a day if you want to compare, since neither knows about
-the other. The default install is embedded, with the dashboard at
-`/railwatch` and no token. The token and alert steps below apply when
-you send to Railwatch Cloud, either as a cloud install or by exporting
-from embedded.
+the other. The token steps below apply to Railwatch Cloud and to a
+self-hosted railwatch-rs; with the `railwatch-server` gem the token is
+set for you.
 
 ## Decide whether Railwatch covers your workload
 
@@ -33,7 +32,7 @@ Railwatch does not claim those broader capabilities.
 | Ruby profiling | Conditional | Requires `vernier` or `stackprof`; there is no profiler bundled into the SDK. |
 | Browser monitoring | Partial | The optional Inertia client reports visits, Web Vitals, browser errors, and breadcrumbs. Session Replay, native/mobile SDKs, and Sentry's full browser/source-map workflow are outside the currently released Rails-server replacement. |
 | Runtime compatibility | Narrow today | The currently proved pair is Ruby 3.4 + Rails 8.1. A maintained compatibility matrix and any safe lowering of requirements are tracked by [#26](https://github.com/Rebulk/railwatch/issues/26). |
-| Managed integrations and operations | Partial | Railwatch Cloud delivers alerts to email, Slack, webhooks and Linear, plus self-hosting; embedded mode records alerts without delivering them. It does not promise Sentry's broader integration catalog. |
+| Managed integrations and operations | Partial | Railwatch Cloud and railwatch-rs deliver alerts to email, Slack, webhooks and Linear. It does not promise Sentry's broader integration catalog. |
 | SQL value privacy | Supported by default | Query records carry normalized SQL shapes without literal values, and Active Record binds are never sent. Raw SQL and query plans are separate opt-ins; either can contain values. |
 
 For a Rails 8.1 application whose work enters through Rack and Active Job,
@@ -73,11 +72,10 @@ deploy config once the app boots without it.
 `config/initializers/railwatch.rb` (written by the install generator) is
 where every option from `Sentry.init` lands. The mapping:
 
-- **`dsn:`** has no equivalent in embedded mode, which stores telemetry in
-  the app. For Railwatch Cloud it becomes `RAILWATCH_TOKEN`, one token per
-  environment, created in Railwatch Cloud. Self-hosting adds
-  `RAILWATCH_INGEST_URL`. On a cloud install the token is also the on/off
-  switch: with it blank, Railwatch installs nothing.
+- **`dsn:`** becomes `RAILWATCH_TOKEN`, one token per environment,
+  created in Railwatch Cloud or your own server. Self-hosting adds
+  `RAILWATCH_INGEST_URL`. The token is also the on/off switch: with it
+  blank, Railwatch installs nothing.
 - **`environment:`** becomes `c.environment`, which defaults to
   `Rails.env` — set it only to report under a different name.
 - **`release:`** becomes `c.deploy`, which auto-detects the release from
@@ -116,9 +114,7 @@ where every option from `Sentry.init` lands. The mapping:
 - **Rack `X-Request-Start` queue time** needs no setting: it is parsed
   into `queue_time` on every `request` record.
 
-A worked initializer for a cloud install, roughly what a `Sentry.init`
-block turns into (an embedded install has `c.transport = :local` instead
-of the token):
+A worked initializer, roughly what a `Sentry.init` block turns into:
 
 ```ruby
 # config/initializers/railwatch.rb
@@ -424,7 +420,7 @@ startRailwatch({
 |---|---|
 | `Sentry.init({ dsn })` | `startRailwatch()`. There is no DSN: the beacon posts to the app's own origin and the *server* decides whether to record it (`c.beacon_enabled`, and whether Railwatch is enabled). The gate you already have on whether `startRailwatch()` runs at all is the only gate. |
 | `release` | Automatic. The record is stamped with `c.deploy`, the same release the server records carry, so a browser issue and a server issue from one deploy line up without a matching pair of settings to get wrong. |
-| `environment` | Automatic — the embedded databases belong to one environment, and on Railwatch Cloud the ingest token identifies it. |
+| `environment` | Automatic — the ingest token identifies the environment. |
 | `ignoreErrors` | `startRailwatch({ ignoreErrors })`. Strings match anywhere in the message; regexes are tested against it. Both `ResizeObserver` messages are ignored by default. |
 | `denyUrls` | `startRailwatch({ denyUrls })`, matched against the top stack frame's URL. `/extensions\//i`, `/^chrome:\/\//i`, and `/^moz-extension:\/\//i` are denied by default, **and** any frame from an origin that isn't the app's own is dropped — extensions, injected widgets, tag managers. |
 | `Sentry.setUser` | Server-side. The beacon is a same-origin POST carrying the session cookie, so the server resolves the user the same way it does for a request (`Railwatch.user`) when `Current.user` or Warden is set by middleware; an app that authenticates in a `before_action` gives Railwatch the same lookup with `c.beacon_user { \|request\| ... }`. Nothing the browser sends names the user, so it cannot be forged. |
@@ -568,10 +564,10 @@ hook matching `rails runner …` previews, or `sentry_runner_noise.rb` under
 | Inertia visit timing | Real browser page-visit duration, prop byte size, partial reloads, SSR time, and Core Web Vitals, from a client the generator installs. |
 | Spec matchers as a CI gate | `have_railwatch_queries`, `have_railwatch_n_plus_one`, `have_railwatch_outgoing_requests` fail the pull request that regresses a hot path. |
 | Zero app-DB writes | The gem holds records in memory and ships them from a background thread; a bench gate asserts no `INSERT`/`UPDATE`/`DELETE` ever originates in `lib/railwatch`. This is why it is safe on single-writer SQLite. |
-| A dashboard inside the app | The default install serves the whole dashboard at `/railwatch` from two SQLite files the app owns, with no hosted service at all ([`embedded.md`](embedded.md)). |
+| A dashboard inside the app | The `railwatch-server` gem runs the server next to Puma and serves the whole dashboard at `/railwatch`, with no hosted service at all ([Getting started](getting-started.md#embedded-railwatch-server)). |
 | One SQLite database per environment | Railwatch Cloud stores each monitored environment's telemetry in its own database file, which makes retention pruning, backup, and restore per-environment operations. |
 | LLM calls | RubyLLM calls are recorded with tokens, cost, finish reason, tool calls and workflows, in the request or job that made them ([`records.md`](records.md#llm_call)). |
-| An MCP server | With Railwatch Cloud, AI assistants can ask what broke after the last deploy, list slow routes, read an execution's timeline, and search logs ([`ai-and-mcp.md`](ai-and-mcp.md)). |
+| An MCP server | AI assistants can ask what broke after the last deploy, list slow routes, read an execution's timeline, and search logs ([`ai-and-mcp.md`](ai-and-mcp.md)). |
 
 ## See also
 

data/docs/security.md

@@ -3,25 +3,20 @@
 This review covers the open-source gem that runs in a customer's Rails
 application. Railwatch Cloud is a separate service and is outside this review.
 
-## Embedded dashboard
-
-In embedded mode (the installer's default) the gem also serves a dashboard at
-the engine's mount, showing every query, log line and exception the app
-recorded. HTTP Basic authentication is on by default. With no credentials
-configured, every dashboard request is 401 in every environment except
-development, where it is open; the app logs a warning at boot outside
-development, and `railwatch:doctor` reports the gate. Credentials, once set,
-apply in development too. An app that turns Basic off gates pages with its own
-`base_controller_class` or a routes constraint; live updates over Action Cable
-are refused unless Basic, a `dashboard_user` resolver, or `dashboard_open`
-authorizes them. See [Embedded mode](embedded.md#authentication).
-
-The writer socket that web workers hand batches to is created with a 0700
-directory and a 0600 socket, so only the app's own user can connect.
+## Dashboard gate (railwatch-server)
+
+The gem serves no dashboard. With the separate `railwatch-server` gem
+installed, a dashboard showing every query, log line and exception the app
+recorded is proxied at `/railwatch`, and its gate is this gem's settings.
+HTTP Basic authentication is on by default. With no credentials configured,
+every dashboard request is 401 in every environment except development,
+where it is open. Credentials, once set, apply in development too. An app
+that turns Basic off gates the dashboard with its own `base_controller_class`,
+which railwatch-server's proxy controller inherits from. See
+[Configuration](configuration.md#dashboard-gate-railwatch-server).
 
 ## Transport
 
-This applies to a cloud install and to export from an embedded install.
 `Railwatch::Transport::Http` sends gzip NDJSON with `Net::HTTP`. HTTPS explicitly
 sets OpenSSL's `VERIFY_PEER`; a spec pins that setting. The transport does not
 implement redirect handling, so a redirect response is treated as a permanent
@@ -52,8 +47,7 @@ configuration and record specs:
   filtered. `Locals.inspect_value` rescues an `inspect` implementation that
   raises; this behavior is covered by an exception-record spec.
 - `capture_exception_source` is true. Source lines surrounding in-application
-  backtrace frames are recorded, and sent to Railwatch Cloud when the install
-  reports or exports there. Disable it if source context is outside the
+  backtrace frames are recorded and sent to the configured server. Disable it if source context is outside the
   application's telemetry policy.
 
 Log record messages are sent exactly as supplied to `Rails.logger`. Railwatch
@@ -107,8 +101,8 @@ application/deployment secret and must not be committed.
   application-specific credentials and personal data.
 - Keep secrets out of exception messages, log text, source files, tenant ids,
   user resolvers, and custom context.
-- In embedded mode, set dashboard credentials (or your own gate) before
-  deploying; see [Embedded mode](embedded.md#authentication).
+- With railwatch-server, set dashboard credentials (or your own gate) before
+  deploying; see [Configuration](configuration.md#dashboard-gate-railwatch-server).
 - Use HTTPS in production and keep TLS verification enabled.
 - Put a request-body limit at the reverse proxy when the public beacon is
   enabled, and choose a shared cache if rate limits must span processes.

data/docs/self-hosting.md

@@ -1,14 +1,22 @@
 # Self-hosting
 
-This page is for sending telemetry to a Railwatch Cloud you run
-yourself. An [embedded](embedded.md) install keeps everything inside
-your app and needs none of it.
+This page is for sending telemetry to a Railwatch server you run
+yourself instead of Railwatch Cloud.
 
-Railwatch Cloud is a Rails app you can run yourself. The gem doesn't care
-which install it talks to — point it at yours and everything works the
-same.
+The self-hosted server is [railwatch-rs](https://github.com/Rebulk/railwatch-rs)
+(AGPL-3.0): one static binary on SQLite that serves many apps, with the
+same dashboard, alerts, MCP server and JSON API as Railwatch Cloud. Its
+install, configuration, backups and upgrades are documented in its
+[SELF-HOST.md](https://github.com/Rebulk/railwatch-rs/blob/main/docs/SELF-HOST.md).
+The gem doesn't care which server it talks to — point it at yours and
+everything works the same.
 
-## Point the gem at your platform
+For a single app, the [`railwatch-server`](https://github.com/Rebulk/railwatch-server)
+gem runs that same server next to Puma and wires this gem to it, with no
+host to set up; see [Getting started](getting-started.md#embedded-railwatch-server).
+The rest of this page is for a server on its own host.
+
+## Point the gem at your server
 
 ```ruby
 # config/initializers/railwatch.rb
@@ -21,22 +29,22 @@ end
 `ingest_url` defaults to `https://railwatch.rebulk.com`, so this is the one
 setting a self-hosted install always needs; everything the gem sends —
 records, ping, deploys — hangs off that host. Pass `--url=` to the
-installer to have it written for you (it implies `--cloud`):
+installer to have it written for you:
 
 ```sh
 bin/rails generate railwatch:install --url=https://telemetry.example.com
 ```
 
-To keep an embedded install and mirror it to your platform, set
-`RAILWATCH_INGEST_URL` and `RAILWATCH_TOKEN` and turn on
-[export](embedded.md#three-ways-to-run-it) instead.
+The railwatch-rs installer prints both values (`RAILWATCH_INGEST_URL`,
+`RAILWATCH_TOKEN`) when it finishes.
 
 ## Getting a token
 
-On your install: sign up, create an application, then create an
-environment inside it (`production`, `staging` — one token each). The
-token is shown once, right after you create the environment; a lost one
-is rotated from the environment's settings, not recovered.
+railwatch-rs prints the first environment's token once, at the end of
+its install. Each further environment (`production`, `staging` — one
+token each) gets its own, created from the dashboard or with
+`sudo railwatch env create <name>`. A token is shown once; a lost one is
+replaced, not recovered.
 
 ```sh
 bin/rails railwatch:token    # prints the URL to create/copy a token
@@ -55,14 +63,8 @@ so it works as a post-deploy smoke test.
 
 ## MCP
 
-Your install serves its own MCP endpoint at `<ingest host>/mcp` —
+Your server serves its own MCP endpoint at `<ingest host>/mcp` —
 `https://telemetry.example.com/mcp` for the example above. It authenticates
 with a per-user API token generated from Settings → Profile, the same
 token the public JSON API at `/api/v1` uses. See
 [`ai-and-mcp.md`](ai-and-mcp.md) for every client's configuration block.
-
-## Running the platform
-
-Railwatch Cloud's backend is not part of this gem repository. Licensed
-self-hosted customers receive separate platform deployment, backup, retention,
-quota, and restore documentation from Rebulk.