# AGENTS.md

## परियोजना अवलोकन

यो वेब विकासको आधारभूत सिद्धान्तहरू सिकाउनका लागि शैक्षिक पाठ्यक्रमको संग्रहालय हो। पाठ्यक्रम Microsoft Cloud Advocates द्वारा विकास गरिएको १२ हप्ताको समग्र कोर्स हो, जसमा JavaScript, CSS, र HTML कभर गर्ने २४ व्यावहारिक पाठहरू छन्।

### प्रमुख घटकहरू

- **शैक्षिक सामग्री**: परियोजना आधारित मोड्युलहरूमा व्यवस्थित २४ संरचित पाठहरू
- **व्यावहारिक परियोजनाहरू**: Terrarium, Typing Game, Browser Extension, Space Game, Banking App, Code Editor, र AI Chat Assistant
- **परस्पर प्रतिक्रिया क्विजहरू**: ४८ क्विजहरू जहाँ प्रत्येकमा ३ प्रश्नहरू (पाठ अघि र पछि मापन)
- **बहुभाषिक समर्थन**: GitHub Actions मार्फत ५०+ भाषाहरूको स्वचालित अनुवाद
- **प्रविधिहरू**: HTML, CSS, JavaScript, Vue.js 3, Vite, Node.js, Express, Python (AI परियोजनाहरूका लागि)

### वास्तुकला

- पाठ-आधारित संरचना भएको शैक्षिक रिपोजिटरी
- प्रत्येक पाठ फोल्डरमा README, कोड उदाहरणहरू, र समाधानहरू
- अलग फोल्डरहरूमा स्वतन्त्र परियोजनाहरू (quiz-app, विभिन्न पाठ परियोजनाहरू)
- GitHub Actions (co-op-translator) प्रयोग गरी अनुवाद प्रणाली
- Docsify मार्फत डकुमेन्टेशन सेवा र PDF रूपमा उपलब्ध

## सेटअप आदेशहरू

यो रिपोजिटरी मुख्य रूपमा शैक्षिक सामग्री प्रयोगका लागि हो। विशेष परियोजनाहरूमा काम गर्नका लागि:

### मुख्य रिपोजिटरी सेटअप

```bash
git clone https://github.com/microsoft/Web-Dev-For-Beginners.git
cd Web-Dev-For-Beginners
```

### क्विज एप सेटअप (Vue 3 + Vite)

```bash
cd quiz-app
npm install
npm run dev        # विकास सर्भर सुरु गर्नुहोस्
npm run build      # उत्पादनको लागि निर्माण गर्नुहोस्
npm run lint       # ESLint चलाउनुहोस्
```

### बैंक परियोजना API (Node.js + Express)

```bash
cd 7-bank-project/api
npm install
npm start          # एपीआई सर्भर सुरु गर्नुहोस्
npm run lint       # ESLint चलाउनुहोस्
npm run format     # Prettier सँग ढाँचा मिलाउनुहोस्
```

### ब्राउजर एक्सटेन्सन परियोजनाहरू

```bash
cd 5-browser-extension/solution
npm install
# ब्राउजर-विशिष्ट एक्सटेन्सन लोड गर्ने निर्देशनहरू पालना गर्नुहोस्
```

### स्पेस गेम परियोजनाहरू

```bash
cd 6-space-game/solution
npm install
# index.html ब्राउजरमा खोल्नुहोस् वा Live Server प्रयोग गर्नुहोस्
```

### च्याट परियोजना (Python Backend)

```bash
cd 9-chat-project/solution/backend/python
pip install openai
# GITHUB_TOKEN वातावरण चर सेट गर्नुहोस्
python api.py
```

## विकास कार्यप्रवाह

### सामग्री योगदानकर्ताहरूका लागि

1. **रिपोजिटरीलाई Fork गर्नुहोस्** आफ्नो GitHub खातामा
2. **आफ्नो Fork क्लोन गर्नुहोस्** स्थानीय रूपमा
3. **आफ्नो परिवर्तनहरूका लागि नयाँ शाखा बनाउनुहोस्**
4. पाठ सामग्री वा कोड उदाहरणहरूमा परिवर्तन गर्नुहोस्
5. सम्बन्धित परियोजना फोल्डरहरूमा कोड परिवर्तनहरू परीक्षण गर्नुहोस्
6. योगदान दिशानिर्देशहरू अनुसरण गरी pull request पेश गर्नुहोस्

### सिक्नेहरूका लागि

