[longobucco]

What changed and why

GET /api/courses was offset/limit with no ORDER BY at all, so result order wasn't even
guaranteed. This resolves issue #73 (scoped to the course list only — the issue's other two
surfaces, document lists and study-session lists, are explicit follow-up work) by switching to
cursor (keyset) pagination on (created_at, id), newest first.

Cursor rather than offset specifically because the issue calls it out: an offset page can skip or
repeat rows when the underlying set changes between requests; a keyset cursor can't, since it's
always relative to a specific row rather than a position.

Backend:

• Course had no created_at column — migration 0009_course_created_at adds it (backfilled to
  a fixed sentinel for existing rows, since their real creation order was never recorded) plus a
  composite index, and the SQLAlchemy model declares the matching index so alembic upgrade head
  and Base.metadata.create_all() stay in sync.
• New reusable CursorPage envelope (app/schemas/pagination.py) — {items, next_cursor, has_more}, opaque base64 cursor — meant to be reused by the document/session-list follow-ups
  mentioned in the issue.
• Response shape change on GET /api/courses: breaking, but the only consumer is this repo's own
  frontend, updated in the same branch.

Frontend:

• getCourses moves from (skip, limit) → Course[] to (cursor, limit) → CoursePage.
• The course grid loads 20 at a time and appends further pages via a "Load more" control
  (preserves scroll position naturally, since it only adds content).
• Removed the MVP_COURSES_LIMIT constant and its comment — the debt it documented is resolved.

docs/specifications.md updated under requirement 1 to describe the new behavior, per AGENTS.md.

Issue

Refs #73. Not closing it — the issue also covers document lists and study-session lists, which
this PR deliberately leaves open as separate follow-up work (same CursorPage convention applies
directly). The trigger the issue names (50+ courses/user, or a measured page-load threshold) had
not been hit; built proactively ahead of it per discussion with the repo owner.

How it was verified

• Backend: cd services/ai && uv run --no-sync pytest — 1100 passed, 85.38% coverage (ratchet
  76%). uv run --no-sync mypy app — clean, 88 source files.
• Frontend: cd apps/web && npm run type-check && npm run lint && npm test — clean, 32 suites /
  299 tests passed.
• New integration tests (test_courses_pagination_api.py) specifically cover: newest-first
  ordering, full traversal without duplicates/gaps across pages, the exact-limit boundary
  (has_more must be False, not a false-positive extra page), id tie-breaking when
  created_at is identical (what every backfilled row hits), inactive courses staying excluded
  across pages, six malformed-cursor shapes that must 422 rather than 500, and — the issue's own
  stated reason for preferring cursor over offset — a course inserted between two page requests
  not shifting or duplicating rows the first page already returned.
• Independent review pass (opus) on the full branch diff before this PR: no Critical findings;
  all Important findings (crafted cursors reaching the generic 500 handler instead of a 422;
  course-list state getting wiped by next-auth's session refetch-on-focus and losing "Load more"
  progress; a failed "load more" hiding the entire grid instead of retrying inline) fixed in a
  follow-up commit, along with the missing boundary/tie-break/malformed-cursor tests it flagged
  and some cheap dead-code cleanup (unused course_service.list_courses /
  course_repo.get_all_courses, an unused frontend fetchCourses helper).

Things reviewers should watch for

• The course-count/documents header in apps/web/src/app/courses/page.tsx now describes only the
  loaded courses, not the true total, once "Load more" is in play (e.g. "20 courses" when 60
  exist). Left as-is since the envelope has no total count today — a total field is a natural
  follow-up if this needs fixing, flagged rather than silently shipped.
• Course.created_at follows this codebase's existing pattern (default=func.now() on a
  String column, explicit ISO-8601 override at the one call site that creates rows) — same
  latent risk as Quiz.created_at already has if a future code path ever constructs a Course
  directly instead of through course_repo.create_course. Not introduced by this PR, not fixed
  here, consistent with the existing convention.
• No per-user ownership filter exists on this list endpoint today (pre-existing, unrelated to this
  PR) — every authenticated user sees every active course, same as on master.

[lucaosti]

Thanks Luca, this is a really clean piece of work. The tie-break tests and the "insert between pages" test are exactly what I wanted to see, and I checked them myself: paging over identical sentinel created_at values with limit 1 and 2, and on a database migrated from 0008, gives no skips and no duplicates, and EXPLAIN QUERY PLAN uses the new index.

Before we merge:

• A deeply nested JSON cursor (for example base64 of a thousand [ characters) raises RecursionError in decode_cursor, so it still reaches the 500 handler. Could you add a max_length on the cursor query parameter and catch that case too? Validating created_at with datetime.fromisoformat would also reject odd values such as embedded NUL bytes, which Postgres would refuse.
• scripts/seed_demo.sh:98 still reads the list as a plain array (jq '.[] | ...'). It needs .items[] now.
• Migration numbering: #312 also adds revision 0009 on top of 0008, and with both merged alembic sees two heads. Whichever lands second needs to become 0010 with down_revision = "0009".

Optional: setting the model default to the same UTC ISO lambda as create_course would close the mixed-format risk you already flagged, and apps/web/README.md:131 still shows the old array response.