railwatch 0.6.0 → 0.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6da9b1e629335b1623cfc24e8b18c5a5d17bed076630768b9d947ff2d0b1a5c2
-  data.tar.gz: 827e8cc13fa4e1373bd6656c851e7fabbdfe2af60c37432c9feeb10801972367
+  metadata.gz: 293f64188856fdbadb54fb91bc640441a0996ba3d914d320b778c72536cbb3a8
+  data.tar.gz: b10e36a4cbb054e5170d1984003be84d2ea62acee2c1a3bda1c3b560a5f54bab
 SHA512:
-  metadata.gz: 741964c31992572e63aeabb9a601482d4a4facb6f895ac1c3fe362c9e0f493f7e7b7636b070bc0909b764e38514495f838e8dbda9de5fef8423cd978fc833281
-  data.tar.gz: 2eb78e494a27b97451023876f6e72e1cb73bf4aebacb002af148d674841a3f62348c2992cd131d16f7cc75a6308203d68da2738b1431791c4a15fd134b7d3fc4
+  metadata.gz: 7e45fc461237f0d9aceccbd99f359b8a81a404d6620600361d3d4fd973f986baf32779ea3921f581a81527c4764687aa8771897c466498860cd8f30c53cd5e4b
+  data.tar.gz: 5152d7d1b250d98299e2f675a951ec6f544e0a91405365877b434e8fa6fb1cbfddf061f84fe06aca00cb9202de0092f0016c024779707e69f9d400d33117a007

data/AGENTS.md

@@ -4,11 +4,12 @@ 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 ships linked telemetry to
+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
-an **execution**; every query, cache read, log line, outgoing HTTP call, view
-render, exception, and span is a child of one, linked by
-`execution_id`/`trace_id`. It never writes to the app's database.
+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.
 
 ## Install
 
@@ -19,24 +20,35 @@ bin/rails generate railwatch:install --prompt-token --kamal-secrets  # or: Railw
 ```
 
 With no flags the install is embedded (see [Embedded mode](docs/embedded.md)):
-telemetry stays in two SQLite databases the app owns and the dashboard is served
-at `/railwatch`. `--cloud`, or any of `--prompt-token`, `--token-stdin`, `--url`,
-`--kamal-secrets`, sends it to Railwatch Cloud instead. For the cloud install the generator writes `config/initializers/railwatch.rb`, mounts `Railwatch::Engine`
-at `/railwatch`, 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 then runs `railwatch:doctor`. 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.
+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
+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`.
 
 ## Rake tasks
 
 | Task | Does |
 |---|---|
-| `bin/rails railwatch:doctor` | ✓/✗ per check: token, ingest URL, reachability, middleware, engine mount, deploy marker, sample rates, ignored types, Kamal hook, browser client and whether an entrypoint calls it, profiler backend, test matchers. Exits non-zero if the token is missing or the host is unreachable. **Run this first when telemetry is missing.** |
-| `bin/rails railwatch:token` | Where to create an ingest token for this app's platform. |
-| `bin/rails railwatch:mcp` | Paste-ready MCP client configuration for this app's platform. |
-| `bin/rails railwatch:deploy[ref,name,url]` | Records a deploy marker. Use as a release step when not deploying with Kamal. |
+| `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: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
@@ -77,9 +89,11 @@ 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 — set any
-non-blank `RAILWATCH_TOKEN`; records go to an in-memory transport, never over the
-wire. All matchers are block matchers.
+`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
+go to an in-memory transport, never over the wire. All matchers are block
+matchers.
 
 ```ruby
 expect { get "/widgets" }.to have_railwatch_queries(at_most: 6)   # or exactly:/at_least:
@@ -102,8 +116,8 @@ melt in production.
 
 ## MCP
 
-The platform is an MCP server at `<ingest host>/mcp`. Generate a personal
-token at Settings → Profile → "API & MCP token", then:
+Railwatch Cloud (not embedded mode) is an MCP server at `<ingest host>/mcp`.
+Generate a personal token at Settings → Profile → "API & MCP token", then:
 
 ```sh
 claude mcp add railwatch --transport http https://railwatch.rebulk.com/mcp \
