[R1] Browse — public catalogue discovery

[mrboxs]

[R1] Browse — public catalogue discovery

Roadmap: docs/roadmap.md — “R1 — Browse”
Prerequisite: #27 — R0 Catalogue data
Branch: feat/r1-browse
Release: R1 — Browse

Outcome

Let a visitor discover the catalogue without signing in: browse a paginated grid of published projects and open a public project-detail page.

In scope

1. Public catalogue API

• Define listProjects({ page, limit }) and getProjectBySlug({ slug }) contracts before their router handlers.
• Implement public router procedures for the project list and project detail.
• Filter by status = 'published' in each public query, not in the UI.
• Return the same generic 404 for a missing slug and for draft, rejected, or removed projects.
• Load GitHub stars and forks without N+1 queries.
• Validate pagination inputs and use a sensible, bounded page size.

2. Browse and detail experience

• Replace the static homepage content with a paginated project grid and reusable project card.
• Provide loading, empty, and pagination states that remain usable on narrow viewports.
• Add /projects/$slug with project identity, repository and optional website links, Markdown content, and repository stats.
• Make broken or absent optional website URLs non-fatal to the detail page.

3. Tests and verification

• Add API tests for published-only visibility, pagination, and missing/non-public detail lookups.
• Add route/UI coverage for navigation from the browse grid to a project detail page.
• Verify direct detail requests for draft, rejected, and removed do not disclose project existence.
• Run vp install, vp check, vp run -r test, and vp run -r build before merge.

Definition of done

• A visitor sees only published projects in a paginated browse grid.
• A visitor can open a public project detail page and return to browsing.
• Public API queries enforce visibility server-side.
• Direct detail requests for non-public projects behave exactly like a missing project.
• Empty states and broken optional website URLs do not crash the page.
• Tests cover public visibility, pagination, and missing/non-public detail behaviour.

Explicitly out of scope

• Search, filters, categories, sort controls, and URL search state — R2.
• Sign-in, session-aware UI, and protected routes — R3.
• Submissions, GitHub metadata refreshes, ownership, moderation, and admin tools — R4–R5.
• Home-feed sections, featured projects, tags/topics, and personalised recommendations.

Implementation notes

• Follow the API and authorization conventions in docs/roadmap.md: public list/detail procedures must apply status = 'published' on the server.
• Keep list and detail queries deliberate about joins so repository statistics are loaded efficiently.
• Do not expose different errors, response shapes, or timing-sensitive detail behaviour for non-public projects.
• Keep this release focused on browsing; do not pre-build R2 filter/search infrastructure.

Suggested PR checklist

• Branch is feat/r1-browse.
• The R0 prerequisite ([R0] Catalogue data — durable project foundation #27) is merged and its migration/seed data are available locally.
• API contracts, router procedures, routes, and tests are included in the PR.
• vp check, vp run -r test, and vp run -r build results are included in the PR description.
• Known limitations are recorded before merge.