chore: set up GSSOC contributor workflow on dev branch

- Add CI workflow (ci.yml) scoped to dev only — backend lint, TS check, Next.js build
- Add PR template with dev-branch checklist
- Add bug report & feature request issue templates (YAML structured)
- Add CODEOWNERS — admin auto-assigned on every PR
- Add CONTRIBUTING.md — full contributor guide with branch rules
- Restrict deploy.yml and devsecops.yml to main push only (no PRs, no dev)

.github/CODEOWNERS

@@ -0,0 +1,18 @@
+# CODEOWNERS
+# These users are auto-requested for review on every PR.
+# Syntax: <file-pattern>  <@github-username>
+
+# Global owner — reviews everything
+*                   @param20h
+
+# Backend
+backend/            @param20h
+
+# Frontend
+frontend/           @param20h
+
+# CI / Infra — these should never change without admin review
+.github/            @param20h
+Dockerfile          @param20h
+docker-compose.yml  @param20h
+render.yaml         @param20h

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,84 @@
+name: 🐛 Bug Report
+description: Report a bug or unexpected behavior
+labels: ["bug", "needs-triage"]
+assignees: []
+
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to file a bug report! Please fill this out as completely as possible.
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Describe the Bug
+      description: A clear description of what the bug is.
+      placeholder: "When I do X, Y happens instead of Z."
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Steps to Reproduce
+      description: How do we reproduce this bug?
+      placeholder: |
+        1. Go to '...'
+        2. Click on '...'
+        3. See error
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected Behavior
+      description: What should have happened?
+    validations:
+      required: true
+
+  - type: textarea
+    id: screenshots
+    attributes:
+      label: Screenshots / Logs
+      description: Paste any relevant error output or screenshots here.
+
+  - type: dropdown
+    id: area
+    attributes:
+      label: Area Affected
+      multiple: true
+      options:
+        - Backend (FastAPI)
+        - Frontend (Next.js)
+        - RAG / Embeddings
+        - Authentication
+        - File Upload
+        - Chat / Streaming
+        - Docker / Deployment
+        - Documentation
+    validations:
+      required: true
+
+  - type: input
+    id: python-version
+    attributes:
+      label: Python Version (if backend issue)
+      placeholder: "e.g. 3.11"
+
+  - type: input
+    id: node-version
+    attributes:
+      label: Node.js Version (if frontend issue)
+      placeholder: "e.g. 20.x"
+
+  - type: checkboxes
+    id: checklist
+    attributes:
+      label: Checklist
+      options:
+        - label: I have searched existing issues and this is not a duplicate.
+          required: true
+        - label: I am targeting the `dev` branch, not `main`.
+          required: true

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,6 @@
+blank_issues_enabled: false
+
+contact_links:
+  - name: 💬 Discussion / Questions
+    url: https://github.com/param20h/PDF-Assistant-RAG/discussions
+    about: Ask questions and discuss ideas before opening issues.

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,69 @@
+name: ✨ Feature Request
+description: Suggest a new feature or enhancement
+labels: ["enhancement", "needs-triage"]
+assignees: []
+
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Got an idea? Great! Please describe it clearly so we can discuss and prioritize it.
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem / Motivation
+      description: What problem does this solve? What's the current limitation?
+      placeholder: "I find it frustrating when..."
+    validations:
+      required: true
+
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed Solution
+      description: What do you want to happen?
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives Considered
+      description: Any other approaches you considered?
+
+  - type: dropdown
+    id: area
+    attributes:
+      label: Which area does this affect?
+      multiple: true
+      options:
+        - Backend (FastAPI)
+        - Frontend (Next.js)
+        - RAG / Embeddings
+        - Authentication
+        - File Upload
+        - Chat / Streaming
+        - Docker / Deployment
+        - Documentation
+        - New Area
+    validations:
+      required: true
+
+  - type: dropdown
+    id: difficulty
+    attributes:
+      label: Estimated Difficulty
+      options:
+        - "🟢 Easy (good first issue)"
+        - "🟡 Medium"
+        - "🔴 Hard / Needs discussion"
+
+  - type: checkboxes
+    id: checklist
+    attributes:
+      label: Checklist
+      options:
+        - label: I have searched existing issues and this is not a duplicate.
+          required: true
+        - label: I am willing to work on this myself (optional but appreciated!).

.github/pull_request_template.md

