FE-1456: Add a usage manual for the Python bindings

[kube]

🌟 What is the purpose of this PR?

Implements FE-1456: the CLI has a usage manual attached to its layer, the Python bindings had only a package README and docstrings. A caller who wants to drive Petrinaut from Python now has the same kind of guide in the docs site, attached to the python-bindings layer.

Top of stack #9226, on FE-1415.

🔗 Related links

• FE-1456 (internal): this PR
• FE-1270 (internal): the package this documents
• FE-1413 (internal): the CLI manual this is modelled on

🔍 What does this change?

One new authored page, content/python-bindings/usage-manual.mdx, plus a one-line cross-link from the CLI manual. Sections: depending on the package, opening a session, run requests, optimization studies, errors, timeouts and shutdown, end to end.

It documents the Python layer and links to the CLI manual for wire-level detail rather than repeating it. Every symbol, default, and limit was checked against the source, which corrected several claims the package README implies:

Claim	What the source says
Line caps	The bindings enforce 8 MiB on bootstrap and protocol lines, not the CLI's 10 MiB request cap
Error hierarchy	PetrinautRunError extends RuntimeError directly; only PetrinautProtocolError extends PetrinautClientError
seedsPerTrial	Defaults to 1 when absent or when study is not an object, and booleans are rejected
Response deadline	240 s per seed, so a two-seed study allows 480 s
Child environment	Only PETRINAUT_CLI_NODE_OPTIONS is forwarded, under the child's NODE_OPTIONS
Concurrency	The lock guards start and close only, so one session serves one caller

Pre-Merge Checklist 🚀

🚢 Has this modified a publishable library?

This PR:

• modifies a workspace but not a publishable library

📜 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?

lint:arch-docs validates attachTo and every doc:/layer: target, so a stale link fails the build. Authored pages go from 15 to 16.

❓ How to test this?

1. turbo run dev --filter @apps/petrinaut-docs
2. Open /architecture/python-bindings/usage-manual: it appears under the python-bindings layer beside its Overview, and its links to the CLI manual resolve.

🐾 Next steps

The CLI manual keeps its em dashes, so the two pages differ in punctuation style. Bringing the older page in line with the prose rules is a separate cleanup.

🤖 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 21, 2026 12:17am
petrinaut	Ready	Preview	Aug 21, 2026 12:17am
petrinaut-docs	Ready	Preview	Aug 21, 2026 12:17am

1 Skipped Deployment

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