ज्ञात आश्चर्य

यह फ़ाइल रिपॉजिटरी-विशिष्ट भ्रम बिंदुओं को ट्रैक करती है जो एजेंट की गलतियों का कारण बनती है।

प्रवेश मानदंड

कोई प्रविष्टि तभी जोड़ें जब सभी सत्य हों:

• यह इस भंडार के लिए विशिष्ट है (सामान्य सलाह नहीं)।
• भविष्य के एजेंटों के लिए इसकी पुनरावृत्ति होने की संभावना है।
• इसका एक ठोस शमन है जिसका पालन किया जा सकता है।

यदि अनिश्चित हो, तो प्रविष्टि जोड़ने से पहले डेवलपर से पूछें।

प्रवेश टेम्पलेट

### [Short title]

- **Date:** YYYY-MM-DD
- **Observed by:** agent name or contributor
- **Context:** where/when it happened
- **What was surprising:** concrete unexpected behavior
- **Impact:** what went wrong or could go wrong
- **Mitigation:** exact step future agents should take
- **Status:** confirmed | superseded

प्रविष्टियां

पोर्टलेस कैनोनिकल स्थानीय ऐप यूआरएल को बदलता है

• दिनांक: 2026-03-18
• देखा गया: कोडेक्स
• संदर्भ: ब्राउज़र सत्यापन और धुआं प्रवाह
• क्या आश्चर्य की बात थी: डिफ़ॉल्ट स्थानीय यूआरएल सामान्य वाइट पोर्ट नहीं है। रेपो पोर्टलेस के माध्यम से https://bitsocial.localhost की अपेक्षा करता है, इसलिए localhost:3000 या localhost:5173 की जाँच करने से गलत ऐप या कुछ भी नहीं मिल सकता है।
• प्रभाव: डेव सर्वर स्वस्थ होने पर भी ब्राउज़र जांच विफल हो सकती है या गलत लक्ष्य को मान्य कर सकती है।
• शमन: पहले https://bitsocial.localhost का उपयोग करें। केवल PORTLESS=0 corepack yarn start के साथ इसे बायपास करें जब आपको स्पष्ट रूप से सीधे वाइट पोर्ट की आवश्यकता हो।
• **स्थिति: पुष्टि की गई

कमिटिजन हुक गैर-इंटरैक्टिव कमिट को रोकते हैं

• दिनांक: 2026-03-18
• देखा गया: कोडेक्स
• संदर्भ: एजेंट-संचालित प्रतिबद्ध वर्कफ़्लोज़
• क्या आश्चर्य की बात थी: git commit हस्की के माध्यम से कमिटिजन को ट्रिगर करता है और इंटरैक्टिव TTY इनपुट की प्रतीक्षा करता है, जो गैर-इंटरैक्टिव एजेंट शेल को लटका देता है।
• प्रभाव: एजेंट एक सामान्य प्रतिबद्धता के दौरान अनिश्चित काल तक रुक सकते हैं।
• शमन: एजेंट-निर्मित प्रतिबद्धताओं के लिए git commit --no-verify -m "message" का उपयोग करें। मनुष्य अभी भी corepack yarn commit या corepack yarn exec cz का उपयोग कर सकते हैं।
• **स्थिति: पुष्टि की गई

यार्न क्लासिक से बचने के लिए कोरपैक आवश्यक है

• दिनांक: 2026-03-19
• देखा गया: कोडेक्स
• संदर्भ: पैकेज प्रबंधक का यार्न 4 में स्थानांतरण
• क्या आश्चर्य की बात थी: मशीन में अभी भी PATH पर एक वैश्विक यार्न क्लासिक इंस्टाल है, इसलिए सादा yarn चलाने से पिन किए गए यार्न 4 संस्करण के बजाय v1 का समाधान हो सकता है।
• प्रभाव: डेवलपर्स गलती से रेपो के पैकेज-मैनेजर पिनिंग को बायपास कर सकते हैं और अलग-अलग इंस्टॉल व्यवहार या लॉकफ़ाइल आउटपुट प्राप्त कर सकते हैं।
• शमन: शेल कमांड के लिए corepack yarn ... का उपयोग करें, या पहले corepack enable चलाएं ताकि सादा yarn पिन किए गए यार्न 4 संस्करण में हल हो जाए।
• **स्थिति: पुष्टि की गई

फिक्स्ड पोर्टलेस ऐप नाम बिटसोशल वेब वर्कट्रीज़ में टकराते हैं

