@sparkerp/plugin-sdk 0.1.0 → 1.1.0

package/bundle/docs/guides/checkout-an-installed-plugin.md

@@ -0,0 +1,151 @@
+---
+title: Check out an installed plugin and work on it
+audience: tenant
+---
+
+# Check out an installed plugin and work on it
+
+## What you're doing
+
+You already have a plugin **installed** on an environment — maybe you built
+it yourself weeks ago and lost the local source, maybe you inherited it from
+someone else, maybe you're fixing a real, confirmed bug in your own
+tenant-owned plugin. Either way you want a real local copy: something you
+can `git diff`, edit, and ship back — not a live-database patch, and not a
+raw dump of API responses.
+
+**Before you reach for this:** if what you actually want is to *extend* a
+shipped, vendor-owned application (HCM, CRM, ...) rather than edit a plugin
+you own, this is the wrong page — see
+[Extend a shipped application](./extend-a-shipped-application.md) instead.
+Editing another module's own source is never the right move for a feature
+request, only for a confirmed bug in a plugin that's genuinely yours.
+
+## The command set
+
+Modeled on git, on purpose — the mental model is the same one you already
+have:
+
+| git | erp | what it does |
+|---|---|---|
+| `git branch` / `git remote -v` | `erp plugin list` | Every plugin installed on the current env, as a readable table (`pluginId`, `version`, `state`, `name`) — pick one before cloning. `--json` for the raw response. |
+| `git clone` | `erp plugin clone <pluginId> [--out <dir>]` | A **real, full local checkout** — every page, menu, data service, data view, mobile nav, provider, application/module membership, and this plugin's own i18n keys it owns, written to `<out>/<pluginId>/spk-assembly/metadata/...` in the same on-disk shape a shipped module has. Always gets the latest version of every artifact. |
+| `git checkout <ref>` | `erp plugin checkout <pluginId> --version <n> [--out <dir>]` | Same full checkout as `clone`, but for each artifact independently, prefers version `n` from *that artifact's own* history if it has one that old, else falls back to latest. See the caveat below — this is not a single point-in-time snapshot. |
+| `git add` / `git commit` | plain `git`, inside the checked-out directory | It's a real folder now. `cd <pluginId> && git init && git add . && git commit -m "..."` gives you real, diffable history — no special erp command needed. |
+| `git push` | `erp plugin build <dir> -o out.spk` then `erp plugin publish out.spk --env <name>` (or `erp plugin push`, an alias) | Package your edited `spk-assembly/` into a `.spk` and ship it to an environment. See [Publish and upgrade a plugin](./publish-and-upgrade.md). |
+
+`erp plugin pull <pluginId>` (no `--full`) still exists separately — it's
+the *thin* form: just `plugin.json` + install config + install state, no
+artifact bodies. Useful for a quick "what version is installed, what's its
+manifest" check without the full fan-out `clone`/`checkout` do.
+
+## The complete example
+
+```bash
+# 1. See what's there
+erp plugin list
+
+# PLUGIN ID          VERSION   STATE      NAME
+# hcm-foundation     1.0.299   installed  HCM Foundation
+# office-equipment   1.0.0     installed  Office Equipment
+# ...
+
+# 2. Clone the one you own
+erp plugin clone office-equipment
+
+# == Checking out plugin "office-equipment" ==
+# -- spk-assembly/plugin.json (version 1.0.0) --
+# -- pages: 3 owned by office-equipment --
+#    wrote page/office-equipment-list.json (id 4021, v2)
+#    ...
+# -- i18n --
+#    wrote i18n/en.json (41 keys under "office-equipment.*")
+#
+# == Full checkout done: 9 artifacts + plugin.json + i18n written to office-equipment/spk-assembly ==
+#
+# Now a real local directory — e.g.:
+#   cd office-equipment && git init && git add . && git commit -m "Clone of office-equipment@1.0.0"
+
+# 3. Real git, from here on
+cd office-equipment
+git init && git add . && git commit -m "Clone of office-equipment@1.0.0"
+
+# 4. Edit under spk-assembly/metadata/, commit as you go
+#    (e.g. spk-assembly/metadata/page/office-equipment-list.json)
+git add -A && git commit -m "Add a status filter to the equipment list"
+
+# 5. Ship it — dev first, then prod
+erp plugin build . -o office-equipment-1.0.1.spk
+erp plugin publish office-equipment-1.0.1.spk --env dev
+#   ...verify it looks right...
+erp plugin publish office-equipment-1.0.1.spk --env prod
+```
+
+## What actually gets written
+
+```
+office-equipment/
+├── plugin.json                    ← THIN pull output (manifest only, kept for compat)
+├── config.json
+├── installation-state.json
+└── spk-assembly/                  ← the real, editable, buildable tree
+    ├── plugin.json
+    └── metadata/
+        ├── page/*.json
+        ├── menu/*.json
+        ├── mobile_nav/*.json
+        ├── provider/*.json
+        ├── data_service/*.json
+        ├── data_view/*.json
+        ├── application/*.json     ← membership rows, if this plugin owns any
+        ├── module/*.json
+        ├── entity/*.json          ← best-effort, see caveat below
+        └── i18n/en.json           ← only this plugin's own `<pluginId>.*` keys
+```
+
+Every artifact file is `{ name, description, metadata, definition }` — the
+same shape `erp plugin build` reads when packaging a `.spk`.
+
+## Known limits (disclosed, not hidden)
+
+- **`--version` is per-artifact, not a plugin-wide snapshot.** `plugin.json`'s
+  own `version` (e.g. `1.0.299`) is bumped once per `.spk` release, but each
+  individual artifact versions independently, on its own publish cadence.
+  There's no server-side record of "which version of every one of this
+  plugin's 28 artifacts was live when the plugin itself was at 1.0.298" — so
+  `checkout --version 4` takes artifact-level `v4` wherever that artifact
+  has one, and its latest otherwise. Good enough to inspect an older cut of
+  one screen; not a substitute for real git tags on your own commits going
+  forward.
+- **Entities are best-effort.** Unlike pages/menus/data-services/etc.,
+  entities have no `ownerPlugin` field at all — the closest available signal
+  is a free-text `category` field, matched against the plugin id. Confirmed
+  live to hold real plugin ids for entity-heavy modules, but it's not an
+  enforced foreign key.
+- **`erp plugin validate`** isn't available in packaged SDK mode (needs
+  platform build tooling not shipped in the authoring bundle) — validate
+  what you can with `erp schema validate <file> --schema <name>` per file
+  instead.
+
+## Common mistakes
+
+- **Cloning a vendor-owned plugin to "fix" a feature gap.** If it's not a
+  confirmed bug in code you own, use
+  [Extend a shipped application](./extend-a-shipped-application.md) instead
+  — a companion plugin, not an edit to someone else's source.
+- **Editing the THIN `plugin.json`/`config.json`/`installation-state.json`
+  files at the top level.** Those are install-state snapshots, not build
+  input — edit under `spk-assembly/metadata/` instead; that's what
+  `erp plugin build` actually reads.
+- **Forgetting `--env`.** `clone`/`checkout` read from whatever `erp env
+  use`'s current environment is (or `--env <name>` for one call) — cloning
+  from `prod` when you meant `dev` gets you prod's live content, not a
+  sandbox to break.
+
+## See also
+
+- [Publish and upgrade a plugin](./publish-and-upgrade.md) — the `build`/
+  `publish` half of this flow, in more depth.
+- [Extend a shipped application](./extend-a-shipped-application.md) — the
+  right tool when you don't own the plugin's source.
+- [Validate and test a plugin](./validate-and-test.md)

