railwatch 0.9.4 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bfbb6b3ab550297baaa042889c6e98fe0b5fc1528acf6696fa343631b05936bd
-  data.tar.gz: 37b7b7bce05a1e0b19ed8051f9dcc7cd09f3ca0c8d638404c9fa55bb227c44c4
+  metadata.gz: 3620348235aae6e5733728931b85a9c0edd0ac31367a4fd143eceee1de28cbc0
+  data.tar.gz: 273a578b3059f4390854d7452df971d8223c9e4f6c8c6a9e7e8d9f46a27ef1f3
 SHA512:
-  metadata.gz: dc66f26f906bdab5b2be01c151c81e40767004508f94c1c7860d0a590272daa7469ec3a1a66cb8d5992e1f8ff7f080d6280049afe932b0582859b693c2801655
-  data.tar.gz: 9296b26cf0c6c0eb837fdc85f7b69cd4f589c2ebfe5579e30401d3b16819e653dd86ad52764cff5d2ab6e768bf72c5b505ec4255d128a0f3334bfcefe0c41b72
+  metadata.gz: 82640c29a57b4c99d890b40ef75179d635b53308879516ba4973aaed0cfa1179696e0ee14e6660be2eb59c935611eb395e9f508e583c2604fbe8a7e57da0f8ad
+  data.tar.gz: 53ff388054d12658c7d0cb99c3d0c3dd01be8579ac2227efbb07d65f008a766851761655904b081c8f344aa5db6f3ad9d2cb1e25a349bf30b943e85cb74489bc

data/AGENTS.md

@@ -4,9 +4,11 @@ About *using* the `railwatch` gem from a Rails application; copy
 this into that application's repository. Index of everything else:
 [`llms.txt`](llms.txt).
 
