FE-1532: Track a launch config for the Petrinaut dev servers

[kube]

Important

Dev tooling, nothing user-facing.

Summary

Before this PR, no launch configuration was tracked, so every agent session rediscovered the Petrinaut dev servers and their ports by hand. The docs site has to start through Turborepo, which regenerates the architecture bundle first, and running the package script alone skips that step.

Adds a launch configuration naming the three servers, and lets each of them take its port from the environment so a preview can move off a port that is already busy.

Links

• Ticket FE-1532

Changes

Launch configuration

• Three environments, each named after its package

  Storybook for @hashintel/petrinaut, the demo site for @apps/petrinaut-website, the documentation site for @apps/petrinaut-docs.

• Documentation entry starts through Turborepo

  sync:bundle regenerates the architecture bundle before Astro serves it.

• Every entry sets autoPort

  Preview can claim another port when the declared one is taken, which happens whenever a second Storybook already serves 6006.

Dev servers

• Storybook, the demo site and the documentation site read their port from PORT

  None of the three did, so autoPort had nothing to steer and the preview waited on a port that never opened.
  Storybook and Astro take -p ${PORT:-<default>}; the demo site reads server.port in vite.config.ts, matching the preview block already there.

• Documentation task declares PORT in Turborepo

  Strict environment mode drops any variable a task does not declare.

Next steps

• A petrinaut-optimization entry runs the demo site against the local optimizer service

  Covers the whole loop, browser through to the CLI subprocess, and was verified end to end.
  Held until the launcher forwards --port and --strictPort to Vite, tracked as FE-1529.

Test coverage

• Manual port checks:

  PORT=7801, 7802 and 7803 bind Storybook, the demo site and the documentation site on those ports.
  Each server still falls back to its declared default when PORT is unset.

• Existing @apps/petrinaut-website and @apps/petrinaut-docs jobs:

  Build and typecheck both packages.

How to test

• PORT=7801 yarn workspace @hashintel/petrinaut dev
• Expect Storybook on 7801
• yarn workspace @hashintel/petrinaut dev
• Expect Storybook on 6006
• PORT=7803 yarn exec turbo run dev --filter @apps/petrinaut-docs
• Expect documentation site on 7803

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
hash	Ready	Preview	Sep 3, 2026 6:45pm UTC
petrinaut	Ready	Preview	Sep 3, 2026 6:45pm UTC
petrinaut-docs	Ready	Preview	Sep 3, 2026 6:45pm UTC

1 Skipped Deployment

Project	Deployment	Actions	Updated
hashdotdesign-tokens	Ignored	Preview	Sep 3, 2026 6:45pm UTC

[cursor]

PR Summary

Low Risk
Dev-only launcher and local port configuration; no user-facing runtime or security-sensitive paths.

Overview
Adds .claude/launch.json so Claude Code can start the three Petrinaut dev targets without rediscovering commands and ports: Storybook (@hashintel/petrinaut, 6006), the demo site (@apps/petrinaut-website, 5173), and docs via Turborepo (@apps/petrinaut-docs, 4321). Each entry sets autoPort so previews can move off a busy default port.

Wires PORT through the actual servers so that behavior works: Storybook gets -p ${PORT:-6006} in dev.sh, Astro docs use astro dev --port ${PORT:-4321}, and the website Vite server.port now mirrors the existing preview block (PORT or 5173). Docs turbo.json declares PORT on the dev task so Turborepo’s strict env does not strip it.

^{Reviewed by Cursor Bugbot for commit 77cc453. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 4a55526. Configure here.}

[Copilot]

🟢 Approval recommended

All reviewed changes are focused and no unresolved issues were identified.

Pull request overview

Adds launch configurations for Petrinaut development servers with configurable ports.

Changes:

• Adds launch entries for Storybook, the demo website, and documentation.
• Reads PORT while preserving default ports.
• Passes PORT through Turborepo for documentation.

File summaries

File	Description
libs/@hashintel/petrinaut/scripts/dev.sh	Configures Storybook’s port.
apps/petrinaut-website/vite.config.ts	Configures Vite’s development port.
apps/petrinaut-docs/turbo.json	Allows PORT through Turborepo.
apps/petrinaut-docs/package.json	Configures Astro’s development port.
.claude/launch.json	Defines three auto-port launch configurations.

Review details

• Files reviewed: 5/5 changed files
• Comments generated: 0
• Review effort level: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.