swallowkit 2.0.0-alpha.2 → 2.0.0-alpha.4

package/src/cli/commands/scaffold.ts

@@ -62,9 +62,35 @@ interface ScaffoldOptions {
   functionsDir?: string; // Azure Functions のディレクトリ（デフォルト: "functions"）
   apiDir?: string; // BFF directory (Next.js: app/api, React: bff)
   apiOnly?: boolean; // true の場合、UI を生成しない（デフォルト: false）
+  skipInfra?: boolean; // true の場合、infra/ 配下（コンテナー migration）を変更しない
   expectedSchemaAnalysis?: SchemaAnalysisSnapshot;
 }
 
+export function buildInfraSkippedWarning(modelName: string, modelArgument: string): string {
+  return `infra-skipped: The Cosmos DB container migration for ${modelName} was not generated (--skip-infra); infra/ was left unchanged. ` +
+    `Generate it later with "swallowkit migrations add-model ${modelArgument}", or re-plan scaffold without --skip-infra.`;
+}
+
+const USER_SCOPE_FIELD = /^(user|owner|learner|member|account|customer|student|author|creator|profile|person|employee|patient)Id$/i;
+
+function isAuthenticationConfigured(authConfig: AuthConfig | undefined): boolean {
+  if (!authConfig || authConfig.provider === "none") return false;
+  return Boolean(authConfig.provider) || Object.keys(authConfig.schemes ?? {}).length > 0;
+}
+
+/** Warn when a model looks per-user (partition key or owner-like id field) but no authentication is configured. */
+export function buildUserScopedDataWarning(modelInfo: ModelInfo, authConfig: AuthConfig | undefined): string | undefined {
+  if (isAuthenticationConfigured(authConfig)) return undefined;
+  const partitionField = modelInfo.partitionKey.replace(/^\//, "");
+  const fieldNames = modelInfo.fields.filter((field) => field.type === "string" && !field.isArray).map((field) => field.name);
+  const ownerField = [partitionField, ...fieldNames].find((name) => USER_SCOPE_FIELD.test(name) && fieldNames.includes(name));
+  if (!ownerField) return undefined;
+  const reason = ownerField === partitionField ? `is the partition key and looks like a per-user owner id` : `looks like a per-user owner id`;
+  return `user-scoped-data-without-auth: ${modelInfo.name}.${ownerField} ${reason}, but authentication is not configured. ` +
+    `Generated CRUD does not scope data to a principal, so any caller can read and write every ${modelInfo.name} document. ` +
+    `Add authentication with "plan auth", restrict or remove the generated write endpoints, and add ai-authored endpoints that derive ${ownerField} from the verified principal instead of the request body.`;
+}
+
 function getMachineAwareStdio(): "inherit" | "pipe" {
   return process.env.SWALLOWKIT_MACHINE_OUTPUT === "1" ? "pipe" : "inherit";
 }
@@ -132,6 +158,12 @@ export async function scaffoldCommand(options: ScaffoldOptions) {
     session.setSchemaAnalysis(schemaAnalysis);
     console.log(`✅ Model parsed: ${modelInfo.name} (${modelInfo.schemaName})`);
 
+    const userScopeWarning = buildUserScopedDataWarning(modelInfo, getAuthConfig());
+    if (userScopeWarning) {
+      session.addWarning(userScopeWarning);
+      console.warn(`⚠️  ${userScopeWarning}`);
+    }
+
     const backendLanguage = getBackendLanguage();
     const frontend = getFrontendFramework();
     const apiDir = options.apiDir || (frontend === "react" ? "bff" : "app/api");
@@ -210,9 +242,15 @@ export async function scaffoldCommand(options: ScaffoldOptions) {
       await generateBFFRoutes(modelInfo, apiDir, sharedPackageName, session);
     }
 
-    // 8. Generate Cosmos DB container Bicep file (skip for connector models)
+    // 8. Generate Cosmos DB container Bicep file (skip for connector models or when infra changes are excluded)
     if (!isConnectorModel) {
-      await generateCosmosContainer(modelInfo, session);
+      if (options.skipInfra) {
+        const warning = buildInfraSkippedWarning(modelInfo.name, toKebabCase(modelInfo.name));
+        session.addWarning(warning);
+        console.warn(`\n⚠️  ${warning}`);
+      } else {
+        await generateCosmosContainer(modelInfo, session);
+      }
     }
 
     // 9. Generate UI components (unless --api-only)

package/src/cli/index.ts

@@ -8,6 +8,7 @@ import { initCommand, devCommand, devSeedsCommand, scaffoldCommand, createModelC
 import { provisionCommand } from "./commands/provision";
 import { createMigrationCommand } from "./commands/create-migration";
 import { migrationsCommand } from "./commands/migrations";
+import { configureMcpCommand } from "./commands/configure-mcp";
 import { addConnectorCommand } from "./commands/add-connector";
 import { addAuthCommand } from "./commands/add-auth";
 import { planScaffoldOperation } from "../core/operations/scaffold-plan";
@@ -15,6 +16,7 @@ import { inspectArtifacts } from "../core/project/artifacts";
 import { detectDrift } from "../core/project/drift";
 import { runVerify } from "../core/verify";
 import { isMachineCommand, runMachineCli } from "../machine";
+import { MachineCommandError } from "../machine/errors";
 
 const packageJsonPath = path.resolve(__dirname, "../../package.json");
 export const CLI_VERSION = JSON.parse(readFileSync(packageJsonPath, "utf8")).version as string;
@@ -140,6 +142,7 @@ export function createProgram(devCommandOverride: Command = devCommand): Command
   program.addCommand(provisionCommand);
   program.addCommand(migrationsCommand);
   program.addCommand(createMigrationCommand);
+  program.addCommand(configureMcpCommand);
 
   program
     .command("create-model <names...>")
@@ -160,6 +163,7 @@ export function createProgram(devCommandOverride: Command = devCommand): Command
     .option("--functions-dir <dir>", "Azure Functions directory", "functions")
     .option("--api-dir <dir>", "BFF routes directory (Next.js: app/api; React: bff)")
     .option("--api-only", "Skip UI components; still update Functions, BFF routes, OpenAPI, and native schema assets", false)
+    .option("--skip-infra", "Do not create or update anything under infra/ (generate the container migration later with migrations add-model)", false)
     .option("--dry-run", "Show planned file changes without writing anything", false)
     .action(async (model, options) => {
       if (options.dryRun) {
@@ -168,6 +172,7 @@ export function createProgram(devCommandOverride: Command = devCommand): Command
           functionsDir: options.functionsDir,
           apiDir: options.apiDir,
           apiOnly: options.apiOnly,
+          skipInfra: options.skipInfra,
         });
         return;
       }
@@ -177,6 +182,7 @@ export function createProgram(devCommandOverride: Command = devCommand): Command
         functionsDir: options.functionsDir,
         apiDir: options.apiDir,
         apiOnly: options.apiOnly,
+        skipInfra: options.skipInfra,
       });
     });
 
