Rebalance AI docs to lead with the agent ecosystem, not only Neo#20079
Rebalance AI docs to lead with the agent ecosystem, not only Neo#20079joeduffy wants to merge 3 commits into
Conversation
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>
|
Your site preview for commit d0c76f0 is ready! 🎉 http://www-testing-pulumi-docs-origin-pr-20079-d0c76f07.s3-website.us-west-2.amazonaws.com |
Pre-merge Review — Last updated 2026-07-07T16:27:09ZTip 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 Review confidence:
Investigation log
🔍 Verification trail75 claims extracted · 69 verified · 2 unverifiable · 1 contradicted
🚨 Outstanding in this PRNo outstanding findings in this PR.
|
Lighthouse Performance ReportCommit: d0c76f0 | Metric definitions
|
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>
"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>
|
@claude #update-review |
|
🤖 Review updated on @CamSoper's request. |
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 fromdata/docs_menu_sections.yml).what-is-agentic-infrastructurepillar 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 label —
Agentic infrastructure→AI infrastructure agentin 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 errorsmake build— succeeds; rendered output spot-checked for nav order, card grids,/llms.txt, and the LLM sitemapNotes
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