@sparkerp/plugin-sdk 0.1.0

package/bundle/docs/guides/build-a-tenant-extension-service.md

@@ -0,0 +1,149 @@
+---
+title: Build a tenant extension service (L5)
+audience: tenant
+---
+
+# Build a tenant extension service (L5)
+
+## What you're doing
+
+Every guide before this one builds something that runs **inside** the shared
+ERP — a plugin's Java code loads into the same JVM as every other tenant's.
+An L5 extension is different: it is **your own separate process**, running
+in your own container, that the ERP core calls over plain HTTP whenever your
+tenant has one installed and enabled for a given extension point. The core
+never loads your code, never shares your JVM, and keeps working exactly as
+before if your service is down, slow, or was never installed at all.
+
+Use this when a plugin isn't enough — you need to run code the platform
+can't vet and load in-process (a proprietary calculation, a call to your own
+internal systems, dependencies that would never be approved into the shared
+runtime).
+
+| Artifact | What it is | Where it runs |
+| --- | --- | --- |
+| A regular plugin (every other guide) | Java/TS code, installed into the shared ERP | In-process, shared JVM |
+| An **L5 extension service** (this guide) | Your own Spring Boot app | Your own process/container |
+
+## The complete example
+
+Copy the real, runnable skeleton at
+[`extensions/archetype/`](../../extensions/archetype) — don't hand-write one.
+The fastest way:
+
+```bash
+erp extension create-service acme-payroll
+cd extensions/acme-payroll-extension-service
+mvn spring-boot:run
+```
+
+This scaffolds a small Spring Boot app with exactly one endpoint:
+
+```java
+@RestController
+@RequestMapping("/extension-api")
+public class ExtensionApiController {
+
+    @PostMapping("/{extensionPointCode}")
+    public ResponseEntity<Map<String, Object>> invoke(
+            @PathVariable String extensionPointCode,
+            @RequestHeader(value = "Authorization", required = false) String authorization,
+            @RequestBody(required = false) Map<String, Object> request) {
+        if (!serviceAuthTokenVerifier.verify(authorization)) {
+            return ResponseEntity.status(HttpStatus.UNAUTHORIZED).body(Map.of("error", "invalid token"));
+        }
+        // request is a FLAT map: your payload fields + tenantId/applicationId/
+        // extensionId/actor/correlationId merged in — see the file's own doc comment.
+        Map<String, Object> response = new LinkedHashMap<>();
+        // ... your logic here, keyed on extensionPointCode ...
+        return ResponseEntity.ok(response); // fields to merge into the caller's record
+    }
+}
+```
+
+## The wire contract, exactly
+
+The ERP core's `ExtensionRouter` calls your service like this — match it
+exactly, there is no other shape:
+
+- **Request**: `POST {your-endpoint}/extension-api/{extensionPointCode}` — a
+  FLAT JSON body (your business fields, plus `tenantId`/`applicationId`/
+  `extensionId`/`actor`/`correlationId` always present and always trustworthy
+  — never read a tenant id from anywhere else). Headers carry
+  `Authorization: Bearer <token>` (see Security below), `X-Tenant-Id`,
+  `X-Correlation-Id`.
+- **Response**: any 2xx with a FLAT JSON body = "extended" — return only the
+  field(s) you want merged into the record. `{}` is a valid, successful
+  "no changes" response.
+- **Timeout**: 2 seconds. The core wraps every call in a circuit breaker —
+  a slow or broken service degrades to "not extended," it never breaks the
+  tenant's request.
+- Today the ERP fires exactly ONE extension point:
+  `EntityRecordBeforeCreate` — before a new Entity Engine record is
+  inserted, for ANY tenant-designed entity in ANY application.
+
+## Security
+
+Every call from the core carries a short-lived (30s) HMAC-SHA256 signed
+bearer token. Set the SAME secret on both sides:
+
+```bash
+# ERP core (env on the erp-suite/engine-api process)
+ERP_EXTENSION_SERVICE_AUTH_SECRET=<your real shared secret>
+
+# your extension service
+ERP_EXTENSION_SERVICE_AUTH_SECRET=<the SAME shared secret>
+```
+
+Never ship the `dev-only-...` default to production. This is a shared
+secret, not certificate-based mTLS — see the archetype's own README
+"Security model" section for exactly what's real vs. deliberately deferred.
+
+## Ground yourself first
+
+```bash
+erp extension create-service --help
+erp platform describe RemoteExtensionPoint
+```
+
+## Register and enable it
+
+Your service does nothing until it's installed AND enabled for a tenant —
+until then, the core never calls it at all.
+
+```bash
+erp tenant plugin install <tenantId> acme-payroll --runtime service \
+  --endpoint https://<your-service-host>:8480 --application HCM
+erp tenant plugin enable  <tenantId> acme-payroll --application HCM
+```
+
+## How to verify it worked
+
+```bash
+curl -s -X POST localhost:8480/extension-api/EntityRecordBeforeCreate \
+  -H 'content-type: application/json' \
+  -H 'authorization: Bearer <token minted with your shared secret>' \
+  -d '{"tenantId":42,"applicationId":"HCM","extensionId":"EntityRecordBeforeCreate","actor":"system","correlationId":"demo","employeeId":100234}'
+```
+
+```json
+{}
+```
+
+Then create a record in that tenant's app that goes through the Entity
+Engine's create path — your service's logs should show the call arriving.
+
+## Common mistakes
+
+| Symptom | Cause | Fix |
+| --- | --- | --- |
+| Service never gets called | Binding not `ENABLED`, or you're on the wrong `applicationId` | `erp tenant plugin list <tenantId>` to check status |
+| `401` on every call | Shared secret mismatch | Set the exact same `ERP_EXTENSION_SERVICE_AUTH_SECRET` on both sides |
+| Core logs "security violation" | Your response's `tenantId` field doesn't match the request | Don't echo `tenantId` back at all unless it's unchanged |
+| Change never takes effect for up to ~45s | Binding resolution is cached | Expected — bounded staleness, not a bug |
+| Deployed extension can't reach anything else in the cluster | `NetworkPolicy` default-denies egress | Correct by design — add one narrow rule if you truly need an external call |
+
+## What to read next
+
+- [`extensions/archetype/README.md`](../../extensions/archetype/README.md) — full security model, Docker/Kubernetes deployment
+- [Publish and upgrade a plugin](./publish-and-upgrade.md) — for the regular (in-process) plugin path this guide is the alternative to