@@ -112,10 +126,12 @@ claude mcp add railwatch --transport http https://railwatch.rebulk.com/mcp \
 
 `bin/rails railwatch:mcp` prints this and the Claude Desktop, Cursor, VS Code, and
 Zed equivalents for whichever platform the app points at. Call
-`list_applications` first; then `list_issues`, `get_issue`, `get_route`,
-`search_requests`, `get_execution`, `explain_query`, `get_profile`,
-`search_logs`, `release_health`, `recent_deploys`, `list_alerts`, and the
-`triage_issue` / `slow_route` / `daily_summary` prompts. All durations are
+`list_applications` first; then `list_issues`, `get_issue` (stack frames,
+cause, locals, breadcrumbs), `get_route`, `search_requests`, `get_execution`,
+`explain_query`, `get_profile`, `search_logs`, `search_telemetry`,
+`release_health`, `recent_deploys`, `list_alerts`, and the `triage_issue` /
+`slow_route` / `daily_summary` prompts. `update_issue` and `add_comment` write,
+attributed to the token's user and your agent name. All durations are
 milliseconds; these docs are served at `railwatch://docs/<name>`.
 
 ## Gotchas

data/CHANGELOG.md

@@ -6,6 +6,34 @@
      filled in by the release commit, which is also the only commit that
      touches lib/railwatch/version.rb and Gemfile.lock. See CONTRIBUTING.md. -->
 
+## 0.6.1 (2026-09-23)
+
+- The docs describe embedded as the default install throughout: two
+  commands, then optional Railwatch Cloud. They correct what 0.6.0 left
+  stale: an embedded install needs no token; the PostgreSQL and MySQL
+  steps; export needs a token first; a `dashboard_user` resolver names
+  the operator but does not gate pages; the Puma plugin line must be
+  unconditional; an embedded app's test databases need one
+  `RAILS_ENV=test bin/rails db:prepare`. MCP is marked as a Railwatch
+  Cloud feature. LLM calls are listed.
+- The installer's embedded next steps say to get a token before turning
+  on export.
+- Draw the Trend sparklines. Recharts pads every side of a chart by 5px,
+  which left the 32x10 table-cell sparkline a plot area 0px tall, so every
+  Trend column on every page was blank.
+- LLM calls: a failed call no longer counts as "unpriced". It used no
+  tokens and has nothing to price, yet any failure made its model read
+  "+N unpriced" beside a complete spend total; the Recent table shows "–"
+  for it instead. The model and tool call charts label their bars ok /
+  failed instead of HTTP status classes, and the Recent table's Call
+  column truncates instead of pushing Detail off the right edge.
+- Issues: the daily chart marks each deploy day with a line and names the
+  deploys in the tooltip, instead of printing refs that overprint when
+  several ship in a week.
+- Jobs: the recent runs card keeps the job name readable. The exception
+  truncates, and the origin user and tenant columns appear from 2xl up
+  (the job class page shows them at every width).
+
 ## 0.6.0 (2026-09-22)
 
 - Embedded is now the installer's default. `bin/rails generate

data/README.md

@@ -9,9 +9,10 @@ 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, for
-alerts that arrive when the app is down, MCP for your AI assistant, and
-many apps and servers in one place.
+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.
 
 ## Install
 
@@ -23,9 +24,12 @@ bin/rails generate railwatch:install  # 2. embedded: databases, Puma writer, das
 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).
