docs: add AI wizard page for wizard feature-flags

contents/docs/ai-engineering/ai-wizard.mdx

@@ -41,7 +41,9 @@
 8. Optionally installs the [PostHog MCP server](/docs/model-context-protocol) for your AI agent
 
 <Caption>
+
 The AI wizard integrating both the JS Web SDK and Node SDK into a Next.js application
+
 </Caption>
 
 ## AI wizard installation
@@ -74,9 +76,10 @@
 |---|---|
 | `wizard` | Default flow – installs and instruments PostHog |
 | `wizard self-driving` | Turn on [self-driving](/docs/self-driving) – enable signal sources, set up scouts, and get your inbox link |
 | `wizard audit <subcommand>` | Audit an existing integration – see [Audit subcommands](#audit-subcommands) |
 | `wizard revenue-analytics` | Wire up Stripe + PostHog revenue analytics |
 | `wizard mcp-analytics` | Instrument your own MCP server with [MCP Analytics](/docs/mcp-analytics) |
+| `wizard feature-flags` | Add feature flags on Next.js App Router (server eval + client bootstrap) – see [AI wizard installation](/docs/feature-flags/installation/ai-wizard) |
 | `wizard ai-observability` | Instrument your LLM calls with [AI Observability](/docs/ai-observability) |
 | `wizard replay-vision` | Turn on Session Replay and create [Replay Vision](/docs/replay-vision) scanners written for your product |
 | `wizard migrate` | Migrate from another analytics or feature-flag vendor |
@@ -85,9 +88,9 @@
 | `wizard slack add` | Connect PostHog to your Slack |
 | `wizard skill <skill-name>` | Run a single skill by name – browse the available skills in the [context-mill releases](https://github.com/PostHog/context-mill/releases/latest) |
 
 ### Audit subcommands
 
 `@npx @posthog/wizard audit` on its own runs the `events` audit. Pass a subcommand to run a specific one.
 
 | Command | What it does |
 |---|---|
@@ -96,7 +99,7 @@
 | `wizard audit autocapture` | Audit autocapture setup and cost |
 | `wizard audit feature-flags` | Audit feature flag usage and cost |
 | `wizard audit identify` | Audit your `$identify` implementation |
 | `wizard audit session-replay` | Audit session replay setup |
 | `wizard audit web-analytics` | Audit web analytics setup |
 
 ### Legacy commands
@@ -106,8 +109,8 @@
 | Old command | New command | What changed |
 |---|---|---|
 | `wizard integrate` | `wizard` | The default flow now runs the integration |
 | `wizard events-audit` | `wizard audit events` | Now an `audit` subcommand |
 | `wizard audit` | `wizard audit <subcommand>` | Now takes a subcommand; `wizard audit all` runs a full audit |
 | `wizard revenue` | `wizard revenue-analytics` | Renamed – update any scripts using `revenue` |
 | `wizard upload-sourcemaps` | `wizard upload-source-maps` | Renamed (the old `upload-sourcemaps` still works) |
 

contents/docs/feature-flags/installation/ai-wizard.mdx

@@ -0,0 +1,93 @@
+---
+title: AI wizard feature flags installation
+platformIconName: IconSparkles
+---
+
+import WizardCommand from 'components/WizardCommand'
+import CalloutBox from 'components/Docs/CalloutBox'
+import { Steps, Step } from 'components/Docs/Steps'
+
+`wizard feature-flags` adds the cheap feature flags path to an **existing** PostHog install. It evaluates flags once per request on the server with `evaluateFlags()`, bootstraps those values into the client so the first paint has no flicker and no extra `/flags` fetch, and turns `/flags` polling off in CI.
+
+You still create and target flags in PostHog. This command is the first-hour wiring: one evaluation per request, the same distinct id on server and client, and a kill switch that stays off until you raise rollout. For SDK snippets without the wizard, see [adding feature flag code](/docs/feature-flags/adding-feature-flag-code).
+
+This command is not:
+
+- Default `npx @posthog/wizard` — that installs product analytics. Run it first if PostHog is not initialized.
+- `wizard audit feature-flags` — that is a read-only usage and cost audit after you already have flags.
+- The [PostHog MCP surface](/docs/feature-flags/surfaces/mcp) or [PostHog AI](/docs/feature-flags/manage-flags-ai) — those manage flags from an editor or the app. This command wires evaluation into your Next.js app.
+
+## AI wizard
+
+The fastest way to get this wiring is the wizard (it also works for [LLM coding agents](/blog/envoy-wizard-llm-agent) like Cursor and Bolt):
+
+<WizardCommand command="feature-flags" />
+
+<CalloutBox icon="IconWarning" title="Next.js App Router 15.3+ only" type="caution">
+
+This command instruments **Next.js App Router 15.3 or newer** (`app/` directory). Pages Router, older Next.js, and other frameworks abort. For those stacks, follow [manual installation](/docs/feature-flags/installation) and [bootstrapping](/docs/feature-flags/bootstrapping).
+
+</CalloutBox>
+
+<CalloutBox icon="IconInfo" title="Not on npm @latest yet" type="fyi">
+
+The command ships in [wizard pull request 1192](https://github.com/PostHog/wizard/pull/1192) and [context-mill pull request 378](https://github.com/PostHog/context-mill/pull/378). Until those merge, `npx @posthog/wizard@latest feature-flags` will not find it. Use a local wizard build, or wait for the next npm release.
+
+</CalloutBox>
+
+## What it does
+
+<Steps>
+
+<Step title="Run it in your app repo" badge="required">
+
+From the Next.js project that already has PostHog installed, run the command above. Authenticate if the wizard asks.
+
+If PostHog is not initialized, the run aborts and tells you to run `npx @posthog/wizard` first, then re-run `wizard feature-flags`.
+
+</Step>
+
+<Step title="Confirm one UI path, or skip" badge="required">
+
+The wizard asks once. **Skip is first:** no new flag, no UI change. Confirm: one boolean flag, **active, 0% rollout**, plus one additive UI path (a new, visibly flagged element, not a wrap around existing critical logic). Auth, checkout, payments, and data-mutation handlers stay ungated. Flag-off (including 0%) is current behavior.
+
+</Step>
+
+<Step title="What it changes in code" badge="required">
+
+The wizard:
+
+- Calls `evaluateFlags()` once per request on the server
+- Bootstraps those values into the client `PostHogProvider`
+- Turns `/flags` polling off in CI so tests do not bill you
+
+It does not add local evaluation. See [bootstrapping](/docs/feature-flags/bootstrapping) and [cutting costs](/docs/feature-flags/cutting-costs) for why this path is cheaper.
+
+</Step>
+
+<Step title="Test the kill switch" badge="recommended">
+
+In PostHog, raise the flag's rollout to 100%. Reload the app. The gated UI appears. Set rollout back to 0%. Production users keep seeing today's UI until someone raises rollout in PostHog.
+
+</Step>
+
+</Steps>
+
+## For agents
+
+Paste this page's URL into any coding agent as a prompt:
+
+`https://posthog.com/docs/feature-flags/installation/ai-wizard.md`
+
+Or run the same skill without the TUI:
+
+```bash
+npx @posthog/wizard skill feature-flags-setup
+```
+
+## Related
+
+- [Bootstrapping](/docs/feature-flags/bootstrapping)
+- [Cutting costs](/docs/feature-flags/cutting-costs)
+- [`wizard audit feature-flags`](/docs/ai-engineering/ai-wizard#audit-subcommands)
+- [Manage flags over MCP](/docs/feature-flags/surfaces/mcp)

contents/docs/feature-flags/installation/index.mdx

@@ -8,9 +8,11 @@ import WizardCommand from 'components/WizardCommand'
 
 ## AI wizard
 
-Install PostHog in seconds with our wizard by running this command in your project directory with your terminal (it also works for [LLM coding agents](/blog/envoy-wizard-llm-agent) like Cursor and Bolt):
+On Next.js App Router 15.3+, add the cheap flags path with this command (it also works for [LLM coding agents](/blog/envoy-wizard-llm-agent) like Cursor and Bolt):
 
-<WizardCommand />
+<WizardCommand command="feature-flags" />
+
+This extends an existing PostHog install. It does not replace `npx @posthog/wizard`. Full walkthrough: [AI wizard feature flags installation](/docs/feature-flags/installation/ai-wizard). Other platforms: pick one below.
 
 Wait for it to finish and test the setup once the wizard is complete.
 

contents/docs/feature-flags/start-here.mdx

@@ -8,9 +8,26 @@
 import { QuestLog, QuestLogItem } from 'components/Docs/QuestLog'
 import { IconFlask } from '@posthog/icons'
 import OSButton from 'components/OSButton'
+import WizardCommand from 'components/WizardCommand'
 
 <QuestLog firstSpeechBubble="Let's ship some flags!" lastSpeechBubble="Time to start flagging features!">
 
+<QuestLogItem
+    title="Install with the AI wizard"
+    subtitle="Next.js App Router"
+    icon="IconSparkles"
+>
+
+  On Next.js App Router 15.3+, `wizard feature-flags` adds server `evaluateFlags()`, client bootstrap, and an optional 0% kill switch. It extends an existing PostHog install. Other stacks: skip this step and install an SDK below.
+
+  <WizardCommand command="feature-flags" />
+
+  <OSButton variant="primary" asLink to="/docs/feature-flags/installation/ai-wizard">
+    AI wizard walkthrough
+  </OSButton>
+
+</QuestLogItem>
+
 <QuestLogItem
     title="Create your first flag"
     subtitle="Required"
@@ -70,11 +87,11 @@
 
   Before going live, test that your flag behaves correctly. PostHog gives you several ways to test and roll out safely:
 
   - **Override for yourself** &mdash; Target your email or user ID to see each variant
   - **Phased rollout** &mdash; Start at 5-10% of users, monitor metrics, then gradually increase
   - **Target by properties** &mdash; Show features to specific users, cohorts, or groups
   - **Set up dependencies** &mdash; Make flags depend on other flags for complex rollout strategies
   - **Edit inline** &mdash; Update release conditions, payloads, and variants directly from the flag overview page
 
   <ProductScreenshot
       imageLight="https://res.cloudinary.com/dmukukwp6/image/upload/w_1600,c_limit,q_auto,f_auto/create_feature_flags_light_133081fabc.png"

src/navs/index.js

@@ -5161,6 +5161,7 @@ export const docsMenu = {
                     featured: true,
                     children: [
                         { name: 'Overview', url: '/docs/feature-flags/installation' },
+                        { name: 'AI wizard', url: '/docs/feature-flags/installation/ai-wizard' },
                         { name: 'Web', url: '/docs/feature-flags/installation/web' },
                         { name: '.NET', url: '/docs/feature-flags/installation/dotnet' },
                         { name: 'Android', url: '/docs/feature-flags/installation/android' },