স্কিপ করে মূল কন্টেন্ট এ যান

পরিচিত বিস্ময়

এই ফাইলে সেই রিপোজিটরি-নির্দিষ্ট বিভ্রান্তির জায়গাগুলো লিপিবদ্ধ থাকে যেগুলো এজেন্টদের ভুলের কারণ হয়েছে।

এন্ট্রি যোগ করার মানদণ্ড​

নিচের সবগুলো সত্য হলে তবেই একটি এন্ট্রি যোগ করুন:

  • এটি কেবল এই রিপোজিটরির ক্ষেত্রেই প্রযোজ্য (সাধারণ পরামর্শ নয়)।
  • ভবিষ্যতের এজেন্টদের ক্ষেত্রেও এটি আবার ঘটার সম্ভাবনা আছে।
  • এর একটি সুনির্দিষ্ট প্রতিকার আছে, যা অনুসরণ করা সম্ভব।

সন্দেহ থাকলে এন্ট্রি যোগ করার আগে ডেভেলপারকে জিজ্ঞাসা করুন।

এন্ট্রি টেমপ্লেট​

### [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-এর বদলে সর্বশেষ ডেভেলপমেন্ট কমিট পরিবেশন করে, অথচ about/src/lib/apps-data.ts-এ ওই ZIP-এর index.html হ্যাশই লিপিবদ্ধ থাকে।
  • প্রতিকার: মিরর যাচাইয়ের মেটাডেটা যোগ বা হালনাগাদ করার আগে vercel api /v9/projects/<project-id> দিয়ে Vercel প্রজেক্টটি দেখে নিন এবং gitProviderOptions.createDeployments = "disabled" আছে কি না নিশ্চিত করুন। রিলিজ ZIP-এর বিষয়বস্তু vercel deploy --prebuilt --prod দিয়ে ডিপ্লয় করুন এবং ডেভেলপমেন্ট ডিপ্লয়মেন্টের জন্য seedit-omega.vercel.app বা 5chan-omega.vercel.app ব্যবহার করুন।
  • অবস্থা: নিশ্চিত

লঞ্চার HTTPS বাধ্যতামূলক না করলে Portless 0.11 পুরোনো প্রক্সি অবস্থাই পুনরায় ব্যবহার করে​

  • তারিখ: 2026-04-28
  • পর্যবেক্ষণ করেছেন: Tommaso + Codex
  • প্রসঙ্গ: সাধারণ yarn start ফ্লোকে পুরোনো http://bitsocial.localhost:1355 প্রক্সি URL থেকে সরিয়ে নেওয়া হচ্ছিল https://bitsocial.localhost.
  • যা অপ্রত্যাশিত ছিল: portless@0.11.1 ইনস্টল থাকা সত্ত্বেও Portless বিদ্যমান ~/.portless/proxy.port = 1355 HTTP প্রক্সিটিই আবার ব্যবহার করত এবং পুরোনো :1355 URL ছাপত।
  • প্রভাব: কেবল প্যাকেজের সংস্করণ ও ডকুমেন্টেশন হালনাগাদ করাই যথেষ্ট নয়; কোনো অবদানকারীর মেশিনে পুরোনো Portless অবস্থা চালু থাকলে yarn start এখনও পুরোনো URL দেখাতে ও ব্যবহার করতে পারে।
  • প্রতিকার: স্টার্ট স্ক্রিপ্টগুলো যেন অ্যাপ রুট নিবন্ধনের আগেই স্পষ্টভাবে 443 পোর্টে Portless HTTPS প্রক্সি চালু করে, সেটি বজায় রাখুন, যাতে রানটাইম ফ্লো সংরক্ষিত 1355 অবস্থা উত্তরাধিকারসূত্রে না নিয়ে সেখান থেকে সরে আসে।
  • অবস্থা: নিশ্চিত

