Enhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active
TypeScript aianthropicartifactsawsazurechatgptchatgpt-cloneclaudeclonedeepseekgeminigooglegpt-5librechatmcpo1openairesponses-apivisionwebui
🧤 docs: Define Safe Backend Error Contracts in AGENTS.md (#16443)
lia-by-librechat[bot]76dbb931a17a
diff --git a/AGENTS.md b/AGENTS.mdindex 13d8f4ca20..594e547840 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -1,4 +1,9 @@-See CLAUDE.md.+# LibreChat contributor and agent guidance++`AGENTS.md` is the repository's contributor guidance. Backend code lives in `packages/api`+(TypeScript) and `packages/data-schemas` (database methods); `api` is legacy Express wiring.+Shared API types and services live in `packages/data-provider`, and the React app lives in+`client` with shared primitives in `packages/client`.## Branching and pull requests@@ -18,8 +23,9 @@ explicitly based on `canary` stays there; the main-to-dev retarget workflow doesStill link related issues in the PR (for example, `Related to #N`) so the work remainstraceable. `Fixes #N` does not close an issue on a `dev` or `canary` merge — GitHub honors closingkeywords only on the default branch. Close resolved issues by hand after merging. Worktrees share-one stash stack, so never use a bare `git stash pop`. See the detailed policy in `CLAUDE.md` under-"Branching and Pull Requests".+one stash stack, so never use a bare `git stash pop`. Prefer a WIP commit; if a stash is necessary,+apply the specific tagged entry. The `target: main` label and release-bound upstream branches are+exempt from the main-to-dev retarget workflow; do not use either to backport ordinary work.Write the description for a reader who has not followed the branch: what breaks, what triggers it,how it behaves after the change, then one or two views of the mechanism — a focused diff, a call@@ -34,17 +40,18 @@ Read the inline review threads themselves — a summary comment or notificationAudit each one against the current code, fix what is valid, and reject what is obsolete in a replythat says why. After each round: focused tests, `npx tsc --noEmit` in every workspace you changed,push, then request the next review naming the pull request's exact remote head — a clean review of-an earlier head says nothing about what you just pushed, and CI runs on its own clock. After two-actionable rounds, stop patching thread by thread and read the subsystem by invariant instead.-Which reviewer and what phrase triggers it will change; that the review must cover the exact pushed-head will not.+an earlier head says nothing about what you just pushed, and CI runs on its own clock. Reply on+each resolved thread with the resolving commit and evidence. After two actionable rounds, stop+patching thread by thread and read the subsystem by invariant instead: identity, authorization,+persistence, retry, cancellation, cleanup and mixed-version behavior where relevant. Which reviewer+and what phrase triggers it will change; that the review must cover the exact pushed head will not.A clean review is one completion signal, not the definition of done. Ship the observable experience— loading, empty, success, failure, cancellation, retry, restored session — with strings localized,accessibility intact, defaults and stored data preserved, and no backend capability left without a-frontend entry point. Report the pushed head, what you ran locally, CI state, the review result at-that head, and any finding you rejected with the reasoning. See `CLAUDE.md` under "Review and-Completion".+frontend entry point. Keep fixes small and test the missed behavior. Report the pushed head, what you+ran locally, CI state, the review result at that head, any finding you rejected with the reasoning,+and checks you could not run.## Verification@@ -56,11 +63,17 @@ See [budgets, reproduction and failure diagnosis](e2e/lighthouse/README.md).A green build is not a typecheck: `packages/api`, `packages/client` and `packages/data-schemas` buildwith `tsdown`, which emits without checking types. Run `npx tsc --noEmit` in the workspace youchanged. `packages/client` excludes `*.spec.ts(x)` and `*.test.ts(x)` from typechecking entirely.-`npm run sort-imports` with no arguments rewrites every source root — pass the paths you touched. See-`CLAUDE.md` under "Typechecking" and "Formatting".+`npm run sort-imports` with no arguments rewrites every source root — pass the paths you touched.+Run `npm run static-checks -- --against origin/dev` to reproduce the PR's static checks; use+`npm run static-checks:full` for the slower gates. Fix all formatting, lint, and TypeScript+warnings/errors in the code you change.## Module boundaries and configuration+All new backend behavior belongs in TypeScript under `packages/api`; database-specific shared logic+belongs in `packages/data-schemas`, and frontend/backend shared API logic belongs in+`packages/data-provider`. Build data-provider from the project root with `npm run build:data-provider`.+`/api` holds wiring, not behavior. When a change would add logic to a CJS file there — a branch, ahelper, a validation step, a service call — the logic belongs in `packages/api`, and the JS filekeeps requires, route registration and the call into the TS module (`MCPRequestContext.js` is the@@ -85,7 +98,46 @@ supplies, so a second implementation is a new argument instead of a new branch.under `packages/api/src/mcp` are the shape to stop extending, not a pattern to copy. This is thebackend half of client state ownership: pass it in, do not reach for it.-See `CLAUDE.md` under "Workspace Boundaries".+## Service failures and user-facing errors++This section applies to backend services (`packages/api`) and database methods/repositories+(`packages/data-schemas`), not to React components. For new or substantially changed code in+those layers, choose failure behavior at the contract boundary instead of treating every+unsuccessful outcome as an exception:++- Return a plain value on success. Use `null` only for a documented absence (for example, a+ successful lookup with no record), never to hide a query failure.+- For an expected failure the caller can handle without aborting the operation, prefer a typed+ discriminated result such as `{ ok: true; value: T } | { ok: false; error: { code: string;+ message?: string } }`. Keep an existing domain-specific result shape when changing it would+ break callers; do not introduce interchangeable `ok`, `valid`, and bare `{ message }` contracts+ in the same service. Codes should be stable, machine-readable identifiers when the caller+ needs to distinguish failures. Internal validation helpers may use the existing local pattern.+- Throw for unexpected operational failures (database, provider, network) and violated invariants.+ Use a typed/coded error when a boundary must recognize a particular failure. Catch where you can+ recover or translate it; otherwise let it reach the owning request or job boundary. Do not catch+ an exception and return a truthy record, `null`, or `{ message }` in its place: callers can then+ mistake an outage for data or send it as an HTTP 200. Keep separate migrations for existing+ contracts, with their callers and tests, rather than changing wire shapes incidentally.+- At the HTTP, stream, or job boundary, map failures to the existing status and response contract.+ Only expose intentionally approved codes and helpful user-safe information. Error disclosure is+ a security boundary: never forward raw exceptions, stacks, query text, credentials, request+ bodies, headers, provider payloads, or arbitrary `error.message` to a client or persisted+ user-visible status. Sanitize diagnostics and log only what the path can safely retain. For+ errors that may echo submitted content, prefer `getSafeErrorMetadata` over error text;+ `packages/api/src/utils/errors.ts` documents when redacted error text is appropriate.+- Localization is a UI responsibility, not a database-method return shape. When a failure reaches+ a user-facing surface, expose a safe, stable code the UI can map to localized, actionable copy+ and a fallback. See `client/src/components/Messages/Content/Error/registry.ts` and+ `client/src/components/Chat/Trace/Viewer.tsx`. Keep any intentionally disclosed provider detail+ behind its existing protection policy rather than treating arbitrary upstream text as safe.++Examples of local contracts, not a mandate to copy their shapes: `packages/api/src/admin/auditLog.ts`+uses a parsing result, `packages/api/src/agents/openai/service.ts` validates before mapping to an+OpenAI-compatible response, and `packages/api/src/skills/sync/errors.ts` names a sync failure by+stable code. `packages/data-schemas/src/methods/prompt.ts` currently returns `{ message }` on query+failure; do not extend that pattern. Test absence versus failure, the boundary's non-success response,+and that sensitive diagnostics cannot reach a user-visible surface.## Frontend theming and styling@@ -93,15 +145,16 @@ For frontend work, compose existing `@librechat/client` primitives and variantsfeature-local styles. Use semantic theme/Tailwind roles for color and shared appearance; do notintroduce raw palette utilities, hard-coded colors, or arbitrary theme CSS. If the system cannotexpress a reusable design need, deepen the shared primitive or versioned theme-token registry-instead of copying classes into a feature. Keep genuine layout and behavior local, and document-why any new custom CSS cannot be expressed by the shared system. See the detailed policy in-`CLAUDE.md` under “Theming and styling.”+instead of copying classes into a feature. Theme definitions select semantic colors and appearance,+not selectors, app behavior, or alternate layouts. Keep genuine layout and behavior local, and+explain why any new custom CSS cannot use shared primitives. Support light/dark and reduced motion;+preserve defaults and test a deliberately different reference theme for reusable new variants.## Backend auth cacheWhen adding or changing code that mutates user documents, invalidate the auth user document cache-for affected users, including bulk role and user mutations. See the detailed policy in `CLAUDE.md`-under “Auth cache invalidation”.+for affected users, including bulk role and user mutations. Otherwise burst-cached JWT requests can+serve a stale `req.user` until the cache expires.## Client state ownership@@ -115,5 +168,38 @@ and keep it inside the feature; app-global preferences and shell state a featurethrough props or a small host-supplied context rather than reached for through `~/store`; when aconsumer sits outside the feature you are changing, leave that atom on Recoil and pass it in. Passingthem in is what lets a feature move to its own workspace later without a rewrite, and it keeps the-Jotai conversion scoped to the state a feature owns. See the detailed policy in `CLAUDE.md` under-“Client State Ownership”.+Jotai conversion scoped to the state a feature owns. For persisted atoms, use the helpers in+`client/src/store/jotai-utils.ts`.++## Code style and performance++Use short, single-word file names when possible; group related modules in a single-word directory.+Prefer flat early returns, pure functions, and explicit types. Avoid `any`, broad `unknown`/casts,+duplicated types, and dynamic imports. Extract genuinely repeated logic instead of copying it;+write comments only for non-obvious behavior or public API contracts.++Imports have three sections: package values (shortest line first, with `react` first), `import type`+(longest line first, package types before local types), and local/project values (longest line first).+Use standalone `import type { ... }`, not inline `type` within a value import. Run the scoped+import sorter on files you change.++Avoid extra passes over shared message arrays and unnecessary allocations. For startup and+request paths, reuse already-loaded user/config data, avoid serial database reads, and start+independent reads in parallel. Do not weaken authorization or tenant checks or write a response+before those checks succeed.++## Frontend rules++Use `useLocalize()` for all visible copy and update only English keys in+`client/src/locales/en/translation.json`. Use semantic HTML, keyboard behavior, and ARIA labels.+Use React Query for API interactions and invalidate related queries after mutations; define query+and mutation keys in `packages/data-provider/src/keys.ts`. Put shared endpoint definitions, types,+and data services in `packages/data-provider`, and encode dynamic URL parameters. Cover loading,+success, and failure states in focused component tests.++## Testing++Run focused Jest tests from the owning workspace, not the entire monorepo. Prefer real logic and+spies over mocked internals; use `mongodb-memory-server` for database queries and the real MCP SDK+for MCP behavior. Mock only external HTTP APIs or uncontrollable services. For frontend tests use+the component's colocated `__tests__` and `test/layout-test-utils` where applicable.diff --git a/CLAUDE.md b/CLAUDE.mddeleted file mode 100644index 0331e00921..0000000000--- a/CLAUDE.md+++ /dev/null@@ -1,391 +0,0 @@-# LibreChat--## Project Overview--LibreChat is a monorepo with the following key workspaces:--| Workspace | Language | Side | Dependency | Purpose |-|---|---|---|---|---|-| `/api` | JS (legacy) | Backend | `packages/api`, `packages/data-schemas`, `packages/data-provider`, `@librechat/agents` | Express server — minimize changes here |-| `/packages/api` | **TypeScript** | Backend | `packages/data-schemas`, `packages/data-provider` | New backend code lives here (TS only, consumed by `/api`) |-| `/packages/data-schemas` | TypeScript | Backend | `packages/data-provider` | Database models/schemas, shareable across backend projects |-| `/packages/data-provider` | TypeScript | Shared | — | Shared API types, endpoints, data-service — used by both frontend and backend |-| `/client` | TypeScript/React | Frontend | `packages/data-provider`, `packages/client` | Frontend SPA |-| `/packages/client` | TypeScript | Frontend | `packages/data-provider` | Shared frontend utilities |--The source code for `@librechat/agents` (major backend dependency, same team) lives at-<https://github.com/LibreChat-AI/agents>.-------## Workspace Boundaries--- **All new backend code must be TypeScript** in `/packages/api`.-- **`/api` holds wiring, not behavior.** When a change would add logic to a CJS file under `/api` —- a branch, a helper, a validation step, a new service call — that logic goes in `/packages/api`,- and the JS file keeps only what wires it up: requires, route registration, request plumbing, and- the call into the TS module. `api/server/services/MCPRequestContext.js` is the shape, at thirteen- lines of re-export. "Minimum" describes how much behavior `/api` gains, not how small the diff is:- lifting a function into `/packages/api` and calling it is the larger diff and the correct one.- Editing an existing CJS file is the common case and the rule applies there, not only to new files.-- Database-specific shared logic goes in `/packages/data-schemas`.-- Frontend/backend shared API logic (endpoints, types, data-service) goes in `/packages/data-provider`.-- Build data-provider from project root: `npm run build:data-provider`.-- **Database contracts stay inside `/packages/data-schemas`.** A Mongoose type in an exported- signature — `FilterQuery`, `Types.ObjectId`, `Document`, `HydratedDocument` — makes the storage- engine part of that module's public API, and every consumer then depends on Mongo instead of on- the data it needs. Take and return plain typed objects, and express the query behind a- data-schemas method. The boundary already leaks across dozens of files in `/packages/api`, so the- rule is to stop widening it rather than to rewrite what exists; `/client` carries none of it and- must stay that way.-- **New levers ship configurable.** A limit, timeout, toggle or capability introduced in code earns- a field on `configSchema` (`packages/data-provider/src/config.ts`) so an operator can set it in- `librechat.yaml`, with a default that reproduces today's behavior. Hard-coded constants and- env-only switches need a reason. The schema is also what keeps one definition of the value instead- of a constant, a fallback and a doc line that drift apart.-- **A backend module takes its dependencies, it does not reach for them.** Code in `/packages/api`- should receive its config, database methods and clients from the caller the way- `createModels(mongoose)` receives the app's connection, rather than importing app singletons or- reading global state. A module the caller constructs can be tested without a running app and moved- to another workspace without a rewrite; one that calls `getInstance()` can do neither. This is the- backend half of "Client State Ownership" — pass it in, do not reach for it. The static singletons- under `packages/api/src/mcp` are the shape to stop extending, not a pattern to copy.-- **Integrations arrive through an interface the caller supplies.** A provider SDK, storage backend,- vector store or OAuth server is injected, so a second implementation is a new argument instead of- a new branch in shared code, and a test can exercise the real logic against a substitute at the- boundary rather than mocking the module that holds it.-------## Branching and Pull Requests--- **Normally branch off `dev` and target `dev`.** This is the default for work ready to follow the- regular release path. A maintainer-directed canary exception is described below.-- **`main` is the released branch.** It is kept as a fast-forward of `dev` and synced as-is, so it- is always an ancestor of `dev` — equal to it right after a sync, behind it otherwise. It never- carries a commit that `dev` does not have.-- **Never open a backport pull request to `main`.** Anything merged to `dev` reaches `main` at the- next sync; a second pull request for the same change is redundant.-- **The repository's default branch is `main`**, so `gh pr create` and the GitHub UI target it- unless told otherwise — pass `--base dev` for normal work or `--base canary` for an explicitly- maintainer-directed canary PR.-- Pull requests opened against `main` are retargeted to `dev` automatically by- `.github/workflows/pr-retarget-dev.yml`. The `target: main` label exempts one, as do release-bound- upstream branches (`dev`, `release/*`, `hotfix/*`). PRs deliberately based on `canary` are not- retargeted, including manual sweeps; the script skips them explicitly. Backport branches are- deliberately not exempt — a backport merged straight to `main` breaks the fast-forward invariant.-- **Canary is an explicit, maintainer-selected integration target, not a path that automatically- flows to `dev` or `main`.** Experimental changes and PRs that are ready to merge following review- but must not enter the next `main` sync can go to `canary`. The maintainer may decide this when- assigning the work or while reviewing an older/stale PR. For a new canary PR, branch from the- current `origin/canary` and set `--base canary`. Never infer that a canary-targeted PR should move- to `dev` just because `dev` is the default; do not copy canary features into `dev` without an- explicit maintainer decision. If a stale PR is reassigned to canary, check the PR's base, diff and- exact reviewed head against current canary before changing its base or proposing a new canary- branch/PR; if a rebase changes the head, verify and review that new head before merging.-- **Link related issues in the PR even when they will not auto-close.** Reference each relevant- issue in the description (for example, `Related to #N`) so reviewers can find the context and- track the work. GitHub honors `Fixes #N` and other closing keywords only when a pull request- merges into the default branch (`main`). Merging to `dev` or `canary` does not close an issue,- and the later fast-forward of `main` is not a merge event either — close resolved issues by hand- after merging.-- **Git worktrees share one stash stack.** `refs/stash` lives in the common `.git` directory, so a- bare `git stash pop` in one worktree can take work stashed in another. Prefer a throwaway WIP- commit; if you must stash, `git stash push -m <tag>` and `apply` that specific entry.-- **Write the description for a reader who has not followed the branch.** Say what breaks, what- triggers it, and how it behaves after the change, then show the mechanism with whichever one or- two views make it reviewable — a focused diff, a call tree, a shallow file tree, or a Mermaid- sequence — keeping only the calls, files and state the change actually carries. Describe the code- as it stands: do not narrate what earlier commits tried or what a review round changed. Naming the- merged pull request that caused the bug is different — that is history the reader needs.- `.github/pull_request_template.md` carries the formats and examples.-------## Review and Completion--### AI review cycles--The reviewer, its trigger phrase and its cadence all change; this subsection is the fluid one, so-rewrite it when they do. What survives a change of tool: a review counts only for the exact commit-it ran on, its findings are judged against the code rather than accepted or dismissed wholesale, and-findings that keep arriving mean the subsystem needs a sweep, not another patch.--- **Inline review threads are the source of truth.** A summary comment, a check name or a- notification list omits findings — read the threads on the pull request itself.-- Audit every finding against the current code. Fix the valid ones; reject the obsolete or wrong- ones in a reply that says why.-- After each round of fixes, run the focused tests and `npx tsc --noEmit` for every workspace you- changed, push, read the pull request's remote head (`gh pr view <n> --json headRefOid`), and- request the next review naming that exact SHA. **A clean review of an earlier head says nothing- about what you just pushed.** Do not wait for CI before asking — review and CI run on their own- clocks.-- Reply on each thread you resolved with the commit that resolved it and the coverage that proves- it.-- **After two actionable rounds** — or sooner, when each fix uncovers an adjacent defect — stop- answering threads one at a time and read the subsystem by invariant: identity, ownership,- authorization, persistence, retry, replay, abort, cleanup, expiry, rollout. Follow producers,- consumers, adapters, alternate write paths, and the final consumer of every limit; check- mixed-version behavior in both directions; read the whole base-to-head diff with the callers and- tests around it; then add transition or failure-injection coverage at the deepest boundary that- owns the behavior.-- The cycle ends when the exact pushed head draws no major findings, or only repeats ones already- resolved. A clean review is one completion signal, not the definition of done.--### Definition of done--- **Ship the observable experience, not the reported path.** Where they apply, cover loading, empty,- success, failure, cancellation, retry and restored-session behavior.-- **A backend capability with no frontend entry point is unfinished**, and so is a control with no- validation, persistence, error handling or authorization behind it.-- Localize every visible string through `useLocalize()`, keep semantic HTML, keyboard behavior and- ARIA intact, and compose shared primitives and semantic theme roles before adding local styling- (see "Frontend Rules"). Custom styling that proves unavoidable still supports light/dark and- reduced motion.-- Preserve existing defaults, configuration compatibility, stored data, and mixed-version behavior,- and expose any new lever through `configSchema` rather than a constant (see "Workspace- Boundaries").-- Make the fix the smallest one consistent with the patterns already in the file, and test the- behavior that was missed rather than the line a reviewer pointed at.-- **Report what you actually ran**: the pushed head, the local checks from "Testing" and- "Typechecking", CI state, the review result at that head, and any finding you rejected with the- reasoning. Name the checks you could not run instead of implying coverage.-------## Code Style--### Naming and File Organization--- **Single-word file names** whenever possible (e.g., `permissions.ts`, `capabilities.ts`, `service.ts`).-- When multiple words are needed, prefer grouping related modules under a **single-word directory** rather than using multi-word file names (e.g., `admin/capabilities.ts` not `adminCapabilities.ts`).-- The directory already provides context — `app/service.ts` not `app/appConfigService.ts`.--### Structure and Clarity--- **Never-nesting**: early returns, flat code, minimal indentation. Break complex operations into well-named helpers.-- **Functional first**: pure functions, immutable data, `map`/`filter`/`reduce` over imperative loops. Only reach for OOP when it clearly improves domain modeling or state encapsulation.-- **No dynamic imports** unless absolutely necessary.--### DRY--- Extract repeated logic into utility functions.-- Reusable hooks / higher-order components for UI patterns.-- Parameterized helpers instead of near-duplicate functions.-- Constants for repeated values; configuration objects over duplicated init code.-- Shared validators, centralized error handling, single source of truth for business rules.-- Shared typing system with interfaces/types extending common base definitions.-- Abstraction layers for external API interactions.--### Iteration and Performance--- **Minimize looping** — especially over shared data structures like message arrays, which are iterated frequently throughout the codebase. Every additional pass adds up at scale.-- Consolidate sequential O(n) operations into a single pass whenever possible; never loop over the same collection twice if the work can be combined.-- Choose data structures that reduce the need to iterate (e.g., `Map`/`Set` for lookups instead of `Array.find`/`Array.includes`).-- Avoid unnecessary object creation; consider space-time tradeoffs.-- Prevent memory leaks: careful with closures, dispose resources/event listeners, no circular references.--### Backend Database Performance--- On request startup and first page load paths, watch for serial database reads.- Multiple round trips to MongoDB can add significant latency when the database- is far from the app server.-- Prefer passing already-loaded request/user/config data through helper- functions instead of re-reading the same user, role, tenant, or principal data.-- When two reads are independent, start them in parallel and gate the response- on the authorization or validation result before returning data.-- Keep authorization, permission, and tenant checks semantically identical when- parallelizing reads. Speculative reads must remain scoped to the authenticated- user or tenant and must not write to the response before validation succeeds.--### Type Safety--- **Never use `any`**. Explicit types for all parameters, return values, and variables.-- **Limit `unknown`** — avoid `unknown`, `Record<string, unknown>`, and `as unknown as T` assertions. A `Record<string, unknown>` almost always signals a missing explicit type definition.-- **Don't duplicate types** — before defining a new type, check whether it already exists in the project (especially `packages/data-provider`). Reuse and extend existing types rather than creating redundant definitions.-- Use union types, generics, and interfaces appropriately.-- All TypeScript and ESLint warnings/errors must be addressed — do not leave unresolved diagnostics.--### Comments and Documentation--- Write self-documenting code; no inline comments narrating what code does.-- JSDoc only for complex/non-obvious logic or intellisense on public APIs.-- Single-line JSDoc for brief docs, multi-line for complex cases.-- Avoid standalone `//` comments unless absolutely necessary.--### Import Order--Imports are organized into three sections:--1. **Package imports** — sorted shortest to longest line length (`react` always first).-2. **`import type` imports** — sorted longest to shortest (package types first, then local types; length resets between sub-groups).-3. **Local/project imports** — sorted longest to shortest.--Multi-line imports count total character length across all lines. Consolidate value imports from the same module. Always use standalone `import type { ... }` — never inline `type` inside value imports.--### JS/TS Loop Preferences--- **Limit looping as much as possible.** Prefer single-pass transformations and avoid re-iterating the same data.-- `for (let i = 0; ...)` for performance-critical or index-dependent operations.-- `for...of` for simple array iteration.-- `for...in` only for object property enumeration.-------## Frontend Rules (`client/src/**/*`)--### Localization--- All user-facing text must use `useLocalize()`.-- Only update English keys in `client/src/locales/en/translation.json` (other languages are automated externally).-- Semantic key prefixes: `com_ui_`, `com_assistants_`, etc.--### Components--- TypeScript for all React components with proper type imports.-- Semantic HTML with ARIA labels (`role`, `aria-label`) for accessibility.-- Group related components in feature directories (e.g., `SidePanel/Memories/`).-- Use index files for clean exports.--### Theming and styling--- **Compose before styling.** Search `@librechat/client` for an existing primitive, semantic- variant, or composition before adding feature-local classes or CSS.-- **Use semantic roles.** Colors and shared appearance values must come from the semantic- Tailwind/theme roles. Do not add raw palette utilities, hard-coded hex/RGB/HSL colors, or- light/dark-specific values in feature components.-- **Deepen the system when the need is reusable.** Add a focused variant to a shared primitive or- extend the canonical, versioned theme-token registry when multiple screens should share the- same design decision. Do not create shallow local wrappers that merely relocate class strings.-- **Themes are data, not arbitrary CSS.** Theme definitions may select semantic colors and shared- appearance roles. They must not contain selectors, arbitrary CSS, application behavior, or- alternate feature layouts. Preserve existing environment and stored-theme compatibility when- changing the theme engine.-- **Keep layout and behavior local.** Feature structure, responsive layout, state-driven- transitions, and specialized visualization may remain feature-owned. Expose a theme role only- when it represents a stable, reusable appearance decision; do not turn every measurement into a- global token.-- **Treat custom CSS as an exception.** Use it only when shared primitives and semantic utilities- cannot express the requirement. Keep it narrowly scoped, consume theme variables where- applicable, support light/dark and reduced motion, and add a brief code or PR explanation of why- the exception is necessary.-- **Preserve defaults and prove variability.** New theme-aware variants must reproduce the current- default appearance unless a redesign is explicitly requested. Test semantic-token use and, when- extending theme capabilities, include a deliberately different reference theme to prove that- components adapt without feature-specific overrides.--### Data Management--- Feature hooks: `client/src/data-provider/[Feature]/queries.ts` → `[Feature]/index.ts` → `client/src/data-provider/index.ts`.-- React Query (`@tanstack/react-query`) for all API interactions; proper query invalidation on mutations.-- QueryKeys and MutationKeys in `packages/data-provider/src/keys.ts`.--### Client State Ownership--The client is migrating from Recoil to Jotai. **New state is always Jotai**, including inside a file-that already imports Recoil. For existing state, the unit of conversion is one atom together with-every file that reads or writes it: the two libraries hold different atom objects, so an atom cannot-be half converted, and many files already import both — mixed imports are not a signal that either-choice is fine here. Convert the areas you touch rather than migrating wholesale, and split the work-by who owns the state:--- **Feature-owned state** — atoms a single feature both writes and reads. Convert these to- Jotai as you touch them, with all of their consumers, and keep them inside the feature.- `client/src/store/jotai-utils.ts` carries the equivalents for persisted atoms- (`createStorageAtom`, `createStorageAtomWithEffect`, `createTabIsolatedAtom`), so a Recoil atom- with a localStorage effect has a direct port.-- **App-global state** — preferences and shell state a feature merely consumes- (`maximizeChatSpace`, `showScrollButton`, `enterToSend`, artifact visibility). A feature- that could plausibly be extracted must not reach into `~/store` for these; accept them- through props or a small context the host supplies. When a consumer sits outside the feature you- are changing, leave the atom on Recoil and pass it in — do not convert the shell to make one- feature tidy.--Passing app-global state in — rather than reaching for it — is what lets a feature move to-its own workspace later without a rewrite, and it keeps the Jotai conversion scoped to the-state a feature actually owns instead of dragging the global migration forward early.--### Data-Provider Integration--- Endpoints: `packages/data-provider/src/api-endpoints.ts`-- Data service: `packages/data-provider/src/data-service.ts`-- Types: `packages/data-provider/src/types/queries.ts`-- Use `encodeURIComponent` for dynamic URL parameters.--### Performance--- Prioritize memory and speed efficiency at scale.-- Cursor pagination for large datasets.-- Proper dependency arrays to avoid unnecessary re-renders.-- Leverage React Query caching and background refetching.-------## Backend Rules (`api/**`, `packages/api/**`)--### Auth cache invalidation--When adding or changing code that mutates user documents, invalidate the auth user document cache-for the affected users. This covers single-user updates as well as bulk role and user mutations.-Without it, OpenID JWT request burst caching can serve a stale `req.user` until its TTL expires.-------## Development Commands--| Command | Purpose |-|---|---|-| `npm run smart-reinstall` | Install deps (if lockfile changed) + build via Turborepo |-| `npm run reinstall` | Clean install — wipe `node_modules` and reinstall from scratch |-| `npm run backend` | Start the backend server |-| `npm run backend:dev` | Start backend with file watching (development) |-| `npm run build` | Build all compiled code via Turborepo (parallel, cached) |-| `npm run frontend` | Build all compiled code sequentially (legacy fallback) |-| `npm run frontend:dev` | Start frontend dev server with HMR (port 3090, requires backend running) |-| `npm run build:data-provider` | Rebuild `packages/data-provider` after changes |--- Node.js: v24.16.0-- Database: MongoDB-- Backend runs on `http://localhost:3080/`; frontend dev server on `http://localhost:3090/`-------## Testing--- Framework: **Jest**, run per-workspace.-- Run tests from their workspace directory: `cd api && npx jest <pattern>`, `cd packages/api && npx jest <pattern>`, etc.-- Frontend tests: `__tests__` directories alongside components; use `test/layout-test-utils` for rendering.-- Cover loading, success, and error states for UI/data flows.--### Typechecking--- **A green build is not a typecheck.** `packages/api`, `packages/client` and `packages/data-schemas`- build with `tsdown` alone, which emits without checking types. Only `packages/data-provider` runs- `tsc` as part of its build.-- Run `npx tsc --noEmit` in the workspace you changed before calling it done. `client` also exposes- it as `npm run typecheck`.-- `packages/client/tsconfig.json` excludes `*.spec.ts(x)` and `*.test.ts(x)`, so test files there are- never typechecked — a type error in a spec surfaces only when the test runs.-- `npm run static-checks` runs the Static Checks CI job locally against your staged files;- `npm run static-checks -- --against origin/dev` reproduces what CI sees for a pull request, and- `npm run static-checks:full` adds the slow gates (TypeScript, config migration tests, unused i18n- keys, unused npm packages).--### Philosophy--- **Real logic over mocks.** Exercise actual code paths with real dependencies. Mocking is a last resort.-- **Spies over mocks.** Assert that real functions are called with expected arguments and frequency without replacing underlying logic.-- **MongoDB**: use `mongodb-memory-server` for a real in-memory MongoDB instance. Test actual queries and schema validation, not mocked DB calls.-- **MCP**: use real `@modelcontextprotocol/sdk` exports for servers, transports, and tool definitions. Mirror real scenarios, don't stub SDK internals.-- Only mock what you cannot control: external HTTP APIs, rate-limited services, non-deterministic system calls.-- Heavy mocking is a code smell, not a testing strategy.-------## Formatting--Fix all formatting lint errors (trailing spaces, tabs, newlines, indentation) using auto-fix when available. All TypeScript/ESLint warnings and errors **must** be resolved.--`npm run sort-imports` with no arguments rewrites every file under `api/`, `client/src` and the four-`packages/*/src` roots — far beyond what you touched. Always pass explicit paths:-`npm run sort-imports -- path/to/file.ts`.diff --git a/packages/client/src/components/SegmentedMeter.spec.tsx b/packages/client/src/components/SegmentedMeter.spec.tsxindex 3b587c3a46..71a3fc7aa1 100644--- a/packages/client/src/components/SegmentedMeter.spec.tsx+++ b/packages/client/src/components/SegmentedMeter.spec.tsx@@ -161,7 +161,7 @@ describe('MeterSwatch', () => {});});-/** CLAUDE.md requires a deliberately different reference theme, to prove the+/** AGENTS.md requires a deliberately different reference theme, to prove the* component follows theme data rather than the bundled LibreChat values. */const referenceTheme: ThemeDefinition = {version: THEME_VERSION,diff --git a/scripts/sort-imports.mts b/scripts/sort-imports.mtsindex 2d89608f76..a4cb1308f4 100644--- a/scripts/sort-imports.mts+++ b/scripts/sort-imports.mts@@ -1,7 +1,7 @@#!/usr/bin/env node/*** Sorts imports across the LibreChat monorepo per project convention- * (CLAUDE.md § Import Order):+ * (AGENTS.md § Code style and performance):** 1. Package value imports — shortest line to longest (`react` always first)* 2. import type from packages — longest line to shortest@@ -81,7 +81,7 @@ function extractSpec(raw: string): string | null {return raw.match(/from\s+['"]([^'"]+)['"]/)?.[1] ?? null;}-/** Applies the CLAUDE.md grouping/length ordering to a run of pure imports. */+/** Applies the AGENTS.md grouping/length ordering to a run of pure imports. */function sortSegment(stmts: Stmt[]): string[] {const g1 = stmts.filter((s) => !s.isType && !s.isLocal)