1. रिपोजिटरी Fork वा क्लोन गर्नुहोस्
2. पाठ फोल्डरहरू अनुक्रममा जानुहोस्
3. प्रत्येक पाठका README फाइलहरू पढ्नुहोस्
4. https://ff-quizzes.netlify.app/web/ मा पाठ अघि क्विजहरू पूरा गर्नुहोस्
5. पाठ फोल्डरहरूमा कोड उदाहरणहरू कार्यान्वयन गर्नुहोस्
6. असाइनमेन्ट र चुनौतिहरू पूरा गर्नुहोस्
7. पाठ पछि क्विजहरू लिनुहोस्

### प्रत्यक्ष विकास

- **डकुमेन्टेशन**:रुटमा `docsify serve` चलाउनुहोस् (पोर्ट ३०००)
- **क्विज एप**: `quiz-app` फोल्डरमा `npm run dev` चलाउनुहोस्
- **परियोजनाहरू**: HTML परियोजनाहरूका लागि VS Code Live Server एक्सटेन्सन प्रयोग गर्नुहोस्
- **API परियोजनाहरू**: सम्बन्धित API फोल्डरहरूमा `npm start` चलाउनुहोस्

## परीक्षण निर्देशनहरू

### क्विज एप परीक्षण

```bash
cd quiz-app
npm run lint       # कोड शैली समस्याहरू जाँच गर्नुहोस्
npm run build      # बिल्ड सफल हुन्छ भन्ने पक्का गर्नुहोस्
```

### बैंक API परीक्षण

```bash
cd 7-bank-project/api
npm run lint       # कोड शैलीका समस्याहरू जाँच गर्नुहोस्
node server.js     # सर्भर त्रुटिहरू बिना सुरु हुन्छ कि छैन जाँच गर्नुहोस्
```

### सामान्य परीक्षण दृष्टिकोण

- यो शैक्षिक रिपोजिटरी हो, यसमा पूर्ण स्वचालित परीक्षणहरू छैनन्
- म्यानुअल परीक्षण मुख्य रूपमा:
  - कोड उदाहरणहरू बिना त्रुटि चल्ने
  - डकुमेन्टेशनमा लिंकहरू सही काम गर्ने
  - परियोजना सफलतापूर्वक बिल्ड हुने
  - उदाहरणहरू उत्कृष्ट अभ्यासहरू अनुसरण गर्ने

### पठाउने अघि जाँचहरू

- पस_PACKAGE.JSON भएका फोल्डरहरूमा `npm run lint` चलाउनुहोस्
- मार्कडाउन लिंकहरू मान्य छन् कि छैनन् जाँच्नुहोस्
- ब्राउजर वा Node.js मा कोड उदाहरणहरू परीक्षण गर्नुहोस्
- अनुवादहरूले उचित संरचना कायम राखेका छन् कि छैनन् जाँच गर्नुहोस्

## कोड शैली दिशानिर्देशहरू

### JavaScript

- आधुनिक ES6+ सिन्ट्याक्स प्रयोग गर्नुहोस्
- परियोजनाहरूमा दिइएको मानक ESLint सेटिङहरू अनुसरण गर्नुहोस्
- शिक्षार्थीहरूको स्पष्टताका लागि अर्थपूर्ण भेरिएबल र फंक्शन नामहरू प्रयोग गर्नुहोस्
- सिकाउनका लागि अवधारणाहरू व्याख्या गर्ने टिप्पणीहरू थप्नुहोस्
- जहाँ सेट गरिएको छ त्यहाँ Prettier द्वारा फर्म्याटिङ गर्नुहोस्

### HTML/CSS

- सेमेन्टिक HTML5 तत्त्वहरू प्रयोग गर्नुहोस्
- उत्तरदायी डिजाइन सिद्धान्तहरू अवलम्बन गर्नुहोस्
- स्पष्ट वर्ग नामकरण प्रणालीहरू
- CSS प्रविधिहरू व्याख्या गर्ने टिप्पणीहरू

### Python

- PEP 8 शैली दिशानिर्देशहरू पालना गर्नुहोस्
- स्पष्ट, शैक्षिक कोड उदाहरणहरू
- सिकाइमा मद्दत पुर्‍याउने थाइप संकेतहरू जहाँ उपयोगी हुन्छन्

### Markdown डकुमेन्टेशन

- स्पष्ट शीर्षक अनुक्रम
- भाषा निर्दिष्ट गरिएको कोड ब्लकहरू
- थप स्रोत सामग्रीका लागि लिंकहरू
- `images/` फोल्डरहरूमा स्क्रिनशट र चित्रहरू
- पहुँचको लागि छविहरूमा Alt पाठ

### फाइल संगठन