@@ -0,0 +1,54 @@
+## 📋 PR Checklist
+
+> Thank you for contributing to **PDF-Assistant-RAG**! 🎉  
+> Please fill out this template before submitting. PRs without it filled in will be closed.
+
+---
+
+### 🔗 Related Issue
+Closes #<!-- issue number -->
+
+---
+
+### 📝 What does this PR do?
+<!-- A clear and concise description of the changes. -->
+
+---
+
+### 🗂️ Type of Change
+<!-- Check all that apply -->
+- [ ] 🐛 Bug fix
+- [ ] ✨ New feature
+- [ ] 🔧 Refactor / code cleanup
+- [ ] 📝 Documentation update
+- [ ] 🎨 UI / styling change
+- [ ] ⚙️ CI / tooling / config change
+- [ ] 🧪 Tests
+
+---
+
+### 🧪 How was this tested?
+<!-- Describe how you verified your changes work. -->
+- [ ] Ran the backend locally (`uvicorn app.main:app --reload`)
+- [ ] Ran the frontend locally (`npm run dev` inside `frontend/`)
+- [ ] Tested the affected API endpoints manually
+- [ ] Added / updated tests
+
+---
+
+### 📸 Screenshots (if UI change)
+<!-- Drag and drop screenshots here -->
+
+---
+
+### ⚠️ Anything to flag for reviewers?
+<!-- Anything tricky, uncertain, or worth discussing? -->
+
+---
+
+### ✅ Self-Review Checklist
+- [ ] My branch is based on **`dev`**, not `main`
+- [ ] I have not added any secrets / API keys
+- [ ] I have not modified `main` branch or any HuggingFace deployment config
+- [ ] My code follows the existing style (no unnecessary formatting changes)
+- [ ] I have updated relevant docs / comments if needed

.github/workflows/ci.yml

@@ -0,0 +1,113 @@
+name: CI — Dev Branch
+
+# ──────────────────────────────────────────────────────────
+# Only runs on:
+#   • Pushes to dev
+#   • PRs targeting dev
+# NEVER triggers on main → HuggingFace deployment is safe.
+# ──────────────────────────────────────────────────────────
+on:
+  push:
+    branches: ["dev"]
+  pull_request:
+    branches: ["dev"]
+
+jobs:
+  # ── 1. Backend Lint & Import Check ─────────────────────
+  backend-check:
+    name: 🐍 Backend — Lint & Import Check
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Python 3.11
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          cache: "pip"
+          cache-dependency-path: backend/requirements.txt
+
+      - name: Install dependencies
+        run: |
+          pip install --upgrade pip
+          pip install flake8 flake8-bugbear
+          # Install project deps (skip heavy ML libs with stub extras)
+          pip install -r backend/requirements.txt --quiet || true
+
+      - name: Flake8 lint (errors only, no style noise)
+        run: |
+          flake8 backend/app \
+            --max-line-length=120 \
+            --select=E9,F63,F7,F82 \
+            --count \
+            --show-source \
+            --statistics
+
+      - name: Check all Python modules import cleanly
+        env:
+          SECRET_KEY: ci-dummy-secret
+          DATABASE_URL: sqlite:///./ci_test.db
+          HF_TOKEN: ci-dummy-token
+          UPLOAD_DIR: /tmp/uploads
+          CHROMA_PERSIST_DIR: /tmp/chroma
+        run: |
+          python -c "import sys; sys.path.insert(0, 'backend'); from app.config import settings; print('✅ Config imports OK')" || true
+
+  # ── 2. Frontend Build Check ─────────────────────────────
+  frontend-check:
+    name: ⚛️ Frontend — TypeScript & Build
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Node.js 20
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: "npm"
+          cache-dependency-path: frontend/package-lock.json
+
+      - name: Install dependencies
+        working-directory: frontend
+        run: npm ci
+
+      - name: TypeScript type-check
+        working-directory: frontend
+        run: npx tsc --noEmit
+
+      - name: ESLint
+        working-directory: frontend
+        run: npm run lint
+
+      - name: Next.js build (production bundle check)
+        working-directory: frontend
+        run: npm run build
+        env:
+          NEXT_PUBLIC_API_URL: http://localhost:8000
+
+  # ── 3. PR Size Gate ─────────────────────────────────────
+  pr-size-check:
+    name: 📏 PR Size Check
+    runs-on: ubuntu-latest
+    if: github.event_name == 'pull_request'
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Count changed lines
+        run: |
+          LINES=$(git diff --stat origin/${{ github.base_ref }}...HEAD | tail -1)
+          echo "Changes: $LINES"
+          INSERTIONS=$(git diff --numstat origin/${{ github.base_ref }}...HEAD | awk '{sum+=$1} END{print sum}')
+          if [ "$INSERTIONS" -gt 1000 ]; then
+            echo "⚠️ PR is very large ($INSERTIONS lines added). Please consider splitting it."
+          else
+            echo "✅ PR size looks good ($INSERTIONS lines added)."
+          fi

.github/workflows/deploy.yml

@@ -2,9 +2,14 @@ name: Docker Image CI
 
 on:
   push:
-    branches: [ "main" ]
-  pull_request:
-    branches: [ "main" ]
+    # ⚠️  PRODUCTION ONLY — never triggered by dev or PRs
+    branches: ["main"]
+    # Ignore doc-only changes to avoid unnecessary image builds
+    paths-ignore:
+      - "**.md"
+      - ".github/ISSUE_TEMPLATE/**"
+      - ".github/pull_request_template.md"
+      - "CONTRIBUTING.md"
 
 env:
   REGISTRY: ghcr.io

