railwatch 1.3.0 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: af26db042e24211ffde4ad4e82dd90a7bc27e37c0bc9f74674947a30109b0036
-  data.tar.gz: 8c8033a1fa3f4b97142dd6b3593cf4bcc7fa16d2bea97fed6d580ee1584133de
+  metadata.gz: fd59ae7a65fbd673b2069d096802144c04277a08379fa42285d32677ad5502c6
+  data.tar.gz: 49ff48d1ec8340609c23c12a117ae1e381ac938f7fbdfb6aa914b7e33505a25c
 SHA512:
-  metadata.gz: 1ab758eed04fbcc9088989d5c411c88e0e80d8c3fbc08195c2908f04fcf38a21ad6b9ed8ec3ab8363081fcad59886f1abff8efb93bd6abfaeb156bada0bb66dc
-  data.tar.gz: 81e0e6e114d46a70619e21ae97816f451b83ccee7ee3f8e8aad8f2ccce8bd487beb31bfdea4cbbdf467357da7e7c4ae1b32dad69eae317e55083755897f3aa23
+  metadata.gz: 9c45c3639f2787b16b9104afed286ff712bfb63028e13fd83eda44323544ddb9a156c60566287d5465d6daaeffb46b4a8379addb8a51ebf90ab178f9c17a41d4
+  data.tar.gz: 31fe3a1492400bf823ef7dbd04ee22a45edda63349168032b93a3f8e429525cf9cb205b15b96eb6238819a6386916457a75ed3f4de52164227c39e39c8a1a576

data/AGENTS.md

@@ -129,6 +129,13 @@ claude mcp add railwatch --transport http https://railwatch.rebulk.com/mcp \
   --header "Authorization: Bearer rwp_your_token_here"
 ```
 
+In development with railwatch-server no token is needed from the same
+machine: `claude mcp add --transport http railwatch http://localhost:3000/railwatch/mcp`,
+or `bin/rails generate railwatch:agents` to write `.mcp.json`, a marked
+block in `AGENTS.md`/`CLAUDE.md` and a Claude Code skill. Development
+responses carry `Server-Timing` and `X-Railwatch-Execution-Id` for
+`get_execution`.
+
 `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` (stack frames,

data/CHANGELOG.md

@@ -6,6 +6,60 @@
      filled in by the release commit, which is also the only commit that
      touches lib/railwatch/version.rb and Gemfile.lock. See CONTRIBUTING.md. -->
 
+## 1.5.0 (2026-10-28)
+
+- The browser session is one per browser, shared by every tab, as in GA4
+  and Amplitude: kept in `localStorage`, it ends after 30 minutes with no
+  activity in any tab or 24 hours after it started. Each tab also has its
+  own id. Every visit record carries `session_id` and `tab_id`, and every
+  request record carries the `session_id` from the `X-Railwatch-Session`
+  header or `railwatch_session` cookie and the `tab_id` from
+  `X-Railwatch-Tab`, which the client now sends on same-origin Inertia
+  visits. A browser error's `context.browser` carries the `session` and
+  `tab` it was thrown in, stamped when it fired, and both are dropped
+  rather than cut when they are not shaped like an id. A browser's first
+  page load, which arrives before the client has set its cookie, is handed
+  one by the request middleware (successful HTML `GET`s only, never a
+  publicly cacheable one, and only when the browser client is installed:
+  `browser_client`), so that page is in the session's journey and no
+  longer opens a second `user:<id>` session in release health. A closing
+  tab no longer marks the session `ended`: the browser's other tabs may
+  still be in it. Apps that copied the client
+  (`app/frontend/lib/railwatch.ts`) need the same change in their copy:
+  `bin/rails generate railwatch:install --force --no-doctor` updates it.
+- `railwatch:install`, `railwatch:doctor` and the `browser_client`
+  detection find the app's frontend sources in ViteRuby's `sourceCodeDir`,
+  else in `app/frontend` or `app/javascript`. They only looked in
+  `app/frontend` before, so an `app/javascript` app got no client and no
+  entrypoint wiring.
+
+## 1.4.0 (2026-10-26)
+
+- In development each recorded request's response carries
+  `Server-Timing` (`total`, `db` with the query count, `view`, `other`) and
+  `X-Railwatch-Execution-Id`, so `curl -i`, the browser's network panel or a
+  coding agent sees what the request cost and which execution to open.
+  `timing_headers` / `RAILWATCH_TIMING_HEADERS` turns it on or off
+  elsewhere; about 4 µs per request when on.
+- `bin/rails generate railwatch:agents` points coding agents at the
+  development Railwatch: `.mcp.json` with the local MCP server, a marked
+  block in `AGENTS.md` and/or `CLAUDE.md` describing the dev loop, and a
+  Claude Code skill. Re-running it changes only its own block and entry.
+- The beacon refuses a body over 256 KiB before Rails parses it.
+  `limit_payload` ran as a before_action, after ActionController had
+  already parsed the params, and a chunked body was read whole to find its
+  length, so an unauthenticated client could make a worker buffer an
+  unbounded body. A middleware in the engine's stack now refuses an
+  oversized Content-Length unread and reads at most one byte past the
+  limit of a chunked body.
+- A plain-HTTP ingest URL that is not allowed is a permanent failure. The
+  result carried no status, which read as retryable, so the reporter kept
+  the batch and walked its whole backoff ladder for a setting that cannot
+  change between attempts.
+- The Kamal post-deploy hook skips an ingest URL that is not https,
+  loopback, or allowed plain HTTP. An upper-case scheme or a bare host fell
+  through the `case` to curl, which sent the token over plain HTTP.
+
 ## 1.3.0 (2026-10-25)
 
 - The initial-load visit splits its TTFB into `redirect_ms`,

data/app/controllers/railwatch/beacon_controller.rb

@@ -13,7 +13,7 @@ module Railwatch
     # Browsers stop following a redirect chain at 20 (Fetch's limit).
     MAX_REDIRECTS = 20
 
-    MAX_REQUEST_BYTES = 256 * 1024
+    MAX_REQUEST_BYTES = Middleware::BeaconLimit::MAX_BYTES
     MAX_VISITS = 50
     MAX_ERRORS = 50
     MAX_ERROR_MESSAGE = 1024
@@ -26,7 +26,9 @@ module Railwatch
 
     RATE_LIMIT_WINDOW = 60 # seconds
 
-    before_action :limit_payload, :verify_origin, :throttle, if: -> { Railwatch.config.beacon_enabled }
+    # The body size is enforced before this controller parses anything, by
+    # Middleware::BeaconLimit in the engine's stack.
+    before_action :verify_origin, :throttle, if: -> { Railwatch.config.beacon_enabled }
 
     def create
       return head :no_content unless Railwatch.config.beacon_enabled
@@ -53,6 +55,7 @@ module Railwatch
           inp: metric_ms(v["inp"]),
           ttfb: metric_ms(v["ttfb"]),
           **ttfb_phases(v),
+          **browser_fields(v),
           user: user_id,
           tenant: tenant,
           user_agent: safe_string(request.user_agent, 256))
