oh-my-opencode 4.9.2 → 4.11.0

package/dist/skills/programming/references/python/httpx2-optimization.md

@@ -0,0 +1,360 @@
+# httpx2 — Production Defaults
+
+> **Source**: [pydantic/httpx2](https://github.com/pydantic/httpx2) — next-generation HTTP client for Python 3, continuation of HTTPX under Pydantic stewardship.
+>
+> **Rule**: Every network request MUST use `httpx2`. **ALL optimizations below are ON by default** — HTTP/2, brotli+zstd, tuned connection pool, fine-grained timeouts, transport retries, TCP_NODELAY. This is the baseline, not a stretch goal. A bare `httpx2.AsyncClient()` is a bug.
+
+---
+
+## 1. Installation — all extras, always
+
+```toml
+# pyproject.toml
+dependencies = [
+    "httpx2[http2,brotli,zstd]",
+]
+```
+
+| Extra | What it enables | Why it's mandatory |
+|-------|----------------|--------------------|
+| `http2` | HTTP/2 multiplexing via `h2` | Single TCP connection handles concurrent requests; eliminates head-of-line blocking |
+| `brotli` | Brotli content decoding (`br`) | ~20% smaller payloads than gzip for text/JSON |
+| `zstd` | Zstandard content decoding | Faster decompression than brotli at similar ratios; stdlib in Python ≥ 3.14 |
+| `socks` | SOCKS5 proxy support via `socksio` | Install only if you route through SOCKS proxies |
+
+All three core extras (`http2,brotli,zstd`) are non-negotiable. Omitting any is leaving performance on the table.
+
+---
+
+## 2. The canonical defaults — ALL ON
+
+These are not "optimizations to consider". These are **the correct defaults** that every httpx2 client must use.
+
+```python
+import socket
+import httpx2
+
+# ── These are the STANDARD values. Use them verbatim. ──
+
+LIMITS = httpx2.Limits(
+    max_connections=200,           # library default 100 is too conservative
+    max_keepalive_connections=40,  # library default 20 wastes reconnects
+    keepalive_expiry=30.0,         # library default 5s kills warm connections too fast
+)
+
+TIMEOUT = httpx2.Timeout(
+    connect=5.0,    # TCP + TLS handshake budget
+    read=30.0,      # time to receive a response chunk
+    write=10.0,     # time to send a request chunk
+    pool=10.0,      # time to acquire a connection from pool
+)
+
+SOCKET_OPTIONS: list[tuple[int, int, int]] = [
+    (socket.IPPROTO_TCP, socket.TCP_NODELAY, 1),   # disable Nagle — no 40ms delay
+]
+```
+
+### Why each knob is set this way
+
+| Setting | Library default | Our default | Why |
+|---------|----------------|-------------|-----|
+| `http2` | `False` | **`True`** | HTTP/2 multiplexing is strictly superior for any modern API |
+| `max_connections` | `100` | `200` | Headroom for fan-out; prevents pool exhaustion under load |
+| `max_keepalive_connections` | `20` | `40` | Keeps warm connections alive; fewer TLS handshakes |
+| `keepalive_expiry` | `5.0s` | `30.0s` | 5s is too aggressive — kills connections between burst requests |
+| `Timeout(5.0)` uniform | `5.0` all | Split | Uniform 5s is too tight for reads, too loose for connects |
+| `read` timeout | `5.0` | `30.0` | Slow APIs and streaming need breathing room |
+| `pool` timeout | `5.0` | `10.0` | Explicit — hitting this means `max_connections` needs raising |
+| `TCP_NODELAY` | off | **on** | Eliminates Nagle's 40ms coalescing delay for small payloads |
+| `retries` | `0` | `3` | Retries on `ConnectError`/`ConnectTimeout` only — safe and resilient |
+| `follow_redirects` | `False` | **`True`** | Most APIs redirect; failing on 3xx is wrong default behavior |
+
+---
+
+## 3. Factory functions — the ONE correct way to create clients
+
+Copy this into your project. This is the canonical pattern.
+
+```python
+"""httpx2 client factory. Always use create_client() / create_async_client()."""
+
+from __future__ import annotations
+
+import socket
+import typing
+
+import httpx2
+
+_LIMITS = httpx2.Limits(
+    max_connections=200,
+    max_keepalive_connections=40,
+    keepalive_expiry=30.0,
+)
+
+_TIMEOUT = httpx2.Timeout(
+    connect=5.0,
+    read=30.0,
+    write=10.0,
+    pool=10.0,
+)
+
+_SOCKET_OPTIONS: list[tuple[int, int, int]] = [
+    (socket.IPPROTO_TCP, socket.TCP_NODELAY, 1),
+]
+
+
+def create_async_client(
+    *,
+    base_url: str = "",
+    http2: bool = True,
+    retries: int = 3,
+    limits: httpx2.Limits = _LIMITS,
+    timeout: httpx2.Timeout = _TIMEOUT,
+    headers: dict[str, str] | None = None,
+    event_hooks: dict[str, list[typing.Callable[..., typing.Any]]] | None = None,
+    **kwargs: typing.Any,
+) -> httpx2.AsyncClient:
+    transport = httpx2.AsyncHTTPTransport(
+        http2=http2,
+        retries=retries,
+        limits=limits,
+        socket_options=_SOCKET_OPTIONS,
+    )
+    return httpx2.AsyncClient(
+        transport=transport,
+        timeout=timeout,
+        base_url=base_url,
+        headers=headers or {},
+        event_hooks=event_hooks or {},
+        follow_redirects=True,
+        **kwargs,
+    )
+
+
+def create_client(
+    *,
+    base_url: str = "",
+    http2: bool = True,
+    retries: int = 3,
+    limits: httpx2.Limits = _LIMITS,
+    timeout: httpx2.Timeout = _TIMEOUT,
+    headers: dict[str, str] | None = None,
+    event_hooks: dict[str, list[typing.Callable[..., typing.Any]]] | None = None,
+    **kwargs: typing.Any,
+) -> httpx2.Client:
+    transport = httpx2.HTTPTransport(
+        http2=http2,
+        retries=retries,
+        limits=limits,
+        socket_options=_SOCKET_OPTIONS,
+    )
+    return httpx2.Client(
+        transport=transport,
+        timeout=timeout,
+        base_url=base_url,
+        headers=headers or {},
+        event_hooks=event_hooks or {},
+        follow_redirects=True,
+        **kwargs,
+    )
+```
+
+Usage:
+
+```python
+# Async — the common case
+async with create_async_client(base_url="https://api.example.com") as client:
+    r = await client.get("/users")
+
+# Sync
+with create_client() as client:
+    r = client.get("https://api.example.com/health")
+```
+
+**If you are NOT using this factory pattern, you are doing it wrong.** A bare `httpx2.AsyncClient()` leaves HTTP/2 off, retries off, TCP_NODELAY off, keepalive too short, and timeouts too uniform.
+
+---
+
+## 4. Special case overrides
+
+The factory defaults cover 95% of use cases. Override only when you have a specific reason:
+
+| Scenario | Override |
+|----------|----------|
+| LLM streaming endpoints | `timeout=httpx2.Timeout(connect=10.0, read=None, write=10.0, pool=10.0)` — no read timeout on streaming |
+| Single-host API with low concurrency | `limits=httpx2.Limits(max_connections=50, max_keepalive_connections=20, keepalive_expiry=60.0)` |
+| Ephemeral short-lived requests | `keepalive_expiry=5.0` — don't hold connections |
+| Unix domain sockets | `httpx2.AsyncHTTPTransport(uds="/path/to/socket", ...)` |
+| mTLS / client certs | Pass `verify=ssl_ctx` with `ctx.load_cert_chain(certfile=...)` |
+| SOCKS proxy | `httpx2[socks]`, `proxy="socks5://..."` |
+
+---
+
+## 5. Event hooks — always wire observability
+
+This is not optional. Every production client should log requests.
+
+```python
+import time
+import logging
+
+logger = logging.getLogger(__name__)
+
+async def log_request(request: httpx2.Request) -> None:
+    request.extensions["request_start"] = time.perf_counter()
+
+async def log_response(response: httpx2.Response) -> None:
+    start = response.request.extensions.get("request_start", 0)
+    elapsed = time.perf_counter() - start
+    logger.info(
+        "HTTP %s %s → %d (%.3fs, %s)",
+        response.request.method,
+        response.request.url,
+        response.status_code,
+        elapsed,
+        response.http_version,
+    )
+
+# Sync versions for Client
+def log_request_sync(request: httpx2.Request) -> None:
+    request.extensions["request_start"] = time.perf_counter()
+
+def log_response_sync(response: httpx2.Response) -> None:
+    start = response.request.extensions.get("request_start", 0)
+    elapsed = time.perf_counter() - start
+    logger.info(
+        "HTTP %s %s → %d (%.3fs, %s)",
+        response.request.method,
+        response.request.url,
+        response.status_code,
+        elapsed,
+        response.http_version,
+    )
+```
+
+For auto `raise_for_status()`:
+
+```python
+async def raise_on_error(response: httpx2.Response) -> None:
+    response.raise_for_status()
+```
+
+---
+
+## 6. Verification script — confirm your setup is fully optimized
+
+Run this against your target endpoint to **verify** (not decide) that all optimizations are active:
+
+```python
+"""Verify httpx2 is fully optimized against a target endpoint."""
+
+from __future__ import annotations
+
+import socket
+import time
+
+import anyio
+import httpx2
+
+
+TARGET_URL = "https://api.example.com/health"
+ITERATIONS = 30
+
+
+async def bench(label: str, client: httpx2.AsyncClient, url: str, n: int) -> float:
+    for _ in range(3):  # warmup
+        await client.get(url)
+    start = time.perf_counter()
+    for _ in range(n):
+        r = await client.get(url)
+        assert r.status_code == 200
+    elapsed = time.perf_counter() - start
+    avg_ms = (elapsed / n) * 1000
+    print(f"  {label}: {avg_ms:.1f}ms avg ({n} reqs in {elapsed:.2f}s)")
+    return avg_ms
+
+
+async def main() -> None:
+    results: dict[str, float] = {}
+
+    # BAD: bare defaults (this is what we're proving is worse)
+    async with httpx2.AsyncClient() as c:
+        results["BAD-bare-defaults"] = await bench("BAD-bare-defaults", c, TARGET_URL, ITERATIONS)
+
+    # GOOD: full production defaults (this is what we always use)
+    limits = httpx2.Limits(max_connections=200, max_keepalive_connections=40, keepalive_expiry=30.0)
+    timeout = httpx2.Timeout(connect=5.0, read=30.0, write=10.0, pool=10.0)
+    transport = httpx2.AsyncHTTPTransport(
+        http2=True, retries=3, limits=limits,
+        socket_options=[(socket.IPPROTO_TCP, socket.TCP_NODELAY, 1)],
+    )
+    async with httpx2.AsyncClient(transport=transport, timeout=timeout, follow_redirects=True) as c:
+        results["GOOD-full-production"] = await bench("GOOD-full-production", c, TARGET_URL, ITERATIONS)
+
+    print("\n--- Proof ---")
+    baseline = results["BAD-bare-defaults"]
+    for label, avg in results.items():
+        delta = ((avg - baseline) / baseline) * 100
+        print(f"  {label}: {avg:.1f}ms ({delta:+.1f}% vs bare)")
+
+
+if __name__ == "__main__":
+    anyio.run(main)
+```
+
+---
+
+## 7. Quick reference — all knobs
+
+### `httpx2.AsyncClient` / `httpx2.Client`
+
+| Parameter | Type | Library Default | **Our Default** |
+|-----------|------|-----------------|-----------------|
+| `http1` | `bool` | `True` | `True` |
+| `http2` | `bool` | `False` | **`True`** |
+| `verify` | `ssl.SSLContext \| str \| bool` | `True` | `True` |
+| `cert` | `CertTypes \| None` | `None` | `None` |
+| `proxy` | `str \| Proxy \| None` | `None` | `None` |
+| `mounts` | `dict[str, Transport]` | `None` | `None` |
+| `timeout` | `Timeout \| float \| None` | `Timeout(5.0)` | **Split: 5/30/10/10** |
+| `limits` | `Limits` | `Limits(100, 20, 5.0)` | **`Limits(200, 40, 30.0)`** |
+| `follow_redirects` | `bool` | `False` | **`True`** |
+| `max_redirects` | `int` | `20` | `20` |
+| `event_hooks` | `dict` | `{}` | **Wire logging** |
+| `base_url` | `str` | `""` | Set for single-API clients |
+| `trust_env` | `bool` | `True` | `True` |
+| `default_encoding` | `str \| Callable` | `"utf-8"` | `"utf-8"` |
+
+### `httpx2.AsyncHTTPTransport` / `httpx2.HTTPTransport`
+
+| Parameter | Type | Library Default | **Our Default** |
+|-----------|------|-----------------|-----------------|
+| `http1` | `bool` | `True` | `True` |
+| `http2` | `bool` | `False` | **`True`** |
+| `retries` | `int` | `0` | **`3`** |
+| `limits` | `Limits` | `Limits(100, 20, 5.0)` | **`Limits(200, 40, 30.0)`** |
+| `uds` | `str \| None` | `None` | `None` |
+| `local_address` | `str \| None` | `None` | `None` |
+| `socket_options` | `Iterable[SOCKET_OPTION]` | `None` | **`[TCP_NODELAY]`** |
+| `proxy` | `str \| Proxy \| None` | `None` | `None` |
+
+### `httpx2.Timeout`
+
+| Parameter | Library Default | **Our Default** |
+|-----------|-----------------|-----------------|
+| `connect` | `5.0` | `5.0` |
+| `read` | `5.0` | **`30.0`** |
+| `write` | `5.0` | **`10.0`** |
+| `pool` | `5.0` | **`10.0`** |
+
+### `httpx2.Limits`
+
+| Parameter | Library Default | **Our Default** |
+|-----------|-----------------|-----------------|
+| `max_connections` | `100` | **`200`** |
+| `max_keepalive_connections` | `20` | **`40`** |
+| `keepalive_expiry` | `5.0` | **`30.0`** |
+
+### Async backend (httpcore2)
+
+httpcore2 uses `anyio` by default (works with both asyncio and trio). No extra config needed if you're already on the anyio stack. For trio, install `httpcore2[trio]`.

package/dist/skills/programming/references/python/libraries.md

@@ -0,0 +1,307 @@
+# Library Defaults — Decision Tree
+
+For each domain, the canonical 2026 choice, why, and the canonical usage snippet. The skill enforces these unless the project's `pyproject.toml` explicitly says otherwise.
+
+## CLI — typer
+
+`typer` builds a CLI from type-annotated function signatures. argparse needs 5x the code; click ignores type annotations; fire is magic that breaks at scale.
+
+```python
+import typer
+from rich import print as rprint
+
+app = typer.Typer()
+
+@app.command()
+def greet(name: str, count: int = 1, shout: bool = False) -> None:
+    """Print a greeting `count` times."""
+    message = f"Hello, {name}!" if not shout else f"HELLO, {name.upper()}!"
+    for _ in range(count):
+        rprint(message)
+
+if __name__ == "__main__":
+    app()
+```
+
+For a single-function script, `typer.run(main)` skips the `Typer()` boilerplate. Subcommands use `@app.command()`.
+
+## Terminal output — rich
+
+`rich` produces tables, progress bars, syntax highlighting, traceback rendering. Use it for any structured output. Plain `print` is acceptable for non-interactive log lines (and even those are usually better via `rich.console.Console(stderr=True).log(...)`).
+
+```python
+from rich.console import Console
+from rich.table import Table
+
+console = Console()
+
+table = Table(title="Users")
+table.add_column("ID", style="cyan")
+table.add_column("Name", style="magenta")
+table.add_row("1", "Alice")
+console.print(table)
+
+# Rich tracebacks (call once at process start)
+from rich.traceback import install
+install(show_locals=True)
+```
+
+## HTTP client — [httpx2](https://github.com/pydantic/httpx2)
+
+Next-generation HTTP client under Pydantic stewardship. Sync and async in one library, HTTP/2 native, brotli + zstd content decoding, real type stubs. Replaces `requests` (sync only), `aiohttp` (async only), and the original `httpx`.
+
+**Install**: `httpx2[http2,brotli,zstd]` — always include all three extras, no exceptions.
+
+**A bare `httpx2.AsyncClient()` / `httpx2.Client()` is a bug.** Always use the factory pattern from `references/httpx2-optimization.md` with ALL optimizations enabled by default:
+
+```python
+import socket
+import httpx2
+
+# ── Production defaults — ALL ON, always. ──
+_LIMITS = httpx2.Limits(max_connections=200, max_keepalive_connections=40, keepalive_expiry=30.0)
+_TIMEOUT = httpx2.Timeout(connect=5.0, read=30.0, write=10.0, pool=10.0)
+_SOCKET_OPTS: list[tuple[int, int, int]] = [(socket.IPPROTO_TCP, socket.TCP_NODELAY, 1)]
+
+# Async (the common case)
+transport = httpx2.AsyncHTTPTransport(http2=True, retries=3, limits=_LIMITS, socket_options=_SOCKET_OPTS)
+async with httpx2.AsyncClient(transport=transport, timeout=_TIMEOUT, follow_redirects=True) as client:
+    response = await client.get("https://api.example.com/users")
+    response.raise_for_status()
+    users = response.json()
+
+# Sync
+transport = httpx2.HTTPTransport(http2=True, retries=3, limits=_LIMITS, socket_options=_SOCKET_OPTS)
+with httpx2.Client(transport=transport, timeout=_TIMEOUT, follow_redirects=True) as client:
+    response = client.get("https://api.example.com/users")
+    response.raise_for_status()
+    users = response.json()
+```
+
+See `references/httpx2-optimization.md` for the full factory functions (`create_client()` / `create_async_client()`), event hooks, and the rationale behind every setting. **Load that reference whenever you write ANY network code.**
+
+## JSON — stdlib `json` (default) or `orjson` (hot paths)
+
+Stdlib `json` is fine for cold paths and configs. **Reach for `orjson` when JSON is in the hot path** — cache layers, queue payloads, streaming responses, structured logs, FastAPI endpoints returning raw `dict` / `list`.
+
+```python
+import orjson
+
+# orjson.dumps returns bytes, not str
+raw: bytes = orjson.dumps(
+    payload,
+    option=orjson.OPT_NAIVE_UTC | orjson.OPT_UTC_Z | orjson.OPT_SERIALIZE_DATACLASS,
+)
+```
+
+**Critical 2026 fact**: with Pydantic v2, `model.model_dump_json()` is backed by pydantic-core (Rust) and is faster than `orjson + default=` bridge for Pydantic-shaped responses. **Use `model_dump_json()` for Pydantic; orjson for everything else.**
+
+For FastAPI: `app = FastAPI(default_response_class=ORJSONResponse)`. Pydantic-typed responses bypass it (and that's correct — Pydantic's path is faster). Raw `dict`/`list` returns go through orjson.
+
+See `references/orjson-stack.md` for the full decision tree, option flag reference, FastAPI integration, Redis/queue/logging patterns, and the `model_dump_json()` vs orjson benchmark.
+
+## Validation — pydantic v2
+
+Pydantic v2's core is in Rust (~10x faster than v1). It is the de-facto boundary validator. Use it for:
+
+- HTTP request/response models (FastAPI uses pydantic natively)
+- Config files (env vars via `pydantic-settings`)
+- Anything entering the program from outside
+
+```python
+from pydantic import BaseModel, Field, EmailStr, field_validator
+
+class User(BaseModel):
+    id: int = Field(ge=1)
+    email: EmailStr
+    name: str = Field(min_length=1, max_length=100)
+    age: int | None = Field(default=None, ge=0, le=150)
+
+    @field_validator("name")
+    @classmethod
+    def name_no_digits(cls, v: str) -> str:
+        if any(c.isdigit() for c in v):
+            raise ValueError("name cannot contain digits")
+        return v
+
+# Inside the program, use the validated instance with confidence
+user = User.model_validate({"id": 1, "email": "a@b.com", "name": "Alice"})
+print(user.model_dump_json(indent=2))
+```
+
+`@dataclass` is fine for purely internal records (no validation needed). For anything crossing a process boundary, use Pydantic.
+
+## Async — anyio
+
+Full reference: [async-anyio.md](async-anyio.md). The summary:
+
+```python
+import anyio
+
+async def fetch(url: str) -> str:
+    await anyio.sleep(0.1)
+    return url
+
+async def main() -> None:
+    async with anyio.create_task_group() as tg:
+        for url in ["a", "b", "c"]:
+            tg.start_soon(fetch, url)
+
+anyio.run(main)
+```
+
+Never `import asyncio` directly. The third-party libraries you call are free to use asyncio internally.
+
+## Web framework — fastapi
+
+Type-hint-driven HTTP framework. Pydantic models become OpenAPI schemas automatically.
+
+```python
+from fastapi import FastAPI
+from pydantic import BaseModel
+
+app = FastAPI()
+
+class CreateUser(BaseModel):
+    name: str
+    email: str
+
+class User(BaseModel):
+    id: int
+    name: str
+    email: str
+
+@app.post("/users", response_model=User)
+async def create_user(payload: CreateUser) -> User:
+    return User(id=1, **payload.model_dump())
+```
+
+Full stack with database: [fastapi-stack.md](fastapi-stack.md).
+
+## ORM — sqlalchemy 2.x async
+
+SQLAlchemy 2.x finally has a real async API. Use the modern declarative `MappedAsDataclass` style with type annotations.
+
+```python
+from sqlalchemy import String
+from sqlalchemy.ext.asyncio import AsyncSession, create_async_engine, async_sessionmaker
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column, MappedAsDataclass
+
+class Base(MappedAsDataclass, DeclarativeBase):
+    pass
+
+class User(Base):
+    __tablename__ = "users"
+    id: Mapped[int] = mapped_column(primary_key=True, init=False)
+    name: Mapped[str] = mapped_column(String(100))
+    email: Mapped[str] = mapped_column(String(255), unique=True)
+
+engine = create_async_engine("postgresql+asyncpg://localhost/myapp")
+SessionFactory = async_sessionmaker(engine, expire_on_commit=False)
+```
+
+Full pattern with FastAPI integration: [fastapi-stack.md](fastapi-stack.md).
+
+## Database — postgres + asyncpg
+
+For new applications, default to Postgres. SQLite for tests is fine; SQLite for production is not.
+
+asyncpg is the fastest Python Postgres driver, native to SQLAlchemy 2.x async, native to FastAPI's lifespan model. URL: `postgresql+asyncpg://user:pass@host:5432/db`.
+
+For migrations, use Alembic with `[alembic.context]` configured to use the async engine. Single-step:
+
+```bash
+uv add alembic
+uv run alembic init -t async migrations
+```
+
+## TUI — textual
+
+Textual builds rich, mouse-aware, mobile-style TUIs on the rich rendering engine. See [textual-tui.md](textual-tui.md).
+
+## AI agents — pydantic-ai
+
+The agent framework from the Pydantic team. Type-strict, structured outputs are first-class, model-agnostic. See [pydantic-ai.md](pydantic-ai.md).
+
+## DataFrames — polars + numpy
+
+Polars is 10-50x faster than pandas, has a real type system, and supports lazy evaluation. Numpy stays in the toolbox for arrays. See [data-processing.md](data-processing.md).
+
+## OLAP / SQL — duckdb
+
+DuckDB is the SQL engine for analytical workloads. Query CSV/Parquet/JSON files directly without loading into memory; perform joins and aggregations 3-4x faster than Polars; zero-copy interchange with Polars via Arrow. See [data-processing.md](data-processing.md).
+
+## Tests — pytest
+
+Plain `unittest` is fine for stdlib; everything else uses pytest. Conventions:
+
+- File names `test_*.py`, function names `test_*`.
+- Fixtures via `@pytest.fixture`. Async fixtures are anyio-aware (`@pytest.fixture` on an async function works under `pytest-anyio` which is bundled with anyio).
+- Parametrise with `@pytest.mark.parametrize`.
+- Mark async tests with `@pytest.mark.anyio` (provided by anyio's pytest plugin).
+
+```python
+import pytest
+import anyio
+
+@pytest.fixture
+def sample_user() -> dict[str, str]:
+    return {"name": "Alice", "email": "a@b.com"}
+
+@pytest.mark.parametrize("count,expected", [(1, "Hello"), (2, "Hello, Hello")])
+def test_greet(count: int, expected: str) -> None:
+    result = ", ".join(["Hello"] * count)
+    assert result == expected
+
+@pytest.mark.anyio
+async def test_async_fetch() -> None:
+    await anyio.sleep(0)
+    assert True
+```
+
+`pyproject.toml`:
+
+```toml
+[tool.pytest.ini_options]
+minversion = "8.0"
+testpaths = ["tests"]
+addopts = ["-ra", "--strict-config", "--strict-markers"]
+```
+
+## Settings / config — pydantic-settings
+
+Loads env vars and `.env` files into a Pydantic model. Replaces ad-hoc `os.environ.get(...)` everywhere.
+
+```python
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(env_file=".env", env_prefix="MYAPP_")
+
+    database_url: str
+    api_key: str = Field(min_length=1)
+    debug: bool = False
+
+settings = Settings()  # loads at import time; raises if any required var is missing
+```
+
+## Logging — stdlib logging + rich handler
+
+Stdlib `logging` is fine; it gets a face-lift from `rich.logging.RichHandler`.
+
+```python
+import logging
+from rich.logging import RichHandler
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(message)s",
+    datefmt="[%X]",
+    handlers=[RichHandler(rich_tracebacks=True, show_path=False)],
+)
+log = logging.getLogger(__name__)
+log.info("ready")
+```
+
+For structured logging in production, swap to `structlog` (separate dep). Don't roll your own.