@sparkerp/plugin-sdk 0.1.0

package/bundle/docs/applications/hcm/employee-profile.md

@@ -0,0 +1,144 @@
+---
+title: Employee Profile
+audience: tenant
+---
+
+# Employee Profile (HCM)
+
+This page documents the shipped **Employee Profile** screen in the HCM
+Employee module (`hcm-employee`), for the people who use it day to day — HR
+admins and anyone with access to an employee record — not for plugin
+developers. If you're building or extending this screen yourself, it's an
+ordinary JSON-first page (`spk-assembly/metadata/page/employee-profile.json`)
+like any other; see [Build a page](../../guides/build-a-page.md) for that.
+
+## Getting there
+
+Open it from the **Employees** list (or Active Employees / Consultants /
+Contract Employees / Interns / Probation Employees / Remote Employees / Ex
+Employees — the other roster views in the same module): click any row. The
+URL is `/hcm-employee/employee-profile/<employeeId>` — it always shows one
+employee's record, never a list.
+
+## What the header shows
+
+- An icon avatar (initials/icon only — there's no photo field on the
+  Employee entity, so no photo ever renders here).
+- The employee's full name, plus a status chip: **Active** (green),
+  **Inactive** (default), or **Terminated** (red) — whichever one matches
+  the record's `employmentStatus`.
+- Their current position/designation.
+- Employee code, email, and phone, each with an icon.
+- Three info chips: **Department**, **Reports To** (manager name), and
+  **Employment Type**.
+- An **Edit Profile** button, top right (see below).
+
+## Editing the record
+
+**Edit Profile** opens a dialog pre-filled from the current record. It
+covers: Full Name, Email, Phone, Employment Status, Employment Type,
+Department, Position, Reporting Manager, Date of Birth, Gender, Marital
+Status, Nationality, Languages, and Blood Group — plus an optional
+**Apply Change On** date, for scheduling when an edit should take effect
+rather than applying it immediately. Full Name and Email are required;
+Save is blocked until both are filled in.
+
+## The tabs
+
+The profile is organized into tabs across the top. What's real and backed by
+live data, and what's disclosed as not yet built, differs by tab — this
+section says which is which plainly, because the page itself does too (see
+the on-page disclosure notes quoted below).
+
+### Overview
+
+The landing tab. A grid of cards:
+
+- **About** — date of birth, gender, marital status, with a "View more" that
+  expands to also show nationality, languages, and blood group.
+- **Job Information** — employee ID, joining date, department, designation,
+  reports-to, grade. (Work Location is deliberately not shown here — see
+  [Known gaps](#known-gaps).)
+- **Quick Info** — tenant-defined custom fields for the employee, via the
+  platform's generic Custom Field Engine (`entityType: "employee"`). This is
+  how country- or tenant-specific identifiers (e.g. statutory IDs) show up
+  without being hardcoded into this module — an admin adds them as custom
+  field definitions, not code changes.
+- **Reporting Structure** — the employee's direct reports, pulled live from
+  the org chart.
+- **Recent Activities** — a real, employee-scoped feed from the platform's
+  audit trail.
+- **Skills & Expertise** — a real list of skills, each with a proficiency
+  level (Beginner / Intermediate / Advanced / Expert). An **Add Skill**
+  control lets you add a new skill name + level to the record.
+
+### Employment / Personal
+
+Read-oriented detail tabs breaking the same employment and personal-info
+fields (employment type/status, department, grade, work location, hire
+date, reports-to, designation / date of birth, gender, marital status,
+nationality, languages, blood group) into their own focused views, separate
+from the Overview summary cards.
+
+### Documents
+
+Real: lists documents actually attached to the employee record via the
+platform's File Management module, plus their verification status. There's
+no upload control on this page yet — the page's own description flags that
+as a known follow-up (needs a file-upload source wired into the page
+runtime). A **Request Document Verification** action opens a dialog
+(document ID + category: Identity Proof, Address Proof, Education
+Certificate, Employment Contract, Work Authorization, or Other) that routes
+into the platform's approval workflow.
+
+### Compensation
+
+Real: shows the employee's current compensation (base salary, currency, pay
+frequency, effective date, status) and their compensation history. A
+**Request Compensation Change** action opens a dialog (base salary,
+currency, pay frequency, effective-from date) that also routes into an
+approval workflow rather than writing the change directly.
+
+### Attendance, Leave, Payroll, Performance, Assets, Notes
+
+These six tabs are shown with representative sample content, not live data
+— there is no Attendance, Leave, Payroll, Performance, or Assets module
+installed for this platform yet, and Notes has no backend of its own. This
+is a disclosed, deliberate choice the page makes explicit on-screen (small
+disclosure text), not a silent fabrication. For example, the page's own
+copy says: *"Attendance is not yet tracked for this tenant — no Attendance
+module is installed. Not fabricated."* and *"Leave tracking is not yet
+available for this tenant — no Leave module is installed. Balances shown at
+0, not fabricated."* Treat anything on these six tabs as a preview of the
+intended shape, not real employee data.
+
+### Requests
+
+A small summary tab: how many change requests are on file for this
+employee record (i.e. pending/past edits routed through workflow, such as
+the compensation and document-verification requests above), with a link to
+view them.
+
+## Known gaps
+
+- **No photo support.** The header always shows an icon, never an uploaded
+  photo — there is no photo field on the Employee entity.
+- **Work Location isn't shown**, even though it's a real field elsewhere in
+  HCM. Every read on this page goes through a Data Service (a platform-wide
+  rule — no page action calls a raw REST endpoint directly), and Work
+  Location would need a bespoke recursive-ancestor lookup that isn't
+  expressible as a flat Data View today. Rather than fetch it with a raw
+  call and break that rule, the field is left off this page entirely — a
+  disclosed gap, not a silent downgrade.
+- **Document upload isn't wired into this page yet** — Documents is
+  read-only (list + verification status + a verification *request*), not a
+  place to attach a new file. That needs a `FileUploadSource` wired into the
+  page runtime.
+- **Attendance / Leave / Payroll / Performance / Assets / Notes have no real
+  backend.** See [above](#attendance-leave-payroll-performance-assets-notes).
+
+## Related
+
+- [Build a page](../../guides/build-a-page.md) — if you're extending this
+  page or building something like it.
+- [How does a page get its data?](../../concepts/page-data-flow.md)

package/bundle/docs/concepts/artifact-types.md

@@ -0,0 +1,80 @@
+---
+title: What are the artifact types?
+audience: tenant
+---
+
+# What are the artifact types?
+
+A plugin is a folder of JSON files. Each file is an **artifact** of one type, and
+each type lives in its own subfolder of `spk-assembly/metadata/`. This page is
+the map: what each one is, and which guide covers it.
+
+## The manifest
+
+| File | What it is |
+| --- | --- |
+| `spk-assembly/plugin.json` | the manifest — id, version, `mainClass`, `schemaName`, roles, dependencies. [Create a plugin](../guides/create-a-plugin.md) |
+
+## Data
+
+| Folder | Type | One-line description | Guide |
+| --- | --- | --- | --- |
+| `metadata/entities/` | **entity** | a table you declare by its fields; the Entity Engine generates DDL + CRUD REST | [Add an entity](../guides/add-an-entity.md) |
+| `metadata/provider/` | **data provider** | a name → REST base path mapping; a page's `metadata.dataSource` points here | [Add a data provider](../guides/add-a-data-provider.md) |
+| `metadata/data_view/` | **data view** | a declared read-only SQL join over physical tables | [Add a data provider](../guides/add-a-data-provider.md) |
+| `metadata/data_service/` | **data service** | a parameterized query: `count` / `search` / `get` / `composite` | [Add a KPI](../guides/add-a-kpi.md) |
+| `metadata/seed-data/` | **seed data** | rows to upsert on install, idempotently | [Seed data on install](../guides/seed-data-on-install.md) |
+
+## Screens
+
+| Folder | Type | One-line description | Guide |
+| --- | --- | --- | --- |
+| `metadata/page/` | **page** | one screen — rows/columns of blocks, plus page-level `metadata.dataSource` | [Build a page](../guides/build-a-page.md) |
+| `metadata/menu/` | **menu** | a tree of navigation nodes pointing at routes | [Add menus](../guides/add-menus.md) |
+| `metadata/i18n/` | **translations** | `en.json` etc. — dotted key → text | [Add i18n](../guides/add-i18n.md) |
+| `metadata/application/` | **application** | (standalone plugins) the top-level product surface | [Tutorial ch.1](../tutorial/01-create-the-plugin.md) |
+| `metadata/module/` | **module** | (standalone plugins) a functional area inside an application; pages attach here | [Tutorial ch.1](../tutorial/01-create-the-plugin.md) |
+
+## Logic
+
+| Folder | Type | One-line description | Guide |
+| --- | --- | --- | --- |
+| `metadata/rules/` | **entity rule** | declarative logic at a lifecycle point — reject / set value / execute service / start workflow | [Add business rules](../guides/add-business-rules.md) |
+| `metadata/workflow/` | **workflow** | a multi-stage approval process | [Add an approval workflow](../guides/add-an-approval-workflow.md) |
+
+## Code
+
+| Path | What it is |
+| --- | --- |
+| `spk-assembly/lib/*.jar` | **optional** — a compiled `Plugin` subclass and its deps, only if the plugin ships Java extensions. A pure-JSON plugin has no `lib/` and leaves `mainClass` `null`. [Create a plugin](../guides/create-a-plugin.md); for a complete real example pairing this with a custom React component, [Build a plugin with custom React + Java code](../guides/build-a-code-plugin.md) |
+
+A custom block — a real React component of your own, no Java required — is
+not a `spk-assembly/metadata/` file at all; it's registered at runtime
+through `@erp/block-engine`/`@erp/block-adapter-mui`. See
+[Add a custom block](../guides/add-a-custom-block.md).
+
+## Scheduled jobs are not their own artifact type
+
+A scheduled job is **not** a file you write. It's a row you *seed* into a shared
+platform config entity (`entity_status_date_sweep_config`,
+`entity_aggregation_config`, `entity_cadence_config`, `entity_compliance_config`)
+plus an `AFTER_CREATE` register rule. The generic job engine does the rest. See
+the [job guides](../guides/index.md#scheduled-jobs-no-java).
+
+## The two file shapes
+
+Most artifact files use a **wrapper**:
+
+```json
+{ "name": "...", "description": "...", "definition": { /* the real contract */ }, "metadata": {}, "modules": [] }
+```
+
+Entities use `{ "entity": {...}, "fields": [...] }`. Pages use the wrapper with
+`definition` holding a `contractVersion: 1` object. `erp schema pull <name>`
+shows you the exact shape for each.
+
+## What to read next
+
+- [How does a plugin get installed?](./plugin-lifecycle.md)
+- [How does a page get its data?](./page-data-flow.md)
+- [Glossary](./glossary.md)

package/bundle/docs/concepts/glossary.md

@@ -0,0 +1,124 @@
+---
+title: Glossary
+audience: tenant
+---
+
+# Glossary
+
+Every term these docs use, defined once. Terms are cross-linked from the pages
+that introduce them.
+
+**action chain** — an ordered list of *actions* attached to a block *event*
+(`mounted`, `clicked`, `committed`, `rowClicked`). Actions include `callApi`,
+`setValue`, `showToast`, `downloadFile`, `navigate`.
+
+**application** — the top-level product surface a user opens (e.g. "HCM"). A
+standalone plugin ships its own in `metadata/application/`.
+
+**artifact** — one JSON file of one type in `spk-assembly/metadata/`. See
+[artifact types](./artifact-types.md).
+
+**authoring bundle** — the offline grounding data (schemas, capability catalog,
+blocks, examples, docs) the SDK reads. Refreshed with `erp env sync`. See
+[SDK modes](./sdk-modes.md).
+
+**binding** — a block property that reads from page state:
+`{ "source": "binding", "binding": { "scope": "page", "key": "kpiTotal" } }`.
+The other property form is `{ "source": "static", "value": ... }`.
+
+**block** — a UI widget (`core.grid`, `core.button`, `core.kpi-card`,
+`core.lookup`, …). The unit of a page's layout. Never called "widget" in
+platform terminology, but they're the same thing. `erp blocks list`.
+
+**composite (Data Service)** — a Data Service that fans out to several other
+Data Services in one call. Response: `{ "results": { "<step>": <envelope> } }`.
+
+**connected mode** — running the SDK as a package against a deployed ERP with no
+platform source. See [SDK modes](./sdk-modes.md).
+
+**data provider** — a `metadata/provider/*.json` file mapping a `name` to a REST
+`basePath`. A page's `metadata.dataSource` names one.
+
+**data service** — a `metadata/data_service/*.json` file: a parameterized query
+(`count` / `search` / `get` / `composite`). Called at
+`/api/v1/data-services/<name>/execute`.
+
+**data view** — a `metadata/data_view/*.json` file: a declared read-only SQL
+join over physical tables.
+
+**day_offset** — a field on a status-date-sweep config. `0` = compare a date
+against *now*; `N` = compare against *now + N days* (the "N days before"
+reminder). Negative shifts earlier.
+
+**entity** — a table you declare by its fields (`metadata/entities/*.json`). The
+Entity Engine generates the DDL, CRUD REST, grid query, and single-record read.
+
+**entity rule** — a `metadata/rules/*.json` file: declarative logic
+(`REJECT` / `SET_VALUE` / `EXECUTE_SERVICE` / `START_WORKFLOW`) at a lifecycle
+point (`BEFORE_CREATE`, `AFTER_UPDATE`, …).
+
+**`event.new`** — in a `committed` action chain, the value the user just entered
+or picked. **Not** `event.value`. For a `core.lookup`, it's the picked record's
+id.
+
+**`.spk`** — the built plugin package. A zip of `spk-assembly/`.
+
+**flags** — a pre-stringified JSON field on an entity field definition. Holds
+`{ "reference": { "entityType": "Employee" } }` (turns on `_label` resolution)
+or `{ "formula": "<expression>" }` (computed field, no column).
+
+**i18n key** — a dotted string (`office-equipment.equipment-register.title`)
+standing in for user-visible text. Resolved from `metadata/i18n/en.json`.
+
+**idempotent-additive** — the install behaviour for entities and seed data:
+re-installing adds missing columns / upserts rows by key, never drops or
+duplicates.
+
+**KPI card** — `core.kpi-card`, a block that shows one number bound from page
+state.
+
+**mainClass** — the fully-qualified name of a PF4J `Plugin` subclass in
+`spk-assembly/lib/*.jar`. Optional: a pure-JSON plugin leaves it `null` and the
+platform loads it through a built-in generic no-op entry point. Set it only when
+you ship your own Java extensions.
+
+**MCP server** — `erp-plugin-language`, the tool server your AI agent calls for
+schemas, blocks, examples, and validation. `erp mcp install`.
+
+**metadata.dataSource** — the page-level string that wires a `core.grid` to a
+data provider. Page-level, never on the grid block.
+
+**module** — a functional area inside an application (e.g. "Leave Management").
+Owns menu entries. Pages attach to a module via their `modules` array.
+
+**page** — one screen (`metadata/page/*.json`): rows → columns → items (blocks),
+plus page-level `metadata`.
+
+**page state** — the runtime key/value bag a page reads with bindings and writes
+with `setValue`. Keys are whatever you invent (`kpiTotal`, `formDialogOpen`).
+
+**PF4J** — the Java plugin framework the platform uses to load a plugin. A
+pure-JSON plugin is loaded through a built-in generic entry point; you never
+touch PF4J directly.
+
+**register rule** — an unconditional `AFTER_CREATE` `EXECUTE_SERVICE` rule on a
+shared config entity that auto-registers a scheduled job on the first seeded
+config row.
+
+**role code** — the stable identifier for a role (`OFFICE_EQUIPMENT_MANAGER`).
+Workflows and permissions reference roles by code, never by display name.
+
+**schemaName** — the Postgres schema an entity's table routes to, from
+`plugin.json`. The scaffold default is `erp_core`.
+
+**seed data** — `metadata/seed-data/*.json`: rows upserted on install by
+`keyFields`. Used for reference data and for shared job-config rows.
+
+**status-date-sweep** — the generic scheduled job
+(`engine-entity.status-date-sweep`) that flips a record's status when a date
+column crosses now (± `day_offset`). Configured by seeding an
+`entity_status_date_sweep_config` row.
+
+**workflow** — a `metadata/workflow/*.json` file: stages, an approval task, and
+`approvalPermissions`. Started by a `START_WORKFLOW` rule action; the decision is
+written back by a generic callback controller.

package/bundle/docs/concepts/overview.md

@@ -0,0 +1,88 @@
+---
+title: Platform overview
+audience: tenant
+---
+
+# Platform overview
+
+A plugin is a bundle of **JSON metadata** (and optionally a little Java) that the
+platform's generic engines execute. You rarely write CRUD code — you declare
+what you want and an engine does it.
+
+## App → Module → Page
+
+- **Application** — the top-level product surface a user opens (e.g. "HCM").
+- **Module** — a functional area inside an app (e.g. "Leave Management"). A
+  module owns menu entries.
+- **Page** — one screen. A `metadata/page/*.json` file: rows of **blocks**
+  (widgets), plus page-level `metadata` (including `dataSource` — the single
+  field that wires a grid to its data; it is *page*-level, never grid-level).
+
+## Entities
+
+An **entity** (`metadata/entities/*.json`, Entity Engine) is a table you declare
+by its fields and relationships. The platform generates the DDL, the CRUD REST
+endpoints, grid queries, and single-record reads — zero hand-written persistence
+code. Mark a foreign-key field with `flags.reference.entityType` and reads
+automatically gain a resolved `<field>_label` sibling (id → display name).
+
+## Data providers, data views, data services
+
+- **Data Provider** (`metadata/provider/*.json`) — names a REST base path a grid
+  or lookup reads from. A page's `metadata.dataSource` must match a provider's
+  `name` exactly.
+- **Data View** (`metadata/data_view/*.json`) — a declared multi-table SQL join
+  over physical tables, read-only.
+- **Data Service** (`metadata/data_service/*.json`) — a parameterized query
+  (filters, `search` params, composite steps) that a `core.lookup` or a report
+  calls server-side.
+
+Prefer a Data View / Data Service over a bespoke REST endpoint for reads.
+
+## Workflows
+
+A **workflow** (`metadata/workflow/*.json`, Workflow Engine) is a multi-stage
+approval process: `stagesJson`, `tasksJson`, `transitionsJson` (each a
+JSON-encoded string) and a top-level `approvalPermissions` array that references
+roles by stable `role.code`. Every approval-bearing state transition should be a
+real workflow instance, not a permission-gated direct action.
+
+## Rules
+
+An **entity rule** (`metadata/rules/*.json`, Rule Engine) fires declarative
+conditions/actions at lifecycle points (`BEFORE_CREATE`, `AFTER_UPDATE`, …) —
+computed fields, cross-field validation, "on first row, register this job".
+
+## Themes
+
+Theming cascades: platform → application → **user**. A plugin ships theme tokens;
+it never hardcodes colors in page JSON.
+
+## Scheduled jobs
+
+You almost never write a job class. The platform ships generic, JSON-configured
+sweep engines:
+
+- **status-date-sweep** — flip a field when a date column crosses now (± an
+  offset for "N days before" reminders).
+- **aggregation-sweep** — roll up count/sum/avg/min/max into a summary entity.
+- **cadence-generator** — create records on a schedule.
+- **compliance-sweep** — evaluate a boolean expression per row and flag/escalate.
+
+Each is one config row. See `erp examples patterns --kind jobs`.
+
+## Install seeding
+
+To make config rows (job configs, reference data) travel with the `.spk`
+instead of a manual per-tenant POST, add `metadata/seed-data/*.json`:
+`{ entity, keyFields, source, rows }`. The installer upserts them idempotently
+on every install/upgrade. Schema: `erp schema pull plugin-seed-data`.
+
+## Go deeper
+
+- [What are the artifact types?](./artifact-types.md) — the full folder map
+- [How does a plugin get installed?](./plugin-lifecycle.md) — build → upload → pipeline
+- [How do the SDK modes work?](./sdk-modes.md) — monorepo vs connected
+- [How does a page get its data?](./page-data-flow.md) — the three data paths
+- [Glossary](./glossary.md)
+- [The tutorial](../tutorial/index.md) builds all of this into one working module.

package/bundle/docs/concepts/page-data-flow.md

@@ -0,0 +1,84 @@
+---
+title: How does a page get its data?
+audience: tenant
+---
+
+# How does a page get its data?
+
+There are exactly three ways data reaches a page. Knowing which is which stops
+the "0 rows, no error" confusion.
+
+## 1. The grid — via `metadata.dataSource`
+
+A `core.grid` block has **no** data configuration on it. It renders whatever the
+page's top-level `metadata.dataSource` resolves to:
+
+```
+page.metadata.dataSource  ──▶  a metadata/provider/*.json whose `name` matches
+                          ──▶  that provider's basePath (e.g. /api/v1/entities/oeq_equipment/records)
+                          ──▶  the Entity Engine serves rows at basePath + /query
+```
+
+The grid's `externalFilter` binding supplies query filters; `refreshTrigger`
+re-runs the query. This is the *only* mechanism for `core.grid`. See
+[Wire a page's data](../guides/wire-a-pages-data.md).
+
+## 2. Page state — via action chains
+
+Everything that isn't the grid — KPI numbers, a detail panel, a form's current
+values, dialog open/closed flags — lives in **page state**, a bag of key/value
+pairs. You:
+
+- **write** it with `setValue` actions: `setValue page.kpiTotal = ${kpi.results.total.value}`
+- **read** it with bindings: `{ "source": "binding", "binding": { "scope": "page", "key": "kpiTotal" } }`
+
+An **action chain** is an ordered list of actions on a block event
+(`mounted`, `clicked`, `committed`, `rowClicked`). The typical loader chain:
+
+```
+mounted:
+  callApi  POST /api/v1/data-services/oeq-equipment-kpis/execute   → output "kpi"
+  setValue page.kpiTotal = ${kpi.results.total.value}
+  setValue page.kpiAvailable = ${kpi.results.available.value}
+```
+
+`${kpi....}` references the `output` name of an earlier `callApi` in the same
+chain. `${event.new}` (in a `committed` handler) is the value the user entered.
+`${event.id}` (in `rowClicked`) is the clicked row's id.
+
+## 3. A lookup field — via `optionsSourceKey`
+
+A `core.lookup` block calls a **`search` Data Service** named by its
+`optionsSourceKey`, passing the user's keystrokes as the `search` parameter, and
+expects back `{ value, label }` rows. Its `committed` event fires with
+`event.new` = the picked record's id. See
+[the lookup recipe](../recipes/related-record-lookup-field.md).
+
+## Data Service response shapes (the part everyone gets wrong once)
+
+| `operation` | `/execute` returns | bind |
+| --- | --- | --- |
+| `count` | `{ "value": 12 }` | `${out.value}` |
+| `search` / `get` | `{ "items": [...] }` (or `{ "records": [...] }` for a dataView source) | `${out.items}` |
+| `composite` | `{ "results": { "total": { "value": 12 }, ... } }` | `${out.results.total.value}` |
+
+A parameterized Data Service is called with args nested **one level deeper**:
+`{ "params": { "parameters": { "search": "lap" } } }`.
+
+## Putting it together — the tutorial's Equipment Register page
+
+```
+mount loader block  → callApi oeq-equipment-kpis → setValue page.kpiTotal / kpiAvailable / kpiAssigned
+KPI cards           → bind page.kpiTotal / ...
+search + status inputs → committed → setValue page.gridExternalFilter.search / .status
+grid                → page.metadata.dataSource = "oeq-equipment-provider"; externalFilter = page.gridExternalFilter
+"New" button        → setValue page.form* = null/defaults; setValue page.formDialogOpen = true
+dialog inputs       → committed → setValue page.form<Field> = ${event.new}
+"Save" button       → callApi POST /records; setValue page.formDialogOpen=false; setValue page.gridRefreshTick=${!page.gridRefreshTick}
+```
+
+## What to read next
+
+- [Wire a page's data](../guides/wire-a-pages-data.md)
+- [Add a create / edit form](../guides/add-a-create-edit-form.md)
+- [Add a KPI or aggregation](../guides/add-a-kpi.md)

package/bundle/docs/concepts/plugin-lifecycle.md

@@ -0,0 +1,81 @@
+---
+title: How does a plugin get installed?
+audience: tenant
+---
+
+# How does a plugin get installed?
+
+A mental model of what happens between `erp plugin publish` and your page being
+live. Knowing this makes install errors readable.
+
+## Build
+
+`erp plugin build spk-assembly -o x.spk` zips `spk-assembly/` into a `.spk`
+file. Nothing clever — it's a zip with `plugin.json` at the root, `metadata/`,
+and `lib/`. It runs `erp plugin validate` first and refuses to package invalid
+pages.
+
+## Upload
+
+`erp plugin publish x.spk --tenant N` POSTs the file to
+`/api/v1/authoring/plugins/upload` with your `erp login` token. The server:
+
+1. **recomputes the checksum** and compares — it never trusts the client digest.
+2. **stores the artifact** at `system/plugins/<id>/<version>/<id>-<version>.spk`.
+   This key is **immutable** — re-storing different bytes under the same version
+   is refused.
+3. **reads the manifest** — `id` and `version` must be present and non-blank.
+   `mainClass` is optional: a pure-JSON plugin leaves it `null` and the platform
+   loads it via a built-in generic no-op entry point.
+
+## Install pipeline (`PluginInstallPipeline.installNew`)
+
+In order, all-or-nothing:
+
+| Stage | What it does | Common failure |
+| --- | --- | --- |
+| **VALIDATING** | schema + block-registry validation; artifact persistence | immutable-artifact conflict; a page block property that doesn't exist |
+| **LOADING** | PF4J loads `lib/*.jar` (or the built-in entry point for a pure-JSON plugin), calls the plugin's `start()` | a declared `mainClass` not found in the jar; **another version of the same plugin id already loaded** |
+| entities | create / `ALTER TABLE ADD COLUMN` (idempotent-additive — never drops) | `label` not valid JSON; `required` without `nullable` |
+| providers / views / services / pages / menus | upsert each artifact | route/module mismatch |
+| rules / workflows | install | `stagesJson` authored as an object not a string |
+| i18n / roles | install | **role `name` or `code` collides with another installed plugin** |
+| seed data | `PluginDataSeedInstaller` upserts each `metadata/seed-data/*.json` by `keyFields` | entity not shipped; non-unique key |
+| register rules fire | `AFTER_CREATE` rules on config entities call `ensure<Job>Registered` → your scheduled jobs get an `erp_job` row | (seed no config row → job never registers) |
+
+If any stage throws, **everything rolls back**, including the PF4J load. The
+error names the stage:
+
+```
+plugin install failed at stage LOADING: ...
+plugin install failed after code load, rolled back PF4J load: Role "..." already exists
+```
+
+## Upgrade
+
+Publishing a higher version while the plugin is installed is an **upgrade**. The
+platform's convergence loop unloads the old PF4J code, loads the new, and re-runs
+the artifact/seed stages (all upserts, nothing dropped).
+
+## Uninstall (and why not to, mid-development)
+
+`DELETE /api/v1/authoring/plugins/<id>` marks the installation removed. The
+**code** is unloaded asynchronously by a background convergence loop, not
+immediately. If that unload stalls (it can, on a transient DB error), the old
+PF4J code stays loaded, and the next `publish` — which uses the *install-new*
+path — is refused with "already loaded plugin ... same id". Recovery is a backend
+restart or a new plugin id.
+
+**Practical rule: to iterate, bump the version and re-publish. Don't uninstall.**
+
+## Verify an install
+
+```bash
+erp plugin list          # your plugin: state "installed", pf4jState "STARTED"
+erp api get "/api/v1/authoring/pages?module=<yourModule>"   # pages registered
+```
+
+## What to read next
+
+- [Publish and upgrade a plugin](../guides/publish-and-upgrade.md)
+- [Troubleshooting: publishing and install errors](../troubleshooting/publishing-errors.md)

package/bundle/docs/concepts/sdk-modes.md

@@ -0,0 +1,71 @@
+---
+title: How do the SDK modes work (monorepo vs connected)?
+audience: tenant
+---
+
+# How do the SDK modes work (monorepo vs connected)?
+
+The `erp` CLI and the `erp-plugin-language` MCP server both need **grounding
+data** — the JSON Schemas, the catalog of platform capabilities, the block
+registry, curated examples, these docs. Where that data comes from depends on how
+the SDK is installed.
+
+## The authoring bundle
+
+The grounding data is packaged as an **authoring bundle**: a folder of
+`schemas/`, a frozen `catalog.json`, `blocks.json`, `validators/`, `examples/`,
+and the tenant-public docs. It is produced by `erp bundle build`, which is the
+**only** step that reads platform source (it scans the Java for REST mappings and
+runs esbuild on the validators). Clients never do that scan.
+
+## Mode 1 — monorepo (platform developers)
+
+You're working inside the ERP source tree. `erp bundle build` runs locally
+against the live source; `erp` and the MCP server read the freshly built bundle.
+Everything is always current. This is how these docs were written and how the
+tutorial module was verified.
+
+## Mode 2 — connected (you, a third-party developer)
+
+You have the SDK as a package, and **no platform source**. Two data sources, in
+priority order:
+
+1. **`erp env sync`** downloads your ERP's own authoring bundle from
+   `{baseUrl}/api/v1/dev/bundle` into `~/.erp/cache/<env>/`. This is bundle data
+   generated *by your ERP*, so it matches exactly the version you're building
+   against — including the live list of entity and theme names in your tenant.
+   Re-run it after every ERP upgrade.
+2. **the bundle shipped inside the SDK package** — a fallback used when your ERP
+   doesn't expose `/api/v1/dev/bundle` yet. It's a snapshot; it may lag your
+   ERP's actual version.
+
+`erp env sync --check` tells you whether your cached bundle has drifted from what
+the server would send.
+
+## What each mode can and can't do offline
+
+| Capability | monorepo | connected + synced | connected, offline fallback |
+| --- | --- | --- | --- |
+| pull schemas, list blocks, list examples | yes | yes | yes (may lag) |
+| validate a page / lint semantics | yes | yes | yes |
+| `erp api ...` against the live ERP | yes | yes | no (needs the server) |
+| `erp logs tail` for a failed call's stack trace | yes | yes | no — use the ERP admin log view |
+| know your tenant's real entity / theme names | yes | yes (from the sync) | no |
+| publish a plugin | yes | yes | no |
+
+## No Java toolchain required
+
+A pure-JSON plugin (the default shape) needs **no JDK, no pf4j jars, no compiled
+stub**. Leave `plugin.json`'s `mainClass` `null` and the platform loads the
+plugin through a built-in generic entry point. You only reach for a Java
+toolchain if a plugin ships its own `Plugin` subclass for behaviour the engines
+can't express — see [Create a plugin](../guides/create-a-plugin.md), and for a
+complete, real Java-plus-React example, [Build a plugin with custom React +
+Java code](../guides/build-a-code-plugin.md). A custom React component on its
+own, reading data through the generic query engine with no Java at all, is
+[Add a custom block](../guides/add-a-custom-block.md) instead.
+
+## What to read next
+
+- [Set up the SDK](../guides/set-up-the-sdk.md)
+- [Use the MCP server with an AI agent](../guides/use-the-mcp-server.md)