@sparkerp/plugin-sdk 0.1.0

package/bundle/docs/guides/wire-a-pages-data.md

@@ -0,0 +1,153 @@
+---
+title: Wire a page's data
+audience: tenant
+---
+
+# Wire a page's data
+
+## What you're doing
+
+You have a page with a `core.grid` block and it shows **zero rows and no error
+message**. This is the single most common confusion on the platform. This guide
+explains the one chain that connects a grid to a table.
+
+## The mental model
+
+```
+page.metadata.dataSource   ──names──▶   a Data Provider file      ──points at──▶   a REST base path
+"oeq-equipment-provider"                metadata/provider/          /api/v1/entities/oeq_equipment/records
+```
+
+Three things must line up **exactly**:
+
+1. The page's top-level **`metadata.dataSource`** is a string.
+2. That string equals the **`name`** field of a file in
+   `spk-assembly/metadata/provider/`.
+3. That provider's **`definition.basePath`** is a real REST path that supports
+   `search`.
+
+The grid block itself has **no** data configuration. It renders whatever the
+page's `dataSource` provider returns.
+
+## The complete example
+
+Page (`equipment-register.json`), last two lines of the file:
+
+```json
+  "metadata": { "dataSource": "oeq-equipment-provider" },
+  "modules": ["office-equipment"]
+}
+```
+
+Provider (`spk-assembly/metadata/provider/oeq-equipment-provider.json`) —
+[the real file](../tutorial/example-plugin/spk-assembly/metadata/provider/oeq-equipment-provider.json):
+
+```json
+{
+  "name": "oeq-equipment-provider",
+  "description": "Data Provider for oeq_equipment (grid + CRUD).",
+  "definition": {
+    "kind": "rest",
+    "connectionRef": "self",
+    "basePath": "/api/v1/entities/oeq_equipment/records",
+    "supports": ["search", "get", "create", "update"]
+  },
+  "metadata": {},
+  "modules": []
+}
+```
+
+The string `"oeq-equipment-provider"` appears in **both** files, spelled
+identically. That is the whole wiring.
+
+## Line by line
+
+- **`metadata.dataSource`** — page-level. Not inside `definition`, not on any
+  block. A grid with no matching `dataSource` shows nothing.
+- **provider `name`** — the lookup key. Must match `dataSource` character for
+  character.
+- **`kind: "rest"`** — the provider calls a REST endpoint.
+- **`connectionRef: "self"`** — this ERP's own backend. (External systems use a
+  named connection.)
+- **`basePath`** — for an entity you own, it's always
+  `/api/v1/entities/<entityName>/records`. The Entity Engine serves `search` at
+  `<basePath>/query`, `get` at `<basePath>/{id}`, `create` at `POST <basePath>`,
+  `update` at `PUT <basePath>/{id}`.
+- **`supports`** — which of those the grid/dialogs may use.
+
+## Filtering the grid
+
+The grid's `externalFilter` property binds a page state object. Its keys become
+query filters:
+
+```json
+"externalFilter": { "source": "binding", "binding": { "scope": "page", "key": "gridExternalFilter" } }
+```
+
+A search input then writes into it:
+
+```json
+"events": { "committed": { "source": "action-chain", "actions": [
+  { "id": "a0", "order": 0, "type": "setValue",
+    "config": { "field": "page.gridExternalFilter.search", "value": "${event.new}" } }
+] } }
+```
+
+Now typing in the box filters the grid on `search`; picking a status filters on
+`status`. (`${event.new}` — the committed value — see
+[Add a create/edit form](./add-a-create-edit-form.md).)
+
+## Refreshing the grid after a write
+
+Bind `refreshTrigger` to a page value and flip it at the end of a save chain:
+
+```json
+{ "id": "a2", "order": 2, "type": "setValue",
+  "config": { "field": "page.gridRefreshTick", "value": "${!page.gridRefreshTick}" } }
+```
+
+## When you need a computed / joined read
+
+If the grid needs columns from more than one table, or server-side aggregation,
+the provider's `basePath` can point at a **Data Service** or **Data View**
+instead of a raw entity. See [Add a data provider, data view, or data
+service](./add-a-data-provider.md).
+
+## How to verify it worked
+
+The semantic linter catches the mismatch before you publish:
+
+```bash
+erp plugin test office-equipment/spk-assembly
+```
+
+If the wiring is broken you get:
+
+```
+PAGE-DS-001  equipment-register.json: core.grid present but metadata.dataSource
+             "oeq-equipmnt-provider" does not match any metadata/provider/*.json name
+```
+
+When it's right, `erp plugin test` is silent on `PAGE-DS-001` and after publish:
+
+```bash
+erp api get "/api/v1/entities/oeq_equipment/records/query?size=3"
+```
+
+returns real rows — which is exactly what the grid will show.
+
+## Common mistakes
+
+| Symptom | Cause | Fix |
+| --- | --- | --- |
+| grid empty, no error | `dataSource` typo / absent / put on the grid block | move it to page `metadata.dataSource`, match the provider `name` |
+| grid empty but the entity has rows | provider `basePath` wrong | for your own entity it's `/api/v1/entities/<name>/records` |
+| grid loads once, never refreshes after save | no `refreshTrigger` binding | bind it and toggle it at the end of the save chain |
+| filter box does nothing | `externalFilter` not bound, or `committed` writes the wrong key | bind `gridExternalFilter`; write `page.gridExternalFilter.<key>` |
+| "0 rows" only for some users | row-level permissions | expected — check the user's role |
+
+## What to read next
+
+- [Add a data provider, data view, or data service](./add-a-data-provider.md)
+- [Add a create / edit form](./add-a-create-edit-form.md)
+- Troubleshooting: [My grid shows 0 rows](../troubleshooting/grid-shows-zero-rows.md)

