From 5c1d745ed3f3d6f3afc4b60b6ff24137e9e24898 Mon Sep 17 00:00:00 2001
From: ARIA <no-reply@zephyre.one>
Date: Tue, 28 Jul 2026 13:00:29 +0200
Subject: [PATCH] Add AGENTS.md for future agent sessions

---
 AGENTS.md | 46 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 46 insertions(+)
 create mode 100644 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..86e23dd
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,46 @@
+# AGENTS.md
+
+## Project Structure
+
+- `src/` — All application code (no subpackages)
+  - `cli.py` — Entry point, argparse CLI with subcommands: add, remove, update, list, check, serve, daemon
+  - `github.py` — GitHub REST API client (httpx), rate-limit aware, exponential backoff
+  - `db.py` — SQLite layer with 0600 file permissions, upsert with UNIQUE(repo_id, tag_name)
+  - `rss.py` — RSS 2.0 generation via xml.etree, markdown→plain text via markdown+bleach, 300-char truncation, 50-item cap
+  - `server.py` — ThreadingHTTPServer with /feed.xml, /, /health endpoints
+  - `config.py` — Centralized config (db_path, gh_token, defaults)
+- `tests/` — pytest test suite, 72 tests total
+
+## Commands
+
+```bash
+# Install for development
+pip install -e ".[test]"
+
+# Run all tests (use timeout to avoid server test hangs)
+timeout 30 python3 -m pytest tests/ -q
+
+# Run single test file
+python3 -m pytest tests/test_db.py -v
+
+# Run single test
+python3 -m pytest tests/test_db.py::TestCreateTables::test_tables_exist -v
+```
+
+## Testing Quirks
+
+- `respx` is used to mock GitHub API calls in `test_github.py`
+- Integration tests in `test_integration.py` use `urllib` for localhost requests to avoid respx interception
+- Server tests spawn ThreadingHTTPServer — use `timeout 30` for full test suite to avoid hangs
+
+## Key Gotchas
+
+- `--base-url` flag on `serve` command auto-appends port from `--port` (user only specifies hostname)
+- Tag date resolution uses commit SHA from tags API + `commits/{sha}` endpoint (works without auth for public repos)
+- Database uses `ON DELETE CASCADE` — removing a repo deletes its entries
+- `src` package requires `[tool.setuptools.packages.find]` in pyproject.toml for proper installation
+
+## Environment
+
+- `GH_TOKEN` — GitHub token for API access (validate on startup if provided)
+- `GDB_REL_DB` — Override database path (default: `~/.local/share/ghrel/ghrel.db`)