@@ -226,7 +232,7 @@ export function createProgram(devCommandOverride: Command = devCommand): Command
   return program;
 }
 
-async function runScaffoldDryRun(options: { model: string; functionsDir?: string; apiDir?: string; apiOnly?: boolean }): Promise<void> {
+async function runScaffoldDryRun(options: { model: string; functionsDir?: string; apiDir?: string; apiOnly?: boolean; skipInfra?: boolean }): Promise<void> {
   console.log("🔍 Scaffold dry-run — no files will be written.\n");
 
   const plan = await planScaffoldOperation(options);
@@ -264,7 +270,7 @@ async function runScaffoldDryRun(options: { model: string; functionsDir?: string
     console.log(`⚠️  ${plan.conflicts.length} file(s) were modified after generation and would be overwritten.`);
     console.log(`   Review the conflicts, then run: swallowkit scaffold ${options.model} (or machine apply scaffold --plan ${plan.planId} --approve)`);
   } else {
-    console.log(`   Run without --dry-run to apply: swallowkit scaffold ${options.model}`);
+    console.log(`   Run without --dry-run to apply: swallowkit scaffold ${options.model}${options.skipInfra ? " --skip-infra" : ""}`);
   }
 }
 
@@ -351,9 +357,26 @@ export async function runCli(argv: string[] = process.argv): Promise<void> {
   await createProgram().parseAsync(normalizeDevCommandArgv(argv));
 }
 
+/** Human-readable error output for regular CLI commands (machine commands print JSON). */
+export function formatCliError(error: unknown): string {
+  if (error instanceof MachineCommandError) {
+    const lines = [`❌ ${error.message}`, `   (code: ${error.code})`];
+    const details = error.details as Record<string, unknown> | undefined;
+    if (details && typeof details === "object") {
+      if (typeof details.nextAction === "string") lines.push(`   Next: ${details.nextAction}`);
+      if (Array.isArray(details.changedFiles)) lines.push(`   Changed files: ${details.changedFiles.join(", ")}`);
+    }
+    return lines.join("\n");
+  }
+  if (error instanceof Error) {
+    return process.env.SWALLOWKIT_DEBUG ? String(error.stack ?? error.message) : `❌ ${error.message}`;
+  }
+  return `❌ ${String(error)}`;
+}
+
 if (require.main === module) {
   void runCli().catch((error) => {
-    console.error(error);
+    console.error(formatCliError(error));
     process.exitCode = 1;
   });
 }

package/src/core/operations/model-migration.ts

@@ -0,0 +1,52 @@
+/**
+ * Generate only the Cosmos DB container migration for a model. Used after
+ * `scaffold --skip-infra`, when infrastructure changes become allowed.
+ */
+
+import { resolveModelPath } from "../../cli/commands/scaffold";
+import { MachineCommandError } from "../../machine/errors";
+import { parseModelFile } from "../scaffold/model-parser";
+import { recordSessionOperations } from "../project/artifacts";
+import { FileOperationSession } from "./file-session";
+import { generateModelContainerMigration } from "./migration-generator";
+
+export interface ModelMigrationResult {
+  model: string;
+  dryRun: boolean;
+  migration: { version: number; template: string } | null;
+  reason?: string;
+  operations: Array<{ path: string; action: string }>;
+}
+
+export async function addModelContainerMigration(
+  modelInput: string,
+  options: { dryRun?: boolean; projectRoot?: string } = {}
+): Promise<ModelMigrationResult> {
+  const projectRoot = options.projectRoot ?? process.cwd();
+  const modelInfo = await parseModelFile(resolveModelPath(modelInput));
+  if (modelInfo.connectorConfig) {
+    throw new MachineCommandError(
+      "connector-model-has-no-container",
+      `${modelInfo.name} uses connector ${modelInfo.connectorConfig.connector}; connector models do not get a Cosmos DB container.`,
+      undefined,
+      "failed"
+    );
+  }
+
+  const session = new FileOperationSession(options.dryRun ? "collect" : "commit", projectRoot);
+  const migration = generateModelContainerMigration(modelInfo, session);
+  if (!options.dryRun) {
+    recordSessionOperations(session.operations, {
+      schemaHash: modelInfo.semanticFingerprint,
+      sourceModel: modelInfo.name,
+    }, projectRoot);
+  }
+
+  return {
+    model: modelInfo.name,
+    dryRun: Boolean(options.dryRun),
+    migration: migration ? { version: migration.version, template: migration.template } : null,
+    ...(migration ? {} : { reason: "The container is already owned by the legacy migration baseline." }),
+    operations: session.operations.map((operation) => ({ path: operation.path, action: operation.action })),
+  };
+}

package/src/core/operations/provision-operations.ts

@@ -5,12 +5,14 @@
  *   ネットワークアクセスや az login を必要とする操作は行わない。
  *   --what-if を明示した場合のみ az deployment group what-if を実行する。
  * - apply provision: 常に承認(--approve)必須。承認なしでは requires-human で停止する。
+ * - 対話的な `swallowkit provision` は同じ計画をメモリ上で作成・表示し、確認後に
+ *   executeProvisionPlan で同じ安全確認を経て実行する(計画ファイルは保存しない)。
  */
 
 import * as crypto from "crypto";
 import * as fs from "fs";
+import { AzCliAvailability, checkAzCliAvailability, runAzCli } from "../../utils/azure-cli";
 import * as path from "path";
-import { spawnSync } from "child_process";
 import { MachineCommandError } from "../../machine/errors";
 import { getSwallowKitVersion } from "../../version";
 import { inspectInfra, InfraInspection } from "../project/infra";
@@ -30,7 +32,6 @@ import {
   getMigrationTagKey,
   loadMigrationManifest,
   replaceMigrationManifest,
-  resolveMigrations,
   selectPendingMigrations,
 } from "../project/migrations";
 
@@ -113,13 +114,10 @@ function validateProvisionInputs(options: PlanProvisionOptions): void {
   }
 }
 
-function isAzCliAvailable(): boolean {
-  try {
-    const result = spawnSync("az", ["--version"], { shell: false, stdio: "ignore", timeout: 30_000 });
-    return result.status === 0;
-  } catch {
-    return false;
-  }
+function azCliUnavailableWarning(availability: Exclude<AzCliAvailability, { available: true }>): string {
+  return availability.reason === "not-found"
+    ? "az-cli-not-found: Azure CLI was not found on PATH. Install it (https://aka.ms/azure-cli) or add it to PATH, then try again."
+    : `az-cli-not-runnable: Azure CLI was found but could not be started. ${availability.detail}`;
 }
 
 function displayCommand(command: ProvisionCommand): string {
@@ -133,14 +131,27 @@ interface AzResult {
 }
 
 function runAz(args: string[], timeout = 300_000): AzResult {
-  const result = spawnSync("az", args, { shell: false, encoding: "utf-8", timeout });
+  const result = runAzCli(args, { timeout });
   return {
     status: result.status,
-    stdout: result.stdout ?? "",
-    stderr: result.stderr ?? "",
+    stdout: result.stdout,
+    stderr: result.stderr || (result.error ? result.error.message : ""),
   };
 }
 
+function azQueryError(code: string, message: string, result: AzResult): MachineCommandError {
+  const output = (result.stderr || result.stdout || "").trim();
+  if (/az login|not logged in|AADSTS|expired/i.test(output)) {
+    return new MachineCommandError(
+      "az-not-logged-in",
+      `Azure CLI is not signed in (or the session expired). Run "az login", then try again.\n${output.slice(0, 1000)}`,
+      undefined,
+      "requires-human"
+    );
+  }
+  return new MachineCommandError(code, `${message}: ${output}`, undefined, "blocked");
+}
+
 function subscriptionArgs(subscription?: string): string[] {
   return subscription ? ["--subscription", subscription] : [];
 }
@@ -176,12 +187,12 @@ interface RemoteGroupState {
 function inspectRemoteGroup(options: PlanProvisionOptions): RemoteGroupState {
   const existsResult = runAz(["group", "exists", "--name", options.resourceGroup, ...subscriptionArgs(options.subscription)], 60_000);
   if (existsResult.status !== 0) {
-    throw new MachineCommandError("azure-state-query-failed", `Could not query resource group: ${(existsResult.stderr || existsResult.stdout || "").trim()}`, undefined, "blocked");
+    throw azQueryError("azure-state-query-failed", "Could not query resource group", existsResult);
   }
   if ((existsResult.stdout || "").trim() !== "true") return { exists: false, tags: {} };
   const showResult = runAz(["group", "show", "--name", options.resourceGroup, ...subscriptionArgs(options.subscription), "--query", "{id:id,tags:tags}", "-o", "json"], 60_000);
   if (showResult.status !== 0) {
-    throw new MachineCommandError("azure-state-query-failed", `Could not read resource group tags: ${(showResult.stderr || showResult.stdout || "").trim()}`, undefined, "blocked");
+    throw azQueryError("azure-state-query-failed", "Could not read resource group tags", showResult);
   }
   const parsed = JSON.parse(showResult.stdout || "{}");
   return { exists: true, id: parsed.id, tags: parsed.tags ?? {} };
@@ -231,7 +242,14 @@ function assertAdoptionWhatIfIsSafe(whatIfResult: string): void {
   }
 }
 
-export async function planProvisionOperation(options: PlanProvisionOptions): Promise<ProvisionPlanData> {
+/**
+ * Builds the provision plan. Machine/MCP callers persist it for a later `apply provision --plan`;
+ * the interactive `swallowkit provision` command keeps it in memory and executes it after confirmation.
+ */
+export async function planProvisionOperation(
+  options: PlanProvisionOptions,
+  planOptions: { persist?: boolean } = {}
+): Promise<ProvisionPlanData> {
   const projectRoot = process.cwd();
   validateProvisionInputs(options);
 
@@ -250,9 +268,10 @@ export async function planProvisionOperation(options: PlanProvisionOptions): Pro
     warnings.push("infra/main.parameters.json not found; deployment will fail until it is created.");
   }
 
-  const azCliAvailable = isAzCliAvailable();
-  if (!azCliAvailable) {
-    warnings.push("az-cli-not-found: Azure CLI is not installed. Install it before applying: https://aka.ms/azure-cli");
+  const azCli = checkAzCliAvailability();
+  const azCliAvailable = azCli.available;
+  if (!azCli.available) {
+    warnings.push(azCliUnavailableWarning(azCli));
   }
 
   const mainBicepPath = path.join(projectRoot, "infra", "main.bicep");
@@ -396,7 +415,13 @@ export async function planProvisionOperation(options: PlanProvisionOptions): Pro
       }
     }
   } else if (options.whatIf || options.adoptExisting || options.reconcile) {
-    throw new MachineCommandError("az-cli-not-found", "Azure CLI is required for --what-if, --adopt-existing, and --reconcile.", undefined, "blocked");
+    const detail = azCli.available ? "" : ` ${azCliUnavailableWarning(azCli)}`;
+    throw new MachineCommandError(
+      !azCli.available && azCli.reason === "not-runnable" ? "az-cli-not-runnable" : "az-cli-not-found",
+      `Azure CLI is required for --what-if, --adopt-existing, and --reconcile.${detail}`,
+      undefined,
+      "blocked"
+    );
   }
 
   const fingerprints: Record<string, string | null> = {
@@ -460,7 +485,7 @@ export async function planProvisionOperation(options: PlanProvisionOptions): Pro
     ...(baselineSnapshotChecksum ? { baselineSnapshotChecksum } : {}),
   };
 
-  savePlanState(plan, projectRoot);
+  if (planOptions.persist !== false) savePlanState(plan, projectRoot);
   return plan;
 }
 
@@ -490,37 +515,40 @@ function readRemoteMigrationState(plan: ProvisionPlanData): { group: RemoteGroup
   return { group, state: tagValue ? decodeMigrationState(tagValue) : null };
 }
 
-function assertPlanRemoteState(plan: ProvisionPlanData, expected: MigrationState | null | undefined): void {
+function assertPlanRemoteState(plan: ProvisionPlanData, expected: MigrationState | null | undefined, retryHint: string): void {
   if (plan.mode === "offline") return;
   const current = readRemoteMigrationState(plan);
   if (plan.mode === "bootstrap") {
     if (current.group.exists) {
-      throw new MachineCommandError("stale-azure-state", "The resource group was created after this plan. Re-run plan provision.", undefined, "blocked");
+      throw new MachineCommandError("stale-azure-state", `The resource group was created after the preview was computed. ${retryHint}`, undefined, "blocked");
     }
     return;
   }
   if (!current.group.exists || !statesEqual(current.state, expected)) {
     throw new MachineCommandError(
       "stale-azure-state",
-      "Azure migration state changed after this plan was created. Re-run plan provision.",
+      `Azure migration state changed after the preview was computed. ${retryHint}`,
       { expected, actual: current.state, resourceGroupExists: current.group.exists },
       "blocked"
     );
   }
 }
 
-function assertTagExpectedState(plan: ProvisionPlanData, expected: MigrationState | null | undefined): void {
+function assertTagExpectedState(plan: ProvisionPlanData, expected: MigrationState | null | undefined, retryHint: string): void {
   const current = readRemoteMigrationState(plan);
   if (!current.group.exists || !statesEqual(current.state, expected)) {
     throw new MachineCommandError(
       "stale-azure-state",
-      "Azure migration state changed before its tag could be updated. Re-run plan provision.",
+      `Azure migration state changed before its tag could be updated. ${retryHint}`,
       { expected, actual: current.state, resourceGroupExists: current.group.exists },
       "blocked"
     );
   }
 }
 
+const MACHINE_RETRY_HINT = "Re-run plan provision.";
+export const INTERACTIVE_PROVISION_RETRY_HINT = 'Run "swallowkit provision" again to review the current state.';
+
 export async function applyProvisionOperation(options: ApplyProvisionOptions): Promise<ApplyProvisionResult> {
   const projectRoot = process.cwd();
 
@@ -534,6 +562,22 @@ export async function applyProvisionOperation(options: ApplyProvisionOptions): P
     );
   }
 
+  const result = await executeProvisionPlan(plan, { approve: options.approve, retryHint: MACHINE_RETRY_HINT, projectRoot });
+  deletePlanState(plan.planId, projectRoot);
+  return result;
+}
+
+/**
+ * Runs an approved provision plan with every safety check: local files and Azure state must still
+ * match the reviewed preview, and each migration/tag step re-checks Azure state before it runs.
+ */
+export async function executeProvisionPlan(
+  plan: ProvisionPlanData,
+  options: { approve?: boolean; retryHint?: string; projectRoot?: string } = {}
+): Promise<ApplyProvisionResult> {
+  const projectRoot = options.projectRoot ?? process.cwd();
+  const retryHint = options.retryHint ?? MACHINE_RETRY_HINT;
+
   // Bicep が plan 後に変更されていないか確認
   const changedFiles: string[] = [];
   for (const [relativePath, expectedHash] of Object.entries(plan.fingerprints)) {
@@ -543,8 +587,8 @@ export async function applyProvisionOperation(options: ApplyProvisionOptions): P
   if (changedFiles.length > 0) {
     throw new MachineCommandError(
       "stale-plan",
-      `Plan "${options.planId}" is stale: ${changedFiles.join(", ")} changed after the plan was created. Re-run "plan provision".`,
-      { planId: options.planId, changedFiles },
+      `${changedFiles.join(", ")} changed after the preview was computed. ${retryHint}`,
+      { planId: plan.planId, changedFiles },
       "blocked"
     );
   }
@@ -553,8 +597,8 @@ export async function applyProvisionOperation(options: ApplyProvisionOptions): P
     if (currentBaselineChecksum !== plan.baselineSnapshotChecksum) {
       throw new MachineCommandError(
         "stale-plan",
-        `Plan "${options.planId}" is stale: baseline infrastructure inventory changed after the plan was created.`,
-        { planId: options.planId },
+        `Baseline infrastructure files changed after the preview was computed. ${retryHint}`,
+        { planId: plan.planId },
         "blocked"
       );
     }
@@ -569,10 +613,15 @@ export async function applyProvisionOperation(options: ApplyProvisionOptions): P
     );
   }
   if (!plan.mode || !plan.commandSpecs) {
-    throw new MachineCommandError("incompatible-plan", "This provision plan was created by an older SwallowKit version. Re-run plan provision.", undefined, "blocked");
+    throw new MachineCommandError("incompatible-plan", `This provision plan was created by an older SwallowKit version. ${retryHint}`, undefined, "blocked");
   }
   if (plan.mode === "offline") {
-    throw new MachineCommandError("online-plan-required", "Provision apply requires a fresh plan created while Azure CLI is available and authenticated.", undefined, "blocked");
+    throw new MachineCommandError(
+      "online-plan-required",
+      `Azure state was not read because Azure CLI was unavailable, so nothing can be applied. Make az available and signed in (az login). ${retryHint}`,
+      { planId: plan.planId, warnings: plan.warnings },
+      "blocked"
+    );
   }
 
   if (plan.mode === "adoption-required") {
@@ -584,27 +633,23 @@ export async function applyProvisionOperation(options: ApplyProvisionOptions): P
     );
   }
 
-  if (!isAzCliAvailable()) {
-    throw new MachineCommandError(
-      "az-cli-not-found",
-      "Azure CLI is not installed. Install it first: https://aka.ms/azure-cli",
-      undefined,
-      "blocked"
-    );
+  const azCli = checkAzCliAvailability();
+  if (!azCli.available) {
+    throw new MachineCommandError(azCli.reason === "not-found" ? "az-cli-not-found" : "az-cli-not-runnable", azCliUnavailableWarning(azCli), undefined, "blocked");
   }
 
   const executedCommands: string[] = [];
   const warnings = [...plan.warnings];
   let deploymentOutputs: Record<string, unknown> | undefined;
 
-  assertPlanRemoteState(plan, plan.remoteState);
+  assertPlanRemoteState(plan, plan.remoteState, retryHint);
 
   for (const command of plan.commandSpecs) {
     if (command.kind === "migration") {
-      assertPlanRemoteState(plan, command.expectedState);
+      assertPlanRemoteState(plan, command.expectedState, retryHint);
     }
     if (command.kind === "tag") {
-      assertTagExpectedState(plan, command.expectedState);
+      assertTagExpectedState(plan, command.expectedState, retryHint);
     }
     const result = runAz(command.args);
     const commandText = displayCommand(command);
@@ -630,7 +675,6 @@ export async function applyProvisionOperation(options: ApplyProvisionOptions): P
   if (plan.manifestAfterApply) {
     replaceMigrationManifest(plan.manifestAfterApply, projectRoot);
   }
-  deletePlanState(plan.planId, projectRoot);
 
   return {
     planId: plan.planId,

package/src/core/operations/scaffold-apply.ts

@@ -19,6 +19,7 @@ export interface ApplyScaffoldOptions {
   functionsDir?: string;
   apiDir?: string;
   apiOnly?: boolean;
+  skipInfra?: boolean;
 }
 
 export interface ApplyScaffoldResult extends MachineScaffoldOperationResult {
@@ -70,6 +71,7 @@ export async function applyScaffoldOperation(options: ApplyScaffoldOptions): Pro
     functionsDir: options.functionsDir ?? basePlan?.options.functionsDir,
     apiDir: options.apiDir ?? basePlan?.options.apiDir,
     apiOnly: options.apiOnly ?? basePlan?.options.apiOnly,
+    skipInfra: options.skipInfra ?? basePlan?.options.skipInfra,
   };
 
   // 常に最新状態で collect し、競合を検出する(plan 指定時も現況を再確認)

package/src/core/operations/scaffold-machine.ts

@@ -13,6 +13,7 @@ export interface MachineScaffoldOperationOptions {
   functionsDir?: string;
   apiDir?: string;
   apiOnly?: boolean;
+  skipInfra?: boolean;
   expectedSchemaAnalysis?: SchemaAnalysisSnapshot;
 }
 

package/src/core/operations/scaffold-plan.ts

@@ -29,6 +29,7 @@ export interface PlanScaffoldOptions {
   functionsDir?: string;
   apiDir?: string;
   apiOnly?: boolean;
+  skipInfra?: boolean;
 }
 
 export type ScaffoldPlanAction = "create" | "update" | "overwrite" | "append" | "delete" | "skip";
@@ -59,6 +60,7 @@ export interface ScaffoldPlanData {
     functionsDir?: string;
     apiDir?: string;
     apiOnly?: boolean;
+    skipInfra?: boolean;
   };
   createdAt: string;
   swallowkitVersion: string;
@@ -93,6 +95,7 @@ async function collectScaffoldOperations(options: PlanScaffoldOptions): Promise<
             functionsDir: options.functionsDir,
             apiDir: options.apiDir,
             apiOnly: options.apiOnly,
+            skipInfra: options.skipInfra,
           });
         });
       });
