📚 README describes a stack that doesn't exist; 15 root-level docs; missing LICENSE file
- Dominant language
- JavaScript
- Stars
- 1
- Forks
- 12
- Avg merge
- 2d 7h
- Merged PRs (30d)
- 4
Description
## Summary
The documentation describes a project that doesn't exist, and what does exist is scattered across **15 markdown files at the repo root**. A new contributor following the README will fail at step 1. Separately, the README badge claims MIT license but there is **no LICENSE file** — which means the project is legally *not* open source yet and contributors have no license covering their submissions.
## Problems
**1. README describes a fictional stack.** The README says the frontend is "Next.js 14 with React 18, Tailwind, NextAuth.js, Zustand" and the backend uses "PostgreSQL with Prisma, Redis, Privy custodial wallets". In reality:
- There is no `frontend/` directory; the app is vanilla HTML/CSS/JS (`index.html`, `game.html`, `game.js`, `styles.css`)
- The Quick Start says `cd backend && npm install && npm run dev` — `backend/server.js` crashes on startup (missing route modules), and the real entry point is root `server.js` via `npm start`
- It links to `docs/DEPLOYMENT.md`, `docs/API.md`, `docs/WEB3_INTEGRATION.md`, `docs/GRANT_COMPLIANCE.md` — only `docs/DEPLOYMENT.md` exists
- It cites unverifiable claims as fact ("Ethereum Foundation grant recipient", "Average 23% improvement", "Audited smart contracts") — these should be removed or clearly marked as goals
- It points to a different repo entirely (`github.com/spellbloc/platform`) and even a different project name (SpellBloc vs. Wordbloc)
**2. 15 overlapping root-level docs**: `README.md`, `README-WORLDCLASS.md`, `SETUP.md`, `DEPLOYMENT_DEMO.md`, `DEPLOYMENT_INSTRUCTIONS.md`, `FINAL_DEPLOYMENT_STATUS.md`, `DOMAIN_SETUP.md`, `PROJECT_STRUCTURE.md`, `SPELLBLOC_PRD.md`, `WEB3_ARCHITECTURE.md`, `WEB3_FEATURES.md`, `CELO_PROOF_OF_SHIP.md`, `AI_AGENT_DOCUMENTATION.md`, `CURRICULUM.md`, `LANGUAGE-TESTING.md`. Several contradict each other about how to deploy and run the app.
**3. No LICENSE file** despite the MIT badge and `"license": "MIT"` in `package.json`.
## Proposed fix
- [ ] Add a `LICENSE` file (MIT, matching package.json) — this is a 2-minute good-first-issue-sized task on its own
- [ ] Rewrite `README.md` to describe the *actual* app: vanilla JS PWA + Express server + Hardhat/Celo contracts; accurate Quick Start (`npm install && npm start`); remove or clearly label aspirational content
- [ ] Move the remaining useful docs into `docs/` (architecture, deployment, curriculum, PRD) and delete stale status files (`FINAL_DEPLOYMENT_STATUS.md`, `DEPLOYMENT_DEMO.md`, `README-WORLDCLASS.md`)
- [ ] Fix broken links and repo references
## Acceptance criteria
- A newcomer can clone, install, and run the game following only README.md
- Every link in README.md resolves
- ≤ 2 markdown files remain at the repo root (README + CONTRIBUTING)
- `LICENSE` exists and matches the declared license
Contributor guide
No contributing guide indexed for this repository
Research direction
Start with README.md, package.json, root server.js, and docs/DEPLOYMENT.md; run npm install && npm start to verify the documented entry point, then inventory the named root markdown files and README links. Done means README describes the actual app, its links resolve, no more than README.md and CONTRIBUTING remain at the root, and LICENSE matches the declared MIT license.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- express, javascript
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 45/100