+(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.
 
-Or send everything to Railwatch Cloud instead:
+To send everything to Railwatch Cloud instead, pass `--cloud` or a token
+option:
 
 ```sh
 bundle add railwatch
@@ -33,10 +37,10 @@ bin/rails generate railwatch:install --prompt-token  # hidden token input plus a
 bin/rails railwatch:doctor                          # check every piece is wired up after restart
 ```
 
-Getting the token, the generator's flags, and deploying with Kamal,
+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 a self-hosted deployment
-or an unreleased revision, use the Git source instead:
+[Getting started](docs/getting-started.md). For an unreleased revision,
+use the Git source instead:
 
 ```ruby
 gem "railwatch", github: "Rebulk/railwatch"
@@ -52,12 +56,16 @@ gem "railwatch", github: "Rebulk/railwatch"
   ([Configuration](docs/configuration.md)).
 - An optional stack profiler through `vernier` or `stackprof`, off by
   default ([Configuration](docs/configuration.md)).
+- LLM calls made through RubyLLM: tokens, cost, cut-off answers, tool
+  calls and workflows, each tied to the request or job that made it
+  ([Record types](docs/records.md#llm_call)).
 - A browser client for Inertia apps: page-visit timing, Core Web Vitals,
   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)).
-- An MCP server so Claude Code, Cursor, VS Code, or Zed can read your
-  production data ([AI assistants and MCP](docs/ai-and-mcp.md)).
+- With Railwatch Cloud, an MCP 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
 also have a `RAILWATCH_*` environment variable.
@@ -79,11 +87,11 @@ expect { get "/widgets" }.not_to have_railwatch_n_plus_one
 
 ## Embedded mode
 
-The default install keeps everything inside the application. Telemetry goes to two
-SQLite files it 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, and there is nothing else to run.
+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
@@ -92,20 +100,21 @@ 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 outside development it is closed by default the way
-Mission Control Jobs is: HTTP Basic is on with no credentials, and every
-request is 401 until you set them with
-`bin/rails railwatch:authentication:configure`. In development, with no
-credentials set, it is open. Apps that
-would rather use their own session hand it a `dashboard_user` resolver
-instead. [Embedded mode](docs/embedded.md) covers all of it, including
-upgrades and what it costs to store.
+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) — five-minute install for a
-  Rails 8 app, the three optional lines, and deploying with Kamal, Docker,
-  Heroku, Render, or none of them.
+- [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.
 - [Configuration](docs/configuration.md) — every option and `RAILWATCH_*`
   variable, field by field.
 - [Record types](docs/records.md) — every record Railwatch ships and every
@@ -113,13 +122,15 @@ 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.
+  Cursor, VS Code, or Zed to your production data through Railwatch
+  Cloud.
 - [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 whole dashboard inside your
-  app, telemetry in your own SQLite files, no cloud.
+- [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.
 - [Troubleshooting](docs/troubleshooting.md) — every failure mode, paired

data/app/jobs/railwatch/rollup_job.rb

@@ -118,7 +118,9 @@ module Railwatch
          cache_read_tokens: group.sum { |r| r.cache_read_tokens.to_i }, cache_write_tokens: group.sum { |r| r.cache_write_tokens.to_i },
          cost_nanos: group.sum { |r| r.cost_nanos.to_i },
          priced: group.count { |r| r.cost_nanos },
-         unpriced: group.count { |r| r.cost_nanos.nil? },
+         # A call that failed before the provider answered used no tokens,
+         # so there is nothing to price; only an answered call can be unpriced.
+         unpriced: group.count { |r| r.cost_nanos.nil? && r.status != "failed" },
          # A cut-off answer is not an error and will never show in the error
          # rate, so it needs counting on its own or it stays invisible.
          truncated: group.count { |r| r.finish_reason == "max_tokens" },

data/app/models/railwatch/ingest/rollup_absorber.rb

@@ -160,7 +160,7 @@ module Railwatch
           extra["cache_write_tokens"] += row[:cache_write_tokens].to_i
           extra["cost_nanos"] += row[:cost_nanos].to_i
           extra["priced"] += 1 if row[:cost_nanos]
-          extra["unpriced"] += 1 if row[:cost_nanos].nil?
+          extra["unpriced"] += 1 if row[:cost_nanos].nil? && row[:status] != "failed"
           extra["truncated"] += 1 if row[:finish_reason] == "max_tokens"
           extra["with_attachments"] += 1 if row[:attachments].to_i.positive?
         end

data/docs/ai-and-mcp.md

@@ -9,6 +9,10 @@ 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:
@@ -145,9 +149,9 @@ durations are milliseconds.** Every `window` argument takes `1h`, `6h`,
 
 | Tool | Arguments | Returns |
 |---|---|---|
-| `list_applications` | — | applications, their account, and their environments. Start here — everything else takes the `application_slug` and `environment` this returns. |
+| `list_applications` | — | applications, their account, and their environments. Start here — everything else takes the `application_slug` and `environment` this returns (plus `account_slug`/`application_id` when two accounts share a slug). |
 | `list_issues` | `application_slug?`, `environment?`, `status?` (`open`/`resolved`/`ignored`, default `open`), `limit?` | issues with key, title, kind, status, priority, occurrence and affected-user counts, culprit, first/last seen. |
-| `get_issue` | `key` | one issue plus the sample occurrence: exception class, message, stack frames, and the execution it happened inside. |
+| `get_issue` | `key` or `issue_id` | one issue. For an exception, the sample and latest occurrences with stored stack frames, cause, locals, parsed context, browser breadcrumbs, and the execution it happened inside. For a performance or anomaly issue, the metric, limit or baseline, representative records, trend, and deploy comparison. |
 | `update_issue` | `key`, `status?`, `priority?`, `assignee_email?`, `agent?` | the updated issue. Writes an activity entry attributed to your user and `agent`. |
 | `add_comment` | `key`, `body`, `agent?` | the created comment, attributed the same way. |
 | `list_slow_routes` | `application_slug`, `environment`, `window?` | the 20 slowest routes by p95, each with `group_hash`, count, errors, `p95_ms`. |
@@ -157,6 +161,7 @@ durations are milliseconds.** Every `window` argument takes `1h`, `6h`,
 | `explain_query` | `application_slug`, `environment`, `group_hash`, `window?` | the stored query plan for a query group, with the SQL and the sample's duration. `explain` is null unless the app sets `RAILWATCH_CAPTURE_QUERY_EXPLAIN`. `sql` is the normalized shape unless the app also sets `RAILWATCH_CAPTURE_SQL_VALUES`. |
 | `get_profile` | `application_slug`, `environment`, `profile_id?`, `execution_id?`, `limit?` | the hottest frames of a stack profile — self and total samples, each with a percentage. |
 | `search_logs` | `application_slug`, `environment`, `q`, `level?`, `limit?` | matching log lines, each with the `execution_id` to expand with `get_execution`. |
+| `search_telemetry` | `application_slug`, `environment`, `resource` (`jobs`/`exceptions`/`logs`/`queries`), `q?`, `window?`, `cursor?`, `limit?` | raw rows of that resource with cursor pagination (`meta.next_cursor`, `meta.has_more`). `q` takes `after:`, `before:`, `user:`, `tenant:`, `deploy:`, plus per-resource keys such as `class:`, `queue:`, `level:`. |
 | `list_tenants` | `application_slug`, `environment`, `window?`, `q?` | your app's own tenants (whatever it passes to `Railwatch.context(tenant:)`) with request, error, job, exception, and user counts. |
 | `recent_deploys` | `application_slug`, `environment` | the 20 most recent deploys with ref, name, time, and link. |
 | `release_health` | `application_slug`, `environment`, `window?` | crash-free session rate, crash-free user rate, and adoption per release. |
@@ -220,7 +225,8 @@ Copy either into your own app's repo to give its agent the same context.
 
 ## See also
 
-- [`getting-started.md`](getting-started.md) — install, token, first request.
+- [`getting-started.md`](getting-started.md) — install, the cloud token,
+  first request.
 - [`self-hosting.md`](self-hosting.md) — pointing the gem, and this endpoint,
   at your own platform.
 - [`troubleshooting.md`](troubleshooting.md) — when something isn't

data/docs/configuration.md

@@ -2,18 +2,17 @@
 
 Everything below lives on `Railwatch::Configuration`, in
 `lib/railwatch/configuration.rb`. Set it via
-`Railwatch.configure { |c| ... }` in `config/initializers/railwatch.rb`.
-That file is created by
-`bin/rails generate railwatch:install`. Most settings have a `RAILWATCH_*`
-env var default; the tables below show which. Explicit values set in the
-initializer always win over the env var.
+`Railwatch.configure { |c| ... }` in `config/initializers/railwatch.rb`,
+which `bin/rails generate railwatch:install` creates. Most settings have a
+`RAILWATCH_*` env var default; the tables below show which. Explicit
+values set in the initializer always win over the env var.
 
 ## Core
 
 | Attribute | Env var | Default | Meaning |
 |---|---|---|---|
-| `enabled` | `RAILWATCH_ENABLED` | `true` | Master switch. `Railwatch.enabled?` is also `false` whenever `token` is blank, so setting only `RAILWATCH_TOKEN` is enough to turn Railwatch on. |
-| `token` | `RAILWATCH_TOKEN` | nil | Bearer token for `/ingest`. Required. |
+| `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. |
 | `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. |
@@ -26,7 +25,8 @@ 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 &&
-token.present?`. There is no separate "is configured" check elsewhere.
+(local? || token.present?)`. There is no separate "is configured" check
+elsewhere.
 
 Deploy detection stops at the first value found: `RAILWATCH_DEPLOY`,
 `KAMAL_VERSION`, `GIT_REV`, `GIT_SHA`, `SOURCE_VERSION`,
@@ -569,7 +569,7 @@ Rake tasks and Solid Queue jobs are never interactive.
 
 | Attribute | Env var | Default | Meaning |
 |---|---|---|---|
-| `capture_exception_source` | `RAILWATCH_CAPTURE_EXCEPTION_SOURCE_CODE` | `true` | Send source snippet lines surrounding each in-application exception frame to Railwatch Cloud. 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 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_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. |
@@ -884,7 +884,7 @@ ignore block's building blocks, and are nestable.
 ## Embedded mode
 
 ```ruby
-c.transport = :local        # RAILWATCH_TRANSPORT; default "http"
+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
@@ -892,8 +892,9 @@ c.http_basic_auth_enabled = true      # RAILWATCH_HTTP_BASIC_AUTH_ENABLED; on, a
 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; public on purpose
+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
@@ -905,25 +906,48 @@ 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. |
+
+`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).
+
 ## Rake tasks
 
 Ship with the gem via Rails::Engine's default `lib/tasks` convention, in
 `lib/tasks/railwatch_tasks.rake`:
 
-- **`railwatch:status`** pings `{ingest_url}/ingest/ping` with the
-  configured token. It aborts if `RAILWATCH_TOKEN` is unset or the ping
-  fails.
-- **`railwatch:doctor`** prints a ✓/✗ checklist of the whole install:
-  token, ingest URL, `GET /ingest/ping`, `Railwatch::Middleware::Request`
+- **`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: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`
   in the middleware stack, the mounted engine's beacon route,
-  `config.deploy` and its environment, `REVISION`, Git, or initializer
-  source, sample rates, ignored record types, the Kamal `post-deploy`
-  hook, `app/frontend/lib/railwatch.ts`, and whether `railwatch/rspec` or
-  `railwatch/minitest` is required by the test helper. The last five are
-  informational. It exits non-zero only when the token is missing or the
-  ping fails.
-- **`railwatch:deploy[ref,name,url]`** POSTs `{deploy, ref, name, url,
-  server, timestamp, performer, destination, service, commits}` to
+  `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,
+  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
   passed. `performer`/`destination`/`service` come from `KAMAL_PERFORMER`,
@@ -931,13 +955,30 @@ 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: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. It no-ops when
-`RAILWATCH_TOKEN` isn't set, and never fails a deploy. Every network call
-ends in `|| true`.
+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.
+Every network call ends in `|| true`.
 
 The hook runs on the **deployer machine**, not in a container, which is
 the whole point. That's where the git history lives and where Kamal