railwatch 0.5.1 → 0.6.1

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`,
@@ -385,7 +385,7 @@ the app database.
 
 | Attribute | Env var | Default | Meaning |
 |---|---|---|---|
-| `buffer_size` | `RAILWATCH_BUFFER_SIZE` | `10000` | Max buffered records (`Railwatch::Buffer`). Oldest is dropped (and counted) when full — never blocks the request thread. Keep it at or above `Execution::MAX_RECORDS` (10,000): a kept execution's whole tree is written here at once when it ends, and a queue smaller than the tree drops the tree's own oldest records first. |
+| `buffer_size` | `RAILWATCH_BUFFER_SIZE` | `10000` | Max buffered records (`Railwatch::Buffer`). Oldest is dropped (and counted) when full — never blocks the request thread. In practice `buffer_bytes` fills first: on a realistic mix of records, 16 MiB holds about 5,000 of them, so this count is never reached and raising it changes nothing. Tune `buffer_bytes` instead. Do not lower this below `Execution::MAX_RECORDS` (10,000): a kept execution's whole tree is written here at once when it ends, and a queue smaller than the tree drops the tree's own oldest records first. |
 | `buffer_bytes` | `RAILWATCH_BUFFER_BYTES` | `16777216` (16 MiB) | Estimated payload memory the reporter queue may hold. A record count alone does not bound memory: 10,000 records is a few megabytes of ordinary telemetry, or a gigabyte of captured attachments. Oldest records are dropped (and counted) under byte pressure, same as under count pressure. |
 | `execution_buffer_bytes` | `RAILWATCH_EXECUTION_BUFFER_BYTES` | `8388608` (8 MiB) | The same ceiling for one execution's buffered tree, before it finishes. A normal execution keeps its earliest records; a failure-context ring keeps its latest. |
 | `batch_bytes` | `RAILWATCH_BATCH_BYTES` | `8388608` (8 MiB) | Uncompressed NDJSON bytes in one ingest request. A queue holding more than this is delivered as several batches — the tail is kept for the next flush, not dropped. |
@@ -399,13 +399,13 @@ the app database.
 
 Delivery is `Railwatch::Transport::Http`, in
 `lib/railwatch/transport/http.rb`: a gzip NDJSON POST to
-`{ingest_url}/ingest`, with one retry on a raised error or a 5xx within
-each delivery attempt. If that still fails, or ingest returns 402, 408,
-or 429, the immutable batch and its prior drop count are retained for
-retry. Every newly formed batch gets an `X-Railwatch-Batch-Id` UUID. It is
-reused for the immediate HTTP retry and every later reporter retry, so
-the platform can return the first committed result without inserting the
-payload twice. Records written while a request is in flight collect in a
+`{ingest_url}/ingest`, one attempt per delivery. If it raises, or ingest
+returns 402, 408, 429, or a 5xx, the immutable batch and its prior drop
+count are retained for retry; the transport does not retry on its own,
+so each rung of the reporter's ladder costs one timeout, not two. Every
+newly formed batch gets an `X-Railwatch-Batch-Id` UUID. It is reused for
+every reporter retry, so the platform can return the first committed
+result without inserting the payload twice. Records written while a request is in flight collect in a
 separate bounded buffer, so they never change the retained request's
 identity. At most one retained batch plus one live buffer are held in
 memory. The reporter retries with jittered exponential backoff, from one
@@ -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. |
@@ -827,9 +827,25 @@ Railwatch.on_unrecoverable { |error| Rails.error.report(error, handled: true) }
 Called whenever Railwatch rescues one of its own internal errors, ingest
 permanently rejects a batch, or shutdown expires with retained records
 that could not be sent. Retryable delivery failures stay buffered and do
-not fire the callback on every attempt. With no callback registered, this
-falls back to `Railwatch.debug`. That goes to stderr, gated on
-`RAILWATCH_DEBUG`, never `Rails.logger`, so gem-internal failures can
+not fire the callback on every attempt. With no callback registered, a
+recovered internal error falls back to `Railwatch.debug`, gated on
+`RAILWATCH_DEBUG` — the gem carried on and there is nothing to do about it.
+
+**Lost records are different, and are reported by default.** A batch
+dropped after its retry ladder, one the receiver permanently refused, or
+records still unsent when the bounded shutdown ran out of time each print
+one `[railwatch]` stderr line. Telemetry that vanishes silently looks
+exactly like having nothing to report, and a short-lived process — a rake
+task, a `rails runner`, a cron job — gets one bounded shutdown and no
+second chance to mention it.
+
+Two ways out, and the line names both. A registered `on_unrecoverable`
+always wins, which is how an app routes the loss somewhere better
+(`Rails.error.report`). Or set `warn_on_data_loss = false`
+(`RAILWATCH_WARN_ON_DATA_LOSS=false`) and the gem goes back to saying
+nothing.
+
+Either way it is stderr, never `Rails.logger`, so gem-internal failures can
 never themselves become `log` records.
 
 ## Faraday
@@ -868,46 +884,70 @@ 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
-c.http_basic_auth_enabled = true      # RAILWATCH_HTTP_BASIC_AUTH_ENABLED; on and closed until credentials exist
+c.http_basic_auth_enabled = true      # RAILWATCH_HTTP_BASIC_AUTH_ENABLED; on, and closed outside development until credentials exist
 c.http_basic_auth_user = "ops"        # RAILWATCH_HTTP_BASIC_AUTH_USER, or credentials railwatch.http_basic_auth_user
 c.http_basic_auth_password = "..."    # RAILWATCH_HTTP_BASIC_AUTH_PASSWORD, or credentials railwatch.http_basic_auth_password
 c.base_controller_class = "AdminController"  # RAILWATCH_BASE_CONTROLLER_CLASS; default ActionController::Base
-c.dashboard_open = false              # RAILWATCH_DASHBOARD_OPEN; 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
 own `railwatch_telemetry` database instead of POSTing it, and the engine
 serves the dashboard at its mount. `enabled?` no longer needs a token.
 The others only matter in that mode. The dashboard is behind HTTP Basic
-by default and answers 401 until `bin/rails
+by default and, outside development, answers 401 until `bin/rails
 railwatch:authentication:configure` has written credentials; a host with
 its own admin auth turns Basic off and sets `base_controller_class` or a
 routes constraint. Full walkthrough: [Embedded mode](embedded.md).
 
