# AGENTS.md

## Project Overview

ఇది ఆరంభకులకు వెబ్ అభివృద్ధి ప్రాథమికాలను బోధించడానికి ఒక విద్యా పాఠ్యక్రమ సంచయ కోశం. ఈ పాఠ్యపథకం మైక్రోసాఫ్ట్ క్లౌడ్ ఆక్టివ్‌లు అభివృద్ధి చేసిన 12-వారాల సమగ్ర కోర్సు, జావాస్క్రిప్ట్, CSS, మరియు HTML ను కవర్ చేసే 24 ప్రాయోగిక పాఠాలు కలిగి ఉంటుంది.

### Key Components

- **శిక్షణా విషయాలు**: ప్రాజెక్ట్-ఆధారిత మాడ్యూల్స్ లో 24 క్రమబద్ధీకరించిన పాఠాలు
- **ప్రాయోగిక ప్రాజెక్టులు**: టెరరియం, టైపింగ్ ఆట, బ్రౌజర్ ఎక్స్‌టెన్షన్, స్పేస్ ఆట, బాంకింగ్ ఆప్, కోడ్ ఎడిటర్, మరియు AI చాట్ అసిస్టెంట్
- **ఆకట్టుకునే క్విజ్‌లు**: ప్రతి పాఠానికి 3 ప్రశ్నలతో కలిపి 48 క్విజ్‌లు (పూర్వ / అనంతర-పాఠ పరీక్షలు)
- **బహుభాషా మద్దతు**: GitHub Actions ద్వారా 50+ భాషలకి స్వయంచాలక అనువాదాలు
- **సాంకేతికతలు**: HTML, CSS, JavaScript, Vue.js 3, Vite, Node.js, Express, Python (AI ప్రాజెక్టులకు)

### Architecture

- పాఠాల ఆధారంగా నిర్మించిన విద్యా కోశం
- ప్రతి పాఠం ఫోల్డర్ README, కోడ్ ఉదాహరణలు, పరిష్కారాలు కలిగి ఉంటుంది
- స్వతంత్ర ప్రాజెక్టులు వేరే డైరెక్టరీలలో (quiz-app, వివిధ పాఠ ప్రాజెక్టులు)
- GitHub Actions (co-op-translator) ఉపయోగించి అనువాద వ్యవస్థ
- Docsify ద్వారా డాక్యుమెంటేషన్ అందించబడుతుంది మరియు PDF లో కూడా అందుబాటులో ఉంది

## Setup Commands

ఈ సంచయ కోశం ఎక్కువగా విద్యా విషయాలను వినియోగించుకోవడానికి. ప్రత్యేక ప్రాజెక్టులతో పని చేయడానికి:

### Main Repository Setup

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

### Quiz App Setup (Vue 3 + Vite)

```bash
cd quiz-app
npm install
npm run dev        # డెవలప్‌మెంట్ సర్వర్‌ను ప్రారంభించండి
npm run build      # ఉత్పత్తి కోసం నిర్మించండి
npm run lint       # ESLint నడపండి
```

### Bank Project API (Node.js + Express)

```bash
cd 7-bank-project/api
npm install
npm start          # API సర్వర్‌ను ప్రారంభించండి
npm run lint       # ESLint ని నడపండి
npm run format     # Prettier తో ఫార్మాట్ చేయండి
```

### Browser Extension Projects

```bash
cd 5-browser-extension/solution
npm install
# బ్రౌజర్-ప్రత్యేక ఎక్స్‌టెన్షన్ లోడ్ చేయడం సంబంధిత సూచనలను అనుసరించండి
```

### Space Game Projects

```bash
cd 6-space-game/solution
npm install
# బ్రౌజర్‌లో index.html ని తెరవండి లేదా Live Server వినియోగించండి
```

### Chat Project (Python Backend)

```bash
cd 9-chat-project/solution/backend/python
pip install openai
# GITHUB_TOKEN పరిసర వేరియబుల్ సెట్చేయండి
python api.py
```

## Development Workflow

### For Content Contributors

1. **రిపాజిటరీని ఫోర్క్ చేయండి** మీ GitHub ఖాతాకు
2. **మీ fork ని స్థానికంగా క్లోన్ చేయండి**
3. మీ మార్పులకు **కొత్త బ్రాంచ్ సృష్టించండి**
4. పాఠ విషయాలు లేదా కోడ్ ఉదాహరణలలో మార్పులు చేయండి
5. సంబంధిత ప్రాజెక్ట్ డైరెక్టరీలలో కోడ్ మార్పులను పరీక్షించండి
6. సహకార మార్గదర్శకాలను అనుసరించి పుల్ రిక్వెస్ట్‌లు పంపండి

