railwatch 0.6.0 → 0.7.0

data/app/frontend/types/globals.d.ts

@@ -0,0 +1,9 @@
+import type { FlashData, SharedProps } from "@/types"
+
+declare module "@inertiajs/core" {
+  export interface InertiaConfig {
+    sharedPageProps: SharedProps
+    flashDataType: FlashData
+    errorValueType: string[]
+  }
+}

data/app/frontend/types/index.ts

@@ -0,0 +1,288 @@
+import type { LucideIcon } from "lucide-react"
+
+export interface Auth {
+  user: User
+  session: Pick<Session, "id" | "recently_authenticated">
+}
+
+export interface BreadcrumbItem {
+  title: string
+  href: string
+}
+
+export interface NavItem {
+  title: string
+  href: string
+  icon?: LucideIcon | null
+  isActive?: boolean
+}
+
+export interface FlashData {
+  alert?: string
+  warning?: string
+  notice?: string
+}
+
+export interface AccountSummary {
+  id: number
+  name: string
+  slug: string
+  plan: string
+}
+
+export interface EnvironmentSummary {
+  id: number
+  name: string
+  slug: string
+  last_seen_at: string | null
+  paused: boolean
+}
+
+export interface ApplicationSummary {
+  id: number
+  name: string
+  slug: string
+  issue_prefix: string
+  environments: EnvironmentSummary[]
+}
+
+export interface EnvironmentContext {
+  id: number
+  name: string
+  slug: string
+  application_id: number
+  application_name: string
+  issue_prefix: string
+  last_seen_at: string | null
+  paused: boolean
+  token_prefix: string
+  repository_url: string | null
+  default_branch: string
+}
+
+export type Window = "1h" | "6h" | "24h" | "7d" | "30d" | "custom"
+
+// Chart bucket width; the server offers the subset that fits the window.
+export type Step = "1m" | "5m" | "15m" | "1h" | "6h" | "1d"
+
+export interface WindowRange {
+  from: string
+  to: string
+}
+
+export type TelemetryTimeParams =
+  | { window: Exclude<Window, "custom">; from?: never; to?: never }
+  | { window?: never; from: string; to: string }
+
+export interface CursorMeta {
+  limit: number
+  next_cursor: string | null
+  has_more: boolean
+}
+
+export interface SharedProps {
+  auth: Auth
+  account: AccountSummary | null
+  accounts: { id: number; name: string }[]
+  applications: ApplicationSummary[]
+  environment?: EnvironmentContext
+  telemetry_freshness?: {
+    received_at: string | null
+    aggregated_at?: string | null
+    processing_lag_seconds: number | null
+  }
+  window?: Window
+  range?: WindowRange
+  step?: Step
+  steps?: Step[]
+  flash: FlashData
+  google_oauth: boolean
+  embedded?: boolean
+  saved_views?: SavedView[]
+  [key: string]: unknown
+}
+
+export interface User {
+  id: number
+  name: string
+  email: string
+  provider: string | null
+  avatar?: string
+  verified: boolean
+  editor: string
+  editor_root: string | null
+  created_at: string
+  updated_at: string
+  [key: string]: unknown
+}
+
+export interface Session {
+  id: string
+  user_agent: string
+  ip_address: string
+  created_at: string
+  recently_authenticated: boolean
+}
+
+// Telemetry shapes shared by pages
+
+export type Percentile = "p50" | "p95" | "p99"
+
+// One chart bucket. Durations are null where nothing ran, so a latency
+// line breaks over a quiet bucket instead of dropping to zero.
+export interface SeriesPoint {
+  t: string
+  count: number
+  errors: number
+  client_errors: number
+  avg: number | null
+  p50: number | null
+  p95: number | null
+  p99: number | null
+}
+
+export interface GroupRow {
+  group_hash: string
+  name: string
+  count: number
+  errors: number
+  client_errors: number
+  avg: number
+  p50: number
+  p95: number
+  p99: number
+  max: number
+  sparkline: number[]
+}
+
+export interface Summary {
+  count: number
+  errors: number
+  client_errors: number
+  avg: number
+  p50: number
+  p95: number
+  p99: number
+  max: number
+}
+
+export interface SummaryWithDelta {
+  current: Summary
+  previous: Summary
+}
+
+// Release health: crash-free rates are null, not 0, when there were no
+// sessions (or no users) to divide by.
+export interface ReleaseHealthSummary {
+  sessions: number
+  users: number
+  crash_free_sessions: number | null
+  crash_free_users: number | null
+  errored: number | null
+  avg_duration_ms: number | null
+}
+
+export interface SessionStatusPoint {
+  t: string
+  sessions: number
+  ok: number
+  errored: number
+  crashed: number
+}
+
+export interface DeployMarker {
+  deploy: string
+  ref: string
+  at: string
+}
+
+export interface IssueRow {
+  id: number
+  key: string
+  title: string
+  kind: "exception" | "performance"
+  status: "open" | "resolved" | "ignored" | "merged"
+  priority: "low" | "normal" | "high" | "urgent"
+  culprit?: string | null
+  occurrences: number
+  affected_users: number
+  first_seen_at?: string
+  last_seen_at: string
+  assignee?: { id: number; name: string } | null
+  fingerprint_source?: string | null
+  source?: string | null
+  application?: { id: number; name: string }
+  environment?: { id: number; name: string }
+}
+
+export interface ExecutionRow {
+  execution_id: string
+  name: string
+  kind?: string
+  status?: number | null
+  outcome?: string | null
+  duration: number
+  occurred_at: string
+  user_ref?: string | null
+  tenant?: string | null
+  exception_preview?: string | null
+  inertia_component?: string | null
+  queries?: number
+  deploy?: string | null
+}
+
+export interface Frame {
+  file: string
+  line: number
+  function: string
+  in_app: boolean
+  code?: Record<string, string>
+}
+
+export interface ExceptionDetail {
+  id: number
+  class_name: string
+  message: string
+  handled: boolean
+  severity?: string
+  source?: string
+  file?: string | null
+  line?: number | null
+  frames: Frame[]
+  cause?: { class: string; message: string } | null
+  locals?: Record<string, string> | null
+  context?: string | null
+  occurred_at?: string
+  execution_id?: string | null
+  execution_source?: string | null
+  execution_preview?: string | null
+  deploy?: string | null
+  group_hash?: string
+}
+
+export interface TimelineEntry {
+  type: string
+  id: number
+  offset: number
+  duration: number | null
+  label: string
+  stage: string | null
+  sql?: string | null
+  source?: string | null
+  detail?: Record<string, string | number | boolean | null>
+}
+
+// A named filter on one environment page, shared through every env page's
+// props. `url` is built server-side from the page's route helper.
+export interface SavedView {
+  id: number
+  name: string
+  page: string
+  query: string | null
+  window: string | null
+  params: Record<string, string>
+  pinned: boolean
+  shared: boolean
+  mine: boolean
+  url: string
+}

