@sparkerp/plugin-sdk 0.1.0

package/bundle/docs/reference/connector-definition.md

@@ -0,0 +1,36 @@
+---
+title: connector-definition schema
+audience: tenant
+generated: true
+---
+
+# `connector-definition` schema
+
+Generic External Provider Connector Engine's content model (engine-provider-connector) — domain/providerKey/connectorKind(DIRECT|HTTP)/baseUrl/auth/request-template/response-mapping.
+
+Pull the full JSON Schema: `erp schema pull connector-definition`  ·  MCP: `erp_get_schema {"name":"connector-definition"}`
+
+## Top-level properties
+
+| Property | Type | Required | Notes |
+| --- | --- | --- | --- |
+| `domain` | string | yes | Consumer namespace, e.g. "hcm-employee-documents.signature" — any plugin/feature can register its own domain. |
+| `providerKey` | string | yes | Unique per (tenant, domain) — what the consuming entity's provider_name/provider_key column resolves against. |
+| `name` | string | yes |  |
+| `connectorKind` | string | yes | one of: `DIRECT`, `HTTP` |
+| `active` | boolean |  |  |
+| `isDefault` | boolean |  |  |
+| `baseUrl` | string |  |  |
+| `authType` | string |  | one of: `NONE`, `API_KEY_HEADER`, `BEARER_TOKEN`, `BASIC` |
+| `authConfig` | object |  | e.g. {headerName, secretRef} — secretRef of shape "env:VAR_NAME" resolved from environment at call time, never a literal secret stored here. |
+| `requestPath` | string |  |  |
+| `httpMethod` | string |  | one of: `POST`, `PUT` |
+| `requestTemplate` | object |  | JSON object whose string leaves may contain {{fieldName}} tokens substituted at call time. |
+| `responseMapping` | object |  | {providerReferencePath, statusPath, signingUrlPath} dot-paths into the vendor's JSON response. |
+| `statusMapping` | object |  | Vendor status string -> this domain's own internal status vocabulary. |
+| `completionMode` | string |  | one of: `MANUAL_CONFIRM`, `POLL`, `WEBHOOK` |
+| `pollPathTemplate` | string |  |  |
+| `webhookPath` | string |  |  |
+| `notes` | string |  |  |
+| `ownerPlugin` | string |  |  |
+

package/bundle/docs/reference/data-service-definition.md

@@ -0,0 +1,22 @@
+---
+title: data-service-definition schema
+audience: tenant
+generated: true
+---
+
+# `data-service-definition` schema
+
+Data Service layer's content model (engine-entity DataServiceSpec) — provider/entity/dataView source + filters/parameters/composite steps.
+
+Pull the full JSON Schema: `erp schema pull data-service-definition`  ·  MCP: `erp_get_schema {"name":"data-service-definition"}`
+
+## Top-level properties
+
+| Property | Type | Required | Notes |
+| --- | --- | --- | --- |
+| `name` | string | yes |  |
+| `description` | string |  |  |
+| `metadata` | object |  |  |
+| `modules` | array |  |  |
+| `definition` | object | yes |  |
+

package/bundle/docs/reference/data-view-definition.md

@@ -0,0 +1,26 @@
+---
+title: data-view-definition schema
+audience: tenant
+generated: true
+---
+
+# `data-view-definition` schema
+
+Data View layer's content model (engine-entity DataViewSpec) — a real multi-table SQL join over plain physical tables.
+
+Pull the full JSON Schema: `erp schema pull data-view-definition`  ·  MCP: `erp_get_schema {"name":"data-view-definition"}`
+
+## Top-level properties
+
+| Property | Type | Required | Notes |
+| --- | --- | --- | --- |
+| `name` | string | yes |  |
+| `description` | string |  |  |
+| `metadata` | object |  |  |
+| `modules` | array |  |  |
+| `definition` | object | yes |  |
+
+## Named sub-definitions
+
+`calcExpr`
+

package/bundle/docs/reference/entity-aggregation-config.md

