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, and its own data volume. Convex does not use Postgres unless a cloned project explicitly enables the commented optional POSTGRES_URL example.

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

bun db:up          # start Convex and dashboard
bun dev:next       # host Next + deploy/watch local Convex functions
bun db:down        # stop and preserve Convex data
bun db:down:wipe   # remove Convex volume and generated admin key

Local URLs: app http://localhost:3000, Convex http://localhost:3210, dashboard http://localhost:6791. Use INFISICAL_ENV=staging bun dev:next for staging services. Normal db:up never connects to staging and does not start Postgres.

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.

2.8 KiB Raw Blame History