docs(packages): link canonical examples and clarify registry submission for community packages

[joeduffy]

Fixes #11611

The "Overview, installation, & configuration" section of the Publishing to the Pulumi Registry guide described what authors should write in _index.md and installation-configuration.md, but gave no concrete examples and did not explain where these files ultimately need to go.

This PR makes two changes:

1. Adds links to canonical community provider examples (ImprovMX and Logfire) after the existing description of _index.md and installation-configuration.md, so authors have real, well-authored references to model their docs on.

2. Adds a clarifying note that while these files are authored in the provider repository's docs/ folder, they are submitted to pulumi/registry under themes/default/content/registry/packages/<package>/ as part of the registry submission PR.

3. Updates the "Publish the documentation" steps to include an explicit step for adding _index.md and installation-configuration.md to the registry repository (this step was previously missing), and links to pulumi/registry#10358 as a complete worked example.

---

🧠 This PR was created by workprentice on behalf of @joeduffy.

[github-actions]

Pre-merge Review — Last updated 2026-05-24T14:18:42Z

Tip

Summary: This PR adds 6 lines (and removes 1) to the existing publishing-packages.md guide: it points readers at two canonical community-provider examples (ImprovMX, Logfire), clarifies that files authored in a package repo's docs/ folder are republished through the pulumi/registry repo, and adds a missing step to the registry submission checklist along with a reference PR (pulumi/registry#10358). The main reader-impacting risk is link correctness — two of the new directory pointers use GitHub's /blob/<branch>/<dir>/ URL form (the verifier got HTTP 400 on one), where the conventional form is /tree/<branch>/<dir>/. Investigative passes that ran: external URL/claim verification on 4 claims, frontmatter & alias sweep, and cross-sibling reads against 6 peer pages in the same packages/ folder.

Review confidence:

Dimension	Level	Notes
mechanics	HIGH
facts	MEDIUM	One high-confidence "contradicted" URL (malformed directory link). Two unverifiable claims, both due to verifier-side body truncation, not because the underlying claim is wrong.
cross-sibling consistency	HIGH	Six peer pages in the same folder read; no contradictions on registry paths or workflow. Sibling style note (siblings consistently use /tree/ for directory links) folded into the 🚨 fix below.

Investigation log

• Cross-sibling reads: 6 of 6 siblings
• External claim verification: 1 of 4 claims verified (2 unverifiable, 1 contradicted) · 4 specialists (numerical, cross-reference, capability, framing); 0 cross-specialist corroborations · routed: 0 inline, 1 Pass 1, 3 Pass 2 (verified 0, contradicted 1, unverifiable 2), 0 Pass 3.
• Cited-claim spot-checks: 3 of 3 cited claims fetched and compared
• Frontmatter sweep: ran on body + meta_desc
• Temporal-trigger sweep: not run (no trigger words)
• Code execution: not run (no static/programs/ change)
• Code-examples checks: not run (no fenced code blocks in content files)
• Editorial-balance pass: not run (not under content/blog/)

🚨 Outstanding	⚠️ Low-confidence	💡 Pre-existing	✅ Resolved
1	2	0	0

🔍 Verification trail

4 claims extracted · 1 verified · 2 unverifiable · 1 contradicted