package/bundle/docs/guides/extend-a-shipped-application.md

@@ -0,0 +1,132 @@
+---
+title: Extend a shipped application (e.g. HCM)
+audience: tenant
+---
+
+# Extend a shipped application
+
+This page answers a question the other guides don't: *"HCM (or CRM, or any
+other shipped application) already has the screen I want — how do I add to
+it without forking the product?"* It uses HCM as the worked example because
+it's the largest shipped application, but the pattern is identical for every
+other one.
+
+## What you're doing
+
+There are exactly three ways to extend a shipped application. Picking the
+wrong one is the most common mistake — start here.
+
+| You want to... | Use | Why |
+|---|---|---|
+| Add a field to an existing screen (e.g. a new column on the Employee form) | **Custom Fields** (no code) — see [Document Settings, Custom Fields, Custom Forms & Numbering Sequences](../applications/hcm/settings-extensibility.md) | It's a tenant admin setting, not a development task. No plugin needed. |
+| Add a new screen, report, KPI, or workflow that *reads* existing data (e.g. a dashboard of employees whose certifications expire soon) | **A companion plugin** that reads the shipped module's entities through a **Data Service / Data View** (read-only) | This is what the rest of this page walks through. |
+| Add a new approval step or business rule triggered by an existing entity changing | **A workflow or business rule** attached via metadata to the existing entity | See [Add an approval workflow](./add-an-approval-workflow.md) and [Add business rules and expressions](./add-business-rules.md) — no Java, and no edit to the shipped plugin. |
+
+What you must **never** do: edit `hcm-employee`'s (or any shipped plugin's)
+own Java source or its metadata files. Those are the platform's, upgraded
+independently of your tenant, and per
+[[feedback-avoid-frequent-core-code-changes]] only a real, confirmed bug
+justifies touching another module's code — a feature request never does.
+Every legitimate extension in the table above is additive: a new plugin, a
+new metadata file, a new rule. Nothing you write ever modifies a file that
+ships with `hcm-employee`, `hcm-leave`, or any other application module.
+
+## The complete example
+
+A companion plugin, `hcm-cert-tracker`, that adds one new read-only page to
+HCM: **Employees by Department** — a KPI built entirely from data that
+already lives in the shipped `hcm-employee` module's own database table,
+without touching that module at all.
+
+`spk-assembly/metadata/data_view/employees-by-department-view.json`:
+
+```json
+{
+  "name": "hcm-cert-tracker-employees-by-department-view",
+  "description": "Read-only view over hcm-employee's own `employee` table — active headcount grouped by department. This plugin never writes to this table.",
+  "definition": {
+    "source": { "table": "employee", "alias": "e", "excludeDeleted": false, "schema": "hcm" },
+    "joins": [
+      { "table": "org_unit", "alias": "dept", "type": "INNER", "on": [{ "leftRef": "e.department_id", "rightRef": "dept.id" }], "excludeDeleted": false, "schema": "hcm" }
+    ],
+    "fields": [{ "ref": "dept.name", "outputName": "label" }],
+    "calculatedFields": [],
+    "filter": "{\"and\":[{\"field\":\"e.employment_status\",\"operator\":\"eq\",\"value\":\"active\"}]}",
+    "groupBy": ["dept.name"],
+    "aggregations": [{ "ref": "e.id", "fn": "COUNT", "outputName": "value" }],
+    "sort": [{ "ref": "dept.name", "descending": false }],
+    "pagination": { "defaultPageSize": 50, "maxPageSize": 100 },
+    "permissionKey": null
+  },
+  "metadata": {},
+  "modules": ["hcm-cert-tracker-dashboard"]
+}
+```
+
+`spk-assembly/metadata/data_service/employees-by-department.json`:
+
+```json
+{
+  "name": "hcm-cert-tracker-employees-by-department",
+  "operation": "search",
+  "source": { "kind": "dataView", "ref": "hcm-cert-tracker-employees-by-department-view" }
+}
+```
+
+The page then binds a `core.donut-chart` (or `core.list`) block to
+`POST /api/v1/data-services/hcm-cert-tracker-employees-by-department/execute`
+— the exact same `callApi` → `setValue` → binding pattern in
+[Wire a page's data](./wire-a-pages-data.md).
+
+## Line by line
+
+- **`source.schema: "hcm"`** — every HCM module's tables live in the shared
+  `hcm` Postgres schema, not a per-plugin schema. Get this from the shipped
+  module's own real, already-installed `data_view` files (as done here,
+  copied from `hcm-employee`'s own
+  `department-headcount-distribution-view.json`) — never guess it, and never
+  trust a plugin's `plugin.json` `schemaName` field, which can be stale (see
+  [[feedback-entity-engine-tables-must-route-to-app-schema]]).
+- **`source.table: "employee"`** — the real table name. Reverse-engineer real
+  table/column names the same way: read an existing, shipped `data_view`
+  JSON from the module you're extending. Every shipped HCM module's
+  `metadata/data_view/` directory is real, readable reference material for
+  exactly this purpose.
+- **This view is read-only** — a `dataView`/`dataService` pair can only
+  `search`/`get`/`count`; there is no write path through this mechanism.
+  Writing to another module's table is not supported and not safe — if you
+  need to change HCM data, do it through HCM's own real forms/APIs, not by
+  reaching into its schema.
+- **`modules: ["hcm-cert-tracker-dashboard"]`** — scopes this data service to
+  your own plugin's page, not to `hcm-employee`'s.
+
+## How to verify it worked
+
+1. `erp plugin build && erp plugin publish --env dev`
+2. `curl -X POST $BASE/api/v1/data-services/hcm-cert-tracker-employees-by-department/execute -H "Authorization: Bearer $TOKEN"` and confirm it returns real `{label, value}` rows matching your tenant's actual employee/department data — spot-check one row against the HCM Employee Directory screen itself.
+3. Confirm `hcm-employee`'s own files are untouched: `git status` inside `backend/modules/hcm-employee` should show nothing.
+
+## Common mistakes
+
+- **Editing the shipped module instead of reading it.** If you find yourself
+  opening `hcm-employee`'s source to add a field or endpoint, stop — that's
+  Custom Fields or a companion plugin, not a source edit.
+- **Guessing the schema name.** Always confirm it from a real, already-shipped
+  `data_view` file in the module you're reading from.
+- **Building a bespoke REST controller instead of a Data Service.** See
+  [[feedback-prefer-dataview-over-bespoke-rest-for-reads]] — if you're
+  reading rows, a `dataView`/`dataService` pair is almost always the right
+  tool, not a hand-written `@RestController`.
+- **Forgetting `TenantContext`.** If any part of your companion plugin adds a
+  `NO_AUTH` endpoint that touches this data outside the normal
+  tenant-request path, it must wrap the call in
+  `TenantContext.set()`/`finally clear()` — see
+  [[feedback-no-auth-endpoints-need-manual-tenant-context]].
+
+## What to read next
+
+- [Add a data provider, data view, or data service](./add-a-data-provider.md) — the full reference for what this guide's worked example used.
+- [Build a page](./build-a-page.md) and [Wire a page's data](./wire-a-pages-data.md) — to add the screen this data feeds.
+- [Add a KPI or aggregation](./add-a-kpi.md) — for the KPI-card version of this same pattern.
+- [Add an approval workflow](./add-an-approval-workflow.md) — for the "add a workflow step to an existing entity" extension path.
+- [Add your own app-owned roles & permissions](./add-app-owned-roles-and-permissions.md) — the correct pattern if your companion plugin needs its own admin role, instead of widening a shipped module's access checks.

package/bundle/docs/guides/index.md

@@ -39,6 +39,8 @@ Every code sample is a real file under
 
 - [Add business rules and expressions](./add-business-rules.md)
 - [Add an approval workflow](./add-an-approval-workflow.md)
+- [Add your own app-owned roles & permissions](./add-app-owned-roles-and-permissions.md)
+- [Extend a shipped application (e.g. HCM)](./extend-a-shipped-application.md)
 
 ## Scheduled jobs (no Java)
 
@@ -49,5 +51,6 @@ Every code sample is a real file under
 
 ## Ship it
 
+- [Check out an installed plugin and work on it](./checkout-an-installed-plugin.md)
 - [Validate and test a plugin](./validate-and-test.md)
 - [Publish and upgrade a plugin](./publish-and-upgrade.md)

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

@@ -27,7 +27,7 @@ Pull the full JSON Schema: `erp schema pull entity-aggregation-config`  ·&
 | `agg_field` | string |  | Required for sum/avg/min/max; the numeric column to fold. |
 | `group_by_field` | string |  | Optional; one result bucket per distinct value. |
 | `target_entity` | string | yes |  |
-| `target_key_field` | string | yes | Column on target_entity that holds the bucket key (a declared field). Special value "id": the bucket key IS a row's own primary key — the fold is written straight back onto target_entity row #<key> (never a create). Use with group_by_field yielding the parent id (e.g. maintenance_id), target_entity = that parent entity, and a blank target_key_prefix — this is the true 'roll child lines up onto the parent record' form (MaintenanceCostSyncJob). |
+| `target_key_field` | string | yes | Column on target_entity that holds the bucket key (a declared field). Special value "id": the bucket key IS a row's own primary key — the fold is written straight back onto target_entity row #&lt;key&gt; (never a create). Use with group_by_field yielding the parent id (e.g. maintenance_id), target_entity = that parent entity, and a blank target_key_prefix — this is the true 'roll child lines up onto the parent record' form (MaintenanceCostSyncJob). |
 | `target_key_prefix` | string |  | Prepended to the bucket key when writing (so multiple configs can share one summary entity without collisions). |
 | `result_key` | string |  | Used as the bucket key when group_by_field is blank; defaults to sweep_code. |
 | `target_value_field` | string | yes |  |

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

@@ -24,7 +24,7 @@ Pull the full JSON Schema: `erp schema pull entity-document-generator-config` &n
 | `format` | string |  | one of: `json`, `csv` |
 | `cabinet_id` | integer |  | DMS cabinet id (engine-file) the artifact is stored in. Give this OR cabinet_name. |
 | `cabinet_name` | string |  | Portable alternative to cabinet_id: the job resolves a cabinet by this name for the tenant, creating it if absent. Preferred for seed-data rows (no hardcoded id). |
-| `file_name_template` | string |  | Generated file name. Supports ${id} ${date} ${ts} ${uuid} and ${field:<name>}. Default: <document_code>-${id}-${date}.<ext>. |
+| `file_name_template` | string |  | Generated file name. Supports ${id} ${date} ${ts} ${uuid} and ${field:&lt;name&gt;}. Default: &lt;document_code&gt;-${id}-${date}.&lt;ext&gt;. |
 | `include_fields` | string |  | Comma-separated source fields to include in the artifact. Blank = all fields. |
 | `child_entity` | string |  | Optional child entity whose rows (matched by child_match_field == source id) are embedded (json) alongside the record. |
 | `child_match_field` | string |  | FK column on child_entity pointing at the source row's id. |

package/bundle/docs/tutorial/01-create-the-plugin.md

@@ -8,12 +8,18 @@ audience: tenant
 ## Scaffold
 
 ```bash
-erp plugin create example-plugin --name "Office Equipment" --type business-app
+erp plugin create example-plugin --name "Office Equipment" --type business-application
 ```
 
 > The folder is `example-plugin/` to match this docs tree. The plugin **id** we
 > use is `office-equipment` — set below. (In real life pick one name and use it
 > for both.)
+>
+> The `--type` value is written into `plugin.json` verbatim, with no
+> validation against what the rest of the platform actually uses — pass
+> `business-application` exactly (not `business-app` or anything else), since
+> that's the real convention every shipped plugin (`hcm-foundation`,
+> `crm-foundation`, ...) uses.
 
 You get `example-plugin/spk-assembly/` with empty `metadata/*` folders and a
 `plugin.json` with `"mainClass": null`.

