spfn 0.2.0-beta.61 → 0.2.0-beta.63

package/README.md

@@ -1,8 +1,9 @@
 # spfn — the SPFN CLI (backend layer for Next.js)
 
-`spfn` scaffolds and runs a Hono-based backend that lives inside a Next.js project.
-It creates the server structure, runs the dev/build/start lifecycle, manages the
-database (Drizzle Kit), generates the RPC route map, and validates environment variables.
+`spfn` takes a Next.js idea from prototype to production with a consistent full-stack
+architecture. It can scaffold either a core-only backend or a production baseline with
+authentication, internationalization, and an agent-facing MCP endpoint, then runs the
+dev/build/start lifecycle, database tooling, RPC codegen, and environment validation.
 
 > Beta: install with the `@beta` tag (`spfn@beta`). The binary is `spfn`.
 
@@ -18,20 +19,25 @@ pnpm dlx spfn@beta <command>
 Or add it as a project dependency (`spfn init`/`spfn create` do this for you), then
 call it via `pnpm spfn <command>` / `npm run spfn:<script>`.
 
-Requirements: Node.js 18.18+, Next.js 15+ (App Router, `src/` dir), PostgreSQL (Redis optional).
+Requirements: Node.js 18.18+ for bare mode, Node.js 20+ for full mode's MCP server,
+Next.js 15+ (App Router, `src/` dir), PostgreSQL (Redis optional).
 
 ## Usage
 
 ```bash
-# New project (runs create-next-app + spfn init)
-npx spfn@beta create my-app
+# Prototype-to-Production baseline: core + auth + i18n + MCP
+npx spfn@beta create my-app --mode full
 cd my-app
 docker compose up -d            # Postgres + Redis
-# .env.local & .env.server are generated — put server secrets in .env.server
+# .env.local & .env.server are generated — keep both gitignored
+pnpm spfn db migrate            # Apply auth migrations
 pnpm spfn:dev                   # Next.js :3790 + SPFN API :8790
 
+# Core-only full-stack skeleton
+npx spfn@beta create my-api --mode bare
+
 # Add SPFN to an existing Next.js project
-npx spfn@beta init
+npx spfn@beta init --mode full
 ```
 
 The package manager is auto-detected (pnpm > yarn > bun > npm) from lockfiles; override
@@ -49,24 +55,32 @@ Registered top-level commands: `create`, `init`, `add`, `dev`, `build`, `start`,
 Runs `create-next-app` with SPFN-recommended flags (TypeScript, App Router, `src/`,
 Tailwind, import alias `@/*`, no ESLint), sets up SVGR icons, then runs `init`.
 
+Choose `full` for the recommended Prototype-to-Production baseline or `bare` for the
+historical core-only skeleton. Without `--mode`, interactive runs show a mode selector
+with `full` recommended. For backward compatibility, non-interactive `--yes` runs without
+an explicit mode continue to generate `bare`; automation that wants full should always
+pass `--mode full`.
+
 | Option | Description |
 |--------|-------------|
 | `--pm <manager>` | Force package manager: `npm` \| `pnpm` \| `yarn` \| `bun` |
 | `--shadcn` | Also run `shadcn init` |
+| `--mode <mode>` | `bare` (core only) \| `full` (core, auth, i18n, MCP) |
 | `--skip-install` | Skip dependency install |
 | `--skip-git` | Skip `git init` |
 | `-y, --yes` | Skip prompts, use defaults |
 
 ### `spfn init`
 
-Adds SPFN to an existing Next.js project: copies the server templates, wires the RPC
+Adds SPFN to an existing Next.js project: copies the selected server templates, wires the RPC
 proxy route, Docker files, deploy + codegen config, updates `package.json` scripts/deps,
-and installs. With auth enabled it also adds the `/_auth/:path*` → SPFN API rewrite to
+and installs. Full mode also adds the `/_auth/:path*` → SPFN API rewrite to
 `next.config` (OAuth callbacks return to the app origin; merged manually if a `rewrites()`
 already exists). See [Scaffold structure](#scaffold-structure) for what lands on disk.
 
 | Option | Description |
 |--------|-------------|
+| `--mode <mode>` | `bare` (core only) \| `full` (core, auth, i18n, MCP) |
 | `-y, --yes` | Skip prompts, use defaults |
 
 Generated projects pin `drizzle-orm` and `drizzle-kit` to `1.0.0-rc.4`, matching
@@ -280,7 +294,7 @@ Install and configure SVGR for SVG-as-component imports (Next.js only).
 
 ## Scaffold structure
 
-`spfn init` (and `create`, which calls it) produces:
+Both modes produce the core full-stack skeleton:
 
 ```
 src/
@@ -303,13 +317,37 @@ docker-compose.production.yml
 Dockerfile, .dockerignore
 next.config.ts                       # patched when auth is enabled: /_auth/:path* rewrite → SPFN API
 .env.example                         # committed reference — every key, placeholder values
-.env.local                           # generated, gitignored (Next.js-facing URLs)
+.env.local                           # generated, gitignored (values loaded by Next.js)
 .env.server                          # generated, gitignored (server secrets: DB, cache)
 ```
 
+Full mode overlays the Prototype-to-Production baseline:
+
+```
+src/
+  app/login/page.tsx                 # provider login starter UI
+  app/auth/callback/page.tsx         # OAuth session handoff
+  i18n/catalogs.ts                   # application-owned en/ko starter messages
+  i18n/server.ts                     # configured server-side i18n registry
+  server/mcp.ts                      # authenticated /mcp endpoint + starter app_status tool
+  server/router.ts                   # authRouter + mcpRouter + global authenticate
+  server/server.config.ts            # createAuthLifecycle + i18n startup
+next.config.ts                       # /_auth/* callback rewrite
+.env.local                           # generated auth session secret (gitignored)
+.env.server                          # auth keyring + MCP operator key (gitignored)
+```
+
+The full RPC proxy imports the auth interceptor and merges `authRouteMap`. Internal auth
+and MCP keys are generated with cryptographic randomness in ignored local env files;
+`.env.example` contains placeholders only. Add only the provider keys you use, then run
+`pnpm spfn db migrate`. The starter MCP endpoint accepts `SPFN_MCP_API_KEY` as a Bearer
+token for first-party operation; replace that validator with OAuth before third-party access.
+
 `init` also patches `package.json` (scripts: `spfn:dev`, `spfn:server`, `spfn:next`,
 `spfn:build`, `spfn:start`, `codegen`; deps: `@spfn/core`, `spfn`, `drizzle-orm`,
-`@sinclair/typebox`, `concurrently`, etc.), excludes `src/server` from the root
+`@sinclair/typebox`, `concurrently`, etc.; full also adds `@spfn/auth`, `@spfn/i18n`,
+`@spfn/mcp`, auth's `@spfn/notification` peer, and a Node `>=20.0.0` engine when the
+existing range still permits older Node versions), excludes `src/server` from the root
 `tsconfig.json` (Vercel compat), and adds `.spfn/`, `.env.local`, `.env.server` to
 `.gitignore`.
 
@@ -387,8 +425,9 @@ type ships from `spfn` (`@type {import('spfn').SpfnConfig}`).
 
 ## Pitfalls
 
-- **`.env.server` is gitignored and server-only.** Put DB/secret values there, not in
-  `.env` (committed) and not in `.env.local` (that's Next.js's local file). There is no
+- **`.env.server` is gitignored and server-only.** Put backend-only DB/secret values there,
+  not in `.env` (committed). Full mode's session-cookie secret is the intentional exception:
+  it lives in gitignored `.env.local` because Next.js must encrypt the cookie. There is no
   `.env.server.local`. `spfn init` generates `.env.server`; put DB/secret values there.
   Load order is the standard dotenv chain ending with `.env.server`.
 - **Never commit secrets in `spfn.config.js`.** It's checked into Git; its `env` block is