- पाठहरू क्रमिक रूपमा नम्बर गरिएको (1-getting-started-lessons, 2-js-basics आदि)
- प्रत्येक परियोजनामा `solution/` र प्रायः `start/` वा `your-work/` फोल्डरहरू
- पाठ विशिष्ट `images/` फोल्डरहरूमा छविहरू संग्रहित
- अनुवादहरू `translations/{language-code}/` संरचनामा

## निर्माण र तैनाथी

### क्विज एप तैनाथी (Azure Static Web Apps)

क्विज एप Azure Static Web Apps मा तैनाथीका लागि कन्फिगर गरिएको छ:

```bash
cd quiz-app
npm run build      # dist/ फोल्डर सिर्जना गर्दछ
# मुख्यमा पुश हुँदा GitHub Actions वर्कफ्लो मार्फत परिनियोजन गर्दछ
```

Azure Static Web Apps कन्फिगरेसन:
- **एप स्थान**: `/quiz-app`
- **आउटपुट स्थान**: `dist`
- **कार्यप्रवाह**: `.github/workflows/azure-static-web-apps-ashy-river-0debb7803.yml`

### डकुमेन्टेशन PDF निर्माण

```bash
npm install                    # docsify-to-pdf स्थापना गर्नुहोस्
npm run convert               # डकहरूबाट PDF निर्माण गर्नुहोस्
```

### Docsify डकुमेन्टेशन

```bash
npm install -g docsify-cli    # Docsify लाई ग्लोबली इन्स्टल गर्नुहोस्
docsify serve                 # localhost:3000 मा सेवा दिनुहोस्
```

### परियोजना-विशिष्ट निर्माण

प्रत्येक परियोजना फोल्डरले आफ्नै निर्माण प्रक्रिया राख्न सक्छ:
- Vue परियोजनाहरू: `npm run build` ले उत्पादन बन्डलहरू सिर्जना गर्छ
- स्थिर परियोजनाहरू: कुनै निर्माण चरण छैन, फाइलहरू सिधै सेवा गर्नुहोस्

## पुल अनुरोध दिशानिर्देशहरू

### शीर्षक ढाँचा

परिवर्तन क्षेत्र स्पष्ट गर्ने शीर्षक प्रयोग गर्नुहोस्:
- `[Quiz-app] पाठ X को लागि नयाँ क्विज थप्नुहोस्`
- `[Lesson-3] टेरारियम परियोजनामा टाइपो सच्याउनुहोस्`
- `[Translation] पाठ 5 का लागि स्पेनिश अनुवाद थप्नुहोस्`
- `[Docs] सेटअप निर्देशनहरू अद्यावधिक गर्नुहोस्`

### आवश्यक जाँचहरू

PR पेश गर्नु अघि:

1. **कोड गुणस्तर**:
   - प्रभावित परियोजना फोल्डरहरूमा `npm run lint` चलाउनुहोस्
   - सबै लिङ्टिंग त्रुटि र चेतावनीहरू सच्याउनुहोस्

2. **निर्माण प्रमाणीकरण**:
   - लागू भएमा `npm run build` चलाउनुहोस्
   - कुनै निर्माण त्रुटि नभएको सुनिश्चित गर्नुहोस्

3. **लिङ्क जाँच**:
   - सबै मार्कडाउन लिंकहरू परीक्षण गर्नुहोस्
   - छवि सन्दर्भहरू काम गर्ने सुनिश्चित गर्नुहोस्

4. **सामग्री समीक्षा**:
   - वर्तनी र व्याकरणको प्रूफ रिडिंग गर्नुहोस्
   - कोड उदाहरणहरू सही र शैक्षिक छन् कि छैनन् सुनिश्चित गर्नुहोस्
   - अनुवादहरूले मूल अर्थ कायम राखेका छन् कि छैनन् जाँच गर्नुहोस्

### योगदान आवश्यकताहरू

- Microsoft CLA मा सहमति जनाउनुहोस् (पहिलो PR मा स्वचालित जाँच)
- [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/) अनुसरण गर्नुहोस्
- विस्तृत दिशानिर्देशहरूका लागि [CONTRIBUTING.md](./CONTRIBUTING.md) हेर्नुहोस्
- आवश्यकता अनुसार PR विवरणमा इश्यू नम्बर उल्लेख गर्नुहोस्

### समीक्षा प्रक्रिया

- PR हरू मर्मतकर्ता र समुदायले समीक्षा गर्नेछन्
- शैक्षिक स्पष्टता प्राथमिकता दिइनेछ
- कोड उदाहरणहरूले वर्तमान उत्कृष्ट अभ्यासहरू अनुसरण गर्नुपर्छ
- अनुवादहरू सटीकता र सांस्कृतिक उपयुक्तताका लागि समीक्षा गरिनेछ

