Document superuser/trusted; split general PostgreSQL guidance into its own docs

[jnasbyupgrade]

Neither README.asc nor CLAUDE.md mentioned the .control file parameters that decide who may run CREATE EXTENSION. This adds that, but in new files rather than in the existing docs — the material is about PostgreSQL itself, not about pgxntool, and mixing the two blurs which claims pgxntool is actually responsible for.

New files

POSTGRES-NOTES.asc (human-facing) — short section on who can install an extension:

• superuser = false drops the superuser requirement outright; the install/update script then runs as the caller, who must already hold every privilege it needs — nothing is granted implicitly.
• trusted = true lets any non-superuser with CREATE on the database install it, but runs the script as the bootstrap superuser. Only consulted when superuser is true; PG13+.
• Carries the security warning and links PostgreSQL's own Security Considerations for Extensions, plus the reference entries for both parameters.
• Notes that superuser = false is usually the better of the two when the extension doesn't need superuser-only capabilities.

CLAUDE-POSTGRES.md (agent-facing) — the rule this PR was actually requested for:

Whenever you bring up the trusted control-file parameter you MUST in the same breath also (1) offer superuser = false as the alternative, and (2) state that trusted = true carries security consequences, pointing at PostgreSQL's docs rather than reassuring the reader yourself.

One-directional: mentioning superuser = false alone is fine. The rationale is spelled out — trusted = true is the fastest-to-mind answer to "how do I let a non-superuser install this?", so raising it bare reads as a recommendation for what is really a privilege-escalation surface.

Wiring

• README.asc gains a == General PostgreSQL Notes section pointing at POSTGRES-NOTES.asc.
• CLAUDE.md gains a scope sentence plus a ## Read CLAUDE-POSTGRES.md section with an @CLAUDE-POSTGRES.md import, so the rules load automatically where that's supported and are still findable where it isn't.
• The orphaned "never produce metrics or estimates without data" bullet moves from the bottom of CLAUDE.md's Related Repositories list into CLAUDE-POSTGRES.md. It is purely general agent guidance with no connection to pgxntool, and it was sitting under a heading it had nothing to do with.

.gitattributes needs no change: *.asc and *.md are already export-ignore, so both new files reach subtree consumers but not PGXN distributions.

Notes for review

• Doc-only, so CI's doc-only bypass skips the paired-test requirement and the Postgres matrix. The paired pgxntool-test PR exists anyway, for the API-surface bookkeeping.
• README.html was not regenerated. It is already two README.asc commits stale on master, so regenerating here would fold unrelated drift into this diff. Worth handling separately.
• The docs survey behind this PR found a fair amount of other general-PostgreSQL material still embedded in README.asc/CLAUDE.md (extension versioning discipline, pg_regress mechanics, pg_tle background, the pgTAP recommendation, the GNU Make wildcard caching quirk). None of it moved here — that would make this diff unreviewable. Listed in the PR discussion for a follow-up decision.

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. 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: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 5f5a6987-7131-4e73-8e95-f4a43eeb9694

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

---

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.}