FE-1413: Cover petrinaut-cli in the architecture docs and attach a usage manual

[kube]

🌟 What is the purpose of this PR?

The architecture docs covered petrinaut-core and petrinaut only. The CLI's long-form documentation lived in package-local markdown that the docs site does not publish. This PR registers the CLI in the architecture bundle and moves its documentation into an authored usage manual attached to the new cli layer.

Stack #9226: FE-1410, FE-1411, and FE-1408 have merged, so this PR now sits on main. Above it: FE-1270 (Python bindings) → FE-1412.

🔗 Related links

• FE-1413 (internal): this PR

🔍 What does this change?

Architecture bundle

• Registers @hashintel/petrinaut-cli and declares three layers from README frontmatter: cli in src/, cli.commands in src/commands/, and cli.runtime in src/runtime/. The bundle reports 40 layers, 182 edges, and 421 files.
• Adds a rule that core must not import cli, and a diagram colour for the cli root.
• deriveAliases warns when a registered package exposes no importable entry points, because imports of such a package would be missing from the graph. Bin-only packages such as the CLI are exempt.
• @local/petrinaut-arch-docs takes a devDependency on @hashintel/petrinaut-cli. The docs-site CI job builds inside a turbo prune closure, which drops the CLI's sources without it.

Hand-written diagrams

• content/diagrams/ holds .d2 sources. The build renders each one to SVG beside the generated diagrams, and an authored page embeds one as ![alt](@diagrams/name.svg). An unknown name, or a name that collides with a generated diagram, fails the check.
• The manual uses two: one request through the CLI, and the optimization loop.
• Without the d2 renderer, an authored page drops the image the same way a generated page omits its diagram, and the .d2 source still ships.

Link and image rewriting

• doc:, layer:, @diagrams/ and image targets are rewritten in prose only. The page that documents these schemes shows them in examples, and rewriting an example published the resolved path instead of the syntax being taught.

Usage manual (content/cli/usage-manual.mdx, attached to cli)

• One reference for transports and model sources, the JSON-lines protocol, run requests, optimization studies including seeded runs per trial, and driving a study from Python with a stdlib subprocess wrapper. FE-1270 replaces that wrapper with the bindings package.
• Its "Where models and manifests come from" section is now the whole answer to that question: a model file is the editor's save format, and an optimization manifest is what the editor generates for an optimization experiment.

Package-local documents are deleted rather than redirected

• MODEL_EXAMPLES.md, OPTIMIZATION_INTEGRATION.md, and PYTHON_INTEGRATION.md are removed. README.md keeps a short description of the package and a link to the manual, and links elsewhere in the repository are updated, including the one in the editor's docs/examples.md.
• One fact from PYTHON_INTEGRATION.md that the manual lacked moved into it: every run starts from fresh simulation state, so repeating an identical request with the same seed returns the same result.

The examples/ directory is deleted

• Three of its documents are test infrastructure, not examples, so they move to libs/@hashintel/petrinaut-cli/test-fixtures/: sir-model.json and satellites-launcher.json (which transports.test.ts uses for its colored-token case), and supply-chain-profit-optimization.json. Four test files read them — transports.test.ts, optimization.test.ts, optimization-manifest.fixtures.ts, and the bindings' test_e2e_cli.py.
• deployment-pipeline.json, production-with-machine-failure.json, supply-chain-profit-model.json, supply-chain-with-disruption.json, and python_stdio.py are removed. Nothing reads them. The same models exist as TypeScript in petrinaut-core/src/examples/, which is what the editor and the core tests use.
• Three references go with them: the serve:example script, the COPY of supply-chain-profit-model.json into the petrinaut-opt image (no code in the repository reads that path), and the manifest pointer in apps/petrinaut-opt/README.md.
• Command examples in the manual, the CLI README, and the bindings' manual now use a neutral path such as ./my-model.json rather than a checked-in file.

Build fix

• arch-docs build used to warn that it was writing a bundle without rendered diagrams and then fail trying to render them, exiting 1 whenever d2 was unavailable. It now skips rendering in that mode and exits 0. The failure predates this PR; the flag it depends on is the one this PR extends to authored diagrams.
• The docs' own troubleshooting page (content/maintaining/running-locally.mdx) already tells readers the build only warns when d2 is absent. That is now true.

Pre-Merge Checklist 🚀

🚢 Has this modified a publishable library?