package/bundle/docs/quickstart/index.md

@@ -0,0 +1,118 @@
+---
+title: Build and publish a one-page plugin
+audience: tenant
+---
+
+# Quickstart: a one-page plugin, live
+
+By the end of this page you will have a plugin installed on your ERP tenant with
+one working page reachable from the app menu. Every command is real against the
+current `erp` CLI.
+
+## 0. Prerequisites
+
+- Node.js 20+.
+- The plugin SDK on your `PATH` (the `erp` command). Until the SDK is published
+  to npm you run it directly: `node <sdk>/tools/erp-cli/erp.mjs`. Substitute that
+  for `erp` below.
+- The base URL of your ERP (e.g. `https://erp.example.com`).
+
+## 1. Point the CLI at your ERP and log in
+
+```bash
+erp env use prod --base-url https://erp.example.com
+erp login
+```
+
+`erp login` opens your browser, you authorize the CLI, and the session is written
+to `~/.erp/config.json`. Confirm it:
+
+```bash
+erp whoami
+```
+
+## 2. Sync the authoring bundle (optional but recommended)
+
+```bash
+erp env sync
+```
+
+This pulls your ERP's schema/catalog/example/doc bundle into
+`~/.erp/cache/`. If your ERP does not expose the bundle endpoint yet, this
+no-ops and the SDK falls back to the bundle shipped inside the SDK package —
+you can keep going.
+
+## 3. Wire up the MCP server for your IDE agent
+
+```bash
+erp mcp install
+```
+
+Writes a `.mcp.json` in the current directory pointing at the
+`erp-plugin-language` MCP server, so Claude Code / Cursor / Codex can call
+`erp_get_schema`, `erp_list_blocks`, `erp_platform_catalog`,
+`erp_search_docs`, `erp_examples_patterns`, `erp_validate_page`, and the rest.
+
+## 4. Scaffold the plugin
+
+```bash
+erp plugin create acme-hello --name "Acme Hello" --type business-app
+```
+
+This creates `acme-hello/` with a `spk-assembly/` tree (`plugin.json`,
+`metadata/page/`, `metadata/menu/`, `metadata/i18n/`, …).
+
+> **No Java needed.** The scaffold leaves `plugin.json`'s `mainClass` `null` and
+> that is exactly right for a pure-JSON plugin — the platform loads it through a
+> built-in generic entry point. You compile a `Plugin` class only if your plugin
+> ships its own Java behaviour. See
+> [Create a plugin from scratch](../guides/create-a-plugin.md).
+
+Author one page under `spk-assembly/metadata/page/hello.json`. Ground yourself
+first — do not guess the shape:
+
+```bash
+erp schema pull page                 # the page.json contract
+erp blocks list --category display   # what widgets exist
+erp examples patterns --kind page    # curated real page shapes
+```
+
+Give the page a menu entry:
+
+```bash
+erp menu create acme-hello acme-hello.main --display-name "Hello" --route /hello
+```
+
+## 5. Validate before you ship
+
+```bash
+erp plugin validate acme-hello/spk-assembly
+erp plugin test acme-hello/spk-assembly      # semantic lints (i18n keys, grid data-source, …)
+```
+
+Fix anything flagged. These are the same checks the platform runs at install
+time — a clean run here means a clean install.
+
+## 6. Build and publish
+
+```bash
+erp plugin build acme-hello/spk-assembly -o acme-hello.spk
+erp plugin publish acme-hello.spk
+```
+
+## 7. See it live
+
+Open your ERP, navigate to the app that owns the module, and you'll find the
+**Hello** menu item. The page URL is
+`/app/<app>/<module>/acme-hello/hello` (the route pattern in your menu file is
+*not* the browser URL — see `troubleshooting/known-gotchas.md`).
+
+## Next
+
+- [The tutorial](../tutorial/index.md) — build and publish a real 3-page module
+  end to end, every step verified.
+- [Guides](../guides/index.md) — every task as its own page.
+- [concepts/overview.md](../concepts/overview.md) — how the pieces fit together.
+- [reference/](../reference/index.md) — every authoring artifact's JSON Schema.
+- [troubleshooting/known-gotchas.md](../troubleshooting/known-gotchas.md) — the
+  mistakes everyone makes once.

