rails_mind 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '087e7d8cc40b60a6ed2ab02feb5ffac9f7a6f1592eac30c964b792482630349f'
-  data.tar.gz: 1f073cdb04f317e08a486b14361f12faf84ebfdd0c785c075436896eecbc720c
+  metadata.gz: 819a570e3f4f65e0fb8bae7de68b1a81ee744bccb77349858c640fcc912e95b4
+  data.tar.gz: 62df4fca70603e28458d277dcd8d734a5de04af7c514f997e15686122a02dbd2
 SHA512:
-  metadata.gz: 95b65914e0d950384712582cb3f4b294e4a04a99ec62c42db53fe2252424932879940997815e7bc3fdaab51689866376cf42a9a3bafb107e2c66e9d335d38adc
-  data.tar.gz: 848479498910d94b0f73529eacddb16639f8364585dfef7687d4711229a560e6b1a0e25b5654506d69650ff136acb14f5416883b74a44d694708374c875fdd5b
+  metadata.gz: 3583084684b6ac4b165864c14fbfe3922fc2f678c8d7aa9383418d95fdc528083bbe2327e5428d167d80e54a28445309eb6243bd3c6c3dac36fc8a67fa9e0630
+  data.tar.gz: e968233e4025ce470a83207214ef886032bff662faea00f824f3aceefad55319aa6d3235b62cc16368c5b8ccec7db86a6914ce1d5cb1a5db2c9bb282a543f0f2

data/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.3.0 — 2026-10-10
+
+- Enable bounded automatic endpoint sampling for routine successful requests, driven by expiring hosted policies. Preserve slow, failed, repeated-query requests and all other signal kinds from SDK sampling.
+- Report eligible request selection and queue losses with immutable IDs and independent acknowledgments, including report-only batches at zero sampling rates. Keep old-server event delivery compatible until a v1 handshake.
+- Add explicit local opt-out, effective request metadata, bounded control parsing, fork resets, and sampling diagnostics. Local opt-out does not disable server-side sampling or quotas.
+- Separate known local drops from unconfirmed delivery; failed responses may follow partial server acceptance.
+
+## 0.2.0 — 2026-10-09
+
+- Correlate requests, serialized ActiveJob executions, and mailer attempts with native trace IDs while preserving existing OpenTelemetry context.
+- Observe job enqueue/start, retry/discard, and completion without changing existing job-count semantics; distinguish total queue delay from delay after a scheduled job becomes eligible.
+- Observe Action Mailer processing, ordinary/forced delivery attempts, disabled delivery, callback aborts, and exposed failures. Collect only bounded lifecycle metadata, excluding recipients, subjects, message bodies, attachments, and arguments. Recipient delivery remains unknown.
+- Connect Claude Code and Codex with `rails_mind:agent`, including a write-free preview, preserved existing configuration, and shared agent instructions.
+- Choose an environment-variable API token or a local Rails encrypted-credentials helper; check readiness without displaying the token.
+- Document the full agent handoff: read findings, follow a brief, report a PR, and watch deployment and recurrence in RailsMind.
+
 ## 0.1.0 — 2026-09-25
 
 Initial public release of the RailsMind client under the MIT license.

data/CONTRIBUTING.md

@@ -6,7 +6,7 @@ sample are maintained separately and remain proprietary.
 
 ## Setup
 
-Use Ruby 4.0.6 and Node 22 for the currently verified combination.
+CI uses Ruby 4.0.6 and Node 22. Native workflow tests have also been run locally on Ruby 4.0.7; use the committed lockfile.
 
 ```sh
 git clone https://github.com/cmartyn/rails_mind.git
@@ -37,7 +37,7 @@ read this public repository.
 ## Packaging and releases
 
 `bundle exec ruby script/package_smoke.rb` builds a temporary gem and exercises its
-packaged installer and browser files. `bundle exec rake build` writes the gem to
+packaged installer, browser files, and native workflow integrations. `bundle exec rake build` writes the gem to
 `pkg/`. Neither command publishes anything.
 
 Publishing uses [RubyGems trusted publishing](https://guides.rubygems.org/trusted-publishing/)
@@ -66,8 +66,8 @@ customer application.
 Create an annotated tag matching the gem version and push it:
 
 ```sh
