मुख्य कंटेंट तक स्किप करें

ज्ञात आश्चर्यजनक बातें

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

प्रविष्टि के मानदंड​

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

  • यह इसी रिपॉज़िटरी से जुड़ी हो (सामान्य सलाह न हो)।
  • आगे आने वाले एजेंट के साथ इसके दोहराए जाने की संभावना हो।
  • इसका कोई ठोस उपाय हो जिसका पालन किया जा सके।

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

प्रविष्टि टेम्पलेट​

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

प्रविष्टियाँ​

Vercel ऐप के प्रोडक्शन डोमेन वापस Git master डिप्लॉयमेंट पर खिसक सकते हैं​

  • दिनांक: 2026-04-28
  • किसने देखा: Tommaso + Codex
  • संदर्भ: Bitsocial Web ऐप डायरेक्ट्री में Seedit और 5chan ऐप मिरर की जाँच।
  • क्या आश्चर्यजनक था: Vercel के seedit और 5chan प्रोजेक्ट में gitProviderOptions.createDeployments = "enabled" था, इसलिए GitHub master पुश प्रोडक्शन डोमेन पर प्रमोट हो जाते थे, जबकि रिपॉज़िटरी की नीति यह अपेक्षा करती है कि प्रोडक्शन ऐप मिरर केवल रिलीज़ आर्टिफ़ैक्ट सर्व करें।
  • प्रभाव: ऐप डायरेक्ट्री के सत्यापित-मिरर बैज गलत हो सकते हैं, क्योंकि प्रोडक्शन डोमेन उस GitHub रिलीज़ ZIP के बजाय नवीनतम डेवलपमेंट कमिट सर्व करते हैं जिसके index.html का हैश about/src/lib/apps-data.ts में दर्ज है।
  • उपाय: मिरर सत्यापन मेटाडेटा जोड़ने या ताज़ा करने से पहले vercel api /v9/projects/<project-id> से Vercel प्रोजेक्ट जाँचें और पुष्टि करें कि gitProviderOptions.createDeployments = "disabled" है। रिलीज़ ZIP की सामग्री vercel deploy --prebuilt --prod से डिप्लॉय करें और डेवलपमेंट डिप्लॉयमेंट के लिए seedit-omega.vercel.app या 5chan-omega.vercel.app इस्तेमाल करें।
  • स्थिति: पुष्ट

Portless 0.11 पुरानी प्रॉक्सी स्थिति दोबारा इस्तेमाल कर लेता है, जब तक लॉन्चर HTTPS बाध्य न करे​

  • दिनांक: 2026-04-28
  • किसने देखा: Tommaso + Codex
  • संदर्भ: सामान्य yarn start फ़्लो को पुराने http://bitsocial.localhost:1355 प्रॉक्सी URL से नए URL पर अपग्रेड करना: https://bitsocial.localhost.
  • क्या आश्चर्यजनक था: portless@0.11.1 इंस्टॉल होने के बावजूद Portless ने मौजूदा ~/.portless/proxy.port = 1355 HTTP प्रॉक्सी को ही दोबारा इस्तेमाल किया और पुराना :1355 URL छापा।
  • प्रभाव: पैकेज संस्करण और दस्तावेज़ अपडेट करना काफ़ी नहीं है; अगर किसी योगदानकर्ता के यहाँ पुरानी Portless स्थिति चल रही हो, तो yarn start अब भी पुराना URL दिखा और इस्तेमाल कर सकता है।
  • उपाय: स्टार्ट स्क्रिप्ट से ऐप रूट रजिस्टर करने से पहले Portless HTTPS प्रॉक्सी को पोर्ट 443 पर स्पष्ट रूप से शुरू करवाते रहें, ताकि रनटाइम फ़्लो सहेजी हुई 1355 स्थिति को विरासत में लेने के बजाय उससे आगे बढ़ जाए।
  • स्थिति: पुष्ट

Portless कैनोनिकल लोकल ऐप URL बदल देता है​

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

Commitizen हुक नॉन-इंटरैक्टिव कमिट रोक देते हैं​

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

Yarn classic से बचने के लिए Corepack ज़रूरी है​

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

तय Portless ऐप नाम Bitsocial Web वर्कट्री के बीच टकराते हैं​

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

डॉक्स प्रीव्यू में पहले पोर्ट 3001 हार्ड-कोडेड था​

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

तय डॉक्स Portless होस्टनेम हार्ड-कोडेड था​

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

वर्कट्री शेल रिपॉज़िटरी के पिन किए गए Node संस्करण से चूक सकते हैं​

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

docs-site/ के बचे-खुचे हिस्से रिफ़ैक्टर के बाद गायब डॉक्स सोर्स को छिपा सकते हैं​

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

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

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

