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

package/skills/dforge-mcp-author/references/number-sequences.md

@@ -0,0 +1,117 @@
+# Number Sequences Reference
+
+dForge has built-in **automatic document numbering**. Declare a sequence on an entity, and any INSERT that leaves the target column empty gets the next value assigned automatically — no DSL, no manual counter, no race conditions.
+
+## Declaring on an entity
+
+```json
+{
+    "description": "Invoices",
+    "dbObject": "invoice",
+    "toString": "{number}",
+    "traits": ["identity", "audit"],
+    "numberSequence": {
+        "column": "number",
+        "pattern": "INV-{yyyy}-{seq:4}",
+        "resetPeriod": "year"
+    },
+    "fields": {
+        "number": {
+            "dbDatatype": "varchar",
+            "fieldTypeCd": "text",
+            "flags": "VEM",
+            "maxLen": 50,
+            "orderNum": 10,
+            "description": "Invoice Number"
+        },
+        /* ... */
+    }
+}
+```
+
+The platform:
+
+1. On INSERT, checks if the `number` column is empty.
+2. If empty, atomically increments the counter and formats the value.
+3. Writes it into the column before the row is committed.
+
+No code needed on your side. No DSL. No race conditions (the counter uses a database-level atomic operation).
+
+## Pattern placeholders
+
+| Placeholder | Meaning | Example |
+|---|---|---|
+| `{yyyy}` | 4-digit year | `2026` |
+| `{yy}` | 2-digit year | `26` |
+| `{mm}` | 2-digit month | `04` |
+| `{dd}` | 2-digit day | `08` |
+| `{seq:N}` | Zero-padded counter with N digits | `{seq:3}` → `001`, `002`, ... |
+
+You can combine them freely:
+
+```
+"INV-{yyyy}-{seq:4}"           → "INV-2026-0001"
+"Q{yyyy}{mm}-{seq:3}"          → "Q202604-001"
+"{dd}/{mm}/{yyyy}-{seq:2}"     → "08/04/2026-01"
+"PO-{seq:6}"                   → "PO-000001"
+```
+
+## Reset periods
+
+`resetPeriod` controls when the counter resets to 1:
+
+| Value | Resets |
+|---|---|
+| `"never"` | Counter never resets (monotonic forever) |
+| `"year"` | Counter resets on Jan 1 |
+| `"month"` | Counter resets on the 1st of each month |
+| `"day"` | Counter resets daily |
+
+If the pattern uses `{yyyy}` but `resetPeriod` is `"never"`, you get the same number each year — probably not what you want. Match the reset period to the pattern.
+
+## Prefix resolution via settings
+
+For multi-tenant or multi-folder setups, prefixes can come from module settings instead of being hardcoded. Declare a setting:
+
+```json
+// settings.json
+{
+    "invoice_prefix": {
+        "fieldTypeCd": "text",
+        "defaultValue": "INV",
+        "label": "Invoice Prefix"
+    }
+}
+```
+
+And reference it in the pattern:
+
+```
+"pattern": "$[invoice_prefix]-{yyyy}-{seq:4}"
+```
+
+Folder-scoped settings mean different folders can have different prefixes (e.g. `US-INV-2026-0001` in the US folder, `EU-INV-2026-0001` in the EU folder).
+
+## Cross-module sequences
+
+Sequences can be called from other modules via `nextNumber('<module>.<entity>')` in DSL actions:
+
+```
+execute:
+    invoice_num = nextNumber("fin.invoice")
+    notify("Next invoice number: " + invoice_num)
+```
+
+But most of the time, you don't need this — the automatic INSERT behaviour is enough.
+
+## Storage
+
+Counters are stored in `dForge.number_sequence` (definitions) and `dForge.number_sequence_counter` (atomic values). Don't touch these tables directly.
+
+## Common mistakes
+
+- Declaring a number column without a `numberSequence` and manually counting in a DSL — **unnecessary**. Use the platform.
+- Using `{seq}` without a width — the counter has no padding. Use `{seq:N}`.
+- Mismatching `resetPeriod` and placeholders — e.g. `resetPeriod: "month"` with a pattern like `{yyyy}-{seq:4}` (no month) means Jan and Feb start at 1 producing duplicate numbers.
+- Trying to set the number column manually on INSERT — it will be overwritten (unless you provide a non-null value, in which case the sequence respects it).
+- Forgetting `numberSequence` declaration and expecting it to "just work" — needs to be declared per entity.

