Content glow-up: content/docs/iac/get-started/terraform/begin.md

[pulumi-bot]

Important

Glow-up PR — human review required. Auto-merge is never armed on glow-up PRs and the automated PR-review sweep never approves them; it assigns the reviewers. Adjudicate the Backlog executed / Backlog declined tables below and merge manually.

Why this page

• Page: content/docs/iac/get-started/terraform/begin.md → /docs/iac/get-started/terraform/begin/
• Lane: glowup
• Strategic tier: 1 (no_retire: true)
• Traffic: 802 monthly visits (period 2026-02-17 to 2026-08-17; source CLICKSTREAM.FCT_PAGEVIEWS)
• Last reviewed: 2026-07-16 (attempts: 0)
• Selection score: 14.4873

This section is composed deterministically from the selection queue; do not edit it.

Backlog executed

Warning

Backlog recovery failed. The ledger records 13 deferred finding(s) and a clarity flag for this page, but none could be recovered (no review PR has ever used content-review/docs-iac-get-started-terraform-begin, content-review/retire-docs-iac-get-started-terraform-begin, content-review/glowup-docs-iac-get-started-terraform-begin; run the taxonomy-only sweep). This run is a taxonomy sweep only. The backlog is preserved and the page stays eligible for a later glow-up — do not treat this as a clean page.

Heads queried: content-review/docs-iac-get-started-terraform-begin, content-review/retire-docs-iac-get-started-terraform-begin, content-review/glowup-docs-iac-get-started-terraform-begin.

Backlog declined

None — the backlog could not be recovered (see the warning above), so there were no banked findings to execute or decline. The ledger's 13 deferred findings and clarity flag are preserved and carried forward.

Secondary sweep

• Style improvements: Removed first-person/marketing-adjacent phrasing and tightened three sentences. L29 "In this tutorial we're going to focus on AWS." → "This tutorial focuses on AWS." L54 "you are good to go" → "your access is configured correctly", and the sentence now names the actor ("If the command prints your AWS user ID..."). L91 "You may optionally use" (redundant) → "You can also use". L155 "verify everything is in working order" → "verify your installation". L185 "please refer to" → "see" (Google style avoids "please" in instructions).
• Structural fixes: No changes. Heading levels and casing already follow the style guide (H1 from frontmatter, H2+ sentence case), and no paragraph needed splitting.
• Code formatting: L56 — the aws sts get-caller-identity sample output block was an unlabeled fence; added the json language identifier. This also resolves the six Vale findings at L58–L60 (Google.Quotes, Google.Ellipses, Google.FirstPerson), which fired only because the sample output was being linted as prose.
• Terminology corrections: No changes. Product and service names ("Pulumi", "Terraform", "AWS CLI", "Pulumi ESC") are all correct.
• Link improvements: L87 — /docs/esc/providers/login/aws-login was missing its trailing slash; corrected to /docs/esc/providers/login/aws-login/ to match the canonical internal-link form used elsewhere in /docs/. All 11 other links on the page verified in .verified-claims.json (see Findings not applied for the one unverifiable verdict). Also normalized the {{% choosable os ... %}} arguments to the quoted form used by the rest of content/docs/iac/get-started/ (four unquoted windows/macos/linux arguments) — presentation-only, no rendered change.
• Image and diagram improvements: No changes. The page references no images (see Screenshot check).
• Content enhancements: No changes. The setup steps, prerequisites, and CLI verification are accurate and complete; nothing on the page was contradicted by the claim pass, and adding material would exceed a glow-up's remit.

Estimated impact: minor tweaks (9 edits, 24 changed lines).

Findings not applied

Finding	Why not applied
.verified-claims.json c4 (L66) — unverifiable: the anchor #access-keys-and-secret-access-keys on the AWS "security credential types" page could not be confirmed in the fetched body.	The page returns 200 and is topically correct; an unverified anchor is not evidence of a broken link, and re-targeting it would be a judgment call. Flagged for a human.
.verified-claims.json c11 (L143) — framing-drift: "Java 11+ and Maven 3.6.1+" is asserted as a prerequisite, but the cited Oracle downloads page doesn't state that minimum.	The minimum-version fact belongs to Pulumi's Java SDK, not Oracle's download portal; correcting it means citing a different source, which is judgment-level. Flagged rather than guessed at.
Vale L5 Google.FirstPerson — stepper_link: "I'm ready to begin".	First person is deliberate here: the stepper link is the reader's own voice, and the same pattern is used across the get-started steppers. Changing it is a cross-page UX decision.
Raw <a href=... target="_blank"> tags for external links (L30, L66, L119–143) instead of markdown links.	Consistent with the rest of the get-started section and load-bearing for target="_blank"; converting them is a section-wide convention change, not a single-page glow-up.
$ / > shell prompts inside the fenced command blocks (L41, L49, L71–72, L80–81, L96, L104).	Prompt characters make the blocks non-copy-pasteable, but the convention is used throughout content/docs/iac/get-started/; removing it on one page only would make the tutorial inconsistent.
The ledger's 13 deferred findings and standing clarity flag for this page.	Unrecoverable — no prior review PR exists for any of this page's content-review branches, so there was nothing to read them from. Preserved; the page stays eligible for a later glow-up.

