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.

FE-1415 (#9265) sits below in this stack and FE-1457 (#9267) above.

🔗 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 12:22pm
petrinaut	Ready	Preview	Aug 26, 2026 12:22pm
petrinaut-docs	Ready	Preview	Aug 26, 2026 12:22pm

1 Skipped Deployment

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

[cursor]

PR Summary

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

Overview
Adds a new python-bindings usage manual on the architecture docs site (content/python-bindings/usage-manual.mdx, attached to the python-bindings layer). It documents how to depend on @local/petrinaut-python, open PetrinautSession / OptimizationSession, run and optimization APIs, exceptions, timeouts, and shutdown, with protocol details deferred to the CLI manual via doc: links.

The CLI usage manual “Driving the CLI from Python” section no longer teaches a hand-rolled subprocess JSON-lines client; it points to the bindings layer and the new page, and shows a short OptimizationSession + Optuna-oriented describe() / objective() example instead.

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

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[kube]

Superseded by #9341. GitHub closed this PR when its base branch cf/fe-1447-arch-docs-emit-layer-facts-and-relations-as-structured-data was deleted by the merge of #9264, and a closed PR whose base branch no longer exists cannot be reopened or retargeted. The branch cf/fe-1456-arch-docs-usage-manual-for-the-python-bindings and its commits are unchanged; #9341 carries them, rebased onto main.