-Railwatch instruments a Rails app end to end and stores linked telemetry in
-two SQLite databases of the app's own (embedded, the default) or sends it to
-Railwatch Cloud. Every request, job attempt, scheduled task run, and command is
+Railwatch instruments a Rails app end to end and sends linked telemetry over
+HTTPS to a Railwatch server: Railwatch Cloud (`https://railwatch.rebulk.com`,
+the default), a self-hosted [railwatch-rs](https://github.com/Rebulk/railwatch-rs),
+or the one the [`railwatch-server`](https://github.com/Rebulk/railwatch-server)
+gem runs next to Puma. Every request, job attempt, scheduled task run, and command is
 an **execution**; every query, cache read, log line, outgoing HTTP call, LLM
 call, view render, exception, and span is a child of one, linked by
 `execution_id`/`trace_id`. It never writes to the app's primary database.
@@ -15,40 +17,41 @@ call, view render, exception, and span is a child of one, linked by
 
 ```sh
 bundle add railwatch
-bin/rails generate railwatch:install                                 # embedded: dashboard at /railwatch
-bin/rails generate railwatch:install --prompt-token --kamal-secrets  # or: Railwatch Cloud
+bin/rails generate railwatch:install --prompt-token --kamal-secrets  # Railwatch Cloud
+bin/rails generate railwatch:install --url=https://telemetry.example.com  # self-hosted railwatch-rs
 ```
 
-With no flags the install is embedded (see [Embedded mode](docs/embedded.md)):
-telemetry stays in two SQLite databases the app owns (`railwatch`,
-`railwatch_telemetry`, added to `config/database.yml`), Puma forks one writer
-for them (`plugin :railwatch` in `config/puma.rb`), and the dashboard is served
-at `/railwatch`. It is open in development and answers 401 elsewhere until
-`RAILS_ENV=production bin/rails railwatch:authentication:configure` sets a
-password. An exported `RAILWATCH_TOKEN` alone does not change the mode.
-`--cloud`, or any of `--prompt-token`, `--token-stdin`, `--url`,
-`--kamal-secrets`, sends telemetry to Railwatch Cloud instead.
-
-Both modes write `config/initializers/railwatch.rb`, mount `Railwatch::Engine`
-at `/railwatch`, add the Kamal `post-deploy` hook and the Inertia browser client
-where the app has them, and require `railwatch/rspec` (or `railwatch/minitest`)
-in the test helper; the cloud install then runs `railwatch:doctor`. A
+The generator writes `config/initializers/railwatch.rb`, mounts
+`Railwatch::Engine` at `/railwatch` (it serves only the browser beacon), adds
+the Kamal `post-deploy` hook and the Inertia browser client where the app has
+them, requires `railwatch/rspec` (or `railwatch/minitest`) in the test helper,
+and runs `railwatch:doctor` (`--no-doctor` skips it). A
 prompted/stdin/environment token goes into `.env` only when Git confirms that
-file is ignored; token values are never printed. Configuration lives only in
-that initializer; every option also has a `RAILWATCH_*` environment variable.
-An embedded install mirrors to Railwatch Cloud as well with a token and
-`c.export_enabled = true`.
+file is ignored; token values are never printed. Without a token the gem is
+inert. Configuration lives only in that initializer; every option also has a
+`RAILWATCH_*` environment variable.
+
+Embedded (the dashboard inside the app, no token to manage): add
+`gem "railwatch-server"` to the Gemfile and `plugin :railwatch_server` to
+`config/puma.rb`. It provisions `storage/railwatch/<env>` on first boot and
+points this agent at it. Its dashboard at `/railwatch` is gated by this gem's
+`http_basic_auth_*` settings (open in development, 401 elsewhere until
+`RAILS_ENV=production bin/rails railwatch:authentication:configure` sets a
+password) or, with Basic off, by `c.base_controller_class`.
+
+Railwatch 0.x's in-gem embedded mode (`c.transport = :local`, `plugin :railwatch`,
+the `railwatch`/`railwatch_telemetry` databases) is gone in 1.0; remove all three
+and add railwatch-server. Its old SQLite files are not migrated.
 
 ## Rake tasks
 
 | Task | Does |
 |---|---|
-| `bin/rails railwatch:doctor` | ✓/✗ per check. Embedded: databases, migrations, writer process, last write, maintenance, dashboard access, export. Cloud: token, token storage, ingest URL, reachability. Both: middleware, engine mount, deploy, sample rates, ignored types, Kamal hook, browser client and whether an entrypoint calls it, profiler backend, test matchers. Exits non-zero on a missing database, pending migrations, broken export, a missing or tracked token, or an unreachable host. **Run this first when telemetry is missing.** |
-| `bin/rails railwatch:authentication:configure` | Sets the embedded dashboard's HTTP Basic credentials for the current `RAILS_ENV`. |
-| `bin/rails railwatch:export:status` | What the export queue holds and whether it can send. |
-| `bin/rails railwatch:token` | Where to create a Railwatch Cloud ingest token for this app. |
-| `bin/rails railwatch:mcp` | Paste-ready MCP client configuration for this app's Railwatch Cloud. |
-| `bin/rails railwatch:deploy[ref,name,url]` | Records a deploy marker (in the embedded database, or on the cloud). Use as a release step when not deploying with Kamal. |
+| `bin/rails railwatch:doctor` | ✓/✗ per check: token, token storage, ingest URL, reachability, middleware, engine mount, deploy, sample rates, ignored types, Kamal hook, browser client and whether an entrypoint calls it, profiler backend, test matchers. Exits non-zero on a missing or tracked token, or an unreachable host. **Run this first when telemetry is missing.** |
+| `bin/rails railwatch:authentication:configure` | Sets the HTTP Basic credentials that gate railwatch-server's dashboard, for the current `RAILS_ENV`. |
+| `bin/rails railwatch:token` | Where to create an ingest token for this app on the server `ingest_url` points at. |
+| `bin/rails railwatch:mcp` | Paste-ready MCP client configuration for that server. |
+| `bin/rails railwatch:deploy[ref,name,url]` | Records a deploy marker on the server. Use as a release step when not deploying with Kamal. |
 | `bin/rails 'railwatch:sourcemaps[public,true]'` | Uploads Vite source maps for the configured deploy, then deletes acknowledged files. Run after building and before publishing assets. Omit `true` to retain files. See [Source maps](docs/source-maps.md). |
 
 ## Facade
@@ -89,9 +92,9 @@ Per action, in a controller class body: `railwatch_sample 0.01, only: :index`,
 ## Specs
 
 `require "railwatch/rspec"` in `spec/rails_helper.rb` (or `"railwatch/minitest"` in
-`test/test_helper.rb`). Railwatch must be enabled in the test env: an embedded
-install is, and needs `RAILS_ENV=test bin/rails db:prepare` once so its test
-databases exist; a cloud install needs any non-blank `RAILWATCH_TOKEN`. Records
+`test/test_helper.rb`). Railwatch must be enabled in the test env, which
+needs any non-blank `RAILWATCH_TOKEN` there (railwatch-server is off in test
+and does not set one). Records
 go to an in-memory transport, never over the wire. All matchers are block
 matchers.
 
