Four things, once. Three are already done — they were mine to run, not yours. Only step 2 needs you, and it needs about thirty seconds.
Run for you. All 114 sūrahs at their canonical Kūfan āyah count, and all 195 source files matching the sealed manifest. Re-run it any time; it must always print CORPUS VERIFIED.
cd "C:/Users/walee/Downloads/Quran Research/01-TOOLKIT" python verify_corpus.py
what you should see:
The readings are the one thing no rebuild can recreate, and they exist in one folder called Downloads. I cannot create the repository — this token can read but not create. Open github.com/new, name it quran-consensus-tafsir, tick Private, create. Then run these two lines.
cd "C:/Users/walee/Downloads/Quran Research" git remote add origin https://github.com/waleed-alvi/quran-consensus-tafsir.git git push -u origin master
what you should see:
Started for you in the background: no model needed, about 2–3 hours of pure machine time. It only writes into 05-READINGS/work/, so it cannot touch a reading. If it is interrupted, the same command resumes it — files already built are simply rewritten.
cd "C:/Users/walee/Downloads/Quran Research/01-TOOLKIT" for n in $(seq 3 114); do python surah_engine.py $n --data; done
The one judgement here that is genuinely yours. It is the controlled vocabulary all nine windows obey — 05-READINGS/GLOSSARY.md. If you disagree with a rendering, change it now: changing it later means reconciling every sūrah already written.
Set the model first — a prompt cannot do this. Then paste that window's prompt. Everything after that is the skill.
/model claude-opus-5
Inside the window each sūrah is the same five steps, and the window does them for you:
| # | Step | Who |
|---|---|---|
| 1 | --data gathers the evidence | machine |
| 2 | the agreed readings — one per āyah, similarities only | judgement |
| 3 | the ḥadīth picks — 3–5, a cross-tradition pair if one exists | judgement |
| 4 | --build — refuses on a missing reading or a non-verbatim quote | machine |
| 5 | --audit then publish | machine |
Your job in each window: set the model, paste the prompt, then confirm as it runs. Start the next window the moment one frees up — do not wait for a whole wave to finish.
Āl ʿImrān, al-Nisāʾ, al-Māʾida, al-Anʿām, al-Aʿrāf — finishing the class al-Baqarah opened.
You are WINDOW 1 of 9 building the Qur'an surah pages.
Your range is surahs 3-7 - 5 surahs, 867 ayat. No other window
touches them.
FIRST: read 05-READINGS/GLOSSARY.md and hold to it. It is the controlled
vocabulary for all nine windows and it is READ-ONLY for you. When you
settle a term it does not carry, append the row to
05-READINGS/glossary-in/W1.md instead - never edit the master.
Then work ONE SURAH AT A TIME, in order, all five steps of the skill, and
publish it before starting the next. A finished surah should be finished.
After each surah run:
python check_consistency.py <N>
and fix anything it flags HARD before you move on. Then append one line to
05-READINGS/progress/W1.md:
<surah> | <ayat> | AUDIT CLEAN | <artifact URL>
WHERE TO SPEND THOUGHT. The agreed readings and the hadith picks are the
entire job; everything else is three commands. Run --data, --build and
--audit without deliberation. Think hard about: what the commentaries
SHARE for this ayah, whether a term is already settled in the glossary,
and whether the hadith picks carry a cross-tradition convergence. If a
gate fails, fix the input - never the gate.
AT THE END report: surahs built, total ayat, every gate that fired and
why, and every term you put in glossary-in/W1.md.
Start now with /surah-purge 340–46 all open Ḥā Mīm and are a recognised family. They must never be split across windows.
You are WINDOW 6 of 9 building the Qur'an surah pages.
Your range is surahs 36-49 - 14 surahs, 925 ayat. No other window
touches them.
FIRST: read 05-READINGS/GLOSSARY.md and hold to it. It is the controlled
vocabulary for all nine windows and it is READ-ONLY for you. When you
settle a term it does not carry, append the row to
05-READINGS/glossary-in/W6.md instead - never edit the master.
Then work ONE SURAH AT A TIME, in order, all five steps of the skill, and
publish it before starting the next. A finished surah should be finished.
After each surah run:
python check_consistency.py <N>
and fix anything it flags HARD before you move on. Then append one line to
05-READINGS/progress/W6.md:
<surah> | <ayat> | AUDIT CLEAN | <artifact URL>
WHERE TO SPEND THOUGHT. The agreed readings and the hadith picks are the
entire job; everything else is three commands. Run --data, --build and
--audit without deliberation. Think hard about: what the commentaries
SHARE for this ayah, whether a term is already settled in the glossary,
and whether the hadith picks carry a cross-tradition convergence. If a
gate fails, fix the input - never the gate.
AT THE END report: surahs built, total ayat, every gate that fired and
why, and every term you put in glossary-in/W6.md.
Start now with /surah-purge 36al-Mulk to al-Balad — short, Makkan, eschatological. One register throughout.
You are WINDOW 8 of 9 building the Qur'an surah pages.
Your range is surahs 67-89 - 23 surahs, 782 ayat. No other window
touches them.
FIRST: read 05-READINGS/GLOSSARY.md and hold to it. It is the controlled
vocabulary for all nine windows and it is READ-ONLY for you. When you
settle a term it does not carry, append the row to
05-READINGS/glossary-in/W8.md instead - never edit the master.
Then work ONE SURAH AT A TIME, in order, all five steps of the skill, and
publish it before starting the next. A finished surah should be finished.
After each surah run:
python check_consistency.py <N>
and fix anything it flags HARD before you move on. Then append one line to
05-READINGS/progress/W8.md:
<surah> | <ayat> | AUDIT CLEAN | <artifact URL>
WHERE TO SPEND THOUGHT. The agreed readings and the hadith picks are the
entire job; everything else is three commands. Run --data, --build and
--audit without deliberation. Think hard about: what the commentaries
SHARE for this ayah, whether a term is already settled in the glossary,
and whether the hadith picks carry a cross-tradition convergence. If a
gate fails, fix the input - never the gate.
AT THE END report: surahs built, total ayat, every gate that fired and
why, and every term you put in glossary-in/W8.md.
Start now with /surah-purge 67al-Raʿd to Ṭā Hā — Ibrāhīm, the Cave, Maryam, and the fullest telling of Mūsā.
You are WINDOW 3 of 9 building the Qur'an surah pages.
Your range is surahs 13-20 - 8 surahs, 776 ayat. No other window
touches them.
FIRST: read 05-READINGS/GLOSSARY.md and hold to it. It is the controlled
vocabulary for all nine windows and it is READ-ONLY for you. When you
settle a term it does not carry, append the row to
05-READINGS/glossary-in/W3.md instead - never edit the master.
Then work ONE SURAH AT A TIME, in order, all five steps of the skill, and
publish it before starting the next. A finished surah should be finished.
After each surah run:
python check_consistency.py <N>
and fix anything it flags HARD before you move on. Then append one line to
05-READINGS/progress/W3.md:
<surah> | <ayat> | AUDIT CLEAN | <artifact URL>
WHERE TO SPEND THOUGHT. The agreed readings and the hadith picks are the
entire job; everything else is three commands. Run --data, --build and
--audit without deliberation. Think hard about: what the commentaries
SHARE for this ayah, whether a term is already settled in the glossary,
and whether the hadith picks carry a cross-tradition convergence. If a
gate fails, fix the input - never the gate.
AT THE END report: surahs built, total ayat, every gate that fired and
why, and every term you put in glossary-in/W3.md.
Start now with /surah-purge 13al-Anbiyāʾ to al-Shuʿarāʾ. Keeping them in one window is what keeps the retellings consistent with each other.
You are WINDOW 4 of 9 building the Qur'an surah pages.
Your range is surahs 21-26 - 6 surahs, 676 ayat. No other window
touches them.
FIRST: read 05-READINGS/GLOSSARY.md and hold to it. It is the controlled
vocabulary for all nine windows and it is READ-ONLY for you. When you
settle a term it does not carry, append the row to
05-READINGS/glossary-in/W4.md instead - never edit the master.
Then work ONE SURAH AT A TIME, in order, all five steps of the skill, and
publish it before starting the next. A finished surah should be finished.
After each surah run:
python check_consistency.py <N>
and fix anything it flags HARD before you move on. Then append one line to
05-READINGS/progress/W4.md:
<surah> | <ayat> | AUDIT CLEAN | <artifact URL>
WHERE TO SPEND THOUGHT. The agreed readings and the hadith picks are the
entire job; everything else is three commands. Run --data, --build and
--audit without deliberation. Think hard about: what the commentaries
SHARE for this ayah, whether a term is already settled in the glossary,
and whether the hadith picks carry a cross-tradition convergence. If a
gate fails, fix the input - never the gate.
AT THE END report: surahs built, total ayat, every gate that fired and
why, and every term you put in glossary-in/W4.md.
Start now with /surah-purge 21al-Anfāl and al-Tawba are read as one — no basmala divides them. Then Yūnus, Hūd, and Yūsuf, which is a single unbroken story.
You are WINDOW 2 of 9 building the Qur'an surah pages.
Your range is surahs 8-12 - 5 surahs, 547 ayat. No other window
touches them.
FIRST: read 05-READINGS/GLOSSARY.md and hold to it. It is the controlled
vocabulary for all nine windows and it is READ-ONLY for you. When you
settle a term it does not carry, append the row to
05-READINGS/glossary-in/W2.md instead - never edit the master.
Then work ONE SURAH AT A TIME, in order, all five steps of the skill, and
publish it before starting the next. A finished surah should be finished.
After each surah run:
python check_consistency.py <N>
and fix anything it flags HARD before you move on. Then append one line to
05-READINGS/progress/W2.md:
<surah> | <ayat> | AUDIT CLEAN | <artifact URL>
WHERE TO SPEND THOUGHT. The agreed readings and the hadith picks are the
entire job; everything else is three commands. Run --data, --build and
--audit without deliberation. Think hard about: what the commentaries
SHARE for this ayah, whether a term is already settled in the glossary,
and whether the hadith picks carry a cross-tradition convergence. If a
gate fails, fix the input - never the gate.
AT THE END report: surahs built, total ayat, every gate that fired and
why, and every term you put in glossary-in/W2.md.
Start now with /surah-purge 8al-Naml to Fāṭir — sustained argument, the signs in creation.
You are WINDOW 5 of 9 building the Qur'an surah pages.
Your range is surahs 27-35 - 9 surahs, 546 ayat. No other window
touches them.
FIRST: read 05-READINGS/GLOSSARY.md and hold to it. It is the controlled
vocabulary for all nine windows and it is READ-ONLY for you. When you
settle a term it does not carry, append the row to
05-READINGS/glossary-in/W5.md instead - never edit the master.
Then work ONE SURAH AT A TIME, in order, all five steps of the skill, and
publish it before starting the next. A finished surah should be finished.
After each surah run:
python check_consistency.py <N>
and fix anything it flags HARD before you move on. Then append one line to
05-READINGS/progress/W5.md:
<surah> | <ayat> | AUDIT CLEAN | <artifact URL>
WHERE TO SPEND THOUGHT. The agreed readings and the hadith picks are the
entire job; everything else is three commands. Run --data, --build and
--audit without deliberation. Think hard about: what the commentaries
SHARE for this ayah, whether a term is already settled in the glossary,
and whether the hadith picks carry a cross-tradition convergence. If a
gate fails, fix the input - never the gate.
AT THE END report: surahs built, total ayat, every gate that fired and
why, and every term you put in glossary-in/W5.md.
Start now with /surah-purge 27Qāf to al-Taḥrīm — 11 of these 17 are Madanī: community and law.
You are WINDOW 7 of 9 building the Qur'an surah pages.
Your range is surahs 50-66 - 17 surahs, 611 ayat. No other window
touches them.
FIRST: read 05-READINGS/GLOSSARY.md and hold to it. It is the controlled
vocabulary for all nine windows and it is READ-ONLY for you. When you
settle a term it does not carry, append the row to
05-READINGS/glossary-in/W7.md instead - never edit the master.
Then work ONE SURAH AT A TIME, in order, all five steps of the skill, and
publish it before starting the next. A finished surah should be finished.
After each surah run:
python check_consistency.py <N>
and fix anything it flags HARD before you move on. Then append one line to
05-READINGS/progress/W7.md:
<surah> | <ayat> | AUDIT CLEAN | <artifact URL>
WHERE TO SPEND THOUGHT. The agreed readings and the hadith picks are the
entire job; everything else is three commands. Run --data, --build and
--audit without deliberation. Think hard about: what the commentaries
SHARE for this ayah, whether a term is already settled in the glossary,
and whether the hadith picks carry a cross-tradition convergence. If a
gate fails, fix the input - never the gate.
AT THE END report: surahs built, total ayat, every gate that fired and
why, and every term you put in glossary-in/W7.md.
Start now with /surah-purge 50al-Shams to al-Nās — the shortest, the most recited, the most memorised.
You are WINDOW 9 of 9 building the Qur'an surah pages.
Your range is surahs 90-114 - 24 surahs, 209 ayat. No other window
touches them.
FIRST: read 05-READINGS/GLOSSARY.md and hold to it. It is the controlled
vocabulary for all nine windows and it is READ-ONLY for you. When you
settle a term it does not carry, append the row to
05-READINGS/glossary-in/W9.md instead - never edit the master.
Then work ONE SURAH AT A TIME, in order, all five steps of the skill, and
publish it before starting the next. A finished surah should be finished.
After each surah run:
python check_consistency.py <N>
and fix anything it flags HARD before you move on. Then append one line to
05-READINGS/progress/W9.md:
<surah> | <ayat> | AUDIT CLEAN | <artifact URL>
WHERE TO SPEND THOUGHT. The agreed readings and the hadith picks are the
entire job; everything else is three commands. Run --data, --build and
--audit without deliberation. Think hard about: what the commentaries
SHARE for this ayah, whether a term is already settled in the glossary,
and whether the hadith picks carry a cross-tradition convergence. If a
gate fails, fix the input - never the gate.
AT THE END report: surahs built, total ayat, every gate that fired and
why, and every term you put in glossary-in/W9.md.
Start now with /surah-purge 90Windows running together cannot see each other, so each writes its new terms to its own file. Merging is yours, and it takes minutes.
| # | Do |
|---|---|
| 1 | Read every 05-READINGS/glossary-in/W*.md |
| 2 | Where two windows settled the same term differently, pick one; the loser goes under ## Disputed |
| 3 | Append the agreed rows to 05-READINGS/GLOSSARY.md |
| 4 | Add a matching row to HARD or SOFT in check_consistency.py — otherwise the glossary and the checker drift apart |
| 5 | Re-run the checker over everything built so far |
python check_consistency.py
One window, one command. This is the only check that can see across sūrahs — every gate in the engine verifies one sūrah against itself and passes while the muṣḥaf as a whole drifts.
python check_consistency.py
| It reports | Meaning |
|---|---|
| HARD | a variant that can only be the wrong rendering of that term. Fix these. |
| SOFT | ambiguous, shown with context. Judge each in seconds. |
| Names | a prophet left transliterated — Mūsā where the rest say Moses. |
| Coverage | how far the glossary and the checker have drifted apart. |
| Shape | readings under 80 or over 1200 characters. |
Done looks like this: 114 pages each AUDIT CLEAN, the checker reporting CONSISTENT, 111 lines with URLs across progress/W1..W9.md, and ## Disputed in the glossary either empty or carrying your decisions.
| Gate | What it caught |
|---|---|
| text | a sūrah whose āyah count is not the canonical Kūfan count — the build refuses outright |
| verbatim | a quotation that is not character-for-character in its source |
| page ≤ 16 MB | al-Baqarah first built at 19.8 MB and would not have published |
| relevance | excerpts landing off the passage — was 31.9%, now 3.3% |
| false silence | an edition both quoted and named absent on the same āyah |
| counts | a header number that is not what the page rendered |