@dforge-core/dforge-mcp 0.1.0-rc.11 → 0.1.0-rc.13

package/skills/dforge-mcp-author/references/column-types.md

@@ -0,0 +1,168 @@
+# Column Types Reference
+
+Every column has a `columnType` (optional for the default physical type). Seven values exist:
+
+| `columnType` | Physical DB column? | Description |
+|---|---|---|
+| (omitted) or `"D"` | Yes | **Data column** — default. Maps to a real SQL column. |
+| `"R"` | No | **Reference column** — virtual N:1 lookup. Paired with a hidden FK column (see FK+Reference pattern). |
+| `"S"` | No | **Set column** — virtual 1:N backwards reference. Used for detail grids. |
+| `"F"` | No | **Formula column** — virtual computed value. Evaluated by the formula engine. |
+| `"A"` | Yes | **Accumulation register column** — stores posted state for accumulation registers. Advanced (accounting modules). |
+| `"L"` | Yes | **Ledger register column** — stores posted state for double-entry bookkeeping. Advanced (accounting modules). |
+| `"G"` | Yes | **Generated column** — DB-level computed aggregate (e.g. SUM over child set via trigger, or PostgreSQL `GENERATED ALWAYS AS`). The aggregated child column **must be physical** (a `D` column) — never a virtual `F`/`R`/`S` column. For a simple roll-up total, prefer `F` (see below). |
+
+**For most module development, you'll only use D, R, S, and F.** Types A, L, and G are for advanced accounting/registry modules that use the `postable`, `accumulation`, or `ledger` traits.
+
+## Data columns (`columnType` omitted or `"D"`)
+
+Most columns. They map 1:1 to a physical SQL column.
+
+```json
+"first_name": {
+    "dbDatatype": "varchar",
+    "fieldTypeCd": "text",
+    "flags": "VEM",
+    "maxLen": 100,
+    "orderNum": 20,
+    "description": "First Name"
+}
+```
+
+## Reference columns (`columnType: "R"`)
+
+Virtual N:1 lookup. No physical column. Always **paired with a hidden FK column** that does hold the physical data. Together they form the **FK+Reference pattern**.
+
+```json
+// Hidden FK column — physical, hidden
+"account_id": {
+    "dbDatatype": "cuid",
+    "flags": "EM",
+    "orderNum": 90,
+    "description": "Account ID"
+},
+// Visible Reference column — virtual, shown as lookup picker
+"account": {
+    "columnType": "R",
+    "fieldTypeCd": "lookup",
+    "flags": "VEM",
+    "orderNum": 95,
+    "description": "Account",
+    "link": {
+        "entity": "account",
+        "thisKey": "account_id",
+        "otherKey": "account_id"
+    }
+}
+```
+
+Plus declare the FK constraint in the entity's `references` block:
+
+```json
+"references": {
+    "FK_Contact_Account": {
+        "from": { "field": "account_id" },
+        "to": { "entity": "account", "field": "account_id" }
+    }
+}
+```
+
+> **FK column `dbDatatype` must exactly match the referenced entity's PK `dbDatatype`.** Never guess.
+> - Entities using the `identity` trait → PK is `dbDatatype: "cuid"` → FK column must also be `"cuid"`
+> - Cross-module or legacy entities → call `dforge_module_inspect` on the referenced module and read the PK column's `dbDatatype` before declaring the FK
+> - **`bigint`, `integer`, `int8` are wrong values for FK columns** — even though `cuid` is physically stored as int8, the platform type name is `cuid`, not `bigint`
+
+**Why two columns?** The FK stores the actual value. The Reference column configures how the value is rendered in the UI (as a typeahead picker showing the target's `toString`). They must be kept in sync — column order in JSON doesn't matter but `orderNum` determines UI ordering.
+
+## Set columns (`columnType: "S"`)
+
+Virtual 1:N backwards reference. Shows a grid of related records on the parent's detail view.
+
+```json
+"activities": {
+    "columnType": "S",
+    "fieldTypeCd": "grid",
+    "flags": "VEM",
+    "orderNum": 150,
+    "description": "Activities",
+    "link": {
+        "entity": "activity",
+        "thisKey": "contact_id",    // column on THIS entity (parent PK)
+        "otherKey": "contact_id"    // column on the OTHER entity (FK back to parent)
+    }
+}
+```
+
+`link.entity` is the child entity. `link.thisKey` is the column on the current entity (typically the PK). `link.otherKey` is the FK column on the child entity pointing back to the parent.
+
+Set columns are **not** declared in the `references` block — the FK already lives on the child entity.
+
+## Formula columns (`columnType: "F"`)
+
+Virtual computed column. No physical storage. Value is calculated at runtime by the formula engine.
+
+```json
+"full_name": {
+    "columnType": "F",
+    "fieldTypeCd": "text",
+    "baseDatatypeCd": "string",
+    "flags": "V",
+    "orderNum": 25,
+    "formula": "[first_name] + ' ' + [last_name]",
+    "description": "Full Name"
+}
+```
+
+**Required fields for formula columns**:
+
+- `columnType: "F"`
+- `fieldTypeCd` — how to render it
+- `baseDatatypeCd` — **required** on formula columns even though there's no physical column; used for type inference
+- `flags: "V"` (usually — formula columns are almost always read-only)
+- `formula` — the formula expression
+- `orderNum`
+- `description`
+
+Do **not** include `dbDatatype` on formula columns (there's no physical storage).
+
+See `formulas.md` for syntax.
+
+## Roll-up totals over child rows — use `F`, not `G`
+
+To total a child set on a header (line items → order total, movements → quantity on hand),
+**use a Formula column (`"F"`) with `SUM([set].[field])`**. It is computed at query time, so it
+can reference **any** child column — including the child's own formula columns.
+
+```json
+// purchase_order.total_amount — query-time roll-up (installs cleanly)
+"total_amount": {
+    "columnType": "F",
+    "fieldTypeCd": "currency",
+    "baseDatatypeCd": "number",
+    "flags": "V",
+    "orderNum": 90,
+    "formula": "SUM([lines].[line_total])",      // line_total may itself be a formula column
+    "description": "Total Amount"
+}
+```
+
+> ⛔ **Never make a `G` (Generated) column aggregate a virtual `F` column.** A `G` aggregate is
+> maintained by a database trigger that reads the child's `OLD`/`NEW` *physical* values. A formula
+> (`F`) column has no physical storage, so the trigger references a column that doesn't exist and
+> **install fails** with `db_error: column old.<field> does not exist`. If you need a stored
+> (`G`) aggregate over a *derived* quantity (e.g. a signed movement quantity), make that child
+> column **physical** first — either a plain `D` column written by the action logic, or a
+> same-row `G`/`GENERATED ALWAYS AS` column with a `dbDatatype` — then aggregate that. For most
+> modules a query-time `F` roll-up is the right choice; reserve `G` for high-volume stored aggregates.
+
+## Quick reference: which columnType do I use?
+
+- **Plain text/number/date/etc. field that stores a value** → omit `columnType` (default `"D"`)
+- **"This contact belongs to one account"** → `"R"` (plus hidden FK)
+- **"This account has many contacts"** → `"S"` on the account side
+- **"Compute full_name from first_name + last_name"** → `"F"`
+- **"User picker" (points to admin.user)** → omit `columnType`, use `fieldTypeCd: "user"` (writes user ID directly, no paired FK)
+- **"Polymorphic link to any entity"** → omit `columnType`, use `fieldTypeCd: "entitylink"` (stored as JSON)
+- **"Roll-up total over child rows"** (line items → header total, movements → quantity on hand) → `"F"` with `SUM([set].[field])` (query-time; see "Roll-up totals" above). Reserve `"G"` for high-volume *stored* aggregates, and only over a **physical** child column — never over an `F` column.
+- **"Accumulation register state"** → `"A"` (advanced accounting — requires `postable` + `accumulation` traits)
+- **"Double-entry ledger state"** → `"L"` (advanced accounting — requires `postable` + `ledger` traits)

package/skills/dforge-mcp-author/references/conventions.md

@@ -0,0 +1,177 @@
+# Module Conventions Reference
+
+Rules that apply across the entire module package. Violating these produces technically-valid but non-idiomatic modules, and in several cases breaks the installer.
+
+## Naming
+
+| Thing | Convention | Example |
+|---|---|---|
+| Module `code` | lowercase, letters/digits/underscore | `crm`, `my_module`, `wms_fin` |
+| Entity keys / `dbObject` | `snake_case`, singular | `contact`, `opportunity_line` |
+| Column codes | `snake_case` | `first_name`, `account_id` |
+| Data view codes | `snake_case` | `contact_list`, `deal_kanban` |
+| Report codes | `snake_case` | `sales_pipeline` |
+| Action codes | `snake_case` | `change_stage`, `send_welcome` |
+| Menu codes | `snake_case` | `sales`, `pipeline` |
+| Role codes | `snake_case`, domain-specific | `sales_rep`, `sales_admin` |
+| Setting codes | `snake_case` | `vat_rate`, `invoice_prefix` |
+| Trait names | lowercase single word | `identity`, `audit` |
+| Seed data files | numbered prefix | `01-countries.json`, `02-currencies.json` |
+| Action DSL files | `<action_code>.dsl` | `change_stage.dsl` |
+| Reference keys | `FK_<FromEntity>_<Purpose>` | `FK_Contact_Account` |
+
+Everything is **case-sensitive**. Don't mix snake_case and camelCase.
+
+## File layout
+
+Standard module directory structure:
+
+```
+my_module/
+├── manifest.json
+├── README.md                    # module overview
+├── CHANGELOG.md                 # version history
+├── MODULE-INFO.md               # user-facing intro (shown in module picker)
+├── entities/
+│   └── <entity>.json
+├── logic/
+│   └── actions/
+│       └── <action>.dsl
+├── ui/
+│   ├── data_views.json
+│   ├── menus.json
+│   ├── actions.json
+│   ├── folders.json
+│   └── reports/
+│       └── <report>.json
+├── security/
+│   └── roles.json
+├── settings.json
+├── seed-data/
+│   ├── 01-<first>.json
+│   └── 02-<second>.json
+├── translations/
+│   └── de-DE.json              # IETF tags, one file per non-English locale
+├── print_templates/
+│   └── <template>.scriban
+├── files/                       # static assets
+└── webhooks.json                # optional
+```
+
+Only include what your module actually uses — not every module needs `print_templates/` or `webhooks.json`.
+
+## The FK+Reference pattern (again, because it's critical)
+
+**Every reference to another entity is two columns**:
+
+1. Hidden FK column with `flags: "EM"` and `dbDatatype` matching the target PK type
+2. Visible Reference column with `columnType: "R"`, `fieldTypeCd: "lookup"`, `flags: "VEM"`, and a `link` object pointing at the target
+
+Plus the actual FK constraint declared in the entity's `references` block.
+
+See `column-types.md` for the full example.
+
+## Bridge modules
+
+When two core modules need to integrate (e.g. CRM and Finance), create a **bridge module**:
+
+- Name it with a hyphen: `crm-fin`, `wms-fin`, `crm-pricing`
+- Depends on **both** core modules
+- Owns the integration: extension entities, cross-module actions, cross-module data views
+- Core modules stay independent and don't know about each other
+
+Extension entities in a bridge module have `"extends": "fin.invoice"` at the top. Physical columns in the extension go into a 1:1 ext table.
+
+## Seed data ordering
+
+Seed files run in numeric prefix order. Put entities with FK dependencies **after** their targets:
+
+```
+seed-data/
+├── 01-currencies.json          # no FKs, insert first
+├── 02-countries.json           # references currency
+├── 03-regions.json             # references country
+└── 04-offices.json             # references region
+```
+
+Each seed file has two top-level keys: `"entityCode"` (NOT `"entity"`) and `"records"` (array). **Using `"entity"` instead of `"entityCode"` is a silent failure** — the installer reads an empty entity code and the INSERT fails.
+
+Use explicit **numeric** PKs in seed data so cross-file references work. The `identity` trait creates `cuid` columns which are `int8` (bigint) — **NOT UUIDs**. Use simple integers like `1001`, `1002`:
+
+```json
+{
+    "entityCode": "country",
+    "records": [
+        { "country_id": 1001, "code": "US", "name": "United States" },
+        { "country_id": 1002, "code": "DE", "name": "Germany" }
+    ]
+}
+```
+
+**Common mistake**: using UUID strings like `"10000000-0000-0000-0000-000000000001"` — **wrong**. The `cuid` datatype is a numeric `int8`, not a UUID string. Seed data PKs must be numbers. Use a numbering scheme that avoids collisions (e.g. 1001-1099 for countries, 2001-2099 for regions, etc.).
+
+## Translations
+
+Translation files live in `translations/` and are named after the **IETF locale tag** (`de-DE.json`, `uk-UA.json`, etc.). Filenames are auto-discovered; declare which ones you ship in `manifest.supportedLocales`. English is the default — labels and descriptions live in entity/view JSON, so **don't** create `en.json` or `en-US.json` (they're skipped by the installer).
+
+```json
+// translations/de-DE.json
+{
+    "contact": "Kontakt",
+    "account": "Kunde",
+    "contact_list.label": "Alle Kontakte"
+}
+```
+
+Missing keys fall back to the English value declared in the source JSON.
+
+## Versioning — always bump before packaging
+
+The manifest has **two version numbers** that must be managed:
+
+| Field | When to bump | Example |
+|---|---|---|
+| `version` | **Every release** — any change at all (bug fix, feature, schema change) | `0.1.0` → `0.2.0` |
+| `dbSchemaVersion` | **Only when the DB schema changes** — new entity, new column, removed column, changed type, new constraint, new index | `0.0.1` → `0.0.2` |
+
+Both use **semver** (`MAJOR.MINOR.PATCH`).
+
+**Rules**:
+
+- If you added an action but no new columns → bump `version` only, keep `dbSchemaVersion`.
+- If you added a new entity or column → bump both `version` and `dbSchemaVersion`.
+- If you changed a view or menu → bump `version` only.
+- If you changed translations only → bump `version` only.
+- The installer uses `dbSchemaVersion` to decide whether to run schema migrations. Wrong version = skipped migrations.
+- **Never ship a package without bumping at least `version`** from the previous release. The installer may reject or silently skip a re-install with the same version.
+- For brand-new modules, start at `version: "0.1.0"` and `dbSchemaVersion: "0.0.1"`.
+
+## `orderNum` — always set it
+
+On every column, data view, menu item, setting, and action that appears in a list. Without `orderNum`, UI ordering is undefined. Use widely-spaced values (10, 20, 30, 40) so you can insert between them later.
+
+## Consistency across the module
+
+- All timestamps use the same trait (`audit`)
+- All primary keys use the same trait (`identity`) with consistent PK type (`cuid`)
+- All entities have `toString`
+- All views use `dataSources` array
+- All roles use `rights`
+- All menus use nested dicts + `dataViewCode`
+- All actions have `canExecute:` (even if it's just `true`)
+
+## Do not invent
+
+- Do not invent field types (`rating`, `geolocation`, `signature`) — not in the catalog
+- Do not invent column types beyond `D` / `R` / `S` / `F`
+- Do not invent role rights letters beyond `SIUDC` + `E`
+- Do not invent view types beyond the registered ones
+- Do not invent menu item types beyond `V` / `R` / `D` / `A`
+- Do not invent DSL functions
+- Do not invent formula functions
+
+If you genuinely need something new, **say so** and ask the user how to work around it with existing primitives.
+
+## Reference
+
+This file summarises the key conventions. If you need to verify a pattern not covered here, ask the user or check the reference modules in the `examples/` directory.

package/skills/dforge-mcp-author/references/data-migration.md

@@ -0,0 +1,270 @@
+# Data Migration Reference
+
+When the user has an existing database (typically after running the schema importer to produce a rough-cut module) and wants to **move the actual rows** into dForge, write them a migration script they can run locally.
+
+This assumes:
+- dForge is running locally (e.g. `docker compose up`).
+- The legacy database is reachable from the developer's machine.
+- The target is a **dev tenant**, never production.
+
+## Script template — Python / psycopg
+
+This is the most portable choice. Works against any source database with a Python driver, writes to dForge Postgres.
+
+```python
+#!/usr/bin/env python3
+"""
+Migration script: old_crm → dForge my_crm module
+Generated on 2026-04-08
+"""
+
+import argparse
+import sys
+import uuid
+import psycopg
+from datetime import datetime
+from typing import Dict
+
+MIGRATION_USER_ID = "00000000-0000-0000-0000-000000000001"  # override with --migration-user
+
+def cuid() -> str:
+    """Generate a new cuid-like identifier for target PKs."""
+    return str(uuid.uuid4())
+
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--source", required=True, help="Source DB connection string")
+    parser.add_argument("--target", required=True, help="Target dForge tenant DB connection string")
+    parser.add_argument("--migration-user", default=MIGRATION_USER_ID)
+    parser.add_argument("--dry-run", action="store_true", help="Simulate without committing")
+    args = parser.parse_args()
+
+    src = psycopg.connect(args.source)
+    tgt = psycopg.connect(args.target)
+
+    try:
+        with tgt.transaction():
+            pk_map: Dict[str, Dict[int, str]] = {}  # source_table → {source_id → target_id}
+
+            # Phase 1: parents (no FK deps)
+            migrate_accounts(src, tgt, pk_map, args.migration_user)
+            migrate_products(src, tgt, pk_map, args.migration_user)
+
+            # Phase 2: children (depend on parents)
+            migrate_contacts(src, tgt, pk_map, args.migration_user)
+            migrate_opportunities(src, tgt, pk_map, args.migration_user)
+
+            # Phase 3: grandchildren
+            migrate_opportunity_lines(src, tgt, pk_map, args.migration_user)
+            migrate_activities(src, tgt, pk_map, args.migration_user)
+
+            if args.dry_run:
+                print("[DRY RUN] Rolling back.")
+                raise SystemExit(0)
+
+        print("Migration committed successfully.")
+
+    except Exception as e:
+        print(f"Migration failed: {e}", file=sys.stderr)
+        sys.exit(1)
+    finally:
+        src.close()
+        tgt.close()
+
+
+def migrate_accounts(src, tgt, pk_map, migration_user):
+    print("Migrating accounts…")
+    pk_map["accounts"] = {}
+    with src.cursor() as sc, tgt.cursor() as tc:
+        sc.execute("SELECT id, name, phone, website, created_at FROM accounts")
+        count = 0
+        for row in sc:
+            old_id, name, phone, website, created_at = row
+            new_id = cuid()
+            pk_map["accounts"][old_id] = new_id
+            tc.execute(
+                """
+                INSERT INTO crm.account
+                    (account_id, name, phone, website, created_date, created_by, last_updated, last_updated_by)
+                VALUES (%s, %s, %s, %s, %s, %s, %s, %s)
+                """,
+                (new_id, name, phone, website, created_at or datetime.utcnow(),
+                 migration_user, created_at or datetime.utcnow(), migration_user),
+            )
+            count += 1
+    print(f"  {count} accounts migrated")
+
+
+def migrate_contacts(src, tgt, pk_map, migration_user):
+    print("Migrating contacts…")
+    pk_map["contacts"] = {}
+    skipped = 0
+    with src.cursor() as sc, tgt.cursor() as tc:
+        sc.execute("SELECT id, first_name, last_name, email, phone, account_id, created_at FROM contacts")
+        count = 0
+        for row in sc:
+            old_id, first_name, last_name, email, phone, old_account_id, created_at = row
+
+            # Resolve FK via pk_map
+            new_account_id = pk_map["accounts"].get(old_account_id)
+            if old_account_id and not new_account_id:
+                print(f"  Skipping contact {old_id}: account {old_account_id} not found in mapping")
+                skipped += 1
+                continue
+
+            new_id = cuid()
+            pk_map["contacts"][old_id] = new_id
+            tc.execute(
+                """
+                INSERT INTO crm.contact
+                    (contact_id, first_name, last_name, email, phone, account_id,
+                     created_date, created_by, last_updated, last_updated_by)
+                VALUES (%s, %s, %s, %s, %s, %s, %s, %s, %s, %s)
+                """,
+                (new_id, first_name, last_name, email, phone, new_account_id,
+                 created_at or datetime.utcnow(), migration_user,
+                 created_at or datetime.utcnow(), migration_user),
+            )
+            count += 1
+    print(f"  {count} contacts migrated, {skipped} skipped")
+
+
+# … migrate_products, migrate_opportunities, migrate_opportunity_lines, migrate_activities follow the same pattern
+
+
+if __name__ == "__main__":
+    main()
+```
+
+## Script template — Pure SQL (Postgres → Postgres via dblink)
+
+When both databases are PostgreSQL and you want the fastest possible migration, use `dblink` or `postgres_fdw`. This requires the `dblink` extension to be installed on the target.
+
+```sql
+-- migrate.sql — run against the dForge tenant DB
+-- Connect to the legacy source via dblink
+
+BEGIN;
+
+-- Ensure dblink is available
+CREATE EXTENSION IF NOT EXISTS dblink;
+
+-- Create a PK mapping temp table
+CREATE TEMP TABLE pk_map (
+    source_table text NOT NULL,
+    source_id    bigint NOT NULL,
+    target_id    text NOT NULL,
+    PRIMARY KEY (source_table, source_id)
+);
+
+-- Phase 1: Accounts
+INSERT INTO crm.account
+    (account_id, name, phone, website, created_date, created_by, last_updated, last_updated_by)
+SELECT
+    gen_random_uuid()::text,
+    src.name,
+    src.phone,
+    src.website,
+    COALESCE(src.created_at, NOW()),
+    '00000000-0000-0000-0000-000000000001'::text,
+    COALESCE(src.created_at, NOW()),
+    '00000000-0000-0000-0000-000000000001'::text
+FROM dblink(
+    'host=legacy.local dbname=old_crm user=readonly',
+    'SELECT id, name, phone, website, created_at FROM accounts'
+) AS src(id bigint, name text, phone text, website text, created_at timestamp)
+RETURNING account_id;
+
+-- Record mappings for FK resolution
+-- (In practice, do this in the same INSERT using a CTE with RETURNING)
+
+-- Phase 2: Contacts (needs account FK resolution)
+-- …
+
+COMMIT;
+```
+
+Pure SQL is faster but harder to read and debug. **Prefer the Python script unless the dataset is very large.**
+
+## Key rules
+
+### PK generation
+
+Source uses integer PKs, dForge uses cuid (string). Generate a **new cuid for every row** and record it in the mapping table. Never preserve source integer PKs.
+
+### FK resolution order
+
+Topologically sort the entities by FK dependencies. Parents first, then children, then grandchildren. If the source schema has cycles, break them: insert parents with NULL FKs first, then UPDATE the FKs in a second pass.
+
+### Audit fields
+
+Set `created_by` / `last_updated_by` to a designated migration user. The zero user (`00000000-0000-0000-0000-000000000001`) is a common convention for "system-generated" rows. Ask the user if you're unsure which user to attribute to. (Note: `created_by`/`last_updated_by` only exist if the entity uses `audit-full` trait; with just `audit`, only timestamps exist.)
+
+Set `created_date` / `last_updated` from source timestamps if available, otherwise `NOW()`. Note: dForge audit column names are `created_date` and `last_updated` — NOT `created_at`/`updated_at`.
+
+### Enum conversion
+
+If the schema importer converted a lookup table (like `statuses`) to a `dropdown` column, the migration script must map source integer FK values to the new string option values. Read `params.options` on the target column and the importer's `MIGRATION_NOTES.md` to find the mapping.
+
+### NULL handling
+
+Source column is nullable, but the target column has `NOT NULL` (because the importer detected `NOT NULL` or the user made it mandatory). The script should either:
+
+- Provide a sensible default, or
+- Skip the row and log it
+
+Never silently insert NULL into a NOT NULL column — it will fail.
+
+### Type conversions
+
+Common cases:
+
+- `varchar(50)` → `varchar(100)` — safe
+- `varchar(200)` → `varchar(100)` — **detect and truncate + warn, or skip + log**
+- `int` enum → `dropdown` string — use the importer's option map
+- Latin-1 → UTF-8 — re-encode bytes
+- Naive timestamp → timestamptz — assume a tz (ask user) or keep naive
+
+### Idempotency
+
+Wrap the migration in a transaction. A failed run rolls back cleanly. For re-runs, either:
+
+1. Truncate target tables before running (destructive — explicit user approval)
+2. Use `ON CONFLICT DO NOTHING` with deterministic PKs derived from source (e.g. `md5(source_id)`)
+3. Simply drop and reinstall the module, then re-run the migration
+
+Default: **transaction + fail-fast**. Let the user re-run after fixing whatever failed.
+
+## Dry-run mode
+
+**Always** include `--dry-run`. In dry-run mode:
+
+1. Connect to both DBs
+2. Run all SELECTs
+3. Do all transforms
+4. Print a summary: `"Would insert 1,243 accounts, 87 contacts, 3,412 activities. 12 rows would be skipped."`
+5. Rollback before committing
+
+The user reviews, then re-runs without `--dry-run` to apply.
+
+## What NOT to do
+
+- **Do not go through the dForge API.** The RPC stack is 100x slower than direct SQL and adds no safety for a one-shot migration. Direct INSERTs into the tenant DB are the right tool.
+- **Do not skip dry-run mode.** It's the only safe way to preview.
+- **Do not migrate to production without multiple explicit confirmations.** Dev/local only by default. If the user insists on production, make the script check `--i-know-this-is-production` and print a scary warning.
+- **Do not hardcode credentials.** Pass via arguments or env vars.
+- **Do not silently drop rows.** Every skipped row gets logged to stderr with a reason.
+- **Do not assume target tables exist.** Check first; bail if the module isn't installed.
+- **Do not migrate views, stored procs, or triggers.** Those are listed in `MIGRATION_NOTES.md` and converted manually to dForge constructs (formulas, actions, reports).
+
+## Produce a MIGRATION.md alongside the script
+
+When you generate the migration script, also generate (or update) a `MIGRATION.md` in the module folder with:
+
+- What the script does in plain English
+- How to run it (example command lines for dry-run and actual run)
+- What gets migrated and what doesn't
+- Known caveats specific to this dataset
+- Rollback instructions
+
+The user reads `MIGRATION.md` first, then runs the script.