awel 0.1.1 → 0.2.0

package/README.md

@@ -12,9 +12,17 @@ AI-powered development overlay for Next.js. Awel runs a proxy in front of your d
 # Skip if you're already in a Next.js app
 npx create-next-app@latest my-app && cd my-app
 
+# Set up at least one AI provider (pick one):
+export ANTHROPIC_API_KEY="sk-ant-..."   # Anthropic API
+export OPENAI_API_KEY="sk-..."          # OpenAI
+export GOOGLE_GENERATIVE_AI_API_KEY="..." # Google AI
+# Or install the Claude CLI: https://docs.anthropic.com/en/docs/claude-code
+
 npx awel dev
 ```
 
+Awel needs at least one configured provider to function. See [Supported Models](#supported-models) for the full list.
+
 This starts Awel on port 3001 and proxies your Next.js dev server on port 3000. Open `http://localhost:3001` to see your app with the Awel overlay.
 
 ### Options

package/README.zh-CN.md

@@ -12,9 +12,17 @@
 # 如果你已经在一个 Next.js 项目中，可以跳过这一步
 npx create-next-app@latest my-app && cd my-app
 
+# 至少配置一个 AI 服务商（任选其一）：
+export ANTHROPIC_API_KEY="sk-ant-..."   # Anthropic API
+export OPENAI_API_KEY="sk-..."          # OpenAI
+export GOOGLE_GENERATIVE_AI_API_KEY="..." # Google AI
+# 或安装 Claude CLI：https://docs.anthropic.com/en/docs/claude-code
+
 npx awel dev
 ```
 
+Awel 需要至少一个已配置的服务商才能运行。完整列表见[支持的模型](#支持的模型)。
+
 Awel 会在端口 3001 启动，并代理运行在端口 3000 的 Next.js 开发服务器。打开 `http://localhost:3001` 即可看到带有 Awel 浮层的应用。
 
 ### 选项

package/dist/cli/agent.d.ts

@@ -2,5 +2,6 @@ import { Hono } from 'hono';
 /**
  * Creates the agent API routes with SSE streaming.
  * @param projectCwd - The user's project directory (where they ran `awel dev`)
+ * @param isFresh - Getter for whether the project is in creation mode
  */
-export declare function createAgentRoute(projectCwd: string, targetPort: number): Hono<import("hono/types").BlankEnv, import("hono/types").BlankSchema, "/">;
+export declare function createAgentRoute(projectCwd: string, targetPort: number, isFresh?: () => boolean): Hono<import("hono/types").BlankEnv, import("hono/types").BlankSchema, "/">;

package/dist/cli/agent.js

