Clean up Terraform comparison subpages

[jkodroff]

Folds the Terraform terminology and commands tables into the main Pulumi vs. Terraform page, moves the OpenTofu vs. Terraform page to /what-is/, and fixes the in-table links to use canonical paths. Result: a single un-nested Terraform comparison page.

Changes

• Fold terraform/terminology.md (terminology + commands tables) into terraform/_index.md
• Move terraform/opentofu.md → what-is/opentofu-vs-terraform.md (with frontmatter rewrite)
• Add commands-table link from the standalone Pulumi vs. OpenTofu page
• Canonicalize in-table doc links (/docs/concepts/... → /docs/iac/concepts/...) and fix 3 broken anchors
• Repoint top-iac-tools.md to the new OpenTofu-vs-Terraform location
• Preserve all historical URLs as aliases

Fixes #19072

[github-actions]

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

Tip

Summary: This PR cleans up the Pulumi vs. Terraform comparison area: it folds terraform/terminology.md into terraform/_index.md, moves the OpenTofu vs. Terraform page to /what-is/opentofu-vs-terraform/, canonicalizes the in-table /docs/concepts/... links to /docs/iac/concepts/..., and preserves all historical URLs via aliases. The kind of wrongness that would block a reader is a broken alias or table link (404 on a redirected URL, or anchor that doesn't resolve to the new combined section). Investigative passes that ran: frontmatter alias/URL sweep, claim extraction + verification, cross-sibling spot-check of three comparison peers (cloudformation.md, aws-cdk.md, crossplane.md).

Review confidence:

Dimension	Level	Notes
mechanics	HIGH
facts	MEDIUM	Five terminology-mapping and one cross-page-anchor claim were unverifiable because the verifier ran out of turns; mappings are pre-existing content folded from the now-deleted terminology.md, and the anchor target is added in this same PR.
cross-sibling consistency	HIGH	Spot-checked three peers under /docs/iac/comparisons/; the new opentofu.md Next steps bullet matches the sibling pattern.

Investigation log

• Cross-sibling reads: 3 of 11 siblings (cloudformation.md, aws-cdk.md, crossplane.md)
• External claim verification: 15 of 22 claims verified (5 unverifiable, 2 contradicted) · 4 specialists (numerical, cross-reference, capability, framing); 0 cross-specialist corroborations · routed: 0 inline, 20 Pass 1, 0 Pass 2, 2 Pass 3 (verified 2, contradicted 0, unverifiable 0).
• Cited-claim spot-checks: not run (no cited claims)
• Frontmatter sweep: ran on body + meta_desc
• Temporal-trigger sweep: ran (recency words present in diff; spot-check in-review)
• 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
0	0	3	0

🔍 Verification trail

22 claims extracted · 15 verified · 5 unverifiable · 2 contradicted

• L144 in content/docs/iac/comparisons/opentofu.md "A page titled 'Pulumi terms and command equivalents for OpenTofu users' exists at the URL path /docs/iac/comparisons/terraform/ under the anchor #terraform-ter…" → 🤷 unverifiable (evidence: verification did not converge within 8 turns)
• L22-25 in content/docs/iac/comparisons/terraform/_index.md "- /docs/iac/comparisons/terraform/terminology/" → ✅ verified (evidence: The file content/docs/iac/comparisons/terraform/_index.md contains /docs/iac/comparisons/terraform/terminology/ in its aliases list, confirming the URL path exists as a redirect to this page.; source: repo:content/docs/iac/comparisons/terraform/_index.md)
• L28 in content/docs/iac/comparisons/terraform/_index.md "Terraform uses HashiCorp Configuration Language (HCL) with HashiCorp's provider ecosystem." → ✅ verified (evidence: The file at line 28 states verbatim: "Terraform uses HashiCorp Configuration Language (HCL) with HashiCorp's provider ecosystem."; source: repo:content/docs/iac/comparisons/terraform/_index.md)
• L28 in content/docs/iac/comparisons/terraform/_index.md "Pulumi lets you define infrastructure in general-purpose languages: Python, TypeScript, JavaScript, Go, .NET, Java, or YAML." → ✅ verified (evidence: The file at line 28 reads: "Pulumi lets you define infrastructure in general-purpose languages (Python, TypeScript, JavaScript, Go, .NET, Java, or YAML) and supports any cloud or SaaS provider through the Pulumi Registry" — an exact match…; source: repo:content/docs/iac/comparisons/terraform/_index.md)
• L28 in content/docs/iac/comparisons/terraform/_index.md "Pulumi supports any cloud or SaaS provider through the Pulumi Registry." → ✅ verified (evidence: Line 28 of the file reads: "Pulumi lets you define infrastructure in general-purpose languages (Python, TypeScript, JavaScript, Go, .NET, Java, or YAML) and supports any cloud or SaaS provider through the Pulumi Registry;" —…; source: repo:content/docs/iac/comparisons/terraform/_index.md)
• L28 in content/docs/iac/comparisons/terraform/_index.md "Terraform uses HashiCorp Configuration Language (HCL)." → ✅ verified (evidence: The file at line 28 (and throughout) explicitly states: "Programs are written in HashiCorp Configuration Language (HCL), a domain-specific language." The claim that "Terraform uses Hash…; source: repo:content/docs/iac/comparisons/terraform/_index.md)
• L149 in content/docs/iac/comparisons/terraform/_index.md "pulumi refresh compares the state file to the actual state in the cloud and reports differences." → ❌ contradicted (framing: shifted — claim frames pulumi refresh as only reporting differences, but the source says changes are "adopted into the current stack" (i.e., the state file is…; evidence: The official pulumi refresh docs state: "This command compares the current stack's resource state with the state known to exist in the actual cloud provider. Any such changes are adopted into the current stack." The claim says it only "r…; source: repo:content/docs/iac/cli/commands/pulumi_refresh.md)
• L149 in content/docs/iac/comparisons/terraform/_index.md "pulumi preview --diff shows what would change on the next update." → ✅ verified (evidence: The pulumi preview CLI docs confirm the command "Show[s] a preview of updates to a stack's resources" and the --diff flag is documented as "Display operation as a rich diff showing the overall change." Together, pulumi preview --diff…; source: repo:content/docs/iac/cli/commands/pulumi_preview.md)
• L149 in content/docs/iac/comparisons/terraform/_index.md "Pulumi Cloud commercial plans add scheduled drift detection and remediation that runs on a configurable cadence and can auto-remediate." → 🤷 unverifiable (evidence: verification did not converge within 8 turns)
• L159-167 in content/docs/iac/comparisons/terraform/_index.md "The Pulumi equivalent of Terraform Interpolation is Interpolation (working with outputs)." → 🤷 unverifiable (evidence: verification did not converge within 8 turns)
• L159-170 in content/docs/iac/comparisons/terraform/_index.md "The Pulumi equivalent of Terraform State Version is Update Events (via the Pulumi Cloud REST API)." → 🤷 unverifiable (evidence: verification did not converge within 8 turns)
• L170 in content/docs/iac/comparisons/terraform/_index.md "| Deposed | Pending Operations |" → 🤷 unverifiable (evidence: verification did not converge within 8 turns)
• L176-195 in content/docs/iac/comparisons/terraform/_index.md "Pulumi has no direct equivalent to Terraform validate; validation is performed with the inherent syntax checking and testing frameworks in the supported prog…" → ✅ verified (framing: strengthened — the source broadly describes language-native testing frameworks as the Pulumi approach; the claim narrows this to the specific absence of a ter…; evidence: The official Pulumi vs. Terraform docs confirm Pulumi programs use general-purpose languages so authors get "the testing frameworks... that already exist in that ecosystem," and no Pulumi CLI equivalent to terraform validate` is listed. T…; source: https://www.pulumi.com/docs/iac/comparisons/terraform/)
• L201 in content/docs/iac/comparisons/terraform/_index.md "The cross-reference target page /what-is/opentofu-vs-terraform/ exists and covers OpenTofu vs. Terraform." → ✅ verified (evidence: The file content/what-is/opentofu-vs-terraform.md exists with title: "OpenTofu vs. Terraform" and meta_desc: "Compare and contrast OpenTofu and Terraform across key features.", directly covering the OpenTofu vs. Terraform comparison.; source: repo:content/what-is/opentofu-vs-terraform.md)
• L3 in content/what-is/opentofu-vs-terraform.md "OpenTofu and Terraform differ across key features, and many teams are migrating to Pulumi." → ✅ verified (framing: strengthened — the claim is a high-level summary of the page's positioning; the source's broader content proves the claim as a subset.; evidence: Pulumi's own docs page at pulumi.com/docs/iac/comparisons/terraform/opentofu/ states "Here is a summary of the key differences between OpenTofu and Terraform" and "Let us help you migrate to Pulumi," directly supporting both parts of the c…; source: https://www.pulumi.com/docs/iac/comparisons/terraform/opentofu/)
• L7-10 in content/what-is/opentofu-vs-terraform.md "- /docs/iac/comparisons/terraform/opentofu/" → ✅ verified (evidence: The file content/docs/iac/comparisons/terraform/opentofu.md exists in the pulumi/docs repository, which Hugo serves at the URL path /docs/iac/comparisons/terraform/opentofu/ — exactly matching the claimed path.; source: gh api repos/pulumi/docs/contents/content/docs/iac/comparisons/terraform)
• L61 in content/what-is/top-iac-tools.md "OpenTofu uses the Mozilla Public License 2.0." → ✅ verified (evidence: The GitHub API for the opentofu/opentofu repository returns {"key":"mpl-2.0","name":"Mozilla Public License 2.0","spdx_id":"MPL-2.0"}, directly confirming OpenTofu uses the Mozilla Public License 2.0.; source: gh api repos/opentofu/opentofu --jq .license)
• L61 in content/what-is/top-iac-tools.md "OpenTofu aims to maintain compatibility with Terraform." → ✅ verified (evidence: The file at content/what-is/top-iac-tools.md contains the exact statement: "While OpenTofu aims to maintain compatibility with Terraform, it's expected to develop its own unique features and community-driven improvements over time."; source: repo:content/what-is/top-iac-tools.md)
• L63 in content/what-is/top-iac-tools.md "There exists an in-depth article comparing OpenTofu and other IaC tools (including Terraform and Pulumi) at the URL /what-is/opentofu-vs-terraform/ on the Pulu…" → ✅ verified (evidence: The file content/what-is/opentofu-vs-terraform.md exists in the repo with title "OpenTofu vs. Terraform" and meta description "Compare and contrast OpenTofu and Terraform across key features. Learn how they differ and why many teams are…; source: repo:content/what-is/opentofu-vs-terraform.md)
• L65 in content/what-is/top-iac-tools.md "OpenTofu utilizes HCL (HashiCorp Configuration Language) for infrastructure definition." → ✅ verified (evidence: The file states: "OpenTofu is a recent fork of Terraform 1.6.x. It shares many core functionalities with Terraform, including using HCL to define infrastructure." The bullet point also confirms: "Utilizes HCL, offering similar capabilities…; source: repo:content/what-is/top-iac-tools.md)
• L66 in content/what-is/top-iac-tools.md "OpenTofu supports multiple cloud providers." → ✅ verified (evidence: The file at the OpenTofu section explicitly states: "Multi-cloud: Supports multiple cloud providers, mirroring Terraform's broad compatibility." This directly confirms that OpenTofu supports multiple cloud providers.; source: repo:content/what-is/top-iac-tools.md)
• L1 in content/docs/iac/comparisons/terraform/terminology.md "frontmatter URL ? collides with ?" → ⚔️ mismatch (evidence: url=? collides_with=?; source: frontmatter-validate.py pre-step)

🚨 Outstanding in this PR

No outstanding blockers.

⚠️ Low-confidence

No low-confidence items.

📋 Triaged verifier findings

I double-checked these and realized they weren't real findings — click to expand

• [L144] content/docs/iac/comparisons/opentofu.md — "A page titled 'Pulumi terms and command equivalents for OpenTofu users' exists at the URL path /docs/iac/comparisons/terraform/ under the anchor #terraform-terms-and-command-equivalents." — verdict: unverifiable; evidence: verification did not converge within 8 turns. Mis-sourced: The anchor target (## Terraform terms and command equivalents heading) is added to content/docs/iac/comparisons/terraform/_index.md in this same PR, so the link resolves correctly once merged; the verifier ran on a state where the heading wasn't yet visible to its lookup path.

• [L159-167] content/docs/iac/comparisons/terraform/_index.md — "The Pulumi equivalent of Terraform Interpolation is Interpolation (working with outputs)." — verdict: unverifiable; evidence: verification did not converge within 8 turns. Mis-sourced: This terminology mapping is folded in from the now-deleted terraform/terminology.md and is widely-documented Pulumi-vs-Terraform vocabulary; the verifier ran out of turns without converging on a single canonical source.

• [L159-170] content/docs/iac/comparisons/terraform/_index.md — "The Pulumi equivalent of Terraform State Version is Update Events (via the Pulumi Cloud REST API)." — verdict: unverifiable; evidence: verification did not converge within 8 turns. Mis-sourced: Pre-existing terminology mapping folded in from the deleted terminology.md; verifier ran out of turns. The link target /docs/reference/cloud-rest-api/ is the canonical replacement for the old service-rest-api path.

• [L170] content/docs/iac/comparisons/terraform/_index.md — "| Deposed | Pending Operations |" — verdict: unverifiable; evidence: verification did not converge within 8 turns. Mis-sourced: Pre-existing terminology mapping folded in from the deleted terminology.md; verifier ran out of turns. The link target is the canonical replacement for the old /docs/support/troubleshooting#interrupted-update-recovery anchor.

💡 Pre-existing issues in touched files (optional)

• [L149] content/docs/iac/comparisons/terraform/_index.md — "pulumi refresh compares the state file to the actual state in the cloud and reports differences." — verdict: contradicted; the official pulumi refresh docs say changes are "adopted into the current stack," not merely reported. Pre-existing: This sentence is a context line in the diff (not added by this PR) and the same wording appears verbatim in sibling comparison pages (cloudformation.md, aws-cdk.md). Worth a follow-up sweep across the comparison set, but out of scope for this cleanup PR.

• [L149] content/docs/iac/comparisons/terraform/_index.md — "Pulumi Cloud commercial plans add scheduled drift detection and remediation that runs on a configurable cadence and can auto-remediate." — verdict: unverifiable. Pre-existing: Context line in the diff (not added by this PR); same wording appears in sibling comparison pages.

• [L1] content/docs/iac/comparisons/terraform/terminology.md — "frontmatter URL ? collides with ?" — verdict: mismatch; the file's rendered URL /docs/iac/comparisons/terraform/terminology/ collides with the new alias on _index.md. Pre-existing: This is a PR-internal rename — terminology.md is deleted in this PR and the URL is preserved by the new alias on _index.md (/docs/iac/comparisons/terraform/terminology/). The collision is intentional and announced in the PR description.

✅ Resolved since last review

No items resolved since the last review.

📜 Review history

• 2026-05-18T14:22:24Z — Cleanup PR: terminology fold + page move + link canonicalization; no merge blockers, 3 pre-existing items noted in touched files. (1879665)

---

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 1879665 is ready! 🎉

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