@@ -0,0 +1,38 @@
+---
+title: entity-aggregation-config schema
+audience: tenant
+generated: true
+---
+
+# `entity-aggregation-config` schema
+
+One config row for the generic engine-entity.aggregation-sweep job — fold count/sum/avg/min/max across a source entity and upsert the result into a target entity.
+
+Pull the full JSON Schema: `erp schema pull entity-aggregation-config`  ·  MCP: `erp_get_schema {"name":"entity-aggregation-config"}`
+
+## Top-level properties
+
+| Property | Type | Required | Notes |
+| --- | --- | --- | --- |
+| `sweep_code` | string | yes | Stable identifier / natural key for idempotent seeding. |
+| `source_entity` | string | yes |  |
+| `filter_field` | string |  | Optional single-column equality pre-filter. |
+| `filter_value` | string |  |  |
+| `when_status_in` | string |  | Optional comma-separated status filter. |
+| `status_field` | string |  |  |
+| `date_field` | string |  | Optional date pre-filter column. |
+| `date_compare_op` | string |  | one of: `lte`, `lt`, `gte`, `gt` |
+| `day_offset` | integer |  |  |
+| `aggregation` | string | yes | one of: `count`, `sum`, `avg`, `min`, `max` |
+| `agg_field` | string |  | Required for sum/avg/min/max; the numeric column to fold. |
+| `group_by_field` | string |  | Optional; one result bucket per distinct value. |
+| `target_entity` | string | yes |  |
+| `target_key_field` | string | yes | Column on target_entity that holds the bucket key (a declared field). Special value "id": the bucket key IS a row's own primary key — the fold is written straight back onto target_entity row #<key> (never a create). Use with group_by_field yielding the parent id (e.g. maintenance_id), target_entity = that parent entity, and a blank target_key_prefix — this is the true 'roll child lines up onto the parent record' form (MaintenanceCostSyncJob). |
+| `target_key_prefix` | string |  | Prepended to the bucket key when writing (so multiple configs can share one summary entity without collisions). |
+| `result_key` | string |  | Used as the bucket key when group_by_field is blank; defaults to sweep_code. |
+| `target_value_field` | string | yes |  |
+| `target_timestamp_field` | string |  | Optional; now written here on each run. |
+| `target_extra_json` | object |  | Optional static fields set only when a target row is first created. |
+| `seeded_by` | string |  |  |
+| `active` | boolean | yes |  |
+

package/bundle/docs/reference/entity-cadence-config.md

@@ -0,0 +1,33 @@
+---
+title: entity-cadence-config schema
+audience: tenant
+generated: true
+---
+
+# `entity-cadence-config` schema
+
+One config row for the generic engine-entity.cadence-generator job — create new target-entity rows on a cadence, source-driven or standalone, deduped.
+
+Pull the full JSON Schema: `erp schema pull entity-cadence-config`  ·  MCP: `erp_get_schema {"name":"entity-cadence-config"}`
+
+## Top-level properties
+
+| Property | Type | Required | Notes |
+| --- | --- | --- | --- |
+| `cadence_code` | string | yes | Stable identifier / natural key for idempotent seeding. |
+| `target_entity` | string | yes |  |
+| `interval_days` | integer | yes | Minimum days between generations; the job stamps last_generated_at on its own config row after each run. |
+| `last_generated_at` | string |  | Managed by the job; leave unset in seed files. |
+| `template_json` | object |  | Static field values for each created row. String values may use ${date} ${ts} ${uuid} ${sourceId} placeholders. |
+| `source_entity` | string |  | Set for source-driven generation (one target row per due source row); leave blank for a standalone single-row generator. |
+| `source_filter_field` | string |  |  |
+| `source_filter_value` | string |  |  |
+| `source_status_field` | string |  |  |
+| `source_status_in` | string |  |  |
+| `source_date_field` | string |  | Only source rows whose date_field <= now + due_within_days are generated from. |
+| `due_within_days` | integer |  |  |
+| `field_map_json` | object |  | { targetField: sourceField } - copies values from each source row. |
+| `dedupe_target_field` | string |  | Target column holding the source row id (source-driven) or the cadence marker (standalone) - the idempotency key. |
+| `seeded_by` | string |  |  |
+| `active` | boolean | yes |  |
+

package/bundle/docs/reference/entity-compliance-config.md

