Adding additional references to Policy section in Docs

[arunkumar611]

Consolidating helpful areas of policy from other sections into the policy docs path.

[claude]

Documentation Review

Overall, this is a well-structured PR that adds useful reference pages and consolidates navigation. The new CLI, CI/CD, and API reference pages are clearly written, have proper frontmatter, and follow heading conventions correctly. A few items to address below.

---

Issue 1 — IDP pattern links use alias paths instead of canonical paths

File: content/docs/insights/policy/_index.md (near the end of the file, in the new bullet points added)

The three links to IDP patterns point to alias paths rather than the canonical page locations:

/docs/idp/best-practices/patterns/policies-as-tests/
/docs/idp/best-practices/patterns/validating-component-inputs-using-policy-functions/
/docs/idp/best-practices/patterns/cost-control-using-components-policies-constrained-inputs/

These files actually live under /docs/idp/guides/best-practices/patterns/ and have aliases set up for the shorter paths, so the links do work. However, best practice is to link to canonical URLs to avoid a redirect chain. Consider updating to the canonical paths:

- **Building an internal developer platform?** Explore advanced patterns including [policies as tests](/docs/idp/guides/best-practices/patterns/policies-as-tests/), [validating component inputs using policy functions](/docs/idp/guides/best-practices/patterns/validating-component-inputs-using-policy-functions/), and [cost control using components, policies, and constrained inputs](/docs/idp/guides/best-practices/patterns/cost-control-using-components-policies-constrained-inputs/).

---

Issue 2 — Em dash replaced with hyphen in definition-style list items

Files: content/docs/insights/policy/policy-groups.md, content/docs/insights/policy/policy-packs/authoring.md

The PR replaces — (em dash) with - (hyphen) in bullets formatted as **term** — definition. The Google Developer Documentation Style Guide recommends em dashes to set off a parenthetical or to follow a bold term in a list. The existing content used em dashes consistently for this purpose.

For example, in policy-groups.md:

- **Block non-compliant deployments before they happen** — Prevent security issues like public S3 buckets or unencrypted databases from ever reaching production
- **Provide fast feedback to developers** — Catch policy violations during development and testing, before code review or CI/CD
- **Enforce standards for Pulumi-managed infrastructure** — Ensure all resources deployed through Pulumi meet organizational requirements

And in authoring.md:

- **advisory** — Issues warnings but allows deployments to proceed
- **mandatory** — Blocks deployments when violations are detected
- **disabled** — Skips policy evaluation entirely

---

What looks good

• New pages are well-structured: api-reference.md, ci-cd.md, and cli.md all have correct frontmatter, title-case H1 headings, sentence-case H2+ headings, and valid links.
• Ordered lists: The ci-cd.md how-it-works list correctly uses 1. for all items.
• FAQ link fix: Correcting /docs/support/faq/policies to /docs/support/faq/policies/ (adding trailing slash) is correct.
• Em dash to comma changes in prose and meta_desc: These read more naturally and are appropriate.
• {{% notes %}} shortcode: Used correctly in cli.md.
• GitHub Actions anchor: The link to /docs/iac/guides/continuous-delivery/github-actions/#caching-plugins-and-policy-packs points to an anchor that exists in the target file.

---

Mention @claude if you'd like additional review or have questions about specific feedback.

[pulumi-bot]

Your site preview for commit f2e6749 is ready! 🎉

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