Problem
pgxntool ships extensive, genuinely valuable documentation in README.asc and CLAUDE.md - including hard-won guidance like the update+upgrade (U&U) testing pattern (#42), working examples, and even project-specific critiques (e.g. the U&U section notes that pg_count_nulls' own historical test/sql/extension_tests.sql demonstrates schema-targeting, but explicitly warns not to copy its plpgsql-function-based assertion style as a model). None of that is discoverable to an AI agent working in a project that has pgxntool embedded via git subtree, unless the agent happens to read the entire README.asc up front - which in practice it usually doesn't, since most of that file (build system internals, PGXN packaging, asciidoc generation, pgtle_versions.md interactions, etc.) is irrelevant to whatever the agent's current task actually is.
Concretely: while adding update+upgrade test coverage to pg_count_nulls, an agent spent real effort independently reverse-engineering cat_tools' test/install mechanics from its raw source, before discovering that pgxntool's own README.asc already documented the exact pattern end-to-end (mode-switching via current_setting()/PGOPTIONS, why the install must be committed not rolled back, two worked examples, and the caveat above) - it was there the whole time, just never surfaced.
The obvious fix - having the consuming project's own CLAUDE.md blanket-@-include pgxntool/README.asc - has a real cost: the file is long, and most of it is irrelevant to any given task. Doing that on every single agent turn burns tokens regardless of relevance.
Proposed solution
Ship a small, cheap-to-read "index"/"trigger" file (a few dozen lines, not the documentation itself) whose only job is mapping task context to "go read section X of README.asc (or CLAUDE.md)" - a table of contents with trigger conditions, not the content. For example:
- Writing or changing tests, especially update/upgrade testing? -> read the
test/install and "Update & Upgrade (U&U) Testing" sections of README.asc.
- Cutting a release? -> read the relevant release-process section.
- etc., one line per topic, growing over time as new sections get added.
This could live as a new short section inside the existing pgxntool/CLAUDE.md (already excluded from distribution via .gitattributes export-ignore, already the recognized "AI assistant guidance, for people USING pgxntool" file), or as its own tiny sibling file - happy to defer to maintainers on the exact shape. The key property is that it should be cheap enough to read by default every time, while only pointing at the expensive stuff rather than either omitting it entirely or inlining it wholesale.
Why this matters beyond one project
Every extension repo that embeds pgxntool has the identical problem: agents working in any of them are equally unaware that README.asc already has answers, until they happen to read the whole thing. A single small pointer file living in pgxntool itself would fix this for every consuming project at once, rather than each project inventing its own ad hoc cross-reference (or, worse, each project's agents independently re-deriving guidance pgxntool already documented).
Related: #42, whose own U&U section is the specific content that went undiscovered in the case above.
Problem
pgxntool ships extensive, genuinely valuable documentation in
README.ascandCLAUDE.md- including hard-won guidance like the update+upgrade (U&U) testing pattern (#42), working examples, and even project-specific critiques (e.g. the U&U section notes that pg_count_nulls' own historicaltest/sql/extension_tests.sqldemonstrates schema-targeting, but explicitly warns not to copy its plpgsql-function-based assertion style as a model). None of that is discoverable to an AI agent working in a project that has pgxntool embedded viagit subtree, unless the agent happens to read the entireREADME.ascup front - which in practice it usually doesn't, since most of that file (build system internals, PGXN packaging, asciidoc generation,pgtle_versions.mdinteractions, etc.) is irrelevant to whatever the agent's current task actually is.Concretely: while adding update+upgrade test coverage to
pg_count_nulls, an agent spent real effort independently reverse-engineeringcat_tools'test/installmechanics from its raw source, before discovering that pgxntool's ownREADME.ascalready documented the exact pattern end-to-end (mode-switching viacurrent_setting()/PGOPTIONS, why the install must be committed not rolled back, two worked examples, and the caveat above) - it was there the whole time, just never surfaced.The obvious fix - having the consuming project's own
CLAUDE.mdblanket-@-includepgxntool/README.asc- has a real cost: the file is long, and most of it is irrelevant to any given task. Doing that on every single agent turn burns tokens regardless of relevance.Proposed solution
Ship a small, cheap-to-read "index"/"trigger" file (a few dozen lines, not the documentation itself) whose only job is mapping task context to "go read section X of README.asc (or CLAUDE.md)" - a table of contents with trigger conditions, not the content. For example:
test/installand "Update & Upgrade (U&U) Testing" sections of README.asc.This could live as a new short section inside the existing
pgxntool/CLAUDE.md(already excluded from distribution via.gitattributes export-ignore, already the recognized "AI assistant guidance, for people USING pgxntool" file), or as its own tiny sibling file - happy to defer to maintainers on the exact shape. The key property is that it should be cheap enough to read by default every time, while only pointing at the expensive stuff rather than either omitting it entirely or inlining it wholesale.Why this matters beyond one project
Every extension repo that embeds pgxntool has the identical problem: agents working in any of them are equally unaware that
README.ascalready has answers, until they happen to read the whole thing. A single small pointer file living in pgxntool itself would fix this for every consuming project at once, rather than each project inventing its own ad hoc cross-reference (or, worse, each project's agents independently re-deriving guidance pgxntool already documented).Related: #42, whose own U&U section is the specific content that went undiscovered in the case above.