docs: prune obsolete process docs, consolidate SQL doc guidance, fix scalar-domain reference

[tobyhede]

What

Documentation-only cleanup of the developer/reference docs. No code, build, or behaviour changes.

Prune obsolete process docs; consolidate SQL doc guidance (6480636a)

• Removes the completed-effort reference-sync cluster (documentation-blockers, documentation-questions, reference-sync-notes, reference-sync-rules) — empty stubs and a self-referential rules doc with no live consumer.
• Merges sql-documentation-standards + sql-documentation-templates into a single docs/development/sql-documentation.md, cross-linked to CLAUDE.md as the source of truth. Drops the dead Operator Class / Composite Type templates that contradicted the v3 jsonb-domain footgun rules.
• Updates the stale reference-sync example in docs_v3_grep.sh's comment.

Correct inaccuracies in scalar encrypted-domain reference (57428738)

Verification pass over docs/reference/adding-a-scalar-encrypted-domain-type.md:

• Drops the stale "codegen gates the PostgreSQL test matrix" claim (the gate was removed).
• Fixes filename pin_search_path.sql → pin_search_path_v3.sql (5 refs).
• Fixes non-compiling example int_values!(.., INT4) → INT4_FIXTURES.
• Rewrites section 6 stage-4 to match generate_type (ensure_generated_paths_writable → write_generated_file → remove_generated_orphans).
• Corrects text domain count (five → six), operator wording, and the intro reference range.
• Misc precision nits (text pivots, SignedScalar for timestamptz, binding output paths, int_values! location, splinter labels, self-containment gate pointer).

Diff

9 files changed, +346 / −484 — net removal of dead process docs.

Review note

A CodeRabbit pass flagged 19 issues, but all of them are in docs/presentations/, an untracked POC directory (vendored reveal.js/Quarto bundles) that is not part of this branch. This PR's actual diff produced zero findings.

Summary by CodeRabbit

• New Features
  • Added a new guide for writing SQL documentation, including examples and ready-to-use templates.
• Documentation
  • Updated several development and reference docs to match the current workflow, catalog structure, and test coverage.
  • Clarified regeneration, validation, and CI behavior for generated assets and matrix test inventories.
  • Removed outdated documentation pages and templates that are no longer needed.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 02e44bd9-980d-41d9-bb1c-e9e5ffcd4fb0

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/dev-cleanup

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

🧹 Nitpick comments (1)

docs/development/sql-documentation.md (1)

13-13: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Hyphenate the compound modifier.

"One sentence description" should be "one-sentence description" when used as a compound modifier before a noun.

- - `@brief` - One sentence description
+ - `@brief` - One-sentence description

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/development/sql-documentation.md` at line 13, Update the SQL
documentation wording so the `@brief` entry uses the hyphenated compound
modifier form; in the documentation text around `@brief`, change the phrase
describing it from “One sentence description” to “one-sentence description” when
it modifies the noun.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@docs/development/sql-documentation.md`:
- Line 13: Update the SQL documentation wording so the `@brief` entry uses the
hyphenated compound modifier form; in the documentation text around `@brief`,
change the phrase describing it from “One sentence description” to “one-sentence
description” when it modifies the noun.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 6ad5c0b0-386d-41f5-9e34-db9af9b4736f

📥 Commits

Reviewing files that changed from the base of the PR and between 746ad83 and 5742873.

📒 Files selected for processing (9)

• docs/development/documentation-blockers.md
• docs/development/documentation-questions.md
• docs/development/reference-sync-notes.md
• docs/development/reference-sync-rules.md
• docs/development/sql-documentation-standards.md
• docs/development/sql-documentation-templates.md
• docs/development/sql-documentation.md
• docs/reference/adding-a-scalar-encrypted-domain-type.md
• tasks/test/docs_v3_grep.sh

💤 Files with no reviewable changes (6)

• docs/development/sql-documentation-templates.md
• docs/development/sql-documentation-standards.md
• docs/development/documentation-questions.md
• docs/development/reference-sync-rules.md
• docs/development/documentation-blockers.md
• docs/development/reference-sync-notes.md