docs: rewrite AGENTS.MD to reflect ueberDB2 reality

[JohnMcLear]

Summary

The existing AGENTS.MD described Etherpad — React UIs, i18n, accessibility rules, a plugin framework, Easysync, Playwright E2E, a ep_UeberDB-lite workspace — none of which exists in this repository. This rewrites it to describe ueberDB2 as it actually is.

What the new guide covers (verified against source)

• What it is — ueberdb2, a key/value database abstraction library with a read cache + write buffer; a library, not an application.
• Stack — Node ≥22, pnpm, TypeScript compiled to ESM via rolldown + tsc, linted with oxlint/oxfmt, tested with Vitest + testcontainers.
• Real directory layout — index.ts (entry, lazy driver loading), lib/AbstractDatabase.ts, lib/CacheAndBufferLayer.ts, lib/logging.ts, databases/<name>_db.ts, test/.
• The 17 backends from the DatabaseType union; drivers are optional, lazily-imported peer deps; sqlite is the default.
• Public API — init/get/set/remove/findKeys/findKeysPaged/getSub/setSub/flush/close (+ deprecated doShutdown), connection-string support.
• Commands — pnpm run lint / ts-check / build / test <name>, which backends need Docker, the 120s timeout and 5× retry policy.
• CI — ci.yml (lint/ts-check/build) and npmpublish.yml (per-DB test matrix → publish).
• Flags where README.md and CONTRIBUTING.md carry stale Etherpad-era instructions.

🤖 Generated with Claude Code

[qodo-code-review]

Qodo reviews are paused for this user.

Troubleshooting steps vary by plan Learn more →

On a Teams plan?
Reviews resume once this user has a paid seat and their Git account is linked in Qodo.
Link Git account →

Using GitHub Enterprise Server, GitLab Self-Managed, or Bitbucket Data Center?
These require an Enterprise plan - Contact us
Contact us →

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

Review Summary by Qodo

Rewrite AGENTS.MD to reflect ueberDB2 reality

📝 Documentation

Walkthroughs

Description

• Rewrites AGENTS.MD to document ueberDB2 as a key/value database library
• Replaces outdated Etherpad references with accurate technical stack details
• Documents 17 supported backends, public API, and directory structure
• Provides build/test/lint commands and CI workflow information

Diagram

flowchart LR
  A["Outdated Etherpad docs<br/>React, i18n, plugins"] -->|Replace| B["ueberDB2 guide<br/>Key/value library"]
  B --> C["Project overview<br/>& stack"]
  B --> D["Directory structure<br/>& backends"]
  B --> E["Public API<br/>& conventions"]
  B --> F["Build/test commands<br/>& CI workflows"]

Loading

File Changes

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

Complete rewrite of AGENTS.MD for ueberDB2

• Created comprehensive 125-line agent guide for ueberDB2 replacing Etherpad-focused documentation
• Covers project overview, technical stack (Node 22+, pnpm, TypeScript, rolldown, Vitest,
 testcontainers)
• Documents real directory layout with 17 supported database backends and their lazy-loading
 mechanism
• Details public API methods (init, get, set, remove, findKeys, findKeysPaged, getSub, setSub,
 flush, close)
• Includes coding conventions, backend addition steps, build/lint/test commands, CI workflows, and
 contribution guidelines

AGENTS.MD

---

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

Code Review by Qodo

🐞 Bugs (1) 📘 Rule violations (0)

1. Missing findKeysPaged API 🐞 Bug ≡ Correctness

Description

AGENTS.MD documents and demonstrates Database.findKeysPaged(), but the exported Database class
has no findKeysPaged method, so following the guide will fail (TypeScript compile error / runtime
undefined). The same example passes null to findKeys() even though the parameter is typed as an
optional string, so the snippet does not typecheck as written.

Code

AGENTS.MD[R57-58]

Evidence

The guide shows findKeysPaged() as part of the public API and references it in the “Adding a New
Backend” section, but the exported Database wrapper class only exposes
init/flush/doShutdown/get/findKeys/remove/set/getSub/setSub/close. The documented `findKeys(...,
null)` call also contradicts the method signature’s optional string parameter.

AGENTS.MD[50-63]
AGENTS.MD[76-80]
index.ts[48-171]

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` documents a `findKeysPaged()` API and suggests implementing/overriding it for new backends, but the project’s exported `Database` class does not expose such a method, and the repository contains no implementation. Additionally, the TypeScript example calls `findKeys(..., null)` even though the API expects an optional `string` (`undefined`/omitted), not `null`.

### Issue Context
This guide claims to reflect the repository’s reality; incorrect API documentation will immediately mislead contributors and cause broken copy/paste examples.

### Fix Focus Areas
- AGENTS.MD[50-63]
- AGENTS.MD[76-80]

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

---

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

1. Missing findkeyspaged api 🐞 Bug ≡ Correctness

AGENTS.MD documents and demonstrates Database.findKeysPaged(), but the exported Database class
has no findKeysPaged method, so following the guide will fail (TypeScript compile error / runtime
undefined). The same example passes null to findKeys() even though the parameter is typed as an
optional string, so the snippet does not typecheck as written.

Agent Prompt

### Issue description
`AGENTS.MD` documents a `findKeysPaged()` API and suggests implementing/overriding it for new backends, but the project’s exported `Database` class does not expose such a method, and the repository contains no implementation. Additionally, the TypeScript example calls `findKeys(..., null)` even though the API expects an optional `string` (`undefined`/omitted), not `null`.

### Issue Context
This guide claims to reflect the repository’s reality; incorrect API documentation will immediately mislead contributors and cause broken copy/paste examples.

### Fix Focus Areas
- AGENTS.MD[50-63]
- AGENTS.MD[76-80]

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