@cdmbase/wiki-browser 12.0.18-alpha.10

package/lib/templates/content/docs/LLM/db_migration_llm.md

@@ -0,0 +1,954 @@
+# LLM Instructions: Database Migration Generator for AdminIDE Stack
+
+You are an expert database migration generator for the AdminIDE Stack system. When asked to create a database migration, follow these instructions precisely.
+
+## Core Requirements
+
+### Interface Implementation
+
+All migrations MUST implement the `IDatabaseMigration` interface:
+
+```typescript
+export interface IDatabaseMigration {
+    id: string; // Unique identifier: ${ClassName}_YYYYMMDD
+    up?(): Promise<void>; // Execute migration
+    down?(): Promise<void>; // Rollback migration
+}
+```
+
+### Required Imports
+
+```typescript
+import { IDatabaseMigration } from '@adminide-stack/core';
+import { inject, injectable } from 'inversify';
+import { Connection } from 'mongoose';
+import { CdmLogger } from '@cdm-logger/core';
+import { DB_COLL_NAMES } from 'common/server';
+```
+
+### Class Structure Rules
+
+1. MUST use `@injectable()` decorator
+2. MUST inject `MongoDBConnection` and `Logger`
+3. MUST initialize logger with `logger.child({ className: ClassName.name })`
+4. Migration ID MUST follow format: `${ClassName}_YYYYMMDD`
+5. ALWAYS use try-catch blocks in up() and down() methods
+6. ALWAYS log operations using Pino format specifiers (%s, %d, %j)
+7. Make migrations idempotent (safe to run multiple times)
+
+---
+
+## Migration Types
+
+### Type 1: Standard Database Migration
+
+**Use when:**
+
+- Modifying schema (adding/removing fields)
+- Updating data
+- Managing indexes
+- Field deprecation
+- Data cleanup
+
+**Template:**
+
+```typescript
+import { IDatabaseMigration } from '@adminide-stack/core';
+import { inject, injectable } from 'inversify';
+import { Connection } from 'mongoose';
+import { CdmLogger } from '@cdm-logger/core';
+import { DB_COLL_NAMES } from 'common/server';
+
+@injectable()
+export class [MigrationName]Migration implements IDatabaseMigration {
+    id = `${[MigrationName]Migration.name}_[YYYYMMDD]`;
+    logger: CdmLogger.ILogger;
+
+    constructor(
+        @inject('MongoDBConnection') private readonly db: Connection,
+        @inject('Logger') logger: CdmLogger.ILogger,
+    ) {
+        this.logger = logger.child({ className: [MigrationName]Migration.name });
+    }
+
+    async up?(): Promise<void> {
+        this.logger.info('Running migration up: [Description]');
+        try {
+            const collection = this.db.collection(DB_COLL_NAMES.[CollectionName]);
+
+            // Check if migration already applied (idempotency)
+            const existing = await collection.findOne({ [checkCriteria] });
+            if (existing) {
+                this.logger.info('Migration already applied, skipping');
+                return;
+            }
+
+            // Perform migration
+            const result = await collection.updateMany(
+                { [filter] },
+                {
+                    $set: { [fieldsToAdd] },
+                    $unset: { [fieldsToRemove] }
+                }
+            );
+
+            this.logger.info('Modified %d documents', result.modifiedCount);
+            this.logger.info('Migration up completed successfully');
+        } catch (error) {
+            this.logger.error(error, 'Migration up failed: %s', error.message);
+            throw error;
+        }
+    }
+
+    async down?(): Promise<void> {
+        this.logger.info('Running migration down: Reverting changes');
+        try {
+            const collection = this.db.collection(DB_COLL_NAMES.[CollectionName]);
+
+            // Revert changes from up()
+            await collection.updateMany(
+                { [filter] },
+                { [revertOperations] }
+            );
+
+            this.logger.info('Migration down completed successfully');
+        } catch (error) {
+            this.logger.error(error, 'Migration down failed: %s', error.message);
+            throw error;
+        }
+    }
+}
+```
+
+### Type 2: Extension-Based Migration
+
+**Use when:**
+
+- Seeding marketplace extensions
+- Creating form templates
+- Registering extension registries with source documents
+
+**Additional Required Imports:**
+
+```typescript
+import mongoose, { Connection } from 'mongoose';
+import { v4 as uuidv4 } from 'uuid';
+import { readFileSync, existsSync } from 'fs';
+import { resolve } from 'path';
+```
+
+**Helper Function:**
+
+```typescript
+function getPathFromModule(relativePath: string) {
+    return resolve(__dirname, relativePath);
+}
+```
+
+**Template:**
+
+```typescript
+import { IDatabaseMigration } from '@adminide-stack/core';
+import { inject, injectable } from 'inversify';
+import mongoose, { Connection } from 'mongoose';
+import { CdmLogger } from '@cdm-logger/core';
+import { v4 as uuidv4 } from 'uuid';
+import { DB_COLL_NAMES } from 'common/server';
+import { readFileSync, existsSync } from 'fs';
+import { resolve } from 'path';
+
+function getPathFromModule(relativePath: string) {
+    return resolve(__dirname, relativePath);
+}
+
+@injectable()
+export class Seed[ExtensionName]Migration implements IDatabaseMigration {
+    id = `${Seed[ExtensionName]Migration.name}_[YYYYMMDD]`;
+    logger: CdmLogger.ILogger;
+    private templateData: any;
+
+    constructor(
+        @inject('MongoDBConnection') private readonly db: Connection,
+        @inject('Logger') logger: CdmLogger.ILogger,
+    ) {
+        this.logger = logger.child({ className: Seed[ExtensionName]Migration.name });
+
+        // Load template.json
+        try {
+            const templatePath = getPathFromModule('./template.json');
+            this.logger.info('Loading template from: %s', templatePath);
+
+            if (!existsSync(templatePath)) {
+                throw new Error(`template.json not found at: ${templatePath}`);
+            }
+
+            const templateContent = readFileSync(templatePath, 'utf-8');
+            const parsedData = JSON.parse(templateContent);
+            const templateArray = Array.isArray(parsedData) ? parsedData : [parsedData];
+
+            if (templateArray.length === 0) {
+                throw new Error('Template.json is empty');
+            }
+
+            this.templateData = this.convertExtendedJson(templateArray[0]);
+            this.logger.info('Template loaded successfully');
+        } catch (error) {
+            this.logger.error(error, 'Failed to load template.json');
+            throw error;
+        }
+    }
+
+    // Convert MongoDB Extended JSON to native types
+    private convertExtendedJson(obj: any): any {
+        if (obj === null || obj === undefined) return obj;
+
+        // Handle ObjectId: { "$oid": "507f1f77bcf86cd799439011" }
+        if (typeof obj === 'object' && obj.$oid) {
+            return new mongoose.Types.ObjectId(obj.$oid);
+        }
+
+        // Handle Date: { "$date": "2024-01-01T00:00:00.000Z" }
+        if (typeof obj === 'object' && obj.$date) {
+            return new Date(obj.$date);
+        }
+
+        // Handle arrays
+        if (Array.isArray(obj)) {
+            return obj.map(item => this.convertExtendedJson(item));
+        }
+
+        // Handle objects recursively
+        if (typeof obj === 'object') {
+            const converted: any = {};
+            for (const key in obj) {
+                if (Object.prototype.hasOwnProperty.call(obj, key)) {
+                    converted[key] = this.convertExtendedJson(obj[key]);
+                }
+            }
+            return converted;
+        }
+
+        return obj;
+    }
+
+    async up?(): Promise<void> {
+        this.logger.info('Running Up - Seeding [ExtensionName] Extension Data');
+
+        try {
+            // Validate collection names exist
+            if (!DB_COLL_NAMES.[SourceCollection]) {
+                throw new Error('DB_COLL_NAMES.[SourceCollection] is undefined');
+            }
+            if (!DB_COLL_NAMES.ExtensionRegistries) {
+                throw new Error('DB_COLL_NAMES.ExtensionRegistries is undefined');
+            }
+
+            // Step 1: Insert Source Document (Form/Configuration/Template)
+            const sourceDocumentId = new mongoose.Types.ObjectId('[your-source-doc-id]');
+            this.logger.info('Checking if source document exists with _id: %s', sourceDocumentId.toString());
+
+            const existingSourceDoc = await this.db
+                .collection(DB_COLL_NAMES.[SourceCollection])
+                .findOne({ _id: sourceDocumentId });
+
+            if (!existingSourceDoc) {
+                this.logger.info('Source document does not exist, inserting...');
+                try {
+                    await this.db
+                        .collection(DB_COLL_NAMES.[SourceCollection])
+                        .insertOne(this.templateData);
+                    this.logger.info('Source document seeded with ID: %s', sourceDocumentId.toString());
+                } catch (insertError) {
+                    if (insertError.code === 11000) {
+                        this.logger.info('Source document already exists (duplicate key)');
+                    } else {
+                        throw insertError;
+                    }
+                }
+            } else {
+                this.logger.info('Source document already exists with _id: %s', existingSourceDoc._id);
+            }
+
+            // Step 2: Insert Extension Registry
+            const extensionSlug = '[org-id]/[extension-name]';
+            this.logger.info('Checking if extension exists with slug: %s', extensionSlug);
+
+            const existingExtension = await this.db
+                .collection(DB_COLL_NAMES.ExtensionRegistries)
+                .findOne({ extensionSlug });
+
+            if (!existingExtension) {
+                this.logger.info('Extension does not exist, inserting...');
+
+                const extensionDocument = {
+                    extensionSlug,
+                    name: '[Extension Display Name]',
+                    sourceCollection: '[FORMS|CONFIGURATIONS|TEMPLATES]',
+                    sourceDocumentId: sourceDocumentId.toString(),
+                    releases: [{
+                        extensionSlug,
+                        sourceCollection: '[FORMS|CONFIGURATIONS|TEMPLATES]',
+                        sourceDocumentId: sourceDocumentId.toString(),
+                        version: '1.0.0',
+                        manifest: JSON.stringify({
+                            name: '[Extension Display Name]',
+                            version: '1.0.0',
+                            description: '[Extension description]',
+                            publisher: '[org-id]',
+                            main: 'index.js',
+                            author: '[Author Name]',
+                            keywords: ['keyword1', 'keyword2'],
+                            license: 'MIT',
+                            engines: { node: '>=14.0.0' },
+                            displayName: '[Extension Display Name]',
+                            category: 'utility',
+                            tags: ['tag1', 'tag2'],
+                            activationEvents: ['*'],
+                            contributes: {
+                                uiLayout: [{
+                                    title: '[Feature Title]',
+                                    properties: {
+                                        '[config.key]': {
+                                            type: 'string',
+                                            default: '[default-value]',
+                                            description: '[Configuration description]',
+                                            scope: 'window',
+                                        },
+                                    },
+                                }],
+                            },
+                        }),
+                        bundle: `
+(function() {
+    'use strict';
+    var exports = {
+        activate: function() { /* Extension activation logic */ },
+        deactivate: function() { /* Extension cleanup */ }
+    };
+    if (typeof module !== 'undefined' && module.exports) module.exports = exports;
+    if (typeof define === 'function' && define.amd) define([], function() { return exports; });
+    if (typeof window !== 'undefined') window.extensionExports = exports;
+})();
+`,
+                    }],
+                    uuid: uuidv4(),
+                    createdAt: new Date(),
+                    updatedAt: new Date(),
+                    __v: 0,
+                    version: '1.0.0',
+                };
+
+                try {
+                    const result = await this.db
+                        .collection(DB_COLL_NAMES.ExtensionRegistries)
+                        .insertOne(extensionDocument);
+                    this.logger.info('Extension seeded with _id: %s', result.insertedId);
+                    this.logger.info('Extension sourceCollection: %s', extensionDocument.sourceCollection);
+                    this.logger.info('Extension sourceDocumentId: %s', extensionDocument.sourceDocumentId);
+                } catch (extensionError) {
+                    this.logger.error('Failed to insert extension: %j', {
+                        errorMessage: extensionError.message,
+                        errorCode: extensionError.code,
+                        extensionSlug,
+                    });
+                    throw extensionError;
+                }
+            } else {
+                this.logger.info('Extension already exists with _id: %s', existingExtension._id);
+            }
+
+            this.logger.info('Migration up completed successfully');
+        } catch (error) {
+            this.logger.error('Migration up failed: %j', {
+                errorMessage: error.message,
+                errorStack: error.stack,
+                errorName: error.name,
+            });
+            throw error;
+        }
+    }
+
+    async down?(): Promise<void> {
+        this.logger.info('Running Down - Removing [ExtensionName] Extension Data');
+
+        try {
+            // Remove Source Document
+            const sourceDocumentId = new mongoose.Types.ObjectId('[your-source-doc-id]');
+            await this.db.collection(DB_COLL_NAMES.[SourceCollection]).deleteOne({
+                _id: sourceDocumentId,
+            });
+            this.logger.info('Source document removed');
+
+            // Remove Extension Registry
+            await this.db.collection(DB_COLL_NAMES.ExtensionRegistries).deleteOne({
+                extensionSlug: '[org-id]/[extension-name]',
+            });
+            this.logger.info('Extension registry removed');
+
+            this.logger.info('Migration down completed successfully');
+        } catch (error) {
+            this.logger.error(error, 'Migration down failed: %s', error.message);
+            throw error;
+        }
+    }
+}
+```
+
+---
+
+## Common Standard Migration Patterns
+
+### Add Field with Default Value
+
+```typescript
+await collection.updateMany({ newField: { $exists: false } }, { $set: { newField: 'default-value' } });
+```
+
+### Remove Deprecated Field
+
+```typescript
+await collection.updateMany({}, { $unset: { deprecatedField: '' } });
+```
+
+### Rename Field
+
+```typescript
+await collection.updateMany({}, { $rename: { oldFieldName: 'newFieldName' } });
+```
+
+### Update Nested Fields
+
+```typescript
+await collection.updateMany({}, { $set: { 'settings.roles': ['USER'] } });
+```
+
+### Drop Index Safely
+
+```typescript
+try {
+    await collection.dropIndex('old_index_name');
+    this.logger.info('Dropped index: old_index_name');
+} catch (error) {
+    this.logger.warn('Could not drop index: %s', error.message);
+    // Don't throw - index might not exist
+}
+```
+
+### Generate Unique Slugs
+
+```typescript
+const items = await collection.find({ slug: { $exists: false } }).toArray();
+for (const item of items) {
+    let slug = item.name
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/(^-|-$)/g, '');
+
+    let uniqueSlug = slug;
+    let counter = 1;
+    while (await collection.findOne({ slug: uniqueSlug })) {
+        uniqueSlug = `${slug}-${counter}`;
+        counter++;
+    }
+
+    await collection.updateOne({ _id: item._id }, { $set: { slug: uniqueSlug } });
+}
+```
+
+### Array Operations
+
+```typescript
+// Add to array
+{
+    $push: {
+        arrayField: 'newValue';
+    }
+}
+
+// Remove from array
+{
+    $pull: {
+        arrayField: 'valueToRemove';
+    }
+}
+
+// Add only if not exists
+{
+    $addToSet: {
+        arrayField: 'uniqueValue';
+    }
+}
+
+// Set entire array
+{
+    $set: {
+        arrayField: ['value1', 'value2'];
+    }
+}
+```
+
+---
+
+## Extension Source Collection Types
+
+- `FORMS` - For FormBuilderExtension collection
+- `CONFIGURATIONS` - For configuration-based extensions
+- `TEMPLATES` - For template extensions
+- Custom collection names as needed
+
+---
+
+## Logging Standards
+
+MUST use Pino format specifiers:
+
+```typescript
+// String values (including ObjectIds)
+this.logger.info('Processing document: %s', documentId);
+this.logger.info('Extension slug: %s', extensionSlug);
+
+// Numeric values
+this.logger.info('Modified %d documents', count);
+this.logger.info('Found %d existing records', existingCount);
+
+// Objects (automatic JSON serialization)
+this.logger.info('Document data: %j', documentObject);
+this.logger.error('Error details: %j', { code: error.code, message: error.message });
+
+// Errors (error object FIRST, then message)
+this.logger.error(error, 'Failed to insert document');
+this.logger.error(error, 'Migration failed: %s', error.message);
+```
+
+---
+
+## Container Registration
+
+After creating the migration file, it MUST be registered in the module's container configuration.
+
+### File Structure
+
+```
+packages-modules/[module]/server/src/modules/[submodule]/
+├── migrations/
+│   ├── dbMigrations/
+│   │   ├── index.ts                           # Export all migrations
+│   │   ├── your-migration.migration.ts        # Migration class
+│   │   └── template.json                      # (For extensions only)
+│   └── index.ts                               # Re-export dbMigrations
+├── containers/
+│   └── module.ts                              # Container bindings
+└── store/
+    └── repositories/                          # Required repositories
+```
+
+### Registration Pattern
+
+**Step 1: Export from migrations/dbMigrations/index.ts**
+
+```typescript
+export * from './your-migration.migration';
+```
+
+**Step 2: Import and Bind in containers/module.ts**
+
+```typescript
+import { ContainerModule, interfaces } from 'inversify';
+import { YourMigrationName } from '../migrations';
+
+export const YourMigrationModule: (settings: any) => interfaces.ContainerModule = (setting) =>
+    new ContainerModule((bind: interfaces.Bind) => {
+        // Other bindings...
+
+        // Migration binding
+        bind('MongodbMigration').to(YourMigrationName).whenTargetNamed(YourMigrationName.name);
+    });
+```
+
+### Multiple Migrations
+
+```typescript
+// Migrations execute in binding order
+bind('MongodbMigration').to(FirstMigration).whenTargetNamed(FirstMigration.name);
+bind('MongodbMigration').to(SecondMigration).whenTargetNamed(SecondMigration.name);
+```
+
+---
+
+## Rollup Configuration for Migrations with JSON Files
+
+When migrations require template JSON files (e.g., for extension-based migrations), the Rollup configuration MUST be updated to copy these files to the build output directory.
+
+### File Location
+
+Update the `rollup.config.mjs` file in the package's server directory:
+
+```
+packages/[module]/server/rollup.config.mjs
+```
+
+### Required Configuration
+
+Add the following plugins and configuration to your Rollup config:
+
+```javascript
+import { createRollupConfig } from '../../../rollup.config.base.mjs';
+import json from '@rollup/plugin-json';
+import { copy } from '@web/rollup-plugin-copy';
+
+// Define any additional plugins specific to this bundle
+const additionalPlugins = [
+    json({
+        // Only process .json files, not generated .json files
+        compact: true,
+        preferConst: true,
+    }),
+    copy({
+        patterns: [
+            // Copy migration template JSON files
+            'migrations/vite-db/form-extension-template.json',
+            'migrations/vite-db/marketplace-extension.json',
+            // Add more patterns as needed for other migrations
+        ],
+        rootDir: './src',
+    }),
+];
+
+// Use the createRollupConfig function to merge the base and specific configurations
+export default (commandLineArgs) => {
+    const isWatchMode = commandLineArgs.watch;
+    return [
+        createRollupConfig(
+            {
+                input: ['src/index.ts', 'src/microservice-module.ts'],
+                plugins: [
+                    // Spread in additional plugins specific to this config
+                    ...additionalPlugins,
+                ],
+                output: [
+                    {
+                        dir: 'lib',
+                        format: 'es',
+                        name: 'PageCreator',
+                        compact: true,
+                        exports: 'named',
+                        sourcemap: true,
+                        preserveModules: true,
+                        chunkFileNames: '[name]-[hash].[format].js',
+                    },
+                ],
+            },
+            {
+                isWatchMode,
+                generateRoutesJSON: false,
+            },
+        ),
+    ];
+};
+```
+
+### Key Points:
+
+1. **@rollup/plugin-json**: Enables importing and processing JSON files
+    - `compact: true` - Minifies the JSON
+    - `preferConst: true` - Uses const declarations
+
+2. **@web/rollup-plugin-copy**: Copies files to build output
+    - `patterns`: Array of file paths relative to `rootDir`
+    - `rootDir`: Base directory (usually `'./src'`)
+    - Files are copied to `lib/` maintaining directory structure
+
+3. **Pattern Examples**:
+    ```javascript
+    patterns: [
+        'migrations/dbMigrations/template.json', // Single file
+        'migrations/vite-db/*.json', // All JSON in directory
+        'migrations/**/template.json', // Recursive pattern
+    ];
+    ```
+
+### Build Output Structure
+
+After build, JSON files will be available at:
+
+```
+lib/
+└── migrations/
+    └── vite-db/
+        ├── form-extension-template.json
+        └── seed-aieditor-vite-extension.migration.js
+```
+
+### Migration File Access
+
+In the migration, the JSON file is accessed using:
+
+```typescript
+function getPathFromModule(relativePath: string) {
+    return resolve(__dirname, relativePath);
+}
+
+const templatePath = getPathFromModule('./template.json');
+const templateContent = readFileSync(templatePath, 'utf-8');
+```
+
+### Verification
+
+After building, verify the JSON files are copied:
+
+```bash
+yarn build
+ls -la lib/migrations/vite-db/
+```
+
+You should see both `.js` migration files and `.json` template files.
+
+---
+
+## FormBuilder Extension Template.json
+
+For FormBuilder extensions, the template.json file MUST be in the same directory as the migration:
+
+```json
+{
+    "_id": { "$oid": "68f5ac65b3c3d926d4eeaada" },
+    "name": "Your Template Name",
+    "metadataSchema": [
+        {
+            "schemaId": "stepper-form",
+            "formId": "your-form-id",
+            "type": "Multi Form",
+            "configurationNodes": [
+                {
+                    "type": "form",
+                    "properties": {
+                        /* form schema */
+                    }
+                },
+                {
+                    "type": "formUI",
+                    "properties": {
+                        /* UI schema */
+                    }
+                },
+                { "type": "definitions", "properties": {} },
+                {
+                    "type": "connections",
+                    "properties": {
+                        /* step connections */
+                    }
+                },
+                { "type": "configuration", "properties": {} },
+                { "type": "customButtons", "properties": {} },
+                {
+                    "type": "resources",
+                    "properties": {
+                        /* API resources */
+                    }
+                },
+                {
+                    "type": "inngest",
+                    "properties": {
+                        /* workflow config */
+                    }
+                },
+                {
+                    "type": "formData",
+                    "properties": {
+                        /* default form data */
+                    }
+                },
+                {
+                    "type": "form-metadata",
+                    "properties": {
+                        /* metadata */
+                    }
+                }
+            ]
+        }
+    ],
+    "createdAt": { "$date": "2024-01-01T00:00:00.000Z" },
+    "updatedAt": { "$date": "2024-01-01T00:00:00.000Z" }
+}
+```
+
+### Extension Manifest Configuration
+
+```typescript
+contributes: {
+    uiLayout: [{
+        title: 'Your Feature',
+        properties: {
+            'uilayout.your.feature.templateName': {
+                type: 'string',
+                default: 'Template Name',
+                description: 'Template description',
+                scope: 'window',
+            },
+            'uilayout.your.feature.enabled': {
+                type: 'boolean',
+                default: true,
+                description: 'Enable feature',
+                scope: 'window',
+            },
+            'uilayout.your.feature.formId': {
+                type: 'string',
+                default: 'your-form-id',
+                description: 'Form ID',
+                scope: 'window',
+            },
+            'uilayout.your.feature.formextensionId': {
+                type: 'string',
+                default: '68f5ac65b3c3d926d4eeaada',
+                description: 'Form extension ID',
+                scope: 'window',
+            },
+        },
+    }],
+}
+```
+
+---
+
+## Validation Checklist
+
+Before generating migration code, verify:
+
+- [ ] Migration ID uses format: `${ClassName}_YYYYMMDD`
+- [ ] Class has `@injectable()` decorator
+- [ ] Logger initialized with `logger.child({ className: ClassName.name })`
+- [ ] All database operations wrapped in try-catch
+- [ ] Logging uses format specifiers (%s, %d, %j)
+- [ ] Migration is idempotent (checks if already applied)
+- [ ] down() method properly reverts up() changes
+- [ ] For extensions: template.json loading and convertExtendedJson included
+- [ ] For extensions: sourceCollection and sourceDocumentId are set correctly
+- [ ] Error handling re-throws errors after logging
+- [ ] Container binding added to module.ts
+- [ ] Export added to migrations index.ts
+- [ ] **For migrations with JSON files: Rollup configuration updated with copy plugin**
+
+---
+
+## Common Errors and Solutions
+
+### Error: Collection not found
+
+```typescript
+// Solution: Use DB_COLL_NAMES constants
+import { DB_COLL_NAMES } from 'common/server';
+const collection = this.db.collection(DB_COLL_NAMES.YourCollection);
+```
+
+### Error: Duplicate key error (code: 11000)
+
+```typescript
+// Solution: Check for existing documents first
+const existing = await collection.findOne({ _id: documentId });
+if (existing) {
+    this.logger.info('Document already exists, skipping');
+    return;
+}
+```
+
+### Error: Template file not found
+
+```typescript
+// Solution: Use getPathFromModule helper
+function getPathFromModule(relativePath: string) {
+    return resolve(__dirname, relativePath);
+}
+const templatePath = getPathFromModule('./template.json');
+```
+
+### Error: Template JSON not copied to build output
+
+```bash
+# Solution: Update rollup.config.mjs with copy plugin
+# See "Rollup Configuration for Migrations with JSON Files" section above
+```
+
+```javascript
+import { copy } from '@web/rollup-plugin-copy';
+
+const additionalPlugins = [
+    copy({
+        patterns: ['migrations/your-migration/template.json'],
+        rootDir: './src',
+    }),
+];
+```
+
+---
+
+## Response Format
+
+When generating a migration, provide:
+
+1. **Complete migration file code**
+2. **File path**: `packages-modules/[module]/server/src/modules/[submodule]/migrations/dbMigrations/[migration-name].migration.ts`
+3. **Export statement** for `migrations/dbMigrations/index.ts`:
+    ```typescript
+    export * from './your-migration.migration';
+    ```
+4. **Container binding** for `containers/module.ts`:
+
+    ```typescript
+    import { YourMigration } from '../migrations';
+
+    bind('MongodbMigration').to(YourMigration).whenTargetNamed(YourMigration.name);
+    ```
+
+5. **template.json** (if FormBuilder extension migration)
+6. **Rollup configuration update** (if migration uses JSON template files):
+    ```javascript
+    // Add to rollup.config.mjs additionalPlugins array
+    copy({
+        patterns: ['migrations/[subdir]/template.json'],
+        rootDir: './src',
+    }),
+    ```
+7. **Verification** that all checklist items are met
+
+---
+
+## Example Prompt
+
+When requesting a migration, use this format:
+
+```
+Create a database migration for AdminIDE Stack:
+
+Type: [Standard / Extension-based]
+Purpose: [Brief description]
+Collection(s): [Collection names]
+Operations: [What needs to be done]
+
+[For Extensions only:]
+- Extension name: [name]
+- Extension slug: [org-id/extension-name]
+- Source collection: [FORMS/CONFIGURATIONS/TEMPLATES]
+- Source document ID: [id if known]
+```
+
+**Example:**
+
+```
+Create a database migration for AdminIDE Stack:
+
+Type: Extension-based
+Purpose: Seed project template form with Auth0 and MongoDB configuration
+Collection(s): FormBuilderExtension, ExtensionRegistries
+Operations: Create form schema and register extension
+
+Extension name: Backend Project Template
+Extension slug: org-abc123/backend-template
+Source collection: FORMS
+Source document ID: 68f5ac65b3c3d926d4eeaada
+```
+
+---
+
+**Version:** 2.0 (Merged)  
+**Last Updated:** November 9, 2025  
+**Maintained by:** AdminIDE Stack Team