शुरुआत: शून्य से एक कार्यशील हार्नेस तक

यह ट्यूटोरियल आपको आपके पहले Apothem सेटअप के पूरे दौर से ले जाता है। आप कुछ भी इंस्टॉल किए बिना शुरू करते हैं और एक वास्तविक हार्नेस कॉन्फ़िगरेशन के साथ समाप्त होते हैं — आपके लिखे प्रोफ़ाइल से उत्पन्न, सत्यापित, और कार्यशील के रूप में पुष्ट। लगभग पंद्रह मिनट का अनुमान लगाएँ। नीचे का हर कमांड वास्तविक है और कॉपी-पेस्ट करने योग्य है।

अंत तक आपके पास होगा:

1. स्क्रिप्ट इंस्टॉलर से इंस्टॉल किया गया Apothem।
2. हर हार्नेस को संचालित करने वाली साझा प्रोफ़ाइल, संपादित।
3. एक हार्नेस का नेटिव कॉन्फ़िगरेशन, मूर्त रूप दिया गया।
4. वह कॉन्फ़िगरेशन सत्यापित, और एक कार्यशील पहला रन पुष्ट।

पूरे ट्यूटोरियल में हम उदाहरण हार्नेस के रूप में Claude Code का उपयोग करेंगे, क्योंकि यह इंस्टॉलर का डिफ़ॉल्ट है। वही चरण किसी भी समर्थित हार्नेस पर लागू होते हैं: जब आप हार्नेस सूची तक पहुँचें तो नाम बदल दें।

आपको पहले क्या चाहिए

• एक Unix-जैसा शेल (macOS, Linux, या WSL)। PowerShell इंस्टॉलर Windows को कवर करता है; यह ट्यूटोरियल bash पथ दिखाता है।
• आपके PATH में Python 3.10 या उसके बाद का। इसे python3 --version से जाँचें।
• दो रनटाइम लाइब्रेरी जिन्हें इंजन आपके इंटरप्रेटर से आयात करता है: click और rich। बाकी स्टैक (pyyaml, jsonschema) ट्री में ही शामिल (vendored) है, इसलिए केवल इन्हीं दो का आयात-योग्य होना ज़रूरी है। इंस्टॉलर इन्हें जाँचता है, गायब लाइब्रेरी बताता है, और गायब टुकड़ों को आपके लिए इंस्टॉल करने की पेशकश करता है, ताकि आप पुष्टि करके आगे बढ़ सकें।

Apothem एक प्रकाशित पैकेज के बजाय एक पैकेज किए गए स्रोत-कोड वृक्ष के रूप में वितरित होता है: कोई pip install चरण नहीं है। इंस्टॉलर वृक्ष को क्लोन करता है और सीधे उससे इंजन चलाता है।

चरण 1 — Apothem इंस्टॉल करें

नेटवर्क इंस्टॉलर चलाएँ:

curl -fsSL https://apothem.ahmedgad.com/install.sh | bash

इंस्टॉलर ये चरण करता है:

1. पूर्वापेक्षा जाँच। इंस्टॉलर एक वास्तविक Python 3.10+ इंटरप्रेटर ढूँढता है और पुष्टि करता है कि दो रनटाइम लाइब्रेरी (click और rich) आयात-योग्य हैं। यदि कोई गायब है, तो यह उसे बताता है और उसे आपके लिए इंस्टॉल करने की पेशकश करता है — या बिना पूछे इंस्टॉल करने के लिए APOTHEM_AUTO_INSTALL_DEPS=1 सेट करें।
2. स्रोत-कोड स्थापन। पैकेज किया गया वृक्ष ~/.apothem में क्लोन होता है (APOTHEM_HOME पर्यावरण-चर से अधिभावी करें)। पुनः-चलाना मौजूदा क्लोन को डुप्लिकेट करने के बजाय अपडेट करता है।
3. प्रोफ़ाइल आरंभीकरण। यदि आपके पास अभी तक कोई प्रोफ़ाइल नहीं है, तो इंस्टॉलर एक नमूना प्रोफ़ाइल ~/.config/apothem/profile.yaml में कॉपी करता है, फिर आगे बढ़ने से पहले रुककर आपसे इसे संपादित करने को कहता है। यह जानबूझकर है: नमूना प्लेसहोल्डर पहचान-डेटा का उपयोग करता है, और किसी भी हार्नेस कॉन्फ़िगरेशन को लिखने से पहले आपको इसे अपना बना लेना चाहिए। हम चरण 2 में ऐसा करेंगे।

