---

🔥 Six Forging Engines

Engine	Form	In one line
⚡ thunderforge-capture	Plugin	LLM payload capture: transparent proxy + secret redaction + rotation + an index.jsonl stream (clean-room implementation)
🧠 thunderforge-skills	Skill ×5	Five-layer knowledge base: entry index + architecture standard + pitfalls handbook + portrait-adaptive communication (dsh-buddy) + release checklist
🔨 thunderforge-scaffold	Model tools	Conversational scaffolder: four zero-dependency templates (tool / events / webui / llm-adapter), smoke-tested the moment they're generated, plus an upgrade advisor for older skeletons
🔍 thunderforge-debugger	Model tool	Dual-source trajectory waterfall: session logs × capture payloads aligned by the millisecond; browse, diff two payloads, watch live, token cost rollup
🧰 thunderforge-profile	Model tool	Profile management + one-shot dev presets (only ever creates new dirs — never touches your existing setups)
🚢 thunderforge-release	Model tool	Publish gate: smoke + raw-registration contract check + zero-harness dependency rule + changelog consistency, with manual steps left to the human

Also exportable: dsh-thunderforge/contract — the real-machine tool-contract checker as a pure function library, and mcp.mjs — an MCP stdio entry exposing five tools to non-dsh hosts.

🚀 Installation

# from npm (recommended)
dsh plugin --profile <profile> add dsh-thunderforge
# or from GitHub
dsh plugin --profile <profile> add github:oneinitAI/dsh-thunderforge
# or a local directory (developers)
dsh plugin --profile <profile> add /path/to/dsh-thunderforge

Restart the target app after installing (profiles compose at boot; for web, restart dsh web), then verify:

dsh --profile <profile> --dump-config    # should show a "# == dsh-thunderforge" layer

Removal is always reversible: dsh plugin --profile <profile> remove dsh-thunderforge

⚠️ Layer order (critical for capture): after installing into an existing profile, move dsh-thunderforge to the front of the profile's dsh.profile.bundles array (before @deepseek-ai/dsh-base) — capture wraps adapter registration and silently misses if applied after base. Presets made via thunderforge_profile are ordered correctly already.

Then just tell your agent:

Build me a DSH plugin with a webui — it invokes thunderforge_scaffold; the skeleton ships with debug instrumentation and smoke tests, verified as it lands.

A clean dev environment in one line:

You: create a dev preset named demo
AI:  (thunderforge_profile) → tf-dev-demo ready
     dsh plugin --profile tf-dev-demo add <your-plugin> && dsh --profile tf-dev-demo

🛠️ The Forging Journey

  Create ──► Develop ──► Debug ──────────► Verify ───────► Ship
 scaffold    skills      capture +         dev preset      release gate +
  smoke on   on demand   debugger          clean profile    checklist skill
  generate               dual-source ⚡    create-only ✅   human owns publish ✅

• Each step's output feeds the next: the skeleton's thunderforge.debug.json declares the capture index stream and event prefix, which the debugger consumes directly.
• Real-runtime acceptance: plugin add + --dump-config on dsh 0.1.1-rc.2 loads every row ✅ (including one patch-format bug caught — and fixed — by the real CLI).

📦 Status

• ✅ node --test 59/59 (incl. real-machine contract tests); all four templates generate-and-smoke
• ✅ Real-runtime verified end to end: conversation → scaffold → capture persisted → aligned waterfall
• ✅ Live skill-trigger evals: train 6/6, validation 4/4 (sampled in a web session)
• 🙋 Try it yourself: dsh --profile <your-profile> "invoke thunderforge_scaffold ..."

📚 Docs

Doc	Content
HANDOFF	Handover guide: overview, architecture constraints, release flow (read this first)
DEVELOPMENT	Architecture decisions + code map + testing philosophy + skill authoring canon
ROADMAP	Roadmap: improvement & expansion candidates (all shipped)
PRD	Phased product plan & acceptance records
RELEASE	Release checklist & one-shot release
NETWORK-NOTES	Network troubleshooting manual
CONFIGURATION	Configuration guide: every config key across the six engines and buddy, override recipes

🙏 Acknowledgements & Upstream Licenses (required reading)

ThunderForge stands on the shoulders of community giants and strictly respects the open-source license of every upstream repository:

Upstream	License	Role in ThunderForge
deepseek-harness	MIT	The runtime foundation and source of official conventions
dsh-plugin-dev-skills	MIT	Vendored verbatim → skills/arch-standard/ (upstream license text included)
dsh-plugin-guide	Apache-2.0	Vendored verbatim → skills/pitfalls/ (license & NOTICE retained)
dsh-replay	MIT	Vendored verbatim → src/debugger/session-log.js (provenance header)
dshp	MIT	Absorbed into first-party modules (src/profile/store.js etc.; MIT attribution kept in file headers and the ledger)
dsh-trajectory-debug	MIT	Concept reference (no code vendored), recorded in the ledger

• All vendored files are unmodified — only a provenance header is prepended; every upstream license text ships with the package (see LICENSES/).
• The Apache-2.0 component keeps its license and NOTICE at file level, as its license requires.
• An unlicensed payload-capture component exists in the ecosystem; ThunderForge explicitly does not include it — its function is clean-room implemented here, with none of its code used or consulted.

📄 License

MIT © 2026 ThunderForge Contributors

Provided "as is"; claims regarding upstream components remain governed by their original licenses. Full ledger: LICENSES/README.md.