समस्या निवारण

#स्क्रीन या विंडो रिकॉर्ड नहीं होती (macOS)

संदेश: पूरी स्क्रीन या दूसरी विंडो रिकॉर्ड करने के लिए macOS की Screen Recording अनुमति चाहिए।

1. रिकॉर्डिंग Target dialog में System Settings खोलें पर क्लिक करें।
2. Privacy & Security → Screen & System Audio Recording: Ferret चालू करें।
3. ऐप रीस्टार्ट करें, फिर फिर से जाँचें पर क्लिक करें।

बिल्ट-इन Browser रिकॉर्ड करने के लिए किसी अनुमति की ज़रूरत नहीं होती।

macOS पर source से चलाते समय pnpm dev Electron की एक renamed, ad-hoc signed copy launch करता है जिसका नाम भी Ferret है (scripts/prepare-dev-electron.mjs), इसलिए यह इन सूचियों में एक अलग Ferret entry के रूप में दिखता है। पहली बार चलने पर macOS फिर से Screen Recording और Microphone की अनुमति माँगता है। उसके बाद दोबारा नहीं माँगता। Development builds एक mock keychain (--use-mock-keychain) इस्तेमाल करते हैं, इसलिए Keychain का कोई prompt नहीं आता: dev build में सेव की गई cookies और keys असली Keychain से नहीं, एक तय key से encrypt होती हैं। असली Keychain इस्तेमाल करने के लिए ADE_DEV_REAL_KEYCHAIN=1 सेट करें।

#माइक्रोफ़ोन नहीं खुलता

संदेश: माइक्रोफ़ोन नहीं खुल सका। OS settings में अनुमति जाँचें।

• macOS: System Settings → Privacy & Security → Microphone, फिर Ferret चालू करें।
• Windows: Settings → Privacy & security → Microphone, फिर डेस्कटॉप ऐप्स को अनुमति दें।

माइक के बिना भी पेन से घेरी गई जगहें findings बनाती हैं, पर उनमें बोला गया अनुरोध नहीं होता।

#डिवाइस पर कोई मॉडल नहीं / whisper-cli नहीं मिला

संदेश: डिवाइस पर ट्रांसक्रिप्शन का कोई मॉडल नहीं मिला। ऑडियो सेव होगा, और सिर्फ़ पेन findings प्रोसेस होंगी।

Settings में मॉडल डाउनलोड करें, या पहले से मौजूद ggml-*.bin चुनें। अगर Settings में whisper.cpp (whisper-cli) नहीं मिला दिखे, तो उसे इंस्टॉल करें (निर्देश), पक्का करें कि वह PATH में है, और Settings दोबारा खोलें। Finder या Explorer से launch किए गए पैकेज वाले ऐप आपकी shell का PATH शायद न देखें, इसलिए Homebrew जैसी किसी मानक जगह पर इंस्टॉल करें।

जो मॉडल डाउनलोड sha256 जाँच में fail होता है, उसे हटा दिया जाता है। दोबारा कोशिश करें।

#टर्मिनल: node-pty load नहीं हो सका

यह तब होता है जब आप source से चला रहे हों और node-pty किसी दूसरे Node या Electron ABI के लिए build हुआ हो।

pnpm rebuild:native

#Agent नहीं मिला / Agent को भेजें नहीं भेजता

• टर्मिनल में command not found: claude (या codex, gemini, या किसी दूसरे agent का command): CLI इंस्टॉल नहीं है या PATH में नहीं है। Ferret shell का अपना error दिखाता है और कोई संकेत नहीं जोड़ता। जाँचें कि command आपके सामान्य टर्मिनल में चलता है, Settings → Agents में इंस्टॉल करें इस्तेमाल करें, या उस agent के कमांड में absolute path सेट करें।
• agent पुष्टि का इंतज़ार कर रहा है। terminal में जवाब दें, फिर भेजें। पहले agent के सवाल का जवाब दें।
• agent का इनपुट अभी तैयार नहीं है। Agent के पूरी तरह शुरू होने तक इंतज़ार करें।
• टेक्स्ट डाल दिया गया पर भेजा नहीं गया। terminal में Enter दबाएँ।
• पहले एक terminal खोलें।
• launch arguments पार्स नहीं हो सके: Quote बंद नहीं किया गया। Agent के arguments में quotes ठीक करें।

#रिकॉर्डिंग शुरू नहीं होती

• पहले एक प्रोजेक्ट फ़ोल्डर खोलें।
• पहले समीक्षा के लिए URL खोलें।
• पेज लोड नहीं हुआ। दिखने वाला URL खोलें, फिर रिकॉर्ड करें। जाँचें कि dev server चल रहा है। सर्वर से कनेक्ट नहीं हो सका का मतलब है कि उस port पर कुछ भी सुन नहीं रहा।

#OpenAI key या endpoint सेट नहीं है

कोई OpenAI API key सेट नहीं है।… या ट्रांसक्रिप्शन endpoint (Base URL / मॉडल) सेट नहीं है।…: इसे Settings में जोड़ें, या डिवाइस पर (मुफ़्त) पर जाएँ। उस रिकॉर्डिंग का ऑडियो पहले ही सेव हो चुका है।

#GitHub errors

• GitHub CLI (gh) नहीं मिला। gh इंस्टॉल करें।
• GitHub में साइन इन नहीं है। Settings → GitHub / GitLab → Terminal में साइन इन करें।
• कोई origin remote नहीं है। या origin कोई GitHub repository नहीं है। git remote -v जाँचें।
• Repository नहीं मिली, या आपके पास एक्सेस नहीं है। gh auth status और GH_TOKEN जाँचें।

#Bug रिपोर्ट करें

github.com/JapanMarketing-Dev/ferret/issues (नए टैब में खुलता है) पर एक issue खोलें, जिसमें आपका OS, ऐप का version (फ़ुटर → अपडेट), और समस्या दोहराने के कदम हों। .ferret/ की ऐसी सामग्री न जोड़ें जिसमें निजी स्क्रीन हों।