swallowkit 2.0.0-alpha.1 → 2.0.0-alpha.11

package/src/core/project/home-page.ts

@@ -0,0 +1,114 @@
+import { FrontendFramework } from "../../types";
+import { PackageManager, getCommands } from "../../utils/package-manager";
+import { adaptReactPage } from "../scaffold/react-ui-generator";
+
+export function buildHomePage(
+  frontend: FrontendFramework,
+  pm: PackageManager
+): string {
+  const framework = frontend === "react" ? "React" : "Next.js";
+  const page = `import { useState } from 'react';
+import Link from 'next/link';
+import { scaffoldConfig } from '@/lib/scaffold-config';
+
+export default function Home() {
+  const [greetingStatus, setGreetingStatus] = useState<'idle' | 'loading' | 'success' | 'error'>('idle');
+  const [message, setMessage] = useState('');
+
+  const testConnection = async () => {
+    setGreetingStatus('loading');
+    try {
+      const response = await fetch('/api/greet?name=SwallowKit');
+      const data = await response.json();
+      if (!response.ok) {
+        throw new Error(data.error || \`Server error: \${response.status}\`);
+      }
+      setMessage(data.message);
+      setGreetingStatus('success');
+    } catch (error) {
+      setMessage(error instanceof Error ? error.message : 'Failed to connect to Azure Functions');
+      setGreetingStatus('error');
+    }
+  };
+
+  return (
+    <div className="min-h-screen bg-gradient-to-br from-blue-50 to-indigo-50 dark:from-gray-900 dark:to-gray-800">
+      <div className="container mx-auto px-4 py-12">
+        <header className="text-center mb-16">
+          <h1 className="text-5xl font-bold text-gray-800 dark:text-white mb-4">
+            Welcome to SwallowKit
+          </h1>
+          <p className="text-xl text-gray-600 dark:text-gray-400">
+            ${framework} on Azure Static Web Apps + Functions + Cosmos DB — Zod schema sharing
+          </p>
+        </header>
+
+        <section className="max-w-2xl mx-auto mb-12">
+          <div className="bg-white dark:bg-gray-800 rounded-xl p-8 border border-gray-200 dark:border-gray-700">
+            <h2 className="text-2xl font-semibold mb-4 text-gray-900 dark:text-gray-100">
+              Test BFF → Functions Connection
+            </h2>
+            <button
+              onClick={testConnection}
+              disabled={greetingStatus === 'loading'}
+              className="px-6 py-3 bg-blue-600 hover:bg-blue-700 disabled:bg-gray-400 text-white rounded-lg font-medium transition-colors"
+            >
+              {greetingStatus === 'loading' ? 'Testing...' : 'Test Connection'}
+            </button>
+            {greetingStatus === 'success' && (
+              <div role="status" className="mt-4 p-4 bg-green-50 dark:bg-green-900/20 border border-green-200 dark:border-green-800 rounded-lg">
+                <p className="text-green-800 dark:text-green-200 font-medium">✅ Connection successful!</p>
+                <p className="text-green-700 dark:text-green-300 text-sm mt-1">{message}</p>
+              </div>
+            )}
+            {greetingStatus === 'error' && (
+              <div role="alert" className="mt-4 p-4 bg-red-50 dark:bg-red-900/20 border border-red-200 dark:border-red-800 rounded-lg">
+                <p className="text-red-800 dark:text-red-200 font-medium">❌ Connection failed</p>
+                <p className="text-red-700 dark:text-red-300 text-sm mt-1">{message}</p>
+              </div>
+            )}
+          </div>
+        </section>
+
+        {scaffoldConfig.models.length > 0 ? (
+          <section className="max-w-6xl mx-auto">
+            <h2 className="text-3xl font-bold mb-8 text-gray-900 dark:text-gray-100">Your Models</h2>
+            <div className="grid gap-6 grid-cols-1 md:grid-cols-2 lg:grid-cols-3">
+              {scaffoldConfig.models.map((model) => (
+                <Link
+                  key={model.name}
+                  href={model.path}
+                  className="block p-8 bg-white dark:bg-gray-800 border border-gray-200 dark:border-gray-700 rounded-xl hover:shadow-lg hover:border-blue-400 dark:hover:border-blue-600 transition-all"
+                >
+                  <h3 className="text-2xl font-semibold mb-2 text-gray-900 dark:text-gray-100">{model.label}</h3>
+                  <p className="text-gray-600 dark:text-gray-400">Manage {model.label.toLowerCase()}</p>
+                </Link>
+              ))}
+            </div>
+          </section>
+        ) : (
+          <section className="max-w-2xl mx-auto text-center">
+            <div className="bg-white dark:bg-gray-800 rounded-xl p-12 border border-gray-200 dark:border-gray-700">
+              <h2 className="text-2xl font-semibold mb-4 text-gray-900 dark:text-gray-100">Get Started</h2>
+              <p className="text-gray-600 dark:text-gray-400 mb-6">
+                Create your first model with Zod and generate CRUD operations automatically.
+              </p>
+              <code className="block bg-gray-100 dark:bg-gray-900 p-4 rounded text-left text-sm">
+                ${getCommands(pm).exec} swallowkit scaffold shared/models/your-model.ts
+              </code>
+            </div>
+          </section>
+        )}
+
+        <footer className="mt-16 text-center text-gray-600 dark:text-gray-400 text-sm">
+          <p>Built with SwallowKit</p>
+        </footer>
+      </div>
+    </div>
+  );
+}
+`;
+  return frontend === "react"
+    ? adaptReactPage(page)
+    : `'use client'\n\nexport const dynamic = 'force-dynamic';\n\n${page}`;
+}