@@ -117,7 +120,8 @@ melt in production.
 
 ## MCP
 
-Railwatch Cloud (not embedded mode) is an MCP server at `<ingest host>/mcp`.
+Railwatch Cloud and railwatch-rs are MCP servers at `<ingest host>/mcp`
+(with railwatch-server: the app's host plus `/railwatch/mcp`).
 Generate a personal token at Settings → Profile → "API & MCP token", then:
 
 ```sh

data/CHANGELOG.md

@@ -6,6 +6,69 @@
      filled in by the release commit, which is also the only commit that
      touches lib/railwatch/version.rb and Gemfile.lock. See CONTRIBUTING.md. -->
 
+## 1.1.0 (2026-10-22)
+
+- A receiver that refuses the connection (nothing listening: a Railwatch
+  server restarting, or a deploy handing over to the next container) no
+  longer counts as backpressure. The retry ladder it starts used to double
+  the sampling divisor every flush tick, so the app's first requests after
+  the server came back were sampled out: a fresh app recorded 23-29 of 30
+  requests sent right after its embedded server was killed and restarted,
+  in every one of 10 runs. A timeout, a 5xx and a full buffer are still
+  pressure.
+- `Configuration#local?` is gone. It was kept in 1.0.0 only for
+  railwatch-server 0.1.0; railwatch-server 0.1.1 no longer calls it.
+
+## 1.0.0 (2026-10-22)
+
+- **Breaking: `railwatch` is the agent only.** It instruments the app and
+  sends to an ingest URL: Railwatch Cloud (the default,
+  `https://railwatch.rebulk.com`) or a self-hosted
+  [railwatch-rs](https://github.com/Rebulk/railwatch-rs) server
+  (`RAILWATCH_INGEST_URL`, `RAILWATCH_TOKEN`). Embedded mode is gone from
+  this gem: `transport :local` / `RAILWATCH_TRANSPORT`, the two SQLite
+  databases (`railwatch`, `railwatch_telemetry`) and their migrations, the
+  Puma writer (`plugin :railwatch`), the maintenance clock, export to the
+  cloud, the dashboard pages, its live channel and its compiled bundle.
+  The dashboard is part of the server now, and the gem has no runtime
+  dependency on `inertia_rails` or `tdigest`.
+  - The dashboard inside the app is the separate
+    [railwatch-server](https://github.com/Rebulk/railwatch-server) gem. It
+    runs the railwatch-rs server next to Puma and points this agent at it.
+  - Removed settings: `transport`, `issue_prefix`, `repository_url`,
+    `retention_days`, `dashboard_user`, `dashboard_open`, `writer_socket`,
+    `migration_busy_timeout`, and every `export_*`, with their
+    `RAILWATCH_*` variables. Removed rake tasks: `railwatch:vacuum`,
+    `railwatch:vacuum:status`, `railwatch:export:status`, `:rebind` and
+    `:discard`. Removed: `Railwatch.migrations_path`,
+    `Railwatch.url_helpers`, `Railwatch.frontend_path`.
+  - `http_basic_auth_enabled`, `http_basic_auth_user`,
+    `http_basic_auth_password`, `base_controller_class` and
+    `bin/rails railwatch:authentication:configure` stay. They are the gate
+    railwatch-server puts in front of its dashboard, and do nothing without
+    it.
+  - `bin/rails generate railwatch:install` sets up the agent only: token,
+    ingest URL (`--url` for a self-hosted server), the beacon mount, the
+    Kamal hook, the browser client and the test helpers. It no longer
+    writes `config/database.yml` or `config/puma.rb`, and `--cloud` is gone
+    because there is no other mode.
+  - The browser client moved to
+    `lib/generators/railwatch/install/templates/railwatch.ts`
+    (`Railwatch.browser_client_path`). Apps that already copied it keep
+    their copy at `app/frontend/lib/railwatch.ts`.
+  - Upgrading an embedded 0.x install: delete `c.transport = :local` (or
+    `RAILWATCH_TRANSPORT=local`), delete `plugin :railwatch` from
+    `config/puma.rb` (Puma refuses to boot with a plugin it cannot find),
+    and delete the `railwatch` and `railwatch_telemetry` entries from
+    `config/database.yml`. Then add `gem "railwatch-server"` and
+    `plugin :railwatch_server`. The old data in
+    `storage/<env>_railwatch.sqlite3` and
+    `storage/<env>_railwatch_telemetry.sqlite3` is not migrated: railwatch-rs
+    has no import for these files (`railwatch import-rails` reads a
+    Railwatch Cloud install, not this gem's embedded databases), so the new
+    dashboard starts empty. Keep the old files only if you want them; they
+    can be deleted.
+
 ## 0.9.4 (2026-10-22)
 
 - Sampling recovers as soon as ingest does. A receiver refusing with a

data/README.md

@@ -6,37 +6,26 @@ outgoing HTTP, storage, views, and logs, and links them into one trace
 per execution, for about half a millisecond per request plus tens of
 microseconds per query, with zero writes to your database.
 
-By default all of it stays inside the app:
-[embedded mode](docs/embedded.md) serves the full dashboard at
-`/railwatch` out of two SQLite files your app owns, with no token, no
-Node, no Redis and no job worker. Railwatch Cloud is optional: it
-delivers alerts to Slack, email, webhooks or Linear (including when the
-app is down), serves MCP to your AI assistant, and puts many apps and
-servers in one place.
+The gem is the agent. It sends what it records over HTTPS to a
+Railwatch server, which stores it, groups exceptions into issues, sends
+alerts, and serves the dashboard and an MCP server:
 
-## Install
-
-```sh
-bundle add railwatch                  # 1. add the public gem
-bin/rails generate railwatch:install  # 2. embedded: databases, Puma writer, dashboard at /railwatch
-```
-
-Restart and open `/railwatch`. It is open in development; before you
-deploy, give it a password with
-`RAILS_ENV=production bin/rails railwatch:authentication:configure`
-(it answers 401 in production until you do). On a PostgreSQL or MySQL
-app without the `sqlite3` gem, the generator adds it to the Gemfile;
-run `bundle install` and `bin/rails db:prepare` to finish.
+- **Railwatch Cloud** at <https://railwatch.rebulk.com>, the default.
+- **Self-hosted [railwatch-rs](https://github.com/Rebulk/railwatch-rs)**,
+  one static binary for many apps ([Self-hosting](docs/self-hosting.md)).
+- **Embedded**: the [`railwatch-server`](https://github.com/Rebulk/railwatch-server)
+  gem runs that server next to Puma for one app and serves the dashboard
+  at `/railwatch`, with nothing else to run.
 
-To send everything to Railwatch Cloud instead, pass `--cloud` or a token
-option:
+## Install
 
 ```sh
-bundle add railwatch
-bin/rails generate railwatch:install --prompt-token  # hidden token input plus app wiring
+bundle add railwatch                                # 1. add the public gem
+bin/rails generate railwatch:install --prompt-token # 2. hidden token input plus app wiring
 bin/rails railwatch:doctor                          # check every piece is wired up after restart
 ```
 
+For a self-hosted server, add `--url=https://telemetry.example.com`.
 The generator's flags, getting a token, and deploying with Kamal,
 Docker, Heroku, or Render are covered in
 [Getting started](docs/getting-started.md). For an unreleased revision,
@@ -46,6 +35,36 @@ use the Git source instead:
 gem "railwatch", github: "Rebulk/railwatch"
 ```
 
+### Embedded
+
+To keep everything inside the app, add `railwatch-server` next to this
+gem:
+
+```ruby
+# Gemfile
+gem "railwatch"
+gem "railwatch-server"
+```
+
+```ruby
+# config/puma.rb
+plugin :railwatch_server
+```
+
+It provisions its data under `storage/railwatch/<env>` on first boot and
+points this gem at it, so there is no token to manage. The dashboard at
+`/railwatch` is open in development and answers 401 elsewhere until you
+give it a password with
+`RAILS_ENV=production bin/rails railwatch:authentication:configure`, or
+put it behind your own admin authentication
+([Configuration](docs/configuration.md#dashboard-gate-railwatch-server)).
+Everything else is in the
+[railwatch-server README](https://github.com/Rebulk/railwatch-server#readme).
+
+Railwatch 0.x kept embedded telemetry in two SQLite databases written by
+`plugin :railwatch`. 1.0 removes that mode; see
+[Coming from 0.x embedded mode](docs/getting-started.md#coming-from-0x-embedded-mode).
+
 ## What you get
 
 - Requests, jobs, scheduled tasks, commands, queries, exceptions, and
@@ -63,8 +82,8 @@ gem "railwatch", github: "Rebulk/railwatch"
   and browser errors ([Getting started](docs/getting-started.md)).
 - RSpec and Minitest matchers that turn a query budget into a CI gate
   ([Testing](docs/testing.md)).
-- With Railwatch Cloud, an MCP server so Claude Code, Cursor, VS Code, or
-  Zed can read your production data
+- An MCP server on the Railwatch server, so Claude Code, Cursor, VS Code,
+  or Zed can read your production data
   ([AI assistants and MCP](docs/ai-and-mcp.md)).
 
 Configuration lives in `config/initializers/railwatch.rb`; most options
@@ -85,36 +104,12 @@ expect { get "/widgets" }.to have_railwatch_queries(at_most: 6)
 expect { get "/widgets" }.not_to have_railwatch_n_plus_one
 ```
 
-## Embedded mode
-
-Telemetry goes to two SQLite files the app owns -- `railwatch` for
-issues, comments and saved views, `railwatch_telemetry` for what the app
-reports -- and the dashboard is served at `/railwatch` from a bundle
-shipped inside the gem. Nothing leaves the machine unless you turn on
-export to Railwatch Cloud, and there is nothing else to run.
-
-Puma forks a single writer process (`plugin :railwatch`, which the
-installer adds) that owns both files. The web workers hand it batches
-over a Unix socket instead of writing SQLite on their own threads, and it
-runs the maintenance clock too, so exception grouping, rollups, retention
-and threshold scans happen without a queue.
-
-That dashboard reads every query, log line and exception the app
-produced, so it is gated the way Mission Control Jobs is: HTTP Basic is
-on, and with no credentials every request is 401 until you set them
-with `bin/rails railwatch:authentication:configure`. Development is the
-exception: with no credentials set there, it is open. Apps that would
-rather use their own authentication turn Basic off and gate the pages
-with `base_controller_class` or a routes constraint around the mount; a
-`dashboard_user` resolver then names the operator and authorizes live
-updates, but does not gate pages. [Embedded mode](docs/embedded.md)
-covers all of it, including upgrades and what it costs to store.
-
 ## Documentation
 
-- [Getting started](docs/getting-started.md) — the embedded install, the
-  Railwatch Cloud install and its token, the three optional lines, and
-  deploying with Kamal, Docker, Heroku, Render, or none of them.
+- [Getting started](docs/getting-started.md) — the install and its token,
+  embedded with railwatch-server, moving from 0.x embedded mode, the three
+  optional lines, and deploying with Kamal, Docker, Heroku, Render, or none
+  of them.
 - [Configuration](docs/configuration.md) — every option and `RAILWATCH_*`
   variable, field by field.
 - [Record types](docs/records.md) — every record Railwatch ships and every
@@ -122,17 +117,13 @@ covers all of it, including upgrades and what it costs to store.
 - [Testing](docs/testing.md) — the RSpec and Minitest matchers, and a CI
   performance gate.
 - [AI assistants and MCP](docs/ai-and-mcp.md) — connecting Claude Code,
-  Cursor, VS Code, or Zed to your production data through Railwatch
-  Cloud.
+  Cursor, VS Code, or Zed to your production data.
 - [Replacing Sentry](docs/replacing-sentry.md) — a step-by-step migration,
   option by option and call site by call site.
 - [Coming from Laravel Nightwatch](docs/replacing-nightwatch.md) — the
   record-type mapping and the sampling model, for Laravel people.
-- [Embedded mode](docs/embedded.md) — the default: the whole dashboard
-  inside your app, telemetry in your own SQLite files, and optional
-  export to Railwatch Cloud.
 - [Self-hosting](docs/self-hosting.md) — pointing the gem at your own
-  Railwatch Cloud.
+  railwatch-rs server.
 - [Troubleshooting](docs/troubleshooting.md) — every failure mode, paired
   with the `railwatch:doctor` line it shows up as.
 - [FAQ](docs/faq.md) — overhead numbers, retention, PII posture, SQLite.

data/config/routes.rb

@@ -2,63 +2,4 @@
 
 Railwatch::Engine.routes.draw do
   post "beacon", to: "beacon#create"
-
-  # The embedded dashboard. Same URL shape as the hosted platform so the
-  # prebuilt bundle's route helpers resolve unchanged once js-routes knows
-  # the mount point; a singleton install always answers for app 1, env 1.
-  root to: redirect { |_p, req| "#{req.script_name}/apps/1/envs/1" }
-  get "dashboard", to: redirect { |_p, req| "#{req.script_name}/apps/1/envs/1" }
-  get "docs", to: redirect("https://railwatch.rebulk.com/docs")
-
-  scope "apps/:application_id", as: :application do
-    get "/", to: redirect { |p, req| "#{req.script_name}/apps/#{p[:application_id]}/envs/1" }
-    scope "envs/:environment_id", as: :environment do
-      get "/", to: "overview#show", as: :overview
-      resources :requests, only: [ :index, :show ] do
-        get "routes/:group_hash", to: "requests#route", on: :collection, as: :route
-      end
-      resources :jobs, only: [ :index, :show ] do
-        get "classes/:group_hash", to: "jobs#klass", on: :collection, as: :klass
-      end
-      resources :scheduled_tasks, only: [ :index, :show ]
-      resources :commands, only: [ :index, :show ]
-      resources :executions, only: [ :show ]
-      resources :queries, only: [ :index, :show ]
-      resources :spans, only: [ :index, :show ]
-      resources :profiles, only: [ :index, :show ]
-      resources :attachments, only: [ :show ]
-      get "traces/:trace_id", to: "traces#show", as: :trace
-      resources :view_renders, path: "views", only: [ :index ]
-      resources :transactions, only: [ :index ]
-      resources :deprecations, only: [ :index ]
-      resources :exceptions, only: [ :index ]
-      resources :cache_events, path: "cache", only: [ :index ]
-      resources :mails, path: "mail", only: [ :index ]
-      resources :notifications, only: [ :index ]
-      resources :broadcasts, only: [ :index ]
-      resources :outgoing_requests, only: [ :index ]
-      resources :llm_calls, path: "llm", only: [ :index ]
-      resources :storage_ops, path: "storage", only: [ :index ]
-      resources :logs, only: [ :index ]
-      resources :people, path: "users", only: [ :index, :show ]
-      resources :deploys, only: [ :index, :show ]
-      resources :releases, only: [ :index, :show ]
-      resources :visits, only: [ :index ]
-      resources :processes, only: [ :index ]
-      resources :tenants, only: [ :index, :show ]
-      resources :saved_views, only: [ :create, :update, :destroy ]
-      resources :thresholds, only: [ :index, :create, :update, :destroy ]
-      resources :anomaly_rules, only: [ :create, :update, :destroy ]
-      resources :alerts, only: [ :index ]
-    end
-  end
-
-  resources :issues, only: [ :index, :show, :update ] do
-    resources :comments, only: [ :create ]
-    post :bulk, on: :collection
-    get :merge_candidates, on: :member
-  end
-  resources :alerts, only: [ :index ] do
-    post :retry, on: :member
-  end
 end

data/docs/ai-and-mcp.md

@@ -1,6 +1,7 @@
 # AI assistants and MCP
 
-Railwatch Cloud is an [MCP](https://modelcontextprotocol.io) server. Point
+Railwatch Cloud, and any railwatch-rs server, is an
+[MCP](https://modelcontextprotocol.io) server. Point
 Claude Code, Claude Desktop, Cursor, VS Code, or Zed at it and the assistant
 sitting in your editor can read the same production data your dashboards
 show: issues and their stack traces, slow routes, the queries and N+1s
@@ -9,13 +10,13 @@ crash-free rates per release. It can also write — resolve an issue, set a
 priority, leave a comment — and every write is signed with your user and the
 agent's name in the issue's activity feed.
 
-MCP is a Railwatch Cloud feature. The embedded dashboard at `/railwatch`
-does not serve it; an embedded install gets it by
-[exporting to the cloud](embedded.md#three-ways-to-run-it).
-
 The endpoint is `<your ingest host>/mcp`. For the hosted platform that's
 `https://railwatch.rebulk.com/mcp`; if you self-host, it is your own host (see
-[`self-hosting.md`](self-hosting.md)). The gem knows which one you're on:
+[`self-hosting.md`](self-hosting.md)). With the `railwatch-server` gem the
+server runs under the app's dashboard path, so the endpoint is the app's own
+host plus `/railwatch/mcp`; see the
+[railwatch-server README](https://github.com/Rebulk/railwatch-server#readme).
+For Railwatch Cloud and a self-hosted server the gem knows which one you're on:
 
 ```sh
 bin/rails railwatch:mcp
@@ -225,9 +226,9 @@ Copy either into your own app's repo to give its agent the same context.
 
 ## See also
 
-- [`getting-started.md`](getting-started.md) — install, the cloud token,
+- [`getting-started.md`](getting-started.md) — install, the token,
   first request.
 - [`self-hosting.md`](self-hosting.md) — pointing the gem, and this endpoint,
-  at your own platform.
+  at your own server.
 - [`troubleshooting.md`](troubleshooting.md) — when something isn't
   reporting.

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`,
@@ -585,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. |
@@ -900,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
@@ -974,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