docs: add AGENTS.MD for AI and developer guidance

[JohnMcLear]

This PR adds an AGENTS.MD file to provide context and instructions for AI agents and developers, following the project's standards and updated naming convention.

[qodo-free-for-open-source-projects]

Review Summary by Qodo

Add AGENTS.MD guide for AI agents and developers

📝 Documentation

Walkthroughs

Description

• Adds AGENTS.MD guide for AI agents and developers
• Documents project overview and technical stack details
• Provides directory structure and core development conventions
• Includes testing requirements and key architectural concepts

Diagram

flowchart LR
  A["Project Documentation"] -->|"adds new guide"| B["AGENTS.MD"]
  B -->|"contains"| C["Project Overview"]
  B -->|"contains"| D["Technical Stack"]
  B -->|"contains"| E["Development Conventions"]
  B -->|"contains"| F["Testing & Validation"]
  B -->|"contains"| G["AI-Specific Guidance"]

Loading

File Changes

1. AGENTS.MD 📝 Documentation +61/-0

New comprehensive guide for AI agents and developers

• New comprehensive guide for AI agents and developers contributing to Etherpad
• Documents technical stack including Node.js, pnpm, TypeScript, Express.js, and Socket.io
• Outlines directory structure with backend, frontend, admin, and test directories
• Specifies coding conventions, development workflow, branching strategy, and commit message format
• Details testing requirements including regression tests for bug fixes and linting standards
• Explains key concepts like Easysync synchronization engine and plugin framework architecture
• Provides AI-specific guidance emphasizing adherence to CONTRIBUTING.md and project stability

AGENTS.MD

---

[qodo-free-for-open-source-projects]

Code Review by Qodo

🐞 Bugs (37) 📘 Rule violations (4) 📎 Requirement gaps (0)

1. Node engine raised to 20 📘 Rule violation ⛯ Reliability

Description

The PR increases the minimum supported Node.js version to >=20.0.0, which is a
backward-incompatible runtime requirement change. This breaking change is not documented in the
user-facing requirements documentation and can break existing deployments pinned to Node 18.

Code

src/package.json[126]

+    "node": ">=20.0.0",

Evidence

PR Compliance ID 3 requires backward-incompatible changes to configuration/runtime requirements to
be justified and clearly documented. The diff shows the Node.js engine requirement being raised to
>=20.0.0 while the README simultaneously removes the previously documented minimum version,
leaving the breaking change undocumented.

src/package.json[126-126]
README.md[103-103]
Best Practice: Repository guidelines

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The PR raises the Node.js engine requirement to `>=20.0.0`, which is a backward-incompatible runtime/configuration change, but the PR does not document this breaking requirement change (and removes the previously documented minimum Node version from the README).
## Issue Context
This can break existing deployments and developer environments that still use Node 18.x. Compliance requires that unavoidable breaking changes be clearly documented along with impact.
## Fix Focus Areas
- src/package.json[126-126]
- README.md[103-103]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. README hides Node>=20 req ☑ 🐞 Bug ✓ Correctness

Description

README’s Requirements section no longer states a minimum Node.js version, but the repo enforces Node
>=20 (engineStrict + runtime check). Users following the README may install an unsupported Node
version and hit install/runtime failures.

Code

README.md[103]

+[Node.js](https://nodejs.org/).

Evidence

The README no longer specifies a Node version, but the project explicitly requires Node >=20 in the
root and src package manifests and enforces the requirement at runtime on startup.

README.md[101-105]
package.json[44-52]
src/package.json[125-129]
src/node/server.ts[67-74]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
README no longer specifies a minimum Node.js version, but the repo enforces Node >= 20.0.0 at install time (`engineStrict`) and at runtime (startup exits if Node is too old). This mismatch will cause avoidable setup failures for new users.
## Issue Context
- Root `package.json` sets `engines.node` to `>=20.0.0` and `engineStrict: true`.
- `src/node/server.ts` enforces the minimum based on `src/package.json`.
## Fix Focus Areas
- README.md[101-105]
- package.json[44-52]
- src/package.json[125-129]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

3. Docs set HTML 2-space 📘 Rule violation ✓ Correctness

Description

The PR updates contributor/agent guidance to state that HTML should be indented with 2 spaces, which
conflicts with the required style rule (HTML must be 4 spaces). This creates non-compliant guidance
that will likely lead to future whitespace-style violations.

Code

AGENTS.MD[R30-33]

+### Coding Style
+- **Indentation:** 2 spaces for all files (JS/TS/CSS/HTML).
+- **No Tabs:** Use spaces only.
+- **Comments:** Provide clear comments for complex logic.

Evidence

PR Compliance ID 9 requires HTML indentation to be 4 spaces, but the new/updated documentation
explicitly instructs 2-space indentation for HTML.

AGENTS.MD[30-32]
CONTRIBUTING.md[86-86]
best_practices.md[86-86]
Best Practice: Repository guidelines

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The PR updates documentation to instruct `Indentation: 2 spaces` for everything, including HTML, which conflicts with the required whitespace rule (HTML must be 4 spaces).
## Issue Context
This is a direct mismatch between documented style guidance and the compliance requirement, and will likely cause future diffs and formatting violations.
## Fix Focus Areas
- AGENTS.MD[30-33]
- CONTRIBUTING.md[86-86]
- best_practices.md[86-86]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

View more (2)

4. Node engine raised to 20 📘 Rule violation ⛯ Reliability

Description

The PR increases the minimum supported Node.js version to >=20.0.0, which is a
backward-incompatible runtime requirement change. This breaking change is not documented in the
user-facing requirements documentation and can break existing deployments pinned to Node 18.

Code

src/package.json[126]

+    "node": ">=20.0.0",

Evidence

PR Compliance ID 3 requires backward-incompatible changes to configuration/runtime requirements to
be justified and clearly documented. The diff shows the Node.js engine requirement being raised to
>=20.0.0 while the README simultaneously removes the previously documented minimum version,
leaving the breaking change undocumented.

src/package.json[126-126]
README.md[103-103]
Best Practice: Repository guidelines

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The PR raises the Node.js engine requirement to `>=20.0.0`, which is a backward-incompatible runtime/configuration change, but the PR does not document this breaking requirement change (and removes the previously documented minimum Node version from the README).
## Issue Context
This can break existing deployments and developer environments that still use Node 18.x. Compliance requires that unavoidable breaking changes be clearly documented along with impact.
## Fix Focus Areas
- src/package.json[126-126]
- README.md[103-103]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

5. README hides Node>=20 req 🐞 Bug ✓ Correctness

Description

README’s Requirements section no longer states a minimum Node.js version, but the repo enforces Node
>=20 (engineStrict + runtime check). Users following the README may install an unsupported Node
version and hit install/runtime failures.

Code

README.md[103]

+[Node.js](https://nodejs.org/).

Evidence

The README no longer specifies a Node version, but the project explicitly requires Node >=20 in the
root and src package manifests and enforces the requirement at runtime on startup.

README.md[101-105]
package.json[44-52]
src/package.json[125-129]
src/node/server.ts[67-74]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
README no longer specifies a minimum Node.js version, but the repo enforces Node >= 20.0.0 at install time (`engineStrict`) and at runtime (startup exits if Node is too old). This mismatch will cause avoidable setup failures for new users.
## Issue Context
- Root `package.json` sets `engines.node` to `>=20.0.0` and `engineStrict: true`.
- `src/node/server.ts` enforces the minimum based on `src/package.json`.
## Fix Focus Areas
- README.md[101-105]
- package.json[44-52]
- src/package.json[125-129]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

6. Node version mismatch ☑ 🐞 Bug ⛯ Reliability

Description

AGENTS.MD declares Node.js >=20.0.0, but README.md and src/package.json state >=18.18.2, while the
root package.json enforces >=20.0.0; this inconsistency will confuse contributors and can lead to
setup failures depending on which source they follow.

Code

AGENTS.MD[9]

+- **Runtime:** Node.js (>= 20.0.0)

Evidence

The new guidance sets a Node minimum that conflicts with existing documentation and the core
package’s engine constraints. With multiple “source of truth” values, contributors may install the
wrong Node version (or incorrectly assume older Node is supported) and hit engine/install/runtime
issues.

AGENTS.MD[8-10]
README.md[101-114]
src/package.json[125-129]
package.json[44-46]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
AGENTS.MD states Node.js >=20.0.0, but README.md and src/package.json indicate Node.js >=18.18.2 while the root package.json enforces >=20.0.0. This creates conflicting guidance and can cause contributor setup failures.
## Issue Context
The repo currently has multiple stated Node minimums. AGENTS.MD should not add another competing requirement; it should either align with the project-wide requirement or clearly explain why different parts of the repo have different engine constraints.
## Fix Focus Areas
- AGENTS.MD[8-11]
- README.md[101-114]
- package.json[44-46]
- src/package.json[125-129]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

7. Wrong easysync doc path ☑ 🐞 Bug ✓ Correctness

Description

AGENTS.MD tells contributors to consult doc/easysync/, but the easysync docs checked into this
repo are under doc/public/easysync/. This will send contributors to a dead-end location when
working on synchronization logic.

Code

AGENTS.MD[R51-53]

+### Easysync
+The real-time synchronization engine. It is complex; refer to `doc/easysync/` before modifying core synchronization logic.
+

Evidence

The guide points to doc/easysync/, but the repo’s easysync notes are present under
doc/public/easysync/, so the referenced location is inaccurate for local navigation.

AGENTS.MD[51-53]
doc/public/easysync/easysync-notes.txt[1-5]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`AGENTS.MD` references a non-existent/inaccurate easysync documentation path (`doc/easysync/`). The easysync materials in this repository live under `doc/public/easysync/`.
### Issue Context
This is onboarding-critical documentation; wrong paths cause contributors to waste time when touching Easysync.
### Fix Focus Areas
- AGENTS.MD[51-53]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

8. HTML indent rule conflicts ☑ 🐞 Bug ⛯ Reliability

Description

AGENTS.MD mandates 4-space HTML indentation, but .editorconfig sets indent_size=2 globally with no
HTML override; contributors using EditorConfig-aware tools will format HTML with 2 spaces, causing
noisy diffs and review churn.

Code

AGENTS.MD[31]

+- **Indentation:** 2 spaces for JS/TS/CSS; 4 spaces for HTML.

Evidence

The new guide repeats the 4-space HTML rule, but the repo’s EditorConfig configuration will drive
most IDEs/formatters to apply 2 spaces to HTML. This mismatch predictably results in inconsistent
formatting across contributions.

AGENTS.MD[30-33]
.editorconfig[1-9]
CONTRIBUTING.md[83-87]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
AGENTS.MD says HTML should be indented with 4 spaces, but .editorconfig enforces indent_size=2 for all files. EditorConfig-aware tools will format HTML with 2 spaces, leading to inconsistent formatting and PR churn.
## Issue Context
CONTRIBUTING.md also says HTML is 4 spaces, so the inconsistency likely predates this PR; however, adding AGENTS.MD amplifies the mismatch. Decide which rule is correct and make the documentation and tooling consistent.
## Fix Focus Areas
- AGENTS.MD[30-33]
- .editorconfig[1-20]
- CONTRIBUTING.md[83-90]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

View more (33)

9. Misleading tests directory ☑ 🐞 Bug ✓ Correctness

Description

AGENTS.MD lists a top-level tests/ directory, but the test suites live under src/tests/ (and
scripts reference tests/... relative to src/). This can confuse contributors when locating tests
and test docs from the repo root.

Code

AGENTS.MD[R23-26]

+- `doc/`: Documentation in Markdown and Adoc formats.
+- `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.

Evidence

From the repo root, the tests live under src/tests/ (documented by src/tests/README.md). The
backend test script in src/package.json runs mocha against tests/... paths that are relative
to the src/ package, not a repo-root tests/ directory.

AGENTS.MD[17-26]
src/tests/README.md[1-11]
src/package.json[134-138]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`AGENTS.MD` claims a repo-root `tests/` directory, but tests are located under `src/tests/` (repo-root path). Some scripts use `tests/...` paths relative to `src/`, which is easy to misinterpret.
### Issue Context
Contributors reading AGENTS.MD from the repo root will likely search for `./tests` and not find the test documentation.
### Fix Focus Areas
- AGENTS.MD[17-26]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

10. Plugin tooling Node floor stale ☑ 🐞 Bug ⛯ Reliability

Description

Core now declares Node >=20 in src/package.json, but the plugin checker still writes
engines.node: >=18.0.0 into plugin package.json files. This can mislead plugin authors into
thinking Node 18 is a supported baseline for current Etherpad development.

Code

src/package.json[126]

+    "node": ">=20.0.0",

Evidence

CI and the root package already target Node >=20, and the server enforces the Node minimum from
src/package.json. However, the plugin tooling continues to set a lower engines.node in plugins,
creating inconsistent guidance after this PR’s Node engine bump in src/package.json.

src/package.json[125-129]
package.json[44-46]
.github/workflows/backend-tests.yml[27-31]
bin/plugins/checkPlugin.ts[229-233]
src/node/server.ts[71-74]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
After bumping core’s Node requirement to >=20, the plugin checker still stamps plugins with `engines.node >=18.0.0`, which is inconsistent with the runtime users will actually run plugins under. This is likely to confuse plugin authors and create avoidable incompatibility reports.
## Issue Context
- Core requires Node >=20 (root and src package manifests; CI matrix).
- `bin/plugins/checkPlugin.ts` currently writes `>=18.0.0` into plugin `package.json`.
## Fix Focus Areas
- bin/plugins/checkPlugin.ts[229-233]
- package.json[44-46]
- src/package.json[125-129]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

11. Wrong easysync doc path ☑ 🐞 Bug ✓ Correctness

Description

AGENTS.MD tells contributors to consult doc/easysync/, but the easysync docs checked into this
repo are under doc/public/easysync/. This will send contributors to a dead-end location when
working on synchronization logic.

Code

AGENTS.MD[R51-53]

+### Easysync
+The real-time synchronization engine. It is complex; refer to `doc/easysync/` before modifying core synchronization logic.
+

Evidence

The guide points to doc/easysync/, but the repo’s easysync notes are present under
doc/public/easysync/, so the referenced location is inaccurate for local navigation.

AGENTS.MD[51-53]
doc/public/easysync/easysync-notes.txt[1-5]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`AGENTS.MD` references a non-existent/inaccurate easysync documentation path (`doc/easysync/`). The easysync materials in this repository live under `doc/public/easysync/`.
### Issue Context
This is onboarding-critical documentation; wrong paths cause contributors to waste time when touching Easysync.
### Fix Focus Areas
- AGENTS.MD[51-53]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

12. Backend runner misstated ☑ 🐞 Bug ✓ Correctness

Description

AGENTS.MD lists Vitest as a primary testing tool, but the default backend test command uses Mocha
(Vitest exists as a separate script). This can lead contributors to run the wrong tool when
validating backend changes.

Code

AGENTS.MD[R8-16]

+## Technical Stack
+- **Runtime:** Node.js (>= 20.0.0)
+- **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:** Vitest, Playwright, custom backend test suite
+

Evidence

The guide’s testing stack description emphasizes Vitest, but src/package.json shows the default
test script is Mocha and Vitest is only available via test:vitest.

AGENTS.MD[8-16]
src/package.json[134-149]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`AGENTS.MD` describes the test stack as primarily Vitest, but the default backend test runner is Mocha.
### Issue Context
Contributors may attempt to use Vitest for backend tests and fail to run the actual CI-equivalent suite.
### Fix Focus Areas
- AGENTS.MD[8-16]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

13. Node version mismatch ☑ 🐞 Bug ⛯ Reliability

Description

AGENTS.MD declares Node.js >=20.0.0, but README.md and src/package.json state >=18.18.2, while the
root package.json enforces >=20.0.0; this inconsistency will confuse contributors and can lead to
setup failures depending on which source they follow.

Code

AGENTS.MD[9]

+- **Runtime:** Node.js (>= 20.0.0)

Evidence

The new guidance sets a Node minimum that conflicts with existing documentation and the core
package’s engine constraints. With multiple “source of truth” values, contributors may install the
wrong Node version (or incorrectly assume older Node is supported) and hit engine/install/runtime
issues.

AGENTS.MD[8-10]
README.md[101-114]
src/package.json[125-129]
package.json[44-46]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
AGENTS.MD states Node.js >=20.0.0, but README.md and src/package.json indicate Node.js >=18.18.2 while the root package.json enforces >=20.0.0. This creates conflicting guidance and can cause contributor setup failures.
## Issue Context
The repo currently has multiple stated Node minimums. AGENTS.MD should not add another competing requirement; it should either align with the project-wide requirement or clearly explain why different parts of the repo have different engine constraints.
## Fix Focus Areas
- AGENTS.MD[8-11]
- README.md[101-114]
- package.json[44-46]
- src/package.json[125-129]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

14. Misleading tests directory ☑ 🐞 Bug ✓ Correctness

Description

AGENTS.MD lists a top-level tests/ directory, but the test suites live under src/tests/ (and
scripts reference tests/... relative to src/). This can confuse contributors when locating tests
and test docs from the repo root.

Code

AGENTS.MD[R23-26]

+- `doc/`: Documentation in Markdown and Adoc formats.
+- `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.

Evidence

From the repo root, the tests live under src/tests/ (documented by src/tests/README.md). The
backend test script in src/package.json runs mocha against tests/... paths that are relative
to the src/ package, not a repo-root tests/ directory.

AGENTS.MD[17-26]
src/tests/README.md[1-11]
src/package.json[134-138]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`AGENTS.MD` claims a repo-root `tests/` directory, but tests are located under `src/tests/` (repo-root path). Some scripts use `tests/...` paths relative to `src/`, which is easy to misinterpret.
### Issue Context
Contributors reading AGENTS.MD from the repo root will likely search for `./tests` and not find the test documentation.
### Fix Focus Areas
- AGENTS.MD[17-26]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

15. Wrong easysync doc path 🐞 Bug ✓ Correctness

Description

AGENTS.MD tells contributors to consult doc/easysync/, but the easysync docs checked into this
repo are under doc/public/easysync/. This will send contributors to a dead-end location when
working on synchronization logic.

Code

AGENTS.MD[R51-53]

+### Easysync
+The real-time synchronization engine. It is complex; refer to `doc/easysync/` before modifying core synchronization logic.
+

Evidence

The guide points to doc/easysync/, but the repo’s easysync notes are present under
doc/public/easysync/, so the referenced location is inaccurate for local navigation.

AGENTS.MD[51-53]
doc/public/easysync/easysync-notes.txt[1-5]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`AGENTS.MD` references a non-existent/inaccurate easysync documentation path (`doc/easysync/`). The easysync materials in this repository live under `doc/public/easysync/`.
### Issue Context
This is onboarding-critical documentation; wrong paths cause contributors to waste time when touching Easysync.
### Fix Focus Areas
- AGENTS.MD[51-53]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

16. Backend runner misstated 🐞 Bug ✓ Correctness

Description

AGENTS.MD lists Vitest as a primary testing tool, but the default backend test command uses Mocha
(Vitest exists as a separate script). This can lead contributors to run the wrong tool when
validating backend changes.

Code

AGENTS.MD[R8-16]

+## Technical Stack
+- **Runtime:** Node.js (>= 20.0.0)
+- **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:** Vitest, Playwright, custom backend test suite
+

Evidence

The guide’s testing stack description emphasizes Vitest, but src/package.json shows the default
test script is Mocha and Vitest is only available via test:vitest.

AGENTS.MD[8-16]
src/package.json[134-149]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`AGENTS.MD` describes the test stack as primarily Vitest, but the default backend test runner is Mocha.
### Issue Context
Contributors may attempt to use Vitest for backend tests and fail to run the actual CI-equivalent suite.
### Fix Focus Areas
- AGENTS.MD[8-16]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

17. HTML indent rule conflicts 🐞 Bug ⛯ Reliability

Description

AGENTS.MD mandates 4-space HTML indentation, but .editorconfig sets indent_size=2 globally with no
HTML override; contributors using EditorConfig-aware tools will format HTML with 2 spaces, causing
noisy diffs and review churn.

Code

AGENTS.MD[31]

+- **Indentation:** 2 spaces for JS/TS/CSS; 4 spaces for HTML.

Evidence

The new guide repeats the 4-space HTML rule, but the repo’s EditorConfig configuration will drive
most IDEs/formatters to apply 2 spaces to HTML. This mismatch predictably results in inconsistent
formatting across contributions.

AGENTS.MD[30-33]
.editorconfig[1-9]
CONTRIBUTING.md[83-87]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
AGENTS.MD says HTML should be indented with 4 spaces, but .editorconfig enforces indent_size=2 for all files. EditorConfig-aware tools will format HTML with 2 spaces, leading to inconsistent formatting and PR churn.
## Issue Context
CONTRIBUTING.md also says HTML is 4 spaces, so the inconsistency likely predates this PR; however, adding AGENTS.MD amplifies the mismatch. Decide which rule is correct and make the documentation and tooling consistent.
## Fix Focus Areas
- AGENTS.MD[30-33]
- .editorconfig[1-20]
- CONTRIBUTING.md[83-90]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

18. Misleading tests directory 🐞 Bug ✓ Correctness

Description

AGENTS.MD lists a top-level tests/ directory, but the test suites live under src/tests/ (and
scripts reference tests/... relative to src/). This can confuse contributors when locating tests
and test docs from the repo root.

Code

AGENTS.MD[R23-26]

+- `doc/`: Documentation in Markdown and Adoc formats.
+- `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.

Evidence

From the repo root, the tests live under src/tests/ (documented by src/tests/README.md). The
backend test script in src/package.json runs mocha against tests/... paths that are relative
to the src/ package, not a repo-root tests/ directory.

AGENTS.MD[17-26]
src/tests/README.md[1-11]
src/package.json[134-138]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`AGENTS.MD` claims a repo-root `tests/` directory, but tests are located under `src/tests/` (repo-root path). Some scripts use `tests/...` paths relative to `src/`, which is easy to misinterpret.
### Issue Context
Contributors reading AGENTS.MD from the repo root will likely search for `./tests` and not find the test documentation.
### Fix Focus Areas
- AGENTS.MD[17-26]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

19. Wrong easysync doc path 🐞 Bug ✓ Correctness

Description

AGENTS.MD tells contributors to consult doc/easysync/, but the easysync docs checked into this
repo are under doc/public/easysync/. This will send contributors to a dead-end location when
working on synchronization logic.

Code

AGENTS.MD[R51-53]

+### Easysync
+The real-time synchronization engine. It is complex; refer to `doc/easysync/` before modifying core synchronization logic.
+

Evidence

The guide points to doc/easysync/, but the repo’s easysync notes are present under
doc/public/easysync/, so the referenced location is inaccurate for local navigation.

AGENTS.MD[51-53]
doc/public/easysync/easysync-notes.txt[1-5]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`AGENTS.MD` references a non-existent/inaccurate easysync documentation path (`doc/easysync/`). The easysync materials in this repository live under `doc/public/easysync/`.
### Issue Context
This is onboarding-critical documentation; wrong paths cause contributors to waste time when touching Easysync.
### Fix Focus Areas
- AGENTS.MD[51-53]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

20. Backend runner misstated 🐞 Bug ✓ Correctness

Description

AGENTS.MD lists Vitest as a primary testing tool, but the default backend test command uses Mocha
(Vitest exists as a separate script). This can lead contributors to run the wrong tool when
validating backend changes.

Code

AGENTS.MD[R8-16]

+## Technical Stack
+- **Runtime:** Node.js (>= 20.0.0)
+- **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:** Vitest, Playwright, custom backend test suite
+

Evidence

The guide’s testing stack description emphasizes Vitest, but src/package.json shows the default
test script is Mocha and Vitest is only available via test:vitest.

AGENTS.MD[8-16]
src/package.json[134-149]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`AGENTS.MD` describes the test stack as primarily Vitest, but the default backend test runner is Mocha.
### Issue Context
Contributors may attempt to use Vitest for backend tests and fail to run the actual CI-equivalent suite.
### Fix Focus Areas
- AGENTS.MD[8-16]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

21. Misleading tests directory 🐞 Bug ✓ Correctness

Description

AGENTS.MD lists a top-level tests/ directory, but the test suites live under src/tests/ (and
scripts reference tests/... relative to src/). This can confuse contributors when locating tests
and test docs from the repo root.

Code

AGENTS.MD[R23-26]

+- `doc/`: Documentation in Markdown and Adoc formats.
+- `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.

Evidence

From the repo root, the tests live under src/tests/ (documented by src/tests/README.md). The
backend test script in src/package.json runs mocha against tests/... paths that are relative
to the src/ package, not a repo-root tests/ directory.

AGENTS.MD[17-26]
src/tests/README.md[1-11]
src/package.json[134-138]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`AGENTS.MD` claims a repo-root `tests/` directory, but tests are located under `src/tests/` (repo-root path). Some scripts use `tests/...` paths relative to `src/`, which is easy to misinterpret.
### Issue Context
Contributors reading AGENTS.MD from the repo root will likely search for `./tests` and not find the test documentation.
### Fix Focus Areas
- AGENTS.MD[17-26]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

22. Backend runner misstated 🐞 Bug ✓ Correctness

Description

AGENTS.MD lists Vitest as a primary testing tool, but the default backend test command uses Mocha
(Vitest exists as a separate script). This can lead contributors to run the wrong tool when
validating backend changes.

Code

AGENTS.MD[R8-16]

+## Technical Stack
+- **Runtime:** Node.js (>= 20.0.0)
+- **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:** Vitest, Playwright, custom backend test suite
+

Evidence

The guide’s testing stack description emphasizes Vitest, but src/package.json shows the default
test script is Mocha and Vitest is only available via test:vitest.

AGENTS.MD[8-16]
src/package.json[134-149]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`AGENTS.MD` describes the test stack as primarily Vitest, but the default backend test runner is Mocha.
### Issue Context
Contributors may attempt to use Vitest for backend tests and fail to run the actual CI-equivalent suite.
### Fix Focus Areas
- AGENTS.MD[8-16]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

23. README keeps https:// URL 📘 Rule violation ✓ Correctness

Description

The modified README line includes a hardcoded https:// URL instead of a protocol-independent URL
form. This may conflict with the project's requirement to use protocol-independent URLs where
expected.

Code

README.md[103]

+[Node.js](https://nodejs.org/).

Evidence

PR Compliance ID 10 requires protocol-independent URLs where appropriate; the PR-modified README
line contains https://nodejs.org/.

README.md[103-103]
Best Practice: Repository guidelines

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The modified README line contains a hardcoded protocol URL (`https://...`) where protocol-independent URLs are required by the compliance checklist.
## Issue Context
If the project expects protocol-independent URLs in documentation, update the link to match that convention.
## Fix Focus Areas
- README.md[103-103]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

24. Plugin guide out of sync 🐞 Bug ✓ Correctness

Description

Root CONTRIBUTING/best_practices now state a simplified indentation rule, but
bin/plugins/lib/CONTRIBUTING.md still documents the old HTML indentation guidance. This creates
conflicting instructions for contributors, especially when using the plugin template.

Code

CONTRIBUTING.md[86]

+* Indentation: 2 spaces

Evidence

The PR updates the primary contributor docs to say “Indentation: 2 spaces”, but the plugin
template’s CONTRIBUTING guide still states “HTML: 4 spaces”. Having two different in-repo sources of
truth will confuse contributors and reviewers.

CONTRIBUTING.md[83-87]
best_practices.md[83-87]
bin/plugins/lib/CONTRIBUTING.md[73-77]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The repo now contains conflicting indentation guidance: root docs say `Indentation: 2 spaces` while the plugin template guide still says `HTML: 4 spaces`.
### Issue Context
This inconsistency can cause unnecessary formatting churn and review friction, particularly for contributors using the plugin template under `bin/plugins/lib/`.
### Fix Focus Areas
- bin/plugins/lib/CONTRIBUTING.md[73-77]
- CONTRIBUTING.md[83-87]
- best_practices.md[83-87]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

25. Node version mismatch 🐞 Bug ⛯ Reliability

Description

AGENTS.MD declares Node.js >=20.0.0, but README.md and src/package.json state >=18.18.2, while the
root package.json enforces >=20.0.0; this inconsistency will confuse contributors and can lead to
setup failures depending on which source they follow.

Code

AGENTS.MD[9]

+- **Runtime:** Node.js (>= 20.0.0)

Evidence

The new guidance sets a Node minimum that conflicts with existing documentation and the core
package’s engine constraints. With multiple “source of truth” values, contributors may install the
wrong Node version (or incorrectly assume older Node is supported) and hit engine/install/runtime
issues.

AGENTS.MD[8-10]
README.md[101-114]
src/package.json[125-129]
package.json[44-46]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
AGENTS.MD states Node.js >=20.0.0, but README.md and src/package.json indicate Node.js >=18.18.2 while the root package.json enforces >=20.0.0. This creates conflicting guidance and can cause contributor setup failures.
## Issue Context
The repo currently has multiple stated Node minimums. AGENTS.MD should not add another competing requirement; it should either align with the project-wide requirement or clearly explain why different parts of the repo have different engine constraints.
## Fix Focus Areas
- AGENTS.MD[8-11]
- README.md[101-114]
- package.json[44-46]
- src/package.json[125-129]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

26. Wrong easysync doc path 🐞 Bug ✓ Correctness

Description

AGENTS.MD tells contributors to consult doc/easysync/, but the easysync docs checked into this
repo are under doc/public/easysync/. This will send contributors to a dead-end location when
working on synchronization logic.

Code

AGENTS.MD[R51-53]

+### Easysync
+The real-time synchronization engine. It is complex; refer to `doc/easysync/` before modifying core synchronization logic.
+

Evidence

The guide points to doc/easysync/, but the repo’s easysync notes are present under
doc/public/easysync/, so the referenced location is inaccurate for local navigation.

AGENTS.MD[51-53]
doc/public/easysync/easysync-notes.txt[1-5]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`AGENTS.MD` references a non-existent/inaccurate easysync documentation path (`doc/easysync/`). The easysync materials in this repository live under `doc/public/easysync/`.
### Issue Context
This is onboarding-critical documentation; wrong paths cause contributors to waste time when touching Easysync.
### Fix Focus Areas
- AGENTS.MD[51-53]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

27. HTML indent rule conflicts 🐞 Bug ⛯ Reliability

Description

AGENTS.MD mandates 4-space HTML indentation, but .editorconfig sets indent_size=2 globally with no
HTML override; contributors using EditorConfig-aware tools will format HTML with 2 spaces, causing
noisy diffs and review churn.

Code

AGENTS.MD[31]

+- **Indentation:** 2 spaces for JS/TS/CSS; 4 spaces for HTML.

Evidence

The new guide repeats the 4-space HTML rule, but the repo’s EditorConfig configuration will drive
most IDEs/formatters to apply 2 spaces to HTML. This mismatch predictably results in inconsistent
formatting across contributions.

AGENTS.MD[30-33]
.editorconfig[1-9]
CONTRIBUTING.md[83-87]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
AGENTS.MD says HTML should be indented with 4 spaces, but .editorconfig enforces inden...

[JohnMcLear]

/review

[qodo-free-for-open-source-projects]

Persistent review updated to latest commit 1b656b4

[JohnMcLear]

/review

[qodo-free-for-open-source-projects]

Persistent review updated to latest commit ec37d5d

[JohnMcLear]

/review

[qodo-free-for-open-source-projects]

Persistent review updated to latest commit 2b36182

[qodo-free-for-open-source-projects]

Review Summary by Qodo

Add agent guide and standardize project documentation

📝 Documentation ✨ Enhancement

Walkthroughs

Description

• Add AGENTS.MD guide for AI agents and developers
• Standardize indentation to 2 spaces across documentation
• Update Node.js version requirement to >=20.0.0
• Enable automatic PR review via .pr_agent.toml configuration

Diagram

flowchart LR
  A["New AGENTS.MD<br/>Agent Guide"] --> B["Documentation<br/>Standards"]
  C["PR Agent Config<br/>.pr_agent.toml"] --> D["Automation"]
  E["Node.js >=20.0.0<br/>Version Update"] --> F["Dependencies"]
  B --> G["Indentation<br/>Standardization"]
  G --> H["Updated Files<br/>CONTRIBUTING.md<br/>best_practices.md<br/>README.md"]

Loading

File Changes

1. AGENTS.MD 📝 Documentation +61/-0

New agent guide for project contribution

• New comprehensive guide for AI agents and developers
• Covers project overview, technical stack, and directory structure
• Documents core mandates, coding conventions, and development workflow
• Includes testing requirements, key concepts (Easysync, plugins), and AI-specific guidance

AGENTS.MD

---

2. .pr_agent.toml ⚙️ Configuration changes +5/-0

Add PR Agent automation configuration

• New configuration file for PR Agent automation
• Enables automatic PR review on sync
• Enables automatic PR description generation on sync

.pr_agent.toml

---

3. CONTRIBUTING.md 📝 Documentation +1/-1

Standardize indentation guidelines

• Standardize indentation guideline from "JS/CSS: 2 spaces; HTML: 4 spaces" to uniform "2 spaces"
• Aligns with project-wide indentation standardization

CONTRIBUTING.md

---

View more (3)

4. best_practices.md 📝 Documentation +1/-1

Standardize indentation guidelines

• Standardize indentation guideline from "JS/CSS: 2 spaces; HTML: 4 spaces" to uniform "2 spaces"
• Aligns with project-wide indentation standardization

best_practices.md

---

5. README.md 📝 Documentation +1/-1

Remove hardcoded Node.js version

• Remove specific Node.js version requirement (18.18.2)
• Update to reference package.json as source of truth for version requirements

README.md

---

6. src/package.json Dependencies +1/-1

Update Node.js engine requirement

• Update Node.js engine requirement from >=18.18.2 to >=20.0.0
• Aligns with root package.json and project minimum version

src/package.json

---

[qodo-free-for-open-source-projects]

Code Review by Qodo

🐞 Bugs (19) 📘 Rule violations (3) 📎 Requirement gaps (0)

1. Docs set HTML 2-space 📘 Rule violation ✓ Correctness ⭐ New

Description

The PR updates contributor/agent guidance to state that HTML should be indented with 2 spaces, which
conflicts with the required style rule (HTML must be 4 spaces). This creates non-compliant guidance
that will likely lead to future whitespace-style violations.

Code

AGENTS.MD[R30-33]

+### Coding Style
+- **Indentation:** 2 spaces for all files (JS/TS/CSS/HTML).
+- **No Tabs:** Use spaces only.
+- **Comments:** Provide clear comments for complex logic.

Evidence

PR Compliance ID 9 requires HTML indentation to be 4 spaces, but the new/updated documentation
explicitly instructs 2-space indentation for HTML.

AGENTS.MD[30-32]
CONTRIBUTING.md[86-86]
best_practices.md[86-86]
Best Practice: Repository guidelines

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The PR updates documentation to instruct `Indentation: 2 spaces` for everything, including HTML, which conflicts with the required whitespace rule (HTML must be 4 spaces).

## Issue Context
This is a direct mismatch between documented style guidance and the compliance requirement, and will likely cause future diffs and formatting violations.

## Fix Focus Areas
- AGENTS.MD[30-33]
- CONTRIBUTING.md[86-86]
- best_practices.md[86-86]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Node engine raised to 20 📘 Rule violation ⛯ Reliability

Description

The PR increases the minimum supported Node.js version to >=20.0.0, which is a
backward-incompatible runtime requirement change. This breaking change is not documented in the
user-facing requirements documentation and can break existing deployments pinned to Node 18.

Code

src/package.json[126]

+    "node": ">=20.0.0",

Evidence

PR Compliance ID 3 requires backward-incompatible changes to configuration/runtime requirements to
be justified and clearly documented. The diff shows the Node.js engine requirement being raised to
>=20.0.0 while the README simultaneously removes the previously documented minimum version,
leaving the breaking change undocumented.

src/package.json[126-126]
README.md[103-103]
Best Practice: Repository guidelines

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The PR raises the Node.js engine requirement to `>=20.0.0`, which is a backward-incompatible runtime/configuration change, but the PR does not document this breaking requirement change (and removes the previously documented minimum Node version from the README).
## Issue Context
This can break existing deployments and developer environments that still use Node 18.x. Compliance requires that unavoidable breaking changes be clearly documented along with impact.
## Fix Focus Areas
- src/package.json[126-126]
- README.md[103-103]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

3. README hides Node>=20 req 🐞 Bug ✓ Correctness

Description

README’s Requirements section no longer states a minimum Node.js version, but the repo enforces Node
>=20 (engineStrict + runtime check). Users following the README may install an unsupported Node
version and hit install/runtime failures.

Code

README.md[103]

+[Node.js](https://nodejs.org/).

Evidence

The README no longer specifies a Node version, but the project explicitly requires Node >=20 in the
root and src package manifests and enforces the requirement at runtime on startup.

README.md[101-105]
package.json[44-52]
src/package.json[125-129]
src/node/server.ts[67-74]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
README no longer specifies a minimum Node.js version, but the repo enforces Node >= 20.0.0 at install time (`engineStrict`) and at runtime (startup exits if Node is too old). This mismatch will cause avoidable setup failures for new users.
## Issue Context
- Root `package.json` sets `engines.node` to `>=20.0.0` and `engineStrict: true`.
- `src/node/server.ts` enforces the minimum based on `src/package.json`.
## Fix Focus Areas
- README.md[101-105]
- package.json[44-52]
- src/package.json[125-129]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

4. README keeps https:// URL 📘 Rule violation ✓ Correctness ⭐ New

Description

The modified README line includes a hardcoded https:// URL instead of a protocol-independent URL
form. This may conflict with the project's requirement to use protocol-independent URLs where
expected.

Code

README.md[103]

+[Node.js](https://nodejs.org/).

Evidence

PR Compliance ID 10 requires protocol-independent URLs where appropriate; the PR-modified README
line contains https://nodejs.org/.

README.md[103-103]
Best Practice: Repository guidelines

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The modified README line contains a hardcoded protocol URL (`https://...`) where protocol-independent URLs are required by the compliance checklist.

## Issue Context
If the project expects protocol-independent URLs in documentation, update the link to match that convention.

## Fix Focus Areas
- README.md[103-103]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

5. Plugin guide out of sync 🐞 Bug ✓ Correctness ⭐ New

Description

Root CONTRIBUTING/best_practices now state a simplified indentation rule, but
bin/plugins/lib/CONTRIBUTING.md still documents the old HTML indentation guidance. This creates
conflicting instructions for contributors, especially when using the plugin template.

Code

CONTRIBUTING.md[86]

+* Indentation: 2 spaces

Evidence

The PR updates the primary contributor docs to say “Indentation: 2 spaces”, but the plugin
template’s CONTRIBUTING guide still states “HTML: 4 spaces”. Having two different in-repo sources of
truth will confuse contributors and reviewers.

CONTRIBUTING.md[83-87]
best_practices.md[83-87]
bin/plugins/lib/CONTRIBUTING.md[73-77]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
The repo now contains conflicting indentation guidance: root docs say `Indentation: 2 spaces` while the plugin template guide still says `HTML: 4 spaces`.

### Issue Context
This inconsistency can cause unnecessary formatting churn and review friction, particularly for contributors using the plugin template under `bin/plugins/lib/`.

### Fix Focus Areas
- bin/plugins/lib/CONTRIBUTING.md[73-77]
- CONTRIBUTING.md[83-87]
- best_practices.md[83-87]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

6. Node version mismatch 🐞 Bug ⛯ Reliability

Description

AGENTS.MD declares Node.js >=20.0.0, but README.md and src/package.json state >=18.18.2, while the
root package.json enforces >=20.0.0; this inconsistency will confuse contributors and can lead to
setup failures depending on which source they follow.

Code

AGENTS.MD[9]

+- **Runtime:** Node.js (>= 20.0.0)

Evidence

The new guidance sets a Node minimum that conflicts with existing documentation and the core
package’s engine constraints. With multiple “source of truth” values, contributors may install the
wrong Node version (or incorrectly assume older Node is supported) and hit engine/install/runtime
issues.

AGENTS.MD[8-10]
README.md[101-114]
src/package.json[125-129]
package.json[44-46]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
AGENTS.MD states Node.js >=20.0.0, but README.md and src/package.json indicate Node.js >=18.18.2 while the root package.json enforces >=20.0.0. This creates conflicting guidance and can cause contributor setup failures.
## Issue Context
The repo currently has multiple stated Node minimums. AGENTS.MD should not add another competing requirement; it should either align with the project-wide requirement or clearly explain why different parts of the repo have different engine constraints.
## Fix Focus Areas
- AGENTS.MD[8-11]
- README.md[101-114]
- package.json[44-46]
- src/package.json[125-129]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

View more (16)

7. Wrong easysync doc path 🐞 Bug ✓ Correctness

Description

AGENTS.MD tells contributors to consult doc/easysync/, but the easysync docs checked into this
repo are under doc/public/easysync/. This will send contributors to a dead-end location when
working on synchronization logic.

Code

AGENTS.MD[R51-53]

+### Easysync
+The real-time synchronization engine. It is complex; refer to `doc/easysync/` before modifying core synchronization logic.
+

Evidence

The guide points to doc/easysync/, but the repo’s easysync notes are present under
doc/public/easysync/, so the referenced location is inaccurate for local navigation.

AGENTS.MD[51-53]
doc/public/easysync/easysync-notes.txt[1-5]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`AGENTS.MD` references a non-existent/inaccurate easysync documentation path (`doc/easysync/`). The easysync materials in this repository live under `doc/public/easysync/`.
### Issue Context
This is onboarding-critical documentation; wrong paths cause contributors to waste time when touching Easysync.
### Fix Focus Areas
- AGENTS.MD[51-53]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

8. HTML indent rule conflicts 🐞 Bug ⛯ Reliability

Description

AGENTS.MD mandates 4-space HTML indentation, but .editorconfig sets indent_size=2 globally with no
HTML override; contributors using EditorConfig-aware tools will format HTML with 2 spaces, causing
noisy diffs and review churn.

Code

AGENTS.MD[31]

+- **Indentation:** 2 spaces for JS/TS/CSS; 4 spaces for HTML.

Evidence

The new guide repeats the 4-space HTML rule, but the repo’s EditorConfig configuration will drive
most IDEs/formatters to apply 2 spaces to HTML. This mismatch predictably results in inconsistent
formatting across contributions.

AGENTS.MD[30-33]
.editorconfig[1-9]
CONTRIBUTING.md[83-87]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
AGENTS.MD says HTML should be indented with 4 spaces, but .editorconfig enforces indent_size=2 for all files. EditorConfig-aware tools will format HTML with 2 spaces, leading to inconsistent formatting and PR churn.
## Issue Context
CONTRIBUTING.md also says HTML is 4 spaces, so the inconsistency likely predates this PR; however, adding AGENTS.MD amplifies the mismatch. Decide which rule is correct and make the documentation and tooling consistent.
## Fix Focus Areas
- AGENTS.MD[30-33]
- .editorconfig[1-20]
- CONTRIBUTING.md[83-90]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

9. Misleading tests directory 🐞 Bug ✓ Correctness

Description

AGENTS.MD lists a top-level tests/ directory, but the test suites live under src/tests/ (and
scripts reference tests/... relative to src/). This can confuse contributors when locating tests
and test docs from the repo root.

Code

AGENTS.MD[R23-26]

+- `doc/`: Documentation in Markdown and Adoc formats.
+- `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.

Evidence

From the repo root, the tests live under src/tests/ (documented by src/tests/README.md). The
backend test script in src/package.json runs mocha against tests/... paths that are relative
to the src/ package, not a repo-root tests/ directory.

AGENTS.MD[17-26]
src/tests/README.md[1-11]
src/package.json[134-138]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`AGENTS.MD` claims a repo-root `tests/` directory, but tests are located under `src/tests/` (repo-root path). Some scripts use `tests/...` paths relative to `src/`, which is easy to misinterpret.
### Issue Context
Contributors reading AGENTS.MD from the repo root will likely search for `./tests` and not find the test documentation.
### Fix Focus Areas
- AGENTS.MD[17-26]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

10. Plugin tooling Node floor stale 🐞 Bug ⛯ Reliability

Description

Core now declares Node >=20 in src/package.json, but the plugin checker still writes
engines.node: >=18.0.0 into plugin package.json files. This can mislead plugin authors into
thinking Node 18 is a supported baseline for current Etherpad development.

Code

src/package.json[126]

+    "node": ">=20.0.0",

Evidence

CI and the root package already target Node >=20, and the server enforces the Node minimum from
src/package.json. However, the plugin tooling continues to set a lower engines.node in plugins,
creating inconsistent guidance after this PR’s Node engine bump in src/package.json.

src/package.json[125-129]
package.json[44-46]
.github/workflows/backend-tests.yml[27-31]
bin/plugins/checkPlugin.ts[229-233]
src/node/server.ts[71-74]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
After bumping core’s Node requirement to >=20, the plugin checker still stamps plugins with `engines.node >=18.0.0`, which is inconsistent with the runtime users will actually run plugins under. This is likely to confuse plugin authors and create avoidable incompatibility reports.
## Issue Context
- Core requires Node >=20 (root and src package manifests; CI matrix).
- `bin/plugins/checkPlugin.ts` currently writes `>=18.0.0` into plugin `package.json`.
## Fix Focus Areas
- bin/plugins/checkPlugin.ts[229-233]
- package.json[44-46]
- src/package.json[125-129]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

11. Wrong easysync doc path 🐞 Bug ✓ Correctness

Description

AGENTS.MD tells contributors to consult doc/easysync/, but the easysync docs checked into this
repo are under doc/public/easysync/. This will send contributors to a dead-end location when
working on synchronization logic.

Code

AGENTS.MD[R51-53]

+### Easysync
+The real-time synchronization engine. It is complex; refer to `doc/easysync/` before modifying core synchronization logic.
+

Evidence

The guide points to doc/easysync/, but the repo’s easysync notes are present under
doc/public/easysync/, so the referenced location is inaccurate for local navigation.

AGENTS.MD[51-53]
doc/public/easysync/easysync-notes.txt[1-5]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`AGENTS.MD` references a non-existent/inaccurate easysync documentation path (`doc/easysync/`). The easysync materials in this repository live under `doc/public/easysync/`.
### Issue Context
This is onboarding-critical documentation; wrong paths cause contributors to waste time when touching Easysync.
### Fix Focus Areas
- AGENTS.MD[51-53]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

12. Backend runner misstated 🐞 Bug ✓ Correctness

Description

AGENTS.MD lists Vitest as a primary testing tool, but the default backend test command uses Mocha
(Vitest exists as a separate script). This can lead contributors to run the wrong tool when
validating backend changes.

Code

AGENTS.MD[R8-16]

+## Technical Stack
+- **Runtime:** Node.js (>= 20.0.0)
+- **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:** Vitest, Playwright, custom backend test suite
+

Evidence

The guide’s testing stack description emphasizes Vitest, but src/package.json shows the default
test script is Mocha and Vitest is only available via test:vitest.

AGENTS.MD[8-16]
src/package.json[134-149]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`AGENTS.MD` describes the test stack as primarily Vitest, but the default backend test runner is Mocha.
### Issue Context
Contributors may attempt to use Vitest for backend tests and fail to run the actual CI-equivalent suite.
### Fix Focus Areas
- AGENTS.MD[8-16]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

13. Node version mismatch 🐞 Bug ⛯ Reliability

Description

AGENTS.MD declares Node.js >=20.0.0, but README.md and src/package.json state >=18.18.2, while the
root package.json enforces >=20.0.0; this inconsistency will confuse contributors and can lead to
setup failures depending on which source they follow.

Code

AGENTS.MD[9]

+- **Runtime:** Node.js (>= 20.0.0)

Evidence

The new guidance sets a Node minimum that conflicts with existing documentation and the core
package’s engine constraints. With multiple “source of truth” values, contributors may install the
wrong Node version (or incorrectly assume older Node is supported) and hit engine/install/runtime
issues.

AGENTS.MD[8-10]
README.md[101-114]
src/package.json[125-129]
package.json[44-46]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
AGENTS.MD states Node.js >=20.0.0, but README.md and src/package.json indicate Node.js >=18.18.2 while the root package.json enforces >=20.0.0. This creates conflicting guidance and can cause contributor setup failures.
## Issue Context
The repo currently has multiple stated Node minimums. AGENTS.MD should not add another competing requirement; it should either align with the project-wide requirement or clearly explain why different parts of the repo have different engine constraints.
## Fix Focus Areas
- AGENTS.MD[8-11]
- README.md[101-114]
- package.json[44-46]
- src/package.json[125-129]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

14. Misleading tests directory 🐞 Bug ✓ Correctness

Description

AGENTS.MD lists a top-level tests/ directory, but the test suites live under src/tests/ (and
scripts reference tests/... relative to src/). This can confuse contributors when locating tests
and test docs from the repo root.

Code

AGENTS.MD[R23-26]

+- `doc/`: Documentation in Markdown and Adoc formats.
+- `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.

Evidence

From the repo root, the tests live under src/tests/ (documented by src/tests/README.md). The
backend test script in src/package.json runs mocha against tests/... paths that are relative
to the src/ package, not a repo-root tests/ directory.

AGENTS.MD[17-26]
src/tests/README.md[1-11]
src/package.json[134-138]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`AGENTS.MD` claims a repo-root `tests/` directory, but tests are located under `src/tests/` (repo-root path). Some scripts use `tests/...` paths relative to `src/`, which is easy to misinterpret.
### Issue Context
Contributors reading AGENTS.MD from the repo root will likely search for `./tests` and not find the test documentation.
### Fix Focus Areas
- AGENTS.MD[17-26]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

15. Wrong easysync doc path 🐞 Bug ✓ Correctness

Description

AGENTS.MD tells contributors to consult doc/easysync/, but the easysync docs checked into this
repo are under doc/public/easysync/. This will send contributors to a dead-end location when
working on synchronization logic.

Code

AGENTS.MD[R51-53]

+### Easysync
+The real-time synchronization engine. It is complex; refer to `doc/easysync/` before modifying core synchronization logic.
+

Evidence

The guide points to doc/easysync/, but the repo’s easysync notes are present under
doc/public/easysync/, so the referenced location is inaccurate for local navigation.

AGENTS.MD[51-53]
doc/public/easysync/easysync-notes.txt[1-5]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`AGENTS.MD` references a non-existent/inaccurate easysync documentation path (`doc/easysync/`). The easysync materials in this repository live under `doc/public/easysync/`.
### Issue Context
This is onboarding-critical documentation; wrong paths cause contributors to waste time when touching Easysync.
### Fix Focus Areas
- AGENTS.MD[51-53]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

16. Backend runner misstated 🐞 Bug ✓ Correctness

Description

AGENTS.MD lists Vitest as a primary testing tool, but the default backend test command uses Mocha
(Vitest exists as a separate script). This can lead contributors to run the wrong tool when
validating backend changes.

Code

AGENTS.MD[R8-16]

+## Technical Stack
+- **Runtime:** Node.js (>= 20.0.0)
+- **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:** Vitest, Playwright, custom backend test suite
+

Evidence

The guide’s testing stack description emphasizes Vitest, but src/package.json shows the default
test script is Mocha and Vitest is only available via test:vitest.

AGENTS.MD[8-16]
src/package.json[134-149]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`AGENTS.MD` describes the test stack as primarily Vitest, but the default backend test runner is Mocha.
### Issue Context
Contributors may attempt to use Vitest for backend tests and fail to run the actual CI-equivalent suite.
### Fix Focus Areas
- AGENTS.MD[8-16]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

17. HTML indent rule conflicts 🐞 Bug ⛯ Reliability

Description

AGENTS.MD mandates 4-space HTML indentation, but .editorconfig sets indent_size=2 globally with no
HTML override; contributors using EditorConfig-aware tools will format HTML with 2 spaces, causing
noisy diffs and review churn.

Code

AGENTS.MD[31]

+- **Indentation:** 2 spaces for JS/TS/CSS; 4 spaces for HTML.

Evidence

The new guide repeats the 4-space HTML rule, but the repo’s EditorConfig configuration will drive
most IDEs/formatters to apply 2 spaces to HTML. This mismatch predictably results in inconsistent
formatting across contributions.

AGENTS.MD[30-33]
.editorconfig[1-9]
CONTRIBUTING.md[83-87]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
AGENTS.MD says HTML should be indented with 4 spaces, but .editorconfig enforces indent_size=2 for all files. EditorConfig-aware tools will format HTML with 2 spaces, leading to inconsistent formatting and PR churn.
## Issue Context
CONTRIBUTING.md also says HTML is 4 spaces, so the inconsistency likely predates this PR; however, adding AGENTS.MD amplifies the mismatch. Decide which rule is correct and make the documentation and tooling consistent.
## Fix Focus Areas
- AGENTS.MD[30-33]
- .editorconfig[1-20]
- CONTRIBUTING.md[83-90]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

18. Misleading tests directory 🐞 Bug ✓ Correctness

Description

AGENTS.MD lists a top-level tests/ directory, but the test suites live under src/tests/ (and
scripts reference tests/... relative to src/). This can confuse contributors when locating tests
and test docs from the repo root.

Code

AGENTS.MD[R23-26]

+- `doc/`: Documentation in Markdown and Adoc formats.
+- `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.

Evidence

From the repo root, the tests live under src/tests/ (documented by src/tests/README.md). The
backend test script in src/package.json runs mocha against tests/... paths that are relative
to the src/ package, not a repo-root tests/ directory.

AGENTS.MD[17-26]
src/tests/README.md[1-11]
src/package.json[134-138]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`AGENTS.MD` claims a repo-root `tests/` directory, but tests are located under `src/tests/` (repo-root path). Some scripts use `tests/...` paths relative to `src/`, which is easy to misinterpret.
### Issue Context
Contributors reading AGENTS.MD from the repo root will likely search for `./tests` and not find the test documentation.
### Fix Focus Areas
- AGENTS.MD[17-26]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

19. Wrong easysync doc path 🐞 Bug ✓ Correctness

Description

AGENTS.MD tells contributors to consult doc/easysync/, but the easysync docs checked into this
repo are under doc/public/easysync/. This will send contributors to a dead-end location when
working on synchronization logic.

Code

AGENTS.MD[R51-53]

+### Easysync
+The real-time synchronization engine. It is complex; refer to `doc/easysync/` before modifying core synchronization logic.
+

Evidence

The guide points to doc/easysync/, but the repo’s easysync notes are present under
doc/public/easysync/, so the referenced location is inaccurate for local navigation.

AGENTS.MD[51-53]
doc/public/easysync/easysync-notes.txt[1-5]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`AGENTS.MD` references a non-existent/inaccurate easysync documentation path (`doc/easysync/`). The easysync materials in this repository live under `doc/public/easysync/`.
### Issue Context
This is onboarding-critical documentation; wrong paths cause contributors to waste time when touching Easysync.
### Fix Focus Areas
- AGENTS.MD[51-53]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

20. Backend runner misstated 🐞 Bug ✓ Correctness

Description

AGENTS.MD lists Vitest as a primary testing tool, but the default backend test command uses Mocha
(Vitest exists as a separate script). This can lead contributors to run the wrong tool when
validating backend changes.

Code

AGENTS.MD[R8-16]

+## Technical Stack
+- **Runtime:** Node.js (>= 20.0.0)
+- **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:** Vitest, Playwright, custom backend test suite
+

Evidence

The guide’s testing stack description emphasizes Vitest, but src/package.json shows the default
test script is Mocha and Vitest is only available via test:vitest.

AGENTS.MD[8-16]
src/package.json[134-149]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`AGENTS.MD` describes the test stack as primarily Vitest, but the default backend test runner is Mocha.
### Issue Context
Contributors may attempt to use Vitest for backend tests and fail to run the actual CI-equivalent suite.
### Fix Focus Areas
- AGENTS.MD[8-16]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

21. Misleading tests directory 🐞 Bug ✓ Correctness

Description

AGENTS.MD lists a top-level tests/ directory, but the test suites live under src/tests/ (and
scripts reference tests/... relative to src/). This can confuse contributors when locating tests
and test docs from the repo root.

Code

AGENTS.MD[R23-26]

+- `doc/`: Documentation in Markdown and Adoc formats.
+- `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.

Evidence

From the repo root, the tests live under src/tests/ (documented by src/tests/README.md). The
backend test script in src/package.json runs mocha against tests/... paths that are relative
to the src/ package, not a repo-root tests/ directory.

AGENTS.MD[17-26]
src/tests/README.md[1-11]
src/package.json[134-138]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`AGENTS.MD` claims a repo-root `tests/` directory, but tests are located under `src/tests/` (repo-root path). Some scripts use `tests/...` paths relative to `src/`, which is easy to misinterpret.
### Issue Context
Contributors reading AGENTS.MD from the repo root will likely search for `./tests` and not find the test documentation.
### Fix Focus Areas
- AGENTS.MD[17-26]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

22. Backend runner misstated 🐞 Bug ✓ Correctness

Description

AGENTS.MD lists Vitest as a primary testing tool, but the default backend test command uses Mocha
(Vitest exists as a separate script). This can lead contributors to run the wrong tool when
validating backend changes.

Code

AGENTS.MD[R8-16]

+## Technical Stack
+- **Runtime:** Node.js (>= 20.0.0)
+- **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:** Vitest, Playwright, custom backend test suite
+

Evidence

The guide’s testing stack description emphasizes Vitest, but src/package.json shows the default
test script is Mocha and Vitest is only available via test:vitest.

AGENTS.MD[8-16]
src/package.json[134-149]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`AGENTS.MD` describes the test stack as primarily Vitest, but the default backend test runner is Mocha.
### Issue Context
Contributors may attempt to use Vitest for backend tests and fail to run the actual CI-equivalent suite.
### Fix Focus Areas
- AGENTS.MD[8-16]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

ⓘ The new review experience is currently in Beta. Learn more

[qodo-free-for-open-source-projects]

1. Docs set html 2-space 📘 Rule violation ✓ Correctness

The PR updates contributor/agent guidance to state that HTML should be indented with 2 spaces, which
conflicts with the required style rule (HTML must be 4 spaces). This creates non-compliant guidance
that will likely lead to future whitespace-style violations.

Agent Prompt

## Issue description
The PR updates documentation to instruct `Indentation: 2 spaces` for everything, including HTML, which conflicts with the required whitespace rule (HTML must be 4 spaces).

## Issue Context
This is a direct mismatch between documented style guidance and the compliance requirement, and will likely cause future diffs and formatting violations.

## Fix Focus Areas
- AGENTS.MD[30-33]
- CONTRIBUTING.md[86-86]
- best_practices.md[86-86]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools