मुख्य सामग्रीवर जा

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

ही फाइल रेपॉजिटरी-विशिष्ट गोंधळ बिंदूंचा मागोवा घेते ज्यामुळे एजंटच्या चुका झाल्या.

प्रवेशाचे निकष​

सर्व सत्य असल्यासच प्रविष्टी जोडा:

  • हे या भांडारासाठी विशिष्ट आहे (सामान्य सल्ला नाही).
  • भविष्यातील एजंटसाठी त्याची पुनरावृत्ती होण्याची शक्यता आहे.
  • त्यात एक ठोस शमन आहे ज्याचे पालन केले जाऊ शकते.

अनिश्चित असल्यास, एंट्री जोडण्यापूर्वी विकासकाला विचारा.

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

### [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

नोंदी​

पोर्टलेस कॅनॉनिकल स्थानिक ॲप URL बदलते​

  • तारीख: २०२६-०३-१८
  • निरीक्षण: कोडेक्स
  • संदर्भ: ब्राउझर सत्यापन आणि धूर प्रवाह
  • काय आश्चर्यकारक होते: डीफॉल्ट स्थानिक URL नेहमीच्या Vite पोर्ट नाही. रेपोला पोर्टलेसद्वारे https://bitsocial.localhost अपेक्षित आहे, त्यामुळे localhost:3000 किंवा localhost:5173 तपासणे चुकीचे ॲप किंवा काहीही नाही.
  • प्रभाव: ब्राउझर चेक अयशस्वी होऊ शकतात किंवा डेव्ह सर्व्हर निरोगी असताना देखील चुकीचे लक्ष्य प्रमाणित करू शकतात.
  • शमन: प्रथम https://bitsocial.localhost वापरा. जेव्हा तुम्हाला थेट Vite पोर्टची आवश्यकता असेल तेव्हाच PORTLESS=0 corepack yarn start सह बायपास करा.
  • स्थिती: पुष्टी केली

कमिटीझन हुक नॉन-इंटरॅक्टिव्ह कमिट ब्लॉक करतात​

  • तारीख: २०२६-०३-१८
  • निरीक्षण: कोडेक्स
  • संदर्भ: एजंट-चालित कमिट वर्कफ्लो
  • काय आश्चर्यकारक होते: git commit हस्कीद्वारे कमिटीझनला ट्रिगर करते आणि परस्परसंवादी TTY इनपुटची प्रतीक्षा करते, जे नॉन-इंटरॅक्टिव्ह एजंट शेल्स हँग करते.
  • प्रभाव: एजंट सामान्य कमिट दरम्यान अनिश्चित काळासाठी थांबू शकतात.
  • शमन: एजंटने तयार केलेल्या कमिटसाठी git commit --no-verify -m "message" वापरा. मानव अजूनही corepack yarn commit किंवा corepack yarn exec cz वापरू शकतात.
  • स्थिती: पुष्टी केली

यार्न क्लासिक टाळण्यासाठी कोरपॅक आवश्यक आहे​

  • तारीख: 2026-03-19
  • निरीक्षण: कोडेक्स
  • संदर्भ: यार्न ४ वर पॅकेज मॅनेजर स्थलांतर
  • काय आश्चर्यकारक होते: मशीनमध्ये अजूनही PATH वर ग्लोबल यार्न क्लासिक इंस्टॉल आहे, त्यामुळे प्लेन yarn पिन केलेल्या यार्न 4 आवृत्तीऐवजी v1 वर रिझोल्यूशन करू शकते.
  • प्रभाव: विकसक चुकून रेपोच्या पॅकेज-व्यवस्थापक पिनिंगला बायपास करू शकतात आणि भिन्न इंस्टॉल वर्तन किंवा लॉकफाइल आउटपुट मिळवू शकतात.
  • शमन: शेल कमांडसाठी corepack yarn ... वापरा किंवा प्रथम corepack enable चालवा जेणेकरून साधा yarn पिन केलेल्या यार्न 4 आवृत्तीवर निराकरण करेल.
  • स्थिती: पुष्टी केली