data/app/frontend/types/vite-env.d.ts

@@ -0,0 +1,9 @@
+/// <reference types="vite/client" />
+
+interface ImportMetaEnv {
+  readonly VITE_APP_NAME: string
+}
+
+interface ImportMeta {
+  readonly env: ImportMetaEnv
+}

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/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/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

data/docs/configuration.md

@@ -2,18 +2,17 @@
 
 Everything below lives on `Railwatch::Configuration`, in
 `lib/railwatch/configuration.rb`. Set it via
-`Railwatch.configure { |c| ... }` in `config/initializers/railwatch.rb`.
-That file is created by
-`bin/rails generate railwatch:install`. Most settings have a `RAILWATCH_*`
-env var default; the tables below show which. Explicit values set in the
-initializer always win over the env var.
+`Railwatch.configure { |c| ... }` in `config/initializers/railwatch.rb`,
+which `bin/rails generate railwatch:install` creates. Most settings have a
+`RAILWATCH_*` env var default; the tables below show which. Explicit
+values set in the initializer always win over the env var.
 
 ## Core
 
 | Attribute | Env var | Default | Meaning |
 |---|---|---|---|
-| `enabled` | `RAILWATCH_ENABLED` | `true` | Master switch. `Railwatch.enabled?` is also `false` whenever `token` is blank, so setting only `RAILWATCH_TOKEN` is enough to turn Railwatch on. |
-| `token` | `RAILWATCH_TOKEN` | nil | Bearer token for `/ingest`. Required. |
+| `enabled` | `RAILWATCH_ENABLED` | `true` | Master switch. With `transport = :http`, `Railwatch.enabled?` is also `false` whenever `token` is blank, so setting only `RAILWATCH_TOKEN` is enough to turn a cloud install on. An embedded install needs no token. |
+| `token` | `RAILWATCH_TOKEN` | nil | Bearer token for `/ingest`. Required with `transport = :http` and for [export](#export-to-railwatch-cloud). |
 | `ingest_url` | `RAILWATCH_INGEST_URL` | `https://railwatch.rebulk.com` | Platform base URL. Point at a self-hosted instance to override. |
 | `allow_http` | `RAILWATCH_ALLOW_HTTP` | `false` | Permit a non-loopback plain HTTP ingest URL. HTTPS is required by default; `localhost`, `127.0.0.1`, and `::1` remain available for local self-hosted development. |
 | `deploy` | `RAILWATCH_DEPLOY` | auto-detected (order below), then nil | Version tag stamped on every record and used by `railwatch:deploy`. Full 40-character SHAs are shortened to 12 characters. |
@@ -26,7 +25,8 @@ initializer always win over the env var.
 | `beacon_rate_limit` | `RAILWATCH_BEACON_RATE_LIMIT` | `120` | Beacon POSTs accepted per client IP per minute before `POST /railwatch/beacon` answers 429. The beacon is unauthenticated and keeps every browser error it is sent, so this is what stops a script from spending the app's event quota. Counted in the app's cache store; `0` turns it off. |
 
 `Railwatch.enabled?` delegates to `config.enabled?`, which is `@enabled &&
-token.present?`. There is no separate "is configured" check elsewhere.
+(local? || token.present?)`. There is no separate "is configured" check
+elsewhere.
 
 Deploy detection stops at the first value found: `RAILWATCH_DEPLOY`,
 `KAMAL_VERSION`, `GIT_REV`, `GIT_SHA`, `SOURCE_VERSION`,
@@ -569,7 +569,7 @@ Rake tasks and Solid Queue jobs are never interactive.
 
 | Attribute | Env var | Default | Meaning |
 |---|---|---|---|
-| `capture_exception_source` | `RAILWATCH_CAPTURE_EXCEPTION_SOURCE_CODE` | `true` | Send source snippet lines surrounding each in-application exception frame to Railwatch Cloud. This is on by default for crash context; disable it when source disclosure is outside the application's telemetry policy. |
+| `capture_exception_source` | `RAILWATCH_CAPTURE_EXCEPTION_SOURCE_CODE` | `true` | Record source snippet lines surrounding each in-application exception frame (sent to Railwatch Cloud when the install reports there or exports). This is on by default for crash context; disable it when source disclosure is outside the application's telemetry policy. |
 | `capture_exception_locals` | `RAILWATCH_CAPTURE_EXCEPTION_LOCALS` | `false` | Snapshot the raising frame's local variables (up to 25, values truncated to 200 chars, run through the same filter as request params) onto each exception, like Sentry's locals panel. Installs a `TracePoint(:raise)`; opt in per environment. |
 | `capture_request_payload` | `RAILWATCH_CAPTURE_REQUEST_PAYLOAD` | `false` | Capture (redacted) request params — only for a request that raised, never otherwise. |
 | `capture_job_arguments` | `RAILWATCH_CAPTURE_JOB_ARGUMENTS` | `false` | Add the job's real arguments (`job.serialize["arguments"]`) to each `job_attempt`/`scheduled_task` record, capped at 8 KiB of JSON. Hash arguments run through the same filter as request params. Off by default because job arguments routinely carry PII; `arguments_preview` (argument *shapes* only) is always on regardless. |
@@ -884,7 +884,7 @@ ignore block's building blocks, and are nestable.
 ## Embedded mode
 
 ```ruby
-c.transport = :local        # RAILWATCH_TRANSPORT; default "http"
+c.transport = :local        # RAILWATCH_TRANSPORT; runtime default "http", but the installer writes :local
 c.issue_prefix = "SHOP"     # RAILWATCH_ISSUE_PREFIX; default from the app name
 c.repository_url = "..."    # RAILWATCH_REPOSITORY_URL
 c.retention_days = 7        # RAILWATCH_RETENTION_DAYS
@@ -892,8 +892,9 @@ c.http_basic_auth_enabled = true      # RAILWATCH_HTTP_BASIC_AUTH_ENABLED; on, a
 c.http_basic_auth_user = "ops"        # RAILWATCH_HTTP_BASIC_AUTH_USER, or credentials railwatch.http_basic_auth_user
 c.http_basic_auth_password = "..."    # RAILWATCH_HTTP_BASIC_AUTH_PASSWORD, or credentials railwatch.http_basic_auth_password
 c.base_controller_class = "AdminController"  # RAILWATCH_BASE_CONTROLLER_CLASS; default ActionController::Base
-c.dashboard_open = false              # RAILWATCH_DASHBOARD_OPEN; public on purpose
+c.dashboard_open = false              # RAILWATCH_DASHBOARD_OPEN; default false, true makes it public on purpose
 c.dashboard_user = ->(request) { { id:, name:, email: } or nil }
+c.writer_socket = "tmp/sockets/railwatch-writer.sock"  # RAILWATCH_WRITER_SOCKET
 ```
 
 With `transport = :local` the reporter writes each batch into the app's
@@ -905,25 +906,48 @@ railwatch:authentication:configure` has written credentials; a host with
 its own admin auth turns Basic off and sets `base_controller_class` or a
 routes constraint. Full walkthrough: [Embedded mode](embedded.md).
 
+### Export to Railwatch Cloud
+
+An embedded install can also mirror every record to Railwatch Cloud.
+Off unless `export_enabled` is set; a configured token alone sends
+nothing. Only meaningful with `transport = :local`.
+
+| Attribute | Env var | Default | Meaning |
+|---|---|---|---|
+| `export_enabled` | `RAILWATCH_EXPORT_ENABLED` | `false` | Mirror every record to the cloud as well as storing it locally. |
+| `export_token` | `RAILWATCH_EXPORT_TOKEN` | `token` | Cloud environment token to send with. |
+| `export_url` | `RAILWATCH_EXPORT_URL` | `{ingest_url}/ingest` | Where to send. |
+| `export_max_bytes` | `RAILWATCH_EXPORT_MAX_BYTES` | `268435456` (256 MiB) | Queue ceiling in bytes. At capacity new work is refused and counted, not swapped for old. |
+| `export_max_deliveries` | `RAILWATCH_EXPORT_MAX_DELIVERIES` | `100000` | Queue ceiling in deliveries. |
+| `export_max_age` | `RAILWATCH_EXPORT_MAX_AGE_SECONDS` | `86400` | How long a queued delivery is kept. At most seven days, past which the receiver no longer recognises it. |
+
+`railwatch:doctor` fails when export is enabled and cannot work, and
+`railwatch:export:status` shows the queue. See
+[Embedded mode](embedded.md#three-ways-to-run-it).
+
 ## Rake tasks
 
 Ship with the gem via Rails::Engine's default `lib/tasks` convention, in
 `lib/tasks/railwatch_tasks.rake`:
 
-- **`railwatch:status`** pings `{ingest_url}/ingest/ping` with the
-  configured token. It aborts if `RAILWATCH_TOKEN` is unset or the ping
-  fails.
-- **`railwatch:doctor`** prints a ✓/✗ checklist of the whole install:
-  token, ingest URL, `GET /ingest/ping`, `Railwatch::Middleware::Request`
+- **`railwatch:status`** embedded: prints that telemetry is stored in the
+  app. Cloud: pings `{ingest_url}/ingest/ping` with the configured token,
+  and aborts if `RAILWATCH_TOKEN` is unset or the ping fails.
+- **`railwatch:doctor`** prints a ✓/✗ checklist of the whole install.
+  Embedded, it checks both databases and their migrations, telemetry
+  disk mode, the maintenance clock, the writer process, dashboard access,
+  and export when enabled. Cloud, it checks the token, where the token is
+  stored, the ingest URL and its transport security, and
+  `GET /ingest/ping`. Then, either way: `Railwatch::Middleware::Request`
   in the middleware stack, the mounted engine's beacon route,
-  `config.deploy` and its environment, `REVISION`, Git, or initializer
-  source, sample rates, ignored record types, the Kamal `post-deploy`
-  hook, `app/frontend/lib/railwatch.ts`, and whether `railwatch/rspec` or
-  `railwatch/minitest` is required by the test helper. The last five are
-  informational. It exits non-zero only when the token is missing or the
-  ping fails.
-- **`railwatch:deploy[ref,name,url]`** POSTs `{deploy, ref, name, url,
-  server, timestamp, performer, destination, service, commits}` to
+  `config.deploy` and its source, sample rates, ignored record types, the
+  Kamal `post-deploy` hook, the browser client and whether an entrypoint
+  calls it, the profiler backend, and the test matchers. It exits
+  non-zero only on the lines marked fatal in
+  [Troubleshooting](troubleshooting.md).
+- **`railwatch:deploy[ref,name,url]`** embedded: writes the deploy marker
+  to the app's `railwatch` database. Cloud: POSTs `{deploy, ref, name,
+  url, server, timestamp, performer, destination, service, commits}` to
   `{ingest_url}/ingest/deploys`. `deploy` comes from `config.deploy`. It
   aborts if that's unset. `ref` defaults to `git rev-parse HEAD` when not
   passed. `performer`/`destination`/`service` come from `KAMAL_PERFORMER`,
@@ -931,13 +955,30 @@ Ship with the gem via Rails::Engine's default `lib/tasks` convention, in
   `{sha, author, message, at}` objects, newest first, from `git log`. It
   is empty inside an app container, which has no `.git`. That is why the
   hook below posts from the deployer instead.
+- **`railwatch:authentication:configure`** writes the embedded
+  dashboard's HTTP Basic credentials to the current environment's Rails
+  credentials.
+- **`railwatch:export:status`**, **`railwatch:export:rebind`**,
+  **`railwatch:export:discard`** show the export queue, clear a
+  credential block (abandoning work queued under the old token), and
+  abandon everything queued.
+- **`railwatch:vacuum:status`** and **`railwatch:vacuum`** report and
+  reclaim the telemetry database's disk
+  ([Embedded mode](embedded.md#giving-the-disk-back)).
+- **`railwatch:token`** and **`railwatch:mcp`** print where to create a
+  cloud ingest token and paste-ready MCP client configuration.
+- **`railwatch:sourcemaps[directory,delete]`** uploads browser source
+  maps ([Source maps](source-maps.md)).
 
 ## Kamal integration
 
 `bin/rails generate railwatch:install` writes `.kamal/hooks/post-deploy`,
-but only if `config/deploy.yml` already exists. It no-ops when
-`RAILWATCH_TOKEN` isn't set, and never fails a deploy. Every network call
-ends in `|| true`.
+but only if `config/deploy.yml` already exists. With
+`RAILWATCH_TRANSPORT=local` in the deployer's environment it runs
+`bin/rails railwatch:deploy[$KAMAL_VERSION]` in the primary container,
+which records the marker in the embedded database, and stops. Otherwise
+it no-ops when `RAILWATCH_TOKEN` isn't set. It never fails a deploy.
+Every network call ends in `|| true`.
 
 The hook runs on the **deployer machine**, not in a container, which is
 the whole point. That's where the git history lives and where Kamal