This PR:

• modifies a workspace but not a publishable library. It edits one link target in libs/@hashintel/petrinaut/docs/examples.md, which ships inside the publishable @hashintel/petrinaut; a link target needs no release, so there is no changeset.

📜 Does this require a change to the docs?

The changes in this PR:

• are docs. In-app user-guide behaviour is unchanged, and the docs-content test passes.

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

The changes in this PR:

• affected the execution graph, and the turbo.json's have been updated to reflect this
  • The new devDependency puts @hashintel/petrinaut-cli in the arch-docs package's graph, so the docs job's prune closure keeps the sources it scans.

🛡 What tests cover this?

• The arch-docs unit suite: 79 tests, four of them new — two for resolveDiagramImages, one for the no-renderer path, and one proving a documented example inside a code fence survives verbatim.
• lint:arch-docs, which fails on an unannotated file, an undeclared ancestor, a rule violation, or an unresolved doc:/layer: target.
• turbo run build --filter @apps/petrinaut-docs, which proves both pages and the diagrams render, and that every doc: and layer: link in them resolves.
• The CLI's own suite, 39 tests, against the relocated fixtures, plus the bindings' 24 (two of which spawn the built CLI end to end) and petrinaut-opt's 75.
• markdownlint, and a per-file check that nothing in the repository still references any deleted document or the old examples/ path.
• Both renderer paths were run by hand: with d2 present, three SVGs render and the manual references both authored diagrams; with mise off the path, the build exits 0, ships the .d2 sources, and the manual references no SVG.

❓ How to test this?

