sunpeak 0.20.1 → 0.20.5

package/README.md

@@ -16,7 +16,13 @@
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue?style=flat&logo=typescript&label=ts&color=FFB800&logoColor=white&labelColor=000035)](https://www.typescriptlang.org/)
 [![React](https://img.shields.io/badge/React-19-blue?style=flat&logo=react&label=react&color=FFB800&logoColor=white&labelColor=000035)](https://reactjs.org/)
 
-Inspector, testing framework, and runtime framework for MCP servers and MCP Apps.
+MCP App framework, MCP testing framework, and inspector for MCP servers and MCP Apps.
+
+Build cross-platform: sunpeak is a ChatGPT App framework, Claude Connector framework, and more.
+
+```bash
+npx sunpeak new
+```
 
 [Demo (Hosted)](https://sunpeak.ai/inspector) ~
 [Demo (Video)](https://cdn.sunpeak.ai/sunpeak-demo-prod.mp4) ~
@@ -26,126 +32,89 @@ Inspector, testing framework, and runtime framework for MCP servers and MCP Apps
 
 ## sunpeak is three things
 
-### 1. Inspector
+### 1. App Framework
+
+Building an MCP App from scratch means wiring up an MCP server, handling protocol message routing, managing resource HTML bundles, and setting up a dev environment with hot reload. Each host has different capabilities and CSS variables, so you end up writing platform-specific code without a clear structure.
 
-Manually test any MCP server in replicated ChatGPT and Claude runtimes.
+sunpeak gives you a convention-over-configuration framework with the inspector and testing built in.
 
 ```bash
-sunpeak inspect --server http://localhost:8000/mcp
+npx sunpeak new
 ```
 
-<div align="center">
-  <a href="https://sunpeak.ai/docs/mcp-apps-inspector">
-    <picture>
-      <img alt="Inspector" src="https://cdn.sunpeak.ai/chatgpt-simulator.png">
-    </picture>
-  </a>
-</div>
-
-- Multi-host inspector replicating ChatGPT and Claude runtimes
-- Toggle themes, display modes, device types from the sidebar or URL params
-- Call real tool handlers or use simulation fixtures for mock data
+This creates a project, starts a dev server with HMR, and opens the inspector at `localhost:3000`:
 
-### 2. Testing Framework
+```
+sunpeak-app/
+├── src/resources/review/review.tsx    # UI component (React)
+├── src/tools/review-diff.ts           # Tool handler, schema, resource link
+├── tests/simulations/review-diff.json # Mock data for the inspector
+└── package.json
+```
 
-Automatically test any MCP server against replicated ChatGPT and Claude runtimes.
+Tools, resources, and simulations are auto-discovered from the file system. Multi-platform React hooks (`useToolData`, `useAppState`, `useTheme`, `useDisplayMode`) let you write your app logic once and deploy it across ChatGPT, Claude, and future hosts.
 
-```ts
-import { test, expect } from 'sunpeak/test';
+[App framework documentation →](https://sunpeak.ai/docs/mcp-apps-framework)
 
-test('review tool renders title', async ({ inspector }) => {
-  const result = await inspector.renderTool('review-diff');
-  const app = result.app();
-  await expect(app.locator('h1:has-text("Refactor")')).toBeVisible();
-});
-```
+---
 
-- **Works for any MCP server**: `sunpeak test init` scaffolds tests for Python, Go, TS, or any language
-- **MCP-native assertions**: `toBeError()`, `toHaveTextContent()`, `toHaveStructuredContent()`
-- **Multi-host**: Tests run against ChatGPT and Claude hosts automatically
-- **Live tests**: Automated browser tests against real ChatGPT via `sunpeak/test/live`
-- **Evals**: Test your tool interface design against multiple LLMs (GPT-4o, Claude, Gemini, etc.) via `sunpeak/eval`
+### 2. Testing Framework
 
-### 3. App Framework
+MCP Apps render inside host iframes with host-specific themes, display modes, and capabilities. Standard browser testing can't replicate this because the runtime environment only exists inside ChatGPT and Claude. Each app also has many dimensions of state: tool inputs, tool results, server tool responses, host context, and display configuration. Testing all combinations manually is slow and error-prone.
 
-Next.js for MCP Apps. Convention-over-configuration project structure with the inspector and testing built in.
+sunpeak replicates these host runtimes and provides simulation fixtures (JSON files that define reproducible tool states) so you can test every combination of host, theme, and data in CI without accounts or API credits.
 
 ```bash
-sunpeak-app/
-├── src/
-│   ├── resources/
-│   │   └── review/
-│   │       └── review.tsx            # Review UI component + resource metadata.
-│   ├── tools/
-│   │   ├── review-diff.ts            # Tool with handler, schema, and optional resource link.
-│   │   ├── review-post.ts            # Multiple tools can share one resource.
-│   │   └── review.ts                 # Backend-only tool (no resource, no UI).
-│   └── server.ts                     # Optional: auth, server config.
-├── tests/simulations/
-│   ├── review-diff.json              # Mock state for testing (includes serverTools).
-│   ├── review-post.json              # Mock state for testing (includes serverTools).
-│   └── review-purchase.json          # Mock state for testing (includes serverTools).
-└── package.json
+npx sunpeak test init --server http://localhost:8000/mcp
 ```
 
-- **Runtime APIs**: Strongly typed React hooks (`useToolData`, `useAppState`, `useHostContext`, etc.)
-- **Convention over configuration**: Resources, tools, and simulations are auto-discovered
-- **Multi-platform**: Build once, deploy to ChatGPT, Claude, and future hosts
-
-## Quickstart
-
-Requirements: Node (20+), pnpm (10+)
+This scaffolds E2E tests, visual regression, live host tests, and multi-model evals. Then run them:
 
 ```bash
-pnpm add -g sunpeak
-sunpeak new
+npx sunpeak test
 ```
 
-## CLI
+Playwright fixtures handle inspector startup, MCP connection, iframe traversal, and host switching. Works with Python, Go, TypeScript, Rust, or any language.
 
-**Testing** (works with any MCP server):
+```ts
+import { test, expect } from 'sunpeak/test';
 
-| Command                               | Description                                 |
-| ------------------------------------- | ------------------------------------------- |
-| `sunpeak inspect --server <url\|cmd>` | Inspect any MCP server in the inspector     |
-| `sunpeak test`                        | Run unit + e2e tests                        |
-| `sunpeak test --unit`                 | Run unit tests only (Vitest)                |
-| `sunpeak test --e2e`                  | Run e2e tests only (Playwright)             |
-| `sunpeak test --visual`               | Run e2e tests with visual regression        |
-| `sunpeak test --visual --update`      | Update visual regression baselines          |
-| `sunpeak test --live`                 | Run live tests against real hosts           |
-| `sunpeak test --eval`                 | Run evals against multiple LLM models       |
-| `sunpeak test init`                   | Scaffold test infrastructure into a project |
+test('search tool returns results', async ({ mcp }) => {
+  const result = await mcp.callTool('search', { query: 'headphones' });
+  expect(result.isError).toBeFalsy();
+});
 
-**App framework** (for sunpeak projects):
+test('album cards render', async ({ inspector }) => {
+  const result = await inspector.renderTool('show-albums');
+  await expect(result.app().locator('button:has-text("Summer Slice")')).toBeVisible();
+});
+```
 
-| Command                          | Description                                 |
-| -------------------------------- | ------------------------------------------- |
-| `sunpeak new [name] [resources]` | Create a new project                        |
-| `sunpeak dev`                    | Start dev server + inspector + MCP endpoint |
-| `sunpeak build`                  | Build resources + tools for production      |
-| `sunpeak start`                  | Start production MCP server                 |
-| `sunpeak upgrade`                | Upgrade sunpeak to latest version           |
+[Testing documentation →](https://sunpeak.ai/docs/testing/overview)
 
-## Coding Agent Skills
+---
 
-Install the sunpeak skills to give your coding agent (Claude Code, Cursor, etc.) built-in knowledge of sunpeak patterns, hooks, and testing:
+### 3. Inspector
+
+MCP servers are opaque. You can call tools and read the JSON responses, but you can't see how your app actually looks and behaves inside ChatGPT or Claude without deploying to each host, setting up a tunnel, paying for accounts, and manually refreshing through a multi-step cycle on every code change.
+
+The sunpeak inspector replicates the ChatGPT and Claude app runtimes locally. Point it at any MCP server and see your tools and resources rendered the same way they appear in production hosts.
 
 ```bash
-pnpm dlx skills add Sunpeak-AI/sunpeak@create-sunpeak-app Sunpeak-AI/sunpeak@test-mcp-server
+npx sunpeak inspect --server http://localhost:8000/mcp
 ```
 
-## Troubleshooting
-
-If your app doesn't render in ChatGPT or Claude:
+<div align="center">
+  <a href="https://sunpeak.ai/docs/mcp-apps-inspector">
+    <picture>
+      <img alt="Inspector" src="https://cdn.sunpeak.ai/chatgpt-simulator.png">
+    </picture>
+  </a>
+</div>
 
-1. **Check your tunnel** is running and pointing to the correct port
-2. **Restart `sunpeak dev`** to clear stale connections
-3. **Refresh or re-add the MCP server** in the host's settings (Settings > MCP Servers)
-4. **Hard refresh** the host page (`Cmd+Shift+R` / `Ctrl+Shift+R`)
-5. **Open a new chat** in the host (cached iframes persist per-conversation)
+Toggle between hosts, themes, display modes, and device types from the sidebar. Call real tool handlers or load simulation fixtures for deterministic mock data. Changes reflect instantly via HMR. Works with any MCP server in any language.
 
-Full guide: [sunpeak.ai/docs/app-framework/guides/troubleshooting](https://sunpeak.ai/docs/app-framework/guides/troubleshooting)
+[Inspector documentation →](https://sunpeak.ai/docs/mcp-apps-inspector)
 
 ## Resources
 
@@ -153,3 +122,4 @@ Full guide: [sunpeak.ai/docs/app-framework/guides/troubleshooting](https://sunpe
 - [MCP Overview](https://sunpeak.ai/docs/mcp-apps/mcp/overview) · [Tools](https://sunpeak.ai/docs/mcp-apps/mcp/tools) · [Resources](https://sunpeak.ai/docs/mcp-apps/mcp/resources)
 - [MCP Apps SDK](https://github.com/modelcontextprotocol/ext-apps)
 - [ChatGPT Apps SDK Design Guidelines](https://developers.openai.com/apps-sdk/concepts/design-guidelines)
+- [Troubleshooting](https://sunpeak.ai/docs/app-framework/guides/troubleshooting)

package/bin/commands/inspect.mjs

@@ -388,7 +388,7 @@ function isAuthError(err) {
  * Create an MCP client connection.
  * @param {string} serverArg - URL or command string
  * @param {{ type?: 'none' | 'bearer' | 'oauth', bearerToken?: string, authProvider?: import('@modelcontextprotocol/sdk/client/auth.js').OAuthClientProvider, env?: Record<string, string>, cwd?: string }} [authConfig]
- * @returns {Promise<{ client: import('@modelcontextprotocol/sdk/client/index.js').Client, transport: import('@modelcontextprotocol/sdk/types.js').Transport, stderrOutput?: string[] }>}
+ * @returns {Promise<{ client: import('@modelcontextprotocol/sdk/client/index.js').Client, transport: import('@modelcontextprotocol/sdk/types.js').Transport, serverUrl?: string, stderrOutput?: string[] }>}
  */
 async function createMcpConnection(serverArg, authConfig) {
   const { Client } = await import('@modelcontextprotocol/sdk/client/index.js');
@@ -400,6 +400,19 @@ async function createMcpConnection(serverArg, authConfig) {
       '@modelcontextprotocol/sdk/client/streamableHttp.js'
     );
 
+    // Follow redirects (e.g. /mcp → /mcp/) before creating the transport.
+    // The MCP SDK transport doesn't follow redirects on its own.
+    let finalUrl = serverArg;
+    try {
+      const probeResponse = await fetch(serverArg, { method: 'HEAD', redirect: 'follow' });
+      if (probeResponse.url && probeResponse.url !== serverArg) {
+        finalUrl = probeResponse.url;
+      }
+    } catch {
+      // Probe failed (server down, network error) — use original URL and let
+      // the transport handle the error with its own diagnostics.
+    }
+
     const transportOpts = {};
 
     if (authConfig?.type === 'bearer' && authConfig.bearerToken) {
@@ -410,9 +423,9 @@ async function createMcpConnection(serverArg, authConfig) {
       transportOpts.authProvider = authConfig.authProvider;
     }
 
-    const transport = new StreamableHTTPClientTransport(new URL(serverArg), transportOpts);
+    const transport = new StreamableHTTPClientTransport(new URL(finalUrl), transportOpts);
     await client.connect(transport);
-    return { client, transport };
+    return { client, transport, serverUrl: finalUrl };
   } else {
     // Stdio transport — parse command string
     const parts = serverArg.split(/\s+/);
@@ -501,8 +514,21 @@ async function discoverSimulations(client) {
     const uri = tool._meta?.ui?.resourceUri ?? tool._meta?.['ui/resourceUri'];
     if (uri) {
       resource = resourceByUri.get(uri);
-      if (resource) {
-        resourceUrl = `/__sunpeak/read-resource?uri=${encodeURIComponent(uri)}`;
+      // Always create a resource URL when a tool declares a resourceUri,
+      // even if it wasn't found in listResources(). The server may use
+      // resource templates (e.g., ui://counter/{ui}) that resolve dynamically.
+      // The /__sunpeak/read-resource endpoint calls client.readResource()
+      // which handles template resolution server-side.
+      resourceUrl = `/__sunpeak/read-resource?uri=${encodeURIComponent(uri)}`;
+      // Create a synthetic resource object when not found via listResources().
+      // The inspector UI needs .resource to include the tool in the simulation list.
+      if (!resource) {
+        resource = {
+          uri,
+          name: tool.name,
+          title: tool.title || tool.name,
+          mimeType: 'text/html',
+        };
       }
     }
 
@@ -641,6 +667,45 @@ root.render(
  * @param {{ callToolDirect?: (name: string, args: Record<string, unknown>) => Promise<object>, simulationsDir?: string | null }} [pluginOpts]
  */
 function sunpeakInspectEndpointsPlugin(getClient, setClient, pluginOpts = {}) {
+  // Server URL and options for automatic session recovery.
+  // Set by inspectServer() after creating the initial connection.
+  let _serverUrl = '';
+  /** @type {Record<string, unknown>} */
+  let _connectionOpts = {};
+
+  /**
+   * Check if an error is a dead-session error (MCP server no longer recognizes
+   * the session ID). This happens when the MCP server restarts, the session
+   * times out, or the connection is interrupted.
+   * @param {Error} err
+   */
+  function isDeadSession(err) {
+    const msg = err?.message ?? '';
+    return msg.includes('Unknown session') || msg.includes('404') || msg.includes('fetch failed');
+  }
+
+  /**
+   * Attempt to reconnect to the MCP server and replace the current client.
+   * Returns true if reconnection succeeded.
+   */
+  async function tryReconnect() {
+    if (!_serverUrl) return false;
+    try {
+      console.warn(`[inspect] MCP session lost, reconnecting to ${_serverUrl}...`);
+      const newConn = await createMcpConnection(_serverUrl, _connectionOpts);
+      setClient(newConn.client);
+      console.log('[inspect] MCP session re-established');
+      return true;
+    } catch (err) {
+      console.error(`[inspect] MCP reconnection failed: ${err?.message ?? err}`);
+      return false;
+    }
+  }
+
+  // Initialize reconnection state from plugin options.
+  if (pluginOpts.serverUrl) _serverUrl = pluginOpts.serverUrl;
+  if (pluginOpts.connectionOpts) _connectionOpts = pluginOpts.connectionOpts;
+
   // In-memory OAuth state keyed by server URL, persisted across reconnects.
   /** @type {Map<string, { provider: any, getAuthUrl: () => URL | undefined, hasTokens: () => boolean, stateParam: string }>} */
   const oauthProviders = new Map();
@@ -654,7 +719,7 @@ function sunpeakInspectEndpointsPlugin(getClient, setClient, pluginOpts = {}) {
   return {
     name: 'sunpeak-inspect-endpoints',
     configureServer(server) {
-      // List tools from connected server
+      // List tools from connected server (with automatic session recovery)
       server.middlewares.use('/__sunpeak/list-tools', async (_req, res) => {
         try {
           const client = getClient();
@@ -662,6 +727,15 @@ function sunpeakInspectEndpointsPlugin(getClient, setClient, pluginOpts = {}) {
           res.writeHead(200, { 'Content-Type': 'application/json' });
           res.end(JSON.stringify(result));
         } catch (err) {
+          // If the session died (server restarted, timeout, etc.), try to reconnect once.
+          if (isDeadSession(err) && await tryReconnect()) {
+            try {
+              const result = await getClient().listTools();
+              res.writeHead(200, { 'Content-Type': 'application/json' });
+              res.end(JSON.stringify(result));
+              return;
+            } catch { /* fall through to error response */ }
+          }
           res.writeHead(500, { 'Content-Type': 'application/json' });
           res.end(JSON.stringify({ error: err.message }));
         }
@@ -706,6 +780,16 @@ function sunpeakInspectEndpointsPlugin(getClient, setClient, pluginOpts = {}) {
           res.writeHead(200, { 'Content-Type': 'application/json' });
           res.end(JSON.stringify(result));
         } catch (err) {
+          // Try reconnecting on dead session before returning error
+          if (isDeadSession(err) && await tryReconnect()) {
+            try {
+              const { name, arguments: args } = parsed;
+              const result = await getClient().callTool({ name, arguments: args });
+              res.writeHead(200, { 'Content-Type': 'application/json' });
+              res.end(JSON.stringify(result));
+              return;
+            } catch { /* fall through */ }
+          }
           res.writeHead(200, { 'Content-Type': 'application/json' });
           res.end(
             JSON.stringify({
@@ -1145,6 +1229,22 @@ function sunpeakInspectEndpointsPlugin(getClient, setClient, pluginOpts = {}) {
             res.end('');
           }
         } catch (err) {
+          // Try reconnecting on dead session before returning error
+          if (isDeadSession(err) && await tryReconnect()) {
+            try {
+              const retryResult = await getClient().readResource({ uri });
+              const retryContent = retryResult.contents?.[0];
+              if (retryContent) {
+                const mimeType = retryContent.mimeType || 'text/html';
+                res.writeHead(200, {
+                  'Content-Type': `${mimeType}; charset=utf-8`,
+                  'X-Content-Type-Options': 'nosniff',
+                });
+                res.end(typeof retryContent.text === 'string' ? retryContent.text : '');
+                return;
+              }
+            } catch { /* fall through */ }
+          }
           res.writeHead(500, { 'Content-Type': 'text/plain' });
           res.end(`Error reading resource: ${err.message}`);
         }
@@ -1229,13 +1329,16 @@ export async function inspectServer(opts) {
   // Connect to the MCP server (with retry for local servers that may still be starting)
   let mcpConnection;
   let lastStderrOutput = [];
+  // Track the resolved URL (after following redirects like /mcp → /mcp/).
+  let resolvedServerUrl = serverArg;
   const maxRetries = 5;
   const connectionOpts = {};
   if (serverEnv) connectionOpts.env = serverEnv;
   if (serverCwd) connectionOpts.cwd = serverCwd;
   for (let attempt = 1; attempt <= maxRetries; attempt++) {
     try {
-      mcpConnection = await createMcpConnection(serverArg, connectionOpts);
+      mcpConnection = await createMcpConnection(resolvedServerUrl, connectionOpts);
+      if (mcpConnection.serverUrl) resolvedServerUrl = mcpConnection.serverUrl;
       break;
     } catch (err) {
       // Capture stderr from the failed connection attempt for diagnostics.
@@ -1244,16 +1347,17 @@ export async function inspectServer(opts) {
       }
 
       // If the server requires OAuth, negotiate it and retry once.
-      if (isAuthError(err) && serverArg.startsWith('http')) {
+      if (isAuthError(err) && resolvedServerUrl.startsWith('http')) {
         console.log('Server requires authentication. Negotiating OAuth...');
         try {
-          const authProvider = await negotiateOAuth(serverArg);
+          const authProvider = await negotiateOAuth(resolvedServerUrl);
           console.log('OAuth authorized. Reconnecting...');
-          mcpConnection = await createMcpConnection(serverArg, {
+          mcpConnection = await createMcpConnection(resolvedServerUrl, {
             ...connectionOpts,
             type: 'oauth',
             authProvider,
           });
+          if (mcpConnection.serverUrl) resolvedServerUrl = mcpConnection.serverUrl;
           break;
         } catch (oauthErr) {
           console.error(`OAuth negotiation failed: ${oauthErr.message}`);
@@ -1278,6 +1382,23 @@ export async function inspectServer(opts) {
 
   console.log('Connected. Discovering tools and resources...');
 
+  // Monitor transport health. The MCP SDK opens a background SSE stream after
+  // initialization. If this stream drops, the server may purge the session,
+  // causing "Unknown session" errors on subsequent requests. Log lifecycle
+  // events so we can diagnose connection issues when they occur.
+  if (mcpConnection.transport) {
+    const origOnError = mcpConnection.transport.onerror;
+    mcpConnection.transport.onerror = (err) => {
+      console.warn(`[inspect] MCP transport error: ${err?.message ?? err}`);
+      origOnError?.(err);
+    };
+    const origOnClose = mcpConnection.transport.onclose;
+    mcpConnection.transport.onclose = () => {
+      console.warn('[inspect] MCP transport closed (session may be lost)');
+      origOnClose?.();
+    };
+  }
+
   // Extract app name and icon from server info (reported during MCP initialize)
   const serverInfo = mcpConnection.client.getServerVersion();
   const serverAppName = nameOverride ?? serverInfo?.name;
@@ -1333,7 +1454,7 @@ export async function inspectServer(opts) {
 </body>
 </html>`;
 
-  const inspectorServerUrl = serverArg;
+  const inspectorServerUrl = resolvedServerUrl;
 
   // Create the Vite server.
   // Use the sunpeak package dir as root to avoid scanning the user's project
@@ -1357,7 +1478,7 @@ export async function inspectServer(opts) {
       sunpeakInspectEndpointsPlugin(
         () => mcpConnection.client,
         (newClient) => { mcpConnection.client = newClient; },
-        { callToolDirect: opts.callToolDirect, simulationsDir }
+        { callToolDirect: opts.callToolDirect, simulationsDir, serverUrl: resolvedServerUrl, connectionOpts }
       ),
       // Serve /dist/{name}/{name}.html from the project directory (for Prod Resources mode).
       // The Inspector polls these paths via HEAD to check if built resources exist.
@@ -1441,8 +1562,16 @@ export async function inspectServer(opts) {
     ],
     server: {
       port,
-      open: open ?? (!process.env.CI && !process.env.SUNPEAK_LIVE_TEST),
+      // Listen on all interfaces so both 127.0.0.1 (used by Playwright tests)
+      // and localhost (used by interactive browsing) connect successfully.
+      // Without this, Vite defaults to localhost which may resolve to IPv6-only
+      // (::1) on macOS, causing ECONNREFUSED for IPv4 clients.
+      host: '0.0.0.0',
+      // Allow any hostname so the inspector works behind tunnels, in containers,
+      // and with custom /etc/hosts entries. Without this, Vite 8's DNS rebinding
+      // protection blocks requests whose Host header isn't localhost/127.0.0.1.
       allowedHosts: 'all',
+      open: open ?? (!process.env.CI && !process.env.SUNPEAK_LIVE_TEST),
     },
     optimizeDeps: {
       // Only pre-bundle React — the virtual entry module imports sunpeak from

package/bin/commands/new.mjs

@@ -299,6 +299,28 @@ export async function init(projectName, resourcesArg, deps = defaultDeps) {
 
   // Install dependencies with spinner
   const pm = d.detectPackageManager();
+
+  // Replace package manager references in README
+  if (pm !== 'pnpm') {
+    const readmePath = join(targetDir, 'README.md');
+    if (d.existsSync(readmePath)) {
+      const run = pm === 'npm' ? 'npm run' : pm;
+      const dlx = pm === 'npm' ? 'npx' : 'yarn dlx';
+      let readme = d.readFileSync(readmePath, 'utf-8');
+      readme = readme.replace(/pnpm dev\b/g, `${run} dev`);
+      readme = readme.replace(/pnpm build\b/g, `${run} build`);
+      readme = readme.replace(/pnpm start\b/g, `${run} start`);
+      readme = readme.replace(/pnpm test\b/g, `${run} test`);
+      readme = readme.replace(/pnpm test:unit\b/g, `${run} test:unit`);
+      readme = readme.replace(/pnpm test:e2e\b/g, `${run} test:e2e`);
+      readme = readme.replace(/pnpm test:visual\b/g, `${run} test:visual`);
+      readme = readme.replace(/pnpm test:live\b/g, `${run} test:live`);
+      readme = readme.replace(/pnpm test:eval\b/g, `${run} test:eval`);
+      readme = readme.replace(/pnpm add\b/g, pm === 'npm' ? 'npm install' : `${pm} add`);
+      readme = readme.replace(/pnpm dlx\b/g, dlx);
+      d.writeFileSync(readmePath, readme);
+    }
+  }
   const s = d.spinner();
   s.start(`Installing dependencies with ${pm}...`);
 
@@ -366,30 +388,32 @@ export async function init(projectName, resourcesArg, deps = defaultDeps) {
       initialValue: true,
     });
     if (!clack.isCancel(installSkill) && installSkill) {
+      const dlx = pm === 'yarn' ? 'yarn dlx' : pm === 'npm' ? 'npx' : 'pnpm dlx';
       try {
-        d.execSync('pnpm dlx skills add Sunpeak-AI/sunpeak@create-sunpeak-app Sunpeak-AI/sunpeak@test-mcp-server', {
+        d.execSync(`${dlx} skills add Sunpeak-AI/sunpeak@create-sunpeak-app Sunpeak-AI/sunpeak@test-mcp-server`, {
           cwd: targetDir,
           stdio: 'inherit',
         });
       } catch {
-        d.console.log('Skill install skipped. You can install later with: pnpm dlx skills add Sunpeak-AI/sunpeak@create-sunpeak-app Sunpeak-AI/sunpeak@test-mcp-server');
+        d.console.log(`Skill install skipped. You can install later with: ${dlx} skills add Sunpeak-AI/sunpeak@create-sunpeak-app Sunpeak-AI/sunpeak@test-mcp-server`);
       }
     }
   }
 
+  const run = pm === 'npm' ? 'npm run' : pm;
   d.outro(`Done! To get started:
 
   cd ${projectName}
-  sunpeak dev
+  ${run} dev
 
 Your project commands:
 
-  sunpeak dev                # Start dev server + MCP endpoint
-  sunpeak build              # Build for production
-  sunpeak test               # Run unit + e2e tests
-  sunpeak test --eval        # Run LLM evals (configure models in tests/evals/eval.config.ts)
-  sunpeak test --visual      # Run visual regression tests
-  sunpeak test --live        # Run live tests against real AI hosts`);
+  ${run} dev              # Start dev server + MCP endpoint
+  ${run} build            # Build for production
+  ${run} test             # Run unit + e2e tests
+  ${run} test:eval        # Run LLM evals (configure models in tests/evals/eval.config.ts)
+  ${run} test:visual      # Run visual regression tests
+  ${run} test:live        # Run live tests against real AI hosts`);
 }
 
 // Allow running directly