package/bundle/docs/guides/create-a-plugin.md

@@ -0,0 +1,172 @@
+---
+title: Create a plugin from scratch
+audience: tenant
+---
+
+# Create a plugin from scratch
+
+## What you're doing
+
+A **plugin** is a folder of JSON metadata that the ERP's generic engines
+execute — no Java required. You declare what you want — a
+table here, a screen there, an approval there — and the platform does the rest.
+This guide gets you an empty, valid, buildable plugin.
+
+## The complete sequence
+
+```bash
+erp plugin create office-equipment --name "Office Equipment" --type business-app
+erp menu create office-equipment office-equipment-menu \
+  --display-name "Equipment" --route /office-equipment/equipment-register
+```
+
+That produces:
+
+```
+office-equipment/
+├── README.md
+└── spk-assembly/
+    ├── plugin.json                 <- the manifest
+    └── metadata/
+        ├── entities/               <- one *.json per table
+        ├── page/                   <- one *.json per screen
+        ├── provider/               <- REST data providers for grids
+        ├── data_service/           <- parameterized read queries
+        ├── data_view/              <- SQL joins over physical tables
+        ├── rules/                  <- lifecycle rules
+        ├── workflow/               <- approval processes
+        ├── seed-data/              <- rows to upsert on install
+        ├── menu/                   <- navigation
+        └── i18n/                   <- en.json etc.
+```
+
+`spk-assembly/` is the build root. The `.spk` file `erp plugin build` produces
+is just a zip of this tree.
+
+## The manifest (`spk-assembly/plugin.json`)
+
+Here is a complete, real manifest — the one the [tutorial module](../tutorial/example-plugin/spk-assembly/plugin.json) ships:
+
+```json
+{
+  "id": "office-equipment",
+  "name": "Office Equipment",
+  "version": "1.0.3",
+  "type": "business-application",
+  "schemaName": "erp_core",
+  "vendor": "ACME Corp",
+  "license": "Proprietary",
+  "licenseTier": "free",
+  "category": "custom",
+  "erpVersion": "*",
+  "minErpVersion": "1.0",
+  "maxErpVersion": "99.0",
+  "mainClass": null,
+  "dependencies": [],
+  "optionalDependencies": [],
+  "owner": "business",
+  "editable": false,
+  "extendable": true,
+  "capabilitiesProvided": [],
+  "capabilitiesRequired": [],
+  "featureFlags": [],
+  "configSchemaJson": null,
+  "roles": [
+    {
+      "name": "Office Equipment Manager",
+      "code": "OFFICE_EQUIPMENT_MANAGER",
+      "description": "Full control of the Office Equipment module.",
+      "permissionKeys": [
+        "OeqEquipment.View", "OeqEquipment.Create", "OeqEquipment.Edit",
+        "OeqCheckout.View", "OeqCheckout.Create", "OeqCheckout.Submit", "OeqCheckout.Approve"
+      ]
+    }
+  ],
+  "runtimeModes": ["embedded"],
+  "serviceDeployment": null
+}
+```
+
+### Line by line
+
+- **`id`** — globally unique, lowercase kebab-case. It's baked into every route,
+  i18n key, and page id. **Choose it once.** Renaming later means rewriting every
+  file. (It is also the PF4J plugin id, and the platform cannot load two plugins
+  with the same id even across versions — see
+  [Publish and upgrade](./publish-and-upgrade.md).)
+- **`version`** — semver. **Bump it before every publish** or the publish is a
+  silent no-op (see [known gotchas](../troubleshooting/known-gotchas.md)).
+- **`type`** — `business-application` for a normal feature plugin.
+- **`schemaName`** — the Postgres schema your entity tables route to. The
+  scaffold default is `erp_core`. See the caveat below.
+- **`mainClass`** — leave it `null` (as the scaffold writes it) for a pure-JSON
+  plugin. Only set it if you ship your own Java extensions. See "Java: only if
+  you need it" below.
+- **`roles`** — the roles this plugin creates on install. `code` is stable and
+  referenced by workflows; `name` must be unique across all installed plugins.
+- **`dependencies`** — plugin ids that must already be installed. Leave `[]` for
+  a standalone plugin.
+- **`runtimeModes: ["embedded"]`** — the plugin runs inside the ERP process. The
+  alternative, `"service"`, is for plugins deployed as their own container and is
+  out of scope here.
+
+## Java: only if you need it
+
+A pure-JSON plugin ships **no Java at all**. Leave `"mainClass": null` and omit
+`spk-assembly/lib/`. On install the platform loads it through a built-in generic
+no-op PF4J entry point; start/stop/enable/disable/upgrade, migrations and data
+seeding all run exactly as for a plugin with its own `mainClass`. This is the
+default and the recommended shape.
+
+You only add Java when a feature genuinely needs behaviour the Entity / Query /
+Rule / Workflow / Job engines can't express. Then write a `Plugin` subclass,
+compile it against `pf4j` + `slf4j-api`, drop the jar in `spk-assembly/lib/`,
+and set `mainClass` to its fully-qualified name — `erp plugin build` zips
+whatever is in `lib/` into the `.spk`.
+
+## The `schemaName` caveat
+
+Entity tables get created in the schema named by `plugin.json`'s `schemaName`.
+The scaffold default `erp_core` works for CRUD and for the pages in this guide,
+**but** some generic write paths (notably the status-date-sweep job) assume a
+tenant-scoped table and can fail against a table that isn't laid out the way an
+app-schema table is. If your plugin owns entities and uses scheduled jobs,
+prefer a dedicated schema name and confirm your entities behave against it with
+`erp plugin test` and a live sweep before you rely on it. The tutorial uses
+`erp_core` and documents where this bites.
+
+## How to verify it worked
+
+```bash
+erp plugin validate office-equipment/spk-assembly
+erp plugin test office-equipment/spk-assembly
+```
+
+A fresh scaffold with no pages yet prints:
+
+```
+no page JSON found under .../metadata/page — nothing to validate
+```
+
+```
+Plugin Tests
+────────────────────────────────────────
+✓ plugin.json:valid-json
+1 passed, 0 failed, 0 semantic warning(s), 3 skipped
+```
+
+That's a healthy empty plugin. Now add an [entity](./add-an-entity.md).
+
+## Common mistakes
+
+| Symptom | Cause | Fix |
+| --- | --- | --- |
+| `erp menu create` route becomes `C:/Program Files/Git/...` | Git Bash rewrites the leading `/` | run it from PowerShell, or `MSYS_NO_PATHCONV=1` |
+| you renamed `id` after building pages | id is in every page/i18n/menu key | pick the id once; if you must rename, sed the whole tree |
+| publish rejected: role name already exists | another installed plugin has a role with the same `name` | make your role `name` distinctive |
+
+## What to read next
+
+- [Add an entity](./add-an-entity.md)
+- [Build a page](./build-a-page.md)
+- [Validate and test a plugin](./validate-and-test.md)