package/skills/dforge-mcp-author/references/print-templates.md

@@ -0,0 +1,159 @@
+# Print Templates Reference
+
+dForge ships Liquid-based print templates. A record + its child sets are rendered to HTML, which the browser prints or saves as PDF.
+
+Lives in: `ui/print_templates.json` + HTML/CSS files under `print_templates/`. Schema: [`docs/schemas/print_templates.schema.json`](../../../docs/schemas/print_templates.schema.json). Full guide: [`docs/ui/print-templates.md`](../../../docs/ui/print-templates.md). QR + snippets: [`docs/ui/print-qr-codes.md`](../../../docs/ui/print-qr-codes.md).
+
+## Two render paths
+
+| Path        | Engine          | Used by                                                  |
+| ----------- | --------------- | -------------------------------------------------------- |
+| **Server**  | Scriban (Liquid) | `print.render` RPC — final print / save-as-PDF           |
+| **Client**  | LiquidJS         | Editor preview — fast iteration                          |
+
+Filters are mirrored on both sides so the preview matches the print.
+
+## Manifest structure
+
+```json
+{
+    "invoice": {
+        "entityCd": "invoice",
+        "description": "Invoice Print Form",
+        "file": "invoice.html",
+        "css": "invoice.css",
+        "pageSettings": {
+            "size": "A4",
+            "orientation": "portrait",
+            "margins": { "top": "15mm", "right": "15mm", "bottom": "15mm", "left": "15mm" }
+        }
+    },
+    "footer": {
+        "type": "snippet",
+        "description": "Shared invoice footer block",
+        "file": "footer.html"
+    }
+}
+```
+
+The key (`"invoice"`, `"footer"`) becomes `template_cd` on the row.
+
+## Field reference
+
+| Field          | Required        | Notes                                                                                                                              |
+| -------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| `type`         | No              | `"template"` (default) or `"snippet"`.                                                                                              |
+| `entityCd`     | Yes (templates) | Entity code. Cross-module form `"module.entity"` supported (bridge modules). Must be omitted on snippets.                          |
+| `description`  | No              | Label shown in the print menu.                                                                                                     |
+| `template`     | One of these    | Inline Liquid HTML.                                                                                                                |
+| `file`         | One of these    | Path relative to `print_templates/`.                                                                                               |
+| `css`          | No              | Inline CSS or a `.css` filename under `print_templates/`. Snippets typically inherit and omit.                                     |
+| `pageSettings` | No              | `{ size, orientation, margins }`. `size` ∈ `A4` / `letter` / `legal`. `orientation` ∈ `portrait` / `landscape`. Margins are CSS lengths. |
+
+## Template context (what you can read in Liquid)
+
+Every column on the entity is a top-level variable. Display formatting is pre-applied for dropdown / radio / flags / user columns.
+
+| Variable                | What it holds                                                                                          |
+| ----------------------- | ------------------------------------------------------------------------------------------------------ |
+| `{{ <column> }}`        | Display value: dropdown labels resolved, user names resolved, refs resolved to their display column     |
+| `{{ _fmt.<column> }}`   | Locale-aware **string**: `currency` → `"$1,234.56"`, `date` → `"5/22/2026"`, `bool` → `"Yes"`/`"No"`    |
+| `{{ _raw.<column> }}`   | Original code / id (use for CSS classes, predicates, wire-format payloads)                              |
+| `{{ _color.<column> }}` | Option color hex for single-value dropdown/radio columns                                                |
+| `{{ _settings.<cd> }}`  | Folder-resolved module setting. Image/file settings come as base64 data URIs (drop into `<img src>`).   |
+| `{{ _today }}`          | Typed `DateTimeOffset` (UTC); `{{ _fmt._today }}` is the pre-formatted string                          |
+| `{{ <set_name> }}`      | Child set — array. Iterate with `{% for x in <set_name> %}`. Only loaded if the template iterates it.   |
+| `{{ _css }}`            | The CSS string attached to the template (rarely needed in template body)                                |
+
+Inside a child-set loop, the same shape applies per row: `line._fmt.<col>`, `line._raw.<col>`, `line._color.<col>`.
+
+## Custom filters
+
+| Filter                                          | Example                                                | Output                       |
+| ----------------------------------------------- | ------------------------------------------------------ | ---------------------------- |
+| `format_currency: <currency>, <digits?>`        | `{{ amount | format_currency: 'USD' }}`                | `"$1,234.56"` (en-US)        |
+| `format_number: <decimals?>`                    | `{{ rate | format_number: 4 }}`                        | `"0.0125"`                   |
+| `format_date: <strftime>`                       | `{{ invoice_date | format_date: '%B %d, %Y' }}`        | `"May 22, 2026"`             |
+| `qr_code: <size?>, <ecc?>, <margin?>, <format?>`| `{{ payment_url | qr_code: 200, 'M' }}`                | `data:image/png;base64,…`    |
+
+`format_date` supports strftime: `%Y %m %d %B %b %H %M %S %I %p %A %a %e`.
+
+## Snippets
+
+Module-scoped Liquid partials. Pull one in via `{% include 'module_cd.snippet_cd' %}`. Snippets see all variables from the host template by default; pass overrides with `with`:
+
+```liquid
+{% include 'fin-sepa.epc_qr_block' %}
+{% include 'fin-sepa.epc_qr_block' with currency: 'EUR' %}
+```
+
+Declare a snippet with `"type": "snippet"`. No `entityCd`. The `template_cd` must not contain `.` (collides with the `module_cd.snippet_cd` separator).
+
+Full mechanics + an EPC SEPA QR worked example: [`docs/ui/print-qr-codes.md`](../../../docs/ui/print-qr-codes.md).
+
+## Module package layout
+
+```
+my_module/
+├── manifest.json
+├── ui/
+│   └── print_templates.json
+└── print_templates/
+    ├── invoice.html
+    ├── invoice.css
+    └── footer.html       (snippet)
+```
+
+## Example template
+
+```liquid
+<div class="invoice-header">
+  {% if _settings.company_logo %}
+    <img class="company-logo" src="{{ _settings.company_logo }}" />
+  {% endif %}
+  <h1>INVOICE {{ invoice_number }}</h1>
+  <p>Date: {{ _fmt.invoice_date }} · Due: {{ _fmt.due_date }}</p>
+  <p>Status: <span class="badge" style="--c: {{ _color.status }}">{{ status }}</span></p>
+</div>
+
+<table>
+  {% for line in lines %}
+    <tr>
+      <td>{{ line.description }}</td>
+      <td>{{ line.quantity }}</td>
+      <td>{{ line._fmt.unit_price }}</td>
+      <td>{{ line._fmt.line_total }}</td>
+    </tr>
+  {% endfor %}
+</table>
+
+<p>Total: <strong>{{ _fmt.total_amount }}</strong></p>
+
+{% if amount_paid > 0 %}
+  <p>Paid: -{{ _fmt.amount_paid }}</p>
+  <p>Due: {{ _fmt.amount_due }}</p>
+{% endif %}
+
+{% include 'fin.footer' %}
+```
+
+## Common mistakes
+
+- **Using `_fmt` in a predicate.** `{% if _fmt.amount_paid > 0 %}` compares strings. Use the bare reference: `{% if amount_paid > 0 %}`.
+- **Forgetting `_raw` for codes.** Direct `{{ status }}` is the label (`"Partially Paid"`). For CSS classes / wire-format payloads / predicates against codes, use `{{ _raw.status }}` (`"P"`).
+- **Manually formatting dates/currency.** Don't reach for `format_currency` when the column is already `fieldTypeCd: "currency"` — `_fmt.<col>` already matches the form. Use the filter only for derived values.
+- **Referencing a child set outside a `{% for %}`.** The platform only loads sets that appear in a `for` loop. `{{ lines.size }}` won't trigger the load.
+- **Snippet `template_cd` with a dot.** `{% include 'my_module.foo.bar' %}` — the resolver splits on the last dot only, so `my_module.foo` becomes the module name and breaks. No dots in snippet codes.
+- **Dropping CSS in `<style>` blocks inline.** The renderer wires `<style>` for you; declare CSS in the separate `.css` file (or inline string via the `css` field).
+- **Trying to use `TODAY()` / `NOW()` in a formula column expecting it to render in print.** The print-time formula evaluator skips those. Pre-compute via a formula column at insert time, or use `{{ _today | format_date: '...' }}` directly in Liquid.
+- **Module-installed template renamed in editor.** The editor preserves the original `template_cd` so `{% include %}` references stay intact — don't try to work around it.
+
+Module-installed print-template rows can't be deleted from the editor — uninstall the owning module to remove them.
+
+## Reference
+
+- Full developer guide: [`docs/ui/print-templates.md`](../../../docs/ui/print-templates.md)
+- QR codes + snippets guide: [`docs/ui/print-qr-codes.md`](../../../docs/ui/print-qr-codes.md)
+- JSON Schema: [`docs/schemas/print_templates.schema.json`](../../../docs/schemas/print_templates.schema.json)
+- Reference modules: [`modules/fin/`](../../../modules/fin/), [`modules/fin-ch/`](../../../modules/fin-ch/) (Swiss QR-bill), [`modules/crm/`](../../../modules/crm/), [`modules/wms/`](../../../modules/wms/), [`modules/hr/`](../../../modules/hr/)
+- Source: `server/src/dForge.Api/Services/PrintTemplateService.cs`, `server/src/dForge.Admin/Services/ModuleInstall/PrintTemplateRegistrar.cs`

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

