railwatch 0.1.0

data/docs/self-hosting.md

@@ -0,0 +1,60 @@
+# Self-hosting
+
+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.
+
+## Point the gem at your platform
+
+```ruby
+# config/initializers/railwatch.rb
+Railwatch.configure do |c|
+  c.ingest_url = "https://telemetry.example.com"   # RAILWATCH_INGEST_URL
+  c.token      = ENV["RAILWATCH_TOKEN"]
+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:
+
+```sh
+bin/rails generate railwatch:install --url=https://telemetry.example.com
+```
+
+## Getting a token
+
+On your install: sign up, create an application, then create an
+environment inside it (`production`, `staging` — one token each). The
+token is shown once, right after you create the environment; a lost one
+is rotated from the environment's settings, not recovered.
+
+```sh
+bin/rails railwatch:token    # prints the URL to create/copy a token
+```
+
+## Check the connection
+
+```sh
+bin/rails railwatch:status   # pings {ingest_url}/ingest/ping with your token
+bin/rails railwatch:doctor   # the full checklist: token, URL, reachability, wiring
+```
+
+`railwatch:status` aborts if the token is unset or the host is unreachable,
+so it works as a post-deploy smoke test.
+[`troubleshooting.md`](troubleshooting.md) covers each doctor line.
+
+## MCP
+
+Your install serves its own MCP endpoint at `<ingest host>/mcp` —
+`https://telemetry.example.com/mcp` for the example above. It authenticates
+with a per-user API token generated from Settings → Profile, the same
+token the public JSON API at `/api/v1` uses. See
+[`ai-and-mcp.md`](ai-and-mcp.md) for every client's configuration block.
+
+## Running the platform
+
+Railwatch Cloud's backend is not part of this gem repository. Licensed
+self-hosted customers receive separate platform deployment, backup, retention,
+quota, and restore documentation from Rebulk.

data/docs/source-maps.md