package/bundle/docs/guides/expose-a-plugin-operation-as-an-ai-tool.md

@@ -0,0 +1,114 @@
+---
+title: Expose a plugin operation as an AI tool
+audience: tenant
+---
+
+# Expose a plugin operation as an AI tool
+
+## What you're doing
+
+This is different from [Use the MCP server with an AI agent](./use-the-mcp-server.md)
+— that guide is about *your coding agent* (Claude Code, Cursor) getting
+grounded while it writes your plugin. **This guide is about the ERP
+product's own embedded AI assistant** calling *your plugin's* real
+operations for an end user, at runtime, once your plugin is installed.
+
+Declare which of your plugin's REST endpoints are safe for the AI to call,
+under what permission, with what risk level. The platform reads this at
+install time and registers real, callable tools — no separate admin step,
+no retraining, no hand-written tool-registry entry.
+
+| | Your plugin's REST APIs | Your declared AI tools |
+| --- | --- | --- |
+| Who calls it | Any authorized caller | The platform's AI assistant, on a user's behalf |
+| Default | Every endpoint you write | **None** — opt-in only |
+| Where it's declared | Your controller code | `metadata/tool/*.json` files |
+
+**Never expose every endpoint automatically.** An internal cache-clear
+endpoint or an admin-only bulk-delete has no business being AI-callable just
+because it exists — only declare the operations you've deliberately decided
+are safe for an AI to invoke on a user's behalf.
+
+## The file
+
+One JSON file per tool, under your plugin's `metadata/tool/` directory —
+same convention as `metadata/page/`, `metadata/form/`, `metadata/provider/`.
+Real, shipped example — `hello-plugin`'s own
+`metadata/tool/hello.greeting.get.json`:
+
+```json
+{
+  "toolCode": "hello.greeting.get",
+  "name": "Get Hello Greeting",
+  "description": "Returns hello-plugin's demo greeting for the current tenant.",
+  "inputSchema": { "type": "object", "properties": {} },
+  "handlerType": "REST",
+  "handlerConfig": {
+    "path": "/api/v1/plugins/hello-plugin/greeting",
+    "method": "GET"
+  },
+  "requiredPermission": "HELLO_PLUGIN_DEMO",
+  "applicationCode": "hello-plugin",
+  "riskLevel": "LOW",
+  "strictPermissionCheck": false
+}
+```
+
+`handlerConfig` also accepts `pathParams`/`queryParams` (input keys
+substituted into the path/query string) and `bodyFromInput: true` (the whole
+input map sent as a POST body) — see `hcm-ai-intelligence`'s own 18 tool
+files for real examples of each, including a real **cross-plugin** one
+(`employee.search` calling `hcm-employee`'s own endpoint, not
+`hcm-ai-intelligence`'s own namespace — a deliberately supported pattern for
+an AI-assistant module that fronts several other plugins).
+
+## The namespace rule
+
+`handlerConfig.path` **must** be under `/api/v1/plugins/**` (any plugin's own
+namespace) or `/api/v1/entities/**` (the Entity Engine data API). A tool
+pointed at an internal/admin/authoring route is rejected at install — before
+your plugin touches anything else.
+
+## Ownership
+
+Re-installing/upgrading your own plugin re-registers your own tools
+idempotently. Declaring a `toolCode` another plugin already owns — or one
+that was created manually outside any plugin — fails install with a clear
+error; tool codes aren't a shared free-for-all namespace.
+
+Disabling or uninstalling your plugin deactivates its tools (not a hard
+delete) — re-enabling reactivates them.
+
+## Ground yourself first
+
+```bash
+erp_get_schema {"name":"plugin-manifest"}
+```
+
+Look at `hcm-ai-intelligence`'s real `metadata/tool/*.json` files for the
+fullest working example of `pathParams`/`queryParams`/`bodyFromInput` in
+practice, and for `riskLevel: "HIGH"` + `strictPermissionCheck: true` pairing
+on a genuinely mutating operation.
+
+## How to verify it worked
+
+Install your plugin, then check the discovery endpoint lists your tool:
+
+```bash
+curl localhost:8080/api/v1/agents/metadata/tools \
+  -H "X-Tenant-Id: <id>" -H "X-Actor: <actor>" | grep your.tool.code
+```
+
+## Common mistakes
+
+| Symptom | Cause | Fix |
+| --- | --- | --- |
+| Install fails: "not under an allowed namespace" | `handlerConfig.path` points outside `/api/v1/plugins/**` or `/api/v1/entities/**` | An AI tool can only call a real plugin business endpoint or the Entity Engine, never an internal/admin route |
+| Install fails: tool already exists | `toolCode` collides with a manually-created tool or another plugin's tool | Pick a more specific, namespaced `toolCode` (e.g. `<your-plugin>.<noun>.<verb>`) |
+| Tool still callable after uninstall | You're checking a cached list | Tools are deactivated, not deleted — re-query the discovery endpoint |
+| AI never calls your tool | `requiredPermission` the calling user lacks, or `riskLevel`/policy gating it out | Check the user's actual permission grant first |
+
+## What to read next
+
+- [Use the MCP server with an AI agent](./use-the-mcp-server.md) — the *other* MCP concept: grounding your coding agent while you build, not this guide's runtime AI-tool-calling
+- [Create a plugin from scratch](./create-a-plugin.md)