package/bundle/docs/tutorial/07-return-due-reminder-job.md

@@ -78,12 +78,35 @@ numbers) before the write, so a config targeting a `boolean`/`integer`/`numeric`
 `set_field` is fully supported. An earlier draft of this tutorial hit a SQL type
 error doing exactly that — that platform bug is fixed.
 
-## 3. The job registers itself
+## 3. Ship the rule that registers the job
+
+Unlike this doc's own first draft claimed, **the platform does not ship this
+rule for you** — every plugin using a shared sweep-style entity
+(`entity_status_date_sweep_config`, `entity_aggregation_config`,
+`entity_compliance_config`, ...) ships its own copy of the one small
+`AFTER_CREATE` rule that registers the corresponding job, the same way
+`hcm-assets` ships its own `entity_aggregation_config_register.json` /
+`entity_compliance_config_register.json`. Skip this file and your config rows
+sit in the table forever with no job ever scheduled to read them — confirmed
+live (2026-09-22): a tenant with pre-existing `entity_status_date_sweep_config`
+rows from another plugin still had no `engine-entity.status-date-sweep` job at
+all until this rule shipped.
+
+`spk-assembly/metadata/rules/entity_status_date_sweep_config_register.json`
+([real file](./example-plugin/spk-assembly/metadata/rules/entity_status_date_sweep_config_register.json)):
 
