railwatch 0.6.0 → 0.6.1

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.

data/docs/troubleshooting.md

@@ -8,20 +8,48 @@ below are keyed to those lines.
 bin/rails railwatch:doctor
 ```
 
-The task exits non-zero only when **token** or **ingest reachable**
-fails. Everything else is informational. A `✗` there means a feature
+The first lines depend on the transport. An embedded install checks its
+databases, writer and dashboard; a cloud install checks its token and
+ingest host. The task exits non-zero only on the lines marked fatal
+below. Everything else is informational: a `✗` there means a feature
 isn't wired, not that the install is broken.
 
+Embedded (`transport = :local`):
+
+| Doctor line | What a `✗` means |
+|---|---|
+| `export` | Only shown with `export_enabled` on. Export is on and cannot work: no token, no URL, a plain-HTTP URL, or an unsupported policy. Fatal. |
+| `export destination` | The export queue is blocked or deferred; the line gives the reason. `bin/rails railwatch:export:rebind` clears a credential block. |
+| `railwatch database`, `railwatch_telemetry database` | The database is missing from `config/database.yml` for this environment. Fatal. Re-run the install generator. |
+| `railwatch migrations`, `railwatch_telemetry migrations` | Migrations are pending. Fatal. Run `bin/rails db:prepare`. |
+| `telemetry disk` | The telemetry database is not in incremental auto-vacuum, so pruning never shrinks the file. See [Embedded mode](embedded.md#giving-the-disk-back). |
+| `maintenance` | No maintenance tick in the last ten minutes. Expected when the app is stopped: the clock runs in the app's processes, not in rake. |
+| `writer process` | The writer socket is not answering, `plugin :railwatch` is missing from `config/puma.rb`, or the socket path is over Linux's 108-byte limit. Expected when the app is stopped. |
+| `last write` | Shown when the writer answers: nothing written in five minutes. With the app serving traffic, the writer is stuck or workers are not reaching it. |
+| `dashboard access` | HTTP Basic is on with no credentials outside development, so every page is 401; or Basic is off and nothing else is declared. Run `bin/rails railwatch:authentication:configure`, or see [Embedded mode](embedded.md#authentication). |
+| `json compatibility` | The installed `json` gem cannot decode on this Rails; see [below](#binjobs-dies-in-a-loop-with-wrong-number-of-arguments-given-2-expected-1). |
+| `recurring.yml` | `config/recurring.yml` still lists `Railwatch::*` jobs from a pre-release. Remove them. |
+
+Cloud (`transport = :http`):
+
 | Doctor line | What a `✗` means |
 |---|---|
 | `token` | `RAILWATCH_TOKEN` is unset or empty. Fatal: nothing is recorded at all. |
+| `token storage` | A plaintext token is in a file Git tracks. Fatal. Move it to credentials or a secret manager. |
 | `ingest url` | `ingest_url` isn't a parseable HTTP(S) URL. |
+| `ingest transport security` | The ingest URL is plain HTTP on a non-loopback host without `RAILWATCH_ALLOW_HTTP=true`. |
 | `ingest reachable` | `GET {ingest_url}/ingest/ping` didn't return success. Fatal. The ping carries the token, so a missing or wrong token fails this line too; fix `token` first. |
+
+Both:
+
+| Doctor line | What a `✗` means |
+|---|---|
 | `request middleware` | `Railwatch::Middleware::Request` isn't in the stack, so requests aren't executions. |
 | `engine mounted` | `mount Railwatch::Engine, at: "/railwatch"` is missing from `config/routes.rb`; the browser beacon has nowhere to post. |
 | `deploy` | `config.deploy` is unset — records ship, charts get no deploy markers. |
 | `sample rates` | Never fails; it prints the effective rate per execution kind. |
 | `ignored record types` | Never fails; it prints what `c.ignore` is dropping. |
+| `interactive sessions` | Never fails; it prints whether consoles are captured and the runner scratch paths. |
 | `kamal post-deploy hook` | `.kamal/hooks/post-deploy` is missing or doesn't mention Railwatch. Only matters if you deploy with Kamal. |
 | `browser client` | `app/frontend/lib/railwatch.ts` isn't there. Only matters for Inertia visit timing. |
 | `browser client imported` | The client exists but nothing calls `startRailwatch()` — no `startRailwatch` found in `app/frontend/entrypoints`. Visits won't report. |
@@ -33,30 +61,35 @@ isn't wired, not that the install is broken.
 **Symptom.** The environment's pages stay empty however much traffic the
 app takes.
 
-Work down this list. The first five are the same root cause seen from
+Work down this list. Most of it is the same root cause seen from
 different angles: Railwatch decided not to record.
 
-**The token is missing or blank.** `Railwatch.enabled?` is
-`config.enabled && token.present?`. With no token the engine's
-`railwatch.subscribe` initializer returns early, so no subscribers and no
-patches are installed at all. This is by design, so the gem is inert in
-development. Fix: set `RAILWATCH_TOKEN`, restart, and re-run
-`railwatch:doctor`. The `token` line prints the first 6 characters and
-the length, which is enough to spot a truncated or quoted value.
+**Embedded: the writer is not writing.** Run `railwatch:doctor` with the
+app serving traffic. `writer process` and `last write` say whether the
+writer is up and when it last wrote; the migrations lines catch a
+database that was never prepared.
+
+**Cloud: the token is missing or blank.** With `transport = :http`,
+`Railwatch.enabled?` is `config.enabled && token.present?`. With no token
+the engine's `railwatch.subscribe` initializer returns early, so no
+subscribers and no patches are installed at all. Fix: set
+`RAILWATCH_TOKEN`, restart, and re-run `railwatch:doctor`. The `token`
+line prints the first 6 characters and the length, which is enough to
+spot a truncated or quoted value.
 
-**The token is wrong.** A 401 from the ingest marks the transport
+**Cloud: the token is wrong.** A 401 from the ingest marks the transport
 permanently unauthorized: no further flush is attempted for the lifetime
 of that process. Fixing the env var isn't enough. Restart the process.
 `railwatch:doctor`'s `ingest reachable` line catches this before you
 deploy.
 
-**`RAILWATCH_INGEST_URL` points somewhere else.** Records go where you sent
-them. `railwatch:status` prints the URL it is actually using. Compare it
-against the platform you're looking at. Self-hosting: see
+**Cloud: `RAILWATCH_INGEST_URL` points somewhere else.** Records go where
+you sent them. `railwatch:status` prints the URL it is actually using.
+Compare it against the platform you're looking at. Self-hosting: see
 [`self-hosting.md`](self-hosting.md).
 
 **`config.enabled` is false.** `RAILWATCH_ENABLED=0` (or `false`/`no`/`off`)
-turns everything off with a valid token present.
+turns everything off, embedded or not.
 
 **Sample rates are at zero.** `c.sample = { requests: 0.0 }` means no
 request records. So does the per-route `railwatch_never_sample` macro on
@@ -70,11 +103,11 @@ rather than a broken install.
 built. The `ignored record types` doctor line prints the list. Ignoring
 `:queries` also drops `n_plus_one`, since both key off `:queries`.
 
-**You're looking at the test environment.** Requiring `railwatch/rspec`
-(or `railwatch/minitest`) swaps the reporter's transport for an in-memory
-one. A suite records normally but never sends anything over the
-network. Independently: the health sampler, the session flusher, and the
-profiler all refuse to start when `Rails.env.test?`.
+**You're looking at the test environment.** The spec helpers swap the
+reporter's transport for an in-memory one, so a suite records normally
+but never sends or stores anything. Independently: the health sampler,
+the session flusher, and the profiler all refuse to start when
+`Rails.env.test?`.
 
 Still nothing? Set `RAILWATCH_DEBUG=1` and restart. Internal diagnostics go
 to stderr prefixed `[railwatch]`. They never go to `Rails.logger`, so they
@@ -296,7 +329,13 @@ hook below.
 
 **Cause and fix**, in the order the hook itself checks:
 
-- **`RAILWATCH_TOKEN` isn't exported to the hook.** The first thing
+- **Embedded: `RAILWATCH_TRANSPORT=local` isn't exported to the hook.**
+  The hook reads the deployer's environment, not your initializer. With
+  that variable set it runs `bin/rails railwatch:deploy[$KAMAL_VERSION]`
+  in the primary container, which writes the marker to the embedded
+  database. Without it, the hook treats the install as a cloud one and
+  exits at the next check, since an embedded install has no token.
+- **Cloud: `RAILWATCH_TOKEN` isn't exported to the hook.** The next thing
   `.kamal/hooks/post-deploy` does is `[ -z "$RAILWATCH_TOKEN" ] && exit 0`.
   The hook runs on the deployer machine, in your shell, not in a
   container. So a token that only exists in `.kamal/secrets` for the
@@ -317,8 +356,8 @@ it exits 0 regardless.
 
 ## Log search finds less than it should
 
-**Symptom.** On a Postgres-backed platform install, log search matches
-fewer lines and highlights nothing.
+**Symptom.** On a self-hosted platform backed by Postgres, log search
+matches fewer lines and highlights nothing.
 
 **Cause.** Full-text search uses SQLite's FTS5 (`logs_fts`). The
 platform checks for both a SQLite adapter *and* the `logs_fts` table.

data/lib/generators/railwatch/install/install_generator.rb

@@ -258,10 +258,11 @@ module Railwatch
                  config/puma.rb Puma forks one Railwatch writer process that
                  writes every batch and runs the maintenance clock, so no web
                  process ever holds the telemetry database. No job worker.
-              4. Optional: mirror to Railwatch Cloud for alerts that still
-                 arrive when this app is down, MCP for your AI assistant, and
-                 every app in one place. Set RAILWATCH_TOKEN and
-                 c.export_enabled = true (docs/embedded.md).
+              4. Optional: mirror to Railwatch Cloud for alerts delivered even
+                 when this app is down, MCP for your AI assistant, and every
+                 app in one place. Get a token (bin/rails railwatch:token), set
+                 RAILWATCH_TOKEN, then c.export_enabled = true in the
+                 initializer (docs/embedded.md).
           STEPS
           return
         end

data/lib/generators/railwatch/install/templates/initializer.rb.tt

@@ -5,8 +5,8 @@
 Railwatch.configure do |c|
 <% if local? -%>
   # Telemetry stays in this app's own railwatch_telemetry database and the
-  # dashboard is served at /railwatch. No token, no cloud. Put the mount
-  # behind your own authentication; this only names who is looking.
+  # dashboard is served at /railwatch. No token, no cloud. Who can open the
+  # dashboard is the Access block below.
   c.transport = :local                              # RAILWATCH_TRANSPORT
   c.ignored_request_paths += ["/railwatch", %r{\A/railwatch/}]
   # c.issue_prefix = "APP"                          # RAILWATCH_ISSUE_PREFIX; issue keys like APP-12

data/lib/railwatch/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Railwatch
-  VERSION = "0.6.0"
+  VERSION = "0.6.1"
 end

data/llms.txt

@@ -3,39 +3,42 @@
 > Railwatch is a Ruby gem that instruments a Rails application end to end —
 > requests, jobs, scheduled tasks, rake/runner commands, database queries and
 > N+1s, exceptions, cache, mail, notifications, broadcasts, outgoing HTTP,
-> Active Storage, view renders, and logs — links every one of them into a
-> single execution tree by `execution_id`/`trace_id`, and writes them from a
-> background thread into the app's own SQLite files (embedded, the default) or
-> to Railwatch Cloud. It replaces a separate APM and a
+> Active Storage, view renders, RubyLLM calls, and logs — links every one of
+> them into a single execution tree by `execution_id`/`trace_id`, and writes
+> them from a background thread into two SQLite files the app owns (embedded,
+> the default) or to Railwatch Cloud. It replaces a separate APM and a
 > separate error tracker with one gem and one configuration block, costs
 > under a millisecond of CPU per request, and never writes to the
-> application's own database. Install is `bundle add railwatch` followed by
-> `bin/rails generate railwatch:install`, which by default keeps everything in
-> the app (two SQLite databases, the dashboard at `/railwatch`); with
-> `--cloud` or a token option it ships to Railwatch Cloud instead. It writes
-> the initializer, mounts
-> the beacon engine, adds a Kamal post-deploy hook and the Inertia browser
-> client where the app has them, wires the test matchers, and then runs
-> `bin/rails railwatch:doctor` to print a ✓/✗ line for every piece.
+> application's primary database. Install is `bundle add railwatch` followed
+> by `bin/rails generate railwatch:install`, which by default keeps
+> everything in the app (two SQLite databases, a Puma writer process, the
+> dashboard at `/railwatch`, open in development and password-protected
+> elsewhere); with `--cloud` or a token option it sends to Railwatch Cloud
+> instead, and an embedded install can export to the cloud as well. It
+> writes the initializer, mounts the engine, adds a Kamal post-deploy hook
+> and the Inertia browser client where the app has them, and wires the test
+> matchers. `bin/rails railwatch:doctor` prints a ✓/✗ line for every piece.
 
 ## Docs
 
-- [README](README.md): what Railwatch is, the install, sampling, spans, profiling, tail sampling, and the Sentry option mapping table.
-- [Getting started](docs/getting-started.md): five-minute install for a Rails 8 app, where the token comes from, the three optional lines, and deploying under Kamal, Docker/Heroku/Render, or no deploy tool at all.
+- [README](README.md): what Railwatch is, the install, embedded mode, and where each document fits.
+- [Getting started](docs/getting-started.md): the two-command embedded install, the Railwatch Cloud install and where its token comes from, the three optional lines, and deploying under Kamal, Docker/Heroku/Render, or no deploy tool at all.
+- [Embedded mode](docs/embedded.md): the default install — the dashboard inside the app, its two SQLite databases, dashboard authentication, the Puma writer process, maintenance without a job worker, disk reclaim, and optional export to Railwatch Cloud.
 - [Configuration](docs/configuration.md): every configuration option and its `RAILWATCH_*` environment variable, plus the full public facade, redaction, rejection, transport and buffering behaviour, and the rake tasks.
-- [Record types](docs/records.md): every record type the gem ships and every attribute on it, sourced from the code that builds it.
+- [Record types](docs/records.md): every record type the gem ships and every attribute on it, including RubyLLM calls (tokens, cost, finish reason, tool calls, workflows), sourced from the code that builds it.
 - [Testing](docs/testing.md): the RSpec and Minitest matchers (`have_railwatch_queries`, `have_railwatch_n_plus_one`, `record_railwatch_span`, `record_railwatch_exception`, `have_railwatch_outgoing_requests`) and a CI performance-gate recipe.
 - [Production source maps](docs/source-maps.md): hidden Vite maps, private upload before publishing assets, safe opt-in deletion, resolved browser stacks and default issue grouping.
-- [AI assistants and MCP](docs/ai-and-mcp.md): the MCP endpoint, how to get a token, paste-ready client configuration for Claude Code, Claude Desktop, Cursor, VS Code, and Zed, and every tool, prompt, and resource the server exposes.
+- [AI assistants and MCP](docs/ai-and-mcp.md): Railwatch Cloud's MCP endpoint, how to get a token, paste-ready client configuration for Claude Code, Claude Desktop, Cursor, VS Code, and Zed, and every tool, prompt, and resource the server exposes.
 - [Replacing Sentry](docs/replacing-sentry.md): a step-by-step migration — removing the gems, porting each option, rewriting each call site, breadcrumbs, spans, profiling, attachments, `before_send`, fingerprints, and release health.
 - [Coming from Laravel Nightwatch](docs/replacing-nightwatch.md): the record-type mapping, what "execution" means in Railwatch, sampling parity, and the facade method names in Ruby.
 - [Self-hosting](docs/self-hosting.md): pointing the gem at a self-hosted Railwatch Cloud, creating a token there, and checking the connection.
-- [Troubleshooting](docs/troubleshooting.md): every failure mode paired with the `railwatch:doctor` line it shows up as — no records, doubled scheduled tasks, WebMock in specs, Puma fork, tail-sampling memory, missing profiler, missing deploy marker, Kamal hook, log search, empty tenants.
+- [Troubleshooting](docs/troubleshooting.md): every `railwatch:doctor` line, embedded and cloud, and the failure modes behind them — no records, doubled scheduled tasks, WebMock in specs, Puma fork, tail-sampling memory, missing profiler, missing deploy marker, Kamal hook, log search, empty tenants.
+- [Security](docs/security.md): transport, capture defaults, the browser beacon, token handling, and application responsibilities.
 - [FAQ](docs/faq.md): overhead numbers and how they are measured, retention, what is redacted by default versus opt-in, SQLite, and what happens when the platform is unreachable.
 
 ## For coding agents
 
-- [AGENTS.md](AGENTS.md): how to install and use Railwatch from inside a Rails app — the facade methods, the spec matchers, `railwatch:doctor`, and the MCP hookup.
+- [AGENTS.md](AGENTS.md): how to install and use Railwatch from inside a Rails app — the facade methods, the spec matchers, `railwatch:doctor`, and the Railwatch Cloud MCP hookup.
 
 ## Optional