Lessons Learned
Knowledge base from resolved issues
Lessons
| Category | Lesson | Issue | Date | Actions |
|---|---|---|---|---|
| docs | Mermaid in GitHub markdown: a ';' inside sequenceDiagram message text is a statement separator and causes 'Expecting arrow, got NEWLINE' parse errors. Avoid ';' (and '#') in sequence message/note text. Validate diagrams for real before shipping: npm i mermaid jsdom, set globalThis.window/document from jsdom, mermaid.initialize({startOnLoad:false}), then await mermaid.parse(block) per fenced block — same engine GitHub uses, no browser needed. | #83 | 2026-07-25 | |
| ci | GitHub-hosted runners can't reach a local unix-socket Postgres; make the test harness build its DB URL (asyncpg / libpq / psycopg DSN) from env components defaulting to the socket, so one conftest runs both locally and against a TCP service container. Grep the whole tests/ tree for hardcoded DSNs — individual test files (test_db.py) had their own. | #82 | 2026-07-25 | |
| bug | auth.rodmena.app permission names use underscores; converting Futex colon-perms (hitl:x:y) to underscore form and back is LOSSY when a segment contains an underscore (manage_self/manage_others). Use an explicit reverse map from the known vocabulary, never a blind replace('_',':'). | - | 2026-07-23 | |
| infra | rodmena-mail-api admin cli.py lacks an if __name__=='__main__' guard; invoke via the installed console script venv/bin/mail-api-admin, not python mail_api/admin/cli.py. Template create uses fields html/text (not html_body/text_body); client_key is a short slug (regex ^[a-z0-9-]{3,32}$), not a UUID. | - | 2026-07-23 |