swallowkit 1.0.0-beta.56 → 1.0.0-beta.58

package/src/cli/commands/init.ts

@@ -18,6 +18,7 @@ import {
 } from "../../utils/package-manager";
 import { syncProjectManifest } from "../../core/project/manifest";
 import { writeWorkflowDocs, writeAgentSkills } from "../../core/project/workflows";
+import { writeAgentInstructionFiles } from "../../core/project/agent-instructions";
 import {
   buildCSharpCodegenToolManifestSource,
   buildPythonCodegenRequirementsSource,
@@ -789,7 +790,7 @@ function runSimple(command: string, args: string[], cwd: string): Promise<void>
 export function injectSwallowKitNextConfig(nextConfigContent: string, projectName: string): string {
   return nextConfigContent.replace(
     /(const\s+nextConfig[:\s]*(?::\s*NextConfig\s*)?=\s*\{)(\s*\/\*[^*]*\*\/)?/,
-    `$1\n  output: 'standalone',\n  transpilePackages: ['@${projectName}/shared'],\n  serverExternalPackages: ['applicationinsights', 'diagnostic-channel-publishers'],$2`
+    `$1\n  output: 'standalone',\n  agentRules: false, // SwallowKit owns the canonical root AGENTS.md contract\n  transpilePackages: ['@${projectName}/shared'],\n  serverExternalPackages: ['applicationinsights', 'diagnostic-channel-publishers'],$2`
   );
 }
 
@@ -2105,532 +2106,34 @@ This project was generated by SwallowKit. If you encounter any issues or have su
   console.log('✅ README.md created\n');
 }
 
-function createAiAgentFiles(projectDir: string, projectName: string, backendLanguage: BackendLanguage, pm: PackageManager) {
+function createAiAgentFiles(
+  projectDir: string,
+  projectName: string,
+  backendLanguage: BackendLanguage,
+  pm: PackageManager
+) {
   console.log('🤖 Creating AI agent instruction files...\n');
-  const backendLanguageLabel = getBackendLanguageLabel(backendLanguage);
   const runCmd = pm === 'pnpm' ? 'pnpm' : 'npx';
-  const projectMcpConfigSource = buildSwallowKitMcpProjectConfigSource(pm);
-  const functionsStructureLine = backendLanguage === 'typescript'
-    ? `│   └── src/               # HTTP trigger handlers with Cosmos DB bindings`
-    : backendLanguage === 'csharp'
-      ? `│   ├── Crud/              # C# HTTP trigger handlers\n│   └── generated/         # Native-generated C# schema assets`
-      : `│   ├── blueprints/        # Python HTTP trigger handlers\n│   └── generated/         # Native-generated Python schema assets`;
-  const backendSchemaNote = backendLanguage === 'typescript'
-    ? `- The shared package (\`@${projectName}/shared\`) is consumed by both Next.js and Azure Functions as a workspace dependency.`
-    : `- The frontend/BFF source of truth stays in \`shared/models/\` as Zod schemas.\n- \`swallowkit scaffold\` exports OpenAPI into \`functions/openapi/\` and generates ${backendLanguageLabel} schema assets into \`functions/generated/\` with native ${backendLanguageLabel} tooling.`;
-  const backendRulesNote = backendLanguage === 'typescript'
-    ? `- All CRUD operations and business logic live in \`functions/src/\`.\n- Use Azure Functions Cosmos DB **input/output bindings** (\`extraInputs\`/\`extraOutputs\`) for reads and writes.\n- Use the Cosmos DB SDK client directly **only** for delete operations (bindings do not support delete).\n- Validate all data against Zod schemas before writing to Cosmos DB.\n- The backend auto-generates \`id\` (UUID), \`createdAt\`, and \`updatedAt\` — never trust client-sent values for these fields.`
-    : `- All business logic lives in \`functions/\` and the generated handlers perform real Cosmos DB CRUD.\n- Keep Zod schemas in \`shared/models/\` as the source of truth.\n- Regenerate backend contracts with \`swallowkit scaffold shared/models/<name>.ts\` whenever a schema changes.\n- Use the native-generated schema assets in \`functions/generated/\` to keep backend contracts aligned.\n- The backend should still own \`id\`, \`createdAt\`, and \`updatedAt\`.`;
-
-  // ── 1. AGENTS.md (Codex / generic agents) ──────────────────────────
-
-  const agentsMd = `# AGENTS.md
-
-This project was generated by **SwallowKit**.
-All coding agents **must** follow the architecture and conventions described below.
-
-## Architecture Overview
-
-This is a full-stack application deployed on Azure with a TypeScript frontend/BFF and an Azure Functions backend in ${backendLanguageLabel}.
-
-\`\`\`
-Frontend (React / Next.js App Router)
-  ↓ fetch('/api/{model}', ...)
-BFF Layer (Next.js API Routes)
-  ↓ HTTP → Azure Functions
-Backend (Azure Functions)
-  ↓
-Azure Cosmos DB (Document Database)
-\`\`\`
-
-### Project Structure
-
-\`\`\`
-${projectName}/
-├── app/                    # Next.js App Router
-│   ├── api/               # BFF API routes (proxy to Azure Functions)
-│   └── {model}/           # UI pages per model (list, detail, create, edit)
-├── functions/             # Azure Functions (backend)
-${functionsStructureLine}
-├── shared/                # Shared workspace package
-│   ├── models/            # Zod schema definitions (single source of truth)
-│   └── index.ts           # Re-exports all models
-├── lib/
-│   └── api/               # API client utilities (backend.ts, call-function.ts)
-├── components/            # Shared React components
-├── infra/                 # Bicep infrastructure-as-code files
-│   ├── main.bicep
-│   └── modules/
-├── .mcp.json              # Project-scoped MCP bootstrap resolving SwallowKit on each launch
-└── .github/workflows/     # CI/CD workflows (if configured)
-\`\`\`
-
-## Setup & Everyday Commands
-
-\`\`\`bash
-${pm} install                                  # install dependencies
-${runCmd} swallowkit dev                       # Next.js (3000) + Azure Functions (7071)
-${pm} run build                                # production build
-${pm} run lint                                 # ESLint (generated code must stay error-free)
-${runCmd} swallowkit verify                    # structure / drift / typecheck (exit 1 on failure)
-\`\`\`
-
-Run \`${runCmd} swallowkit verify\` (or \`machine verify project\`) before finishing any task.
-
-## SwallowKit MCP / Machine Workflow
-
-- This repository includes a project-scoped \`.mcp.json\` file that resolves and starts the latest SwallowKit MCP server on each launch. Set \`SWALLOWKIT_MCP_VERSION\` in that file to pin a specific version.
-- Prefer the \`swallowkit_*\` MCP tools for framework-owned inspection, validation, and generation when they are available.
-- If MCP is unavailable in your runtime, fall back to the machine CLI:
-  - \`${runCmd} swallowkit machine inspect project\`
-  - \`${runCmd} swallowkit machine inspect boundaries\` — responsibility boundary contract (which files you may edit freely)
-  - \`${runCmd} swallowkit machine validate project\`
-  - \`${runCmd} swallowkit machine plan scaffold <name>\` → \`apply scaffold --plan <planId>\` — safe two-phase generation
-  - \`${runCmd} swallowkit machine verify project\` → \`explain failure\` — verification loop
-- Do not hand-edit framework-owned artifacts when the MCP or machine interface can generate or validate them for you.
-- The MCP bootstrap uses ${pm} and requires network access when the selected version is not cached.
-- **Always invoke SwallowKit via \`${runCmd}\`.** Do not mix package manager commands.
-
-## Autonomous Loop (Plan / Apply / Verify)
-
-Machine commands return a \`status\` terminal state (\`complete\` / \`in-progress\` / \`blocked\` / \`requires-human\` / \`failed\`) and \`nextActions\`. Standard loop:
-
-1. \`plan scaffold <model>\` — compute changes without writing (get \`planId\`)
-2. \`apply scaffold --plan <planId>\` — apply with freshness + approval checks
-3. \`verify project\` — structure / drift / typecheck (and project-specific checks)
-4. \`explain failure\` — evidence and repair actions when verification fails
-
-Step-by-step runbooks live in \`.swallowkit/workflows/\` (agent-agnostic Markdown):
-
-- \`.swallowkit/workflows/add-model.md\`
-- \`.swallowkit/workflows/modify-model.md\`
-- \`.swallowkit/workflows/verify-and-repair.md\`
-- \`.swallowkit/workflows/provision.md\`
-
-The same runbooks are installed as **Agent Skills** ([agentskills.io](https://agentskills.io/) open standard) under \`.github/skills/\`:
-
-| Skill | Use when |
-|-------|----------|
-| \`swallowkit-add-model\` | adding a new model / entity / CRUD feature |
-| \`swallowkit-modify-model\` | changing an existing schema and re-aligning artifacts |
-| \`swallowkit-verify-repair\` | converging to a verified state after any change |
-| \`swallowkit-provision\` | provisioning Azure infrastructure (human approval required) |
-
-Skills-aware agents (GitHub Copilot in VS Code / CLI / cloud agent, and other agents supporting the standard) discover these automatically from their \`name\`/\`description\` and load the body on demand. If your agent does not support skills, read the equivalent runbook in \`.swallowkit/workflows/\` before performing these tasks.
-
-## Responsibility Boundary (AI × Deterministic Generation)
-
-- **ai-authored (write freely)**: \`shared/models/\`, business logic, custom pages/components, tests.
-- **deterministic (never hand-edit)**: artifacts recorded in \`.swallowkit/artifacts.json\` with \`managed\` ownership, and \`.swallowkit/\` metadata. Change the model/config and regenerate via plan/apply instead.
-- **shared (edit outside markers)**: \`infra/main.bicep\`, \`functions/function_app.py\`, \`shared/index.ts\`.
-- Full machine-readable contract: \`${runCmd} swallowkit machine inspect boundaries\`
-
-## Critical Design Principles
-
-### 1. Next.js API Routes Are Strictly a BFF (Backend for Frontend)
-
-- \`app/api/\` routes exist **only** to proxy requests to Azure Functions.
-- **Never** place business logic, database access, or direct Cosmos DB calls in Next.js API routes.
-- The BFF layer may validate input/output with Zod schemas before forwarding to Functions.
-- Use the \`callFunction\` helper (\`lib/api/call-function.ts\`) or the \`api\` client (\`lib/api/backend.ts\`) to call Azure Functions.
-
-Example BFF route pattern:
-
-\`\`\`typescript
-// app/api/{model}/route.ts
-import { callFunction } from '@/lib/api/call-function';
-import { ModelSchema } from '@${projectName}/shared';
-import { z } from 'zod/v4';
-
-export async function GET() {
-  return callFunction({
-    method: 'GET',
-    path: '/api/{model}',
-    responseSchema: z.array(ModelSchema),
-  });
-}
-
-export async function POST(request: NextRequest) {
-  const body = await request.json();
-  return callFunction({
-    method: 'POST',
-    path: '/api/{model}',
-    body,
-    inputSchema: ModelSchema.omit({ id: true, createdAt: true, updatedAt: true }),
-    responseSchema: ModelSchema,
-    successStatus: 201,
-  });
-}
-\`\`\`
-
-### 2. Zod Schemas Are the Single Source of Truth
-
-- All data models are defined **once** as Zod schemas in \`shared/models/\`.
-- TypeScript types are derived with \`z.infer<typeof Schema>\` — never define types separately.
-- ${backendSchemaNote}
-
-Model definition pattern:
-
-\`\`\`typescript
-// shared/models/{model}.ts
-import { z } from 'zod/v4';
-
-export const Todo = z.object({
-  id: z.string(),
-  name: z.string().min(1),
-  // ... your fields
-  createdAt: z.string().optional(),
-  updatedAt: z.string().optional(),
-});
-
-export type Todo = z.infer<typeof Todo>;
-export const displayName = 'Todo';
-\`\`\`
-
-Key rules:
-- Use the **Zod official pattern**: the schema constant and the TypeScript type share the same name.
-- \`id\`, \`createdAt\`, and \`updatedAt\` are auto-managed by the backend. Mark them as \`optional()\` in the schema.
-- Always re-export models from \`shared/index.ts\`.
-
-### 3. Azure Functions Own All Business Logic and Data Access
-
-- ${backendRulesNote}
-
-${backendLanguage === 'typescript' ? 'Azure Functions handler pattern:' : `Generated ${backendLanguageLabel} handlers live under \`functions/\`. Re-run \`swallowkit scaffold shared/models/<name>.ts\` after schema changes to keep generated CRUD handlers and the native schema assets under \`functions/generated/\` in sync.`}
-
-${backendLanguage === 'typescript' ? `\`\`\`typescript
-// functions/src/{model}.ts
-import { app } from '@azure/functions';
-import { ModelSchema } from '@${projectName}/shared';
-
-const containerName = 'Models'; // PascalCase + 's'
-
-app.http('{model}-get-all', {
-  methods: ['GET'],
-  route: '{model}',
-  authLevel: 'function',
-  extraInputs: [{ type: 'cosmosDB', name: 'cosmosInput', containerName, ... }],
-  handler: async (request, context) => {
-    const documents = context.extraInputs.get('cosmosInput');
-    const validated = z.array(ModelSchema).parse(documents);
-    return { status: 200, jsonBody: validated };
-  },
-});
-\`\`\`` : ''}
-
-## Naming Conventions
-
-| Item | Convention | Example |
-|------|-----------|---------|
-| Model schema file | \`shared/models/{kebab-case}.ts\` | \`shared/models/todo.ts\` |
-| Schema/type name | PascalCase (same name for both) | \`export const Todo = z.object({...}); export type Todo = z.infer<typeof Todo>;\` |
-| Functions handler file | backend-language specific under \`functions/\` | \`${backendLanguage === 'typescript' ? 'functions/src/todo.ts' : backendLanguage === 'csharp' ? 'functions/Crud/TodoCrudFunctions.cs' : 'functions/blueprints/todo.py'}\` |
-| Functions handler name | \`{camelCase}-{operation}\` | \`todo-get-all\`, \`todo-create\` |
-| API route path | \`/api/{camelCase}\` | \`/api/todo\`, \`/api/todo/{id}\` |
-| BFF route file | \`app/api/{kebab-case}/route.ts\` | \`app/api/todo/route.ts\` |
-| BFF detail route | \`app/api/{kebab-case}/[id]/route.ts\` | \`app/api/todo/[id]/route.ts\` |
-| UI page directory | \`app/{kebab-case}/\` | \`app/todo/page.tsx\` |
-| React component | PascalCase | \`TodoForm.tsx\` |
-| Cosmos DB container | PascalCase + 's' | \`Todos\` |
-| Cosmos DB partition key | \`/id\` (default) | Custom: \`export const partitionKey = '/field'\` |
-| Bicep container file | \`infra/containers/{kebab-case}-container.bicep\` | \`infra/containers/todo-container.bicep\` |
-
-## Adding New Models (SwallowKit CLI)
-
-Use the SwallowKit CLI — do **not** manually create model files or CRUD boilerplate.
-For autonomous agents, prefer the plan/apply loop above (or the \`swallowkit-add-model\` skill); the commands below are the human-friendly equivalents.
-
-### Create a new data model
-
-\`\`\`bash
-${runCmd} swallowkit create-model <name>
-# Multiple models at once:
-${runCmd} swallowkit create-model user post comment
-\`\`\`
-
-Creates \`shared/models/<name>.ts\` with a Zod schema template including \`id\`, \`createdAt\`, \`updatedAt\`.
-Edit the generated file to add your domain-specific fields, then run scaffold.
-
-### Generate full CRUD from a model
-
-\`\`\`bash
-${runCmd} swallowkit scaffold shared/models/<name>.ts
-\`\`\`
-
-Generates:
-- Azure Functions handlers (${backendLanguage === 'typescript' ? '`functions/src/<name>.ts`' : '`functions/` language-specific CRUD files + `functions/generated/` schema assets'})
-- BFF API routes (\`app/api/<name>/route.ts\`, \`app/api/<name>/[id]/route.ts\`)
-- UI pages (\`app/<name>/page.tsx\`, detail, create, edit pages)
-- Cosmos DB Bicep container config (\`infra/containers/<name>-container.bicep\`)
-
-### Start development servers
-
-\`\`\`bash
-${runCmd} swallowkit dev
-\`\`\`
 
-Runs Next.js (http://localhost:3000) and Azure Functions (http://localhost:7071) concurrently.
-Checks for Cosmos DB Emulator availability.
-
-### Provision Azure resources
-
-\`\`\`bash
-${runCmd} swallowkit provision --resource-group <name> --location <region>
-\`\`\`
-
-Deploys Bicep infrastructure: Static Web Apps, Functions, Cosmos DB, Storage, Managed Identity.
-
-### Typical workflow for "add a new feature/model"
-
-1. \`${runCmd} swallowkit create-model <name>\`
-2. Edit \`shared/models/<name>.ts\` — add fields
-3. \`${runCmd} swallowkit scaffold shared/models/<name>.ts\`
-4. \`${runCmd} swallowkit dev\` — verify at http://localhost:3000/<name>
-5. If \`dev-seeds/\` already exists, update the seed JSON files to include realistic data for the new model and adjust existing seeds if relationships changed.
-
-## Do NOT
-
-- **Do not** put business logic or database calls in \`app/api/\` routes. They are BFF only.
-- **Do not** define TypeScript interfaces/types separately from Zod schemas. Always derive types with \`z.infer<>\`.
-- **Do not** manually duplicate model definitions across layers. Use the shared package.
-- **Do not** manually create CRUD boilerplate. Use \`swallowkit scaffold\`.
-- **Do not** hardcode Cosmos DB connection strings. Use Managed Identity (\`CosmosDBConnection__accountEndpoint\`) in production and emulator settings locally.
-- By default, all containers use \`/id\` as the partition key. To use a custom partition key, add \`export const partitionKey = '/yourField'\` to the model file. The scaffold command will apply it across all layers.
-
-## Technology Stack
-
-- **Frontend**: Next.js (App Router), React, TypeScript, Tailwind CSS
-- **BFF**: Next.js API Routes (proxy only)
-- **Backend**: Azure Functions (${backendLanguageLabel})
-- **Database**: Azure Cosmos DB (NoSQL)
-- **Schema**: Zod (shared across all layers via workspace package)
-- **Infrastructure**: Bicep (IaC)
-- **Hosting**: Azure Static Web Apps (frontend) + Azure Functions Flex Consumption (backend)
-- **Auth**: Azure Managed Identity (no connection strings in production)
-- **Monitoring**: Application Insights
-`;
-
-  fs.writeFileSync(path.join(projectDir, 'AGENTS.md'), agentsMd);
-  console.log('  ✅ AGENTS.md (Codex / generic agents)');
-
-  // ── 2. CLAUDE.md (Claude Code) ─────────────────────────────────────
-
-  const claudeMd = `# CLAUDE.md
-
-This file is for Claude Code. Read AGENTS.md in the project root for the full architecture, conventions, and rules.
-
-## Quick Reference
-
-- **Architecture**: Next.js (frontend) → BFF (API routes, proxy only) → Azure Functions (backend) → Cosmos DB
-- **Schema**: Zod schemas in \`shared/models/\` are the single source of truth. Never define types separately.
-- **BFF rule**: \`app/api/\` routes must ONLY proxy to Azure Functions via \`callFunction()\`. No business logic.
-- **Backend language**: ${backendLanguageLabel}
-- **Backend rule**: Regenerate backend contracts with \`swallowkit scaffold\` after schema changes and keep \`functions/generated/\` in sync.
-
-## SwallowKit MCP
-
-- This repository includes a project-scoped \`.mcp.json\` that resolves and starts the latest SwallowKit MCP server on each launch. Set \`SWALLOWKIT_MCP_VERSION\` in that file to pin a specific version.
-- When the \`swallowkit_*\` tools are available, prefer them for inspect / validate / generate tasks.
-- If MCP is unavailable, use \`${runCmd} swallowkit machine ...\` instead.
-- For generation, prefer the two-phase flow: \`plan scaffold <name>\` → \`apply scaffold --plan <planId>\` → \`verify project\`. Runbooks: \`.swallowkit/workflows/\`.
-- Agent Skills (agentskills.io) for the same workflows live in \`.github/skills/\` (\`swallowkit-add-model\`, \`swallowkit-modify-model\`, \`swallowkit-verify-repair\`, \`swallowkit-provision\`). If your runtime does not auto-discover them, read the relevant \`SKILL.md\` before performing these tasks.
-- Boundary contract (what you may edit freely vs what SwallowKit regenerates): \`${runCmd} swallowkit machine inspect boundaries\`
-- **Always invoke SwallowKit via \`${runCmd}\`.** Do not mix package manager commands.
-
-## SwallowKit CLI Commands
-
-| Task | Command |
-|------|---------|
-| Create model | \`${runCmd} swallowkit create-model <name>\` |
-| Generate CRUD | \`${runCmd} swallowkit scaffold shared/models/<name>.ts\` |
-| Dev servers | \`${runCmd} swallowkit dev\` |
-| Provision Azure | \`${runCmd} swallowkit provision --resource-group <rg> --location <region>\` |
-
-## Workflow: Add a new model
-
-1. \`${runCmd} swallowkit create-model <name>\`
-2. Edit \`shared/models/<name>.ts\` — add your fields
-3. \`${runCmd} swallowkit scaffold shared/models/<name>.ts\`
-4. \`${runCmd} swallowkit dev\` — verify at http://localhost:3000/<name>
-5. If \`dev-seeds/\` exists, update the seed JSON files to include data for the new model and adjust existing seeds if relationships changed.
-`;
-
-  fs.writeFileSync(path.join(projectDir, 'CLAUDE.md'), claudeMd);
-  console.log('  ✅ CLAUDE.md (Claude Code)');
-
-  fs.writeFileSync(path.join(projectDir, '.mcp.json'), projectMcpConfigSource);
-  console.log('  ✅ .mcp.json (project-scoped MCP bootstrap)');
-
-  // ── 3. .github/copilot-instructions.md (GitHub Copilot) ────────────
-
-  const ghDir = path.join(projectDir, '.github');
-  fs.mkdirSync(ghDir, { recursive: true });
-
-  const copilotInstructions = `# Copilot Instructions
-
-This project was generated by **SwallowKit**. See \`AGENTS.md\` in the project root for the full specification.
-
-## Architecture (3-layer)
-
-\`\`\`
-Frontend (Next.js App Router) → BFF (Next.js API Routes) → Backend (Azure Functions) → Cosmos DB
-\`\`\`
-
-## Key Rules
-
-1. **BFF is proxy only** — \`app/api/\` routes call Azure Functions via \`callFunction()\`. No business logic, no direct DB access.
-2. **Zod = single source of truth** — Models live in \`shared/models/\`. Types are derived with \`z.infer<>\`. Never define types separately.
-3. **Backend owns data** — All CRUD and business logic stay in \`functions/\`, and generated contract assets under \`functions/generated/\` must stay aligned with \`shared/models/\`.
-4. **Use the CLI** — Run \`${runCmd} swallowkit create-model <name>\` then \`${runCmd} swallowkit scaffold shared/models/<name>.ts\` to add models. Do not create boilerplate manually.
-5. **Maintain seed data** — When adding models or changing schemas, update the JSON files under \`dev-seeds/\` to keep seed data consistent with the current schema.
-
-## SwallowKit Framework Operations
-
-- Prefer the SwallowKit MCP or machine interface for framework-owned inspection, validation, and generation instead of hand-editing generated files.
-- If your runtime loads project-scoped MCP config from \`.mcp.json\`, use the \`swallowkit_*\` tools.
-- Otherwise use \`${runCmd} swallowkit machine inspect project\`, \`${runCmd} swallowkit machine validate project\`, and the two-phase flow \`${runCmd} swallowkit machine plan scaffold <name>\` → \`apply scaffold --plan <planId>\` → \`verify project\`.
-- Agent Skills in \`.github/skills/\` (\`swallowkit-add-model\`, \`swallowkit-modify-model\`, \`swallowkit-verify-repair\`, \`swallowkit-provision\`) cover these workflows — load them when the task matches.
-- Boundary contract: \`${runCmd} swallowkit machine inspect boundaries\` tells you which files are free to edit and which are regenerated. Runbooks live in \`.swallowkit/workflows/\`.
-- **Always invoke SwallowKit via \`${runCmd}\`.** Do not mix package manager commands.
-
-## Naming
-
-- Schema/type: PascalCase, same name for both (\`export const Todo = z.object({...}); export type Todo = z.infer<typeof Todo>;\`)
-- Files: kebab-case (\`shared/models/todo.ts\`, backend handlers under \`functions/\`)
-- Cosmos DB containers: PascalCase + 's' (\`Todos\`), partition key default \`/id\` (customizable via \`export const partitionKey\`)
-
-## Managed Fields
-
-\`id\`, \`createdAt\`, \`updatedAt\` are auto-managed by the backend. Define them as \`optional()\` in schemas. Never trust client-sent values.
-`;
-
-  fs.writeFileSync(path.join(ghDir, 'copilot-instructions.md'), copilotInstructions);
-  console.log('  ✅ .github/copilot-instructions.md (GitHub Copilot)');
-
-  // ── 4. .github/instructions/*.instructions.md (Copilot layer-specific) ──
-
-  const instructionsDir = path.join(ghDir, 'instructions');
-  fs.mkdirSync(instructionsDir, { recursive: true });
-
-  // 4a. shared/models — Zod schema layer
-  const sharedModelsInstructions = `---
-applyTo: "shared/models/**"
----
-
-# Shared Models — Zod Schema Rules
-
-Files in this directory are the **single source of truth** for data models across the entire application.
-
-## Rules
-
-- Define Zod schemas using \`zod/v4\` (\`import { z } from 'zod/v4'\`).
-- Use the **Zod official pattern**: the schema constant and the TypeScript type share the same name.
-  \`\`\`typescript
-  export const Todo = z.object({ ... });
-  export type Todo = z.infer<typeof Todo>;
-  \`\`\`
-- Always include \`id: z.string()\`, \`createdAt: z.string().optional()\`, \`updatedAt: z.string().optional()\`. These are managed by the backend.
-- Export a \`displayName\` string constant for UI display.
-- Re-export every model from \`shared/index.ts\`.
-- For relationships, use **nested schemas** (import and embed the related schema), not ID references.
-- After editing a model, run \`${runCmd} swallowkit scaffold shared/models/<name>.ts\` to regenerate CRUD code.
-`;
-
-  fs.writeFileSync(
-    path.join(instructionsDir, 'shared-models.instructions.md'),
-    sharedModelsInstructions
-  );
-
-  // 4b. app/api — BFF layer
-  const bffInstructions = `---
-applyTo: "app/api/**"
----
-
-# BFF API Routes — Rules
-
-Files in \`app/api/\` are the **BFF (Backend for Frontend)** layer. They exist solely to proxy requests to Azure Functions.
-
-## Rules
-
-- **Never** put business logic, database access, or direct Cosmos DB calls here.
-- Use \`callFunction()\` from \`@/lib/api/call-function\` to forward requests to Azure Functions.
-- You may validate input/output with Zod schemas before forwarding.
-- Import schemas from \`@${projectName}/shared\`.
-
-## Pattern
-
-\`\`\`typescript
-import { callFunction } from '@/lib/api/call-function';
-import { ModelSchema } from '@${projectName}/shared';
-import { z } from 'zod/v4';
-
-export async function GET() {
-  return callFunction({
-    method: 'GET',
-    path: '/api/{model}',
-    responseSchema: z.array(ModelSchema),
+  writeAgentInstructionFiles(projectDir, {
+    projectName,
+    backendLanguage,
+    packageManager: pm,
   });
-}
-\`\`\`
-`;
-
-  fs.writeFileSync(
-    path.join(instructionsDir, 'bff-routes.instructions.md'),
-    bffInstructions
-  );
-
-  // 4c. functions — Azure Functions backend layer
-  const functionsInstructions = `---
-applyTo: "functions/**"
----
-
-# Azure Functions — Backend Rules
-
-Files in \`functions/\` contain all business logic and data access for this application.
-
-## Rules
-
-- Keep backend contracts aligned with \`shared/models/\` by rerunning \`swallowkit scaffold\` after schema changes.
-- For TypeScript backends, use Cosmos DB **input/output bindings** (\`extraInputs\`/\`extraOutputs\`) for reads and writes.
-- For C#/Python backends, consume the native-generated assets in \`functions/generated/\`.
-- Auto-generate \`id\` (UUID), \`createdAt\`, and \`updatedAt\` on the backend. Never trust client-sent values.
-- Container names are PascalCase + 's' (e.g., \`Todos\`). Partition key defaults to \`/id\` but can be customized per model.
-
-## Handler Pattern
-
-\`\`\`typescript
-import { app } from '@azure/functions';
-import { ModelSchema } from '@${projectName}/shared';
-
-app.http('{model}-get-all', {
-  methods: ['GET'],
-  route: '{model}',
-  authLevel: 'function',
-  extraInputs: [cosmosInput],
-  handler: async (request, context) => {
-    const documents = context.extraInputs.get(cosmosInput);
-    const validated = z.array(ModelSchema).parse(documents);
-    return { status: 200, jsonBody: validated };
-  },
-});
-\`\`\`
-`;
+  console.log('  ✅ AGENTS.md (canonical project contract)');
+  console.log('  ✅ CLAUDE.md (Claude Code adapter)');
+  console.log('  ✅ .github/copilot-instructions.md (GitHub Copilot adapter)');
+  console.log('  ✅ .github/instructions/ (path-specific instructions)');
 
   fs.writeFileSync(
-    path.join(instructionsDir, 'azure-functions.instructions.md'),
-    functionsInstructions
+    path.join(projectDir, '.mcp.json'),
+    buildSwallowKitMcpProjectConfigSource(pm)
   );
+  console.log('  ✅ .mcp.json (project-scoped MCP bootstrap)');
 
-  console.log('  ✅ .github/instructions/ (Copilot layer-specific instructions)');
-  console.log('     - shared-models.instructions.md');
-  console.log('     - bff-routes.instructions.md');
-  console.log('     - azure-functions.instructions.md');
-
-  // ── 5. .swallowkit/workflows/*.md (agent-agnostic runbooks) ────────
   writeWorkflowDocs(projectDir, runCmd);
   console.log('  ✅ .swallowkit/workflows/ (agent-agnostic autonomous-loop runbooks)');
 
-  // ── 6. .github/skills/<name>/SKILL.md (Agent Skills, agentskills.io) ─
   const skillPaths = writeAgentSkills(projectDir, runCmd);
   console.log('  ✅ .github/skills/ (Agent Skills — agentskills.io open standard)');
   for (const skillPath of skillPaths) {
@@ -2638,16 +2141,7 @@ app.http('{model}-get-all', {
   }
 
   console.log('\n✅ AI agent files created\n');
-  console.log('   Supported agents:');
-  console.log('   - OpenAI Codex          → AGENTS.md');
-  console.log('   - Claude Code           → CLAUDE.md (+ AGENTS.md)');
-  console.log('   - Project MCP runtimes  → .mcp.json');
-  console.log('   - GitHub Copilot        → .github/copilot-instructions.md');
-  console.log('   - GitHub Copilot (edit) → .github/instructions/*.instructions.md');
-  console.log('   - Skills-aware agents   → .github/skills/*/SKILL.md');
-  console.log('');
 }
-
 export function buildFunctionsHostKeyBicepExpression(): string {
   return "listKeys('${resourceId('Microsoft.Web/sites', functionsAppName)}/host/default', '2023-12-01').functionKeys.default";
 }

package/src/cli/commands/scaffold.ts

@@ -31,7 +31,7 @@ import {
   generateAuthLayout,
   UIAuthOptions,
 } from "../../core/scaffold/ui-generator";
-import { generateLanguageSchemaArtifacts } from "../../core/scaffold/native-schema-generator";
+import { generateLanguageSchemaArtifacts, validateNativeSchemaToolchain } from "../../core/scaffold/native-schema-generator";
 import { detectFromProject, getCommands } from "../../utils/package-manager";
 import {
   BackendLanguage,
@@ -135,6 +135,19 @@ export async function scaffoldCommand(options: ScaffoldOptions) {
     const relatedModels = backendLanguage === "typescript"
       ? [modelInfo]
       : await collectModelGraph(modelPath);
+    for (const relatedModel of relatedModels) {
+      session.registerInput(relatedModel.filePath);
+    }
+
+    // 4b. 書き込み前に外部 codegen toolchain を検証し、失敗時はプロジェクト無変更で終了する
+    if (session.mode === "commit" && backendLanguage !== "typescript" && !isConnectorModel) {
+      await validateNativeSchemaToolchain(
+        relatedModels,
+        modelInfo,
+        backendLanguage,
+        path.join(process.cwd(), functionsDir)
+      );
+    }
 
     if (options.apiOnly) {
       console.log("ℹ️  --api-only skips UI generation only; Functions, BFF routes, OpenAPI, and native schema assets are still updated.");
@@ -152,13 +165,7 @@ export async function scaffoldCommand(options: ScaffoldOptions) {
       await generateFunctionsCode(modelInfo, functionsDir, sharedPackageName, backendLanguage, session);
 
       if (backendLanguage !== "typescript") {
-        if (session.mode === "collect") {
-          session.addWarning(
-            `external-codegen: ${functionsDir}/openapi and ${functionsDir}/generated are regenerated by external tooling on apply and are not included in this plan.`
-          );
-        } else {
-          await generateLanguageSchemaArtifacts(relatedModels, modelInfo, functionsDir, backendLanguage);
-        }
+        await generateLanguageSchemaArtifacts(relatedModels, modelInfo, functionsDir, backendLanguage, session);
       }
     }
 

package/src/core/operations/file-session.ts

@@ -75,6 +75,7 @@ export class FileOperationSession {
   readonly warnings: string[] = [];
 
   private readonly operationsByPath = new Map<string, RecordedFileOperation>();
+  private readonly inputFingerprintsByPath = new Map<string, string | null>();
   /** overlay: absolute normalized path -> content (null = deleted in session) */
   private readonly overlay = new Map<string, string | null>();
 
@@ -87,12 +88,23 @@ export class FileOperationSession {
     return Array.from(this.operationsByPath.values()).sort((a, b) => a.path.localeCompare(b.path));
   }
 
+  get inputFingerprints(): Record<string, string | null> {
+    return Object.fromEntries(
+      Array.from(this.inputFingerprintsByPath.entries()).sort(([left], [right]) => left.localeCompare(right))
+    );
+  }
+
   addWarning(message: string): void {
     if (!this.warnings.includes(message)) {
       this.warnings.push(message);
     }
   }
 
+  registerInput(absolutePath: string): void {
+    const relativePath = toProjectRelativePath(this.rootDirectory, absolutePath);
+    this.inputFingerprintsByPath.set(relativePath, hashFileIfExists(absolutePath));
+  }
+
   private overlayKey(absolutePath: string): string {
     return path.resolve(absolutePath);
   }