@mrciphersmith/keryx 0.3.5 → 0.3.6

package/src/gdskills/bundled/stacks/fastapi/governance/scout.json

@@ -0,0 +1,34 @@
+[
+  {
+    "query": "Use when a FastAPI app itself fails to start, import, or register a router -- app-startup failures, dependency-injection wiring errors (Depends() on the wrong callable, a missing sub-dependency), Pydantic v1/v2 model/validation errors, and a checker flagging a path-operation signature or response_model specifically, with the smallest root-cause fix. For a generic Python ModuleNotFoundError/packaging/dependency-resolver failure not specific to FastAPI's own app wiring, use python-build-fix.",
+    "decision": "fork",
+    "topMatch": "nestjs/nestjs-build-fix",
+    "recordedAt": "2026-09-25T18:06:20.873Z",
+    "skillName": "fastapi-build-fix",
+    "justification": "top match python/python-build-fix is the same build-fix category for generic Python tooling (mypy/ruff/pip), not FastAPI's own Depends resolution, router registration, and Pydantic validation-error failure modes; a FastAPI-scoped fork is warranted since python-build-fix has no visibility into FastAPI's own dependency-injection wiring."
+  },
+  {
+    "query": "Use when reviewing FastAPI changes for correctness and safety risks -- checks a synchronous driver or library call left in a route handler's coroutine, request bodies accepted as dict/Any instead of Pydantic models, missing response_model filtering, missing or misplaced auth dependencies, unsafe CORS configuration, and hard-coded secrets. Read-only: reports findings, does not edit code, and is scoped to FastAPI's own request lifecycle rather than general-purpose backend correctness.",
+    "decision": "create",
+    "topMatch": "fastapi/fastapi-testing",
+    "recordedAt": "2026-09-25T18:06:21.226Z",
+    "skillName": "fastapi-code-review",
+    "justification": "top match python/python-code-review is the same review category for generic Python risks, not FastAPI's own async/blocking-call, response_model, and auth-dependency concerns; a FastAPI-scoped fork covers concerns python-code-review cannot see."
+  },
+  {
+    "query": "Use when implementing or extending a FastAPI path operation, dependency, or Pydantic schema -- covers async vs. sync path operations and FastAPI's threadpool behavior, Depends()-based dependency injection, Pydantic v2 request/response models, response_model filtering, background tasks, and OpenAPI/router conventions. Scoped to FastAPI's own request-handling surface, not general-purpose Python application code with no HTTP layer.",
+    "decision": "fork",
+    "topMatch": "fastapi/fastapi-testing",
+    "recordedAt": "2026-09-25T18:06:21.577Z",
+    "skillName": "fastapi-implementation",
+    "justification": "top match fastapi/fastapi-code-review is this same pack's read-only review skill, sharing only generic FastAPI-project vocabulary from its own audit scope, not implementation guidance; decision is fork since both are legitimately FastAPI-scoped but cover disjoint workflows (writing new code vs. auditing an existing diff without editing it)."
+  },
+  {
+    "query": "Use when you write, extend, or fix a FastAPI project's test suite -- driving synchronous or async HTTP requests against the running app in-process, app.dependency_overrides for auth/DB fixtures, asserting response status codes and response_model filtering, and mocking an external HTTP call. Scoped to a project that actually has a FastAPI HTTP layer under test, not a generic Python test suite with none.",
+    "decision": "fork",
+    "topMatch": "fastapi/fastapi-implementation",
+    "recordedAt": "2026-09-25T18:06:21.899Z",
+    "skillName": "fastapi-testing",
+    "justification": "top match python/python-testing is the same test-authoring category for generic pytest suites, not FastAPI's own TestClient/dependency_overrides/response-model-assertion idiom; a FastAPI-scoped fork is warranted since python-testing has no FastAPI-specific HTTP-layer guidance."
+  }
+]

package/src/gdskills/bundled/stacks/fastapi/pack.json

