DogStark / DogStark/Wordbloc

📚 README describes a stack that doesn't exist; 15 root-level docs; missing LICENSE file

Open
#7 2 comments 0 reactions 0 assignees View on GitHub
documentation good first issue GrantFox OSS Maybe Rewarded Official Campaign | FWC26
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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.