docs: add AGENTS.MD for AI and developer guidance (#7348)

* docs: add AGENTS.MD for AI and developer guidance

* docs: update project name from Etherpad Lite to Etherpad

* docs: fix incorrect test directory path in AGENTS.MD

* docs: correct test stack description in AGENTS.MD (Mocha is primary)

* docs: fix incorrect easysync documentation path in AGENTS.MD

* chore: add .pr_agent.toml to enable automatic PR review/description on push

* docs: remove nodejs version from README and AGENTS.MD (prefer package.json)

* docs: standardize all indentation to 2 spaces

* chore: update src/package.json node engine to match root (>=20.0.0)

.pr_agent.toml

@@ -0,0 +1,5 @@
+[pr_reviewer]
+run_on_pr_sync = true
+
+[pr_description]
+run_on_pr_sync = true

AGENTS.MD

@@ -0,0 +1,61 @@
+# Agent Guide - Etherpad
+
+Welcome to the Etherpad project. This guide provides essential context and instructions for AI agents and developers to effectively contribute to the codebase.
+
+## Project Overview
+Etherpad is a real-time collaborative editor designed to be lightweight, scalable, and highly extensible via plugins.
+
+## Technical Stack
+- **Runtime:** Node.js
+- **Package Manager:** pnpm
+- **Languages:** TypeScript (primary), JavaScript, CSS, HTML
+- **Backend:** Express.js, Socket.io
+- **Frontend:** Legacy core (`src/static`), New UI (`ui/`), Admin UI (`admin/`)
+- **Build Tools:** Vite (for `ui` and `admin`), custom scripts in `bin/`
+- **Testing:** Mocha (Backend), Vitest, Playwright, custom backend test suite
+
+## Directory Structure
+- `src/node/`: Backend logic, API, and database abstraction.
+- `src/static/`: Core frontend logic (Legacy).
+- `ui/`: Modern React-based user interface.
+- `admin/`: Modern React-based administration interface.
+- `bin/`: Utility and lifecycle scripts.
+- `doc/`: Documentation in Markdown and Adoc formats.
+- `src/tests/`: Test suites (backend, frontend, UI, admin).
+- `var/`: Runtime data (logs, dirtyDB, etc. - ignored by git).
+- `local_plugins/`: Directory for developing and testing plugins locally.
+
+## Core Mandates & Conventions
+
+### Coding Style
+- **Indentation:** 2 spaces for all files (JS/TS/CSS/HTML).
+- **No Tabs:** Use spaces only.
+- **Comments:** Provide clear comments for complex logic.
+- **Backward Compatibility:** Always ensure compatibility with older versions of the database and configuration files.
+
+### Development Workflow
+- **Branching:** Work in feature branches. Issue PRs against the `develop` branch.
+- **Commits:** Maintain a linear history (no merge commits). Use meaningful messages in the format: `submodule: description`.
+- **Feature Flags:** New features should be placed behind feature flags and disabled by default.
+- **Deprecation:** Never remove features abruptly; deprecate them first with a `WARN` log.
+
+### Testing & Validation
+- **Requirement:** Every bug fix MUST include a regression test in the same commit.
+- **Backend Tests:** Run `pnpm --filter ep_etherpad-lite run test` from the root.
+- **Frontend Tests:** Accessible at `/tests/frontend` on a running instance.
+- **Linting:** Run `pnpm run lint` to ensure style compliance.
+- **Build:** Run `pnpm run build:etherpad` before production deployment.
+
+## Key Concepts
+
+### Easysync
+The real-time synchronization engine. It is complex; refer to `doc/public/easysync/` before modifying core synchronization logic.
+
+### Plugin Framework
+Most functionality should be implemented as plugins (`ep_...`). Avoid modifying the core unless absolutely necessary.
+
+### Settings
+Configured via `settings.json`. A template is available at `settings.json.template`. Environment variables can override any setting using `"${ENV_VAR}"` or `"${ENV_VAR:default_value}"`.
+
+## AI-Specific Guidance
+AI/Agent contributions are explicitly welcomed by the maintainers, provided they strictly adhere to the guidelines in `CONTRIBUTING.md` and this guide. Always prioritize stability, readability, and compatibility.

CONTRIBUTING.md

@@ -83,7 +83,7 @@ Also, keep it maintainable. We don't wanna end up as the monster Etherpad was!
 ## Coding style
 * Do write comments. (You don't have to comment every line, but if you come up with something that's a bit complex/weird, just leave a comment. Bear in mind that you will probably leave the project at some point and that other people will read your code. Undocumented huge amounts of code are worthless!)
 * Never ever use tabs
-* Indentation: JS/CSS: 2 spaces; HTML: 4 spaces
+* Indentation: 2 spaces
 * Don't overengineer. Don't try to solve any possible problem in one step, but try to solve problems as easy as possible and improve the solution over time!
 * Do generalize sooner or later! (if an old solution, quickly hacked together, poses more problems than it solves today, refactor it!)
 * Keep it compatible. Do not introduce changes to the public API, db schema or configurations too lightly. Don't make incompatible changes without good reasons!

README.md

@@ -100,7 +100,7 @@ volumes:
 
 ### Requirements
 
-[Node.js](https://nodejs.org/) >= **18.18.2**.
+[Node.js](https://nodejs.org/).
 
 ### Windows, macOS, Linux
 

best_practices.md

@@ -85,7 +85,7 @@ Also, keep it maintainable. We don't wanna end up as the monster Etherpad was!
 ## Coding style
 * Do write comments. (You don't have to comment every line, but if you come up with something that's a bit complex/weird, just leave a comment. Bear in mind that you will probably leave the project at some point and that other people will read your code. Undocumented huge amounts of code are worthless!)
 * Never ever use tabs
-* Indentation: JS/CSS: 2 spaces; HTML: 4 spaces
+* Indentation: 2 spaces
 * Don't overengineer. Don't try to solve any possible problem in one step, but try to solve problems as easy as possible and improve the solution over time!
 * Do generalize sooner or later! (if an old solution, quickly hacked together, poses more problems than it solves today, refactor it!)
 * Keep it compatible. Do not introduce changes to the public API, db schema or configurations too lightly. Don't make incompatible changes without good reasons!

src/package.json

@@ -123,7 +123,7 @@
     "vitest": "^4.0.18"
   },
   "engines": {
-    "node": ">=18.18.2",
+    "node": ">=20.0.0",
     "npm": ">=6.14.0",
     "pnpm": ">=8.3.0"
   },