@@ -193,7 +196,7 @@ export async function planScaffoldOperation(options: PlanScaffoldOptions): Promi
     .update(
       JSON.stringify({
         model: options.model,
-        options: { functionsDir: options.functionsDir, apiDir: options.apiDir, apiOnly: options.apiOnly },
+        options: { functionsDir: options.functionsDir, apiDir: options.apiDir, apiOnly: options.apiOnly, skipInfra: options.skipInfra },
         operations: operations.map((op) => ({ path: op.path, action: op.action })),
         fingerprints,
         schemaAnalysis,
@@ -210,6 +213,7 @@ export async function planScaffoldOperation(options: PlanScaffoldOptions): Promi
       ...(options.functionsDir ? { functionsDir: options.functionsDir } : {}),
       ...(options.apiDir ? { apiDir: options.apiDir } : {}),
       ...(options.apiOnly !== undefined ? { apiOnly: options.apiOnly } : {}),
+      ...(options.skipInfra ? { skipInfra: true } : {}),
     },
     createdAt: new Date().toISOString(),
     swallowkitVersion: getSwallowKitVersion(),

package/src/core/project/agent-instructions.ts

@@ -71,6 +71,9 @@ function getBackendRules(backendLanguage: BackendLanguage): string {
     "- All backend business logic and data access live in `functions/`.",
     `- SwallowKit derives OpenAPI and native ${BACKEND_LANGUAGE_LABELS[backendLanguage]} schema assets from the Zod source of truth.`,
     "- Keep custom business logic in ai-authored locations identified by the current boundary contract.",
+    backendLanguage === "python"
+      ? "- Use uv with the user's interpreter/version settings. Local Python is not pinned to the Azure deployment runtime. Preserve functions/.venv and functions/.codegen-venv; do not clear them or weaken OS application-control policy to fix interpreter errors."
+      : "- Start the isolated Functions backend with dotnet run, not func start from the source directory, so the SDK loads extensions from the build output.",
   ].join("\n");
 }
 
@@ -91,7 +94,7 @@ function interpolateTemplate(template: string, context: AgentInstructionContext)
       ? "├── src/                    # React SPA (Vite + React Router)\n│   └── pages/              # generated/custom UI and route registrations\n├── bff/                    # SWA managed HTTP-only Functions\n│   ├── src/                # BFF handlers and request-local helpers\n│   └── {function}/         # function.json registrations"
       : "├── app/                    # Next.js App Router\n│   ├── api/                # BFF routes\n│   └── {model}/            # generated/custom UI",
     devGuidance: react
-      ? "Use http://localhost:4280 for the app. `swallowkit dev` runs Vite (3000), the managed BFF (7073), standalone Functions (7071), and SWA CLI (4280). SWA forwards /api only to the managed BFF, never directly to standalone Functions. `--no-functions` leaves the BFF running; `--no-swa` removes same-origin routing/auth emulation. BFF local settings belong in bff/local.settings.json. Build bundles BFF dependencies and copies staticwebapp.config.json into dist/. Deploy dist/ + bff/ together, and functions/ separately."
+      ? "Use http://localhost:4280 for the app. `swallowkit dev` runs Vite (3000), the managed BFF (7073), standalone Functions (7071), and SWA CLI (4280). SWA forwards /api only to the managed BFF, never directly to standalone Functions. `--no-functions` leaves the BFF running; `--no-swa` removes same-origin routing/auth emulation. BFF local settings belong in bff/local.settings.json. Build bundles BFF dependencies and copies staticwebapp.config.json into dist/. Deploy dist/ + bff/ together, and functions/ separately. Generated home, CRUD, and login pages share the Next.js presentation templates. Preserve their Tailwind styles and the light/dark defaults in src/style.css when editing them."
       : "Use http://localhost:3000 for the app, or the SWA emulator port (4280) when testing SWA authentication. `swallowkit dev` runs Next.js and standalone Functions (7071). The BFF remains Next.js API routes.",
     pm: context.packageManager,
     runCmd,

package/src/core/project/agent-templates/AGENTS.md

@@ -41,7 +41,14 @@ When a SwallowKit capability, project structure, or ownership boundary affects
 a design decision, inspect the current project and the currently available
 SwallowKit interfaces before deciding.
 
-Prefer the `swallowkit_*` MCP tools when available.
+Prefer the `swallowkit_*` MCP tools when available, with one exception: every
+MCP response reports the SwallowKit version that answered in
+`metadata.swallowkitVersion` and `metadata.mcp`. If that version is older than
+the project's installed SwallowKit (`{{runCmd}} swallowkit --version`), or
+`metadata.warnings` contains `mcp-older-than-project`, its capabilities,
+boundaries, and plan/apply contracts may be outdated for this project. Use
+`{{runCmd}} swallowkit machine ...` instead and follow the response's
+`nextActions` (for example `{{runCmd}} swallowkit configure-mcp`).
 
 If MCP is unavailable, use the machine interface:
 
@@ -263,6 +270,18 @@ SwallowKit should generate framework-owned CRUD artifacts.
 
 Do not manually recreate boilerplate that SwallowKit owns.
 
+When the task must not change Bicep or other infrastructure, still scaffold the
+model: pass `--skip-infra` to `plan scaffold` / `apply scaffold` (MCP
+`skipInfra: true`, or `swallowkit scaffold --skip-infra`). Nothing under
+`infra/` changes, the plan reports `infra-skipped`, and `verify project` still
+passes. Generate only the pending container migration later with
+`{{runCmd}} swallowkit migrations add-model <model>`.
+
+Treat plan `warnings` as decisions to make, not noise. In particular,
+`user-scoped-data-without-auth` means the model looks per-user (for example a
+`/userId` partition key) while authentication is not configured, so generated
+CRUD would let any caller read and write every document.
+
 ## Authentication
 
 Authentication is a **plan/apply operation**, not a free-form config edit.
@@ -458,9 +477,19 @@ same generated structure.
 - Re-export models from `shared/index.ts`.
 - `id` is a required `z.string()`; only `createdAt` / `updatedAt` are optional
   backend-managed fields.
-- Models may declare `partitionKey`, `authPolicy`, `displayName`, and
-  `connectorConfig` as exported constants. Exact formats:
+- Models may declare `partitionKey`, `authPolicy`, `displayName`,
+  `references`, and `connectorConfig` as exported constants. Exact formats:
   `{{runCmd}} swallowkit machine inspect capabilities` (modelDeclarations).
+- A string field named `<model>Id` is treated as a foreign key only when that
+  model exists in `shared/models`. Declare other references explicitly with
+  `export const references = { authorId: 'User' };` (map a field to `false`
+  to opt out).
+- Native C#/Python schema types come from Zod, not field names: use
+  `z.iso.datetime()` / `z.iso.date()` for date values (`createdAt` stays a
+  string), `z.number().int()` for integers, and inline `z.object` for nested
+  classes. Length/range/regex/item constraints are enforced natively; formats
+  such as email remain Zod (BFF) validation. See `inspect capabilities`
+  (sharedModels.nativeSchemaMapping).
 - Cosmos DB containers use PascalCase plural names and default to `/id` as the
   partition key unless the model declares another key, e.g.
   `export const partitionKey = '/learnerId';` (the field must exist in the
@@ -517,3 +546,10 @@ Do:
 - verify before final semantic review
 
 Use `{{pm}}`, the package manager selected for this project. Do not introduce another package manager or lockfile. Use `{{runCmd}} swallowkit` for the project-local CLI. The MCP launcher intentionally resolves `latest` independently.
+Exception for prerelease projects: when the project's SwallowKit is newer than
+the published `latest` (for example `2.0.0-alpha.3` while `latest` is `1.1.2`),
+`.mcp.json` may pin `SWALLOWKIT_MCP_VERSION` to the project version, and a
+`latest` launcher that supports it hands the session to the project-installed
+MCP. Run `{{runCmd}} swallowkit configure-mcp` to re-select the version (it
+returns to `latest` once `latest` is at least the project version). Until MCP
+reports the project version, prefer `{{runCmd}} swallowkit machine ...`.