create-restforge-skills 1.0.0 → 1.0.2

package/skills/restforge/references/backend-pipeline.md

@@ -0,0 +1,388 @@
+# Reference: Backend Pipeline and Decisions
+
+Read this file when the intent router in SKILL.md points to the backend track
+(schema, payload, endpoint, dashboard, processor, consumer, SDK, launcher) and
+the next step is not obvious from the router row alone.
+
+## Table of Contents
+
+1. [Pipeline (canonical)](#pipeline-canonical)
+2. [Schema decisions](#schema-decisions)
+3. [RDF payload decisions](#rdf-payload-decisions)
+4. [Backend module type](#backend-module-type)
+5. [Soft-delete vs hard-delete](#soft-delete-vs-hard-delete)
+
+---
+
+## Pipeline (canonical)
+
+This is the canonical (golden) path. For state-dependent choices see the decision
+sections below; for failure handling see SKILL.md § Guardrails and
+troubleshooting.md.
+
+The sequence below applies to a **new project from scratch**. For an existing
+project, start from the step that matches the current state — do not re-run
+earlier steps that already succeeded.
+
+```
+1.  npx create-restforge-app <name>     ── PRIMARY ── human-run scaffolder
+      One shot: creates the project folder, runs
+      npm install @restforgejs/platform (local), and bundles the designer
+      binary. This is the dominant way to start a new project.
+      Granular alternative (agent scaffolds step by step):
+        setup_create_folder   → create the project folder.
+
+2.  setup_install_package               (granular path only)
+      Install @restforgejs/platform into the folder. SKIP when the project
+      was created with create-restforge-app (already installed). Plain
+      'npm install @restforgejs/platform' stays valid but is not the
+      primary entry point.
+
+3.  setup_init_config
+      Write config/db-connection.env from the default template.
+      setup_get_init_template returns that same template WITHOUT writing a
+      file — use it to compare an edited config against the defaults.
+
+4.  setup_write_env  /  setup_update_env
+      Set values: LICENSE, SERVER_ADDRESS, SERVER_PORT, DB_TYPE,
+      DB_HOST, DB_PORT, DB_USER, DB_PASSWORD, DB_NAME (9 required parameters).
+      Use setup_read_env to read existing values before overwriting.
+      Grounding for the full parameter set: setup_get_config_schema.
+
+5.  setup_validate_config
+      ── GATE ── Must pass before the first tool that takes a 'config'
+      parameter (it reads the .env or connects to the database). Validates
+      database connection and license. Running such a tool before this gate
+      passes produces uninformative errors. Steps 6-9 are file-only and may
+      run before the gate.
+      Read-only by default. Set autoCreateDb=true only when the target database
+      itself does not exist yet AND the user agreed to have it created: it runs
+      CREATE DATABASE on the server (postgres/mysql only, ignored for sqlite and
+      oracle), and validation has to be repeated afterwards.
+
+6.  Decide where the table structure comes from (§ Schema decisions):
+      New table   → the CLARIFY gate: the user names the fields and types, or
+                    explicitly hands the design to the agent.
+      Existing DB → step 7b.
+
+7.  codegen_get_dbschema_catalog
+      ── GROUNDING ── Source of truth for SDF syntax: field types,
+      constraints, shorthand syntax, relations, referential actions,
+      check operations, and the soft-delete contract. Ask only for the
+      sections the task needs ('section': fieldTypes, shorthandSyntax,
+      auditColumns, relationTypes, ...), once per session.
+      → references/dbschema-catalog.md
+
+7a. [author schema/<table>.js]    (new table — PRIMARY path)
+      Write the complete SDF with the Write tool: every agreed field, the
+      RESTForge conventions (§ Schema decisions), indexes, uniques,
+      checks, and relations. One file per table.
+    codegen_dbschema_template     (only when the user asks for a ready-made
+                                   template / reference example)
+    codegen_dbschema_init         (only when the user explicitly asks for a
+                                   draft / initial / skeleton file)
+7b. codegen_list_tables           (existing DB — what is actually in there)
+    → codegen_describe_table      (columns, PK, FKs, indexes of one table)
+    → codegen_dbschema_introspect (generate SDF from the actual schema)
+      list/describe are read-only catalog reads: they answer "what does this
+      database already hold?" without writing an SDF file. Use them before
+      introspecting a subset, and whenever a question about an existing table
+      would otherwise be answered from memory.
+
+8.  codegen_dbschema_validate
+      Validate SDF before any DDL is generated. Catch errors here, not at migrate.
+      File-only by default. With 'config' it also compares every model with the
+      database and gives one verdict per table: [OK], [DRIFT], or [ERROR] with
+      category table-missing or sdf-invalid. Exit code 1 in that mode is a
+      result (drift or error found), not a tool failure. SQLite is not
+      supported by the database mode.
+      codegen_dbschema_models (optional) lists the models already defined in the
+      SDF files with field count, primary key kind, indexes, uniques, relations.
+
+9.  codegen_dbschema_generate_ddl  (optional — preview DDL without executing)
+
+10a. codegen_dbschema_migrate      (empty DB — apply DDL directly)
+10b. codegen_dbschema_diff         (existing DB — review the differences first)
+     → codegen_dbschema_apply      (apply only after confirming the drift)
+
+11. codegen_get_field_validation_catalog
+      ── GROUNDING ── before defining fieldValidation in a payload.
+      → references/field-validation.md
+
+12. codegen_get_query_declarative_catalog
+      ── GROUNDING ── when the payload contains datatablesQuery, viewQuery,
+      viewName, exportQuery, or detailQuery.
+    codegen_validate_sql
+      Check the SELECT / WITH statement against the live database (EXPLAIN, no
+      rows executed) BEFORE pasting it into the payload: syntax, column
+      references, function existence, type compatibility, JOIN resolution.
+
+13. codegen_generate_payload
+      Generate payload JSON from a table. Foundation for all subsequent
+      codegen operations. 'detail' (a detail table name) also writes the
+      masterDetail block, the detail query file, and the composite actions.
+      Re-running it on an existing payload keeps the customisations made to
+      generator-owned keys; commit payload/.meta/<name>.json together with the
+      payload (see § RDF payload decisions).
+
+14. codegen_validate_payload
+      Validate the payload before codegen. Catch errors here.
+
+15. codegen_diff_payload   (when a payload exists and the DB schema has changed)
+    → codegen_sync_payload    (apply the schema drift to the payload)
+      'expandFk' (with 'table') also writes query/<table>-join.sql so
+      datatablesQuery (and viewQuery) show columns of referenced tables.
+
+16a. codegen_create_endpoint        (standard CRUD module)
+       Leave 'database' UNSET unless the user named a database: the CLI then
+       auto-detects DB_TYPE from the active config (fallback postgres), so a
+       MySQL/Oracle/SQLite project generates for its own dialect. 'config'
+       selects that .env explicitly. createDemo (default true) writes the
+       curl / Postman / Insomnia examples. force defaults to true — an existing
+       module is overwritten and the previous files are moved to
+       .restforge/archive/<run>/<original relative path> (the 5 most recent runs
+       are kept); force=false stops without writing anything when the module
+       exists, which is the closest thing to a conflict dry run.
+16b. codegen_get_dashboard_catalog
+     → codegen_validate_dashboard_payload
+       ── GATE ── structural check of a dashboard payload; writes nothing.
+       On a platform without 'dashboard create --validate-only' the tool
+       answers with an upgrade suggestion instead of a validation result — then
+       let the generator itself validate, since it runs the same validator
+       before it writes.
+     → codegen_create_dashboard     (analytic dashboard with SQL widgets)
+       No database auto-detection here: the dashboard command uses 'database'
+       when given and plain postgres otherwise, so pass it whenever the project
+       is not postgres. force defaults to true and then re-registers the project
+       under the database type carried by this call; force=false refuses cleanly
+       instead of writing.
+16c. codegen_create_processor       (background processing)
+16d. codegen_create_kafka_consumer  (Kafka event streaming)
+     → runtime_generate_consumer_launcher
+       Prepare a way to RUN that consumer: mode=host writes the fixed
+       consumer-start/consumer-stop pair in the project root, mode=pm2 produces
+       ecosystem.config.js + consumer-manager.sh in ./deploy/. 'config' is
+       required and must end with .env.
+     → (user runs the consumer) — the agent never starts it, same rule as the
+       server launcher below.
+
+17. codegen_generate_test   (optional)
+      Jest + Supertest integration test for an endpoint that ALREADY exists.
+      Natural follow-up once the module is generated.
+
+18. project_sdk_generate    (optional)
+      Write the JavaScript SDK source for the project (one resource file per
+      registered endpoint, plus client.auth when the backend auth extension is
+      installed) so a frontend calls client.<resource>.<verb>(payload). Source
+      only: the user runs install / build / deploy. Without force it refuses
+      when an SDK exists; with force=true it overwrites IN PLACE with no
+      archive, so local edits in the SDK folder are lost.
+
+19. runtime_check_launcher_exists  →  runtime_validate_preflight
+      →  runtime_generate_launcher
+      Check what is already there (read-only), validate the runtime
+      prerequisites, then write the launcher script. The agent STOPS here. The
+      user executes the launcher — the server runs independently of the agent
+      session.
+
+20. (user executes the launcher)
+
+21. runtime_check_status
+      Verify the server is running and endpoints are reachable.
+```
+
+Three hard checkpoints (SKILL.md § Guardrails): **step 5** is a gate — no tool that
+takes a `config` parameter before `setup_validate_config` passes; **step 6** is
+the clarify gate — no new table is written before its structure is settled;
+**step 19** is where the agent stops (it generates the launcher, never runs the
+server).
+
+**Payload naming differs per generator** — the value is handed to the CLI and
+each verb resolves it differently:
+
+| Tool | Accepted form |
+|---|---|
+| `codegen_create_endpoint`, `codegen_create_processor` | bare name, with or without `.json`; lowercased by the CLI; path forms are rejected |
+| `codegen_create_dashboard`, `codegen_validate_dashboard_payload` | name or relative path **with** the extension, used verbatim (`dash-sales.json`, `payload/dash-sales.json`) — nothing is appended |
+| `codegen_create_kafka_consumer` | name or path |
+
+**Config selection across calls.** Most backend tools take an optional `config`
+and otherwise fall back to the default recorded per working directory in
+`.restforge/defaults.json`. Manage that default instead of repeating the file
+name on every call: `setup_list_configs` (which `.env` files exist),
+`setup_set_default_config` (record one), `setup_get_default_config` (which one is
+active), `setup_clear_default_config` (remove it — afterwards every call must
+name its config explicitly).
+
+---
+
+## Schema decisions
+
+Pick the branch from **what the user asked for**, not from whether the database
+is empty. "Create a product table" is a request for a real table, never a request
+for a skeleton.
+
+- **New table, fields not stated** (e.g. "buatkan tabel product") → **CLARIFY
+  gate.** Ask once, in one short message, for the fields and their types
+  (optionally: required, unique, relations to other tables), and say the user may
+  leave the design to the agent. Write nothing and call no schema tool while
+  waiting: no `codegen_dbschema_init`, no `codegen_dbschema_template`, no file.
+- **New table, fields stated** (with or without types) → author the SDF from
+  them. Missing types are chosen from the field names and the conventions below;
+  ask only when a type is genuinely ambiguous. Do not add business fields the user
+  did not list, apart from the conventional PK and audit columns.
+- **New table, design handed to the agent** ("terserah", "tentukan sendiri",
+  "you decide", or no structure after the clarify question) → design the fields
+  from domain knowledge of the entity, then author the SDF with the conventions
+  below. Report the chosen structure briefly after the file is validated.
+- **RESTForge table conventions** (apply to every authored table; syntax from the
+  catalog):
+  - table name snake_case, singular (`product`, `stock_inbound_item`);
+  - primary key `<table>_id` as `string:36 pk`, or the PK style the other SDF
+    files of the project already use;
+  - foreign key named after the target PK (`category_id` →
+    `fk:category.category_id`), only to a table that exists in the schema folder
+    (`codegen_dbschema_models`) or that the user asked for — otherwise ask;
+  - business code `string:<n> unique notnull`, display name `notnull`,
+    money/quantity `decimal:15,2 default:0` with a `gte: 0` check, active flag
+    `is_active` as `boolean default:true`, an index on columns used for search;
+  - the 4 audit columns exactly as the catalog `auditColumns` section gives
+    them (`created_at`, `created_by`, `updated_at`, `updated_by`) — the RDF
+    generator assumes they exist.
+- **Explicit draft / initial / skeleton request** ("draft table", "inisial
+  table", "skeleton schema", "file awal untuk diisi sendiri") →
+  `codegen_dbschema_init`. It writes the generic `dummy` template (a sample
+  column per field type plus audit columns) for the user to edit. Never use it as
+  a first step before authoring a real table.
+- **Explicit template request** ("pakai template", "contoh schema invoice",
+  "template apa saja untuk ERP") → `codegen_dbschema_template` (list, show, or
+  generate).
+- **Table already in the database** → `codegen_dbschema_introspect` to generate SDF from the
+  actual schema. Do not hand-write a schema that a real DB can describe.
+- **Question about what the DB already contains** → `codegen_list_tables` (tables
+  and views) and `codegen_describe_table` (columns, primary key, foreign keys,
+  indexes of one table). Both are read-only live introspection; they are the
+  safe way to answer such a question without generating anything.
+- **Starting from a UI design** (HTML mockup, screenshot, image, Figma export)
+  → first confirm the design is an entity to model, not a dashboard/analytics
+  screen (those map to the Dashboard RDF branch below, not to a new SDF table).
+  Then classify visible elements into stored / derived / relation / audit, draft
+  the SDF, and run `codegen_dbschema_validate`. The design shows presentation,
+  not storage — do not turn every visible label into a column.
+  → references/design-to-sdf.md
+- **"Is my schema valid and in sync with the database?"** →
+  `codegen_dbschema_validate` with `config` (optionally `table`): one verdict per
+  table, `[OK]`, `[DRIFT]`, or `[ERROR]` (`table-missing` → migrate/apply fixes
+  it; `sdf-invalid` → fix the file). Exit code 1 means drift or an error was
+  found, not that the tool failed. Not available for SQLite.
+- **DB exists with drift** → `codegen_dbschema_diff` to review the per-column
+  differences, then `codegen_dbschema_apply`. Not `codegen_dbschema_migrate` —
+  that is for empty DBs only.
+
+---
+
+## RDF payload decisions
+
+- **No payload yet** → `codegen_generate_payload`.
+- **Payload exists, edit is API-layer only** (e.g. add/adjust `fieldValidation`,
+  messages, or a query — no column added or dropped) → ground via the matching
+  catalog, edit `payload/<name>.json`, run `codegen_validate_payload`, then regenerate
+  with `codegen_create_endpoint`. No DB migration: the schema (SDF) is unchanged.
+- **Payload exists, DB schema changed** → `codegen_diff_payload` first, then
+  `codegen_sync_payload`. Turning the RDF into a frontend UDF is a separate
+  frontend step (Frontend Pipeline step 2a), not part of this branch.
+- **Customisations survive regeneration.** `codegen_generate_payload` and
+  `codegen_sync_payload` keep edits made to generator-owned keys (`action`,
+  `fieldValidation`, inline SQL, `auditColumns`, the datatables query file).
+  A column deliberately removed from `fieldName` stays removed because generate
+  records the known columns in `payload/.meta/<name>.json`; commit that snapshot
+  with the payload and never edit it.
+- **Show columns of a referenced table in the list** (e.g. `supplier_name` next
+  to `supplier_id`) → `codegen_sync_payload` with `table` and `expandFk`
+  (`"both"`, or `"datatables-only"` to leave a custom `viewQuery` alone). It
+  writes `query/<table>-join.sql` and points `datatablesQuery` (and `viewQuery`)
+  at it; `FK_AUTO_JOIN` picks LEFT or INNER JOIN. The display column per FK is
+  chosen automatically and is never the primary key. Use `fkColumns`
+  (`ref_table.column`, or `local_fk:ref_table.column`) to override it and
+  `expandFkSkip` to leave a relation out. When the CLI reports "No natural
+  display column found", **ask the user** which column to show or whether to
+  skip that relation — do not pick one yourself.
+- **Custom query needed** → ground via `codegen_get_query_declarative_catalog`,
+  check the statement with `codegen_validate_sql` against the live database, then
+  set `datatablesQuery`, `viewQuery`, or `exportQuery` in the payload. External
+  SQL files use the `file:` prefix
+  (e.g. `"datatablesQuery": "file:sql/orders.sql"`). Validating first turns a
+  runtime 500 into an error message before the payload is even written.
+  A joined column must not reuse the name of a main table column
+  (`s.status_name AS status` when `status` is the FK column is rejected by
+  `codegen_validate_payload`, and `codegen_migrate_payload` then skips that
+  field). Select the main table column itself and give the joined column its
+  own name, e.g. `s.status_name`.
+
+> **"Add an uppercase / case constraint" is ambiguous — disambiguate first.**
+> In RESTForge `uppercase` is an RDF `fieldValidation` *normalization transform*
+> (forces the stored value to upper case), not a reject-if-not-uppercase
+> validator. If the user wants rejection, use `pattern`. If the user wants the
+> database to enforce it, that is an SDF check constraint, not RDF. Confirm which
+> one is meant before editing — see SKILL.md § Grounding-First Rules.
+
+---
+
+## Backend module type
+
+- **Standard CRUD** → `codegen_create_endpoint`. One payload = one module.
+- **Analytic dashboard** → `codegen_validate_dashboard_payload`, then
+  `codegen_create_dashboard`. Payload must have `widgets` (not `tableName`); page
+  name must be prefixed `dash-`; the payload argument keeps its `.json`
+  extension.
+- **Background job** → `codegen_create_processor`.
+- **Kafka event consumer** → `codegen_create_kafka_consumer`; requires
+  `KAFKA_ENABLED=true` in config. The consumer runtime is a separate process:
+  `runtime_generate_consumer_launcher` prepares it (host scripts or PM2 deploy
+  files) and the user starts it.
+- **JavaScript client for a generated project** → `project_sdk_generate`. Run it
+  after the endpoints exist, and after `project_auth` when the project needs
+  auth, so `client.auth` is included.
+- **Integration test for an existing endpoint** → `codegen_generate_test`.
+- **Every feature endpoint needs its `action` flag.** A feature block without
+  the matching flag in `action` produces no endpoint.
+  → references/rdf-advanced.md § The `action` Block
+- **Workflow (status transitions)** → set `action.workflow: true` and add a
+  `workflow` block (`statusField`, `transitions` as a map `status → [targets]`,
+  optional `hooks` keyed by target status) to the RDF; generates
+  `/change-status`. The buttons are UDF `workflowActions` — a frontend key that
+  never goes into the RDF.
+  → references/rdf-advanced.md § Workflow
+- **Master-detail (composite CRUD)** → run `codegen_generate_payload` with
+  `detail: "<detail table>"`. It writes the `masterDetail` block, the detail
+  query file, and `action.createComposite` / `updateComposite` /
+  `readComposite`; then fill `headerCalculations` and `calculated` formulas by
+  hand. Generates `/create-composite`, `/update-composite`, `/read-composite`.
+  → references/rdf-advanced.md § Master-Detail
+- **Summary numbers per resource** (count, sum, avg, min, max, optionally
+  grouped) → `action.aggregate: true`; the request body carries the operations,
+  and `aggregateConfig.joins` only whitelists JOINs. For charts or KPIs across
+  several tables, prefer a backend dashboard (`codegen_create_dashboard`).
+  → references/rdf-advanced.md § Aggregate Config
+- **Excel export** → `/export` works by default (falls back to
+  `SELECT {fields} FROM tableName`); customise the columns/filter with
+  `exportQuery` in the RDF payload. Tune `EXPORT_FILE_EXPIRY` / `EXPORT_CHUNK_SIZE`
+  in config. Ground `exportQuery` via `codegen_get_query_declarative_catalog`.
+  → references/rdf-advanced.md § Data Source Resolution
+- **Excel import (.xlsx)** → set `action.import: true` and add `importConfig`
+  with `enabled: true` (`upsertKeys`, `upsertStrategy`, `requiredFields`,
+  optional `lookupFields`) to the RDF payload; generates `/import-upload`,
+  `/import-preview`, `/import-commit`, and `/import-status`.
+  → references/rdf-advanced.md § Import Config
+  - Activate on an existing project: edit the payload to add `importConfig`
+    (and/or `exportQuery`) → `codegen_validate_payload` → `codegen_create_endpoint`.
+
+---
+
+## Soft-delete vs hard-delete
+
+- Use soft-delete when deleted rows must be audited or recoverable. Declare
+  `softDelete: { enabled: true }` in SDF and add the three contract columns
+  (`is_deleted`, `deleted_at`, `deleted_by`).
+- Soft-delete is supported on PostgreSQL only (Phase 1).
+- Tables with composite UNIQUE constraints are incompatible with soft-delete.

package/skills/restforge/references/data-seeding.md

@@ -0,0 +1,27 @@
+# Reference: Data Seeding and Migration (rows)
+
+Read this file when the user wants to export, import, seed, back up, or move
+table rows. Structure changes go through the dbschema tools, not through these.
+
+Move table **rows** through SDF-driven envelope files. This is for data, never
+for schema — use the dbschema tools for structure.
+
+**Default output location:** `data-storage/<schema>/<table>.json`, relative to the
+project cwd. The `data-storage` folder is the default of the `storagePath` param
+(CLI `--storage-path <folder>`); override it to write elsewhere. The SDF read from
+is `schemaPath` (CLI `--schema-path`, default `schema`).
+
+- **Export / dump / snapshot / back up rows** → `data_pull`. Scope is exactly one
+  of `table`, `schema`, or `allSchemas`. Only tables registered in the SDF can be
+  pulled. `force: true` overwrites existing envelope files. Optional `limit`,
+  `batchSize`, `config` (falls back to the default set via `config set-default`,
+  i.e. `.restforge/defaults.json`), `schemaPath`, `storagePath`.
+- **Import / load / seed / restore rows** → `data_push`. Same file names as
+  `data_pull`, so pulled files push back directly. Scope is exactly one of `table`,
+  `schema`, or `allSchemas`; for `schema`/`allSchemas` tables load in FK
+  parent→child order.
+- **Move data between databases** → `data_pull` from the source, then `data_push`
+  into the target (`config` selects the env per side).
+- ⚠ `data_push` is **APPEND-ONLY** (batch INSERT, no upsert/replace). Running it
+  twice inserts the rows twice. Confirm with the user before pushing into a
+  database that may already hold those rows.

package/skills/restforge/references/dbschema-catalog.md

@@ -158,8 +158,8 @@ Oracle enforces the same way. `codegen_dbschema_diff` treats `noAction` and
 
 ## Audit Columns
 
-4 standard columns for tables managed by RESTForge. Emitted automatically by
-`codegen_dbschema_init`. Lookup/system tables may remove them manually.
+4 standard columns for tables managed by RESTForge. Every authored table
+declares them with the shorthand below; lookup/system tables may leave them out.
 
 | Column | SDF shorthand | Notes |
 |---|---|---|

package/skills/restforge/references/field-validation.md

@@ -60,10 +60,10 @@ Constraints not listed for a given type will be rejected.
 
 | Type | Database Types | Applicable Constraints |
 |---|---|---|
-| `string` | VARCHAR, TEXT, CHAR | required, unique, default, primaryKey, autoGenerate, nullable, minLength, maxLength, pattern, patternMessage, format, enum, trim, lowercase, uppercase |
-| `integer` | INTEGER, INT, BIGINT | required, unique, default, primaryKey, nullable, min, max, precision, scale, positive, negative, integer, format |
-| `decimal` | DECIMAL, NUMERIC | required, unique, default, primaryKey, nullable, min, max, precision, scale, positive, negative, integer, format |
-| `number` | NUMERIC | required, unique, default, primaryKey, nullable, min, max, precision, scale, positive, negative, integer, format |
+| `string` | VARCHAR, TEXT, CHAR | required, unique, default, primaryKey, autoGenerate, nullable, minLength, maxLength, pattern, patternMessage, format, enum, notEqual, trim, lowercase, uppercase |
+| `integer` | INTEGER, INT, BIGINT | required, unique, default, primaryKey, nullable, min, max, precision, scale, positive, negative, integer, notEqual, format |
+| `decimal` | DECIMAL, NUMERIC | required, unique, default, primaryKey, nullable, min, max, precision, scale, positive, negative, integer, notEqual, format |
+| `number` | NUMERIC | required, unique, default, primaryKey, nullable, min, max, precision, scale, positive, negative, integer, notEqual, format |
 | `boolean` | BOOLEAN | required, unique, default, primaryKey, nullable, strict |
 | `date` | DATE | required, unique, default, primaryKey, autoGenerate, nullable, format, min, max, before, after |
 | `datetime` | TIMESTAMP | required, unique, default, primaryKey, autoGenerate, nullable, format, min, max, before, after |
@@ -105,6 +105,7 @@ Constraints not listed for a given type will be rejected.
 | `patternMessage` | string | — | `"patternMessage": "Invalid format"` |
 | `format` | string | `formatMessage` | `"format": "email"` (see format presets) |
 | `enum` | array | `enumMessage` | `"enum": ["active", "inactive"]` |
+| `notEqual` | string | `notEqualMessage` | `"notEqual": "none"` (derived from an SDF CHECK `neq`) |
 | `trim` | boolean | — | `"trim": true` |
 | `lowercase` | boolean | — | `"lowercase": true` |
 | `uppercase` | boolean | — | `"uppercase": true` |
@@ -126,6 +127,7 @@ Constraints not listed for a given type will be rejected.
 | `positive` | boolean | `positiveMessage` | `"positive": true` |
 | `negative` | boolean | `negativeMessage` | `"negative": true` |
 | `integer` | boolean | `integerMessage` | `"integer": true` |
+| `notEqual` | number | `notEqualMessage` | `"notEqual": 0` (derived from an SDF CHECK `neq`) |
 | `format` | string | — | `"format": "currency"` (the only valid value) |
 
 `format: "currency"` is a display hint, not a validator. `codegen_migrate_payload`

package/skills/restforge/references/frontend-pipeline.md

@@ -0,0 +1,178 @@
+# Reference: Frontend Pipeline and Decisions
+
+Read this file when the intent router in SKILL.md points to the frontend track
+(UDF, frontend page, plugin, designer generate).
+
+## Table of Contents
+
+1. [Pipeline (canonical)](#pipeline-canonical)
+2. [UDF decisions](#udf-decisions)
+3. [Regenerating an existing app](#regenerating-an-existing-app)
+4. [Page type](#page-type)
+5. [Plugin choice](#plugin-choice)
+
+---
+
+## Pipeline (canonical)
+
+This is the canonical (golden) path for the frontend track. It runs
+**independently** from the backend pipeline. The backend API must be running and
+reachable at `apiBaseUrl` before the generated frontend is useful, but the
+frontend can be defined and generated without the backend live.
+
+```
+1.  designer_list_plugins
+      ── GROUNDING ── list available output plugins before creating the UDF.
+      Built-in: vanilla-js-basic (no auth), vanilla-js-auth and
+      vanilla-js-custom (JWT auth + RBAC).
+      → references/udf-catalog.md § Plugins
+
+2a. codegen_migrate_payload   ── PRIMARY ── when a backend RDF payload exists
+      Convert the RDF into a split UDF set in the output folder (default
+      frontend/payload/): app-config.json, pages/<pageId>.json, the aggregator
+      <appCode>.json, and snapshots in .meta/pages/. Run it once per RDF with
+      the same output folder to add pages to one app. It derives fields, types,
+      lookups, details[], status filters, and the date patterns from the
+      backend, so start here instead of writing pages by hand.
+      Needs a license and the backend config (it takes `config`, so the
+      SKILL.md Guardrail 3 gate applies).
+2b. [hand-write the UDF]      only when there is no RDF to migrate from
+      Ground every key with designer_get_udf_catalog first.
+    designer_init_project      (optional) scaffold a project folder with the
+      assets of an auth-capable plugin (vanilla-js-auth / vanilla-js-custom).
+      It writes no UDF payload file.
+
+3.  designer_get_udf_catalog
+      ── GROUNDING ── call before editing any UDF page.
+      Returns valid field types, enums, limits, and validation constants for
+      the installed designer version.
+      → references/udf-catalog.md
+
+4.  [edit the UDF pages]
+      Edit pages/<pageId>.json (labels, layout, features, workflowActions) and
+      the aggregator (navigation, homepage). One page entry = one CRUD page or
+      one dashboard page. Re-running migrate later merges RDF changes into
+      these files without losing the edits (§ UDF decisions).
+
+5.  designer_validate_payload
+      ── GATE ── validate the UDF (the aggregator file). Catches structural
+      errors before generation. Run before preview or generate, every time.
+
+6.  designer_preview_files
+      Dry-run: list the files the generator produces, without writing to disk.
+      It does not read the output folder, so it cannot show which files a
+      re-generate will merge, keep, or skip.
+
+7.  designer_generate
+      Generate frontend HTML/JS/CSS from the aggregator. On an existing app it
+      merges into the files on disk (§ Regenerating an existing app).
+      The agent STOPS here — the user opens the output in a browser.
+```
+
+For plugin development (custom output plugins):
+
+```
+designer_scaffold_plugin   →  [develop plugin templates]
+  → designer_inspect_plugin    (verify plugin metadata and capabilities)
+  → designer_generate          (test generation with the custom plugin)
+```
+
+Two checkpoints (SKILL.md § Guardrails): **step 5** is a gate — never `designer_generate`
+an unvalidated payload; **step 7** is where the agent stops (generates files, does
+not serve or deploy).
+
+Licensing note: the Designer tools (`designer_preview_files`, `designer_generate`,
+etc.) do **not** require a RESTForge license, unlike the `codegen_*`, `runtime_*`,
+and `setup_validate_config` tools. `codegen_migrate_payload` is a `codegen_*`
+tool, so step 2a runs in the backend project folder.
+
+---
+
+## UDF decisions
+
+- **A backend RDF exists** → `codegen_migrate_payload`; do not write the page by
+  hand. Run it once per RDF into the same output folder to build one app.
+- **Re-running migrate** (RDF changed, or a page must pick up new columns) →
+  run it again **without** `overwrite`. Existing pages are merged: user edits
+  (labels, layout, removed fields, blocks) are kept and RDF changes to untouched
+  values are applied. Backend contract values (`apiPath`, `primaryKey`, `type`,
+  `required`, `maxlength`, `decimalPlaces`, `tableField`, lookup source, option
+  values) follow the RDF when both sides changed, with a warning. The merge uses
+  the snapshots in `<output>/.meta/pages/<pageId>.json`; commit them with the
+  pages and never edit them. The aggregator (`navigation`, `homepage`) and
+  `app-config.json` are merged too.
+- **`overwrite: true`** recreates the page from the RDF and discards every
+  customisation (the old file goes to `.restforge/archive/`). Confirm with the
+  user before using it.
+- **Date patterns** → `appConfig.dateFormat` / `dateTimeFormat` are rewritten
+  from the backend `DATEFORMAT` / `DATETIMEFORMAT` on every migrate. After the
+  backend changes them, re-run migrate and `designer_generate`; never edit the
+  frontend values to differ from the backend.
+
+---
+
+## Regenerating an existing app
+
+`designer_generate` without `overwrite` is the normal way to bring UDF changes
+into an app that already exists, for scope `app` and `form` alike. The user may
+edit the generated app files (`<page>.html`, `js/<page>.js`, `js/common.js`,
+`js/config.js`, `sidebar.html`, assets); the edits survive.
+
+- **Merge** — each text file is merged three-way against the snapshot of the
+  last generate in `<output parent>/.meta/<output folder>/` (for
+  `frontend/apps/<project>` that is `frontend/apps/.meta/<project>/`). User
+  edits are kept and UDF or template changes on untouched lines are applied.
+  The result lists a status per file: `written`, `merged`, `unchanged`, `kept`,
+  `conflict`, or `skipped`. Commit the `.meta` folder with the app, except
+  `conflicts/` (it has its own `.gitignore`); never edit it.
+- **Conflict** — a file whose edits clash with the new output is left untouched;
+  the version with conflict markers is in `.meta/<project>/conflicts/<path>`.
+  All other files are still processed and the command exits 1. That is a result
+  to relay, not a tool failure: resolve the file (apply the conflict version and
+  keep the user's intent), then run generate again. Do not use `overwrite` as
+  the fix.
+- **Managed lines** — `BACKEND_DATE_FORMAT` and `BACKEND_DATETIME_FORMAT` in
+  `js/common.js` (marked `restforge:managed`) always take the new value.
+- **Assets** — a modified asset (CSS, vendor bundle, image) is kept with a
+  warning; the new version is in `conflicts/<path>`.
+- **App generated before snapshots existed** — files that differ from the new
+  output are kept with a warning and the new version goes to `conflicts/<path>`.
+  The user merges by hand, or recreates one page with `scope: "form"`, `page`,
+  and `overwrite`.
+- **`index.html`** — merged like the shared files when it carries the
+  `RESTForge-Designer:LandingGenerated` marker. Without the marker it is never
+  replaced, even with `overwrite`, and is reported as `skipped`; a new page then
+  does not appear on the homepage. Remove the file or add the marker line back,
+  then generate with scope `app`.
+- **`overwrite: true`** recreates every file from scratch and discards the
+  customisations in all of them (each old file that differs is archived to
+  `.restforge/archive/`). Confirm with the user before using it.
+- **Not handled** — files of a page removed from the UDF are not deleted, and a
+  clean text merge is not proof that the logic still works; test the result in
+  the browser.
+
+---
+
+## Page type
+
+- **Standard CRUD page** → `pageType: "crud"` (default) with `apiPath`,
+  `primaryKey`, `displayField`, and `fields[]`.
+- **Dashboard page** → `pageType: "dashboard"` with a `dataSources` object
+  (`name → { url, method, body }`) and `rows[]` → `columns[]` → `widgets[]`.
+  → references/udf-catalog.md § Dashboard Page
+- **Page with approval workflow** → add `workflow` (`statusField` and
+  `transitions`, identical to the RDF) and `workflowActions[]` whose `actionId`
+  equals the target status. Add `fieldStates` to lock rows in final statuses.
+  → references/udf-catalog.md § Workflow Actions
+
+---
+
+## Plugin choice
+
+- **No auth** → `vanilla-js-basic`.
+- **Auth WITH RBAC, built into the app** → `vanilla-js-auth` or
+  `vanilla-js-custom` at `designer_init_project`. Use `noAuth: true` (`--no-auth`)
+  to get the plugin's UI without its auth.
+- **Custom branding / new plugin** → `designer_scaffold_plugin`.
+- **Bolt-on auth WITHOUT RBAC** → not a plugin; see auth.md § Choosing the mechanism.
+  → references/udf-catalog.md § Plugins

package/skills/restforge/references/rdf-advanced.md

@@ -26,7 +26,7 @@ before `codegen_create_endpoint` — a processor payload through
 `dateTimeFields`, `deleteReferences`, `softDelete`, and (for a table with an
 `is_active` column) `defaultScope`. Edit that file; do not write those keys by
 hand. Later `codegen_generate_payload` / `codegen_sync_payload` runs keep the
-customisations made to those keys (see SKILL.md § RDF Payload).
+customisations made to those keys (see backend-pipeline.md § RDF payload decisions).
 
 ---