chore!: reset version history and ship clean v1.0.0

Collapse pre-1.0 changelog entries, drop ApexScout namespace history
and post-1.0 upgrade notes, soften positioning vs Meilisearch/Algolia/
Typesense, add FAQ + "Should I use this?" sections, scope ensureSearchable
cache + lookup by database/schema/table, drop minimum-stability=dev,
add ext-pdo_pgsql requirement.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: jonaspauleta

.github/ISSUE_TEMPLATE/bug.yml

@@ -15,7 +15,7 @@ body:
     attributes:
       label: Package version
       description: Output of `composer show jonaspauleta/scout-postgres | grep versions`.
-      placeholder: "0.3.0"
+      placeholder: "1.0.0"
     validations:
       required: true
 

.github/PULL_REQUEST_TEMPLATE.md

@@ -22,7 +22,7 @@ Closes #
 - [ ] Pest test added that fails before this change and passes after.
 - [ ] `composer quality` passes clean (Rector, Pint, PHPStan level max).
 - [ ] `composer test` passes locally against Postgres 14+.
-- [ ] `CHANGELOG.md` updated under `[Unreleased]` using Keep a Changelog categories.
+- [ ] `CHANGELOG.md` updated with an entry describing the change, using Keep a Changelog categories.
 - [ ] README / docblocks updated if public API changed.
 - [ ] Conventional Commit prefix on the PR title (`feat:`, `fix:`, `docs:`, …).
 

CHANGELOG.md

@@ -1,10 +1,8 @@
 # scout-postgres — Agent Guide
 
-Native Postgres 18 FTS + pg_trgm engine for Laravel Scout. Standalone
+Native Postgres FTS + pg_trgm engine for Laravel Scout. Standalone
 package — published as `jonaspauleta/scout-postgres` on Packagist.
-Root PHP namespace is `ScoutPostgres\`. The legacy `ApexScout\ScoutPostgres\`
-namespace was removed in `1.1.0` — pre-1.1 imports must be migrated to
-`ScoutPostgres\…`.
+Root PHP namespace is `ScoutPostgres\`.
 
 ## Installation
 

CLAUDE.md

@@ -14,7 +14,7 @@ Thanks for considering a contribution. This document is short and concrete.
    composer test      # pest
    ```
 
