railwatch 0.5.1 → 0.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6f70fd1ff6ba5db7cfb11bff9fd076b480d6ac899c0a65694b9fbb7ce4753a10
-  data.tar.gz: da7db6bc23129be7120f38405d522b1be212b76dd7d30435088fbd462e795028
+  metadata.gz: 293f64188856fdbadb54fb91bc640441a0996ba3d914d320b778c72536cbb3a8
+  data.tar.gz: b10e36a4cbb054e5170d1984003be84d2ea62acee2c1a3bda1c3b560a5f54bab
 SHA512:
-  metadata.gz: 7c042d82399b79a4aeefaefd0b6a9d9af3d6868af5b4656d215115b46d84c233bbbe185c6e4692170c36c057431328f66d01ad2b4885d8b470e3cc534dbc17b1
-  data.tar.gz: 8eb054b07c1e559362647bd125e030add13ee7b4d84d03bdd72dd1bfe3b89cdb26d98f961d01c20c682cf320570700abd6d61baca1c7263c5b3b44004d71926b
+  metadata.gz: 7e45fc461237f0d9aceccbd99f359b8a81a404d6620600361d3d4fd973f986baf32779ea3921f581a81527c4764687aa8771897c466498860cd8f30c53cd5e4b
+  data.tar.gz: 5152d7d1b250d98299e2f675a951ec6f544e0a91405365877b434e8fa6fb1cbfddf061f84fe06aca00cb9202de0092f0016c024779707e69f9d400d33117a007

data/AGENTS.md

@@ -4,35 +4,51 @@ 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
 
 ```sh
 bundle add railwatch
-bin/rails generate railwatch:install --prompt-token --kamal-secrets
+bin/rails generate railwatch:install                                 # embedded: dashboard at /railwatch
+bin/rails generate railwatch:install --prompt-token --kamal-secrets  # or: Railwatch Cloud
 ```
 
-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.
+With no flags the install is embedded (see [Embedded mode](docs/embedded.md)):
+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
@@ -73,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:
@@ -98,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 \
@@ -108,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

@@ -1,5 +1,152 @@
 # Changelog
 