फिक्स्ड पोर्टलेस ॲपची नावे बिटसोशियल वेब वर्कट्रीजवर टक्कर देतात​

  • तारीख: २०२६-०३-३०
  • निरीक्षण: कोडेक्स
  • संदर्भ: एका बिटसोशियल वेब वर्कट्रीमध्ये yarn start सुरू करत आहे तर दुसरे वर्कट्री आधीच पोर्टलेसद्वारे सेवा देत आहे
  • काय आश्चर्यकारक होते: प्रत्येक वर्कट्रीमध्ये अक्षरशः पोर्टलेस ॲप नाव bitsocial वापरल्याने मार्ग स्वतःच आदळतो, जरी बॅकिंग पोर्ट भिन्न असले तरीही, दुसरी प्रक्रिया अयशस्वी झाली कारण bitsocial.localhost आधीच नोंदणीकृत आहे.
  • प्रभाव: समांतर बिटसोशियल वेब शाखा एकमेकांना ब्लॉक करू शकतात जरी पोर्टलेस त्यांना सुरक्षितपणे एकत्र राहू देण्यासाठी आहे.
  • शमन: पोर्टलेस स्टार्टअपला scripts/start-dev.mjs च्या मागे ठेवा, जे आता कॅनॉनिकल केसच्या बाहेर शाखा-स्कोप असलेला *.bitsocial.localhost मार्ग वापरते आणि जेव्हा उघडे bitsocial.localhost नाव आधीच व्यापलेले असते तेव्हा शाखा-स्कोप असलेल्या मार्गावर परत येते.
  • स्थिती: पुष्टी केली

हार्ड-कोड पोर्ट 3001 साठी वापरलेले डॉक्स पूर्वावलोकन​

  • तारीख: २०२६-०३-३०
  • निरीक्षण: कोडेक्स
  • संदर्भ: इतर स्थानिक रेपो आणि एजंटसह yarn start चालवणे
  • काय आश्चर्यकारक होते: रूट dev कमांडने docusaurus start --port 3001 सह डॉक्स वर्कस्पेस चालवले, त्यामुळे जेव्हा मुख्य ॲप आधीच पोर्टलेस वापरत असला तरीही, 3001 च्या मालकीच्या दुसऱ्या प्रक्रियेच्या मालकीचे संपूर्ण डेव्ह सत्र अयशस्वी झाले.
  • प्रभाव: yarn start वेब प्रक्रिया बूट झाल्यानंतर लगेचच नष्ट करू शकते, डॉक्स-पोर्ट टक्करमुळे असंबंधित स्थानिक कामात व्यत्यय आणू शकते.
  • शमन: डॉक्स स्टार्टअपला yarn start:docs च्या मागे ठेवा, जे आता पोर्टलेस प्लस scripts/start-docs.mjs वापरते इंजेक्टेड फ्री पोर्टचा सन्मान करण्यासाठी किंवा थेट रन केल्यावर पुढील उपलब्ध पोर्टवर परत येते.
  • स्थिती: पुष्टी केली

निश्चित डॉक्स पोर्टलेस होस्टनाव हार्ड-कोड केलेले होते​

  • तारीख: २०२६-०४-०३
  • निरीक्षण: कोडेक्स
  • संदर्भ: दुय्यम बिटसोशियल वेब वर्कट्रीमध्ये yarn start चालवत असताना दुसरी वर्कट्री आधीच पोर्टलेसद्वारे डॉक्स सेवा देत होती
  • काय आश्चर्यकारक होते: start:docs ने अद्याप अक्षरशः docs.bitsocial.localhost होस्टनाव नोंदणीकृत केले आहे, त्यामुळे yarn start अयशस्वी होऊ शकते जरी ॲपला त्याच्या स्वतःच्या होस्टनावासाठी पोर्टलेस मार्ग टक्कर कशी टाळायची हे आधीच माहित असले तरीही.
  • प्रभाव: समांतर वर्कट्रीज रूट डेव्ह कमांडचा विश्वासार्हपणे वापर करू शकले नाहीत कारण डॉक्स प्रक्रिया प्रथम बाहेर पडली आणि नंतर concurrently ने उर्वरित सत्र नष्ट केले.
  • शमन: दस्तऐवज स्टार्टअपला scripts/start-docs.mjs च्या मागे ठेवा, जे आता ॲप प्रमाणेच शाखा-स्कोप असलेले पोर्टललेस होस्टनाव मिळवते आणि /docs डेव्ह प्रॉक्सी लक्ष्यात सार्वजनिक URL सामायिक करते.
  • स्थिती: पुष्टी केली