• दिनांक: 2026-03-30
• देखा गया: कोडेक्स
• संदर्भ: एक बिटसोशल वेब वर्कट्री में yarn start प्रारंभ करना जबकि दूसरा वर्कट्री पहले से ही पोर्टलेस के माध्यम से सेवा दे रहा था
• क्या आश्चर्य की बात थी: प्रत्येक वर्कट्री में शाब्दिक पोर्टलेस ऐप नाम bitsocial का उपयोग करने से मार्ग स्वयं टकरा जाता है, भले ही बैकिंग पोर्ट अलग-अलग हों, इसलिए दूसरी प्रक्रिया विफल हो जाती है क्योंकि bitsocial.localhost पहले से ही पंजीकृत है।
• प्रभाव: समानांतर बिटसोशल वेब शाखाएं एक-दूसरे को अवरुद्ध कर सकती हैं, भले ही पोर्टलेस का उद्देश्य उन्हें सुरक्षित रूप से सह-अस्तित्व देना है।
• शमन: पोर्टलेस स्टार्टअप को scripts/start-dev.mjs के पीछे रखें, जो अब कैनोनिकल केस के बाहर एक शाखा-स्कोप्ड *.bitsocial.localhost मार्ग का उपयोग करता है और जब नंगे bitsocial.localhost नाम पहले से ही व्याप्त है, तो शाखा-स्कोप्ड मार्ग पर वापस आ जाता है।
• **स्थिति: पुष्टि की गई

डॉक्स पूर्वावलोकन का उपयोग पोर्ट 3001 को हार्ड-कोड करने के लिए किया जाता है

• दिनांक: 2026-03-30
• देखा गया: कोडेक्स
• संदर्भ: अन्य स्थानीय रेपो और एजेंटों के साथ yarn start चलाना
• क्या आश्चर्य की बात थी: रूट डेव कमांड ने डॉक्स वर्कस्पेस को docusaurus start --port 3001 के साथ चलाया, इसलिए जब भी कोई अन्य प्रक्रिया पहले से ही 3001 के स्वामित्व में थी, तो पूरा डेव सत्र विफल हो गया, भले ही मुख्य ऐप पहले से ही पोर्टलेस का उपयोग करता था।
• प्रभाव: yarn start वेब प्रक्रिया को बूट होने के तुरंत बाद बंद कर सकता है, जिससे डॉक्स-पोर्ट टकराव पर असंबंधित स्थानीय कार्य बाधित हो सकता है।
• शमन: डॉक्स स्टार्टअप को yarn start:docs के पीछे रखें, जो अब इंजेक्टेड फ्री पोर्ट का सम्मान करने के लिए पोर्टलेस प्लस scripts/start-docs.mjs का उपयोग करता है या सीधे चलने पर अगले उपलब्ध पोर्ट पर वापस आ जाता है।
• **स्थिति: पुष्टि की गई

फिक्स्ड डॉक्स पोर्टलेस होस्टनाम हार्ड-कोड किया गया था

• दिनांक: 2026-04-03
• देखा गया: कोडेक्स
• संदर्भ: एक द्वितीयक बिटसोशल वेब वर्कट्री में yarn start चला रहा है जबकि एक अन्य वर्कट्री पहले से ही पोर्टलेस के माध्यम से डॉक्स परोस रहा था
• क्या आश्चर्य की बात थी: start:docs ने अभी भी शाब्दिक docs.bitsocial.localhost होस्टनाम पंजीकृत किया है, इसलिए yarn start विफल हो सकता है, भले ही ऐप के बारे में पहले से ही पता था कि अपने स्वयं के होस्टनाम के लिए पोर्टलेस रूट टकराव से कैसे बचा जाए।
• प्रभाव: पैरेलल वर्कट्रीज़ रूट डेव कमांड का विश्वसनीय रूप से उपयोग नहीं कर सका क्योंकि डॉक्स प्रक्रिया पहले बाहर हो गई और concurrently ने शेष सत्र को समाप्त कर दिया।
• शमन: डॉक्स स्टार्टअप को scripts/start-docs.mjs के पीछे रखें, जो अब ऐप के समान शाखा-स्कोप्ड पोर्टलेस होस्टनाम प्राप्त करता है और उस साझा सार्वजनिक यूआरएल को /docs डेव प्रॉक्सी लक्ष्य में इंजेक्ट करता है।
• **स्थिति: पुष्टि की गई

वर्कट्री शेल रेपो के पिन किए गए नोड संस्करण को मिस कर सकते हैं