-The platform ships an `AFTER_CREATE` rule on `entity_status_date_sweep_config`
-that calls `ensureEntityStatusDateSweepJobRegistered`. So the first row you seed
-auto-registers the job for your tenant — **you ship no register rule for this
-job** (unlike the aggregation/cadence/compliance jobs).
+```json
+{
+  "entityType": "entity_status_date_sweep_config",
+  "name": "ensure_status_date_sweep_job_registered",
+  "description": "Register the generic EntityStatusDateSweepJob for this tenant on first config row.",
+  "triggerEvent": "AFTER_CREATE",
+  "conditions": null,
+  "actions": "[{\"type\": \"EXECUTE_SERVICE\", \"service\": \"ensureEntityStatusDateSweepJobRegistered\"}]",
+  "priority": 10,
+  "active": true
+}
+```
 
 ## Verify
 

package/bundle/docs/tutorial/08-menus-i18n-publish.md

@@ -44,7 +44,7 @@ erp plugin test     example-plugin/spk-assembly
 ```
 
 ```
-validated 3 page(s) — clean
+OK — 3 page(s) valid
 
 Plugin Tests
 ────────────────────────────────────────
@@ -65,24 +65,24 @@ node developer-docs/examples/test-examples.mjs
 ## Build
 
 ```bash
-erp plugin build example-plugin/spk-assembly -o example-plugin/office-equipment-1.0.0.spk
+erp plugin build example-plugin/spk-assembly -o example-plugin/office-equipment-1.0.4.spk
 ```
 
 ```
 validated 3 page(s) — clean
-packaged 33 files -> example-plugin/office-equipment-1.0.0.spk (231986 bytes)
+packaged 32 files -> example-plugin/office-equipment-1.0.4.spk (230832 bytes)
 sha256: ...
 ```
 
 ## Publish
 
 ```bash
-erp plugin publish example-plugin/office-equipment-1.0.0.spk --tenant 2
+erp plugin publish example-plugin/office-equipment-1.0.4.spk --tenant 2
 ```
 
 ```
 installed:
-{"pluginId":"office-equipment","version":"1.0.0","state":"installed","pf4jState":"STARTED", ...}
+{"pluginId":"office-equipment","version":"1.0.4","state":"installed","pf4jState":"STARTED", ...}
 ```
 
 ## Confirm it's all live

