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.

In stack #9280, FE-1415 (#9265) sits below 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, and 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 and links to the new page.

Every symbol, default, and limit was checked against the source. Claims the package README implies that 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

Review fixes

• The claim that the package uses only the standard library is replaced with its real dependency, pydantic.
• The optimization example leads with the dict constructor, the one the production consumer uses, and reads results through attribute access on the pydantic models instead of subscripts.
• The error section states both halves: a non-finite objective raises PetrinautRunError and leaves the session usable, while a non-numeric one fails schema validation and raises PetrinautProtocolError. It also states that request params that fail JSON serialization raise PetrinautClientError before anything is written, leaving the session running.
• The guarantee that close() may be called from another thread is restored.
• A dangling cross-reference ("worked through there") is removed.
• The CLI-manual snippet sends every described parameter and uses its describe result.

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 22, 2026 3:06am
petrinaut	Ready	Preview	Aug 22, 2026 3:06am
petrinaut-docs	Ready	Preview	Aug 22, 2026 3:06am

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
hashdotdesign-tokens	Ignored	Preview	Aug 22, 2026 3:06am

[cursor]

PR Summary

Low Risk
Documentation-only change to architecture docs; no runtime, auth, or data-handling code is modified.

Overview
Adds a python-bindings usage manual on the docs site (attachTo: python-bindings) covering sessions, run/optimization APIs, exceptions, timeouts, and shutdown.

The CLI manual’s “Driving the CLI from Python” section no longer shows a raw subprocess wrapper. It now uses OptimizationSession and links to the new page for lifecycle, timeouts, and error types. Protocol details stay in the CLI manual rather than being duplicated.

^{Reviewed by Cursor Bugbot for commit 1d6951e. 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.