docs: make the repo discoverable and contributor-ready

guillermoscript · claude · guillermoscript · commit be37e8fc79ec · 2026-07-25T18:50:10.000+02:00
Rewrite the README opener with badges, a live-instance link and a feature table, and add the community health files GitHub looks for: CONTRIBUTING (setup, branch/commit conventions, the five things reviewers actually check), SECURITY (private reporting, in/out of scope for a multi-tenant app), CODE_OF_CONDUCT, issue forms and a PR template. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01APEKg6qy9TcLausNecrg89
diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml
@@ -0,0 +1,47 @@
+name: Bug report
+description: Something is broken
+labels: [bug]
+body:
+  - type: textarea
+    id: what
+    attributes:
+      label: What happened
+      description: What you expected, and what happened instead.
+    validations:
+      required: true
+  - type: textarea
+    id: steps
+    attributes:
+      label: Steps to reproduce
+      placeholder: |
+        1. Log in as owner@e2etest.com on lvh.me:3000
+        2. Go to /dashboard/admin/...
+        3. ...
+    validations:
+      required: true
+  - type: dropdown
+    id: role
+    attributes:
+      label: Role you were signed in as
+      options: [student, teacher, admin, super admin, not signed in]
+    validations:
+      required: true
+  - type: input
+    id: tenant
+    attributes:
+      label: Tenant / URL
+      description: Which subdomain, and the page URL.
+      placeholder: code-academy.lvh.me:3000/en/dashboard/student
+  - type: dropdown
+    id: env
+    attributes:
+      label: Environment
+      options: [local dev, self-hosted, hosted instance]
+    validations:
+      required: true
+  - type: textarea
+    id: logs
+    attributes:
+      label: Console / server errors
+      description: Browser console, terminal output, or Supabase logs. Screenshots welcome.
+      render: shell
diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml
@@ -0,0 +1,8 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Question or idea
+    url: https://github.com/guillermoscript/lms-front/discussions
+    about: Setup help, architecture questions, and open-ended ideas go in Discussions.
+  - name: Report a vulnerability
+    url: https://github.com/guillermoscript/lms-front/security/advisories/new
+    about: Please report security issues privately, not as a public issue.
diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml
@@ -0,0 +1,38 @@
+name: Feature request
+description: Propose something new
+labels: [enhancement]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: What can't you do today? Who is blocked — a student, a teacher, a school admin, a self-hoster?
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed solution
+    validations:
+      required: true
+  - type: dropdown
+    id: area
+    attributes:
+      label: Area
+      options:
+        - courses / lessons
+        - exams / grading
+        - payments / billing
+        - multi-tenancy / onboarding
+        - gamification
+        - AI tutor / MCP server
+        - community spaces
+        - i18n / translations
+        - admin dashboard
+        - other
+  - type: checkboxes
+    id: help
+    attributes:
+      label: Contribution
+      options:
+        - label: I'd be willing to work on this
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
@@ -0,0 +1,30 @@
+## What
+
+<!-- What changed, in one or two sentences. -->
+
+Closes #
+
+## Why
+
+<!-- The problem this solves. Link the issue if there is one. -->
+
+## How to QA
+
+<!-- Steps a reviewer can follow on a fresh `npm run db:reset`. Include the account and subdomain. -->
+
+1.
+2.
+
+## Screenshots / GIF
+
+<!-- Required for anything a user can see or click. Before + after if it's a change. -->
+
+## Checklist
+
+- [ ] `npm run typecheck` and `npm run test:unit` pass
+- [ ] `npm run build` passes
+- [ ] Every new tenant-scoped query filters by `tenant_id` (or the table genuinely has no such column)
+- [ ] Tested with every relevant role (student / teacher / admin)
+- [ ] Loading and error states handled
+- [ ] New UI strings added to both `messages/en.json` and `messages/es.json`
+- [ ] Migration (if any) applies cleanly on `npm run db:reset`, has RLS policies, and `lib/database.types.ts` was regenerated
diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
@@ -0,0 +1,36 @@
+# Code of Conduct
+
+## Our pledge
+
+We want this project to be a place where anyone can ask a question, report a bug, or send a patch
+without fear of being belittled for it. Everyone who takes part — contributors, maintainers, and
+people just passing through an issue thread — is expected to help keep it that way.
+
+## Expected behavior
+
+- Be respectful and assume good faith. People come from different backgrounds and skill levels, and
+  the project spans two languages (English and Spanish) — both are welcome in issues and PRs.
+- Give and take feedback on the work, not the person.
+- Keep discussion focused on the project.
+
+## Unacceptable behavior
+
+- Harassment, insults, or personal attacks
+- Discriminatory language or imagery, sexual attention or advances
+- Publishing someone's private information without permission
+- Sustained disruption of discussions
+
+## Enforcement
+
+Maintainers may remove comments, close issues or PRs, and block accounts that violate this policy.
+
+Report problems to **arepayquezo@gmail.com**. Reports stay confidential; the reporter's identity is
+not shared with the person reported. Maintainers who do not uphold this policy in good faith may
+face consequences decided by the other maintainers.
+
+## Scope
+
+This applies in all project spaces — issues, pull requests, discussions, commit messages — and when
+representing the project in public.
+
+Adapted from the [Contributor Covenant](https://www.contributor-covenant.org/), version 2.1.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,70 @@
+# Contributing
+
+Thanks for considering a contribution. This is a real, running product, so the bar is "it works for every tenant and every role" — but the setup is a single `npm install` + `supabase start` away, and small fixes are very welcome.
+
+## Ways to help
+
+- **Good first issues** — [`good first issue`](https://github.com/guillermoscript/lms-front/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) and [`help wanted`](https://github.com/guillermoscript/lms-front/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22)
+- **Bugs** — open an issue with the tenant, role, and steps to reproduce
+- **Translations** — `messages/en.json` and `messages/es.json`; new locales welcome
+- **Docs** — anything in `docs/` that was wrong or missing when you set up
+- **Payment providers** — the provider contract lives in `lib/payments/` (see `docs/PROVIDER_AGNOSTIC_PAYMENTS_SPIKE.md`)
+
+## Setup
+
+Full walkthrough: [`docs/GETTING_STARTED.md`](docs/GETTING_STARTED.md). The short version:
+
+```bash
+npm install
+cp .env.example .env.local        # fill in the four local Supabase vars
+supabase start && npm run db:reset
+npm run dev                        # open http://lvh.me:3000 — NOT localhost
+```
+
+Seeded logins (all `password123`, local dev only) are listed in the [README](README.md#quick-start).
+
+## Workflow
+
+1. Branch from `master`: `<type>/<slug>-<issueNumber>` — e.g. `fix/payout-rounding-516`
+2. Commit with [Conventional Commits](https://www.conventionalcommits.org/): `fix(payments): ...`, `feat(admin): ...`, `docs: ...`
+3. Open a PR against `master`, filling in the template (what changed, why, how to QA)
+4. CI runs typecheck + unit tests on every PR; lint is surfaced but non-blocking (there is a large pre-existing baseline — just keep the files *you* touch clean)
+
+Before pushing:
+
+```bash
+npm run typecheck
+npm run test:unit
+npm run build          # catches what typecheck alone misses
+npx playwright test    # if you touched auth, tenancy, or payments
+```
+
+## What reviewers look for
+
+This is a **multi-tenant** app with **RLS as the security boundary**. Most review comments come from these five:
+
+- **Every tenant-scoped query filters by `tenant_id`** — even though RLS also enforces it. Exceptions: `profiles`, `gamification_levels`, `lesson_completions`, and the exam child tables, which have no `tenant_id` column at all.
+- **Reads go straight from components via RLS.** Server actions are for multi-step mutations, service-role work, and external APIs (Stripe, email) — not for ordinary reads.
+- **`createAdminClient()` bypasses RLS.** If you use it, validate tenant ownership by hand before any write.
+- **Tested with every relevant role** — student, teacher, admin — and on both seeded tenants.
+- **Loading and error states handled**, and any new UI string added to both `en.json` and `es.json`.
+
+Architecture, schema invariants, and the list of known pitfalls live in [`CLAUDE.md`](CLAUDE.md) — it is written for AI agents but it is the fastest orientation for humans too. Schema details: [`docs/DATABASE_SCHEMA.md`](docs/DATABASE_SCHEMA.md).
+
+## Database changes
+
+```bash
+supabase migration new <name>   # never edit an applied migration
+npm run db:reset                # verify it applies from scratch, with the seed
+npm run db:types                # regenerate lib/database.types.ts, commit the diff
+```
+
+New tenant-scoped table? It needs `tenant_id`, RLS enabled, and policies — a table without policies is invisible to the app and a table without `tenant_id` leaks across schools.
+
+## Security
+
+Do not open a public issue for a vulnerability. See [SECURITY.md](SECURITY.md).
+
+## Questions
+
+Open a [Discussion](https://github.com/guillermoscript/lms-front/discussions) or comment on the issue you want to pick up.
diff --git a/README.md b/README.md
@@ -1,8 +1,31 @@
 # LMS Platform
 
-A multi-tenant SaaS Learning Management System. Schools run on subdomains (`school.platform.com`). Educators create and sell courses; students enroll and learn.
+**Open-source, multi-tenant LMS for creators and schools.** Every school gets its own subdomain (`school.platform.com`), its own branding, and its own students. Educators build courses and sell them; students enroll, learn, take exams, and earn verifiable certificates.
 
-**Stack:** Next.js 16 · React 19 · TypeScript · Supabase · Shadcn UI · Tailwind CSS v4 · Stripe Connect · next-intl (en/es)
+[![CI](https://github.com/guillermoscript/lms-front/actions/workflows/ci.yml/badge.svg)](https://github.com/guillermoscript/lms-front/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Next.js 16](https://img.shields.io/badge/Next.js-16-black?logo=next.js)](https://nextjs.org)
+[![Supabase](https://img.shields.io/badge/Supabase-Postgres%20%2B%20RLS-3ECF8E?logo=supabase&logoColor=white)](https://supabase.com)
+[![PRs welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)
+
+**Live instance:** [preciopana.com](https://preciopana.com) · **Setup:** [`docs/GETTING_STARTED.md`](docs/GETTING_STARTED.md) · **Contribute:** [`CONTRIBUTING.md`](CONTRIBUTING.md)
+
+**Stack:** Next.js 16 · React 19 · TypeScript · Supabase (Postgres + Auth + RLS) · Shadcn UI (base-mira) · Tailwind CSS v4 · Stripe Connect · next-intl (en/es)
+
+## What's in it
+
+| | |
+|--|--|
+| **Multi-tenancy** | Subdomain-per-school, tenant theming, per-tenant roles — one deployment, many schools. Isolation is enforced in Postgres with Row Level Security, not in application code. |
+| **Courses** | Block-editor lessons with rich MDX components, exercises, checkpoints, exams with AI-assisted grading, progress tracking, FSRS spaced repetition. |
+| **Payments** | Stripe Connect (platform fee + revenue split), PayPal, Lemon Squeezy, Solana, Binance, and manual/offline receipts for markets where cards fail. Provider-agnostic contract — adding one is a single module. |
+| **Monetization** | One-off products, subscriptions, plan-based feature gating, payouts, invoices, revenue dashboard. Separate platform billing for schools paying you. |
+| **AI tutor** | An MCP server (`mcp-server/`) exposing the LMS as tools + interactive widgets: drill practice, weak-topic remediation, exam readiness, ask-a-teacher. Works from any MCP client, auth'd via Supabase OAuth 2.1 with RLS intact. |
+| **Engagement** | XP, levels, streaks, achievements, challenges, weekly leagues, coin store, certificates with public verification, community spaces with polls and moderation. |
+| **Creator tools** | AI landing-page generation, drag-and-drop page builder, guided onboarding, guided tours. |
+| **i18n** | Full English + Spanish across the app, built for LATAM and English-speaking markets. |
+
+Self-host it, fork it for your own school, or use it as a reference for multi-tenant Supabase + Next.js patterns. MIT licensed.
 
 ## Prerequisites
 
@@ -15,7 +38,7 @@ A multi-tenant SaaS Learning Management System. Schools run on subdomains (`scho
 
 1. **Clone and install**
    ```bash
-   git clone <repo-url>
+   git clone https://github.com/guillermoscript/lms-front.git
    cd lms-front
    npm install
    ```
@@ -85,3 +108,20 @@ A multi-tenant SaaS Learning Management System. Schools run on subdomains (`scho
 - [`docs/DATABASE_SCHEMA.md`](docs/DATABASE_SCHEMA.md) — complete DB schema
 - [`docs/AUTH.md`](docs/AUTH.md) — authentication flows
 - [`docs/MONETIZATION.md`](docs/MONETIZATION.md) — billing and payments
+- [`docs/MCP_SETUP.md`](docs/MCP_SETUP.md) — the MCP server and AI tutor tooling
+
+More in [`docs/`](docs/) — deployment, i18n, gamification, community spaces, the landing-page builder.
+
+## Contributing
+
+Contributions are welcome — bug reports, translations, docs fixes, new payment providers, features.
+
+- Read [`CONTRIBUTING.md`](CONTRIBUTING.md) for the workflow and what reviewers look for
+- Browse [`good first issue`](https://github.com/guillermoscript/lms-front/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) and [`help wanted`](https://github.com/guillermoscript/lms-front/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22)
+- Questions and ideas: [Discussions](https://github.com/guillermoscript/lms-front/discussions)
+- Found a vulnerability? [`SECURITY.md`](SECURITY.md) — please report it privately
+- By participating you agree to the [Code of Conduct](CODE_OF_CONDUCT.md)
+
+## License
+
+[MIT](LICENSE) — free to self-host, fork, and build a business on.
diff --git a/SECURITY.md b/SECURITY.md
@@ -0,0 +1,38 @@
+# Security Policy
+
+## Reporting a vulnerability
+
+**Please do not open a public issue.** Report privately via
+[GitHub Security Advisories](https://github.com/guillermoscript/lms-front/security/advisories/new),
+or email **arepayquezo@gmail.com** with `[security]` in the subject.
+
+Include: what you found, how to reproduce it, and the impact you think it has. A proof of concept
+against your own local instance is ideal.
+
+Expect an acknowledgement within a few days. Please give a reasonable window for a fix before
+disclosing publicly.
+
+## In scope
+
+This is a multi-tenant platform, so anything that crosses a boundary is high priority:
+
+- **Cross-tenant data access** — reading or writing another school's data
+- **Privilege escalation** — student → teacher/admin, tenant admin → super admin
+- **RLS bypass** — reaching rows a policy should have blocked
+- **Payment integrity** — gaining course access without a successful transaction or valid entitlement, tampering with revenue splits or payouts
+- **Auth flaws** — session fixation, JWT claim forgery, broken password reset
+- **Exposure of secrets** — service-role keys or provider credentials leaking to the browser bundle
+
+## Out of scope
+
+- The seeded local-dev accounts and their `password123` passwords (`supabase/seed.sql`) — local only, never deployed
+- The hardcoded Sentry DSN in `sentry.server.config.ts` — public by design
+- `NEXT_PUBLIC_*` values being visible in the client bundle — that is what the prefix means
+- Findings that require a self-hosted operator to misconfigure their own instance
+- Automated scanner output with no demonstrated impact, missing security headers with no exploit path, DoS by volume
+
+## Self-hosting notes
+
+If you run your own instance: keep `SUPABASE_SERVICE_ROLE_KEY` server-side only, never put a
+production OpenAI key in `NEXT_PUBLIC_OPENAI_API_KEY` (it ships to the browser), reseed nothing
+from `supabase/seed.sql` in production, and verify RLS is enabled on every table you add.