Screenshot check

No images. The page source references no screenshots, diagrams, or other content images (only the generic shared meta_image card, if any), so there is nothing to verify. (Determined from the source; the screenshot pass was skipped.)

Verification

• make lint: ✅ make lint re-verified by the workflow on 9a5c64b
• Pre-step artifacts:
  • .verified-claims.json: 12 verdict(s); 0 contradicted/mismatch, 1 unverifiable
  • .vale-findings.json: 9 finding(s)
  • .readthrough-findings.json: ran=True, 0 finding(s)
  • .frontmatter-validation.json: 1 file(s); 0 alias collision(s)

[github-actions]

Pre-merge Review — Last updated 2026-08-21T14:25:19Z

Tip

Summary: This is a copyedit pass over the "Get started with Pulumi and Terraform" tutorial's first step (begin.md) — the AWS credential setup and CLI verification page that parallels content/docs/iac/get-started/aws/configure.md. All twelve changed lines are prose tightening ("In this tutorial we're going to focus on AWS" → "This tutorial focuses on AWS"), shortcode-argument quoting ({{% choosable os windows %}} → {{% choosable os "windows" %}}), a json language tag on the aws sts get-caller-identity sample output, and a trailing slash on the ESC AWS-login link. The wrongness that would block a reader here is a broken tab (a malformed choosable argument silently hides an OS's instructions) or a credential/CLI step that no longer matches what AWS or the Pulumi CLI actually does — neither is present. Passes run: claim extraction and verification (11 claims, 10 verified, 0 contradicted), a cross-sibling convention sweep over all 9 tutorial siblings, code-example checks, a frontmatter sweep, and pattern-based linting.

Review confidence:

Dimension	Level	Notes
mechanics	HIGH
facts	HIGH
cross-sibling consistency	HIGH
code correctness	HIGH

Investigation log

• Cross-sibling reads: 9 of 9 siblings (targeted convention sweep — choosable shortcode usage, ESC/install link forms, and the shared credential-check passage)
• External claim verification: 10 of 11 claims verified (0 unverifiable, 0 contradicted) · 4 specialists (numerical, cross-reference, capability, framing); 0 cross-specialist corroborations · routed: 0 inline, 11 Pass 1, 0 Pass 2, 0 Pass 3.
• 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: ran (3 specialists: structural, existence, body-code-coverage); 0 findings
• Editorial-balance pass: not run (not under content/blog/)

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

🔍 Verification trail

11 claims extracted · 10 verified · 0 unverifiable · 0 contradicted