### For Learners

1. రిపాజిటరీని ఫోర్క్ లేదా క్లోన్ చేయండి
2. పాఠాల డైరెక్టరీలలో వరుసగా navigation చేయండి
3. ప్రతి పాఠం README ఫైళ్ళను చదవండి
4. pre-lesson క్విజ్‌లు పూర్తి చేయండి https://ff-quizzes.netlify.app/web/
5. పాఠం ఫోల్డర్లలోని కోడ్ ఉదాహరణలపై పని చేయండి
6. అసైన్‌మెంట్‌లు మరియు సవాళ్లను పూర్తి చేయండి
7. post-lesson క్విజ్‌లు పూర్తి చేయండి

### Live Development

- **డాక్యుమెంటేషన్**: రూట్ లో `docsify serve` నడపండి (పోర్ట్ 3000)
- **క్విజ్ ఆప్**: quiz-app డైరెక్టరీలో `npm run dev` నడపండి
- **ప్రాజెక్టులు**: HTML ప్రాజెక్టులకు VS Code Live Server ఎక్స్‌టెన్షన్ ఉపయోగించండి
- **API ప్రాజెక్టులు**: సంబంధిత API డైరెక్టరీలలో `npm start` నడపండి

## Testing Instructions

### Quiz App Testing

```bash
cd quiz-app
npm run lint       # కోడ్ శైలి సమస్యలు తనిఖీ చేయండి
npm run build      # నిర్మాణం విజయవంతమవుతుందో నిర్ధారించుకోండి
```

### Bank API Testing

```bash
cd 7-bank-project/api
npm run lint       # కోడ్ స్టైల్ సమస్యలను తనిఖీ చేయండి
node server.js     # సర్వర్ లో తప్పులు లేకుండా ప్రారంభమవుతుందో ధృవీకరించండి
```

### General Testing Approach

- ఇది పూర్తిస్థాయి ఆటోమెటిక్ పరీక్షలలేని విద్యా రిపాజిటరీ
- మాన్యువల్ టెస్టింగ్ కింది అంశాలపై ఫోకస్ చేస్తుంది:
  - కోడ్ ఉదాహరణలు ఎర్రర్ లేకుండా నడుస్తున్నాయా
  - డాక్యుమెంటేషన్ లో లింకులు బాగా పనిచేస్తున్నాయా
  - ప్రాజెక్ట్ బిల్డింగ్ విజయవంతమయింది
  - ఉదాహరణలు ఉత్తమ అభ్యాసాలకు అనుగుణంగా ఉన్నాయా

### Pre-submission Checks

- package.json ఉన్న డైరెక్టరీలలో `npm run lint` నడపండి
- మార్క్డౌన్ లింకులు సరైనవా అని ధృవీకరించండి
- బ్రౌజర్ లేదా Node.js లో కోడ్ ఉదాహరణలను పరీక్షించండి
- అనువాదాలు సరైన నిర్మాణాన్ని కలిగి ఉన్నాయా అని పరిశీలించండి

## Code Style Guidelines

### JavaScript

- ఆధునిక ES6+ వాక్యరచన ఉపయోగించండి
- ప్రాజెక్టుల్లో కలిగిన ESLint నియమాలను అనుసరించండి
- విద్యార్థుల స్పష్టతకు అర్థమయ్యే వేరియబుల్ మరియు ఫంక్షన్ పేర్లను వాడండి
- కాంప్లెక్స్ కాన్సెప్ట్‌ల వివరణకు వ్యాఖ్యలు జోడించండి
- Prettier ద్వారా ఫార్మాటింగ్ చేయండి (అక్కడ అమర్చబడిన ఉంటే)

### HTML/CSS

- సేమాంటిక్ HTML5 ఎలిమెంట్స్ ఉపయోగించండి
- రెస్పాన్సివ్ డిజైన్ సూత్రాలు పాటించండి
- క్లియర్ క్లాస్ నేమింగ్ కన్వెన్షన్స్
- CSS సాంకేతికతలను అవగాహన కోసం వ్యాఖ్యలతో వివరించండి