Portless ক্যানোনিকাল স্থানীয় অ্যাপ URL বদলে দেয়​

  • তারিখ: 2026-03-18
  • পর্যবেক্ষণ করেছেন: Codex
  • প্রসঙ্গ: ব্রাউজার যাচাই ও স্মোক ফ্লো
  • যা অপ্রত্যাশিত ছিল: ডিফল্ট স্থানীয় URL চেনা Vite পোর্ট নয়। রেপো Portless-এর মাধ্যমে https://bitsocial.localhost প্রত্যাশা করে, তাই localhost:3000 বা localhost:5173 দেখলে ভুল অ্যাপে গিয়ে পড়া বা কিছুই না পাওয়া হতে পারে।
  • প্রভাব: ডেভ সার্ভার সুস্থভাবে চললেও ব্রাউজার যাচাই ব্যর্থ হতে পারে, কিংবা ভুল টার্গেট যাচাই করতে পারে।
  • প্রতিকার: প্রথমে https://bitsocial.localhost ব্যবহার করুন। সরাসরি কোনো Vite পোর্ট স্পষ্টভাবে দরকার হলে তবেই PORTLESS=0 corepack yarn start দিয়ে সেটি বাইপাস করুন।
  • অবস্থা: নিশ্চিত

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 আগে থেকেই নিবন্ধিত।
  • প্রভাব: Portless যেখানে সমান্তরাল ব্রাঞ্চগুলোকে নিরাপদে পাশাপাশি চলতে দেওয়ার জন্য তৈরি, সেখানে সমান্তরাল Bitsocial Web ব্রাঞ্চ একে অপরকে আটকে দিতে পারে।
  • প্রতিকার: 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/-এ সরে যাওয়ার পরেও পুরোনো docs-site/ ফোল্ডারটি ডিস্কে থেকে যেতে পারে, সঙ্গে i18n/-এর মতো বাসি অথচ গুরুত্বপূর্ণ ফাইলও। এতে স্থানীয়ভাবে রিফ্যাক্টরটিকে দ্বিগুণ মনে হয়, আর এটি আড়ালও করে দিতে পারে যে ট্র্যাক করা ডক্স অনুবাদগুলো আসলে 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 ইংরেজি বিস্তারিত পৃষ্ঠা পরিবেশন করার বা লোকেল আউটপুট বিল্ড করতে ব্যর্থ হওয়ার পরে স্থানীয়কৃত ডক্স রুট ও কনটেন্ট ঠিক করা
  • যা অপ্রত্যাশিত ছিল: ডক্স অনুবাদ পাইপলাইনে এই রেপো-নির্দিষ্ট দুটি ব্যর্থতা একসঙ্গে ছিল: tr(...) কল এমন রূপে লেখা হলে যা scripts/translate-docs.py পার্স করতে পারত না, স্ক্রিপ্টটি DocsHome-এর বার্তাগুলোর সামান্য একটি অংশই বের করত; আর docs/i18n/**-এর অনূদিত মার্কডাউনে লিংক টার্গেটের ভেতরেই মেশিন-অনূদিত স্লাগ বা ZXQPLACEHOLDER অবশিষ্টাংশ থাকতে পারত।
  • প্রভাব: স্থানীয়কৃত হোমপেজ নীরবে ইংরেজিতে ফিরে যেতে পারে, স্থানীয়কৃত বিস্তারিত পৃষ্ঠা অনূদিত না হওয়ার মতো দেখাতে পারে, এবং সোর্স ডক্স বৈধ হওয়া সত্ত্বেও পূর্ণ yarn docs:build ভাঙা লোকেল লিংকের কারণে ব্যর্থ হতে পারে।
  • প্রতিকার: ডক্স অনুবাদ বদলানোর বা লোকেল ফাইল পুনরায় তৈরি করার পরে সবসময় রেপো রুট থেকে yarn docs:build চালান, docs/i18n/**-এর মার্কডাউনে ZXQPLACEHOLDER খুঁজে দেখুন, এবং যাচাই করুন যে অনূদিত লিংকগুলো এখনও অনূদিত URL পাথের বদলে /apps/5chan/-এর মতো ক্যানোনিকাল ডক স্লাগেই নির্দেশ করছে। DocsHome-এর কপি বদলে থাকলে নিশ্চিত করুন scripts/translate-docs.py এখনও সব docs.home.* বার্তা বের করছে।
  • অবস্থা: নিশ্চিত

About-সাইটের no-JS যাচাই আলাদা কোনো SSR প্রিভিউ নয়, Portless রুট দিয়েই করতে হবে​

  • তারিখ: 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 হোস্টনেম বাসি মনে হলে পুরোনো প্রসেসটি পরীক্ষা করে থামিয়ে দিন, তারপর আবার পরীক্ষা করুন।
  • অবস্থা: নিশ্চিত

yarn build:verify ও yarn doctor-এর চোখে chain/ অদৃশ্য ছিল​

  • তারিখ: 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 এর বিদ্যমান উদাহরণ। ডক্স পৃষ্ঠা যোগ করে বা তাতে লিংক করে এমন কোনো পরিবর্তন হস্তান্তরের আগে শুধু build:verify নয়, পূর্ণ yarn docs:build চালান।
  • অবস্থা: নিশ্চিত

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 স্কিল স্পষ্টভাবেই একসঙ্গে চারটি পর্যন্ত সাবএজেন্ট চালাতে বলে, যাদের প্রত্যেকেই এই স্ক্রিপ্টটি ডাকবে।
  • প্রভাব: রেপো-রুট রূপটি সশব্দে ব্যর্থ হয় এবং একটি পুরো পাস নষ্ট করে। সমান্তরালতার সমস্যাটি নীরবে ব্যর্থ হয়: যেকোনো লোকেল থেকে কী হারিয়ে যায়, অথচ ডিফ দেখে সবকিছু যুক্তিসঙ্গতই মনে হয়।
  • প্রতিকার: এটি চালান cd about && node ../scripts/update-translations.js --key <key> --map <abs-path> --write হিসেবে। অনুবাদক সাবএজেন্টদের কখনও একসঙ্গে লোকেল ফাইল লিখতে দেবেন না — তারা কেবল ডিকশনারি JSON ফাইল তৈরি করবে, তারপর প্যারেন্ট এজেন্ট প্রতিটি কী একে একে প্রয়োগ করবে। প্রয়োগের পরে প্রোগ্রাম্যাটিকভাবে যাচাই করুন যে প্রতিটি কী ইংরেজি ছাড়া বাকি 35টি লোকেলেই আছে এবং কোনো মান ইংরেজি সোর্সের সঙ্গে বাইট-সমান নয়।
  • অবস্থা: নিশ্চিত