FE-1567: Add optional description and metadata fields to SDCPN nodes

.agents/skills/publishing-packages/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: publishing-packages
+description: Conventions for publishing npm packages from this repository, including when a PR needs a changeset and how to write one. Use when adding or editing a changeset, versioning or releasing a package, or deciding whether a change to a publishable library needs a changelog entry.
+license: AGPL-3.0
+metadata:
+  triggers:
+    type: domain
+    enforcement: suggest
+    priority: high
+    keywords:
+      - changeset
+      - changelog
+      - npm publish
+      - release
+      - version bump
+    intent-patterns:
+      - "\\b(add|write|create|edit|split)\\b.*?\\bchangesets?\\b"
+      - "\\b(publish|release|version)\\b.*?\\bpackages?\\b"
+---
+
+# Publishing Packages
+
+npm-publishable packages in this repository are versioned and released with [changesets](https://github.com/changesets/changesets). The changeset configuration, including which packages are ignored, lives in [`.changeset/config.json`](../../../.changeset/config.json).
+
+## Changesets
+
+A PR that changes an npm-publishable package adds a changeset file under `.changeset/`. The changeset text becomes the package's published changelog entry, so write it for the package's consumers:
+
+- Describe the change as a consumer of the package experiences it: behaviour changes, bug fixes, and interface changes. Leave out implementation details that do not affect consumers, and do not mention this repository or its internal systems.
+- Every sentence must apply to each package the changeset lists. When a PR changes several packages in different ways, write a separate changeset for each package.
+- Use at most one paragraph per changeset.
+
+A package's own `AGENTS.md` can carry further conventions, such as the bump level it accepts; check it before writing the changeset.

.changeset/sdcpn-description-metadata-core.md

@@ -0,0 +1,5 @@
+---
+"@hashintel/petrinaut-core": patch
+---
+
+SDCPN elements carry an optional `description` (places, transitions, types, subnets, component instances, and the net root) and an optional `metadata` record of JSON values (transitions, subnets, component instances, and the net root). `metadata` is host-defined and opaque to the library. Both fields validate against the entity schemas, survive file import/export, and are preserved when an `SDCPNInput` is normalized. Files written without the fields still validate.

.changeset/sdcpn-description-metadata-ui.md

@@ -0,0 +1,5 @@
+---
+"@hashintel/petrinaut": patch
+---
+
+The place, transition, component-instance, and type properties panels display and allow editing of the element's optional `description`.

.claude/skills/publishing-packages

@@ -0,0 +1 @@
+../../.agents/skills/publishing-packages

.claude/skills/skill-rules.json

@@ -214,6 +214,33 @@
       "blockMessage": "Skill is required to proceed",
       "skipConditions": {}
     },
