coolhand 0.8.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 256c9237619b3f7116aa9751f78f0d0e367381b12afa694742da07ed1d7d3123
-  data.tar.gz: 149ddf8c4cd1800b105382ade5d2a2e9e57a360884e34e1b988b926739e90f30
+  metadata.gz: 301fa9e603334f3c6b5349755239cdf06418b9b78f1fae3de44abc352b8f1828
+  data.tar.gz: 0b687769a058ff206f50deaf46ad1e28909e7f4e4229d217ad5b36b7350ff9ce
 SHA512:
-  metadata.gz: 2ccbf54c2787a8df93178120583d83666553454a1b86385ec1c4ea10e228b859b995a35bed1450e9ab6d38dbb5d145d9b7a269be89f5562870d51a63630e5653
-  data.tar.gz: 4e6db88c4530737370030809a9d8e094d791761a6306a63701edc4413ed81f61a716d975953799c3d46b0cebbb3ddd9e1d172b22ee5d7b29c18bdd65ffe9e25c
+  metadata.gz: 9a4653638e2362853b90baf55bc1df97f73ee1144357524c61be21798b58fcffe383d9bbde1b9cb33ac7c9d07064377eff681667be8ed2a341103cdb06ab42ff
+  data.tar.gz: 464a1d38d383ebf98f3f42b9f60fccfe65d13fcc3a1ea45d5df0c7fc1f26aad721a9b2650f1c41277a09dbf5a92a24f32f2223f961c9940de592fecf54d1057d

data/CHANGELOG.md

