@sparkerp/plugin-sdk 0.1.0

package/bundle/docs/guides/build-a-code-plugin.md

@@ -0,0 +1,141 @@
+---
+title: Build a plugin with custom React + Java code
+audience: tenant
+---
+
+# Build a plugin with custom React + Java code
+
+## What you're doing
+
+Every other guide in these docs builds a plugin out of JSON: entities, pages,
+data services, workflows. That covers the large majority of real screens. This
+guide is for the remaining case — a screen that needs **real component state,
+hooks, or business logic the block engine can't express**, backed by **real
+server-side logic the Entity / Query / Rule / Workflow / Job engines can't
+express either**.
+
+You'll use two escape hatches together, both real and already shipped:
+
+- **The custom-component escape hatch** (frontend) — a genuinely arbitrary
+  React component, mounted through `@erp/block-engine`'s `registerExternal` +
+  `@erp/block-adapter-mui`'s `registerCustomRenderer`, reading data through
+  `@erp/data`'s hooks or plain `fetch`.
+- **A Java `Plugin` extension** (backend) — a real class implementing one of
+  `engine-plugin-api`'s extension-point interfaces (`RestContribution`,
+  `DashboardWidgetContribution`, and others — see
+  [`erp platform catalog`](./use-the-mcp-server.md)), loaded in-process into
+  the shared ERP via PF4J.
+
+## When to reach for this (and when not to)
+
+Try these first, in order — see `create-a-plugin.md`'s own "Java: only if you
+need it" section:
+
+1. **JSON composition** — entities, pages, data services/views, workflows,
+   rules. No code at all. Covers most screens.
+2. **A scheduled job config row** — no Java, see the
+   [job guides](./index.md#scheduled-jobs-no-java).
+3. **The compile-to-JSON Code Plugin path** — `@erp/ui` + `definePlugin()`,
+   for declarative composition of existing blocks with no runtime hooks/state.
+4. **The custom-component escape hatch alone** (frontend only) — real React,
+   reading data through the generic query engine (`useERPQuery`). No Java —
+   see [Add a custom block](./add-a-custom-block.md) if this is all you need.
+5. **This guide** — real React AND real Java, when the data or logic your
+   component needs isn't something the generic engines can compute at all
+   (a bespoke server-side calculation, a call to a library or resource only
+   your Java code should touch).
+
+## Level 4 (this guide) vs Level 5 (a tenant extension service)
+
+Both let you write real, unrestricted code. They differ in **where it runs**
+and **what it's allowed to touch**:
+
+| | **Level 4 — a Java plugin (this guide)** | **Level 5 — a [tenant extension service](./build-a-tenant-extension-service.md)** |
+| --- | --- | --- |
+| Where your code runs | In-process, loaded via PF4J into the SAME JVM as the ERP core and every other plugin | Your own separate process/container, called over plain HTTP |
+| `scope` | `global` — an ERP-vendor/marketplace-style plugin, installed once, available to any tenant that installs it | `tenant` — isolated to the one tenant that owns it |
+| What it can do | Contribute a real extension point (`RestContribution`, `DashboardWidgetContribution`, `ScheduledJobContribution`, ...) — genuinely part of the platform's own request handling | Respond to ONE wire contract (`POST /extension-api/{extensionPointCode}`) the core calls with a timeout + circuit breaker |
+| Trust bar | Vetted/loaded like core code — no sandbox, full JVM access, affects every tenant with it installed | The core never loads it; a slow/broken service just degrades to "not extended" |
+| Use it when | You're building a plugin (JSON or code) that ANY tenant could install, same trust level as the platform's own modules | You need to run code the platform can't vet in-process — a proprietary calculation, a call to your own internal systems, dependencies that would never be approved into the shared runtime |
+
+If you're not sure: a normal Java plugin (this guide) is the default for
+`scope: global` work. Reach for an L5 extension service only when the code
+genuinely must NOT run inside the shared ERP process — see that guide's own
+"What you're doing" for the full reasoning.
+
+## The complete example
+
+Copy the real, runnable example at
+[`developer-docs/tutorial/code-plugin-example/`](../tutorial/code-plugin-example) —
+don't hand-write one from scratch. It pairs:
+
+- **Java**: `RiskScoreSummaryContribution` — a real `RestContribution` (a live
+  route, `GET /api/v1/plugins/risk-score-widget/summary`) that also
+  implements `DashboardWidgetContribution`, computing a "risk score" over the
+  tenant's real `organization_tag` rows with a plain `JdbcTemplate` query —
+  the exact same arithmetic the JSON tutorial's data lives inside, just run
+  in Java instead of read through the generic query engine.
+- **React**: `RiskScoreSummaryPanel` — real `useState`/`useEffect`, calls that
+  SAME Java route with a plain `fetch` (there's no generic `@erp/data` hook
+  for an arbitrary plugin-owned route — only for entity reads/writes),
+  renders the real returned score.
+
+### Build and verify it yourself
+
+```bash
+# 1. Java compiles standalone (own pom.xml, never added to the platform's
+#    own Maven reactor — see the example's README for what a true
+#    third-party build (no platform source) looks like)
+mvn -f developer-docs/tutorial/code-plugin-example/java/pom.xml clean package
+
+# 2. React type-checks and tests clean (extends the existing
+#    erp-code-plugin-demo workspace package)
+cd frontend/packages/erp-code-plugin-demo
+pnpm typecheck && pnpm test
+
+# 3. Package the .spk — auto-refreshes spk-assembly/lib/*.jar from the
+#    Java build above, validates the page JSON
+node tools/spark-cli/spark.js package developer-docs/tutorial/code-plugin-example/spk-assembly
+
+# 4. Validate the manifest against the real schema
+node tools/erp-cli/erp.mjs schema validate \
+  developer-docs/tutorial/code-plugin-example/spk-assembly/plugin.json \
+  --schema plugin-manifest
+```
+
+Installing it on a live ERP and re-running the React test against the real
+route is the example's own README's last step — it needs a running ERP, which
+this guide doesn't assume you have yet.
+
+## The parts that differ from a pure-JSON plugin
+
+- **`plugin.json`'s `mainClass`** is a real fully-qualified class name, not
+  `null` — see [`reference/plugin-manifest.md`](../reference/plugin-manifest.md).
+- **`spk-assembly/lib/`** carries your compiled jar (and only your own
+  classes — `engine-plugin-api`/Spring dependencies are `provided`, resolved
+  from the host's own classloader at runtime, never bundled).
+- **Your Java class** implements one of `engine-plugin-api`'s extension-point
+  interfaces (`org.pf4j.ExtensionPoint` subtypes), annotated `@Extension`.
+  `erp platform catalog` lists every one that exists today.
+- **Your React component** is registered through `registerExternal` +
+  `registerCustomRenderer`, not composed from `@erp/ui` primitives — see
+  [Add a custom block](./add-a-custom-block.md) for that seam on its own
+  (no Java), and [`concepts/sdk-modes.md`](../concepts/sdk-modes.md) for the
+  full custom-component boundary (what IS and ISN'T sandboxed).
+- **Getting the bundle onto a live tenant** is `erp plugin publish-frontend`
+  (uploads `dist/browser.js`, stamps `plugin.json`'s `frontendBundle`) — a
+  separate step from `.spk` packaging, run after install.
+
+## What this guide does NOT cover
+
+- Writing your OWN new extension-point interface — `engine-plugin-api`'s
+  existing interfaces are what you implement; adding a new one is platform
+  work, not plugin work.
+- Wiring a `DashboardWidgetContribution` into Studio's actual Dashboard
+  designer/renderer — real, shipped as an extension-point SHAPE, but the
+  host-side rendering wire-up is a disclosed, not-yet-built platform gap (see
+  that interface's own Javadoc). The example above still uses it to show the
+  shape; the `RestContribution` route is what's reachable end to end today.
+- `scope: tenant` + Java — that's Level 5, the
+  [tenant extension service guide](./build-a-tenant-extension-service.md), a
+  different deployable entirely.

package/bundle/docs/guides/build-a-page.md

@@ -0,0 +1,213 @@
+---
+title: Build a page
+audience: tenant
+---
+
+# Build a page
+
+## What you're doing
+
+A **page** is one screen. It is a JSON file under `spk-assembly/metadata/page/`
+describing a tree of **blocks** (widgets) arranged in rows and columns. The
+platform renders it; you never write React.
+
+The house style for a "list" screen — the one you'll build most often — is a
+single column of stacked sections:
+
+1. a hidden **loader** block that fetches KPI counts when the page mounts
+2. a **header** row: title on the left, action buttons on the right
+3. a **KPI row**: a few `core.kpi-card` blocks
+4. a **filter row**: a search box and a status dropdown
+5. a **grid**
+6. one or more **dialogs** for create / edit / detail
+
+## The complete example
+
+The tutorial's `equipment-register.json` is a full, working instance of this
+pattern:
+[the real file](../tutorial/example-plugin/spk-assembly/metadata/page/equipment-register.json).
+It is large (every widget is spelled out), so read it alongside this guide
+rather than pasting it here. Its shape on disk:
+
+```json
+{
+  "name": "equipment-register",
+  "description": "Office Equipment tutorial - Equipment Register.",
+  "definition": {
+    "contractVersion": 1,
+    "id": "office-equipment.equipment-register",
+    "version": "1.0.0",
+    "publisher": "office-equipment",
+    "title": "office-equipment.equipment-register.title",
+    "usesAppShell": true,
+    "route": { "pattern": "/office-equipment/equipment-register", "params": [] },
+    "designer": {
+      "displayNameKey": "office-equipment.equipment-register.title",
+      "descriptionKey": "office-equipment.equipment-register.title",
+      "icon": "devices",
+      "category": "list",
+      "propertyGroups": [],
+      "preview": { "kind": "page" }
+    },
+    "rows": [
+      { "id": "row-1", "columns": [ { "id": "col-1", "items": [ /* blocks */ ] } ] }
+    ]
+  },
+  "metadata": { "dataSource": "oeq-equipment-provider" },
+  "modules": ["office-equipment"]
+}
+```
+
+## Line by line
+
+### The wrapper
+
+- **`name`** — the file's short name; unique within the plugin.
+- **`definition`** — the actual page contract (`contractVersion: 1`).
+- **`metadata.dataSource`** — **the single field that wires the grid to its
+  data.** It names a [Data Provider](./add-a-data-provider.md). It is
+  *page-level*, never on the grid block. Get this wrong and the grid renders zero
+  rows with no error. See [Wire a page's data](./wire-a-pages-data.md).
+- **`modules`** — the module id(s) this page belongs to. The app shell only
+  lists a page in the sidenav if it's here. Use your module's `name`.
+
+### Inside `definition`
+
+- **`id`** — must be `<pluginId>.<page-name>`, dotted, lowercase.
+- **`title`** — an i18n key (define it in `metadata/i18n/en.json`).
+- **`route.pattern`** — starts with `/`. This is an internal routing key, **not**
+  the browser URL. The reachable URL is
+  `/app/<app-slug>/<module-slug>/<pluginId>/<page-name>`.
+- **`designer`** — required metadata for Studio. `category` is one of
+  `workspace | detail | list | dashboard | landing`. `propertyGroups: []` and
+  `preview: { "kind": "page" }` are fine as-is.
+- **`rows`** — an array of `{ id, columns: [ { id, items: [...] } ] }`. Each
+  `item` is `{ id, kind: "block", block: { ... } }`.
+
+### A block
+
+Every block instance looks like:
+
+```json
+{
+  "contractVersion": 1,
+  "instanceId": "kpi-8",
+  "blockType": "core.kpi-card",
+  "blockVersion": "1.0.0",
+  "properties": {
+    "value":    { "source": "binding", "binding": { "scope": "page", "key": "kpiTotal" } },
+    "labelKey": { "source": "static", "value": "office-equipment.equipment-register.kpi.total" },
+    "format":   { "source": "static", "value": "number" }
+  }
+}
+```
+
+- Every property is `{ "source": "static", "value": ... }` (a literal) or
+  `{ "source": "binding", "binding": { "scope": "page", "key": "..." } }` (read
+  from page state).
+- **`page` state** is a bag of values you set with `setValue` actions and read
+  with bindings. `kpiTotal`, `gridExternalFilter`, `formDialogOpen` are all just
+  keys you invented.
+
+### The mount loader
+
+The first block is a `core.container` with `hidden: true` and a `mounted` event
+that runs an **action chain** — call the KPI data service, then `setValue` each
+result into page state:
+
+```json
+{
+  "blockType": "core.container",
+  "properties": { "variant": { "source": "static", "value": "plain" },
+                  "hidden": { "source": "static", "value": true } },
+  "events": {
+    "mounted": {
+      "source": "action-chain",
+      "actions": [
+        { "id": "a0", "order": 0, "type": "callApi",
+          "config": { "connectionRef": "self", "path": "/api/v1/data-services/oeq-equipment-kpis/execute", "httpMethod": "POST", "params": {} },
+          "output": "kpi" },
+        { "id": "a1", "order": 1, "type": "setValue",
+          "config": { "field": "page.kpiTotal", "value": "${kpi.results.total.value}" } }
+      ]
+    }
+  }
+}
+```
+
+`${kpi.results.total.value}` is the response-shape for a **composite** data
+service — see [Add a KPI](./add-a-kpi.md).
+
+### The grid
+
+```json
+{
+  "blockType": "core.grid",
+  "properties": {
+    "columns": { "source": "static", "value": [
+      { "name": "asset_tag", "type": "string", "headerKey": "office-equipment.equipment-register.column.asset_tag" },
+      { "name": "status", "type": "string", "headerKey": "...column.status", "renderAs": "chip",
+        "colorMap": { "AVAILABLE": "success", "ASSIGNED": "info", "MAINTENANCE": "warning", "RETIRED": "default" } }
+    ] },
+    "pageSize": { "source": "static", "value": 25 },
+    "externalFilter": { "source": "binding", "binding": { "scope": "page", "key": "gridExternalFilter" } },
+    "refreshTrigger": { "source": "binding", "binding": { "scope": "page", "key": "gridRefreshTick" } }
+  }
+}
+```
+
+`core.grid` has **no** `dataSource`, `entity`, or `recordType` property — its
+data comes from the page's `metadata.dataSource`. `externalFilter` binds a page
+object whose keys become query filters; `refreshTrigger` re-runs the query
+whenever the bound value changes (toggle it with `setValue page.gridRefreshTick
+= "${!page.gridRefreshTick}"` after a save).
+
+## Ground yourself first
+
+```bash
+erp blocks list                       # every block type
+erp blocks list --type core.grid      # one block's full property/event list
+erp examples patterns --kind page     # curated real page shapes
+```
+
+## How to verify it worked
+
+```bash
+erp plugin test office-equipment/spk-assembly
+```
+
+```
+✓ page:equipment-register.json
+4 passed, 0 failed, 0 semantic warning(s), 3 skipped
+```
+
+After publishing, confirm it registered:
+
+```bash
+erp api get "/api/v1/authoring/pages?module=office-equipment"
+```
+
+```json
+[ { "id": 11324, "name": "equipment-register", "status": "published",
+    "route": { "pageId": "office-equipment.equipment-register",
+               "pattern": "/office-equipment/equipment-register", "params": [] } } ]
+```
+
+Then open `/app/<app>/<module>/office-equipment/equipment-register` in the ERP.
+
+## Common mistakes
+
+| Symptom | Cause | Fix |
+| --- | --- | --- |
+| grid shows 0 rows, no error | `metadata.dataSource` missing / misspelled / not a provider name | see [Wire a page's data](./wire-a-pages-data.md); `erp plugin test` flags this as `PAGE-DS-001` |
+| page not in the sidenav | `modules` array wrong or missing | set it to your module's `name` |
+| KPI cards blank | wrong response path in the `setValue` | composite → `${out.results.<step>.value}`; count → `${out.value}` |
+| text shows the raw i18n key | key missing from `metadata/i18n/en.json` | add it; `erp plugin test` flags `I18N-001` |
+| "route" is the browser URL — it isn't | confusing `route.pattern` with the reachable URL | URL is `/app/<app>/<module>/<plugin>/<page>` |
+
+## What to read next
+
+- [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)
+- Recipe: [KPI dashboard page](../recipes/kpi-dashboard-page.md), [master-detail page](../recipes/master-detail-page.md)

package/bundle/docs/guides/build-a-polyglot-service-plugin.md

@@ -0,0 +1,201 @@
+---
+title: Build a Service-mode plugin in Python or Node.js
+audience: tenant
+---
+
+# Build a Service-mode plugin in Python or Node.js
+
+## What you're doing
+
+Every plugin starts life **Embedded** — Java code loaded in-process via PF4J,
+sharing the ERP core's own JVM. Since 2026-08-14 a plugin can also declare
+**Service mode**: its own standalone process, reached over plain HTTP, that
+self-registers itself with the platform and sends a heartbeat. Until now the
+only real Service-mode example was Spring Boot. As of 2026-09-14 the wire
+contract is proven language-agnostic with two more real, working
+implementations — the platform genuinely does not care what language your
+process is written in, as long as it speaks the same three things: self-
+registration, a heartbeat, and the tenant-context headers.
+
+| Runtime | Framework | Real example in this repo | Port |
+| --- | --- | --- | --- |
+| `java` (default) | `spring-boot` | `backend/modules/hello-plugin-service/` | 8090 |
+| `python` | `fastapi` | `backend/modules/hello-plugin-service-python/` | 8091 |
+| `nodejs` | `express` | `backend/modules/hello-plugin-service-node/` | 8092 |
+
+This is a **different mechanism** from
+[Build a tenant extension service (L5)](./build-a-tenant-extension-service.md)
+— don't confuse the two:
+
+| | This guide (Service-mode plugin) | L5 extension service |
+| --- | --- | --- |
+| What it replaces | An entire plugin's REST surface | One narrow extension point (`EntityRecordBeforeCreate`) |
+| Who calls whom | Platform proxies EVERY request for that plugin to your process | Platform calls your process only at one specific hook |
+| Auth | Shared-secret self-registration token | Short-lived HMAC-signed bearer token per call |
+| Scope | A full business application (HCM, CRM, or your own) | A single tenant-specific customization |
+
+## The fastest way: scaffold it
+
+> The plugin ids used below (`ai-document-parser`, `whatsapp-connector`) are
+> illustrative example names for this guide, chosen to show the kind of
+> plugin each language suits — a Python service calling an ML model, a
+> Node.js service calling a chat API. Neither ships with this platform;
+> swap in your own plugin id.
+
+Don't hand-write the self-registration/heartbeat/tenant-context wiring —
+generate a real, runnable starting point:
+
+```bash
+platform-cli service-plugin:scaffold --id ai-document-parser --runtime python --vendor "Acme Corp" --out .
+# or:
+platform-cli service-plugin:scaffold --id whatsapp-connector --runtime nodejs --vendor "Acme Corp" --out .
+```
+
+This produces the same structure `hello-plugin-service-python`/
+`hello-plugin-service-node` have by hand: `plugin.json`, the app source with
+self-registration/heartbeat/tenant-context already wired in, a
+`requirements.txt`/`package.json`, a multi-stage `Dockerfile`, and a local
+dev launcher script. Both arms of this command are proven by actually running
+their own scaffolded output end-to-end, not just hand-verified once.
+
+## The manifest
+
+```json
+{
+  "id": "ai-document-parser",
+  "name": "AI Document Parser",
+  "version": "1.0.0",
+  "runtimeModes": ["service"],
+  "serviceRuntime": "python",
+  "serviceFramework": "fastapi"
+}
+```
+
+Python and Node.js plugins can **only** declare `runtimeModes: ["service"]`
+— never `"embedded"` — nothing outside the JVM can load in-process. Installing
+a manifest that sets `serviceRuntime` to `"python"`/`"nodejs"` without
+`"service"` in `runtimeModes` fails install with a clear error
+(`PluginCodeLifecycle#validateServiceRuntime`). `serviceRuntime`/
+`serviceFramework` default to `"java"`/`"spring-boot"` when absent — every
+manifest written before this feature existed keeps its exact current
+behavior.
+
+## The wire contract, exactly
+
+Match this regardless of language — it's the same contract
+`hello-plugin-service`/`-python`/`-node` all implement:
+
+- **Self-register on startup**: `POST {engine-api base URL}/api/v1/platform/service-registrations`
+  with your plugin id and this process's own reachable URL, header
+  `X-Plugin-Registration-Token: <token>` — same env var name in every
+  language, `ERP_PLUGIN_SERVICE_TOKEN`.
+- **Heartbeat**: repeat the same POST on an interval (`deploymentConfig.heartbeatIntervalSeconds`,
+  default matches whatever your `plugin.json`'s `serviceDeployment` declares)
+  — a missed heartbeat past a freshness window makes the platform treat your
+  service as unavailable and return a clean `503`, never a hang.
+- **Deregister on shutdown**: `DELETE {engine-api base URL}/api/v1/platform/service-registrations/{pluginId}`
+  — a graceful `SIGTERM` (container/pod termination, not a hard `kill -9`)
+  should trigger this.
+- **Every proxied request** carries `X-Tenant-Id`/`X-Actor` (and
+  `Authorization` when present) — read them, never trust anything else as
+  the tenant identity.
+- **Health endpoint**: whatever path your manifest's `serviceDeployment.healthPath`
+  declares (`/health` for both the Python and Node.js examples — no
+  FastAPI/Express equivalent of Spring's `/actuator/health` exists, so this
+  is just a plain declared value, not a framework convention).
+
+## Ground yourself first
+
+```bash
+erp_get_schema {"name":"plugin-manifest"}
+```
+
+## Build, run, and verify it standalone (no ERP needed yet)
+
+Python:
+
+```bash
+cd backend/modules/hello-plugin-service-python
+python -m venv .venv && .venv/Scripts/activate
+pip install -r requirements.txt
+uvicorn app.main:app --port 8091
+curl localhost:8091/health
+curl localhost:8091/greeting -H "X-Tenant-Id: 1" -H "X-Actor: demo"
+```
+
+Node.js:
+
+```bash
+cd backend/modules/hello-plugin-service-node
+npm install && npm run build && npm start
+curl localhost:8092/health
+curl localhost:8092/greeting -H "X-Tenant-Id: 1" -H "X-Actor: demo"
+```
+
+Then build the real container each ships:
+
+```bash
+docker build -t ai-document-parser .
+docker run -p 8091:8091 -e ERP_PLUGIN_SERVICE_TOKEN=<your token> ai-document-parser
+```
+
+## Test it
+
+Both languages have a real, committed, passing test suite you can run and
+extend as your own starting point — not just illustrative snippets:
+
+```bash
+# Python — pytest + FastAPI's TestClient, no live engine-api needed
+cd backend/modules/hello-plugin-service-python
+pip install -r requirements.txt -r requirements-dev.txt
+python -m pytest tests/ -v
+
+# Node.js — vitest + supertest, no live engine-api needed
+cd backend/modules/hello-plugin-service-node
+npm install
+npm test
+```
+
+Both suites drive the real app in-process (no port bound, no engine-api
+required) and cover the same two things worth testing in any Service-mode
+plugin: your health endpoint responds, and your handlers correctly read
+`X-Tenant-Id`/`X-Actor` from the tenant-context layer. Note Node's Express
+app is deliberately split into `app.ts` (routes, importable/testable) and
+`main.ts` (the actual `listen()` + registration + signal handling) — import
+`createApp()` in your own tests the same way, rather than importing a file
+that starts a real server as a side effect of being imported.
+
+## Register it against a running ERP
+
+```bash
+start-hello-plugin-service-python.bat   # or start-hello-plugin-service-node.bat
+```
+
+Then flip the plugin to Service mode in Studio's Plugin Runtime panel — the
+platform starts routing `GET /api/v1/plugins/<your-plugin-id>/**` to your
+process instead of (or in addition to, if you're testing) the Java version.
+
+## Deploying it for real
+
+Each example ships a parallel Kustomize tree — `deploy/kubernetes/hello-plugin-service-python/`
+and `.../hello-plugin-service-node/`, mirroring the Java one's `base`/`overlays/{local,aws}`
+shape with a different image/port/health-path. Copy the tree for your own
+plugin id rather than trying to parameterize one shared tree across
+languages — the images, ports, and health checks genuinely differ per
+language and a single shared tree obscures more than it clarifies.
+
+## Common mistakes
+
+| Symptom | Cause | Fix |
+| --- | --- | --- |
+| Install fails with a serviceRuntime error | Declared `serviceRuntime: "python"`/`"nodejs"` without `"service"` in `runtimeModes` | Embedded is always Java — add `"service"` to `runtimeModes` |
+| `403`/`401` on self-registration | Token mismatch | Same `ERP_PLUGIN_SERVICE_TOKEN` value on both the ERP core and your process |
+| Requests never reach your process | Plugin still on Embedded mode in Studio | Flip the Plugin Runtime toggle to Service |
+| Clean `503`s from every call | No heartbeat received recently | Check your process is actually running and its heartbeat interval hasn't lapsed |
+| Graceful shutdown never deregisters | Process was hard-killed (`kill -9`, or on native Windows a bare terminal `kill`) rather than sent a real `SIGTERM` | Use `docker stop`/pod termination in any real deployment — that delivers a real, trappable signal |
+
+## What to read next
+
+- [Build a tenant extension service (L5)](./build-a-tenant-extension-service.md) — the narrower, single-extension-point alternative to this guide
+- [Publish and upgrade a plugin](./publish-and-upgrade.md)
+- `platform-cli service-plugin:scaffold --help` for every scaffold option