@@ -95,8 +95,9 @@ function setSSEHeaders(c) {
 /**
  * Creates the agent API routes with SSE streaming.
  * @param projectCwd - The user's project directory (where they ran `awel dev`)
+ * @param isFresh - Getter for whether the project is in creation mode
  */
-export function createAgentRoute(projectCwd, targetPort) {
+export function createAgentRoute(projectCwd, targetPort, isFresh) {
     const agent = new Hono();
     // ─── Model Catalog ───────────────────────────────────────
     agent.get('/api/models', (c) => {
@@ -158,7 +159,7 @@ export function createAgentRoute(projectCwd, targetPort) {
             // Appending eagerly would leave orphan user messages in the session when
             // the stream is aborted or paused for user input, causing consecutive
             // user messages that trigger API 400 errors (especially with Anthropic).
-            provider.streamResponse(adapter, messages, { projectCwd, targetPort, signal })
+            provider.streamResponse(adapter, messages, { projectCwd, targetPort, signal, creationMode: isFresh?.() })
                 .then((responseMessages) => {
                 if (responseMessages.length > 0) {
                     appendUserMessage(userContent);

package/dist/cli/awel-config.d.ts

@@ -0,0 +1,10 @@
+export interface AwelConfig {
+    babelPlugin?: boolean;
+    onboarded?: boolean;
+    fresh?: boolean;
+    createdAt?: string;
+}
+export declare function readAwelConfig(projectCwd: string): AwelConfig;
+export declare function writeAwelConfig(projectCwd: string, config: AwelConfig): void;
+export declare function isProjectFresh(projectCwd: string): boolean;
+export declare function markProjectReady(projectCwd: string): void;

package/dist/cli/awel-config.js

@@ -0,0 +1,28 @@
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { join } from 'path';
+export function readAwelConfig(projectCwd) {
+    const configPath = join(projectCwd, '.awel', 'config.json');
+    if (!existsSync(configPath))
+        return {};
+    try {
+        return JSON.parse(readFileSync(configPath, 'utf-8'));
+    }
+    catch {
+        return {};
+    }
+}
+export function writeAwelConfig(projectCwd, config) {
+    const dir = join(projectCwd, '.awel');
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+    writeFileSync(join(dir, 'config.json'), JSON.stringify(config, null, 2) + '\n', 'utf-8');
+}
+export function isProjectFresh(projectCwd) {
+    return readAwelConfig(projectCwd).fresh === true;
+}
+export function markProjectReady(projectCwd) {
+    const config = readAwelConfig(projectCwd);
+    config.fresh = false;
+    writeAwelConfig(projectCwd, config);
+}

package/dist/cli/babel-setup.js

@@ -1,6 +1,7 @@
-import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { existsSync, readFileSync, writeFileSync } from 'fs';
 import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
+import { readAwelConfig, writeAwelConfig } from './awel-config.js';
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const BABEL_CONFIG_FILES = [
     'babel.config.js',
@@ -37,24 +38,6 @@ function findExistingBabelConfig(projectCwd) {
         return 'package.json';
     return null;
 }
-function readAwelConfig(projectCwd) {
-    const configPath = join(projectCwd, '.awel', 'config.json');
-    if (!existsSync(configPath))
-        return {};
-    try {
-        return JSON.parse(readFileSync(configPath, 'utf-8'));
-    }
-    catch {
-        return {};
-    }
-}
-function writeAwelConfig(projectCwd, config) {
-    const dir = join(projectCwd, '.awel');
-    if (!existsSync(dir)) {
-        mkdirSync(dir, { recursive: true });
-    }
-    writeFileSync(join(dir, 'config.json'), JSON.stringify(config, null, 2) + '\n', 'utf-8');
-}
 // ANSI 256-color helpers — darker shades that stay visible on light backgrounds
 const bold = (s) => `\x1b[1m${s}\x1b[22m`;
 const dim = (s) => `\x1b[2m${s}\x1b[22m`;

package/dist/cli/create.d.ts

@@ -0,0 +1 @@
+export declare function runCreate(projectNameArg?: string): Promise<void>;

package/dist/cli/create.js

@@ -0,0 +1,136 @@
+import { existsSync, cpSync, readdirSync } from 'fs';
+import { join, dirname, resolve } from 'path';
+import { fileURLToPath } from 'url';
+import { execSync } from 'child_process';
+import * as p from '@clack/prompts';
+import { writeAwelConfig } from './awel-config.js';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const TEMPLATES = [
+    { value: 'blank', label: 'Blank', hint: 'Empty Next.js app with AGENT.md' },
+    { value: 'landing', label: 'Landing Page', hint: 'Hero, features, and CTA sections' },
+    { value: 'dashboard', label: 'Dashboard', hint: 'Sidebar layout with stats cards' },
+    { value: 'blog', label: 'Blog', hint: 'Blog listing with dynamic post pages' },
+    { value: 'portfolio', label: 'Portfolio', hint: 'Project showcase with cards' },
+    { value: 'saas', label: 'SaaS', hint: 'Landing, pricing, and dashboard pages' },
+];
+function detectPackageManager() {
+    const agent = process.env.npm_config_user_agent;
+    if (agent) {
+        if (agent.startsWith('pnpm'))
+            return 'pnpm';
+        if (agent.startsWith('yarn'))
+            return 'yarn';
+        if (agent.startsWith('bun'))
+            return 'bun';
+    }
+    return 'npm';
+}
+function getTemplatesDir() {
+    return join(__dirname, 'templates');
+}
+export async function runCreate(projectNameArg) {
+    p.intro('Create a new Awel project');
+    // 1. Project name
+    let projectName;
+    if (projectNameArg) {
+        projectName = projectNameArg;
+        p.log.info(`Project name: ${projectName}`);
+    }
+    else {
+        const result = await p.text({
+            message: 'What is your project name?',
+            placeholder: 'my-app',
+            validate(value) {
+                if (!value || !value.trim())
+                    return 'Project name is required';
+                if (!/^[a-zA-Z0-9_-]+$/.test(value.trim()))
+                    return 'Project name can only contain letters, numbers, hyphens, and underscores';
+            },
+        });
+        if (p.isCancel(result)) {
+            p.cancel('Operation cancelled.');
+            process.exit(0);
+        }
+        projectName = result;
+    }
+    const projectDir = resolve(process.cwd(), projectName);
+    // Check if directory already exists
+    if (existsSync(projectDir)) {
+        p.cancel(`Directory "${projectName}" already exists.`);
+        process.exit(1);
+    }
+    // 2. Template selection
+    const template = await p.select({
+        message: 'Which template would you like to use?',
+        options: TEMPLATES,
+    });
+    if (p.isCancel(template)) {
+        p.cancel('Operation cancelled.');
+        process.exit(0);
+    }
+    // 3. Package manager
+    const detected = detectPackageManager();
+    const packageManager = await p.select({
+        message: 'Which package manager do you want to use?',
+        options: [
+            { value: 'npm', label: 'npm', hint: detected === 'npm' ? 'detected' : undefined },
+            { value: 'pnpm', label: 'pnpm', hint: detected === 'pnpm' ? 'detected' : undefined },
+            { value: 'yarn', label: 'yarn', hint: detected === 'yarn' ? 'detected' : undefined },
+            { value: 'bun', label: 'bun', hint: detected === 'bun' ? 'detected' : undefined },
+        ],
+        initialValue: detected,
+    });
+    if (p.isCancel(packageManager)) {
+        p.cancel('Operation cancelled.');
+        process.exit(0);
+    }
+    const pm = packageManager;
+    const templateName = template;
+    // 4. Scaffold with create-next-app
+    const s = p.spinner();
+    s.start('Creating Next.js app...');
+    const useFlag = pm === 'npm' ? '--use-npm' : pm === 'pnpm' ? '--use-pnpm' : pm === 'yarn' ? '--use-yarn' : '--use-bun';
+    const cnaArgs = [
+        'create-next-app@latest',
+        projectDir,
+        '--ts',
+        '--tailwind',
+        '--eslint',
+        '--app',
+        '--src-dir',
+        '--import-alias', '@/*',
+        useFlag,
+    ];
+    try {
+        execSync(`npx ${cnaArgs.map(a => `"${a}"`).join(' ')}`, {
+            stdio: 'inherit',
+            timeout: 120000,
+        });
+    }
+    catch (err) {
+        s.stop('Failed to create Next.js app.');
+        const message = err instanceof Error ? err.message : String(err);
+        p.log.error(message);
+        process.exit(1);
+    }
+    s.stop('Next.js app created.');
+    // 5. Copy template overlay files
+    s.start('Applying template...');
+    const templateDir = join(getTemplatesDir(), templateName);
+    if (existsSync(templateDir) && readdirSync(templateDir).length > 0) {
+        cpSync(templateDir, projectDir, { recursive: true, force: true });
+    }
+    s.stop('Template applied.');
+    // 6. Write Awel config
+    writeAwelConfig(projectDir, {
+        template: templateName,
+        packageManager: pm,
+        createdAt: new Date().toISOString(),
+    });
+    // 7. Done
+    p.log.success(`Project "${projectName}" created with the "${templateName}" template.`);
+    p.log.info('Next steps:');
+    p.log.step(`  cd ${projectName}`);
+    p.log.step('  npx awel dev');
+    p.outro('Happy building!');
+}

package/dist/cli/index.js

@@ -3,8 +3,11 @@ import { startServer } from './server.js';
 import { AWEL_PORT, USER_APP_PORT } from './config.js';
 import { setVerbose } from './verbose.js';
 import { ensureBabelPlugin } from './babel-setup.js';
+import { ensureProvider } from './onboarding.js';
 import { awel } from './logger.js';
 import { spawnDevServer } from './subprocess.js';
+import { writeAwelConfig, isProjectFresh } from './awel-config.js';
+import { resolve } from 'path';
 program
     .name('awel')
     .description('AI-powered development overlay for Next.js')
@@ -18,17 +21,70 @@ program
     const targetPort = parseInt(options.port, 10);
     if (options.verbose)
         setVerbose(true);
-    await ensureBabelPlugin(process.cwd());
+    const fresh = isProjectFresh(process.cwd());
+    await ensureProvider(process.cwd());
+    if (!fresh)
+        await ensureBabelPlugin(process.cwd());
     awel.log('🌟 Starting Awel...');
+    if (fresh)
+        awel.log('   Mode: Creation (new project)');
     awel.log(`   Target app port: ${targetPort}`);
     awel.log(`   Awel control server: http://localhost:${AWEL_PORT}`);
     awel.log('');
     // Start the Awel control server (proxy + dashboard)
-    await startServer({ awelPort: AWEL_PORT, targetPort, projectCwd: process.cwd() });
+    await startServer({ awelPort: AWEL_PORT, targetPort, projectCwd: process.cwd(), fresh });
     // Start the user's Next.js app via subprocess manager (handles auto-restart)
     await spawnDevServer({ port: targetPort, cwd: process.cwd() });
     awel.log('');
-    awel.log(`✨ Awel is ready! Open http://localhost:${AWEL_PORT}`);
-    awel.log('   Look for the floating button in the bottom-right corner.');
+    if (fresh) {
+        awel.log(`✨ Awel is ready! Open http://localhost:${AWEL_PORT}`);
+        awel.log('   Describe what you want to build and Awel will create it for you.');
+    }
+    else {
+        awel.log(`✨ Awel is ready! Open http://localhost:${AWEL_PORT}`);
+        awel.log('   Look for the floating button in the bottom-right corner.');
+    }
+});
+program
+    .command('create')
+    .description('Create a new Next.js project with Awel')
+    .action(async () => {
+    const p = await import('@clack/prompts');
+    const { execa } = await import('execa');
+    p.intro('Create a new project with Awel');
+    const name = await p.text({
+        message: 'Project name',
+        placeholder: 'my-app',
+        validate: (value) => {
+            if (!value)
+                return 'Project name is required';
+            if (!/^[a-z0-9._-]+$/i.test(value))
+                return 'Project name must only contain letters, numbers, dashes, dots, and underscores';
+        },
+    });
+    if (p.isCancel(name)) {
+        p.cancel('Cancelled');
+        process.exit(0);
+    }
+    const s = p.spinner();
+    s.start('Creating Next.js project...');
+    try {
+        await execa('npx', [
+            'create-next-app@latest', name,
+            '--yes',
+            '--typescript', '--tailwind', '--eslint',
+            '--app', '--use-npm',
+        ], { cwd: process.cwd(), stdin: 'ignore', stdout: 'pipe', stderr: 'pipe' });
+    }
+    catch (err) {
+        s.stop('Failed to create project');
+        const stderr = err.stderr || err.message || String(err);
+        p.log.error(stderr);
+        process.exit(1);
+    }
+    s.stop('Project created');
+    const projectDir = resolve(process.cwd(), name);
+    writeAwelConfig(projectDir, { fresh: true, createdAt: new Date().toISOString() });
+    p.outro(`Done! Now run:\n\n  cd ${name}\n  npx awel dev`);
 });
 program.parse();

package/dist/cli/onboarding.d.ts

@@ -0,0 +1 @@
+export declare function ensureProvider(projectCwd: string): Promise<void>;

package/dist/cli/onboarding.js

@@ -0,0 +1,58 @@
+import { readAwelConfig, writeAwelConfig } from './awel-config.js';
+import { getAvailableProviders, PROVIDER_ENV_KEYS, PROVIDER_LABELS } from './providers/registry.js';
+import { awel } from './logger.js';
+function printSetupInstructions() {
+    awel.log('No LLM providers are configured.');
+    awel.log('Awel needs at least one AI provider to function.');
+    awel.log('');
+    awel.log('Set up a provider by exporting its API key:');
+    awel.log('');
+    // List all providers with their setup commands
+    for (const [provider, envKey] of Object.entries(PROVIDER_ENV_KEYS)) {
+        const label = PROVIDER_LABELS[provider] ?? provider;
+        awel.log(`  ${label}`);
+        awel.log(`  export ${envKey}="..."`);
+        awel.log('');
+    }
+    // Claude Code is special — no env var, needs CLI install
+    const label = PROVIDER_LABELS['claude-code'] ?? 'Claude Code';
+    awel.log(`  ${label}`);
+    awel.log('  Install the Claude CLI: https://docs.anthropic.com/en/docs/claude-code');
+    awel.log('');
+    awel.log('Then run `awel dev` again.');
+}
+export async function ensureProvider(projectCwd) {
+    const config = readAwelConfig(projectCwd);
+    const providers = getAvailableProviders();
+    const available = providers.filter(p => p.available);
+    const isFirstRun = !config.onboarded;
+    if (isFirstRun && available.length > 0) {
+        // First run with providers available — show welcome
+        awel.log('');
+        awel.log('Welcome to Awel!');
+        awel.log('AI-powered development overlay for Next.js');
+        awel.log('');
+        awel.log(`\u2714 ${available.length} provider${available.length === 1 ? '' : 's'} available:`);
+        for (const p of available) {
+            awel.log(`  \u25CF ${p.label}`);
+        }
+        awel.log('');
+        writeAwelConfig(projectCwd, { ...config, onboarded: true });
+        return;
+    }
+    if (isFirstRun && available.length === 0) {
+        // First run with NO providers — show welcome + instructions, exit
+        awel.log('');
+        awel.log('Welcome to Awel!');
+        awel.log('AI-powered development overlay for Next.js');
+        awel.log('');
+        printSetupInstructions();
+        process.exit(1);
+    }
+    if (!isFirstRun && available.length === 0) {
+        // Subsequent run with NO providers — instructions only, exit
+        printSetupInstructions();
+        process.exit(1);
+    }
+    // Subsequent run with providers available — silent pass-through
+}

package/dist/cli/providers/registry.d.ts

@@ -1,5 +1,17 @@
 import type { StreamProvider, ModelDefinition } from './types.js';
 export declare const PROVIDER_ENV_KEYS: Record<string, string>;
+export declare const PROVIDER_LABELS: Record<string, string>;
+export interface ProviderAvailability {
+    provider: string;
+    label: string;
+    available: boolean;
+    envVar: string | null;
+}
+/**
+ * Returns deduplicated provider availability info.
+ * Checks each provider once (claude-code via binary check, others via env var).
+ */
+export declare function getAvailableProviders(): ProviderAvailability[];
 export declare function resolveProvider(modelId: string): {
     provider: StreamProvider;
     modelProvider: string;

package/dist/cli/providers/registry.js

@@ -59,6 +59,47 @@ function isClaudeBinaryAvailable() {
     }
     return _claudeBinaryAvailable;
 }
+// ─── Provider Availability ────────────────────────────────────
+export const PROVIDER_LABELS = {
+    'claude-code': 'Claude Code',
+    anthropic: 'Anthropic API',
+    openai: 'OpenAI',
+    'google-ai': 'Google AI',
+    'vercel-gateway': 'Vercel AI Gateway',
+    qwen: 'Qwen',
+    minimax: 'MiniMax',
+};
+/**
+ * Returns deduplicated provider availability info.
+ * Checks each provider once (claude-code via binary check, others via env var).
+ */
+export function getAvailableProviders() {
+    const seen = new Set();
+    const result = [];
+    for (const model of MODEL_CATALOG) {
+        if (seen.has(model.provider))
+            continue;
+        seen.add(model.provider);
+        const label = PROVIDER_LABELS[model.provider] ?? model.provider;
+        if (model.provider === 'claude-code') {
+            result.push({
+                provider: model.provider,
+                label,
+                available: isClaudeBinaryAvailable(),
+                envVar: null,
+            });
+            continue;
+        }
+        const envKey = PROVIDER_ENV_KEYS[model.provider];
+        result.push({
+            provider: model.provider,
+            label,
+            available: envKey ? !!process.env[envKey] : true,
+            envVar: envKey ?? null,
+        });
+    }
+    return result;
+}
 // ─── Provider Resolution ─────────────────────────────────────
 export function resolveProvider(modelId) {
     const model = MODEL_CATALOG.find(m => m.id === modelId);

package/dist/cli/providers/types.d.ts

@@ -6,6 +6,8 @@ export interface ProviderConfig {
     targetPort: number;
     /** When aborted, the provider should stop the LLM stream and exit early. */
     signal?: AbortSignal;
+    /** When true, the agent uses a creation-mode system prompt for building new apps. */
+    creationMode?: boolean;
 }
 export interface StreamProvider {
     streamResponse(stream: SSEStreamingApi, messages: ModelMessage[], config: ProviderConfig): Promise<ResponseMessage[]>;

package/dist/cli/providers/vercel.js

@@ -67,6 +67,48 @@ Inspector Context:
 
 Language:
 - IMPORTANT: Always respond in the same language the user writes in. If the user writes in Chinese, respond in Chinese. If the user writes in English, respond in English. Match the user's language throughout the conversation.`;
+const CREATION_SYSTEM_PROMPT = `You are Awel in creation mode. The user has just created a fresh Next.js project and wants to build something new.
+
+You have access to the same tools as in normal mode:
+- Read: Read file contents
+- Write: Create or overwrite files (creates parent directories automatically)
+- Edit: Find-and-replace edits in files
+- Bash: Execute shell commands
+- Glob: Find files by glob pattern
+- Ls: List directory contents
+- AskUser: Ask the user clarifying questions with selectable options
+- Grep: Search file contents for a regex pattern
+- MultiEdit: Apply multiple find-and-replace edits to a single file in one call
+- WebSearch: Search the web for real-time information
+- WebFetch: Fetch content from a URL
+- CodeSearch: Search the web for code examples
+- TodoRead: Read the current task list
+- TodoWrite: Create or update the task list
+- RestartDevServer: Restart the dev server
+
+Your workflow:
+
+1. UNDERSTAND: If the user's request is vague or could go multiple directions, use AskUser to ask 1-3 clarifying questions about the app type, key features, and design preferences. Keep questions focused and provide concrete options.
+
+2. GENERATE: Create a complete, working Next.js app using:
+   - App Router with TypeScript
+   - Tailwind CSS for all styling
+   - Clean component structure in the app/ directory
+   - Modern, responsive design with good typography and spacing
+   - Proper error handling and loading states
+   - No placeholder code or TODOs — everything should work
+
+3. VERIFY: After generating all files, check that the dev server is running without errors. If there are build errors, fix them.
+
+Clarifying Questions:
+- When a user's request is ambiguous or has multiple valid approaches, use the AskUser tool to ask clarifying questions before proceeding.
+- Present 1-4 questions, each with 2-4 concrete options. Use multiSelect when choices are not mutually exclusive.
+- Keep header labels short (max 12 chars). Put the recommended option first with "(Recommended)" in the label.
+- CRITICAL: All fields in the AskUser tool must be plain text. Do NOT use markdown formatting.
+- After calling AskUser, STOP and wait for the user's answers before continuing.
+
+Language:
+- IMPORTANT: Always respond in the same language the user writes in. If the user writes in Chinese, respond in Chinese. If the user writes in English, respond in English.`;
 /** Detects files Claude Code uses for plan output (.claude/plans/*.md, plan.md) */
 function isPlanFile(filePath) {
     const normalized = filePath.replace(/\\/g, '/');
@@ -184,9 +226,10 @@ export function createVercelProvider(modelId, providerType) {
             try {
                 // Self-contained providers handle their own system prompt and tools internally.
                 // All other providers get our system prompt + tools.
+                const basePrompt = config.creationMode ? CREATION_SYSTEM_PROMPT : SYSTEM_PROMPT;
                 const systemPrompt = isSelfContained
                     ? undefined
-                    : `${SYSTEM_PROMPT}\n\nThe user's project directory is: ${config.projectCwd}`;
+                    : `${basePrompt}\n\nThe user's project directory is: ${config.projectCwd}`;
                 const streamTextArgs = {
                     model,
                     ...(systemPrompt && { system: systemPrompt }),

package/dist/cli/proxy.d.ts

@@ -2,4 +2,4 @@
  * Creates proxy middleware that forwards requests to the target app
  * and injects the Awel host script into HTML responses.
  */
-export declare function createProxyMiddleware(targetPort: number, projectCwd?: string): (c: any, _next: () => Promise<void>) => Promise<any>;
+export declare function createProxyMiddleware(targetPort: number, projectCwd?: string, isFresh?: () => boolean): (c: any, _next: () => Promise<void>) => Promise<any>;

package/dist/cli/proxy.js

@@ -1,10 +1,48 @@
+import { readFileSync, existsSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+/**
+ * Reads the dashboard index.html and injects the creation mode flag.
+ * Returns the modified HTML or null if the file doesn't exist.
+ */
+function getCreationModeHtml() {
+    const indexPath = join(__dirname, '../dashboard/index.html');
+    if (!existsSync(indexPath))
+        return null;
+    let html = readFileSync(indexPath, 'utf-8');
+    const creationScript = `<script>window.__AWEL_CREATION_MODE__=true</script>`;
+    if (html.includes('</head>')) {
+        html = html.replace('</head>', `${creationScript}</head>`);
+    }
+    else {
+        html = creationScript + html;
+    }
+    return html;
+}
 /**
  * Creates proxy middleware that forwards requests to the target app
  * and injects the Awel host script into HTML responses.
  */
-export function createProxyMiddleware(targetPort, projectCwd) {
+export function createProxyMiddleware(targetPort, projectCwd, isFresh) {
     return async (c, _next) => {
         const url = new URL(c.req.url);
+        // In creation mode, serve the dashboard at all HTML navigation requests.
+        // Non-HTML requests (JS, CSS, HMR) still proxy through to the dev server.
+        if (isFresh?.()) {
+            const accept = c.req.header('accept') || '';
+            const isNavigation = accept.includes('text/html');
+            if (isNavigation) {
+                const html = getCreationModeHtml();
+                if (html) {
+                    return new Response(html, {
+                        status: 200,
+                        headers: { 'Content-Type': 'text/html; charset=utf-8' },
+                    });
+                }
+            }
+        }
         const targetUrl = `http://localhost:${targetPort}${url.pathname}${url.search}`;
         try {
             // Clone headers and remove Accept-Encoding to get uncompressed response
@@ -18,7 +56,7 @@ export function createProxyMiddleware(targetPort, projectCwd) {
                     : undefined,
             });
             const contentType = response.headers.get('content-type') || '';
-            // If it's HTML, inject our script
+            // If it's HTML, inject the Awel host script
             if (contentType.includes('text/html')) {
                 let html = await response.text();
                 // Inject project CWD (for source-map resolution) and the host script
@@ -26,12 +64,8 @@ export function createProxyMiddleware(targetPort, projectCwd) {
                     ? `<script>window.__AWEL_PROJECT_CWD__=${JSON.stringify(projectCwd)}</script>`
                     : '';
                 // Constrain Next.js error overlay stacking context below Awel's UI.
-                // Covers both legacy and modern Next.js error overlay custom elements.
                 const awelOverlayStyle = `<style id="awel-overlay-fix">nextjs-portal, nextjs-portal-root, next-error-overlay, nextjs-dev-tools { position: relative !important; z-index: 999997 !important; }</style>`;
                 const scriptTag = `${awelOverlayStyle}${cwdScript}<script src="/_awel/host.js"></script>`;
-                // Inject into <head> so the script loads early — even on error pages
-                // where the body might be minimal or replaced by Next.js error recovery.
-                // Fall back to </body> then </html> if <head> isn't found.
                 if (html.includes('</head>')) {
                     html = html.replace('</head>', `${scriptTag}</head>`);
                 }
@@ -56,7 +90,6 @@ export function createProxyMiddleware(targetPort, projectCwd) {
             // For non-HTML responses, pass through as-is but clean up encoding headers
             const body = await response.arrayBuffer();
             const responseHeaders = new Headers(response.headers);
-            // Remove content-encoding since we've already decoded the response
             responseHeaders.delete('content-encoding');
             responseHeaders.delete('content-length');
             return new Response(body, {