आप इंस्टॉलेशन को पर्यावरण-चर से निर्देशित कर सकते हैं। जिनका आप सबसे अधिक उपयोग करेंगे:

# Install a different harness as the default, and point at a project profile.
APOTHEM_HARNESS=cursor \
APOTHEM_PROFILE="$HOME/.config/apothem/profile.yaml" \
  curl -fsSL https://apothem.ahmedgad.com/install.sh | bash

अन्य पहचाने गए चर हैं APOTHEM_REPO और APOTHEM_REF (कौन-सा रिमोट क्लोन करें और कौन-सा git ref डाउनलोड करें; बिना सेट किए यह नवीनतम हस्ताक्षरित संस्करण टैग का समाधान और सत्यापन करता है, पिन करने के लिए कोई टैग सेट करें या चलती हुई शाखा के लिए main), APOTHEM_ALLOW_UNVERIFIED=1 (टैग-हस्ताक्षर सत्यापन विफलता को चेतावनी में घटाता है), APOTHEM_SOURCE (क्लोन करने के बजाय मौजूदा स्थानीय चेकआउट का उपयोग करता है), और APOTHEM_SKIP_VERIFY=1 (इंस्टॉल-पश्चात सत्यापन छोड़ देता है, जिसे हम चलाना चाहते हैं, इसलिए इसे बिना सेट किए छोड़ें)।

जब इंस्टॉलर एक पूर्ण रन समाप्त करता है तो यह एक बैनर प्रिंट करता है जो दिखाता है कि इंजन को कैसे बुलाएँ। यह आपके PATH पर एक apothem shim रखता है (POSIX: $HOME/.local/bin; Windows: %LOCALAPPDATA%\Microsoft\WindowsApps), इसलिए एक बार वह डायरेक्टरी PATH पर आ जाने के बाद आप इंजन को सीधे चलाते हैं:

apothem <command>

यदि shim नहीं रखा जा सका — या उसकी डायरेक्टरी अभी PATH पर नहीं है — तो बैनर एक स्व-निहित फ़ॉलबैक प्रिंट करता है जिसे किसी shim की ज़रूरत नहीं:

PYTHONPATH="$HOME/.apothem/src" python3 -m apothem <command>

इस ट्यूटोरियल का शेष भाग apothem <command> लिखता है; यदि आप फ़ॉलबैक रूप पर हैं, तो अपने इंस्टॉलर बैनर द्वारा प्रिंट किया गया सटीक उपसर्ग हर कमांड से पहले लगाएँ।

चरण 2 — प्रोफ़ाइल को अपना बनाएँ

~/.config/apothem/profile.yaml में साझा प्रोफ़ाइल ही एकमात्र सत्य-स्रोत है। हर हार्नेस अडैप्टर इसे पढ़ता है और इससे उस हार्नेस का नेटिव कॉन्फ़िगरेशन निकालता है। इसे एक बार संपादित करें और आपके द्वारा इंस्टॉल किया गया हर हार्नेस संगत बना रहता है।

इसे इंजन के संपादक, या किसी भी टेक्स्ट संपादक में खोलें:

apothem profile edit

एक न्यूनतम वैध प्रोफ़ाइल ऐसी दिखती है:

identity:
  name: "Example User"
preferences:
  style: "concise"
rules:
  - "Validate external input before writing files."

प्लेसहोल्डर name को अपने नाम से बदलें, और कोई भी नियम जोड़ें जिसे आप हर हार्नेस से लागू करवाना चाहते हैं। नमूना काल्पनिक मानों को बनाए रखें: प्रोफ़ाइल को सुरक्षित रूप से साझा करने योग्य बनाने के लिए डिज़ाइन किया गया है।

पुष्टि करें कि इंजन आपके संपादनों को बिना किसी समस्या के फिर से पढ़ता है:

apothem profile show --json

यदि YAML त्रुटिपूर्ण है, तो आप इसे यहीं देखेंगे: इसे ठीक करें और आगे बढ़ने से पहले फिर से चलाएँ।

चरण 3 — एक हार्नेस कॉन्फ़िगरेशन को मूर्त रूप दें

इंस्टॉलर ने चरण 1 के दौरान पहले ही डिफ़ॉल्ट हार्नेस को मूर्त रूप दे दिया था। इसे स्पष्ट रूप से करने के लिए — या दूसरे हार्नेस को मूर्त रूप देने के लिए — install चलाएँ:

