create-restforge-skills 1.0.0 → 1.0.2

package/skills/restforge/SKILL.md

@@ -25,810 +25,267 @@ compatibility: >
 
 RESTForge is a deterministic, definition-first generator with two output tracks:
 
-- **Backend track** — SDF defines the database schema; RDF defines REST API
-  endpoints. One SDF produces identical DDL; one RDF payload produces an
-  identical endpoint module on every execution.
-- **Frontend track** — UDF defines the frontend application. One UDF payload
-  produces identical HTML/JS/CSS via `npx restforge-designer`, plugin-driven,
-  no build step required.
-
-The agent interacts with the platform **exclusively through MCP tools**. The
-agent does not write generation code itself, does not modify generated output,
-and does not guess options outside the catalog. All valid options come from the
-catalog returned by grounding tools.
-
-The platform exposes its capabilities as MCP tools grouped by domain: `health_*`,
-`setup_*`, `codegen_*`, `runtime_*`, `designer_*`, `data_*`, `key_*`,
-`project_*`, `license_*`. Two facts follow from this and shape every task:
-
-1. **The skill describes intent and order; the MCP server executes.** If the
-   RESTForge MCP server is not registered in the client, this skill cannot do
-   anything — there is nothing to call. Confirm the tools are available before
-   planning a multi-step operation.
-2. **The catalog is the source of truth, not memory.** Field types, constraints,
-   validation rules, and plugin capabilities belong to the *installed* platform
-   version. Always ground against the catalog before proposing definition
-   content (see Grounding-First Rules, below).
+- **Backend track** — SDF (`schema/<table>.js`) defines the database schema; RDF
+  (`payload/<name>.json`) defines a REST API resource. One SDF produces identical
+  DDL; one RDF produces an identical endpoint module on every run.
+- **Frontend track** — UDF (`frontend/payload/`: `app-config.json`,
+  `pages/<pageId>.json`, and the aggregator `<appCode>.json`) defines the
+  frontend. `npx restforge-designer` turns it into HTML/JS/CSS, plugin-driven.
+
+Because the generators are deterministic, speed and correctness depend on two
+things only: turning the user's intent into the right tool, and running the
+tools in the right order. This file is the router for both. Detail lives in
+`references/`, read only when its branch is relevant.
+
+The agent works **through MCP tools** (`health_*`, `setup_*`, `codegen_*`,
+`runtime_*`, `designer_*`, `data_*`, `key_*`, `project_*`, `license_*`). It does
+not hand-write generator output, does not edit generated files, and does not
+guess options outside the catalog.
 
 ---
 
-## Preflight (run before any RESTForge task)
-
-Verify readiness before planning or producing anything:
-
-1. **Are the RESTForge MCP tools present?** Look for `codegen_*` / `designer_*`,
-   including client-prefixed names such as `mcp__restforge__codegen_*`. If the
-   client supports deferred tool discovery, search for RESTForge tools first.
-   If they remain unavailable, the MCP server is **not active**. Stop and tell the
-   user to register the RESTForge MCP server and restart the client. Do **not**
-   finish the task by hand-reading the bundled `references/` — that bypasses the
-   generator and yields slower, non-deterministic output.
-2. **Backend work** → confirm the project and config are ready with
-   `runtime_detect_project`, list the candidate `.env` files in `config/` with
-   `runtime_detect_config` when the config to use is not obvious, then the
-   `setup_validate_config` gate.
-3. **Before writing a launcher** → `runtime_validate_preflight`. It re-runs the
-   config validation and adds the two runtime-only checks the gate does not
-   cover: a possibly-running server (`.restforge/server.pid`) and availability
-   of the local port. Use it as the last check before `runtime_generate_launcher`,
-   not as a replacement for the `setup_validate_config` gate earlier in the run.
-4. **License questions** → `license_info` reports the activation stored on this
-   machine (key, e-mail, type, machine id, last validation, expiry) and changes
-   nothing. Repeat the key, e-mail, or machine id back to the user only when
-   they asked for them. Activation and `license deactivate` are deliberately
-   **not** wrapped by MCP — deactivation frees a machine slot across machines,
-   so the user runs it in their own terminal.
-5. **Frontend work** → the Designer tools pre-check that `npx restforge-designer`
-   can run (its binary is bundled in `@restforgejs/platform`, so it is available
-   once the project is created with `npx create-restforge-app` / the platform is
-   installed); if it cannot run, surface that before proceeding.
-
-If a prerequisite is missing, report it as the next step — do not improvise around it.
+## Preflight
 
