مرکزی مواد پر جائیں۔

معلوم حیران کن باتیں

یہ فائل اس ریپوزٹری سے مخصوص اُن اُلجھن کے مقامات کا ریکارڈ رکھتی ہے جن کی وجہ سے ایجنٹوں سے غلطیاں ہوئیں۔

اندراج کا معیار​

اندراج صرف اُسی صورت میں شامل کریں جب درج ذیل تمام باتیں درست ہوں:

  • یہ اسی ریپوزٹری سے مخصوص ہو (عمومی مشورہ نہ ہو)۔
  • مستقبل کے ایجنٹوں کے ساتھ اس کے دوبارہ پیش آنے کا امکان ہو۔
  • اس کا کوئی ٹھوس تدارک موجود ہو جس پر عمل کیا جا سکے۔

اگر یقین نہ ہو تو اندراج شامل کرنے سے پہلے ڈویلپر سے پوچھ لیں۔

اندراج کا سانچہ​

### [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 فلو کو پرانے پراکسی URL http://bitsocial.localhost:1355 سے اَپ گریڈ کر کے نئے کینونیکل 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 ناکام ہو سکتا تھا حالانکہ اباؤٹ ایپ پہلے ہی جانتی تھی کہ اپنے ہوسٹ نام کے لیے Portless روٹ ٹکراؤ سے کیسے بچنا ہے۔
  • اثر: متوازی ورک ٹریز روٹ ڈیو کمانڈ کو بھروسے سے استعمال نہیں کر سکتے تھے، کیونکہ دستاویزات کا پراسیس پہلے ختم ہو جاتا اور پھر concurrently باقی سیشن کو بھی ختم کر دیتا تھا۔
  • تدارک: دستاویزات کے آغاز کو scripts/start-docs.mjs کے پیچھے رکھیں، جو اب اباؤٹ ایپ جیسا ہی برانچ کے دائرے والا 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.* پیغامات نکالتی ہے۔
  • حیثیت: تصدیق شدہ

اباؤٹ سائٹ کی بغیر JS جانچ Portless روٹ پر ہونی چاہیے، الگ SSR پیش منظر پر نہیں​

  • تاریخ: 2026-04-12
  • مشاہدہ کرنے والا: Codex
  • سیاق و سباق: برانچ ورک ٹری سے about/ سائٹ کے لیے بغیر JS سپورٹ کی تصدیق
  • حیرت کی بات کیا تھی: الگ SSR پیش منظر بظاہر ٹھیک لگ سکتا ہے جب کہ اصل برانچ کے دائرے والا Portless روٹ اب بھی غلط ایپ شیل یا کوئی پرانا پراسیس سرو کر رہا ہو۔ اس ریپو میں اصل مقامی معاہدہ yarn start سے ملنے والا Portless ہوسٹ نام ہے، نہ کہ کوئی عارضی پیش منظر سرور۔
  • اثر: ایجنٹ غلط طور پر دعویٰ کر سکتے ہیں کہ بغیر 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 میں رہتا ہے، اس لیے ریپو میں کہیں اس کا اشارہ تک نہیں ملتا۔
  • اثر: تکنیکی طور پر قابلِ یقین مگر غلط عوامی عبارت لکھنا بہت آسان ہے — مثلاً یہ کہنا کہ Bitsocial کا براؤزر P2P اس لیے ممکن ہوا کہ WebTransport مارچ 2026 میں براؤزر Baseline تک پہنچ گیا۔ ڈویلپر کے پکڑنے سے پہلے یہ دعویٰ لینڈنگ پیج، موازنے کے جدول اور دو دستاویزاتی صفحات تک پہنچ چکا تھا۔ عوامی صفحات پر آرکیٹیکچر کے غلط دعوے بالکل اُسی ڈویلپر سامعین کی نظر سے گزرتے ہیں جنہیں یہ سائٹ ہدف بناتی ہے۔
  • تدارک: یہ کبھی نہ سمجھیں کہ Bitsocial کون سے ٹرانسپورٹس استعمال کرتا ہے، محض اس بنیاد پر کہ libp2p یا براؤزر پلیٹ فارم اصولاً کن کی حمایت کرتا ہے۔ موجودہ انکار کی فہرست کے لیے node_modules/@pkcprotocol/pkc-js/dist/browser/helia/dial-transport-filter.js دیکھیں، تصدیق کریں کہ about/src/ کے تحت کوئی connectionGater اوور رائیڈ موجود نہیں، اور کوئی بھی عوامی دعویٰ کرنے سے پہلے بلاگ کے "P2P status" پینل میں ٹرانسپورٹ کے زندہ لیبل پڑھیں۔ اصل میں براؤزر سے پبلشنگ کی راہ کھولنے والی اَپ اسٹریم تبدیلی @libp2p/gossipsub 15.0.21 (مئی 2026) میں gossipsub کے monotonic-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 اس کی موجود مثال ہے۔ کوئی بھی ایسی تبدیلی حوالے کرنے سے پہلے جو دستاویزی صفحہ شامل کرتی ہو یا اس سے لنک کرتی ہو، صرف build:verify نہیں بلکہ پورا yarn docs:build چلائیں۔
  • حیثیت: تصدیق شدہ

update-translations.js کو about/ سے چلانا ضروری ہے، اور بیک وقت چلنے والے رنز خاموشی سے کیز گنوا دیتے ہیں​

  • تاریخ: 2026-08-02
  • مشاہدہ کرنے والا: Claude
  • سیاق و سباق: translate اسکل کے ذریعے 26 ترجمہ شدہ i18next کیز کو تمام 36 لوکیلز پر لاگو کرنا
  • حیرت کی بات کیا تھی: ایک ہی اسکرپٹ میں دو الگ الگ پھندے۔ پہلا، 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 غیر انگریزی لوکیلز میں موجود ہے اور کوئی ویلیو انگریزی سورس سے بائٹ در بائٹ یکساں نہیں۔
  • حیثیت: تصدیق شدہ