### Python

- PEP 8 శైలీ మార్గదర్శకాలు
- సరళమైన, విద్యా కోడ్ ఉదాహరణలు
- నేర్చుకునే వారికి ఉపయోగపడే టైప్ హింట్స్

### Markdown Documentation

- స్పష్టమైన శీర్షిక హియరార్కీ
- భాష స్పష్టీకరణతో కోడ్ బ్లాక్స్
- అదనపు వనరులకు లింకులు
- `images/` డైరెక్టరీలలో స్క్రీన్‌షాట్లు మరియు చిత్రాలు
- అందుబాటుని పెంచేందుకు చిత్రాలకు ఆల్ట్ టెక్స్ట్

### File Organization

- పాఠాలు వరుస సంఖ్యలతో (1-getting-started-lessons, 2-js-basics, మొదలైనవి)
- ప్రతి ప్రాజెక్ట్ కి `solution/`, తరచుగా `start/` లేదా `your-work/` ఫోల్డర్లు ఉంటాయి
- చిత్రాలు పాఠానికి చెందిన `images/` ఫోల్డర్‌లలో భద్రపరచబడతాయి
- అనువాదాలు `translations/{language-code}/` నిర్మాణంలో

## Build and Deployment

### Quiz App Deployment (Azure Static Web Apps)

