jkodroff · Oct 22, 2026 · Oct 12, 2026 · Oct 12, 2026 · Oct 22, 2026 · Oct 22, 2026
diff --git a/content/docs/administration/concepts/agent-accounts.md b/content/docs/administration/concepts/agent-accounts.md
@@ -75,7 +75,7 @@ In these cases, the CLI uses the existing credentials. If multiple agents run on
 ## See also
 
 - [Pulumi Cloud accounts](/docs/administration/concepts/accounts/)
-- [Pulumi Agent Skills](/docs/ai/skills/)
-- [Pulumi MCP server](/docs/ai/mcp-server/)
+- [Pulumi Agent Skills](/docs/ai/concepts/agent-skills/)
+- [Pulumi MCP server](/docs/ai/guides/set-up-mcp-server/)
 - [The agentic infrastructure era](/blog/the-agentic-infrastructure-era/) (blog post)
 - [Direct resource operations](/docs/iac/cli/direct-resource-operations/)
diff --git a/content/docs/administration/concepts/billing-managers.md b/content/docs/administration/concepts/billing-managers.md
@@ -58,7 +58,7 @@ Billing managers can be removed by any organization admin at any time. The steps
 
 ## Billing manager permissions
 
-A billing manager has the ability to access and update billing information, and to view organization metrics, such as resource count and member count (but not member names). This includes setting [Neo usage limits](/docs/ai/neo/usage-limits/) to cap what the organization spends on Pulumi Neo.
+A billing manager has the ability to access and update billing information, and to view organization metrics, such as resource count and member count (but not member names). This includes setting [Neo usage limits](/docs/ai/concepts/neo/usage-limits/) to cap what the organization spends on Pulumi Neo.
 
 | Resource | Permissions |
 | --- | --- |

diff --git a/content/docs/administration/get-started/choose-edition.md b/content/docs/administration/get-started/choose-edition.md
@@ -77,7 +77,7 @@ Pay monthly with a credit card. This option provides flexibility and is ideal fo
 Annual commitment pricing is available on Pro and Enterprise only. Pay upfront with invoicing for a committed amount of usage. [Contact us](/contact/) to discuss commitment pricing.
 
 {{% notes type="info" %}}
-Both billing options include detailed usage insights through the Billing & usage page in your organization settings. Track IaC resources, deployment minutes, ESC secrets, and download usage history. You can also set [Neo usage limits](/docs/ai/neo/usage-limits/) to cap spend on Pulumi Neo. Only organization administrators and designated [billing administrators](/docs/administration/concepts/billing-managers/) can access these pages. You'll also receive monthly usage reports via email.
+Both billing options include detailed usage insights through the Billing & usage page in your organization settings. Track IaC resources, deployment minutes, ESC secrets, and download usage history. You can also set [Neo usage limits](/docs/ai/concepts/neo/usage-limits/) to cap spend on Pulumi Neo. Only organization administrators and designated [billing administrators](/docs/administration/concepts/billing-managers/) can access these pages. You'll also receive monthly usage reports via email.
 {{% /notes %}}
 
 ## Getting started with your chosen model

diff --git a/content/docs/administration/self-hosting/components/api.md b/content/docs/administration/self-hosting/components/api.md
@@ -249,7 +249,7 @@ If a feature needs to reach a service on the same host or private network as you
 | Scope         | Outbound requests it covers                                                                                                  |
 |---------------|------------------------------------------------------------------------------------------------------------------------------|
 | `ESC`         | Pulumi ESC providers and rotators that call a URL you configure: Vault, Infisical, Terraform state, GitHub login, and external providers and rotators. |
-| `AGENTS_BYOK` | Pulumi Neo requests to a [custom model provider](/docs/ai/neo/model-providers/).                                             |
+| `AGENTS_BYOK` | Pulumi Neo requests to a [custom model provider](/docs/ai/concepts/neo/model-providers/).                                             |
 | `OIDC_ISSUER` | Registering an OIDC issuer and fetching its signing keys. |
 | `VCS`         | Refreshing a member's GitHub Enterprise Server token when [individual user authentication](/docs/integrations/version-control/github-app/#individual-user-authentication-for-github-enterprise-server) is enabled. |
 | `WEBHOOKS`    | Webhook delivery. |

diff --git a/content/docs/ai/_index.md b/content/docs/ai/_index.md
@@ -16,43 +16,43 @@ menu:
 link_buttons:
   primary:
     label: Get Started
-    link: /docs/ai/neo/get-started/
+    link: /docs/ai/get-started/
 
 sections:
 - type: flat
   heading: Overview
   description_md: |