@@ -406,6 +445,9 @@ type ships from `spfn` (`@type {import('spfn').SpfnConfig}`).
 - **Package manager is auto-detected from lockfiles.** If detection is wrong (e.g. mixed
   lockfiles), pass `--pm` to `create`. In a pnpm workspace, `create` installs from the
   workspace root, not the new project dir.
+- **Make scaffold mode explicit in automation.** Interactive runs recommend `full`, while
+  historical `--yes` calls without `--mode` remain `bare`. Pass `--mode full` or
+  `--mode bare` so scripts state their intended architecture.
 - **Regenerate the route map after route changes outside dev.** If
   `src/generated/route-map.ts` is missing or stale, run `spfn codegen run` — the RPC proxy
   depends on it.
@@ -416,5 +458,3 @@ type ships from `spfn` (`@type {import('spfn').SpfnConfig}`).
 
 - `@spfn/core` — server, route DSL, codegen, db, client runtime.
 - Project root README — framework overview and getting started.
-</content>
-</invoke>

package/dist/index.js

@@ -87,6 +87,44 @@ var init_messages = __esm({
   }
 });
 
+// src/commands/init/mode.ts
+import prompts from "prompts";
+async function selectScaffoldMode(options) {
+  if (options.mode) {
+    return options.mode;
+  }
+  if (options.yes) {
+    return "bare";
+  }
+  const { selectedMode } = await prompts({
+    type: "select",
+    name: "selectedMode",
+    message: "Which SPFN scaffold do you want?",
+    choices: [
+      {
+        title: "full (recommended)",
+        description: "Core, auth, i18n, and MCP \u2014 ready for Prototype to Production",
+        value: "full"
+      },
+      {
+        title: "bare",
+        description: "Core-only full-stack skeleton",
+        value: "bare"
+      }
+    ],
+    initial: 0
+  });
+  if (!selectedMode) {
+    process.exit(0);
+  }
+  return selectedMode;
+}
+var init_mode = __esm({
+  "src/commands/init/mode.ts"() {
+    "use strict";
+  }
+});
+
 // src/commands/setup.ts
 var setup_exports = {};
 __export(setup_exports, {
@@ -387,7 +425,7 @@ var init_setup = __esm({
 // src/commands/init/steps/validate.ts
 import { existsSync as existsSync3 } from "fs";
 import { join as join3 } from "path";
-import prompts from "prompts";
+import prompts2 from "prompts";
 async function validateProject(cwd, skipPrompts) {
   const packageJsonPath = join3(cwd, "package.json");
   if (!existsSync3(packageJsonPath)) {
@@ -401,7 +439,7 @@ async function validateProject(cwd, skipPrompts) {
   if (!hasNext) {
     logger.warn("Next.js not detected in dependencies.");
     if (!skipPrompts) {
-      const { proceed } = await prompts(
+      const { proceed } = await prompts2(
         {
           type: "confirm",
           name: "proceed",
@@ -418,7 +456,7 @@ async function validateProject(cwd, skipPrompts) {
   if (existsSync3(join3(cwd, "src", "server"))) {
     logger.warn("src/server directory already exists.");
     if (!skipPrompts) {
-      const { overwrite } = await prompts(
+      const { overwrite } = await prompts2(
         {
           type: "confirm",
           name: "overwrite",
@@ -432,19 +470,7 @@ async function validateProject(cwd, skipPrompts) {
       }
     }
   }
-  let includeAuth = false;
-  if (!skipPrompts) {
-    const { auth } = await prompts(
-      {
-        type: "confirm",
-        name: "auth",
-        message: "Include authentication (@spfn/auth)?",
-        initial: true
-      }
-    );
-    includeAuth = auth;
-  }
-  return { packageJson, packageJsonPath, includeAuth };
+  return { packageJson, packageJsonPath };
 }
 var init_validate = __esm({
   "src/commands/init/steps/validate.ts"() {
@@ -470,6 +496,10 @@ function findTemplatesPath() {
   if (existsSync4(devPath)) {
     return devPath;
   }
+  const sourcePath = join4(__dirname, "..", "..", "..", "..", "templates");
+  if (existsSync4(sourcePath)) {
+    return sourcePath;
+  }
   throw new Error("Templates directory not found. Please rebuild the package.");
 }
 var __dirname;
@@ -482,10 +512,10 @@ var init_templates = __esm({
 
 // src/commands/init/steps/server-structure.ts
 import { existsSync as existsSync5 } from "fs";
-import { join as join5 } from "path";
+import { join as join5, sep } from "path";
 import ora2 from "ora";
 import fse2 from "fs-extra";
-async function setupServerStructure(cwd) {
+async function setupServerStructure(cwd, mode) {
   const spinner = ora2("Setting up server structure...").start();
   try {
     const templatesDir = findTemplatesPath();
@@ -511,6 +541,27 @@ async function setupServerStructure(cwd) {
       copySync(envConfigTemplate, envConfigTarget);
       logger.success("Created src/server/config/env.config.ts (environment management)");
     }
+    if (mode === "full") {
+      const fullTemplateDir = join5(templatesDir, "modes", "full");
+      if (!existsSync5(fullTemplateDir)) {
+        throw new Error(`Full scaffold templates not found at: ${fullTemplateDir}`);
+      }
+      const fullAppTemplateDir = join5(fullTemplateDir, "src", "app");
+      const fullI18nTemplateDir = join5(fullTemplateDir, "src", "i18n");
+      const mergeOnlyDirs = [fullAppTemplateDir, fullI18nTemplateDir];
+      copySync(fullTemplateDir, cwd, {
+        filter: (source) => !mergeOnlyDirs.some((directory) => source === directory || source.startsWith(`${directory}${sep}`))
+      });
+      const appTargetDir = existsSync5(join5(cwd, "src", "app")) ? join5(cwd, "src", "app") : join5(cwd, "app");
+      copySync(fullAppTemplateDir, appTargetDir, {
+        overwrite: false,
+        errorOnExist: false
+      });
+      copySync(fullI18nTemplateDir, join5(cwd, "src", "i18n"), {
+        overwrite: false,
+        errorOnExist: false
+      });
+    }
     spinner.succeed("Server structure created");
   } catch (error) {
     spinner.fail("Failed to create server structure");
@@ -551,8 +602,10 @@ async function setupApiProxy(cwd, includeAuth) {
     return;
   }
   ensureDirSync3(rpcDir);
-  const authImport = includeAuth ? `import '@spfn/auth/nextjs/api';
+  const authImports = includeAuth ? `import '@spfn/auth/nextjs/api';
+import { authRouteMap } from '@spfn/auth';
 ` : "";
+  const proxyRouteMap = includeAuth ? "{ ...routeMap, ...authRouteMap }" : "routeMap";
   const routeContent = `/**
  * SPFN RPC Proxy
  *
@@ -566,10 +619,10 @@ async function setupApiProxy(cwd, includeAuth) {
  * Run \`spfn codegen run\` if route-map.ts is missing.
  */
 
-${authImport}import { routeMap } from '@/generated/route-map';
+${authImports}import { routeMap } from '@/generated/route-map';
 import { createRpcProxy } from '@spfn/core/nextjs/server';
 
-export const { GET, POST } = createRpcProxy({ routeMap });
+export const { GET, POST } = createRpcProxy({ routeMap: ${proxyRouteMap} });
 `;
   writeFileSync2(rpcRoutePath, routeContent);
   const relativePath = rpcRoutePath.replace(cwd + "/", "");
@@ -869,7 +922,7 @@ var init_deployment_config = __esm({
 
 // src/utils/version.ts
 function getCliVersion() {
-  return "0.2.0-beta.61";
+  return "0.2.0-beta.63";
 }
 function getTagFromVersion(version) {
   const match = version.match(/-([a-z]+)\./i);
@@ -888,7 +941,7 @@ var init_version = __esm({
 import ora3 from "ora";
 import { execa as execa2 } from "execa";
 import fse7 from "fs-extra";
-async function setupPackageJson(cwd, packageJsonPath, packageJson, packageManager, includeAuth) {
+async function setupPackageJson(cwd, packageJsonPath, packageJson, packageManager, mode) {
   const spinner = ora3("Updating package.json...").start();
   packageJson.dependencies = packageJson.dependencies || {};
   packageJson.devDependencies = packageJson.devDependencies || {};
@@ -902,8 +955,19 @@ async function setupPackageJson(cwd, packageJsonPath, packageJson, packageManage
   packageJson.dependencies["pg"] = "^8.16.3";
   packageJson.dependencies["spfn"] = spfnTag;
   packageJson.dependencies["concurrently"] = "^9.2.1";
-  if (includeAuth) {
+  if (mode === "full") {
     packageJson.dependencies["@spfn/auth"] = spfnTag;
+    packageJson.dependencies["@spfn/i18n"] = spfnTag;
+    packageJson.dependencies["@spfn/mcp"] = spfnTag;
+    packageJson.dependencies["@spfn/notification"] = spfnTag;
+    packageJson.engines = packageJson.engines || {};
+    const existingNodeRange = packageJson.engines.node;
+    if (!existingNodeRange || !requiresNode20OrNewer(existingNodeRange)) {
+      packageJson.engines.node = ">=20.0.0";
+      if (existingNodeRange) {
+        logger.warn(`Updated engines.node from "${existingNodeRange}" to ">=20.0.0" because full mode includes @spfn/mcp`);
+      }
+    }
   }
   packageJson.devDependencies["@types/node"] = "^20.11.0";
   packageJson.devDependencies["tsx"] = "^4.20.6";
@@ -935,6 +999,16 @@ async function setupPackageJson(cwd, packageJsonPath, packageJson, packageManage
     process.exit(1);
   }
 }
+function requiresNode20OrNewer(range) {
+  return range.split("||").map((alternative) => alternative.trim()).every((alternative) => {
+    const lowerBound = alternative.match(/^(?:>=|>|\^|~|=)?\s*v?(\d+)/);
+    if (!lowerBound) {
+      return false;
+    }
+    const major = Number(lowerBound[1]);
+    return major >= 20;
+  });
+}
 var writeFileSync6;
 var init_package = __esm({
   "src/commands/init/steps/package.ts"() {
@@ -1041,14 +1115,70 @@ var init_env_file = __esm({
 
 // src/commands/init/steps/config-files.ts
 import { existsSync as existsSync11, readFileSync as readFileSync5 } from "fs";
+import { randomBytes } from "crypto";
+import { spawnSync } from "child_process";
 import { join as join11 } from "path";
 import fse8 from "fs-extra";
+function envExampleTemplate(mode) {
+  return withPlaceholderCreds(`# Example environment \u2014 committed reference for the variables SPFN uses.
+# Real values live in .env.local (Next.js) and .env.server (backend secrets),
+# both gitignored. This file documents the keys; it is not loaded by anything.
+
+${ENV_LOCAL_TEMPLATE}${mode === "full" ? FULL_ENV_LOCAL_EXAMPLE : ""}
+${ENV_SERVER_TEMPLATE}${mode === "full" ? FULL_ENV_SERVER_EXAMPLE : ""}`);
+}
+function envServerExampleTemplate(mode) {
+  return withPlaceholderCreds(
+    `${ENV_SERVER_TEMPLATE}${mode === "full" ? FULL_ENV_SERVER_EXAMPLE : ""}`
+  );
+}
+function envLocalTemplate(mode) {
+  if (mode === "bare") {
+    return ENV_LOCAL_TEMPLATE;
+  }
+  return `${ENV_LOCAL_TEMPLATE}
+# Full scaffold: auth session encryption (Next.js server only; never NEXT_PUBLIC_*)
+SPFN_AUTH_SESSION_SECRET=${randomSecret("base64url")}
+SPFN_AUTH_SESSION_TTL=7d
+NEXT_PUBLIC_SPFN_APP_URL=http://localhost:3790
+`;
+}
+function envLocalExampleTemplate(mode) {
+  return `${ENV_LOCAL_TEMPLATE}${mode === "full" ? FULL_ENV_LOCAL_EXAMPLE : ""}`;
+}
+function envServerTemplate(mode) {
+  if (mode === "bare") {
+    return ENV_SERVER_TEMPLATE;
+  }
+  return `${ENV_SERVER_TEMPLATE}
+# Full scaffold: authentication
+SPFN_AUTH_VERIFICATION_TOKEN_SECRET=${randomSecret("base64url")}
+SPFN_AUTH_TOKEN_ENCRYPTION_KEYS=v1:${randomSecret("base64")}
+
+# Enable the social providers you need.
+# SPFN_AUTH_GOOGLE_CLIENT_ID=your-google-client-id
+# SPFN_AUTH_GOOGLE_CLIENT_SECRET=your-google-client-secret
+# SPFN_AUTH_GITHUB_CLIENT_ID=your-github-client-id
+# SPFN_AUTH_GITHUB_CLIENT_SECRET=your-github-client-secret
+# SPFN_AUTH_KAKAO_CLIENT_ID=your-kakao-rest-api-key
+# SPFN_AUTH_KAKAO_CLIENT_SECRET=your-kakao-client-secret
+# SPFN_AUTH_NAVER_CLIENT_ID=your-naver-client-id
+# SPFN_AUTH_NAVER_CLIENT_SECRET=your-naver-client-secret
+
+# Full scaffold: MCP operator endpoint
+SPFN_MCP_URL=http://localhost:8790
+SPFN_MCP_API_KEY=${randomSecret("base64url")}
+`;
+}
+function randomSecret(encoding) {
+  return randomBytes(32).toString(encoding);
+}
 function withPlaceholderCreds(text) {
   return text.replace(/(postgresql:\/\/)[^@\s/]+@/g, "$1user:password@");
 }
-async function setupConfigFiles(cwd) {
+async function setupConfigFiles(cwd, mode) {
   updateGitignore(cwd);
-  generateEnvFiles(cwd);
+  generateEnvFiles(cwd, mode);
   const spfnrcPath = join11(cwd, ".spfnrc.ts");
   if (!existsSync11(spfnrcPath)) {
     const spfnrcContent = `import { defineConfig, defineGenerator } from '@spfn/core/codegen';
@@ -1076,20 +1206,42 @@ export default defineConfig({
   }
   updateTsconfig(cwd);
 }
-function generateEnvFiles(cwd) {
-  writeEnvFile(cwd, ".env.local", ENV_LOCAL_TEMPLATE);
-  writeServerEnv(cwd);
-  writeExampleEnv(cwd, ENV_EXAMPLE_TEMPLATE);
+function generateEnvFiles(cwd, mode) {
+  writeLocalEnv(cwd, envLocalTemplate(mode), envLocalExampleTemplate(mode));
+  writeServerEnv(cwd, envServerTemplate(mode), envServerExampleTemplate(mode));
+  writeExampleEnv(cwd, envExampleTemplate(mode));
+}
+function writeLocalEnv(cwd, template, exampleTemplate) {
+  const filename = ".env.local";
+  const filePath = join11(cwd, filename);
+  if (isGitTracked(cwd, filename)) {
+    const referenceName = ".env.local.spfn.example";
+    const referencePath = join11(cwd, referenceName);
+    if (!existsSync11(referencePath)) {
+      writeFileSync8(referencePath, exampleTemplate);
+    }
+    logger.warn(`${filename} is tracked by Git \u2014 left it untouched; wrote ${referenceName}. Untrack ${filename}, then add the missing keys with freshly generated values`);
+    return;
+  }
+  writeEnvFile(cwd, filename, template);
+  restrictEnvFilePerms(filePath);
+}
+function isGitTracked(cwd, filename) {
+  const result = spawnSync("git", ["ls-files", "--error-unmatch", "--", filename], {
+    cwd,
+    stdio: "ignore"
+  });
+  return result.status === 0;
 }
-function writeServerEnv(cwd) {
+function writeServerEnv(cwd, template, exampleTemplate) {
   const filePath = join11(cwd, ".env.server");
   if (!existsSync11(filePath)) {
-    writeFileSync8(filePath, ENV_SERVER_TEMPLATE);
+    writeFileSync8(filePath, template);
     restrictEnvFilePerms(filePath);
     logger.success("Created .env.server");
     return;
   }
-  writeFileSync8(join11(cwd, ".env.server.example"), withPlaceholderCreds(ENV_SERVER_TEMPLATE));
+  writeFileSync8(join11(cwd, ".env.server.example"), exampleTemplate);
   logger.warn(".env.server already exists \u2014 left it untouched; wrote SPFN's reference to .env.server.example, add any missing keys manually");
 }
 function writeExampleEnv(cwd, content) {
@@ -1181,7 +1333,7 @@ function updateTsconfig(cwd) {
     logger.warn('Could not update tsconfig.json (you can add "src/server" to exclude manually)');
   }
 }
-var writeFileSync8, ENV_LOCAL_TEMPLATE, ENV_SERVER_TEMPLATE, ENV_EXAMPLE_TEMPLATE;
+var writeFileSync8, ENV_LOCAL_TEMPLATE, FULL_ENV_LOCAL_EXAMPLE, ENV_SERVER_TEMPLATE, FULL_ENV_SERVER_EXAMPLE;
 var init_config_files = __esm({
   "src/commands/init/steps/config-files.ts"() {
     "use strict";
@@ -1189,8 +1341,8 @@ var init_config_files = __esm({
     init_env_file();
     ({ writeFileSync: writeFileSync8 } = fse8);
     ENV_LOCAL_TEMPLATE = `# Next.js environment
-# Loaded by Next.js (and the SPFN backend). Only non-secret, Next.js-facing
-# values belong here \u2014 server secrets go in .env.server.
+# Loaded by Next.js (and the SPFN backend). Never prefix secrets with
+# NEXT_PUBLIC_. Backend-only secrets belong in .env.server.
 
 # SPFN API endpoint \u2014 browser + Next.js SSR/proxy target
 SPFN_API_URL=http://localhost:8790
@@ -1198,6 +1350,12 @@ NEXT_PUBLIC_SPFN_API_URL=http://localhost:8790
 
 # Next.js app URL (used by the SPFN server for CORS/redirects)
 SPFN_APP_URL=http://localhost:3790
+`;
+    FULL_ENV_LOCAL_EXAMPLE = `
+# Full scaffold: auth session encryption (Next.js server only; never NEXT_PUBLIC_*)
+SPFN_AUTH_SESSION_SECRET=replace-with-a-random-secret-at-least-32-characters
+SPFN_AUTH_SESSION_TTL=7d
+NEXT_PUBLIC_SPFN_APP_URL=http://localhost:3790
 `;
     ENV_SERVER_TEMPLATE = `# SPFN backend environment
 # Loaded ONLY by the SPFN server, never by Next.js. Keep all server-only config
@@ -1224,12 +1382,25 @@ DB_POOL_IDLE_TIMEOUT=30
 # DATABASE_READ_URL=postgresql://user:password@replica:5432/dbname
 # CACHE_PASSWORD=your-redis-password
 `;
-    ENV_EXAMPLE_TEMPLATE = withPlaceholderCreds(`# Example environment \u2014 committed reference for the variables SPFN uses.
-# Real values live in .env.local (Next.js) and .env.server (backend secrets),
-# both gitignored. This file documents the keys; it is not loaded by anything.
-
-${ENV_LOCAL_TEMPLATE}
-${ENV_SERVER_TEMPLATE}`);
+    FULL_ENV_SERVER_EXAMPLE = `
+# Full scaffold: authentication
+SPFN_AUTH_VERIFICATION_TOKEN_SECRET=replace-with-a-random-secret-at-least-32-characters
+SPFN_AUTH_TOKEN_ENCRYPTION_KEYS=v1:replace-with-a-base64-encoded-32-byte-key
+
+# Enable the social providers you need.
+# SPFN_AUTH_GOOGLE_CLIENT_ID=your-google-client-id
+# SPFN_AUTH_GOOGLE_CLIENT_SECRET=your-google-client-secret
+# SPFN_AUTH_GITHUB_CLIENT_ID=your-github-client-id
+# SPFN_AUTH_GITHUB_CLIENT_SECRET=your-github-client-secret
+# SPFN_AUTH_KAKAO_CLIENT_ID=your-kakao-rest-api-key
+# SPFN_AUTH_KAKAO_CLIENT_SECRET=your-kakao-client-secret
+# SPFN_AUTH_NAVER_CLIENT_ID=your-naver-client-id
+# SPFN_AUTH_NAVER_CLIENT_SECRET=your-naver-client-secret
+
+# Full scaffold: MCP operator endpoint
+SPFN_MCP_URL=http://localhost:8790
+SPFN_MCP_API_KEY=replace-with-a-random-operator-key
+`;
   }
 });
 
@@ -1254,15 +1425,16 @@ async function setupReadme(cwd, ctx) {
   const content = renderReadme(template, {
     projectName: ctx.packageJson.name || basename(cwd) || "my-app",
     pm: ctx.pm,
+    pmExec: ctx.pm === "npm" ? "npx" : ctx.pm,
     pmRun: getRunCommand(ctx.pm),
-    includeAuth: ctx.includeAuth
+    mode: ctx.mode
   });
   writeFileSync9(readmePath, content);
   logger.success("Created README.md");
 }
 function renderReadme(template, vars) {
   const authBlock = /\r?\n?<!-- \{\{#auth\}\} -->\r?\n([\s\S]*?)\r?\n<!-- \{\{\/auth\}\} -->\r?\n/;
-  return template.replace(authBlock, vars.includeAuth ? "\n$1\n" : "\n").replaceAll("{{projectName}}", () => vars.projectName).replaceAll("{{pmRun}}", () => vars.pmRun).replaceAll("{{pm}}", () => vars.pm);
+  return template.replace(authBlock, vars.mode === "full" ? "\n$1\n" : "\n").replaceAll("{{mode}}", () => vars.mode).replaceAll("{{projectName}}", () => vars.projectName).replaceAll("{{pmRun}}", () => vars.pmRun).replaceAll("{{pmExec}}", () => vars.pmExec).replaceAll("{{pm}}", () => vars.pm);
 }
 var writeFileSync9;
 var init_readme = __esm({
@@ -1281,31 +1453,40 @@ __export(init_exports, {
   initCommand: () => initCommand,
   initializeSpfn: () => initializeSpfn
 });
-import { Command as Command2 } from "commander";
+import { Command as Command2, Option } from "commander";
 import chalk4 from "chalk";
 async function initializeSpfn(options = {}) {
   const cwd = process.cwd();
-  const { packageJson, packageJsonPath, includeAuth } = await validateProject(cwd, options.yes || false);
+  const { packageJson, packageJsonPath } = await validateProject(cwd, options.yes || false);
+  const mode = await selectScaffoldMode(options);
+  const includeAuth = mode === "full";
   const pm = detectPackageManager(cwd);
   logger.step(`Detected package manager: ${pm}`);
-  await setupServerStructure(cwd);
+  await setupServerStructure(cwd, mode);
   await setupApiProxy(cwd, includeAuth);
   await setupNextConfig(cwd, includeAuth);
   await setupDockerFiles(cwd, pm);
   await setupDeploymentConfig(cwd, packageJson, pm);
-  await setupPackageJson(cwd, packageJsonPath, packageJson, pm, includeAuth);
-  await setupConfigFiles(cwd);
-  await setupReadme(cwd, { pm, packageJson, includeAuth, overwrite: options.overwriteReadme ?? false });
+  await setupPackageJson(cwd, packageJsonPath, packageJson, pm, mode);
+  await setupConfigFiles(cwd, mode);
+  await setupReadme(cwd, { pm, packageJson, mode, overwrite: options.overwriteReadme ?? false });
   console.log("\n" + chalk4.green.bold("\u2713 SPFN initialized successfully!\n"));
   console.log("Next steps:");
   console.log("  1. Start PostgreSQL & Redis (if not installed locally):");
   console.log("     " + chalk4.cyan("docker compose up -d"));
   console.log("  2. Review the generated env files (.env.local, .env.server)");
   console.log("     " + chalk4.dim(ENV_FILES_HINT));
-  console.log("  3. Run: " + chalk4.cyan(`${getRunCommand(pm)} spfn:dev`));
-  console.log("  4. Visit:");
+  if (mode === "full") {
+    const spfnCommand = pm === "npm" ? "npx spfn" : `${pm} spfn`;
+    console.log("  3. Apply the auth migrations: " + chalk4.cyan(`${spfnCommand} db migrate`));
+  }
+  console.log(`  ${mode === "full" ? "4" : "3"}. Run: ` + chalk4.cyan(`${getRunCommand(pm)} spfn:dev`));
+  console.log(`  ${mode === "full" ? "5" : "4"}. Visit:`);
   console.log("     - Next.js: " + chalk4.cyan("http://localhost:3790"));
   console.log("     - API:     " + chalk4.cyan("http://localhost:8790/health"));
+  if (mode === "full") {
+    console.log("     - MCP:     " + chalk4.cyan("http://localhost:8790/mcp"));
+  }
   console.log("\nAvailable commands:");
   console.log("  \u2022 " + chalk4.cyan(`${getRunCommand(pm)} spfn:dev`) + "       - Start SPFN + Next.js");
   console.log("  \u2022 " + chalk4.cyan("spfn env validate") + "  - Validate environment variables");
@@ -1329,7 +1510,8 @@ var init_init = __esm({
     init_package();
     init_config_files();
     init_readme();
-    initCommand = new Command2("init").description("Initialize SPFN in your Next.js project").option("-y, --yes", "Skip prompts and use defaults").action(initializeSpfn);
+    init_mode();
+    initCommand = new Command2("init").description("Initialize SPFN in your Next.js project").addOption(new Option("--mode <mode>", "Scaffold mode: bare (core) or full (core, auth, i18n, MCP)").choices(["bare", "full"])).option("-y, --yes", "Skip prompts and use defaults").action(initializeSpfn);
   }
 });
 
@@ -1684,10 +1866,11 @@ import { Command as Command13 } from "commander";
 init_logger();
 init_package_manager();
 init_messages();
-import { Command as Command3 } from "commander";
+init_mode();
+import { Command as Command3, Option as Option2 } from "commander";
 import { existsSync as existsSync13 } from "fs";
 import { join as join13, resolve, dirname as dirname2 } from "path";
-import prompts2 from "prompts";
+import prompts3 from "prompts";
 import ora4 from "ora";
 import { execa as execa3 } from "execa";
 import chalk5 from "chalk";
@@ -1713,7 +1896,7 @@ async function createProject(projectName, options) {
   console.log(chalk5.blue.bold("\n\u{1F680} Creating Next.js project with SPFN...\n"));
   let pm = options.pm || detectPackageManager(cwd);
   if (!options.yes && !options.pm) {
-    const { selectedPm } = await prompts2({
+    const { selectedPm } = await prompts3({
       type: "select",
       name: "selectedPm",
       message: "Which package manager do you want to use?",
@@ -1731,6 +1914,8 @@ async function createProject(projectName, options) {
     pm = selectedPm;
   }
   logger.step(`Using package manager: ${pm}`);
+  const mode = await selectScaffoldMode(options);
+  logger.step(`Using scaffold mode: ${mode}`);
   const workspaceRoot = pm === "pnpm" ? findPnpmWorkspaceRoot(cwd) : null;
   const isInWorkspace = workspaceRoot !== null;
   if (isInWorkspace) {
@@ -1829,7 +2014,7 @@ async function createProject(projectName, options) {
   const initSpinner = ora4("Initializing SPFN...").start();
   try {
     const { initializeSpfn: initializeSpfn2 } = await Promise.resolve().then(() => (init_init(), init_exports));
-    await initializeSpfn2({ yes: true, overwriteReadme: true });
+    await initializeSpfn2({ yes: true, overwriteReadme: true, mode });
     initSpinner.succeed("SPFN initialized");
   } catch (error) {
     initSpinner.fail("Failed to initialize SPFN");
@@ -1841,6 +2026,10 @@ async function createProject(projectName, options) {
   console.log(`  ${chalk5.cyan("cd")} ${projectName}`);
   console.log(`  ${chalk5.cyan("docker compose up -d")}  ${chalk5.gray("# Start PostgreSQL & Redis")}`);
   console.log(`  ${chalk5.gray(`# .env.local & .env.server are generated \u2014 ${ENV_FILES_HINT}`)}`);
+  if (mode === "full") {
+    const spfnCommand = pm === "npm" ? "npx spfn" : `${pm} spfn`;
+    console.log(`  ${chalk5.cyan(`${spfnCommand} db migrate`)}  ${chalk5.gray("# Apply auth migrations")}`);
+  }
   console.log(`  ${chalk5.cyan(`${getRunCommand(pm)} spfn:dev`)}  ${chalk5.gray("# Start dev server")}
 `);
   console.log(chalk5.bold("Your app will be available at:\n"));
@@ -1857,7 +2046,7 @@ async function createProject(projectName, options) {
 `);
   console.log(chalk5.dim("  \u{1F310} Documentation: https://github.com/spfn/spfn\n"));
 }
-var createCommand = new Command3("create").description("Create a new Next.js project with SPFN").argument("<project-name>", "Name of the project directory").option("--skip-install", "Skip installing dependencies").option("--skip-git", "Skip initializing a git repository").option("--pm <manager>", "Package manager to use (npm, pnpm, yarn, bun)").option("--shadcn", "Setup shadcn/ui (component library)").option("-y, --yes", "Skip prompts and use defaults").action(async (projectName, options) => {
+var createCommand = new Command3("create").description("Create a new Next.js project with SPFN").argument("<project-name>", "Name of the project directory").option("--skip-install", "Skip installing dependencies").option("--skip-git", "Skip initializing a git repository").option("--pm <manager>", "Package manager to use (npm, pnpm, yarn, bun)").option("--shadcn", "Setup shadcn/ui (component library)").addOption(new Option2("--mode <mode>", "Scaffold mode: bare (core) or full (core, auth, i18n, MCP)").choices(["bare", "full"])).option("-y, --yes", "Skip prompts and use defaults").action(async (projectName, options) => {
   await createProject(projectName, options);
 });
 
@@ -1869,7 +2058,7 @@ init_logger();
 init_package_manager();
 import { Command as Command4 } from "commander";
 import { existsSync as existsSync16, readFileSync as readFileSync8, writeFileSync as writeFileSync10, mkdirSync, unlinkSync, rmSync, watch } from "fs";
-import { join as join17, relative, sep } from "path";
+import { join as join17, relative, sep as sep2 } from "path";
 import { execa as execa6 } from "execa";
 import chokidar from "chokidar";
 
@@ -2064,7 +2253,7 @@ async function resolveKeychainEnv(cwd) {
 
 // src/commands/dev.ts
 function ignoreDotfilesUnder(root) {
-  return (watchedPath) => relative(root, watchedPath).split(sep).some((segment) => segment.startsWith(".") && segment !== "." && segment !== "..");
+  return (watchedPath) => relative(root, watchedPath).split(sep2).some((segment) => segment.startsWith(".") && segment !== "." && segment !== "..");
 }
 function waitForReadyFile(filePath, timeoutMs = 3e4) {
   return new Promise((resolve3, reject) => {
@@ -2793,16 +2982,16 @@ import { execSync } from "child_process";
 import chalk11 from "chalk";
 
 // src/utils/secret-gen.ts
-import { randomBytes, randomUUID } from "crypto";
+import { randomBytes as randomBytes2, randomUUID } from "crypto";
 function randomBase64Url(bytes) {
-  return randomBytes(bytes).toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=/g, "");
+  return randomBytes2(bytes).toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=/g, "");
 }
 function generateSecretValue(spec) {
   switch (spec) {
     case "hex32":
-      return randomBytes(32).toString("hex");
+      return randomBytes2(32).toString("hex");
     case "hex64":
-      return randomBytes(64).toString("hex");
+      return randomBytes2(64).toString("hex");
     case "base64url32":
       return randomBase64Url(32);
     case "uuid":
@@ -3137,7 +3326,7 @@ async function dbGenerate() {
 
 // src/commands/db/push.ts
 import chalk15 from "chalk";
-import prompts3 from "prompts";
+import prompts4 from "prompts";
 import "@spfn/core/config";
 import { loadEnv as loadEnv4 } from "@spfn/core/server";
 import { sql } from "drizzle-orm";
@@ -3322,7 +3511,7 @@ async function dbPush(options = {}) {
         console.log(chalk15.red(`   ${stmt.sql.replace(/\s+/g, " ").trim()}`));
         console.log(chalk15.dim(`   \u2192 ${stmt.reason}`));
       }
-      const { confirm } = await prompts3({
+      const { confirm } = await prompts4({
         type: "confirm",
         name: "confirm",
         message: "Apply destructive changes?",
@@ -3388,7 +3577,7 @@ import ora7 from "ora";
 // src/commands/db/utils/database.ts
 import net from "net";
 import chalk16 from "chalk";
-import prompts4 from "prompts";
+import prompts5 from "prompts";
 function parseDatabaseUrl2(dbUrl) {
   try {
     const url = new URL(dbUrl);
@@ -3412,7 +3601,7 @@ async function confirmDangerousTarget(dbInfo) {
   if (!isRemoteHost(dbInfo.host) && process.env.NODE_ENV !== "production") {
     return;
   }
-  const { typed } = await prompts4({
+  const { typed } = await prompts5({
     type: "text",
     name: "typed",
     message: `Remote/production database detected. Type the database name "${dbInfo.database}" to continue:`
@@ -3931,7 +4120,7 @@ async function dbStudio(requestedPort) {
 
 // src/commands/db/drop.ts
 import chalk23 from "chalk";
-import prompts5 from "prompts";
+import prompts6 from "prompts";
 import { env as env7 } from "@spfn/core/config";
 import { loadEnv as loadEnv7 } from "@spfn/core/server";
 async function dbDrop() {
@@ -3945,7 +4134,7 @@ async function dbDrop() {
   console.log(chalk23.yellow("\u26A0\uFE0F  WARNING: This will drop all tables in your database!"));
   console.log(chalk23.dim(`   Target: ${dbInfo.database} @ ${dbInfo.host}:${dbInfo.port}
 `));
-  const { confirm } = await prompts5({
+  const { confirm } = await prompts6({
     type: "confirm",
     name: "confirm",
     message: "Are you sure you want to drop all tables?",
@@ -3984,7 +4173,7 @@ import path4 from "path";
 import { spawn as spawn4 } from "child_process";
 import chalk25 from "chalk";
 import ora9 from "ora";
-import prompts6 from "prompts";
+import prompts7 from "prompts";
 import { env as env8 } from "@spfn/core/config";
 import { loadEnv as loadEnv8 } from "@spfn/core/server";
 async function dbRestore(backupFile, options = {}) {
@@ -4003,7 +4192,7 @@ async function dbRestore(backupFile, options = {}) {
       console.log(chalk25.yellow("No backups found in ./backups directory"));
       process.exit(0);
     }
-    const { selected } = await prompts6({
+    const { selected } = await prompts7({
       type: "select",
       name: "selected",
       message: "Select backup to restore:",
@@ -4066,7 +4255,7 @@ async function dbRestore(backupFile, options = {}) {
     }
   }
   const dbInfo = parseDatabaseUrl2(dbUrl);
-  const { confirm } = await prompts6({
+  const { confirm } = await prompts7({
     type: "confirm",
     name: "confirm",
     message: chalk25.yellow(`\u26A0\uFE0F  This will replace all data in "${dbInfo.database}" @ ${dbInfo.host}:${dbInfo.port}. Continue?`),
@@ -4249,7 +4438,7 @@ async function dbBackupList() {
 import { promises as fs4 } from "fs";
 import chalk27 from "chalk";
 import ora10 from "ora";
-import prompts7 from "prompts";
+import prompts8 from "prompts";
 async function dbBackupClean(options) {
   console.log(chalk27.blue("\u{1F9F9} Cleaning old backups...\n"));
   const backups = await listBackupFiles();
@@ -4279,7 +4468,7 @@ async function dbBackupClean(options) {
   toDelete.forEach((backup) => {
     console.log(chalk27.gray(`  - ${backup.name} (${backup.size})`));
   });
-  const { confirm } = await prompts7({
+  const { confirm } = await prompts8({
     type: "confirm",
     name: "confirm",
     message: "\nProceed with deletion?",
@@ -5004,7 +5193,7 @@ import { Command as Command12 } from "commander";
 
 // src/commands/secret/set.ts
 init_logger();
-import prompts8 from "prompts";
+import prompts9 from "prompts";
 import chalk31 from "chalk";
 
 // src/commands/secret/options.ts
@@ -5158,7 +5347,7 @@ async function secretSet(key, options) {
     process.exit(1);
   }
   await warnIfNotSecret(pkg, resolvedKey);
-  const { value } = await prompts8({
+  const { value } = await prompts9({
     type: "password",
     name: "value",
     message: `Value for ${chalk31.cyan(resolvedKey)} (${env9})`
@@ -5185,7 +5374,7 @@ async function pickSecretKey(pkg) {
   if (entries.length === 0) {
     return void 0;
   }
-  const { key } = await prompts8({
+  const { key } = await prompts9({
     type: "select",
     name: "key",
     message: "Which secret?",

package/dist/templates/README.md

@@ -1,7 +1,7 @@
 # {{projectName}}
 
-A full-stack app built with [SPFN](https://github.com/spfn/spfn) — a typed SPFN
-backend running alongside Next.js.
+A full-stack app built with [SPFN](https://github.com/spfn/spfn) — a consistent
+architecture for taking an AI-built prototype to production. Scaffold mode: `{{mode}}`.
 
 ## Getting started
 
@@ -10,7 +10,7 @@ backend running alongside Next.js.
 docker compose up -d
 
 # 2. The env files are generated for you:
-#    .env.local  — Next.js-facing values (gitignored)
+#    .env.local  — values loaded by Next.js, including auth session crypto (gitignored)
 #    .env.server — server secrets: DB, cache (gitignored, never loaded by Next.js)
 #    Review them and adjust as needed.
 
@@ -30,7 +30,7 @@ src/
   app/                 Next.js App Router
   server/              SPFN backend (entities, repositories, routes, router)
   generated/           codegen output (route map) — do not edit by hand
-.env.local             Next.js-facing env (gitignored)
+.env.local             Next.js runtime env (gitignored)
 .env.server            server secrets (gitignored)
 .env.example           committed reference — keys only, placeholder values
 .spfnrc.ts             codegen configuration
@@ -46,15 +46,15 @@ A feature is a vertical slice: `Entity` (Drizzle table) → `Repository` →
 {{pmRun}} spfn:dev          # dev: Next.js + SPFN API (add --watch to restart on changes)
 {{pmRun}} spfn:build        # production build
 {{pmRun}} spfn:start        # run the production build
-{{pm}} spfn db generate     # create a migration from schema changes
-{{pm}} spfn db migrate      # apply pending migrations
-{{pm}} spfn env check       # check .env files against the schema
-{{pm}} spfn secret set DB_URL   # store a secret (keychain locally, SOPS for deploys)
+{{pmExec}} spfn db generate     # create a migration from schema changes
+{{pmExec}} spfn db migrate      # apply pending migrations
+{{pmExec}} spfn env check       # check .env files against the schema
+{{pmExec}} spfn secret set DB_URL   # store a secret (keychain locally, SOPS for deploys)
 ```
 
 ## Environment & secrets
 
-`.env.server` holds server-only secrets and is gitignored — Next.js never loads it.
+`.env.server` holds backend-only secrets and is gitignored — Next.js never loads it.
 For a managed workflow use `spfn secret`: local values go to the OS keychain (only a
 `secret:keychain:` reference lands in `.env.server`), and deployed secrets are stored
 in encrypted SOPS files. See the [SPFN CLI docs](https://github.com/spfn/spfn).
@@ -63,8 +63,21 @@ in encrypted SOPS files. See the [SPFN CLI docs](https://github.com/spfn/spfn).
 ## Authentication
 
 This project includes `@spfn/auth`. Configure providers and session settings in your
-server setup, and read `@spfn/auth`'s README for the full Entity → Repository →
-Service → Route flow and the typed `authApi` client.
+generated env files, then run `{{pmExec}} spfn db migrate`. The lifecycle, router,
+Next.js interceptor, `/login` starter UI, OAuth callback, and route map are already wired.
+
+## Internationalization
+
+Edit `src/i18n/catalogs.ts` to add application-owned messages. Server components
+and handlers can import `getT` or `getClientMessages` from `@/i18n/server`.
+
+## Agent operations with MCP
+
+The SPFN API serves MCP at `http://localhost:8790/mcp`. Connect with the Bearer
+token stored as `SPFN_MCP_API_KEY` in `.env.server`, then replace the starter
+`app_status` tool in `src/server/mcp.ts` with operations from your domain layer.
+Before third-party access, replace the generated operator-key validator with your
+OAuth access-token validator and scope each tool to the resolved operator.
 <!-- {{/auth}} -->
 
 ## Deployment

package/dist/templates/modes/full/src/app/auth/callback/page.tsx

@@ -0,0 +1 @@
+export { OAuthCallback as default } from '@spfn/auth/nextjs/client';

package/dist/templates/modes/full/src/app/login/page.tsx

@@ -0,0 +1,68 @@
+'use client';
+
+import { useState } from 'react';
+import { authApi } from '@spfn/auth';
+import { I18nProvider, useT } from '@spfn/i18n/client';
+import { catalogs } from '@/i18n/catalogs';
+
+const providers = ['google', 'github', 'kakao', 'naver'] as const;
+
+export default function LoginPage()
+{
+    return (
+        <I18nProvider locale="en" messages={catalogs.en ?? {}}>
+            <LoginContent />
+        </I18nProvider>
+    );
+}
+
+function LoginContent()
+{
+    const [error, setError] = useState<string>();
+    const [pending, setPending] = useState<string>();
+    const t = useT('common');
+
+    async function signIn(provider: typeof providers[number]): Promise<void>
+    {
+        setError(undefined);
+        setPending(provider);
+
+        try
+        {
+            const { authUrl } = provider === 'google'
+                ? await authApi.getGoogleOAuthUrl.call({ body: { returnUrl: '/' } })
+                : await authApi.getProviderOAuthUrl.call({
+                    params: { provider },
+                    body: { returnUrl: '/' },
+                });
+
+            window.location.assign(authUrl);
+        }
+        catch (cause)
+        {
+            setPending(undefined);
+            setError(cause instanceof Error ? cause.message : 'Could not start sign in');
+        }
+    }
+
+    return (
+        <main style={{ maxWidth: 420, margin: '10vh auto', padding: 24 }}>
+            <h1>{t('appName')} — Sign in</h1>
+            <p>Connect a provider key in <code>.env.server</code>, then continue.</p>
+            <div style={{ display: 'grid', gap: 12, marginTop: 24 }}>
+                {providers.map(provider => (
+                    <button
+                        key={provider}
+                        type="button"
+                        disabled={pending !== undefined}
+                        onClick={() => void signIn(provider)}
+                        style={{ padding: 12, textTransform: 'capitalize' }}
+                    >
+                        {pending === provider ? 'Connecting…' : `Continue with ${provider}`}
+                    </button>
+                ))}
+            </div>
+            {error ? <p role="alert">{error}</p> : null}
+        </main>
+    );
+}

package/dist/templates/modes/full/src/i18n/catalogs.ts

@@ -0,0 +1,16 @@
+import type { LocaleCatalogs } from '@spfn/i18n';
+
+export const catalogs: LocaleCatalogs = {
+    en: {
+        common: {
+            appName: 'My SPFN app',
+            welcome: 'Welcome, {name}',
+        },
+    },
+    ko: {
+        common: {
+            appName: '나의 SPFN 앱',
+            welcome: '환영합니다, {name}',
+        },
+    },
+};

package/dist/templates/modes/full/src/i18n/server.ts

@@ -0,0 +1,9 @@
+import { configureI18n } from '@spfn/i18n/server';
+import { catalogs } from './catalogs';
+
+configureI18n({
+    catalogs,
+    fallbackLocale: 'en',
+});
+
+export { getClientMessages, getT } from '@spfn/i18n/server';

package/dist/templates/modes/full/src/server/config/env.config.ts

@@ -0,0 +1,23 @@
+import {
+    createEnvRegistry,
+    defineEnvSchema,
+    envSecret,
+    envUrl,
+} from '@spfn/core/env';
+
+export const envSchema = defineEnvSchema({
+    SPFN_MCP_URL: envUrl({
+        description: 'Public base URL of the SPFN server that exposes /mcp',
+        default: 'http://localhost:8790',
+        required: false,
+    }),
+    SPFN_MCP_API_KEY: envSecret({
+        description: 'First-party Bearer token for the generated MCP operator endpoint',
+        required: true,
+        generate: 'base64url32',
+    }),
+});
+
+export const env = createEnvRegistry(envSchema).validate();
+
+export default env;

package/dist/templates/modes/full/src/server/mcp.ts

@@ -0,0 +1,75 @@
+/**
+ * Remote MCP endpoint for operating this application with an agent.
+ *
+ * The generated operator key makes the endpoint usable immediately. Replace
+ * `validateToken` with your OAuth access-token validator before granting access
+ * to third-party clients, and expose only tools the resolved operator may use.
+ */
+import { timingSafeEqual } from 'node:crypto';
+import type { McpAuth, McpTool } from '@spfn/mcp';
+import { createMcpRoute } from '@spfn/mcp/server';
+import env from './config/env.config';
+
+type OperatorAuth = McpAuth & {
+    operatorId: string;
+};
+
+type OperatorContext = {
+    operatorId: string;
+};
+
+const tools: McpTool<OperatorContext>[] = [
+    {
+        name: 'app_status',
+        title: 'Application status',
+        description: 'Check that the deployed application MCP endpoint is available.',
+        inputSchema: {
+            type: 'object',
+            properties: {},
+        },
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+        },
+        handler: async (_args, context) => ({
+            status: 'ok',
+            operatorId: context.operatorId,
+        }),
+    },
+];
+
+export const mcpRouter = createMcpRoute<OperatorAuth, OperatorContext>({
+    appUrl: env.SPFN_MCP_URL,
+    serverInfo: {
+        name: 'spfn-app',
+        version: '1.0.0',
+        description: 'Operate this SPFN application with an agent.',
+    },
+    validateToken: async (token) =>
+    {
+        // The registry validates this required secret at startup. Its public
+        // proxy type remains optional so schemas can also describe values that
+        // are not required in every environment.
+        if (!secretsMatch(token, env.SPFN_MCP_API_KEY!))
+        {
+            throw new Error('Invalid MCP access token');
+        }
+
+        return {
+            clientId: 'operator-agent',
+            operatorId: 'operator',
+            scopes: ['operate'],
+        };
+    },
+    resolveContext: async auth => ({ operatorId: auth.operatorId }),
+    listTools: () => tools,
+});
+
+function secretsMatch(actual: string, expected: string): boolean
+{
+    const actualBytes = Buffer.from(actual);
+    const expectedBytes = Buffer.from(expected);
+
+    return actualBytes.length === expectedBytes.length
+        && timingSafeEqual(actualBytes, expectedBytes);
+}

package/dist/templates/modes/full/src/server/router.ts

@@ -0,0 +1,32 @@
+/**
+ * Prototype-to-Production application router.
+ *
+ * Auth protects application routes by default. Public routes opt out with
+ * `.skip(['auth'])`; the MCP router owns its Bearer-token boundary.
+ */
+import { authRouter, authenticate } from '@spfn/auth/server';
+import { defineRouter } from '@spfn/core/route';
+import { mcpRouter } from './mcp';
+import { getRoot } from './routes/root';
+import { getHealth } from './routes/health';
+import {
+    listExamples,
+    getExample,
+    createExample,
+    updateExample,
+    deleteExample,
+} from './routes/examples';
+
+export const appRouter = defineRouter({
+    getRoot,
+    getHealth,
+    listExamples,
+    getExample,
+    createExample,
+    updateExample,
+    deleteExample,
+})
+    .packages([authRouter, mcpRouter])
+    .use([authenticate]);
+
+export type AppRouter = typeof appRouter;

package/dist/templates/modes/full/src/server/routes/examples.ts

@@ -0,0 +1,94 @@
+import { route } from '@spfn/core/route';
+import { Type } from '@sinclair/typebox';
+import { ExampleRepository } from '../repositories/example.repository';
+
+const exampleRepo = new ExampleRepository();
+
+export const listExamples = route.get('/examples')
+    .input({
+        query: Type.Object({
+            limit: Type.Optional(Type.Number({ minimum: 1, maximum: 100 })),
+            offset: Type.Optional(Type.Number({ minimum: 0 })),
+        }),
+    })
+    .skip(['auth'])
+    .handler(async (c) =>
+    {
+        const { query } = await c.data();
+        const limit = query.limit ?? 10;
+        const offset = query.offset ?? 0;
+
+        return {
+            examples: await exampleRepo.findAll(limit, offset),
+            total: await exampleRepo.countAll(),
+            limit,
+            offset,
+        };
+    });
+
+export const getExample = route.get('/examples/:id')
+    .input({
+        params: Type.Object({ id: Type.String() }),
+    })
+    .skip(['auth'])
+    .handler(async (c) =>
+    {
+        const { params } = await c.data();
+        const example = await exampleRepo.findById(params.id);
+        if (!example)
+        {
+            throw new Error('Example not found');
+        }
+
+        return example;
+    });
+
+export const createExample = route.post('/examples')
+    .input({
+        body: Type.Object({
+            name: Type.String(),
+            description: Type.String(),
+        }),
+    })
+    .handler(async (c) =>
+    {
+        const { body } = await c.data();
+
+        return exampleRepo.createExample(body);
+    });
+
+export const updateExample = route.put('/examples/:id')
+    .input({
+        params: Type.Object({ id: Type.String() }),
+        body: Type.Object({
+            name: Type.Optional(Type.String()),
+            description: Type.Optional(Type.String()),
+        }),
+    })
+    .handler(async (c) =>
+    {
+        const { params, body } = await c.data();
+        const example = await exampleRepo.updateExample(params.id, body);
+        if (!example)
+        {
+            throw new Error('Example not found');
+        }
+
+        return example;
+    });
+
+export const deleteExample = route.delete('/examples/:id')
+    .input({
+        params: Type.Object({ id: Type.String() }),
+    })
+    .handler(async (c) =>
+    {
+        const { params } = await c.data();
+        const example = await exampleRepo.deleteExample(params.id);
+        if (!example)
+        {
+            throw new Error('Example not found');
+        }
+
+        return { success: true, id: params.id };
+    });

package/dist/templates/modes/full/src/server/routes/health.ts

@@ -0,0 +1,9 @@
+import { route } from '@spfn/core/route';
+
+export const getHealth = route.get('/health')
+    .skip(['auth'])
+    .handler(async () => ({
+        status: 'ok',
+        timestamp: Date.now(),
+        uptime: process.uptime(),
+    }));

package/dist/templates/modes/full/src/server/routes/root.ts

@@ -0,0 +1,15 @@
+import { route } from '@spfn/core/route';
+
+export const getRoot = route.get('/')
+    .skip(['auth'])
+    .handler(async () => ({
+        name: 'SPFN API',
+        version: '1.0.0',
+        status: 'running',
+        endpoints: {
+            health: '/health',
+            examples: '/examples',
+            auth: '/_auth',
+            mcp: '/mcp',
+        },
+    }));

package/dist/templates/modes/full/src/server/server.config.ts

@@ -0,0 +1,14 @@
+/**
+ * Prototype-to-Production server configuration.
+ */
+import '@/i18n/server';
+import { createAuthLifecycle } from '@spfn/auth/server';
+import { defineServerConfig } from '@spfn/core/server';
+import { appRouter } from '@/server/router';
+
+export default defineServerConfig()
+    .port(8790)
+    .host('0.0.0.0')
+    .routes(appRouter)
+    .lifecycle(createAuthLifecycle())
+    .build();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spfn",
-  "version": "0.2.0-beta.61",
+  "version": "0.2.0-beta.63",
   "description": "Superfunction CLI - Add SPFN to your Next.js project",
   "type": "module",
   "bin": {