apothem install --harness claude-code

यह आपकी प्रोफ़ाइल पढ़ता है और Claude Code का नेटिव कॉन्फ़िगरेशन लिखता है। हर उस हार्नेस को देखने के लिए जिसे आप लक्षित कर सकते हैं:

apothem harnesses list

कुछ हार्नेस उपयोगकर्ता-दायरे के बजाय परियोजना-दायरे के होते हैं, और उन्हें एक --project पथ चाहिए ताकि अडैप्टर जान सके कि कहाँ लिखना है:

apothem install --harness cursor --project .

चरण 4 — सत्यापित करें और पहले रन की पुष्टि करें

मूर्तीकरण कहानी का केवल आधा हिस्सा है। अब पुष्टि करें कि कॉन्फ़िगरेशन सही ढंग से लागू हुआ:

apothem verify --harness claude-code

verify जाँचता है कि हार्नेस की अपेक्षित कॉन्फ़िगरेशन फ़ाइलें मौजूद हैं और प्रोफ़ाइल जो घोषित करती है उससे मेल खाती हैं। एक स्वच्छ रन का अर्थ है कि मूर्तीकरण सफल रहा।

हर पंजीकृत अडैप्टर पर पूरे-मशीन स्वास्थ्य-जाँच के लिए चलाएँ:

apothem doctor

doctor हर अडैप्टर की इंस्टॉलेशन स्थिति की रिपोर्ट करता है और यदि कोई पंजीकृत अडैप्टर स्वयं को अनइंस्टॉल बताए तो शून्येतर कोड के साथ बाहर निकलता है: सेटअप स्क्रिप्ट में एक उपयोगी द्वार।

आपका पहला रन। जिस हार्नेस को आपने अभी कॉन्फ़िगर किया — हमारे उदाहरण में Claude Code — उसे खोलें और किसी भी परियोजना में सत्र शुरू करें। आपने प्रोफ़ाइल में जो नियम और प्राथमिकताएँ लिखीं वे पहले से ही उस टूल के व्यवहार का हिस्सा हैं। यही पहला कार्यशील रन है: चरण 2 में आपने जो प्रोफ़ाइल संपादित की वह एक वास्तविक सत्र को आकार दे रही है।

आपने क्या बनाया

एक खाली मशीन से शुरू करके, आपने Apothem इंस्टॉल किया, एक साझा प्रोफ़ाइल लिखी, उससे एक हार्नेस के नेटिव कॉन्फ़िगरेशन को मूर्त रूप दिया, परिणाम सत्यापित किया, और उसे कार्यशील के रूप में पुष्ट किया। प्रोफ़ाइल टिकाऊ कलाकृति है: इसे एक बार बदलें और उस परिवर्तन को किसी भी हार्नेस में धकेलने के लिए apothem update --harness <name> फिर से चलाएँ।

आगे कहाँ जाएँ

• एक और टूल जोड़ें। हार्नेस सूची हर समर्थित प्लेटफ़ॉर्म और उसके अडैप्टर नाम को कवर करती है। नए --harness के साथ चरण 3 दोहराएँ।
• एक कार्य में गहराई से उतरें। हाउ-टू मार्गदर्शिकाएँ नियम लिखने, योजनाएँ बनाने, और अनुरूपता-द्वार चलाने के लिए कार्य-केंद्रित नुस्खे हैं।
• ठोस विवरण देखें। संदर्भ हर अडैप्टर, प्रोफ़ाइल स्कीमा, और पूरी CLI सतह का दस्तावेज़ीकरण करता है।
• किसी सत्र से आगे टिकने वाले कार्य की योजना बनाएँ। पुनरारंभ-योग्य योजना समझाती है कि Apothem दीर्घकालिक कार्य को किसी प्रोजेक्ट-स्थानीय .apothem/plans/ सुइट में कैसे बाहरीकृत करता है ताकि किसी भी मशीन पर एक नया सत्र उसे यथास्थान फिर से शुरू कर दे।

अनुशंसित अगला कदम

apothem doctor चलाएँ — अपना सेटअप जाँचने के लिए; यह प्रत्येक पंजीकृत अडैप्टर की स्थिति की रिपोर्ट करता है, इसलिए आपने जो हार्नेस अभी इंस्टॉल किया वह स्वस्थ के रूप में दिखता है जबकि शेष अभी-तक-इंस्टॉल-नहीं के रूप में — इससे पहले कि आप और हार्नेस जोड़ने की ओर बढ़ें।