-    Pulumi is built to be driven by AI agents, including the coding agents your team already uses. Because Pulumi infrastructure is real code with a verifiable plan for every change, agents like Claude Code, Codex, Cursor, and GitHub Copilot can write, preview, and deploy it directly. The [Pulumi CLI](/docs/ai/cli-for-agents/) is designed for them: run any command with `npx pulumi`, perform one-shot resource operations with [`pulumi do`](/docs/iac/cli/direct-resource-operations/), and parse structured `--json` output. [Pulumi Agent Skills](/docs/ai/skills/) teach agents proven Pulumi workflows, the [Pulumi MCP server](/docs/ai/mcp-server/) offers the same reach over [MCP](/what-is/mcp-for-infrastructure-as-code/), and [agent accounts](/docs/administration/concepts/agent-accounts/) remove signup friction entirely.
+    Pulumi is built to be driven by AI agents, including the coding agents your team already uses. Because Pulumi infrastructure is real code with a verifiable plan for every change, agents like Claude Code, Codex, Cursor, and GitHub Copilot can write, preview, and deploy it directly. The [Pulumi CLI](/docs/ai/concepts/cli-for-agents/) is designed for them: run any command with `npx pulumi`, perform one-shot resource operations with [`pulumi do`](/docs/iac/cli/direct-resource-operations/), and parse structured `--json` output. [Pulumi Agent Skills](/docs/ai/concepts/agent-skills/) teach agents proven Pulumi workflows, the [Pulumi MCP server](/docs/ai/guides/set-up-mcp-server/) offers the same reach over [MCP](/what-is/mcp-for-infrastructure-as-code/), and [agent accounts](/docs/administration/concepts/agent-accounts/) let an agent start working before anyone signs up.
 
-    [Pulumi Neo](/docs/ai/neo/) is Pulumi's own infrastructure agent, built on the same foundations and adding organizational context, policy guardrails, human-in-the-loop approvals, and scheduled autonomous work. Use your favorite agent, use Neo, or use both together: Neo for long-running, governed infrastructure tasks, and your coding agent for interactive development.
+    [Pulumi Neo](/docs/ai/concepts/neo/) is Pulumi's own infrastructure agent, built on the same foundations and adding organizational context, policy guardrails, human-in-the-loop approvals, and scheduled autonomous work. Use your favorite agent, use Neo, or use both together: Neo for long-running, governed infrastructure tasks, and your coding agent for interactive development.
 
 - type: button-cards
-  heading: Bring your own agent
-  cards:
-  - icon: lightbulb
-    heading: Agent Skills
-    link: /docs/ai/skills/
-    description: Teach Claude Code, Codex, Cursor, Copilot, and other agents Pulumi workflows.
-  - icon: terminal
-    heading: Pulumi CLI
-    link: /docs/ai/cli-for-agents/
-    description: An agent-friendly CLI, from npx pulumi and pulumi do to structured JSON output.
-  - icon: plug
-    heading: MCP server
-    link: /docs/ai/mcp-server/
-    description: Give any MCP-capable agent access to your Pulumi Cloud resources and the Registry.
-  - icon: rocket-launch
-    heading: Agent Accounts
-    link: /docs/administration/concepts/agent-accounts/
-    description: Ephemeral Pulumi Cloud accounts provisioned automatically for AI agents.
-
-- type: button-cards
-  heading: Use Pulumi Neo
+  heading: Explore Infrastructure AI
   cards:
   - icon: rocket-launch
+    heading: Get started
+    link: /docs/ai/get-started/
+    description: Connect the coding agent you already use to Pulumi, or enable Pulumi Neo for your organization and run your first task.
+  - icon: lightbulb
+    heading: Concepts
+    link: /docs/ai/concepts/
+    description: How Agent Skills and the agent-friendly Pulumi CLI work, and how Neo handles tasks, permissions, pull requests, and automations.
+  - icon: pulumi-neo
     heading: Pulumi Neo
-    link: /docs/ai/neo/
+    link: /docs/ai/concepts/neo/
     description: Pulumi's purpose-built infrastructure agent. Investigates your live infrastructure, reviews and proposes changes to your IaC code, and takes on recurring maintenance.
+  - icon: wrench
+    heading: Guides
+    link: /docs/ai/guides/
+    description: Step-by-step tasks, such as connecting Claude Code, Cursor, and other agents to the Pulumi MCP server.
+  - icon: plug
+    heading: Integrations
+    link: /docs/ai/integrations/
+    description: Connect Neo to external MCP servers, cloud CLIs, and Slack.
+  - icon: books
+    heading: Reference
+    link: /docs/ai/reference/
+    description: The tools and prompts the Pulumi MCP server exposes, and the pulumi neo CLI command.
 
 - type: flat
   heading: Have questions?

