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

package/skills/dforge-mcp-author/references/excel-import.md

@@ -0,0 +1,61 @@
+# Importing a data model from a spreadsheet (.xlsx / .csv)
+
+When the user gives you a spreadsheet to turn into a module, you can't read a
+binary `.xlsx` directly — decode it first, then reason over the result.
+
+## Flow
+
+1. **Extract the sheets to a JSON model.** Load the bundled extractor resource
+   `dforge://script/xlsx-to-model`, write it to a temp file, and run it:
+
+   ```bash
+   python3 /tmp/xlsx_to_model.py "<path/to/file.xlsx>"
+   ```
+
+   It needs only Python 3 (pure standard library — no `pip install`). It prints
+   `{"sheets":[{"name":..,"headers":[..],"rows":[[..],..]}]}`. If it prints
+   `{"error":..}` (e.g. Python missing), fall back: ask the user to export each
+   sheet as **CSV** (CSV is plain text — read it directly).
+
+2. **Turn the model into a table-spec.** For each sheet:
+   - `name` = the sheet name, snake_cased (`"Order Lines"` → `order_lines`).
+   - One **column** per header: `name` = header snake_cased; `sampleValues` =
+     that column's values from `rows` (a few are enough). Don't set `fieldTypeCd`
+     unless you're sure — let the import infer it. Add a `sqlType` hint only when
+     the values make the type obvious (all integers → `int`, decimals → `numeric`,
+     `YYYY-MM-DD` strings → `date`; remember xlsx **dates arrive as numbers**, so
+     lean on the header name, e.g. `*_date`, to spot them).
+   - **References (FKs):** when a column looks like a foreign key — header
+     `<thing>_id` (or `<thing> id`) where `<thing>` matches another sheet — put it
+     in `references: [{ column, toTable }]` instead of as a plain column.
+   - Skip an `id` / primary-key column — the `identity` trait provides `{entity}_id`.
+
+3. **Show the proposed entity inventory for sign-off** (same gate as any Phase 1
+   scaffold), then call **`dforge_module_import`**:
+   - existing module → `{ moduleDir, tables }`
+   - new module → add `module: { code, displayName }` (greenfield).
+
+4. **Run `dforge_module_validate`** and refine the generated default grids to
+   surface the imported columns.
+
+## With data or empty — both work
+
+A sheet may be **populated** (headers + rows) or **structure-only** (headers, no
+data rows). Both produce a valid entity:
+
+- **Populated** → use the `sampleValues` for type inference (numbers, dates,
+  dropdowns). Best results.
+- **Empty (headers only)** → the extractor returns `"rows": []`. You still get
+  one column per header, but with no samples the import defaults most columns to
+  `text` — so lean on the **header name** (`email`, `phone`, `*_date`, `*_id` →
+  FK) and add `sqlType` hints where the user can tell you the type. Consider
+  confirming the inferred types with the user before importing.
+
+## Notes
+
+- One worksheet (or one Excel table object) = one entity. Ignore obviously
+  non-tabular sheets (dashboards, notes).
+- The extractor returns the first non-empty row as `headers`; if a sheet has
+  title rows above the real header, tell the user or adjust the spec by hand.
+- Type inference + the FK+Reference pattern are handled by `dforge_module_import`
+  against the `@dforge-core/metadata` registry — you only produce the table-spec.

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