package/bundle/manifest.json

@@ -1,13 +1,13 @@
 {
-  "bundleVersion": "2026-09-14.1",
+  "bundleVersion": "2026-09-23.1",
   "platformVersion": "0.0.0",
-  "generatedAt": "2026-09-14T13:48:11.809Z",
+  "generatedAt": "2026-09-23T08:53:09.048Z",
   "generatedBy": "erp bundle build (tools/erp-cli/erp.mjs bundleBuildCommand)",
   "schemaCount": 27,
-  "docCount": 90,
+  "docCount": 249,
   "exampleFileCount": 14,
   "blockCount": 124,
-  "catalogGeneratedAt": "2026-09-14T13:48:11.094Z",
+  "catalogGeneratedAt": "2026-09-23T08:53:08.093Z",
   "catalogEngineCount": 43,
   "catalogContractUnitCount": 74,
   "sdkMode": "packaged"

package/bundle/schemas/page.schema.json

@@ -285,6 +285,19 @@
     "isSessionExpiredPage": { "type": "boolean" },
     "isAccessDeniedPage": { "type": "boolean" },
     "devicePersistence": { "type": "array", "items": { "$ref": "#/$defs/devicePersistenceRule" } },
+    "events": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "hook": { "const": "onLoad" },
+          "actions": { "type": "array", "items": { "type": "object" }, "description": "Frozen @erp/action-engine ActionDefinition[] - validated against the live ActionRegistry at mount time, same as a block item's own events." }
+        },
+        "required": ["hook", "actions"],
+        "additionalProperties": false
+      },
+      "description": "Page-level lifecycle hooks - today only \"onLoad\", fired once after the page mounts."
+    },
     "modules": { "type": "array", "items": { "type": "string" }, "description": "App-module ids this page belongs to (e.g. \"hcm-foundation-home\") - TenantPageHost's per-module page listing only surfaces a page if it's present here. Load-bearing in practice for any page reached via the app sidenav/module shell, even on pages authored before this was documented." }
   },
   "required": ["contractVersion", "id", "version", "publisher", "title", "rows", "route", "designer"],