+    "publishing-packages": {
+      "type": "domain",
+      "enforcement": "suggest",
+      "priority": "high",
+      "description": "Conventions for publishing npm packages from this repository, including when a PR needs a changeset and how to write one. Use when adding or editing a changeset, versioning or releasing a package, or deciding whether a change to a publishable library needs a changelog entry.",
+      "promptTriggers": {
+        "keywords": [
+          "changeset",
+          "changelog",
+          "npm publish",
+          "release",
+          "version bump"
+        ],
+        "intentPatterns": [
+          "\\b(add|write|create|edit|split)\\b.*?\\bchangesets?\\b",
+          "\\b(publish|release|version)\\b.*?\\bpackages?\\b"
+        ]
+      },
+      "fileTriggers": {
+        "include": [],
+        "exclude": [],
+        "content": [],
+        "create-only": false
+      },
+      "blockMessage": "Skill is required to proceed",
+      "skipConditions": {}
+    },
     "rust-coding-style": {
       "type": "domain",
       "enforcement": "suggest",

apps/petrinaut-website/scripts/generate-example-artifacts.ts

@@ -18,7 +18,6 @@ import {
   exampleCatalog,
   type ExampleCatalogEntry,
 } from "../src/examples/catalog-metadata.ts";
-import { normalizeExampleDefinition } from "../src/examples/normalize-example.ts";
 
 const scriptDirectory = dirname(fileURLToPath(import.meta.url));
 const examplesDirectory = resolve(scriptDirectory, "../src/examples");
@@ -33,8 +32,8 @@ const readModelFile = async (slug: string): Promise<SDCPN> => {
   if (!parsed.ok) {
     throw new Error(`${slug}: ${parsed.error}`);
   }
-  const { title: _title, ...rawDefinition } = parsed.sdcpn;
-  return normalizeExampleDefinition(slug, rawDefinition);
+  const { title: _title, ...definition } = parsed.sdcpn;
+  return definition;
 };
 
 const loadDefinition = (entry: ExampleCatalogEntry): Promise<SDCPN> => {

apps/petrinaut-website/src/examples/catalog.ts

@@ -16,7 +16,6 @@ import {
   type ExampleSlug,
   type ModelFileExampleSlug,
 } from "./catalog-metadata";
-import { normalizeExampleDefinition } from "./normalize-example";
 
 export {
   exampleCatalog,
@@ -88,8 +87,8 @@ const loadModelFile = async (slug: ModelFileExampleSlug): Promise<SDCPN> => {
     throw new Error(parsed.error);
   }
 
-  const { title: _title, ...rawDefinition } = parsed.sdcpn;
-  return normalizeExampleDefinition(slug, rawDefinition);
+  const { title: _title, ...definition } = parsed.sdcpn;
+  return definition;
 };
 
 const loadDefinition = async (entry: ExampleCatalogEntry): Promise<SDCPN> => {

apps/petrinaut-website/src/examples/models/gases-1-pn-consumption-trigger.json

@@ -3,6 +3,7 @@
     {
       "id": "place__idle_tankers",
       "name": "IdleTankers",
+      "description": "Tankers parked at the depot and free to be dispatched. Dispatch takes one; unloading returns it.",
       "colorId": null,
       "dynamicsEnabled": false,
       "differentialEquationId": null,
@@ -13,6 +14,7 @@
     {
       "id": "place__loads_delivered",
       "name": "LoadsDelivered",
+      "description": "Cumulative count of tanker deliveries unloaded at a customer.",
       "colorId": null,
       "dynamicsEnabled": false,
       "differentialEquationId": null,
@@ -23,6 +25,7 @@
     {
       "id": "place__s1_order_placed",
       "name": "SteadyNitrogenOrderPlaced",
+      "description": "An open order from the steady nitrogen customer, waiting for a tanker. At most one is open at a time because raising an order also takes the order permit.",
       "colorId": null,
       "dynamicsEnabled": false,
       "differentialEquationId": null,
@@ -33,6 +36,7 @@
     {
       "id": "place__s1_order_permits",
       "name": "SteadyNitrogenOrderPermits",
+      "description": "The single permit that lets the steady nitrogen customer have one order open at a time. Raising an order takes it; unloading the delivery hands it back.",
       "colorId": null,
       "dynamicsEnabled": false,
       "differentialEquationId": null,
@@ -43,6 +47,7 @@
     {
       "id": "place__s1_on_route",
       "name": "SteadyNitrogenOnRoute",
+      "description": "A dispatched tanker travelling to the steady nitrogen customer with a 12-unit load.",
       "colorId": null,
       "dynamicsEnabled": false,
       "differentialEquationId": null,
@@ -53,6 +58,7 @@
     {
       "id": "place__s1_vented",
       "name": "SteadyNitrogenVented",
+      "description": "Cumulative units of product the steady nitrogen customer lost through the relief valve because the tank was full.",
       "colorId": null,
       "dynamicsEnabled": false,
       "differentialEquationId": null,
@@ -63,6 +69,7 @@
     {
       "id": "place__s1_line_running",
       "name": "SteadyNitrogenLineRunning",
+      "description": "Marker token present while the production line of the steady nitrogen customer is running on gas from the tank.",
       "colorId": null,
       "dynamicsEnabled": false,
       "differentialEquationId": null,
@@ -73,6 +80,7 @@
     {
       "id": "place__s1_line_stopped",
       "name": "SteadyNitrogenLineStopped",
+      "description": "Marker token present while the line of the steady nitrogen customer is stopped because the tank is empty.",
       "colorId": null,
       "dynamicsEnabled": false,
       "differentialEquationId": null,
@@ -83,6 +91,7 @@
     {
       "id": "place__s1_stockouts",
       "name": "SteadyNitrogenStockouts",
+      "description": "Cumulative count of times the tank of the steady nitrogen customer ran dry and stopped the line.",
       "colorId": null,
       "dynamicsEnabled": false,
       "differentialEquationId": null,
@@ -93,6 +102,7 @@
     {
       "id": "place__s1_consumed",
       "name": "SteadyNitrogenConsumed",
+      "description": "Cumulative units drawn by the process of the steady nitrogen customer.",
       "colorId": null,
       "dynamicsEnabled": false,
       "differentialEquationId": null,
@@ -103,6 +113,7 @@
     {
       "id": "place__s1_evaporated",
       "name": "SteadyNitrogenEvaporated",
+      "description": "Cumulative units lost to boil-off from the cryogenic tank of the steady nitrogen customer.",
       "colorId": null,
       "dynamicsEnabled": false,
       "differentialEquationId": null,
@@ -113,6 +124,7 @@
     {
       "id": "place__s1_contents",
       "name": "SteadyNitrogenContents",
+      "description": "Units of liquid in the tank of the steady nitrogen customer. Draw and boil-off take one at a time and a delivery adds 12; Contents plus Ullage is the tank's capacity.",
       "colorId": null,
       "dynamicsEnabled": false,
       "differentialEquationId": null,
@@ -123,6 +135,7 @@
     {
       "id": "place__s1_ullage",
       "name": "SteadyNitrogenUllage",
+      "description": "Empty space in the tank of the steady nitrogen customer, in units. Every unit drawn, boiled off, or vented frees one; a delivery needs 12 free units to unload.",
       "colorId": null,
       "dynamicsEnabled": false,
       "differentialEquationId": null,
@@ -133,6 +146,7 @@
     {
       "id": "place__s1_units_drawn_since_order",
       "name": "SteadyNitrogenUnitsDrawnSinceOrder",
+      "description": "Counter of units the steady nitrogen customer has drawn since the last order was raised. Reaching 8 raises the next order, so ordering follows consumption rather than tank level.",
       "colorId": null,
       "dynamicsEnabled": false,
       "differentialEquationId": null,
@@ -145,6 +159,7 @@
     {
       "id": "transition__s1_draw",
       "name": "Draw a unit (SteadyNitrogen)",
+      "description": "The process of the steady nitrogen customer draws one unit from the tank into Consumed, freeing one unit of ullage and advancing the units-drawn counter. Enabled only while draw_enabled is set, so the shut-plant scenario can switch consumption off.",
       "inputArcs": [
         {
           "placeId": "place__s1_contents",
@@ -175,6 +190,7 @@
     {
       "id": "transition__s1_boil_off",
       "name": "Boil off a unit (SteadyNitrogen)",
+      "description": "Heat leak evaporates one unit from the tank of the steady nitrogen customer into Evaporated, freeing one unit of ullage. Runs whether or not the customer is drawing.",
       "inputArcs": [
         {
           "placeId": "place__s1_contents",
@@ -201,6 +217,7 @@
     {
       "id": "transition__s1_raise_order",
       "name": "Raise an order, 8 units drawn (SteadyNitrogen)",
+      "description": "Places an order for the steady nitrogen customer once 8 units have been drawn since the last order, consuming the counter and the single order permit.",
       "inputArcs": [
         {
           "placeId": "place__s1_units_drawn_since_order",
@@ -228,6 +245,7 @@
     {
       "id": "transition__s1_dispatch",
       "name": "Dispatch a tanker (SteadyNitrogen)",
+      "description": "Pairs the open order of the steady nitrogen customer with an idle tanker and sends it on route.",
       "inputArcs": [
         {
           "placeId": "place__s1_order_placed",
@@ -255,6 +273,7 @@
     {
       "id": "transition__s1_arrive",
       "name": "Unload the tanker (SteadyNitrogen)",
+      "description": "The tanker arrives at the steady nitrogen customer and discharges 12 units into the tank, which must have 12 units of ullage to take them. Returns the order permit and the tanker to the depot and counts a delivery.",
       "inputArcs": [
         {
           "placeId": "place__s1_on_route",
@@ -294,6 +313,7 @@
     {
       "id": "transition__s1_vent",
       "name": "Vent through the relief valve (SteadyNitrogen)",
+      "description": "With no ullage left in the tank of the steady nitrogen customer, boil-off gas has nowhere to go: one unit is vented and one unit of ullage is left free.",
       "inputArcs": [
         {
           "placeId": "place__s1_contents",
@@ -325,6 +345,7 @@
     {
       "id": "transition__s1_stop_line",
       "name": "Stop the line (SteadyNitrogen)",
+      "description": "When the tank of the steady nitrogen customer is empty (inhibitor arc on Contents) the running line stops and a stockout is counted.",
       "inputArcs": [
         {
           "placeId": "place__s1_line_running",
@@ -356,6 +377,7 @@
     {
       "id": "transition__s1_resume_line",
       "name": "Resume the line (SteadyNitrogen)",
+      "description": "The stopped line of the steady nitrogen customer restarts as soon as the read arc sees product back in the tank.",
       "inputArcs": [
         {
           "placeId": "place__s1_line_stopped",
@@ -482,5 +504,6 @@
   "meta": {
     "generator": "Petrinaut"
   },
-  "title": "Gases 1 — plain net, one customer (consumption trigger)"
+  "title": "Gases 1 — plain net, one customer (consumption trigger)",
+  "description": "The one-customer plain net with a different ordering policy: an order is raised after 8 units have been drawn rather than when the tank level drops below a trigger. Boil-off drains the tank without advancing the counter, so a shut plant can run dry before an order is ever placed."
 }