1. turbo run dev --filter @apps/petrinaut-docs
2. Open /architecture/cli: the layer page carries the three layers, the two hand-written diagrams, and a link to the usage manual.
3. `turbo run test:unit --filter @hashintel/petrinaut-cli exercises the relocated fixtures.

🤖 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 19, 2026 11:57pm
petrinaut	Ready	Preview	Aug 19, 2026 11:57pm
petrinaut-docs	Ready	Preview	Aug 19, 2026 11:57pm

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
hashdotdesign-tokens	Ignored	Preview	Aug 19, 2026 11:57pm

[cursor]

PR Summary

Low Risk
Changes are documentation, arch-docs generator behavior, and CI wiring; runtime CLI behavior is unchanged aside from doc accuracy fixes.

Overview
Architecture bundle now includes @hashintel/petrinaut-cli with layers cli, cli.commands, and cli.runtime (README frontmatter), a core must not import cli rule, and CLI styling in generated D2. AGENTS.md and maintaining pages require layer declarations when CLI structure changes.

Documentation moves replace MODEL_EXAMPLES.md, OPTIMIZATION_INTEGRATION.md, and PYTHON_INTEGRATION.md with usage-manual.mdx and model-examples.mdx under the cli layer. The CLI README.md is shortened and points at those pages; examples.md in the editor links to the usage manual instead of the old optimization doc. Supply-chain profit examples are corrected (replenishment_aggressiveness, Adjusted profit vs the optimization manifest’s reorder_threshold / Profit).

Arch-docs build adds content/diagrams/ (render to SVG, @diagrams/name.svg in MDX, collision checks with generated diagrams), resolveDiagramImages, and rewrites of doc: / layer: / @diagrams/ only outside code fences. When d2 is missing, the build writes the bundle without SVGs and skips render (exit 0) instead of failing. deriveAliases warns on packages with no importable exports (bin-only CLI exempt). Dev dependency on @hashintel/petrinaut-cli keeps prune CI closures scanning CLI sources.

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

[Copilot]

Pull request overview

Registers Petrinaut CLI in the architecture documentation and centralizes its usage documentation.

Changes:

• Adds CLI architecture layers, dependency rules, and diagram styling.
• Introduces an attached CLI usage manual and redirects existing documentation.
• Warns when registered libraries expose no importable entry points.

Reviewed changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
libs/@local/petrinaut-arch-docs/src/graph.ts	Adds missing-entry-point diagnostics.
libs/@local/petrinaut-arch-docs/src/emit/d2.ts	Adds CLI diagram styling.
libs/@local/petrinaut-arch-docs/content/cli/usage-manual.mdx	Provides the consolidated CLI manual.
libs/@local/petrinaut-arch-docs/architecture.config.ts	Registers the CLI and dependency rule.
libs/@hashintel/petrinaut/docs/examples.md	Updates the optimization documentation link.
libs/@hashintel/petrinaut-cli/src/runtime/README.md	Declares and documents the runtime layer.
libs/@hashintel/petrinaut-cli/src/commands/README.md	Declares and documents the commands layer.
libs/@hashintel/petrinaut-cli/src/cli.ts	Declares the CLI root layer.
libs/@hashintel/petrinaut-cli/README.md	Replaces duplicated reference material with a manual link.
libs/@hashintel/petrinaut-cli/PYTHON_INTEGRATION.md	Redirects optimization guidance to the manual.
libs/@hashintel/petrinaut-cli/OPTIMIZATION_INTEGRATION.md	Replaces moved content with a redirect stub.
libs/@hashintel/petrinaut-cli/MODEL_EXAMPLES.md	Updates the optimization manual reference.

---

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

[Copilot]

Pull request overview

Copilot reviewed 13 out of 14 changed files in this pull request and generated no new comments.

Suppressed comments (2)

libs/@local/petrinaut-arch-docs/content/cli/usage-manual.mdx:12

• This conflates the two transport lifecycles. Socket mode does not observe stdin; it waits for SIGINT/SIGTERM (see src/commands/serve.ts:147-169), whereas only stdio exits at EOF (src/commands/stdio.ts:128-132). A socket caller must not expect closing stdin to stop the server, so document the lifecycles separately.

and only then reports readiness on stderr. From that point it answers one
JSON-lines request at a time until stdin closes or it is signalled.

libs/@local/petrinaut-arch-docs/content/cli/usage-manual.mdx:261

• The documented build only creates dist/cli.js; this private workspace does not install a petrinaut executable on the caller's PATH. The existing integration launches node with that file (PYTHON_INTEGRATION.md:25-45), so the bare invocations at lines 44, 47, 50, and here fail after following this page's build step (the Python call raises FileNotFoundError). Either use node libs/@hashintel/petrinaut-cli/dist/cli.js consistently or document and use an actual installation/linking step.

            ["petrinaut", "serve", "--optimization", manifest_path, "--stdio"],

[Copilot]

Pull request overview

Copilot reviewed 13 out of 14 changed files in this pull request and generated no new comments.

Suppressed comments (1)

libs/@local/petrinaut-arch-docs/architecture.config.ts:54

• The CLI rejects every optimization source when --socket is selected (libs/@hashintel/petrinaut-cli/src/cli.ts:82-88), so this generated package description incorrectly says optimization studies are served over a Unix socket. This conflicts with the new usage manual's transport table and will mislead architecture-doc readers; distinguish the stdio-only optimization path from model runs.

        "JSON-lines CLI serving one compiled model per process: run requests and optimization studies over stdio or a Unix socket. No HTTP, no React.",

[Copilot]

Pull request overview

Copilot reviewed 13 out of 14 changed files in this pull request and generated no new comments.

Suppressed comments (1)

libs/@local/petrinaut-arch-docs/content/cli/usage-manual.mdx:12

• The socket transport does not observe stdin: serve() waits for SIGINT/SIGTERM (see src/commands/serve.ts:147-170), whereas only serveStdio() exits when stdin closes. As written, a socket-mode supervisor that closes stdin based on this lifecycle contract will leave the CLI running. Distinguish the two shutdown conditions explicitly.

and only then reports readiness on stderr. From that point it answers one
JSON-lines request at a time until stdin closes or it is signalled.

[Copilot]

Pull request overview

Copilot reviewed 16 out of 17 changed files in this pull request and generated no new comments.

Suppressed comments (2)

libs/@local/petrinaut-arch-docs/architecture.config.ts:54

• The CLI rejects every optimization source with --socket (libs/@hashintel/petrinaut-cli/src/cli.ts:78-84), and the usage manual correctly marks both optimization sources as stdio-only. This description instead says optimization studies run over stdio or a Unix socket; the same ambiguity appears in libs/@hashintel/petrinaut-cli/README.md:4-6 and src/README.md:6-7. Clarify in all three places that the socket transport supports model/run requests only.

        "JSON-lines CLI serving one compiled model per process: run requests and optimization studies over stdio or a Unix socket. No HTTP, no React.",

libs/@local/petrinaut-arch-docs/src/graph.ts:119

• The exemption checks for any bin, not a bin-only package. If a registered package exposes both a command and module exports but alias derivation yields no entries, this suppresses the warning even though imports of that package still disappear from the graph. Exempt only manifests that have bin and no exports.

  if (aliases.length === 0 && manifest.bin === undefined) {

[Copilot]

Pull request overview

Copilot reviewed 16 out of 17 changed files in this pull request and generated no new comments.

[Copilot]

Pull request overview

Copilot reviewed 34 out of 35 changed files in this pull request and generated no new comments.

Suppressed comments (2)

libs/@local/petrinaut-arch-docs/content/cli/usage-manual.mdx:307

• libs/@local/petrinaut-python does not exist in this repository, while the PR description says those bindings are upcoming in FE-1270. Consequently both examples in this section fail at from petrinaut import ... instead of documenting a usable interim wrapper. Keep this section based on the existing subprocess/JSON-lines client (for example petrinaut-cli/examples/python_stdio.py) until the bindings package lands.

## Driving the CLI from Python

The [`@local/petrinaut-python`](https://github.com/hashintel/hash/tree/main/libs/@local/petrinaut-python)
bindings wrap the protocol: a session owns one CLI process, requests are
methods, and error frames become exceptions. Running a model:

libs/@hashintel/petrinaut-cli/src/runtime/optimization.ts:273

• The online update is not a numerically valid mean for all finite objectives: with replicates Number.MAX_VALUE and -Number.MAX_VALUE, the true mean is 0, but replicate.objective - mean overflows and this rejects the trial. The new test at optimization.test.ts:464-479 explicitly codifies that incorrect result. Compute the weighted terms before adding (for example, mean * (index / (index + 1)) + replicate.objective / (index + 1)) and update that test to expect zero, so valid finite replicate sets produce their documented mean.

      const objective = replicates.reduce(
        (mean, replicate, index) =>
          mean + (replicate.objective - mean) / (index + 1),
        0,
      );

[Copilot]

Pull request overview

Copilot reviewed 34 out of 35 changed files in this pull request and generated 1 comment.

Suppressed comments (2)

libs/@local/petrinaut-arch-docs/content/cli/usage-manual.mdx:307

• This manual documents a package and API that are not present in the repository: there is no libs/@local/petrinaut-python, PetrinautSession, or OptimizationSession, so the link is a 404 and both examples fail at import time. The PR description also identifies the bindings as upcoming FE-1270. Replace this section with the current subprocess/JSON-lines wrapper (the existing PYTHON_INTEGRATION.md is available) or explicitly mark the bindings as forthcoming rather than presenting them as usable now.

The [`@local/petrinaut-python`](https://github.com/hashintel/hash/tree/main/libs/@local/petrinaut-python)
bindings wrap the protocol: a session owns one CLI process, requests are
methods, and error frames become exceptions. Running a model:

libs/@local/petrinaut-arch-docs/src/build.ts:275

• buildBundle documents that includeDiagrams: false makes pages omit image references (src/build.ts:75-77), but this unconditional rewrite still emits diagrams/*.svg links in authored pages. A caller requesting a no-diagram bundle therefore receives an authored usage page pointing at SVGs it explicitly said would not exist. Gate authored diagram embedding on includeDiagrams and omit these image nodes in that mode.

    const illustrated = resolveDiagramImages(
      imported.contents,
      slug,
      authoredDiagramNames,
    );

[Copilot]

Pull request overview

Copilot reviewed 36 out of 37 changed files in this pull request and generated 1 comment.

Suppressed comments (2)

libs/@hashintel/petrinaut-cli/src/runtime/optimization.ts:273

• This online update overflows when finite objectives have opposite signs: for [Number.MAX_VALUE, -Number.MAX_VALUE], replicate.objective - mean becomes -Infinity, so the trial is rejected even though its required arithmetic mean is 0. The new test currently codifies that incorrect result. Use a sign-aware online mean (the weighted form mean * index / (index + 1) + value / (index + 1) when signs differ) and update the extreme-value test to expect the finite mean.

      const objective = replicates.reduce(
        (mean, replicate, index) =>
          mean + (replicate.objective - mean) / (index + 1),
        0,
      );

libs/@local/petrinaut-arch-docs/src/emit/mdx.ts:230

• This raw replacement also transforms references inside fenced and inline code. For example, the newly added snippet at content/maintaining/declaring-layers.mdx:110-112 is emitted with a page-relative path instead of the documented @diagrams/... authoring syntax. Exclude Markdown/MDX code regions from resolution and add a fenced-code test.

[Copilot]

Pull request overview

Copilot reviewed 36 out of 37 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 26 out of 27 changed files in this pull request and generated no new comments.

[Copilot]

Pull request overview

Copilot reviewed 27 out of 28 changed files in this pull request and generated no new comments.

[Copilot]

Pull request overview

Copilot reviewed 28 out of 29 changed files in this pull request and generated no new comments.

Suppressed comments (2)

libs/@local/petrinaut-arch-docs/src/emit/mdx.ts:142

• CommonMark code can also use ~~~ fences and code spans delimited by two or more backticks, but this splitter protects only triple-backtick fences and single-backtick spans. For example, [text](doc:missing) inside a ~~~md block is still rewritten and reported as unresolved, so authored examples can be corrupted or make lint:arch-docs fail. Parse Markdown/MDX nodes or scan matching fence/span delimiter lengths, and cover both cases in the tests.

    .split(/(```[\s\S]*?```|`[^`\n]*`)/gu)

