swallowkit 1.0.0-beta.57 → 1.0.0-beta.59

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/index.ts

@@ -189,10 +189,12 @@ export function createProgram(devCommandOverride: Command = devCommand): Command
     .description("Add authentication and authorization to the project")
     .option("--provider <provider>", "Auth provider: custom-jwt | swa | external-token | swa-custom | none", "custom-jwt")
     .option("--scheme <name>", "Add a named authentication scheme")
+    .option("--allowed-providers <list>", "Comma-separated SWA identity providers to allow (e.g. github,aad); defaults to aad")
     .action((options) => {
       addAuthCommand({
         provider: options.provider,
         scheme: options.scheme,
+        allowedProviders: options.allowedProviders ? String(options.allowedProviders).split(",") : undefined,
       });
     });
 

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

@@ -27,6 +27,8 @@ import {
 export interface PlanAuthOptions {
   provider: string;
   scheme?: string;
+  /** SWA の許可 identity provider。未指定時は add-auth 側の既定 (['aad'])。 */
+  allowedProviders?: string[];
 }
 
 export type AuthPlanAction = "create" | "update" | "overwrite" | "append" | "delete" | "skip";
@@ -44,6 +46,7 @@ export interface AuthPlanData {
   planType: "auth";
   provider: string;
   scheme?: string;
+  allowedProviders?: string[];
   createdAt: string;
   swallowkitVersion: string;
   operations: AuthPlanOperation[];
@@ -70,7 +73,7 @@ async function collectAuthOperations(options: PlanAuthOptions): Promise<FileOper
     const captured = await captureConsoleMessagesWithError(async () => {
       await interceptProcessExit(async () => {
         await runWithFileSession(session, async () => {
-          await addAuthCommand({ provider: options.provider, scheme: options.scheme });
+          await addAuthCommand({ provider: options.provider, scheme: options.scheme, allowedProviders: options.allowedProviders });
         });
       });
     });
@@ -166,6 +169,7 @@ export async function planAuthOperation(options: PlanAuthOptions): Promise<AuthP
       JSON.stringify({
         provider: options.provider,
         scheme: options.scheme,
+        allowedProviders: options.allowedProviders,
         operations: operations.map((op) => ({ path: op.path, action: op.action })),
         fingerprints,
       })
@@ -178,6 +182,7 @@ export async function planAuthOperation(options: PlanAuthOptions): Promise<AuthP
     planType: "auth",
     provider: options.provider,
     ...(options.scheme ? { scheme: options.scheme } : {}),
+    ...(options.allowedProviders && options.allowedProviders.length > 0 ? { allowedProviders: options.allowedProviders } : {}),
     createdAt: new Date().toISOString(),
     swallowkitVersion: getSwallowKitVersion(),
     operations,
@@ -208,6 +213,7 @@ export function verifyAuthPlanFingerprints(
 export interface ApplyAuthOptions {
   provider?: string;
   scheme?: string;
+  allowedProviders?: string[];
   planId?: string;
   approve?: boolean;
 }
@@ -241,7 +247,7 @@ async function runCommitAuthOperation(options: PlanAuthOptions): Promise<{
     const tracked = await trackFileMutations(async () => {
       const captured = await captureConsoleMessagesWithError(async () => {
         await interceptProcessExit(async () => {
-          await addAuthCommand({ provider: options.provider, scheme: options.scheme });
+          await addAuthCommand({ provider: options.provider, scheme: options.scheme, allowedProviders: options.allowedProviders });
         });
       });
 
@@ -318,6 +324,7 @@ export async function applyAuthOperation(options: ApplyAuthOptions): Promise<App
   const effectiveOptions: PlanAuthOptions = {
     provider,
     scheme: options.scheme ?? basePlan?.scheme,
+    allowedProviders: options.allowedProviders ?? basePlan?.allowedProviders,
   };
 
   // 常に最新状態で collect し、競合を再確認する