@agentuity/cli 0.1.15 → 0.1.16

package/src/cmd/project/template-flow.ts

@@ -55,6 +55,9 @@ interface CreateFlowOptions {
 	orgId?: string;
 	region?: string;
 	apiClient?: APIClient;
+	database?: string;
+	storage?: string;
+	enableAuth?: boolean;
 }
 
 export interface CreateFlowResult {
@@ -85,8 +88,14 @@ export async function runCreateFlow(options: CreateFlowOptions): Promise<CreateF
 		region,
 		apiClient,
 		domains,
+		database: databaseOption,
+		storage: storageOption,
+		enableAuth: enableAuthOption,
 	} = options;
 
+	const isHeadless = !process.stdin.isTTY || !process.stdout.isTTY;
+	const isInteractive = !skipPrompts && !isHeadless;
+
 	// Fetch available templates
 	if (templateDir) {
 		tui.info(`📋 Loading templates from local directory: ${templateDir}...\n`);
@@ -120,11 +129,11 @@ export async function runCreateFlow(options: CreateFlowOptions): Promise<CreateF
 	// Create prompt flow
 	const prompt = createPrompt();
 
-	if (!skipPrompts) {
+	if (isInteractive) {
 		prompt.intro('Create Agentuity Project');
 	}
 
-	if (!projectName && !skipPrompts) {
+	if (!projectName && isInteractive) {
 		projectName = await prompt.text({
 			message: 'What is the name of your project?',
 			hint: 'The name must be unique for your organization',
@@ -164,8 +173,8 @@ export async function runCreateFlow(options: CreateFlowOptions): Promise<CreateF
 	const destEmpty = destIsDir ? readdirSync(dest).length === 0 : !destExists;
 
 	if (destExists && !destEmpty && dirName !== '.') {
-		// In TTY mode, ask if they want to overwrite
-		if (process.stdin.isTTY && !skipPrompts) {
+		// In interactive mode, ask if they want to overwrite
+		if (isInteractive) {
 			tui.warning(`Directory ${dest} already exists and is not empty.`, true);
 			console.log(tui.tuiColors.secondary('│'));
 			const overwrite = await prompt.confirm({
@@ -210,7 +219,7 @@ export async function runCreateFlow(options: CreateFlowOptions): Promise<CreateF
 			return undefined as never;
 		}
 		selectedTemplate = found;
-	} else if (skipPrompts || templates.length === 1) {
+	} else if (!isInteractive || templates.length === 1) {
 		selectedTemplate = templates[0];
 	} else {
 		let maxLength = 15;
@@ -275,7 +284,13 @@ export async function runCreateFlow(options: CreateFlowOptions): Promise<CreateF
 	}
 
 	// Add separator bar if we're going to show resource prompts
-	if (!skipPrompts && auth && apiClient && catalystClient && orgId && region) {
+	const canProvision = auth && apiClient && catalystClient && orgId && region;
+	// Only count as resource flags if actually requesting provisioning (not explicit skip)
+	const hasResourceFlags =
+		(databaseOption !== undefined && databaseOption.toLowerCase() !== 'skip') ||
+		(storageOption !== undefined && storageOption.toLowerCase() !== 'skip');
+
+	if (isInteractive && canProvision) {
 		const { symbols, tuiColors } = tui;
 		console.log(tuiColors.secondary(symbols.bar));
 	}
@@ -283,43 +298,127 @@ export async function runCreateFlow(options: CreateFlowOptions): Promise<CreateF
 	let _domains = domains;
 	const resourceEnvVars: EnvVars = {};
 
-	if (auth && apiClient && catalystClient && orgId && region && !skipPrompts) {
-		// Fetch resources for selected org and region using Catalyst API
-		const resources = await tui.spinner({
-			message: 'Fetching resources',
-			clearOnSuccess: true,
-			callback: async () => {
-				return listResources(catalystClient, orgId, region);
-			},
-		});
+	// Validate that resource flags require authentication and registration
+	if (hasResourceFlags && !canProvision) {
+		logger.fatal(
+			'Cannot provision database/storage without being authenticated and registering the project.\n' +
+				'Remove --no-register or omit --database/--storage flags.',
+			ErrorCode.VALIDATION_FAILED
+		);
+	}
 
-		logger.debug(`Resources for org ${orgId} in region ${region}:`, resources);
+	// Validate that --enable-auth requires authentication and registration
+	if (enableAuthOption && !canProvision) {
+		logger.fatal(
+			'Cannot enable Agentuity Auth without being authenticated and registering the project.\n' +
+				'Remove --no-register or omit --enable-auth flag.',
+			ErrorCode.VALIDATION_FAILED
+		);
+	}
 
-		const db_action = await prompt.select({
-			message: 'Create SQL Database?',
-			options: [
-				{ value: 'Skip', label: 'Skip or Setup later' },
-				{ value: 'Create New', label: 'Create a new database' },
-				...resources.db.map((db) => ({
-					value: db.name,
-					label: `Use database: ${tui.tuiColors.primary(db.name)}`,
-				})),
-			],
-		});
+	if (canProvision) {
+		// Fetch resources for selected org and region using Catalyst API (needed for both interactive and CLI flags)
+		let resources: Awaited<ReturnType<typeof listResources>> | undefined;
 
-		const s3_action = await prompt.select({
-			message: 'Create Storage Bucket?',
-			options: [
-				{ value: 'Skip', label: 'Skip or Setup later' },
-				{ value: 'Create New', label: 'Create a new bucket' },
-				...resources.s3.map((bucket) => ({
-					value: bucket.bucket_name,
-					label: `Use bucket: ${tui.tuiColors.primary(bucket.bucket_name)}`,
-				})),
-			],
-		});
+		const needResources =
+			isInteractive ||
+			(databaseOption && databaseOption !== 'skip' && databaseOption !== 'new') ||
+			(storageOption && storageOption !== 'skip' && storageOption !== 'new');
+
+		if (needResources) {
+			resources = await tui.spinner({
+				message: 'Fetching resources',
+				clearOnSuccess: true,
+				callback: async () => {
+					return listResources(catalystClient!, orgId!, region!);
+				},
+			});
+			// Log sanitized summary (avoid exposing DATABASE_URL, tokens, secrets)
+			logger.debug(
+				`Resources for org ${orgId} in region ${region}: ${resources.db.length} databases, ${resources.s3.length} storage buckets`
+			);
+			logger.debug(
+				`Database names: ${resources.db.map((d) => d.name).join(', ') || '(none)'}`
+			);
+			logger.debug(
+				`Storage buckets: ${resources.s3.map((b) => b.bucket_name).join(', ') || '(none)'}`
+			);
+		}
+
+		// Determine database action: CLI flag > interactive prompt > skip (headless)
+		let db_action: string;
+		if (databaseOption !== undefined) {
+			// CLI flag provided - normalize to expected values
+			if (databaseOption.toLowerCase() === 'new') {
+				db_action = 'Create New';
+			} else if (databaseOption.toLowerCase() === 'skip') {
+				db_action = 'Skip';
+			} else {
+				// Existing database name - validate it exists
+				const existingDb = resources?.db.find((d) => d.name === databaseOption);
+				if (!existingDb) {
+					logger.fatal(
+						`Database '${databaseOption}' not found. Use 'new' to create a new database or 'skip' to skip.`,
+						ErrorCode.RESOURCE_NOT_FOUND
+					);
+				}
+				db_action = databaseOption;
+			}
+		} else if (isInteractive) {
+			db_action = await prompt.select({
+				message: 'Create SQL Database?',
+				options: [
+					{ value: 'Skip', label: 'Skip or Setup later' },
+					{ value: 'Create New', label: 'Create a new database' },
+					...resources!.db.map((db) => ({
+						value: db.name,
+						label: `Use database: ${tui.tuiColors.primary(db.name)}`,
+					})),
+				],
+			});
+		} else {
+			// Headless without flag - skip
+			db_action = 'Skip';
+		}
 
-		if (!domains?.length) {
+		// Determine storage action: CLI flag > interactive prompt > skip (headless)
+		let s3_action: string;
+		if (storageOption !== undefined) {
+			// CLI flag provided - normalize to expected values
+			if (storageOption.toLowerCase() === 'new') {
+				s3_action = 'Create New';
+			} else if (storageOption.toLowerCase() === 'skip') {
+				s3_action = 'Skip';
+			} else {
+				// Existing bucket name - validate it exists
+				const existingBucket = resources?.s3.find((b) => b.bucket_name === storageOption);
+				if (!existingBucket) {
+					logger.fatal(
+						`Storage bucket '${storageOption}' not found. Use 'new' to create a new bucket or 'skip' to skip.`,
+						ErrorCode.RESOURCE_NOT_FOUND
+					);
+				}
+				s3_action = storageOption;
+			}
+		} else if (isInteractive) {
+			s3_action = await prompt.select({
+				message: 'Create Storage Bucket?',
+				options: [
+					{ value: 'Skip', label: 'Skip or Setup later' },
+					{ value: 'Create New', label: 'Create a new bucket' },
+					...resources!.s3.map((bucket) => ({
+						value: bucket.bucket_name,
+						label: `Use bucket: ${tui.tuiColors.primary(bucket.bucket_name)}`,
+					})),
+				],
+			});
+		} else {
+			// Headless without flag - skip
+			s3_action = 'Skip';
+		}
+
+		// Custom DNS: only prompt in interactive mode if not already provided
+		if (!domains?.length && isInteractive) {
 			const customDns = await prompt.text({
 				message: 'Setup custom DNS?',
 				hint: 'Enter a domain name or press Enter to skip',
@@ -335,14 +434,14 @@ export async function runCreateFlow(options: CreateFlowOptions): Promise<CreateF
 			}
 		}
 
-		const choices = { db_action, s3_action };
-		switch (choices.s3_action) {
+		// Process storage action
+		switch (s3_action) {
 			case 'Create New': {
 				const created = await tui.spinner({
 					message: 'Provisioning New Bucket',
 					clearOnSuccess: true,
 					callback: async () => {
-						return createResources(catalystClient, orgId, region!, [{ type: 's3' }]);
+						return createResources(catalystClient!, orgId!, region!, [{ type: 's3' }]);
 					},
 				});
 				// Collect env vars from newly created resource
@@ -356,39 +455,49 @@ export async function runCreateFlow(options: CreateFlowOptions): Promise<CreateF
 			}
 			default: {
 				// User selected an existing bucket - get env vars from the resources list
-				const selectedBucket = resources.s3.find((b) => b.bucket_name === choices.s3_action);
+				const selectedBucket = resources?.s3.find((b) => b.bucket_name === s3_action);
 				if (selectedBucket?.env) {
 					Object.assign(resourceEnvVars, selectedBucket.env);
 				}
 				break;
 			}
 		}
-		switch (choices.db_action) {
+
+		// Process database action
+		switch (db_action) {
 			case 'Create New': {
-				const dbNameInput = await prompt.text({
-					message: 'Database name',
-					hint: 'Optional - lowercase letters, digits, underscores only',
-					validate: (value: string) => {
-						const trimmed = value.trim();
-						if (trimmed === '') return true;
-						const result = validateDatabaseName(trimmed);
-						return result.valid ? true : result.error!;
-					},
-				});
-				const dbName = dbNameInput.trim() || undefined;
-				const dbDescription = await prompt.text({
-					message: 'Database description',
-					hint: 'Optional - press Enter to skip',
-				});
+				let dbName: string | undefined;
+				let dbDescription: string | undefined;
+
+				// Only prompt for name/description in interactive mode
+				if (isInteractive) {
+					const dbNameInput = await prompt.text({
+						message: 'Database name',
+						hint: 'Optional - lowercase letters, digits, underscores only',
+						validate: (value: string) => {
+							const trimmed = value.trim();
+							if (trimmed === '') return true;
+							const result = validateDatabaseName(trimmed);
+							return result.valid ? true : result.error!;
+						},
+					});
+					dbName = dbNameInput.trim() || undefined;
+					dbDescription =
+						(await prompt.text({
+							message: 'Database description',
+							hint: 'Optional - press Enter to skip',
+						})) || undefined;
+				}
+
 				const created = await tui.spinner({
 					message: 'Provisioning New SQL Database',
 					clearOnSuccess: true,
 					callback: async () => {
-						return createResources(catalystClient, orgId, region!, [
+						return createResources(catalystClient!, orgId!, region!, [
 							{
 								type: 'db',
 								name: dbName,
-								description: dbDescription || undefined,
+								description: dbDescription,
 							},
 						]);
 					},
@@ -404,7 +513,7 @@ export async function runCreateFlow(options: CreateFlowOptions): Promise<CreateF
 			}
 			default: {
 				// User selected an existing database - get env vars from the resources list
-				const selectedDb = resources.db.find((d) => d.name === choices.db_action);
+				const selectedDb = resources?.db.find((d) => d.name === db_action);
 				if (selectedDb?.env) {
 					Object.assign(resourceEnvVars, selectedDb.env);
 				}
@@ -413,15 +522,19 @@ export async function runCreateFlow(options: CreateFlowOptions): Promise<CreateF
 		}
 	}
 
-	// Auth setup - either from template or user choice
+	// Auth setup - either from template, CLI flag, or user choice
 	const templateHasAuth = selectedTemplate.id === 'agentuity-auth';
 
 	let authEnabled = templateHasAuth; // Auth templates have auth enabled by default
 	let authDatabaseName: string | undefined;
 	let authDatabaseUrl: string | undefined;
 
-	// For non-auth templates, ask if they want to enable auth
-	if (auth && catalystClient && orgId && region && !skipPrompts && !templateHasAuth) {
+	// Handle auth enablement: CLI flag > interactive prompt > disabled (headless)
+	if (enableAuthOption !== undefined) {
+		// CLI flag provided
+		authEnabled = enableAuthOption;
+	} else if (canProvision && isInteractive && !templateHasAuth) {
+		// For non-auth templates in interactive mode, ask if they want to enable auth
 		const enableAuth = await prompt.select({
 			message: 'Enable Agentuity Authentication?',
 			options: [
@@ -434,9 +547,10 @@ export async function runCreateFlow(options: CreateFlowOptions): Promise<CreateF
 			authEnabled = true;
 		}
 	}
+	// In headless mode without --enable-auth flag, authEnabled stays false (unless template has auth)
 
 	// Set up database and secret for any auth-enabled project
-	if (authEnabled && auth && catalystClient && orgId && region && !skipPrompts) {
+	if (authEnabled && canProvision) {
 		// If a database was already selected/created above, use it for auth
 		if (resourceEnvVars.DATABASE_URL) {
 			authDatabaseUrl = resourceEnvVars.DATABASE_URL;
@@ -457,7 +571,7 @@ export async function runCreateFlow(options: CreateFlowOptions): Promise<CreateF
 				message: 'Provisioning database for auth',
 				clearOnSuccess: true,
 				callback: async () => {
-					return createResources(catalystClient, orgId, region!, [{ type: 'db' }]);
+					return createResources(catalystClient!, orgId!, region!, [{ type: 'db' }]);
 				},
 			});
 			authDatabaseName = created[0].name;
@@ -607,7 +721,7 @@ export async function runCreateFlow(options: CreateFlowOptions): Promise<CreateF
 	await initGitRepo(dest);
 
 	// Show completion message
-	if (!skipPrompts) {
+	if (isInteractive) {
 		if (setupResult.success) {
 			tui.success('✨ Project created successfully!\n');
 		} else {
@@ -641,7 +755,7 @@ export async function runCreateFlow(options: CreateFlowOptions): Promise<CreateF
 
 	playSound();
 
-	if (process.stdin.isTTY && !skipPrompts && _domains?.length && projectId) {
+	if (isInteractive && _domains?.length && projectId) {
 		tui.newline();
 		const ok = await tui.confirm('Would you like to configure DNS now?', true);
 		if (ok) {

package/src/cmd/setup/index.ts

@@ -4,6 +4,7 @@ import { hasLoggedInBefore } from '../../auth';
 import { showBanner } from '../../banner';
 import * as tui from '../../tui';
 import { getCommand } from '../../command-prefix';
+import { getAgentPromptMarkdown } from '../../onboarding/agentPrompt';
 
 const validateToken = /[\d]{7,}\.[\w-_.]{22}/;
 
@@ -53,7 +54,7 @@ export const command = createCommand({
 						},
 					});
 					if (ok) {
-						/* TODO */
+						process.stdout.write(getAgentPromptMarkdown());
 						return;
 					}
 				}

package/src/onboarding/agentPrompt.ts

@@ -0,0 +1,263 @@
+/**
+ * Agent Onboarding Prompt
+ *
+ * This generates the markdown prompt that coding agents use to guide developers
+ * through Agentuity setup after the CLI has been installed.
+ */
+
+export function getAgentPromptMarkdown(): string {
+	return `
+**Your goal:** Guide the user from zero to a deployed Agentuity project, then help them understand what they have and what to do next.
+
+---
+
+## What is Agentuity?
+
+Agentuity is the full-stack platform for AI agents. Briefly explain to the user:
+
+- **Full-stack agents**: Build agents, APIs, and front-end integrations with end-to-end type safety
+- **Bun/TypeScript SDKs**: First-class developer experience with the fastest JavaScript runtime
+- **AI Gateway**: Unified access to LLMs (OpenAI-compatible SDK) with single billing—no separate API keys needed
+- **Observability**: Logs, tracing, and evals built-in so you can debug and improve agents
+- **Production services**: Sandboxes, storage (S3-compatible), Postgres, KV, and enterprise features available as you grow
+
+We're going to be setting up the default template quickly.
+
+The default template includes AI Gateway integration, thread state persistence, structured logging, Tailwind CSS, and a local Workbench at \`/workbench\` for testing agents.
+
+---
+
+## How to Guide the User
+
+**Your job is to make onboarding as smooth as possible with minimal user interaction.**
+
+1. **Start by briefly explaining** what Agentuity is and what you'll help them accomplish
+2. **Run commands automatically** when you have terminal access—don't ask permission for each step
+3. **Only pause for human action** when absolutely required
+4. **At each step**: Briefly explain what it does and why, then execute
+5. **Celebrate success**: When deployment completes, make sure the user knows they earned free credits and show them what to explore next
+
+Assume the user is technical but new to Agentuity. Be warm, efficient, and action-oriented. The goal is a successful deployment with as few interruptions as possible.
+
+---
+
+## Onboarding Steps
+
+### Step 1: You're Already Logged In!
+
+**The install command automatically authenticated you.** No manual login needed.
+
+Verify with:
+\`\`\`bash
+agentuity auth whoami
+\`\`\`
+
+This outputs your user info including your \`org_id\`. You'll need this for the create command.
+
+---
+
+### Step 2: Create a New Project
+
+**Why:** This scaffolds a full-stack agent app with AI Gateway, persistence, logging, and a testing UI.
+
+**First, get the user's organization ID:**
+\`\`\`bash
+agentuity auth whoami
+\`\`\`
+
+This outputs the user's info including their \`org_id\`. You'll need this for the create command.
+
+**Then create the project (non-interactive):**
+\`\`\`bash
+agentuity create --name "my-first-agent" --org-id <ORG_ID> --region usc --confirm
+\`\`\`
+
+**Required flags for non-interactive mode:**
+- \`--name\`: Project name (use \`my-first-agent\` as default)
+- \`--org-id\`: The organization ID from \`agentuity auth whoami\` (required in non-interactive mode)
+- \`--region\`: Cloud region (use \`usc\` for US Central, or \`use\` for US East)
+- \`--confirm\`: Skips interactive prompts
+
+**Example with real org ID:**
+\`\`\`bash
+agentuity create --name "my-first-agent" --org-id ..... --region usc --confirm
+\`\`\`
+
+If the user wants a different location, add \`--dir\`:
+\`\`\`bash
+agentuity create --name "my-first-agent" --org-id <ORG_ID> --region usc --dir ~/projects/my-first-agent --confirm
+\`\`\`
+
+After creation, \`cd\` into the project directory.
+
+**Docs:** https://agentuity.dev/Get-Started/quickstart
+
+---
+
+### Step 3: Run Locally
+
+**Why:** Start the development server to test the project locally before deploying.
+
+**Command:**
+\`\`\`bash
+agentuity dev
+\`\`\`
+
+**⚠️ This is a long-running process!** The dev server runs continuously until killed. Before or after starting it, **immediately tell the user what to do** — don't just wait silently.
+
+**What happens:**
+- **Local server** starts at \`http://localhost:3500\` — this is where your APIs and agents are served
+- **Workbench** available at \`http://localhost:3500/workbench\` — a built-in UI for testing and interacting with your agents directly, without needing a frontend
+- **Public tunnel URL** is automatically created — the CLI will display a public URL that tunnels to your local server, useful for testing webhooks or sharing with others
+- **Hot reload** enabled — code changes reflect immediately
+
+**Immediately after starting the dev server, tell the user:**
+
+> "The dev server is now running! Here's what to try:
+>
+> 1. Open **http://localhost:3500** to see the app
+> 2. Open **http://localhost:3500/workbench** to interact with your agents (this is a key feature!)
+> 3. The public tunnel URL shown in the terminal can be shared with others
+>
+> Take a few minutes to explore. When you're ready to deploy to production, let me know!"
+
+**Wait for the user to confirm** they're ready to deploy before proceeding to Step 4.
+
+**Keyboard shortcuts** while dev server runs: \`h\` for help, \`r\` to restart, \`q\` to quit.
+
+**Docs:** https://agentuity.dev/Reference/CLI/development
+
+---
+
+### Step 4: Deploy to Production
+
+**Why:** Make the project live with observability, logs, and analytics.
+
+**Important:** Deploying their first project earns the user **free credits** to continue experimenting with the platform. Make sure they know this is a reward for completing onboarding!
+
+**First, stop the dev server:**
+Before deploying, you must stop the dev server that's still running from Step 3. Send \`Ctrl+C\` or \`q\` to the terminal running \`agentuity dev\` to gracefully shut it down. Don't leave it running or you'll have an orphaned process on port 3500.
+
+**Then deploy:**
+\`\`\`bash
+agentuity deploy
+\`\`\`
+
+**What happens:**
+- Project builds and deploys to Agentuity's global edge network
+- The CLI will output the production URL when deployment succeeds
+- Observability (logs, tracing, analytics) is now live
+- **Free credits are awarded** for their first deployment
+
+**⚠️ CRITICAL: Do not hallucinate URLs!**
+- **Only show the user URLs that the CLI actually outputs**
+- Do not make up or guess production URLs (e.g., don't invent \`https://project-name.agentuity.app\`)
+- If the deploy command fails or doesn't show a URL, tell the user to check the dashboard instead
+- If there's an error, report the actual error message from the CLI
+
+**After successful deployment:**
+1. Show the user the **exact production URL from the CLI output**
+2. Direct them to the Agentuity dashboard at https://app.agentuity.com to:
+   - View their deployed project
+   - Explore logs and traces
+   - See their credit balance
+   - Monitor analytics
+
+**If deployment fails or shows errors:**
+- Report the actual error message
+- Don't claim success if the CLI didn't confirm it
+- Suggest checking the dashboard for deployment status
+
+---
+
+## What the Template Provides
+
+After deployment, explain what they now have:
+
+| Feature | What It Does |
+|---------|--------------|
+| **AI Gateway** | OpenAI-compatible SDK routed through Agentuity—unified billing, no separate API keys |
+| **Thread State** | Conversations and agent state persist automatically for multi-turn flows |
+| **Structured Logging** | Logs and traces captured for debugging and analytics |
+| **Workbench** | Local UI at \`/workbench\` for testing agents without a frontend |
+| **Tailwind CSS** | Pre-configured styling for the frontend |
+| **Type Safety** | End-to-end types from agent schemas to API routes to frontend |
+
+---
+
+## Next Steps
+
+After successful deployment, guide the user through these recommendations:
+
+### 1. Celebrate the Free Credits!
+- Remind the user: their first deployment earned them **free credits** to keep experimenting
+- They can view their credit balance in the Agentuity dashboard
+- These credits let them continue building and testing without upfront cost
+
+### 2. Join the Community
+- **Discord**: https://discord.gg/agentuity
+- Get help, see examples, share what you're building
+
+### 3. Explore the Dashboard
+- **Observability**: View logs, traces, and evals for your deployment
+- **Deployments**: See version history with rollback options
+- **Analytics**: Monitor usage and performance
+
+### 4. Connect GitHub
+- Enable GitHub integration in project settings for:
+  - Automatic deployments from branches
+  - CI/CD workflows
+  - Team collaboration
+
+### 5. Explore Additional Services
+As your project grows, Agentuity provides:
+- **Postgres**: Relational database
+- **KV**: Fast key-value storage
+- **Storage**: S3-compatible file storage
+- **Sandboxes**: Isolated execution environments
+
+### 6. Customize Your Agents
+The SDK makes it easy to:
+- Add new agents in \`src/agent/\` (just add a folder with \`agent.ts\`)
+- Create API routes in \`src/api/\`
+- Build type-safe frontend integrations
+
+**Docs:** https://agentuity.dev/Get-Started/project-structure
+
+---
+
+## Handling Common Issues
+
+- **Bun not installed**: The CLI will prompt to install it, or run: \`curl -fsSL https://bun.sh/install | bash\`
+- **Login fails/times out**: Rerun \`agentuity login\` and check browser
+- **Port 3500 in use**: Kill the existing process or use \`agentuity dev --port 8080\`
+- **Deploy fails**: Check build errors in CLI output, ensure you're in the project directory
+
+---
+
+## Success Criteria
+
+**Onboarding is successful when the user has:**
+
+1. ✅ **CLI installed** and authenticated
+2. ✅ **Local dev environment running** — they've seen \`localhost:3500\` and tried the Workbench
+3. ✅ **First deployment complete** — they have a live production URL
+4. ✅ **Free credits earned** — they know they've been rewarded and can keep building
+5. ✅ **Clear next steps** — they know about Discord, the dashboard, and how to extend their project
+
+**Make them feel accomplished!** They just went from zero to a deployed AI agent platform in minutes.
+
+---
+
+## Style Guidelines
+
+- Keep explanations short and practical
+- Explain what & why at each step
+- Give exact commands
+- Handle errors calmly with concrete suggestions
+- Be explicit when human action is required
+- Use non-interactive CLI flags (\`--confirm\`, \`--name\`, \`--org-id\`, \`--region usc\`, \`--dir\`) for smooth automation
+- **Never hallucinate or make up information** — only report URLs, IDs, and status from actual CLI output
+- If something fails or you're unsure, say so honestly and direct the user to the dashboard
+`;
+}

package/src/schema-generator.ts

@@ -13,7 +13,7 @@ export interface SchemaArgument {
 
 export interface SchemaOption {
 	name: string;
-	type: 'string' | 'number' | 'boolean' | 'array';
+	type: 'string' | 'number' | 'boolean' | 'array' | 'optionalString';
 	required: boolean;
 	default?: unknown;
 	description?: string;