त्वरित शुरुआत
पूरी toolchain को शुरू से आख़िर तक लगभग तीस सेकंड में चलाइए — offline, बिना API key और शून्य tokens खर्च करके।
Handbooks क्या करता है, यह समझने का सबसे तेज़ तरीक़ा है उसे करते हुए देखना। यह पूरी pipeline — analysis, generation, rendering, packaging, validation — एक bundled sample project पर, bundled mock LLM server के साथ चलाता है।
कोई API key नहीं। कोई network नहीं। शून्य tokens।
Step 1 — चलाइए
git clone <this repo> && cd handbooks
pnpm install
pnpm build
pnpm demoStep 2 — जो छपा, उसे पढ़िए
== build ==
== start mock LLM (offline; prose will be placeholder text) ==
== 1. analyze (no LLM) ==
{ "language": "multi", "files": 5, "functions": 23, "edgesKept": 31, "edgesDropped": 4, "filesUnparsed": 0 }
== 2. generate (phases 2+3) ==
{ "phasesRun": ["2a","2b","2c","3"], "nCards": 5, "nStages": 4, "nRegisters": 2 }
== 3. render markdown + HTML site + agent index + llms.txt ==
== 4. package as an agent SKILL (with the agent locator pages) ==
== 5. validate the SKILL ==
validate: OKProse बेतुकी होगी — यही अपेक्षित है
Mock LLM placeholder text लौटाता है। Structure पूरी तरह असली है — stages, file assignment, call facts, line ranges, register table, हर link। सिर्फ़ वाक्य नक़ली हैं। यही ठीक वह विभाजन है जिस पर यह project बना है: facts parser से आते हैं, prose model से।
Step 3 — नतीजे खोलिए
open examples/work/demo/handbook/overview.md # the markdown handbook
open examples/work/demo/handbook/html/overview.html # the multi-page HTML site
open examples/work/demo/handbook/handbook.html # the whole thing in one file
open examples/work/demo/skill/SKILL.md # the agent SKILL packageख़ास तौर पर देखने लायक़ चीज़ें:
| इसे खोलिए | और इस पर ग़ौर कीजिए |
|---|---|
handbook/overview.md | Call graph से generate किया गया mermaid stage map |
handbook/index.md | हर stage, nested, हरेक के साथ एक paragraph |
handbook/register.md | Cross-stage state, हर हिस्से को छूने वाले stages के साथ |
handbook/agent/index.md | Agent index — lookup नुस्ख़े, stage तालिका, coverage। इसे पूरा पढ़िए |
handbook/agent/symbols.tsv | हर symbol → path:startLine-endLine। यही वह चीज़ है जो गद्य पृष्ठों के पास कभी नहीं थी |
skill/references/coverage.json | हर file का एक content hash। यही drift का signal है। |
work/demo/phase1/dropped-calls.json | वे calls जिन्हें analyzer resolve नहीं कर सका — guess करने के बजाय सहेजी और categorized |
work/demo/phase1/scan-coverage.json | वे files जिन्हें analyzer पढ़ या पूरी तरह parse नहीं कर सका। यहाँ [] का मतलब है, पाँचों parse हुईं |
Step 4 — hood के नीचे झाँकिए
Pipeline ने जो कुछ बनाया, वह सब work directory में सादा JSON और YAML है:
ls examples/work/demo/
# phase1/ phase2/ phase3/ handbook/ skill/ run-manifest.json
cat examples/work/demo/phase1/graph.json | head -40
cat examples/work/demo/phase2/skeleton.yaml
cat examples/work/demo/run-manifest.json # model, phases, timings, token usageइनमें से हर एक पढ़े जाते समय schema-validated है। अगर आप किसी को hand-edit करके invalid बना दें, तो अगला command बताता है कौन-सी file और क्यों — गड़बड़ी आगे नहीं फैलती।
बाक़ी demos
pnpm demo:self # this repo as its own input, against the mock LLM
pnpm demo:self:real # same, but against the real endpoint from .env
pnpm mock-llm # just the mock server, on port 8099पढ़ने के लिहाज़ से pnpm demo:self ज़्यादा दिलचस्प है: यह ग्यारह असली TypeScript packages का
विश्लेषण करता है, इसलिए उससे बनने वाली stage structure एक असली codebase का असली नक़्शा है।
अभी हुआ क्या
analyzeने जो-जो file पढ़ सका उसे tree-sitter से parse करके एक typed call graph बनाया, और जो नहीं पढ़ सका उसेphase1/scan-coverage.jsonमें लिख दिया। कोई LLM नहीं।generateने हर file का एक card लिखा, एक stage skeleton synthesize किया, हर file को किसी stage में assign किया, उन्हें group और order किया, फिर bottom-up narration लिखा और cross-stage state registers निकाले।renderने उसे markdown, एक HTML site, एक self-contained page, agent locator index औरllms.txtमें बदला। कोई LLM नहीं।skillने उसे हर file के content hash के साथ एक agent SKILL में दोबारा package किया। कोई LLM नहीं।validateने structure, frontmatter contract, index ↔ stage-page links और hash की ताज़गी जाँची। कोई LLM नहीं।
Demo यहीं रुक जाता है। दूसरा आधा हिस्सा — plan → apply → rollback → resync —
आपका पहला handbook और
बदलावों की planning में शामिल है।