package/src/core/project/mcp-config.ts

@@ -0,0 +1,84 @@
+/**
+ * Project-scoped MCP launcher version management.
+ *
+ * `.mcp.json` intentionally resolves `swallowkit@latest` so that projects created
+ * with older releases still get the current stable tools. A prerelease project can
+ * be newer than `latest`; in that case the launcher is pinned to the project
+ * version until a stable release that understands project-aware delegation catches up.
+ */
+
+import { spawnSync } from "child_process";
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+import { compareSemver, isPrerelease, parseSemver } from "../../utils/semver";
+
+export const MCP_CONFIG_PATH = ".mcp.json";
+export const MCP_VERSION_ENV = "SWALLOWKIT_MCP_VERSION";
+export const MCP_LATEST = "latest";
+
+export interface McpPinDecision {
+  version: string;
+  reason: string;
+}
+
+/**
+ * Decide the SWALLOWKIT_MCP_VERSION value for a project that uses `projectVersion`.
+ * Uses `latest` unless the project version is newer than the published `latest`.
+ * When the registry could not be reached, prereleases are pinned conservatively.
+ */
+export function resolveMcpPinVersion(projectVersion: string, publishedLatest: string | null): McpPinDecision {
+  if (!parseSemver(projectVersion)) {
+    return { version: MCP_LATEST, reason: `Project version ${projectVersion} is not a valid semantic version.` };
+  }
+  if (publishedLatest && parseSemver(publishedLatest)) {
+    const comparison = compareSemver(projectVersion, publishedLatest)!;
+    return comparison > 0
+      ? { version: projectVersion, reason: `Project version ${projectVersion} is newer than published latest ${publishedLatest}.` }
+      : { version: MCP_LATEST, reason: `Published latest ${publishedLatest} is the same as or newer than project version ${projectVersion}.` };
+  }
+  return isPrerelease(projectVersion)
+    ? { version: projectVersion, reason: `Published latest is unknown; prerelease ${projectVersion} is pinned so MCP matches the project.` }
+    : { version: MCP_LATEST, reason: "Published latest is unknown; stable projects keep latest." };
+}
+
+export function lookupPublishedLatestVersion(packageName: string, timeoutMs = 15000): string | null {
+  // Run outside the project so its devEngines/packageManager policy does not reject npm.
+  const result = spawnSync("npm", ["view", `${packageName}@latest`, "version"], {
+    cwd: os.tmpdir(),
+    encoding: "utf8",
+    timeout: timeoutMs,
+    shell: process.platform === "win32",
+    stdio: ["ignore", "pipe", "ignore"],
+  });
+  if (result.error || result.status !== 0) return null;
+  const version = String(result.stdout).trim().split(/\s+/).pop() ?? "";
+  return parseSemver(version) ? version : null;
+}
+
+export function readMcpConfigVersion(projectDir: string): string | null {
+  const configPath = path.join(projectDir, MCP_CONFIG_PATH);
+  if (!fs.existsSync(configPath)) return null;
+  try {
+    const config = JSON.parse(fs.readFileSync(configPath, "utf8"));
+    const value = config?.mcpServers?.swallowkit?.env?.[MCP_VERSION_ENV];
+    return typeof value === "string" ? value : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Update only the SwallowKit MCP version in .mcp.json, preserving all other content. */
+export function writeMcpConfigVersion(projectDir: string, version: string): void {
+  const configPath = path.join(projectDir, MCP_CONFIG_PATH);
+  if (!fs.existsSync(configPath)) {
+    throw new Error(`${MCP_CONFIG_PATH} was not found. Run this command from a SwallowKit project root.`);
+  }
+  const config = JSON.parse(fs.readFileSync(configPath, "utf8"));
+  const server = config?.mcpServers?.swallowkit;
+  if (!server || typeof server !== "object") {
+    throw new Error(`${MCP_CONFIG_PATH} does not define mcpServers.swallowkit.`);
+  }
+  server.env = { ...(server.env ?? {}), [MCP_VERSION_ENV]: version };
+  fs.writeFileSync(configPath, `${JSON.stringify(config, null, 2)}\n`);
+}

package/src/core/project/react-project.ts

@@ -1,6 +1,9 @@
 import * as fs from "fs";
 import * as path from "path";
 import { BackendLanguage } from "../../types";
+import { buildReactDevWatchIgnoredSource } from "../../utils/react-dev";
+import { DEFAULT_AZURE_PYTHON_VERSION } from "../../utils/python-uv";
+import { buildHomePage } from "./home-page";
 import {
   PackageManager,
   getCommands,
@@ -45,7 +48,8 @@ export function buildReactSwaConfig() {
 
 export function createReactProject(
   projectDir: string,
-  projectName: string
+  projectName: string,
+  pm: PackageManager = "pnpm"
 ): void {
   write(
     projectDir,
@@ -117,7 +121,11 @@ export default defineConfig({
     '@': fileURLToPath(new URL('.', import.meta.url)),
     '@${projectName}/shared': fileURLToPath(new URL('./shared/index.ts', import.meta.url)),
   } },
-  server: { port: 3000, strictPort: true },
+  server: {
+    port: 3000,
+    strictPort: true,
+    watch: { ignored: ${buildReactDevWatchIgnoredSource("fileURLToPath(new URL('.', import.meta.url))")} },
+  },
   build: { outDir: 'dist' },
 });
 `
@@ -126,9 +134,9 @@ export default defineConfig({
     projectDir,
     "index.html",
     `<!doctype html>
-<html lang="en">
+<html lang="en" class="h-full antialiased">
   <head><meta charset="UTF-8" /><meta name="viewport" content="width=device-width, initial-scale=1.0" /><title>SwallowKit</title></head>
-  <body><div id="root"></div><script type="module" src="/src/main.tsx"></script></body>
+  <body class="min-h-full flex flex-col"><div id="root" class="flex flex-1 flex-col"></div><script type="module" src="/src/main.tsx"></script></body>
 </html>
 `
   );
@@ -169,31 +177,34 @@ export default function App() {
   write(
     projectDir,
     "src\\Home.tsx",
-    `import { useState } from 'react';
-import { Link } from 'react-router-dom';
-import { scaffoldConfig } from '@/lib/scaffold-config';
-
-export default function Home() {
-  const [message, setMessage] = useState('');
-  async function testConnection() {
-    try {
-      const response = await fetch('/api/greet?name=SwallowKit');
-      if (!response.ok) throw new Error('BFF request failed (' + response.status + ')');
-      const data = await response.json();
-      setMessage(data.message);
-    } catch (error) { setMessage(error instanceof Error ? error.message : String(error)); }
+    buildHomePage("react", pm)
+  );
+  write(projectDir, "src\\style.css", `@import "tailwindcss";
+
+:root {
+  --background: #ffffff;
+  --foreground: #171717;
+}
+
+@theme inline {
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+  --font-sans: Arial, Helvetica, sans-serif;
+}
+
+@media (prefers-color-scheme: dark) {
+  :root {
+    --background: #0a0a0a;
+    --foreground: #ededed;
   }
-  return <main className="container mx-auto p-8">
-    <h1 className="text-3xl font-bold mb-4">SwallowKit + React</h1>
-    <p>React SPA → SWA managed Functions BFF → standalone Functions → Cosmos DB</p>
-    <button className="my-4 bg-blue-600 text-white rounded px-4 py-2" onClick={testConnection}>Test backend connection</button>
-    <p role="status">{message}</p>
-    <nav>{scaffoldConfig.models.map(model => <p key={model.name}><Link to={model.path}>{model.label}</Link></p>)}</nav>
-  </main>;
 }
-`
-  );
-  write(projectDir, "src\\style.css", '@import "tailwindcss";\n');
+
+body {
+  background: var(--background);
+  color: var(--foreground);
+  font-family: Arial, Helvetica, sans-serif;
+}
+`);
   write(
     projectDir,
     "lib\\scaffold-config.ts",
@@ -375,6 +386,17 @@ The BFF stays separate even with \`--no-functions\`; \`--no-swa\` starts only th
 direct Vite/BFF servers (no same-origin API routing or SWA authentication).
 Core Tools v4 must already be available. Start Cosmos DB Emulator manually if
 this application needs Cosmos; SwallowKit never starts it.
+${backend === "python" ? `
+Python environments use normal uv discovery and user settings, including installed
+Python, \`.python-version\`, and \`UV_PYTHON\`. Local Python is not pinned to the Azure
+deployment runtime (${DEFAULT_AZURE_PYTHON_VERSION}). Functions uses \`functions/.venv\`; scaffold uses
+\`functions/.codegen-venv\`. Existing environments are never cleared automatically.
+When switching interpreters, explicitly recreate them with uv. Do not disable
+Windows application-control policy to run an unsigned interpreter.
+` : backend === "csharp" ? `
+The .NET isolated backend starts with \`dotnet run\` so extensions are loaded from
+the build output. Vite does not watch \`functions/\` or \`bff/\` build artifacts.
+` : ""}
 
 Local BFF settings live in \`bff/local.settings.json\` (gitignored). Backend settings
 live in \`functions/local.settings.json\`. Keep their secrets out of source control.
@@ -385,7 +407,7 @@ live in \`functions/local.settings.json\`. Keep their secrets out of source cont
 \`\`\`sh
 ${pm} run build
 ${cmd.exec} swallowkit machine verify project
-${cmd.exec} swallowkit machine verify project --checks structure,drift,typecheck,build
+${cmd.exec} swallowkit machine verify project --checks "structure,drift,typecheck,backend-build,build"
 \`\`\`
 
 The build compiles shared schemas, checks the SPA, builds static assets, and

package/src/core/project/state.ts

@@ -57,6 +57,76 @@ export function deletePlanState(planId: string, projectRoot: string = process.cw
   }
 }
 
+function provisionRunPath(runId: string, projectRoot: string): string {
+  if (!/^[a-f0-9]{12}$/.test(runId)) throw new Error("Invalid provision run ID.");
+  return path.join(projectRoot, SWALLOWKIT_STATE_DIR, "provision", `${runId}.json`);
+}
+
+export function saveProvisionRun<T extends { runId: string }>(run: T, projectRoot: string = process.cwd()): void {
+  ensureStateDir(projectRoot);
+  const file = provisionRunPath(run.runId, projectRoot);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const temporary = `${file}.tmp-${process.pid}`;
+  fs.writeFileSync(temporary, `${JSON.stringify(run, null, 2)}\n`, { encoding: "utf-8", mode: 0o600 });
+  fs.renameSync(temporary, file);
+}
+
+export function loadProvisionRun<T>(runId: string, projectRoot: string = process.cwd()): T | null {
+  const file = provisionRunPath(runId, projectRoot);
+  if (!fs.existsSync(file)) return null;
+  // Unlike a preview, discarding a corrupt execution checkpoint could replay Azure writes.
+  return JSON.parse(fs.readFileSync(file, "utf-8")) as T;
+}
+
+export function listProvisionRuns<T>(projectRoot: string = process.cwd()): T[] {
+  const directory = path.join(projectRoot, SWALLOWKIT_STATE_DIR, "provision");
+  if (!fs.existsSync(directory)) return [];
+  return fs.readdirSync(directory).filter((name) => /^[a-f0-9]{12}\.json$/.test(name))
+    .map((name) => loadProvisionRun<T>(name.slice(0, -5), projectRoot)!);
+}
+
+/** A live local executor must not share an Azure target with another executor. */
+export function lockProvisionTarget(key: string, projectRoot: string = process.cwd()): () => void {
+  if (!/^[a-f0-9]{64}$/.test(key)) throw new Error("Invalid provision lock key.");
+  const directory = path.join(ensureStateDir(projectRoot), "provision");
+  fs.mkdirSync(directory, { recursive: true });
+  const file = path.join(directory, `${key}.lock`);
+  const create = () => {
+    const descriptor = fs.openSync(file, "wx", 0o600);
+    try { fs.writeFileSync(descriptor, String(process.pid)); } finally { fs.closeSync(descriptor); }
+  };
+  try {
+    create();
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+    const recoveryFile = `${file}.recovery`;
+    let descriptor: number;
+    try {
+      descriptor = fs.openSync(recoveryFile, "wx", 0o600);
+    } catch (recoveryError) {
+      if ((recoveryError as NodeJS.ErrnoException).code !== "EEXIST") throw recoveryError;
+      throw new Error("Provision lock recovery is already in progress. Inspect the checkpoint before retrying.");
+    }
+    fs.closeSync(descriptor);
+    try {
+      const pid = Number(fs.readFileSync(file, "utf-8"));
+      if (!Number.isInteger(pid) || pid < 1) throw new Error("Invalid provision lock; inspect the checkpoint before removing the lock.");
+      try {
+        process.kill(pid, 0);
+      } catch (probeError) {
+        if ((probeError as NodeJS.ErrnoException).code !== "ESRCH") throw probeError;
+        fs.unlinkSync(file);
+        create();
+        return () => fs.unlinkSync(file);
+      }
+      throw new Error("Another local provision executor is using this Azure target. Inspect its run; do not start a second deployment.");
+    } finally {
+      fs.unlinkSync(recoveryFile);
+    }
+  }
+  return () => fs.unlinkSync(file);
+}
+
 const LAST_VERIFY_FILE = "last-verify.json";
 
 export function saveLastVerifyState(result: unknown, projectRoot: string = process.cwd()): void {

package/src/core/project/workflows.ts

@@ -36,10 +36,10 @@ export function buildWorkflowDocs(runCmd: string): WorkflowDoc[] {
     title: "Add a new model (autonomous loop)",
     skillName: "swallowkit-add-model",
     skillDescription:
-      "Add a new data model to a SwallowKit project and deterministically derive CRUD Functions, BFF routes, UI pages, and Cosmos DB infra from it using the plan/apply/verify loop. Use when asked to add a model, entity, resource, table, or a new CRUD feature.",
+      "Add a new persistent model, including models with custom APIs, and generate required infrastructure. Derive CRUD Functions, BFF routes, and UI only when needed using the plan/apply/verify loop. Use when asked to add a model, entity, resource, table, or a new CRUD feature.",
     content: `# Workflow: Add a new model
 
-Goal: add a data model and derive CRUD/BFF/UI/infra deterministically.
+Goal: add a persistent model and generate its required infrastructure, even with custom APIs. A hand-written model alone is not complete.
 
 ## Responsibility boundary
 
@@ -51,15 +51,43 @@ Goal: add a data model and derive CRUD/BFF/UI/infra deterministically.
 
 1. Create the model file (deterministic template):
    \`${runCmd} swallowkit machine generate model <name> --overwrite never\`
+   - This is the machine equivalent of \`${runCmd} swallowkit create-model <name>\`.
+     Preserve existing schemas; model creation alone does not generate a Cosmos DB container.
 2. Edit \`shared/models/<name>.ts\` — add domain fields (free-form authoring).
-3. Compute the change plan (writes nothing):
+   - Native C#/Python types follow Zod, not names: \`z.iso.datetime()\` for dates, \`z.number().int()\` for integers.
+   - \`<model>Id\` fields reference a model only when it exists in \`shared/models\`; otherwise declare
+     \`export const references = { fieldId: 'Model' }\` (or \`false\` to opt out).
+3. When CRUD is needed, compute the change plan (writes nothing):
    \`${runCmd} swallowkit machine plan scaffold <name>\`
    - \`status: "requires-human"\` → review \`data.conflicts\`; only proceed with \`--approve\` if overwriting is intended.
-4. Apply:
+   - Must not change Bicep/infrastructure? Add \`--skip-infra\` to plan and apply. Nothing under \`infra/\` changes and
+     the plan warns \`infra-skipped\`; later run \`${runCmd} swallowkit migrations add-model <name>\` to add only the container migration.
+     State the reason and pending infrastructure work; a passing verify does not mean the model is complete or deployment-ready.
+   - Read \`data.warnings\`. \`user-scoped-data-without-auth\` means generated CRUD would expose every user's documents;
+     add auth (\`swallowkit-add-auth\`) and owner-scoped ai-authored endpoints before exposing the model.
+   - \`auth-policy-without-auth\` blocks generation before file writes: configure authentication with plan/apply auth,
+     then re-plan. Do not remove a required policy to bypass this prerequisite.
+     For named \`auth.schemes\`, define named authorization policies selecting schemes/roles and reference them from
+     \`authPolicy.policy\` or read/write names; role-only declarations block with \`auth-policy-requires-named-policy\`.
+     Single-provider \`auth.provider\` supports role lists only; named policies block with \`auth-named-policy-requires-named-scheme\`.
+   - Scaffold appends missing exports to \`shared/index.ts\` for hand-authored models too.
+     Manual exports are allowed; no managed markers exist in that file.
+   - If custom APIs replace CRUD, skip scaffold (including \`--api-only\`, which still generates CRUD).
+     Review \`${runCmd} swallowkit migrations add-model <name> --dry-run\`, then run
+     \`${runCmd} swallowkit migrations add-model <name>\` to generate only the container migration and generation records.
+     Keep the schema exported from \`shared/index.ts\`. External connector models need their connector mapping, not a Cosmos container.
+4. Apply the reviewed CRUD scaffold plan, if needed:
    \`${runCmd} swallowkit machine apply scaffold --plan <planId>\`
 5. Verify:
-   \`${runCmd} swallowkit machine verify project\`
+   - Inspect \`machine inspect entities\`, \`machine inspect infra\`, \`machine inspect artifacts\`, and \`machine inspect drift\`.
+     Match the model's container name and partition key to its Bicep, \`sourceModel\` in
+     \`infra/migrations/manifest.json\`, and \`.swallowkit/artifacts.json\`.
+     For a baseline-owned container, verify the tracked definition and \`infra/main.bicep\` wiring instead of requiring a new migration.
+     Do not hand-edit a checksum-locked baseline or an existing migration.
+   - Run \`${runCmd} swallowkit machine verify project\`.
    - \`summary.done: false\` → \`${runCmd} swallowkit machine explain failure\` and repair, then re-verify.
+   - Required infrastructure still missing? Report the reason and remaining work, not completion or deployment readiness.
+     Local generation does not provision Azure; follow the separate provision workflow and human approval gates.
 6. If \`dev-seeds/\` exists, update seed JSON for the new model. Seeds are only
    applied by \`${runCmd} swallowkit dev --seed-env <environment>\` — editing the
    JSON alone does nothing.
@@ -153,7 +181,7 @@ the scoping key from the verified principal, never from the request body.
     title: "Verify and repair loop",
     skillName: "swallowkit-verify-repair",
     skillDescription:
-      "Converge a SwallowKit project to a verified state: run structure/drift/typecheck (and build/lint/test) checks, read evidence with explain failure, repair, and repeat. Use after any code or schema change, when verification fails, when the build/lint/tests are broken, or before finishing a task.",
+      "Converge a SwallowKit project to a verified state: run structure/drift/typecheck/backend-build (and build/lint/test) checks, read evidence with explain failure, repair, and repeat. Use after any code or schema change, when verification fails, when the build/lint/tests are broken, or before finishing a task.",
     content: `# Workflow: Verify and repair
 
 Goal: converge the project to a verified state after any change.
@@ -161,14 +189,16 @@ Goal: converge the project to a verified state after any change.
 ## Loop
 
 1. \`${runCmd} swallowkit machine verify project\`
-   - default checks: structure, drift, typecheck (+ project-specific checks from swallowkit.config \`verify.checks\`)
-   - opt-in heavier checks: \`--checks structure,drift,typecheck,build,lint,test\`
+   - default checks: structure, drift, typecheck, backend-build (+ project-specific checks from swallowkit.config \`verify.checks\`)
+   - backend-build: standalone C# \`dotnet build\`, TypeScript \`tsc --noEmit\`, Python 3 \`compileall\` (syntax only).
+     Missing toolchains are skipped with a reason, not proof of a working backend. Restore them and re-run.
+   - opt-in heavier checks: \`--checks "structure,drift,typecheck,backend-build,build,lint,test"\` (quote CSV in PowerShell)
 2. If \`summary.done\` is false:
    - \`${runCmd} swallowkit machine explain failure\` → evidence (logTail, findings, violations) and suggestedActions per check.
    - Repair:
      - \`drift\` failures → follow each finding's \`repairAction\` (usually re-run plan/apply scaffold).
      - \`structure\` failures → follow \`suggestedFix\` per violation.
-     - \`typecheck\`/\`build\`/\`lint\`/\`test\` failures → fix the code in ai-authored files.
+     - \`typecheck\`/\`backend-build\`/\`build\`/\`lint\`/\`test\` failures → fix the source code, not generated artifacts.
 3. Repeat until \`summary.done: true\`.
 
 ## Exit criteria
@@ -195,9 +225,14 @@ Goal: bootstrap Azure once, then apply only pending versioned infrastructure mig
   \`status: "requires-human"\` and \`requiresApproval: true\` by design.
 - Never pass \`--approve\` to \`apply provision\` unless a human explicitly
   instructed you to provision in this session.
+- This plan/apply workflow is for agents. Humans normally run \`swallowkit provision\`
+  directly; do not switch to that command to bypass the agent approval gate.
 - Inspect infra locally first — no \`az\` calls are needed for inspection.
 - Never edit an applied migration. Create a corrective migration instead.
 - Never use \`--reconcile\` for an ordinary model or resource addition.
+- A local az error/timeout or Ctrl+C does not prove Azure failed. Never
+  re-submit, cancel, or delete a deployment to repair a wait or bookkeeping failure.
+- Respect \`status\`, \`outcome\`, and \`nextActions\`, not just \`ok\`.
 
 ## Steps
 
@@ -205,7 +240,7 @@ Goal: bootstrap Azure once, then apply only pending versioned infrastructure mig
    \`${runCmd} swallowkit machine inspect infra\`
    - review parameters, modules, outputs, and container wiring warnings.
 2. Compute the provisioning plan (no resources are created):
-   \`${runCmd} swallowkit machine plan provision -g <resource-group> --location <region>\`
+   \`${runCmd} swallowkit machine plan provision -g <resource-group> --location <region> --swa-location <swa-region>\`
   - the plan reports \`bootstrap\`, \`migrate\`, \`noop\`, or \`adoption-required\`.
   - it lists only pending migrations and the exact \`az\` commands that would run.
   - for an older untagged environment, first run \`${runCmd} swallowkit migrations init --legacy-baseline\`, then plan with \`--adopt-existing --baseline 0 --what-if\`.
@@ -213,12 +248,35 @@ Goal: bootstrap Azure once, then apply only pending versioned infrastructure mig
 3. Present the plan to the human and wait for explicit approval.
 4. Only after approval:
    \`${runCmd} swallowkit machine apply provision --plan <planId> --approve\`
-5. Verify the deployment outputs and report them.
+5. If \`in-progress\`, \`unknown\`, or \`partial\`, retain the execution
+   checkpoint and read/wait for the original deployment:
+   \`${runCmd} swallowkit machine inspect provision --plan <runId> --wait-seconds 300\`.
+   Inspection never writes Azure tags or the local ledger.
+6. After fresh explicit human approval, resume:
+   \`${runCmd} swallowkit machine apply provision --plan <runId> --approve\`.
+   Attempted deployments are not re-submitted; remaining reviewed steps and
+   tags/ledger finish only after Azure \`Succeeded\`.
+7. Report completion only when \`status: "complete"\` and
+   \`outcome: "succeeded"\`. Never report deployment output secrets.
+
+For an older untracked bootstrap, plan with \`--resume-deployment <name>\`
+and the original RG, subscription and regions. Recovery compares its ARM
+template and non-secure parameters to local Bicep before approval. Mismatch,
+unreadable evidence or secure parameters block; do not work around this by
+using reconcile/adoption or replacing the migration manifest.
 
 ## Terminal states
 
 \`apply provision\` without \`--approve\` fails with \`approval-required\` —
 this is the guardrail working as intended, not an error to work around.
+
+Azure \`Running\`/\`Accepted\` means \`in-progress\`. An unreadable or missing
+deployment means \`unknown\`, not Azure failure. Azure \`Failed\`/\`Canceled\`
+returns sanitized Azure and operation causes. Azure \`Succeeded\` with incomplete
+tag/ledger writes means \`partial\`; resume bookkeeping without redeploying.
+The default wait is 300 seconds (0-3600 via \`--wait-seconds\`), not unlimited.
+Warning-only stderr with exit 0 is accepted. Diagnostics report local exit,
+signal, elapsed time and truncated/redacted output separately from Azure state.
 `,
   };
 
@@ -247,7 +305,9 @@ under \`.github/skills/\` so skills-aware agents load them automatically.
 
 - **ai-authored** (write freely): \`shared/models/\`, business logic, custom pages/components, tests.
 - **deterministic** (never hand-edit): artifacts generated by SwallowKit (see \`.swallowkit/artifacts.json\`) and \`.swallowkit/\` metadata. Change models/config and regenerate via plan/apply.
-- **shared** (edit outside markers): \`infra/main.bicep\`, \`functions/function_app.py\`, \`shared/index.ts\`.
+- **shared**: \`shared/index.ts\` allows manual exports (no markers; SwallowKit appends missing entries).
+  For Python \`functions/function_app.py\`, edit outside the registration marker.
+- **infrastructure**: baseline \`infra/\` files are checksum-locked by \`infra/migrations/manifest.json\`; add resources as new migrations (\`swallowkit create-migration <slug>\`, \`swallowkit migrations add-model <model>\`).
 
 Full machine-readable contract: \`${runCmd} swallowkit machine inspect boundaries\`
 `,