Migrate remaining general-PostgreSQL guidance out of README.asc/CLAUDE.md into POSTGRES-NOTES.asc/CLAUDE-POSTGRES.md

[jnasbyupgrade]

Repo: pgxntool

Follow-up to #113, which established POSTGRES-NOTES.asc (human) and CLAUDE-POSTGRES.md (agent) as the home for guidance that is about PostgreSQL itself rather than about pgxntool. That PR only seeded them with the superuser/trusted material plus one orphaned agent rule; a survey of README.asc and CLAUDE.md turned up substantially more that arguably belongs there.

This issue is the inventory, not a decision. Each item needs a judgment call, because most of them are a general kernel wrapped in pgxntool-specific mechanism — splitting those means rewriting, not moving, and the pgxntool side still needs a pointer so the docs don't lose the thread.

Purely general — clean candidates to move

Where	What
README.asc 353–362	PGXN distribution vs extension (a distribution is what you upload to PGXN; an extension is what CREATE EXTENSION installs). Pure PGXN meta-spec. Last paragraph (362, "nothing generates one from the other", issue #47) is pgxntool's and stays.
README.asc 395–411	Why to commit each version's install script; when it's OK to skip one; why a skipped version should be rmed rather than .gitignored.
README.asc 413–428	Never hand-edit a shipped version file — frozen historical record, bump and add an upgrade script. 428 is already an explicit AI-agent caution and is a natural fit for CLAUDE-POSTGRES.md.
README.asc 451–460	Multiple-version file naming and upgrade-script convention.
README.asc 559–566, 586–598, 663–665	pg_tle background: what it is, pgtle_admin, trusted-languages-only / no C. Nothing to do with pgxntool.
CLAUDE.md 269	pg_tle requires PostgreSQL 14.5+.
CLAUDE.md 279	Duplicate of README.asc 413–428 — already duplicated today, so consolidating in one place is a win regardless.

General kernel inside pgxntool mechanism — needs a rewrite, not a move

Where	General part	pgxntool part that stays
README.asc 172–189	Update (ALTER EXTENSION … UPDATE) vs Upgrade (pg_upgrade) are the two transitions every multi-release extension goes through; running one unchanged suite against fresh/update/existing modes is the update-equivalence assertion.	test/install/, PGOPTIONS, test/expected/ paths
README.asc 193	Tests inside BEGIN;…ROLLBACK; never exercise a committed update, which is what production does — hides bugs like enum modification.	The rollback convention itself (test/pgxntool/setup.sql)
README.asc 223	"I STRONGLY recommend pgTap" — explicit pass/fail beats reading diffs; pg_regress is diff-based.	make test / make results framing
README.asc 227–233, CLAUDE.md 174–182	Never blindly promote actual output to expected; a human verifies diffs first. Universal pg_regress discipline, and the agent-facing half is a strong CLAUDE-POSTGRES.md candidate.	make results, test/expected/
README.asc 464–473	GNU Make wildcard caches a directory listing for the life of one make invocation, so a recursively-expanded variable can see a stale pre-generation listing; two workarounds. General GNU Make/PGXS knowledge.	DATA seeding, issue #44
README.asc 542–548	PGXS DOCS semantics (install into PREFIX/share/doc/extension).	base.mk forcibly defining it NULL
README.asc 480–482	Commit generated HTML so users get it on install.	pgxntool building it when Asciidoc is present
README.asc 199–202, 443, 445	pgTAP style (don't wrap assertions in plpgsql functions), testing into a non-default schema, upgrade scripts are hand-written, PGXN consumers need make+PGXS to build.	surrounding make dist / git archive text
CLAUDE.md 185–201	pg_regress mechanics (results/ vs expected/, how comparison works); MAJORVER = version × 10; --load-language=plpgsql below PG13; version detection via pg_config --version. All PostgreSQL/PGXS facts.	surfaced as pgxntool variables
CLAUDE.md 33–35, 172	"No AI attribution in commit messages"; "if PostgreSQL isn't running, stop and ask the user rather than improvising". Both are general agent rules.	the make test target name
CLAUDE.md 283–287	"Read each script's header comment rather than a hand-maintained list, which just goes stale." General documentation-hygiene principle.	applied to this repo's script list

Open questions

1. How aggressive should the split be? Moving everything above would gut the middle of README.asc and leave it a thin index. A narrower rule — move only what is purely general and has no pgxntool mechanism attached — keeps both files readable.
2. Duplication vs pointers. README.asc 413–428 and CLAUDE.md 279 already say the same thing twice. Whatever the split, that one should end up stated once.
3. README.html is a committed rendering of README.asc and is currently stale; any large README.asc restructuring should settle whether it stays committed at all.