diff --git a/content/docs/ai/concepts/_index.md b/content/docs/ai/concepts/_index.md
@@ -0,0 +1,36 @@
+---
+title: Concepts
+title_tag: Infrastructure AI concepts
+h1: Concepts
+meta_desc: How AI agents work with Pulumi, including Agent Skills, the Pulumi CLI for agents, and Pulumi Neo's tasks, permissions, automations, and settings.
+menu:
+    ai:
+        name: Concepts
+        parent: ai-home
+        identifier: ai-concepts
+        weight: 10
+---
+
+These pages explain how AI agents work with Pulumi. To set something up, see [Guides](/docs/ai/guides/). To try it end to end, start with [Get started](/docs/ai/get-started/).
+
+## Agents and Pulumi
+
+- [Agent Skills](/docs/ai/concepts/agent-skills/): Packaged Pulumi workflows that teach coding agents how to work with Pulumi.
+- [CLI for agents](/docs/ai/concepts/cli-for-agents/): How the Pulumi CLI is built for agents, from `npx pulumi` to structured `--json` output.
+
+## Pulumi Neo
+
+- [Pulumi Neo](/docs/ai/concepts/neo/): What Neo does, where you can use it, and how much autonomy you give it.
+  - [Tasks](/docs/ai/concepts/neo/tasks/): The unit of work in Neo, including Plan Mode, task modes, and approvals.
+  - [Permissions model](/docs/ai/concepts/neo/permissions/): Which identity Neo acts as on each surface, and how permission and approval modes constrain it.
+  - [Automations](/docs/ai/concepts/neo/automations/): Scheduled Neo tasks that deliver their results as pull requests.
+  - [Neo in the CLI](/docs/ai/concepts/neo/neo-in-the-cli/): Interactive Neo sessions in your terminal with your local project and credentials.
+  - [Neo in your editor](/docs/ai/concepts/neo/neo-in-your-editor/): Neo inside Zed, JetBrains IDEs, VS Code, and Cursor through the Agent Client Protocol.
+  - [Pull requests](/docs/ai/concepts/neo/pull-requests/): How Neo opens and updates pull requests through your existing review process.
+  - [Code reviews](/docs/ai/concepts/neo/code-reviews/): How Neo reviews pull requests against what Pulumi Cloud knows about your infrastructure.
+  - [Previews](/docs/ai/concepts/neo/previews/): How Neo runs `pulumi preview` to validate changes before opening a pull request.
+  - [Instructions](/docs/ai/concepts/neo/instructions/): Organization-wide custom instructions and per-repository `AGENTS.md` instructions.
+  - [Slash commands](/docs/ai/concepts/neo/slash-commands/): Built-in and custom shortcuts for proven prompts.
+  - [Model providers](/docs/ai/concepts/neo/model-providers/): Running Neo with your own model provider credentials.
+  - [Settings](/docs/ai/concepts/neo/settings/): Access controls, the default task mode, and notifications.
+  - [Usage limits](/docs/ai/concepts/neo/usage-limits/): Spend limits for your organization and its members.
diff --git a/content/docs/ai/skills/index.md → content/docs/ai/concepts/agent-skills.md b/content/docs/ai/skills/index.md → content/docs/ai/concepts/agent-skills.md
@@ -6,10 +6,12 @@ meta_desc: Learn how Pulumi Agent Skills teach Claude Code, Cursor, GitHub Copil
 menu:
     ai:
         name: Agent Skills
-        parent: ai-home
-        weight: 5
+        parent: ai-concepts
+        identifier: ai-concepts-agent-skills
+        weight: 10
 aliases:
 - /docs/ai/agent-skills/
+- /docs/ai/skills/
 ---
 
 Pulumi Agent Skills are knowledge packages that teach AI coding assistants domain-specific Pulumi workflows. These skills help with infrastructure migrations, secret management, and code translation, teaching assistants how to work with Pulumi the way an experienced practitioner would.