package/bundle/docs/recipes/condition-based-compliance-flag.md

@@ -0,0 +1,70 @@
+---
+title: A condition-based compliance flag
+audience: tenant
+---
+
+# A condition-based compliance flag
+
+## When you need this
+
+"Find rows that break a policy and flag them" — where the policy is more than one
+date vs now. Un-acknowledged custody after 7 days, over-allocated licences,
+missing documentation. Zero Java — one `entity_compliance_config` row run by
+`engine-entity.compliance-sweep`.
+
+## The file
+
+`metadata/seed-data/office-equipment-compliance-configs.json`
+([real file](../examples/standalone-plugin/spk-assembly/metadata/seed-data/office-equipment-compliance-configs.json)):
+
+```json
+{
+  "entity": "entity_compliance_config",
+  "keyFields": ["compliance_code"],
+  "source": "office-equipment",
+  "rows": [
+    {
+      "compliance_code": "checkout-acknowledgement-compliance",
+      "source_entity": "oeq_checkout",
+      "when_status_in": "CHECKED_OUT,DUE_SOON,OVERDUE",
+      "condition_expr": "custody_acknowledged != true && daysBetween(checkout_date, now()) > 7",
+      "set_field": "compliance_flag",
+      "set_value": "NON_COMPLIANT",
+      "active": true
+    }
+  ]
+}
+```
+
+A row where `condition_expr` is **true** is non-compliant; the job sets
+`compliance_flag = "NON_COMPLIANT"` on it (idempotent — a row already flagged is
+skipped).
+
+## The expression language
+
+The platform `ExpressionEvaluator` — the same one that powers formula fields and
+cross-field validation. In scope: the row's fields, `now`, and (if configured)
+`related_count`. Allowed: `&&`, `||`, `!`, comparisons, arithmetic, and
+whitelisted functions (`daysBetween`, `now`, `coalesce`, …). **Not allowed:**
+ternary `?:`, `in`, `^`.
+
+## Variants
+
+- **Related-count** (cross-record) — add `related_count_entity`,
+  `related_count_key_field` (FK back to the source id), `related_count_status_in`;
+  then use `related_count` in the expression, e.g.
+  `related_count > entitlement_quantity`.
+- **Escalation** (raise a row in another entity) — replace `set_field`/`set_value`
+  with `escalation_entity`, `escalation_dedupe_field` (a numeric column holding
+  the source id), `field_map_json`, `escalation_template_json`.
+
+## Also ship
+
+- the shared `entity_compliance_config.json` (additive), and
+- `metadata/rules/ensure_compliance_sweep_job_registered.json`
+  (`AFTER_CREATE` → `ensureEntityComplianceSweepJobRegistered`).
+
+## Related
+
+- [Add a compliance-sweep job](../guides/add-a-compliance-job.md)
+- [Add business rules and expressions](../guides/add-business-rules.md) — same expression language

package/bundle/docs/recipes/cross-plugin-offboarding-fanout.md

