railwatch 0.9.3 → 1.0.0

data/docs/configuration.md

@@ -11,9 +11,9 @@ values set in the initializer always win over the env var.
 
 | Attribute | Env var | Default | Meaning |
 |---|---|---|---|
-| `enabled` | `RAILWATCH_ENABLED` | `true` | Master switch. With `transport = :http`, `Railwatch.enabled?` is also `false` whenever `token` is blank, so setting only `RAILWATCH_TOKEN` is enough to turn a cloud install on. An embedded install needs no token. |
-| `token` | `RAILWATCH_TOKEN` | nil | Bearer token for `/ingest`. Required with `transport = :http` and for [export](#export-to-railwatch-cloud). |
-| `ingest_url` | `RAILWATCH_INGEST_URL` | `https://railwatch.rebulk.com` | Platform base URL. Point at a self-hosted instance to override. |
+| `enabled` | `RAILWATCH_ENABLED` | `true` | Master switch. `Railwatch.enabled?` is also `false` whenever `token` is blank, so setting only `RAILWATCH_TOKEN` is enough to turn an install on. |
+| `token` | `RAILWATCH_TOKEN` | nil | Bearer token for `/ingest`. Required; with railwatch-server installed it is set for you. |
+| `ingest_url` | `RAILWATCH_INGEST_URL` | `https://railwatch.rebulk.com` | Server base URL. Point at a self-hosted railwatch-rs to override. |
 | `allow_http` | `RAILWATCH_ALLOW_HTTP` | `false` | Permit a non-loopback plain HTTP ingest URL. HTTPS is required by default; `localhost`, `127.0.0.1`, and `::1` remain available for local self-hosted development. |
 | `deploy` | `RAILWATCH_DEPLOY` | auto-detected (order below), then nil | Version tag stamped on every record and used by `railwatch:deploy`. Full 40-character SHAs are shortened to 12 characters. |
 | `detect_deploy` | `RAILWATCH_DETECT_DEPLOY` | `true` | Detect deploys beyond `RAILWATCH_DEPLOY` and `KAMAL_VERSION`. Set false when the app deliberately reports no inferred deploy. |
@@ -25,7 +25,7 @@ values set in the initializer always win over the env var.
 | `beacon_rate_limit` | `RAILWATCH_BEACON_RATE_LIMIT` | `120` | Beacon POSTs accepted per client IP per minute before `POST /railwatch/beacon` answers 429. The beacon is unauthenticated and keeps every browser error it is sent, so this is what stops a script from spending the app's event quota. Counted in the app's cache store; `0` turns it off. |
 
 `Railwatch.enabled?` delegates to `config.enabled?`, which is `@enabled &&
-(local? || token.present?)`. There is no separate "is configured" check
+token.present?`. There is no separate "is configured" check
 elsewhere.
 
 Deploy detection stops at the first value found: `RAILWATCH_DEPLOY`,
@@ -411,7 +411,12 @@ result without inserting the payload twice. Records written while a request is i
 separate bounded buffer, so they never change the retained request's
 identity. At most one retained batch plus one live buffer are held in
 memory. The reporter retries with jittered exponential backoff, from one
-second up to 60 seconds. It does not busy-loop. A 401 marks the transport
+second up to 60 seconds. It does not busy-loop. A response with a
+`Retry-After` (a 503 for a full disk or busy database, a 429 rate limit) is a
+refusal: the next attempt waits for its `Retry-After` instead, but never
+less than the backoff rung and never more than 15 seconds (jittered down to
+7.5), because Railwatch's receivers send a fixed 60 there, not a forecast.
+A 401 marks the transport
 permanently unauthorized: no further HTTP attempts for the process's
 lifetime. It and other permanent client rejections are reported through
 `on_unrecoverable`. Delivery never raises into app code.
@@ -433,6 +438,15 @@ affects one probabilistic decision. Set `backpressure` false to keep the
 factor at 1. The current value is sent as
 `X-Railwatch-Backpressure-Factor` whenever it is greater than 1.
 
+A refusal from ingest (see above) sets the factor straight to 8x, and the
+first delivery accepted after it sets it straight back to 1x, so sampling
+recovers within one retry of the receiver recovering. Each refusal prints
+two `[railwatch]` lines, the same way lost records do (see
+`warn_on_data_loss`): one when it starts, and one when ingest accepts
+again, with how long it lasted, how many executions backpressure sampled
+out that the configured rates would have kept, and how many records were
+dropped.
+
 `Railwatch.flush` forces an immediate flush, on the calling thread and
 without a time limit, so it is yours to call when you know you want to
 wait. Nothing in the gem calls it for you: a short-lived process keeps its
@@ -571,7 +585,7 @@ Rake tasks and Solid Queue jobs are never interactive.
 
 | Attribute | Env var | Default | Meaning |
 |---|---|---|---|
-| `capture_exception_source` | `RAILWATCH_CAPTURE_EXCEPTION_SOURCE_CODE` | `true` | Record source snippet lines surrounding each in-application exception frame (sent to Railwatch Cloud when the install reports there or exports). This is on by default for crash context; disable it when source disclosure is outside the application's telemetry policy. |
+| `capture_exception_source` | `RAILWATCH_CAPTURE_EXCEPTION_SOURCE_CODE` | `true` | Record source snippet lines surrounding each in-application exception frame (sent to whichever server the app reports to). This is on by default for crash context; disable it when source disclosure is outside the application's telemetry policy. |
 | `capture_exception_locals` | `RAILWATCH_CAPTURE_EXCEPTION_LOCALS` | `false` | Snapshot the raising frame's local variables (up to 25, values truncated to 200 chars, run through the same filter as request params) onto each exception, like Sentry's locals panel. Installs a `TracePoint(:raise)`; opt in per environment. |
 | `capture_request_payload` | `RAILWATCH_CAPTURE_REQUEST_PAYLOAD` | `false` | Capture (redacted) request params — only for a request that raised, never otherwise. |
 | `capture_job_arguments` | `RAILWATCH_CAPTURE_JOB_ARGUMENTS` | `false` | Add the job's real arguments (`job.serialize["arguments"]`) to each `job_attempt`/`scheduled_task` record, capped at 8 KiB of JSON. Hash arguments run through the same filter as request params. Off by default because job arguments routinely carry PII; `arguments_preview` (argument *shapes* only) is always on regardless. |
@@ -827,16 +841,19 @@ Railwatch.on_unrecoverable { |error| Rails.error.report(error, handled: true) }
 ```
 
 Called whenever Railwatch rescues one of its own internal errors, ingest
-permanently rejects a batch, or shutdown expires with retained records
-that could not be sent. Retryable delivery failures stay buffered and do
-not fire the callback on every attempt. With no callback registered, a
+permanently rejects a batch, ingest starts or stops refusing deliveries, or
+shutdown expires with retained records that could not be sent. Retryable
+delivery failures stay buffered and do not fire the callback on every
+attempt. With no callback registered, a
 recovered internal error falls back to `Railwatch.debug`, gated on
 `RAILWATCH_DEBUG` — the gem carried on and there is nothing to do about it.
 
 **Lost records are different, and are reported by default.** A batch
 dropped after its retry ladder, one the receiver permanently refused, or
 records still unsent when the bounded shutdown ran out of time each print
-one `[railwatch]` stderr line. Telemetry that vanishes silently looks
+one `[railwatch]` stderr line. So do the start and end of an ingest
+refusal, which samples down until it is over (see backpressure above).
+Telemetry that vanishes silently looks
 exactly like having nothing to report, and a short-lived process — a rake
 task, a `rails runner`, a cron job — gets one bounded shutdown and no
 second chance to mention it.
@@ -883,72 +900,50 @@ in `lib/railwatch.rb`, unless noted:
 `instrument_outgoing`, `flush`, `debug { }`. `pause`/`resume` are the
 ignore block's building blocks, and are nestable.
 
-## Embedded mode
+## Dashboard gate (railwatch-server)
+
+These settings do nothing on their own. They gate the dashboard that the
+[`railwatch-server`](https://github.com/Rebulk/railwatch-server) gem
+serves at `/railwatch` inside the app, so one setting covers it whichever
+way it is installed.
 
 ```ruby
-c.transport = :local        # RAILWATCH_TRANSPORT; runtime default "http", but the installer writes :local
-c.issue_prefix = "SHOP"     # RAILWATCH_ISSUE_PREFIX; default from the app name
-c.repository_url = "..."    # RAILWATCH_REPOSITORY_URL
-c.retention_days = 7        # RAILWATCH_RETENTION_DAYS
 c.http_basic_auth_enabled = true      # RAILWATCH_HTTP_BASIC_AUTH_ENABLED; on, and closed outside development until credentials exist
 c.http_basic_auth_user = "ops"        # RAILWATCH_HTTP_BASIC_AUTH_USER, or credentials railwatch.http_basic_auth_user
 c.http_basic_auth_password = "..."    # RAILWATCH_HTTP_BASIC_AUTH_PASSWORD, or credentials railwatch.http_basic_auth_password
 c.base_controller_class = "AdminController"  # RAILWATCH_BASE_CONTROLLER_CLASS; default ActionController::Base
-c.dashboard_open = false              # RAILWATCH_DASHBOARD_OPEN; default false, true makes it public on purpose
-c.dashboard_user = ->(request) { { id:, name:, email: } or nil }
-c.writer_socket = "tmp/sockets/railwatch-writer.sock"  # RAILWATCH_WRITER_SOCKET
 ```
 
-With `transport = :local` the reporter writes each batch into the app's
-own `railwatch_telemetry` database instead of POSTing it, and the engine
-serves the dashboard at its mount. `enabled?` no longer needs a token.
-The others only matter in that mode. The dashboard is behind HTTP Basic
-by default and, outside development, answers 401 until `bin/rails
-railwatch:authentication:configure` has written credentials; a host with
-its own admin auth turns Basic off and sets `base_controller_class` or a
-routes constraint. Full walkthrough: [Embedded mode](embedded.md).
-
-### Export to Railwatch Cloud
-
-An embedded install can also mirror every record to Railwatch Cloud.
-Off unless `export_enabled` is set; a configured token alone sends
-nothing. Only meaningful with `transport = :local`.
-
-| Attribute | Env var | Default | Meaning |
-|---|---|---|---|
-| `export_enabled` | `RAILWATCH_EXPORT_ENABLED` | `false` | Mirror every record to the cloud as well as storing it locally. |
-| `export_token` | `RAILWATCH_EXPORT_TOKEN` | `token` | Cloud environment token to send with. |
-| `export_url` | `RAILWATCH_EXPORT_URL` | `{ingest_url}/ingest` | Where to send. |
-| `export_max_bytes` | `RAILWATCH_EXPORT_MAX_BYTES` | `268435456` (256 MiB) | Queue ceiling in bytes. At capacity new work is refused and counted, not swapped for old. |
-| `export_max_deliveries` | `RAILWATCH_EXPORT_MAX_DELIVERIES` | `100000` | Queue ceiling in deliveries. |
-| `export_max_age` | `RAILWATCH_EXPORT_MAX_AGE_SECONDS` | `86400` | How long a queued delivery is kept. At most seven days, past which the receiver no longer recognises it. |
+HTTP Basic is on by default and, outside development, answers 401 until
+credentials exist: `bin/rails railwatch:authentication:configure` writes
+them to the current environment's Rails credentials, or set the env vars.
+In development with no credentials configured, it is open. An initializer
+or env var that sets them wins over credentials.
 
-`railwatch:doctor` fails when export is enabled and cannot work, and
-`railwatch:export:status` shows the queue. See
-[Embedded mode](embedded.md#three-ways-to-run-it).
+An app with its own admin authentication turns Basic off and names a
+base controller. railwatch-server's proxy controller inherits from
+`base_controller_class`, so the app's own `before_action`s (require an
+admin, redirect to sign-in) run in front of every dashboard request.
 
 ## Rake tasks
 
 Ship with the gem via Rails::Engine's default `lib/tasks` convention, in
 `lib/tasks/railwatch_tasks.rake`:
 
-- **`railwatch:status`** embedded: prints that telemetry is stored in the
-  app. Cloud: pings `{ingest_url}/ingest/ping` with the configured token,
-  and aborts if `RAILWATCH_TOKEN` is unset or the ping fails.
+- **`railwatch:status`** pings `{ingest_url}/ingest/ping` with the
+  configured token, and aborts if `RAILWATCH_TOKEN` is unset or the ping
+  fails.
 - **`railwatch:doctor`** prints a ✓/✗ checklist of the whole install.
-  Embedded, it checks both databases and their migrations, telemetry
-  disk mode, the maintenance clock, the writer process, dashboard access,
-  and export when enabled. Cloud, it checks the token, where the token is
-  stored, the ingest URL and its transport security, and
-  `GET /ingest/ping`. Then, either way: `Railwatch::Middleware::Request`
+  It checks the token, where the token is stored, the ingest URL and its
+  transport security, and `GET /ingest/ping`. Then
+  `Railwatch::Middleware::Request`
   in the middleware stack, the mounted engine's beacon route,
   `config.deploy` and its source, sample rates, ignored record types, the
   Kamal `post-deploy` hook, the browser client and whether an entrypoint
   calls it, the profiler backend, and the test matchers. It exits
   non-zero only on the lines marked fatal in
   [Troubleshooting](troubleshooting.md).
-- **`railwatch:deploy[ref,name,url]`** embedded: writes the deploy marker
-  to the app's `railwatch` database. Cloud: POSTs `{deploy, ref, name,
+- **`railwatch:deploy[ref,name,url]`** POSTs `{deploy, ref, name,
   url, server, timestamp, performer, destination, service, commits}` to
   `{ingest_url}/ingest/deploys`. `deploy` comes from `config.deploy`. It
   aborts if that's unset. `ref` defaults to `git rev-parse HEAD` when not
@@ -957,29 +952,20 @@ Ship with the gem via Rails::Engine's default `lib/tasks` convention, in
   `{sha, author, message, at}` objects, newest first, from `git log`. It
   is empty inside an app container, which has no `.git`. That is why the
   hook below posts from the deployer instead.
-- **`railwatch:authentication:configure`** writes the embedded
-  dashboard's HTTP Basic credentials to the current environment's Rails
-  credentials.
-- **`railwatch:export:status`**, **`railwatch:export:rebind`**,
-  **`railwatch:export:discard`** show the export queue, clear a
-  credential block (abandoning work queued under the old token), and
-  abandon everything queued.
-- **`railwatch:vacuum:status`** and **`railwatch:vacuum`** report and
-  reclaim the telemetry database's disk
-  ([Embedded mode](embedded.md#giving-the-disk-back)).
-- **`railwatch:token`** and **`railwatch:mcp`** print where to create a
-  cloud ingest token and paste-ready MCP client configuration.
+- **`railwatch:authentication:configure`** writes the
+  [dashboard gate](#dashboard-gate-railwatch-server)'s HTTP Basic
+  credentials to the current environment's Rails credentials.
+- **`railwatch:token`** and **`railwatch:mcp`** print where to create an
+  ingest token and paste-ready MCP client configuration for the server
+  `ingest_url` points at.
 - **`railwatch:sourcemaps[directory,delete]`** uploads browser source
   maps ([Source maps](source-maps.md)).
 
 ## Kamal integration
 
 `bin/rails generate railwatch:install` writes `.kamal/hooks/post-deploy`,
-but only if `config/deploy.yml` already exists. With
-`RAILWATCH_TRANSPORT=local` in the deployer's environment it runs
-`bin/rails railwatch:deploy[$KAMAL_VERSION]` in the primary container,
-which records the marker in the embedded database, and stops. Otherwise
-it no-ops when `RAILWATCH_TOKEN` isn't set. It never fails a deploy.
+but only if `config/deploy.yml` already exists. It no-ops when
+`RAILWATCH_TOKEN` isn't set. It never fails a deploy.
 Every network call ends in `|| true`.
 
 The hook runs on the **deployer machine**, not in a container, which is

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