@@ -0,0 +1,37 @@
+---
+title: entity-compliance-config schema
+audience: tenant
+generated: true
+---
+
+# `entity-compliance-config` schema
+
+One config row for the generic engine-entity.compliance-sweep job — evaluate a rule-engine boolean expression against every row of an entity and flag/escalate offenders.
+
+Pull the full JSON Schema: `erp schema pull entity-compliance-config`  ·  MCP: `erp_get_schema {"name":"entity-compliance-config"}`
+
+## Top-level properties
+
+| Property | Type | Required | Notes |
+| --- | --- | --- | --- |
+| `compliance_code` | string | yes | Stable identifier / natural key for idempotent seeding. |
+| `source_entity` | string | yes | Entity evaluated row-by-row. |
+| `status_field` | string |  |  |
+| `when_status_in` | string |  | Optional comma-separated status pre-filter. |
+| `filter_field` | string |  | Optional single-column equality pre-filter. |
+| `filter_value` | string |  |  |
+| `related_count_entity` | string |  | Optional: count child rows of this entity whose related_count_key_field equals the source row's id, and bind the result as `related_count` in the expression context. |
+| `related_count_key_field` | string |  | The FK column on related_count_entity that points back to the source row's id. |
+| `related_count_status_field` | string |  |  |
+| `related_count_status_in` | string |  | Optional comma-separated status filter for the related count. |
+| `condition_expr` | string | yes | MVEL boolean expression evaluated against each row's fields (+ `now`, + `related_count`). Whitelisted functions only (daysBetween, now, etc.). True => apply the outcome. |
+| `set_field` | string |  | Flag outcome: column on the source row to write when the condition is true (idempotent — skipped if already equal to set_value). |
+| `set_value` | string |  | Flag outcome: value written into set_field. |
+| `escalation_entity` | string |  | Escalation outcome: create one row in this separate entity per violating source row, deduped by escalation_dedupe_field = source id. |
+| `escalation_dedupe_field` | string |  | Column on escalation_entity that holds the source row id (used for dedupe). |
+| `escalation_timestamp_field` | string |  | Optional column on escalation_entity that receives `now` on create. |
+| `field_map_json` | object |  | Escalation outcome: {targetField: sourceField} — copies source row values into the new escalation row. |
+| `escalation_template_json` | object |  | Escalation outcome: static fields set on every created escalation row. |
+| `seeded_by` | string |  |  |
+| `active` | boolean | yes |  |
+

package/bundle/docs/reference/entity-cross-plugin-action-config.md

