Docs/discoverability for agents: fix make-test exit-status claim; help AIs read the shipped docs

[jnasbyupgrade]

Docs/discoverability improvements to help agents (and humans) do non-trivial work

Feedback from an AI (Claude) doing fairly sophisticated work in a pgxntool
consumer project (cat_tools). The docs here are actually good — this is mostly
about discoverability plus one concrete inaccuracy. Filed at the
maintainer's request to improve AI results with pgxntool.

1. CLAUDE.md mis-describes make test's exit behavior (please fix — highest impact)

Duplicate of #35 — the exit-status bug itself is tracked there; item 1 below is left for reference only.

CLAUDE.md (Key Implementation Details → Test System) says:

.IGNORE: installcheck allows make test to handle errors (show diffs, then exit with error status)

That's backwards. .IGNORE: installcheck makes Make ignore installcheck's non-zero exit, and the test recipe only cats regression.diffs — so make test returns 0 even when tests fail. Verified in practice: a consumer's CI showed "2 of 13 tests failed" while the job's make test step still passed (green). verify-results is the actual gate, and only guards make results, not make test — so CI that runs make test does not fail on a regression unless it also runs a check (e.g. make verify-results).

This is the single most consequential thing for an agent to get right (it determines whether CI catches test regressions), and the current wording asserts the opposite. Suggest correcting it and, ideally, a one-liner: "to make CI fail on a regression, run make verify-results after make test (or check for regression.diffs)."

2. Discoverability: agents in a consumer repo don't see these docs

pgxntool is embedded as a nested pgxntool/ subtree. An agent working in the
consumer project loads the project's CLAUDE.md, not pgxntool/CLAUDE.md or
pgxntool/README.asc (nested, not auto-loaded). So for non-trivial build/test
work it tends to reverse-engineer base.mk and gets things wrong. Concretely, I
conflated DATA as a pgxntool variable when it's PGXS's (pgxntool only seeds
it), and I re-derived test/install's "state persists into the suite" behavior
that README.asc already documents.

Ideas (leaving specifics to you):

• Have setup.sh add (or suggest) a line in the consumer's own CLAUDE.md like:
  "For any non-trivial build/test work, read pgxntool/README.asc and
  pgxntool/CLAUDE.md first." A pointer from the auto-loaded file is what closes
  the gap.
• A short, prominent "mental model for agents" section distinguishing what's
  PGXS (DATA, MODULES, DOCS, installcheck, …) from what pgxntool
  adds/wraps (test, test-build, test/install, verify-results, version-file
  generation, pgxntool-sync). Misattributing that boundary was my main source
  of confusion.

3. Related, already filed

• DATA's parse-time $(wildcard) misses generated (gitignored) versioned SQL #44 — DATA's parse-time $(wildcard) misses generated (gitignored) SQL.
• Document (and maybe support) testing ALTER EXTENSION UPDATE via test/install #42 — documenting the test/install ALTER-UPDATE equivalence pattern.

Net: the framework is well documented; the gap is (a) the one wrong line about
make test exit status, and (b) getting an agent to actually read the shipped
docs before doing sophisticated work.

[jnasbyupgrade]

Follow-up: have pgxntool proactively close the discoverability gap

Beyond fixing/adding docs, pgxntool could actively nudge consumers to wire agents up correctly — since the failure mode is precisely that an agent never reads the (nested, not-auto-loaded) pgxntool docs:

1. Recommend it in pgxntool's own docs. README/CLAUDE.md should explicitly recommend that any project using pgxntool with an AI assistant add an instruction, in its agent config, to read pgxntool/README.asc + pgxntool/CLAUDE.md before non-trivial build/test work (and call out the PGXS-vs-pgxntool boundary and the make test exit-status behavior).

2. Have setup.sh and pgxntool-sync.sh check + warn. On initial embed and on every sync, scan the consumer repo for standard agentic-config files — not just CLAUDE.md, but e.g. AGENTS.md, .cursor/rules/* / .cursorrules, .github/copilot-instructions.md, .clinerules, .windsurfrules, GEMINI.md, .aider*. If any exist but none reference pgxntool/CLAUDE.md (or the pgxntool docs), print a non-fatal warning recommending they add a pointer. This turns "the agent didn't know to read the docs" into a one-time, visible setup nudge rather than a silent gap each project rediscovers.

Rationale: in the cat_tools work that prompted this, the agent (me) worked from base.mk fragments and never opened the shipped docs — a warning at setup/sync time, plus a recommended pointer in the consumer's agent config, would have prevented it. Keeping this on #45 since it's the same discoverability root; happy to split into its own issue if you'd rather track the tooling change separately.