@@ -143,10 +146,6 @@ module Railwatch
       head :too_many_requests
     end
 
-    def limit_payload
-      head :content_too_large if request.raw_post.bytesize > MAX_REQUEST_BYTES
-    end
-
     # The browser half of release health: one `session` record per beacon
     # flush, never more, whatever the flush carried. The first one the client
     # sends has no duration yet and opens the session; every later flush
@@ -195,7 +194,7 @@ module Railwatch
         next unless error
         name = safe_string(error["name"], 255)
         next if name.empty?
-        record_error(error, name, origin, session_id, user_id, tenant)
+        record_error(error, name, origin, Sessions.browser_id(error["session_id"]) || session_id, user_id, tenant)
       end
     end
 
@@ -208,12 +207,19 @@ module Railwatch
       Context.current_tenant || (hint.is_a?(String) ? safe_string(hint, 255).presence : nil)
     end
 
-    # The tab's session id, so a browser error can be lined up with the
-    # session it crashed. Shaped like every other read off this payload:
-    # anything but a hash carrying an id yields no id at all.
+    # The flush's session id, for an error that does not name its own (a
+    # client copied before errors carried one). Anything but a hash carrying
+    # an id shaped like one the client mints yields no id at all.
     def session_id_from(session)
       session = object(session)
-      session ? safe_string(session["id"], 64) : ""
+      Sessions.browser_id(session["id"]) if session
+    end
+
+    # The session and tab each visit says it happened in, which can differ
+    # within one beacon: visits queued before the session timed out ship
+    # with the next session's beat. Omitted unless shaped like an id.
+    def browser_fields(visit)
+      { session_id: Sessions.browser_id(visit["session_id"]), tab_id: Sessions.browser_id(visit["tab_id"]) }.compact
     end
 
     def record_error(error, name, origin, session_id, user_id, tenant)
@@ -237,7 +243,8 @@ module Railwatch
           url: safe_string(error["url"], 2048).presence,
           component: safe_string(error["component"], 255).presence,
           visit: safe_string(error["visit"], 2048).presence,
-          session: session_id.presence,
+          session: session_id,
+          tab: Sessions.browser_id(error["tab_id"]),
           user_agent: safe_string(request.user_agent, 256).presence,
           breadcrumbs: breadcrumbs(error["breadcrumbs"]).presence
         }.compact)),

data/docs/ai-and-mcp.md

