README.asc: fix stale docs, document undocumented API surface

[jnasbyupgrade]

Summary

Follow-up from the new API documentation review process added in Postgres-Extensions/pgxntool-test#42. That PR's dry run compared README.asc against the actual code and found several real gaps — this PR fixes them.

Corrections to existing docs (README described something code no longer does, or never did):

• test's prerequisites no longer include clean (removed a while back — it broke incremental/watch-based builds); README still listed it. Also documents the conditional test-build dependency.
• verify-results safeguard only documented the regression.diffs check; the actual default (PGXNTOOL_VERIFY_RESULTS_MODE=pgtap) scans test output for pgTAP failures first, falling back to regression.diffs. Documents the variable and both modes.
• tag: dropped the claim that it creates an annotated tag (it's git tag NAME — lightweight), and documented the skip-if-already-at-HEAD idempotency, which wasn't mentioned anywhere.
• run-pgtle: corrected the claimed make-level dependency on check-pgtle — that check actually happens inside pgtle.sh itself at runtime.
• Document Rules: fixed an installcheck typo and corrected how html actually gets wired in (via all, not directly as a prerequisite of install/installcheck).
• ASCIIDOC_template code sample: matched the real ifeq (,$(strip $(ASCIIDOC))) check in base.mk — the doc still showed an old ifndef ASCIIDOC version.

New documentation for previously-undocumented items:

• dist/dist-only: the .gitattributes-must-be-committed safety check, and forcedist.
• list and print-% — pgxntool's own dev-helper targets.
• docclean.
• PGXNTOOL_NO_PGXS_INCLUDE.
• pgtle.sh's own CLI flags (--get-version, --get-dir, --run), not just the make targets that wrap them.
• pgxntool-sync: documents that every sync silently prunes pgxntool/.github and pgxntool/.claude from the consumer project (prune_pgxntool_dev_dirs() in lib.sh, added in Add Claude Code GitHub Actions workflows #41) — this had never been mentioned anywhere.

Deliberately left undocumented (per review): EXTRA_CLEAN += pg_tle/ (not worth a doc entry), and the internal conditional helper targets (clean-test-build, the install-schedule file target) that aren't meant to be invoked by hand.

No code changes — doc-only, so no HISTORY.asc entry.

Flag for review: the .gitattributes-must-be-committed note under dist documents dist-only's existing safety check based on reading its implementation — please confirm the explanation is accurate.

Test plan

• asciidoctor README.asc renders clean with no new warnings (one pre-existing unrelated xref warning, _Document_Handling, predates this change).
• Every corrected claim re-verified directly against current base.mk/pgtle.sh/lib.sh source.

🤖 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: e4efa06e-2681-407b-8413-d3febe7dcb0f

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

---

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