Curate PGXN documentation and validate the next published release

Problem

The published 0.2.8 PGXN page still overwhelms readers with development documents before they reach installation guidance. #373 achieved its intended reduction from 69 to 50 indexed documents (67 to 48 entries under Documentation), and #359 was closed after that result was confirmed. This follow-up improves the remaining user experience rather than reopening that completed work.

PGXN places Documentation before the embedded README. The current list includes implementation specs, proposals, testing plans, security-review workbooks, an old MVP guide, and many indistinguishable README links. The GitHub README also includes redundant navigation/badges and Markdown inside a raw HTML div that PGXN displays literally. Relative links and manually authored table-of-contents anchors can point to source files/directories instead of rendered documentation.

Scope

Target the next release, currently 0.2.9, with a tightly curated documentation list and a compact PGXN-specific README. Do not modify or republish the immutable 0.2.8 release.

• Aim for approximately 5-8 reader-facing entries, prioritizing the User Guide, API reference, changelog, HTTP security, examples overview, and installation/upgrade guidance. Record the exact selected set and expected displayed/indexed counts in the implementation PR.
• Exclude development-only material from indexing while retaining source files in the archive. Prefer a maintainable explicit publication policy; PGXN metadata itself supports no_index exclusions, not a native allowlist.
• Provide a compact PGXN README covering purpose, supported PostgreSQL versions, source-build prerequisites, installation, a quick example, and documentation links. Avoid GitHub-specific presentation, duplicate resource links, and development/CI material. Preserve the GitHub README and GitHub source-archive behavior.
• Keep required provides metadata and its User Guide association. Use links that reach the correct rendered documentation and release version; avoid duplicate manual navigation in the PGXN README.
• Add local coverage for generated metadata, the selected document set, bundle contents, version consistency, and the distinction between indexing exclusions and archive removal. Update the release procedure to point to this post-publication gate.

PGXN site-wide layout, sorting, and single-extension presentation changes are outside this implementation's scope.

Implementation checklist

• Implementation PR #395 linked here and merged for the target release.
• Exact curated document set and expected indexed/displayed counts recorded in #395.
• PGXN-specific README and version-aware documentation destinations reviewed in #395.
• Metadata and packaged-artifact coverage added in #395; GitHub README/source archives remain unaffected.
• Next-release tracking issue links this issue as a post-publication gate.

Post-release acceptance criteria

Keep this issue open after the implementation PR merges. Reference it with Related to, not Closes/Fixes. Close only after the published PGXN artifact satisfies the checks below. If the changes miss 0.2.9, update the target release here.

• Record the published PGXN version, immutable release commit, distribution URL, and metadata URL.
• The published docs index matches the agreed curated set, with no unintentionally indexed development documents. Account for PGXN displaying the provided User Guide under Extensions and embedding the root README separately.
• The public Documentation list is short and contains the intended user-facing entries.
• The embedded README is the compact PGXN version, not the GitHub landing page; headings, links, and code blocks render without literal Markdown/HTML artifacts.
• README installation instructions and documentation links work from the published page and point to the intended release/docs. User Guide remains accessible through Extensions.
• The downloaded PGXN archive retains excluded source documents and contains matching release metadata; GitHub source assets and README retain their intended content.
• Add a final evidence comment with URLs/counts and close this issue.

References

• #373: original indexing reduction and PGXN install documentation
• #359: original hardening, completed after 0.2.8 publication
• #384: completed 0.2.8 release
• #392: start of the 0.2.9 development cycle
• #395: curated PGXN documentation and compact PGXN README implementation
• PGXN 0.2.7 baseline
• PGXN 0.2.8 baseline
• PGXN distribution metadata

Review the merged implementation in PR #395, then inspect the published PGXN distribution page and metadata URL for the target release. Compare the docs index, embedded README, links, counts, archive contents, and release metadata against the acceptance criteria; record evidence and close the issue when all checks pass.