@dforge-core/dforge-mcp 0.1.0-rc.9 → 0.1.1

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.

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

@@ -0,0 +1,243 @@
+# Data Views Reference
+
+Data views define how users see and interact with entity data. One entity can have many data views (grid, kanban, gallery, tree-grid, list, calendar, matrix, card).
+
+Lives in: `ui/data_views.json`
+
+## Structure
+
+```json
+{
+    "contact_list": {
+        "label": "All Contacts",
+        "description": "Primary list of contacts",
+        "viewType": "grid",
+        "icon": "bi-people",
+        "dataSources": [{
+            "entityCode": "contact",
+            "label": "Contacts",
+            "columns": [
+                { "column_cd": "first_name", "width": 150 },
+                { "column_cd": "last_name",  "width": 150 },
+                { "column_cd": "email",      "width": 220 },
+                { "column_cd": "phone",      "width": 130 },
+                { "column_cd": "account",    "width": 200 }
+            ],
+            "filter": null
+        }],
+        "order": ["last_name"]
+    }
+}
+```
+
+## Critical rule — `dataSources` array
+
+**Always** put `entityCode`, `columns`, and per-source `filter` inside a `dataSources` array. Never at the root. The view-level `order` and `filter` sit at the view-def root, alongside `viewType`.
+
+```json
+// WRONG — will fail validation
+{
+    "contact_list": {
+        "label": "Contacts",
+        "viewType": "grid",
+        "entityCode": "contact",        // WRONG — should be inside dataSources
+        "columns": [ /* ... */ ]        // WRONG — should be inside dataSources
+    }
+}
+
+// RIGHT
+{
+    "contact_list": {
+        "label": "Contacts",
+        "viewType": "grid",
+        "dataSources": [{
+            "entityCode": "contact",
+            "columns": [ /* ... */ ]
+        }]
+    }
+}
+```
+
+## View types
+
+| `viewType` | Description | `viewConfig` | When to use |
+|---|---|---|---|
+| `grid` | Spreadsheet-style table with sortable columns | — | Default for most entities; bulk data |
+| `list` | Compact list view | — | Mobile-friendly, card-sized items |
+| `kanban` | Columns grouped by a status field | `groupByField` | Workflow entities with stages (deals, tickets) |
+| `gallery` | Image-forward card grid | — | Image-heavy entities (products, real estate) |
+| `tree-grid` | Hierarchical grid with expand/collapse | — | Tree structures (folders, categories, org charts) |
+| `calendar` | Calendar display of date-based records | `dateField`, `titleField` | Schedules, due dates, events |
+| `matrix` | Pivot grid: `rowAxis` × `colAxis`, one value-source record per cell | `rowAxis`, `colAxis`, `cell` | Cross-tab data: P&L (accounts × periods), timesheets (tasks × days), budgets (categories × months) |
+| `card` | Single-record detail view | — | Record detail pages (implicit — every entity has one) |
+
+## View config (`viewConfig`)
+
+Some view types need additional configuration via the `viewConfig` property:
+
+### Kanban
+
+```json
+{
+    "opportunities_kanban": {
+        "viewType": "kanban",
+        "label": "Sales Pipeline",
+        "dataSources": [{
+            "entityCode": "opportunity",
+            "columns": ["opportunity_name", "account", "total_amount", "owner_id"]
+        }],
+        "viewConfig": {
+            "groupByField": "stage"
+        }
+    }
+}
+```
+
+`groupByField` — the dropdown/status column to group cards by. Each distinct value becomes a kanban column.
+
+### Calendar
+
+```json
+{
+    "invoices_calendar": {
+        "viewType": "calendar",
+        "label": "Invoice Calendar",
+        "dataSources": [{
+            "entityCode": "invoice",
+            "columns": ["invoice_number", "customer", "total_amount", "due_date"]
+        }],
+        "viewConfig": {
+            "dateField": "due_date",
+            "titleField": "invoice_number"
+        }
+    }
+}
+```
+
+- `dateField` — the date column that determines where records appear on the calendar
+- `titleField` — the column whose value is shown as the calendar event title
+
+### Matrix
+
+A pivot grid. The view's primary `dataSources` entity is the **cell** entity (one record per row×column intersection). `viewConfig` declares the two axes and how the cell record maps onto them.
+
+```json
+{
+    "income_statement_matrix": {
+        "viewType": "matrix",
+        "label": "Income Statement (Matrix)",
+        "dataSources": [{
+            "entityCode": "balance_register",
+            "columns": ["account_id", "period_key", "pl_amount"]
+        }],
+        "viewConfig": {
+            "rowAxis": {
+                "kind": "dataset",
+                "entity": "account",
+                "labelField": "account_name",
+                "filter": { "c": "statement", "o": "eq", "v": "IncomeStatement" },
+                "sort": [{ "col": "account_code", "dir": "asc" }]
+            },
+            "colAxis": {
+                "kind": "dataset",
+                "entity": "accounting_period",
+                "labelField": "description",
+                "lockedField": "closed",
+                "hideEmpty": true,
+                "sort": [{ "col": "period_key", "dir": "asc" }]
+            },
+            "cell": {
+                "entity": "balance_register",
+                "rowKey": "account_id",
+                "colKey": "period_key",
+                "fields": ["pl_amount"],
+                "editable": false,
+                "drill": true
+            }
+        }
+    }
+}
+```
+
+**`rowAxis` / `colAxis`** — what the rows and columns are. Three `kind`s:
+
+- `"dataset"` — axis values are an entity's records. `entity` + `labelField` required; optional `keyField` (defaults to the axis entity PK — what the cell's `rowKey`/`colKey` matches), `lockedField` (boolean column → that axis value's cells are read-only), `filter` (same `{c,o,v}` grammar as everywhere — scopes which axis records load), `hideEmpty` (**column axis only** — drop columns with no cell record in any row, e.g. periods with no postings; ignored if it would blank the whole grid), `sort` (`[{ col, dir }]`).
+- `"dropdown"` — axis values are a dropdown/flags column's options. Just `kind` + `column` (an `"entity.column"` reference). Codes line up by construction.
+- `"date"` — generated date window, **column axis only** (not valid on `rowAxis`). `kind` + `grain: "day"` + `window: "week"` (v1).
+
+**`cell`** — the value-source record at each intersection. `entity` (must match the primary dataSource), `rowKey` / `colKey` (cell columns matching the row/column axis keys), `fields` (cell columns rendered in each cell). Optional: `cardinality: "one"` (v1 default), `editable`, `drill` (read-only cells become clickable → open the cell record and its child sets), `seedFromRow` (`{ cellField: rowAxisField }` copied into new cell records on insert), `seedCurrentUser` (cell fields set to the current user id on insert).
+
+## Columns
+
+Each column is either a simple string or an object:
+
+```json
+"columns": [
+    "first_name",                                // just column code, default width
+    { "column_cd": "email", "width": 220 },      // with width override
+    { "column_cd": "account", "width": 200, "visible": true }
+]
+```
+
+## Filters
+
+Filters use dForge's canonical JSON filter format — see [filters.md](filters.md) for the full grammar. Keys are `c` (column), `o` (operator), `v` (value) for conditions, and `g` (group operator), `i` (items) for groups.
+
+Single condition:
+
+```json
+"filter": { "c": "status", "o": "=", "v": "active" }
+```
+
+Group:
+
+```json
+"filter": {
+    "g": "and",
+    "i": [
+        { "c": "status", "o": "=", "v": "active" },
+        { "c": "created_date", "o": ">", "v": "2026-01-01" }
+    ]
+}
+```
+
+Do **not** use `op`/`args`/`column`/`value` — that format is rejected.
+
+## Sort (`order`)
+
+Sort lives at the **view-def root** (not inside `dataSources[]`) under the key **`order`** — a `string[]` of column codes. Direction is encoded in the string itself:
+
+- Bare column code → **ascending** (the default; no prefix needed)
+- Leading `-` → **descending**
+
+```json
+"order": ["last_name", "first_name"]          // both ascending
+"order": ["-created_date"]                     // descending (audit trait provides created_date)
+"order": ["-created_date", "last_name"]        // primary desc, then asc tiebreak
+```
+
+The array order is the sort precedence: the first entry is the primary sort key, subsequent entries are tiebreakers.
+
+This matches the shape the runtime persists and `data.get` accepts. **Do not** use `"sort"`, `[{ column_cd, direction }]`, or `[{ c, d }]` here — those shapes belong to `query.run` and `report.run` (see [queries.md](queries.md)), not `data_views.json`.
+
+## Multi-source views
+
+A view can show data from multiple entities (e.g. a dashboard-style view mixing contacts and activities). Each entry in `dataSources` is independent with its own columns/filter.
+
+```json
+"dataSources": [
+    { "entityCode": "contact", "columns": [ /* ... */ ] },
+    { "entityCode": "activity", "columns": [ /* ... */ ] }
+]
+```
+
+Most views only have one source. Order is view-level and applies to the primary (level 0) source.
+
+## Common mistakes
+
+- Putting `entityCode` or `columns` at the root — **wrong**. They go inside `dataSources[]`.
+- Using `viewCode` or `view_cd` — **wrong**. The code is the dictionary key.
+- Using `"sort"` for data view ordering — **wrong**. The field is `"order"` and it lives at view-def root (not inside `dataSources[]`).
+- Object-array order like `[{ column_cd: "...", direction: "asc" }]` — **wrong shape for data views**. Use `string[]` with leading `-` for descending.
+- `viewType` is **optional** — omitted or unknown values fall back to `grid` at runtime. Set it explicitly for any non-grid view (`kanban`, `calendar`, `matrix`, …); a `matrix` view also **requires** a `viewConfig` with `rowAxis`/`colAxis`/`cell`.
+- Inventing view types like `"spreadsheet"` or `"table"` — **wrong**. Use `grid`.