docs: README onboarding overhaul + TypeScript plugin README

[klausagnoletti]

I couldn't figure out how to actually use the tool from reading the README. Eventually I had my AI agent explain it to me — and once it did, it all made sense. I figured I probably wasn't the only one bouncing off the front page, so I had it turn that explanation into proper documentation.

What changed

README.md — four sections added:

• What it is / What it isn't — appears right after the one-liner. The main thing missing: new users (including me) read this as an auto-fix tool. This section makes it clear up front that desloppify finds and queues the work; you or your agent does the fixing.
• Supported Languages — the --exclude flag doesn't filter findings from orphaned, single_use, and cycles detectors #1 question any new user has ("does this work for my stack?") was completely unanswered. Two-tier table: 9 full plugins with extensions and external tool requirements, then the 23+ generic plugins listed out.
• Quick start — three commands to go from zero to first scan, with a note on excluding vendor/build dirs and adding .desloppify/ to .gitignore.
• Key concepts — one-sentence definitions of overall score, strict score, triage, and subjective review. These terms show up everywhere in the tool output but were never explained.

desloppify/languages/typescript/README.md — created. TypeScript is the only full plugin with no README. Covers requirements, project detection, every analysis phase in a table, exclusions, auto-fixers, and maintainer notes.

Why each piece matters

The agent prompt is great once you know what you're dealing with — but right now a new user hits that wall of text before they know what the tool is or whether it supports their language. The new sections front-load exactly that context so the agent prompt lands with meaning instead of confusion.

🤖 Generated with Claude Code

[peteromallet]

Thanks for putting this together, @klausagnoletti — the intent to improve onboarding is appreciated.

After review, we're going to pass on this one. A few reasons:

• The TypeScript README has incorrect test paths (desloppify/languages/typescript/tests/ — tests are actually at desloppify/tests/) and includes draft-note language ("The framing to nail:") that would need cleanup
• Detailed internal layout docs (like the TS README's maintainer notes) tend to drift quickly as the codebase evolves, and inaccurate docs can be worse than no docs
• We're keeping the README minimal for now — the tool's built-in coaching (scan, plan, next commands) is the primary onboarding path

No hard feelings — this is a project direction choice, not a quality judgment. If you're interested in contributing, code fixes and bug reports are always welcome!

[klausagnoletti]

Hey

Fair enough about the TS stuff

First time I encountered the project I tried to figure out what it exactly was by reading the docs over a few times. I literally couldn't. I figure I'm not the only one. In the end of the day the chance of someone using your project is higher if they understand how.

But suit yourself. At least I understand now. By reading the docs my AI wrote.

[peteromallet]

Fair point, @klausagnoletti -- that's useful feedback. If you couldn't figure out what the tool does from the README, that's a real problem regardless of whether this specific PR was the right fix.

The rejection was about the approach (detailed docs that drift, incorrect paths), not the underlying concern. I'll look at adding a concise "what this is + quick-start" section to the README. That addresses the discoverability gap without the maintenance burden.

Thanks for pushing on this.

[klausagnoletti]

Thanks. That was my point exactly. Feel free to cherry pick from my PR