वर्कट्री शेल्स रेपोची पिन केलेली नोड आवृत्ती चुकवू शकतात​

  • तारीख: २०२६-०४-०३
  • निरीक्षण: कोडेक्स
  • संदर्भ: Git वर्कट्रीजमध्ये .claude/worktrees/* किंवा सिबलिंग वर्कट्री चेकआउट्समध्ये yarn start चालवणे
  • काय आश्चर्यकारक होते: काही वर्कट्री शेलने node आणि yarn node ते Homebrew नोड 25.2.1 सोडवले जरी रेपो .nvmrc मध्ये 22.12.0 पिन करत असले तरी .nvmrc 5 सिलेक्रॉईड रन करू शकतात. चुकीच्या रनटाइम अंतर्गत लॉन्चर.
  • प्रभाव: देव-सर्व्हर वर्तन मुख्य चेकआउट आणि वर्कट्रीज दरम्यान वाहून जाऊ शकते, ज्यामुळे बग पुनरुत्पादित करणे कठीण होते आणि रेपोच्या अपेक्षित नोड 22 टूलचेनचे उल्लंघन होते.
  • शमन: डेव्ह लाँचर scripts/start-dev.mjs आणि scripts/start-docs.mjs च्या मागे ठेवा, जे आता .nvmrc नोड बायनरी अंतर्गत चालू शेल चुकीच्या आवृत्तीवर असताना पुन्हा कार्यान्वित होतात. शेल सेटअपने तरीही nvm use ला प्राधान्य दिले पाहिजे.
  • स्थिती: पुष्टी केली

docs-site/ शिल्लक रिफॅक्टर नंतर गहाळ डॉक्स स्त्रोत लपवू शकतात​

  • तारीख: २०२६-०४-०१
  • निरीक्षण: कोडेक्स
  • संदर्भ: डॉकसॉरस प्रकल्प docs-site/ वरून docs/ वर हलवल्यानंतर विलीन झाल्यानंतर मोनोरेपो क्लीनअप
  • काय आश्चर्यकारक होते: ट्रॅक केलेले रेपो docs/ वर हलवल्यानंतरही जुने docs-site/ फोल्डर i18n/ सारख्या जुन्या पण महत्त्वाच्या फाइल्ससह डिस्कवर राहू शकते. यामुळे रिफॅक्टर स्थानिकरित्या डुप्लिकेट केलेला दिसतो आणि ट्रॅक केलेले दस्तऐवज भाषांतरे प्रत्यक्षात docs/ मध्ये हलवली गेली नाहीत हे तथ्य लपवू शकते.
  • प्रभाव: एजंट जुने फोल्डर "जंक" म्हणून हटवू शकतात आणि चुकून दस्तऐवज भाषांतरांची एकमेव स्थानिक प्रत गमावू शकतात किंवा अद्याप मृत docs-site/ मार्गावर दर्शविणारी स्क्रिप्ट संपादित करू शकतात.
  • शमन: docs/ ला एकमेव कॅनॉनिकल डॉक्स प्रकल्प म्हणून हाताळा. कोणतेही स्थानिक docs-site/ उरलेले हटवण्यापूर्वी, docs/i18n/ सारखा ट्रॅक केलेला स्त्रोत पुनर्संचयित करा आणि docs-site संदर्भ देणे थांबवण्यासाठी स्क्रिप्ट आणि हुक अद्यतनित करा.
  • स्थिती: पुष्टी केली

मल्टीलोकल डॉक्स पूर्वावलोकन सत्यापनादरम्यान RAM वाढवू शकते​

  • तारीख: २०२६-०४-०१
  • निरीक्षण: कोडेक्स
  • संदर्भ: yarn start:docs प्लस प्लेराइटसह डॉक्स i18n, लोकेल राउटिंग आणि Pagefind वर्तन निश्चित करणे
  • काय आश्चर्यकारक होते: डीफॉल्ट दस्तऐवज पूर्वावलोकन मोड आता सेवा देण्यापूर्वी संपूर्ण मल्टीलोकल डॉक्स तयार करते आणि पेजफाइंड अनुक्रमणिका बनवते आणि एकाधिक प्लेराइट किंवा क्रोम सत्रांसोबत ती प्रक्रिया जिवंत ठेवल्याने सामान्य विट किंवा सिंगल-लोकेल डॉकसॉरस डेव्ह लूपपेक्षा जास्त RAM वापरता येते.
  • प्रभाव: मशीन मेमरी-संबंधित होऊ शकते, ब्राउझर सत्रे क्रॅश होऊ शकतात आणि व्यत्यय आलेल्या धावांमुळे जुने डॉक्स सर्व्हर किंवा हेडलेस ब्राउझर मागे राहू शकतात जे मेमरी वापरत राहतात.
  • शमन: दस्तऐवज कार्यासाठी ज्यांना लोकेल-रूट किंवा पेजफाइंड पडताळणीची आवश्यकता नाही, DOCS_START_MODE=live yarn start:docs ला प्राधान्य द्या. जेव्हा तुम्हाला भाषांतरित मार्ग किंवा Pagefind सत्यापित करण्याची आवश्यकता असेल तेव्हाच डीफॉल्ट मल्टीलोकेल पूर्वावलोकन वापरा. एकच नाटककार सत्र ठेवा, नवीन उघडण्यापूर्वी जुनी ब्राउझर सत्रे बंद करा आणि पडताळणीनंतर डॉक्स सर्व्हर थांबवा.
  • स्थिती: पुष्टी केली