+## Unreleased
+
+<!-- Pull requests add their entry here. The version number and the date are
+     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
+  railwatch:install` with no flags writes what `--local` used to: the
+  `railwatch` and `railwatch_telemetry` SQLite databases, `plugin
+  :railwatch` in `config/puma.rb`, and `c.transport = :local`, so two
+  commands give a working dashboard at `/railwatch` with no account and no
+  token. The cloud install is `--cloud`, and any option that only means
+  something there (`--prompt-token`, `--token-stdin`, `--url`,
+  `--kamal-secrets`) implies it, so existing cloud instructions keep
+  working. An exported `RAILWATCH_TOKEN` on its own does not pick the
+  cloud: a token in the shell is not a decision about where data goes.
+  `--local` is gone (it is the default); the gem's runtime default when no
+  initializer sets a transport is unchanged. The embedded next steps now
+  end with how to mirror to Railwatch Cloud (`c.export_enabled`).
+
+- The embedded dashboard is open in development when HTTP Basic has no
+  credentials, so the first run needs no password step. Every other
+  environment is unchanged: closed, 401, until credentials exist. That
+  case now also logs a boot warning outside development and test (it was
+  only in the doctor), since a 401 on a deployed dashboard otherwise looks
+  like a broken install. Configured credentials apply in development too.
+
+- Bound how long Puma waits for the embedded writer to stop. The plugin sent
+  the writer TERM and then called `Process.wait` on it, which has no timeout:
+  a writer that did not exit -- stuck in a SQLite write, on a full disk --
+  held Puma's shutdown open for as long as it stayed stuck. Measured against
+  a child that ignores TERM, the stop never returned (the harness gave up at
+  10s with the child still alive). Puma now waits `shutdown_timeout` (2s),
+  the same allowance it gives its own reporter, then KILLs the writer and
+  reaps it, so a wedged writer costs a bounded 2s and never leaves a zombie.
+  A writer killed mid-batch loses nothing -- the batch is retried by id
+  against the next writer -- which is why the bound is not the writer's own
+  worst-case drain (13s at the defaults): waiting for it would buy no data,
+  only exit time, and that time counts against the container's stop grace.
+  A writer that exits on TERM is let go the moment it does (measured
+  ~50ms), and a pid the cluster has already reaped is still treated as gone.
+
+- Make one HTTP attempt per delivery. `Transport::Http#deliver` retried a
+  raised error or a 5xx once on its own, inside a reporter that already owns
+  a retry ladder of eight attempts, so each rung cost two socket timeouts
+  and the effective attempt count was about sixteen. Against a receiver that
+  accepts connections and never answers, one delivery cost 6.0s; it now
+  costs 3.0s (one `read_timeout`), and one attempt, like `deliver_encoded`.
+  Response classification and `Retry-After` are unchanged: a 5xx or a raised
+  error still comes back retryable and the reporter still schedules it.
+
+- Correct `docs/configuration.md` and `docs/troubleshooting.md`, which told
+  users to raise `buffer_size` under pressure. At the defaults the byte
+  ceiling (`buffer_bytes`, 16 MiB) fills at roughly 5,000 records on a
+  realistic mix, so the 10,000-record count is never reached and raising it
+  changes nothing. The setting stays; the advice now points at `buffer_bytes`.
+
+- Say so when records are lost. `Railwatch.on_unrecoverable` fell back to
+  the debug log, so with no callback registered and `RAILWATCH_DEBUG` unset
+  a batch dropped after its retry ladder, one the receiver permanently
+  refused, or the records still unsent when `at_exit`'s bounded shutdown
+  ran out of time all vanished without a word. Since 0.3.7 that shutdown is
+  the only delivery a rake task or `rails runner` gets, so a cron job whose
+  exception never reached the platform looked exactly like one that had
+  nothing to report. Confirmed against a receiver that accepts and never
+  answers: the process left inside `shutdown_timeout` carrying three unsent
+  records and printed nothing.
+
+  A `Reporter::DeliveryError` -- raised only once the records are already
+  gone -- now prints one `[railwatch]` stderr line, and `warn_on_data_loss`
+  (`RAILWATCH_WARN_ON_DATA_LOSS`) defaults to **on**. Silence was the wrong
+  default: telemetry that disappears without a word looks exactly like
+  having nothing to report, which is the one failure an operator cannot
+  diagnose from the platform side, because the evidence is what went
+  missing. One line a deploy is the whole cost, and it only ever appears
+  when something was actually lost.
+
+  Both ways out are named in the line itself, so nobody has to find this
+  entry to stop it: a registered `on_unrecoverable` always wins, which is
+  how an app routes the loss somewhere better (`Rails.error.report`), and
+  `warn_on_data_loss = false` restores silence. Recovered internal errors (a
+  subscriber that raised, a flush that will be retried) stay debug-only
+  either way: the gem carried on and there is nothing for an operator to do.
+
+- Report a lost batch outside the flush lock too. The fix above moved the
+  callback out of `@mutex`, the inner lock -- but `Reporter#flush` holds
+  `@flush_mutex` around the whole of `deliver_buffer`, and the give-up path,
+  the permanent-rejection path and the rescue all report from inside it. A
+  callback that asks this same reporter to flush (`Railwatch.flush` is public
+  and documented) hit the same non-reentrant `Mutex` one level out: the same
+  `ThreadError: deadlock; recursive locking`, rescued and hidden by
+  `notify_unrecoverable`, so the callback ran halfway and reported nothing.
+  The locked path now collects what it needs to report and `flush` hands it
+  over once the lock is released. Found by CodeRabbit on this pull request.
+
+- Report a given-up batch after releasing the reporter lock, not under it.
+  `Reporter#retain` called `on_unrecoverable` inside `@mutex.synchronize`.
+  The documented callback is `Rails.error.report`, whose subscriber records
+  the error as an exception -- a write back into the same reporter, which
+  takes `@mutex` to arm its thread or request a flush. That was
+  `ThreadError: deadlock; recursive locking`, rescued and hidden by
+  `notify_unrecoverable`, so the callback died halfway and the loss it was
+  reporting was never seen. A callback that merely blocked held every
+  request thread's `write_now` and `shutdown` itself behind it for the
+  duration. `notify_unsent` and `delivery_rejected` already called out
+  unlocked; this was the one that did not.
+
+- Investigated and left alone: `Reporter#shutdown` after `thread.join`.
+  The bookkeeping that follows the join (`pending_delivery`, the
+  once-only notify latch) takes `@mutex` for microseconds and never does
+  I/O -- measured 0.2ms over `shutdown_timeout` against a transport wedged
+  forever. The only thing that can extend it is the operator's own
+  callback, which runs once and is theirs to bound, as any `at_exit`
+  handler is. Wrapping it in `Timeout` would trade a visible cost for a
+  killed thread.
+
+
 ## 0.5.1 (2026-09-21)
 
 Three small seams for a host that runs these models on its own routes and

