Skip to content

Rebalance AI docs to lead with the agent ecosystem, not only Neo#20079

Open
joeduffy wants to merge 3 commits into
masterfrom
joeduffy/agent-ecosystem-positioning
Open

Rebalance AI docs to lead with the agent ecosystem, not only Neo#20079
joeduffy wants to merge 3 commits into
masterfrom
joeduffy/agent-ecosystem-positioning

Conversation

@joeduffy

@joeduffy joeduffy commented Jul 3, 2026

Copy link
Copy Markdown
Member

Problem

The site had drifted into telling a single AI story — Neo — in places that should tell a broader one. Navigating to Product > Agentic infrastructure landed on a Neo-specific page, Docs > Infrastructure AI opened on a Neo-heavy page, and the docs that speak to using your own coding agent with Pulumi (Agent Skills, the MCP server) were weighted dead last in the section. This inadvertently framed Neo as an either-or choice against agents like Claude Code, Codex, and Cursor.

Pulumi's actual position: infrastructure as code is the substrate every agent passes through, so any coding agent an engineer already uses is a first-class way to do infrastructure work — through the agent-friendly CLI, Agent Skills, and the Pulumi MCP server. Neo is Pulumi's own purpose-built agent: the deepest integration and the fastest path to a great infrastructure agent out of the box, but one option on a spectrum, not the only door in. Docs should be community-centric and balanced; product pages may lean Neo-forward but shouldn't pretend no other option exists.

What changed

/docs/ai/ landing page — opens with the spectrum (bring-your-own-agent, then Neo) and splits its cards into a Bring your own agent group (Agent Skills, Pulumi CLI, MCP server, Agent Accounts) ahead of the Pulumi Neo group. Also surfaces the previously-unlisted Code Reviews feature, and fixes a duplicate "Pulumi CLI" card label (the Neo one is now "Neo in the CLI").

Nav reordering — the Skills and MCP pages move from weights 60/70 (last in a 12-page section) to the top. The whole Infrastructure AI section moves up to sit directly after Infrastructure as Code — substrate first, then the agents built on it — across the left nav, /llms.txt, the LLM sitemap, and the Docs Home capabilities grid (all derive from data/docs_menu_sections.yml).

what-is-agentic-infrastructure pillar page — gains an explicit "Which AI agents can do infrastructure work?" spectrum section and a "Do you need Pulumi Neo?" FAQ.

MCP naming collision — "MCP Integrations" (Neo consuming external MCP servers like Jira/Datadog) is renamed External MCP servers, with cross-references to/from the Pulumi MCP server page (which points the opposite direction — exposing Pulumi to agents).

Nav labelAgentic infrastructureAI infrastructure agent in the header and footer. The old label named the whole category after one product; the new one is capability-descriptive, matching its siblings ("Secrets & configuration", "Insights & governance").

Product/homepage — the Neo product page drops "unlike generic AI tools" for an honest lead-in acknowledging the agents customers already use before making Neo's case. Homepage and product-overview AI copy get the same one-line treatment.

AGENTS.md — a durable "AI and agent positioning" rule so this doesn't regress: docs ecosystem-first, product pages may lead with Neo but stay honest, never either-or.

Verification

  • make lint — 0 errors
  • make build — succeeds; rendered output spot-checked for nav order, card grids, /llms.txt, and the LLM sitemap
  • No files moved or renamed (display-name changes only), so no alias/SEO risk

Notes

  • The code-reviews docs page still shows a "public preview until July 1, 2026" banner that's now stale; a separate branch already has a commit removing it (a0c41bee2a), so I left it to avoid a conflict.
  • /product/neo/ still doesn't feature code reviews in its 3×3 capability grid — deferred to a separate pass since it needs a card swap, not an addition.

🤖 Generated with Claude Code

The site had drifted into telling a single AI story — Neo — in places
that should tell a broader one. Pulumi's bet is that infrastructure as
code is the substrate every agent passes through, so any coding agent an
engineer already uses (Claude Code, Codex, Cursor, GitHub Copilot) is a
first-class way to do infrastructure work, through the agent-friendly
CLI, Agent Skills, and the Pulumi MCP server. Neo is Pulumi's own
purpose-built agent: the deepest integration and the fastest path to a
great infrastructure agent out of the box, but one option on a spectrum,
not the only door in.

The fix is organizational and editorial rather than new surface area.
The /docs/ai/ landing page now opens with the spectrum and splits its
cards into a "Bring your own agent" group (Agent Skills, CLI, MCP server,
Agent Accounts) ahead of the Neo group, and the Skills and MCP pages —
previously weighted dead last in the section — move to the top of the
nav. The what-is pillar page gains an explicit spectrum section and a "do
you need Neo" FAQ. A durable rule in AGENTS.md keeps docs
ecosystem-first while allowing product pages to stay Neo-forward, so this
does not regress.

Two structural cleanups ride along. The Infrastructure AI section moves
up to sit directly after Infrastructure as Code — substrate first, then
the agents built on it — across the nav, llms.txt, and the LLM sitemap,
which all derive from docs_menu_sections.yml. And the "MCP Integrations"
page (Neo consuming external MCP servers) is renamed "External MCP
servers" with cross-references, resolving a same-acronym collision with
the Pulumi MCP server page that points the opposite direction.

The nav label "Agentic infrastructure" (which pointed at /product/neo/
and so named the whole category after one product) becomes the
capability-descriptive "AI infrastructure agent", matching its siblings
that describe capabilities rather than product brands. The Neo product
page drops "unlike generic AI tools" for an honest lead-in acknowledging
the agents customers already use before making Neo's case.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@joeduffy joeduffy marked this pull request as ready for review July 3, 2026 18:52
@github-actions github-actions Bot added review:triaging Claude Triage is currently classifying the PR domain:website PR touches marketing, pricing, legal, or competitive landing pages domain:docs PR touches technical docs domain:mixed PR touches more than one domain domain:infra PR touches workflows, scripts, infra, Makefile, or build config review:in-progress Claude review is currently running and removed review:triaging Claude Triage is currently classifying the PR labels Jul 3, 2026
@pulumi-bot

pulumi-bot commented Jul 3, 2026