@@ -0,0 +1,144 @@
+# Field Types Reference
+
+The canonical list of field types supported by dForge. **Do not invent new values — the set is fixed** and validated by the platform on module install.
+
+Source of truth: `server/database/system-modules/metadata/seed-data/field_types.json` in the dForge repo.
+
+> **You usually don't set `dbDatatype`.** For a plain data column, omit it — the field tools derive it from `fieldTypeCd` (the "Common `dbDatatype`" column below): `currency` → `numeric(18,2)`, `text` → `varchar`, `checkbox` → `bool`, etc. An explicit value is never overridden, so only set `dbDatatype` when you need to:
+> - **a hidden FK column** — it has no `fieldTypeCd`, so derivation can't fire; set `dbDatatype: "cuid"` to match the target entity's `identity` PK (see `column-types.md`);
+> - **override the size/precision** — e.g. `varchar(100)` via `maxLen`, or a specific numeric scale.
+>
+> Reference (`columnType: "R"`) and formula (`columnType: "F"`) columns never get a `dbDatatype` at all.
+
+## String-backed
+
+| `fieldTypeCd` | `baseDatatypeCd` | Description | Common `dbDatatype` | Params |
+|---|---|---|---|---|
+| `text` | `string` | Single-line text | `varchar` (with `maxLen`) | `maxLen` |
+| `email` | `string` | Email address. Client-side format validation. | `varchar` 250 | — |
+| `phone` | `string` | Phone/telephone. | `varchar` 50 | — |
+| `url` | `string` | Web URL. | `varchar` 500 | — |
+| `textarea` | `string` | Multi-line plain text. | `text` | `defaultLines`, `maxLines` |
+| `richtext` | `string` | Rich text editor (HTML). | `text` | — |
+| `code` | `string` | Code editor with syntax highlighting. | `text` | `language` |
+| `dropdown` | `string` | Fixed list of options. | `varchar` | `options: ["a","b",…]` or `[{value,label,icon,color}]` |
+| `flags` | `string` | Multiple checkboxes with letter flags. | `varchar` | `optionSets`, `style: "buttons"` |
+| `tags` | `string` | Free-form tag list. | `varchar` or `text` | — |
+| `color` | `string` | Color picker. | `varchar(20)` | — |
+| `hidden` | `string` | Internal, never shown in UI. | `varchar` | — |
+
+## Number-backed
+
+| `fieldTypeCd` | `baseDatatypeCd` | Description | Common `dbDatatype` | Params |
+|---|---|---|---|---|
+| `number` | `number` | Numeric value. | `int`, `bigint`, `numeric` | `min`, `max`, `scale` |
+| `currency` | `number` | Monetary value. Precision 2. | `numeric(18,2)` | `currency: "USD"`, `min`, `max` |
+| `percent` | `number` | Percentage 0–100. Precision 2. | `numeric(5,2)` | `min`, `max` (default 0–100) |
+
+## Boolean-backed
+
+| `fieldTypeCd` | `baseDatatypeCd` | Description | Common `dbDatatype` | Params |
+|---|---|---|---|---|
+| `checkbox` | `bool` | Boolean checkbox. | `bool` | — |
+
+> **`checkbox` is the only valid `fieldTypeCd` for boolean fields.** Do not use `bool`, `boolean`, or `toggle` as `fieldTypeCd` — those are not valid field type codes. (`bool` IS the correct `dbDatatype` for this field, but `checkbox` is the only correct `fieldTypeCd`.)
+
+## Date/time-backed
+
+| `fieldTypeCd` | `baseDatatypeCd` | Description | Common `dbDatatype` | Params |
+|---|---|---|---|---|
+| `date` | `date` | Calendar date only. | `date` | `min`, `max` (ISO strings or `TODAY()`) |
+| `datetime` | `timestamp` | Date + time with timezone. | `timestamptz` | `min`, `max` |
+| `time` | `time` | Time of day. | `time` | — |
+
+## Binary / file
+
+| `fieldTypeCd` | `baseDatatypeCd` | Description | Params |
+|---|---|---|---|
+| `file` | `binary` | Arbitrary file upload. | `accept`, `maxSize` |
+| `image` | `binary` | Image upload with preview. | `maxSize`, `dimensions` |
+
+## Reference / lookup / set
+
+| `fieldTypeCd` | `baseDatatypeCd` | `columnType` | Description |
+|---|---|---|---|
+| `lookup` | `guid` | `R` | Reference to another entity (always paired with a hidden FK column — see SKILL.md "FK+Reference pattern") |
+| `user` | `cuid` | `D` | User picker. Writes a user ID directly, no paired FK needed. |
+| `grid` | `set` | `S` | Detail grid of related records (1:N backwards reference). Used with `link` declaring the relation. |
+| `entitylink` | `json` | `D` | Polymorphic link to any entity (stores `{entity, id}` pair). |
+
+## JSON
+
+| `fieldTypeCd` | `baseDatatypeCd` | Description |
+|---|---|---|
+| `json` | `json` | JSON editor. Stored in `jsonb`. |
+
+---
+
+## Default values
+
+There is **no** `defaultValue` (or `default`) key on an entity data column — it fails schema
+validation (`entity.schema.json` is `additionalProperties: false`). To give a column a default:
+
+| Need | Do this |
+|---|---|
+| Literal / computed default (`'draft'`, `TODAY()`) | Carry a `formula` on the column (formula context — uppercase `TODAY()`/`NOW()`), e.g. `"formula": "'draft'"` or `"formula": "TODAY()"`. |
+| Document number (PO-2026-0001) | Declare a `numberSequence` on the entity — auto-fills on insert. |
+| Anything set at create time | Set it in an action/trigger DSL (`execute:` uses lowercase `now()`). |
+
+> `defaultValue` **is** valid on **module settings** (`settings.json`) — that's the only place it
+> belongs. Don't carry the settings habit over to entity fields.
+
+---
+
+## Common mistakes
+
+> **Wrong key name:** `fieldType` is a C# navigation property on the server model — it is not a valid JSON key in entity definitions. Always use `fieldTypeCd` (the string code). Using `fieldType: { ... }` or `fieldType: "date"` causes the platform to silently ignore the field type, producing null constraint errors on save.
+
+> **No `defaultValue` on entity fields:** `defaultValue` is a *settings* key, not a column key — on a field it fails schema validation. Set a column default with a `formula`, a `numberSequence`, or DSL logic (see "Default values" above).
+
+### Wrong `dbDatatype` values
+
+These are SQL type names LLMs tend to use for `dbDatatype`. **They are all wrong.** The right values come from the tables above.
+
+| Wrong `dbDatatype` | Right `dbDatatype` | Used with `fieldTypeCd` |
+|---|---|---|
+| `datetime` | `timestamptz` | `datetime` |
+| `timestamp` | `timestamptz` | `datetime` |
+| `boolean` | `bool` | `checkbox` |
+| `string` | `varchar` (with `maxLen`) or `text` | `text`, `textarea`, `dropdown`, … |
+| `integer` | `int` or `bigint` | `number` |
+| `float`, `double`, `decimal` | `numeric` | `number`, `currency`, `percent` |
+| `number` | `int`, `bigint`, or `numeric` | `number`, `currency`, `percent` |
+
+### Wrong `fieldTypeCd` values
+
+These are the field type names LLMs tend to invent. **They are all wrong.**
+
+| Wrong | Right |
+|---|---|
+| key `fieldType: { fieldTypeCd: "date", ... }` | key `fieldTypeCd: "date"` (plain string) |
+| key `fieldType: "date"` | key `fieldTypeCd: "date"` |
+| `bool`, `boolean` | `checkbox` |
+| `integer` | `number` |
+| `float` | `number` |
+| `decimal` | `number` with `scale` param |
+| `datePicker` | `date` |
+| `timestamp` | `datetime` |
+| `money` | `currency` |
+| `select`, `enum` | `dropdown` |
+| `multiselect` | `flags` or `tags` |
+| `autocomplete` | `lookup` |
+| `reference` | `lookup` |
+| `relation` | `lookup` or `grid` |
+| `link` | `url` |
+| `picture`, `photo` | `image` |
+| `attachment` | `file` |
+| `multiline` | `textarea` |
+| `richText`, `markdown` | `richtext` |
+| `userPicker` | `user` |
+| `phoneNumber` | `phone` |
+
+## When in doubt
+
+If the user describes a field type that isn't in this list (e.g. "rating stars", "geo location", "signature pad"), those field types **do not currently exist**. Do not fabricate a `fieldTypeCd` value. Tell the user what's available and ask how they'd like to model it with existing types (e.g. rating as `number` with `min: 1, max: 5`, geo location as two `number` columns or a `json` column).

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