translate-docs.py डॉक्स लोकेल को आधा-अनूदित या टूटे लिंक टारगेट के साथ छोड़ सकती है​

  • दिनांक: 2026-04-06
  • किसने देखा: Codex
  • संदर्भ: yarn start:docs द्वारा अंग्रेज़ी डिटेल पेज सर्व करने या लोकेल आउटपुट बिल्ड न कर पाने के बाद स्थानीयकृत डॉक्स रूट और सामग्री ठीक करना
  • क्या आश्चर्यजनक था: डॉक्स अनुवाद पाइपलाइन में एक साथ दो रिपॉज़िटरी-विशिष्ट विफलता मोड मौजूद थे: scripts/translate-docs.py DocsHome के केवल थोड़े से संदेश निकालती थी जब tr(...) कॉल ऐसे रूपों में लिखे हों जिन्हें वह पार्स नहीं करती, और docs/i18n/** के अंतर्गत अनूदित मार्कडाउन में लिंक टारगेट के भीतर मशीन-अनूदित स्लग या ZXQPLACEHOLDER अवशेष हो सकते थे।
  • प्रभाव: स्थानीयकृत होमपेज चुपचाप अंग्रेज़ी पर लौट सकते हैं, स्थानीयकृत डिटेल पेज बिना अनुवाद के दिख सकते हैं, और सोर्स डॉक्स सही होने के बावजूद पूरा yarn docs:build टूटे लोकेल लिंक पर विफल हो सकता है।
  • उपाय: डॉक्स अनुवाद बदलने या लोकेल फ़ाइलें दोबारा बनाने के बाद हमेशा रिपॉज़िटरी रूट से yarn docs:build चलाएँ, docs/i18n/** के मार्कडाउन में ZXQPLACEHOLDER खोजें, और सत्यापित करें कि अनूदित लिंक अब भी /apps/5chan/ जैसे कैनोनिकल डॉक स्लग की ओर इशारा करते हैं, न कि अनूदित URL पथों की ओर। अगर DocsHome की कॉपी बदली हो, तो पुष्टि करें कि scripts/translate-docs.py अब भी सभी docs.home.* संदेश निकालती है।
  • स्थिति: पुष्ट

About साइट की no-JS जाँच Portless रूट पर होनी चाहिए, अलग SSR प्रीव्यू पर नहीं​

  • दिनांक: 2026-04-12
  • किसने देखा: Codex
  • संदर्भ: किसी ब्रांच वर्कट्री से about/ साइट के no-JS समर्थन की जाँच
  • क्या आश्चर्यजनक था: एक अलग SSR प्रीव्यू भला-चंगा दिख सकता है, जबकि असली ब्रांच-स्कोप्ड Portless रूट अब भी गलत ऐप शेल या कोई पुरानी प्रक्रिया सर्व कर रहा हो। इस रिपॉज़िटरी में असली लोकल अनुबंध yarn start से मिलने वाला Portless होस्टनेम है, कोई तदर्थ प्रीव्यू सर्वर नहीं।
  • प्रभाव: एजेंट गलती से दावा कर सकते हैं कि no-JS समर्थन काम करता है, या ऐसे रिग्रेशन चूक सकते हैं जो केवल *.bitsocial.localhost पर दिखते हैं।
  • उपाय: about/ की ब्राउज़र जाँच के लिए हमेशा yarn start या yarn start:about से असली लोकल सर्वर शुरू करें और पहले ब्रांच-स्कोप्ड Portless URL पर परीक्षण करें। अगर कोई Portless होस्टनेम बासी लगे, तो दोबारा परीक्षण से पहले पुरानी प्रक्रिया की जाँच करके उसे बंद करें।
  • स्थिति: पुष्ट

chain/ yarn build:verify और yarn doctor को दिखाई ही नहीं देता था​

  • दिनांक: 2026-07-05
  • किसने देखा: Codex
  • संदर्भ: मोनोरेपो में chain/ वर्कस्पेस (chain.bitsocial.net के लिए स्टैंडअलोन Vite ऐप) जुड़ने के बाद केवल chain/ वाले डिफ़ की जाँच।
  • क्या आश्चर्यजनक था: scripts/verify-build.mjs केवल about/, docs/ और stats/ पथ-उपसर्गों को पहचानती थी, इसलिए केवल chain/ वाला डिफ़ "No targeted build checks matched the current diff" छापता था और कोई बिल्ड चलाता ही नहीं था, जबकि रूट package.json में build:chain पहले से मौजूद था। इससे अलग, yarn doctor react-doctor about -y पर हार्ड-कोडेड था, इसलिए chain/src के अंतर्गत React बदलावों को React Doctor की कोई कवरेज नहीं मिलती थी।
  • प्रभाव: chain बदलाव जाँचने वाले एजेंट को यह जानना ज़रूरी था कि yarn build:verify पर भरोसा करने के बजाय सीधे yarn build:chain चलाना है, और chain/src में React समस्याएँ (इफ़ेक्ट, हुक, डेड कोड) yarn doctor की पकड़ में नहीं आती थीं।
  • उपाय: scripts/verify-build.mjs में अब about/ वाली शाखा जैसी ही एक chain/ शाखा है, और doctor तथा doctor:verbose अब एक ही इनवोकेशन में react-doctor --project about,chain -y चलाते हैं। doctor:score केवल about तक सीमित रहता है, क्योंकि एक से ज़्यादा प्रोजेक्ट वाले --project के साथ मिलाने पर --score चुपचाप कुछ नहीं छापता; अगर chain का स्कोर चाहिए तो yarn react-doctor --project about,chain --verbose -y (या --json) इस्तेमाल करें।
  • स्थिति: पुष्ट

ब्राउज़र P2P सुरक्षित WebSockets पर चलता है; pkc-js डिफ़ॉल्ट रूप से WebRTC और WebTransport को मना कर देता है​

  • दिनांक: 2026-08-02
  • किसने देखा: Claude
  • संदर्भ: Bitsocial का ब्राउज़र P2P कैसे काम करता है, इस पर लैंडिंग-पेज और डॉक्स कॉपी लिखना
  • क्या आश्चर्यजनक था: @pkcprotocol/pkc-js एक डिफ़ॉल्ट कनेक्शन गेटर के साथ आता है जो ब्राउज़र में WebRTC और WebTransport डायल अस्वीकार करता है — dist/browser/helia/dial-transport-filter.js DENIED_DIAL_TRANSPORTS_BY_DEFAULT = ["webrtc", "webrtc-direct", "webtransport"] एक्सपोर्ट करती है। इसके सोर्स कमेंट में कारण भी दिया है: ब्राउज़र में ये ट्रांसपोर्ट लंबे और अक्सर विफल होने वाले कनेक्शन-स्थापना पथ (STUN/ICE, certhash रोटेशन) जोड़ते हैं जो लोडिंग धीमी करते हैं, जबकि WebSocket सीधा और भरोसेमंद है। ब्लॉग के P2P स्टेटस पैनल पर हर लाइव पीयर "Secure WebSocket" दिखाता है। यह गेटर node_modules में रहता है, इसलिए रिपॉज़िटरी में इसका कोई संकेत नहीं मिलता।
  • प्रभाव: तकनीकी रूप से भरोसेमंद लगने वाली, पर गलत सार्वजनिक कॉपी लिखना बहुत आसान है — जैसे यह श्रेय देना कि मार्च 2026 में WebTransport के ब्राउज़र Baseline तक पहुँचने से Bitsocial का ब्राउज़र P2P संभव हुआ। डेवलपर के पकड़ने से पहले यह दावा लैंडिंग पेज, तुलना तालिका और दो डॉक्स पेज तक पहुँच चुका था। सार्वजनिक पेजों पर गलत आर्किटेक्चर दावों की जाँच ठीक वही डेवलपर दर्शक करते हैं जिन्हें यह साइट लक्ष्य बनाती है।
  • उपाय: libp2p या ब्राउज़र प्लेटफ़ॉर्म सैद्धांतिक रूप से जो समर्थन करते हैं, उससे कभी यह अनुमान न लगाएँ कि Bitsocial कौन से ट्रांसपोर्ट इस्तेमाल करता है। मौजूदा अस्वीकृति-सूची के लिए node_modules/@pkcprotocol/pkc-js/dist/browser/helia/dial-transport-filter.js जाँचें, पुष्टि करें कि about/src/ के अंतर्गत कोई connectionGater ओवरराइड मौजूद नहीं है, और कोई भी सार्वजनिक दावा करने से पहले ब्लॉग के "P2P status" पैनल में लाइव ट्रांसपोर्ट लेबल पढ़ें। जिस अपस्ट्रीम बदलाव ने असल में ब्राउज़र से पब्लिश करना संभव बनाया, वह @libp2p/gossipsub 15.0.21 (मई 2026) में आया gossipsub मोनोटोनिक-seqno फ़िक्स था; pkc-js फ़िलहाल 16.0.4 शिप करता है।
  • स्थिति: पुष्ट

किसी अनूदित न हुए डॉक्स पेज से सापेक्ष ./page.md लिंक हर स्थानीयकृत बिल्ड को तोड़ देते हैं​

  • दिनांक: 2026-08-02
  • किसने देखा: Claude
  • संदर्भ: एक नया केवल-अंग्रेज़ी पेज docs/browser-p2p.md जोड़ना, जो ./peer-to-peer-protocol.md और ./apps/5chan.md के ज़रिए मौजूदा डॉक्स से जुड़ता था
  • क्या आश्चर्यजनक था: docs/i18n/<lang>/docusaurus-plugin-content-docs/current/ के अंतर्गत हर लोकेल डॉक्स ट्री की नकल रखता है। इन मिरर में अनुपस्थित नया पेज अंग्रेज़ी फ़ॉलबैक के ज़रिए हर लोकेल में रेंडर तो होता है, लेकिन उसके सापेक्ष मार्कडाउन लिंक अब रिज़ॉल्व नहीं होते — Docusaurus /ar/browser-p2p/peer-to-peer-protocol.md/ उत्सर्जित करता है और "Docusaurus found broken links!" के साथ बिल्ड विफल कर देता है। अहम बात यह है कि yarn build:verify और yarn docs:build:verify केवल en बिल्ड करते हैं और साफ़-सुथरे पास हो जाते हैं; यह समस्या केवल पूरे yarn docs:build में सामने आती है, और वह वर्णक्रम में पहले लोकेल (ar) पर ही रुक जाता है।
  • प्रभाव: कोई डॉक्स बदलाव हर तेज़ लोकल जाँच पास कर सकता है और फिर भी प्रोडक्शन का मल्टीलोकेल बिल्ड तोड़ सकता है। विफलता बदलाव से असंबंधित भी लगती है, क्योंकि त्रुटि ऐसे लोकेल पथ का नाम लेती है जिसे लेखक ने कभी छुआ ही नहीं।
  • उपाय: ऐसे किसी भी डॉक्स पेज में, जो docs/i18n/** में मिरर नहीं किया गया है, सापेक्ष .md लिंक के बजाय रूट-सापेक्ष लिंक (/peer-to-peer-protocol/, /apps/5chan/) इस्तेमाल करें; Docusaurus उनके आगे लोकेल अपने आप जोड़ देता है। docs/build-your-own-client.md इसका मौजूदा उदाहरण है। डॉक्स पेज जोड़ने या लिंक करने वाला कोई भी बदलाव सौंपने से पहले पूरा yarn docs:build चलाएँ — केवल build:verify नहीं।
  • स्थिति: पुष्ट

update-translations.js को about/ से चलाना ज़रूरी है, और समानांतर रन चुपचाप कीज़ खो देते हैं​

  • दिनांक: 2026-08-02
  • किसने देखा: Claude
  • संदर्भ: translate स्किल के ज़रिए सभी 36 लोकेल में 26 अनूदित i18next कीज़ लागू करना
  • क्या आश्चर्यजनक था: एक ही स्क्रिप्ट में दो अलग-अलग जाल। पहला, scripts/update-translations.js अपना लक्ष्य path.join(process.cwd(), "public", "translations") के रूप में रिज़ॉल्व करती है, पर यह रिपॉज़िटरी अनुवाद about/public/translations में रखती है। रिपॉज़िटरी रूट से दस्तावेज़ में दिया गया कमांड चलाने पर हर बार "Translations directory not found" के साथ विफलता मिलती है — docs/agent-playbooks/translations.md में node scripts/update-translations.js ... दिखाया गया है, जो रिपॉज़िटरी-रूट कमांड जैसा पढ़ा जाता है। दूसरा, हर इनवोकेशन सभी 36 लोकेल फ़ाइलों पर एक रीड-मॉडिफ़ाई-राइट है, इसलिए एक साथ चल रहे दो इनवोकेशन एक-दूसरे को मिटा देते हैं और एक की बिना किसी त्रुटि के गायब हो जाती है। translate स्किल स्पष्ट रूप से एक साथ 4 सबएजेंट तक चलाने को कहती है, और उनमें से हर एक इसी स्क्रिप्ट को कॉल करेगा।
  • प्रभाव: रिपॉज़िटरी-रूट वाला रूप ज़ोर-शोर से विफल होता है और एक पूरा पास बर्बाद कर देता है। समानांतरता वाली समस्या चुपचाप विफल होती है: कीज़ मनमाने लोकेल से गायब हो जाती हैं, और डिफ़ फिर भी भरोसेमंद दिखता है।
  • उपाय: इसे cd about && node ../scripts/update-translations.js --key <key> --map <abs-path> --write के रूप में चलाएँ। अनुवादक सबएजेंट को लोकेल फ़ाइलें कभी समानांतर में न लिखने दें — उनसे केवल डिक्शनरी JSON फ़ाइलें बनवाएँ, फिर पैरेंट एजेंट से हर की को क्रम से लागू करें। लागू करने के बाद प्रोग्राम से सत्यापित करें कि हर की सभी 35 गैर-अंग्रेज़ी लोकेल में मौजूद है और कोई भी मान अंग्रेज़ी सोर्स के बाइट-दर-बाइट समान नहीं है।
  • स्थिति: पुष्ट