diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 1f3c3ac73..dbbced620 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -50,6 +50,7 @@ Please note that this project is released with a [Code of Conduct](CODE_OF_CONDU
7. [Issue Labels & GSSoC Levels](#7-issue-labels--gssoc-levels)
8. [Pull Request (PR) Checklist](#8-pull-request-pr-checklist)
9. [Self-Hosting & Deployment](#9-self-hosting--deployment)
+10. [Frequently Asked Questions (FAQ)](#10-frequently-asked-questions-faq)
---
@@ -181,9 +182,10 @@ For contributors joining through GirlScript Summer of Code (GSSoC), we map issue
| `gssoc:level3` | **Advanced** — Complex logic, API integrations, deep layout refactoring | **55** |
### Guidelines:
-* **One Issue at a Time**: You can only be assigned to one issue at a time.
-* **Auto-unassignment**: If there is no progress or communication on an assigned issue within **3 days**, it will be unassigned and given to another contributor.
+* **One Issue at a Time**: Prefer working on one issue at a time so reviews stay focused.
+* **Auto-unassignment**: If you are assigned but do not open a PR within **7 days**, the issue-assignment bot will unassign you so others can pick it up. Still working on it? Comment on the issue and request re-assignment.
* **Link Issue to PR**: Ensure your pull request description explicitly links to your assigned issue (e.g. `Closes #45`).
+* **GSSoC scoring labels**: Maintainers apply `level:*` difficulty labels and `gssoc:approved` on your PR at merge time so it counts toward GSSoC scoring. See [FAQ — GSSoC 2026](#gssoc-2026) for details.
---
@@ -212,6 +214,222 @@ For guides on self-hosting DevTrack or deploying it manually, please check the [
---
+## 10. Frequently Asked Questions (FAQ)
+
+Answers to the most common questions from new contributors and GSSoC participants. If your question is not covered here, ask in [GitHub Discussions](https://github.com/Priyanshu-byte-coder/devtrack/discussions) or on the GSSoC Discord.
+
+### Getting Started
+
+
+Do I need to be assigned to an issue before I start coding?
+
+Yes. Comment on the issue you want to work on and wait for the assignment bot to confirm. The bot assigns you when your comment includes phrases such as:
+
+- `I'd like to work on this`
+- `assign me`
+- `I can work on this`
+
+Do not open a PR for an issue that is already assigned to someone else.
+
+
+
+Can I work on multiple issues at the same time?
+
+Prefer one issue at a time so reviews stay manageable. The per-contributor assignment limit is temporarily disabled, but maintainers may still ask you to finish an in-progress issue before picking up another.
+
+
+
+Should I use npm or pnpm?
+
+CI runs `npm ci` against `package-lock.json`, and [DEVELOPMENT.md](./DEVELOPMENT.md) uses `npm` commands. For the closest match with CI, use **npm**:
+
+```bash
+npm install
+npm run dev
+```
+
+Some sections of this guide reference `pnpm`; either package manager works locally, but **do not commit conflicting lockfile changes**. Do not mix `package-lock.json` and `pnpm-lock.yaml` updates in the same PR.
+
+
+
+Which environment variables are required?
+
+At minimum you need Supabase credentials, NextAuth settings, GitHub OAuth keys, and `ENCRYPTION_KEY` to sign in and load the dashboard. See the full table in [Section 3 — Environment Variables Guide](#3-environment-variables-guide).
+
+Optional variables (`GROQ_API_KEY`, Upstash Redis, `GITHUB_TOKEN`, etc.) enable extra features but are not required for basic local development.
+
+
+
+Where is the full local setup guide?
+
+- **[DEVELOPMENT.md](./DEVELOPMENT.md)** — step-by-step setup from clone to running app
+- **[docs/architecture.md](./docs/architecture.md)** — how pages, API routes, and Supabase fit together
+- **[docs/self-hosting.md](./docs/self-hosting.md)** — deployment and production env vars
+
+
+
+I'm new to open source — where should I start?
+
+Browse [good first issues](https://github.com/Priyanshu-byte-coder/devtrack/issues?q=label%3A%22good+first+issue%22), read [docs/architecture.md](./docs/architecture.md), and pick a `gssoc:level1` or documentation issue if you are participating in GSSoC.
+
+
+### Issues and PRs
+
+
+How do I claim an issue?
+
+1. Find an open, unassigned issue.
+2. Comment with your intent (e.g. `I'd like to work on this issue. I'm a GSSoC'26 contributor.`).
+3. Wait for the bot to assign you and add the `gssoc:assigned` label.
+4. Create a branch, implement the change, and open a PR linking the issue (`Closes #123`).
+
+
+
+How long do I have before I lose my assignment?
+
+You have **7 days** from assignment to open a PR. If no PR is linked within that window, the auto-unassign bot removes your assignment so another contributor can take the issue. If you need more time, comment on the issue before the deadline.
+
+
+
+Which branch should my PR target?
+
+Always open PRs against **`main`** on the upstream repository (`Priyanshu-byte-coder/devtrack`). Never push directly to `main` on upstream — work on a feature branch in your fork instead.
+
+
+
+Should I use feat/ or feature/ for branch names?
+
+Prefer the prefixes in [Section 5](#5-branch-naming-conventions): `feat/`, `fix/`, `docs/`, `test/`, `refactor/`. Example: `docs/contributing-faq`.
+
+
+
+What must my pull request include?
+
+- A clear title and description
+- `Closes #` in the PR body
+- Passing CI checks (lint, type-check, tests, build)
+- Screenshots or a short GIF for UI changes
+- Conventional commit messages on your branch
+
+
+
+How do I keep my fork up to date with upstream?
+
+```bash
+git fetch upstream
+git checkout main
+git rebase upstream/main
+git push origin main
+```
+
+Before opening or updating a PR, rebase your feature branch onto the latest `upstream/main`.
+
+
+### GSSoC 2026
+
+
+How do GSSoC points work for DevTrack?
+
+Points depend on issue difficulty and PR quality labels applied by maintainers at merge time. The assignment bot and GSSoC label automation help track your work, but **maintainers must add `level:*` and `gssoc:approved` labels before your PR counts toward scoring**.
+
+
+
+What labels matter for GSSoC scoring?
+
+| Label | Purpose |
+| :--- | :--- |
+| `level:beginner` | 20 pts |
+| `level:intermediate` | 35 pts |
+| `level:advanced` | 55 pts |
+| `level:critical` | 80 pts |
+| `quality:clean` | ×1.2 multiplier (optional) |
+| `quality:exceptional` | ×1.5 multiplier (optional) |
+| `gssoc:approved` | **Required** for the PR to score |
+| `gssoc:invalid` / `gssoc:spam` / `gssoc:ai-slop` | Does not score |
+
+Issue labels such as `gssoc:level1` indicate estimated difficulty; final scoring labels are applied on the merged PR.
+
+
+
+Is documentation-only work valid for GSSoC?
+
+Yes. Documentation improvements are valuable contributions. Use a `docs/` branch prefix, and your PR will receive a `type:docs` label when merged.
+
+
+
+Should I mention GSSoC in my issue comment or PR?
+
+Yes — mention that you are a GSSoC'26 contributor when requesting assignment (e.g. `I'm a GSSoC'26 contributor and I would like to work on this issue.`). Always link the issue in your PR with `Closes #`.
+
+
+
+What happens after my PR is approved?
+
+A maintainer merges your PR and applies the appropriate `level:*` and `gssoc:approved` labels. If those labels are missing after approval, the GSSoC bot will remind maintainers so your contribution counts.
+
+
+### Troubleshooting
+
+
+My pre-commit or Husky hook failed — what do I do?
+
+DevTrack runs ESLint and formatting checks before commits. See **[docs/HUSKY_TROUBLESHOOTING.md](./docs/HUSKY_TROUBLESHOOTING.md)** for step-by-step fixes, including permission errors on Linux/macOS and Windows-specific issues.
+
+
+
+CI is failing on lint or type-check — how do I fix it locally?
+
+Run the same checks CI uses:
+
+```bash
+npm run lint
+npm run type-check
+npm run test
+npm run build
+```
+
+Fix all reported errors before pushing again.
+
+
+
+GitHub OAuth login is not working locally — what should I check?
+
+Verify the following in [Section 1 — Prerequisites](#1-prerequisites):
+
+- GitHub OAuth **callback URL** is exactly `http://localhost:3000/api/auth/callback/github`
+- `NEXTAUTH_URL` is `http://localhost:3000`
+- `GITHUB_ID` and `GITHUB_SECRET` match your OAuth app
+- `.env.local` exists and the dev server was restarted after editing env vars
+
+
+
+Where can I ask for help if I'm stuck?
+
+- **[GitHub Discussions](https://github.com/Priyanshu-byte-coder/devtrack/discussions)** — questions, ideas, and community help
+- **Comment on your assigned issue** — maintainers and other contributors can guide you
+- **GSSoC Discord** — see [docs/HUSKY_TROUBLESHOOTING.md](./docs/HUSKY_TROUBLESHOOTING.md) for community links
+- **[Open an issue](https://github.com/Priyanshu-byte-coder/devtrack/issues/new/choose)** — for bugs or unclear documentation
+
+
+
+My PR has merge conflicts — how do I resolve them?
+
+Sync with upstream and rebase your branch:
+
+```bash
+git fetch upstream
+git rebase upstream/main
+# resolve conflicts in your editor, then:
+git add .
+git rebase --continue
+git push --force-with-lease origin your-branch-name
+```
+
+If you are unsure how to resolve a conflict, ask in your PR or issue before force-pushing.
+
+
+---
+
Thank you for helping make DevTrack better! Happy coding! 🚀