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

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:
 
@@ -217,6 +224,10 @@ required.
 
 Never invent or implicitly grant human approval.
 
+Humans normally invoke `swallowkit provision` directly. Its invocation requests
+execution without an additional confirmation. Agents must still use the
+machine/MCP approval flow and must not switch to normal CLI to bypass it.
+
 ## Model Changes
 
 For an existing model change, the normal pattern is:
@@ -263,6 +274,55 @@ SwallowKit should generate framework-owned CRUD artifacts.
 
 Do not manually recreate boilerplate that SwallowKit owns.
 
+### Persistent models require infrastructure, even with custom APIs
+
+Whenever adding a persistent model, execute the installed SwallowKit model
+creation and infrastructure generation workflow, whether or not it has custom
+APIs. A hand-written model alone is not complete.
+
+1. Create the source-of-truth schema with
+   `{{runCmd}} swallowkit machine generate model <model> --overwrite never`
+   (the machine equivalent of `{{runCmd}} swallowkit create-model <model>`),
+   then author its domain fields in `shared/models/` and check its export from
+   `shared/index.ts`. Preserve an existing hand-written schema; do not overwrite
+   it just to run the template command. Model creation alone does **not**
+   generate a Cosmos DB container.
+2. If generated CRUD is needed, use `machine plan scaffold <model>` →
+   `machine apply scaffold --plan <planId>` to derive Functions, BFF, UI,
+   OpenAPI/native schema assets as applicable, and the container migration.
+   `--api-only` skips UI only; it still generates CRUD Functions and BFF routes.
+   If custom APIs replace CRUD, do **not** scaffold unnecessary CRUD. Instead run
+   `{{runCmd}} swallowkit migrations add-model <model> --dry-run`, review the
+   changes, then `{{runCmd}} swallowkit migrations add-model <model>` to generate
+   only the Cosmos DB container migration and its generation records.
+3. Inspect `machine inspect entities`, `machine inspect infra`,
+   `machine inspect artifacts`, and `machine inspect drift`, then run
+   `{{runCmd}} swallowkit machine verify project`. Check that the model's
+   container name and partition key match the generated Bicep under
+   `infra/migrations/`, its `sourceModel` entry in
+   `infra/migrations/manifest.json`, and `.swallowkit/artifacts.json`.
+   An existing baseline-owned container may need no new migration; verify its
+   tracked definition and wiring in `infra/main.bicep` instead. External
+   `connectorConfig` models use the configured connector rather than Cosmos DB;
+   verify that mapping instead of inventing a Cosmos container.
+
+Do not hand-edit the checksum-locked baseline or an existing migration to add
+a container; use the current migration workflow. Generation is local, not Azure
+provisioning. Deployment still follows the provisioning approval gates below.
+
+If infrastructure generation must be deferred, state the reason and the pending
+container/migration work explicitly. For CRUD, pass `--skip-infra` to
+`plan scaffold` / `apply scaffold` (MCP `skipInfra: true`). Nothing under `infra/`
+changes and the plan reports `infra-skipped`. Generate the pending migration
+later with `{{runCmd}} swallowkit migrations add-model <model>`. Even if
+`verify project` passes, do not mark the persistent model complete or describe
+the project as deployment-ready while required infrastructure is missing.
+
+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 +360,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 +385,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:
 
@@ -359,6 +442,24 @@ Use the `swallowkit-provision` Agent Skill or runbook and never bypass its
 approval gate. A broad request to deploy does not itself grant the explicit
 approval required by that workflow.
 