@@ -0,0 +1,68 @@
+---
+title: A cross-plugin offboarding fan-out
+audience: tenant
+---
+
+# A cross-plugin offboarding fan-out
+
+## When you need this
+
+"When an employee is separated, auto-create the follow-up records for everything
+they hold" — asset return requests, licence reclamations, access revocations. The
+trigger entity can belong to **another plugin** entirely. Zero Java, zero
+cross-plugin HTTP — one `entity_cross_plugin_action_config` row run by
+`engine-entity.cross-plugin-action`.
+
+## The file
+
+`metadata/seed-data/office-equipment-cross-plugin-configs.json`:
+
+```json
+{
+  "entity": "entity_cross_plugin_action_config",
+  "keyFields": ["action_code"],
+  "source": "office-equipment",
+  "rows": [
+    {
+      "action_code": "equipment-separation-return",
+      "trigger_entity": "employee",
+      "trigger_status_field": "employment_status",
+      "trigger_status_in": "TERMINATED,SEPARATED",
+      "trigger_key_field": "id",
+      "related_entity": "oeq_checkout",
+      "related_match_field": "employee_id",
+      "related_status_in": "APPROVED,CHECKED_OUT,DUE_SOON,OVERDUE",
+      "create_entity": "oeq_return",
+      "create_dedupe_field": "checkout_id",
+      "create_template_json": { "status": "REQUESTED", "reason": "EMPLOYEE_SEPARATION" },
+      "create_field_map_json": { "equipment_id": "equipment_id", "employee_id": "employee_id" },
+      "related_set_field": "status",
+      "related_set_value": "RETURN_PENDING",
+      "active": true
+    }
+  ]
+}
+```
+
+## How to read it
+
+When an `employee` row's `employment_status` becomes `TERMINATED` or
+`SEPARATED`, the job finds every `oeq_checkout` for that `employee_id` in an
+active status, creates one `oeq_return` per checkout (deduped on `checkout_id`,
+which **must be a numeric/long column**), copies the mapped fields, applies the
+template, and sets the source checkout's status to `RETURN_PENDING`.
+
+## The rules that bite
+
+- `create_dedupe_field` must be a numeric column holding the related row's id —
+  it's how the job avoids double-creating on the next tick.
+- The `trigger_entity` can be owned by any plugin; you just need its name and
+  the status field.
+- Ship the shared `entity_cross_plugin_action_config.json` (additive) and an
+  `AFTER_CREATE` register rule calling
+  `ensureEntityCrossPluginActionJobRegistered`.
+
+## Related
+
+- `erp examples patterns --kind jobs` → `cross-plugin-offboarding-fanout`
+- [Add a cadence-generator job](../guides/add-a-cadence-job.md) — the source-driven cousin

package/bundle/docs/recipes/cross-row-aggregation.md

@@ -0,0 +1,67 @@
+---
+title: A cross-row aggregation into a summary entity
+audience: tenant
+---
+
+# A cross-row aggregation into a summary entity
+
+## When you need this
+
+"Count / sum / average many rows on a schedule and store the result." A nightly
+inventory reconciliation, per-asset maintenance-cost totals, seats-used per
+licence. Zero Java — one `entity_aggregation_config` row run by
+`engine-entity.aggregation-sweep`.
+
+## The file
+
+`metadata/seed-data/office-equipment-aggregation-configs.json`
+([real file](../examples/standalone-plugin/spk-assembly/metadata/seed-data/office-equipment-aggregation-configs.json)):
+
+```json
+{
+  "entity": "entity_aggregation_config",
+  "keyFields": ["sweep_code"],
+  "source": "office-equipment",
+  "rows": [
+    {
+      "sweep_code": "equipment-status-reconciliation",
+      "source_entity": "oeq_equipment",
+      "aggregation": "count",
+      "group_by_field": "status",
+      "target_entity": "oeq_reconciliation",
+      "target_key_field": "metric_key",
+      "target_key_prefix": "equipment_status:",
+      "target_value_field": "metric_value",
+      "target_timestamp_field": "last_reconciled_at",
+      "active": true
+    }
+  ]
+}
+```
+
+Result: one `oeq_reconciliation` row per status, keyed
+`equipment_status:AVAILABLE`, `equipment_status:ASSIGNED`, … with the count in
+`metric_value`.
+
+## Variants
+
+- **`sum` / `avg` / `min` / `max`** — add `agg_field` (the numeric column).
+- **Write onto the parent row instead of a summary entity** — set
+  `target_key_field: "id"`, leave `target_key_prefix` blank; the `group_by_field`
+  values are the parent's primary keys. (E.g. sum line-item cost onto the
+  maintenance record's own `synced_cost`.)
+- **Filter first** — add `status_field` + `when_status_in`.
+
+## Also ship
+
+- `metadata/entities/oeq_reconciliation.json` (the summary entity), and the
+  shared `entity_aggregation_config.json` (additive).
+- `metadata/rules/ensure_aggregation_sweep_job_registered.json` — an
+  `AFTER_CREATE` `EXECUTE_SERVICE` rule calling
+  `ensureEntityAggregationSweepJobRegistered` (this job does **not** self-register
+  from a platform rule — you ship it).
+
+## Related
+
+- [Add a cross-row aggregation job](../guides/add-an-aggregation-job.md)
+- [A KPI dashboard page](./kpi-dashboard-page.md) — the on-demand version

