🚢 docs: Correct the Deployment and Development Guides

content/docs/development/architecture.mdx

@@ -16,6 +16,7 @@ LibreChat is organized as a monorepo with clearly defined workspace boundaries:
 | `/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 |
+| `/packages/chat` | TypeScript | Frontend | `packages/data-provider`, `packages/client` | `@librechat/chat`: chat state, transport, and message components moving out of `/client`; never imports the app |
 
 ### Key Principles
 
@@ -37,8 +38,8 @@ LibreChat is organized as a monorepo with clearly defined workspace boundaries:
 | `npm run backend:dev` | Start backend with file watching (development) |
 | `npm run frontend:dev` | Start frontend dev server with HMR (port 3090, requires backend running) |
 
-- Node.js: `v24.16.0`
-- npm: `v11.16.0`
+- Node.js: `v24.22.1`
+- npm: `v11.13.0`
 - Database: MongoDB
 - Backend runs on `http://localhost:3080/`; frontend dev server on `http://localhost:3090/`
 

content/docs/development/conventions.mdx

@@ -16,6 +16,7 @@ LibreChat is a monorepo. All new code should target the correct workspace:
 | `/packages/data-provider` | TypeScript | Shared | API types, endpoints, data-service — used by frontend and backend |
 | `/client` | TypeScript/React | Frontend | Frontend SPA |
 | `/packages/client` | TypeScript | Frontend | Shared frontend utilities |
+| `/packages/chat` | TypeScript | Frontend | `@librechat/chat`: chat state, transport, and message components moving out of `/client`; never imports the app |
 
 - **All new backend code must be TypeScript** in `/packages/api`.
 - Keep `/api` changes to the absolute minimum (thin JS wrappers calling into `/packages/api`).
@@ -31,7 +32,7 @@ LibreChat is a monorepo. All new code should target the correct workspace:
 - Use "clean code" principles: keep functions and modules small, adhere to the single responsibility principle, and write expressive and readable code.
 - Use meaningful and descriptive variable and function names.
 - Prioritize code readability and maintainability over brevity.
-- Use the provided `.eslintrc` and `.prettierrc` files for consistent code formatting.
+- Use the repository's `eslint.config.mjs` (ESLint flat config) and `.prettierrc` files for consistent code formatting.
 - Fix all formatting lint errors using auto-fix when available. All TypeScript/ESLint warnings and errors must be resolved.
 
 ### Naming and File Organization
@@ -104,7 +105,7 @@ Imports are organized into three sections (in order):
 - Use try-catch blocks to catch and handle exceptions gracefully.
 - Implement proper error handling and consistently return appropriate error responses.
 - Use the logging system included in the `utils` directory to log important events and errors.
-- Do JWT-based, stateless authentication using the `requireJWTAuth` middleware.
+- Do JWT-based, stateless authentication using the `requireJwtAuth` middleware.
 
 ### File Structure
 

content/docs/development/debugging.mdx

@@ -6,4 +6,9 @@ description: (WIP) Contributions are welcome
 
 <Callout type="warning" title="Under construction, contributions are welcome!" />
 
-see also: [Logging System](/docs/configuration/logging)
+## Useful Settings
+
+- Set `DEBUG_CONSOLE=true` in `.env` for verbose server output in the console.
+- Run `npm run backend:inspect` to start the backend with the Node.js inspector (`--inspect`) and `--expose-gc`, so you can attach a debugger.
+
+See also: [Logging System](/docs/configuration/logging)

content/docs/development/get_started.mdx

