docs: update instructions for python, pytest, and react router

Generated-by: aiautocommit

Author: iloveitaly

.github/copilot-instructions.md

@@ -34,5 +34,5 @@ session_id = client_secret_id.split("_secret")[0]
 
 ### Agent instructions
 
-- When running python tests, use an already open terminal and the `pytest` binary.
+- Run python tests with `pytest` only. If tests fail because of a configuration or system error, do not attempt to fix and let me know. I will fix it.
 - If you added models, generate a migration with `just migration {add,delete,update}_model_other_description`

.github/instructions/pytest-integration-tests.instructions.md

@@ -4,7 +4,7 @@ applyTo: "tests/integration/**/*.py"
 ## Pytest Integration Tests
 
 - Look to tests/factories.py to generate any required database state
-  - Here's an example of how to create + persist a factory `DistributionFactory.save()`
+  - Here's an example of how to create + persist a factory `DistributionFactory.build(domain=PYTHON_TEST_SERVER_HOST).save()`
 - Add the `server` factory to each test
 - Use the `faker` factory to generate emails, etc.
 - Don't add obvious `assert` descriptions

.github/instructions/python.instructions.md

@@ -16,6 +16,7 @@ When writing Python:
   * No variable interpolation in log messages.
   * Do not coerce database IDs or dates to strings
 * Do not fix import ordering or other formatting issues.
+* Do not ever edit any files in `migrations/versions/`
 
 ### Date & DateTime
 

.github/instructions/react-router.instructions.md

@@ -4,6 +4,7 @@ applyTo: "web/app/routes/**/*.tsx"
 ## React Router
 
 - You are using the latest version of React Router (v7).
+- Always include the suffix `Page` when naming the default export of a route.
 - The primary export in a routes file should specify `loaderData` like `export default function RouteNamePage({ loaderData }: Route.ComponentProps)`. `loaderData` is the return value from `clientLoader`.
 - Use `href("/products/:id", { id: "abc123" })` to generate a url path for a route managed by the application.
   - Look at [routes.ts](mdc:web/app/routes.ts) to determine what routes and path parameters exist.
@@ -43,7 +44,7 @@ export async function clientLoader(loaderArgs: Route.ClientLoaderArgs) {
 }
 ```
 
-### How to use clientLoader
+### How to Use `clientLoader`
 
 - `export async function clientLoader(loaderArgs: Route.ClientLoaderArgs) {`
 - Load any server data required for page load here, not in the component function.
@@ -53,10 +54,38 @@ export async function clientLoader(loaderArgs: Route.ClientLoaderArgs) {
 - `loaderArgs` and all sub-objects are all fully typed
 - `loaderArgs.params.id` to get URL parameters
 
-### Using API Data
+### Loading Backend Data
 
 - `~/configuration/client` re-exports all types and functions from `client/*`. Import from `~/configuration/client` instead of anything you find in the `client/` folder/package.
 - For each API endpoint, there's a fully typed async function that can be used to call it. Never attempt to call an API endpoint directly.
+  - Do not generate types for API parameters or responses. Reference the autogenerated types that are re-exported in `~/configuration/client`
+  - For instance, the `getSignedUrl` function in [web/client/sdk.gen.ts] has a `SignedUrlResponse` type in [web/client/types.gen.ts]
+  - This same type is used in the function signature, i.e. `type SignedUrlResponse = Awaited<ReturnType<typeof getSignedUrl>>["data"]`
+
 - When using an import from `~/configuration/client`:
   - use `body:` for request params
   - always `const { data, error } = await theCall()`
+
+`clientLoader` can only be used on initial page load within a route. If you need to load additional server data on component mount:
+
+```tsx
+import { useQuery } from "@tanstack/react-query"
+import {
+  // these options correspond to the server route
+  createCheckoutSessionOptions,
+  publicClient,
+} from "~/configuration/client"
+
+function TheComponent() {
+  const { data, error } = useQuery({
+    enabled: open,
+    ...createCheckoutSessionOptions({
+      // or `client` if authenticated
+      client: publicClient,
+      body: { /* API parameters here */ },
+    }),
+  })
+
+  // remember to display errors by checking `error`
+}
+```

.github/instructions/typescript.instructions.md

@@ -8,6 +8,7 @@ applyTo: "**/*.ts,**/*.tsx"
 - Use `lib/` for generic code, `utils/` for project utilities, `hooks/` for React hooks, and `helpers/` for page-specific helpers.
 - Prefer `function theName() {` over `const theName = () =>`
 - Use `import { invariant } from @epic-web/invariant` instead of another invariant library
+- Use `requireEnv("VITE_THE_ENV_VAR")` instead of `process.env.THE_ENV_VAR`
 
 Here's how frontend code is organized in `web/app/`: