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

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

প্রবেশের মানদণ্ড

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

• এটি এই সংগ্রহস্থলের জন্য নির্দিষ্ট (জেনারিক পরামর্শ নয়)।
• ভবিষ্যতে এজেন্টদের জন্য এটি পুনরাবৃত্তি হওয়ার সম্ভাবনা রয়েছে।
• এটির একটি কংক্রিট প্রশমন রয়েছে যা অনুসরণ করা যেতে পারে।

অনিশ্চিত হলে, একটি এন্ট্রি যোগ করার আগে বিকাশকারীকে জিজ্ঞাসা করুন।

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

### [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 পরিবর্তন করে

• তারিখ: 2026-03-18
• এর দ্বারা পর্যবেক্ষণ করা হয়েছে: কোডেক্স
• প্রসঙ্গ: ব্রাউজার যাচাইকরণ এবং ধোঁয়া প্রবাহ
• কি আশ্চর্যজনক ছিল: ডিফল্ট স্থানীয় URL সাধারণ Vite পোর্ট নয়। রেপো পোর্টলেস এর মাধ্যমে https://bitsocial.localhost আশা করে, তাই localhost:3000 বা localhost:5173 চেক করলে ভুল অ্যাপ বা কিছুই আঘাত করতে পারে।
• ইমপ্যাক্ট: ডেভ সার্ভার সুস্থ থাকলেও ব্রাউজার চেক ভুল টার্গেটকে ব্যর্থ বা যাচাই করতে পারে।
• প্রশমন: প্রথমে https://bitsocial.localhost ব্যবহার করুন। আপনার স্পষ্টভাবে একটি সরাসরি Vite পোর্টের প্রয়োজন হলে শুধুমাত্র 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
• এর দ্বারা পর্যবেক্ষণ করা হয়েছে: কোডেক্স
• প্রসঙ্গ: সুতা ৪-এ প্যাকেজ ম্যানেজার মাইগ্রেশন
• কি আশ্চর্যজনক ছিল: মেশিনে এখনও 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 ব্যবহার করে একটি ইনজেকশনযুক্ত ফ্রি পোর্টকে সম্মান করতে বা সরাসরি চালানোর সময় পরবর্তী উপলব্ধ পোর্টে ফিরে আসে।
• স্থিতি: নিশ্চিত করা হয়েছে

ফিক্সড ডক্স পোর্টলেস হোস্টনাম হার্ড কোডেড ছিল

• তারিখ: ২০২৬-০৪-০৩
• এর দ্বারা পর্যবেক্ষণ করা হয়েছে: কোডেক্স
• প্রসঙ্গ: একটি সেকেন্ডারি বিটসোশ্যাল ওয়েব ওয়ার্কট্রিতে yarn start চালানো হচ্ছে যখন অন্য একটি ওয়ার্কট্রি ইতিমধ্যেই পোর্টলেসের মাধ্যমে ডক্স পরিবেশন করছে
• কি আশ্চর্যজনক ছিল: start:docs এখনও আক্ষরিক docs.bitsocial.localhost হোস্টনামটি নিবন্ধিত করেছে, তাই yarn start ব্যর্থ হতে পারে যদিও অ্যাপটি ইতিমধ্যেই তার নিজের হোস্টনামের জন্য পোর্টলেস রুটের সংঘর্ষ এড়াতে জানে।
• প্রভাব: সমান্তরাল ওয়ার্কট্রিস নির্ভরযোগ্যভাবে root dev কমান্ড ব্যবহার করতে পারেনি কারণ ডক্স প্রসেসটি প্রথমে প্রস্থান করে এবং concurrently তারপর বাকি সেশনটি মেরে ফেলে।
• প্রশমন: ডক্স স্টার্টআপকে scripts/start-docs.mjs এর পিছনে রাখুন, যা এখন প্রায় অ্যাপ হিসাবে একই শাখা-স্কোপযুক্ত পোর্টলেস হোস্টনাম প্রাপ্ত করে এবং /docs ডেভ প্রক্সি টার্গেটে সর্বজনীন URL শেয়ার করে
• স্থিতি: নিশ্চিত করা হয়েছে

ওয়ার্কট্রি শেলগুলি রেপোর পিন করা নোড সংস্করণটি মিস করতে পারে