@@ -0,0 +1,60 @@
+# Production browser source maps
+
+Railwatch can resolve minified browser errors to their original source files,
+lines, function names and embedded code. Maps stay in the environment's
+private telemetry database; Railwatch never downloads a `sourceMappingURL`.
+
+Enable hidden source maps in Vite:
+
+```ts
+export default defineConfig({
+  // Keep your existing plugins and options.
+  build: { sourcemap: "hidden" },
+})
+```
+
+After building, upload the maps **before publishing the image or assets**:
+
+```sh
+RAILWATCH_DEPLOY="$RELEASE_SHA" bin/rails 'railwatch:sourcemaps[public,true]'
+```
+
+The task uses the application's `RAILWATCH_TOKEN` and `RAILWATCH_INGEST_URL`.
+Use the same deploy value the running application reports. The first argument
+is the public URL root: `public/vite/assets/index-abc.js.map` becomes
+`vite/assets/index-abc.js`, matching `/vite/assets/index-abc.js` in a browser
+stack. The optional second argument `true` deletes each map only after the
+server acknowledges its upload. Without it, files are retained. A failed
+upload fails the task and leaves that file on disk. Hidden maps still exist
+on disk, so the deletion step belongs before publishing public assets.
+
+The equivalent environment options are `RAILWATCH_SOURCEMAPS_DIR=public` and
+`RAILWATCH_SOURCEMAPS_DELETE=true`. The generated Kamal post-deploy hook also
+accepts `--sourcemaps` or `RAILWATCH_SOURCEMAPS=true`, using local artifacts on
+the deployer and `KAMAL_VERSION` as the deploy. That hook reports failures
+without failing the deployment. Build-time upload is preferable because it
+removes maps before assets become public.
+
+Uploads accept flat Source Map v3 files (Vite's output), up to 10 MiB each,
+500,000 mapping segments and 200,000 generated lines. Indexed `sections`
+maps and remote references are unsupported. Embedded `sourcesContent`
+provides snippets; it is optional. No local source files are opened by the
+server. Maps for the current deploy and releases referenced by retained
+requests, jobs, exceptions or sessions stay available. Maps for inactive
+releases expire once their last update is older than the environment's raw
+telemetry retention; replacing a map renews that window.
+
+New default browser issue fingerprints use the resolved original location
+when a map is already available. Custom fingerprints are preserved. Late
+uploads improve existing stack displays, Copy for AI, API issue details and
+MCP `get_issue`, while existing occurrences keep their original grouping.
+Missing maps or columns fall back to the raw stack. Upgrade the gem for
+new browser occurrences to include columns; older gem versions discarded
+them and cannot resolve minified locations accurately.
+
+For a custom release uploader, POST the raw `.map` bytes to
+`/ingest/sourcemaps` with `Content-Type: application/octet-stream`,
+`Authorization: Bearer lt_...`, `X-Railwatch-Deploy`, and
+`X-Railwatch-Filename` (the generated JavaScript URL path without a leading
+slash). A successful response is HTTP 201 with
+`{"ok":true,"filename":"vite/assets/index-abc.js","bytes":1234}`.

data/docs/testing.md

@@ -0,0 +1,175 @@
+# Testing with Railwatch
+
+Railwatch already watches every query, N+1, span, exception, and outgoing
+request your app makes. The same instrumentation works in your test suite,
+which means a spec can assert on them — and CI can fail a pull request that
+adds an N+1 or doubles a page's query count.
+
+## Set-up
+
+RSpec — add one line to `spec/rails_helper.rb` (the install generator adds it
+for you):
+
+```ruby
+require "rspec/rails"
+require "railwatch/rspec"
+```
+
+That requires `railwatch/spec_helper`, includes `Railwatch::SpecHelper` into every
+example group, and defines the matchers below.
+
+Minitest — the same thing in `test/test_helper.rb`:
+
+```ruby
+require "rails/test_help"
+require "railwatch/minitest"
+
+class ActiveSupport::TestCase
+  include Railwatch::Minitest
+end
+```
+
+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.
+
+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.
+
+## Matchers
+
+All of them are block matchers.
+
+### `have_railwatch_queries`
+
+```ruby
+expect { OrderSummary.new(order).to_h }.to have_railwatch_queries(at_most: 5)
+expect { user.reload }.to have_railwatch_queries(exactly: 1)
+expect { Report.generate }.to have_railwatch_queries(at_least: 1)
+```
+
+Exactly one of `at_most:`, `exactly:`, `at_least:` — passing two (or none)
+raises `ArgumentError`. On failure the message lists every statement, each
+truncated to 120 characters, so CI output says what to go and fix:
+
+```
+expected the block to run at most 1 database queries, but it ran 3:
+  1. SELECT COUNT(*) FROM "widgets"
+  2. SELECT "widgets".* FROM "widgets" WHERE "widgets"."id" = ?
+  3. SELECT "gadgets".* FROM "gadgets" WHERE "gadgets"."id" = ?
+```
+
+Cached queries don't count — they never become `query` records.
+
+### `have_railwatch_n_plus_one`
+
+```ruby
+expect { get "/widgets" }.not_to have_railwatch_n_plus_one
+```
+
+Matches when the block trips Railwatch's own N+1 detector: the same normalized
+query shape repeated `config.n_plus_one_threshold` times (default 5) inside one
+execution. The negated failure message names the shape, the repeat count, and
+the app-code line that issued it.
+
+### `record_railwatch_span`
+
+```ruby
+expect { Checkout.new(cart).total }.to record_railwatch_span("checkout.total")
+expect { Checkout.new(cart).total }.to record_railwatch_span(nil) # any span
+```
+
+### `record_railwatch_exception` / `record_railwatch_exceptions`
+
+```ruby
+expect { importer.run }.to record_railwatch_exception(ArgumentError)
+expect { importer.run }.not_to record_railwatch_exceptions
+```
+
+These see anything that reaches `Rails.error` — `Rails.error.handle`,
+`Rails.error.report`, `Railwatch.report`, and unhandled exceptions a request
+spec's middleware catches. A block that raises out of the matcher still
+raises; nothing is swallowed.
+
+### `have_railwatch_outgoing_requests`
+
+```ruby
+expect { SyncCustomers.run }.to have_railwatch_outgoing_requests(at_most: 1)
+```
+
+Same bounds as `have_railwatch_queries`. Failures list the method and URL of
+every request the block made.
+
+## Minitest assertions
+
+```ruby
+assert_railwatch_queries(at_most: 5) { OrderSummary.new(order).to_h }
+refute_railwatch_n_plus_one { get widgets_url }
+assert_railwatch_span("checkout.total") { Checkout.new(cart).total }
+```
+
+`assert_railwatch_queries` takes `exactly:`/`at_most:`/`at_least:` too, and
+produces the same statement listing on failure.
+
+## Where the matchers work
+
+Anywhere. A request spec's `get "/widgets"` opens and closes its own
+execution, so its whole tree — queries, N+1s, outgoing HTTP — is visible by
+the time the block returns:
+
+```ruby
+expect { get "/widgets" }.to have_railwatch_queries(at_most: 6)
+```
+
+A model or service spec has nothing executing, so the block is wrapped in an
+execution for the duration of the assertion and closed afterwards. No parent
+`command` record is written for it. A block running *inside* an execution you
+opened yourself has its records read straight off that execution's buffer.
+
+Under the hood every matcher calls `Railwatch::SpecHelper#railwatch_capture`,
+which is public — use it directly for anything the matchers don't cover:
+
+```ruby
+records = railwatch_capture { get "/widgets" }
+expect(records.select { |r| r[:t] == "cache_event" }.size).to eq(2)
+```
+
+`railwatch_records(type = nil)` is still there for assertions about the whole
+example rather than one block.
+
+## CI performance gate
+
+Put the budget for a hot path in a spec and let it fail the build when
+someone regresses it. The point is that the number is checked in, so raising
+it is a reviewed decision rather than an accident:
+
+```ruby
+# spec/performance/widgets_spec.rb
+RSpec.describe "performance budgets", type: :request do
+  before { create_list(:widget, 25) }
+
+  it "renders the widget index within its query budget" do
+    expect { get "/widgets" }.to have_railwatch_queries(at_most: 6)
+  end
+
+  it "renders the widget index without an N+1" do
+    expect { get "/widgets" }.not_to have_railwatch_n_plus_one
+  end
+
+  it "renders the widget index without calling out to anyone" do
+    expect { get "/widgets" }.to have_railwatch_outgoing_requests(exactly: 0)
+  end
+end
+```
+
+Two ways to run it: tag these examples and run them as their own CI step
+(`bundle exec rspec --tag performance`) so a budget failure is obvious in the
+job list, or leave them in the main suite so any pull request that adds a
+query fails immediately. Either way the failure message names the statements,
+so the fix is usually an `includes` one line away.
+
+Seed enough rows in `before` that an N+1 actually crosses
+`config.n_plus_one_threshold` — with three records, a five-query threshold
+never fires and the gate passes on code that would melt in production.

data/docs/troubleshooting.md

@@ -0,0 +1,319 @@
+# Troubleshooting
+
+Start with `bin/rails railwatch:doctor`. It checks every piece of the
+install in one pass and prints a `✓`/`✗` line per piece; the sections
+below are keyed to those lines.
+
+```sh
+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
+isn't wired, not that the install is broken.
+
+| Doctor line | What a `✗` means |
+|---|---|
+| `token` | `RAILWATCH_TOKEN` is unset or empty. Fatal: nothing is recorded at all. |
+| `ingest url` | `ingest_url` isn't a parseable HTTP(S) URL. |
+| `ingest reachable` | `GET {ingest_url}/ingest/ping` didn't return success. Fatal. |
+| `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. |
+| `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. |
+| `profiler backend` | Neither `vernier` nor `stackprof` is installed, so `Railwatch::Profiler.available?` is false and the profiling settings are inert. |
+| `test matchers` | Neither `spec/rails_helper.rb` requires `railwatch/rspec` nor `test/test_helper.rb` requires `railwatch/minitest`. |
+
+## No records at all
+
+**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
+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, 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
+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
+[`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.
+
+**Sample rates are at zero.** `c.sample = { requests: 0.0 }` — or the
+per-route `railwatch_never_sample` macro on a controller — means no
+request records. The `sample rates` doctor line prints the effective
+values. Note that an unhandled exception still ships from a sampled-out
+execution, so "exceptions arrive but nothing else does" is the
+signature of a low sample rate rather than a broken install.
+
+**The record type is ignored.** `c.ignore` drops a type before it is
+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, so 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?`.
+
+Still nothing? Set `RAILWATCH_DEBUG=1` and restart. Internal diagnostics go
+to stderr prefixed `[railwatch]` (never to `Rails.logger`, so they can't
+become `log` records about themselves). `Railwatch.on_unrecoverable { |e|
+... }` gets the same failures as a callback.
+
+## Doubled scheduled_task records
+
+**Symptom.** Every recurring task shows twice on the Scheduled tasks
+page, at the same minute, usually with different `drift`.
+
+**Cause.** Two Solid Queue supervisors are running against the same
+queue database — a stale `bin/jobs` left over from a previous `bin/dev`,
+`SOLID_QUEUE_IN_PUMA=true` while a dedicated job role is also booted, or
+two containers of the job role. Each supervisor has its own recurring
+scheduler and its own workers, so the job really is performed twice.
+Railwatch doesn't dedupe: it records one `scheduled_task` per
+`perform.active_job`, in whichever process performed it. The doubled
+rows are a true report of a doubled run.
+
+**Fix.** Run one supervisor. `SolidQueue::Process.where(kind:
+"Supervisor")` tells you how many think they're alive; `bin/kamal app
+logs -r job` tells you which containers are booting one. The same
+duplication also doubles the work itself, so this is worth fixing
+regardless of what the dashboard says.
+
+## Outgoing requests missing in specs
+
+**Symptom.** `have_railwatch_outgoing_requests` never sees anything, and no
+`outgoing_request` records appear from the test suite. Production is
+fine.
+
+**Cause.** WebMock replaces `::Net::HTTP` with a subclass whose
+`#request` short-circuits before calling `super`, so Railwatch's prepend on
+the real class never runs.
+
+**Fix.** Re-prepend the patch onto the replacement, once, before the
+suite. This is exactly what the gem's own suite does
+(`spec/spec_helper.rb`), and app suites using WebMock should do the
+same:
+
+```ruby
+# WebMock replaces ::Net::HTTP with a subclass whose #request short-circuits
+# before calling super, so Railwatch's prepend on the real class never runs
+# under WebMock. Re-prepend on the replacement so outgoing requests are still
+# observed in this suite. Apps using WebMock in their own tests would do the same.
+RSpec.configure do |config|
+  config.before(:suite) { Net::HTTP.prepend(Railwatch::Patches::NetHttp) }
+end
+```
+
+## Puma cluster mode: threads after fork
+
+**Symptom.** You expect to have to re-arm something in
+`on_worker_boot`, or the Processes page shows fewer processes than you
+have workers.
+
+**What actually happens.** Ruby routes `fork`, `Process.fork`, and
+`Kernel#fork` through `Process._fork`, and Railwatch registers one callback
+with Rails' own `ActiveSupport::ForkTracker` (the same hook Active Record
+uses to reset its connection pools). Before the child returns from
+`fork`, it replaces the inherited reporter buffer, drop accounting,
+transport policy state, mutexes, condition variables, dead threads, and the
+profiler's process-global state (a parent's in-flight profile would
+otherwise leave the child permanently unable to profile).
+The parent's half-finished session map is discarded too. The child then
+emits its own `process` record and starts fresh health/session threads for
+its role. Parent records remain owned by and delivered from the parent;
+they can never be replayed by every child. **No `on_worker_boot`
+configuration is needed**, in Puma cluster mode or in Solid Queue's
+forked workers.
+
+The synchronization objects are replaced without locking them. That is
+deliberate: if another parent thread owned a mutex at the instant of
+`fork`, Ruby preserves the locked mutex in the child but not the thread
+that could unlock it.
+
+**When a process legitimately reports nothing.** `Health.start!` returns
+early unless the process's role is `web` or `worker`, and
+`Sessions.start!` only runs for `web`. Role detection is
+`Railwatch::Subscribers::ProcessInfo.role`, in this order: `worker` when
+Solid Queue is loaded and `$PROGRAM_NAME` includes `"jobs"` (or the
+command starts with `solid_queue:`), then `console`, then `command` when
+`$PROGRAM_NAME` ends in `rake`, then `web` when Puma is defined, else
+`process`. The worker check comes first deliberately — Puma is loaded in
+a job container too. A console or a rake task ships no health records by
+design, and both modules also return early in the `test` env.
+
+## Memory growth with tail sampling on
+
+**Symptom.** RSS climbs after enabling `c.tail_sample_slow_ms`, or the
+`peak_memory` on parent records rises across the board.
+
+**Cause.** That is the trade-off, not a leak. With head sampling only, a
+sampled-out execution builds and buffers nothing. With tail sampling on,
+*every* execution buffers its child records — queries, cache events,
+logs, view renders — for its whole lifetime, because the keep-or-discard
+decision can't be made until it ends.
+
+**What to check.**
+
+- Per execution, the buffer is capped at `Execution::MAX_RECORDS`
+  (10,000). Past that, records are dropped and counted, and the count is
+  added to the reporter's drop counter so the loss is visible on the
+  platform rather than silent.
+- `c.buffer_size` (default 10,000, the same as `MAX_RECORDS`) caps the
+  process-wide queue between the app and the reporter thread.
+  Oldest-dropped-first, also counted. Do not set it below `MAX_RECORDS`:
+  an execution's tree is written to the queue in one go when it ends, so
+  a tree larger than the queue loses its own first records -- typically
+  the outgoing requests a long job made before it started writing.
+  Keeping far more executions than before means far more records
+  arriving at this queue; raise it, or lower what you keep.
+- `c.profile_slow_ms` compounds it: it profiles every tail-buffering
+  execution from its first line and throws away the fast ones, so the
+  profiler's stack table is held alongside the record buffer.
+- `c.failure_context` buffers sampled-out executions too, but a ring of
+  that many records each rather than all of them. If RSS climbed after
+  setting it, lower the count: it is a per-execution bound, so the
+  process-wide cost is that many records times the executions running
+  concurrently.
+
+**Fix.** Lower `tail_sample_slow_ms` so fewer executions qualify to be
+buffered, drop the highest-volume child types for tail-kept traffic with
+`c.ignore`, or use `Railwatch.keep!` on the specific paths you care about
+instead of a global threshold.
+
+## Profiles never appear
+
+**Symptom.** `c.profile_sample` is set but no `profile` records ship and
+no request is marked `profiled`.
+
+**Cause.** No profiler backend is installed. Railwatch doesn't vendor one:
+`Railwatch::Profiler.available?` is false unless `vernier` or `stackprof`
+loads, and every profiling setting is inert while it is. The doctor's
+`profiler backend` line reports this.
+
+**Fix.** Add `gem "vernier"` (Ruby ≥ 3.2, preferred) or
+`gem "stackprof"`. Two other reasons a profile can be absent even with a
+backend: `c.profiler` pinned to a name that doesn't load (profiling
+stays off rather than falling back), and the `test` env, where profiling
+is skipped unless `profile_sample` is explicitly non-zero. Both backends
+are process-global, so an execution that starts while another one is
+being profiled is simply not profiled — expected, not a bug.
+
+## No deploy marker on the charts
+
+**Symptom.** Charts have no vertical deploy lines; the Releases page
+groups everything under one blank release.
+
+**Cause.** `config.deploy` is unset. The doctor's `deploy` line says so,
+and when it is set, names the environment variable, `REVISION`, Git checkout,
+or initializer it came from.
+
+**Fix.** Set one of them; they are read in this order:
+
+1. `RAILWATCH_DEPLOY` — the explicit override on any platform.
+2. `KAMAL_VERSION`.
+3. `GIT_REV`, `GIT_SHA`, `SOURCE_VERSION`, `HEROKU_SLUG_COMMIT`,
+   `RENDER_GIT_COMMIT`, the tag from `FLY_IMAGE_REF`,
+   `VERCEL_GIT_COMMIT_SHA`, `CI_COMMIT_SHA`, or `GITHUB_SHA`.
+4. A Capistrano `REVISION` file.
+5. `.git/HEAD`, resolved through a loose ref or `packed-refs` without a Git
+   subprocess.
+
+Full 40-character SHAs are shortened to 12 characters. Or assign `deploy` in
+the initializer. Set `detect_deploy`/`RAILWATCH_DETECT_DEPLOY` to false to ignore
+steps 3–5. The value is stamped on every record, so a change only affects
+records shipped after the restart. Note that
+`config.deploy` and the deploy *marker* are two different things: the
+marker (with its commit list) comes from `railwatch:deploy` or the Kamal
+hook below.
+
+## The Kamal hook doesn't fire
+
+**Symptom.** Deploys happen; the Deploys page doesn't grow.
+
+**Cause and fix**, in the order the hook itself checks:
+
+- **`RAILWATCH_TOKEN` isn't exported to the hook.** The first 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
+  *app* isn't necessarily in the deployer's environment. Export it there
+  (or source the same secret store your CI uses).
+- **`curl` or `ruby` isn't on the deployer, or `RAILWATCH_INGEST_URL`
+  isn't set.** Then the hook falls back to
+  `bin/kamal app exec --primary --reuse "bin/rails railwatch:deploy[$KAMAL_VERSION]"`,
+  which records the same deploy **minus the commit list** — a container
+  has the code but not the git history. If your deploys show up without
+  commits, this is the path you're on.
+- **The hook isn't there.** The install generator only writes it when
+  `config/deploy.yml` already exists. Re-run
+  `bin/rails generate railwatch:install` after adopting Kamal.
+
+The hook never fails a deploy: every network call ends in `|| true`, and
+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.
+
+**Cause.** Full-text search uses SQLite's FTS5 (`logs_fts`). The
+platform checks for both — a SQLite adapter *and* the `logs_fts` table —
+and when either is absent falls back to `message LIKE '%...%'`. That
+fallback is a plain substring match: no phrase or negation syntax, and no
+snippet highlighting.
+
+**Fix.** Nothing on the gem side; this is a property of the platform's
+telemetry store. SQLite is the default and first-class target for
+per-environment telemetry precisely because of features like this. A
+telemetry database created before the FTS index existed also falls back. A
+self-hosted platform operator should rebuild the documented search index.
+
+## The Tenants page is empty
+
+**Symptom.** Every other page has data; Tenants shows nothing.
+
+**Cause.** `tenant` is a column on every telemetry row, filled from
+`Railwatch::Context.current_tenant`, and a tenant only exists as a GROUP BY
+over those rows. If nothing ever sets it, every row has a null tenant and
+there is nothing to group.
+
+**Fix.** Apps on `activerecord-tenanted` get it free — Railwatch reads
+`ActiveRecord::Base.current_tenant` / `TenantRecord.current_tenant` with
+no configuration. Everyone else sets it explicitly, as early in the
+request as the tenant is known:
+
+```ruby
+Railwatch.context(tenant: org.slug)
+```
+
+Set it in the same `before_action` that resolves the tenant, so every
+record in the execution carries it. Context set after a record is built
+does not retroactively apply to it.
+
+## See also
+
+- [`configuration.md`](configuration.md) — every option and its default.
+- [`records.md`](records.md) — what each record type contains.
+- [`faq.md`](faq.md) — overhead, retention, PII, and what happens when
+  the platform is unreachable.