package/bundle/docs/recipes/entity-with-approval-workflow.md

@@ -0,0 +1,72 @@
+---
+title: An entity with an approval workflow + reminder job
+audience: tenant
+---
+
+# An entity with an approval workflow + reminder job
+
+## When you need this
+
+A record with a full lifecycle: it's drafted, submitted for approval, approved,
+acted on, and eventually chased if it goes stale. This recipe combines
+[the approval workflow](../guides/add-an-approval-workflow.md) and
+[the reminder job](../guides/add-a-reminder-job.md) on one entity — exactly what
+the tutorial's `oeq_checkout` does.
+
+## The five files
+
+| File | Purpose |
+| --- | --- |
+| `metadata/entities/oeq_checkout.json` | the entity; status enum includes every lifecycle value (`DRAFT`, `PENDING_APPROVAL`, `APPROVED`, `CHECKED_OUT`, `DUE_SOON`, `OVERDUE`, `RETURNED`, `REJECTED`) |
+| `metadata/workflow/office-equipment.checkout-approval.json` | single-stage manager approval |
+| `metadata/rules/oeq_checkout_submit_workflow.json` | `AFTER_UPDATE` rule: status → `PENDING_APPROVAL` starts the workflow; decision writes `APPROVED`/`REJECTED` back |
+| `metadata/entities/entity_status_date_sweep_config.json` | ship the shared config entity (idempotent-additive) |
+| `metadata/seed-data/office-equipment-sweep-configs.json` | 2 sweep configs: `CHECKED_OUT` within 3 days → `DUE_SOON`; past due → `OVERDUE` |
+
+All five are real in
+[`tutorial/example-plugin/`](../tutorial/example-plugin/spk-assembly/metadata/).
+
+## The lifecycle, end to end
+
+```
+DRAFT
+  │  user: Submit for approval  (PUT status = PENDING_APPROVAL)
+  ▼
+PENDING_APPROVAL ──rule──▶ workflow instance + manager task
+  │  manager approves ──callback──▶ status = APPROVED
+  ▼
+APPROVED
+  │  equipment handed over  (PUT status = CHECKED_OUT)
+  ▼
+CHECKED_OUT
+  │  nightly sweep: due_date within 3 days
+  ▼
+DUE_SOON
+  │  nightly sweep: due_date passed
+  ▼
+OVERDUE
+  │  equipment returned  (PUT status = RETURNED)
+  ▼
+RETURNED
+```
+
+The **user** drives `DRAFT → PENDING_APPROVAL`, `APPROVED → CHECKED_OUT`,
+`* → RETURNED` (buttons on the page). The **workflow** drives
+`PENDING_APPROVAL → APPROVED/REJECTED`. The **sweep job** drives
+`CHECKED_OUT → DUE_SOON → OVERDUE`. No two mechanisms fight over the same
+transition.
+
+## The rules that bite
+
+- The submit rule needs the `status__previous` guard so it fires only on the
+  transition, not every later update.
+- The `OVERDUE` sweep config's `when_status_in` includes `DUE_SOON`, so a warned
+  checkout still escalates.
+- Sweep configs flip the **status enum**, not a boolean flag (the generic job
+  can't write a string to a boolean column).
+
+## Related
+
+- [Add an approval workflow](../guides/add-an-approval-workflow.md)
+- [Add a scheduled reminder job](../guides/add-a-reminder-job.md)
+- Tutorial chapters [6](../tutorial/06-checkout-approval-workflow.md) and [7](../tutorial/07-return-due-reminder-job.md)

package/bundle/docs/recipes/index.md

@@ -0,0 +1,40 @@
+---
+title: Recipes
+audience: tenant
+---
+
+# Recipes
+
+Short, copy-paste solutions to shapes that come up again and again. Each recipe
+is 2–3 sentences of "when you need this" plus the real file(s). They're drawn
+from the curated `erp examples patterns` catalog — run that any time to see the
+live list, each entry pointing at a real shipped file:
+
+```bash
+erp examples patterns              # all
+erp examples patterns --kind jobs  # just the scheduled-job shapes
+```
+
+## Screens
+
+- [A searchable related-record lookup field](./related-record-lookup-field.md)
+- [A resolved reference column in a grid](./resolved-reference-grid-column.md)
+- [A KPI dashboard page](./kpi-dashboard-page.md)
+- [A master-detail page with a child grid](./master-detail-page.md)
+
+## Logic
+
+- [An entity with an approval workflow](./entity-with-approval-workflow.md)
+
+## Scheduled jobs (no Java)
+
+- [An N-days-before reminder job](./n-days-before-reminder.md)
+- [A cross-row aggregation into a summary entity](./cross-row-aggregation.md)
+- [A scheduled record-generation cadence](./scheduled-record-generation.md)
+- [A condition-based compliance flag](./condition-based-compliance-flag.md)
+- [A cross-plugin offboarding fan-out](./cross-plugin-offboarding-fanout.md)
+- [A per-row document artifact generator](./per-row-document-generator.md)
+
+## Install
+
+- [Install-lifecycle data seeding](./install-lifecycle-data-seeding.md)

package/bundle/docs/recipes/install-lifecycle-data-seeding.md

@@ -0,0 +1,76 @@
+---
+title: Install-lifecycle data seeding
+audience: tenant
+---
+
+# Install-lifecycle data seeding
+
+## When you need this
+
+Any time a data row must **travel with the `.spk`** instead of a manual
+per-tenant `POST` — reference data you own, default settings, and (the important
+case) rows in the **shared platform config entities** that make your scheduled
+jobs exist.
+
+## The file
+
+`metadata/seed-data/<name>.json`:
+
+```json
+{
+  "entity": "oeq_category",
+  "keyFields": ["category_code"],
+  "source": "office-equipment",
+  "rows": [
+    { "category_code": "LAPTOP", "category_name": "Laptops", "status": "ACTIVE", "seeded_by": "office-equipment" }
+  ]
+}
+```
+
+- **`entity`** — must already exist (ship it in `metadata/entities/` if you own
+  it).
+- **`keyFields`** — the natural key. On re-install a matching row is updated only
+  if a non-key value changed, else inserted. **Never duplicated.**
+- **`source`** — your plugin id; stamped into a `seeded_by` field if present.
+- **`rows`** — plain field maps, no tenant id.
+
+## Verified idempotency
+
+First install of the tutorial module:
+
+```
+PluginDataSeedInstaller: office-equipment-categories.json -> entity oeq_category (tenant 2): 4 created, 0 updated, 0 unchanged
+```
+
+Re-publish with one row added:
+
+```
+PluginDataSeedInstaller: office-equipment-categories.json -> entity oeq_category (tenant 2): 1 created, 0 updated, 4 unchanged
+```
+
+## For scheduled-job config
+
+When the target is a shared config entity
+(`entity_status_date_sweep_config`, `entity_aggregation_config`,
+`entity_cadence_config`, `entity_compliance_config`, `entity_cross_plugin_action_config`,
+`entity_document_generator_config`) also ship:
+
+1. **the shared config entity file** — with just the additive columns your rows
+   need. `PluginEntityInstaller` is idempotent-additive: an existing table gains
+   only the missing columns.
+2. **an `AFTER_CREATE` register rule** on that config entity calling
+   `ensure<Job>Registered`, so the first seeded row auto-registers the job. (The
+   status-date-sweep job's register rule ships with the platform; the other five
+   you ship.)
+
+## The rules that bite
+
+- Non-unique `keyFields` → duplicates on re-install. Pick a real key.
+- A `null` in a key field in some rows → matches nothing / everything. Keep key
+  fields populated in every row.
+- Seed targets an entity you forgot to ship → `SEED-001` lint / install failure.
+
+## Related
+
+- [Seed config and reference data on install](../guides/seed-data-on-install.md)
+- Each job guide's "register rule" section