AGENTS.md

AGENTS.md

Entry point for AI agents (Cursor reads this file natively; Claude Code imports it from CLAUDE.md). The rules and architecture live in docs/ — that is the single source of truth; this file is only a map and a short summary. Edit content in docs/, not here.

What this project is

Languages Learner is an Nx + pnpm monorepo for a language-learning web app. apps/* (web, backend, storybook, web-e2e) and packages/* (reusable libraries). Node 20, pnpm 10.6.2. Full overview: docs/architecture/overview.md.

Documentation map

• docs/index.md — the root map of all documentation.
• Architecture: overview · package interaction · web SSR · backend · data layer · i18n · API contract
• Packages: docs/packages/ (one page per workspace package).
• Conventions · Roadmap · Maintaining docs

Core working rules

• English only in docs and code (identifiers, comments, commit messages). Chat with the user in the user's language.
• FSD flows downward. In apps/web/src/ui, imports go app → pages → widgets → features → entities → shared; cycles are forbidden (madge). See package-interaction.md.
• res.locals is the SSR contract. Adding server-derived state touches the middleware, render, window.CLIENT, Locals, and Window.CLIENT. See web-ssr.md.
• Supabase credentials are runtime config. Do not add VITE_-prefixed copies (that bakes them into the bundle).
• Do not containerise apps/web and do not add a web service to docker-compose.dev.yml.
• Backend: no Scope.REQUEST and no authentication inside provider factories; there is no service-role key. See backend.md.
• Do not edit generated files (database.types.ts, openapi.json, api.ts); after changing a DTO, regenerate the schemas. See api-contract.md.
• Formatting and code rules — conventions.md.

Keeping docs current (Definition of Done)

Change code → update the matching page in docs/; complete a roadmap item → move it to Done. Before a PR: pnpm docs:check. The "code path → what to update" trigger table and the full rule set are in maintaining-docs.md.