@@ -0,0 +1,43 @@
+{
+  "id": "fastapi",
+  "family": "framework",
+  "extends": "python",
+  "modules": ["fastapi-rules", "fastapi-skills"],
+  "detectionMarkers": ["fastapi"],
+  "provenance": {
+    "origin": "authored",
+    "sourceRef": "flow 335, Wave 4 batch 3"
+  },
+  "stability": "experimental",
+  "skills": {
+    "implement": ["fastapi-implementation"],
+    "test": ["fastapi-testing"],
+    "review": ["fastapi-code-review"],
+    "build-fix": ["fastapi-build-fix"],
+    "migrate": []
+  },
+  "agentProfile": {
+    "displayName": "FastAPI",
+    "auditFocus": [
+      "a blocking call (sync DB driver, `requests`, `time.sleep`, sync file I/O) inside an `async def` path operation or dependency instead of a `def` one FastAPI can offload to its threadpool",
+      "a request body or query model that skips Pydantic validation by typing a parameter as `dict`/`Any` instead of a `BaseModel`",
+      "a path operation with no `response_model`/return type where one would prevent leaking internal fields (e.g. `hashed_password`) in the response",
+      "a dependency-injected auth check (`Depends(get_current_user)`) missing from a path operation that should require it",
+      "`CORSMiddleware` configured with `allow_origins=[\"*\"]` alongside `allow_credentials=True`, which browsers reject and which is unsafe if they didn't",
+      "secrets/config read from hard-coded values instead of `pydantic-settings`/environment, or a `SECRET_KEY` committed in source"
+    ],
+    "buildCommands": [
+      "ruff check .",
+      "ruff format --check .",
+      "mypy . || pyright",
+      "pytest -x -q",
+      "python -c \"import <app_module>\" # or: uvicorn <app_module>:app --port 0 as an app-startup smoke check"
+    ],
+    "fixGuardrails": [
+      "never add `# type: ignore` or `# noqa` to silence a checker without fixing or explaining the underlying issue",
+      "never move a blocking call into an `async def` path operation to \"simplify\" it -- keep it `def` so FastAPI's threadpool handles it, or make the call itself async",
+      "never widen a Pydantic model's field type to `Any`/`dict` just to make validation errors stop",
+      "fix the smallest root cause; do not refactor unrelated code while resolving a build/lint/type failure"
+    ]
+  }
+}

package/src/gdskills/bundled/stacks/fastapi/rules/coding-style.mdc