@@ -0,0 +1,37 @@
+---
+title: entity-cross-plugin-action-config schema
+audience: tenant
+generated: true
+---
+
+# `entity-cross-plugin-action-config` schema
+
+One config row for the generic engine-entity.cross-plugin-action job — a trigger_entity row entering a triggering status fans out create/update onto every related_entity row keyed back to it (offboarding fan-out; trigger may be another plugin's entity).
+
+Pull the full JSON Schema: `erp schema pull entity-cross-plugin-action-config`  ·  MCP: `erp_get_schema {"name":"entity-cross-plugin-action-config"}`
+
+## Top-level properties
+
+| Property | Type | Required | Notes |
+| --- | --- | --- | --- |
+| `action_code` | string | yes | Stable identifier / natural key for idempotent seeding. |
+| `trigger_entity` | string | yes | Entity A - the record whose status change triggers the fan-out (often owned by another plugin, e.g. employee). |
+| `trigger_status_field` | string |  |  |
+| `trigger_status_in` | string |  | Comma-separated statuses that make a trigger row eligible (e.g. TERMINATED,SEPARATED). Blank = every row. |
+| `trigger_date_field` | string |  | Optional date gate column on the trigger row (e.g. separation_date). |
+| `trigger_date_compare_op` | string |  | one of: `lte`, `lt`, `gte`, `gt` |
+| `trigger_day_offset` | integer |  | Compare trigger_date_field against now + this many days. |
+| `trigger_key_field` | string |  | Field on the trigger row whose value matches related rows (usually id -> employee id). |
+| `related_entity` | string | yes | Entity B - the rows acted on. |
+| `related_match_field` | string | yes | FK column on related_entity that equals the trigger row's key (e.g. employee_id). |
+| `related_status_field` | string |  |  |
+| `related_status_in` | string |  | Comma-separated statuses a related row must be in to be acted on (e.g. ALLOCATED,ACKNOWLEDGED,IN_USE). |
+| `create_entity` | string |  | Create-outcome: entity a row is created in per matched related row (e.g. hcm_asset_return). Omit to only update the related row. |
+| `create_dedupe_field` | string |  | Numeric (long) column on create_entity holding the related row's id - dedupes re-runs. MUST be numeric, not text (EntityRecordService binds numeric-looking filter values as bigint). |
+| `create_template_json` | object |  | Static fields set on every created row. String values may contain ${date} ${ts} ${uuid} ${relatedId} ${triggerKey} - substituted per created row so a required-unique column (e.g. return_number) never collides. |
+| `create_field_map_json` | object |  | {targetField: relatedField} - copies related row values into the created row. |
+| `related_set_field` | string |  | Update-outcome: column on the related row to write (e.g. status). Idempotent - skipped when already equal to related_set_value. |
+| `related_set_value` | string |  | Value written into related_set_field (e.g. RETURN_PENDING). |
+| `seeded_by` | string |  |  |
+| `active` | boolean | yes |  |
+

package/bundle/docs/reference/entity-definition.md

@@ -0,0 +1,18 @@
+---
+title: entity-definition schema
+audience: tenant
+generated: true
+---
+
+# `entity-definition` schema
+
+A real Entity Engine entity (engine-entity) — fields/relationships, produces real DDL, zero hand-written CRUD Java.
+
+Pull the full JSON Schema: `erp schema pull entity-definition`  ·  MCP: `erp_get_schema {"name":"entity-definition"}`
+
+_This schema's root is not a plain object (see the full schema for its shape)._
+
+## Named sub-definitions
+
+`entityProps`, `flatEntity`, `field`, `relationship`
+

package/bundle/docs/reference/entity-document-generator-config.md

@@ -0,0 +1,35 @@
+---
+title: entity-document-generator-config schema
+audience: tenant
+generated: true
+---
+
+# `entity-document-generator-config` schema
+
+One config row for the generic engine-entity.document-generator job — generate a structured-data artifact (json/csv) per eligible row via the FileService, store it in a DMS cabinet, and stamp the file id onto the row.
+
+Pull the full JSON Schema: `erp schema pull entity-document-generator-config`  ·  MCP: `erp_get_schema {"name":"entity-document-generator-config"}`
+
+## Top-level properties
+
+| Property | Type | Required | Notes |
+| --- | --- | --- | --- |
+| `document_code` | string | yes | Stable identifier / natural key for idempotent seeding. |
+| `source_entity` | string | yes | Entity whose rows get a document. |
+| `status_field` | string |  |  |
+| `when_status_in` | string |  | Comma-separated statuses a row must be in to be eligible (e.g. COMPLETED for an audit report). Blank = every row. |
+| `filter_field` | string |  | Optional single-column equality pre-filter. |
+| `filter_value` | string |  |  |
+| `target_file_field` | string | yes | Text column on the source row that receives the generated file id. Its non-blank state IS the dedupe marker. |
+| `format` | string |  | one of: `json`, `csv` |
+| `cabinet_id` | integer |  | DMS cabinet id (engine-file) the artifact is stored in. Give this OR cabinet_name. |
+| `cabinet_name` | string |  | Portable alternative to cabinet_id: the job resolves a cabinet by this name for the tenant, creating it if absent. Preferred for seed-data rows (no hardcoded id). |
+| `file_name_template` | string |  | Generated file name. Supports ${id} ${date} ${ts} ${uuid} and ${field:<name>}. Default: <document_code>-${id}-${date}.<ext>. |
+| `include_fields` | string |  | Comma-separated source fields to include in the artifact. Blank = all fields. |
+| `child_entity` | string |  | Optional child entity whose rows (matched by child_match_field == source id) are embedded (json) alongside the record. |
+| `child_match_field` | string |  | FK column on child_entity pointing at the source row's id. |
+| `template_ref` | string |  | Reserved: a print-template id, for the future render_mode:template branch. Not used today (see description). |
+| `regenerate` | boolean |  | When true, regenerate even if target_file_field is already populated. |
+| `seeded_by` | string |  |  |
+| `active` | boolean | yes |  |
+

package/bundle/docs/reference/entity-rule-definition.md

@@ -0,0 +1,29 @@
+---
+title: entity-rule-definition schema
+audience: tenant
+generated: true
+---
+
+# `entity-rule-definition` schema
+
+A declarative entity-lifecycle rule (engine-rule) — conditions/actions firing at BEFORE_CREATE/AFTER_UPDATE/etc.
+
+Pull the full JSON Schema: `erp schema pull entity-rule-definition`  ·  MCP: `erp_get_schema {"name":"entity-rule-definition"}`
+
+## Top-level properties
+
+| Property | Type | Required | Notes |
+| --- | --- | --- | --- |
+| `entityType` | string | yes | The EntityDefinition.name this rule fires against. |
+| `name` | string | yes |  |
+| `description` | string |  |  |
+| `triggerEvent` | string | yes | one of: `BEFORE_CREATE`, `AFTER_CREATE`, `BEFORE_UPDATE`, `AFTER_UPDATE`, `BEFORE_DELETE`, `AFTER_DELETE` |
+| `priority` | integer |  | Lower runs first when multiple rules match the same trigger. |
+| `active` | boolean |  |  |
+| `conditions` | `#/definitions/condition` | yes |  |
+| `actions` | array | yes |  |
+
+## Named sub-definitions
+
+`condition`, `action`
+

package/bundle/docs/reference/entity-status-date-sweep-config.md

@@ -0,0 +1,27 @@
+---
+title: entity-status-date-sweep-config schema
+audience: tenant
+generated: true
+---
+
+# `entity-status-date-sweep-config` schema
+
+One config row for the generic engine-entity.status-date-sweep job — flip an entity's own status/flag field once its own date column crosses now (±day_offset days).
+
+Pull the full JSON Schema: `erp schema pull entity-status-date-sweep-config`  ·  MCP: `erp_get_schema {"name":"entity-status-date-sweep-config"}`
+
+## Top-level properties
+
+| Property | Type | Required | Notes |
+| --- | --- | --- | --- |
+| `entity_name` | string | yes | Entity Engine entity to sweep, e.g. hcm_asset. |
+| `status_field` | string |  | Column holding the gating status. |
+| `when_status_in` | string | yes | Comma-separated statuses a row must currently be in to be eligible. |
+| `date_field` | string | yes | Date/datetime column compared against now (+day_offset). |
+| `compare_op` | string |  | one of: `lte`, `lt`, `gte`, `gt` |
+| `day_offset` | integer |  | Compare date_field against now + day_offset days (negative shifts earlier). Enables N-days-before reminders. Added 2026-09. |
+| `set_field` | string |  | Field to WRITE when a row matches; defaults to status_field. Use a distinct flag field (e.g. warranty_alert_30d) so a reminder never corrupts the lifecycle enum. |
+| `set_status_to` | string | yes | Value written into set_field on match (e.g. "true" for a boolean flag, or a new status enum value). |
+| `seeded_by` | string |  | Provenance stamp (the plugin id). Set automatically by PluginDataSeedInstaller from the seed file's "source". |
+| `active` | boolean | yes |  |
+

package/bundle/docs/reference/form.md

@@ -0,0 +1,35 @@
+---
+title: form schema
+audience: tenant
+generated: true
+---
+
+# `form` schema
+
+A form's field/section/validation contract.
+
+Pull the full JSON Schema: `erp schema pull form`  ·  MCP: `erp_get_schema {"name":"form"}`
+
+## Top-level properties
+
+| Property | Type | Required | Notes |
+| --- | --- | --- | --- |
+| `contractVersion` | — | yes |  |
+| `id` | string | yes | Dot-namespaced form id, e.g. hr.employee-lookup. |
+| `version` | string | yes |  |
+| `publisher` | string | yes |  |
+| `fields` | array | yes |  |
+| `sections` | array | yes |  |
+| `tabs` | array | yes |  |
+| `layout` | object | yes |  |
+| `canvas` | array |  |  |
+| `validations` | array | yes |  |
+| `rules` | array | yes |  |
+| `events` | array | yes |  |
+| `permissions` | `#/$defs/permissionSurface` | yes |  |
+| `designer` | object | yes |  |
+
+## Named sub-definitions
+
+`identifier`, `i18nKey`, `permissionSurface`, `boundKey`, `fieldValue`, `selectOption`, `fieldConstraints`, `fieldDesigner`, `computedSpec`, `fetchFromBinding`, `rollupBinding`, `childTableSpec`, `fieldSpec`, `sectionSpec`, `tabSpec`, `actionDefinition`, `validationSpec`, `ruleBindingSpec`, `formEventBinding`, `canvasPosition`, `canvasPlacement`
+

package/bundle/docs/reference/index.md

@@ -0,0 +1,37 @@
+---
+title: Schema reference
+audience: tenant
+generated: true
+---
+
+# Schema reference
+
+One page per authoring artifact schema, generated by `erp docs gen-reference` from the SDK authoring bundle. Regenerate after `erp bundle build`.
+
+- [`action`](./action.md)
+- [`block-definition`](./block-definition.md)
+- [`block-instance`](./block-instance.md)
+- [`composite-pack-manifest`](./composite-pack-manifest.md)
+- [`connector-definition`](./connector-definition.md)
+- [`data-service-definition`](./data-service-definition.md)
+- [`data-view-definition`](./data-view-definition.md)
+- [`entity-aggregation-config`](./entity-aggregation-config.md)
+- [`entity-cadence-config`](./entity-cadence-config.md)
+- [`entity-compliance-config`](./entity-compliance-config.md)
+- [`entity-cross-plugin-action-config`](./entity-cross-plugin-action-config.md)
+- [`entity-definition`](./entity-definition.md)
+- [`entity-document-generator-config`](./entity-document-generator-config.md)
+- [`entity-rule-definition`](./entity-rule-definition.md)
+- [`entity-status-date-sweep-config`](./entity-status-date-sweep-config.md)
+- [`form`](./form.md)
+- [`menu`](./menu.md)
+- [`mobile-nav`](./mobile-nav.md)
+- [`page-template`](./page-template.md)
+- [`page`](./page.md)
+- [`plugin-manifest`](./plugin-manifest.md)
+- [`plugin-seed-data`](./plugin-seed-data.md)
+- [`print-template-definition`](./print-template-definition.md)
+- [`provider-definition`](./provider-definition.md)
+- [`report-definition`](./report-definition.md)
+- [`rule`](./rule.md)
+- [`workflow-definition`](./workflow-definition.md)

package/bundle/docs/reference/menu.md

@@ -0,0 +1,26 @@
+---
+title: menu schema
+audience: tenant
+generated: true
+---
+
+# `menu` schema
+
+Menu Designer's content model (@erp/menu-engine) — hierarchical sidenav tree (nodes/navigation/visibility/security/badge/personalization/advanced).
+
+Pull the full JSON Schema: `erp schema pull menu`  ·  MCP: `erp_get_schema {"name":"menu"}`
+
+## Top-level properties
+
+| Property | Type | Required | Notes |
+| --- | --- | --- | --- |
+| `name` | string | yes |  |
+| `description` | string |  |  |
+| `metadata` | object |  |  |
+| `modules` | array |  |  |
+| `definition` | object | yes |  |
+
+## Named sub-definitions
+
+`menuNode`
+

package/bundle/docs/reference/mobile-nav.md

@@ -0,0 +1,22 @@
+---
+title: mobile-nav schema
+audience: tenant
+generated: true
+---
+
+# `mobile-nav` schema
+
+Mobile Navigation Designer's content model (@erp/mobile-nav-engine) — a FLAT item list (bottom-tabs/drawer/hybrid), deliberately distinct from menu-definition.
+
+Pull the full JSON Schema: `erp schema pull mobile-nav`  ·  MCP: `erp_get_schema {"name":"mobile-nav"}`
+
+## Top-level properties
+
+| Property | Type | Required | Notes |
+| --- | --- | --- | --- |
+| `name` | string | yes |  |
+| `description` | string |  |  |
+| `metadata` | object |  |  |
+| `modules` | array |  |  |
+| `definition` | object | yes |  |
+

package/bundle/docs/reference/page-template.md

@@ -0,0 +1,29 @@
+---
+title: page-template schema
+audience: tenant
+generated: true
+---
+
+# `page-template` schema
+
+A reusable page template (see the generic-capability generator pattern).
+
+Pull the full JSON Schema: `erp schema pull page-template`  ·  MCP: `erp_get_schema {"name":"page-template"}`
+
+## Top-level properties
+
+| Property | Type | Required | Notes |
+| --- | --- | --- | --- |
+| `contractVersion` | — | yes |  |
+| `id` | string | yes |  |
+| `version` | string | yes |  |
+| `publisher` | string | yes |  |
+| `extends` | string |  |  |
+| `kind` | enum |  | one of: `standard`, `wizard` |
+| `steps` | array |  |  |
+| `regions` | array | yes |  |
+
+## Named sub-definitions
+
+`identifier`, `i18nKey`, `row`
+

package/bundle/docs/reference/page.md

@@ -0,0 +1,44 @@
+---
+title: page schema
+audience: tenant
+generated: true
+---
+
+# `page` schema
+
+A page's rows/overlays/variants/designer metadata — the top-level page.json contract.
+
+Pull the full JSON Schema: `erp schema pull page`  ·  MCP: `erp_get_schema {"name":"page"}`
+
+## Top-level properties
+
+| Property | Type | Required | Notes |
+| --- | --- | --- | --- |
+| `contractVersion` | — | yes |  |
+| `id` | string | yes |  |
+| `version` | string | yes |  |
+| `publisher` | string | yes |  |
+| `title` | `#/$defs/i18nKey` | yes |  |
+| `template` | string |  |  |
+| `slotFills` | object |  |  |
+| `rows` | array | yes |  |
+| `canvas` | array |  |  |
+| `overlays` | array |  |  |
+| `theme` | object |  |  |
+| `route` | `#/$defs/route` | yes |  |
+| `menu` | `#/$defs/menuEntry` |  |  |
+| `breadcrumb` | `#/$defs/breadcrumb` |  |  |
+| `variants` | array |  |  |
+| `designer` | `#/$defs/designer` | yes |  |
+| `access` | string |  | one of: `public`, `authenticated` |
+| `backgroundImageUrl` | string |  |  |
+| `isLoginPage` | boolean |  |  |
+| `isSessionExpiredPage` | boolean |  |  |
+| `isAccessDeniedPage` | boolean |  |  |
+| `devicePersistence` | array |  |  |
+| `modules` | array |  | App-module ids this page belongs to (e.g. "hcm-foundation-home") - TenantPageHost's per-module page listing only surfaces a page if it's present here. Load-bearing in practice for any page reached via the app sidenav/module shell, even on pages authored before this was documented. |
+
+## Named sub-definitions
+
+`identifier`, `i18nKey`, `expression`, `breakpointOverride`, `breakpointOverrides`, `linkItem`, `item`, `column`, `row`, `routeParam`, `route`, `menuEntry`, `breadcrumb`, `overlay`, `variantRule`, `variant`, `canvasPosition`, `canvasItem`, `designer`, `devicePersistenceRule`
+

package/bundle/docs/reference/plugin-manifest.md

@@ -0,0 +1,54 @@
+---
+title: plugin-manifest schema
+audience: tenant
+generated: true
+---
+
+# `plugin-manifest` schema
+
+A real .spk business-application plugin's own spk-assembly/plugin.json contract (id/version/permissions/roles/dependencies).
+
+Pull the full JSON Schema: `erp schema pull plugin-manifest`  ·  MCP: `erp_get_schema {"name":"plugin-manifest"}`
+
+## Top-level properties
+
+| Property | Type | Required | Notes |
+| --- | --- | --- | --- |
+| `id` | string | yes |  |
+| `name` | string | yes |  |
+| `version` | string | yes |  |
+| `type` | string |  |  |
+| `vendor` | string |  |  |
+| `license` | string |  |  |
+| `licenseTier` | string |  |  |
+| `category` | string |  |  |
+| `erpVersion` | string |  |  |
+| `minErpVersion` | string |  |  |
+| `maxErpVersion` | string |  |  |
+| `mainClass` | string \| null |  | Fully-qualified PF4J plugin main class. Optional (null/absent) for a pure-JSON plugin that ships zero Java classes -- the platform loads it via the built-in JsonOnlyPlugin entry point. |
+| `schemaName` | string |  | App-owned Postgres schema this plugin's Entity-Engine tables route to — see feedback-entity-engine-tables-must-route-to-app-schema. |
+| `scope` | string |  | one of: `global`, `tenant` — Tenant-Safe Plugin & Extension Architecture spec §54. 'global' (default, every manifest that predates this field): a shared plugin installable by any tenant. 'tenant': a private single-tenant L5 extension — MUST also set tenantId, and if it carries Java code (mainClass, or type java-extension/code-plugin) it MUST declare runtimeModes: ['service'] — the shared runtime refuses to load it (ExtensionInstallValidator, spec §11/§28.10/§74). |
+| `tenantId` | string |  | Spec §54 — the owning tenant of a scope:'tenant' plugin. Required iff scope=='tenant'; must match the tenant the plugin is installed into. Absent for a global plugin. |
+| `erpApiVersion` | string |  | Spec §25 — the ERP extension-API contract version this plugin targets (e.g. '5.0'), distinct from erpVersion/minErpVersion (platform build versions). Optional; informational in E1. |
+| `supportedApplications` | array |  | Spec §25 — applications this extension supports, e.g. ['HCM']. Optional; empty/absent means unconstrained. |
+| `dependencies` | array |  |  |
+| `optionalDependencies` | array |  |  |
+| `permissions` | array |  | Legacy flat permission-key catalogue; real installs read roles[].permissionKeys instead (PluginRoleInstaller) — commonly left empty on modules whose roles[] is populated. |
+| `owner` | string |  |  |
+| `editable` | boolean |  |  |
+| `extendable` | boolean |  |  |
+| `capabilitiesProvided` | array |  |  |
+| `capabilitiesRequired` | array |  |  |
+| `featureFlags` | array |  |  |
+| `configSchemaJson` | object \| string \| null |  |  |
+| `frontendBundle` | object |  | Optional — dynamic frontend-plugin-loading (ai/patterns/code-plugin-sdk.md). Absent on every plugin.json that predates it. |
+| `roles` | array |  |  |
+| `runtimeModes` | array |  | Added 2026-09-03 (real gap — this field is genuinely load-bearing on every shipped plugin.json today, e.g. hcm-learning's own ["embedded"], but was entirely absent from this schema until now, so erp_get_schema/erp schema pull misrepresented the real manifest shape). Which Plugin Runtime modes this plugin can run under: 'embedded' (loaded in-process via PF4J, the only behavior every pre-existing manifest declares) and/or 'service' (its own standalone Spring Boot process, routed to over HTTP — see PluginManifest#runtimeModes' own Javadoc in engine-plugin-api). Defaults to ['embedded'] when absent. Declaring 'service' here does not itself switch anything — the actual mode is chosen per-plugin via Studio's Plugin Runtime toggle (erp_core.application.deployment_type). |
+| `serviceRuntime` | string \| null |  | one of: `java`, `python`, `nodejs`, `null` — Added 2026-09-14 (Polyglot Plugin Runtime initiative, PluginManifest#serviceRuntime's own Javadoc in engine-plugin-api). Which language a Service-mode plugin's own process is implemented in. Only meaningful when runtimeModes contains 'service' — an embedded-only plugin is always Java (nothing else can load into the JVM), and installing a manifest that sets this to 'python'/'nodejs' without declaring 'service' in runtimeModes fails install (PluginCodeLifecycle#validateServiceRuntime). null/absent defaults to 'java' — every manifest that predates this field keeps its exact current behavior. Real, proven implementations exist for all three values: hello-plugin-service (java), hello-plugin-service-python (python), hello-plugin-service-node (nodejs) — see 'Build a Service-mode plugin in Python or Node.js' for the SDK and full build/deploy path for each. |
+| `serviceFramework` | string \| null |  | one of: `spring-boot`, `fastapi`, `express`, `null` — Added 2026-09-14, same initiative as serviceRuntime — purely informational (shown as a read-only chip in Studio's Plugin Runtime panel; not validated against serviceRuntime today, so keep them consistent yourself: spring-boot pairs with java, fastapi with python, express with nodejs). null/absent defaults to 'spring-boot'. |
+| `serviceDeployment` | object \| null |  | Added 2026-09-03 (same real-gap fix as runtimeModes). Recommended deployment/runtime defaults for this plugin when run in 'service' mode (PluginManifest.PluginServiceDeploymentSpec in engine-plugin-api). null (the default for almost every manifest) means Studio seeds an empty config the admin fills in the first time they switch this plugin to Service mode. Only healthPath/timeoutMs/heartbeatIntervalSeconds actually drive runtime behavior today (health checks, proxy call timeout) — docker/kubernetes/cloud are real, persisted, Studio-editable data for a future Deployment Manager, not wired to any live provisioning API. |
+
+## Named sub-definitions
+
+`resourceLimits`
+

package/bundle/docs/reference/plugin-seed-data.md

@@ -0,0 +1,21 @@
+---
+title: plugin-seed-data schema
+audience: tenant
+generated: true
+---
+
+# `plugin-seed-data` schema
+
+metadata/seed-data/*.json — Entity-Engine data rows a plugin seeds on install/upgrade, idempotently (upsert by keyFields). See ai/patterns/plugin-install-data-seeding.md.
+
+Pull the full JSON Schema: `erp schema pull plugin-seed-data`  ·  MCP: `erp_get_schema {"name":"plugin-seed-data"}`
+
+## Top-level properties
+
+| Property | Type | Required | Notes |
+| --- | --- | --- | --- |
+| `entity` | string | yes | Entity Engine entity name the rows belong to. Must already exist (ship it in metadata/entities/ if the plugin owns it). |
+| `keyFields` | array | yes | The natural-key fields that uniquely identify a row. On re-install, a row matching all keyFields is updated (only if a non-key value changed); otherwise inserted. Never produces duplicates. |
+| `source` | string |  | The plugin id. Stamped into a seeded_by field when the entity has one. |
+| `rows` | array | yes | The rows to upsert. Each is a plain field map for the entity - no tenant id (the installer supplies it). |
+