1 files changed, 112 insertions, 0 deletions
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 000000000..2dfc1ef3d
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,112 @@
+---
+description: FreshRSS introduction and conventions for AI agents and human contributors
+---
+
+# FreshRSS introduction and conventions
+
+FreshRSS is an open-source news aggregator supporting RSS/ATOM/WebSub and also Web scraping.
+
+The market segment is mostly self-hosting, although multiple user accounts are supported.
+It is supposed to be installed on a modest server (mostly, but not limited to, Linux) and can be accessed through a Web UI and an API.
+
+It is written in PHP to make it easy to deploy and easy to contribute to.
+
+More information can be found in [README](README.md) and in the [documentation](docs/en/) published at <https://freshrss.github.io/FreshRSS/en/>
+
+## Instruction structure for AI agents and humans
+
+* [`.github/instructions/`](.github/instructions/) contain the instructions that primarily match filename patterns.
+* [`.github/skills/`](.github/skills/) contain the skills to achieve higher-level goals, potentially combining multiple instructions.
+* **`AGENTS.md`** is the entry point description for AI coding agents and contributors, referencing other documents such as instructions and skills.
+* Favour standard conventions over vendor-specific ones.
+* To reduce duplication, refer to enforceable configuration files instead of excessive free-text repetitions.
+
+## Code structure
+
+* `app/Controllers/` – Controllers extend `FreshRSS_ActionController`, named as `{name}Controller.php` with class `FreshRSS_{name}_Controller`
+* `app/Models/` – Domain models extend `Minz_Model`.
+	* DAOs may have some database-specific inheritance, e.g.: `*DAO.php` (base or MySQL), `*DAOSQLite.php` (SQLite), `*DAOPGSQL.php` (PostgreSQL)
+* `app/views/{controller}/` – View templates are `.phtml` files mixing PHP and HTML
+* `app/views/helpers/` – Reusable view elements with `$this->partial('name')`
+* `lib/core-extensions/` or `extensions/` – FreshRSS extensions
+* `lib/Minz/` – Core framework: routing, sessions, translations, extensions, PDO abstraction
+* `lib/lib_rss.php` – Contain `spl_autoload_register` and other global functions
+* `p/` – Public Web root. Only the content of this folder should be exposed if possible (`p/` should not be visible in the public URL)
+	* Only the `p/i/` path should be access controlled. The main entry point is `p/i/index.php`
+	* `p/api/greader.php` – Primary API for mobile clients
+	* `p/api/pshb.php` – Receive realtime pushes via WebSub
+	* `p/themes/` – UI themes
+
+### Configuration data
+
+* Constants: [`constants.php`](constants.php) overridden in `constants.local.php`
+* System config: [`config.default.php`](config.default.php) overridden in `data/config.php`
+* User config: [`config-user.default.php`](config-user.default.php) overridden in `data/users/{username}/config.php`
+
+> ℹ Access via `FreshRSS_Context::systemConf()` and `FreshRSS_Context::userConf()`
+
+## Database patterns
+
+Three database backends supported: SQLite, PostgreSQL, MySQL/MariaDB.
+The SQL differences are implemented through inheritance:
+
+```php
+// Base DAO with common queries
+class FreshRSS_EntryDAO extends Minz_ModelPdo { }
+// Database-specific overrides
+class FreshRSS_EntryDAOSQLite extends FreshRSS_EntryDAO { }
+class FreshRSS_EntryDAOPGSQL extends FreshRSS_EntryDAO { }
+```
+
+A factory pattern selects the correct DAO, e.g.:
+
+```php
+FreshRSS_Factory::createEntryDao();
+```
+
+**Important**: in database, VARCHAR/TEXT fields are HTML-encoded, except `attributes` fields, which contain JSON, and which sub-strings are not HTML-encoded.
+
+## Main development commands
+
+> ℹ Recommended before committing
+
+```sh
+# Runs all tests: PHPUnit, PHPCS, PHPStan, typos
+make test-all
+
+# Auto-fix all trivial issues: whitespace, RTL CSS, translations
+make fix-all
+
+# See a list of commands:
+make help
+```
+
+CI/CD is defined in [`.github/workflows/tests.yml`](.github/workflows/tests.yml)
+
+A Dev Container is available under [`.devcontainer/`](.devcontainer/).
+
+## Docker
+
+> ℹ Check [Docker documentation](Docker/README.md).
+
+## CLI Tools
+
+There are scripts in `cli/` for admin tasks, such as:
+
+```sh
+./cli/list-users.php
+```
+
+> ℹ Check [CLI documentation](cli/README.md).
+
+When possible, it is best to run as Web server user:
+
+```sh
+sudo -u www-data cli/actualize-user.php --user alice
+```
+
+or at least re-apply the file permissions after CLI operations:
+
+```sh
+cli/access-permissions.sh
+```