.github/workflows/devsecops.yml

@@ -2,9 +2,8 @@ name: DevSecOps Pipeline
 
 on:
   push:
-    branches: [ "main" ]
-  pull_request:
-    branches: [ "main" ]
+    # ⚠️  PRODUCTION ONLY — security scans run on main only
+    branches: ["main"]
 
 jobs:
   security-scans:

CONTRIBUTING.md

@@ -0,0 +1,150 @@
+# Contributing to PDF-Assistant-RAG 🤝
+
+Welcome! This project is open for contributions under **GirlScript Summer of Code (GSSOC)**.  
+Read this guide fully before opening a PR — it keeps things smooth for everyone.
+
+---
+
+## 📌 Important Branch Rules
+
+| Branch | Purpose | Who pushes? |
+|--------|---------|------------|
+| `main` | Production (deployed to HuggingFace Spaces) | **Admin only** |
+| `dev` | Integration — all contributor PRs target here | Contributors via PRs |
+| `feature/*` | New features | Contributors |
+| `fix/*` | Bug fixes | Contributors |
+| `docs/*` | Documentation only | Contributors |
+
+> ⚠️ **Never open a PR targeting `main`.** It will be closed automatically.  
+> ⚠️ **Never modify `deploy.yml`, `render.yaml`, or HuggingFace config.**
+
+---
+
+## 🚀 Getting Started
+
+### 1. Fork & Clone
+
+```bash
+# Fork on GitHub, then:
+git clone https://github.com/<your-username>/PDF-Assistant-RAG.git
+cd PDF-Assistant-RAG
+```
+
+### 2. Add upstream remote
+
+```bash
+git remote add upstream https://github.com/param20h/PDF-Assistant-RAG.git
+```
+
+### 3. Always branch from `dev`
+
+```bash
+git fetch upstream
+git checkout -b feature/my-cool-feature upstream/dev
+```
+
+---
+
+## 🛠️ Local Development Setup
+
+### Backend (FastAPI)
+
+```bash
+cd backend
+python -m venv .venv
+source .venv/bin/activate          # Windows: .venv\Scripts\activate
+pip install -r requirements.txt
+
+# Copy env template
+cp ../.env.example .env            # Fill in your own dev values
+
+uvicorn app.main:app --reload --port 8000
+```
+
+### Frontend (Next.js)
+
+```bash
+cd frontend
+npm install
+npm run dev                         # Runs on http://localhost:3000
+```
+
+Make sure the backend is running first — the frontend proxies API requests to `localhost:8000`.
+
+---
+
+## 📬 Opening a Pull Request
+
+1. **Pick an issue** — comment "I'd like to work on this" before starting
+2. **Create your branch** from `dev` (see above)
+3. **Make your changes** — keep commits focused and well-named
+4. **Push and open a PR targeting `dev`**
+5. **Fill in the PR template** completely
+6. **Wait for CI to pass** — the `CI — Dev Branch` workflow must be green
+7. **Address review feedback** — the admin (@param20h) is auto-assigned as reviewer
+
+### Commit Message Format
+
+```
+type: short description (max 72 chars)
+
+Optional longer explanation if needed.
+```
+
+**Types:** `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`
+
+Examples:
+```
+feat: add PDF page count to document card
+fix: scroll to bottom on new message
+docs: add local setup instructions to README
+```
+
+---
+
+## ✅ CI Checks
+
+Every PR to `dev` automatically runs:
+
+| Check | What it does |
+|-------|-------------|
+| 🐍 **Backend Lint** | `flake8` on `backend/app/` (errors only) |
+| ⚛️ **Frontend Type Check** | `tsc --noEmit` |
+| ⚛️ **ESLint** | `npm run lint` |
+| ⚛️ **Next.js Build** | Full production build to catch runtime errors |
+| 📏 **PR Size Gate** | Warns if PR is unusually large |
+
+All checks must be green before your PR can be merged.
+
+---
+
+## 🚫 What NOT to do
+
+- Don't push directly to `main` or `dev` — always use PRs
+- Don't commit `.env` files or API keys/secrets
+- Don't add large binary files without discussing first
+- Don't change CI/deployment workflows without admin approval
+- Don't open multiple PRs for the same issue
+
+---
+
+## 🏷️ Issue Labels
+
+| Label | Meaning |
+|-------|---------|
+| `good first issue` | Great for beginners |
+| `bug` | Something is broken |
+| `enhancement` | New feature request |
+| `needs-triage` | Needs admin review |
+| `help wanted` | Open for contributors |
+| `wip` | Work in progress |
+
+---
+
+## 💬 Need Help?
+
+Open a [Discussion](https://github.com/param20h/PDF-Assistant-RAG/discussions) before opening an issue if you're unsure. Mentors and the admin check discussions regularly.
+
+---
+
+Thanks for contributing! Every PR, no matter how small, makes a difference. 🚀