Copy link
Copy Markdown
Collaborator

@github-actions

github-actions Bot commented Jul 3, 2026

Copy link
Copy Markdown
Contributor

Pre-merge Review — Last updated 2026-07-07T16:27:09Z

Tip

Summary: This PR rebalances Pulumi's AI documentation and marketing copy so it presents the full spectrum of AI agents — third-party coding agents (Claude Code, Codex, Cursor, GitHub Copilot) working through Agent Skills and the MCP server, alongside Pulumi Neo — rather than framing Neo as the only path. The changes span the /docs/ai/ landing page, the "What is agentic infrastructure?" explainer, homepage and product copy, nav/footer labels, llms.txt, and a new AGENTS.md positioning section; the docs and marketing edits stay within the balanced-vs-lead-with-Neo split that AGENTS.md now codifies. The previously flagged capability overclaim — "parse structured --json output from every command" — is fixed: two follow-up commits first scoped it to "the commands that emit it," then dropped the quantifier entirely, landing on "parse structured --json output" with no unqualified "every"/"all" claim for a reader to trip on. Investigative passes: external verification of 75 extracted claims, a frontmatter/alias sweep, and a cross-sibling read of the four organizations-teams siblings.

Review confidence:

Dimension Level Notes
mechanics HIGH Content-only PR; full Hugo build runs in the deploy job. One pre-existing alias collision noted under 💡.
facts HIGH Both prior facts findings (the --json overclaim and an unattributed "Many teams" claim) resolved by the two follow-up commits.
cross-sibling consistency HIGH Read all four organizations-teams siblings; the added "See also" links introduce no inconsistency.
Investigation log
  • Cross-sibling reads: 4 of 4 siblings
  • External claim verification: 69 of 74 claims verified (2 unverifiable, 1 contradicted) · 4 specialists (numerical, cross-reference, capability, framing); 0 cross-specialist corroborations · routed: 0 inline, 69 Pass 1, 0 Pass 2, 5 Pass 3 (verified 4, contradicted 0, unverifiable 1).
  • 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 1 2

🔍 Verification trail

