Docs audit: errors and gaps across the reference, tutorial, and upgrade docs

[coderdan]

A full audit of this repo's documentation — every claim verified against the src/v3 SQL source and the shipped @cipherstash/eql 3.0.2 bundle — surfaced ~70 findings across 16 files. This issue tracks resolving them; #419 is the fix PR.

The audit was prompted by the equality-on-ordering-domain errors fixed in #418: the same verification pass applied to the rest of the docs found the problems were not isolated.

Finding classes

1. Copy-pasteable SQL that fails when run — the GIN containment recipe is a PostgreSQL syntax error (missing parens around the cast expression) in three docs; query operands cast to storage domains whose CHECK rejects term-only payloads; text match spelled @> (raises since U-008) in the tutorial and README; the README's GRANT ALTER ON ALL TABLES is not valid PostgreSQL; a "must succeed" verification snippet in the v3.0 guide fails its own domain CHECK; contributor-doc worked examples predate the eql_v3_internal split and the v=3 pin.
2. Injectivity residue — the class of error docs: equality on ordering domains splits on term injectivity #418 fixed, in the places it missed: eql-functions' equality prose, database-indexes' field-level eq_term recommendation and GROUP BY recipe, text_ord_ope absent from every hm-domain enumeration, and — most importantly — the domain-generation rule in adding-a-scalar-encrypted-domain-type.md §2, which as written would generate silently-wrong = for a future string-like scalar.
3. Permissions — permissions.md had no install-privileges section at all (the superuser-gated ORE opclass, per-platform support, the extension-vs-opclass distinction) and over-claimed the eql_v3_internal grant for JSON writes (the validators are deliberately public); the README permissions section needed replacing.
4. Operational traps undocumented — re-running the installer cascade-drops every functional index built on the eql_v3 extractors (while the README called it "idempotent"); the uninstaller's atomicity/lock claims only hold under psql --single-transaction; the ORE opclass skip is a NOTICE, not silent.
5. Stale/phantom surfaces — removed jsonb_array_elements_text still documented; bare eql_v3_json presented as searchable; SchemaVersion = 2; wrong operator/file counts; the 39-domain eql_v3.query_* operand family and the json_entry generated surface undocumented; eql_v3.version() / eql_v3.lints() undocumented; the eql-bindings README term table missing op and mis-scoping ob.

Follow-ups not covered by the fix PR

• Confirm the cipherstash-client 0.38.1+ claim in upgrading/v3.0.md (not verifiable from this repo).
• Confirm the external docs-site link cipherstash.com/docs/stack/cipherstash/encryption/schema used in the tutorial and README.
• Confirm the Proxy pt-envelope version ("v":3) in the proxy tutorial.
• Verify on a live RDS-for-PostgreSQL (non-Aurora) instance whether rds_superuser can CREATE OPERATOR CLASS Resolved: confirmed — multiple CipherStash customers run ORE with custom operator classes on RDS in production. The permissions table row is upgraded in the fix PR (ce132f4); AWS release-notes the delegation only for Aurora, so the probe stays available for the doubtful.