Add plugins concept page and integrate plugin references across docs

[jkodroff]

Fixes #16325

This change introduces a new concept page explaining Pulumi's plugin architecture and updates related documentation to reference it. The plugins page covers all five plugin types (resource, language, analyzer, converter, and tool plugins), installation and management, and implementation details.

Related documentation updates:

• how-pulumi-works.md: Add reference to language plugins
• providers.md: Explain providers as resource plugins
• converters.md: Reference converter plugins and clarify standalone tools
• policy/_index.md: Reference analyzer plugins

🤖 Generated with Claude Code

[claude]

Documentation Review

Thank you for this comprehensive plugins concept page! This is a valuable addition that will help users understand Pulumi's plugin architecture. I've reviewed the changes and have the following feedback:

Issues Found

1. Inconsistent terminology in converters.md (lines 48-51)

The heading says "Additional conversion tools and resources" and the text says "standalone tools," but the listed items include both web tools and actual converters. The crd2pulumi link goes to a blog post (not a web conversion tool like the others were), and cf2pulumi goes to a web tool.

Suggestion: Clarify this section to be more consistent. Consider:

### Additional conversion tools and resources

In addition to the converter plugins, Pulumi offers the following web-based conversion tools:

* [CloudFormation to Pulumi](/cf2pulumi/)

For information about converting Kubernetes CustomResources, see the [crd2pulumi blog post](/blog/introducing-crd2pulumi/).

2. Minor grammar issue in converters.md (line 19)

"allows you translate" is missing "to"

Current (line 19):

The `pulumi convert` command allows you translate supported sources

Should be:

The `pulumi convert` command allows you to translate supported sources

(Note: This appears to already be fixed in the diff, so this may not be an issue.)

3. Heading capitalization consistency

All H2 and H3 headings follow sentence case correctly throughout. ✓

4. List formatting in plugins.md

Lines 65-68 use different list item formats. The first item has parenthetical text, while others don't. Consider making them more parallel.

Current (lines 65-68):

- **Resource plugins** (provider binaries) are installed automatically when you install dependencies in a Pulumi program using your language's package manager (e.g., `npm install`, `pip install`)
- **Language plugins** are installed with the Pulumi CLI
- **Policy plugins** are installed with the Pulumi CLI
- The Pulumi CLI ensures your resource plugins are present when you run your Pulumi program

Suggestion:

- **Resource plugins** (providers) are installed automatically when you install dependencies using your language's package manager (e.g., `npm install`, `pip install`)
- **Language plugins** are installed with the Pulumi CLI
- **Policy plugins** are installed with the Pulumi CLI
- **Converter plugins** are installed automatically when you run the `pulumi convert` command

This makes the list more comprehensive and parallel.

Positive Observations

• All files end with newlines ✓
• No trailing spaces detected ✓
• Frontmatter is properly formatted ✓
• Meta descriptions are appropriate length ✓
• Links use descriptive text (no "click here") ✓
• Headings follow proper hierarchy ✓
• Terminology is consistent with existing docs ✓
• Cross-references are appropriate and helpful ✓
• The new plugins page integrates well with existing documentation ✓
• Good use of the notes shortcode to set expectations ✓

Overall Assessment

This is a well-written and comprehensive addition to the documentation. The plugins concept page provides valuable context about Pulumi's architecture. The integration points with existing docs are well-chosen. After addressing the minor issues above, this will be ready to merge.

---

Mention @claude if you'd like me to review again after making changes or if you need help with any fixes.

[pulumi-bot]

Your site preview for commit a70ee6b is ready! 🎉

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

[pulumi-bot]

Your site preview for commit fd482ca is ready! 🎉

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

[pulumi-bot]

Your site preview for commit d52da46 is ready! 🎉

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

[CamSoper]

I can't speak as to the accuracy of the information, but I see no issues in the presentation.

[pulumi-bot]

Your site preview for commit d41edb9 is ready! 🎉

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

[pulumi-bot]

Your site preview for commit 1c44a44 is ready! 🎉

http://www-testing-pulumi-docs-origin-pr-16406-1c44a441.s3-website.us-west-2.amazonaws.com.

[pulumi-bot]

Your site preview for commit d23eaa6 is ready! 🎉

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

[pulumi-bot]

Your site preview for commit d945678 is ready! 🎉

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

[pulumi-bot]

Your site preview for commit ea201df is ready! 🎉

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

[pulumi-bot]

Your site preview for commit 0cbd400 is ready! 🎉

http://www-testing-pulumi-docs-origin-pr-16406-0cbd4002.s3-website.us-west-2.amazonaws.com.

[pulumi-bot]

Your site preview for commit 897be87 is ready! 🎉

http://www-testing-pulumi-docs-origin-pr-16406-897be873.s3-website.us-west-2.amazonaws.com.

[pulumi-bot]

Your site preview for commit 9800516 is ready! 🎉

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

[pulumi-bot]

Your site preview for commit 2b60072 is ready! 🎉

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