railwatch 0.5.1 → 0.6.1

data/docs/getting-started.md

@@ -1,27 +1,100 @@
 # Getting started
 
-Five minutes from `bundle add` to a request on the dashboard, on a
-Rails 8 app. 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, then a dashboard at `/railwatch`.
+Everything below is the gem's own generator and rake tasks; nothing else
+has to be wired by hand.
 
-Running one server and want the dashboard inside the app itself, with
-no token and no cloud? That is `bin/rails generate railwatch:install
---local`; see [Embedded mode](embedded.md). The rest of this page is
-the cloud install.
-
-## 1. Add the gem
+## Install
 
 ```sh
 bundle add railwatch
+bin/rails generate railwatch:install
 ```
 
 The gem, its Ruby namespace, and its require path share one name:
 `railwatch`, `Railwatch::*`, `require "railwatch"`.
 
-## 2. Run the installer
+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
-bin/rails generate railwatch:install
+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
@@ -36,6 +109,10 @@ 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
@@ -47,24 +124,12 @@ bin/rails generate railwatch:install \
   `config/deploy.yml`, which is the pair of edits Kamal needs to pass a
   secret through to the containers.
 
-What the generator writes, in every case:
-
-- `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).
-- `.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` for you, so the install either
+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.
 
-## 3. Where the token comes from
+### Where the token comes from
 
 In Railwatch Cloud, create an application, then an environment inside it
 (`production`, `staging`, one token each). The token is shown once, on
@@ -76,12 +141,12 @@ update `RAILWATCH_TOKEN`.
 bin/rails railwatch:token   # prints the URL to create/copy a token
 ```
 
-A token looks like `rw_` followed by 40 characters. The gem is
-completely inert without one: `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. 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.
 
-## 4. Check the wiring
+### Check the cloud wiring
 
 ```sh
 bin/rails railwatch:doctor
@@ -89,12 +154,14 @@ bin/rails railwatch:doctor
 
 ```
 ✓ token: rw_9Qv... (43 chars)
+✓ token storage: no tracked plaintext Railwatch token found
 ✓ ingest url: https://railwatch.rebulk.com
+✓ ingest transport security: HTTPS with certificate verification
 ✓ ingest reachable: GET https://railwatch.rebulk.com/ingest/ping
 ✓ request middleware: Railwatch::Middleware::Request at position 0
 ✓ engine mounted: POST /railwatch/beacon -> railwatch/beacon#create
 ✓ deploy: 8f31c0a42e91 (from GIT_REV)
-✓ sample rates: requests=1.0 jobs=1.0 commands=1.0 scheduled_tasks=1.0 exceptions=1.0
+✓ sample rates: requests=1.0 jobs=1.0 commands=1.0 scheduled_tasks=1.0 channels=1.0 exceptions=1.0
 ✓ ignored record types: none
 ```
 
@@ -102,13 +169,12 @@ 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. Every line and
-what to do about a `✗` is in [`troubleshooting.md`](troubleshooting.md).
+the platform answer 401 and that line is `✗` as well.
 
 `bin/rails railwatch:status` is the one-line version: it pings
 `{ingest_url}/ingest/ping` and prints the ingest URL, deploy, and server.
 
-## 5. Make one request
+## Make one request
 
 ```sh
 bin/rails server
@@ -117,9 +183,10 @@ 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 environment's **Requests** page a couple of
-seconds after you make it — with its queries, cache reads, view renders,
-and log lines already attached to it.
+the request shows up on the **Requests** page (`/railwatch`, or the
+environment in Railwatch Cloud) a couple of seconds after you make it —
+with its queries, cache reads, view renders, and log lines already
+attached to it.
 
 ## Three optional lines
 
@@ -187,8 +254,8 @@ newest issues, deploy markers), Requests (routes table and per-request
 waterfall of every child record), Jobs, Scheduled tasks, Commands,
 Exceptions, Queries (slow list and N+1 list with the app line that
 issued them), Spans, Profiles, Transactions, View renders, Cache, Mail,
-Notifications, Broadcasts, Outgoing requests, Storage, Logs,
-Deprecations.
+Notifications, Broadcasts, Outgoing requests, LLM (RubyLLM calls with
+tokens, cost, cut-offs and tool calls), Storage, Logs, Deprecations.
 
 **Monitoring** — Visits (Inertia page-visit timing and web vitals),
 Users, Tenants, Deploys, Releases (crash-free session and user rates),
@@ -199,6 +266,15 @@ 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.
+
 ### Kamal
 
 Two edits, both of which `--kamal-secrets` makes for you:
@@ -276,9 +352,12 @@ 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.
 - [`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.