----
+1. **RESTForge MCP tools present?** Look for `codegen_*` / `designer_*`, including
+   client-prefixed names (`mcp__restforge__codegen_*`). Search deferred tools
+   first when the client supports it. If they stay unavailable, stop and tell the
+   user to register the RESTForge MCP server and restart the client. Do not finish
+   the task by hand from `references/`.
+2. **Backend work that reads the config or the database** → the
+   `setup_validate_config` gate (Guardrail 3). `runtime_detect_project` and
+   `runtime_detect_config` help when the project or the `.env` file is not
+   obvious.
+3. **Frontend work** → the designer tools pre-check that `npx restforge-designer`
+   can run; relay a failed pre-check as a setup step.
 
-## Backend Pipeline (canonical)
-
-This is the canonical (golden) path. For state-dependent choices see Decision
-Points; for failure handling see Guardrails and Common Errors.
-
-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 any codegen_* operation starts.
-      Validates database connection and license. Running codegen before this
-      gate passes produces uninformative errors.
-      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.  codegen_get_dbschema_catalog
-      ── GROUNDING ── Source of truth before defining SDF: field types,
-      constraints, shorthand syntax, relations, referential actions,
-      check operations, and the soft-delete contract.
-      → references/dbschema-catalog.md
-
-7a. codegen_dbschema_init         (empty DB — scaffold SDF with audit columns)
-    codegen_dbschema_template     (minimal template, no DB connection required)
-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 Decision Points § RDF Payload).
-
-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.
-```
-
-Two hard checkpoints (see Guardrails): **step 5** is a gate — no `codegen_*` call
-before `setup_validate_config` passes; **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).
+If a prerequisite is missing, report it as the next step; do not improvise
+around it.
 
 ---
 
-## Frontend 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 (like every codegen_* tool).
-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 (Decision Points § Frontend UDF).
-
-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 files that would be generated, without writing to disk.
-      Use to verify scope before an overwrite.
-
-7.  designer_generate
-      Generate frontend HTML/JS/CSS from the aggregator. Writes output files.
-      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 (see 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.
+## Intent Router
+
+Find the row that matches the request, check the minimum information, and start
+with the first action. When the minimum information is already in the request,
+do not ask for it again. When it is missing, ask once, in one short message, for
+everything missing, and say the user may leave the choice to the agent.
+
+| User intent | Minimum information | First action | Tool chain |
+|---|---|---|---|
+| New table ("buatkan tabel product") | Fields and types, or the design handed over | Ask for the fields when not stated; write nothing while waiting | `codegen_get_dbschema_catalog` (needed sections) → write `schema/<table>.js` → `codegen_dbschema_validate` |
+| Draft / skeleton table file (explicit) | Table name | `codegen_dbschema_init` | → user fills it in → `codegen_dbschema_validate` |
+| Ready-made template (explicit) | Domain or table | `codegen_dbschema_template` | list → show → generate → `codegen_dbschema_validate` |
+| Schema from a UI design (HTML, image) | The design | Confirm it is an entity, not a dashboard | references/design-to-sdf.md |
+| SDF from an existing database | Config, table or schema | `setup_validate_config` | `codegen_list_tables` → `codegen_dbschema_introspect` |
+| Apply schema to an empty database | Schema path, config | `setup_validate_config` | `codegen_dbschema_migrate` (dryRun first, then confirm) |
+| Change an existing table (column, index, FK) | The change | Edit the SDF | `codegen_dbschema_validate` → `codegen_dbschema_diff` → `codegen_dbschema_apply` (dryRun, confirm) |
+| New CRUD endpoint | Source table (exists in DB); master-detail or not | `setup_validate_config` | `codegen_generate_payload` → `codegen_validate_payload` → `codegen_create_endpoint` |
+| Master-detail endpoint | Header table and detail table | `setup_validate_config` | `codegen_generate_payload` with `detail` → fill formulas → validate → create endpoint |
+| Field validation rule | Field, rule, and layer (RDF or SDF) | Ask the layer only when DDL terms or "enforce" make it ambiguous | RDF: `codegen_get_field_validation_catalog` → edit payload → `codegen_validate_payload` → `codegen_create_endpoint`. SDF: edit schema → validate → diff → apply |
+| Show columns of a referenced table | Table | `codegen_sync_payload` with `expandFk` | → `codegen_create_endpoint` |
+| Custom query (list, view, export) | Columns to show and filter | `codegen_get_query_declarative_catalog` | `codegen_validate_sql` → edit payload → validate → create endpoint |
+| Workflow / status transitions | Status field and transitions | Ground in references/rdf-advanced.md § Workflow | edit RDF (`action.workflow`, `workflow`) → validate → create endpoint; UDF `workflowActions` |
+| Payload out of sync with the database | Table (optional) | `codegen_diff_payload` | → `codegen_sync_payload` → `codegen_create_endpoint` |
+| Dashboard endpoint | Widgets (metrics, SQL), `dash-` name | `codegen_get_dashboard_catalog` | write payload → `codegen_validate_dashboard_payload` → `codegen_create_dashboard` |
+| Background job / Kafka consumer | Name, topic for a consumer | `codegen_create_processor` / `codegen_create_kafka_consumer` | consumer → `runtime_generate_consumer_launcher` |
+| Frontend page | Source RDF and plugin (the existing app's plugin when there is one) | `codegen_migrate_payload` when an RDF exists | `designer_get_udf_catalog` → edit page → `designer_validate_payload` → `designer_preview_files` → `designer_generate` |
+| Bring UDF changes into an existing app | Aggregator UDF, output folder | `designer_validate_payload` | `designer_generate` without `overwrite` (merge); exit 1 = conflicts to resolve → generate again |
+| Auth | Backend, frontend, or both; RBAC or not | references/auth.md § Choosing the mechanism | `project_auth` / plugin auth / `designer_auth_create` / `designer_auth_attach` |
+| JavaScript SDK | Project (endpoints already generated) | `project_sdk_generate` | user runs install / build / deploy |
+| Seed, export, or move rows | Tables or schema, config | references/data-seeding.md | `data_pull` / `data_push` |
+| Integration test | Existing endpoint | `codegen_generate_test` | user runs the tests |
+| Run, stop, or restart the server | Project, config | `runtime_validate_preflight` | `runtime_generate_launcher` → the user runs it |
+| Configure the project | Target parameters | `setup_read_env` | `setup_write_env` / `setup_update_env` → `setup_validate_config` |
+| License question | — | `license_info` | `license deactivate` is the user's command |
+| New project | Project name | Suggest `npx create-restforge-app <name>` | granular: `setup_create_folder` → `setup_install_package` → `setup_init_config` |
+
+Detail per track:
+
+- Backend pipeline, schema / payload / module decisions → references/backend-pipeline.md
+- Frontend pipeline, UDF / page type / plugin decisions → references/frontend-pipeline.md
+- Errors, prerequisites, commands outside MCP, runtime lifecycle → references/troubleshooting.md
+
+### Continue, do not stop halfway
+
+A tool response often names the next step. When the user's request already
+covers that step ("buat tabel product sampai endpoint-nya jadi"), continue
+without asking. When it does not, finish with one sentence that offers the next
+step. A destructive step still needs its confirmation (Guardrail 1).
 
 ---
 
-## Auth Extension
+## Layers
 
-RESTForge has **two different auth mechanisms — do not confuse them.** Pick the
-right one; never describe one as the other, and never claim the extension does RBAC.
+Three layers co-exist and must not be conflated:
 
-| Mechanism | RBAC? | How |
-|---|---|---|
-| **Plugin auth** — built into the frontend at generation time | **Yes (auth + RBAC)** | `vanilla-js-auth` or `vanilla-js-custom` plugin in `designer_init_project`; disable with `noAuth: true` (`--no-auth`) |
-| **Auth extension** — bolt-on added to an existing project | **No RBAC** | backend `project_auth`; frontend `designer_auth_create` (embedded `rfx_auth`) |
-
-Confirm which plugins provide auth with `designer_list_plugins` — do not hardcode
-it. The rest of this section covers the **extension** (the no-RBAC bolt-on); for
-plugin auth see Decision Points § Frontend plugin choice. Google Sign-In and
-`@restforgejs/auth` are out of scope for the extension.
-
-### Backend auth — `project_auth`
-
-Adds the auth backend to an existing RESTForge project (run the standard backend
-pipeline first; the project and its endpoint must already exist, and the DB must
-be active).
-
-```
-project_auth   (wraps: npx restforge project auth --create --project=<name>)
-```
-
-Installs auth SDF (`rfx`), DB tables, middleware, router, six processors
-(register/login/refresh/logout/me/reset-password), a random `JWT_SECRET`, and
-`bcrypt`+`jsonwebtoken`. Idempotent. → references/auth.md § Backend
-
-### Frontend auth — `designer_auth_create` / `designer_auth_remove`
-
-Adds (or removes) an **embedded** login / signup / forget-password overlay
-(`rfx_auth`) on an existing frontend project, at route
-`/api/<project>/rfx_auth`. This is independent of the `vanilla-js-auth` plugin.
-
-```
-designer_auth_create   (wraps: npx restforge-designer auth --create --project=<name>)
-designer_auth_remove   (wraps: npx restforge-designer auth --remove --project=<name> --force)
-```
-
-`create` writes the auth pages + `js/rfx_auth.js` and injects a guard into existing
-pages; `remove` deletes them. Idempotent. Runs via `npx restforge-designer`
-(bundled in `@restforgejs/platform`; available once the project was created with
-`npx create-restforge-app` / the platform is installed).
-→ references/auth.md § Frontend
-
-### Retrofit on a generated app — `designer_auth_attach`
-
-```
-designer_auth_attach   (wraps: npx restforge-designer auth --attach --project=<name>)
-```
-
-The "turn auth on afterwards" path for an app whose pages already exist. It
-installs `js/rfx_auth.js`, injects the script tag into the existing pages (except
-the login page), and writes the `embeddedAuth` marker — **page files themselves
-are never touched**, so customisations survive. When the project payload has an
-auth block on an auth-capable plugin (`vanilla-js-auth` / `vanilla-js-custom`) it
-additionally renders the plugin login artifacts (`js/auth.js`, `login.html`,
-`js/login.js`) and extends `js/config.js` with a marked block; in that mode the
-`rfx_auth` login/signup pages are not written, and the storage key is aligned with
-the plugin login so both sides read the same session. Idempotent — existing files
-are skipped unless `overwrite` is set.
-
-Pick between the two: `designer_auth_create` when the app just needs a standalone
-login/signup overlay and no auth-capable plugin is in play;
-`designer_auth_attach` when the pages already exist, the plugin is
-`vanilla-js-auth` / `vanilla-js-custom`, or `designer_generate` reported missing
-auth artifacts. The CLI accepts exactly one of `--create` / `--attach` /
-`--remove` per invocation.
-
-Do not combine the two mechanisms on one app: if an app already has plugin auth
-(`vanilla-js-auth` / `vanilla-js-custom`), do not also add embedded `rfx_auth`.
+- **SDF** — database structure: tables, columns, indexes, foreign keys, CHECK and
+  UNIQUE. Changed in `schema/<table>.js`, applied with migrate (empty database)
+  or diff → apply (existing database).
+- **RDF** — backend API behaviour on that structure: `fieldValidation`, queries,
+  actions, workflow, master-detail. Changed in `payload/<name>.json`, applied by
+  regenerating the endpoint.
+- **UDF** — the frontend consuming the API. Derived from the RDF with
+  `codegen_migrate_payload`, refined by hand, generated with `designer_generate`.
+  Re-generating merges into the existing app files, so edits there survive.
+
+When the user uses DDL terms (NOT NULL, UNIQUE, CHECK, REFERENCES, ALTER TABLE,
+CREATE INDEX), do not map them to payload validation automatically. Ask which
+layer they want: RDF validation answers HTTP 400 with a custom message before the
+request reaches the database; SDF enforcement rejects at storage level. Both can
+exist for the same field. A request about "schema" can mean SDF or RDF; ask when
+the context does not decide it.
 
 ---
 
 ## Grounding-First Rules
 
-Before reasoning about, proposing, or generating any **definition content** —
-SDF fields, RDF `fieldValidation`, queries, dashboard widgets, or UDF pages —
-call the matching grounding tool first and use only what it returns. Never write
-definition content from memory.
+Before writing any definition **syntax** (SDF fields, `fieldValidation`, queries,
+dashboard widgets, UDF pages), call the matching catalog tool and use only what
+it returns. Ask only for the sections the task needs, once per session.
 
 | Context | Grounding tool | Reference |
 |---|---|---|
-| Defining or reviewing SDF | `codegen_get_dbschema_catalog` | references/dbschema-catalog.md |
-| Deriving SDF from a UI design (HTML / image / screenshot) | `codegen_get_dbschema_catalog` | references/design-to-sdf.md |
-| Defining `fieldValidation` in an RDF payload | `codegen_get_field_validation_catalog` | references/field-validation.md |
-| Defining queries in an RDF payload | `codegen_get_query_declarative_catalog` | — |
-| Defining a dashboard payload | `codegen_get_dashboard_catalog` | — |
-| Defining `/aggregate` joins or requests | — (no catalog tool yet) | references/rdf-advanced.md § Aggregate Config |
-| Defining UDF (frontend) | `designer_get_udf_catalog` | references/udf-catalog.md |
-| Listing available frontend plugins | `designer_list_plugins` | references/udf-catalog.md § Plugins |
-| Setting `db-connection.env` parameters | `setup_get_config_schema` | references/config-schema.md |
-
-**Why this rule exists.** The catalog is the source of truth for valid options
-in the *installed* platform version. Reasoning without it produces confident but
-wrong output — field types that do not exist, constraints not applicable to a
-type, or wrong semantics. Two concrete failure modes this rule prevents:
-
-- **Inventing options.** Without grounding, an agent may write a made-up key
-  (e.g. `"toUpper": true`) that the validator rejects. The catalog gives the
-  exact key and value type.
-- **Misreading semantics.** A constraint can mean something different from its
-  plain-English name. For example, `uppercase` on a `string` field is a
-  *normalization transform* (it forces the stored value to upper case), grouped
-  with `trim` and `lowercase` — it is **not** a validator that rejects
-  non-uppercase input. If the user wants rejection, the answer is `pattern`, not
-  `uppercase`; if they want database-level enforcement, that is an SDF check
-  constraint, not RDF `fieldValidation`. Grounding surfaces this distinction
-  before the agent commits to the wrong one.
-
-The reference files help you *understand* the catalog; they do **not** replace
-the tool. Call the tool to ground, produce, and validate — do not hand-produce
-output a tool would generate. The live tool is authoritative; when a reference and
-the tool disagree, trust the tool.
+| SDF | `codegen_get_dbschema_catalog` | references/dbschema-catalog.md |
+| SDF from a UI design | `codegen_get_dbschema_catalog` | references/design-to-sdf.md |
+| RDF `fieldValidation` | `codegen_get_field_validation_catalog` | references/field-validation.md |
+| RDF queries | `codegen_get_query_declarative_catalog` | — |
+| RDF action, workflow, master-detail, aggregate, import | — (no catalog tool) | references/rdf-advanced.md |
+| Dashboard payload | `codegen_get_dashboard_catalog` | — |
+| UDF | `designer_get_udf_catalog` | references/udf-catalog.md |
+| Frontend plugins | `designer_list_plugins` | references/udf-catalog.md § Plugins |
+| `db-connection.env` parameters | `setup_get_config_schema` | references/config-schema.md |
+
+The catalog decides **how** a field is written, not **what** a table holds. When
+the user hands the design over, the agent chooses the business fields from domain
+knowledge of the entity.
+
+A constraint can mean something other than its plain-English name. `uppercase`
+on a string is a normalization transform (it stores the value in upper case), not
+a validator that rejects lowercase input; rejection is `pattern`, and database
+enforcement is an SDF check. Confirm which one is meant before editing.
+
+The live tool is authoritative; when a reference and the tool disagree, trust the
+tool. For RESTForge behaviour that no catalog or reference covers, say so and
+point to the handbook at https://github.com/restforge/handbook (not
+restforge.dev/docs, which is outdated). Never borrow syntax from Express, NestJS,
+Strapi, Hasura, or similar frameworks.
 
 ---
 
-## Decision Points
-
-Use these to pick the correct branch when the request is state-dependent. Each
-branch still obeys the Grounding-First Rules above.
-
-### Schema (SDF)
-
-- **DB does not exist** → `codegen_dbschema_init` (scaffold with audit columns)
-  or `codegen_dbschema_template` (minimal template, no DB connection required).
-- **DB already exists** → `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
-
-- **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.
-
-> **"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 Grounding-First Rules § Misreading semantics.
-
-### 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.
-
-### Data seeding / migration (rows, not schema)
-
-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.
-
-### Frontend UDF
-
-- **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.
-
-### Frontend 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
-
-### Frontend 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 Authentication below.
-  → references/udf-catalog.md § Plugins
-
-### Authentication
-
-- **Needs RBAC** → plugin auth (`vanilla-js-auth` / `vanilla-js-custom`) at
-  `designer_init_project`. The extension below does **not** do RBAC.
-- **Backend auth on an existing project (no RBAC)** → `project_auth` (after the
-  project and its endpoint exist, with an active DB).
-- **Frontend auth on an app built WITHOUT plugin auth (no RBAC)** →
-  `designer_auth_create` (embedded `rfx_auth`).
-- **Remove embedded frontend auth** → `designer_auth_remove` — destructive,
-  confirm first (see Guardrails).
+## New Table Conventions
+
+Apply to every authored table; take the 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 in the schema folder
+  (`codegen_dbschema_models`) or one 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.
+- Fields stated by the user → use them; choose missing types from the names and
+  ask only when a type is genuinely ambiguous. Do not add business fields the user
+  did not list, apart from the PK and audit columns.
+- Design handed over ("terserah", "tentukan sendiri") → design the fields, write
+  the file, validate, then report the chosen structure briefly.
 
 ---
 
 ## Guardrails
 
