[codex] Add Python type checker config examples

docs/tooling.md

@@ -40,6 +40,25 @@ Keep Python configuration in `pyproject.toml`. The Python stack shows Pydantic
 settings/boundary schemas and Alembic migrations as examples; keep them when
 they fit the target repo and replace them when an existing choice is better.
 
+The Python stack includes example configuration for MyPy, Pyright, Pyrefly, and
+ty, but projects should choose one type checker as the required CI gate.
+Recommended defaults:
+
+- Use Pyrefly for new Python projects that want fast CLI checks and a modern
+  language server, provided the team is comfortable with its monthly release
+  cadence and occasional new diagnostics on upgrade.
+- Use Pyright when the team already standardizes on VS Code/Pylance, wants a
+  mature standards-focused checker, or needs strong cross-editor language
+  server behavior.
+- Keep MyPy when the project relies on MyPy plugins, framework-specific typing
+  behavior, or maximum ecosystem compatibility.
+- Use ty only as an advisory or experimental checker until its beta/0.0.x
+  version policy settles.
+
+When switching the CI gate, update `stacks/python/scripts/typecheck.sh`, add the
+chosen checker to the dev dependency group, and regenerate `uv.lock` with the
+repo's supply-chain cooldown policy in mind.
+
 ## Ruby Stack
 
 Use Bundler for Ruby installs and command execution when the target project

stacks/python/README.md

@@ -12,6 +12,8 @@ Python package, or Python-first service tooling.
 - `scripts/worktree-ports.py`: Python implementation of the worktree port helper.
 - `scripts/{lint,format,typecheck,test,check-all}.sh`: validation wrappers for
   this stack.
+- Type checker config examples for MyPy, Pyright, Pyrefly, and ty in
+  `pyproject.toml`.
 
 The root devkit uses `scripts/worktree-ports.sh` by default so projects are not
 forced to include Python just for port allocation.
@@ -53,6 +55,11 @@ settings discovery.
   Python is part of the target runtime or tooling.
 - Copy `apps/`, `packages/`, `pyproject.toml`, and `uv.lock` together so the
   workspace and lockfile stay coherent.
+- Keep one type checker as the CI gate. The default stack still runs MyPy
+  because it is mature, Python-native, and has the widest plugin ecosystem.
+  Prefer Pyrefly for new projects that want a fast modern checker and language
+  server, Pyright when the team standardizes on Pylance or the Pyright CLI, and
+  ty as an advisory experiment until it exits beta.
 - Keep root port helpers shell-based unless the target repo intentionally wants
   Python helper scripts.
 - If copying this stack's `scripts/dev.sh`, copy

stacks/python/pyproject.toml

@@ -81,6 +81,54 @@ warn_redundant_casts = true
 no_implicit_optional = true
 ignore_missing_imports = true
 
+# Optional alternative type checker examples. Keep one checker as the
+# repository's CI gate, then use the others for editor feedback or migration
+# trials.
+[tool.pyright]
+pythonVersion = "3.12"
+typeCheckingMode = "strict"
+include = [
+  "apps/api/src",
+  "apps/api/tests",
+  "packages/shared/src",
+  "tests",
+]
+extraPaths = [
+  "apps/api/src",
+  "packages/shared/src",
+]
+venvPath = "."
+venv = ".venv"
+reportMissingTypeStubs = "warning"
+
+[tool.pyrefly]
+python-version = "3.12"
+project-includes = [
+  "apps/api/src",
+  "apps/api/tests",
+  "packages/shared/src",
+  "tests",
+]
+search-path = [
+  "apps/api/src",
+  "packages/shared/src",
+]
+
+[tool.ty.environment]
+python-version = "3.12"
+root = [
+  "apps/api/src",
+  "packages/shared/src",
+]
+
+[tool.ty.src]
+include = [
+  "apps/api/src",
+  "apps/api/tests",
+  "packages/shared/src",
+  "tests",
+]
+
 [tool.coverage.run]
 source = ["example_api", "example_shared"]
 omit = ["*/tests/*"]