## अनुवाद प्रणाली

### स्वचालित अनुवाद

- GitHub Actions सँग co-op-translator कार्यप्रवाह प्रयोग गर्दछ
- ५०+ भाषामा स्वचालित रूपमा अनुवाद गर्दछ
- मुख्य फोल्डरहरूमा स्रोत फाइलहरू
- अनुवादित फाइलहरू `translations/{language-code}/` फोल्डरमा

### म्यानुअल अनुवाद सुधारहरू थप्ने तरिका

1. `translations/{language-code}/` मा फाइल खोज्नुहोस्
2. संरचना कायम राख्दै सुधार गर्नुहोस्
3. कोड उदाहरणहरू कार्यशील छन् कि छैनन् सुनिश्चित गर्नुहोस्
4. कुनै स्थानीयकृत क्विज सामग्री भए परीक्षण गर्नुहोस्

### अनुवाद मेटाडाटा

अनुवादित फाइलहरूमा मेटाडाटा हेडर समावेश हुन्छ:
```markdown
<!--
CO_OP_TRANSLATOR_METADATA:
{
  "original_hash": "...",
  "translation_date": "...",
  "source_file": "...",
  "language_code": "..."
}
-->
```

## डिबगिङ र समस्या समाधान

### सामान्य समस्याहरू

**क्विज एप सुरु हुँदैन**:
- Node.js संस्करण जाँच्नुहोस् (v14+ सिफारिस गरिएको)
- `node_modules` र `package-lock.json` मेटेर फेरि `npm install` चलाउनुहोस्
- पोर्ट द्वन्द्व जाँच्नुहोस् (पूर्वनिर्धारित: Vite पोर्ट 5173)

**API सर्भर सुरु हुँदैन**:
- Node.js संस्करण कम्तिमा node >=10 छ कि छैन जाँच्नुहोस्
- पोर्ट पहिल्यै प्रयोगमा छ कि छैन देख्नुहोस्
- सबै निर्भरताहरू `npm install` बाट इन्स्टल गरिएको सुनिश्चित गर्नुहोस्

**ब्राउजर एक्सटेन्सन लोड हुँदैन**:
- manifest.json सही ढंगले तयार छ कि छैन जाँच गर्नुहोस्
- ब्राउजर कन्सोलमा त्रुटि हेर्नुहोस्
- ब्राउजर विशेष एक्सटेन्सन स्थापना निर्देशनहरू पालना गर्नुहोस्

**Python च्याट परियोजनामा समस्या**:
- OpenAI प्याकेज इन्स्टल गरिएको छ: `pip install openai`
- GITHUB_TOKEN वातावरण चर सेट गरिएको छ कि छैन जाँच्नुहोस्
- GitHub Models पहुँच अनुमतिहरू ठीक छन् कि हेर्नुहोस्

**Docsify डकुमेन्टेशन सेवा दिदैन**:
- docsify-cli ग्लोबली इन्स्टल गर्नुहोस्: `npm install -g docsify-cli`
- रिपोजिटरीको रुटबाट चलाउनुहोस्
- `docs/_sidebar.md` अस्तित्वमा छ कि छैन जाँच्नुहोस्

### विकास वातावरणका सुझावहरू

- HTML परियोजनाहरूका लागि VS Code Live Server एक्सटेन्सन प्रयोग गर्नुहोस्
- स्थिर फर्म्याटिङका लागि ESLint र Prettier एक्सटेन्सनहरू इन्स्टल गर्नुहोस्
- JavaScript डिबगिङका लागि ब्राउजरका DevTools प्रयोग गर्नुहोस्
- Vue परियोजनाहरूका लागि Vue DevTools ब्राउजर एक्सटेन्सन इन्स्टल गर्नुहोस्

### प्रदर्शन सम्बन्धी विचारहरू

- धेरै अनुवादित फाइलहरू (५०+ भाषा) को कारण पूर्ण क्लोन ठूलो हुन्छ
- केवल सामग्रीमा काम गर्दा shallow clone प्रयोग गर्नुहोस्: `git clone --depth 1`
- अंग्रेजी सामग्रीमा काम गर्दा अनुवादहरू खोजबाट अलग गर्नुहोस्
- पहिलो रनमा निर्माण प्रक्रिया ढिलो हुन सक्छ (npm install, Vite build)

## सुरक्षा सम्बन्धी विचारहरू

### वातावरण चरहरू

- API कुञ्जीहरू रिपोजिटरीमा कहिल्यै कमिट गर्नु हुँदैन
- `.env` फाइलहरू प्रयोग गर्नुहोस् (पहिले नै `.gitignore` मा छन्)
- परियोजना README मा आवश्यक वातावरण चरहरू उल्लेख गर्नुहोस्

