Fix misdirected ESC Automation API links, add Java support, cross-link narrative pages

[workprentice]

Problem

content/docs/esc/concepts/environments.md linked to
/docs/iac/concepts/automation-api/ when telling readers how Automation API manages a
stack's imported ESC environments, but that page has no ESC-environment coverage at
all. The actual addEnvironments/listEnvironments/removeEnvironment documentation
and per-language examples live at /docs/esc/integrations/automation-api/. Separately,
that integration page's language-support matrix omitted Java, and none of the narrative
Automation API pages cross-linked to it.

Changes

• content/docs/esc/concepts/environments.md: both Automation API references now point
  at /docs/esc/integrations/automation-api/ instead of the general concepts page.
• content/docs/esc/integrations/automation-api.md: added Java to the chooser and the
  supported-languages sentence, with a new Java example (verified against the
  com.pulumi.automation.WorkspaceStack / LocalWorkspace reference docs — addEnvironments(Collection<String>)
  and removeEnvironment(String) exist; there is no list method, matching the .NET
  SDK's gap, which the page already calls out for C#).
• content/docs/iac/concepts/automation-api.md,
  content/docs/iac/guides/building-extending/automation-api.md,
  content/docs/iac/guides/building-extending/automation-api-advanced.md: each gained a
  short (2–3 sentence) cross-reference pointing readers to the ESC integration page from
  the natural place in their existing narrative (the Stack/RemoteStack section, the
  "Associate with a stack" section, and the workspace-lifecycle section, respectively).
  No examples were duplicated.

The Java code example was verified against the live API reference at
docs/reference/pkg/java/com/pulumi/automation/{WorkspaceStack,LocalWorkspace}.html
(method signatures for addEnvironments, removeEnvironment, and the inline-program
overload of createOrSelectStack) rather than compiled, since no Maven/JDK toolchain is
available in this environment; the surrounding prose and chooser tag follow the exact
pattern already used for Java elsewhere in this same guide
(content/docs/iac/guides/building-extending/automation-api.md's "Associate with a
stack" section), so the shortcode usage is consistent with existing conventions.

Supporting signal

GA4 (28-day window) shows /docs/iac/concepts/automation-api/ — the misdirected link
target — has a below-average engagement rate for its traffic volume, consistent with
readers arriving expecting ESC coverage, not finding it, and leaving quickly.

Fixes #20634.

---

🧠 This PR was created by workprentice on behalf of the Docs Groundskeeper automation, running its scheduled freshness-audit backlog cycle.

[github-actions]

Pre-merge Review — Last updated 2026-08-01T15:15:59Z

Tip

Summary: This is a docs PR that repoints two "Automation API" links on the ESC Environments concept page from the general IaC Automation API page to the ESC-specific /docs/esc/integrations/automation-api/ page, adds a Java tab (prose + code sample) to that ESC Automation API page, and drops a short cross-link paragraph into three IaC Automation API pages. The failure mode that would block a reader here is a copy-paste-broken code sample or a link that lands on a page which doesn't actually document the ESC methods — so the passes that matter are per-language snippet compilability against the real SDK source, link-target existence, and API-surface accuracy. Fact verification covered 28 claims (all confirmed, including the Java addEnvironments / removeEnvironment signatures and the absence of a listEnvironments in pulumi-java); a cross-sibling read confirmed the ESC docs already point ESC Automation API references at the new target, so this PR closes the last two stragglers. The previously-flagged Java compile error (missing throws Exception on main) was fixed in c3a3302; no outstanding issues remain.

Review confidence:

Dimension	Level	Notes
mechanics	HIGH	Shortcode pairing, chooser language list, frontmatter, aliases, and link targets all check out.
facts	HIGH
cross-sibling consistency	HIGH
code correctness	HIGH	Java sample checked against pulumi/pulumi-java source; the compile-blocking missing throws Exception was fixed in c3a3302 and now compiles as written.

Investigation log

• Cross-sibling reads: 5 of 10 siblings
• External claim verification: 28 of 28 claims verified (0 unverifiable, 0 contradicted) · 4 specialists (numerical, cross-reference, capability, framing); 0 cross-specialist corroborations · routed: 0 inline, 28 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	1

🔍 Verification trail

28 claims extracted · 28 verified · 0 unverifiable · 0 contradicted

• L135 in content/docs/esc/concepts/environments.md "The Pulumi Cloud console provides a visual editor with an intelligent YAML editor, live evaluation preview, version history, revision tagging, and access-contr…" → ✅ verified (evidence: Sibling docs (versioning.md) confirm revision tagging, version history, and comparison are real Pulumi Cloud console/CLI features ("You can assign tags to revisions... You can see the history of revisions using... or in the Pulumi Cloud Co…; source: repo:content/docs/esc/concepts/versioning.md, repo:content/docs/esc/concepts/environments.md)
• L136 in content/docs/esc/concepts/environments.md "The pulumi env CLI subcommands cover the full environment lifecycle: initialize, list, get and set values, edit, open, run commands with injected values, diff…" → ✅ verified (evidence: The auto-generated CLI reference page content/docs/iac/cli/commands/pulumi_env.md (source: pulumi/pulumi cobra-generated docs) lists subcommands including "pulumi env init - Create an empty environment", "pulumi env list - List environment…; source: gh api repos/pulumi/docs/contents/content/docs/iac/cli/commands/pulumi_env.md)
• L137-139 in content/docs/esc/concepts/environments.md "Automation API can be used to manage which environments a Pulumi stack imports programmatically, via functions including addEnvironments, listEnvironments, and…" (also L161) → ✅ verified (evidence: The automation-api.md page states: "Automation API methods for ESC include: addEnvironments(...): Add environments in order to your Pulumi stacks' import list. listEnvironments(): Retrieve a list of environments currently imported into…; source: content/docs/esc/integrations/automation-api.md)
• L137 in content/docs/esc/concepts/environments.md "The Pulumi Cloud REST API performs standard CRUD operations on environments." → ✅ verified (framing: Source describes the REST API generally as covering Pulumi Cloud resources (orgs, stacks, environments, etc.) via OpenAPI-generated docs; claim narrows this to…; evidence: The linked REST API reference page confirms the Pulumi Cloud REST API is "organized into... categories" generated from the live OpenAPI spec (api.pulumi.com/api/openapi/pulumi-spec.json), and ESC environments are managed end-to-end (create…; source: repo:content/docs/reference/cloud-rest-api/_index.md (aliased from /docs/pulumi-cloud/cloud-rest-api/))
• L139 in content/docs/esc/concepts/environments.md "The Environment resource API documentation is located at /registry/packages/pulumiservice/api-docs/environment/." → ✅ verified (evidence: The pulumiservice provider defines a resource pulumiservice:index:Environment (confirmed in pulumi/pulumi-pulumiservice source: provider/pkg/resources/environment.go returns type name pulumiservice:index:Environment, and it's regis…; source: gh search code "resource pulumiservice:index:Environment" → pulumi/pulumi-pulumiservice:provider/pkg/resources/environment.go)
• L139 in content/docs/esc/concepts/environments.md "The Pulumi Service provider's Environment resource allows environments to be managed as infrastructure-as-code, so that environment definitions are themselves…" → ✅ verified (evidence: The pulumi/pulumi-pulumiservice provider ships an Environment resource (used in numerous real examples like new pulumiservice.Environment("aws-credentials", {...}) in pulumi/examples, pulumi/esc-examples, and pulumi/docs' own pulumi-serv…; source: gh search code pulumiservice.Environment (pulumi/pulumi-pulumiservice, pulumi/examples, pulumi/esc-examples, pulumi/docs))
• L141 in content/docs/esc/concepts/environments.md "Every change to an environment creates a new immutable revision." → ✅ verified (evidence: The sibling ESC docs page (content/docs/esc/concepts/versioning.md), which this line links to, states: "Each time a change is made to an environment, a new immutable revision is created," matching the claim exactly.; source: repo:content/docs/esc/concepts/versioning.md)
• L141 in content/docs/esc/concepts/environments.md "The Versioning documentation, which explains how to compare, tag, and pin revisions, is located at /docs/esc/concepts/versioning/." → ✅ verified (evidence: content/docs/esc/concepts/versioning.md exists, titled "Versioning," and covers tagging revisions ("pulumi env version tag"), pinning ("append @<revision>... to pin a stack to a specific, immutable version"), and comparing ("Compare revi…; source: repo:content/docs/esc/concepts/versioning.md)
• L159 in content/docs/esc/concepts/environments.md "The pulumi config env add / command adds an environment to the current stack's configuration." → ✅ verified (evidence: Pulumi CLI source (pkg/cmd/pulumi/config/config_env_add.go) defines the add subcommand with Short: "Add environments to a stack" and Long: "Adds environments to the end of a stack's import list...", and its run() appends the argument to…; source: gh api repos/pulumi/pulumi/contents/pkg/cmd/pulumi/config/config_env_add.go)
• L161 in content/docs/esc/concepts/environments.md "Calling addEnvironments(...) on a stack's workspace attaches environments programmatically in Automation API workflows." → ✅ verified (evidence: The automation-api.md doc states: "addEnvironments(...): Add environments in order to your Pulumi stacks' import list" and shows examples like await stack.addEnvironments(\"env1\", \"env2\"), confirming it attaches environments program…; source: content/docs/esc/integrations/automation-api.md)
• L163 in content/docs/esc/concepts/environments.md "Once an environment is referenced, values flow into a Pulumi program through the standard configuration API." → ✅ verified (evidence: The source file states verbatim: "Once an environment is referenced, values flow into your program through the standard configuration API:" followed by a TypeScript example using new pulumi.Config() and…; source: repo:content/docs/esc/concepts/environments.md (line 163))
• L163 in content/docs/esc/concepts/environments.md "The configuration API documentation is located at /docs/iac/concepts/config/#code." → ✅ verified (evidence: content/docs/iac/concepts/config.md exists and contains the section heading "## Accessing Configuration from Code {#code}", which matches the anchor /docs/iac/concepts/config/#code referenced in the claim.; source: repo:content/docs/iac/concepts/config.md)
• L28 in content/docs/esc/integrations/automation-api.md "The .NET SDK Automation API documentation is located at /docs/reference/pkg/dotnet/Pulumi.Automation/Pulumi.Automation.WorkspaceStack.html." (also L232) → ✅ verified (evidence: The pulumi/docs repo contains a prebuilt reference page at static-prebuilt/docs/reference/pkg/dotnet/pulumi.automation/pulumi.automation.workspacestack.html documenting Pulumi.Automation.WorkspaceStack, including AddEnvironmentsAsync, matc…; source: gh search code --owner pulumi "class WorkspaceStack" / repo pulumi/docs static-prebuilt path)
• L30 in content/docs/esc/integrations/automation-api.md "The Automation API language chooser on this page supports the languages typescript, python, go, csharp, and java." → ✅ verified (evidence: The file contains the shortcode {{< chooser language \"typescript,python,go,csharp,java\" />}} on line 30, exactly matching the claimed set of languages.; source: repo:content/docs/esc/integrations/automation-api.md)
• L232 in content/docs/esc/integrations/automation-api.md "The Java SDK supports adding and removing environments, but does not provide a method to list them." → ✅ verified (evidence: pulumi-java source shows Workspace.java/WorkspaceStack.java define addEnvironments(...) and removeEnvironment(...) methods, but a search for listEnvironments in the pulumi-java repo returns no results — confirming no list method…; source: gh search code --owner pulumi repo:pulumi/pulumi-java "addEnvironments"/"removeEnvironment"/"listEnvironments")
• L235-236 in content/docs/esc/integrations/automation-api.md "The Java Automation API classes LocalWorkspace and WorkspaceStack are located in the package com.pulumi.automation." → ✅ verified (evidence: gh search confirms both files exist in pulumi/pulumi-java at path sdk/java/pulumi/src/main/java/com/pulumi/automation/LocalWorkspace.java and .../WorkspaceStack.java, i.e. package com.pulumi.automation.; source: gh search code (pulumi/pulumi-java): https://github.com/pulumi/pulumi-java/blob/.../sdk/java/pulumi/src/main/java/com/pulumi/automation/LocalWorkspace.java and WorkspaceStack.java)
• L247 in content/docs/esc/integrations/automation-api.md "LocalWorkspace.createOrSelectStack in the Java SDK accepts a project name, stack name, and a context callback, and can be used to create or select an existing…" (also L249-250) → ✅ verified (evidence: The doc file itself shows: LocalWorkspace.createOrSelectStack(projectName, stackName, ctx -> { }) with comment "Create or select an existing stack, using an empty inline program since we're only manipulating environments, not deploying r…; source: gh search code --owner pulumi createOrSelectStack language:java (pulumi/pulumi-java: sdk/java/pulumi/src/main/java/com/pulumi/automation/LocalWorkspace.java); repo:content/docs/esc/integrations/automation-api.md L245-247)
• L249 in content/docs/esc/integrations/automation-api.md "Adding environments to a stack's import list via the Automation API is equivalent to adding them to the imports section of an ESC environment." → ✅ verified (evidence: The sibling concepts page states Automation API is used to "manage which environments a Pulumi stack imports programmatically" and that Pulumi IaC stacks "import" ESC environments the same way environments import each other via the `import…; source: content/docs/esc/concepts/environments.md; content/docs/esc/integrations/automation-api.md)
• L250 in content/docs/esc/integrations/automation-api.md "The Java SDK's WorkspaceStack.addEnvironments method accepts a List of environment name strings to add environments to the stack's import list." → ✅ verified (evidence: pulumi-java source shows: public void addEnvironments(Collection<String> environments) throws AutomationException { this.workspace.addEnvironments(this.name, environments); } in WorkspaceStack.java, matching the claim that it accepts a c…; source: gh search code addEnvironments --owner pulumi (pulumi/pulumi-java:sdk/java/pulumi/src/main/java/com/pulumi/automation/WorkspaceStack.java))
• L253 in content/docs/esc/integrations/automation-api.md "The Java SDK's WorkspaceStack.removeEnvironment method accepts a single environment name string to remove that environment from the stack's import list." → ✅ verified (evidence: pulumi/pulumi-java sdk/java/pulumi/src/main/java/com/pulumi/automation/WorkspaceStack.java defines: "public void removeEnvironment(String environment) throws AutomationException" which delegates to "this.workspace.removeEnvironment(this.na…; source: gh search code removeEnvironment (pulumi/pulumi-java: sdk/java/pulumi/src/main/java/com/pulumi/automation/WorkspaceStack.java))
• L68 in content/docs/iac/concepts/automation-api.md "There is a page at /docs/esc/integrations/automation-api/ ('Automation API for ESC') documenting supported methods and examples in each language for managing E…" → ✅ verified (evidence: The page at content/docs/esc/integrations/automation-api.md (URL /docs/esc/integrations/automation-api/) documents Automation API methods for ESC (addEnvironments, listEnvironments, removeEnvironment) and provides per-language code example…; source: repo:content/docs/esc/integrations/automation-api.md)
• L353 in content/docs/iac/guides/building-extending/automation-api-advanced.md "The 'Automation API for ESC' page at /docs/esc/integrations/automation-api/ documents the supported methods and provides per-language examples for managing ESC…" → ✅ verified (evidence: The page at /docs/esc/integrations/automation-api/ lists supported methods ("addEnvironments(...)", "listEnvironments()", "removeEnvironment(environment)") and provides a language chooser with TypeScript, Python, Go, C#, and Java code exam…; source: repo:content/docs/esc/integrations/automation-api.md)
• L534 in content/docs/iac/guides/building-extending/automation-api.md "The 'Automation API for ESC' documentation page (/docs/esc/integrations/automation-api/) documents the addEnvironments, listEnvironments, and removeEnvironment…" → ✅ verified (evidence: The page at content/docs/esc/integrations/automation-api.md explicitly lists: "addEnvironments(...): Add environments...", "listEnvironments(): Retrieve a list of environments...", and "removeEnvironment(environment): Remove a specif…; source: repo:content/docs/esc/integrations/automation-api.md)
• L538 in content/docs/iac/guides/building-extending/automation-api.md "Automation API drives the same engine as the Pulumi CLI." → ✅ verified (evidence: The sibling concepts page (content/docs/iac/concepts/automation-api.md) states: "Automation API drives the Pulumi engine itself, running updates, previews, refreshes, and destroys from a program" and "Automation API drives the same engine,…; source: repo:content/docs/iac/concepts/automation-api.md)
• L538 in content/docs/iac/guides/building-extending/automation-api.md "Automation API downloads any missing provider plugin automatically before an operation." → ✅ verified (evidence: The linked concepts page states: "When you run the CLI, the engine automatically downloads any missing provider plugin before an operation. Automation API drives the same engine, so this behavior is identical: for providers published to th…; source: repo:content/docs/iac/concepts/automation-api.md (Plugins section))
• L538 in content/docs/iac/guides/building-extending/automation-api.md "The explicit installPlugin call is not required for providers published to the Pulumi Registry when using Automation API." → 🤝 matches (evidence: The sibling concepts page content/docs/iac/concepts/automation-api.md independently states the same behavior: "When you run the CLI, the engine automatically downloads any missing provider plugin before an operation. Automation API drives…; source: repo:content/docs/iac/concepts/automation-api.md)
• L538 in content/docs/iac/guides/building-extending/automation-api.md "The 'Plugins' section at /docs/iac/concepts/automation-api/#plugins contains details about plugin behavior for Automation API." → ✅ verified (evidence: content/docs/iac/concepts/automation-api.md has a heading "## Plugins" (anchor #plugins) that reads: "Pulumi providers are distributed as plugins that the engine loads at runtime... Automation API drives the same engine, so this behavior i…; source: repo:content/docs/iac/concepts/automation-api.md)
• L538 in content/docs/iac/guides/building-extending/automation-api.md "The installPlugin call is shown in the guide to pin a specific plugin version." → ✅ verified (evidence: Line 538 states: "the explicit installPlugin call below isn't required for providers published to the Pulumi Registry... It's shown here to pin a specific plugin version" and the code examples show installPlugin("aws", "v4.0.0") — a pi…; source: repo:content/docs/iac/guides/building-extending/automation-api.md)
• L241 in content/docs/esc/integrations/automation-api.md "The new Java sample's main method compiles as written" → ✅ verified (evidence: main now declares public static void main(String[] args) throws Exception, which covers the checked AutomationException thrown by createOrSelectStack/addEnvironments/removeEnvironment and the checked Exception propagated by the try-with-resources close(); fixed in commit c3a3302; source: repo:content/docs/esc/integrations/automation-api.md L241)

🚨 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

• [L241] content/docs/esc/integrations/automation-api.md — the Java sample's main method now declares throws Exception, covering the checked AutomationException propagated by the Automation API calls and the checked Exception propagated by the try-with-resources close(). The sample compiles as written (resolved in c3a3302).

📜 Review history

• 2026-08-01T14:20:36Z — Link retargets and cross-links verified; 28 claims confirmed; one blocker: the new Java sample is missing a throws clause and won't compile. (167c1c3)
• 2026-08-01T15:15:59Z — re-reviewed after fix push (1 new commit, c3a3302): main now declares throws Exception; the Java sample compiles as written. 0 outstanding remain.

---

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

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

Changed pages:

• /docs/esc/concepts/environments/
• /docs/esc/integrations/automation-api/
• /docs/iac/concepts/automation-api/
• /docs/iac/guides/building-extending/automation-api-advanced/
• /docs/iac/guides/building-extending/automation-api/

[workprentice]

@claude #update-review Fixed: added throws Exception to the Java example's main signature (b40a12d) so it compiles given the checked exceptions from createOrSelectStack, addEnvironments, removeEnvironment, and WorkspaceStack.close().

[github-actions]

🤖 Automatic review refresh errored; the review is still marked stale. Mention @claude #update-review to refresh it.

[workprentice]

@claude #update-review Retrying — the prior refresh attempt errored. CI is now green (retriggered after an unrelated kind/kubectl network flake), and the Java example fix from commit b40a12d (added throws Exception to main) is in place.

[github-actions]

🤖 Review updated on @workprentice[bot]'s request.