{"id":51529458,"url":"https://github.com/bh2smith/read-quest","last_synced_at":"2026-07-09T01:01:43.363Z","repository":{"id":363796967,"uuid":"1264242130","full_name":"bh2smith/read-quest","owner":"bh2smith","description":null,"archived":false,"fork":false,"pushed_at":"2026-06-10T11:41:00.000Z","size":83,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-10T12:20:28.838Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bh2smith.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-09T17:43:20.000Z","updated_at":"2026-06-10T11:41:08.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/bh2smith/read-quest","commit_stats":null,"previous_names":["bh2smith/read-quest"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/bh2smith/read-quest","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bh2smith%2Fread-quest","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bh2smith%2Fread-quest/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bh2smith%2Fread-quest/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bh2smith%2Fread-quest/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bh2smith","download_url":"https://codeload.github.com/bh2smith/read-quest/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bh2smith%2Fread-quest/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35282899,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-08T02:00:06.796Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-07-09T01:01:42.162Z","updated_at":"2026-07-09T01:01:43.317Z","avatar_url":"https://github.com/bh2smith.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ReadQuest\n\nA free vocabulary / language-learning (ESL) game for learners 16+ and study\ncircles: fill in the missing word for a pictured sentence, earn XP, and unlock\non-chain achievement badges. Built as a Circles mini-app, with a Circles\n\"study circle\" (group) where classmates trust each other.\n(See [plan.md](./plan.md) for the full product plan and roadmap.)\n\n\u003e **Direction note:** ReadQuest began as an early-reading game for children and\n\u003e has pivoted to **16+ ESL / language learning**. Raising the age floor clears\n\u003e COPPA/GDPR-K and lets learners self-custody their own Circles accounts, which\n\u003e makes the study-circle (group + trust graph) model honest rather than a\n\u003e workaround. Content and copy now target older learners; the on-chain\n\u003e classroom layer (groups, self-onboarding, ERC-1155 badges) is the next phase.\n\n## Status\n\nThe original 6-day plan (learning loop → polish) plus the **Circles\nstudy-circle** rework (Phases A–D) are implemented.\n\n**Learning loop (Days 1–2)**\n- 5 lessons × 6 exercises (30 prebuilt, static JSON-style data)\n- Multiple-choice answers with instant feedback\n- XP (+10/correct, +50/lesson, +25 perfect bonus) and badge unlocks\n- Progress persisted to `localStorage` (with a reset button)\n\n**Circles connection (Day 3)**\n- Parent/teacher/sponsor \"For grown-ups\" mode\n- Wallet connect via `@aboutcircles/miniapp-sdk` (`requestCreateAccount`,\n  `onWalletChange` as the source of truth). Outside the Circles host it falls\n  back to a clearly-labeled **demo wallet** so the flow is viewable locally.\n- Invite/referral links (`?ref=\u003caddress\u003e`), copy-to-clipboard, and inbound\n  referral attribution (URL or host `?data=` channel)\n- Analytics events stubbed in `src/lib/analytics.ts` (currently `console.debug`)\n\n**Rewards (Day 4)**\n- Badge mint + CRC reward claim per completed lesson, from the grown-up wallet\n- Claim limits: one badge mint and one CRC claim per lesson, per wallet\n- Cooldown between CRC claims (anti-farming); persisted per wallet\n- Mock transaction paths today, with documented seams for a real ERC-1155\n  mint and Circles CRC transfer via the SDK's `sendTransactions`\n  (see `features/rewards/badgeMint.ts` and `crcReward.ts`)\n\n**Polish (Day 5)**\n- Mobile-first layout with safe-area padding and no iOS tap-highlight/zoom\n- Friendly animations: per-question fade, correct-answer pop + floating \"+10 XP\",\n  wrong-answer shake, animated XP counter, and a confetti burst on completion\n- `ErrorBoundary` so a render crash shows a friendly reload screen, not a blank one\n- Respects `prefers-reduced-motion`\n\n**Circles study circle (Phases A–D)**\n- **A — group:** an instructor creates a class as a real Circles **group** via\n  `sdk.register.asGroup` (`@aboutcircles/sdk`), or a simulated group in demo mode.\n- **B — onboarding + trust:** per-class invite links (`?class=…`); a learner\n  opens it in the Circles host, connects their **own** passkey account, and\n  trusts the group so membership is on-chain. The app never stores learner keys.\n  The instructor trusts members into the group (`avatar.trust.add`).\n- **C — on-chain badges:** soulbound ERC-1155 (`contracts/Badge1155.sol`) — one\n  token id per lesson. Completing a lesson mints to the learner's own wallet via\n  the host's `sendTransactions` when `VITE_BADGE_1155_ADDRESS` is set; mock\n  otherwise. Deploy tooling in `contracts/`.\n- **D — cohort dashboard:** roster with per-member trust status, invite sharing,\n  and a live \"Refresh from chain\" read via `sdk.groups.getMembers`.\n\nThe Circles SDK + viem are **code-split** into a lazy chunk, so a learner's\nfirst load stays light (~55 kB gzip); the SDK (~171 kB gzip) loads only when\nentering instructor/join screens.\n\n\u003e **Verification status:** demo mode is fully runnable and verified locally\n\u003e (typecheck + build + dev). The **live on-chain paths** (group registration,\n\u003e trust, badge mint) are correctly typed against the real SDK/contract but have\n\u003e **not been executed against Gnosis mainnet** from here — they need a funded\n\u003e wallet, the Circles host, and a deployed `Badge1155`. Treat them as\n\u003e implemented-but-unverified until run in-host.\n\n## Run\n\n```bash\nbun install\nbun run dev      # http://localhost:5173\nbun run build    # type-check + production build to dist/\n```\n\n## Stack\n\nVite + React + TypeScript, Tailwind CSS v4, Zustand for state,\n`@aboutcircles/miniapp-sdk` + `@aboutcircles/sdk` + viem for Circles/Gnosis.\n\n## Layout\n\n```\nsrc/\n  app/App.tsx                       view router (home → exercise → complete)\n  components/                       AnswerChoice, BadgeCard, LessonCard, ProgressBar,\n                                    WalletConnectButton, Confetti, ErrorBoundary\n  data/                             exercises, lessons, badges (static)\n  features/learning/                ExerciseScreen, LessonCompleteScreen, useLessonProgress\n  features/circles/                 wallet store (miniapp-sdk) + circlesClient (full SDK)\n  features/classroom/               study-circle groups, invites, join, trust, roster\n  features/referrals/               invite link build/copy + referral attribution\n  features/rewards/                 badge mint (mock + on-chain ERC-1155), CRC claim, limits\n  features/parent/                  ParentScreen (instructor mode: wallet, circle, rewards)\n  lib/                              types, storage (localStorage), analytics\ncontracts/                          Badge1155.sol (soulbound ERC-1155) + deploy script\n  styles/globals.css                Tailwind entry + animations\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbh2smith%2Fread-quest","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbh2smith%2Fread-quest","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbh2smith%2Fread-quest/lists"}