@@ -16,7 +16,9 @@ The endpoint is `<your ingest host>/mcp`. For the hosted platform that's
 server runs under the app's dashboard path, so the endpoint is the app's own
 host plus `/railwatch/mcp`; see the
 [railwatch-server README](https://github.com/Rebulk/railwatch-server#readme).
-For Railwatch Cloud and a self-hosted server the gem knows which one you're on:
+In development that endpoint needs no token from the same machine (see
+[In development](#in-development) below). For Railwatch Cloud and a
+self-hosted server the gem knows which one you're on:
 
 ```sh
 bin/rails railwatch:mcp
@@ -24,6 +26,28 @@ bin/rails railwatch:mcp
 
 prints every block below with your platform's host already filled in.
 
+### In development
+
+With `railwatch-server`, the app's own `bin/dev` serves MCP at
+`http://localhost:3000/railwatch/mcp`, and the proxy signs agent requests
+for you, so no token is needed:
+
+```sh
+bin/rails generate railwatch:agents   # .mcp.json, AGENTS.md/CLAUDE.md block, Claude Code skill
+# or by hand:
+claude mcp add --transport http railwatch http://localhost:3000/railwatch/mcp
+```
+
+That holds only in development, for a request from the same machine to a
+`localhost`/`127.0.0.1`/`::1` host name, so anyone who can reach the dev
+server's port from this machine can read and comment on its development
+data, as they can already open its dashboard. Other environments need a
+token unless the app sets `Railwatch::Server.config.agent_access = true`.
+Each recorded development response also carries `Server-Timing` and
+`X-Railwatch-Execution-Id` (`timing_headers` in
+[`configuration.md`](configuration.md)), so an agent can `curl -i` a page and
+pass the id to `get_execution`.
+
 ## 1. Get a token
 
 MCP tokens are **per person**, not per application: sign in to the platform,
@@ -146,19 +170,24 @@ they're configured.
 
 Every tool returns JSON as the text body of a single content block. **All
 durations are milliseconds.** Every `window` argument takes `1h`, `6h`,
-`24h`, `7d`, or `30d`, and defaults to `24h`.
+`24h`, `7d`, or `30d`, and defaults to `24h`. `application_slug` and
+`environment` may be left out when the token sees one application, or the
+application has one environment. A result over 60 KB comes back as
+`{"truncated": {…, "hint"}, "result": …}`, still valid JSON, with a hint on how
+to narrow the call. Rows carry a dashboard `url` for the human.
 
 | Tool | Arguments | 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` 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. |
+| `list_issues` | `application_slug?`, `environment?`, `status?` (`open`/`resolved`/`ignored`, default `open`), `sort?` (`impact`), `limit?` | issues with key, title, kind, status, priority, occurrence and affected-user counts, culprit, first/last seen and the dashboard `url`. Newest first by default; `sort: impact` ranks by occurrences discounted by days since last seen. |
+| `get_issue` | `key` or `issue_id`, `frames?` (`all`) | one issue and its dashboard `url`. For an exception, the sample occurrence with stored stack frames (runs of framework and gem frames collapsed to a count unless `frames: "all"`), cause, locals, parsed context, browser breadcrumbs, and the execution it happened inside; the latest occurrence is shown only when it differs from the sample. 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`. |
+| `list_slow_routes` | `application_slug?`, `environment?`, `window?`, `sort?` (`total`/`avg`/`p95`) | the 20 routes that cost the most request time (count × average) by default, each with `group_hash`, count, errors, `total_ms`, `avg_ms`, `p95_ms` and `url`. `sort: p95` ranks by per-request latency. |
 | `get_route` | `application_slug`, `environment`, `route` or `group_hash`, `window?` | one route's count/errors, p50/p95/p99/max, its slowest individual requests, the slowest queries those requests ran, and each N+1 with a concrete Active Record fix. |
 | `search_requests` | `application_slug`, `environment`, `q?`, `window?`, `limit?` | individual requests. `q` is the dashboard's filter grammar: `method:GET`, `route:/checkout`, `status:500` or `status:5xx`, `deploy:…`, `tenant:…`, `user:…`, `min_ms:250`; bare words match the route name. |
-| `get_execution` | `application_slug`, `environment`, `execution_id` | one execution and its full child timeline — every query, cache read, log line, outgoing request, view render, and exception, each offset in ms from the start. |
+| `get_execution` | `application_slug?`, `environment?`, `execution_id`, `timeline_offset?`, `timeline_limit?`, `timeline_type?` | why one execution took as long as it did. `summary` first: time split by sql, transactions, view, external, cache and untracked; the repeated queries and N+1s with their `source` (`file:line`) and an Active Record fix; the slowest records; notes on what to look at. Then one page of the timeline (25 rows by default, `timeline_offset` for more). |
+| `last_execution` | `application_slug?`, `environment?`, `path?`, `kind?` (`request`/`job`), `timeline_offset?`, `timeline_limit?`, `timeline_type?` | the newest request or job in `get_execution`'s shape: the dev loop. `path` matches the request path, route pattern or execution name. With no executions yet, it says why records may be missing. |
 | `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`. |
@@ -224,6 +253,15 @@ working *in a Rails app that uses Railwatch*:
 
 Copy either into your own app's repo to give its agent the same context.
 
+For the development loop, `bin/rails generate railwatch:agents` writes into
+the app: `.mcp.json` with the local MCP server (Claude Code's
+[project scope](https://code.claude.com/docs/en/mcp)), a block between
+`<!-- BEGIN railwatch ... -->` and `<!-- END railwatch -->` in `AGENTS.md`
+and/or `CLAUDE.md` (whichever exist; `AGENTS.md` when neither does), and a
+[Claude Code skill](https://code.claude.com/docs/en/skills) at
+`.claude/skills/railwatch/SKILL.md` (`--no-skill` skips it). Re-running it
+replaces only its own block and entry; `--url` points it at another port.
+
 ## See also
 
 - [`getting-started.md`](getting-started.md) — install, the token,

data/docs/configuration.md

@@ -20,6 +20,7 @@ values set in the initializer always win over the env var.
 | `server` | `RAILWATCH_SERVER` | `KAMAL_HOST`, else `Socket.gethostname` | Host stamped on every record. Under Kamal the container hostname carries a per-deploy container id, so the Kamal host wins; it is what the post-deploy hook registers as an expected server, which is what silent-host detection compares against. |
 | `environment` | — | resolved lazily from `Rails.env` | Set `c.environment = "staging"` to report under a name other than the actual Rails env. |
 | `ignored_request_paths` | `RAILWATCH_IGNORED_REQUEST_PATHS` (comma-separated) | `/up,/railwatch/beacon` | Exact request paths that bypass Railwatch's request execution entirely. In Ruby configuration, `Regexp` entries are also supported. Setting the env var replaces the defaults; append with `c.ignored_request_paths += ["/healthz"]` to keep them. |
+| `timing_headers` | `RAILWATCH_TIMING_HEADERS` | on in development, off elsewhere | Adds `Server-Timing` (`total`, `db` with the query count in `desc`, `view`, `other`) and `X-Railwatch-Execution-Id` to every recorded request's response, so `curl -i`, the browser's network panel, or a coding agent sees the cost and the execution to pass to `get_execution`. The id is left out when the request was sampled out. An existing `Server-Timing` (Rails' `config.server_timing`) is appended to. Off outside development by default because it tells every visitor how the app spends its time. Costs about 4 µs per request when on. |
 | `beacon_allowed_origins` | `RAILWATCH_BEACON_ALLOWED_ORIGINS` | `[]` | Extra origins allowed to post to the beacon beyond the app's own, comma-separated: a full origin (`https://app.example.com`) or a bare host. Like Sentry's allowed domains this bounds abuse rather than authenticating, since an endpoint a browser posts to cannot hold a secret. |
 | `beacon_global_rate_limit` | `RAILWATCH_BEACON_GLOBAL_RATE_LIMIT` | `6000` | Beacons accepted per minute across every client, so a rotating address cannot multiply past the per-client limit. 0 disables it. |
 | `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. |
@@ -522,15 +523,21 @@ crash-free session and crash-free user rates are computed from. The
 | `track_sessions` | `RAILWATCH_TRACK_SESSIONS` | `true` | Master switch for both session sources. Off means the request middleware does nothing extra and no flusher thread is started. |
 | `session_flush_interval` | `RAILWATCH_SESSION_FLUSH_INTERVAL` | `60.0` | Seconds between server-session flushes. One background thread per web process, re-armed after `fork` exactly like the health sampler, and flushed once more on shutdown. |
 | `session_timeout` | `RAILWATCH_SESSION_TIMEOUT` | `1800.0` | Seconds a server session may sit idle before it ships with `ended` and is forgotten. |
+| `browser_client` | `RAILWATCH_BROWSER_CLIENT` | whether `lib/railwatch.ts` exists in the app's frontend source directory (ViteRuby's `sourceCodeDir`, else `app/frontend` or `app/javascript`) | Whether the app's pages run the browser client. When they do, a browser's first page load gets its session id from the server (below). Set it when the client lives somewhere else, or `false` to never set the cookie. |
 
 There are two sources, and they meet on the same id:
 
 - **The browser client** is `app/frontend/lib/railwatch.ts`, installed by
-  `railwatch:install`. It mints one id per tab in `sessionStorage` and
-  mirrors it into a `railwatch_session` cookie. It rides along on the
-  beacon flushes the client already sends for visits, so this costs no
-  extra requests. This is the primary source for a web app, and it is
-  what makes session duration mean "how long the tab was open".
+  `railwatch:install`. It keeps one id per browser in `localStorage`,
+  shared by every tab and replaced after 30 minutes with no activity in
+  any tab or 24 hours after it started, and mirrors it into a
+  `railwatch_session` cookie. It also sends the id, with the tab's own
+  id, as `X-Railwatch-Session` and `X-Railwatch-Tab` on every Inertia
+  visit to the page's own origin. It rides along on the beacon flushes
+  the client already sends for visits, so this costs no extra requests.
+  This is the primary source for a web app, and it is what makes session
+  duration mean "how long the user was active". The client's 30 minutes
+  is fixed; it matches this setting's default.
 - **The request middleware** aggregates, in memory, every request that
   either resolves a user or carries that cookie or an
   `X-Railwatch-Session` header. It is the only source for an API-only
@@ -540,6 +547,25 @@ There are two sources, and they meet on the same id:
 When a browser session's requests carry the cookie both sources produce
 records under the same id and the platform dedupes them.
 
+A browser's first page load arrives before the client has run, so it
+carries no cookie. With `browser_client` on, the request middleware gives
+it one: a successful `GET` whose response is an HTML document, that is not
+an Inertia visit and carries no `X-Railwatch-Session` or cookie, gets
+`Set-Cookie: railwatch_session=<new id>; path=/; max-age=1800;
+samesite=lax` (plus `secure` over HTTPS, including behind a proxy that
+sets `X-Forwarded-Proto`). That request's record carries the id, and so does its
+server session when it resolved a user (an anonymous one opened no server
+session before and still opens none; its browser opens the session with
+the client's first beat).
+The client adopts it when the browser has no live session of its own, so
+that first page is the first entry of the session's journey and the
+session is not counted twice (once under the id, once as `user:<id>`). It
+is never set on a response whose `Cache-Control` says `public` or
+`s-maxage`, since a shared cache would hand one visitor's cookie to every
+visitor; on such a page the session starts with the client, as before.
+Requests with neither cookie nor header, from an API client or an app
+without the browser client, still key on `user:<id>`.
+
 ## Vendor noise defaults
 
 Framework/vendor activity excluded by default so a fresh install isn't
@@ -718,7 +744,9 @@ credential, so it is throttled per client IP by `beacon_rate_limit`,
 default 120 a minute, `0` to disable. A client past the limit gets a 429
 with `Retry-After` and nothing from that POST is recorded. Client setup:
 call `startRailwatch()` from your Inertia entrypoint. It is generated at
-`app/frontend/lib/railwatch.ts`.
+`lib/railwatch.ts` in the app's frontend source directory, usually
+`app/frontend/lib/railwatch.ts` (see Getting started for how the directory
+is chosen and how to update the copy).
 
 `startRailwatch` takes three optional settings, none of which has a
 server-side equivalent. They are decisions about the browser the code is

data/docs/getting-started.md

@@ -57,9 +57,25 @@ bin/rails generate railwatch:install \
   beacon endpoint the browser client posts to (`POST /railwatch/beacon`).
 - `.kamal/hooks/post-deploy` — only if `config/deploy.yml` already
   exists.
-- `app/frontend/lib/railwatch.ts` plus the `startRailwatch()` call in your
-  Inertia entrypoint — only if `app/frontend/` exists. If it can't find
-  an entrypoint it prints the two lines to add.
+- `lib/railwatch.ts` in the app's frontend source directory, plus the
+  `startRailwatch()` call in its Inertia entrypoint
+  (`entrypoints/inertia.tsx`, `.ts` or `.jsx`). The directory is ViteRuby's
+  `sourceCodeDir` when the app uses vite_ruby, else the first of
+  `app/frontend` and `app/javascript` that exists; with neither, nothing
+  is copied. If it can't find an entrypoint it prints the two lines to add.
+
+The browser client is copied into the app, so upgrading the gem does not
+update it. After an upgrade whose CHANGELOG mentions the client, run
+`bin/rails generate railwatch:install --force --no-doctor`, or copy the
+file by hand:
+
+```sh
+cp "$(bundle exec ruby -e 'require "railwatch"; print Railwatch.browser_client_path')" app/frontend/lib/railwatch.ts  # or app/javascript/lib/...
+```
+
+Without `--force` the generator asks before overwriting a copy that
+differs. Either way, review the diff if you have edited your copy. The
+generator's other steps leave what they already wrote alone.
 - `require "railwatch/rspec"` in `spec/rails_helper.rb`, or
   `require "railwatch/minitest"` in `test/test_helper.rb`.
 

data/docs/records.md

@@ -104,6 +104,8 @@ boundaries. The `action`/`render` boundaries come from
 | `payload` | Filtered request params — only captured when `config.capture_request_payload` is on **and** the request raised an exception (never for successful requests). |
 | `user_agent` | Truncated to 256 chars. |
 | `files` | Array of `{name, size, content_type, error}` for each uploaded file in a multipart request (metadata only, never contents). A non-multipart request body is never parsed to fill this in. |
+| `session_id` | The browser client's session id, from `X-Railwatch-Session` or else the `railwatch_session` cookie, so a full page load carries it too. On a browser's first page load, the id the middleware set in that cookie on this response (see Release health in configuration.md). Never the `"user:<id>"` key the server session falls back to. At most 64 of `[A-Za-z0-9_-]`; absent when missing or not that shape. |
+| `tab_id` | The browser client's tab id, from `X-Railwatch-Tab`, which it sends only on Inertia visits: a full page load has none. Same validation, absent otherwise. |
 | `profiled` | `true` when a `profile` record shipped for this request; absent otherwise. |
 
 ### `job_attempt`
@@ -396,8 +398,10 @@ the normalized message. So browser errors group, split, merge, resolve,
 and regress through the same Issue machinery.
 
 `context` carries a `browser` key with the page `url`, the Inertia
-`component`, the `visit` the error happened in if any, the tab's
-`session` id, the `user_agent`, and up to 20 `breadcrumbs`. Each
+`component`, the `visit` the error happened in if any, the browser
+`session` id and the `tab` id it was thrown in, both stamped by the client
+when the error fired (the flush's session stands in for a client that
+sends none; each at most 64 of `[A-Za-z0-9_-]`, absent otherwise), the `user_agent`, and up to 20 `breadcrumbs`. Each
 breadcrumb is `{at, kind, text}`, with `kind` being `console`, `click`,
 or `navigate`. The breadcrumbs are the trail the client recorded before
 the crash. Anything the app passed as `reportError(error, context)` is
@@ -776,6 +780,8 @@ entirely if `config.beacon_enabled` is off.
 | `user` | Resolved server-side from the beacon request's session/cookies, same resolver as every other record. |
 | `tenant` | Current tenant context. |
 | `user_agent` | Truncated to 256 chars. |
+| `session_id` | The browser session the visit happened in (see `session`), when the client sent one shaped like an id: at most 64 of `[A-Za-z0-9_-]`. Absent otherwise. |
+| `tab_id` | The tab the visit happened in: a 16-hex id the client keeps in `sessionStorage` (`railwatch.tab`), so it survives a reload of the tab but not a new tab. "Duplicate tab" copies `sessionStorage`, so a duplicated tab shares its original's id until one of them is reloaded fresh. Same validation, absent otherwise. |
 
 The **initial page load** is reported as a visit too, even though Inertia
 never routed it. It has `method` `"GET"`, `status` `"success"`, and
@@ -799,13 +805,25 @@ per deploy and reports crash-free rates from them. Two sources produce
 the same record:
 
 - **Browser**, `source: "browser"`. The client,
-  `app/frontend/lib/railwatch.ts`, mints a 16-hex id per tab in
-  `sessionStorage` under the key `railwatch.session`, so it dies with the
-  tab. It mirrors the id into a `railwatch_session` cookie and sends it
-  with every beacon flush. `Railwatch::BeaconController` writes at most
-  one `session` record per flush. The first, with no `duration_ms` yet,
-  opens the session. Later ones beat it along, and the
-  `pagehide`/`visibilitychange` flush closes it with `ended`.
+  `app/frontend/lib/railwatch.ts`, keeps one session per browser, shared
+  by every tab, the way GA4 and Amplitude do: a 16-hex id in
+  `localStorage` (`railwatch.session`, with `railwatch.session.at` when it
+  started and `railwatch.session.seen` for its last activity in any tab).
+  Activity is a page load, an Inertia visit the user waits on, and a tab
+  coming back into view. After 30 minutes with no activity in any tab, or
+  24 hours after it started, the next activity mints a new id. When
+  `localStorage` throws the session lives in `sessionStorage`, and when
+  that throws too, in memory; a new tab still joins the session through
+  the cookie. A browser's first page load gets its id from the server, in
+  that cookie, and the client adopts it when no live session is stored.
+  The client mirrors the id into a `railwatch_session` cookie that lapses
+  after 30 minutes, renewed on every activity, and sends it with every
+  beacon flush. `Railwatch::BeaconController` writes at most one `session` record
+  per flush. The first, with no `duration_ms` yet, opens the session.
+  Later ones beat it along. Closing a tab does not end the session, since
+  other tabs may still be in it; a tab that sees the session time out
+  sends one last beat with `ended`, and a session no tab comes back to
+  ends only by the platform's own timeout.
 - **Server**, `source: "server"`. `lib/railwatch/sessions.rb` aggregates,
   per process, every request that resolves a user or carries that cookie
   or an `X-Railwatch-Session` header. A background thread ships one
@@ -830,7 +848,7 @@ halves of one session rather than counting it twice.
 | `requests` | Requests in this session so far (server only). |
 | `visits` | Inertia visits in this beacon flush (browser only). |
 | `errors` | Requests that 5xx'd or raised (server), or visits with status `"error"` in this flush (browser). |
-| `ended` | Whether this is the session's last record. |
+| `ended` | Whether this is the session's last record. A browser session is only `ended` when a tab saw it time out, never because a tab closed. |
 | `user` | Resolved user id, when there is one. |
 
 ### `process`

data/docs/troubleshooting.md

@@ -26,7 +26,7 @@ the install is broken.
 | `ignored record types` | Never fails; it prints what `c.ignore` is dropping. |
 | `interactive sessions` | Never fails; it prints whether consoles are captured and the runner scratch paths. |
 | `kamal post-deploy hook` | `.kamal/hooks/post-deploy` is missing or doesn't mention Railwatch. Only matters if you deploy with Kamal. |
-| `browser client` | `app/frontend/lib/railwatch.ts` isn't there. Only matters for Inertia visit timing. |
+| `browser client` | `lib/railwatch.ts` isn't in the app's frontend source directory (ViteRuby's `sourceCodeDir`, else `app/frontend` or `app/javascript`). 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`. |

data/lib/generators/railwatch/agents/agents_generator.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+require "erb"
+require "json"
+require "rails/generators"
+
+module Railwatch
+  module Generators
+    # Points the coding agents working on this app at its development
+    # Railwatch: the MCP server the railwatch-server gem serves at
+    # <mount>/mcp (no token needed from this machine in development), and a
+    # short note on the dev loop. Every file it touches is either its own or
+    # changed only between its markers, so it can be re-run after an upgrade.
+    class AgentsGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Writes .mcp.json (Claude Code's project MCP servers) with this app's development Railwatch, " \
+           "a marked Railwatch block in AGENTS.md and/or CLAUDE.md, and a Claude Code skill. Safe to re-run."
+
+      class_option :url, type: :string,
+                         desc: "The MCP endpoint. Default: http://localhost:<PORT or 3000><mount>/mcp."
+      class_option :skill, type: :boolean, default: true,
+                           desc: "Write .claude/skills/railwatch/SKILL.md."
+
+      SERVER_NAME = "railwatch"
+      BEGIN_MARKER = "<!-- BEGIN railwatch (bin/rails generate railwatch:agents) -->"
+      END_MARKER = "<!-- END railwatch -->"
+      AGENT_FILES = %w[AGENTS.md CLAUDE.md].freeze
+
+      # Claude Code's project scope: { "mcpServers": { name: { "type": "http",
+      # "url": ... } } } in .mcp.json at the root
+      # (https://code.claude.com/docs/en/mcp, "Project scope"). Only the
+      # railwatch entry is written; other servers and keys are kept.
+      def write_mcp_json
+        path = File.join(destination_root, ".mcp.json")
+        config = File.exist?(path) ? JSON.parse(File.read(path)) : {}
+        return say("Not touching .mcp.json: its top level is not a JSON object.", :red) unless config.is_a?(Hash)
+
+        servers = config["mcpServers"] ||= {}
+        return say("Not touching .mcp.json: its mcpServers is not a JSON object.", :red) unless servers.is_a?(Hash)
+
+        entry = { "type" => "http", "url" => mcp_url }
+        return say_status(:identical, ".mcp.json", :blue) if servers[SERVER_NAME] == entry
+
+        servers[SERVER_NAME] = entry
+        create_file ".mcp.json", "#{JSON.pretty_generate(config)}\n", force: true
+      rescue JSON::ParserError => e
+        say("Not touching .mcp.json: it is not valid JSON (#{e.message.lines.first.strip}). Add this under mcpServers yourself: " \
+            "#{JSON.generate(SERVER_NAME => { "type" => "http", "url" => mcp_url })}", :red)
+      end
+
+      # The block goes into whichever of AGENTS.md and CLAUDE.md exist, and
+      # AGENTS.md is created when neither does. Between its markers it is
+      # replaced on every run; nothing outside them is changed.
+      def write_agent_instructions
+        existing = AGENT_FILES.select { |name| File.exist?(File.join(destination_root, name)) }
+        (existing.empty? ? [ "AGENTS.md" ] : existing).each { |name| write_block(name, block) }
+      end
+
+      # A Claude Code project skill (https://code.claude.com/docs/en/skills):
+      # .claude/skills/<name>/SKILL.md, frontmatter `name` and `description`.
+      # The whole file is this generator's, rewritten on every run.
+      def write_skill
+        return unless options[:skill]
+
+        template "SKILL.md", ".claude/skills/railwatch/SKILL.md", force: true
+      end
+
+      def show_next_steps
+        say <<~STEPS, :green
+
+          Railwatch MCP for this app (development): #{mcp_url}
+            Claude Code reads .mcp.json and asks once before it uses a project server.
+            Other clients: add the same URL as a streamable HTTP MCP server.
+            No token is needed from this machine in development (railwatch-server).
+            Anywhere else, send one: Authorization: Bearer rwp_... (Settings -> Profile).
+        STEPS
+      end
+
+      # `contents` with the marked block replaced by `block`, or with it
+      # appended (after a blank line) when there is none. The block replaced
+      # is the first BEGIN whose END comes before any other BEGIN, so a BEGIN
+      # left without its END is never paired with a later block's END (which
+      # would delete everything between them): it stays as it is, and the
+      # block is appended once and then found on every re-run.
+      def self.with_block(contents, block)
+        return block if contents.nil? || contents.strip.empty?
+
+        start = finish = nil
+        at = 0
+        while (candidate = contents.index(BEGIN_MARKER, at))
+          after = candidate + BEGIN_MARKER.length
+          close = contents.index(END_MARKER, after)
+          reopen = contents.index(BEGIN_MARKER, after)
+          if close && (reopen.nil? || close < reopen)
+            start, finish = candidate, close
+            break
+          end
+          at = after
+        end
+        if finish
+          tail = contents[(finish + END_MARKER.length)..].sub(/\A\n/, "")
+          "#{contents[0...start]}#{block}#{tail}"
+        else
+          "#{contents.sub(/\n*\z/, "\n")}\n#{block}"
+        end
+      end
+
+      private
+
+      def mcp_url
+        options[:url].presence || "http://localhost:#{ENV.fetch("PORT", "3000")}#{mount_path}/mcp"
+      end
+
+      def dashboard_url
+        mcp_url.delete_suffix("/mcp")
+      end
+
+      # The app itself, for the curl in the instructions.
+      def app_url
+        dashboard_url.delete_suffix(mount_path)
+      end
+
+      # The slug railwatch-server gives the app it provisions: the app's
+      # module name, parameterized.
+      def app_slug
+        name = defined?(Rails) && Rails.application ? Rails.application.class.module_parent_name : File.basename(destination_root)
+        name.to_s.parameterize
+      end
+
+      def mount_path
+        path = defined?(Railwatch::Server) && Railwatch::Server.respond_to?(:config) ? Railwatch::Server.config.normalized_mount_path : "/railwatch"
+        path.to_s.empty? ? "/railwatch" : path
+      end
+
+      def block
+        content = ERB.new(File.read(File.join(self.class.source_root, "agents_block.md.tt")), trim_mode: "-").result(binding).strip
+        "#{BEGIN_MARKER}\n#{content}\n#{END_MARKER}\n"
+      end
+
+      def write_block(name, text)
+        path = File.join(destination_root, name)
+        current = File.exist?(path) ? File.read(path) : nil
+        updated = self.class.with_block(current, text)
+        return say_status(:identical, name, :blue) if updated == current
+
+        create_file name, updated, force: true
+      end
+    end
+  end
+end

data/lib/generators/railwatch/agents/templates/SKILL.md.tt

@@ -0,0 +1,32 @@
+---
+name: railwatch
+description: Find out why a page or job in this Rails app is slow or failing in development, using Railwatch (SQL with file:line, N+1s, views, logs, exceptions per request). Use after changing code that touches the database or views, when a request is slow, or to check a performance fix.
+---
+
+# Railwatch in development
+
+The `railwatch` MCP server (<%= mcp_url %>, in `.mcp.json`) reads what
+this app recorded while it ran under `bin/dev`. No token is needed from this
+machine. Arguments: `application_slug: "<%= app_slug %>"`, `environment: "development"`.
+
+1. Make the request and read its cost from the response headers:
+
+   ```sh
+   curl -si <%= app_url %>/path | grep -i -e server-timing -e x-railwatch
+   ```
+
+   `Server-Timing: total;dur=…, db;dur=…;desc="N queries", view;dur=…, other;dur=…`
+   and `X-Railwatch-Execution-Id: <id>`. A request with a session needs its
+   cookie (`-b`), or use the id from the browser's network panel.
+2. `get_execution(execution_id: <id>)`, or `last_execution(path: "/path")`
+   without the id: `summary` first (where the time went, the repeated
+   queries and N+1s with their `source` `file:line` and a fix), then a page
+   of the timeline (`timeline_offset` for more).
+3. `get_route(route: "GET /path")`: the route's N+1s with the line and the
+   `includes` that fixes each, and its slowest queries. `explain_query` for a
+   query's plan.
+4. Change the code, repeat 1-2, and report the before and after query count
+   and db time.
+
+For a person, link the dashboard: <%= dashboard_url %>. Errors:
+`list_issues`, then `get_issue(key:)`.