• L96 in content/docs/iac/guides/building-extending/packages/publishing-packages.md "The ImprovMX community provider has an installation-configuration.md file at https://github.com/pulumi/registry/blob/master/themes/default/content/registry/p…" → ❌ contradicted (evidence: The cited URL https://github.com/pulumi/registry/blob/master/themes/default/content/registry/packages/improvmx/ returns HTTP 400 Bad Request with an empty body, meaning the resource cannot be confirmed to exist at that path.; source: https://github.com/pulumi/registry/blob/master/themes/default/content/registry/packages/improvmx/)
• L98 in content/docs/iac/guides/building-extending/packages/publishing-packages.md "Package documentation files authored in a package repository's docs/ folder are published through the pulumi/registry GitHub repository, under themes/defa…" → 🤷 unverifiable (evidence: The pre-fetched body of https://github.com/pulumi/registry is truncated to just the page title/meta snippet and does not contain any content about the themes/default/content/registry/packages//` path or the docs publishing w…; source: https://github.com/pulumi/registry)
• L139 in content/docs/iac/guides/building-extending/packages/publishing-packages.md "The process for publishing a community package to the Pulumi Registry involves: (1) adding the package to the community package list at https://github.com/pulu…" (also L143) → 🤷 unverifiable (evidence: The pre-fetched URL (Add logfire community package registry#10358) returned HTTP 200 but the body is truncated to just a <link> tag with no usable content — the PR description/diff cannot be read to verify or contradict the three-step p…; source: Add logfire community package registry#10358)
• L142 in content/docs/iac/guides/building-extending/packages/publishing-packages.md "When submitting a community package to the Pulumi Registry, documentation files must be added to themes/default/content/registry/packages/<your-package>/, in…" → ✅ verified (evidence: The file at content/docs/iac/guides/building-extending/packages/publishing-packages.md states: "Although you author these files in your package repository's docs/ folder, they are published through the [pulumi/registry GitHub reposit…; source: repo:content/docs/iac/guides/building-extending/packages/publishing-packages.md)

🚨 Outstanding in this PR

These must be resolved or refuted before merging.

• [L96] content/docs/iac/guides/building-extending/packages/publishing-packages.md — "The ImprovMX community provider has an installation-configuration.md file at https://github.com/pulumi/registry/blob/master/themes/default/content/registry/p…" — verdict: contradicted; evidence: HTTP 400 on https://github.com/pulumi/registry/blob/master/themes/default/content/registry/packages/improvmx/. The reason is that two of the new directory pointers use GitHub's /blob/<branch>/<dir>/ form, which is reserved for files — directories should use /tree/<branch>/<dir>/. Sibling pages in this same packages/ folder (e.g., pulumi-go-provider-sdk.md, schema.md) consistently use /tree/ for directory references, so this is also a local-style outlier. The two file URLs that follow (_index.md, installation-configuration.md) correctly use /blob/ and resolve fine.

  Suggested rewrite of the new L96 paragraph:

  For reference, the [ImprovMX](https://github.com/pulumi/registry/tree/master/themes/default/content/registry/packages/improvmx) community provider is a well-authored example: see its [`_index.md`](https://github.com/pulumi/registry/blob/master/themes/default/content/registry/packages/improvmx/_index.md) and [`installation-configuration.md`](https://github.com/pulumi/registry/blob/master/themes/default/content/registry/packages/improvmx/installation-configuration.md). The [Logfire provider](https://github.com/pulumi/registry/tree/master/themes/default/content/registry/packages/logfire) is another recent example.
  

⚠️ Low-confidence

Review each and resolve as appropriate — these don't block the PR.

• [L98] content/docs/iac/guides/building-extending/packages/publishing-packages.md — *"Package documentation files authored in a package repository's docs/ folder are published through the pulumi/registry GitHub repository, under themes/defa…"* — verdict: unverifiable; evidence: The pre-fetched body of https://github.com/pulumi/registry is truncated to just the page title/meta snippet and does not contain any content about the themes/default/content/registry/packages//path or the docs publishing w…; source: https://github.com/pulumi/registry. This is a verifier-side truncation, not evidence the claim is wrong — the same path is independently confirmed by the verified L142 claim ("documentation files must be added tothemes/default/content/registry/packages//"), and the workflow is self-described on this page. Question for author: confirm that themes/default/content/registry/packages//is still the canonical destination for community-package docs in the currentpulumi/registry` repo layout (no recent restructure).

• [L139] content/docs/iac/guides/building-extending/packages/publishing-packages.md — "The process for publishing a community package to the Pulumi Registry involves: (1) adding the package to the community package list at https://github.com/pulu…" — verdict: unverifiable; evidence: The pre-fetched URL (Add logfire community package registry#10358) returned HTTP 200 but the body is truncated to just a <link> tag with no usable content — the PR description/diff cannot be read to verify or contradict the three-step p…; source: Add logfire community package registry#10358. Verifier-side truncation again. The three-step process is the docs' own definition; the PR URL is only an illustrative example. Question for author: confirm that pulumi/registry#10358 is a representative community-package submission you want readers to follow as a model (e.g., it actually touches the community-package list + the themes/default/content/registry/packages/<pkg>/ folder), and that it's still accessible / not a closed-without-merge PR that could mislead a reader.

💡 Pre-existing issues in touched files (optional)

No pre-existing issues in touched files.

✅ Resolved since last review

No items resolved since the last review.

📜 Review history

• 2026-05-24T14:18:42Z — One blocker: two new directory pointers use /blob/ where /tree/ is correct (one returned HTTP 400). Two unverifiable claims are verifier-side truncations, not factual issues. (2c7271c)

---

Need a re-review? Want to dispute a finding? Mention @claude and include #update-review.
(For ad-hoc questions or fixes, just @claude — no hashtag.)

[pulumi-bot]

Your site preview for commit 2c7271c is ready! 🎉

http://www-testing-pulumi-docs-origin-pr-19384-2c7271c9.s3-website.us-west-2.amazonaws.com