@@ -0,0 +1,326 @@
+# Filter Format Reference
+
+dForge uses **one canonical JSON filter format everywhere** — folder row filters, data view filters, API filters, report dataset filters, and user ad-hoc filters. Learn it once, use it everywhere.
+
+This is the single filter format used across the entire dForge platform.
+
+## Basic structure
+
+A filter is either a **single condition** or a **group** of conditions.
+
+### Condition — single comparison
+
+```json
+{ "c": "status", "o": "=", "v": "draft" }
+```
+
+| Key | Type | Description |
+|---|---|---|
+| `c` | string | Column code (field name on the entity) |
+| `o` | string | Operator (see table below) |
+| `v` | any | Value to compare against |
+
+### Group — logical combination
+
+```json
+{
+    "g": "and",
+    "i": [
+        { "c": "status", "o": "=", "v": "draft" },
+        { "c": "amount", "o": ">", "v": 1000 }
+    ]
+}
+```
+
+| Key | Type | Description |
+|---|---|---|
+| `g` | string | Group operator: `and`, `or`, `!and` (NAND), `!or` (NOR) |
+| `i` | array | Items — conditions and/or nested groups |
+
+Groups can nest to arbitrary depth.
+
+## Operators
+
+### Condition operators
+
+| Operator | Description | Example value |
+|---|---|---|
+| `=` or `eq` | Equal | `"draft"` |
+| `!=` or `notEq` | Not equal | `"cancelled"` |
+| `>` or `gr` | Greater than | `1000` |
+| `>=` or `grEq` | Greater than or equal | `1000` |
+| `<` or `less` | Less than | `100` |
+| `<=` or `lessEq` | Less than or equal | `100` |
+| `between` or `btw` | Between (inclusive) | `[100, 500]` |
+| `!between` or `nBetween` | Not between | `[100, 500]` |
+| `contains` | Contains substring | `"acme"` |
+| `!contains` or `nContain` | Does not contain | `"test"` |
+| `start` | Starts with | `"INV-"` |
+| `!start` or `nStart` | Does not start with | `"DRAFT-"` |
+| `end` | Ends with | `".pdf"` |
+| `!end` or `nEnd` | Does not end with | `".tmp"` |
+| `mask` | Pattern match (SQL LIKE) | `"INV-2025-%"` |
+| `!mask` or `nMask` | Does not match pattern | `"TEST-%"` |
+| `null` or `empty` | Is null/empty | _(no `v` needed)_ |
+| `!null` or `nEmpty` | Is not null | _(no `v` needed)_ |
+| `in` | In a set | `["draft", "pending"]` |
+| `!in` or `nIn` | Not in a set | `["cancelled", "deleted"]` |
+| `eqRef` | Equal to another column | `"other_column_cd"` |
+| `f` | Function (dynamic runtime value) | `{ "fn": "isToday" }` |
+
+### Function operator — dynamic runtime values
+
+The function operator `f` evaluates a named function at query time instead of comparing against a static value. The value must be an object: `{ "fn": "<functionId>" }`.
+
+| Function | Column types | Description |
+|---|---|---|
+| `isToday` | date, timestamp | `column = CURRENT_DATE` |
+| `isYesterday` | date, timestamp | `column = CURRENT_DATE - 1` |
+| `isThisWeek` | date, timestamp | Within current ISO week |
+| `isThisMonth` | date, timestamp | Within current month |
+| `isThisYear` | date, timestamp | Within current year |
+| `isPast` | date, timestamp | `column < NOW()` |
+| `isFuture` | date, timestamp | `column > NOW()` |
+| `isCurrentUser` | guid | `column = <logged-in user ID>` |
+
+```json
+{ "c": "due_date", "o": "f", "v": { "fn": "isPast" } }
+```
+
+```json
+{ "c": "owner_id", "o": "f", "v": { "fn": "isCurrentUser" } }
+```
+
+Function conditions require **no value input** — the function provides the comparison logic at runtime.
+
+**Functions are valid only with the `f` operator.** They cannot be used as the value of `<`, `>`, `=`, `!=`, `between`, or any other comparison operator — each function already encodes its own comparison (e.g. `isPast` means "column < NOW()"). If you need to combine a dynamic-date check with another condition, put them as separate items in an `and`/`or` group:
+
+```json
+{
+    "g": "and",
+    "i": [
+        { "c": "due_date", "o": "f", "v": { "fn": "isPast" } },
+        { "c": "status", "o": "!=", "v": "done" }
+    ]
+}
+```
+
+These are **wrong** and will be rejected:
+
+```json
+{ "c": "due_date", "o": "<", "v": "@TODAY" }
+{ "c": "due_date", "o": "<", "v": { "fn": "isToday" } }
+```
+
+### Group operators
+
+| Operator | SQL equivalent |
+|---|---|
+| `and` | `A AND B AND C` |
+| `or` | `A OR B OR C` |
+| `!and` | `NOT (A AND B AND C)` — at least one is false |
+| `!or` | `NOT (A OR B OR C)` — none are true |
+
+## Where filters are used
+
+### 1. Folder row filters (`ui/folders.json`)
+
+Scope which records are visible in a subfolder. Used in `rowFilter` property on entity membership:
+
+```json
+"stock": {
+    "viewName": "default",
+    "quickAdd": true,
+    "rowFilter": { "c": "warehouse_id", "o": "eq", "v": 2001 }
+}
+```
+
+Generates: only stock records where `warehouse_id = 2001` appear in this folder.
+
+For compound filters on a folder:
+
+```json
+"rowFilter": {
+    "g": "and",
+    "i": [
+        { "c": "warehouse_id", "o": "eq", "v": 2001 },
+        { "c": "status", "o": "!=", "v": "archived" }
+    ]
+}
+```
+
+### 2. Data view filters (`ui/data_views.json`)
+
+Pre-filter which records appear in a data view:
+
+```json
+{
+    "active_leads": {
+        "viewType": "grid",
+        "label": "Active Leads",
+        "dataSources": [{
+            "entityCode": "lead",
+            "columns": ["name", "email", "stage", "owner_id"],
+            "filter": {
+                "g": "and",
+                "i": [
+                    { "c": "stage", "o": "!=", "v": "Closed Lost" },
+                    { "c": "stage", "o": "!=", "v": "Converted" }
+                ]
+            },
+            "sort": [{ "column_cd": "created_date", "direction": "desc" }]
+        }]
+    }
+}
+```
+
+### 3. Report dataset filters
+
+Same format inside report dataset definitions:
+
+```json
+"datasets": {
+    "ds_pipeline": {
+        "entityCode": "opportunity",
+        "columns": ["stage", "total_amount"],
+        "filter": {
+            "g": "and",
+            "i": [
+                { "c": "stage", "o": "!in", "v": ["Closed Won", "Closed Lost"] },
+                { "c": "total_amount", "o": ">", "v": 0 }
+            ]
+        },
+        "groupBy": ["stage"],
+        "aggregations": {
+            "total_value": { "func": "sum", "column": "total_amount" }
+        }
+    }
+}
+```
+
+### 4. API filters (`data.get` calls)
+
+Same format passed as the `filter` parameter in RPC calls:
+
+```json
+{
+    "method": "data.get",
+    "params": {
+        "entityCode": "contact",
+        "filter": { "c": "account_id", "o": "=", "v": "some-uuid" },
+        "columns": ["first_name", "last_name", "email"]
+    }
+}
+```
+
+### 5. Action DSL (`query()` is different!)
+
+**Important**: the `query()` function in action DSL uses **raw parameterized SQL**, NOT the JSON filter format:
+
+```javascript
+// This is SQL, not a JSON filter
+var results = query('SELECT * FROM crm.contact WHERE account_id = @accId AND status = @status', {
+    accId: [account_id],
+    status: 'active'
+})
+```
+
+The JSON filter format is only used in **declarative contexts** (folders, views, reports, API calls). Action DSL uses SQL directly.
+
+## Common examples
+
+### Filter by status (single condition)
+
+```json
+{ "c": "status", "o": "=", "v": "active" }
+```
+
+### Exclude multiple statuses
+
+```json
+{ "c": "status", "o": "!in", "v": ["cancelled", "deleted", "archived"] }
+```
+
+### Date range
+
+```json
+{
+    "g": "and",
+    "i": [
+        { "c": "created_date", "o": ">=", "v": "2026-01-01" },
+        { "c": "created_date", "o": "<", "v": "2026-04-01" }
+    ]
+}
+```
+
+Or using `between`:
+
+```json
+{ "c": "amount", "o": "between", "v": [1000, 5000] }
+```
+
+### Non-null check
+
+```json
+{ "c": "email", "o": "!null" }
+```
+
+### String matching
+
+```json
+{ "c": "invoice_number", "o": "start", "v": "INV-2026-" }
+```
+
+### Complex: active records in sales or marketing
+
+```json
+{
+    "g": "and",
+    "i": [
+        { "c": "is_active", "o": "=", "v": true },
+        {
+            "g": "or",
+            "i": [
+                { "c": "department", "o": "=", "v": "sales" },
+                { "c": "department", "o": "=", "v": "marketing" }
+            ]
+        }
+    ]
+}
+```
+
+### Column-to-column comparison
+
+```json
+{ "c": "ship_date", "o": "eqRef", "v": "order_date" }
+```
+
+Generates: `WHERE ship_date = order_date`
+
+## Filter composition at query time
+
+All filter layers are **ANDed together** automatically:
+
+```
+Effective filter = folder_row_filter AND view_filter AND api_filter AND user_ad_hoc_filter
+```
+
+The user never sees a record unless it passes **all** layers. You don't need to duplicate folder filters in view filters — they compose automatically.
+
+## Rules
+
+- **`null` filter** (or omitted) means no filtering — show everything the user has access to.
+- **Single condition** is valid without a group wrapper.
+- Use **short operators** (`=`, `!=`, `>`) or **enum keys** (`eq`, `notEq`, `gr`) — both work.
+- For folder `rowFilter` in module packages, prefer the short compact form: `{ "c": "...", "o": "eq", "v": ... }`.
+- Dates are ISO strings: `"2026-01-01"`.
+- Arrays for `in`/`between`: `["a", "b"]` or `[100, 500]`.
+
+## Common mistakes
+
+- Using the JSON filter format inside `query()` in DSL actions — **wrong**. `query()` uses raw SQL.
+- Wrapping a single condition in a group unnecessarily — **valid but noisy**. A bare condition is fine.
+- Using `"operator": "equals"` — **wrong**. Use `"o": "="` or `"o": "eq"`.
+- Using `"column": "status"` — **wrong**. Use `"c": "status"`.
+- Forgetting that `null` means "no filter" (not "filter by null") — to filter for null values, use `{ "c": "field", "o": "null" }`.
+- Putting a `{ "fn": "..." }` object (or `@TODAY`/`@CURRENT_USER` placeholder) as the value of a normal comparison like `<`, `>`, `=` — **wrong**. Functions are standalone conditions that only work with `"o": "f"`.

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

