querylane 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f62396550c8585a01958050e34f4e31628ddb53ad02cf97074900e0882a6e510
+  data.tar.gz: 68f1c601f5a1083d1fd6711db29c87fde0a994962091578cb7f58c5b0b12f98d
+SHA512:
+  metadata.gz: 8c35bb1029b86f33ca864824980c847c532a0a6b5ad4ee9bcd44a53c6ec3370fded089c1146025cf4db3d17736baf5c1383d8ee31edd030c677e3fb78b43b460
+  data.tar.gz: 82f3e9d07e46f33876573d5f4227070965f352e3ec67bf479c90f9a98e457b5e017cdb822e1e7355af17a2e208b9a22b479acf474c546c60078cee98474a4b9e

data/CHANGELOG.md

@@ -0,0 +1,84 @@
+# Changelog
+
+All notable changes to querylane are listed here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project uses
+[Semantic Versioning](https://semver.org/). Before 1.0, a minor version may
+change public APIs; each entry says how.
+
+## [Unreleased]
+
+## [0.1.0] - 2026-10-20
+
+The first release.
+
+### Added
+
+- importmap-rails support (Propshaft or Sprockets): `config/importmap.rb` pins
+  `querylane` and each module by its file name (`querylane/overlay.js`,
+  `querylane/controllers/*.js`), none preloaded; the engine adds
+  `app/javascript` to the asset load path and, when importmap-rails is loaded,
+  appends the gem's map to `config.importmap.paths` and the modules to
+  `config.importmap.cache_sweepers`, but only when the host has its own
+  `config/importmap.rb`. Hosts pin `@hotwired/stimulus` and
+  `@github/combobox-nav`. The `querylane.css` precompile entry is added only
+  under Sprockets.
+- The `querylane_set_query` stream action is handled through
+  `turbo:before-stream-render` instead of `StreamActions`, so querylane never
+  imports `@hotwired/turbo` and works with turbo-rails' bundled Turbo.
+- The modules import each other as `querylane/<file>.js` instead of by relative
+  path (ADR 0003), so one set of files serves importmap-rails, webpack and
+  esbuild aliases, and the npm package (`package.json` now exports `./*`).
+  Hand-written import maps need `querylane` and one `querylane/` prefix entry.
+
+- Query language: words, `key:value` operators, quoted phrases with `\"` and `\\`
+  escapes, implicit AND, `OR` (binding tighter than AND), `-` and `NOT`,
+  parentheses. Bounded by length, nesting depth and term count. Errors carry a
+  character range, a "did you mean" suggestion and a one-click **Fix it**.
+- `Querylane::Definition.build` DSL: `index`, `text`, `filter` (normalize,
+  format, sensitive, masks `:none`/`:all`/`:last4`/`:count`), `flags` (attribute
+  or per-index rules, aliases), `facet` (flag or filter, value subsets, `top`,
+  `show`, "Find…" search), `sort`, `per`, `retrieve`, `highlight`,
+  `interpreter` (with "… instead" alternatives), `parked`, `min_text_length`,
+  `group` (`valid`, `limit`, `order`), `saved`, `option`, `panel`, `example` and
+  `hook`. Declarations are validated at build time.
+- Required `Querylane::Scope` with a permission filter per index;
+  `Scope.unrestricted` and `Scope.denied`. Backend-neutral `Querylane::Filter`
+  (`eq`, `in`, `null`, `missing`, `and`, `or`, `not`, `everything`, `nothing`,
+  `raw`).
+- Query-filter and results hooks with a `Querylane::Context`; results hooks
+  declare `:preserving` or `:changing` cardinality. Hooks fail closed.
+- Meilisearch searcher (Meilisearch 1.13+, `meilisearch` gem `~> 0.33.0`):
+  federated hits across indexes, one batched call for exact totals and
+  disjunctive facet counts, per-group record counts, highlight markers. Fails
+  closed with an `:unavailable` state; a failed count batch keeps the hits.
+- `rake querylane:doctor[Definition]` checks index settings.
+- `Querylane::Controller`: `querylane_search`, `querylane_preview`,
+  `querylane_related`, `querylane_suggest` and `querylane_frame?`, with a guard
+  that refuses query text in a GET URL and sends `Cache-Control: no-store`.
+- View helpers and partials (Bootstrap 5 classes): `querylane_form` (native
+  input with a colored, masking overlay; optional help text),
+  `querylane_results` (chips, error with Fix it, facets, toolbar, pager, grouped
+  rows, footer), `querylane_suggest_box` (header dropdown or ⌘K / Ctrl-K
+  palette) with `querylane_suggestions`, and `querylane_related` ("more records"
+  and the Space preview).
+- States: first load with examples, too short, empty (widen, drop, relax),
+  invalid, unavailable, denied.
+- Options panel that reads the query into fields and writes it back, with a live
+  masked "Writes" preview.
+- Saved searches through a host store (`all`, `create`, `use` with `context:`);
+  queries with sensitive terms, typed or interpreted, are refused.
+- `Querylane::Presenter` base class for host rows: columns, cells, status,
+  flags, Open action or reason (with "+N more"), group titles, suggestions.
+- Encrypted, expiring group tokens; group keys never reach the page.
+- Stimulus controllers (`querylane--box`, `--results`, `--options`,
+  `--suggest`) and the `querylane_set_query` Turbo Stream action, registered with
+  `registerControllers(application)`. Revisions drop stale responses; Turbo
+  snapshots never keep query text.
+- `querylane.css` themed by `--ql-*` custom properties; safe for SassC
+  compressors.
+- English translations under `querylane.*`.
+- `search.querylane` and `saved_search_failed.querylane` instrumentation, without
+  query text. The query parameter and `compose` are filtered from logs.
+
+[Unreleased]: https://github.com/clearstackio/querylane/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/clearstackio/querylane/releases/tag/v0.1.0

data/CONTRIBUTING.md

@@ -0,0 +1,118 @@
+# Contributing
+
+Thanks for working on querylane. This page covers setup, the checks every change
+must pass, the conventions, and how the docs are organized. Read
+[docs/architecture.md](docs/architecture.md) before a larger change.
+
+## Setup
+
+Tools are pinned in `mise.toml` (Ruby 3.3, Node 22, FracturedJSON).
+
+```sh
+mise install
+bundle install
+npm install                       # Turbo, Stimulus, combobox-nav, Playwright (dev only)
+npx playwright install chromium   # for system specs
+```
+
+Most specs need a Meilisearch 1.13+ server:
+
+```sh
+export MEILISEARCH_URL=http://localhost:7700
+export MEILISEARCH_API_KEY=your-key
+```
+
+The suite drops and recreates the indexes `querylane_spec_staff` and
+`querylane_spec_contractors` on that server.
+
+## Running the checks
+
+```sh
+bundle exec rspec                 # everything; :meilisearch examples skip without a server
+bundle exec rspec spec/querylane  # unit specs only
+bin/lint                          # StandardRB, then FracturedJSON on tracked JSON files
+bin/lint fix                      # apply StandardRB fixes and reformat JSON
+bundle exec rake                  # the suite and StandardRB, as CI runs it
+```
+
+Run them through mise if your shell does not activate it:
+`mise exec -- bundle exec rspec`, `mise exec -- bin/lint`.
+
+`bin/lint` checks JSON files known to git (`git ls-files`), outside `spec/dummy`.
+
+## The dummy app
+
+`spec/dummy` is the reference host: a definition (`app/searches/dummy_search.rb`),
+a presenter, a controller using every controller call, an in-memory saved-search
+store, the header box and palette (`/elsewhere`), and an import-map layout that
+serves the gem's JavaScript straight from `app/javascript`. Request and system
+specs run against it. Keep it working and keep it showing every feature: it is
+also the example the guides quote.
+
+## Conventions
+
+- **Style:** StandardRB. Do not add a `.rubocop.yml`.
+- **One concern per file.** Public API first, then private helpers.
+- **Header comments** on every class and module: what it is for and how it fits
+  the flow. Document public methods with YARD (`@param`, `@return`).
+- **Ruby decides, partials draw.** No markup built in Ruby; presenters and
+  helpers return data or render partials.
+- **CSS** must pass SassC compressors: no `min()`, `max()`, `clamp()` or
+  space-separated `rgb()`. Use `font-variant-caps`, never `text-transform`. Keep
+  `[hidden]` winning over display rules.
+- **JavaScript** is plain ES modules that import each other as
+  `querylane/<file>.js`, never by relative path. Never start
+  Stimulus or change Turbo settings from the gem. Use `textContent`, never
+  `innerHTML` with data.
+- **Privacy rules are invariants.** Query text travels by POST, responses are
+  `no-store`, sensitive values are masked wherever they are shown, group keys
+  never reach HTML, saving refuses sensitive terms. A change that weakens one
+  needs a decision record.
+- **Tests:** every behavior gets a spec at the right layer: unit
+  (`spec/querylane/`), integration against Meilisearch (`spec/integration/`),
+  request (`spec/requests/`) or browser (`spec/system/`).
+- **Changelog:** add a line under `[Unreleased]` in [CHANGELOG.md](CHANGELOG.md)
+  for anything a host would notice.
+- **CI:** GitHub Actions (`.github/workflows/ci.yml`): `rake` on Ruby 3.3, 3.4
+  and 4.0 against Meilisearch 1.13 and headless Chromium. Actions are pinned to
+  commit SHAs. FracturedJSON is not run in CI; run `bin/lint` before pushing.
+- **Security:** no secrets in the repo; see [SECURITY.md](SECURITY.md).
+
+## Releasing
+
+Releases go to rubygems.org from GitHub Actions with
+[trusted publishing](https://guides.rubygems.org/trusted-publishing/) (no API
+key) and a Sigstore attestation (`.github/workflows/release.yml`, in the
+`rubygems` environment).
+
+Before the first release, an owner of the gem adds a pending trusted publisher
+on rubygems.org (Profile → Trusted publishers): gem `querylane`, repository
+owner `clearstackio`, repository `querylane`, workflow `release.yml`,
+environment `rubygems`. After the first push it becomes the gem's trusted
+publisher.
+
+1. Update `VERSION` in `lib/querylane/version.rb` and run `bundle install` so
+   `Gemfile.lock` follows.
+2. Move the `[Unreleased]` entries in `CHANGELOG.md` under the new version and
+   date, and update the compare links at the bottom.
+3. Commit, then tag and push: `git tag v0.1.0 && git push origin master v0.1.0`.
+
+The workflow runs the full CI suite on the tagged commit (Meilisearch and
+Chromium included), checks the tag matches `VERSION`, then builds, pushes and
+attests the gem. A failing suite publishes nothing.
+
+## Documentation
+
+| Where | What |
+| --- | --- |
+| [README.md](README.md) | The front door: pitch, install, quick start |
+| [docs/guides/](docs/README.md) | One guide per topic, for people using the gem |
+| [docs/architecture.md](docs/architecture.md) | How the gem works, for contributors |
+| [docs/decisions/](docs/decisions/README.md) | Decision records (ADRs) |
+| [docs/spikes/](docs/spikes/meilisearch-1.13.md) | Evidence from backend experiments |
+| [AGENTS.md](AGENTS.md) | Instructions for coding agents |
+
+When you change behavior, update the guide that describes it in the same change.
+Examples in the guides should match the dummy app or a spec. Record a decision
+that is hard to reverse as a new ADR in `docs/decisions/` and list it in its
+README.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ajaya Agrawalla
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,287 @@
+# querylane
+
+querylane is a Rails engine that adds a Gmail-style search box to a Rails app.
+People type plain words and operators (`smith team:ops -is:terminated`). The
+server parses the text, searches one or more Meilisearch indexes inside a
+permission scope, and renders the results with the engine's partials and
+Stimulus controllers. The query text is the only search state: facets, chips
+and the options panel all rewrite the text in the box, so what you see in the
+box is always what was searched.
+
+[![Build Status](https://github.com/clearstackio/querylane/actions/workflows/ci.yml/badge.svg)](https://github.com/clearstackio/querylane/actions)
+
+## Features
+
+- A small query language: words, `key:value` operators, quotes, `OR`, `-`/`NOT`,
+  parentheses. Errors point at the exact characters, suggest a fix ("Did you mean
+  `status:`?") and offer **Fix it**.
+- An interpreter hook that reads bare tokens as operators (`5432` as a last four),
+  with "… instead" buttons for other readings.
+- "Searching for" chips with × to remove a term. Sensitive values are masked.
+- Facets with counts (OR within a facet, AND across facets) that tick and untick
+  terms in the query text. A "Find…" box for long facet lists.
+- Toolbar with count, sort, page size and pager.
+- Result rows grouped by an attribute (for example one person), drawn from your
+  `Querylane::Presenter`. "N more records" for a group and a Space-key preview.
+- An options panel that turns the query into fields and back.
+- A header search box with suggestions and a ⌘K / Ctrl-K palette.
+- Saved searches through a store you provide.
+- Clear states: first load, too short, empty (with widen, drop and relax buttons),
+  invalid, unavailable and access denied.
+- Keyboard support: `/`, ↑ ↓, Enter, Space, Esc, Tab, ⌘K.
+- Privacy defaults: queries travel by POST only, responses are `no-store`, query
+  parameters are filtered from logs, group handles are encrypted, and saved
+  searches refuse sensitive values.
+
+## Requirements
+
+| | Version |
+| --- | --- |
+| Ruby | 3.3 or newer |
+| Rails | 8.1 (`~> 8.1.0`) |
+| Meilisearch server | 1.13 or newer |
+| `meilisearch` gem | `~> 0.33.0` (you add it to your Gemfile) |
+| JavaScript peers | `@hotwired/turbo` 8, `@hotwired/stimulus` 3.2, `@github/combobox-nav` 3 |
+| CSS | Bootstrap 5 (the partials use its button, form and pagination classes) |
+| Browsers | Current browsers with the Popover API and `<dialog>` |
+
+Turbo Drive may be on or off. The widgets only use Turbo Frames and one custom
+Turbo Stream action.
+
+## Installation
+
+Add the gem and the Meilisearch client to your Gemfile:
+
+```ruby
+gem "querylane"
+gem "meilisearch", "~> 0.33.0"
+```
+
+To try unreleased work, point the gem at the repository
+(`gem "querylane", github: "clearstackio/querylane", branch: "master"`) and use a
+local checkout without reinstalling:
+`bundle config local.querylane /path/to/querylane`.
+
+### JavaScript
+
+Install the peer packages in your app:
+
+```sh
+npm install @hotwired/turbo @hotwired/stimulus @github/combobox-nav
+```
+
+The gem ships ES modules in `app/javascript/querylane/`. Your bundler must find
+them, and must resolve the peers to your app's own copies (two copies of Turbo
+would mean the custom stream action is registered on the wrong one).
+
+**jsbundling with webpack.** Ask Bundler where the gem lives, so local overrides
+and lockfile revisions use the same files:
+
+```js
+// webpack.config.js
+const { execFileSync } = require("child_process")
+const path = require("path")
+
+const querylaneRoot = execFileSync("bundle", ["exec", "ruby", "-e", "print Gem.loaded_specs['querylane'].full_gem_path"],
+  { cwd: __dirname, encoding: "utf8" }).trim()
+
+module.exports = {
+  // ...your config
+  resolve: {
+    alias: {
+      querylane: path.join(querylaneRoot, "app/javascript/querylane"),
+      "@hotwired/stimulus": path.resolve(__dirname, "node_modules/@hotwired/stimulus"),
+      "@hotwired/turbo": path.resolve(__dirname, "node_modules/@hotwired/turbo"),
+      "@github/combobox-nav": path.resolve(__dirname, "node_modules/@github/combobox-nav")
+    }
+  }
+}
+```
+
+Webpack's watcher picks up edits to the gem. Restart it when the gem path changes.
+
+**importmap-rails (Propshaft or Sprockets).** Nothing to configure for the
+gem's own modules: when your app has a `config/importmap.rb`, the engine adds
+`app/javascript` to the asset load path and draws the gem's
+[`config/importmap.rb`](config/importmap.rb) into your app's map. That map pins
+`querylane` and each module by its file name (`querylane/overlay.js`,
+`querylane/controllers/box_controller.js`, ...), none of them preloaded, so
+pages without a search box fetch nothing. Your app pins the peers, so the page
+shares one copy of each with your own code:
+
+```ruby
+# config/importmap.rb
+pin "@hotwired/stimulus", to: "stimulus.min.js"   # stimulus-rails
+pin "@github/combobox-nav"                        # bin/importmap pin @github/combobox-nav
+```
+
+Turbo stays as your app loads it (turbo-rails' `turbo.min.js` pin is fine).
+querylane never imports Turbo: it handles its one custom stream action through
+the `turbo:before-stream-render` event, which every Turbo 8 copy dispatches.
+
+On Sprockets, the modules are precompiled as they are. If your app sets
+`config.assets.js_compressor`, it must parse ES module syntax (`import` and
+`export`), or `assets:precompile` fails on querylane's files. Propshaft does not
+compress.
+
+**How the modules import each other.** As `querylane/overlay.js` and so on,
+never by relative path: a relative import would miss the digested URLs
+importmap-rails serves. The same names resolve under the webpack alias above,
+an esbuild alias, the npm package in `app/javascript/querylane`, and a
+hand-written import map with one `"querylane/"` prefix entry.
+
+**Import maps without importmap-rails.** Serve the gem's `app/javascript`
+directory and the peer packages as ES modules, then map `querylane` and the
+`querylane/` prefix. The dummy app in [`spec/dummy`](spec/dummy/config/application.rb) does exactly
+this with `Rack::Static` and an inline import map; see
+[Getting started](docs/guides/getting-started.md#javascript).
+
+Then register the controllers with your Stimulus application:
+
+```js
+import { registerControllers } from "querylane"
+
+registerControllers(application)
+```
+
+`registerControllers` registers `querylane--box`, `querylane--results`,
+`querylane--options` and `querylane--suggest`. Importing `querylane` also adds
+the `querylane_set_query` Turbo Stream action. The gem never starts Stimulus and
+never changes Turbo settings.
+
+### Stylesheet
+
+```erb
+<%= stylesheet_link_tag "querylane" %>
+```
+
+It is plain CSS and works with Sprockets and Propshaft. Theme it with the
+`--ql-*` custom properties ([Theming](docs/guides/theming.md)).
+
+## Quick start
+
+A complete, working version of this example lives in [`spec/dummy`](spec/dummy).
+
+**1. Point querylane at Meilisearch.**
+
+```ruby
+# config/initializers/querylane.rb
+Rails.application.config.to_prepare do
+  Querylane.configure do |config|
+    config.searcher = -> { Querylane::Searchers::Meilisearch.new(client: Meilisearch::Client.new(ENV["MEILISEARCH_URL"], ENV["MEILISEARCH_API_KEY"])) }
+  end
+end
+```
+
+**2. Describe the search.**
+
+```ruby
+# app/searches/people_search.rb
+module PeopleSearch
+  def self.definition
+    @definition ||= Querylane::Definition.build(:people) do |d|
+      d.index  :staff, name: "staff"
+      d.text   :name, attributes: %i[full_name], default: true, label: "Name contains %{value}"
+      d.filter :team, attribute: :team, label: "Team %{value}"
+      d.flags  :is, alias: :status, attribute: :status_label, label: "Status",
+                    values: {active: "Active", terminated: "Terminated"}
+      d.facet  :status, flag: :is
+      d.group  :person
+    end
+  end
+end
+```
+
+**3. Search in a controller.**
+
+```ruby
+# config/routes.rb
+get  "people", to: "people#index"
+post "people/search", to: "people#search", as: :people_search
+post "people/open", to: "people#open", as: :open_person # the row's Open button posts here
+
+# app/controllers/people_controller.rb
+class PeopleController < ApplicationController
+  include Querylane::Controller
+
+  def index
+    @result = querylane_search(PeopleSearch.definition, scope: scope)
+  end
+
+  def search
+    @result = querylane_search(PeopleSearch.definition, scope: scope)
+    if querylane_frame?(:people)
+      render partial: "people/results", locals: {result: @result}
+    else
+      render :index
+    end
+  end
+
+  private
+
+  # What this user may see. Built on the server, never from params.
+  def scope = Querylane::Scope.new(staff: Querylane::Filter.eq(:company_id, current_user.company_id))
+end
+```
+
+**4. Draw it.**
+
+```erb
+<%# app/views/people/index.html.erb %>
+<%= querylane_form @result, id: :people, url: people_search_path %>
+<%= render "people/results", result: @result %>
+
+<%# app/views/people/_results.html.erb %>
+<%= querylane_results result, id: :people, presenter: PersonPresenter %>
+```
+
+**5. Say how a record looks.**
+
+```ruby
+# app/presenters/person_presenter.rb
+class PersonPresenter < Querylane::Presenter
+  def columns = [Column.new(:team, "Team", 120)]
+
+  def cells(hit) = [Cell.new(hit.document["team"], :strong)]
+
+  def status(hit)
+    (hit.document["status_label"] == "active") ? Badge.new("Active", :success) : Badge.new("Terminated", :neutral)
+  end
+
+  # Open is a full-page POST to the URL, with these params.
+  def outcome(hit) = Action.new("Open", view.open_person_path, {id: hit.id}, :primary)
+end
+```
+
+**6. Check the index settings.**
+
+```sh
+bin/rails "querylane:doctor[PeopleSearch.definition]"
+```
+
+The doctor lists every attribute the definition needs that the index does not
+declare (searchable, filterable, sortable, typo tolerance, facet order).
+
+## Learn more
+
+| Guide | What it covers |
+| --- | --- |
+| [Getting started](docs/guides/getting-started.md) | An end-to-end first page: routes, frames, index settings, JavaScript, the doctor |
+| [Definition](docs/guides/definition.md) | Every DSL method: operators, facets, sorts, interpreter, groups, panel, hooks |
+| [Query language](docs/guides/query-language.md) | What people can type, precedence, errors, wildcards, interpreted tokens |
+| [Widgets](docs/guides/widgets.md) | Each widget, its helper, params, frames and keys |
+| [Presenter](docs/guides/presenter.md) | How result rows, groups and suggestions are drawn |
+| [Controller](docs/guides/controller.md) | `querylane_search`, `_preview`, `_related`, `_suggest`, frames, guards |
+| [Scope and hooks](docs/guides/scope-and-hooks.md) | Permission scopes, the Filter API, query-filter and results hooks |
+| [Saved searches](docs/guides/saved-searches.md) | The store contract and what is refused |
+| [Theming](docs/guides/theming.md) | CSS custom properties, partial overrides, translations |
+| [Security](docs/guides/security.md) | The privacy model and what the host must do |
+| [Testing](docs/guides/testing.md) | Testing a host app, and running the gem's suite |
+| [Architecture](docs/architecture.md) | How a request flows through the gem (for contributors) |
+
+Also: [CHANGELOG](CHANGELOG.md), [CONTRIBUTING](CONTRIBUTING.md),
+[SECURITY](SECURITY.md), [all docs](docs/README.md).
+
+## License
+
+MIT. See [LICENSE](LICENSE).

data/SECURITY.md

@@ -0,0 +1,29 @@
+# Security policy
+
+## Reporting a vulnerability
+
+Report it privately through
+[GitHub's private vulnerability reporting](https://github.com/clearstackio/querylane/security/advisories/new),
+or email ajaya@clearstack.io. Please do not open a public issue.
+
+We aim to acknowledge a report within three working days, and to publish a
+fix and a GitHub security advisory once it is confirmed.
+
+Include the querylane version (or commit), how to reproduce the problem, and
+what an attacker could see or do.
+
+## Supported versions
+
+querylane is pre-1.0. Only the latest release is supported.
+
+## The privacy model
+
+querylane's guarantees, and the duties it leaves to the host app (building the
+scope on the server, filtering a renamed query parameter, keeping request bodies
+out of APM), are described in [docs/guides/security.md](docs/guides/security.md).
+
+## Releases
+
+Releases are published to rubygems.org from GitHub Actions with trusted
+publishing (no long-lived API key) and carry a Sigstore attestation. Any other
+push needs MFA (`rubygems_mfa_required`).