• दिनांक: 2026-04-03
• देखा गया: कोडेक्स
• संदर्भ: Git वर्कट्रीज़ जैसे .claude/worktrees/* या सिबलिंग वर्कट्री चेकआउट में yarn start चलाना
• क्या आश्चर्य की बात थी: कुछ वर्कट्री शैलों ने node और yarn node को होमब्रू नोड 25.2.1 में हल कर दिया, भले ही रेपो .nvmrc में 22.12.0 को पिन करता है, इसलिए yarn start गलत रनटाइम के तहत चुपचाप डेव लॉन्चर चला सकता है।
• प्रभाव: डेव-सर्वर व्यवहार मुख्य चेकआउट और वर्कट्रीज़ के बीच बहाव कर सकता है, जिससे बग को पुन: उत्पन्न करना कठिन हो जाता है और रेपो की अपेक्षित नोड 22 टूलचेन का उल्लंघन होता है।
• शमन: डेव लॉन्चर्स को scripts/start-dev.mjs और scripts/start-docs.mjs के पीछे रखें, जो अब .nvmrc नोड बाइनरी के तहत फिर से निष्पादित होते हैं जब वर्तमान शेल गलत संस्करण पर होता है। शेल सेटअप को अभी भी nvm use को प्राथमिकता देनी चाहिए।
• **स्थिति: पुष्टि की गई

docs-site/ रिफैक्टर के बाद बचे हुए दस्तावेज़ गायब दस्तावेज़ स्रोत को छिपा सकते हैं

• दिनांक: 2026-04-01
• देखा गया: कोडेक्स
• संदर्भ: डॉक्यूसॉरस प्रोजेक्ट को docs-site/ से docs/ में ले जाने के बाद मर्ज के बाद मोनोरेपो क्लीनअप
• क्या आश्चर्य की बात थी: ट्रैक किए गए रेपो को docs/ में स्थानांतरित करने के बाद भी, पुराना docs-site/ फ़ोल्डर i18n/ जैसी पुरानी लेकिन महत्वपूर्ण फ़ाइलों के साथ डिस्क पर बना रह सकता है। इससे रिफैक्टर स्थानीय रूप से डुप्लिकेट दिखता है और इस तथ्य को छुपा सकता है कि ट्रैक किए गए दस्तावेज़ अनुवाद वास्तव में docs/ में स्थानांतरित नहीं किए गए थे।
• प्रभाव: एजेंट पुराने फ़ोल्डर को "जंक" के रूप में हटा सकते हैं और गलती से डॉक्स अनुवाद की एकमात्र स्थानीय प्रति खो सकते हैं, या उन स्क्रिप्ट को संपादित करना जारी रख सकते हैं जो अभी भी मृत docs-site/ पथ पर इंगित करती हैं।
• शमन: docs/ को एकमात्र विहित दस्तावेज़ प्रोजेक्ट मानें। किसी भी स्थानीय docs-site/ बचे हुए को हटाने से पहले, docs/i18n/ जैसे ट्रैक किए गए स्रोत को पुनर्स्थापित करें और docs-site को संदर्भित करना बंद करने के लिए स्क्रिप्ट और हुक को अपडेट करें।
• **स्थिति: पुष्टि की गई

मल्टीलोकेल डॉक्स पूर्वावलोकन सत्यापन के दौरान रैम को बढ़ा सकता है

• दिनांक: 2026-04-01
• देखा गया: कोडेक्स
• संदर्भ: yarn start:docs प्लस प्लेराइट के साथ डॉक्स i18n, लोकेल रूटिंग और पेजफाइंड व्यवहार को ठीक करना
• क्या आश्चर्य की बात थी: डिफ़ॉल्ट डॉक्स पूर्वावलोकन मोड अब एक पूर्ण मल्टीलोकेल डॉक्स बिल्ड प्लस पेजफाइंड इंडेक्सिंग को परोसने से पहले करता है, और कई प्लेराइट या क्रोम सत्रों के साथ उस प्रक्रिया को जीवित रखने से सामान्य वाइट या सिंगल-लोकेल डॉक्यूसॉरस डेव लूप की तुलना में बहुत अधिक रैम की खपत हो सकती है।
• प्रभाव: मशीन मेमोरी-बाधित हो सकती है, ब्राउज़र सत्र क्रैश हो सकते हैं, और बाधित रन पुराने डॉक्स सर्वर या हेडलेस ब्राउज़र को पीछे छोड़ सकते हैं जो मेमोरी का उपभोग करते रहते हैं।
• शमन: दस्तावेज़ कार्य के लिए जिसे लोकेल-रूट या पेजफ़ाइंड सत्यापन की आवश्यकता नहीं है, DOCS_START_MODE=live yarn start:docs को प्राथमिकता दें। डिफ़ॉल्ट मल्टीलोकेल पूर्वावलोकन का उपयोग केवल तभी करें जब आपको अनुवादित मार्गों या पेजफाइंड को सत्यापित करने की आवश्यकता हो। एक एकल नाटककार सत्र रखें, नए ब्राउज़र खोलने से पहले पुराने ब्राउज़र सत्र बंद करें, और सत्यापन के बाद यदि आपको इसकी आवश्यकता नहीं है तो दस्तावेज़ सर्वर बंद कर दें।
• **स्थिति: पुष्टि की गई