FE-1414: Support Python packages in the architecture docs

[kube]

🌟 What is the purpose of this PR?

The architecture docs generator accepted only TypeScript packages, so apps/petrinaut-opt and the new @local/petrinaut-python bindings could not be documented. This PR adds Python support: layer pages, roles, and diagrams for Python packages, with @layerRoot/@role read from module docstrings. Import edges for Python arrive in FE-1415 (#9265), further up this stack.

In stack #9280, FE-1470 (#9278) sits below and FE-1443 (#9263) above.

🔗 Related links

• FE-1414 (internal): this PR
• FE-1415 (internal): Python import edges, FE-1415: Generate import edges for Python packages #9265 in this stack

🔍 What does this change?

Generator (@local/petrinaut-arch-docs)

• Source extensions resolve per package language, .py for Python, and the TypeScript-only check in the extractor is gone. The graph builder still receives only TypeScript packages, exactly as before.
• The tag scanner reads @layerRoot/@role from the module docstring only, in both quote styles; a triple-quoted string elsewhere in the file is a value. The tag grammar, duplicate detection, and miscasing hints are shared across languages.
• __pycache__ and .venv join the ignored directories. The overview page now states that the Python packages contribute no import edges yet.

Registrations

• @apps/petrinaut-opt declares the root layer optimizer in optimization_api.py's docstring.
• @local/petrinaut-python declares the root layer python-bindings in the package docstring.
• Both roots get diagram colours.

Authored content

• content/optimizer/subprocess-boundary.mdx, attached to optimizer, documents the optimizer-to-CLI process contract: the spawn handshake, the ownership split, isolation, and the bounded limits. It links the cli, python-bindings, and cli.runtime layers and the CLI usage manual.

Review fixes

• The module docstring pattern accepts string prefixes (r"""), with a test, so a raw docstring cannot silently drop a package's @layerRoot.
• The per-language extensions live in a Record keyed by the config's language enum, so adding an enum member fails to compile until it names its extensions. The single-use pythonSourceExtensions export was inlined.

Pre-Merge Checklist 🚀

🚢 Has this modified a publishable library?

This PR:

• modifies workspaces but not a publishable library

📜 Does this require a change to the docs?

The changes in this PR:

• are docs (architecture). In-app user docs unaffected.

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

The changes in this PR:

• do not affect the execution graph

🛡 What tests cover this?

• tags.test.ts grows from 9 to 16 cases: module docstrings, single-quoted and prefixed docstrings, non-matches for # comments and JSDoc text inside strings, and duplicate and miscasing diagnostics in Python.
• lint:arch-docs validates the real registrations end to end, including full file coverage of both Python packages and attachTo resolution.
• Both Python packages' suites still pass with the docstring declarations in place.

❓ How to test this?

1. yarn workspace @local/petrinaut-arch-docs lint:arch-docs
2. turbo run dev --filter @apps/petrinaut-docs and open Architecture → optimizer / python-bindings; the boundary guide sits under the optimizer page.

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

1 Skipped Deployment

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

[cursor]

PR Summary

Low Risk
Docs-generator and annotation-only changes; no runtime, auth, or data-path behavior is modified.

Overview
The architecture docs generator can now include Python packages: it scans .py files and reads @layerRoot / @role from the module docstring only (including raw/prefixed quotes). Import edges for Python are still not generated.

@apps/petrinaut-opt and @local/petrinaut-python are registered as optimizer and python-bindings, with diagram colours. A new authored page documents the optimizer↔CLI process contract (spawn handshake, ownership split, isolation, bounds) because that edge never appears in the import graph.

The TypeScript-only extractor rejection is gone; the graph builder still cruises TypeScript packages only. __pycache__ and .venv are ignored.

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

[Copilot]

Pull request overview

Adds Python package support to Petrinaut’s architecture documentation generator.

Changes:

• Extracts layers and roles from Python module docstrings.
• Registers the Python bindings and optimizer packages.
• Adds Python-aware diagrams and subprocess-boundary documentation.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
apps/petrinaut-opt/src/optimization_api.py	Declares the optimizer layer.
libs/@local/petrinaut-python/src/petrinaut/__init__.py	Declares the bindings layer.
libs/@local/petrinaut-arch-docs/architecture.config.ts	Registers Python packages and ignored directories.
libs/@local/petrinaut-arch-docs/src/scope.ts	Selects source extensions by language.
libs/@local/petrinaut-arch-docs/src/extract.ts	Extracts architecture data from Python sources.
libs/@local/petrinaut-arch-docs/src/tags.ts	Adds Python docstring tag scanning.
libs/@local/petrinaut-arch-docs/src/tags.test.ts	Tests Python tag scanning.
libs/@local/petrinaut-arch-docs/src/emit/d2.ts	Adds colors for Python layers.
libs/@local/petrinaut-arch-docs/src/emit/mdx.ts	Clarifies Python import-edge limitations.
libs/@local/petrinaut-arch-docs/content/optimizer/subprocess-boundary.mdx	Documents the optimizer–CLI process boundary.

---

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

[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.