Enhance project file documentation for infra Pulumi YAML

[pose]

Fixes #16674

Expanded explanation of the project file's role in Pulumi YAML programs by adding details about top-level attributes. For example, this should make easier to discover where to find documentation for the resources property.

[claude]

Documentation Review

I've reviewed the changes in this PR. The enhancement adds helpful context about Pulumi YAML's top-level attributes (resources, variables, and outputs) in the project file documentation.

✅ Strengths

• Good addition: The specific examples of top-level attributes (resources, variables, outputs) make it easier for users to discover relevant documentation
• Link validity: The link to /docs/iac/languages-sdks/yaml/yaml-language-reference/ correctly points to the YAML language reference documentation
• Addresses the issue: This change directly addresses issue Document resource attribute on Pulumi.yaml #16674 by providing more discoverable information about the resources property

📝 Suggestions

Line 25: Consider rewording for better clarity

The phrase "top-level attributes related to infrastructure" could be more precise. Consider:

For Pulumi programs specifically written in Pulumi YAML, the project file not only serves as a configuration and metadata repository but also contains the program's infrastructure definition itself. For instance, `resources`, `variables`, and `outputs` are [top-level properties that define your infrastructure](/docs/iac/languages-sdks/yaml/yaml-language-reference/). To learn more, see [Pulumi YAML](/docs/intro/languages/yaml/).

Rationale:

• "top-level properties" is more technically accurate than "top-level attributes" (the YAML spec refers to them as properties in the table)
• "that define your infrastructure" is more direct than "related to infrastructure"

Summary

The change is technically accurate and improves discoverability. The minor wording suggestion above is optional but would improve precision and clarity.

---

If you'd like me to apply the suggested changes or perform additional reviews, mention me (@claude) in a comment.

[pulumi-bot]

Your site preview for commit b0e24cc is ready! 🎉

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

[pose]

@claude apply the suggested changes

[claude]

Claude finished @pose's task —— View job

---

Applying Suggested Changes

I've successfully applied the wording improvements from my previous review.

Tasks

• Read the current file state
• Apply the suggested wording changes
• Commit and push the changes

Changes Made

Updated line 25 in content/docs/iac/concepts/projects/project-file.md:

• Changed "top-level attributes related to infrastructure" → "top-level properties that define your infrastructure"
• Removed backticks around resources, variables, and outputs in the main text (kept them in code context)

These changes improve technical accuracy (the YAML spec refers to them as properties) and make the description more direct and clear.

--- |

[pulumi-bot]

Your site preview for commit 61a3495 is ready! 🎉

http://www-testing-pulumi-docs-origin-pr-16676-61a34951.s3-website.us-west-2.amazonaws.com.