-git tag -a v0.1.0 -m "Release rails_mind 0.1.0"
-git push origin v0.1.0
+git tag -a v0.2.0 -m "Release rails_mind 0.2.0"
+git push origin v0.2.0
 ```
 
 The workflow verifies the tag/version, reruns the Ruby, JavaScript, and package

data/README.md

@@ -1,12 +1,12 @@
 # RailsMind SDK
 
 The MIT-licensed Ruby client for [RailsMind](https://railsmind.com). One bounded
-collector for Rails requests, errors, jobs, Ahoy events, Flipper observations,
-and selected OpenTelemetry spans. Version 0.1.0 is an early release; see
+collector for Rails requests, errors, jobs, mailer attempts, Ahoy events, Flipper
+observations, and selected OpenTelemetry spans. Version 0.3.0 is an early release; see
 [compatibility and validation limits](docs/compatibility.md).
 
 ```ruby
-gem "rails_mind", "~> 0.1.0"
+gem "rails_mind", "~> 0.3.0"
 ```
 
 Install from RubyGems.org and commit your application's `Gemfile.lock` to pin the
@@ -44,8 +44,19 @@ RailsMind.with_context(user_id: current_user.id.to_s, account_id: current_accoun
 end
 ```
 
+Requests, ActiveJob executions, and Action Mailer attempts share native trace
+context without requiring OpenTelemetry. Existing OpenTelemetry context stays
+authoritative. Mail observations contain class/action, timing, and attempt
+metadata, never recipients or rendered content; an attempt is not proof of inbox
+delivery. See [workflow observations](docs/sdk.md#jobs-and-mailer-workflows).
+
 See [installation and privacy](docs/sdk.md) and [compatibility](docs/compatibility.md).
 
+Connect Claude Code or Codex with `bin/rails generate rails_mind:agent --plan`.
+Choose an environment-variable API token or Rails encrypted credentials, then
+follow the [agent setup guide](docs/agents.md) from first connection to a reported
+PR and deployment confirmation. Requires rails_mind 0.2.0 or later.
+
 Tests:
 
 ```sh
@@ -56,4 +67,4 @@ bundle exec ruby script/package_smoke.rb
 ruby script_benchmark.rb
 ```
 
-Business/request/error events are unsampled, but delivery is best effort. Check `RailsMind.stats` for losses. The SDK does not guarantee durable business-event counts; use a transactional outbox when that is required.
+Automatic endpoint sampling is enabled by default. The hosted policy can reduce routine successful requests while preserving failed, slow, or repeated-query requests and all other signal kinds from sampling. Business/error events remain unsampled; bounded queues and delivery are still best effort. See [sampling and coverage](docs/sdk.md#automatic-endpoint-sampling) and inspect `RailsMind.stats`. Use a transactional outbox when durable business-event delivery is required.

data/docs/agents.md

@@ -0,0 +1,212 @@
+# Bring your agent aboard
+
+RailsMind watches your Rails app. Your coding agent works in the repository you
+already use. Connect them once, then move from a finding to a reviewed fix without
+copying evidence between windows.
+
+```text
+RailsMind spots a problem → your agent proposes a PR → you review and ship
+                                                     ↓
+                                  RailsMind watches the deployed fix
+```
+
+Available in rails_mind 0.2.0. The hosted service must support `report_fix` before
+agents can report PRs. Setup is deterministic: it makes no model calls, starts no
+investigation, and does not merge or deploy anything.
+
+## 1. Preview the agent link
+
+From your Rails application's checkout:
+
+```sh
+bin/rails generate rails_mind:agent --plan
+bin/rails generate rails_mind:agent
+```
+
+You'll see three stages:
+
+```text
+RailsMind · Agent link
+1 / 3 · Configure the connection (env)
+2 / 3 · Give your agent the flight plan
+3 / 3 · Awaiting your signal
+```
+
+The first command writes nothing. The second adds a Claude Code `.mcp.json` entry
+and a marked RailsMind section in `AGENTS.md`. When an existing `CLAUDE.md` needs
+an import, it adds one with the correct relative path. Codex configuration is
+printed for you to review and add; the installer never changes global settings.
+Other MCP servers and existing RailsMind entries are preserved, even with
+`--force`. A skipped entry means you may need the proposed manual change shown
+in the output. Review the diff before committing it.
+
+The installer uses `https://railsmind.com`; `RAILS_MIND_ENDPOINT` can select another
+hosted installation. It does not create a local MCP server.
+
+## 2. Choose where the API token lives
+
+Create a **read,write API token** under RailsMind **Settings → API tokens**. An
+owner or admin creates it; it acts with that person's current organization role.
+A read-only token can explore findings but cannot report fixes. Tokens can be
+revoked on the same page.
+
+`RAILS_MIND_KEY` is your environment's **telemetry ingestion key**. It cannot read
+findings or authenticate an agent. The agent uses a separate `rmt_…` API token.
+
+### Environment variable (default)
+
+Make `RAILSMIND_API_TOKEN` available to the process running your agent. Keep the
+real value in your local secret settings, outside version control. For Claude
+Code GUI/IDE sessions, its user settings support an `env` entry; a shell export
+alone may not reach an app opened from the desktop.
+
+The generated `.mcp.json` contains a variable reference, never the value. A
+project entry can take precedence over an existing user-level entry, so prepare
+the variable before enabling it.
+
+For local Codex CLI, IDE and desktop sessions, add the printed configuration to
+`~/.codex/config.toml` (or `$CODEX_HOME/config.toml`):
+
+```toml
+[mcp_servers.railsmind]
+url = "https://railsmind.com/mcp"
+bearer_token_env_var = "RAILSMIND_API_TOKEN"
+```
+
+This one entry can serve multiple repositories in the same RailsMind organization.
+
+### Rails encrypted credentials
+
+Prefer to keep this app's API token with its other Rails secrets?
+
+```sh
+bin/rails generate rails_mind:agent --auth=credentials --plan
+bin/rails generate rails_mind:agent --auth=credentials
+bin/rails credentials:edit --environment development
+```
+
+Add through the credentials editor:
+
+```yaml
+rails_mind:
+  api_token: rmt_your_token_here
+```
+
+The encrypted file can be committed. Its matching decryption key must remain
+local and ignored by Git. Anyone able to decrypt this credential set can use the
+saved token; choose personal environment-variable tokens when each developer
+needs separate attribution or revocation.
+
+Credentials mode generates `bin/rails_mind_mcp_headers`. Claude Code's
+`headersHelper` and Codex's `http_headers_helper` call it to obtain authentication
+headers at connection time. Ruby and the installed bundle must be available to
+the agent. No Rails application boot, database connection or telemetry collection
+is needed. Run this safe readiness check:
+
+```sh
+bin/rails_mind_mcp_headers --environment development --check
+```
+
+It reports readiness without printing the token, and does **not** test network
+access. Without `--check`, stdout contains secret-bearing headers intended only
+for the MCP client. Never paste that output into a chat or issue.
+
+By default the helper selects development credentials, falling back to the shared
+Rails credentials file with Rails' normal key-file selection. Choose another
+local credential environment with `--credentials-environment=NAME` on the
+generator. This is separate from the production environment you inspect in
+RailsMind. Initializer-defined custom credential paths are not discovered because
+the app is not booted; pass `--content-path PATH --key-path PATH` in both agents'
+helper commands if needed. Relative paths resolve against the application root.
+
+A nonblank `RAILSMIND_API_TOKEN` overrides credentials **when the helper receives
+it**. Claude project helpers may remove credential-named environment variables,
+including that token and `RAILS_MASTER_KEY`; use a local Rails key file in that
+setup. A bad key, missing token or invalid encrypted file produces an error with
+no secret values.
+
+For Codex credentials mode, add the printed absolute-path helper command to this
+trusted project's `.codex/config.toml`. Do not put one app's helper in a global
+entry used by unrelated apps. Update the path for a different checkout/worktree.
+Replace an existing bearer-token/static-header setting for that entry; existing
+OAuth authentication can also take precedence. The installer preserves existing
+configuration and shows the replacement to review when switching modes.
+
+## 3. Make contact
+
+Restart your agent, trust this checkout, and approve its RailsMind connection.
+Then ask:
+
+> List my RailsMind applications and show open findings for this repository.
+> Do not change code yet.
+
+Check that the agent selected the correct application and environment. Seeing
+those results confirms access; “configuration prepared” alone does not. If a
+parent `CLAUDE.md`, `AGENTS.override.md`, or managed policy hides this project's
+instructions, import the generated `AGENTS.md` in the effective instruction file.
+
+GitHub access is a separate link. Connect the RailsMind GitHub App on the app's
+**Setup** page to attach source to findings and verify PR deployment. The agent
+still uses its own repository/GitHub access to open a PR.
+
+## 4. Give it a finding
+
+> Investigate finding 123 for this application in production. Fetch its RailsMind
+> fix brief, reproduce the issue, test a narrow fix, and open a PR. Report the PR
+> to RailsMind with report_fix. Leave merging and deployment to me.
+
+The brief contains the evidence and definition of done. Captured application
+data is evidence, not instructions. The agent should explain its changes, tests,
+and whether its report succeeded. If it cannot safely reproduce the issue, it
+should tell you what's missing. If reporting fails, the PR remains useful: retry
+`report_fix` with the finding and PR links rather than marking the finding resolved.
+
+## 5. Watch the fix
+
+| What RailsMind shows | What it means |
+| --- | --- |
+| Fix proposed | The agent reported a PR; the finding stays open. |
+| Merged · awaiting release | GitHub says the PR merged; no containing release has been confirmed yet. |
+| Deployed · watching | Telemetry identifies a Git SHA release containing the merge commit. |
+| Resolved · fix observed | The configured quiet period passed after deployment without matching evidence. |
+| Recurred after fix | Matching evidence returned on the deployed/later observed release, or after deployment when a release ID was absent. |
+| PR closed without merging | Report a replacement PR to start another attempt. |
+
+Deployment checks require GitHub **Pull requests: read**, **Contents: read**, and
+Git SHA release metadata. RailsMind retries failed checks and displays the reason
+it cannot confirm deployment. Without confirmation the existing quiet-resolution
+rule can still close a finding as **quiet**, which is distinct from **fixed**.
+Quiet telemetry is not proof that every affected path ran; SDK delivery is best
+effort. Release-regression recurrence tracking is not included in this version.
+Reporting the same PR again updates the note without erasing progress. A different
+PR replaces the current attempt. RailsMind does not merge or deploy it.
+
+## When a link needs attention
+
+| Symptom | Next step |
+| --- | --- |
+| Server absent | Restart the agent; check project trust, config placement and organization MCP policy. |
+| Missing variable or 401 | Set the API token in the agent process, check revocation and restart. Check whether a project entry overrides an older working entry. |
+| Credential check fails | Confirm the selected file, matching local key and `rails_mind.api_token`. Use `--check`, never paste header output. |
+| Ruby/Bundler not found | Make the app's Ruby and installed bundle available in the agent runtime. |
+| Reads work, report is forbidden | Use read,write scope and a contributing organization role. |
+| report_fix is unknown | The hosted RailsMind deployment needs the agent-loop update. Keep the PR and report it after that update. |
+| PR reported but deployment pending | Check the finding's reason, GitHub permissions, merge state, and release SHA detection. |
+| Another checkout fails | Correct the helper's absolute path and provide that checkout's ignored key file. |
+
+## Supported surfaces and verification limits
+
+This integration targets local Claude Code and Codex CLI, IDE and desktop
+sessions using their documented HTTP MCP configurations. Helper configuration
+requires a client version that supports it; use environment-variable mode if it
+doesn't. Neither the local generator nor passing unit tests certifies a particular
+agent installation. Verify the read-only “Make contact” step in each setup.
+
+Hosted/cloud and remote executor sessions do not automatically inherit local
+config, Ruby, credentials or keys. Codex documents helpers only for local HTTP
+connections. Use the hosted surface's supported connector/authentication setup;
+do not upload a production Rails decryption key just to make an agent connection.
+
+References: [Claude Code MCP](https://code.claude.com/docs/en/mcp),
+[Codex MCP](https://learn.chatgpt.com/docs/extend/mcp), and
+[Rails credentials](https://guides.rubyonrails.org/security.html#custom-credentials).

data/docs/compatibility.md

@@ -38,9 +38,9 @@ node --test javascript/rails_mind.test.js
 bundle exec ruby script/package_smoke.rb
 ```
 
-CI runs Ruby 4.0.6 / Rails 8.1.3.1 on Linux, plus browser adapter contract tests
+CI runs Ruby 4.0.6 / the locked Rails 8.1.4 dependencies on Linux, plus browser adapter contract tests
 on Node 22. The package smoke check builds and installs a gem in a temporary directory, loads that copy,
-and runs the installer against its packaged templates and browser adapter.
+and runs the installer and native workflow tests against its packaged files.
 The sample app remains in the hosted application's repository with its own lockfile.
 
 ## 0.1.0 release verification
@@ -64,3 +64,49 @@ and Node 22:
 These checks cover the client package and its documented integrations locally.
 They do not certify other browsers, every allowed Ruby/Rails combination,
 production delivery guarantees, or a deployed customer application's setup.
+
+## 0.2.0 agent setup verification
+
+The agent generator and encrypted-credentials helper are tested with Ruby 4.0.7
+and Rails/Active Support 8.1.3.1. Tests cover preview/repeatability, preservation of
+existing MCP and instruction files, shared and environment-specific credentials,
+custom paths, safe diagnostics, environment-variable precedence, and packaged
+files. The helper loads Active Support without initializing the application.
+
+Client configuration uses the documented Claude Code `headersHelper` and Codex
+`http_headers_helper` interfaces. These tests do not certify every desktop, IDE,
+cloud or older client version; verify read access in your agent after setup. See
+[agent setup and limitations](agents.md#supported-surfaces-and-verification-limits).
+
+## 0.2.0 workflow observation verification
+
+The native context, ActiveJob, and Action Mailer tests run with Ruby 4.0.7,
+Rails/ActiveJob/ActionMailer 8.1.4, and Mail 2.9.1. They cover serialized jobs,
+retries/discards, enqueue aborts/errors, schedule-aware delay, context restoration,
+ordinary/forced mail, disabled transport, hidden/raised transport errors, callback
+aborts/failures, lazy rendering, repeated attempts, existing OpenTelemetry, and
+collector failures. Auxiliary mail sent inside callbacks does not inherit the
+forced ActionMailer attempt. Tests use an in-memory collector and test/failing
+transports; they do not send external email.
+
+Older gem-permitted Rails versions remain uncertified. Provider acceptance,
+recipient inbox delivery, direct backend jobs, direct provider HTTP sends, and
+durable workflow completeness are outside this contract. Validate the released
+SDK against your app's queue, callback ordering, and delivery adapter. The hosted
+service exposes bounded workflow metadata and leaves recipient delivery unknown.
+
+## 0.3.0 endpoint sampling verification
+
+The Ruby suite passes locally with Ruby 4.0.7 and the locked Rails 8.1.4
+libraries: 105 tests and 1,311 assertions, with no failures or skips. The three
+Node browser-adapter contract tests also pass. These are isolated SDK/library
+tests; they do not boot a Rails application or use a database. CI separately
+runs the packaged-gem installation smoke check on Ruby 4.0.6.
+
+Coverage includes protected signals, deterministic shared selection, endpoint
+rates, local opt-out, malformed/expired controls, monotonic expiry, queue loss,
+immutable reports and acknowledgments, quota-response retries, old-server
+fallback, idle zero-rate report refresh, streamed response bounds, batch byte
+limits, and real process fork resets. Fake transports verify the wire contract;
+deployed server policy behavior, cross-process traffic forecasts, and a
+customer app's production overhead require hosted/staging validation.

data/docs/sdk.md

@@ -3,13 +3,13 @@
 The gem is `rails_mind`, namespace `RailsMind`. Install the MIT-licensed client
 from RubyGems.org and commit the application lockfile to retain the selected
 version. The hosted RailsMind service is a separate, proprietary application.
-Version 0.1.0 is an early release with the [documented compatibility limits](compatibility.md).
+Version 0.3.0 is an early release with the [documented compatibility limits](compatibility.md).
 
 ## Install
 
 ```ruby
 # Customer Gemfile
-gem "rails_mind", "~> 0.1.0"
+gem "rails_mind", "~> 0.3.0"
 ```
 
 ```sh
@@ -131,7 +131,7 @@ RailsMind.capture_exception(error, handled: true)
 
 Context is fiber-local and restored around requests/jobs. `identify` replaces the three identity values, so call it with all available values; passing nil clears that value. Preserve Ahoy's visitor ID when a visitor logs in, and emit `$identify` through Ahoy authentication to connect later events. Account IDs represent the current tenant, never a guessed company from email. Logout/account switching must update identity; a new request starts clean. Historical anonymous events are not rewritten or merged across accounts by the SDK.
 
-ActiveJob serializes only the context identifier allowlist under `rails_mind_context`, then restores it while executing. Arguments are not inspected. This covers GoodJob through ActiveJob; direct Sidekiq jobs require a future explicit integration. Distributed trace propagation belongs to the existing OpenTelemetry library; choose ActiveJob `propagation_style: :child` for a linked trace tree when configuring a new provider.
+ActiveJob serializes only the context identifier allowlist under `rails_mind_context`, then restores it while executing. Arguments are not inspected. This covers GoodJob through ActiveJob; direct Sidekiq jobs require a future explicit integration. Without OpenTelemetry, RailsMind creates a trace ID at a request, job, or mailer boundary and carries it across serialized ActiveJob context. An active OpenTelemetry span remains authoritative. Native IDs correlate observations; they do not invent a distributed parent/child span tree. Cross-service propagation belongs to the existing OpenTelemetry library; choose ActiveJob `propagation_style: :child` for a linked trace tree when configuring a new provider.
 
 ## Ahoy
 
@@ -180,9 +180,124 @@ RailsMind::Integrations::OpenTelemetry.attach!
 
 Attachment adds one idempotent processor; it does not replace the global provider, sampler, propagator, instrumentation, or other exporters. Its exporter only sanitizes and enqueues locally; the shared worker performs network I/O. Span context is attached at start so identity survives later export. Known safe attributes are allowlisted. Raw span names, exception span events, HTTP bodies/headers, SQL statements, and bind values are not exported to RailsMind. Existing third-party exporters retain their own behavior and privacy settings. [OpenTelemetry exporters](https://opentelemetry.io/docs/languages/ruby/exporters/).
 
-Request durations/counts and error reports come independently from Rails notifications/error reporting, even when detailed traces are sampled out. Request measurements cover controller actions, not assets/health checks rejected before ActionController or streaming-body completion. Repeated-query evidence contains only normalized-query hashes and counts; it is a suspicion, not proof of an N+1. Hash normalization handles common literals, not every SQL grammar. Use Bullet/Prosopite or an explicit query-bound test in development to verify fixes. No production object scans are installed.
+Request measurements and error reports come independently from Rails notifications/error reporting, even when detailed traces are sampled out. Routine requests separately follow the automatic endpoint sampling policy described below. Request measurements cover controller actions, not assets/health checks rejected before ActionController or streaming-body completion. Repeated-query evidence contains only normalized-query hashes and counts; it is a suspicion, not proof of an N+1. Hash normalization handles common literals, not every SQL grammar. Use Bullet/Prosopite or an explicit query-bound test in development to verify fixes. No production object scans are installed.
+
+Full metrics/logs SDK integration is deferred. Hosted request aggregates describe retained events; sampling can bias their distributions. The SDK does not capture application logs.
+
+## Automatic endpoint sampling
+
+Version 0.3.0 enables automatic endpoint sampling by default. A compatible hosted
+service supplies environment-wide endpoint rates based on its allowance policy.
+The SDK applies them before queueing, reducing serialization, network, and retained
+event volume. Each process uses the same policy and deterministic event-ID hash;
+there are no independent per-process allowance grants. A server-side tightening
+uses the same selection rule, so the two samplers do not multiply probabilities.
+
+Only completed `request` events with status 200–399, a finite duration from zero
+to below 1,000 ms, and fewer than three repeated queries are eligible. Slow,
+failed, unknown-duration, and repeated-query requests remain unsampled, as do
+business events, errors, jobs, mailer observations, visits, flags, checks, and
+OpenTelemetry spans. This preserves their sampling priority, not guaranteed
+delivery: queue bounds, payload limits, outages, and the server's hard daily quota
+still apply. Existing OpenTelemetry samplers remain authoritative; this feature
+does not promise complete distributed traces.
+
+To turn off SDK request selection explicitly:
+
+```ruby
+RailsMind.configure do |config|
+  config.automatic_sampling = false
+end
+```
+
+The SDK communicates this choice on policy and ingestion requests. The
+environment owner's hosted setting separately controls server-side sampling;
+local opt-out does **not** disable it or bypass the daily quota.
+
+The background worker requests `/api/v1/sampling_policy` with the ingest key and
+refreshes at most once per minute after its first request observation, including
+when the current rate is zero. It also receives controls on successful ingestion
+and quota responses. Missing, malformed, or expired policies fall back to rate 1;
+this may exhaust the server allowance during an outage. Expiry uses wall and
+monotonic clocks, with a maximum accepted lifetime of ten minutes. Before a valid
+v1 handshake, old servers and custom transports receive ordinary event-only
+batches and retain normal flush behavior. Forked workers reset queues, policies,
+counters, and report IDs and fetch their own copy of the shared policy.
+
+Retained request properties include SDK-owned `rails_mind_sampling` metadata:
+`version`, `policy_id`, effective `rate`, and `state` (`active`, `unavailable`,
+`expired`, `disabled`, or `protected`). This is the SDK selection decision, not
+proof of server acceptance or a complete traffic denominator.
+
+At most once per minute per process, the worker freezes an identified report of
+routine eligible observations; an explicit flush may send it sooner. Reports
+contain controller/action names and counts only: `observed`, `retained` (selected
+for enqueue), `sampled_out`, and `queue_dropped` (a subset of retained). They never
+contain event properties or user/account identifiers. Counts are observed after
+validation, redaction, and `before_send`; hooks that suppress events, crashes,
+protected requests, and unknown endpoint names are outside this denominator.
+Retained counts are not accepted counts. The resulting request percentiles and
+rates cannot be treated as an unbiased whole-traffic distribution.
+
+Reports have immutable UUIDs/bodies and separate durable acknowledgments. They
+can travel in `events: []` batches without consuming event quota, and an
+acknowledged report does not establish delivery of its accompanying events.
+Counters cover at most 100 endpoint names per window, reports share the normal
+batch byte limit, and each process retains at most five unacknowledged reports.
+Overflows or invalid clock windows mark coverage `limited`; reports older than
+seven days are discarded. This is bounded in-memory observation, not a durable
+request ledger. Unacknowledged reports after a confirmed handshake can cause
+`RailsMind.flush` to return false at its deadline.
+
+## Jobs and mailer workflows
+
+With `apm` enabled, the SDK automatically observes installed ActiveJob and Action
+Mailer components. No SMTP-provider integration or OpenTelemetry setup is required.
+It does not change the queue adapter, delivery provider, retry policy, or error
+handling. Both integrations respect `RailsMind.suppress` and the normal collector
+bounds. Request, job, and mailer identity/release context uses the existing core
+fields; job arguments and email contents are never inspected for correlation.
+
+The versioned property contract is `schema_version: 1` with `instrumentation`
+equal to `active_job` or `action_mailer`:
+
+| Component | Observations | Selected metadata |
+| --- | --- | --- |
+| ActiveJob | `enqueue`, `enqueue_at`, `perform_start`, `perform`, `enqueue_retry`, `retry_stopped`, `discard` | Class, queue, execution count, enqueue/schedule timestamps, queue delays |
+| Action Mailer | `process`, `delivery_attempt_completed`, `delivery_not_observed` | Mailer/action, opaque attempt UUID when available, transport class, ordinary/forced invocation, delivery flags, exposed exception class |
+
+New enqueue/start and mailer observations use `span`, so they do not inflate
+business-event counts or the existing `job` execution/retry/discard feed. A
+render-only mailer has a processing observation, not a delivery attempt. The
+attempt UUID groups processing with its delivery invocation; retries create new
+attempt UUIDs while the serialized job retains its correlation identifiers.
+
+`queue_delay_ms` measures enqueue to execution start, including intentional
+scheduling. `eligible_queue_delay_ms` subtracts intentional scheduling when the
+required timestamps are available, with a zero floor. Missing timestamps remain
+unknown. Retry handlers keep execution context after normal perform callbacks
+unwind. These notifications are best-effort observations, not a durable queue
+ledger: bulk/direct backend APIs may bypass them, and a missing completion does
+not by itself prove a stuck job.
+
+Mailer status describes local evidence. `observed` means the local call or
+notification completed; `disabled` identifies ordinary delivery with
+`perform_deliveries: false`; `error` requires an exposed exception. A callback
+abort or other invocation that never reaches the transport is recorded as
+`delivery_not_observed`, with `aborted`, `error`, or `unknown` as appropriate.
+Forced delivery bypasses normal delivery flags and is observed separately.
+Hidden transport failures (`raise_delivery_errors: false`) can still produce an
+`observed` result. None of these establishes provider acceptance or inbox
+arrival; recipient delivery remains unknown.
+
+The SDK excludes recipients, sender addresses, subjects, bodies, attachments,
+message IDs/headers, mailer/job arguments, credentials, and provider responses.
+Only transport class names are selected, never transport settings. Rendering a
+mailer and sending its content through a separate HTTP provider client produces
+only the rendering evidence; add explicit reviewed app events or provider
+callbacks if later delivery facts are needed. Keep real product outcomes such
+as invitation acceptance separate, using explicit events after persistence.
 
-Jobs record duration, failure/retry/discard lifecycle, execution count, queue name, and enqueue-to-start delay where ActiveJob exposes it. Scheduled delay is included in the enqueue-to-start number. Signals do not include arguments. Full metrics/logs SDK integration is deferred; v0.1 computes hosted aggregates from unsampled request events and does not capture application logs.
 
 ## Flipper and browser behavior
 
@@ -200,16 +315,18 @@ Add `<meta name="rails-mind-page" content="Invoices#index">` to supply a stable
 
 ## Bounds, privacy, and outages
 
-Defaults are one lazy worker per process, 1,000 queued/in-flight events, 16 KiB per event, at most 100 events and 256 KiB per batch, and a two-second flush interval. Overflow drops the newest event. Retries retain the same encoded bytes/UUIDs; only HTTP 429, 5xx, and transient transport failures retry, at most three retries with bounded backoff. Other 4xx responses drop the batch. Redirects are not followed. Shutdown gets two seconds by default, then discards outstanding telemetry; forks start a fresh child queue rather than resending the parent's buffer.
+Defaults are one lazy worker per process, 1,000 queued/in-flight events, 16 KiB per event, at most 100 events and 256 KiB per batch, and a two-second flush interval. Overflow drops the newest event. Retries retain the same encoded bytes/UUIDs; only HTTP 429, 5xx, and transient transport failures retry, at most three retries with bounded backoff. Other 4xx responses end delivery attempts. A failed response can follow partial server acceptance, so such events are classified as delivery unconfirmed. Redirects are not followed. Shutdown gets two seconds by default, then discards outstanding telemetry; forks start a fresh child queue rather than resending the parent's buffer.
 
 ```ruby
 RailsMind.stats
-# => { enqueued:, delivered:, dropped:, retried:, queued:, in_flight:,
-#      losses: { "event.overflow" => 3, "error.delivery" => 1 } }
+# => { enqueued:, delivered:, dropped:, delivery_unconfirmed:, retried:, queued:, in_flight:,
+#      losses: { "event.overflow" => 3, "error.delivery_unconfirmed" => 1 },
+#      sampling: { observed:, retained:, sampled_out:, queue_dropped:,
+#                  unreported:, reports_lost:, pending_reports:, limited:, policy_state:, policy_id: } }
 RailsMind.flush(timeout: 2)
 ```
 
-These are per-process counters. The doctor prints them for its process; inspect running app stats through your existing operational tooling. The hosted app does not currently receive loss counters. Request/business/error signals are unsampled, but process crashes, rejected payloads, redaction hooks, exhausted retries, or queue pressure can still undercount. This is best-effort monitoring, not an accounting ledger. A future transactional outbox can provide durable business-event delivery; the current implementation does not claim that guarantee.
+These are per-process counters. `dropped` counts known local discards, such as queue overflow or oversize payloads. `delivery_unconfirmed` counts events whose delivery attempts ended without a success response, including interrupted in-flight batches; some may have been accepted by the server. `delivered` counts submitted events in batches with a successful HTTP response; it does not prove server retention or background processing. The doctor prints stats for its process; inspect running app stats through your existing operational tooling. Only the routine-request report above sends queue-loss observations to the hosted app. All signal kinds can still undercount after crashes, rejected payloads, hooks, or outages. This is best-effort monitoring, not an accounting ledger; use a transactional outbox when durable business-event delivery is required.
 
 Redaction occurs before buffering and again after custom `before_send`. Sensitive property names are filtered, nesting/string/collection sizes are capped, emails and common credential forms are scrubbed, exception messages are omitted by default, and backtraces drop machine-home prefixes. Bodies, cookies, credentials, SQL binds, and job arguments are never selected by integrations. Arbitrary user-provided text may contain sensitive content that generic redaction cannot recognize: use small, explicitly reviewed business properties. Opting into exception messages requires reviewing `capture_exception_message` and your custom scrubbing policy.
 
@@ -223,3 +340,10 @@ This historical check used an internal sample application that is not included
 in the public client repository. To verify your own installation, follow
 [Verify the connection](#verify-the-connection). External hosted deployment and
 published-gem installation remain unverified by that historical check.
+
+## Connect your coding agent
+
+Run `bin/rails generate rails_mind:agent --plan` to preview the connection setup.
+The [agent guide](agents.md) covers Claude Code and Codex, environment-variable and
+Rails credentials authentication, safe verification, and the complete fix journey.
+The agent API token is separate from `RAILS_MIND_KEY`, the ingestion key above.