@@ -0,0 +1,312 @@
+# Pre-Built Queries Reference
+
+Modules can ship **pre-built saved queries** — lightweight, explorable analytics that appear in the Query Builder alongside user-created queries. Think of them as "light reports" that are easier to author than full reports.
+
+Lives in: `ui/queries.json`
+
+## When to use queries vs reports vs views
+
+| Need | Use |
+|---|---|
+| Show entity records with filters/sort | **Data view** (`ui/data_views.json`) |
+| Simple aggregation — "totals by X" | **Pre-built query** (`ui/queries.json`) |
+| Ad-hoc exploration by the user | **Query Builder** (runtime, no module authoring needed) |
+| Complex multi-dataset visualizations with charts/KPIs | **Report** (`ui/reports.json`) |
+| Full SQL with window functions, CTEs, cross-schema | **Report with stored procedure** |
+
+Queries fill the gap between views (flat, no aggregation) and reports (heavy, need layout config).
+
+## Structure
+
+```json
+{
+    "overdue_invoices": {
+        "name": "Overdue Invoices",
+        "description": "All invoices past due date, not yet paid",
+        "entityCode": "invoice",
+        "query": {
+            "entityCd": "invoice",
+            "columns": [
+                "invoice_number",
+                "customer",
+                "total_amount",
+                "amount_due",
+                "due_date",
+                "days_overdue",
+                "owner_id"
+            ],
+            "filter": {
+                "g": "and",
+                "i": [
+                    { "c": "status", "o": "!=", "v": "Paid" },
+                    { "c": "status", "o": "!=", "v": "Cancelled" },
+                    { "c": "due_date", "o": "f", "v": { "fn": "isPast" } }
+                ]
+            },
+            "sort": [
+                { "c": "days_overdue", "d": "desc" }
+            ]
+        }
+    },
+    "revenue_by_customer": {
+        "name": "Revenue by Customer",
+        "description": "Total invoiced revenue grouped by customer",
+        "entityCode": "invoice",
+        "query": {
+            "entityCd": "invoice",
+            "columns": [
+                { "c": "customer", "agg": "group", "alias": "Customer" },
+                { "c": "total_amount", "agg": "sum", "alias": "Total Revenue" },
+                { "c": "invoice_number", "agg": "count", "alias": "Invoice Count" }
+            ],
+            "filter": {
+                "c": "status", "o": "!=", "v": "Cancelled"
+            },
+            "sort": [
+                { "c": "total_amount", "d": "desc" }
+            ]
+        }
+    }
+}
+```
+
+## Query JSON format
+
+The `query` object uses the **exact same format** as the Query Builder produces at runtime. This means you can:
+1. Design a query in the Query Builder UI
+2. Copy the JSON
+3. Paste it into `queries.json`
+
+### Flat mode (no aggregation)
+
+```json
+{
+    "entityCd": "contact",
+    "columns": ["first_name", "last_name", "email", "account", "owner_id"],
+    "filter": { "c": "email", "o": "!null" },
+    "sort": [{ "c": "last_name", "d": "asc" }]
+}
+```
+
+Columns are plain strings — field codes or reference paths (`"account.name"`, `"project.client.short_name"`).
+
+### Grouped mode (with aggregation)
+
+```json
+{
+    "entityCd": "opportunity",
+    "columns": [
+        { "c": "stage", "agg": "group", "alias": "Stage" },
+        { "c": "owner_id", "agg": "group", "alias": "Owner" },
+        { "c": "total_amount", "agg": "sum", "alias": "Total Value" },
+        { "c": "opportunity_id", "agg": "count", "alias": "Deal Count" },
+        { "c": "total_amount", "agg": "avg", "alias": "Avg Deal Size" }
+    ],
+    "filter": {
+        "c": "stage", "o": "!in", "v": ["Closed Won", "Closed Lost"]
+    },
+    "sort": [{ "c": "total_amount", "d": "desc" }]
+}
+```
+
+In grouped mode, each column is an object with:
+- `c` — column code (or reference path)
+- `agg` — aggregation: `group` (dimension), `sum`, `count`, `avg`, `min`, `max`
+- `alias` — display name for the result column
+
+At least one column must be `"agg": "group"` and at least one must be an aggregate.
+
+### Reference paths in columns
+
+Columns can traverse references up to 2 levels deep:
+
+```json
+"columns": [
+    "invoice_number",
+    "customer.account_name",
+    "customer.industry",
+    "owner_id"
+]
+```
+
+The query engine automatically JOINs the referenced entities.
+
+### Filters
+
+Filters use the standard JSON filter format (see `references/filters.md`): `{ "c": column, "o": operator, "v": value }`.
+
+### Dynamic date and user filters (function operator)
+
+Instead of hardcoded date values, use the **function operator** `"f"` with a `{ "fn": "..." }` value. This evaluates at query time on the server.
+
+**A function IS the whole condition — it bakes in the comparison.** You cannot pass a function as the value of `<`, `>`, `=`, `!=`, `between`, etc. Functions are ONLY valid with the `"o": "f"` operator, and each function encodes its own comparison logic (for example, `isPast` already means `column < NOW()`).
+
+| Function | Applies to | Description |
+|---|---|---|
+| `isToday` | date, timestamp | Current date |
+| `isYesterday` | date, timestamp | Previous day |
+| `isThisWeek` | date, timestamp | Current ISO week |
+| `isThisMonth` | date, timestamp | Current month |
+| `isThisYear` | date, timestamp | Current year |
+| `isPast` | date, timestamp | Before now |
+| `isFuture` | date, timestamp | After now |
+| `isCurrentUser` | guid | Matches the logged-in user |
+
+**Example — overdue items (due date is in the past):**
+
+```json
+{ "c": "due_date", "o": "f", "v": { "fn": "isPast" } }
+```
+
+**Example — records created this month:**
+
+```json
+{ "c": "created_date", "o": "f", "v": { "fn": "isThisMonth" } }
+```
+
+**Example — assigned to current user:**
+
+```json
+{ "c": "owner_id", "o": "f", "v": { "fn": "isCurrentUser" } }
+```
+
+### Sort
+
+```json
+"sort": [
+    { "c": "total_amount", "d": "desc" },
+    { "c": "customer", "d": "asc" }
+]
+```
+
+`d` is direction: `"asc"` or `"desc"`.
+
+## Wrapper properties
+
+Each query in `queries.json` has:
+
+| Property | Required | Description |
+|---|---|---|
+| `name` | Yes | Display name in the query list |
+| `description` | Recommended | Help text |
+| `entityCode` | Yes | The root entity this query targets |
+| `query` | Yes | The query JSON (flat or grouped format above) |
+
+## Menu integration
+
+Queries are not in menu and not integrated into menu, they have separate section in sidebar, nothing need to be configured additionally.
+
+## Translations
+
+Query names and descriptions are translated in `translations/en-US.json`:
+
+```json
+{
+    "queries": {
+        "overdue_invoices": {
+            "name": "Overdue Invoices",
+            "description": "All invoices past due date, not yet paid"
+        },
+        "revenue_by_customer": {
+            "name": "Revenue by Customer",
+            "description": "Total invoiced revenue grouped by customer"
+        }
+    }
+}
+```
+
+## Manifest declaration
+
+```json
+{
+    "queries": "./ui/queries.json"
+}
+```
+
+## Example queries for common module types
+
+### CRM — Pipeline by stage and owner
+```json
+{
+    "entityCd": "opportunity",
+    "columns": [
+        { "c": "stage", "agg": "group", "alias": "Stage" },
+        { "c": "owner_id", "agg": "group", "alias": "Owner" },
+        { "c": "total_amount", "agg": "sum", "alias": "Total Value" },
+        { "c": "opportunity_id", "agg": "count", "alias": "Count" }
+    ],
+    "sort": [{ "c": "total_amount", "d": "desc" }]
+}
+```
+
+### HR — Headcount by department
+```json
+{
+    "entityCd": "employee",
+    "columns": [
+        { "c": "department", "agg": "group", "alias": "Department" },
+        { "c": "employee_id", "agg": "count", "alias": "Headcount" },
+        { "c": "salary", "agg": "avg", "alias": "Avg Salary" }
+    ],
+    "filter": { "c": "status", "o": "=", "v": "Active" },
+    "sort": [{ "c": "employee_id", "d": "desc" }]
+}
+```
+
+### Finance — Receivables aging summary
+```json
+{
+    "entityCd": "invoice",
+    "columns": [
+        "invoice_number",
+        "customer",
+        "total_amount",
+        "amount_due",
+        "due_date",
+        "days_overdue",
+        "status"
+    ],
+    "filter": {
+        "g": "and",
+        "i": [
+            { "c": "status", "o": "!in", "v": ["Paid", "Cancelled"] },
+            { "c": "amount_due", "o": ">", "v": 0 }
+        ]
+    },
+    "sort": [{ "c": "days_overdue", "d": "desc" }]
+}
+```
+
+### WMS — Low stock items
+```json
+{
+    "entityCd": "stock",
+    "columns": [
+        "product",
+        "warehouse",
+        "quantity",
+        "reserved_qty",
+        "available_qty"
+    ],
+    "filter": { "c": "available_qty", "o": "<", "v": 10 },
+    "sort": [{ "c": "available_qty", "d": "asc" }]
+}
+```
+
+## Rules
+
+- The `query` object must use the same JSON format as the Query Builder produces.
+- Filters use the standard `c`/`o`/`v` format (see `references/filters.md`).
+- Module queries are **read-only** for users — they can run them and "Copy to My Queries" to modify.
+- Security is automatic — the query execution path respects entity, column, and row-level security.
+- Grouped queries need at least one `"agg": "group"` column and one aggregate column.
+- Reference paths go up to 2 levels deep (e.g. `"customer.country"` works, deeper may not).
+
+## Common mistakes
+
+- Putting SQL in the `query` object — **wrong**. Queries use the JSON format, not raw SQL. For raw SQL, use stored procedures in reports.
+- Using `"column"` instead of `"c"` in columns/filters — **wrong**. Use the short keys.
+- Forgetting `"agg"` on columns in grouped mode — every column needs an aggregation assignment.
+- Referencing columns from unrelated entities — queries can only traverse the root entity's references.
+- Using `@TODAY`, `@CURRENT_USER`, or any `@placeholder` syntax in filter values — **wrong**. Queries do not support parameter substitution. Use the function operator instead: `{ "c": "due_date", "o": "f", "v": { "fn": "isPast" } }`.
+- Using a function as the value of a comparison operator (`<`, `>`, `=`, `!=`, `between`) — **wrong**. Functions are standalone conditions, valid only with `"o": "f"` (full detail + examples under "Dynamic date and user filters" above). `{ "c": "due_date", "o": "<", "v": { "fn": "isToday" } }` is invalid; use `{ "c": "due_date", "o": "f", "v": { "fn": "isPast" } }`.