dsh-autotier 0.1.0

package/README.hi.md

@@ -0,0 +1,241 @@
+# dsh-autotier
+
+DeepSeek Harness के लिए स्वचालित मॉडल-स्तर रूटिंग: एक उपयोगकर्ता निर्देश अंदर
+आता है, एक स्तर-निर्णय बाहर आता है — मॉडल हाथ से बदलने की ज़रूरत नहीं।
+
+जटिल आशय (आर्किटेक्चर, योजना, डिबगिंग, बहु-चरण इंजीनियरिंग) को पहले
+**strong** स्तर पर योजना बनाई जाती है, फिर **cheap** स्तर पर लागू किया जाता है।
+सरल आशय (प्रश्न, पुनर्प्राप्ति, बैच कार्य, दैनिक काम) सीधे **cheap** स्तर पर
+डिज़ाइन और कार्यान्वित होता है। cheap स्तर के निष्पादन के दौरान उच्च-जोखिम
+टूल कॉल को एक नियतात्मक गार्ड अस्वीकार करता है, और बार-बार विफलता पर TTL
+के साथ strong स्तर पर वृद्धि होती है।
+
+- **आधिकारिक रिपॉज़िटरी**: <https://github.com/PerryLink/dsh-autotier>
+- **npm**: `dsh-autotier` (सादा नाम, बिना scope)
+
+## संगतता
+
+| Harness | स्थिति |
+|---|---|
+| `@deepseek-ai/dsh` `0.1.2-rc.1` | संगत (CI इसी की जाँच करता है और compat वर्कफ़्लो इसे इंस्टॉल करता है) |
+| `0.1.5-alpha.1` (वर्तमान checkout लाइन) | इसके प्रकाशित type faces के विरुद्ध टाइप-जाँच; end-to-end smoke `0.1.2-rc.1` पर चलता है |
+| `@deepseek-ai/cordis` `^4.0.2`, `@deepseek-ai/schemastery` `^3.18.2` | peer आधार |
+
+यह प्लगइन केवल host plane पर रहता है और अपना preset नहीं माँगता: host पंक्ति
+हर सत्र पर लागू होती है। *आपके* preset में एक प्रॉम्प्ट खंड वैकल्पिक है और
+केवल मॉडल को निर्णय दिखाता है ([इंस्टॉल और अनइंस्टॉल](#इंस्टॉल-और-अनइंस्टॉल) देखें)।
+
+## आपको क्या मिलता है
+
+- **आशय द्वार** — हर turn को नियतात्मक संकेतों (संदेश पाठ, टूल नाम, चित्र की
+  उपस्थिति, संवाद की लंबाई) से वर्गीकृत किया जाता है। नियम-परत आत्मविश्वास होने
+  पर बिना token खर्च किए निर्णय लेती है; केवल कम-आत्मविश्वास वाला turn सस्ते
+  जज मॉडल को बुलाता है, और कभी cooldown के भीतर नहीं।
+- **आधिकारिक seam पर लैंडिंग** — निर्णय `agent/request` waterfall पर बदली हुई
+  provider/model/effort तिकड़ी लौटाकर लागू होता है। सत्र द्वारा पहले से चुने गए
+  सैंपलिंग scalars (`temperature`, `maxTokens`, `stop`) सुरक्षित रहते हैं।
+- **प्लान-मोड हैंडऑफ़** — जटिल निर्देश strong स्तर पर प्लान मोड में जाता है;
+  प्लान मोड छोड़ने पर कार्यान्वयन के लिए cheap स्तर पर लौट आता है।
+- **उच्च-जोखिम गार्ड** — cheap निष्पादन के दौरान विनाशकारी कमांड (`rm -rf`,
+  `sudo`, `mkfs`, `git push --force`, क्रेडेंशियल फ़ाइल लेखन, …) को सुधारात्मक
+  संदेश के साथ अस्वीकार किया जाता है जो स्तर बढ़ाने को कहता है।
+- **विफलता पर वृद्धि** — बार-बार विफलता (वैकल्पिक रूप से समान हस्ताक्षर पर)
+  TTL के लिए स्तर बढ़ाती है; मॉडल/मार्ग विफलता पर कॉन्फ़िगर की गई fallback
+  श्रृंखला चली जाती है।
+- **मैनुअल एस्केप हैच** — `/tier auto|strong|cheap|off` और `tier_status` /
+  `tier_route` टूल। जिस सत्र को अपना मॉडल रखना है, उसके लिए
+  `routingMode: delegated` (या `/tier off`) रूटिंग बंद कर देता है।
+- **`ctx.autotier` सेवा** — एक छोटा पठन-तल (`status`) तथा `autotier/route`
+  वीटो waterfall और `autotier/tier-changed` इवेंट, जिससे अन्य प्लगइन निर्णय
+  देख या रद्द कर सकें।
+
+## त्वरित शुरुआत
+
+```bash
+npm i -g dsh1024
+dsh1024 plugin --profile web add dsh-autotier
+```
+
+फिर harness शुरू करें (या पुनः आरंभ करें)। पंक्ति आपके
+`cordis.patch.yml` में जुड़ जाती है; अगले turn से रूटिंग शुरू हो जाती है।
+
+## इंस्टॉल और अनइंस्टॉल
+
+**npm चैनल**
+
+```bash
+npm i -g dsh1024
+dsh1024 plugin --profile web add dsh-autotier
+```
+
+**git चैनल**
+
+```bash
+git clone https://github.com/PerryLink/dsh-autotier.git
+cd dsh-autotier && pnpm install && pnpm run build
+dsh plugin --profile web add .
+```
+
+**वैकल्पिक preset प्रॉम्प्ट खंड।** इसके बिना भी राउटर काम करता है। मॉडल को यह
+बताने के लिए कि वह किस स्तर पर चल रहा है, *अपने* preset में एक पंक्ति जोड़ें
+(सटीक ब्लॉक `docs/preset-row.md` में है):
+
+```yaml
+- insert:
+    - id: autotier-prompt
+      name: '@deepseek-ai/dsh-system-prompt'
+      # sections: [...]  — देखें docs/preset-row.md
+```
+
+**अनइंस्टॉल**
+
+```bash
+dsh plugin --profile web remove dsh-autotier
+```
+
+पंक्ति, उसका settings namespace, उसका कमांड, उसके टूल और सभी listeners
+प्लगइन के साथ हट जाते हैं; settings दस्तावेज़ के बाहर कुछ नहीं लिखा जाता।
+
+## कॉन्फ़िगरेशन
+
+हर कुंजी लोड के समय जाँची जाती है; अमान्य मान चुपचाप रूटिंग बंद करने के बजाय
+ज़ोर से विफल होता है। इस रिपॉज़िटरी का `cordis.patch.yml` वही कुंजियाँ इनलाइन
+दस्तावेज़ित करता है।
+
+| कुंजी | डिफ़ॉल्ट | अर्थ |
+|---|---|---|
+| `tiers.strong.provider` | `deepseek-official` | योजना/समीक्षा स्तर का provider। |
+| `tiers.strong.model` | `deepseek-v4-pro` | strong मॉडल की कैटलॉग id। |
+| `tiers.strong.effort` | `high` | एडाप्टर शब्दावली `off` \| `low` \| `high` \| `max`। |
+| `tiers.strong.followSession` | `false` | `false` = इस स्तर का effort सत्र के effort को ओवरराइड करता है। |
+| `tiers.strong.fallback` | `[]` | स्तर अनुपलब्ध होने पर क्रमबद्ध provider/model लैंडिंग। |
+| `tiers.cheap.provider` | `deepseek-official` | कार्यान्वयन स्तर का provider। |
+| `tiers.cheap.model` | `deepseek-v4-flash` | cheap मॉडल की कैटलॉग id। |
+| `tiers.cheap.effort` | `low` | एडाप्टर शब्दावली `off` \| `low` \| `high` \| `max`। |
+| `tiers.cheap.followSession` | `true` | `true` = सत्र का effort विरासत में लें, जिससे स्पष्ट चयन जीते। |
+| `tiers.cheap.fallback` | `[]` | स्तर अनुपलब्ध होने पर क्रमबद्ध provider/model लैंडिंग। |
+| `tiers.vision.provider` | `deepseek-official` | चित्र वाले turn का provider। |
+| `tiers.vision.model` | `deepseek-v4-flash-vision-exp` | कैटलॉग का एकमात्र image-सक्षम मॉडल। |
+| `intent.ruleThreshold` | `0.7` | जिस आत्मविश्वास से नियम-परत अकेले निर्णय लेती है। |
+| `intent.attemptBand.enabled` | `false` | मध्य पट्टी को cheap पर शुरू कर संकेत मिलने पर बढ़ाना। |
+| `intent.attemptBand.tauLow` | `0.45` | attempt-first पट्टी की निचली सीमा। |
+| `intent.hysteresis.toStrong` | `0.8` | वह स्कोर जो cheap turn को strong कर देता है। |
+| `intent.hysteresis.toCheap` | `0.6` | जिस स्कोर से नीचे strong turn cheap पर लौटता है। |
+| `intent.rules` | `[]` | घोषणात्मक नियम तालिका (`when.patterns` / `when.tools` / `when.cwd`, `tier`, `priority`)। |
+| `intent.judge.enabled` | `true` | कम-आत्मविश्वास वाले जज की अनुमति। |
+| `intent.judge.model` | `''` | जज मॉडल id; खाली = कैटलॉग का पहला `flash` वाला मॉडल। |
+| `intent.judge.temperature` | `0` | जज सैंपलिंग तापमान। |
+| `intent.judge.maxTokens` | `16` | जज आउटपुट सीमा (एक शब्द में उत्तर)। |
+| `intent.judge.cooldownMs` | `30000` | दो जज कॉल के बीच न्यूनतम अंतर। |
+| `intent.judge.timeoutMs` | `2000` | जज कॉल का समय-समाप्ति। |
+| `intent.judge.unavailableSkip` | `2` | कितनी लगातार विफलताओं के बाद turn जज छोड़ दे। |
+| `intent.scenarios` | सभी `true` | प्रति-परिदृश्य स्विच: `coding`, `review`, `planning`, `retrieval`, `batch`, `daily`, `longText`, `multimodal`। |
+| `intent.costMode` | `balanced` | अस्पष्टता में निर्णय: `cost-first` \| `quality-first` \| `balanced`। |
+| `guard.enabled` | `true` | नियतात्मक उच्च-जोखिम गार्ड सक्रिय करें। |
+| `guard.tiers` | `[cheap]` | गार्ड किन स्तरों की रक्षा करता है। |
+| `guard.whitelist` | `[]` | कमांड, टूल या पथ-उपसर्ग जो गार्ड को कभी नहीं छूते। |
+| `guard.protectedPaths` | `['.dsh','AGENTS.md','package.json','.github/workflows']` | स्व-संशोधन सतहें जो strong समीक्षा ज़रूरी करती हैं। |
+| `guard.interopDefend` | `auto` | `dsh-defend` से संबंध: `auto` सहअस्तित्व का ऑडिट, `none` शांत। |
+| `escalation.threshold` | `2` | विंडो में इतनी विफलताओं पर स्तर बढ़ता है। |
+| `escalation.windowMs` | `60000` | विफलता गिनती की विंडो। |
+| `escalation.ttlMs` | `180000` | वृद्धि कितनी देर प्रभावी रहती है। |
+| `escalation.fallbackTtlMs` | `300000` | fallback लैंडिंग लेने के बाद का TTL। |
+| `escalation.signature` | `true` | हर विफलता के बजाय समान हस्ताक्षर की पुनरावृत्ति गिनें। |
+| `routingMode` | `auto` | `auto` \| `strong` \| `cheap` \| `delegated` \| `off`। |
+
+सभी कुंजियाँ `autotier` settings namespace (`$DSH_HOME/settings.yaml`) से
+लाइव भी बदली जा सकती हैं; क्रॉस-फ़ील्ड शर्त तोड़ने वाला लेखन सहेजने के समय
+अस्वीकार हो जाता है और अंतिम वैध नीति लागू रहती है।
+
+## टूल और सतहें
+
+| सतह | प्रकार | उद्देश्य |
+|---|---|---|
+| `/tier` | कमांड | `auto` \| `strong` \| `cheap` \| `off` \| `status`; सत्र-स्तरीय ओवरराइड। |
+| `tier_status` | टूल | वर्तमान स्तर, मोड, वृद्धि TTL और गार्ड स्थिति। |
+| `tier_route` | टूल | बिना अनुरोध भेजे किसी आशय का ड्राई-रन रूटिंग। |
+| `ctx.autotier` | सेवा | अन्य प्लगइन के लिए `status()` पठन-तल। |
+| `autotier/route` | serial इवेंट | तीसरे पक्ष प्रस्तावित स्तर को वीटो कर सकते हैं। |
+| `autotier/tier-changed` | emit इवेंट | प्रभावी स्तर बदलने पर अवलोकनीयता। |
+
+## अनुमतियाँ और डेटा
+
+- **फ़ाइलें** — प्लगइन साझा settings सेवा (`autotier` namespace) के अलावा कुछ
+  नहीं पढ़ता या लिखता।
+- **नेटवर्क** — एकमात्र आउटबाउंड ट्रैफ़िक जज कॉल है, जो सामान्य `ctx.llm` मार्ग
+  और कॉन्फ़िगर किए गए provider से जाता है।
+- **सत्र लॉग** — प्लगइन कोई अपना सत्र इवेंट नहीं जोड़ता। रूटिंग का निशान प्लगइन
+  logger और लाइव `autotier/tier-changed` बस इवेंट है; एकमात्र जोड़ तब होता है जब
+  plan-mode सेवा अनुपलब्ध हो और `plan/mode` फ़ॉलबैक लिखा जाए। `0.1.2-alpha.1` से
+  अपने इवेंट प्रकार fail-closed हैं, इसलिए प्लगइन का कोई स्थायी रिकॉर्ड नहीं लिखा
+  जाता।
+- **रहस्य** — यह प्लगइन कोई क्रेडेंशियल नहीं पढ़ता, दर्ज नहीं करता, संग्रह नहीं करता।
+
+## सुरक्षा सीमाएँ
+
+- गार्ड **गहन रक्षा** है, sandbox नहीं। यह cheap स्तर पर अपने ज्ञात पैटर्न
+  अस्वीकार करता है और `dsh-defend`, अनुमोदन सेवा या sandbox नीति को कभी कमज़ोर
+  नहीं करता। उन्हें सक्रिय रखें।
+- गार्ड केवल `guard.tiers` में दिए स्तरों की रक्षा करता है (डिफ़ॉल्ट cheap)।
+  strong turn डिज़ाइन से अवरुद्ध नहीं होता: strong मॉडल स्वयं समीक्षक है।
+- यदि गार्ड स्वयं त्रुटि दे, तो कॉल को अनुमति देने के बजाय strong पर बढ़ा दिया
+  जाता है — टूटा हुआ गार्ड खुला दरवाज़ा नहीं बनना चाहिए।
+- `/tier off` रूटिंग पूरी तरह बंद कर देता है; harness ठीक वैसा ही व्यवहार करता
+  है जैसा प्लगइन लगाने से पहले था।
+
+## ज्ञात सीमाएँ
+
+- नियम-परत नियतात्मक है और इसलिए सीमित: किसी जटिल अनुरोध का नया वाक्य cheap पर
+  शुरू हो सकता है और विफलता या गार्ड अस्वीकृति के बाद ही बढ़ेगा। कम-आत्मविश्वास
+  वाला मध्य भाग जज कॉल से ढका जाता है।
+- वृद्धि प्रति-agent और स्मृति में है; harness पुनः आरंभ होने पर `auto` से शुरू
+  होती है।
+- स्तर बदलने पर उस अनुरोध का provider prompt cache रीसेट होता है, इसलिए बहुत
+  सक्रिय सत्रों में बदलाव वाले turn पर थोड़ी cache-miss लागत दिख सकती है;
+  hysteresis सीमाएँ इसी को दुर्लभ रखने के लिए हैं।
+- प्लगइन संवाद अनुरोध रूट करता है। संपीड़न और शीर्षक निर्माण host के अलग seams
+  हैं; समान लागत प्रोफ़ाइल चाहिए तो उनकी मॉडल सेटिंग्स को cheap स्तर के साथ
+  संरेखित करें (`docs/supporting-lanes.md`)।
+- cheap स्तर पर `followSession: true` का अर्थ है कि सत्र का स्पष्ट मॉडल चयन
+  जीतता है; उस स्थिति में cheap स्तर अपना मॉडल नहीं थोप सकता।
+- **अभी Settings कार्ड या composer पिल नहीं है।** रूटिंग पूरी तरह स्वचालित है और
+  host सतह (`ctx.autotier.status()` / `catalog()`, `/tier`, `tier_status`,
+  `tier_route`) पूरी है; ब्राउज़र आधा v0.2 में नियोजित है।
+- **GUI में चुना गया मॉडल स्वचालित रूप से नहीं पहचाना जाता।** रूटिंग रोकने के लिए
+  `routingMode: delegated` या `/tier off` इस्तेमाल करें।
+- **फिंगरप्रिंट posteriors केवल स्मृति में रहते हैं** और पुनः आरंभ पर रीसेट होते हैं।
+- **attempt-first मध्य पट्टी डिफ़ॉल्ट रूप से बंद है**, कैलिब्रेशन कॉर्पस (v0.2) के
+  बाद सक्रिय होगी।
+
+## विकास
+
+```bash
+pnpm install
+pnpm run typecheck      # स्थानीय harness checkout के type faces के विरुद्ध
+pnpm run typecheck:ci   # प्रकाशित 0.1.2-rc.1 faces के विरुद्ध (CI यही चलाता है)
+pnpm test
+pnpm run build
+pnpm run verify:self-contained
+pnpm run verify:artifacts
+pnpm pack
+```
+
+`pnpm run build` `lib/types` (tsc declarations) और `lib/index.js` (tsdown
+बंडल) उत्पन्न करता है। परीक्षण सीधे प्रकाशित host पैकेजों का उपयोग करते हैं —
+वास्तविक `Context`, वास्तविक session/tools/commands/settings सेवाएँ — साथ ही
+एक अस्थायी `cordis.yml` पर एक वास्तविक Loader संयोजन।
+
+## विषय
+
+`dsh`, `dsh-plugin`, `deepseek-harness`, `deepseek`, `cordis`, `router`,
+`model-tier`, `cost`, `auto`.
+
+## योगदानकर्ता
+
+PerryLink. Issues और pull requests:
+<https://github.com/PerryLink/dsh-autotier/issues>।
+
+## लाइसेंस
+
+Apache-2.0. देखें [LICENSE](./LICENSE) और
+[THIRD_PARTY_NOTICES.md](./THIRD_PARTY_NOTICES.md)।

package/README.md

@@ -0,0 +1,245 @@
+# dsh-autotier
+
+Automatic model-tier routing for DeepSeek Harness: one user instruction enters,
+one tier decision comes out — no manual model switching.
+
+Complex intent (architecture, planning, debugging, multi-step engineering) is
+planned on the **strong** tier and then implemented on the **cheap** tier.
+Simple intent (questions, retrieval, batch chores, daily work) is designed and
+implemented on the **cheap** tier directly. While the cheap tier executes,
+high-risk tool calls are denied by a deterministic guard, and repeated failures
+escalate to the strong tier with a TTL fallback.
+
+- **Official repository**: <https://github.com/PerryLink/dsh-autotier>
+- **npm**: `dsh-autotier` (bare, unscoped)
+
+## Compatibility
+
+| Harness | Status |
+|---|---|
+| `@deepseek-ai/dsh` `0.1.2-rc.1` | compatible (this is what CI type-checks and the compat workflow installs) |
+| `0.1.5-alpha.1` (the current harness checkout line) | type-checked against its published type faces; the end-to-end smoke runs on `0.1.2-rc.1` |
+| `@deepseek-ai/cordis` `^4.0.2`, `@deepseek-ai/schemastery` `^3.18.2` | peer baseline |
+
+The plugin is host-plane only. It needs no agent preset of its own: the host
+row applies to every session. A one-line prompt section in *your* preset is
+optional and only makes the router's decisions visible to the model (see
+[Install & uninstall](#install--uninstall)).
+
+## What you get
+
+- **Intent gate** — every turn is classified from deterministic signals
+  (message text, tool names, image presence, conversation length). The
+  zero-token rule layer decides when it is confident; only a low-confidence turn
+  calls the cheap judge model, and never on a cooldown.
+- **Tier landing on the official seam** — the decision is applied on the
+  `agent/request` waterfall by returning a replacement provider/model/effort
+  triple. Sampling scalars the session already chose (`temperature`, `maxTokens`,
+  `stop`) are preserved.
+- **Plan-mode handoff** — a complex instruction enters plan mode on the strong
+  tier; leaving plan mode drops back to the cheap tier for implementation.
+- **High-risk guard** — while the cheap tier executes, destructive commands
+  (`rm -rf`, `sudo`, `mkfs`, `git push --force`, credential-file writes, …) are
+  denied with a corrective message telling the model to escalate instead.
+- **Failure escalation** — repeated failures (optionally same-signature) raise
+  the tier for a TTL; a model/route failure walks the configured fallback chain.
+- **Manual escape hatches** — `/tier auto|strong|cheap|off` and the
+  `tier_status` / `tier_route` tools. Setting `routingMode: delegated` (or
+  `/tier off`) stops routing for a session that must keep its own model.
+- **`ctx.autotier` service** — a small read surface (`status`) plus the
+  `autotier/route` veto waterfall and `autotier/tier-changed` event, so other
+  plugins can observe or override a decision.
+
+## Quick start
+
+```bash
+npm i -g dsh1024
+dsh1024 plugin --profile web add dsh-autotier
+```
+
+Then start (or restart) the harness. The row is appended to your profile's
+`cordis.patch.yml`; routing starts on the next turn with no further setup.
+
+## Install & uninstall
+
+**npm channel**
+
+```bash
+npm i -g dsh1024
+dsh1024 plugin --profile web add dsh-autotier
+```
+
+**git channel**
+
+```bash
+git clone https://github.com/PerryLink/dsh-autotier.git
+cd dsh-autotier && pnpm install && pnpm run build
+dsh plugin --profile web add .
+```
+
+**Optional preset prompt section.** The router works without it. To let the
+model know which tier it is running on, add one row to *your* agent preset
+(`docs/preset-row.md` has the exact block):
+
+```yaml
+- insert:
+    - id: autotier-prompt
+      name: '@deepseek-ai/dsh-system-prompt'
+      # sections: [...]  — see docs/preset-row.md
+```
+
+**Uninstall**
+
+```bash
+dsh plugin --profile web remove dsh-autotier
+```
+
+The row, its settings namespace, its command, its tools and its listeners are
+all removed with the plugin; nothing is written outside the settings document.
+
+## Configuration
+
+Every key is validated at load time; an invalid value fails loudly instead of
+silently disabling routing. `cordis.patch.yml` in this repository documents the
+same keys inline.
+
+| Key | Default | Meaning |
+|---|---|---|
+| `tiers.strong.provider` | `deepseek-official` | Provider for the planning/review tier. |
+| `tiers.strong.model` | `deepseek-v4-pro` | Catalog id of the strong model. |
+| `tiers.strong.effort` | `high` | Adapter vocabulary `off` \| `low` \| `high` \| `max`. |
+| `tiers.strong.followSession` | `false` | `false` = this tier's effort overrides the session's. |
+| `tiers.strong.fallback` | `[]` | Ordered provider/model landings when the tier is unavailable. |
+| `tiers.cheap.provider` | `deepseek-official` | Provider for the implementation tier. |
+| `tiers.cheap.model` | `deepseek-v4-flash` | Catalog id of the cheap model. |
+| `tiers.cheap.effort` | `low` | Adapter vocabulary `off` \| `low` \| `high` \| `max`. |
+| `tiers.cheap.followSession` | `true` | `true` = inherit the session's effort so an explicit choice wins. |
+| `tiers.cheap.fallback` | `[]` | Ordered provider/model landings when the tier is unavailable. |
+| `tiers.vision.provider` | `deepseek-official` | Provider for image-carrying turns. |
+| `tiers.vision.model` | `deepseek-v4-flash-vision-exp` | The catalog's image-capable model. |
+| `intent.ruleThreshold` | `0.7` | Confidence at or above which the rule layer decides alone. |
+| `intent.attemptBand.enabled` | `false` | Start the middle band on the cheap tier and escalate on a signal. |
+| `intent.attemptBand.tauLow` | `0.45` | Lower bound of the attempt-first band. |
+| `intent.hysteresis.toStrong` | `0.8` | Score that switches a cheap turn to strong. |
+| `intent.hysteresis.toCheap` | `0.6` | Score below which a strong turn returns to cheap. |
+| `intent.rules` | `[]` | Declarative rule table (`when.patterns` / `when.tools` / `when.cwd`, `tier`, `priority`). |
+| `intent.judge.enabled` | `true` | Allow the low-confidence judge. |
+| `intent.judge.model` | `''` | Judge model id; empty = first catalog model containing `flash`. |
+| `intent.judge.temperature` | `0` | Judge sampling temperature. |
+| `intent.judge.maxTokens` | `16` | Judge output cap (it answers with one word). |
+| `intent.judge.cooldownMs` | `30000` | Minimum gap between two judge calls. |
+| `intent.judge.timeoutMs` | `2000` | Judge call timeout. |
+| `intent.judge.unavailableSkip` | `2` | Consecutive judge failures after which the turn skips it. |
+| `intent.scenarios` | all `true` | Per-scenario switches: `coding`, `review`, `planning`, `retrieval`, `batch`, `daily`, `longText`, `multimodal`. |
+| `intent.costMode` | `balanced` | Ambiguity arbitration: `cost-first` \| `quality-first` \| `balanced`. |
+| `guard.enabled` | `true` | Enable the deterministic high-risk guard. |
+| `guard.tiers` | `[cheap]` | Tiers the guard protects. |
+| `guard.whitelist` | `[]` | Commands, tools or path prefixes that never trip the guard. |
+| `guard.protectedPaths` | `['.dsh','AGENTS.md','package.json','.github/workflows']` | Self-modification surfaces that force strong-tier review. |
+| `guard.interopDefend` | `auto` | Relationship with `dsh-defend`: `auto` audits coexistence, `none` stays silent. |
+| `escalation.threshold` | `2` | Failures within the window that raise the tier. |
+| `escalation.windowMs` | `60000` | Failure-counting window. |
+| `escalation.ttlMs` | `180000` | How long an escalation stays in effect. |
+| `escalation.fallbackTtlMs` | `300000` | TTL used after a fallback landing was taken. |
+| `escalation.signature` | `true` | Count same-signature recurrences instead of every failure. |
+| `routingMode` | `auto` | `auto` \| `strong` \| `cheap` \| `delegated` \| `off`. |
+
+All keys can also be edited live from the `autotier` settings namespace
+(`$DSH_HOME/settings.yaml`); a write that violates a cross-field requirement is
+refused at save time and the last good policy stays in effect.
+
+## Tools & surfaces
+
+| Surface | Kind | Purpose |
+|---|---|---|
+| `/tier` | command | `auto` \| `strong` \| `cheap` \| `off` \| `status`; session-scoped override. |
+| `tier_status` | tool | Current tier, mode, escalation TTL and guard state. |
+| `tier_route` | tool | Route one intent string without sending a request (dry run). |
+| `ctx.autotier` | service | `status()` read surface for other plugins. |
+| `autotier/route` | serial event | Third parties may veto a proposed tier. |
+| `autotier/tier-changed` | emit event | Observability when the effective tier changes. |
+
+## Permissions & data
+
+- **Files** — the plugin reads nothing and writes nothing except through the
+  shared settings service (the `autotier` namespace).
+- **Network** — the only outbound traffic is the judge call, which goes through
+  the normal `ctx.llm` path and the configured provider.
+- **Session log** — the plugin appends no custom session events. The routing
+  trail is the plugin logger plus the live `autotier/tier-changed` bus event;
+  the only append it makes is the `plan/mode` fallback when the plan-mode
+  service is absent. Custom event types are fail-closed on `0.1.2-alpha.1` and
+  later, so no durable plugin-owned record is written.
+- **Secrets** — no credential is read, logged or stored by this plugin.
+
+## Security boundaries
+
+- The guard is a **defence in depth**, not a sandbox. It denies the patterns it
+  knows on the cheap tier and never weakens `dsh-defend`, the approval service,
+  or the sandbox policy. Keep those enabled.
+- The guard protects only the tiers listed in `guard.tiers` (cheap by default).
+  A strong-tier turn is not blocked by design: the strong model is the reviewer.
+- If the guard itself throws, the call is escalated to the strong tier rather
+  than allowed — a broken guard must not become an open door.
+- `/tier off` disables routing entirely; the harness then behaves exactly as it
+  did before the plugin was installed.
+
+## Known limitations
+
+- The rule layer is deterministic and therefore finite: a novel phrasing of a
+  complex request may start on the cheap tier and escalate only after a failure
+  or a guard denial. The judge call covers the low-confidence middle.
+- Escalation is per-agent and in-memory; a harness restart starts from `auto`.
+- Tier switching resets the provider prompt cache for the changed request, so
+  very chatty sessions may see a small cache-miss cost on the switch turn. The
+  hysteresis thresholds exist to keep that rare.
+- The plugin routes conversation requests. Compaction and title generation are
+  separate host seams; align their own model settings with the cheap tier if you
+  want the same cost profile (`docs/supporting-lanes.md`).
+- `followSession: true` on the cheap tier means an explicit session model choice
+  wins; in that case the cheap tier cannot force its own model.
+- **No Settings card or composer pill yet.** Routing is fully automatic and the
+  host surface (`ctx.autotier.status()` / `catalog()`, `/tier`, `tier_status`,
+  `tier_route`) is complete; the browser half that renders a Settings tab and a
+  composer tier pill is planned for v0.2.
+- **A model picked in the GUI is not detected automatically.** The router does
+  not watch the `agent-default-model` document, so switching models there does
+  not by itself stop routing — use `routingMode: delegated` or `/tier off`.
+- **Fingerprint posteriors are in-memory.** They reset on restart and re-learn
+  from the judge's cold-start fallback; persisting them through the settings
+  document is planned for v0.2.
+- **The attempt-first middle band ships disabled.** `intent.attemptBand.enabled`
+  stays `false` until the calibration corpus and its metric gate land (v0.2).
+
+## Development
+
+```bash
+pnpm install
+pnpm run typecheck      # against the local harness checkout type faces
+pnpm run typecheck:ci   # against the published 0.1.2-rc.1 faces (what CI runs)
+pnpm test
+pnpm run build
+pnpm run verify:self-contained
+pnpm run verify:artifacts
+pnpm pack
+```
+
+`pnpm run build` emits `lib/types` (tsc declarations) and `lib/index.js`
+(tsdown bundle). Tests use the published host packages directly — real
+`Context`, real session/tools/commands/settings services — plus one real Loader
+composition over a temporary `cordis.yml`.
+
+## Topics
+
+`dsh`, `dsh-plugin`, `deepseek-harness`, `deepseek`, `cordis`, `router`,
+`model-tier`, `cost`, `auto`.
+
+## Contributors
+
+PerryLink. Issues and pull requests are welcome at
+<https://github.com/PerryLink/dsh-autotier/issues>.
+
+## License
+
+Apache-2.0. See [LICENSE](./LICENSE) and
+[THIRD_PARTY_NOTICES.md](./THIRD_PARTY_NOTICES.md).