Harden generated-agent scaffolding and onboarding for AI-assisted development.

Require explicit Arcade gateway configuration with actionable setup guidance, add doctor preflight checks, and improve template/docs ergonomics for Cursor/Claude Code/Codex customization workflows.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: teallarson

.github/workflows/ci.yml

@@ -131,6 +131,16 @@ jobs:
         working-directory: ci-test-${{ matrix.template }}
         run: cp .env.example .env
 
+      - name: Doctor (TypeScript templates)
+        if: matrix.template != 'langchain'
+        working-directory: ci-test-${{ matrix.template }}
+        run: npm run doctor
+
+      - name: Doctor (Python template)
+        if: matrix.template == 'langchain'
+        working-directory: ci-test-${{ matrix.template }}
+        run: python -m app.doctor
+
       - name: Type check (TypeScript templates)
         if: matrix.template != 'langchain'
         working-directory: ci-test-${{ matrix.template }}

.gitignore

@@ -5,3 +5,4 @@ dist/
 .env.local
 .next/
 __pycache__/
+.tmp

AGENTS.md

@@ -0,0 +1,33 @@
+# AGENTS.md
+
+Guidance for AI coding agents working in this repository.
+
+## Repo Purpose
+
+`create-arcade-agent` scaffolds starter projects that teach Arcade MCP Gateway concepts and produce working, customizable agent apps.
+
+## High-Signal Workflow
+
+1. Edit source templates in `templates/**` and CLI logic in `src/**`.
+2. Run quality checks:
+   - `npm run lint`
+   - `npm run format:check`
+   - `npm run typecheck`
+   - `npm run build`
+3. Validate scaffolding behavior via CI-equivalent smoke flow:
+   - `node dist/index.js <name> --template <ai-sdk|mastra|langchain>`
+
+## Editing Rules
+
+- Keep generated templates simple and beginner-friendly.
+- Prefer MCP Gateway patterns over direct SDK-specific concepts.
+- Preserve/extend `CUSTOMIZATION POINT` and `AI-EDIT-SAFE` markers.
+- Avoid introducing framework-specific complexity unless required.
+- Keep OAuth/security guidance aligned with Arcade docs (custom verifier for production user-facing apps).
+
+## Important Locations
+
+- `src/` — generator runtime logic
+- `templates/_shared/` — shared assets injected into generated projects
+- `templates/ai-sdk/`, `templates/mastra/`, `templates/langchain/` — template-specific code
+- `.github/workflows/ci.yml` — source of truth for validation gates

README.md

@@ -21,6 +21,18 @@ The generated agent is a daily planning and triage assistant that connects to Sl
 
 All three templates connect to Arcade's MCP Gateway for tool discovery and execution. The TypeScript templates (`ai-sdk` and `mastra`) share a common Next.js frontend. The Python template (`langchain`) uses server-rendered HTML with SSE streaming.
 
+## What Is an MCP Gateway?
+
+An MCP Gateway is a managed tool endpoint in Arcade that your agent connects to via one URL.
+
+Benefits:
+
+- **One connection point** -- use one `ARCADE_GATEWAY_URL` instead of wiring many tool servers
+- **Tool curation** -- choose exactly which tools your agent can see
+- **Faster iteration** -- update tool access in Arcade without changing integration code
+- **Cleaner model context** -- smaller, focused toolsets improve tool selection reliability
+- **Portable setup** -- same gateway pattern works across frameworks and MCP clients
+
 ## Usage
 
 ### Interactive mode
@@ -164,6 +176,15 @@ The default port is `8765` for the langchain template and `3000` for the Next.js
 
 Make sure you are running Node.js >= 18. Check with `node --version`.
 