@@ -0,0 +1,73 @@
+# Column Flags Reference
+
+Column flags are single-letter codes concatenated into a string. Order doesn't matter — `"VEM"` and `"EMV"` are equivalent.
+
+Valid flags regex: `^[VIEMH]*$`
+
+## Flag letters
+
+| Letter | Name | Meaning |
+|---|---|---|
+| `V` | Visible | Column appears in grid / form / card views. Omit to hide from standard UI. |
+| `I` | Internal | Auto-managed by the platform. Used on PK columns, audit timestamps, system fields. Not shown in UI, not directly editable by users. |
+| `E` | Editable | User can modify the value in the UI. Omit for read-only. |
+| `M` | Mandatory | Required (NOT NULL + UI enforcement). |
+| `H` | Hidden | Permanently hidden — never shown, not even in admin metadata views. Stronger than omitting `V`. |
+
+**Only these 5 letters are valid.** The platform rejects any other characters.
+
+## Common column flag combinations
+
+| Flags | Meaning | Use case |
+|---|---|---|
+| `"VEM"` | Visible, Editable, Mandatory | Required field shown in UI (most business fields) |
+| `"VE"` | Visible, Editable, optional | Nullable field |
+| `"V"` | Visible, read-only | Display-only, like formula columns or computed values |
+| `"EM"` | Editable, Mandatory, **not visible** | Hidden FK columns in the FK+Reference pattern |
+| `"I"` | Internal | Trait-provided columns (PK, audit timestamps). Platform-managed. |
+| `""` (empty) | No flags | Rare — column exists but is invisible and not editable |
+
+## Rules
+
+1. **Hidden FK columns**: always `"EM"`. They must be writeable (E) and required (M), but never shown (no V).
+2. **Visible Reference columns**: always `"VEM"`. The user sees and edits the lookup picker.
+3. **Formula columns**: usually `"V"` (visible, read-only). The user never edits them.
+4. **Trait columns** (PK, audit): use `"I"` (internal). These are set automatically by `traits: ["identity", "audit"]`.
+5. **Don't use `I` on your own columns** — it's reserved for trait-provided and platform-managed columns.
+6. **Don't mix `I` with `V` or `E`** — internal columns are not user-facing.
+
+## Entity rights flags (different namespace — roles only)
+
+These letters appear in role `rights` declarations, **NOT** on column flags. Don't confuse them:
+
+| Letter | Permission | Used on |
+|---|---|---|
+| `S` | Select (read rows) | Entity in role `rights` |
+| `I` | Insert (create rows) | Entity in role `rights` |
+| `U` | Update (modify rows) | Entity in role `rights` |
+| `D` | Delete (remove rows) | Entity in role `rights` |
+| `C` | Clone (duplicate row) | Entity in role `rights` |
+| `E` | Execute | Actions, reports, folders in role `rights` |
+
+So `"SIUD"` on a role grants full CRUD; `"SI"` grants read + create only.
+
+**Note**: the `I` in column flags (Internal) and the `I` in role rights (Insert) are different concepts using the same letter. Context makes them unambiguous — column flags go on entity fields, role rights go on `security/roles.json`.
+
+## How uniqueness, PKs, and search work
+
+These are **NOT** flag letters. They're separate properties on the column definition:
+
+| Need | How to declare | NOT this |
+|---|---|---|
+| Primary key | `"isPk": true` (or use `identity` trait) | NOT a `P` flag |
+| Unique column | Add a unique index in the entity's `indexes` block, or `"isUnique": true` | NOT a `U` flag |
+| Searchable | Configure in data view columns or search settings | NOT an `S` flag |
+
+## Mistakes to avoid
+
+- Using `"U"` for unique — **not a valid flag**. Use `"isUnique": true` or indexes.
+- Using `"S"` for searchable — **not a valid flag**.
+- Using `"P"` for primary key — **not a valid flag**. Use `"isPk": true` or the `identity` trait.
+- Using `"VEM"` on trait-provided columns (PK, audit) — **don't**. Traits set their own flags (`"I"`).
+- Using `"I"` on business columns — **don't**. `I` means "platform-managed"; regular business columns use `V`/`E`/`M`.
+- Using long names like `"Visible,Editable"` — **wrong**. Single letters concatenated: `"VE"`.