swallowkit 2.0.0-alpha.3 → 2.0.0-alpha.5

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-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.
@@ -300,6 +319,20 @@ custom endpoints that derive the scoping key (e.g. `learnerId`) from the
 verified principal — never from the request body — and restrict the generated
 write endpoints to admin roles.
 
+Configure authentication with `plan auth` / `apply auth` **before** declaring
+`authPolicy`. Without authentication, an explicit policy
+blocks plan/apply/scaffold with `auth-policy-without-auth` before file writes;
+follow `nextActions`, then re-plan. Do not remove a required policy just to pass
+generation.
+An empty `authPolicy = {}` means no explicit policy; it does not enable authentication.
+
+With named `auth.schemes`, define `auth.authorization.policies` selecting the
+required schemes and roles, then use `authPolicy = { policy: 'adminOnly' }` (or
+read/write policy names). Role-only declarations do not select a named scheme
+and block with `auth-policy-requires-named-policy`. Conversely, single-provider
+`auth.provider` supports role lists only; a named policy (including a named
+`defaultPolicy`) blocks with `auth-named-policy-requires-named-scheme`.
+
 ## Verification Is a Completion Gate
 
 Before treating an agent-driven implementation as complete, run SwallowKit
@@ -311,8 +344,17 @@ verification:
 
 or the equivalent MCP operation.
 
-Verification covers SwallowKit structural correctness, drift, type correctness,
-and configured project checks.
+Default checks are `structure`, `drift`, `typecheck`, `backend-build`, plus
+configured project checks. `backend-build` checks standalone `functions/`:
+C# uses `dotnet build`, TypeScript uses the project's `tsc --noEmit`, and Python
+uses Python 3 `compileall` (syntax only, not imports or type checking), preferring
+`functions/.venv` over PATH. Missing toolchains are `skip` with an explanation;
+a skipped backend check is **not** evidence that the backend works. Restore the
+toolchain and re-run it before claiming backend validation.
+
+Root `build` scripts do not replace standalone backend verification. To include
+frontend production builds, use `--checks "structure,drift,typecheck,backend-build,build"`.
+Quote comma-separated values in PowerShell.
 
 When verification fails, use the structured failure explanation:
 
@@ -455,12 +497,24 @@ same generated structure.
 - Model schema files use `shared/models/{kebab-case}.ts`.
 - The Zod schema constant and inferred TypeScript type use the same PascalCase
   name: `export const Todo = z.object(...); export type Todo = z.infer<typeof Todo>`.
-- Re-export models from `shared/index.ts`.
+- Re-export models from `shared/index.ts`. create-model and plan/apply scaffold
+  append missing exports, including manually authored models. Manual exports
+  are allowed; this file has no managed markers and existing content is preserved.
 - `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 +571,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 ...`.

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

@@ -14,7 +14,9 @@ Always-on rules:
 - Inspect the current project and SwallowKit capabilities before making
   SwallowKit-dependent assumptions or asking questions the repository can answer.
 - Prefer `swallowkit_*` MCP tools.
-- Fall back to `{{runCmd}} swallowkit machine ...` when MCP is unavailable.
+- Fall back to `{{runCmd}} swallowkit machine ...` when MCP is unavailable, or
+  when an MCP response's `metadata.swallowkitVersion` is older than the project's
+  SwallowKit (`metadata.warnings` contains `mcp-older-than-project`).
 - Inspect responsibility boundaries before editing framework-related files.
 - Never hand-edit deterministic SwallowKit-managed artifacts.
 - Add auth schemes only via plan/apply auth; never hand-write `auth.schemes`
@@ -23,6 +25,10 @@ Always-on rules:
 - Use plan/apply for deterministic generation.
 - Respect all `requires-human` states and provisioning approval gates.
 - Run SwallowKit verification before considering implementation complete.
+- Default verification includes `backend-build` for standalone Functions.
+  Skipped toolchains are not validation; Python compilation checks syntax only.
+- Configure auth via plan/apply auth before adding `authPolicy`; otherwise
+  scaffold blocks before file writes. Scaffold appends missing shared model exports.
 
 Task-specific SwallowKit Agent Skills are available under `.github/skills/`.
 Equivalent agent-agnostic runbooks are available under

package/src/core/project/agent-templates/copilot-instructions.md

@@ -13,7 +13,9 @@ Key rules:
 - Inspect current SwallowKit capabilities instead of assuming them.
 - Answer repository- and SwallowKit-inspectable questions before asking the human.
 - Prefer `swallowkit_*` MCP tools when available.
-- Otherwise use `{{runCmd}} swallowkit machine ...`.
+- Otherwise use `{{runCmd}} swallowkit machine ...`. Also use it when an MCP
+  response's `metadata.swallowkitVersion` is older than the project's SwallowKit
+  or `metadata.warnings` contains `mcp-older-than-project`.
 - Inspect responsibility boundaries before editing framework-related files.
 - Never hand-edit deterministic SwallowKit-managed artifacts.
 - Add auth schemes only via plan/apply auth; never hand-write `auth.schemes`
@@ -22,6 +24,10 @@ Key rules:
 - Use plan/apply for deterministic generation.
 - Respect `requires-human` states and other human approval gates.
 - Run SwallowKit verification before completion.
+- Default verification includes `backend-build` for standalone Functions.
+  Skipped toolchains are not validation; Python compilation checks syntax only.
+- Configure auth via plan/apply auth before adding `authPolicy`; otherwise
+  scaffold blocks before file writes. Scaffold appends missing shared model exports.
 
 Task-specific SwallowKit Agent Skills live under `.github/skills/`.
 Agent-agnostic equivalents live under `.swallowkit/workflows/`.

package/src/core/project/agent-templates/shared-models.instructions.md

@@ -18,8 +18,9 @@ source-of-truth models, subject to the current result of
 - `createdAt` and `updatedAt` are **optional** string fields
   (`z.string().optional()`). The backend manages their values.
 - Export a `displayName` string for UI display.
-- Re-export every model from `shared/index.ts`, outside managed markers where
-  applicable.
+- create-model and plan/apply scaffold append missing model exports to
+  `shared/index.ts`, including manually authored models. Manual exports are
+  allowed; there are no managed markers and existing content is preserved.
 - For relationships, use nested schemas rather than duplicating model shapes.
 
 ## Optional model declarations (exact formats)
@@ -30,7 +31,7 @@ These are the only declarations SwallowKit parses from a model file:
 // Cosmos DB partition key (default '/id'). Must reference a schema field.
 export const partitionKey = '/learnerId';
 
-// Role-based access control on generated CRUD.
+// Role-based access control on generated CRUD (requires plan/apply auth first).
 export const authPolicy = { roles: ['admin'] };
 // or: { read: ['user'], write: ['admin'] } or: { policy: 'adminOnly' }
 
@@ -48,6 +49,13 @@ export const connectorConfig = {
 The full machine-readable contract:
 `{{runCmd}} swallowkit machine inspect capabilities`
 
+An explicit `authPolicy` without authentication blocks plan/apply/scaffold with
+`auth-policy-without-auth` before writing files. Follow `nextActions` to configure
+auth, then re-plan. Do not drop a required guard to bypass the prerequisite.
+For named `auth.schemes`, use named authorization policies selecting schemes
+and roles, referenced by `policy` or read/write names. Role-only declarations
+block with `auth-policy-requires-named-policy` rather than emitting missing helpers.
+
 After changing a model, do not manually patch generated artifacts.
 
 ## After changing a model