package/bundle/schemas/plugin-manifest.schema.json

@@ -42,6 +42,19 @@
         "entrypointExport": { "type": "string" }
       }
     },
+    "publicApis": {
+      "type": "array",
+      "description": "Added 2026-09-16 (direct user instruction: \"ideally during plugin installation - plugin should tell what are the apis are what is their behaviour\"). Gateway-public API endpoints this plugin declares — installed into the real, admin-editable gateway_public_read_path table at install/upgrade time (PluginPublicApiInstaller in engine-plugin) instead of a human hand-authoring a platform migration or a gateway Java-source change. Absent/empty (every manifest that predates this field, and the overwhelming majority of plugins going forward) means this plugin declares no public APIs — its whole surface stays tenant/session-gated, same as before this field existed.",
+      "items": {
+        "type": "object",
+        "required": ["pathPattern"],
+        "properties": {
+          "pathPattern": { "type": "string", "description": "Ant-style path, e.g. \"/api/v1/my-plugin/webhook\"." },
+          "category": { "type": "string", "enum": ["PUBLIC_READ", "NO_AUTH"], "default": "PUBLIC_READ", "description": "PUBLIC_READ (GET/HEAD only, gateway injects the platform tenant's own id, never trusted from the client) or NO_AUTH (any verb, no tenant context injected at all — genuinely unauthenticated). Defaults to PUBLIC_READ, the narrower/safer of the two, when absent." },
+          "description": { "type": "string", "description": "Why this endpoint must be reachable before a tenant/session exists — shown to a platform admin reviewing what a plugin is asking to expose." }
+        }
+      }
+    },
     "roles": {
       "type": "array",
       "items": {