### Python परियोजनाहरू

- भर्चुअल वातावरणहरू प्रयोग गर्नुहोस्: `python -m venv venv`
- निर्भरता अपडेट राख्नुहोस्
- GitHub टोकनहरू न्यूनतम आवश्यक अनुमति मात्र राख्नुपर्छ

### GitHub Models पहुँच

- GitHub Models का लागि Personal Access Tokens (PAT) आवश्यक
- टोकनहरू वातावरण चरको रूपमा राख्नुहोस्
- टोकन वा प्रमाणपत्र कहिल्यै कमिट नगर्नुहोस्

## थप नोटहरू

### लक्षित दर्शक

- वेब विकासका नयाँ सुरूवातकर्ताहरू
- विद्यार्थी र स्वतः सिक्नेहरू
- कक्षाहरूमा यो पाठ्यक्रम प्रयोग गर्ने शिक्षकहरू
- सामग्री पहुँचयोग्य र क्रमबद्ध सीप विकासका लागि डिजाइन गरिएको

### शैक्षिक दर्शन

- परियोजना आधारित सिकाइ पद्धति
- बारम्बार ज्ञान परीक्षण (क्विज)
- हात-बाट कोडिङ अभ्यासहरू
- वास्तविक कार्यान्वयन उदाहरणहरू
- फ्रेमवर्क अघि आधारभूतमा केन्द्रित

### रिपोजिटरी मर्मत

- सिक्ने र योगदान गर्ने सक्रिय समुदाय
- निर्भरता र सामग्री नियमित अपडेट
- मर्मतकर्ताद्वारा समस्याहरू र छलफलहरू अनुगमन
- GitHub Actions मार्फत अनुवाद अपडेट स्वचालित

### सम्बन्धित स्रोतहरू

- [Microsoft Learn मोड्युलहरू](https://docs.microsoft.com/learn/)
- [Student Hub स्रोतहरू](https://docs.microsoft.com/learn/student-hub/)
- सिक्नेहरूका लागि सिफारिस: [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot)
- थप पाठ्यक्रमहरू: जनरेटिभ AI, डेटा विज्ञान, ML, IoT पाठ्यक्रमहरू उपलब्ध

### विशेष परियोजनाहरूमा काम गर्ने तरिका

व्यक्तिगतरूपमा परियोजनाहरूको विस्तृत निर्देशनका लागि निम्न फोल्डरहरूमा README हेर्नुहोस्:
- `quiz-app/README.md` - Vue 3 क्विज एप्लिकेशन
- `7-bank-project/README.md` - प्रमाणीकरण सहित बैंकिङ एप्लिकेशन
- `5-browser-extension/README.md` - ब्राउजर एक्सटेन्सन विकास
- `6-space-game/README.md` - क्यानभास आधारित खेल विकास
- `9-chat-project/README.md` - AI च्याट सहयोगी परियोजना

### मोनोरिपोजिटरी संरचना

यो परम्परागत मोनोरिपोजिटरी होइन, तर यसमा धेरै स्वतन्त्र परियोजनाहरू छन्:
- प्रत्येक पाठ स्वयंपूर्ण छ
- परियोजनाहरू निर्भरता साझा गर्दैनन्
- व्यक्तिगत परियोजनामा काम गर्दा अरूलाई असर पर्ने छैन
- सम्पूर्ण पाठ्यक्रम अनुभवका लागि सम्पूर्ण रिपोजिटरी क्लोन गर्नुहोस्

---

<!-- CO-OP TRANSLATOR DISCLAIMER START -->
**अस्वीकरण**:  
यस कागजातलाई AI अनुवाद सेवा [Co-op Translator](https://github.com/Azure/co-op-translator) प्रयोग गरी अनुवाद गरिएको हो। हामी शुद्धताको लागि प्रयास गरिरहेका छौं, तर कृपया बुझ्नुहोस् कि स्वचालित अनुवादमा त्रुटिहरू वा अशुद्धताहरू हुन सक्छन्। मूल कागजात यसको स्वदेशी भाषामा नै आधिकारिक स्रोत मानिनु पर्छ। गम्भीर जानकारीको लागि, व्यावसायिक मानव अनुवाद सिफारिस गरिन्छ। यस अनुवादको प्रयोगबाट उत्पन्न हुने कुनै पनि गलतफहमी वा दृष्टिकोण त्रुटिहरूको लागि हामी जिम्मेवार छैनौं।
<!-- CO-OP TRANSLATOR DISCLAIMER END -->