Update AGENTS.md file

AGENTS.md

@@ -121,6 +121,12 @@ configured and difficult to re-stabilize.
 
 ### Always do these:
 
+- **ALWAYS update `AGENTS.md` when your work changes anything documented here** —
+  architecture, file paths, new files, Payload config, known issues, workflows. Do
+  this in the same task, not as a follow-up. The intro says this too but it bears
+  repeating as a hard rule: the next agent reads this file first and will be misled
+  by stale information.
+
 - **ALWAYS use `bun typecheck` to validate your work**, never `bun build`. Typecheck
   is fast and sufficient. Build is slow and for production deployments only.
 
@@ -531,9 +537,11 @@ packages/backend/
 │   ├── auth.ts                # Auth setup + all user-related functions
 │   ├── crons.ts               # Cron jobs (commented examples)
 │   ├── files.ts               # File upload/storage
+│   ├── globals.d.ts           # Types process.env for Convex backend env vars
 │   ├── http.ts                # HTTP routes (auth only) — DO NOT TOUCH
 │   ├── schema.ts              # Database schema — the source of truth
 │   └── tsconfig.json          # Convex-required TS config
+├── eslint.config.ts           # ESLint config for the backend package
 ├── scripts/
 │   └── generateKeys.mjs       # RS256 JWT keypair generator for Convex Auth
 └── types/
@@ -547,6 +555,19 @@ structure. When `bun typecheck` runs from the repo root, it will print TypeScrip
 output for `@gib/backend` (because there's no valid project to check). This is
 expected and not an error.
 
+**Note on `globals.d.ts`:** The Convex runtime supports `process.env` for reading
+environment variables set in the Convex Dashboard. Because the Convex tsconfig does
+not include `@types/node`, `process` would otherwise be untyped. `globals.d.ts`
+declares `process.env` with the specific variables this backend uses. If you add a
+new env var to the Convex backend, add it here too so TypeScript and ESLint are happy.
+
+**Note on `convex/utils.ts`:** This file may be regenerated by `convex dev` as a
+Convex CLI utility scaffold. It contains `missingEnvVariableUrl` / `deploymentName`
+helpers that reference `CONVEX_CLOUD_URL` — a Convex Cloud concept irrelevant to this
+self-hosted setup. If the file reappears, you can safely delete it (nothing in the
+codebase imports it) or leave it — it won't affect runtime behaviour since the
+functions are never called.
+
 ### Schema design — always extend `users` directly
 
 The preferred and enforced approach in this repo is to **extend the `users` table
@@ -825,6 +846,14 @@ Current state of the template:
   content is partial or missing fields
 - live preview works by loading `/` with `?preview=true` and rendering
   `RefreshRouteOnSave`
+- `payload.config.ts` sets `serverURL: env.NEXT_PUBLIC_SITE_URL` — required for
+  Payload to construct absolute URLs in the admin UI and live preview
+- `get-landing-page-content.ts` only calls `noStore()` when `isPreview` is true —
+  normal (non-preview) requests are cacheable by Next.js. Do not add `noStore()`
+  back unconditionally.
+- `apps/next/src/app/(frontend)/page.tsx` wraps the Payload fetch in a try/catch and
+  falls back to `defaultLandingPageContent` if Postgres is unreachable — the landing
+  page always renders even when the CMS is down
 
 If you need a deeper walkthrough, read `docs/payload-cms.md`. That file should stay in
 sync with the actual Payload implementation in this repo.

apps/next/payload-types.ts

@@ -77,15 +77,9 @@ export interface Config {
   collectionsSelect: {
     users: UsersSelect<false> | UsersSelect<true>;
     'payload-kv': PayloadKvSelect<false> | PayloadKvSelect<true>;
-    'payload-locked-documents':
-      | PayloadLockedDocumentsSelect<false>
-      | PayloadLockedDocumentsSelect<true>;
-    'payload-preferences':
-      | PayloadPreferencesSelect<false>
-      | PayloadPreferencesSelect<true>;
-    'payload-migrations':
-      | PayloadMigrationsSelect<false>
-      | PayloadMigrationsSelect<true>;
+    'payload-locked-documents': PayloadLockedDocumentsSelect<false> | PayloadLockedDocumentsSelect<true>;
+    'payload-preferences': PayloadPreferencesSelect<false> | PayloadPreferencesSelect<true>;
+    'payload-migrations': PayloadMigrationsSelect<false> | PayloadMigrationsSelect<true>;
   };
   db: {
     defaultIDType: number;
@@ -639,6 +633,7 @@ export interface Auth {
   [k: string]: unknown;
 }
 
+
 declare module 'payload' {
   export interface GeneratedTypes extends Config {}
-}
+}

apps/next/src/app/(payload)/admin/importMap.js

@@ -1,6 +1,5 @@
-import { CollectionCards as CollectionCards_f9c02e79a4aed9a3924487c0cd4cafb1 } from '@payloadcms/next/rsc';
+import { CollectionCards as CollectionCards_f9c02e79a4aed9a3924487c0cd4cafb1 } from '@payloadcms/next/rsc'
 
 export const importMap = {
-  '@payloadcms/next/rsc#CollectionCards':
-    CollectionCards_f9c02e79a4aed9a3924487c0cd4cafb1,
-};
+  "@payloadcms/next/rsc#CollectionCards": CollectionCards_f9c02e79a4aed9a3924487c0cd4cafb1
+}

packages/backend/convex/globals.d.ts

@@ -5,7 +5,6 @@ declare const process: {
     readonly USESEND_API_KEY?: string;
     readonly USESEND_URL?: string;
     readonly USESEND_FROM_EMAIL?: string;
-    readonly CONVEX_CLOUD_URL?: string;
     readonly [key: string]: string | undefined;
   };
 };

turbo.json

@@ -16,7 +16,6 @@
     "CONVEX_SELF_HOSTED_URL",
     "CONVEX_SELF_HOSTED_ADMIN_KEY",
     "CONVEX_SITE_URL",
-    "CONVEX_CLOUD_URL",
     "USESEND_API_KEY",
     "USESEND_URL",
     "USESEND_FROM_EMAIL",