-These are hard rules. They override convenience and override an eager reading of
-the user's request. When a guardrail conflicts with finishing faster, the
+These are hard rules. When a guardrail conflicts with finishing faster, the
 guardrail wins.
 
-**1. Confirm before destructive operations.**
-The following require explicit user confirmation before execution:
-
-- `codegen_dbschema_migrate` or `codegen_dbschema_apply` that drops a table or
-  column, or alters a column in a way that loses data.
-- `project_delete` — permanent project deletion.
-- `project_sdk_generate` with `force: true` — the SDK files are rewritten in
-  place with **no** archive backup, so hand edits inside the SDK folder are lost,
-  and resource files of endpoints that no longer exist are left behind.
-- `setup_validate_config` with `autoCreateDb: true` — it runs CREATE DATABASE on
-  the database server. The default call is read-only.
-- `codegen_migrate_payload` with `overwrite: true` — existing UDF pages are
-  recreated and every customisation in them is discarded (the old files are
-  archived). Without `overwrite`, pages are merged and nothing is lost.
-
-`codegen_create_endpoint` and `codegen_create_dashboard` overwrite by default
-(`force` is true) but first move the previous files to
-`.restforge/archive/<run>/<original relative path>` (the 5 most recent runs are
-kept), so they need a plain intent confirmation rather than a
-destructive-operation confirmation. Use `force: false` when the point is to find out whether the module
-already exists: the endpoint command then stops at its confirmation question
-without writing, and the dashboard command refuses with a clean error.
-
-For schema changes, run `codegen_dbschema_diff` first, present a summary of the
-destructive parts (dropped tables/columns, type narrowing), and wait for
-confirmation before calling `codegen_dbschema_apply`. Never infer approval from
-the original request — "update the schema" is not consent to drop a column.
-
-**2. The agent does not run the server.**
-The agent's last step on the backend track is `runtime_generate_launcher`. The
-user executes the launcher in their own terminal. The agent never calls shell
-commands to start, stop, or restart the server, and never assumes the server is
-running — verify with `runtime_check_status` instead. The same rule covers the
-Kafka consumer runtime: `runtime_generate_consumer_launcher` only writes the
-scripts or the PM2 deploy files; starting the consumer belongs to the user. A
-process spawned from an agent session dies with the session.
-
-**3. The `validate_config` gate is mandatory.**
-`setup_validate_config` must pass before any `codegen_*` operation starts. Do not
-skip it "to save a step" — running codegen against an invalid config produces
-uninformative errors that cost more time than the gate.
-
-**4. Validate before generating.**
-Always run `codegen_validate_payload` before `codegen_create_*`, and
-`designer_validate_payload` before `designer_generate`. For a dashboard payload
-the matching validator is `codegen_validate_dashboard_payload` — the general one
-does not understand the `widgets` shape. Generation on an invalid payload
-produces incomplete or broken output that looks like it succeeded.
-
-**5. Stay inside the task scope.**
-Do not modify files outside the requested task. If the change is a backend
-payload edit, do not also "tidy up" the SDF, the runtime, or the frontend. If a
-change genuinely requires touching another area (e.g. an RDF edit that needs a
-new column, which is an SDF change), stop and report the cross-over, then ask
-before expanding scope.
-
-**6. Ground before defining — repeated here because it is a guardrail, not a
-suggestion.** Never write SDF fields, `fieldValidation`, queries, dashboard
-widgets, or UDF content from memory. Call the matching catalog tool first (see
-Grounding-First Rules). Inventing an option that "should" exist is the most
-common way to produce confidently wrong output.
-
-**7. Confirm before removing embedded auth.**
-`designer_auth_remove` deletes the auth files (`login.html`, `signup.html`, the
-forget-password overlay, `js/rfx_auth.js`) and strips the guard from existing
-pages. Under MCP it runs with `--force` (no interactive prompt), so confirm the
-project name and intent with the user **before** calling it.
-
-**8. Execute through tools; never emulate them.** The bundled `references/` help
-you *understand* options — they do not replace the tools. When a tool can produce
-or validate an artifact (`codegen_dbschema_template`/`init`,
-`codegen_generate_payload`, any `*_validate_*`), **call it**; do not hand-write its
-output by reading a reference. Emulating the generator is slower, loses
-determinism, and drifts from what the installed version emits. If the tool is not
-available, stop (see Preflight) rather than improvising from the references.
-
----
-
-## Tools outside this skill's workflows
-
-These MCP tools exist and are callable, but they are not steps of the backend or
-frontend pipeline. They are listed here so their absence from the pipelines reads
-as a decision, not an omission — call them when the user asks for exactly that,
-not as part of a generation run.
-
-| Tool | Why it is outside the pipeline |
-|---|---|
-| `health_ping` | Transport smoke test — answers "is the MCP server itself responsive", touches nothing in RESTForge |
-| `key_generate`, `key_list`, `key_revoke` | API key bookkeeping inside `.env` files; independent of definition files and code generation |
-| `project_list` | Registry inventory (endpoint count, database type, creation date) — useful for orientation, never a prerequisite of a later step |
-
-`license deactivate` has no MCP tool at all, on purpose: it frees a machine slot
-across machines, so the user runs it manually. `license_info` (read-only) is the
-wrapped half of that pair.
+**1. Confirm before destructive operations.** Tool descriptions mark them
+DESTRUCTIVE. Ask before:
+
+- `codegen_dbschema_migrate` (always with `dryRun: false`; with `drop: true` all
+  data in the affected tables is lost) and `codegen_dbschema_apply` with
+  `dryRun: false`, `allowDrop`, or `allowModify`.
+- `project_delete`, `key_revoke`, `designer_auth_remove`, and `data_push`
+  (append-only, a second run duplicates rows).
+- `project_sdk_generate` with `force: true` (rewritten in place, no archive).
+- `setup_validate_config` with `autoCreateDb: true` (runs CREATE DATABASE).
+- `codegen_migrate_payload` with `overwrite: true` (page customisations are
+  discarded; without it pages are merged).
+- `designer_generate` with `overwrite: true` (every app file is recreated and
+  its customisations are discarded; without it files are merged).
+- `codegen_create_endpoint` and `codegen_create_dashboard` overwrite by default
+  but archive the previous files to `.restforge/archive/<run>/` (5 most recent
+  runs kept), so a plain intent confirmation is enough. `force: false` finds out
+  whether the module exists without writing.
+
+For schema changes, present the destructive parts of the diff (dropped tables or
+columns, type narrowing) and wait. "Update the schema" is not consent to drop a
+column.
+
+**2. The agent does not run the server.** The last backend step is
+`runtime_generate_launcher`; the user runs it. Never start, stop, or restart the
+server or a Kafka consumer from a shell, and never assume it is running; check
+with `runtime_check_status`. → references/troubleshooting.md § Runtime lifecycle
+
+**3. The `setup_validate_config` gate.** It must pass once per session before the
+first tool that takes a `config` parameter: `codegen_list_tables`,
+`codegen_describe_table`, `codegen_dbschema_introspect`,
+`codegen_dbschema_validate` with `config`, `codegen_dbschema_diff`,
+`codegen_dbschema_apply`, `codegen_dbschema_migrate`, `codegen_validate_sql`,
+`codegen_generate_payload`, `codegen_validate_payload`, `codegen_diff_payload`,
+`codegen_sync_payload`, `codegen_migrate_payload`, `codegen_create_endpoint`,
+`data_pull`, and `data_push`. Do not run it for file-only work (catalog lookups,
+authoring SDF, file-only validate, DDL preview, templates). Repeat it only when
+the config changed.
+
+**4. Validate before generating.** `codegen_validate_payload` before
+`codegen_create_*`; `codegen_validate_dashboard_payload` for a dashboard payload;
+`designer_validate_payload` before `designer_generate`.
+
+**5. Stay inside the task scope.** Do not tidy up files the task did not ask
+for. When a change crosses into another layer (an RDF edit that needs a new
+column is an SDF change), report the cross-over and ask before expanding.
+
+**6. Ground before defining.** Never write definition syntax from memory (see
+Grounding-First Rules). This rule is about syntax; choosing the business fields
+of a table the user handed over is allowed (Guardrail 9).
+
+**7. Know which generated output survives a regenerate.** Backend output
+(`src/modules/`, `src/models/`, metadata) is overwritten by
+`codegen_create_*` (archived first), so change the RDF instead of the code.
+Frontend app files may be edited: `designer_generate` merges the edits
+(references/frontend-pipeline.md § Regenerating an existing app). Snapshots in
+`payload/.meta/`, `frontend/payload/.meta/pages/`, and
+`frontend/apps/.meta/<project>/` (except `conflicts/`) are committed with their
+files and never edited.
+
+**8. Execute through tools; never emulate them.** When a tool produces or
+validates an artifact (`codegen_generate_payload`, `codegen_dbschema_introspect`,
+`codegen_create_*`, `designer_generate`, any `*_validate_*`), call it. An SDF for
+a new table is authored content, not generator output, so writing
+`schema/<table>.js` with the file tools is the intended path.
+`codegen_dbschema_init` and `codegen_dbschema_template` are only for explicit
+draft or template requests.
+
+**9. Settle the table structure before writing it.** A new table without its
+fields goes through the clarify question in the Intent Router. Never answer it
+with a skeleton, a dummy template, or a reference template, and never create a
+file "to be filled in later" unless the user asked for a draft.
 
 ---
 
-## Prerequisites and Common Errors
-
-### Environment prerequisites
-
-- Node.js ≥ 18.
-- A reachable database matching the configured `DB_TYPE` (PostgreSQL, MySQL,
-  Oracle, or SQLite).
-- A valid RESTForge license for `codegen_*`, `runtime_*`, and
-  `setup_validate_config`. Designer tools do not require a license.
-- The RESTForge MCP server registered in the client
-  (`npm install -g @restforgejs/mcp-server`, then registered as the `restforge`
-  MCP server). Without it, none of the tools below exist.
-- Redis if using cache, distributed lock, or live sync.
-- Kafka if using a Kafka consumer (`KAFKA_ENABLED=true`).
-
-### Required backend config parameters
-
-Nine of the full parameter set are mandatory before `setup_validate_config` can
-pass:
-
-`LICENSE`, `SERVER_ADDRESS`, `SERVER_PORT`, `DB_TYPE`, `DB_HOST`, `DB_PORT`,
-`DB_USER`, `DB_PASSWORD`, `DB_NAME`.
-
-→ references/config-schema.md for the full parameter list, and
-`setup_get_config_schema` for the live version of it.
-
-### Tools that depend on the installed platform version
-
-Two tools wrap CLI sub-commands that old platform releases do not have. Current
-releases have both. On an old project they fail in a recognisable way, so treat
-the failure as a version answer, not a payload problem:
-
-| Tool | Requirement | Symptom on an older platform |
-|---|---|---|
-| `codegen_validate_sql` | a platform providing `query validate` | `Unknown command: query` |
-| `codegen_validate_dashboard_payload` | a platform providing `dashboard create --validate-only` | `Unknown flag: --validate-only`; the tool reports it as an upgrade requirement |
-
-When `codegen_validate_dashboard_payload` is unavailable, the fallback is
-`codegen_create_dashboard` itself — it runs the same validator before writing.
-
-### Common error patterns
-
-| Symptom | Cause | Recovery |
-|---|---|---|
-| Tool not found / no `codegen_*` tools available | MCP server not registered in the client | Install `@restforgejs/mcp-server`, register it as the `restforge` MCP server, restart the client |
-| "authenticity check failed" / HTTP 401 | License not active or expired | Set `LICENSE` in `config/db-connection.env`, run `setup_validate_config` |
-| HTTP 429 from license server | Rate limit (10 req/min/IP) | Expected since v5.1.15 — the client falls back to cache; wait or retry |
-| DB connection failed | Wrong DB config or DB not running | Check `DB_HOST`, `DB_PORT`, `DB_USER`, `DB_PASSWORD`, `DB_NAME`; verify the DB is running |
-| "softDelete contract violation" | Contract columns missing or wrong type | Fix the SDF declaration, run `codegen_dbschema_validate` |
-| "Widget uses undeclared placeholder" | `:paramName` in SQL not in `params` | Add the entry to `params` in the dashboard payload |
-| "tableName and widgets conflict" | Payload contains both | Dashboard uses `widgets`; CRUD uses `tableName` — remove the wrong one |
-| UDF validation error on field type | Field type not supported by the active plugin | Run `designer_list_plugins` + `designer_get_udf_catalog` to verify supported types |
-| `constraints.format ... is not supported for type 'date'` (or `timestamp`) | Per-field date pattern in RDF | Remove `format`; the pattern comes from `DATEFORMAT` / `DATETIMEFORMAT` |
-| Frontend shows a different date than the backend stored | `appConfig.dateFormat` / `dateTimeFormat` differ from the backend config | Re-run `codegen_migrate_payload`, then `designer_generate` |
-| Hook rejection answered HTTP 400 with only the hook message | A component handler returned `{ success: false }` or threw | Expected behaviour; the handler name and path are in the server log |
-
-When an error is not in this table, do not guess a fix. Re-run the relevant
-`*_validate_*` tool, read its message, and ground against the catalog before
-changing the definition.
+## Talking to the User
+
+- Reply in the user's language.
+- Describe actions by what they do ("validate the payload", "generate the
+  endpoint"); do not name internal tools.
+- Summarise results (counts, files, verdicts); do not paste raw CLI output or
+  JSON unless the user asks.
+- Never repeat secrets: license keys, passwords, full connection URIs. Confirm
+  presence only.
+- A precondition that is not met is a next step or a question, not an error.
+- An exit code that the tool describes as a verdict (drift found, payload
+  invalid, items skipped, merge conflicts) is a result to relay, not a tool
+  failure.