FE-1414: Support Python packages in the architecture docs

[kube]

🌟 What is the purpose of this PR?

The architecture docs generator only accepted TypeScript packages, so apps/petrinaut-opt and the new @local/petrinaut-python bindings could not be documented. This teaches it Python: layer pages, roles, file counts, and diagrams for Python packages, with @layerRoot/@role read from docstrings. Import edges for Python remain out of scope (FE-1415, backlog).

Stack #9226 (top): FE-1410 → FE-1411 → FE-1408 → FE-1413 → FE-1270 → FE-1412 → this PR.

🔗 Related links

• FE-1414 (internal) — this PR
• FE-1415 (internal) — follow-up: Python import edges

🔍 What does this change?

Generator (@local/petrinaut-arch-docs)

• Source extensions resolve per package language (.py for Python); the TypeScript-only gate in the extractor is gone. The graph builder still receives only TypeScript packages, exactly as before.
• The tag scanner reads @layerRoot/@role from triple-quoted docstrings (both quote styles). Module docstrings are the Python analog of a file's doc comment; # comments are deliberately not scanned. The tag grammar, duplicate detection, and miscasing hints are shared across languages.
• __pycache__ and .venv join the ignored directories; the generated edge-table caption now states that Python packages contribute no edges yet.

Registrations (42 layers, 433 files — up from 40/423)

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

Authored content

• content/optimizer/subprocess-boundary.mdx (attached to optimizer): the optimizer↔CLI relationship is a process contract a static import graph cannot represent — this page is the missing arrow, covering the spawn handshake, the ownership split, isolation, and the bounded limits, linking the cli, bindings, and cli.runtime layers and the usage manual.

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?

• Arch-docs suite grows to 79: new tests for docstring tag scanning (module docstrings, single-quoted docstrings, #-comment/JSDoc-in-string non-matches, duplicate/miscasing diagnostics in Python).
• lint:arch-docs validates the real registrations end to end (full file coverage of both Python packages, attachTo resolution); a full bundle build is part of verification.
• Both Python suites (75 + 27) 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 / bindings; the boundary guide hangs off 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 20, 2026 10:53am
petrinaut	Ready	Preview	Aug 20, 2026 10:53am
petrinaut-docs	Ready	Preview	Aug 20, 2026 10:53am

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
hashdotdesign-tokens	Ignored	Preview	Aug 20, 2026 10:53am

[cursor]

PR Summary

^{Cursor Bugbot is generating a summary for commit e9619cf. 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.