+### Export to Railwatch Cloud
+
+An embedded install can also mirror every record to Railwatch Cloud.
+Off unless `export_enabled` is set; a configured token alone sends
+nothing. Only meaningful with `transport = :local`.
+
+| Attribute | Env var | Default | Meaning |
+|---|---|---|---|
+| `export_enabled` | `RAILWATCH_EXPORT_ENABLED` | `false` | Mirror every record to the cloud as well as storing it locally. |
+| `export_token` | `RAILWATCH_EXPORT_TOKEN` | `token` | Cloud environment token to send with. |
+| `export_url` | `RAILWATCH_EXPORT_URL` | `{ingest_url}/ingest` | Where to send. |
+| `export_max_bytes` | `RAILWATCH_EXPORT_MAX_BYTES` | `268435456` (256 MiB) | Queue ceiling in bytes. At capacity new work is refused and counted, not swapped for old. |
+| `export_max_deliveries` | `RAILWATCH_EXPORT_MAX_DELIVERIES` | `100000` | Queue ceiling in deliveries. |
+| `export_max_age` | `RAILWATCH_EXPORT_MAX_AGE_SECONDS` | `86400` | How long a queued delivery is kept. At most seven days, past which the receiver no longer recognises it. |
+
+`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`,
@@ -915,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

data/docs/embedded.md

@@ -1,18 +1,17 @@
 # Embedded mode: the dashboard inside your app
 
-Railwatch can keep every record in your own application and serve 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
 
@@ -25,24 +24,40 @@ up:
 | **Cloud** | Railwatch Cloud | the hosted one |
 | **Both** | your app's files, *and* Railwatch Cloud | either |
 