@@ -7,8 +7,8 @@ description: Learn how to contribute using GitHub Desktop, VS Code extensions, a
 ## Requirements
 
 - [Git](https://git-scm.com/downloads) (Essential)
-- [Node.js](https://nodejs.org/en/download) `v24.16.0` (Essential)
-- npm `v11.16.0` (Essential)
+- [Node.js](https://nodejs.org/en/download) `v24.22.1` (Essential)
+- npm `v11.13.0` (Essential)
 - [MongoDB](https://www.mongodb.com/try/download/community) (Essential, for the database)
 - [Git LFS](https://git-lfs.com/) (Useful for larger files)
 - [GitHub Desktop](https://desktop.github.com/) (Optional)
@@ -29,11 +29,13 @@ Install these extensions in VS Code:
 If you use `nvm`, install and select the recommended Node.js version before installing LibreChat:
 
 ```sh filename="Use Node.js 24"
-nvm install 24.16.0
-nvm use 24.16.0
-npm install -g npm@11.16.0
+nvm install 24.22.1
+nvm use 24.22.1
+npm install -g npm@11.13.0
 ```
 
+The `.nvmrc` file in the LibreChat repository is the source of truth for the Node.js version; running `nvm use` from the repository root selects it.
+
 Verify your shell is using the expected versions:
 
 ```sh filename="Check Node.js and npm"
@@ -42,23 +44,31 @@ npm -v
 ```
 
 ```txt filename="Expected versions"
-v24.16.0
-11.16.0
+v24.22.1
+11.13.0
 ```
 
 ### GitHub
 
 - Fork the LibreChat repository: [https://github.com/LibreChat-AI/LibreChat/fork](https://github.com/LibreChat-AI/LibreChat/fork)
 
-- Create a branch on your fork, name it properly, and link it to the original repository.
+- Clone your fork and add the original repository as `upstream`. Contributions branch from and target `dev`; `main` only moves at release time.
+
+```sh filename="Clone your fork and sync dev"
+git clone https://github.com/username/LibreChat.git
+cd LibreChat
+git remote add upstream https://github.com/LibreChat-AI/LibreChat.git
+git fetch upstream dev
+git checkout -B dev upstream/dev
+```
 
-- Download your new branch to your local PC
+- Create a descriptive, slash-based branch off `dev`:
 
-```sh filename="Download your LibreChat branch"
-git clone -b branch-name https://github.com/username/LibreChat.git
+```sh filename="Create your working branch"
+git checkout -b new/feature/x
 ```
 
-> Replace `branch-name` and `username` with your details
+> Replace `username` and the branch name with your details. Do not use `npm run update` to refresh a development branch; it is the self-host updater and checks out `main`.
 
 ### Open in VS Code
 
@@ -89,6 +99,9 @@ git clone -b branch-name https://github.com/username/LibreChat.git
 - .env Configuration
   - Create the `.env` file. If you don't have one, duplicate `.env.example` and configure it.
 
+- Git hooks
+  - `npm install` sets up husky pre-commit checks, which run the Static Checks CI job locally on the files in each commit (ESLint, Prettier, import order, circular dependencies). Set `HUSKY=0` to opt out, and run the checks by hand with `npm run static-checks`.
+
 <Callout type="warning" title="Warning">
   The default values in `.env.example` are usually fine, except for `MONGO_URI`. Provide your own.
   Make sure to install MongoDB and configure `MONGO_URI` correctly to connect to your MongoDB
@@ -125,13 +138,13 @@ By running tests, ensure your contributions are robust and ready for integration
 
 ### Make a Commit
 
-**Commits** mark logical checkpoints in development. Include clear messages explaining changes.
+**Commits** mark logical checkpoints in development. Use conventional commit messages that begin with a type such as `feat`, `fix`, `docs`, or `refactor`, followed by a brief summary.
 
 **Example:**
 
 ```bash filename=" "
 git add .
-git commit -m "Add login functionality"
+git commit -m "feat: Add login functionality"
 ```
 
 ### Push Changes
@@ -146,25 +159,24 @@ git push origin feature-branch-name
 
 ### Create a Pull Request (PR)
 
-**Pull Request** merges changes from a feature branch into the main branch.
+**Pull Request** merges changes from a feature branch into the `dev` branch.
 
-1. Pull latest changes from main branch and resolve conflicts.
+1. Pull the latest changes from `dev` and resolve conflicts.
 2. Push updated feature branch.
 3. Ensure code follows project guidelines.
 
 **Example:**
 
 ```bash filename=" "
-git checkout main
-git pull origin main
+git fetch upstream dev
 git checkout feature-branch-name
-git rebase main
+git rebase upstream/dev
 # Resolve conflicts if any
 git push origin feature-branch-name
 # Open PR on GitHub
 ```
 
-Access your repository in a browser and click "Contribute".
+Access your fork in a browser and click "Contribute", and make sure the pull request targets `dev`.
 
 <Callout type="info" title="Note:">
   Provide a detailed PR description explaining changes and their value. Reference related issues.

content/docs/development/index.mdx

@@ -14,12 +14,12 @@ Use this toolchain for npm-based development:
 
 | Tool    | Version                   |
 | ------- | ------------------------- |
-| Node.js | `v24.16.0`                |
-| npm     | `v11.16.0`                |
+| Node.js | `v24.22.1`                |
+| npm     | `v11.13.0`                |
 | MongoDB | Atlas or Community Server |
 
 Node 24 satisfies LibreChat's runtime needs for CommonJS interop with ESM-only packages, WebCrypto,
-and the Fetch API. If your shell still reports an older Node version, run `nvm use 24.16.0` from the
+and the Fetch API. If your shell still reports an older Node version, run `nvm use 24.22.1` from the
 LibreChat repository before installing dependencies.
 
 ## Work In The Right Workspace
@@ -34,6 +34,7 @@ LibreChat is a monorepo. Pick the smallest workspace that owns the behavior you
 | `/packages/data-provider` | Shared API types, endpoints, query keys, and data-service functions   |
 | `/client`                 | React application code                                                |
 | `/packages/client`        | Shared frontend utilities                                             |
+| `/packages/chat`          | `@librechat/chat`: chat state, transport, and message components      |
 
 ## Daily Commands
 
@@ -50,7 +51,7 @@ LibreChat is a monorepo. Pick the smallest workspace that owns the behavior you
 
 <Callout type="info" title="Development Resources">
   - If you are new to repositories, forks, branches, and pull requests, start with **[GitHub's collaborative development guide](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/getting-started/about-collaborative-development-models)**.
-  - Read the **[Contributor Guidelines](https://github.com/LibreChat-AI/LibreChat/blob/main/.github/CONTRIBUTING.md)** before opening a PR.
+  - Read the **[Contributor Guidelines](https://github.com/LibreChat-AI/LibreChat/blob/main/.github/CONTRIBUTING.md)** before opening a PR. Branch from `dev` and target `dev` with your pull request; `main` only moves at release time.
   - Use **[Contributor Setup](/docs/development/get_started)** for the full local setup flow.
   - Use **[Code Standards and Conventions](/docs/development/conventions)** for workspace boundaries, import order, typing, testing, and frontend rules.
 </Callout>

content/docs/development/testing.mdx

@@ -8,18 +8,23 @@ description: How to locally test the app during development.
 
 Before submitting your updates, verify they pass all unit tests. Follow these steps to run tests locally:
 
-- Copy your `.env.example` file in the `/api` folder and rename it to `.env`
+- Copy the example test environment file used by the API tests:
 
-  ```bash filename="create a /api/.env file"
-  cp .env.example ./api/.env
+  ```bash filename="create api/test/.env.test"
+  cp api/test/.env.test.example api/test/.env.test
   ```
 
-- Add `NODE_ENV=CI` to your `/api/.env` file
 - `npm run test:client`
 - `npm run test:api`
 - `npm run test:packages:api`
 - `npm run test:packages:data-provider`
 - `npm run test:packages:data-schemas`
+- `npm run test:packages:chat`
+- `npm run test:all` runs all of the suites above in sequence.
+
+### Static Checks
+
+Commits also run the Static Checks CI job locally through the husky pre-commit hook (set `HUSKY=0` to opt out). Run it by hand with `npm run static-checks`, or against a base branch with `npm run static-checks -- --against origin/dev`. `npm run static-checks:full` adds the slower gates (TypeScript, config migration tests, unused i18n keys, unused npm packages).
 
 ### Running Tests Per-Workspace
 
@@ -30,6 +35,7 @@ cd api && npx jest <pattern>
 cd packages/api && npx jest <pattern>
 cd packages/data-provider && npx jest <pattern>
 cd packages/data-schemas && npx jest <pattern>
+cd packages/chat && npx jest <pattern>
 cd client && npx jest <pattern>
 ```
 

content/docs/development/tools_and_plugins.mdx

@@ -10,6 +10,10 @@ description: This doc shows you how to create custom plugins for LibreChat by ex
 
 # Making your own Tools/Plugins
 
+<Callout type="warning" title="This walkthrough predates the current code">
+  The steps below were written for an older version of the codebase. Tools now live in `api/app/clients/tools/structured/` and are registered in `api/app/clients/tools/util/handleTools.js`, so file names and function shapes in the examples may differ from the current tree. For new integrations, use [MCP servers](/docs/features/agents#model-context-protocol-mcp) or [Agents tools and actions](/docs/features/agents) instead.
+</Callout>
+
 <Callout type="warning" title="Warning">
   Please refer to the most recents tools used with assistants in `api/app/clients/tools/structured/`
   since plugins will be deprecated in favor of tools in the near future
@@ -49,15 +53,15 @@ Here are the key takeaways for creating your own plugin:
 
 Remember, the key to creating a custom plugin is to extend the `Tool` class and implement the `_call` method. The `_call` method is where you define what your plugin does. You can also define helper methods and properties in your class to support the functionality of your plugin.
 
-**Note: You can find all the files mentioned in this guide in the `.\api\app\langchain\tools` folder.**
+**Note: You can find all the files mentioned in this guide in the `api/app/clients/tools` folder.**
 
 ---
 
 ## StructuredTools
 
 **Multi-Input Plugins**
 
-If you would like to make a plugin that would benefit from multiple inputs from the LLM, instead of a singular input string as we will review, you need to make a LangChain **[StructuredTool](https://blog.langchain.dev/structured-tools/)** instead. A detailed guide for this is in progress, but for now, you can look at how I've made StructuredTools in this directory: `api\app\clients\tools\structured\`. This guide is foundational to understanding StructuredTools, and it's recommended you continue reading to better understand LangChain tools first. The blog linked above is also helpful once you've read through this guide.
+If you would like to make a plugin that would benefit from multiple inputs from the LLM, instead of a singular input string as we will review, you need to make a LangChain **[StructuredTool](https://blog.langchain.dev/structured-tools/)** instead. A detailed guide for this is in progress, but for now, you can look at how I've made StructuredTools in this directory: `api/app/clients/tools/structured/`. This guide is foundational to understanding StructuredTools, and it's recommended you continue reading to better understand LangChain tools first. The blog linked above is also helpful once you've read through this guide.
 
 ---
 
@@ -160,16 +164,16 @@ class StableDiffusionAPI extends Tool {
 
 ## Step 5: Export Your Plugin and import into handleTools.js
 
-**This process will be somewhat automated in the future, as long as you have your plugin/tool in `api\app\langchain\tools`**
+**This process will be somewhat automated in the future, as long as you have your plugin/tool in `api/app/clients/tools`**
 
 ```javascript
 // Export
 module.exports = StableDiffusionAPI
 ```
 
 ```js
-/* api\app\langchain\tools\handleTools.js */
-const StableDiffusionAPI = require('./StableDiffusion');
+/* api/app/clients/tools/util/handleTools.js */
+const StableDiffusionAPI = require('../StableDiffusion');
 ...
 ```
 
@@ -233,7 +237,7 @@ module.exports = {
 
 ## Step 7: Add your Plugin to manifest.json
 
-**This process will be somehwat automated in the future along with step 5, as long as you have your plugin/tool in `api\app\langchain\tools`, and your plugin can be initialized with the default method**
+**This process will be somehwat automated in the future along with step 5, as long as you have your plugin/tool in `api/app/clients/tools`, and your plugin can be initialized with the default method**
 
 ```json
   {