data/README.md

@@ -6,31 +6,41 @@ outgoing HTTP, storage, views, and logs, and links them into one trace
 per execution, for about half a millisecond per request plus tens of
 microseconds per query, with zero writes to your database.
 
-Send that to Railwatch Cloud, or keep all of it inside the app:
-[embedded mode](docs/embedded.md) serves the same dashboard at
+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.
+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
 
 ```sh
-bundle add railwatch            # 1. add the public gem
-bin/rails generate railwatch:install --prompt-token  # 2. hidden token input plus app wiring
-bin/rails railwatch:doctor                    # 3. check every piece is wired up after restart
+bundle add railwatch                  # 1. add the public gem
+bin/rails generate railwatch:install  # 2. embedded: databases, Puma writer, dashboard at /railwatch
 ```
 
-Or keep everything inside your app, with the full dashboard at
-`/railwatch` and no token ([Embedded mode](docs/embedded.md)):
+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). 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.
+
+To send everything to Railwatch Cloud instead, pass `--cloud` or a token
+option:
 
 ```sh
 bundle add railwatch
-bin/rails generate railwatch:install --local
+bin/rails generate railwatch:install --prompt-token  # hidden token input plus app wiring
+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"
@@ -46,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.
@@ -73,11 +87,11 @@ expect { get "/widgets" }.not_to have_railwatch_n_plus_one
 
 ## Embedded mode
 
-`--local` 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
@@ -86,18 +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 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`. 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
@@ -105,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/controllers/railwatch/dashboard_controller.rb

@@ -47,6 +47,7 @@ module Railwatch
     def authenticate_by_http_basic
       config = Railwatch.config
       return unless config.http_basic_auth_enabled
+      return if config.http_basic_auth_waived?
 
       if config.http_basic_auth_configured?
         http_basic_authenticate_or_request_with(name: config.http_basic_auth_user, password: config.http_basic_auth_password,

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/application_record.rb

@@ -15,7 +15,7 @@ module Railwatch
       # No `railwatch` entry in this environment's database.yml, or an entry
       # whose adapter gem is not in the bundle yet (LoadError). A cloud-transport
       # app has none and still eager-loads this class in production, and so
-      # does the --local installer's own boot, before it has written the
+      # does the installer's own boot, before it has written the
       # entry -- so loading must not raise. Using it must, though: without
       # connects_to this class would inherit ActiveRecord::Base's PRIMARY
       # connection, and its tables are unprefixed, so a query would read and
@@ -25,7 +25,7 @@ module Railwatch
       def self.connection_pool
         raise Railwatch::DatabaseNotConfigured,
               "the `railwatch` database (issues, comments, saved views and deploys) is not configured for the " \
-              "#{Rails.env} environment; run `bin/rails generate railwatch:install --local` " \
+              "#{Rails.env} environment; run `bin/rails generate railwatch:install` " \
               "or add it to config/database.yml (docs/embedded.md)"
       end
     end

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/app/models/railwatch/telemetry_record.rb

@@ -18,7 +18,7 @@ module Railwatch
       # No `railwatch_telemetry` entry in this environment's database.yml, or an entry
       # whose adapter gem is not in the bundle yet (LoadError). A cloud-transport
       # app has none and still eager-loads this class in production, and so
-      # does the --local installer's own boot, before it has written the
+      # does the installer's own boot, before it has written the
       # entry -- so loading must not raise. Using it must, though: without
       # connects_to this class would inherit ActiveRecord::Base's PRIMARY
       # connection, and its tables are unprefixed, so a query would read and
@@ -28,7 +28,7 @@ module Railwatch
       def self.connection_pool
         raise Railwatch::DatabaseNotConfigured,
               "the `railwatch_telemetry` database (everything the app reports) is not configured for the " \
-              "#{Rails.env} environment; run `bin/rails generate railwatch:install --local` " \
+              "#{Rails.env} environment; run `bin/rails generate railwatch:install` " \
               "or add it to config/database.yml (docs/embedded.md)"
       end
     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