FE-1529: Document the local optimizer loop

[kube]

🌟 What is the purpose of this PR?

Documents yarn dev:petrinaut-optimization, the one command that runs Petrinaut against the real optimizer service without any HASH infrastructure. Only the website README described it; this adds it to the architecture docs, attached to the optimizer layer. Stacked on #9371.

🔗 Related links

• FE-1529 (internal)
• Base PR: FE-1518: Optimization constraints as shared HIR expressions #9371

🚫 Blocked by

• FE-1518: Optimization constraints as shared HIR expressions #9371 and the stack below it merging first

🔍 What does this change?

• Adds libs/@local/petrinaut-arch-docs/content/optimizer/running-the-loop-locally.mdx, nested under the optimizer layer.
• The page lists the five steps the command runs: Docker image build for petrinaut-opt, a read-only container on 127.0.0.1:4004 with a /status health wait, the petrinaut dist build, the demo website with VITE_PETRINAUT_OPT_PROVIDER=service, and container teardown on exit.
• Explains why plain yarn dev shows no Optimizations view: the /optimization route gate and the null PetrinautOptimizationContext.
• Shows the request path (browser, Vite proxy at /api/petrinaut-opt/*, the service, one petrinaut serve subprocess per run) and links the subprocess-boundary and CLI pages.
• Covers the no-Docker flow (uvicorn on port 4004, the petrinaut executable on PATH) and when to prefer each flow.
• optimization-dev.mjs now forwards extra arguments to Vite, so yarn dev:petrinaut-optimization --port 5175 --strictPort pins the website port for tooling (e.g. an editor launch configuration).
• optimization-dev.mjs reuses an optimizer already serving on 127.0.0.1:4004 (e.g. the compose stack's) instead of failing on the port bind; teardown then leaves it alone.

Pre-Merge Checklist 🚀

🚢 Has this modified a publishable library?

This PR:

• does not modify any publishable blocks or libraries, or modifications do not need publishing

📜 Does this require a change to the docs?

The changes in this PR:

• require changes to docs which are made as part of this PR

🕸️ Does this require a change to the Turbo Graph?

The changes in this PR:

• do not affect the execution graph

🛡 What tests cover this?

• yarn workspace @local/petrinaut-arch-docs lint:arch-docs runs in CI and validates the page's doc: and layer: links.
• A full @apps/petrinaut-docs Astro build compiled the page before pushing.

❓ How to test this?

1. turbo run dev --filter @apps/petrinaut-docs, then open http://localhost:4321.
2. Open Architecture → Optimizer → "Running the loop locally".
3. To exercise what the page documents, run yarn dev:petrinaut-optimization from the repository root (Docker required) and open http://localhost:5173/optimization.
4. To check argument forwarding, add --port 5175 --strictPort and confirm Vite serves on 5175.

🤖 Generated with Claude Code

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
hash	Ready	Preview	Aug 28, 2026 12:29am
petrinaut	Ready	Preview	Aug 28, 2026 12:29am
petrinaut-docs	Ready	Preview	Aug 28, 2026 12:29am

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
hashdotdesign-tokens	Ignored	Preview	Aug 28, 2026 12:29am

[semgrep-code-hashintel]

Semgrep found 1 react-insecure-request finding:

• apps/petrinaut-website/scripts/optimization-dev.mjs
  • L51 - Triage

Unencrypted request over HTTP detected.

[kube]

Superseded by #9394, which carries the same documentation page and launcher changes plus removal of leftover launcher-owned containers (the "port is already allocated" failure), stacked on #9342 instead of the FE-1518 stack.