• তারিখ: ২০২৬-০৪-০৩
• এর দ্বারা পর্যবেক্ষণ করা হয়েছে: কোডেক্স
• প্রসঙ্গ: Git ওয়ার্কট্রিতে yarn start চালানো যেমন .claude/worktrees/* বা ভাইবোন ওয়ার্কট্রি চেকআউট
• কি আশ্চর্যজনক ছিল: কিছু ওয়ার্কট্রি শেল node এবং yarn node থেকে হোমব্রু নোড 25.2.1 সমাধান করেছে যদিও রেপো .nvmrc-এ 22.12.0 পিন করেছে, তাই ZXQPLACEHOLDER4ZXXL5 চালাতে পারে ভুল রানটাইম অধীনে লঞ্চার.
• প্রভাব: ডেভ-সার্ভার আচরণ প্রধান চেকআউট এবং ওয়ার্কট্রির মধ্যে প্রবাহিত হতে পারে, বাগগুলিকে পুনরুত্পাদন করা কঠিন করে তোলে এবং রেপোর প্রত্যাশিত নোড 22 টুলচেন লঙ্ঘন করে।
• প্রশমন: ডেভ লঞ্চারগুলিকে scripts/start-dev.mjs এবং scripts/start-docs.mjs এর পিছনে রাখুন, যা এখন .nvmrc নোড বাইনারির অধীনে পুনরায় কার্যকর হয় যখন বর্তমান শেলটি ভুল সংস্করণে থাকে৷ শেল সেটআপ এখনও nvm use পছন্দ করা উচিত।
• স্থিতি: নিশ্চিত করা হয়েছে

docs-site/ অবশিষ্টাংশ রিফ্যাক্টরের পরে অনুপস্থিত ডক্স উত্স লুকাতে পারে

• তারিখ: ২০২৬-০৪-০১
• এর দ্বারা পর্যবেক্ষণ করা হয়েছে: কোডেক্স
• প্রসঙ্গ: ডকুসারাস প্রজেক্টকে docs-site/ থেকে docs/ তে সরানোর পরে-মার্জন-পরবর্তী মনোরেপো ক্লিনআপ
• কী আশ্চর্যজনক ছিল: পুরানো docs-site/ ফোল্ডারটি i18n/-এর মতো বাসি কিন্তু গুরুত্বপূর্ণ ফাইলগুলি নিয়ে ডিস্কে থাকতে পারে, এমনকি ট্র্যাক করা রেপো docs/-এ চলে যাওয়ার পরেও৷ এটি রিফ্যাক্টরটিকে স্থানীয়ভাবে সদৃশ দেখায় এবং এই সত্যটি লুকিয়ে রাখতে পারে যে ট্র্যাক করা ডক্স অনুবাদগুলি আসলে docs/ এ সরানো হয়নি৷
• প্রভাব: এজেন্টরা পুরানো ফোল্ডারটিকে "জাঙ্ক" হিসাবে মুছে ফেলতে পারে এবং দুর্ঘটনাক্রমে ডক্স অনুবাদের একমাত্র স্থানীয় অনুলিপি হারাতে পারে, অথবা এখনও মৃত docs-site/ পাথের দিকে নির্দেশ করে এমন স্ক্রিপ্ট সম্পাদনা করতে পারে৷
• প্রশমন: docs/ কে একমাত্র আদর্শ নথি প্রকল্প হিসাবে বিবেচনা করুন। কোনো স্থানীয় docs-site/ অবশিষ্টাংশ মুছে ফেলার আগে, docs/i18n/ এর মতো ট্র্যাক করা উৎস পুনরুদ্ধার করুন এবং docs-site উল্লেখ করা বন্ধ করতে স্ক্রিপ্ট এবং হুক আপডেট করুন।
• স্থিতি: নিশ্চিত করা হয়েছে

মাল্টিলোকেল ডক্স প্রিভিউ যাচাইকরণের সময় RAM কে বাড়াতে পারে

• তারিখ: ২০২৬-০৪-০১
• এর দ্বারা পর্যবেক্ষণ করা হয়েছে: কোডেক্স
• প্রসঙ্গ: yarn start:docs প্লাস নাট্যকারের সাথে ডক্স i18n, লোকেল রাউটিং এবং পেজফাইন্ড আচরণ ঠিক করা
• কি আশ্চর্যজনক ছিল: ডিফল্ট ডক্স প্রিভিউ মোড এখন পরিবেশন করার আগে একটি সম্পূর্ণ মাল্টিলোকেল ডক্স তৈরি করে এবং পেজফাইন্ড ইন্ডেক্সিং করে এবং একাধিক নাট্যকার বা ক্রোম সেশনের পাশাপাশি সেই প্রক্রিয়াটিকে জীবিত রাখতে একটি সাধারণ Vite বা একক-লোকেল ডকুসাউরাস ডেভ লুপের চেয়ে অনেক বেশি RAM খরচ করতে পারে৷
• ইমপ্যাক্ট: মেশিনটি মেমরিতে সীমাবদ্ধ হয়ে যেতে পারে, ব্রাউজার সেশনগুলি ক্র্যাশ হতে পারে এবং ব্যাহত রানগুলি পুরানো ডক্স সার্ভার বা হেডলেস ব্রাউজারগুলিকে পিছনে ফেলে যেতে পারে যা মেমরিকে গ্রাস করে।
• প্রশমন: নথির কাজের জন্য যেগুলির লোকেল-রুট বা পেজফাইন্ড যাচাইকরণের প্রয়োজন নেই, DOCS_START_MODE=live yarn start:docs পছন্দ করুন৷ আপনি যখন অনুবাদিত রুট বা পেজফাইন্ড যাচাই করতে চান শুধুমাত্র তখনই ডিফল্ট মাল্টিলোকেল প্রিভিউ ব্যবহার করুন। একটি একক নাট্যকার অধিবেশন রাখুন, নতুনগুলি খোলার আগে পুরানো ব্রাউজার সেশনগুলি বন্ধ করুন, এবং আপনার আর প্রয়োজন না হলে যাচাইকরণের পরে ডক্স সার্ভার বন্ধ করুন৷
• স্থিতি: নিশ্চিত করা হয়েছে