From 14bd75d029157f1f897aae106b5a92b9934a6f9f Mon Sep 17 00:00:00 2001
From: Chris Feijoo <chris@kube.io>
Date: Fri, 28 Aug 2026 00:30:55 +0200
Subject: [PATCH 1/3] FE-1532: Track a launch config for the Petrinaut dev
 servers

---
 .claude/launch.json | 30 ++++++++++++++++++++++++++++++
 1 file changed, 30 insertions(+)
 create mode 100644 .claude/launch.json

diff --git a/.claude/launch.json b/.claude/launch.json
new file mode 100644
index 00000000000..144ce4ba73f
--- /dev/null
+++ b/.claude/launch.json
@@ -0,0 +1,30 @@
+{
+  "version": "0.0.1",
+  "configurations": [
+    {
+      "name": "@hashintel/petrinaut (storybook)",
+      "runtimeExecutable": "yarn",
+      "runtimeArgs": ["workspace", "@hashintel/petrinaut", "dev"],
+      "port": 6006
+    },
+    {
+      "name": "@apps/petrinaut-website",
+      "runtimeExecutable": "yarn",
+      "runtimeArgs": ["workspace", "@apps/petrinaut-website", "dev"],
+      "port": 5173
+    },
+    {
+      "name": "@apps/petrinaut-docs",
+      "runtimeExecutable": "yarn",
+      "runtimeArgs": [
+        "exec",
+        "turbo",
+        "run",
+        "dev",
+        "--filter",
+        "@apps/petrinaut-docs"
+      ],
+      "port": 4321
+    }
+  ]
+}

From fe2793669498cd9cc775d4c9f306d51942b1150b Mon Sep 17 00:00:00 2001
From: Chris Feijoo <chris@kube.io>
Date: Mon, 31 Aug 2026 16:55:50 +0200
Subject: [PATCH 2/3] FE-1532: Let the preview reassign a busy port

---
 .claude/launch.json | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/.claude/launch.json b/.claude/launch.json
index 144ce4ba73f..b41fd39952d 100644
--- a/.claude/launch.json
+++ b/.claude/launch.json
@@ -5,13 +5,15 @@
       "name": "@hashintel/petrinaut (storybook)",
       "runtimeExecutable": "yarn",
       "runtimeArgs": ["workspace", "@hashintel/petrinaut", "dev"],
-      "port": 6006
+      "port": 6006,
+      "autoPort": true
     },
     {
       "name": "@apps/petrinaut-website",
       "runtimeExecutable": "yarn",
       "runtimeArgs": ["workspace", "@apps/petrinaut-website", "dev"],
-      "port": 5173
+      "port": 5173,
+      "autoPort": true
     },
     {
       "name": "@apps/petrinaut-docs",
@@ -24,7 +26,8 @@
         "--filter",
         "@apps/petrinaut-docs"
       ],
-      "port": 4321
+      "port": 4321,
+      "autoPort": true
     }
   ]
 }

From 77cc4534cae7173d1f3b0beef340a0e6caf96181 Mon Sep 17 00:00:00 2001
From: Chris Feijoo <chris@kube.io>
Date: Mon, 31 Aug 2026 17:18:26 +0200
Subject: [PATCH 3/3] FE-1532: Let the Petrinaut dev servers take their port
 from the environment

---
 apps/petrinaut-docs/package.json         | 2 +-
 apps/petrinaut-docs/turbo.json           | 4 +++-
 apps/petrinaut-website/vite.config.ts    | 2 ++
 libs/@hashintel/petrinaut/scripts/dev.sh | 2 +-
 4 files changed, 7 insertions(+), 3 deletions(-)

diff --git a/apps/petrinaut-docs/package.json b/apps/petrinaut-docs/package.json
index 52ae7ec1f23..05d336031fb 100644
--- a/apps/petrinaut-docs/package.json
+++ b/apps/petrinaut-docs/package.json
@@ -7,7 +7,7 @@
   "type": "module",
   "scripts": {
     "build": "astro build",
-    "dev": "astro dev",
+    "dev": "astro dev --port ${PORT:-4321}",
     "lint:tsc": "astro check --minimumSeverity error",
     "preview": "astro preview",
     "sync:bundle": "node scripts/sync-bundle.mjs"
diff --git a/apps/petrinaut-docs/turbo.json b/apps/petrinaut-docs/turbo.json
index cd13dfbb0f8..e2962ab2b4f 100644
--- a/apps/petrinaut-docs/turbo.json
+++ b/apps/petrinaut-docs/turbo.json
@@ -24,7 +24,9 @@
     "dev": {
       "cache": false,
       "persistent": true,
-      "dependsOn": ["sync:bundle"]
+      "dependsOn": ["sync:bundle"],
+      // The Claude Code preview passes the port to serve on.
+      "env": ["PORT"]
     }
   }
 }
diff --git a/apps/petrinaut-website/vite.config.ts b/apps/petrinaut-website/vite.config.ts
index ff28dedd11d..c57e521e885 100644
--- a/apps/petrinaut-website/vite.config.ts
+++ b/apps/petrinaut-website/vite.config.ts
@@ -84,6 +84,8 @@ export default defineConfig(({ mode }) => {
       port: process.env.PORT ? Number(process.env.PORT) : 4173,
     },
     server: {
+      /** the Claude Code preview may provide a PORT to run on */
+      port: process.env.PORT ? Number(process.env.PORT) : 5173,
       proxy: {
         "/api/petrinaut-opt": {
           target: process.env.PETRINAUT_OPT_ORIGIN ?? "http://127.0.0.1:4004",
diff --git a/libs/@hashintel/petrinaut/scripts/dev.sh b/libs/@hashintel/petrinaut/scripts/dev.sh
index a83cf14a51a..ed7a5c52c43 100644
--- a/libs/@hashintel/petrinaut/scripts/dev.sh
+++ b/libs/@hashintel/petrinaut/scripts/dev.sh
@@ -9,4 +9,4 @@ set -euo pipefail
 cd "$(dirname "$0")/.."
 . ../../@local/petrinaut-optimizer-client/scripts/optimizer-service.sh
 optimizer_service_parse "$@"
-run_dev_server yarn storybook dev ${OPTIMIZER_FORWARDED[@]+"${OPTIMIZER_FORWARDED[@]}"}
+run_dev_server yarn storybook dev -p "${PORT:-6006}" ${OPTIMIZER_FORWARDED[@]+"${OPTIMIZER_FORWARDED[@]}"}