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

[kube]

🌟 What is the purpose of this PR?

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.

This replaces #9266, which GitHub closed when its base branch was deleted by the
merge of #9264. The branch and its commits are unchanged; only the pull request
is new. FE-1415 (#9265) has merged, so this PR is based on main, with
FE-1457 (#9267) above it.

🔗 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, covers depending on the package, opening a session, run requests, optimization studies, errors, timeouts and shutdown, with an end-to-end example. It documents the Python layer and links to the CLI manual for the protocol detail rather than repeating it. In the other direction, the CLI manual's "Driving the CLI from Python" section replaces its hand-written subprocess wrapper with a short example that uses the bindings.

Every symbol, default and limit was checked against the source. Claims the package README implies, which the manual corrects:

Claim	What the source says
Line caps	The bindings enforce their own 8 MiB cap on bootstrap and protocol lines; the CLI's 10 MiB request cap is a separate limit
Error hierarchy	PetrinautRunError extends RuntimeError directly; only PetrinautProtocolError extends PetrinautClientError
seedsPerTrial	Defaults to 1 when the study omits it; the generated model bounds it to the CLI's 1–100 range
Response deadline	240 s per seed, so a two-seed study allows 480 s
Child environment	Only PETRINAUT_CHILD_NODE_OPTIONS is forwarded, as the child's NODE_OPTIONS
Concurrency	The lock guards start and close only, so one session serves one caller

The manual states each failure separately: a non-finite objective raises PetrinautRunError and leaves the session usable; a non-numeric one fails schema validation and raises PetrinautProtocolError; request params that fail JSON serialization raise PetrinautClientError before anything is written. close() may be called from another thread. The package's one runtime dependency is pydantic.

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.

❓ 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 26, 2026 4:33pm
petrinaut	Ready	Preview	Aug 26, 2026 4:33pm
petrinaut-docs	Ready	Preview	Aug 26, 2026 4:33pm

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
hashdotdesign-tokens	Ignored	Preview	Aug 26, 2026 4:33pm

[cursor]

PR Summary

Low Risk
Documentation-only changes to arch-docs; no application or library runtime code is modified.

Overview
Adds a usage manual for the python-bindings layer (python-bindings/usage-manual.mdx) on the architecture docs site, parallel to the CLI manual. It documents sessions (PetrinautSession / OptimizationSession), run and optimization calls, exception behavior, timeouts, child-process hardening, and an end-to-end example, and defers protocol field detail to the CLI manual via doc: links.

The CLI manual’s Driving the CLI from Python section no longer embeds a hand-written subprocess wrapper; it points readers to the bindings package and its manual and shows a short OptimizationSession example (including Optuna-oriented describe() / objective() wording).

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