+Provision applies Bicep once and tracks the original Azure deployment with a
+bounded wait. A local timeout/error, output truncation, or Ctrl+C is not proof
+that Azure failed. `in-progress` means Azure is Running/Accepted; `unknown`
+means its result could not be read; `partial` means Azure succeeded but
+tag/ledger completion is pending. Never re-submit Bicep, reconcile, adopt,
+cancel, or delete just to repair waiting or migration bookkeeping.
+
+Retain `.swallowkit/state/provision/` execution checkpoints. Use
+`{{runCmd}} swallowkit machine inspect provision --plan <runId> --wait-seconds 300`
+for read-only status/wait, and after explicit human approval use
+`{{runCmd}} swallowkit machine apply provision --plan <runId> --approve`
+to resume. `runId` equals the original `planId`; fingerprints, subscription,
+deployment identity and migration checks remain in force. Only
+`status: "complete"` / `outcome: "succeeded"` means Azure Succeeded plus verified
+tags and local ledger. Do not print deployment output secrets or raw `az --debug`.
+For older untracked baselines use `plan provision --resume-deployment <name>`
+with original target/regions; it blocks unless ARM/parameter evidence matches.
+
 ## SwallowKit Agent Skills and Runbooks
 
 SwallowKit installs task-specific Agent Skills under:
@@ -455,12 +556,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 +630,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`
@@ -22,7 +24,18 @@ Always-on rules:
   after apply).
 - Use plan/apply for deterministic generation.
 - Respect all `requires-human` states and provisioning approval gates.
+- Normal `swallowkit provision` is for humans. Agents must not use it to bypass
+  the machine/MCP approval flow.
+- Provision timeouts/Ctrl+C do not prove Azure failed. Inspect the original
+  execution checkpoint with `machine inspect provision --plan <runId>`; resume
+  `machine apply provision --plan <runId> --approve` only after explicit human
+  approval. Preserve checkpoints; never re-submit Bicep/reconcile/cancel/delete
+  to repair waiting or tag/ledger failures. Do not print deployment output secrets.
 - 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`
@@ -21,7 +23,19 @@ Key rules:
   after apply).
 - Use plan/apply for deterministic generation.
 - Respect `requires-human` states and other human approval gates.
+- Normal `swallowkit provision` is a human-facing deployment command. Agents must
+  use the machine/MCP approval flow, not normal CLI as an approval bypass.
+- Provision timeouts/Ctrl+C do not prove Azure failed. Read `status`, `outcome`,
+  and `nextActions`; inspect the original run with `machine inspect provision
+  --plan <runId>`, then resume `machine apply provision --plan <runId> --approve`
+  only after explicit human approval. Preserve execution checkpoints; never
+  re-submit Bicep or use reconcile/cancel/delete to repair waiting or tag/ledger
+  failures. Do not print deployment output secrets.
 - 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,9 +18,22 @@ 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.
+- For every new persistent model, follow the root `AGENTS.md` persistent-model
+  workflow even with custom APIs. Use `{{runCmd}} swallowkit machine generate model <model> --overwrite never`
+  (the `create-model` equivalent), preserve existing schemas, and generate the
+  required infrastructure. Model creation alone does not create a container.
+  Use plan/apply scaffold when CRUD is needed; for custom APIs replacing CRUD,
+  review `{{runCmd}} swallowkit migrations add-model <model> --dry-run`, then run
+  `{{runCmd}} swallowkit migrations add-model <model>` without unnecessary CRUD.
+  Check the model, container Bicep, migration manifest, and artifact ledger
+  correspondence, then inspect drift and verify project. For connector models,
+  verify the external connector mapping instead of generating a Cosmos container.
+  If generation is deferred, state why and what remains; do not claim completion
+  or deployment readiness while required infrastructure is missing.
 
 ## Optional model declarations (exact formats)
 
@@ -30,7 +43,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 +61,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

package/src/core/project/boundaries.ts

@@ -10,7 +10,9 @@
  * - shared:        マーカー区切りの共有領域。マーカー内は SwallowKit、外は自由。
  */
 
+import { getBackendLanguage } from "../config";
 import { ArtifactOwnership } from "../operations/file-session";
+import { BackendLanguage } from "../../types";
 import { inspectArtifacts } from "./artifacts";
 
 export type BoundaryZone = "deterministic" | "ai-authored" | "shared";