quiz-app 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`

### Documentation PDF Generation

```bash
npm install                    # docsify-to-pdf ని ఇన్‌స్టాల్ చేయండి
npm run convert               # డాక్స్ నుండి PDF సృష్టించండి
```

### Docsify Documentation

```bash
npm install -g docsify-cli    # Docsify ను గ్లోబల్గా ఇన్స్టాల్ చేయండి
docsify serve                 # localhost:3000 పై సర్వ్ చేయండి
```

### Project-specific Builds

ప్రతి ప్రాజెక్ట్ డైరెక్టరీకి తన స్వంత బిల్డ్ ప్రక్రియ ఉండవచ్చు:
- Vue ప్రాజెక్టులకు: `npm run build` ప్రొడక్షన్ బండిల్స్ సృష్టిస్తుంది
- స్థిర ప్రాజెక్టులు: బిల్డ్ స్టెప్ అవసరం లేదు, ఫైళ్ళను నేరుగా సేవ్ చేయండి

## Pull Request Guidelines

### Title Format

మార్పు ప్రాంతాన్ని స్పష్టంగా సూచించే టైటిల్స్ వాడండి:
- `[Quiz-app] పాఠం X కోసం కొత్త క్విజ్ జోడించండి`
- `[Lesson-3] టెరరియం ప్రాజెక్ట్ లో టైపో సరిచేయండి`
- `[Translation] పాఠం 5 కి స్పానిష్ అనువాదం జోడించండి`
- `[Docs] సెటప్ సూచనలు నవీకరించండి`

### Required Checks

PR సమర్పించే ముందు:

1. **కోడ్ నాణ్యత**:
   - ప్రభావిత ప్రాజెక్ట్ డైరెక్టరీలలో `npm run lint` నడపండి
   - అన్ని లింట్ లోపాలు, హెచ్చరికలు సరి చేయండి

2. **బిల్డ్ ధృవీకరణ**:
   - అవసరమైతే `npm run build` నడపండి
   - ఎలాంటి బిల్డ్ లోపాలు లేవన్నారు తేల్చుకోండి

3. **లింక్ చెల్లింపుదనం**:
   - అన్ని మార్క్‌డౌన్ లింకులను పరీక్షించండి
   - చిత్ర సూచనలు పనిచేస్తున్నాయా పరిశీలించండి

4. **విషయ సమీక్ష**:
   - స్పెల్లింగ్, వ్యాకరణ పొరపాట్ల కోసం పృథ్వీశుద్ధి చేయండి
   - కోడ్ ఉదాహరణలు సరైనవి మరియు విద్యా పరంగానూ సరైనవి
   - అనువాదాలు మూల అర్థాన్ని కాపాడుతున్నాయా చూసుకోండి

### Contribution Requirements

- Microsoft CLAని అంగీకరించాలి (మొదటి PRపై ఆటోమెటిక్ చెక్)
- [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/)ని అనుసరించాలి
- పూర్తి మార్గదర్శకాలకు [CONTRIBUTING.md](./CONTRIBUTING.md) చూడండి
- అవసరమైతే PR వివరణలో ఇష్యూ నంబర్లు సూచించండి

### Review Process

- PRలను నిర్వహకులు మరియు కమ్యూనిటీ సమీక్షిస్తారు
- విద్యా స్పష్టత ప్రాధాన్యం కలదు
- కోడ్ ఉదాహరణలు ప్రస్తుత ఉత్తమ అభ్యాసాలకు అనుగుణంగా ఉండాలి
- అనువాదాలు ఖచ్చితత్వం మరియు సాంస్కృతిక అనుకూలత కోసం పరిశీలించబడతాయి

## Translation System

### Automated Translation

- GitHub Actions లో co-op-translator వర్క్‌ఫ్లో ఉపయోగిస్తుంది
- 50+ భాషలకు ఆటోమేటిక్ అనువాదాలు చేస్తుంది
- మూల ఫైళ్లు ప్రధాన డైరెక్టరీస్‌లో ఉంటాయి
- అనువాద ఫైళ్లు `translations/{language-code}/`లో ఉంటాయి

### Adding Manual Translation Improvements

1. `translations/{language-code}/`లో ఫైల్ కనుగొనండి
2. నిర్మాణాన్ని కాపాడుతూ మెరుగులు చేయండి
3. కోడ్ ఉదాహరణలు ప్రావృత్తి రీతిలో పనిచేస్తున్నాయో చూడండి
4. స్థానికృత క్విజ్ కంటెంట్ ను పరీక్షించండి

### Translation Metadata

అనువదించిన ఫైళ్ళలో మెటాడేటా హెడ్డర్ ఉంటుంది:
```markdown
<!--
CO_OP_TRANSLATOR_METADATA:
{
  "original_hash": "...",
  "translation_date": "...",
  "source_file": "...",
  "language_code": "..."
}
-->
```

## Debugging and Troubleshooting

### Common Issues

**క్విజ్ యాప్ ప్రారంభం కావడం లేదు**:
- 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_ENVIRONMENT వేరియబుల్ సెట్ అయినదని ధృవీకరించండి
- GitHub Models యాక్సెస్ అనుమతులు తనిఖీ చేయండి

**Docsify డాక్స్ అందుబాటులో లేకపోవడం**:
- docsify-cli గ్లోబల్ గా ఇన్స్టాల్ చేయండి: `npm install -g docsify-cli`
- రిపాజిటరీ రూట్ నుండి నడపండి
- `docs/_sidebar.md` ఉందో చూసుకోండి

### Development Environment Tips

- HTML ప్రాజెక్టులకు VS Code లో Live Server ఎక్స్‌టెన్షన్ ఉపయోగించండి
- ESLint, Prettier ఎక్స్‌టెన్షన్‌లను ఇన్స్టాల్ చేసి నిరంతర ఫార్మాటింగ్ కోసం వాడండి
- JavaScript డీబగ్గింగ్ కోసం బ్రౌజర్ DevTools ఉపయోగించండి
- Vue ప్రాజెక్టులకు Vue DevTools బ్రౌజర్ ఎక్స్‌టెన్షన్ ఉపయోగించండి

### Performance Considerations

- అనువాద ఫైళ్ళ సంఖ్య ఎక్కువ (50+ భాషలు) కావున పూర్తి క్లోన్‌లు పెద్దవి
- కంటెంట్ మీద మాత్రమే పని చేస్తే డెఫాల్ట్ క్లోన్ తొలగించి షాలో క్లోన్ వాడండి: `git clone --depth 1`
- ఇంగ్లీష్ కంటెంట్ మీద పని చేసే సమయంలో అనువాదాలను సెర్చ్ నుండి తొలగించండి
- మొదటి సారి npm install మరియు Vite build స్పష్టంగా నడవడానికి బిల్డ్ ప్రక్రియలు కొంచెం ఆలస్యంగా ఉండొచ్చు

## Security Considerations

### Environment Variables

- API కీలు రిపాజిటరీలో ఎప్పుడూ కమిట్ చెయ్యకూడదు
- `.env` ఫైల్స్ వాడండి (ఇవి `.gitignore`లో ఉన్నాయి)
- అవసరమయిన ఎన్‌విరాన్‌మెంట్ వేరియబుల్స్ ప్రాజెక్ట్ README లలో వర్ణించండి

### Python Projects

- వర్చువల్ ఎన్విరాన్మెంట్లు ఉపయోగించండి: `python -m venv venv`
- డిపెండెన్సీలను తాజా గా ఉంచండి
- GitHub టోకెన్లు తక్కువ అనుమతులు కలిగి ఉండాలి

### GitHub Models Access

- GitHub Models కు Personal Access Tokens (PAT) అవసరం
- టోకెన్లు ఎన్‌విరాన్‌మెంట్ వేరియబుల్స్ గా భద్రపరచండి
- టోకెన్లు లేదా క్రెడెన్షియల్స్ ఎప్పుడూ కమిట్ చేయవద్దు

## Additional Notes

### Target Audience

- వెబ్ అభివృద్ధిలో పూర్తి కొత్త వారు
- విద్యార్థులు మరియు స్వీయాధ్యయనకర్తలు
- తరగతి గదుల్లో పాఠ్యక్రమాన్ని ఉపయోగించే ఉపాధ్యాయులు
- కంటెంట్ ఆక్సెసిబిలిటీ మరియు మాటిమీద నెమ్మదిగా నైపుణ్యాలు పెంపొందించేందుకు రూపొద్దు

### Educational Philosophy

- ప్రాజెక్ట్-ఆధారిత నేర్చుకునే విధానం
- తరచుగా నాలెడ్జ్ చెక్స్ (క్విజ్‌లు)
- అమలు చేయగలిగే కోడింగ్ వ్యాయామాలు
- వాస్తవ ప్రపంచ అనువర్తన ఉదాహరణలు
- ఫ్రేమ్‌వర్క్‌ల ముందు ప్రాథమికాంశాలపై దృష్టి

### Repository Maintenance

- సజీవ కమ్యూనిటీ విద్యార్థులు మరియు సహకారకులతో
- ఆపరేషన్లు మరియు కంటెంట్ సాధారణంగా నవీకరణలు
- నిర్వహకులు ఇష్యూలు మరియు చర్చలను పర్యవేక్షిస్తారు
- అనువాద నవీకరణలు GitHub Actions ద్వారా స్వయంచాలకమే

### Related Resources

- [Microsoft Learn modules](https://docs.microsoft.com/learn/)
- [Student Hub resources](https://docs.microsoft.com/learn/student-hub/)
- [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) నేర్చుకునే వారికి సిఫారసు
- అదనపు కోర్సులు: జనరేటివ్ AI, డేటా సైన్స్, ML, IoT పాఠ్యక్రమాలు అందుబాటులో

### Working with Specific Projects

ప్రత్యేక ప్రాజెక్టుల వివరాలకు 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 చాట్ అసిస్టెంట్ ప్రాజెక్ట్

### Monorepo Structure

ఇది సంప్రదాయ మోనోరిపో కానప్పటికీ, ఈ సంకలనం అనేక స్వతంత్ర ప్రాజెక్టులను కలిగి ఉంది:
- ప్రతి పాఠం స్వతంత్రంగా ఉంటుంది
- ప్రాజెక్టులు ఒకరితో ఒకరు డిపెండెన్సీలు పంచుకోరువు
- ఇతరులపై ప్రభావం లేకుండా వ్యక్తిగత ప్రాజెక్టులపై పని చేయండి
- మొత్తం పాఠ్యక్రమ అనుభవం కోసం మొత్తం రిపాజిటరీ ని క్లోన్ చేయండి

---

<!-- CO-OP TRANSLATOR DISCLAIMER START -->
**గుర్తింపు**:  
ఈ పత్రం AI అనువాద సేవ [Co-op Translator](https://github.com/Azure/co-op-translator) ఉపయోగించి అనువదించబడింది. మనం ఖచ్చితత్వం కోసం ప్రయత్నించినప్పటికీ, ఆటోమేటెడ్ అనువాదాల్లో పొరపాట్లు లేదా తప్పిదాలు ఉండవచ్చు అని దయచేసి గమనించండి. మూల పత్రం దాని స్వదేశీ భాషలోనే అధికారిక మూలంగా పరిగణించాలి. కీలకమైన సమాచారానికి, వృత్తిపరమైన మానవ అనువాదాన్ని సిఫార్సు చేస్తాము. ఈ అనువాదం వలన సాధ్యమైన ఏవైనా అపార్థాలు లేదా తప్పుల బాధ్యత మేము వహించము.
<!-- CO-OP TRANSLATOR DISCLAIMER END -->