+### `ARCADE_GATEWAY_URL` is missing
+
+If the app says `ARCADE_GATEWAY_URL is missing`:
+
+1. Create a gateway at [app.arcade.dev/mcp-gateways](https://app.arcade.dev/mcp-gateways)
+2. Add these toolkits: Slack, Google Calendar, Linear, GitHub, Gmail
+3. Copy the gateway URL into `.env` as `ARCADE_GATEWAY_URL`
+4. Retry connection in the app
+
 ### Python virtual environment issues
 
 The CLI creates a `.venv` directory automatically. If it fails:

src/prompts.ts

@@ -1,11 +1,26 @@
 import * as p from "@clack/prompts";
 import { existsSync, readdirSync, readFileSync } from "fs";
 import { resolve, join } from "path";
+import { parseArgs } from "util";
 import type { TemplateMeta } from "./types.js";
 
+function parseCli(argv: string[]): { projectName?: string; template?: string } {
+  const parsed = parseArgs({
+    args: argv.slice(2),
+    options: {
+      template: { type: "string" },
+    },
+    allowPositionals: true,
+    strict: false,
+  });
+
+  const projectName = parsed.positionals.find((arg) => !arg.startsWith("-"));
+  const template = typeof parsed.values.template === "string" ? parsed.values.template : undefined;
+  return { projectName, template };
+}
+
 export async function getProjectName(argv: string[]): Promise<string> {
-  let projectName = argv[2];
-  if (projectName === "--template") projectName = "";
+  let projectName = parseCli(argv).projectName ?? "";
   if (!projectName) {
     const result = await p.text({
       message: "What is your project name?",
@@ -23,7 +38,7 @@ export async function getProjectName(argv: string[]): Promise<string> {
     }
     projectName = result;
   }
-  return projectName;
+  return projectName.trim();
 }
 
 function discoverTemplates(templatesDir: string): { meta: TemplateMeta; dir: string }[] {
@@ -52,10 +67,9 @@ export async function getTemplate(
     process.exit(1);
   }
 
-  // Check --template flag
-  const flagIdx = argv.indexOf("--template");
-  if (flagIdx !== -1 && argv[flagIdx + 1]) {
-    const val = argv[flagIdx + 1];
+  const cliTemplate = parseCli(argv).template;
+  if (cliTemplate) {
+    const val = cliTemplate;
     const match = templates.find((t) => t.meta.name === val);
     if (!match) {
       const names = templates.map((t) => `"${t.meta.name}"`).join(", ");

templates/_shared/agent-playbook.md.hbs

@@ -0,0 +1,56 @@
+# Agent Playbook
+
+This project is intentionally structured so coding agents can safely customize it.
+
+## Safe Edit Zones
+
+Look for these markers:
+
+- `CUSTOMIZATION POINT` — expected user customization area
+- `AI-EDIT-SAFE` — safe for automated edits
+- `AI-EDIT-CAUTION` — integration-sensitive; edit carefully
+
+## First Customization Steps
+
+{{#if (eq name "langchain")}}
+1. Edit `app/system-prompt.md` to change agent behavior.
+2. Change model choice in `app/agent.py`.
+3. Extend schema in `app/models.py` if you need app-specific data.
+4. Ensure `ARCADE_GATEWAY_URL` is set and the gateway has the expected tools.
+{{else if (eq name "mastra")}}
+1. Edit `src/mastra/agents/system-prompt.md` to change agent behavior.
+2. Change model choice in `src/mastra/agents/triage-agent.ts`.
+3. Extend schema in `lib/db/schema.ts` if you need app-specific data.
+4. Ensure `ARCADE_GATEWAY_URL` is set and the gateway has the expected tools.
+{{else}}
+1. Edit `lib/system-prompt.md` to change agent behavior.
+2. Change model choice in `lib/agent.ts`.
+3. Extend schema in `lib/db/schema.ts` if you need app-specific data.
+4. Ensure `ARCADE_GATEWAY_URL` is set and the gateway has the expected tools.
+{{/if}}
+
+## Gateway Checklist
+
+Create/configure your gateway at `https://app.arcade.dev/mcp-gateways` and add:
+
+- Slack
+- Google Calendar
+- Linear
+- GitHub
+- Gmail
+
+## Verification Commands
+
+{{#if (eq name "langchain")}}
+```bash
+python -m app.doctor
+ruff check app/
+ty check .
+```
+{{else}}
+```bash
+npm run doctor
+npm run typecheck
+npm run lint
+```
+{{/if}}

templates/_shared/nextjs-ui/app/api/auth/login/route.ts

@@ -4,18 +4,28 @@ import { db } from "@/lib/db";
 import { users } from "@/lib/db/schema";
 import { verifyPassword, createSession } from "@/lib/auth";
 
+const EMAIL_REGEX = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+
 export async function POST(request: Request) {
-  let body;
+  let body: unknown;
   try {
     body = await request.json();
   } catch {
     return NextResponse.json({ error: "Invalid request body" }, { status: 400 });
   }
-  const { email, password } = body;
+  const email = typeof (body as { email?: unknown }).email === "string"
+    ? (body as { email: string }).email.trim().toLowerCase()
+    : "";
+  const password = typeof (body as { password?: unknown }).password === "string"
+    ? (body as { password: string }).password
+    : "";
 
   if (!email || !password) {
     return NextResponse.json({ error: "Email and password are required" }, { status: 400 });
   }
+  if (!EMAIL_REGEX.test(email)) {
+    return NextResponse.json({ error: "Invalid email address" }, { status: 400 });
+  }
 
   const user = await db.query.users.findFirst({
     where: eq(users.email, email),

templates/_shared/nextjs-ui/app/api/auth/register/route.ts

@@ -4,18 +4,31 @@ import { db } from "@/lib/db";
 import { users } from "@/lib/db/schema";
 import { hashPassword, createSession } from "@/lib/auth";
 
+const EMAIL_REGEX = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+
 export async function POST(request: Request) {
-  let body;
+  let body: unknown;
   try {
     body = await request.json();
   } catch {
     return NextResponse.json({ error: "Invalid request body" }, { status: 400 });
   }
-  const { email, password } = body;
+  const email = typeof (body as { email?: unknown }).email === "string"
+    ? (body as { email: string }).email.trim().toLowerCase()
+    : "";
+  const password = typeof (body as { password?: unknown }).password === "string"
+    ? (body as { password: string }).password
+    : "";
 
   if (!email || !password) {
     return NextResponse.json({ error: "Email and password are required" }, { status: 400 });
   }
+  if (!EMAIL_REGEX.test(email)) {
+    return NextResponse.json({ error: "Invalid email address" }, { status: 400 });
+  }
+  if (password.length < 8) {
+    return NextResponse.json({ error: "Password must be at least 8 characters" }, { status: 400 });
+  }
 
   const existing = await db.query.users.findFirst({
     where: eq(users.email, email),

templates/_shared/nextjs-ui/app/dashboard/page.tsx

@@ -127,6 +127,8 @@ function DashboardContent() {
       const messages: Record<string, string> = {
         auth_incomplete: "Authorization was not completed. Please try connecting again.",
         auth_failed: "Authorization failed. Please try again.",
+        gateway_missing:
+          "ARCADE_GATEWAY_URL is missing. Create one at https://app.arcade.dev/mcp-gateways, add Slack, Google Calendar, Linear, GitHub, and Gmail, then set ARCADE_GATEWAY_URL in .env.",
         verify_failed: "User verification failed. Please try again.",
       };
       setError(messages[urlError] || `Authentication error: ${urlError}`);

templates/_shared/nextjs-ui/lib/db/schema.ts

@@ -1,5 +1,6 @@
 import { sqliteTable, text, integer } from "drizzle-orm/sqlite-core";
 
+// AI-EDIT-SAFE: application schema extension
 // --- CUSTOMIZATION POINT ---
 // Add more tables here for your domain.
 // See: https://orm.drizzle.team/docs/column-types/sqlite