package/bundle/docs/guides/index.md

@@ -0,0 +1,53 @@
+---
+title: Guides
+audience: tenant
+---
+
+# Guides
+
+Task-focused how-tos. Each page answers one question and follows the same rhythm:
+what you're building → a complete, real, copy-pasteable example → a line-by-line
+walkthrough → how to verify it worked → common mistakes → what to read next.
+Every code sample is a real file under
+[`tutorial/example-plugin/`](../tutorial/index.md) or
+[`examples/`](../examples/), kept honest by
+`node developer-docs/examples/test-examples.mjs`.
+
+## Getting started
+
+- [Set up the SDK and connect to an environment](./set-up-the-sdk.md)
+- [Create a plugin from scratch](./create-a-plugin.md)
+- [Use the MCP server with an AI agent](./use-the-mcp-server.md)
+
+## Data
+
+- [Add an entity](./add-an-entity.md)
+- [Add a data provider, data view, or data service](./add-a-data-provider.md)
+- [Seed config and reference data on install](./seed-data-on-install.md)
+
+## Screens
+
+- [Build a page](./build-a-page.md)
+- [Wire a page's data](./wire-a-pages-data.md)
+- [Add a create / edit form](./add-a-create-edit-form.md)
+- [Add a KPI or aggregation](./add-a-kpi.md)
+- [Add menus](./add-menus.md)
+- [Add translations (i18n)](./add-i18n.md)
+- [Make a plugin work on desktop, tablet, and mobile](./responsive-plugin.md)
+
+## Logic
+
+- [Add business rules and expressions](./add-business-rules.md)
+- [Add an approval workflow](./add-an-approval-workflow.md)
+
+## Scheduled jobs (no Java)
+
+- [Add a scheduled reminder job](./add-a-reminder-job.md)
+- [Add a cross-row aggregation job](./add-an-aggregation-job.md)
+- [Add a cadence-generator job](./add-a-cadence-job.md)
+- [Add a compliance-sweep job](./add-a-compliance-job.md)
+
+## Ship it
+
+- [Validate and test a plugin](./validate-and-test.md)
+- [Publish and upgrade a plugin](./publish-and-upgrade.md)

package/bundle/docs/guides/publish-and-upgrade.md

@@ -0,0 +1,152 @@
+---
+title: Publish and upgrade a plugin
+audience: tenant
+---
+
+# Publish and upgrade a plugin
+
+## What you're doing
+
+Getting the `.spk` onto your ERP and, later, shipping a new version.
+
+## The complete sequence
+
+```bash
+# 1. build the .spk (a zip of spk-assembly/)
+erp plugin build spk-assembly -o office-equipment-1.0.0.spk
+
+# 2. publish it to the current env, for a tenant
+erp plugin publish office-equipment-1.0.0.spk --tenant 2
+```
+
+Output on success:
+
+```
+packaged 33 files -> office-equipment-1.0.0.spk (231986 bytes)
+sha256: cef54cdf...
+erp plugin publish: office-equipment-1.0.0.spk -> https://erp.example.com (env "dev", tenant 2)
+POST .../api/v1/authoring/plugins/upload ...
+installed:
+{"pluginId":"office-equipment","version":"1.0.0","state":"installed","pf4jState":"STARTED", ...}
+```
+
+`"state":"installed"` and `"pf4jState":"STARTED"` mean it's live. The server
+recomputes the checksum itself — it never trusts the client digest.
+
+## What happens on install
+
+1. checksum verified server-side;
+2. the manifest is read (`id` and `version` are required; `mainClass` is
+   optional — a pure-JSON plugin leaves it `null`);
+3. PF4J loads the plugin — `lib/*.jar` if present, otherwise a built-in generic
+   no-op entry point for a pure-JSON plugin;
+4. entities are created / altered (idempotent-additive);
+5. providers, data views, data services, pages, menus, rules, workflows,
+   i18n and roles are installed;
+6. seed data is upserted;
+7. `AFTER_CREATE` register rules fire → scheduled jobs register.
+
+If any step fails the whole install rolls back, including the PF4J load.
+
+## Version discipline — the rules that will bite you
+
+### 1. Bump the version before every publish
+
+`plugin.json` `version` must increase. **A re-publish of a version that's
+already installed is a silent no-op** — your fix does not ship. Bump it even if
+you're certain the last publish already contained the change.
+
+### 2. A version is immutable once stored
+
+Once the server has stored `office-equipment/1.0.0/office-equipment-1.0.0.spk`,
+re-uploading **different bytes** under `1.0.0` is rejected:
+
+```
+Refusing to overwrite immutable artifact at "system/plugins/.../1.0.0/..." with different content
+```
+
+A version that genuinely **shipped** (reached `pf4jState: STARTED` on some
+tenant) stays immutable forever — re-publishing different bytes under it is
+rejected, go to the next version.
+
+**But a *failed or partial* install is not a real release.** As of the SDK
+publish-hardening pass, if a `1.0.0` publish never reached `STARTED` (it failed
+later in the pipeline, or it's a metadata-only plugin that isn't PF4J-loaded),
+re-publishing `1.0.0` **replaces** the stored `.spk` and retries — no version
+bump needed just to fix a broken publish. `erp plugin publish` of an
+already-installed id automatically takes the upgrade path, so this "edit a page,
+re-publish the same version" loop works directly for JSON-only plugins.
+
+### 3. The platform cannot load two versions of the same plugin id at once
+
+```
+There is an already loaded plugin ... with the same id (office-equipment) ...
+Simultaneous loading of plugins with the same PluginId is not currently supported.
+```
+
+The publish/upgrade path now **reliably stops and unloads the currently-loaded
+same-id plugin before loading the new bundle** (stop → unload → GC hint → load →
+start), so a normal in-place re-publish never hits this. If an earlier crash or a
+transient DB error during uninstall left the old code *wedged* — `state:
+uninstalled` in the install row but `pf4jState: STARTED` in the process — recover
+without a backend restart:
+
+```bash
+erp plugin force-unload office-equipment      # clears the stuck PF4J load
+erp plugin publish office-equipment-1.0.1.spk --tenant 2
+```
+
+`erp plugin publish --force` does the force-unload automatically before
+retrying, and `spark publish` / `erp plugin publish` also auto-retry once with a
+force-unload if they see the "already loaded" error.
+
+> These behaviours were all hit while building the tutorial module. Treat
+> version numbers as cheap and monotonic; use `force-unload` rather than a
+> restart when a load gets stuck.
+
+## Roles and names must be unique across installed plugins
+
+A `plugin.json` role whose `name` **or** `code` collides with a role from
+another installed plugin fails the install:
+
+```
+A role named "Equipment Manager" already exists
+Role "..." (code "...") already exists owned by "..."
+```
+
+Prefix your role names and codes with something plugin-specific.
+
+## Upgrading
+
+```bash
+# edit files, bump plugin.json version to 1.0.1, rebuild the lib jar if Java changed
+erp plugin build spk-assembly -o office-equipment-1.0.1.spk
+erp plugin publish office-equipment-1.0.1.spk --tenant 2
+```
+
+Entities gain new columns; pages, rules, seed data are re-installed (upserted).
+Nothing is dropped — a removed field's column stays, a removed seed row stays.
+
+## How to verify it worked
+
+```bash
+erp plugin list
+```
+
+Find your plugin: `"version": "1.0.1"`, `"state": "installed"`,
+`"pf4jState": "STARTED"`. Then hit a page or an entity endpoint to confirm the
+new content is live.
+
+## Common mistakes
+
+| Symptom | Cause | Fix |
+| --- | --- | --- |
+| "fix didn't ship" | didn't bump `version` on a **shipped** version | bump; re-publish. (A *failed* same-version publish now retries in place.) |
+| `Refusing to overwrite immutable artifact` | retrying a version that already reached `STARTED` on some tenant | go to the next version |
+| `already loaded plugin ... same id` | a load wedged after a crash / DB blip | `erp plugin force-unload <id>` then re-publish (or `publish --force`) |
+| role name/code clash | another plugin owns that role | prefix yours |
+
+## What to read next
+
+- [Validate and test a plugin](./validate-and-test.md)
+- Troubleshooting: [publishing and install errors](../troubleshooting/publishing-errors.md)