• L29 in content/docs/iac/get-started/terraform/begin.md "Pulumi can use the same cloud provider credentials as Terraform." → ✅ verified (evidence: pulumi-aws's config reads standard AWS credential env vars/shared credentials file (AccessKey: stringValue(vars, "accessKey", []string{"AWS_ACCESS_KEY_ID"})) matching Terraform's AWS provider auth chain, and the doc itself notes "your…; source: gh search code --owner pulumi "AWS_ACCESS_KEY_ID" repo:pulumi/pulumi-aws; content/docs/iac/get-started/terraform/begin.md L29-30)
• L54 in content/docs/iac/get-started/terraform/begin.md "Running the AWS CLI identity-check command prints the user's AWS user ID, account, and ARN if access is configured correctly." (also L57-59) → ✅ verified (evidence: The doc's own example shows aws sts get-caller-identity output as JSON with exactly UserId, Account, and Arn fields, matching AWS's documented CLI behavior for this standard identity-check command.; source: AWS CLI sts get-caller-identity standard output schema (UserId, Account, Arn) as reflected in content/docs/iac/get-started/terraform/begin.md lines 57-61)
• L77 in content/docs/iac/get-started/terraform/begin.md "The Hugo shortcode {{% choosable os 'windows' %}} is valid syntax for the choosable os windows tab in this documentation page." → ✅ verified (evidence: Line 77 of the file reads exactly {{% choosable os "windows" %}}, matching the claim, and this shortcode syntax is used consistently across dozens of other pulumi/docs and pulumi/registry pages (e.g. content/docs/install/_index.md…; source: repo:content/docs/iac/get-started/terraform/begin.md (line 77); gh search code --owner pulumi "choosable os windows")
• L87-88 in content/docs/iac/get-started/terraform/begin.md "Pulumi ESC provides AWS login support enabling dynamic, short-lived AWS credentials via OpenID Connect (OIDC) instead of long-lived static credentials." → ✅ verified (evidence: The aws-login provider doc states: "OIDC is the recommended way to log in to AWS. Pulumi Cloud exchanges a short-lived OIDC token for temporary AWS credentials by assuming an IAM role, so there are no long-lived keys to store or rotate,"…; source: content/docs/esc/providers/login/aws-login.md)
• L91 in content/docs/iac/get-started/terraform/begin.md "Users can optionally use AWS profiles if their configuration requires them." → ✅ verified (evidence: The doc states "You can also use AWS profiles if your configuration requires them:" followed by instructions to set the AWS_PROFILE environment variable, matching the claim that users can optionally use AWS profiles.; source: repo:content/docs/iac/get-started/terraform/begin.md)
• L101 in content/docs/iac/get-started/terraform/begin.md "The Hugo shortcode {{% choosable os 'windows' %}} is valid syntax for the choosable os windows tab used for AWS profile configuration on Windows." → ✅ verified (evidence: Line 101 in content/docs/iac/get-started/terraform/begin.md reads {{% choosable os "windows" %}} followed by a PowerShell snippet and closing {{% /choosable %}}, matching the same shortcode pattern used consistently throughout the…; source: repo:content/docs/iac/get-started/terraform/begin.md)
• L155 in content/docs/iac/get-started/terraform/begin.md "You can verify your Pulumi installation by running the pulumi CLI, specifically the pulumi version command." → ✅ verified (evidence: The doc page itself instructs: "After installing Pulumi, verify your installation by running the pulumi CLI:" followed by the command pulumi version for macOS, Linux, and Windows — exactly matching the claim's description of…; source: repo:content/docs/iac/get-started/terraform/begin.md (lines 155-183))
• L159 in content/docs/iac/get-started/terraform/begin.md "The Hugo shortcode {{% choosable os 'macos' %}} is valid syntax for the choosable os macos tab used for CLI version verification." → ➖ not-a-claim (evidence: Line 159 of the reviewed file itself contains {{% choosable os \"macos\" %}}, used consistently with the same choosable os shortcode pattern elsewhere in this file (lines 38, 46, 68, 77, 93, 101, 167, 175). This is a syntax…; source: repo:content/docs/iac/get-started/terraform/begin.md)
• L167 in content/docs/iac/get-started/terraform/begin.md "The Hugo shortcode {{% choosable os 'linux' %}} is valid syntax for the choosable os linux tab used for CLI version verification." → ✅ verified (evidence: Line 167 of begin.md contains exactly {{% choosable os "linux" %}}, matching the standard choosable.html shortcode signature (type, values, optional mode) used throughout the docs for CLI version verification tabs.; source: repo:content/docs/iac/get-started/terraform/begin.md and repo:layouts/shortcodes/choosable.html)
• L175 in content/docs/iac/get-started/terraform/begin.md "The Hugo shortcode {{% choosable os 'windows' %}} is valid syntax for the choosable os windows tab used for CLI version verification." → ✅ verified (evidence: Line 175 of the file reads exactly {{% choosable os "windows" %}}, used to wrap the Windows-specific pulumi version CLI verification snippet, consistent with the same shortcode pattern used elsewhere in this file (e.g., lines 46, 77…; source: repo:content/docs/iac/get-started/terraform/begin.md (line 175))
• L185 in content/docs/iac/get-started/terraform/begin.md "The Download and install Pulumi page at /docs/install/ contains troubleshooting information for setup issues." → ✅ verified (evidence: The /docs/install/ page includes a "### Common errors and warnings" section stating "These are common installation-related errors or warnings you may encounter," covering the "Pulumi not found error" and "New version warning" — i.e.…; source: repo:content/docs/install/_index.md)

🚨 Outstanding in this PR

No outstanding findings in this PR.

⚠️ Low-confidence

No low-confidence findings.

💡 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-08-21T14:25:19Z — Copyedit-only pass over begin.md; 11 claims checked with no contradictions, shortcode quoting and the ESC link now match the parallel AWS page, no blocking findings (9a5c64b)

---

• Refresh this review — comment @claude #update-review. Say what you fixed, or which finding you dispute and why; both work in the same mention.
• Ask for anything else — comment @claude with no hashtag (questions, one-off fixes). Leaves this review untouched.

Important

Please don't hide, resolve, or delete this comment! It breaks things!

📖 How pre-merge review works — the full lifecycle, short-circuits, and escape hatches.

[pulumi-bot]

Your site preview for commit 9a5c64b is ready! 🎉

http://www-testing-pulumi-docs-origin-pr-21044-9a5c64bd.s3-website.us-west-2.amazonaws.com

Changed pages:

• /docs/iac/get-started/terraform/begin/

[jkodroff]

This is a glowing review.