@@ -48,6 +50,8 @@ export interface BoundaryArtifact {
 export interface BoundariesContract {
   contractVersion: number;
   summary: string;
+  /** backend.language the convention rules were resolved for */
+  backendLanguage: BackendLanguage;
   ownershipPolicies: OwnershipPolicy[];
   /** 台帳に載っていないパスの既定規約 */
   conventionRules: BoundaryPathRule[];
@@ -82,7 +86,7 @@ export const OWNERSHIP_POLICIES: OwnershipPolicy[] = [
     zone: "shared",
     editPolicy: "edit-outside-markers",
     howToChange:
-      "SwallowKit appends only inside marked sections (e.g. `# SwallowKit scaffold registrations`). Edit anywhere outside the markers freely; do not remove the markers.",
+      "SwallowKit appends at the file-specific extension point: marked sections (e.g. `# SwallowKit scaffold registrations`) or append-only files such as shared/index.ts. Follow the path rule; preserve existing generated entries and any markers.",
   },
   {
     ownership: "metadata",
@@ -92,7 +96,7 @@ export const OWNERSHIP_POLICIES: OwnershipPolicy[] = [
   },
 ];
 
-export const CONVENTION_RULES: BoundaryPathRule[] = [
+const COMMON_LEADING_RULES: BoundaryPathRule[] = [
   {
     pattern: ".swallowkit/",
     zone: "deterministic",
@@ -107,32 +111,66 @@ export const CONVENTION_RULES: BoundaryPathRule[] = [
       "Zod model schemas — the single source of truth. AI/developers author these freely; deterministic generation derives everything else from them.",
   },
   {
-    pattern: "infra/main.bicep",
-    zone: "shared",
-    editPolicy: "edit-outside-markers",
-    description: "SwallowKit inserts container modules; other infrastructure edits are free.",
+    pattern: "infra/migrations/manifest.json",
+    zone: "deterministic",
+    editPolicy: "never-hand-edit",
+    description:
+      "Infrastructure migration ledger with baseline checksums. Updated by scaffold, `swallowkit migrations add-model`, and `swallowkit create-migration`.",
   },
   {
-    pattern: "functions/function_app.py",
-    zone: "shared",
-    editPolicy: "edit-outside-markers",
-    description: "SwallowKit appends blueprint registrations under its marker; other edits are free.",
+    pattern: "infra/migrations/",
+    zone: "ai-authored",
+    editPolicy: "free-edit",
+    description:
+      "Versioned Bicep migrations. Edit a migration only before it is provisioned; never change an applied migration — add a new one with `swallowkit create-migration <slug>`.",
   },
   {
-    pattern: "shared/index.ts",
-    zone: "shared",
-    editPolicy: "edit-outside-markers",
-    description: "SwallowKit appends model exports; other exports may be added freely.",
+    pattern: "infra/",
+    zone: "deterministic",
+    editPolicy: "never-hand-edit",
+    description:
+      "Baseline infrastructure (main.bicep and modules) whose checksums are recorded in infra/migrations/manifest.json. Hand edits block scaffold with baseline-drift; add resources through a new migration instead.",
   },
   {
-    pattern: "*",
-    zone: "ai-authored",
+    pattern: "shared/index.ts",
+    zone: "shared",
     editPolicy: "free-edit",
-    description:
-      "Any path not recorded in the artifact ledger is AI/developer-authored. Business logic, custom pages, custom Functions, and tests belong here.",
+    description: "create-model and scaffold append missing model exports while preserving existing content. No managed markers; manual exports are allowed. Keep exports needed by generated code.",
   },
 ];
 
+/** Backend files that SwallowKit appends to; C# and TypeScript discover functions without a registration file. */
+const BACKEND_EXTENSION_RULES: Record<BackendLanguage, BoundaryPathRule[]> = {
+  python: [
+    {
+      pattern: "functions/function_app.py",
+      zone: "shared",
+      editPolicy: "edit-outside-markers",
+      description: "SwallowKit appends blueprint registrations under its marker; other edits are free.",
+    },
+    {
+      pattern: "functions/requirements.txt",
+      zone: "shared",
+      editPolicy: "free-edit",
+      description: "SwallowKit appends connector driver requirements when connector models are scaffolded; keep those lines and edit other requirements freely.",
+    },
+  ],
+  csharp: [],
+  typescript: [],
+};
+
+const FALLBACK_RULE: BoundaryPathRule = {
+  pattern: "*",
+  zone: "ai-authored",
+  editPolicy: "free-edit",
+  description:
+    "Any path not recorded in the artifact ledger is AI/developer-authored. Business logic, custom pages, custom Functions, and tests belong here.",
+};
+
+export function buildConventionRules(backendLanguage: BackendLanguage): BoundaryPathRule[] {
+  return [...COMMON_LEADING_RULES, ...BACKEND_EXTENSION_RULES[backendLanguage], FALLBACK_RULE];
+}
+
 const POLICY_BY_OWNERSHIP = new Map(OWNERSHIP_POLICIES.map((policy) => [policy.ownership, policy] as const));
 
 export const BOUNDARY_GUIDANCE: string[] = [
@@ -143,7 +181,10 @@ export const BOUNDARY_GUIDANCE: string[] = [
   "Run `swallowkit machine verify project` after applying changes; use `explain failure` to get repair evidence.",
 ];
 
-export function inspectBoundaries(projectRoot: string = process.cwd()): BoundariesContract {
+export function inspectBoundaries(
+  projectRoot: string = process.cwd(),
+  backendLanguage: BackendLanguage = getBackendLanguage()
+): BoundariesContract {
   const inspected = inspectArtifacts(projectRoot);
 
   const artifacts: BoundaryArtifact[] = inspected.artifacts.map((artifact) => {
@@ -162,8 +203,9 @@ export function inspectBoundaries(projectRoot: string = process.cwd()): Boundari
     contractVersion: 1,
     summary:
       "SwallowKit separates deterministic generation (models → CRUD/BFF/UI/infra via plan/apply) from AI free-form authoring (models, business logic, custom code). This contract tells agents which files belong to which side.",
+    backendLanguage,
     ownershipPolicies: OWNERSHIP_POLICIES,
-    conventionRules: CONVENTION_RULES,
+    conventionRules: buildConventionRules(backendLanguage),
     artifacts,
     guidance: BOUNDARY_GUIDANCE,
   };

package/src/core/project/capabilities.ts

@@ -53,6 +53,7 @@ export interface CapabilitiesContract {
   sharedModels: {
     idFieldRule: string;
     buildNote: string;
+    nativeSchemaMapping: string[];
   };
   seeding: {
     createTemplates: string;
@@ -60,10 +61,19 @@ export interface CapabilitiesContract {
     notes: string[];
   };
   machineCommands: string[];
+  provisioning: {
+    execution: string;
+    completion: string;
+    tracking: string;
+    recovery: string;
+    diagnostics: string;
+    approval: string;
+  };
   verifyChecks: {
     defaultChecks: string[];
     optInChecks: string[];
     customChecks: string;
+    backendBuild: string;
   };
 }
 
@@ -108,6 +118,19 @@ export function inspectCapabilities(): CapabilitiesContract {
           "Role-based access control metadata applied to the generated CRUD Functions. `roles` guards all operations; `read`/`write` guard per-operation; `policy` references a named authorization policy from swallowkit.config auth.authorization.policies.",
         format:
           "export const authPolicy = { roles: ['admin'] };\n// or per-operation:\nexport const authPolicy = { read: ['user'], write: ['admin'] };\n// or a named policy:\nexport const authPolicy = { policy: 'adminOnly' };",
+        notes: [
+          "An explicit authPolicy without configured authentication blocks plan/apply/generate scaffold with auth-policy-without-auth before any artifacts are written. Run plan auth, apply auth, then re-plan scaffold. An empty {} declaration keeps the existing behavior: no explicit policy.",
+          "With named auth.schemes, define auth.authorization.policies selecting schemes and roles, then reference them via policy or read/write names. A role-only declaration cannot select a named scheme and blocks with auth-policy-requires-named-policy; it is supported by legacy single-provider authentication.",
+          "Conversely, single-provider authentication (auth.provider) supports role lists only. Referencing a named policy (authPolicy.policy, read/write names, or a named auth.authorization.defaultPolicy) blocks with auth-named-policy-requires-named-scheme; add a named scheme first.",
+        ],
+      },
+      {
+        name: "references",
+        required: false,
+        description:
+          "Explicit foreign keys used by generated UI lookups. Without it, a string field named <model>Id is treated as a foreign key only when shared/models contains that model (userId -> User only if user.ts exists). Map a field to false to disable inference. References to missing models are ignored with a reference-model-not-found warning.",
+        format: "export const references = { authorId: 'User', legacyId: false };",
+        notes: ["Only single string id fields can reference a model.", "No lookup UI, fetch, or OpenAPI reference is generated for fields that do not reference an existing model."],
       },
       {
         name: "connectorConfig",
@@ -174,15 +197,24 @@ export function inspectCapabilities(): CapabilitiesContract {
       ],
       notGuaranteed: [
         "Owner scoping: generated CRUD does NOT restrict rows to the authenticated principal. Any authenticated caller passing the policy can read/write any document.",
+        "Without authentication, plan scaffold reports user-scoped-data-without-auth when the partition key or an owner-like field (userId, learnerId, ownerId, ...) suggests per-user data.",
       ],
       guidance: [
-        "For multi-user data where users may only touch their own records, add ai-authored custom endpoints that derive the scoping key (e.g. learnerId) from the verified principal — never from the request body — and restrict generated write endpoints to admin roles or disable them.",
+        "Configure authentication via plan/apply auth before declaring authPolicy. For multi-user data where users may only touch their own records, add ai-authored custom endpoints that derive the scoping key (e.g. learnerId) from the verified principal — never from the request body — and restrict generated write endpoints to admin roles or disable them.",
       ],
     },
     sharedModels: {
       idFieldRule: "id: z.string() (required). createdAt/updatedAt: z.string().optional(). The backend owns their values.",
+      nativeSchemaMapping: [
+        "C#/Python schema assets derive types from Zod, never from field names: z.string() -> string/str (including createdAt/updatedAt).",
+        "Date types only when declared: z.iso.datetime() -> DateTime/datetime, z.iso.date() -> DateOnly/date, z.date() -> DateTime/datetime.",
+        "z.number() -> double / float|int; z.number().int() or z.int() -> long / int.",
+        "Inline z.object({...}) fields become named classes <Model><Field> (e.g. ProbeItemNested); imported model schemas keep their own class.",
+        "min/max/length/nonempty/regex/int/gt/gte/lt/lte/positive/nonnegative and array min/max are enforced by C# IValidatableObject.Validate and Python Field bounds/validators. Regexes use search semantics like Zod.",
+        "String formats (email/uuid/url), refinements, and transforms are not re-implemented natively; the BFF Zod schemas remain the authoritative validation.",
+      ],
       buildNote:
-        "verify typecheck resolves the shared package from its built dist/. SwallowKit rebuilds shared automatically during verify; when typechecking manually, build the shared package first (errors like \"no exported member\" usually mean a stale dist).",
+        "create-model and plan/apply scaffold append missing model exports to shared/index.ts, including manually authored models. Manual exports are allowed (no markers); existing content is preserved. verify typecheck resolves the shared package from its built dist/. SwallowKit rebuilds shared automatically during verify; when typechecking manually, build shared first.",
     },
     seeding: {
       createTemplates: "swallowkit create-dev-seeds <environment> — writes dev-seeds/<environment>/<model>.json templates.",
@@ -190,18 +222,29 @@ export function inspectCapabilities(): CapabilitiesContract {
       notes: ["Editing dev-seeds/*.json alone does nothing; seeds are only applied via dev --seed-env."],
     },
     machineCommands: [
-      "inspect project | entities | routes | artifacts | boundaries | infra | drift | capabilities",
+      "inspect project | entities | routes | artifacts | boundaries | infra | drift | capabilities; inspect provision --plan <runId> [--wait-seconds <0-3600>]",
       "validate project",
       "generate model <names...> | generate scaffold <model>",
-      "plan scaffold <models...> | plan auth --provider <p> [--scheme <name>] [--allowed-providers <csv>] | plan provision -g <rg> --location <loc> --swa-location <loc> [--adopt-existing --baseline 0 --what-if] [--reconcile --what-if]",
-      "apply scaffold [models...] --plan <id> [--approve] | apply auth --plan <id> [--approve] | apply provision --plan <id> --approve",
+      "plan scaffold <models...> [--api-only] [--skip-infra] | plan auth --provider <p> [--scheme <name>] [--allowed-providers <csv>] | plan provision -g <rg> --location <loc> --swa-location <loc> [--adopt-existing --baseline 0 --what-if] [--reconcile --what-if] [--resume-deployment <name>]",
+      "apply scaffold [models...] --plan <id> [--approve] [--skip-infra] | apply auth --plan <id> [--approve] | apply provision --plan <id> --approve [--wait-seconds <0-3600>] (also resumes the same execution checkpoint)",
       "verify project [--checks <ids>] [--compact]",
       "explain failure [--check <id>]",
+      "(regular CLI) migrations add-model <model> [--dry-run] — generate only the container migration after scaffold --skip-infra",
+      "(regular CLI) configure-mcp [--version auto|latest|<semver>] — re-select the MCP launcher version in .mcp.json",
     ],
+    provisioning: {
+      execution: "Submit Bicep once with az deployment group create --no-wait, then bounded state polling (default 300 seconds, configurable 0-3600) for machine/MCP; the human `swallowkit provision` command waits until Azure reaches a terminal state. Azure CLI invocations are bounded separately. Warning-only stderr with exit 0 is not a failure; output capture limits do not terminate az.",
+      completion: "status complete/outcome succeeded requires Azure Succeeded plus verified migration tags and local ledger completion. Running/Accepted -> in-progress; unreadable/not-found state -> blocked/outcome unknown; bookkeeping interruption after Azure Succeeded -> blocked/outcome partial; Failed/Canceled -> failed with Azure causes.",
+      tracking: "Approved runs persist before Azure writes under .swallowkit/state/provision/. runId equals the original planId and preserves the subscription, RG, deployment ID/correlation, fingerprints and migration state. inspect provision is read-only; apply provision --plan resumes without re-submitting attempted deployments. Ctrl+C/termination may leave Azure running; never cancel/delete without explicit consent.",
+      recovery: "For an older untracked baseline, plan provision --resume-deployment <name> compares the existing ARM template and non-secure parameters to the local Bicep/parameters. It observes that deployment and only tags/records it after Succeeded. Mismatches, unreadable evidence, secure parameters or non-baseline migrations block; do not use reconcile just to repair bookkeeping.",
+      diagnostics: "Machine/MCP results include bounded/redacted stdout/stderr, omitted-output flags, exit code, signal, failure kind, elapsed time and deployment identity, but no deployment outputs. Normal CLI shows named resource information and CI/CD setup guidance after success. Never print --debug output, keys, tokens or connection strings.",
+      approval: "Machine/MCP initial apply and every resume require explicit human approval. A human invoking normal provision or provision --resume explicitly requests execution without another confirmation prompt. Agents must not switch to normal CLI to bypass approval. A passing local command or an ok envelope is not proof of completed Azure provisioning; inspect status, outcome and nextActions.",
+    },
     verifyChecks: {
-      defaultChecks: ["structure", "drift", "typecheck"],
+      defaultChecks: ["structure", "drift", "typecheck", "backend-build"],
       optInChecks: ["build", "lint", "test"],
       customChecks: "swallowkit.config verify.checks: [{ id, command, title?, timeoutMs? }]",
+      backendBuild: "Runs dotnet build in functions/ (C#), the project tsc --noEmit (TypeScript), or Python 3 compileall (syntax only, using functions/.venv before PATH). Missing toolchains are skip with a reason, not proof of validation. Root build scripts do not replace backend-build; use --checks \"structure,drift,typecheck,backend-build,build\" for both.",
     },
   };
 }