# AGENTS.md

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

यो शुरुआतीहरूलाई वेब विकासका आधारहरू सिकाउन बनाइएको शैक्षिक पाठ्यक्रम भण्डार हो। यो पाठ्यक्रम माइक्रोसफ्ट क्लाउड एड्भोकेटहरूले विकास गरेको १२ हप्ताको व्याप्त छ, जसमा २४ अभ्यासात्मक पाठहरू छन् जसले JavaScript, CSS, र HTML कभर गर्दछ।

### प्रमुख अङ्गहरू

- **शैक्षिक सामग्री**: २४ संरचित पाठहरू परियोजना-आधारित मोड्युलहरूमा व्यवस्थित
- **व्यावहारिक परियोजनाहरू**: टेरारियम, टाइपिङ खेल, ब्राउजर एक्सटेन्सन, स्पेस गेम, बैंकिङ एप, कोड सम्पादक, र AI च्याट सहायक
- **इन्टरऐक्टिभ क्विजहरू**: प्रत्येकमा ३ प्रश्न सहित ४८ क्विजहरू (पाठभन्दा पहिले/पछि मूल्याङ्कन)
- **धेरै भाषाहरूको समर्थन**: 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          # API सर्भर सुरु गर्नुहोस्
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 खोल्नुहोस् वा लाइभ सर्भर प्रयोग गर्नुहोस्
```

### च्याट परियोजना (Python ब्याकएण्ड)

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

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

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

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

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

1. भण्डार फोर्क वा क्लोन गर्नुहोस्
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 शैली निर्देशनहरू
- स्पष्ट, शैक्षिक कोड उदाहरणहरू
- सिकाइको लागि जहाँ उपयोगी हो टाइप हिंटहरू

### मार्कडाउन दस्तावेजीकरण

- स्पष्ट शीर्षक पदानुक्रम
- भाषा निर्दिष्ट गरेर कोड ब्लकहरू
- अतिरिक्त स्रोतहरूमा लिंकहरू
- `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/ फोल्डर सिर्जना गर्दछ
# main मा पुश गर्दा GitHub Actions workflow मार्फत डिप्लोय गर्दछ
```

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               # docs बाट PDF निर्माण गर्नुहोस्
```

### Docsify दस्तावेजीकरण

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

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

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

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

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

परिवर्तनको क्षेत्र वर्णन गर्ने स्पष्ट, वर्णनात्मक शीर्षकहरू प्रयोग गर्नुहोस्:
- `[Quiz-app] पाठ X को लागि नयाँ क्विज थप्नुहोस्`
- `[Lesson-3] टेरारियम परियोजनामा टाइपो फिक्स गर्नुहोस्`
- `[Translation] पाठ ५ का लागि स्पेनिश अनुवाद थप्नुहोस्`
- `[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 मोडेल पहुँच अनुमति जाँच गर्नुहोस्

**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 मोडेल पहुँच

- GitHub मोडेलहरूका लागि व्यक्तिगत पहुँच टोकनहरू (PAT) आवश्यक हुन्छन्
- टोकनहरू वातावरण चरको रूपमा भण्डारण गर्नुहोस्
- टोकन वा प्रमाणपत्र कहिल्यै कमिट नगर्नुहोस्

## अतिरिक्त नोटहरू

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

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

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

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

### भण्डार मर्मतसम्भार

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

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

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

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

विशिष्ट परियोजनाहरूका लागि विस्तृत निर्देशनहरू हेर्नुहोस्:
- `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 -->