+- [`ai-and-mcp.md`](ai-and-mcp.md) — asking an AI assistant what broke
+  (Railwatch Cloud).

data/docs/records.md

@@ -1,7 +1,7 @@
 # Record types
 
 Every record Railwatch ships is a flat hash. See `lib/railwatch/record.rb`.
-This lists all 27, field by field, sourced from the subscriber or patch
+This lists all 28, field by field, sourced from the subscriber or patch
 that builds each one. Field names below are the hash keys as sent over
 the wire: symbols in Ruby, strings in the gzip NDJSON payload.
 
@@ -207,7 +207,7 @@ vs `#execute`. `db:migrate` and other tasks in
 | `name` | Task name, or `"runner"`. |
 | `command` | Full invocation, e.g. `"rake db:seed[foo]"` or `"rails runner SomeScript.run"`. |
 | `exit_code` | 0 on success, `SystemExit`'s status, or 1 on an unhandled exception, clamped to 0-255. |
-| `interactive` | `true` on a `bin/rails runner` an engineer typed or piped (`-`, inline code, or a `.rb` file under `config.interactive_runner_paths`); absent otherwise. Such a run ships this record — with its `exit_code` and `exception_preview` — but its exception is not reported. A deployed script (`rails runner script/nightly.rb`), a rake task, and a job are never interactive. See [Console and runner sessions](replacing-sentry.md#console-and-runner-sessions). |
+| `interactive` | `true` on a `bin/rails runner` an engineer typed or piped (`-`, inline code, or a `.rb` file under `config.interactive_runner_paths`); absent otherwise. Such a run ships this record — with its `exit_code` and `exception_preview` — but its exception is not reported. A deployed script (`rails runner script/nightly.rb`), a rake task, and a job are never interactive. See [Console and runner sessions](replacing-sentry.md#12-console-and-runner-sessions). |
 
 ### `channel_action`
 
@@ -526,14 +526,17 @@ adds the `workflow_*` fields. `cost_nanos` is null rather than zero
 whenever RubyLLM reported no cost or the model registry could not price
 it — an unpriced call is not a free one.
 
-**Concurrent tool calls are not recorded.** RubyLLM's opt-in
-`tool_concurrency` (`:threads` or `:fibers`) runs each tool in a fresh
-thread or fiber. `Railwatch::Current` is backed by
-`ActiveSupport::IsolatedExecutionState`, which a new thread does not
-inherit, so the `tool_call.ruby_llm` event fires with no execution to
-attach to and the record is dropped rather than misattributed. This
-affects every Railwatch subscriber in an app-spawned thread, not just this
-one. Tool concurrency is off by default; with it off, tool calls are
+**Tool calls run on their own threads are not recorded.** RubyLLM's opt-in
+`tool_concurrency: :threads` runs each tool in a fresh thread.
+`Railwatch::Current` is backed by `ActiveSupport::IsolatedExecutionState`,
+which a new thread does not inherit, so the `tool_call.ruby_llm` event
+fires with no execution to attach to and the record is dropped rather
+than misattributed. This affects every Railwatch subscriber in an
+app-spawned thread, not just this one. `:fibers` depends on Rails'
+isolation level: under the default, `:thread`, fibers share their
+thread's state and the tool calls are recorded; with
+`config.active_support.isolation_level = :fiber` they are dropped the same
+way. Tool concurrency is off by default; with it off, tool calls are
 recorded normally. The model calls themselves are unaffected either way,
 so cost is always complete.
 

data/docs/replacing-nightwatch.md

@@ -2,10 +2,12 @@
 
 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 hosted platform turns them into routes, jobs,
-queries, issues, and alerts. 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.
+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
+places the Rails answer is genuinely different.
 
 Railwatch is an independent product and is not affiliated with Laravel or
 Laravel Nightwatch.
@@ -18,10 +20,10 @@ 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
-(default 5,000 records, oldest dropped and counted), and gzip-NDJSON
-POSTs batches to the platform every 2 seconds or every 500 records. There
-is no daemon to install, supervise, or forget to restart, and nothing
-between the app and the ingest URL.
+(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.
+There is no daemon to install, supervise, or forget to restart.
 
 The thread is re-armed after `fork`, so clustered Puma workers and
 forked Solid Queue workers each get their own with no `on_worker_boot`
@@ -50,7 +52,7 @@ Nightwatch's types, and what they're called here:
 | `queued-job` | `enqueued_job` | The enqueue side, in the execution that enqueued it. |
 | `log` | `log` | Lines at or above `log_level`, plus Rails 8.1 structured `Rails.event` events. |
 | `user` | `user` | Resolved once per user per process-hour, not once per request. |
-| deployment (`nightwatch:deploy`) | `Deploy` on the platform | Posted by `railwatch:deploy` or the Kamal `post-deploy` hook, with up to 50 commits so the platform can diff what shipped. |
+| deployment (`nightwatch:deploy`) | `Deploy` on the dashboard | Recorded by `railwatch:deploy` or the Kamal `post-deploy` hook, with up to 50 commits when Git history is at hand, so the dashboard can diff what shipped. |
 | request `stages` | parent `stages` | Same idea, Rails boundaries: `middleware_before`, `action`, `render`, `middleware_after`, `body`. Laravel's `bootstrap` has no equivalent in a warm process — Railwatch reports boot time once per process as a `process` record instead. |
 
 And the types with no Nightwatch counterpart at all: `storage_op` (Active
@@ -59,7 +61,7 @@ Storage), `view_render`, `span` (your own timed blocks), `attachment`,
 `session` (release health), `process`, `health` (Puma pool, Active Record
 pool, Solid Queue backlog), and `profile` (sampled stack profiles).
 
-Field-by-field detail for all 26 is in [`records.md`](records.md).
+Field-by-field detail for all 28 is in [`records.md`](records.md).
 
 ## What "execution" means
 
@@ -76,7 +78,7 @@ it is propagated across services as a W3C `traceparent` on outgoing HTTP
 — an inbound `traceparent` is adopted, so a trace spans services rather
 than stopping at the process boundary.
 
-Practically: on the platform you never look at a query in isolation. You
+Practically: on the dashboard you never look at a query in isolation. You
 open the request, and the query is in its waterfall with everything else
 that execution did.
 
@@ -182,7 +184,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 token or the ingest host is wrong |
+| — | `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 |
 
 ## The three things worth knowing about Rails
 
@@ -211,6 +213,6 @@ See [`testing.md`](testing.md).
 
 ## Next
 
-- [`getting-started.md`](getting-started.md) — install, in five minutes.
+- [`getting-started.md`](getting-started.md) — the two-command install.
 - [`configuration.md`](configuration.md) — every option and env var.
-- [`records.md`](records.md) — all 26 record types, field by field.
+- [`records.md`](records.md) — all 28 record types, field by field.

data/docs/replacing-sentry.md

@@ -8,7 +8,10 @@ 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 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.
 
 ## Decide whether Railwatch covers your workload
 
@@ -30,7 +33,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 supports its documented email, Slack, and webhook paths plus self-hosting. It does not promise Sentry's broader integration catalog. |
+| 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. |
 | 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,
@@ -70,9 +73,11 @@ 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:`** becomes `RAILWATCH_TOKEN`, one token per environment, created
-  in Railwatch Cloud. Self-hosting adds `RAILWATCH_INGEST_URL`. The token is
-  also the on/off switch: with it blank, Railwatch installs nothing.
+- **`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.
 - **`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
@@ -111,7 +116,9 @@ 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, roughly what a `Sentry.init` block turns into:
+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):
 
 ```ruby
 # config/initializers/railwatch.rb
@@ -415,9 +422,9 @@ startRailwatch({
 
 | Sentry | Railwatch |
 |---|---|
-| `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`, `RAILWATCH_TOKEN`). The gate you already have on whether `startRailwatch()` runs at all is the only gate. |
+| `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 ingest token identifies the environment. |
+| `environment` | Automatic — the embedded databases belong to one environment, and on Railwatch Cloud the ingest token identifies it. |
 | `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. |
@@ -561,8 +568,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. |
-| One SQLite database per environment | The platform stores each monitored environment's telemetry in its own database file, which makes retention pruning, backup, and restore per-environment operations. |
-| 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)). |
+| 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)). |
+| 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)). |
 
 ## See also
 

data/docs/security.md

@@ -3,8 +3,25 @@
 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.
+
 ## 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
@@ -35,8 +52,9 @@ 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 sent to Railwatch Cloud. Disable it if source context is
-  outside the application's telemetry policy.
+  backtrace frames are recorded, and sent to Railwatch Cloud when the install
+  reports or exports there. Disable it if source context is outside the
+  application's telemetry policy.
 
 Log record messages are sent exactly as supplied to `Rails.logger`. Railwatch
 does not attempt to parse and partially filter `key=value` text because doing
@@ -46,7 +64,8 @@ and `Railwatch.reject_logs` or `RAILWATCH_IGNORE_LOGS=true` can omit log records
 
 ## Browser beacon
 
-`POST /railwatch/beacon` is the gem's only inbound unauthenticated endpoint. It
+`POST /railwatch/beacon` is the gem's only inbound endpoint that is
+unauthenticated by design. It
 is rate-limited per client IP through the Rails cache (120 requests per minute
 by default), limited to a 256 KiB body, and capped at 50 visits and 50 errors
 per request. Nested error stacks, messages, breadcrumbs, context, visit partial
@@ -88,6 +107,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).
 - 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,5 +1,9 @@
 # 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.
+
 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.
@@ -17,12 +21,16 @@ 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:
+installer to have it written for you (it implies `--cloud`):
 
 ```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.
+
 ## Getting a token
 
 On your install: sign up, create an application, then create an

data/docs/testing.md

@@ -27,10 +27,20 @@ require "railwatch/minitest"
 ```
 
 Railwatch must be *enabled* in the test environment or every block would look
-empty. `config.enabled?` is true when `config.enabled` is set and a token is
-present, so set any non-blank `RAILWATCH_TOKEN` for the test env. Records go to
-an in-memory transport, never over the network. If Railwatch is disabled, the
-matchers raise `Railwatch::SpecHelper::Disabled` rather than quietly passing.
+empty. An embedded install (`transport = :local`) is enabled with no token. A
+cloud install needs a token present, so set any non-blank `RAILWATCH_TOKEN` for
+the test env. Either way records go to an in-memory transport, never over the
+network or into the telemetry database. If Railwatch is disabled, the matchers
+raise `Railwatch::SpecHelper::Disabled` rather than quietly passing.
+
+An embedded install adds its two databases to the `test` environment too, and
+Rails' schema check refuses to run the suite while their migrations are
+pending. `bin/rails db:test:prepare` does not create them, because they keep no
+schema file; run this once locally and as a CI setup step:
+
+```sh
+RAILS_ENV=test bin/rails db:prepare
+```
 
 Sampling is forced on for the block, so a fractional `c.sample` in the app's
 test config can't turn an assertion into one that never fires either.