-Embedded is `c.transport = :local`, which is what `--local` writes.
-Cloud is the default. "Both" is embedded plus one more line:
+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).
+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
 
@@ -59,13 +74,16 @@ documents: `id`, `slug`, `name`, `with_telemetry`, and the display attributes.
 
 ```sh
 bundle add railwatch
-bin/rails generate railwatch:install --local
+bin/rails generate railwatch:install
 ```
 
-Restart the app and open `/railwatch`. 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.
+Restart the app and open `/railwatch`; in development it is open with no
+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
@@ -79,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 --local   # adds gem "sqlite3", writes the config
+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 `--local` writes, on top of the usual install:
+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.
@@ -104,6 +123,8 @@ What `--local` writes, on top of the usual install:
   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.
@@ -132,23 +153,32 @@ 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, 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
 RAILS_ENV=production bin/rails railwatch:authentication:configure
 ```
 
-which writes them to that environment's Rails credentials:
+The one exception is development. There, with Basic on and no
+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:
 
 ```yml
 railwatch:
@@ -256,18 +286,25 @@ 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
 
 Puma forks one Railwatch writer from its master when `config/puma.rb`
-carries the plugin (`--local` adds it):
+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
@@ -319,6 +356,17 @@ through `Railwatch.on_unrecoverable`, so loss is never silent. A Puma
 phased restart stops the writer and starts a fresh one once the new
 workers are up.
 
+Stopping the writer is bounded. Puma sends it TERM and waits up to
+`c.shutdown_timeout` (2 seconds) for it to exit, the same allowance it
+gives its own reporter, then kills it. A writer killed mid-batch loses
+nothing: the transaction rolls back and the worker retries that batch by
+id against the next writer, so waiting longer for its drain would buy no
+data. The bound is what keeps Puma's exit short when the writer is wedged
+in a SQLite write or on a full disk. It counts against the container's
+stop grace (Docker's default is 10 seconds; Kamal's `stop_timeout` sets
+it), and `RAILWATCH_SHUTDOWN_TIMEOUT` raises it for an app whose grace
+allows more.
+
 ## Maintenance
 
 Railwatch needs no job worker and nothing in `config/recurring.yml`.
@@ -371,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
 ```
@@ -383,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
 
@@ -445,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.**
 
@@ -182,10 +194,10 @@ being silent.
 A queue holding more than one batch is delivered as several batches: the
 tail is put back for the next flush rather than dropped.
 
-A background thread drains the buffer and POSTs. Each POST retries one
-raised network error or 5xx immediately. If delivery still fails, the batch
-and its drop counter go back into the bounded buffer; **402**, **408**,
-**429**, and all **5xx** responses are retained the same way. So is a **2xx
+A background thread drains the buffer and POSTs, one attempt per delivery.
+If it fails, the batch and its drop counter go back into the bounded
+buffer; a raised network error, **402**, **408**, **429**, and all **5xx**
+responses are retained the same way. So is a **2xx
 that cannot acknowledge the batch** — a proxy's HTML sign-in page, malformed
 JSON, or `accepted`/`rejected` counts that do not cover what was sent — which
 would otherwise be a silent drop. The reporter
@@ -217,7 +229,8 @@ already appear on its own ingest batch. Those are visible under
 On shutdown, `at_exit` gives the thread `c.shutdown_timeout` (2 seconds) to
 attempt retained records immediately and retry within the remaining time.
 If the deadline expires, the records stay retained and their count is sent
-to `Railwatch.on_unrecoverable` (or stderr under `RAILWATCH_DEBUG=1`). This is an
+to `Railwatch.on_unrecoverable` (or, with no callback, to `Railwatch.debug`, and
+to stderr by default, which `warn_on_data_loss = false` turns off). This is an
 in-memory buffer, not an on-disk spool: a hard kill, or exiting after that
 deadline, cannot carry those records into the next process. Railwatch never
 uses `Rails.logger` for its own failures, which would turn them into `log`