diff --git a/.github/scripts/check-doc-drift.sh b/.github/scripts/check-doc-drift.sh
new file mode 100644
index 0000000..ac5af3e
--- /dev/null
+++ b/.github/scripts/check-doc-drift.sh
@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+# QUICKSTART.md is the canonical onboarding guide (see
+# CONTRIBUTING.md#-documentation-structure). This fails CI if onboarding
+# workflow steps get copy-pasted back into the other docs instead of
+# linking to QUICKSTART.md.
+set -euo pipefail
+
+CANONICAL_FILE="QUICKSTART.md"
+CHECK_FILES=("README.md" "FAQ.md" "CONTRIBUTING.md")
+
+# Workflow-step commands/markers that must only live in QUICKSTART.md
+PATTERNS=(
+ 'git checkout -b add-your-name'
+ 'git commit --amend -m'
+ 'git push -f origin add-your-name'
+ '<<<<<<< HEAD'
+)
+
+failed=0
+
+for file in "${CHECK_FILES[@]}"; do
+ for pattern in "${PATTERNS[@]}"; do
+ if grep -qF -- "$pattern" "$file"; then
+ echo "::error file=$file::Found onboarding-workflow content ('$pattern') that duplicates $CANONICAL_FILE. Link to $CANONICAL_FILE instead of repeating workflow steps (see CONTRIBUTING.md#-documentation-structure)."
+ failed=1
+ fi
+ done
+done
+
+if [ "$failed" -ne 0 ]; then
+ echo ""
+ echo "Documentation consistency check failed. See CONTRIBUTING.md#-documentation-structure for ownership rules."
+ exit 1
+fi
+
+echo "Documentation consistency check passed."
diff --git a/.github/workflows/ci-validation.yml b/.github/workflows/ci-validation.yml
index 6f0bfc5..28e3416 100644
--- a/.github/workflows/ci-validation.yml
+++ b/.github/workflows/ci-validation.yml
@@ -17,6 +17,9 @@ jobs:
with:
fetch-depth: 0
+ - name: Check for Duplicated Onboarding Instructions
+ run: bash .github/scripts/check-doc-drift.sh
+
- name: Run Markdown Lint Check
uses: davidanson/markdownlint-cli2-action@v23
with:
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 82743b5..3f04bb8 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -66,6 +66,19 @@ Write clear and descriptive commit messages:
- ❌ Avoid: "Update"
- ❌ Avoid: "Changes"
+## 📑 Documentation Structure
+
+To avoid conflicting onboarding instructions across files, each doc has a defined scope:
+
+| Document | Purpose | Owns |
+|----------|---------|------|
+| [QUICKSTART.md](QUICKSTART.md) | **Canonical onboarding guide** | All fork/clone/branch/commit/push/PR steps and their troubleshooting |
+| [README.md](README.md) | Project landing page | Project overview, contributor list, high-level links |
+| [CONTRIBUTING.md](CONTRIBUTING.md) | Contribution policy | PR requirements, commit conventions, code of conduct, this table |
+| [FAQ.md](FAQ.md) | Extended Q&A | Questions outside the core workflow — any workflow-step question links to QUICKSTART.md instead of repeating steps |
+
+**Rule of thumb:** if you're changing how someone forks, clones, branches, commits, pushes, or opens a PR, edit `QUICKSTART.md` only. Other docs should link to it, not restate it.
+
## Code of Conduct
### Our Standards
diff --git a/FAQ.md b/FAQ.md
index ed79bfb..a41d808 100644
--- a/FAQ.md
+++ b/FAQ.md
@@ -51,30 +51,7 @@ If other people merge their Pull Requests while you are working, your fork can f
### ❓ I got a "Merge Conflict" in my Pull Request. What should I do?
A merge conflict happens when two people edit the same line of the same file, and Git doesn't know which version to keep. Don't worry, it's very easy to fix!
-1. Make sure your local repository is updated (see the sync steps above).
-2. Checkout your working branch:
- ```bash
- git checkout add-your-name
- ```
-3. Merge the updated main branch into your working branch:
- ```bash
- git merge main
- ```
-4. Open the conflicting file (`README.md` or `QUICKSTART.md`) in your text editor. Look for conflict markers:
- ```markdown
- <<<<<<< HEAD
- - [Your Name](https://github.com/YOUR-USERNAME)
- =======
- - [Someone Else](https://github.com/someone-else)
- >>>>>>> main
- ```
-5. Edit the file to keep **both** names (make sure to delete the `<<<<<<<`, `=======`, and `>>>>>>>` markers).
-6. Save the file, add, commit, and push:
- ```bash
- git add README.md
- git commit -m "Fix merge conflict"
- git push origin add-your-name
- ```
+See **[QUICKSTART.md → 🆘 Stuck?](QUICKSTART.md#-stuck)** for the full step-by-step walkthrough.
---
diff --git a/QUICKSTART.md b/QUICKSTART.md
index 0634a60..c247cea 100644
--- a/QUICKSTART.md
+++ b/QUICKSTART.md
@@ -10,6 +10,10 @@
---
+> 📌 **This is the canonical onboarding guide.** All fork → clone → branch → commit → push → PR steps and their troubleshooting live here. Other docs (README, CONTRIBUTING, FAQ) link to this file instead of repeating the steps — please keep it that way when editing docs. See [CONTRIBUTING.md → Documentation Structure](CONTRIBUTING.md#-documentation-structure) for the full ownership breakdown.
+
+---
+
## Prerequisites ✅
- [ ] [GitHub account](https://github.com/signup)
@@ -288,8 +292,21 @@ You should see your PR with a number (e.g., `#42`).
* Add and commit: `git add README.md && git commit -m "Fix merge conflict"`
* Push again: `git push origin add-your-name`
+**My terminal/command prompt doesn't work**
+→ **Windows:** Use Git Bash (installed with Git) or PowerShell
+→ **Mac:** Use Terminal (find it in Applications > Utilities)
+→ **Linux:** Use your default terminal (Ctrl+Alt+T)
+
+**I made a mistake in my commit**
+→ Make the correction, then:
+
+```bash
+git add README.md
+git commit --amend -m "Add [Your Name] to contributors list"
+git push -f origin add-your-name
+```
+
**Need more help?**
-→ Check `README.md` for detailed step-by-step instructions
→ See `FAQ.md` for common questions
→ [Open an issue](../../issues) if you're still stuck
diff --git a/README.md b/README.md
index 12f8578..b08ac45 100644
--- a/README.md
+++ b/README.md
@@ -111,56 +111,7 @@ _Your name will appear here once your PR is merged!_
## 🆘 Stuck? Get Help!
-### Common Issues & Solutions
-
-
-❌ "Git is not recognized" or "command not found"
-
-**Solution:** Git isn't installed. Download it from [git-scm.com](https://git-scm.com/downloads) and restart your terminal.
-
-
-
-
-❌ "Permission denied" when pushing
-
-**Solution:** You might not have permission to push to the original repo. Make sure you:
-
-1. Forked the repository first
-2. Cloned YOUR fork, not the original repository
-3. The URL should contain YOUR username
-
-
-
-❌ "Merge conflict" in Pull Request
-
-**Solution:** Someone else added their name in the same spot. Don't panic!
-
-1. Pull the latest changes: `git pull origin main`
-2. Fix the conflicts in README.md (remove the `<<<<`, `====`, `>>>>` markers)
-3. Add and commit: `git add README.md && git commit -m "Fix merge conflict"`
-4. Push again: `git push origin add-your-name`
-
-
-
-❌ My terminal/command prompt doesn't work
-
-**Solutions:**
-
-- **Windows:** Use Git Bash (installed with Git) or PowerShell
-- **Mac:** Use Terminal (find it in Applications > Utilities)
-- **Linux:** Use your default terminal (Ctrl+Alt+T)
-
-
-
-❌ I made a mistake in my commit
-
-**Solution:** You can fix it!
-
-1. Make the correction in README.md
-2. Stage: `git add README.md`
-3. Amend the commit: `git commit --amend -m "Add [Your Name] to contributors list"`
-4. Force push: `git push -f origin add-your-name`
-
+Ran into "Git not recognized", "Permission denied" when pushing, a merge conflict, a terminal issue, or a bad commit? All of that is covered in **[QUICKSTART.md → 🆘 Stuck?](QUICKSTART.md#-stuck)** — the canonical troubleshooting guide for this project.
### Still Need Help?