railwatch 0.6.0 → 0.6.1

data/docs/embedded.md

@@ -1,18 +1,17 @@
 # Embedded mode: the dashboard inside your app
 
-This is the default. Railwatch keeps every record in your own application
-and serves the full dashboard at `/railwatch`, with no token and no cloud. The gem's
-reporter, buffer and sampling are the same; the only difference is
-where a batch ends up. In embedded mode it is written straight into a
-SQLite database your app owns, and the dashboard reads it back from
-there.
+This is what the installer sets up by default. Railwatch keeps every
+record in your own application and serves the full dashboard at
+`/railwatch`, with no token and no cloud. The gem's reporter, buffer and
+sampling are the same as with the cloud; the only difference is where a
+batch ends up. In embedded mode it is written into a SQLite database
+your app owns, and the dashboard reads it back from there.
 
 Use it when one server runs the app. Telemetry lands in a file next to
 your other SQLite databases, so several servers would each see only
-their own slice. For more than one server, or for a team that wants one
-place for many apps, point the gem at Railwatch Cloud instead
-([Getting started](getting-started.md)); the two are switchable with
-one setting.
+their own slice. For more than one server, or one place for many apps,
+add Railwatch Cloud: export alongside embedded, or the cloud on its own
+([Getting started](getting-started.md#railwatch-cloud-instead)).
 
 ## Three ways to run it
 
@@ -27,23 +26,38 @@ up:
 
 Embedded is `c.transport = :local`, which is what the installer writes
 unless you ask it for the cloud (`--cloud`, or any token or URL option).
-Cloud is the gem's default when no initializer says otherwise. "Both" is embedded plus one more line:
+With no initializer setting it, the runtime default is `:http`, the
+cloud. "Both" is embedded plus export, which needs a Railwatch Cloud
+environment token. The default embedded install has none, so set one
+first (`bin/rails railwatch:token` prints where to create it), plus the
+ingest URL if you self-host:
+
+```sh
+RAILWATCH_TOKEN=rw_...
+RAILWATCH_INGEST_URL=https://telemetry.example.com   # only when self-hosting
+```
+
+With a token in place, export is one more line:
 
 ```ruby
 c.export_enabled = true   # or RAILWATCH_EXPORT_ENABLED=true
 ```
 
-It reuses the token and ingest URL you already have, so an install that
-was pointed at the cloud and moved to embedded needs nothing else to send
-to both. Everything captured locally is mirrored — the same records the
-same install would have sent had you chosen the cloud — so the hosted
-dashboard is as complete as it would be either way.
+It reuses `RAILWATCH_TOKEN` and `RAILWATCH_INGEST_URL`
+(`RAILWATCH_EXPORT_TOKEN` and `RAILWATCH_EXPORT_URL` override them), so
+an install that was pointed at the cloud and moved to embedded needs
+nothing else. Every record captured locally is mirrored, so the hosted
+dashboard is as complete as a cloud-only install's, and `/railwatch`
+keeps working.
 
 It is off unless you set that flag. A token being present is not consent:
 an embedded install that has one configured still sends nothing.
 `railwatch:doctor` says nothing about export until you ask for it, and
-fails loudly if you ask for it and it cannot work. `railwatch:export:status`
-shows what is queued.
+fails if you ask for it and it cannot work. `railwatch:export:status`
+shows what is queued. The queue is durable, in the telemetry database,
+and bounded: 256 MiB (`RAILWATCH_EXPORT_MAX_BYTES`), 100,000 deliveries
+(`RAILWATCH_EXPORT_MAX_DELIVERIES`), and a day's age
+(`RAILWATCH_EXPORT_MAX_AGE_SECONDS`, at most seven days).
 
 ## Railwatch Cloud runs the same models
 
@@ -64,10 +78,12 @@ bin/rails generate railwatch:install
 ```
 
 Restart the app and open `/railwatch`; in development it is open with no
-password (see [Authentication](#authentication) for production). Then `bin/rails railwatch:doctor`
-checks the wiring. The generator creates and migrates both databases
-itself; `bin/rails db:prepare`, which a deploy already runs, migrates
-them after every gem update.
+password (see [Authentication](#authentication) for production).
+`bin/rails railwatch:doctor` checks the wiring. When the `sqlite3` gem
+is already in the bundle, the generator creates and migrates both
+databases itself; when it is not, see the next section. After that,
+`bin/rails db:prepare`, which a deploy already runs, migrates them after
+every gem update.
 
 The engine needs Active Job (its grouping and scan jobs are Active Job
 classes even though embedded mode calls them directly) and loads it
@@ -81,20 +97,21 @@ databases it adds are SQLite files either way, so the generated entries
 name `adapter: sqlite3` themselves rather than inheriting your default
 block, and they need no `&default` anchor to exist.
 
-On a PostgreSQL or MySQL app that means the install is two commands
-rather than one, because SQLite's adapter gem will not be in your bundle:
+On a PostgreSQL or MySQL app without the `sqlite3` gem, the install
+takes two more commands:
 
 ```sh
 bin/rails generate railwatch:install   # adds gem "sqlite3", writes the config
 bundle install
-bin/rails db:prepare                           # creates the two SQLite files
+bin/rails db:prepare                   # creates the two SQLite files
 ```
 
 Verified end to end on both. On a PostgreSQL app and on a MySQL app, the
 application's own four databases stay where they were, Railwatch's two are
 files under `storage/`, and neither server gains a single Railwatch table.
 
-What the embedded install writes, on top of what every install writes:
+What the embedded install writes, on top of what every install writes
+(listed in [Getting started](getting-started.md#what-the-generator-writes)):
 
 - `config/initializers/railwatch.rb` with `c.transport = :local` and the
   dashboard's own paths excluded from request capture.
@@ -106,6 +123,8 @@ What the embedded install writes, on top of what every install writes:
   databases need that form. Each entry's `migrations_paths` points into
   the gem, so `db:prepare` builds the tables from the gem's own
   migrations and nothing is copied into `db/`.
+- `plugin :railwatch` at the end of `config/puma.rb`, which forks the
+  [writer process](#the-writer-process).
 - `mount Railwatch::Engine, at: "/railwatch"`, as always.
 
 Nothing touches your primary database.
@@ -134,16 +153,19 @@ inside the gem, so the app needs no Node, no Vite and no asset pipeline
 integration.
 
 Not in embedded mode: accounts and members (the operator is whoever your
-app lets through), integrations (alerts are recorded, not delivered),
-and the MCP server.
+app lets through), integrations (alerts are recorded, not delivered to
+Slack, email, webhooks or Linear), and the
+[MCP server](ai-and-mcp.md). Those are Railwatch Cloud's, and
+[export](#three-ways-to-run-it) gets them without giving up the local
+dashboard.
 
 ## Authentication
 
 The dashboard shows every query, log line and exception your app
 produced, so it works the way Mission Control Jobs does: **HTTP Basic
-authentication is on and closed by default**. With no credentials
-configured every dashboard request is 401, the app logs a warning at
-boot, and `railwatch:doctor` says so. Set them with
+authentication is on by default, and closed until credentials exist**.
+With none configured every dashboard request is 401, the app logs a
+warning at boot, and `railwatch:doctor` says so. Set them with
 
 ```sh
 bin/rails railwatch:authentication:configure
@@ -151,11 +173,10 @@ RAILS_ENV=production bin/rails railwatch:authentication:configure
 ```
 
 The one exception is development. There, with Basic on and no
-credentials set, the dashboard is open, so a first run is the install and
-a page rather than a password step first; Rails already shows full error
-pages in development for the same reason. Set credentials there too and
-development asks for them like everywhere else. Test, staging and
-production are closed until you do.
+credentials set, the dashboard is open, so a first run needs no password
+step; Rails shows full error pages in development for the same reason.
+Set credentials there too and development asks for them like everywhere
+else. Test, staging and production are closed until you do.
 
 `railwatch:authentication:configure` writes them to that environment's Rails credentials:
 
@@ -265,8 +286,10 @@ no user table to check it against. Comments, saved views, issue activity
 and assignment all key off whatever you return, so a person keeps their
 own views and their name on their own comments however you identify them.
 
-Returning `nil` refuses the request, which is what makes this an
-authorisation rule as well as a label.
+On a page, returning `nil` does not refuse the request: the page renders
+with the default "Operator". With HTTP Basic off, `nil` refuses the
+live-update subscription. Pages are gated by HTTP Basic, your
+`base_controller_class`, or a mount constraint, never by this resolver.
 
 ## The writer process
 
@@ -274,9 +297,14 @@ Puma forks one Railwatch writer from its master when `config/puma.rb`
 carries the plugin (the embedded install adds it):
 
 ```ruby
-plugin :railwatch if defined?(Railwatch)
+plugin :railwatch
 ```
 
+Leave it unconditional: `bundle exec puma` reads this file before it
+loads the app, so `if defined?(Railwatch)` would be false there and no
+writer would start. The plugin does nothing when Railwatch is off or not
+in embedded mode.
+
 Every web worker keeps its reporter thread, but instead of writing
 SQLite it hands each batch to the writer over a Unix socket
 (`tmp/sockets/railwatch-writer.sock`, `RAILWATCH_WRITER_SOCKET`). The
@@ -391,7 +419,7 @@ Railwatch.configure do |c|
   c.retention_days = 7            # RAILWATCH_RETENTION_DAYS
   c.http_basic_auth_enabled = true    # RAILWATCH_HTTP_BASIC_AUTH_ENABLED; credentials from Rails credentials or env
   c.base_controller_class = "ActionController::Base"  # RAILWATCH_BASE_CONTROLLER_CLASS
-  c.dashboard_open = false            # RAILWATCH_DASHBOARD_OPEN; "yes, public, on purpose"
+  c.dashboard_open = false            # RAILWATCH_DASHBOARD_OPEN; true makes it public on purpose
   c.dashboard_user = ->(request) { ... }
 end
 ```
@@ -403,8 +431,11 @@ a busy app.
 ## Deploys
 
 `bin/rails railwatch:deploy` records the marker in the app's own
-database instead of posting it, and the Kamal post-deploy hook does the
-same when `RAILWATCH_TRANSPORT=local` is set on the deployer.
+database instead of posting it. The Kamal post-deploy hook runs on the
+deployer, which does not read your initializer, so it only knows the
+install is embedded when `RAILWATCH_TRANSPORT=local` is set in the
+deployer's environment. Then it runs `railwatch:deploy` inside the
+primary container.
 
 ## Storage and overhead
 
@@ -465,6 +496,8 @@ never need to run it again.
 
 ## Switching to the cloud later
 
-Set a token and drop `c.transport = :local` (or set
+To keep the local dashboard and add the cloud, turn on
+[export](#three-ways-to-run-it). To move to the cloud entirely, set a
+token and drop `c.transport = :local` (or set
 `RAILWATCH_TRANSPORT=http`). The local databases can stay; the dashboard
 at `/railwatch` keeps reading what is there until it is pruned.

data/docs/faq.md

@@ -51,20 +51,26 @@ 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 shipped by a background thread. That is not a
-nicety: instrumentation that takes a write lock is what turns a
+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
+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?
 
-To the platform, over one gzip-NDJSON POST to `{ingest_url}/ingest` per
+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).
+
+Railwatch Cloud: one gzip-NDJSON POST to `{ingest_url}/ingest` per
 batch. The platform 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 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 install, retention,
-backups, and pruning are the platform operator's responsibility.
+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.
 
 ## What about PII?
 
@@ -119,8 +125,9 @@ 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. SQL normalization is per adapter, so SQLite, Postgres, MySQL, and
-Trilogy all group correctly.
+writer. Embedded mode's own two databases are separate SQLite files,
+whatever the app runs on. 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
@@ -163,6 +170,11 @@ 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.
+
 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,26 +1,99 @@
 # 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.
 
-The installer's default is embedded: the dashboard inside the app at
-`/railwatch`, no token and no cloud; see [Embedded mode](embedded.md).
-This page is the cloud install, which is the same generator with
-`--cloud` or any of the token options below.
-
-## 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
+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
 ```
 
@@ -51,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
@@ -80,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
@@ -93,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
 ```
 
@@ -106,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
@@ -121,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
 
@@ -191,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),
@@ -203,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:
@@ -280,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.