Initial commit for project Spoon!

2026-06-21 17:52:02 -05:00
commit cf7ff2ee4e
268 changed files with 32981 additions and 0 deletions
@@ -0,0 +1,63 @@
+# AGENTS.md
+
+## Architecture
+
+- `apps/next`: Next.js 16 frontend.
+- `apps/expo`: Expo scaffold; only work here when explicitly requested.
+- `packages/backend/convex`: self-hosted Convex functions, schema, and auth.
+- `packages/ui`: shared shadcn-based UI components.
+- `tools`: shared ESLint, Prettier, Tailwind, TypeScript, and Vitest config.
+- Local development uses host-run apps, local Convex on ports 3210/3211, local
+  Postgres on port 5432 for Convex storage, and the Convex dashboard on port 6791.
+
+## Protected and generated files
+
+- Never edit `packages/backend/convex/_generated/**` or
+  `packages/backend/convex/http.ts`.
+- Do not rename `apps/next/next.config.js` or `apps/next/src/proxy.ts`.
+- Preserve `typescript.ignoreBuildErrors` in Next config.
+- Do not modify Sentry config or `tools/tailwind/theme.css` unless requested.
+- Generated `.cache`, `.turbo`, `.local`, and environment files are ignored.
+
+## Environment rules
+
+- Local `dev` and `staging` come only from Infisical via
+  `scripts/with-env`; it never falls back to `.env*`.
+- Run `infisical login` and `infisical init` before local development.
+- Machine-generated values belong in `.local/<env>.generated.env`; never put
+  the generated Convex admin key in shared Infisical.
+- CI uses Gitea-injected secrets or `CI_ENV_FILE` and must not call Infisical.
+- App code imports validated variables from `@/env`, never `process.env`.
+- Add cache-relevant variables to `turbo.json` `globalEnv`.
+
+## Code and dependency rules
+
+- Use `const` arrow functions instead of function declarations.
+- Add `.js` extensions to Convex generated-file imports.
+- Put custom frontend routes directly in `apps/next/src/app` or normal route
+  groups such as `apps/next/src/app/(auth)`.
+- Extend the Convex `users` table for application user data; do not add a
+  profile table by default. Authenticate protected functions.
+- Manage shared versions in root catalogs. Never run `bun update` in a package.
+- Run root `bun install` and verify with `bun lint:ws`.
+- Update this guide when architecture or workflows change.
+
+## Local stack
+
+```sh
+bun db:up          # start Postgres, Convex, and dashboard
+bun dev:next       # host Next + deploy/watch local Convex functions
+bun db:down        # stop and preserve local data
+bun db:down:wipe   # remove local data volumes and generated admin key
+```
+
+Local URLs: app `http://localhost:3000`, Convex `http://localhost:3210`,
+dashboard `http://localhost:6791`, Postgres `localhost:5432`.
+Use `INFISICAL_ENV=staging bun dev:next` for staging services. Normal `db:up`
+never connects to staging.
+
+## Validation
+
+Use `bun typecheck`, never a production build for routine validation. The full
+gate is `SKIP_E2E=1 bun run ci:check`; local-stack smoke e2e is `bun test:e2e`.
+Pre-commit runs lint-staged serially and pre-push runs the bounded full gate.