@@ -7,6 +7,34 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.10.0] - 2026-10-21
+
+### Added
+- **Read the Coolhand help center** ([#164](https://github.com/Coolhand-Labs/coolhand-ruby/pull/164)) — `Coolhand.public_content_service` wraps the read-only help center endpoints: `search_help_articles(query:, category:, page:, per_page:)` returns a `Coolhand::HelpArticleSearchResult` (`articles`, `pagination`), `get_help_article(slug)` returns one article with its markdown `body` and `toc`, and `list_help_categories` lists the sections. Unlike every other read service it needs **no API key**: with none configured no `X-API-Key` header is sent (anonymous callers are limited to 30 requests per minute per IP), and a configured `config.api_key` is sent and lifts the limit. Like the other read methods, these raise `Coolhand::Error` / `Coolhand::HttpError` rather than logging and returning `nil`. See [Reading the Help Center](docs/help-center.md).
+
+### Security
+- `LoggerService#forward_webhook` now redacts credentials (userinfo and sensitive query parameters such as `token=`) in a caller-supplied `url:` before logging it, the same way intercepted request URLs are. **Migration note:** if you pass a `url:` containing such values, they now appear as `[REDACTED]` in Coolhand.
+
+## [0.9.0] - 2026-10-18
+
+### Added
+- **Declare the workload and template of captured LLM calls** ([#153](https://github.com/Coolhand-Labs/coolhand-ruby/pull/153)) — `Coolhand.with_context(reporter:, workload:, template:) { ... }` stamps every LLM call captured inside the block with the workload and template it belongs to, sent as `llm_request_log.declared`. The context is snapshotted on the calling thread, so it survives `async_logging`. Nested blocks override per field (innermost wins). `Coolhand::Declarable` (`coolhand_workload`, `coolhand_declare`, `coolhand_declare_all`) declares it once on a class, inherited by subclasses, and opt-in `config.auto_declare = [:active_job, :controller]` does the same for Rails jobs and controller actions (the gem still has no Rails dependency). `Coolhand.workload_service.upsert` and `Coolhand.template_service.upsert` create or update records by key with your **private** API key and raise `Coolhand::HttpError` on failure, and `warnings` returned with a logged request (e.g. the public-key cap) are now logged. Keys longer than 255 characters, with surrounding whitespace or a leading, trailing or doubled `/`, and a template `key` with no workload raise `ArgumentError` up front, because the server would reject and drop the whole log. Older servers ignore `declared`. See [Declared Workloads](docs/declared_workloads.md).
+- `bin/live-examples` (also `bundle exec rake examples:live`) runs every `examples/*.rb` against real provider keys and prints one `PASS` / `SKIP` / `FAIL` line per script ([#155](https://github.com/Coolhand-Labs/coolhand-ruby/pull/155)). Development tooling only: `bin/` and `examples/` are not packaged in the gem. See [Examples](examples/README.md).
+
+### Changed
+- The `🔗 Net::HTTP interceptor patched` log line is no longer printed when the interceptor is installed ([#154](https://github.com/Coolhand-Labs/coolhand-ruby/pull/154)). **Migration note:** anything that matched on that line in log output should stop doing so; use `Coolhand::NetHttpInterceptor.patched?` instead.
+- Internal de-duplication with no behavior change ([#156](https://github.com/Coolhand-Labs/coolhand-ruby/pull/156)): list reads share `ReadQuery#fetch_list`, `LoggerService` shares one webhook-rejection path, `OpenAi::WebhookValidator` shares one enforce-or-allow path (same error messages and same strict/lenient behavior by `Rails.env`), and `Coolhand.with_capture` / `without_capture` share one override helper. `contract/` (declared, intentional duplication) is excluded from the gem package.
+- CI: added the `exhale` duplication and complexity gate ([#156](https://github.com/Coolhand-Labs/coolhand-ruby/pull/156)), and bumped `ruby/setup-ruby` to 1.329.0 ([#150](https://github.com/Coolhand-Labs/coolhand-ruby/pull/150)) and `actions/upload-artifact` to 7.0.2 ([#151](https://github.com/Coolhand-Labs/coolhand-ruby/pull/151)).
+
+### Fixed
+- `OpenAi::WebhookValidator` now accepts a `webhook-signature` header carrying several space-separated signatures (`v1,sigA v1,sigB`) and passes if any `v1,` entry matches ([#161](https://github.com/Coolhand-Labs/coolhand-ruby/pull/161)). Previously the whole remainder after `v1,` was compared as one value, so a legitimate webhook sent during secret rotation was rejected with a 401. Every candidate is compared in constant time, non-`v1` entries are ignored, a header that is not valid UTF-8 is rejected rather than raising, and the timestamp and replay-id checks still run only after a match. Single-signature headers behave as before. See [OpenAI Batch Webhook Handler](docs/openai.md#signature-header-and-secret-rotation).
+
+### Security
+- Warnings returned in a Coolhand log response are now sanitized before they are printed ([#162](https://github.com/Coolhand-Labs/coolhand-ruby/pull/162)): entries are coerced with `to_s`, invalid UTF-8 is scrubbed, control characters and line separators become a space, invisible Unicode format characters are removed, entries over 500 characters are truncated, and at most 5 are printed per response. Well-formed warnings print as before.
+
+### Documentation
+- `docs/declared_workloads.md` and the README now state that `Coolhand.with_context`, `with_capture` and `without_capture` are fiber-local, so work started in a new Fiber or Async task inside the block is not covered, and show opening the block inside the Fiber instead ([#160](https://github.com/Coolhand-Labs/coolhand-ruby/pull/160)).
+
 ## [0.8.0] - 2026-10-09
 
 ### Added

data/README.md

@@ -118,6 +118,24 @@ Coolhand.log_service.search_logs(order: 'cost_desc', min_cost: 1.0, per: 10, **w
 
 See [Reading Workloads →](docs/workload-search.md) and [Reading Logs →](docs/log-search.md).
 
+## Reading the Help Center
+
+`Coolhand.public_content_service` reads the Coolhand help center (the same pages as coolhandlabs.com/help and /updates) with **no API key required**:
+
+```ruby
+require 'coolhand'
+
+help_center = Coolhand.public_content_service
+
+result = help_center.search_help_articles(query: 'match rate', per_page: 5)
+article = help_center.get_help_article(result.articles.first[:slug]) # full markdown :body
+categories = help_center.list_help_categories
+```
+
+Anonymous callers are limited to 30 requests per minute per IP. If `config.api_key` is set it is sent and lifts the limit; a key the server rejects raises a 401 `Coolhand::HttpError`. These are read methods, so they **raise** where the write methods log and return `nil`.
+
+See [Reading the Help Center →](docs/help-center.md) for parameters, the category filter and errors.
+
 ## Linking Feedback to an Optimization
 
 Attach feedback to an optimization as evidence, one at a time or in bulk. These require your **private** API key and **raise** `Coolhand::Error` on failure (`Coolhand::HttpError` for non-2xx responses).
@@ -132,6 +150,29 @@ links.unlink_feedback('optimizationHashid', link[:id])
 
 For batching, error semantics, and details, see [Linking Feedback →](docs/feedback-links.md).
 
+## Declaring Workloads and Templates
+
+Tell Coolhand which workload and template an LLM call belongs to, instead of waiting for it to be matched. Calls captured inside the block carry the declared identity:
+
+```ruby
+Coolhand.with_context(reporter: 'my-app', workload: { key: 'Parser#call' }, template: { key: 'Parser#call/summarize' }) do
+  client.chat(...) # captured as usual
+end
+
+Coolhand.workload_service.upsert(key: 'Parser#call', name: 'Parser') # private key; create or rename
+```
+
+Or declare it once on the class and let every capture inside it pick it up, subclasses included:
+
+```ruby
+class ApplicationService
+  include Coolhand::Declarable
+  coolhand_declare_all # each public method declares "ClassName#method"
+end
+```
+
+For nesting rules, class-level declarations, Rails jobs and controllers, upserts, and public-key limits, see [Declared Workloads →](docs/declared_workloads.md).
+
 ## Rails Integration
 
 ### Configuration
@@ -212,6 +253,7 @@ end
 | `exclude_api_patterns` | Array | `["/batchPredictionJobs/"]` | Deny-list checked after `intercept_addresses`; matching paths are skipped. Unlike `intercept_addresses`, `exclude_api_patterns = []` genuinely disables exclusion. See [Configuration](docs/configuration.md) |
 | `max_captured_body_bytes` | Integer | `1_000_000` | Maximum size of a captured JSON request body — oversized bodies are replaced with a placeholder. Non-JSON bodies (e.g. file/audio uploads) are always skipped regardless of size — see [Advanced Configuration](docs/configuration.md) |
 | `async_logging` | Boolean | `true` | Send logs to Coolhand from a background thread so a slow Coolhand API never delays your LLM calls. Set to `false` to send inline — see [Advanced Configuration](docs/configuration.md#asynchronous-logging) |
+| `auto_declare` | Array | `[]` | Rails only: `:active_job` and/or `:controller` to declare a workload and template for LLM calls made from jobs and controller actions — see [Declared Workloads](docs/declared_workloads.md#rails-auto-declare) |
 
 ## Usage Examples
 
@@ -273,7 +315,7 @@ Coolhand.without_capture do
 end
 ```
 
-Both methods are thread-safe. Blocks nest correctly — the innermost block takes precedence, and the outer setting is restored when the block exits.
+Both methods are thread-safe. Blocks nest correctly — the innermost block takes precedence, and the outer setting is restored when the block exits. The override is fiber-local, so it does not follow into new Threads, Fibers or Async tasks started inside the block; see [Threads and background logging](docs/declared_workloads.md#threads-and-background-logging).
 
 ## Logging Inbound Webhooks
 
@@ -464,7 +506,7 @@ The monitor handles errors gracefully:
 - Failed API logging attempts are logged to console but don't interrupt your application
 - Invalid API keys will be reported but won't crash your app
 - Network issues are handled with appropriate error messages
-- The read methods (`search_templates`, `get_template`, `search_workloads`, `search_logs`, `get_log`) and the feedback-link methods are the exception — they raise `Coolhand::Error` (`Coolhand::HttpError` for non-2xx responses); see [Reading Templates →](docs/template-search.md), [Reading Workloads →](docs/workload-search.md), [Reading Logs →](docs/log-search.md) and [Linking Feedback →](docs/feedback-links.md)
+- The read methods (`search_templates`, `get_template`, `search_workloads`, `search_logs`, `get_log`, `search_help_articles`, `get_help_article`, `list_help_categories`), the feedback-link methods and the `upsert` methods are the exception — they raise `Coolhand::Error` (`Coolhand::HttpError` for non-2xx responses); see [Reading Templates →](docs/template-search.md), [Reading Workloads →](docs/workload-search.md), [Reading Logs →](docs/log-search.md), [Linking Feedback →](docs/feedback-links.md) and [Declared Workloads →](docs/declared_workloads.md)
 
 ## Documentation
 
@@ -473,7 +515,9 @@ The monitor handles errors gracefully:
 - **[Reading Templates](docs/template-search.md)** — Search LLM request templates and fetch a single one, prompt patterns included, using the private API key
 - **[Reading Workloads](docs/workload-search.md)** — List workloads with optional cost and performance metrics over a rolling or explicit time window
 - **[Reading Logs](docs/log-search.md)** — Search logs with per-log cost, filter and sort by cost, and fetch one log with its cost breakdown
+- **[Reading the Help Center](docs/help-center.md)** — Search and read Coolhand's help center articles and list its sections, with no API key required
 - **[Linking Feedback](docs/feedback-links.md)** — Link feedback to an optimization as evidence, singly or in bulk, using the private API key
+- **[Declared Workloads](docs/declared_workloads.md)** — Declare the workload and template of captured LLM calls with `Coolhand.with_context`, and create or rename them with `upsert`
 - **[Anthropic Integration](docs/anthropic.md)** — Official and community Anthropic Ruby gems, streaming, dual gem handling, and troubleshooting
 - **[ElevenLabs Integration](docs/elevenlabs.md)** — Webhook capture, feedback submission, and Rails integration
 - **[OpenAI Batch Webhook Handler](docs/openai.md)** — Handle OpenAI batch job completion events via webhook interception

data/Rakefile

@@ -9,4 +9,11 @@ require "rubocop/rake_task"
 
 RuboCop::RakeTask.new
 
+namespace :examples do
+  desc "Run every live script in examples/ against real provider keys (loads keys via zsh -ic)"
+  task :live do
+    sh RbConfig.ruby, File.expand_path("bin/live-examples", __dir__)
+  end
+end
+
 task default: %i[spec rubocop]

data/docs/declared_workloads.md

@@ -0,0 +1,156 @@
+# Declaring workloads and templates
+
+By default Coolhand works out which workload and template an LLM call belongs to by matching the log against known templates. If your code already knows (a service object, a prompt library, an adapter), declare it instead. A declared log skips matching entirely and is filed under the workload and template you named.
+
+There are two parts:
+
+- `Coolhand.with_context` stamps the LLM calls the gem captures automatically.
+- `Coolhand.workload_service.upsert` and `Coolhand.template_service.upsert` create or update workloads and templates explicitly. They need your **private** API key.
+
+## Declaring on captured calls
+
+```ruby
+Coolhand.with_context(
+  reporter: "squishling",
+  workload: { key: "Parser#call", name: "Parser#call", description: "Parses incoming tickets" },
+  template: { key: "Parser#call/squish:L2", name: "Parser#call · squish L2" }
+) do
+  client.chat(...) # captured as usual, and sent with the declared identity
+end
+```
+
+| Field | Accepts | Notes |
+|---|---|---|
+| `reporter` | String | Who is making the declaration, e.g. the library or app. Used when a record is first created. |
+| `workload` | Hash: `id`, `key`, `name`, `description` | Needs an `id` or a `key`. Other keys are ignored. |
+| `template` | Hash: `id`, `key`, `name` | Needs an `id` or a `key`. Other keys are ignored. |
+
+- `id` refers to an existing record. `key` is a stable string of your choosing; Coolhand finds or creates the record with that key. On a template, `id` wins over `key`.
+- `name`, `description` and `reporter` are used only when a record is **first created**. Declaring never renames or re-attributes an existing record; use `upsert` for that. A display name that is already taken gets a numeric suffix, and names such as "Unmatched" are reserved.
+- A declaration with only a `workload` gets a default template keyed `<workload key>/default`. A template given by `key` needs a workload alongside it, either in the same block or an enclosing one.
+- Keys are at most 255 characters, printable, and cannot start or end with whitespace or `/` or contain `//`. `#`, `:` and `·` are fine. Descriptions are cut to 1000 characters.
+- Keys must be stable, so never put a request id or timestamp in one: each distinct key creates a record.
+- A `workload` or `template` that is not a Hash, has neither `id` nor `key`, has an invalid key, or a template `key` with no workload raises `ArgumentError` before your block runs. The server would answer these with a `422` and **not save the log**.
+- An unknown `id` (or one from another client) gets the same `422` and the log is not saved, so prefer `key`.
+
+### Nesting
+
+Blocks nest. Each field (`reporter`, `workload`, `template`) is taken from the innermost block that sets it, and fields an inner block leaves out are inherited (with the one exception below):
+
+```ruby
+Coolhand.with_context(reporter: "my-app", workload: { key: "Parser#call" }) do
+  Coolhand.with_context(template: { key: "Parser#call/summarize" }) do
+    # reporter: "my-app", workload: Parser#call, template: Parser#call/summarize
+  end
+end
+```
+
+A template belongs to a workload, so an inner block that declares a `workload` without a `template` does not inherit the outer block's template. Declare both together when you change workload.
+
+A `workload` or `template` Hash is replaced as a whole, not merged key by key. An inner `workload: { key: "b" }` inside an outer `workload: { id: "a" }` declares only `b`, rather than a mix of `id` and `key`.
+
+### Threads and background logging
+
+The context is thread-local, like `Coolhand.with_capture`. It is also fiber-local, so it does not carry into threads, fibers, `Enumerator#next` blocks or async tasks you start inside the block; calls made there are captured without a declaration. The identity is read on the thread that made the LLM call, before the log is queued, so it survives `async_logging` (the default).
+
+This matters for Fiber-scheduler concurrency such as [Async](https://github.com/socketry/async). Nothing raises: the call is logged, just without a workload or template.
+
+```ruby
+Coolhand.with_context(workload: { key: "Parser#call" }) do
+  Async do
+    client.chat(...) # runs in a new Fiber: captured with no declared workload
+  end
+end
+```
+
+`Coolhand.with_capture` and `Coolhand.without_capture` work the same way, so a `without_capture` block does not suppress calls made from a Fiber started inside it, and with `config.capture = false` a `with_capture` block does not enable them. To cover work that runs in another Fiber, open the block inside that Fiber:
+
+```ruby
+Async do
+  Coolhand.with_context(workload: { key: "Parser#call" }) do
+    client.chat(...) # captured with the declared workload
+  end
+end
+```
+
+### Public keys
+
+Declarations made with a public key are capped per client at 200 workloads and 1,000 templates. Past the cap, Coolhand ignores the declaration, ingests the log normally, and returns a warning, which the gem prints unless `config.silent` is on. Server-supplied warnings are sanitized before printing (control and invisible characters removed, each entry cut at 500 characters, at most 5 printed per response). Declarations from a private key are not capped.
+
+Older Coolhand servers ignore `declared`, so it is safe to use against them.
+
+## Declaring on a class
+
+Wrapping every call site in `with_context` does not suit passive capture. Include `Coolhand::Declarable` and declare the identity once, on the class. Wrapped methods run inside `with_context`, so everything above (nesting, precedence, async) applies unchanged.
+
+```ruby
+class ApplicationService
+  include Coolhand::Declarable
+
+  coolhand_workload reporter: "my-app"
+  coolhand_declare_all
+end
+
+class Parser < ApplicationService
+  def call(ticket) = client.chat(...) # workload "Parser#call", template "Parser#call"
+end
+
+class Summariser < ApplicationService
+  coolhand_workload key: "Summariser" # one workload for every method; templates stay per method
+
+  def call(ticket) = client.chat(...) # workload "Summariser", template "Summariser#call"
+end
+```
+
+- `coolhand_declare :call, :other` wraps just those methods, whether they are defined before or after the line. `template:` takes a key or a `{ key:, name: }` Hash instead of the default `"ClassName#method"`: `coolhand_declare :call, template: "Parser#call/summarise"`.
+- `coolhand_declare_all` wraps every public instance method defined after it, in the class and its subclasses, so put it at the top of the class body. Private and protected methods are left alone, however they are made private (`private def`, `private :name`, or a `private` section), as are attribute readers and writers and object-protocol methods such as `to_s`, `==` and `method_missing`. A method you name in `coolhand_declare` is wrapped regardless.
+- The key uses the **runtime** class, so a method inherited from `ApplicationService` declares as `Parser#call` when called on a `Parser`. Anonymous classes are not declared.
+- `coolhand_workload(key:, name:, description:, reporter:)` sets class-level defaults and is inherited by subclasses, field by field, with the nearest class winning. Without a `key`, each method gets its own workload, `ClassName#method`. `name` and `description` need a `key`, since one name shared by per-method workloads would collide.
+- Services that call each other nest: the innermost wrapped method wins, and it brings its own template (see [Nesting](#nesting)).
+- It only works where the LLM call runs on the same thread and fiber as the wrapped method (see [Threads and background logging](#threads-and-background-logging)).
+
+## Rails auto-declare
+
+For Rails apps, Coolhand can declare jobs and controller actions without touching their classes. It is off by default, because every distinct job and action becomes a workload.
+
+```ruby
+Coolhand.configure do |config|
+  config.api_key = ENV.fetch("COOLHAND_API_KEY")
+  config.auto_declare = [:active_job, :controller]
+end
+```
+
+| Target | Wraps | Declares |
+|---|---|---|
+| `:active_job` | `around_perform` on `ActiveJob::Base` | `SummariseJob#perform`, reporter `rails` |
+| `:controller` | `around_action` on `ActionController::Base` and `::API` | `UsersController#show`, reporter `rails` |
+
+Coolhand must be loaded after Rails (the default with `Bundler.require` in a Rails app), otherwise the hooks are never registered. They are installed after your initializers have run, so `Coolhand.configure` can come before or after anything else. Anything declared inside the job or action (a `Declarable` service, a `with_context` block) takes precedence over the job or action declaration. With a public API key the per-client declaration cap applies (see [Public keys](#public-keys)), so enable only the targets you want as workloads.
+
+## Creating and renaming explicitly
+
+```ruby
+Coolhand.configure { |config| config.api_key = ENV.fetch("COOLHAND_PRIVATE_API_KEY") }
+
+workload = Coolhand.workload_service.upsert(
+  key: "Parser#call", name: "Parser", description: "Parses incoming tickets", reporter: "my-app"
+)
+
+Coolhand.template_service.upsert(
+  key: "Parser#call/summarize",
+  workload: { key: "Parser#call" }, # or { id: workload[:id] }
+  name: "Parser · summarize",
+  reporter: "my-app"
+)
+```
+
+- Both are `PUT .../by_key/<key>`: they create the record if the key is new and update it otherwise. The server answers `201` on create and `200` on update; both return the record as a Hash.
+- The key never changes. Calling `upsert` with the same key and a new `name` renames the record, and an update changes only the fields you send.
+- A template needs a `workload` (`{ id: }` or `{ key: }`, sent to the server as `workload_id` / `workload_key`) when it is new. For an existing template, naming a different workload is a `422`.
+- A key may contain `/`, `#`, `:` and other characters; the gem escapes it for the URL.
+
+## Errors
+
+`upsert` raises, unlike the logging writes. A non-2xx response raises `Coolhand::HttpError` whose `status` is the HTTP code (`401` for a missing or public key, `422` for an invalid key, a taken name, a missing or unknown workload, or a key held by a deprecated template, `504` if the server timed out). A blank key, or one made of `.` / `..` path segments, and transport failures raise `Coolhand::Error`; a `workload` that is not a Hash raises `ArgumentError`.
+
+`config.debug_mode` does not suppress `upsert`: it changes server state, so it is always sent.

data/docs/help-center.md

@@ -0,0 +1,120 @@
+# Reading the Help Center
+
+`Coolhand::PublicContentService` reads Coolhand's help center: the articles served at
+`coolhandlabs.com/help/:slug` and the posts at `/updates/:slug`. "Help center" is the user-facing name;
+on the wire the resource is `public_content` (`GET /api/v2/public_content`, `/:slug` and `/categories`).
+It is read-only. Creating, updating and archiving articles is Coolhand-internal and not wrapped.
+
+**Auth:** none required. Unlike every other service, no API key is needed:
+
+```ruby
+require "coolhand"
+
+help_center = Coolhand.public_content_service # works with Coolhand.configure never called
+```
+
+- No key configured: no `X-API-Key` header is sent, and the calls work. Anonymous callers are limited to
+  **30 requests per minute per IP**; beyond that the server answers `429`.
+- A configured `config.api_key` is sent as `X-API-Key` and callers with a valid key are not rate limited.
+  This gem reads the key from configuration only, not from the environment.
+- A key the server does not recognise is a `401` (`{"error":"Invalid API key."}`) even though the endpoint is
+  public. It is raised, not retried anonymously.
+
+## `search_help_articles`
+
+```ruby
+result = help_center.search_help_articles(query: "match rate", category: "feedback-and-prompts", per_page: 10)
+
+result.articles.each { |a| puts "#{a[:title]}: #{a[:search_headline]}" }
+result.pagination.total_count
+```
+
+### Keywords
+
+All optional.
+
+| keyword | type | notes |
+|---|---|---|
+| `query` | String | Relevance search (Postgres full text, the same as the website's). Supports quoted phrases, `-exclusions` and `or`. Omit for a full listing. A blank string counts as omitted. |
+| `category` | String | Restrict to one section by slug (see `list_help_categories`). A blank string counts as omitted. |
+| `page` | Integer | 1-based. |
+| `per_page` | Integer | Default 25, max 100, both enforced server-side. |
+
+The endpoint has no `category` parameter. `category` is sent in its structured form instead, which also
+moves the relevance search to a different key; the plain `q=...` string and the `q[...]` form cannot be
+mixed:
+
+| `query` | `category` | Sent |
+|---|---|---|
+| set | unset | `q=<query>` |
+| unset | set | `q[help_category_slug_eq]=<category>` |
+| set | set | `q[help_category_slug_eq]=<category>&q[full_text]=<query>` |
+
+### Return value
+
+A `Coolhand::HelpArticleSearchResult` with `articles` (an Array of Symbol-keyed Hashes) and `pagination`.
+Each article is a summary; the markdown `:body` is omitted from lists:
+
+```ruby
+{
+  slug: "what-is-feedback-match-rate",
+  title: "What is feedback match rate?",
+  answer: "Match rate is the share of ...",       # String or nil
+  article_kind: "concept",   # reference | concept | how_to | troubleshooting | faq_answer | release_note
+  tags: ["feedback", "matching"],
+  category: "feedback-and-prompts",               # section slug
+  url: "https://coolhandlabs.com/help/what-is-feedback-match-rate",
+  markdown_url: "https://coolhandlabs.com/help/what-is-feedback-match-rate.md",
+  reading_time_minutes: 10,                       # Integer or nil
+  search_headline: "<mark>Match</mark> rate ...", # nil on a plain listing
+  published_at: "2026-08-30T13:57:52Z",           # String or nil
+  updated_content_at: "2026-08-30T13:57:52Z"      # String or nil
+}
+```
+
+`:search_headline` is the matching passage with `<mark>` tags around the matched terms, so you can see
+why something matched without fetching the body.
+
+`pagination` is a `Coolhand::Pagination`, the same as the other read methods, built from the `X-Page`,
+`X-Per-Page`, `X-Total-Count` and `X-Total-Pages` response headers (`current_page`, `per_page`,
+`total_count`, `total_pages`, `has_next_page`, `has_prev_page`).
+
+## `get_help_article(slug)`
+
+```ruby
+article = help_center.get_help_article("what-is-feedback-match-rate")
+article[:body] # full markdown
+article[:toc]  # [{ id:, text:, level:, children: }]
+```
+
+Returns a Hash: the summary fields minus `:search_headline`, plus `:body` (full markdown), `:noindex`
+(Boolean) and `:toc` (the heading structure, h3s nested under their h2). The slug is escaped as a single
+path segment. Raises `Coolhand::Error` before any request if `slug` is blank or a bare `.`/`..`. An unknown
+or unpublished slug raises `Coolhand::HttpError` with `status` 404.
+
+## `list_help_categories`
+
+```ruby
+help_center.list_help_categories
+# [{ slug: "providers", name: "Provider guides", description: "...", url_prefix: "/help", allowed_tags: nil }, ...]
+```
+
+Returns an Array of Hashes: `:slug` (the `category` filter above), `:name`, `:description`, `:url_prefix`
+(`/help` or `/updates`) and `:allowed_tags` (the only tags the section accepts; `nil` means any tag).
+
+## Errors
+
+These are read methods, so they raise where the logging writes log and return `nil`. A network failure or
+a non-JSON body raises `Coolhand::Error`. A non-2xx response raises `Coolhand::HttpError`, whose `status`
+holds the HTTP status code and `body` the (truncated) response body: `401` for an invalid key, `404` for an
+unknown slug, `429` when the anonymous rate limit is exceeded.
+
+## Verifying against a live server
+
+`spec/live/coolhand_public_content_live_spec.rb` runs against a real server with no key:
+
+```bash
+COOLHAND_SPEC_LIVE_BASE_URL=http://127.0.0.1:3000/api bundle exec rspec spec/live/coolhand_public_content_live_spec.rb
+```
+
+It makes about nine anonymous requests, so running it repeatedly within a minute can hit the `429`.

data/docs/openai.md

@@ -59,6 +59,10 @@ end
 # ...existing code...
 ```
 
+## Signature header and secret rotation
+
+The `webhook-signature` header may carry several space-separated signatures (`v1,sigA v1,sigB`), as senders produce while a webhook secret is being rotated. `Coolhand::OpenAi::WebhookValidator` accepts the request if any `v1,` entry matches your secret, comparing each in constant time and ignoring entries with any other version prefix. The timestamp and replay checks below still run, and only after a signature matches.
+
 ## Replay protection
 
 `Coolhand::OpenAi::WebhookValidator` rejects requests whose `webhook-timestamp` is more than **300 seconds** away from the current time, and rejects a `webhook-id` it has already seen within that window — this prevents a captured request (from a log aggregator, APM trace, or proxy log) from being replayed to re-trigger `Coolhand::OpenAi::BatchResultProcessor`.

data/lib/coolhand/api_service.rb

@@ -6,12 +6,14 @@ require "json"
 require_relative "collector"
 require_relative "errors"
 require_relative "read_requests"
+require_relative "response_warnings"
 
 module Coolhand
   class ApiService
     # The GET half of this class. See Coolhand::ReadRequests for why reads raise where writes
     # log and return nil.
     include ReadRequests
+    include ResponseWarnings
 
     # Caps how much of a failed response body is interpolated into a log line or an exception
     # message. Without it an oversized body from a proxy or gateway becomes the message.
@@ -36,7 +38,9 @@ module Coolhand
         log JSON.pretty_generate(sanitize_payload_for_json(payload))
         nil
       else
-        send_request(payload, "✅ Successfully sent request metadata")
+        result = send_request(payload, "✅ Successfully sent request metadata")
+        log_response_warnings(result)
+        result
       end
     end
 

data/lib/coolhand/base_interceptor.rb

@@ -149,7 +149,8 @@ module Coolhand
     end
 
     def send_complete_request_log(request_id:, method:, url:, request_headers:, request_body:, response_headers:,
-      response_body:, status_code:, start_time:, end_time:, duration_ms:, is_streaming:, source_api: nil, model: nil)
+      response_body:, status_code:, start_time:, end_time:, duration_ms:, is_streaming:, source_api: nil, model: nil,
+      declared: nil)
       raw_request = {
         id: request_id,
         timestamp: start_time.iso8601,
@@ -168,6 +169,7 @@ module Coolhand
       raw_request[:model] = model if Coolhand.required_field?(model)
 
       request_data = { raw_request: raw_request }
+      request_data[:declared] = declared if declared && !declared.empty?
 
       LogQueue.submit do
         Coolhand::ApiService.new.send_llm_request_log(request_data)

data/lib/coolhand/configuration.rb

@@ -30,7 +30,7 @@ module Coolhand
 
     attr_accessor :api_key, :environment, :silent, :debug_mode, :capture, :exclude_api_patterns, :enabled,
       :max_captured_body_bytes, :webhook_replay_tolerance_seconds, :webhook_id_store, :async_logging
-    attr_reader :intercept_addresses, :intercept_path_patterns, :base_url
+    attr_reader :intercept_addresses, :intercept_path_patterns, :base_url, :auto_declare
 
     def initialize
       # Set defaults
@@ -45,6 +45,7 @@ module Coolhand
       @exclude_api_patterns = DEFAULT_EXCLUDE_API_PATTERNS.dup
       @enabled = true
       @async_logging = true
+      @auto_declare = []
       @max_captured_body_bytes = DEFAULT_MAX_CAPTURED_BODY_BYTES
       @webhook_replay_tolerance_seconds = 300
       @webhook_id_store = Coolhand::OpenAi::WebhookIdStore.new
@@ -74,6 +75,18 @@ module Coolhand
       @intercept_path_patterns = value.is_a?(Array) ? value : [value]
     end
 
+    # Rails entry points to declare a workload/template for automatically: any of
+    # RailsAutoDeclare::TARGETS (:active_job, :controller). Off by default. See docs/declared_workloads.md.
+    def auto_declare=(value)
+      targets = Array(value).map { |target| target.to_s.to_sym }
+      unknown = targets - RailsAutoDeclare::TARGETS
+      unless unknown.empty?
+        raise Error, "auto_declare supports #{RailsAutoDeclare::TARGETS.inspect}, got #{unknown.inspect}"
+      end
+
+      @auto_declare = targets.uniq
+    end
+
     def base_url=(value)
       stripped = value&.sub(%r{/+\z}, "")
       raise Error, BASE_URL_ERROR_MSG unless stripped.nil? || valid_base_url?(stripped)