@@ -232,6 +234,6 @@ See the [CONTRIBUTING.md](https://github.com/pulumi/agent-skills/blob/main/CONTR
 
 ## See also
 
-- [Pulumi MCP server](/docs/ai/mcp-server/) - give your agent live access to your Pulumi Cloud resources and the Registry
+- [Pulumi MCP server](/docs/ai/guides/set-up-mcp-server/) - give your agent live access to your Pulumi Cloud resources and the Registry
 - [Agent accounts](/docs/administration/concepts/agent-accounts/) - ephemeral Pulumi Cloud accounts provisioned automatically for agents
 - [What is agentic infrastructure?](/what-is/what-is-agentic-infrastructure/) - the broader picture of AI agents operating infrastructure
diff --git a/content/docs/ai/cli-for-agents/index.md → content/docs/ai/concepts/cli-for-agents.md b/content/docs/ai/cli-for-agents/index.md → content/docs/ai/concepts/cli-for-agents.md
@@ -6,13 +6,16 @@ h1: The Pulumi CLI for agents
 menu:
     ai:
         name: CLI for agents
-        parent: ai-home
-        weight: 9
+        parent: ai-concepts
+        identifier: ai-concepts-cli-for-agents
+        weight: 20
+aliases:
+- /docs/ai/cli-for-agents/
 ---
 
 The [Pulumi CLI](/docs/iac/cli/) is built to be driven by AI agents. Because Pulumi infrastructure is real code with a verifiable plan for every change, agents like Claude Code, Codex, Cursor, and GitHub Copilot can write, preview, and deploy it directly, with no bespoke integration required. This page collects the CLI features that make that possible.
 
-The same features power [Pulumi Agent Skills](/docs/ai/skills/) and the [Pulumi MCP server](/docs/ai/mcp-server/), but they work with any agent that can run a shell command, so you are never locked into a particular tool.
+The same features power [Pulumi Agent Skills](/docs/ai/concepts/agent-skills/) and the [Pulumi MCP server](/docs/ai/guides/set-up-mcp-server/), but they work with any agent that can run a shell command, so you are never locked into a particular tool.
 
 ## No install step: `npx pulumi`
 
@@ -64,7 +67,7 @@ An agent that runs the CLI still needs somewhere to store state. [Agent accounts
 
 ## Next steps
 
-- [Agent Skills](/docs/ai/skills/) — teach your agent proven Pulumi workflows it can apply on top of the CLI.
-- [Pulumi MCP server](/docs/ai/mcp-server/) — give an MCP-capable agent the same reach over the [Model Context Protocol](/what-is/mcp-for-infrastructure-as-code/).
+- [Agent Skills](/docs/ai/concepts/agent-skills/) — teach your agent proven Pulumi workflows it can apply on top of the CLI.
+- [Pulumi MCP server](/docs/ai/guides/set-up-mcp-server/) — give an MCP-capable agent the same reach over the [Model Context Protocol](/what-is/mcp-for-infrastructure-as-code/).
 - [Agent accounts](/docs/administration/concepts/agent-accounts/) — ephemeral Pulumi Cloud accounts provisioned automatically for agents.
 - [Pulumi CLI reference](/docs/iac/cli/) — the full command set behind everything above.
diff --git a/content/docs/ai/neo/_index.md → content/docs/ai/concepts/neo/_index.md b/content/docs/ai/neo/_index.md → content/docs/ai/concepts/neo/_index.md
@@ -7,12 +7,13 @@ aliases:
 - /docs/pulumi-cloud/neo/
 - /docs/iac/neo/
 - /docs/neo/
+- /docs/ai/neo/
 menu:
     ai:
         name: Pulumi Neo
-        parent: ai-home
-        identifier: ai-neo
-        weight: 1
+        parent: ai-concepts
+        identifier: ai-concepts-neo
+        weight: 50
 ---
 
 Pulumi Neo is Pulumi's own infrastructure agent, powered by Anthropic's Claude
@@ -29,28 +30,28 @@ open a pull request against your IaC code.
 
 - **Answers questions about your infrastructure.** Ask which resources are
   running an outdated provider, why a stack failed, or what a change will do,
-  and Neo searches your real state to answer. [Tasks](/docs/ai/neo/tasks/)
+  and Neo searches your real state to answer. [Tasks](/docs/ai/concepts/neo/tasks/)
   covers how it investigates.
 - **Proposes changes to your code.** When a task calls for changing
   infrastructure, Neo changes the IaC code rather than clicking in a console.
   The usual way it hands that back is a
-  [pull request](/docs/ai/neo/pull-requests/) describing the problem, the
+  [pull request](/docs/ai/concepts/neo/pull-requests/) describing the problem, the
   resources affected, and a preview summary, so your branch protection rules
   and reviewers still gate what ships.
 - **Runs previews before anything lands.** Neo can
-  [run `pulumi preview`](/docs/ai/neo/running-previews/) to validate a change,
+  [run `pulumi preview`](/docs/ai/concepts/neo/previews/) to validate a change,
   surface policy violations, and show the resource diff.
 - **Reviews your pull requests.** Neo
-  [comments on PRs](/docs/ai/neo/code-reviews/) using what Pulumi Cloud knows
+  [comments on PRs](/docs/ai/concepts/neo/code-reviews/) using what Pulumi Cloud knows
   about your running infrastructure, flagging issues inline. It never blocks
   the merge.
 - **Takes on recurring maintenance.** Turn any task into
-  [an automation](/docs/ai/neo/automations/) that runs on a schedule: provider
+  [an automation](/docs/ai/concepts/neo/automations/) that runs on a schedule: provider
   freshness checks, encryption and backup audits, activity digests. Some
   automations report what they found; others open a pull request when there's
   work to do.
 - **Applies Pulumi best practices.** Neo ships with the
-  [Pulumi Agent Skills](/docs/ai/skills/) catalog built in, so it already knows
+  [Pulumi Agent Skills](/docs/ai/concepts/agent-skills/) catalog built in, so it already knows
   proven workflows for components, ESC, migrations, and provider upgrades.
 
 ## Where to use Neo
@@ -59,33 +60,33 @@ Neo is one agent reachable from several places. Your permissions, approval
 controls, and integrations carry over whichever surface you start from.
 
 - **Pulumi Cloud console.** The Neo section in Pulumi Cloud is the main home for
-  tasks, automations, and settings. [Get started](/docs/ai/neo/get-started/).
-- **Your terminal.** Run [`pulumi neo`](/docs/ai/neo/pulumi-cli/) for an
+  tasks, automations, and settings. [Get started](/docs/ai/get-started/neo/).
+- **Your terminal.** Run [`pulumi neo`](/docs/ai/concepts/neo/neo-in-the-cli/) for an
   interactive session that inherits your local setup: the CLIs you've
   authenticated, your environment variables and kubeconfigs, and the project
   you're editing.
-- **Your editor.** Use [Neo in your editor's agent panel](/docs/ai/neo/editors/)
+- **Your editor.** Use [Neo in your editor's agent panel](/docs/ai/concepts/neo/neo-in-your-editor/)
   in Zed, JetBrains IDEs, VS Code, and Cursor through the Agent Client
   Protocol, working on the project you have open.
-- **Slack.** Mention [`@Neo`](/docs/ai/neo/integrations/slack/) in any channel
+- **Slack.** Mention [`@Neo`](/docs/ai/integrations/slack/) in any channel
   and it replies in the thread, so you can check stack state or investigate a
   failure without leaving the conversation.
 - **Pull requests.** Neo reviews PRs automatically, and you can mention
   `@pulumi-neo` in a PR description, a review comment, or an issue to ask for
-  something specific. See [code reviews](/docs/ai/neo/code-reviews/).
+  something specific. See [code reviews](/docs/ai/concepts/neo/code-reviews/).
 - **From another AI agent.** Claude Code, Codex, Cursor, and other agents can
   hand long-running infrastructure work to Neo through the
-  [Pulumi MCP server](/docs/ai/mcp-server/) or the
-  [Neo handoff skill](/docs/ai/skills/), then keep working while Neo runs.
+  [Pulumi MCP server](/docs/ai/guides/set-up-mcp-server/) or the
+  [Neo handoff skill](/docs/ai/concepts/agent-skills/), then keep working while Neo runs.
 
-Neo also reaches outward: [integrations](/docs/ai/neo/integrations/mcp/) connect
+Neo also reaches outward: [integrations](/docs/ai/integrations/external-mcp-servers/) connect
 it to services like Datadog, PagerDuty, Linear, and Atlassian so it can pull in
 the context a task needs.
 
 ## How much autonomy you give it
 
-[Plan Mode](/docs/ai/neo/tasks/#plan-mode) makes Neo agree on a plan with you
-before it acts, [task modes](/docs/ai/neo/tasks/#task-modes) control which steps
+[Plan Mode](/docs/ai/concepts/neo/tasks/#plan-mode) makes Neo agree on a plan with you
+before it acts, [task modes](/docs/ai/concepts/neo/tasks/#task-modes) control which steps
 need your approval, and
-[read-only mode](/docs/ai/neo/get-started/#read-only-mode) removes its ability
-to change anything at all. Neo never has more access than you do, only less.
+[read-only mode](/docs/ai/get-started/neo/#read-only-mode) stops it from
+making changes in Pulumi Cloud. Neo never has more access than you do, only less.