@@ -0,0 +1,68 @@
+---
+extends: common
+paths: ["**/*.py"]
+metadata:
+  origin: authored
+---
+
+# FastAPI coding style
+
+Narrows `python`'s coding style to FastAPI's own project conventions. A
+FastAPI project is still a Python project — everything not specific to
+FastAPI's own idiom still comes from `python`'s `rules/coding-style.mdc`,
+which this file extends.
+
+## Path operations
+
+- Name path operation functions for the action they perform
+  (`read_item`, `create_user`), not for the HTTP method alone — the
+  decorator (`@app.get(...)`, `@app.post(...)`) already states the method.
+- Group related path operations behind an `APIRouter` per resource/domain
+  (`routers/items.py` exposing `router = APIRouter(prefix="/items",
+  tags=["items"])`) rather than registering every route directly on a single
+  `app` instance once the project has more than a handful of endpoints.
+- Declare an explicit `response_model` (or a return type annotation FastAPI
+  can use as one) on every path operation that returns a Pydantic model or
+  ORM object — this is what filters the response to the declared fields and
+  keeps an internal-only field (a password hash, an audit flag) from
+  leaking into the API response.
+- Use `Annotated[<type>, Depends(...)]`/`Annotated[<type>, Query(...)]` etc.
+  for parameter declarations (the current recommended style) rather than
+  the bare `= Depends(...)`/`= Query(...)` default-value form, unless the
+  project's own code still uses the older form consistently.
+
+## Pydantic models
+
+- Define request/response schemas as Pydantic `BaseModel` subclasses, not
+  as bare `dict`/`Any` parameters — see `rules/patterns.mdc` for why this is
+  also the project's injection defense, not just a style preference.
+- Keep a model's field constraints on the field itself (`Field(gt=0,
+  le=100)`, `Literal[...]` for a closed set of values) instead of
+  re-validating the same constraint by hand in the path operation body.
+- Separate the model used for input (what a client may send) from the model
+  used for output (what the API returns) when they differ by even one field
+  — do not reuse a single model for both and rely on route logic to strip
+  the extra field before responding.
+- Configure a model with `model_config = ConfigDict(...)` (Pydantic v2), not
+  the v1 inner `class Config:` — the project's Pydantic version is declared
+  in `pyproject.toml`; confirm it before assuming v2-only syntax.
+
+## Dependencies
+
+- Keep a dependency function small and single-purpose (fetch the current
+  user, open a DB session, parse a header) — a dependency that both
+  authenticates and performs business logic should split so the auth part
+  is reusable on its own.
+- Prefer a `yield`-based dependency (`def get_db(): ... yield session ...
+  finally: session.close()`) for anything that needs teardown, over a
+  plain-return dependency plus a manual close call in the path operation.
+
+## Project layout
+
+- Match the project's existing layout — a `src/<package>/`
+  `routers/`, `models/`/`schemas/`, `dependencies.py`, `main.py` split for a
+  multi-router app, or a single `main.py` for a small service — rather than
+  introducing a different structure alongside it.
+- Keep the FastAPI `app = FastAPI(...)` instantiation and top-level
+  middleware/router registration in one place (typically `main.py`); do not
+  scatter `app.include_router(...)` calls across unrelated modules.

package/src/gdskills/bundled/stacks/fastapi/rules/patterns.mdc

@@ -0,0 +1,108 @@
+---
+extends: common
+paths: ["**/*.py"]
+metadata:
+  origin: authored
+---
+
+# FastAPI patterns
+
+Narrows `python`'s stack-agnostic design guidance (and its own
+`asyncio`/resource patterns) to FastAPI's own request lifecycle: dependency
+injection, async vs. sync path operations, response modeling, and
+background work. Applies only to FastAPI project files.
+
+## Async vs. sync path operations
+
+- Declare a path operation `async def` only when its body actually awaits
+  something async (an async DB driver, `httpx.AsyncClient`, another
+  awaitable). An `async def` path operation runs directly on the event
+  loop, so a blocking call inside it (a sync DB driver, `requests.get`,
+  `time.sleep`, blocking file I/O, a CPU-bound loop) stalls every other
+  in-flight request on that worker.
+- Declare a path operation with plain `def` when its body calls a blocking
+  library with no async equivalent. FastAPI runs a `def` path operation in
+  an external threadpool automatically — this is current, documented
+  behavior, not a workaround — so a blocking call inside it does not block
+  the event loop.
+- The same rule applies to dependencies: a `def` dependency runs in the
+  threadpool, an `async def` dependency runs on the loop and must not
+  block. FastAPI accepts either kind of dependency under either kind of
+  path operation (an `async def` dependency under a `def` path operation
+  and vice versa), so choose per-dependency based on what its own body
+  does, not to match the path operation's own declaration.
+- For a compute-only path operation with no I/O at all, prefer `async def`
+  — it avoids the threadpool's scheduling overhead for work that was never
+  going to block anything.
+
+## Dependency injection
+
+- Use `Depends(...)` (or `Security(...)` for an auth dependency that also
+  carries OAuth2 scopes) to inject anything a path operation needs but
+  should not construct itself: a DB session, the current authenticated
+  user, pagination parameters, a feature flag. This is what makes each
+  piece independently testable via FastAPI's `app.dependency_overrides`.
+- Chain dependencies (a dependency that itself depends on another) instead
+  of duplicating the same setup logic across sibling dependencies — FastAPI
+  caches a dependency's result per request by default, so a shared
+  sub-dependency runs once even when several path-level dependencies need
+  it.
+- Use `yield` in a dependency that owns a resource needing teardown (a DB
+  session, a lock, an open connection); the code after `yield` runs after
+  the response is sent, even when the path operation raised — this is
+  FastAPI's own resource-lifecycle pattern for a request-scoped resource,
+  not a manual `try`/`finally` bolted onto a plain-return dependency.
+
+## Request/response modeling
+
+- Model every request body as a Pydantic `BaseModel`, never as a raw
+  `dict`/`Any` parameter — FastAPI validates the incoming JSON against the
+  model before the path operation body runs, which is the framework's own
+  first line of defense against malformed or malicious input (see
+  `rules/security.mdc`).
+- Use `field_validator`/`model_validator` (Pydantic v2) for a constraint
+  that spans multiple fields or needs custom logic beyond `Field(...)`'s
+  declarative constraints (`gt`, `max_length`, `pattern`), not a manual
+  `if`-check inside the path operation body after the model has already
+  validated.
+- Declare `response_model` (or a return-type annotation FastAPI can infer
+  one from) so the response is filtered to the declared fields even when
+  the object returned from the path operation carries more — this is a
+  correctness property, not just documentation: it is what keeps an
+  internal-only field out of the response body.
+
+## Background work
+
+- Use `BackgroundTasks` (injected the same way as any other dependency)
+  for work that must run after the response is sent but is short, best-
+  effort, and does not need retries, a result, or cross-process durability
+  (writing a log line, sending a best-effort notification).
+- Reach for a real task queue (Celery, arq, a message broker) instead of
+  `BackgroundTasks` once the work needs retries, visibility into failure,
+  distribution across multiple worker processes, or survival past the
+  serving process' lifetime — `BackgroundTasks` runs in-process and is lost
+  if the process restarts before it completes.
+
+## OpenAPI and schema
+
+- Let FastAPI generate the OpenAPI schema from type hints, `response_model`,
+  and `Field(...)` constraints rather than hand-maintaining a separate
+  OpenAPI YAML/JSON file alongside the code — the generated schema is what
+  keeps documentation and implementation from drifting apart.
+- Use `tags=[...]` on each `APIRouter`/path operation and a `summary`/
+  `description` (or a docstring, which FastAPI uses as the description)
+  for anything beyond an obvious CRUD endpoint, so the generated docs stay
+  usable as the API grows.
+
+## Anti-patterns to flag, not introduce
+
+- An `async def` path operation that calls a synchronous DB driver or
+  `requests.get` directly — this silently degrades every concurrent request
+  on that worker instead of raising an obvious error.
+- Accepting the request body as `request: Request` and manually calling
+  `await request.json()` to bypass Pydantic validation — this discards
+  FastAPI's own validation, error responses, and OpenAPI schema generation
+  for that endpoint.
+- Using `BackgroundTasks` for work that must not be lost (payment capture,
+  an email a user is relying on) instead of a real task queue with
+  retries.

package/src/gdskills/bundled/stacks/fastapi/rules/security.mdc

@@ -0,0 +1,99 @@
+---
+extends: common
+paths: ["**/*.py"]
+metadata:
+  origin: authored
+---
+
+# FastAPI security
+
+Narrows `python`'s security guidance to where FastAPI's own attack surface
+actually lives: path operations, dependencies, and request-body/response
+models — the code an unauthenticated or under-authenticated client can
+reach directly. In practice that means `routers/`/`api/` modules,
+`dependencies.py`, and `schemas/`/`models/` request-body definitions, not
+test files, where the same patterns (a hard-coded test JWT, a permissive
+CORS config asserted against) are often deliberately exercised rather than
+shipped.
+
+## Input validation
+
+- Type every request body, query, and path parameter through Pydantic (a
+  `BaseModel` for the body, typed function parameters for query/path
+  params) rather than reading raw JSON off `Request` — Pydantic validation
+  is FastAPI's primary injection defense: a field typed `int` cannot carry
+  a SQL-injection string or an oversized payload past validation the way an
+  untyped `dict`/`Any` parameter can.
+- Use `Field(...)` constraints (`max_length`, `gt`/`le`, `pattern`) on any
+  field whose size or shape matters for downstream safety (a filename, a
+  free-text field written to a file path, a numeric field used in a
+  calculation) — validating shape at the model is cheaper and more
+  reliable than validating it again deeper in the call stack.
+- Never accept a client-supplied value as a filesystem path, shell
+  argument, or SQL fragment without the same validation/parameterization
+  `python`'s `rules/security.mdc` already requires — FastAPI's own
+  validation does not substitute for parameterized SQL or `shell=True`
+  avoidance once the value leaves the Pydantic model.
+
+## Authentication and authorization
+
+- Put an auth check in a `Depends(...)` (or `Security(...)` for scoped
+  OAuth2) dependency shared across every path operation that needs it, not
+  duplicated inline in each path operation body — a dependency added once
+  and reused is much harder to accidentally omit from a new endpoint than
+  a copy-pasted inline check.
+- Use `OAuth2PasswordBearer`/`OAuth2PasswordRequestForm` (or the project's
+  existing auth scheme) with a real JWT library (`pyjwt`) and a password
+  hashing library (`pwdlib`/`passlib`) for credential handling — never
+  compare a plaintext password directly or hash it with a fast general-
+  purpose hash (`md5`, `sha256` with no salt/work factor).
+- Run the password-verify step even on a failed username lookup (compare
+  against a dummy hash) — skipping verification when the username is
+  unknown lets an attacker time the difference between "unknown user" and
+  "wrong password" and enumerate valid usernames.
+- Never trust a client-supplied role/permission field on the request body
+  to grant elevated access — authorization decisions come from the
+  authenticated user record (via the auth dependency) or a trusted store,
+  never from data the same request also supplies.
+
+## CORS
+
+- Configure `CORSMiddleware`'s `allow_origins` with an explicit list of
+  trusted origins for any API that accepts cookies/credentialed requests;
+  never combine `allow_origins=["*"]` with `allow_credentials=True` —
+  browsers reject that combination, and if a proxy or older client allowed
+  it anyway it would let any origin make authenticated requests on the
+  user's behalf.
+- Scope `allow_methods`/`allow_headers` to what the API actually needs
+  rather than defaulting every project to `["*"]`/`["*"]` out of habit.
+
+## Secrets and configuration
+
+- Read secrets (`SECRET_KEY`, database URLs, third-party API keys) through
+  `pydantic-settings`' `BaseSettings` (or the project's existing settings
+  module) backed by environment variables, never hard-coded in source —
+  including in an example/tutorial-style constant left over from scaffolding.
+- Generate a real `SECRET_KEY` per environment (e.g. `openssl rand -hex
+  32`) and never reuse a tutorial/example key found in documentation or a
+  starter template in anything beyond local experimentation.
+
+## Data access
+
+- Build SQL through the ORM's query builder or parameterized raw queries,
+  never by interpolating a Pydantic model's field into a SQL string — the
+  same rule `python`'s `rules/security.mdc` states for any Python code,
+  restated here because a validated Pydantic field is still just a string
+  once it reaches a raw query.
+
+## Red flags
+
+- "I'll read the body with `await request.json()` here, the Pydantic model
+  felt like overkill for one field" — skips validation entirely for that
+  endpoint; use a `BaseModel`, even a one-field one.
+- "`allow_origins=[\"*\"]` is fine, we don't use cookies" — true only until
+  the API adds a credentialed endpoint later; scope origins explicitly from
+  the start rather than relying on the current absence of cookies.
+- "This SECRET_KEY from the FastAPI tutorial is just a placeholder, I'll
+  swap it before we ship" — a placeholder committed to source control is a
+  leaked secret the moment the repository is; generate the real one at
+  deploy time from the environment instead.

package/src/gdskills/bundled/stacks/fastapi/rules/testing.mdc

@@ -0,0 +1,85 @@
+---
+extends: common
+paths: ["**/*.py"]
+metadata:
+  origin: authored
+---
+
+# FastAPI testing
+
+Narrows `python`'s `pytest` conventions to FastAPI's own test client and
+dependency-override patterns. Applies only to FastAPI project files; see
+`skills/fastapi-testing/SKILL.md` for the full test-authoring workflow this
+rule file backs.
+
+## Test client
+
+- Test path operations through `fastapi.testclient.TestClient` (sync tests)
+  or `httpx.AsyncClient` with `ASGITransport` (async tests) against the
+  real `app` instance, rather than calling the path operation function
+  directly — calling the function directly skips FastAPI's own request
+  parsing, dependency resolution, and response-model filtering, which is
+  exactly what most bugs in a path operation live in.
+- Build the `TestClient`/`AsyncClient` from a fixture shared across a test
+  module (or `conftest.py` once a second module needs it), not
+  re-instantiated per test, unless a test needs a differently configured
+  app instance.
+
+## Dependency overrides
+
+- Override a dependency for a test with `app.dependency_overrides[real_dep]
+  = fake_dep`, not by monkeypatching the dependency function's module
+  attribute — `dependency_overrides` is FastAPI's own supported mechanism
+  and is what keeps the override scoped to the app instance under test.
+- Clear `app.dependency_overrides` after each test that sets one (a fixture
+  `yield`ing the override and clearing it in teardown, or `.clear()` in the
+  test itself) — an override left in place leaks into unrelated tests run
+  afterward in the same process.
+- Use a dependency override for the current-user/auth dependency to test
+  both an authenticated and an unauthenticated path without standing up
+  real credential handling in every test.
+
+## Request/response assertions
+
+- Assert on the parsed response body (`response.json()`) and
+  `response.status_code`, not just that the call didn't raise — a path
+  operation that returns the wrong status code or a malformed body with no
+  exception is a real bug a bare "it didn't crash" assertion misses.
+- For a validation-error case, assert the `422` status FastAPI returns for
+  a Pydantic validation failure, not a generic exception — a request that
+  fails Pydantic validation never reaches the path operation body at all.
+- When `response_model` is declared, assert that a field the model
+  excludes (e.g. `hashed_password`) is actually absent from the response
+  body for at least one test — this is the behavior `response_model`
+  exists to guarantee, and a typo in the model's field list would
+  otherwise ship unnoticed.
+
+## Database and external dependencies
+
+- Use a real test database (a throwaway SQLite file, a test-scoped
+  Postgres schema, or the project's own configured test-DB fixture) behind
+  a `get_db`-style dependency override, not a hand-rolled mock of the ORM
+  session, for anything beyond the simplest unit test — an ORM session
+  mock only checks that the code called the mock the way the mock expects.
+- Mock genuinely external services (a third-party HTTP API, an email
+  provider) at the client boundary (`httpx`/`requests` mock, or the
+  project's configured HTTP mocking library), matching `python`'s own
+  testing rule: mock external dependencies, not internal collaborators.
+
+## Async tests
+
+- Mark an async test `pytest.mark.asyncio` (or the project's configured
+  async plugin/mode) exactly as `python`'s testing rule requires; this
+  applies the same way to a test that awaits `AsyncClient` calls against a
+  FastAPI app.
+
+## Coverage expectations
+
+- Every new or touched path operation gets at least one test for its
+  success path, its validation-failure path (a `422` for bad input when
+  the body is a Pydantic model), and, when it requires auth, both an
+  authenticated and an unauthenticated case.
+- A dependency with nontrivial logic (parses a header, decodes a token,
+  applies a business rule) gets its own test independent of any path
+  operation that happens to use it, in addition to the path operation's
+  own integration-level test.

package/src/gdskills/bundled/stacks/fastapi/skills/fastapi-build-fix/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: fastapi-build-fix
+description: "Use when a FastAPI app itself fails to start, import, or register a router -- app-startup failures, dependency-injection wiring errors (Depends() on the wrong callable, a missing sub-dependency), Pydantic v1/v2 model/validation errors, and a checker flagging a path-operation signature or response_model specifically, with the smallest root-cause fix. For a generic Python ModuleNotFoundError/packaging/dependency-resolver failure not specific to FastAPI's own app wiring, use python-build-fix."
+triggers:
+  - "fix this FastAPI app startup error"
+  - "the FastAPI app fails to import after adding a new router"
+  - "this Depends() dependency is failing to resolve"
+  - "this FastAPI path operation's response_model is rejecting valid data"
+  - "the linter flags this FastAPI router file specifically"
+  - "this Pydantic model keeps raising an unexpected validation error"
+  - "fix this FastAPI router registration error causing a 404"
+metadata:
+  origin: authored
+  category: build-fix
+  version: "1.0.0"
+  compatible_harnesses: "claude,codex,cursor,zed,opencode"
+license: "MIT"
+---
+
+# FastAPI build-fix
+
+Resolve a broken FastAPI app startup, dependency-injection wiring, type-
+check, or lint failure with the smallest change that fixes the actual
+cause. Scoped to FastAPI's own framework layer — for a generic Python
+`ModuleNotFoundError`, packaging, or dependency-resolver failure not
+specific to FastAPI's own app wiring, use `python-build-fix`; for adding a
+feature use `fastapi-implementation`; for writing/fixing test content (not
+a collection error) use `fastapi-testing`; for reviewing without fixing use
+`fastapi-code-review`.
+
+## Workflow
+
+### Step 1: Reproduce and classify the failure
+
+Run the project's own configured commands (discover the run prefix — `uv
+run`, `poetry run`, or none — from `pyproject.toml`):
+
+```bash
+ruff check .
+ruff format --check .
+mypy .   # or: pyright
+pytest -x -q
+python -c "import <app_module>"   # or: uvicorn <app_module>:app --port 0
+```
+
+Read the *first* error in each tool's output. Classify:
+
+- **App startup/import** — `app = FastAPI(...)` module fails to import, or
+  `uvicorn` fails to start the app (distinct from a generic Python
+  `ModuleNotFoundError` unrelated to FastAPI wiring — that goes to
+  `python-build-fix`).
+- **Router registration** — `app.include_router(...)` raises, a route
+  conflict (duplicate path + method), or a route silently 404s because it
+  was never registered.
+- **Dependency-injection wiring** — `Depends(...)` resolves to the wrong
+  callable, a sub-dependency is missing, or FastAPI reports it cannot
+  determine how to resolve a dependency's own parameters.
+- **Pydantic model errors** — a `BaseModel` raises at class-definition time
+  (bad field type, invalid `Field(...)` constraint) or at request-parse
+  time in a way that shouldn't be a validation error at all (a v1/v2
+  syntax mismatch is a common cause).
+- **Type errors** — `mypy`/`pyright` reports a real mismatch on a path
+  operation's parameters, return type, or a `Depends(...)`-injected value.
+- **Lint failures** — `ruff check` reports a rule violation.
+
+### Step 2: Find the root cause
+
+- **App startup/import**: does `app = FastAPI(...)` fail because a router
+  module it imports itself fails to import (circular import between
+  `main.py` and a router, or a router importing something not yet
+  defined)? Read the actual traceback's innermost frame, not just the
+  outermost "app failed to start" message.
+- **Router registration**: check `app.include_router(router, prefix=...,
+  tags=[...])` — a duplicated `prefix` across two routers, or a path
+  operation decorated on the wrong router variable, are the common causes
+  of a route that 404s despite the code appearing correct.
+- **Dependency-injection wiring**: read FastAPI's own error message about
+  which parameter it couldn't resolve; check whether the dependency
+  function's own parameters are all themselves either request data
+  (query/path/body) or other `Depends(...)` — a parameter with no default
+  and no `Depends(...)`/request-data annotation is what breaks resolution.
+- **Pydantic model errors**: confirm the pinned Pydantic version
+  (`pyproject.toml`) and whether the failing syntax is v1-only (`class
+  Config:`, `@validator`) or v2-only (`model_config = ConfigDict(...)`,
+  `@field_validator`) — mixing the two is the most common cause of a
+  confusing model-definition error.
+- **Type errors**: read the exact mismatch; a `Depends(...)`-injected
+  parameter's annotated type must match what the dependency function
+  actually returns — fix whichever side is actually wrong given the
+  dependency's real contract.
+- **Lint failures**: apply `ruff check --fix .` for mechanical fixes; for a
+  substantive rule, fix the flagged code.
+
+### Step 3: Apply the smallest fix
+
+- Fix the actual cause identified in Step 2 — the wrong `Depends(...)`
+  target, the router registered on the wrong variable, the v1/v2 syntax
+  mismatch, the real type mismatch.
+- Touch only what the failure requires; do not refactor unrelated
+  path operations or schemas while fixing a build failure.
+
+### Step 4: Verify
+
+Re-run every command from Step 1 in order; all must exit 0, including the
+app-import/startup check — a fix that satisfies `mypy`/`ruff` can still
+leave the app failing to start if a router or dependency wiring mistake
+remains.
+
+### Step 5: Report
+
+```
+Fixed: new `/webhooks/stripe` endpoint returns 404 in every environment
+  Root cause: routers/webhooks.py defines `router = APIRouter()` and the
+    route with `@router.post("/stripe")`, but main.py still calls
+    `app.include_router(legacy_router)` -- a leftover router object from
+    an earlier refactor that was never renamed -- so the new router
+    object is built but never mounted onto the app at all.
+  Fix: changed main.py to `app.include_router(webhooks_router,
+    prefix="/webhooks")`, pointing at the actual router object the new
+    route was added to, and removed the unused `legacy_router` import.
+  Verified: ruff check, mypy, pytest -x -q, and app import all green
+```
+
+## Rules
+
+- NEVER add `# type: ignore` or `# noqa` as a blanket suppression to make a
+  real error disappear without fixing or explicitly justifying it inline.
+- NEVER move a blocking call into an `async def` path operation (or leave
+  one there) to make an error disappear — if the fix requires the function
+  to stay blocking, keep it `def` so FastAPI's threadpool handles it.
+- NEVER widen a Pydantic field's type to `Any`/`dict` to make a validation
+  error stop, when the actual cause is a v1/v2 syntax mismatch or a genuine
+  schema bug.
+- Fix the root cause with the smallest change; do not refactor beyond what
+  the failure requires.
+
+## Red Flags
+
+| Rationalization | Why it is wrong |
+|---|---|
+| "This Pydantic validation error is annoying, I'll just type the field `Any`" | Hides the real schema mismatch (often a v1/v2 syntax mix) instead of fixing it; find and fix the actual cause |
+| "The dependency resolution error is confusing, I'll just remove the `Depends(...)` and call the function directly" | Removes dependency injection entirely, losing `dependency_overrides` testability and any caching FastAPI provided; fix the actual parameter FastAPI couldn't resolve |
+| "I'll add `# type: ignore` here, the real fix is bigger" | Hides the type hole permanently; if the real fix is out of scope, say so in the report and leave the error visible |
+| "ruff flagged something in this router, I'll disable the rule in `pyproject.toml`" | Disables it project-wide for all future code, not just this failure; fix the flagged code instead |
+
+## Verification
+
+Do not report the fix done until all of the following hold:
+
+- The originally failing command now exits 0.
+- `ruff check .`, `ruff format --check .`, `mypy .`/`pyright`, `pytest -x
+  -q`, and the app import/startup check all exit 0.
+- No new `# type: ignore`/`# noqa` was added without an inline reason, and
+  none was added as a blanket suppression.
+- `git status` shows only the files whose actual cause was diagnosed in
+  Step 2 — no unrelated refactor.
+- The report names the root cause, not just the symptom that was fixed.