libs/@local/petrinaut-arch-docs/content/cli/model-examples.mdx:12

• The PR and the CLI README advertise a complete request for every model in examples/, but this page has no sections for examples/deployment-pipeline.json or examples/production-with-machine-failure.json; the usage manual repeats the same promise at lines 366–369. Add runnable requests for those two models, or narrow all of these claims if they are intentionally excluded.

The models below ship in
[`libs/@hashintel/petrinaut-cli/examples/`](https://github.com/hashintel/hash/tree/main/libs/@hashintel/petrinaut-cli/examples).
Each section gives a complete `run` request for one of them, so the differences
between an uncolored place, a colored place, and a model with an objective
metric are visible side by side.

[Copilot]

Pull request overview

Copilot reviewed 28 out of 29 changed files in this pull request and generated no new comments.

Suppressed comments (2)

libs/@local/petrinaut-arch-docs/content/cli/usage-manual.mdx:164

• The same seed alone does not guarantee the same result: changing parameters, initial state, metrics, or run limits changes the response. The deterministic behavior verified by the compiled-model contract applies to otherwise identical run configurations, so qualify this statement to avoid promising reproducibility across different requests.

Every `run` starts from fresh simulation state, so two requests with the same
seed return the same result.

libs/@local/petrinaut-arch-docs/content/cli/model-examples.mdx:12

• This page says it provides a complete run request for every model in examples/, matching the PR description, but the directory also contains production-with-machine-failure.json and deployment-pipeline.json and neither has a section here. Add complete requests for those two models (or explicitly narrow the documented scope); otherwise the new consolidated reference is incomplete.

Each section gives a complete `run` request for one of them, so the differences
between an uncolored place, a colored place, and a model with an objective
metric are visible side by side.

[Copilot]

Pull request overview

Copilot reviewed 38 out of 42 changed files in this pull request and generated no new comments.

Suppressed comments (1)

libs/@local/petrinaut-arch-docs/content/index.mdx:76

• The PR description says the deleted MODEL_EXAMPLES.md content moved to a second authored page, content/cli/model-examples.mdx, but this checkout contains only content/cli/usage-manual.mdx and deletes every file under petrinaut-cli/examples/. As a result, the promised per-model requests and several runnable model examples are removed rather than published in the architecture bundle. Add the authored model-examples page (and retain or relocate the models it documents), or stop deleting the source material.

`@hashintel/petrinaut-cli` is the headless JSON-lines CLI that scripts and the
Python optimizer service drive; its [usage manual](doc:cli/usage-manual) covers
the transports, the protocol, and optimization studies.

[YannisZa]

Love this @kube! Minor comment on the testing instructions:

turbo run test:unit --filter @hashintel/petrinaut-cli --filter @local/petrinaut-python

gave me back

× No package found with name '@local/petrinaut-python' in workspace

I couldn't find any petrinaut-python app or lib on the branch.

[kube]

Love this @kube! Minor comment on the testing instructions:

turbo run test:unit --filter @hashintel/petrinaut-cli --filter @local/petrinaut-python

gave me back

× No package found with name '@local/petrinaut-python' in workspace

I couldn't find any petrinaut-python app or lib on the branch.

Yes sorry, indeed it comes in the next PR.