-5. Update `CHANGELOG.md` under the `[Unreleased]` section using [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) categories (`Added` / `Changed` / `Fixed` / `Deprecated` / `Removed` / `Security`).
+5. Update `CHANGELOG.md` with an entry describing the change, using [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) categories (`Added` / `Changed` / `Fixed` / `Deprecated` / `Removed` / `Security`). Maintainers cut and tag releases.
 6. Commit using [Conventional Commits](https://www.conventionalcommits.org/) (`feat:`, `fix:`, `docs:`, `refactor:`, `test:`, `chore:` …).
 7. Open a PR against `main`. Link any related issue.
 

CONTRIBUTING.md

@@ -6,14 +6,32 @@
 [![Total Downloads](https://img.shields.io/packagist/dt/jonaspauleta/scout-postgres.svg?style=flat-square)](https://packagist.org/packages/jonaspauleta/scout-postgres)
 [![License](https://img.shields.io/packagist/l/jonaspauleta/scout-postgres.svg?style=flat-square)](LICENSE.md)
 
-Postgres-native search engine for [Laravel Scout](https://laravel.com/docs/scout). Removes the need for Meilisearch / Algolia / Typesense for the common 80% case when you already run Postgres — no extra service, no sync queue, no separate index. See [Comparison](#comparison) and [Limitations](#limitations) for the cases it does **not** cover.
+A Postgres-native Laravel Scout engine for apps that want search without running Meilisearch, Algolia, or Typesense. Targets the common 80% case when you already run Postgres — no extra service, no sync queue, no separate index. See [Should I use this?](#should-i-use-this), [Comparison](#comparison), and [Limitations](#limitations) for the cases it does **not** cover.
 
 Works on any Postgres 14+ where `pg_trgm` and `unaccent` are available — managed (Neon, Laravel Cloud, RDS, Supabase, DigitalOcean) or self-managed.
 
 ## Why
 
 Most Laravel apps already have Postgres. Adding Meilisearch or Typesense means another service to deploy, secure, monitor, scale, and keep in sync. For mid-sized catalogs (millions of rows, sub-100ms p95) Postgres FTS combined with `pg_trgm` similarity is good enough, cheaper, and stays consistent with your source of truth — there is no separate index to drift out of sync.
 
+## Should I use this?
+
+**Use it when:**
+
+- You already run Postgres and don't want to operate a second search service.
+- Your corpus is in the hundreds-of-thousands to low-millions of rows.
+- You need typo tolerance, prefix / as-you-type matching, and accent-insensitive search.
+- You're happy with raw-SQL faceting and aggregation (Scout returns model IDs; you join from there).
+- A single `regconfig` (text search configuration) per table is enough — usually `simple_unaccent` or one language per migration.
+
+**Use a dedicated engine instead when:**
+
+- You need first-class faceting, highlighting, or synonym dictionaries.
+- You need per-document language switching (English row, Portuguese row, Japanese row in the same table).
+- Your corpus is hundreds of millions of rows.
+- You need geo-search and don't want to add PostGIS.
+- You need learning-to-rank, vector hybrid search, or relevance feedback features.
+
 ## Comparison
 
 Honest side-by-side. Use this to decide whether `scout-postgres` is the right tool, or whether you actually need a dedicated engine.
@@ -266,8 +284,8 @@ LIMIT :perPage OFFSET :offset;
 
 So in the worst case adaptive runs two queries; in the common case it runs
 one. `query_strategy=hybrid` forces single-pass FTS+trigram for every
-query (the pre-1.0 behaviour). `query_strategy=fts_only` never runs the
-trigram pass — fastest but loses typo recovery.
+query. `query_strategy=fts_only` never runs the trigram pass — fastest but
+loses typo recovery.
 
 ### Short-prefix fast path
 
@@ -329,8 +347,8 @@ that matter:
   are available as opt-in tunings; their thresholds have different
   semantics so re-tune the threshold when switching.
 
-See [`benchmarks/`](benchmarks/) for measured numbers on a 50,150-row
-corpus, including before/after deltas vs `1.0.0`.
+See [`benchmarks/`](benchmarks/) for measured numbers on 50k and 500k
+row corpora, with full methodology and the artisan harness.
 
 ## Production notes
 
@@ -382,8 +400,7 @@ Book::search('foo')
     ->paginate(20);
 ```
 
-Or globally via `SCOUT_POSTGRES_TOTAL_COUNT=true` to restore the pre-1.0
-default for every search.
+Or globally via `SCOUT_POSTGRES_TOTAL_COUNT=true` for every search.
 
 When `total_count` is enabled the window aggregate forces Postgres to
 materialise every matching row before applying `LIMIT`, so latency scales
@@ -394,8 +411,6 @@ million-row corpora.
 
 The package is **stable** as of `v1.0.0`. The public API — the `postgresSearchable()` migration macro, the `dropPostgresSearchable()` macro, the `PostgresSearchable` contract, the `pgsql` Scout engine driver name, and the keys in `config/scout-postgres.php` — is committed across the entire `1.x` line. Breaking changes will land on a `2.0.0` release tag and will be documented in `CHANGELOG.md` with a migration note.
 
-The legacy `ApexScout\ScoutPostgres\` namespace was dropped in `1.1.0` — migrate any remaining imports to `ScoutPostgres\…`.
-
 ## Limitations
 
 By design, this package targets the 80% case. The following are **not** in scope for the `1.x` line:
@@ -421,32 +436,34 @@ The model's connection driver is not `pgsql`. Check `config/database.php` and th
 **`text search configuration "simple_unaccent" does not exist`**
 The package migration did not run. Run `php artisan migrate`. The package's own migration is loaded automatically — no `--path` flag is needed.
 
-## Upgrading from earlier 1.x releases
+## FAQ
 
-The post-1.0.0 work flips several behavioural defaults to make the
-out-of-the-box experience faster on common Scout-driver workloads. Each is
-backed by a config key so the old behaviour can be restored without code
-changes — useful when an existing deployment depends on the previous
-ranking or pagination semantics.
+**Do I need to run `php artisan scout:import`?**
+No. The `search_vector` and `search_text` columns are `STORED GENERATED`,
+so Postgres recomputes them automatically on every `INSERT` / `UPDATE`.
+There is no external index to seed.
 
-| Change                                      | Restore old behaviour                                |
-|---------------------------------------------|------------------------------------------------------|
-| Adaptive query strategy (FTS-first)         | `SCOUT_POSTGRES_QUERY_STRATEGY=hybrid`               |
-| Short-prefix fast path                      | `SCOUT_POSTGRES_PREFIX_FAST_PATH=false`              |
-| `COUNT(*) OVER()` omitted by default        | `SCOUT_POSTGRES_TOTAL_COUNT=true`                    |
-| `SET LOCAL jit = off` per query             | `SCOUT_POSTGRES_DISABLE_JIT=false`                   |
-| `search_text` capped at 1000 chars (new migrations only) | pass `0` as the third macro arg: `$table->postgresSearchable($weights, null, 0)` |
+**Should I enable `SCOUT_QUEUE=true`?**
+No — keep it `false`. Scout's queue exists to debounce writes to a remote
+index; this engine has no remote index. Enabling the queue just adds a
+no-op job to your worker.
 
-Existing `search_text` columns are unaffected by the cap — only new
-migrations applying `postgresSearchable()` pick up the `LEFT(...)` wrapper.
+**Why are `update`, `delete`, `flush`, `createIndex`, and `deleteIndex`
+no-ops?**
+The Postgres generated columns and GIN indexes are the source of truth.
+There is no separate index to push to, so Scout's per-row sync hooks have
+nothing to do — the engine implements them as no-ops on purpose. Adding
+`postgresSearchable()` in a migration is the only "indexing" step.
 
-The legacy `ApexScout\ScoutPostgres\` namespace was removed in `1.1.0`.
-Replace any remaining imports:
+**What text search configuration does the engine use?**
+`simple_unaccent` — a copy of the built-in `simple` config mapped through
+the `unaccent` dictionary. The package migration creates it. Override via
+`SCOUT_POSTGRES_CONFIG` or per model via `scoutPostgresConfig()`.
 
-```diff
--use ApexScout\ScoutPostgres\Contracts\PostgresSearchable;
-+use ScoutPostgres\Contracts\PostgresSearchable;
-```
+**Can different models use different connections?**
+Yes. The model's connection driver must be `pgsql`, otherwise the engine
+throws `UnsupportedDriverException`. The engine reads the connection from
+the model on every query.
 
 ## Testing
 
@@ -467,7 +484,7 @@ When sending a PR:
 
 1. Add a Pest test that fails before your change and passes after.
 2. Run `composer quality` — it must pass clean (Pint, Rector, PHPStan level max).
-3. Update `CHANGELOG.md` under the `[Unreleased]` section.
+3. Update `CHANGELOG.md` with an entry describing the change.
 
 ## Security
 

README.md

@@ -34,8 +34,8 @@ Security fixes are issued for the latest minor release. Older minors receive fix
 
 | Version | Supported          |
 |---------|--------------------|
-| 0.3.x   | ✅                 |
-| < 0.3   | ❌                 |
+| 1.x     | ✅                 |
+| < 1.0   | ❌                 |
 
 ## Credit
 

SECURITY.md

@@ -52,12 +52,12 @@ php artisan bench:scout --seed=500000 --runs=30 --warmup=3
 
 Run on Postgres 18.3, PHP 8.5, Laravel 13, 500,150 rows, hot cache.
 
-### Current defaults (adaptive strategy, prefix fast path, JIT off, total_count off)
+### Default config (500,150 rows)
 
-Run with the 1.1.0 default config: `query_strategy=adaptive`,
+Run with the shipped defaults: `query_strategy=adaptive`,
 `prefix_fast_path=true`, `disable_jit=true`, `total_count=false`,
 `trigram_function=similarity`, `trigram_threshold=0.3`. Schema migrated with
-the new `search_text` cap (1000 chars).
+the `search_text` cap (1000 chars).
 
 | query              | `pgsql` p50 (ms) | `database` p50 (ms) | hits (pg / db) | notes                                                |
 |--------------------|-----------------:|--------------------:|:---------------|:-----------------------------------------------------|
@@ -81,7 +81,9 @@ holds latency bounded and where it doesn't:
 - `qwxzqwxzqwxz` stays cheap because the trigram bitmap is empty — the
   GIN index returns no candidates regardless of corpus size.
 
-### 50,150-row results (post-1.0 defaults) — for reference
+### Default config (50,150 rows) — for corpus-size scaling
+
+Same configuration, smaller corpus, same hardware:
 
 | query              | `pgsql` p50 (ms) | `database` p50 (ms) | hits (pg / db) |
 |--------------------|-----------------:|--------------------:|:---------------|
@@ -93,51 +95,26 @@ holds latency bounded and where it doesn't:
 | `qwxzqwxzqwxz`     |              7.9 |               191.5 | 0 / 0          |
 | long natural query |              7.1 |                 2.9 | 20 / 20        |
 
-### 1.0.0 results at 50,150 rows (`trigram_threshold = 0.3`, no adaptive)
-
-| query              | `pgsql` p50 (ms) | `database` p50 (ms) | hits (pg / db) | notes                                     |
-|--------------------|-----------------:|--------------------:|:---------------|:------------------------------------------|
-| `world`            |              8.9 |                 2.3 | 20 / 20        | both indexed paths fast                   |
-| `modern history`   |            185.7 |               196.0 | **20 / 0**     | `database` cannot bridge token gaps       |
-| `philosophical exposition` | 82.6     |                 2.8 | 20 / 20        | window-aggregate cost on broad match set  |
-| `phil`             |            599.5 |                 2.7 | 20 / 20        | short prefix → broad match → big sort     |
-| `philosphy`        |              9.2 |               186.7 | 0 / 0          | trigram correctly rejects, fast           |
-| `qwxzqwxzqwxz`     |              4.6 |               175.5 | 0 / 0          | GIN miss is instant; LIKE seq-scans       |
-| `a comprehensive history of modern philosophical thought` | 31.3 | 2.6 | 20 / 20        | FTS handles long queries                  |
-
-### Pre-1.0 default at 50,150 rows (`trigram_threshold = 0.15`) — for reference
-
-| query              | `pgsql` p50 (ms) | `database` p50 (ms) | hits (pg / db) |
-|--------------------|-----------------:|--------------------:|:---------------|
-| `world`            |            180.2 |                 2.4 | 20 / 20        |
-| `modern history`   |           1263.9 |               181.3 | 20 / 0         |
-| `philosophical exposition` |   1584.4 |                 3.0 | 20 / 20        |
-| `phil`             |           1428.7 |                 2.9 | 20 / 20        |
-| `philosphy`        |            483.6 |               172.8 | 0 / 0          |
-| `qwxzqwxzqwxz`     |              4.8 |               176.5 | 0 / 0          |
-| long natural query |           1393.7 |                 3.0 | 20 / 20        |
-
-The 0.15 default is preserved here as evidence for the threshold change in 1.0.0.
-
 ## Findings
 
 1. **`scout-postgres` has measurably better recall.** Multi-token queries,
    prefix matches, and accent variants all return matches that the
    `database` driver's `LIKE %term%` strategy misses entirely.
 2. **The adaptive strategy + short-prefix fast path are the dominant wins.**
-   `phil` drops from 599 ms (1.0.0) to 4 ms (current) because the fast path
-   skips both `websearch_to_tsquery` and the trigram bitmap entirely. Multi-
-   token FTS queries (e.g. `modern history`) drop from 186 ms to 5 ms
-   because adaptive returns the FTS hits without running the trigram pass.
-3. **`total_count=false` removes the second-biggest cost.** The previous
-   `COUNT(*) OVER()` window aggregate forced materialisation of the full
-   match set before `LIMIT`. Latency now scales with page size, not
-   match-set size. Opt back in per-query when an exact total is required.
-4. **The `trigram_threshold` setting is still the dominant trigram cost knob.**
-   A 2× change in threshold can change p50 by 10–100× on the hybrid
-   fallback path. The default `0.3` is chosen to be safe for typical
-   mixed-length corpora; tune **higher** for long-text corpora, **lower**
-   only for short titles where false negatives are the bigger concern.
+   The fast path skips both `websearch_to_tsquery` and the trigram bitmap
+   entirely on single short tokens, so `phil` runs in ~4 ms even on
+   500k rows. Multi-token FTS queries (e.g. `modern history`) stay
+   sub-10 ms because adaptive returns the FTS hits without running the
+   trigram pass.
+3. **`total_count=false` removes a major p95 cost.** A `COUNT(*) OVER()`
+   window aggregate forces materialisation of the full match set before
+   `LIMIT`. With it off, latency scales with page size, not match-set
+   size. Opt back in per-query when an exact total is required.
+4. **`trigram_threshold` is the dominant trigram cost knob.** A 2× change
+   in threshold can change p50 by 10–100× on the hybrid fallback path.
+   The default `0.3` is chosen to be safe for typical mixed-length
+   corpora; tune **higher** for long-text corpora, **lower** only for
+   short titles where false negatives are the bigger concern.
 5. **The `database` driver wins on small literal-substring queries** because
    `LIMIT 20` short-circuits its sequential scan. It loses badly on
    `no_match` (full table seq scan) and on multi-token queries (zero recall).

benchmarks/README.md

@@ -30,6 +30,8 @@
     ],
     "require": {
         "php": "^8.3",
+        "ext-pdo": "*",
+        "ext-pdo_pgsql": "*",
         "illuminate/contracts": "^11.0 || ^12.0 || ^13.0",
         "illuminate/database": "^11.0 || ^12.0 || ^13.0",
         "illuminate/support": "^11.0 || ^12.0 || ^13.0",
@@ -79,6 +81,5 @@
             "providers": ["ScoutPostgres\\ScoutPostgresServiceProvider"]
         }
     },
-    "minimum-stability": "dev",
     "prefer-stable": true
 }

composer.json

@@ -97,8 +97,8 @@
     |              FTS+trigram query only when FTS recall is insufficient.
     |              Cheapest on common queries; same recall as "hybrid" on
     |              typo / fuzzy queries via fallback.
-    | "hybrid"   — always run the FTS+trigram query in a single pass. The
-    |              pre-1.0 behaviour. Use to reproduce historical timings.
+    | "hybrid"   — always run the FTS+trigram query in a single pass.
+    |              Higher floor latency, no two-query fallback overhead.
     | "fts_only" — never use trigram. Loses typo tolerance but cuts the
     |              trigram-bitmap candidate-set cost on every query.
     */