75 claims extracted · 69 verified · 2 unverifiable · 1 contradicted
  • L97 in AGENTS.md "Pulumi supports the full spectrum of AI agents, and content must never present Neo as the only way to use AI with Pulumi or frame Neo as an either-or choice ag…" → ➖ not-a-claim (evidence: This is internal editorial/positioning guidance in AGENTS.md instructing content authors on how to frame Neo relative to other AI agents—an authored policy statement, not a falsifiable factual assertion about the world.; source: AGENTS.md L97 (self-referential authoring guideline))
  • L99 in AGENTS.md "- Docs (content/docs/, content/what-is/, content/tutorials/): community-centric and balanced. Third-party coding agents (Claude Code, Codex, Cursor,…" → ✅ verified (evidence: Confirmed via GitHub API that content/docs/ai/skills/index.md exists in pulumi/docs (path resolves to /docs/ai/skills/), and content/docs/ai/mcp-server/ also exists, matching both links referenced in the claim.; source: gh api repos/pulumi/docs/contents/content/docs/ai/skills)
  • L274 in content/_index.md "Pulumi's platform allows users to bring their own coding agent, or use Pulumi Neo, to generate, debug, and refactor infrastructure code with built-in best prac…" → ✅ verified (evidence: Line 274 of content/_index.md reads: "Bring your own coding agent — or use Pulumi Neo — to generate, debug, and refactor infrastructure code with built-in best practices and full organizational context," matching the claim almost verbatim,…; source: repo:content/_index.md)
  • L297 in content/_index.md "Pulumi Neo executes complex tasks end-to-end, with or without a human in the loop." → ✅ verified (evidence: content/_index.md L297 states: "Pulumi Neo understands your code and organizational context, respects your policies, and executes complex tasks end-to-end — with or without a human in the loop." The claim is a verbatim restatement of this…; source: repo:content/_index.md)
  • L31-37 in content/docs/_index.md "Pulumi's Infrastructure as Code offering allows defining and managing cloud infrastructure using TypeScript, Python, Go, .NET, Java, and YAML." → ✅ verified (evidence: The source file itself states: "description: Define and manage cloud infrastructure using TypeScript, Python, Go, .NET, Java, and YAML." matching the claim's language list exactly.; source: repo:content/docs/_index.md)
  • L32 in content/docs/_index.md "Pulumi's Infrastructure as Code capability supports defining and managing cloud infrastructure using TypeScript, Python, Go, .NET, Java, and YAML." → ✅ verified (evidence: content/docs/_index.md line 32 reads: "description: Define and manage cloud infrastructure using TypeScript, Python, Go, .NET, Java, and YAML." matching the claim's language list exactly.; source: repo:content/docs/_index.md)
  • L33 in content/docs/_index.md "The Infrastructure as Code section links to /docs/iac/." → ✅ verified (evidence: Line 30-33 of content/docs/_index.md shows the "Infrastructure as Code" card with link: /docs/iac/.; source: repo:content/docs/_index.md)
  • L37 in content/docs/_index.md "The Infrastructure AI section links to /docs/ai/." → ✅ verified (evidence: In content/docs/_index.md, the "Infrastructure AI" card (heading: Infrastructure AI) has link: /docs/ai/ at line 37.; source: repo:content/docs/_index.md)
  • L37 in content/docs/_index.md "link: /docs/ai/" → ✅ verified (evidence: content/docs/ai/_index.md exists in the pulumi/docs repo with title "Infrastructure AI", confirming /docs/ai/ is a valid, existing docs section that the link on line 37 correctly points to.; source: repo:content/docs/ai/_index.md)
  • L79-80 in content/docs/administration/organizations-teams/agent-accounts.md "There exists a Pulumi documentation page about the Pulumi MCP server located at /docs/ai/mcp-server/." → ✅ verified (evidence: The docs repo contains content/docs/ai/mcp-server/index.md (confirmed via GitHub API), which builds to the URL /docs/ai/mcp-server/, matching the linked page "Pulumi MCP server" in the See also section.; source: gh api repos/pulumi/docs/contents/content/docs/ai/mcp-server)
  • L3 in content/docs/ai/_index.md "Pulumi supports using AI agents including Claude Code, Codex, or Cursor via Agent Skills and the MCP server." → ✅ verified (evidence: The same page's meta_desc states: "Use AI agents with Pulumi. Bring Claude Code, Codex, or Cursor via Agent Skills and the MCP server, or use Neo, the purpose-built infrastructure agent," and the body reiterates "agents like Claude Code, C…; source: repo:content/docs/ai/_index.md)
  • L3 in content/docs/ai/_index.md "Pulumi Neo is a purpose-built infrastructure agent offered by Pulumi." → ✅ verified (evidence: The same page's meta_desc/description explicitly describes Neo as "the purpose-built infrastructure agent" / "Neo, a purpose-built infrastructure agent" offered by Pulumi, and product/neo.md is titled "Pulumi Neo - Your AI Infrastructure A…; source: repo:content/docs/ai/_index.md)
  • L10 in content/docs/ai/_index.md "Pulumi works with AI agents that users already use." → ✅ verified (evidence: The page's own description field states: "Pulumi works with the AI agents you already use and provides Neo, a purpose-built infrastructure agent, for the deepest integration," and the Overview section lists Claude Code, Codex, Cursor, and…; source: repo:content/docs/ai/_index.md)
  • L10 in content/docs/ai/_index.md "Pulumi Neo is a purpose-built infrastructure agent that provides the deepest integration with Pulumi." → ✅ verified (evidence: The same page's front matter states "Pulumi works with the AI agents you already use and provides Neo, a purpose-built infrastructure agent, for the deepest integration," and the body describes Neo as "Pulumi's own infrastructure agent," m…; source: repo:content/docs/ai/_index.md)
  • L30 in content/docs/ai/_index.md "pulumi do performs one-shot resource operations." → ✅ verified (evidence: The docs page for pulumi do states: "The pulumi do command provides direct operations on cloud resources through the Pulumi CLI without requiring a project, program, or state file... Resource operations: Create, read, patch (update), a…; source: repo:content/docs/iac/cli/direct-resource-operations.md)
  • L30 in content/docs/ai/_index.md "The Pulumi MCP server offers the same reach as Pulumi Agent Skills, but over MCP." → ✅ verified (evidence: The same page states: "Pulumi Agent Skills teach agents proven Pulumi workflows, the Pulumi MCP server offers the same reach over MCP, and agent accounts remove signup friction entirely." This is a direct, near-verbatim match to the claim…; source: repo:content/docs/ai/_index.md)
  • L30 in content/docs/ai/_index.md "Agent accounts remove signup friction entirely for AI agents using Pulumi." → ✅ verified (evidence: The agent-accounts doc states "Agent accounts give AI agents a free ephemeral Pulumi Cloud account to work in, without requiring a human user to sign up first," and the linked blog post says agent accounts let agents "do anything a human c…; source: repo:content/docs/administration/organizations-teams/agent-accounts.md; pulumi/docs:content/blog/the-agentic-infrastructure-era/index.md)
  • L30 in content/docs/ai/_index.md "AI agents such as Claude Code, Codex, Cursor, and GitHub Copilot can write, preview, and deploy Pulumi infrastructure directly." → ✅ verified (evidence: The same page states: "agents like Claude Code, Codex, Cursor, and GitHub Copilot can write, preview, and deploy it directly" and links to /docs/iac/cli/, which exists and describes the CLI's agent-friendly design (npx pulumi, pulumi do, -…; source: repo:content/docs/ai/_index.md)
  • L32 in content/docs/ai/_index.md "Neo is intended for long-running, governed infrastructure tasks, while a coding agent is intended for interactive development." → ✅ verified (framing: strengthened — the sources establish Neo's governed/long-running lifecycle role and separately establish coding agents' interactive code-generation role; the c…; evidence: Sources describe Neo as governing "the full infrastructure lifecycle" with "Fully agentic workflow: Launch short- or long-running tasks with approvals" and enterprise governance (RBAC, policy), while distinguishing it from coding agents/as…; source: https://www.pulumi.com/product/neo/ and https://www.pulumi.com/blog/pulumi-neo/)
  • L39 in content/docs/ai/_index.md "link: /docs/ai/skills/" → ✅ verified (evidence: The target page exists in the pulumi/docs repo at content/docs/ai/skills/index.md (html_url: github.com/pulumi/docs/blob/master/content/docs/ai/skills/index.md), and the same /docs/ai/skills/ path is referenced consistently across other pu…; source: gh api repos/pulumi/docs/contents/content/docs/ai/skills)
  • L40 in content/docs/ai/_index.md "Pulumi Agent Skills can teach Claude Code, Codex, Cursor, Copilot, and other agents Pulumi workflows." → ✅ verified (evidence: Sibling page content/docs/ai/skills/index.md meta_desc states: "Learn how Pulumi Agent Skills teach Claude Code, Cursor, GitHub Copilot, and JetBrains Junie to work with Pulumi." The _index.md overview line also names "agents like Claude C…; source: repo:content/docs/ai/skills/index.md and repo:content/docs/ai/_index.md)
  • L43 in content/docs/ai/_index.md "link: /docs/iac/cli/" → ✅ verified (evidence: content/docs/iac/cli/_index.md exists in the repo with title "Pulumi CLI", confirming the link target /docs/iac/cli/ is valid.; source: repo:content/docs/iac/cli/_index.md)
  • L44 in content/docs/ai/_index.md "The Pulumi CLI is agent-friendly, supporting invocation via npx pulumi and pulumi do as well as structured JSON output." → ✅ verified (evidence: The same page's overview text states: "run any command with npx pulumi, perform one-shot resource operations with pulumi do, and parse structured --json output from every command." The pulumi do doc confirms "All pulumi do operatio…; source: repo:content/docs/ai/_index.md and repo:content/docs/iac/cli/direct-resource-operations.md)
  • L47 in content/docs/ai/_index.md "link: /docs/ai/mcp-server/" → ✅ verified (evidence: The link target content/docs/ai/mcp-server/index.md exists in pulumi/docs repo (confirmed via GitHub contents API), so /docs/ai/mcp-server/ resolves to a real, existing page linked from the AI overview page.; source: gh api repos/pulumi/docs/contents/content/docs/ai/mcp-server)
  • L48 in content/docs/ai/_index.md "The Pulumi MCP server gives any MCP-capable agent access to Pulumi Cloud resources and the Registry." → ✅ verified (evidence: The same _index.md card text reads "Give any MCP-capable agent access to your Pulumi Cloud resources and the Registry," and the linked mcp-server/index.md page details tools for querying Pulumi Cloud resources ("Query your Pulumi Cloud sta…; source: repo:content/docs/ai/_index.md L48; repo:content/docs/ai/mcp-server/index.md)
  • L51 in content/docs/ai/_index.md "link: /docs/administration/organizations-teams/agent-accounts/" → ✅ verified (evidence: The file content/docs/administration/organizations-teams/agent-accounts.md exists in pulumi/docs, confirming the link target /docs/administration/organizations-teams/agent-accounts/ is a valid, existing page. It's also referenced consi…; source: gh api search/code?q=repo:pulumi/docs+filename:agent-accounts)
  • L52 in content/docs/ai/_index.md "Pulumi Agent Accounts are ephemeral Pulumi Cloud accounts provisioned automatically for AI agents." → ✅ verified (evidence: The sibling docs page states: "Agent accounts give AI agents a free ephemeral Pulumi Cloud account to work in, without requiring a human user to sign up first... it creates an account automatically and continues," matching the claim's descri…; source: repo:content/docs/administration/organizations-teams/agent-accounts.md)
  • L69-72 in content/docs/ai/_index.md "Neo reviews pull requests against what Pulumi Cloud knows about the running infrastructure, as part of a Code Reviews capability." → ✅ verified (evidence: The linked page content/docs/ai/code-reviews/_index.md states: "Neo code reviews analyze pull requests against what Pulumi Cloud knows about your running infrastructure and leave feedback in the pull request," confirming Code Reviews is th…; source: repo:content/docs/ai/code-reviews/_index.md)
  • L71 in content/docs/ai/_index.md "link: /docs/ai/code-reviews/" → ✅ verified (evidence: The file content/docs/ai/code-reviews/_index.md exists in pulumi/docs (title: "Code reviews", h1: "Neo code reviews"), confirming the link /docs/ai/code-reviews/ resolves to a valid page.; source: gh api repos/pulumi/docs/contents/content/docs/ai/code-reviews/_index.md)
  • L82-84 in content/docs/ai/_index.md "Running pulumi neo starts an interactive Neo session in the terminal." → ✅ verified (evidence: Pulumi CLI source and blog confirm this: pkg/backend/display/ai.go prints "Or run pulumi neo for an interactive agent in your terminal," and the pulumi-neo-cli blog post states "Pulumi Neo is now available in the terminal! As of today, y…; source: gh search code --owner pulumi "pulumi neo" (pulumi/pulumi:pkg/backend/display/ai.go; pulumi/docs:content/blog/pulumi-neo-cli/index.md))
  • L2-4 in content/docs/ai/integrations/mcp/_index.md "The page/section previously titled 'MCP Integrations' has been renamed to 'External MCP Servers'." (also L8) → ✅ verified (evidence: gh search of the repo shows the prior indexed version of content/docs/ai/integrations/mcp/_index.md had title: MCP Integrations / h1: MCP Integrations, while the current file content (read directly) now has `title: External MCP Servers…; source: gh search code --owner pulumi "MCP Integrations" -R pulumi/docs; repo:content/docs/ai/integrations/mcp/_index.md)
  • L14 in content/docs/ai/integrations/mcp/_index.md "Once connected, Neo can use external MCP-exposed services as tools during a task." → ✅ verified (evidence: The same doc states: "Once connected, Neo can use those services as tools during a task, with credentials managed centrally in Pulumi Cloud" — an exact match to the claim's framing.; source: repo:content/docs/ai/integrations/mcp/_index.md)
  • L14 in content/docs/ai/integrations/mcp/_index.md "There exists a documentation page at /docs/ai/tasks/ describing 'task' in the context of Neo." → ✅ verified (evidence: content/docs/ai/tasks/_index.md exists at /docs/ai/tasks/ with title "Tasks" and content "Tasks are Neo's primary unit of work. Each task is a conversation where you describe what you want to accomplish, and Neo handles the infrastructure…; source: repo:content/docs/ai/tasks/_index.md)
  • L14 in content/docs/ai/integrations/mcp/_index.md "MCP integrations connect Neo to external services that expose a Model Context Protocol (MCP) server." → ✅ verified (evidence: The page itself states verbatim: "MCP integrations connect Neo to external services that expose a Model Context Protocol server." — the claim is a direct quote of the doc's intro sentence.; source: repo:content/docs/ai/integrations/mcp/_index.md)
  • L14 in content/docs/ai/integrations/mcp/_index.md "Credentials for external MCP service connections are managed centrally in Pulumi Cloud." → ✅ verified (evidence: The same doc states: "credentials managed centrally in Pulumi Cloud" and later "Integration credentials are encrypted at rest in Pulumi Cloud using a per-organization encryption key. When a task needs to connect to an integration, Pulumi C…; source: repo:content/docs/ai/integrations/mcp/_index.md)
  • L16-17 in content/docs/ai/integrations/mcp/_index.md "This page (External MCP Servers) is about connecting Neo to other services' MCP servers, as distinct from connecting your own AI agent (e.g., Claude Code, Curs…" → ✅ verified (evidence: The page itself states: "This page is about connecting Neo to other services' MCP servers. To connect your own AI agent (Claude Code, Cursor, and others) to Pulumi, see the Pulumi MCP server." which matches the clai…; source: repo:content/docs/ai/integrations/mcp/_index.md)
  • L19 in content/docs/ai/integrations/mcp/_index.md "MCP integrations are configured at the organization level by an administrator." → ✅ verified (evidence: The doc states verbatim: "MCP integrations are configured at the organization level by an administrator. Once enabled, they are available to all Neo tasks in the organization," and the Enabling section describes navigating to Neo Settings…; source: repo:content/docs/ai/integrations/mcp/_index.md)
  • L19 in content/docs/ai/integrations/mcp/_index.md "Once an MCP integration is enabled, it becomes available to all Neo tasks in the organization." → ✅ verified (evidence: The doc states: "MCP integrations are configured at the organization level by an administrator. Once enabled, they are available to all Neo tasks in the organization." This directly matches the claim, and is further reinforced by "By defau…; source: repo:content/docs/ai/integrations/mcp/_index.md)
  • L18 in content/docs/ai/mcp-server/index.md "The Pulumi MCP server integration allows launching automated infrastructure workflows from within the AI assistant of the user's choice." → ✅ verified (evidence: The doc itself states: "This integration allows you to query your cloud infrastructure, search for resources, and launch automated infrastructure workflows - all from within the AI assistant of your choice," and further documents a neo-bri…; source: repo:content/docs/ai/mcp-server/index.md)
  • L20-21 in content/docs/ai/mcp-server/index.md "This documentation page is about connecting a user's own AI agent to Pulumi, as opposed to connecting Pulumi Neo to other services' MCP servers." → ✅ verified (evidence: The page itself contains this exact framing in an INFO callout: "This page is about connecting your own AI agent to Pulumi. For the opposite direction, connecting Neo to other services' MCP servers (Jira, Datadog, and others), see [Externa…; source: repo:content/docs/ai/mcp-server/index.md)
  • L429-430 in content/docs/ai/mcp-server/index.md "Pulumi Cloud supports 'Agent accounts', which are ephemeral Pulumi Cloud accounts provisioned automatically for agents, documented at /docs/administration/orga…" → ✅ verified (evidence: The page content/docs/administration/organizations-teams/agent-accounts.md exists with meta_desc: "Agent accounts let AI agents provision ephemeral Pulumi Cloud accounts automatically so agents can use state and ESC without manual signup,"…; source: gh search code --owner pulumi "Agent accounts" (pulumi/docs:content/docs/administration/organizations-teams/agent-accounts.md))
  • L431 in content/docs/ai/mcp-server/index.md "Pulumi has a documentation page titled 'What is agentic infrastructure?' located at /what-is/what-is-agentic-infrastructure/." → ✅ verified (evidence: File content/what-is/what-is-agentic-infrastructure.md exists in pulumi/docs with front matter title "What Is Agentic Infrastructure?", confirming the page at /what-is/what-is-agentic-infrastructure/ exists as linked.; source: gh api repos/pulumi/docs/contents/content/what-is (file listing) and read_file content/what-is/what-is-agentic-infrastructure.md)
  • L5 in content/docs/ai/pulumi-cli/_index.md "An interactive Neo session started via pulumi neo has access to your local project, credentials, and stacks." → ✅ verified (evidence: The page's own meta_desc states: "Run pulumi neo to start an interactive Neo session in your terminal with access to your local project, credentials, and stacks," and the body explains "Neo inherits your setup: the CLIs you've authenticate…; source: repo:content/docs/ai/pulumi-cli/_index.md)
  • L8 in content/docs/ai/pulumi-cli/_index.md "The navigation menu entry previously labeled 'Pulumi CLI' is renamed to 'Neo in the CLI'." → ✅ verified (evidence: The file's front matter directly shows the current menu configuration: menu: ai: name: Neo in the CLI, identifier: ai-pulumi-cli, confirming the nav label is now 'Neo in the CLI' while the identifier retains the legacy 'pulumi-cli' slug,…; source: repo:content/docs/ai/pulumi-cli/_index.md)
  • L199 in content/docs/ai/skills/index.md "The CONTRIBUTING.md file at https://github.com/pulumi/agent-skills/blob/main/CONTRIBUTING.md contains guidelines for contributing." → ✅ verified (evidence: The file exists at https://github.com/pulumi/agent-skills/blob/main/CONTRIBUTING.md and begins "# Contributing to Pulumi Agent Skills\n\nThank you for your interest in contributing to Pulumi's Agent Skills! This guide covers how to write,…; source: gh api repos/pulumi/agent-skills/contents/CONTRIBUTING.md)
  • L203-204 in content/docs/ai/skills/index.md "A page documenting agent accounts exists at /docs/administration/organizations-teams/agent-accounts/." → ✅ verified (evidence: The file content/docs/administration/organizations-teams/agent-accounts.md exists in pulumi/docs, which maps to the /docs/administration/organizations-teams/agent-accounts/ page. It's linked from multiple other docs/blog pages, e.g. "[Agen…; source: gh api repos/pulumi/docs/contents/content/docs/administration/organizations-teams)
  • L204 in content/docs/ai/skills/index.md "- Agent accounts - ephemeral Pulumi Cloud accounts provisioned automatically for agents" → ✅ verified (evidence: The page content/docs/administration/organizations-teams/agent-accounts.md exists at that URL and states: "Agent accounts give AI agents a free ephemeral Pulumi Cloud account to work in, without requiring a human user to sign up first. Whe…; source: gh api repos/pulumi/docs/contents/content/docs/administration/organizations-teams/agent-accounts.md)
  • L205 in content/docs/ai/skills/index.md "A page titled 'What is agentic infrastructure?' describing the broader picture of AI agents operating infrastructure exists at /what-is/what-is-agentic-infrast…" → ❌ contradicted (evidence: Listing content/what-is/ in pulumi/docs shows many "what-is-*" pages (e.g. infrastructure-as-code-for-devops.md, javascript-and-infrastructure-as-code.md, python-for-devops.md) but no "what-is-agentic-infrastructure.md", and a code search…; source: gh api repos/pulumi/docs/contents/content/what-is; gh search code repo:pulumi/docs "what-is-agentic-infrastructure")
  • L530 in content/docs/install/_index.md "The Pulumi MCP server provides live access to a user's Pulumi Cloud stacks, resources, and the Pulumi Registry when an assistant is connected to it." → ✅ verified (evidence: The linked /docs/ai/mcp-server/ page states: "Pulumi's MCP server implementation provides AI assistants with the ability to: Query your Pulumi Cloud stacks and their resources... Access the Pulumi Registry for resource information, propert…; source: gh api repos/pulumi/docs/contents/content/docs/ai/mcp-server/index.md)
  • L52 in content/product/_index.md "Pulumi Neo works with coding agents including Claude Code, Codex, and Cursor." → ✅ verified (framing: strengthened — claim narrows the general "Pulumi works with..." statement to "Pulumi Neo works with...", but this is within the same section introducing Neo, s…; evidence: The same file states: "Pulumi works with the coding agents your team already uses — Claude Code, Codex, Cursor, and more. Neo is the industry's first AI agent purpose-built for infrastructure..." confirming Neo's section explicitly names C…; source: repo:content/product/_index.md L51-52)
  • L36 in content/product/neo.md "Neo is the industry's first AI agent built from the ground up to execute, govern, and optimize complex cloud automation at enterprise scale." → 🤷 unverifiable (evidence: The claim is Pulumi's own marketing superlative about Neo, repeated consistently across their own pages (content/product/_index.md: "The industry's first AI agent purpose-built for infrastructure"). There is no third-party authoritative so…; source: gh search code --owner pulumi "industry's first AI agent" (pulumi/docs:content/product/neo.md, content/product/_index.md); intuition: "Industry's first" is a common but unverifiable marketing superlative; consistent with sibling pages but not something…)
  • L49 in content/what-is/what-is-agentic-infrastructure.md "The CodeAct paper (Wang et al., ICML 2024) found that agents consistently perform better when they act by writing executable code rather than emitting JSON or…" → ✅ verified (evidence: The paper "Executable Code Actions Elicit Better LLM Agents" by Xingyao Wang et al., ICML 2024, found that "CodeAct outperforms widely used alternatives like Text and JSON (up to 20% higher success rate)," directly supporting the claim tha…; source: https://github.com/xingyaoww/code-act)
  • L53 in content/what-is/what-is-agentic-infrastructure.md "Because Pulumi expresses infrastructure in general-purpose languages, coding agents like Claude Code, OpenAI Codex, Cursor, and GitHub Copilot can write, previ…" → ✅ verified (evidence: The same page's sibling FAQ states: "Any coding agent can manage Pulumi infrastructure directly, and Pulumi Agent Skills and the Pulumi MCP server make agents like Claude Code, Codex, and Cursor considerably better at it" — consistent with…; source: repo:content/what-is/what-is-agentic-infrastructure.md (L175))
  • L55 in content/what-is/what-is-agentic-infrastructure.md "The Pulumi CLI allows performing one-shot resource operations with pulumi do." → ✅ verified (evidence: pulumi/docs blog confirms: "The new pulumi do command enables direct create, read, update, delete, list, and API operations with a single command," and it ships as documented at /docs/iac/cli/direct-resource-operations/, matching the cla…; source: gh search code "direct-resource-operations" --repo pulumi/docs; pulumi/docs:content/blog/the-agentic-infrastructure-era/index.md)
  • L55 in content/what-is/what-is-agentic-infrastructure.md "The Pulumi CLI can parse structured --json output." → ✅ verified (evidence: 46c4df5/d0c76f0 dropped the "from every command" quantifier that pulumi_new.md contradicted — pulumi new has no --json flag among its options (-l, --list-templates, -n, --name string, etc.). The claim as it now reads no longer asserts universality, and the CLI does support structured --json/JSON output on many commands (corroborated by L44's verified claim on the same page); source: repo:content/docs/iac/cli/commands/pulumi_new.md; repo:content/docs/ai/_index.md L30)
  • L55 in content/what-is/what-is-agentic-infrastructure.md "Ephemeral accounts can be provisioned automatically for agents via the agent-accounts feature." → ✅ verified (evidence: Pulumi blog confirms: "Now agents can use free, ephemeral Pulumi Cloud accounts straight from Claude Code, Codex, OpenCode, Copilot, Cursor, and others... [Agent accounts]... simplify this by letting an agent provision its own ephemeral Pu…; source: gh search code --owner pulumi "agent-accounts" (pulumi/docs:content/blog/the-agentic-infrastructure-era/index.md, content/blog/pulumi-do-direct-resource-operations/index.md))
  • L55 in content/what-is/what-is-agentic-infrastructure.md "An agent editing Pulumi code can run pulumi preview to check the plan against its intent, and this verification loop works out of the box with no special int…" → ✅ verified (evidence: The Pulumi CLI docs page (/docs/iac/cli/) lists pulumi preview as a standard, built-in CLI command ("preview your changes explicitly before deploying") available via the open-source CLI with no special setup — consistent with the claim t…; source: repo:content/docs/iac/cli/_index.md)
  • L57 in content/what-is/what-is-agentic-infrastructure.md "Pulumi Agent Skills teach agents proven Pulumi workflows, including migrations, component authoring, and secrets management." → ✅ verified (evidence: The /docs/ai/skills/ page confirms this exactly: "These skills help with infrastructure migrations, secret management, and code translation" and lists a Migration Plugin (Terraform/CDK/CloudFormation/ARM to Pulumi), a "pulumi-component" sk…; source: repo:content/docs/ai/skills/index.md)
  • L59 in content/what-is/what-is-agentic-infrastructure.md "Pulumi Neo adds grounding in an organization's actual infrastructure state." → ✅ verified (evidence: The same document elaborates this exact claim: Neo "queries your actual Pulumi state graph" and "synthesizes a plan grounded in your real environment, not in hypothetical configurations," and is described as "grounded AI: it reasons over y…; source: repo:content/what-is/what-is-agentic-infrastructure.md (lines 71, 83))
  • L61 in content/what-is/what-is-agentic-infrastructure.md "Many teams use Pulumi Neo for scheduled, longer-horizon infrastructure work and their everyday coding agent for interactive development." → 🤷 unverifiable (evidence: The linked /docs/ai/skills/ page documents the technical hand-off mechanism ("Hand off in-progress work from coding agents to Pulumi Neo" via the pulumi-neo-handoff skill) but makes no claim about how "many teams" actually divide work betw…; source: content/docs/ai/skills/index.md; intuition: Unattributed "many teams" usage-pattern claim with no survey/data backing; reads as plausible marketing framing rather…)
  • L137 in content/what-is/what-is-agentic-infrastructure.md "There are two entry points to agentic infrastructure with Pulumi: bringing the coding agent you already use, or using Pulumi Neo, which is built into Pulumi Cl…" → ✅ verified (evidence: Line 137 of the source file reads: "There are two entry points, and they compose: bring the coding agent you already use, or use Pulumi Neo, which is built into Pulumi Cloud." This is a faithful paraphrase of the doc's own…; source: repo:content/what-is/what-is-agentic-infrastructure.md (line 137); pulumi/docs search for "product/neo")
  • L139 in content/what-is/what-is-agentic-infrastructure.md "Pulumi provides conversion documentation for teams migrating from other tools, covering common starting points." → ✅ verified (evidence: The page /docs/iac/comparisons/terraform/ contains a section "## Adoption: coexistence, conversion, and import" stating "There are several common paths for adopting Pulumi alongside or in place of Terraform, and they can be combined," dire…; source: repo:content/docs/iac/comparisons/terraform/_index.md)
  • L141 in content/what-is/what-is-agentic-infrastructure.md "You can start using either the coding agent approach or Neo with a single project or stack before expanding." → ➖ not-a-claim (evidence: This is the author's own practical recommendation within a "How do you get started" walkthrough, consistent with the document's own Step 1-6 progressive rollout guidance ("Step 6: Expand to more environments... extend it"). It is not a fal…; source: repo:content/what-is/what-is-agentic-infrastructure.md L135-149)
  • L171 in content/what-is/what-is-agentic-infrastructure.md "Pulumi Neo accepts natural-language tasks, reasons over your actual infrastructure state graph, writes and modifies infrastructure code, runs previews, enforce…" → 🤝 matches (evidence: The same file's workflow walkthrough describes Neo taking a natural-language task ("A user sends the goal in natural language"), querying "your actual Pulumi state graph," generating code, running pulumi preview, running "your Pulumi Pol…; source: repo:content/what-is/what-is-agentic-infrastructure.md)
  • L171 in content/what-is/what-is-agentic-infrastructure.md "Pulumi Neo provides configurable human-in-the-loop controls." → ✅ verified (evidence: The same document states Neo "adds grounding in your organization's actual infrastructure state, policy guardrails, configurable human-in-the-loop approvals, and scheduled autonomous work" and elaborates: "Configurable human-in-the-loop. R…; source: repo:content/what-is/what-is-agentic-infrastructure.md (lines 59, 113))
  • L171 in content/what-is/what-is-agentic-infrastructure.md "Pulumi Neo works across Amazon Web Services (AWS), Azure, Google Cloud, and hundreds of other providers." → ✅ verified (evidence: Sibling docs consistently describe Pulumi's provider ecosystem the same way: content/product/infrastructure-as-code.md states "Access AWS, Azure, Google Cloud, Kubernetes, and hundreds of providers through a unified, consistent API," and c…; source: gh search code --owner pulumi "hundreds of providers")
  • L175 in content/what-is/what-is-agentic-infrastructure.md "Pulumi Neo adds grounding in your actual infrastructure state, built-in policy enforcement, and scheduled autonomous tasks, which a general-purpose agent doesn…" → ✅ verified (evidence: Line 175 of the same file states verbatim: "Neo adds what a general-purpose agent doesn't have out of the box: grounding in your actual infrastructure state, built-in policy enforcement, and scheduled autonomous tasks." This is corroborate…; source: repo:content/what-is/what-is-agentic-infrastructure.md#L175 and pulumi/docs:content/docs/ai/skills/index.md)
  • L203 in content/what-is/what-is-agentic-infrastructure.md "The Pulumi Neo product page covers capabilities and sign-up." → ✅ verified (evidence: The page exists at pulumi/docs:content/product/neo.md and is linked site-wide as the canonical Neo product page (e.g., data/header_nav.yaml, content/_index.md cta_link: /product/neo/, and dozens of docs pages referencing '[Pulumi Neo](/pro…; source: gh search code --owner pulumi "product/neo" (pulumi/docs:content/product/neo.md, data/header_nav.yaml, content/_index.md cta_link: /product/neo/))
  • L203 in content/what-is/what-is-agentic-infrastructure.md "'10 things you can do with Neo' walks through concrete examples." → ✅ verified (evidence: The blog post at the cited URL is titled "10 Things You Can Do With Our Infrastructure Agent, Neo" and states: "Here are 10 concrete workflows that platform teams can use Neo for right now, each one designed to save hours of manual work."; source: https://www.pulumi.com/blog/10-things-you-can-do-with-neo/)
  • L203 in content/what-is/what-is-agentic-infrastructure.md "The Pulumi Agent Skills and Pulumi MCP server documentation pages are where you go to equip the coding agent you already use." → ✅ verified (evidence: The pulumi/docs repo contains both content/docs/ai/skills and content/docs/ai/mcp-server directories, and the same page's body text states: "Pulumi Agent Skills teach agents proven Pulumi workflows ... and the Pulumi MCP server gives them…; source: gh api repos/pulumi/docs/contents/content/docs/ai --jq ".[].name")
  • L203 in content/what-is/what-is-agentic-infrastructure.md "The Pulumi Policies docs and the full Neo documentation are the authoritative references for governance specifics." → ✅ verified (evidence: Both cited destinations exist and are used elsewhere in the same doc: "Pulumi Policies lets teams define organizational rules as code..." and "See the Neo documentation for a full reference," confirming…; source: repo:content/what-is/what-is-agentic-infrastructure.md)
  • L203 in content/what-is/what-is-agentic-infrastructure.md "'Grounded AI: Why Neo Knows Your Infrastructure' explains the context lake approach that makes Neo reliable for production." → ✅ verified (evidence: The blog post "Grounded AI: Why Neo Knows Your Infrastructure" exists and discusses the context lake concept: "When you combine observability data, infrastructure-as-code programs, and deployment history into a context lake, the AI doesn't…; source: https://www.pulumi.com/blog/grounded-ai-why-neo-knows-your-infrastructure/)
  • L70 in layouts/index.llms.txt "- Doing infrastructure work as an agent — the Pulumi CLI is designed for agents: run any command with npx pulumi, perform one-shot resource operations wi…" → ✅ verified (evidence: Both linked docs pages exist in pulumi/docs at the cited paths: content/docs/iac/cli/direct-resource-operations.md (for pulumi do) and content/docs/administration/organizations-teams/agent-accounts.md, whose meta description states "Agen…; source: gh api repos/pulumi/docs/contents/content/docs/administration/organizations-teams/agent-accounts.md)
  • L79 in layouts/index.llms.txt "- Infrastructure AI: Using AI agents with Pulumi — bring your own agent via [Agent Skills](https://www.pulumi.com/docs/ai/sk…" → ✅ verified (evidence: Repo confirms: docs_menu_sections.yml has menu 'ai' labeled 'Infrastructure AI'; content/docs/ai/skills/index.md exists titled 'Agent Skills' ('Learn how Pulumi Agent Skills teach Claude Code, Cursor, GitHub Copilot, and JetBrains Junie to…; source: gh search code --owner pulumi repo:pulumi/docs "Agent Skills"; repo:data/docs_menu_sections.yml)
  • L1 in content/docs/_index.md "frontmatter alias /docs/reference/ collides with content/docs/reference/_index.md" → 🚩 flagged (frontmatter: alias-collision)

🚨 Outstanding in this PR

No outstanding findings in this PR.

⚠️ Low-confidence

No low-confidence findings.

📋 Triaged verifier findings

I double-checked these and realized they weren't real findings — click to expand
  • [L205] content/docs/ai/skills/index.md — link to /what-is/what-is-agentic-infrastructure/ flagged as ❌ contradicted (target page reportedly not found). Spurious: the page exists — content/what-is/what-is-agentic-infrastructure.md is present in the repo (this PR edits it) and resolves to /what-is/what-is-agentic-infrastructure/, confirmed by the frontmatter sweep. The verification step's file listing simply missed it.

💡 Pre-existing issues in touched files (optional)

  • [L1] content/docs/_index.mdPre-existing: the frontmatter alias /docs/reference/ collides with the live page at content/docs/reference/_index.md (the real page wins, so the alias is inert). This PR only reorders the section cards and doesn't touch the aliases list, so the collision predates it. Worth removing the dead alias in a follow-up, but not this PR's concern.

✅ Resolved since last review

  • [L30] content/docs/ai/_index.md / [L55] content/what-is/what-is-agentic-infrastructure.md"…and parse structured --json output from every command." — ✅ resolved: 46c4df5 first scoped the claim to "the commands that emit it," then d0c76f0 dropped the quantifier entirely rather than hedge it, landing on "parse structured --json output" — no more unqualified "every command" for pulumi new and other scaffolding commands to contradict.

  • [L61] content/what-is/what-is-agentic-infrastructure.md"Many teams use Pulumi Neo for scheduled, longer-horizon infrastructure work and their everyday coding agent for interactive development." — ✅ resolved: 46c4df5 softened the unattributed "Many teams" adoption claim to "Teams often," removing the implication of measured usage data.

📜 Review history

  • 2026-07-03T18:55:41Z — Balanced AI-positioning rebalance; flagged one --json-from-every-command overclaim, triaged a spurious "page not found" flag and a pre-existing alias collision (f87819a)
  • 2026-07-07T16:27:09Z — Re-reviewed after fix push (2 new commits, d0c76f0); both facts findings resolved, 0 outstanding remain

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.)

@github-actions github-actions Bot added review:outstanding-issues Claude review completed; outstanding has author-actionable findings and removed review:in-progress Claude review is currently running labels Jul 3, 2026
@pulumi-bot

pulumi-bot commented Jul 3, 2026

Copy link
Copy Markdown
Collaborator

Lighthouse Performance Report

Commit: d0c76f0 | Metric definitions

Page Device Score FCP LCP TBT CLS SI
Homepage Mobile 🔴 37 6.1s 12.8s 1047ms 0.001 6.1s
Homepage Desktop 🟡 63 0.7s 1.1s 291ms 0.320 2.7s
Install Pulumi Mobile 🟡 58 5.5s 8.0s 52ms 0.057 7.7s
Install Pulumi Desktop 🟡 82 1.3s 1.9s 0ms 0.145 1.4s
AWS Get Started Mobile 🟡 60 5.2s 7.9s 90ms 0.092 5.2s
AWS Get Started Desktop 🟡 82 1.2s 1.9s 0ms 0.024 2.7s

The pre-merge review flagged "parse structured --json output from every
command" as an overclaim: scaffolding and interactive commands like
pulumi new have no --json flag, so the universal "every command" is
wrong. Scope it to "the commands that emit it" on both the /docs/ai/
landing page and the what-is explainer. Also soften an unattributed
"Many teams" adoption claim to "Teams often" and reword a "There are"
sentence opener, both on the what-is page.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@github-actions github-actions Bot added review:stale New commits since last Claude review; refresh on next ready-transition or @claude mention and removed review:outstanding-issues Claude review completed; outstanding has author-actionable findings labels Jul 3, 2026
"from the commands that emit it" was a clunky hedge that undersold the
CLI's agent-friendly design to avoid a pedantic contradiction, while
"from every command" overclaimed a flag that pulumi new and other
scaffolding commands don't have. Neither serves the reader. Drop the
quantifier entirely: "parse structured --json output" states the
capability truthfully without a universal claim an agent would trip on
or a caveat that obscures the point.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@CamSoper

CamSoper commented Jul 7, 2026

Copy link
Copy Markdown
Contributor

@claude #update-review

@github-actions github-actions Bot added review:in-progress Claude review is currently running and removed review:stale New commits since last Claude review; refresh on next ready-transition or @claude mention labels Jul 7, 2026
@github-actions

github-actions Bot commented Jul 7, 2026

Copy link
Copy Markdown
Contributor

🤖 Review updated on @CamSoper's request.

@github-actions github-actions Bot added review:no-blockers Claude review completed cleanly; outstanding is empty and removed review:in-progress Claude review is currently running labels Jul 7, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

domain:docs PR touches technical docs domain:infra PR touches workflows, scripts, infra, Makefile, or build config domain:mixed PR touches more than one domain domain:website PR touches marketing, pricing, legal, or competitive landing pages review:no-blockers Claude review completed cleanly; outstanding is empty

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants