Update README positioning

README.md

@@ -1,12 +1,35 @@
 # Distil.
 
-Fast dead-code scanner for Java and Spring projects.
+Find the code your Java project forgot about.
 
-Distil. is a read-only CLI static analysis tool that reports likely dead code with confidence scores. It is designed to help humans and coding agents review cleanup candidates before making source changes.
+Distil. is a read-only scanner for Java and Spring codebases that reports likely dead code, unwired features, and suspicious public APIs with no in-project callers.
+
+It does not delete code or prove that removal is safe. Instead, it gives developers and coding agents high-signal review candidates before they make source changes.
+
+Use Distil. when you want to:
+
+- Find dead code before it becomes maintenance debt.
+- Spot public methods and constructors that no code path appears to call.
+- Investigate features that look implemented but may not be wired into runtime behavior.
+- Review cleanup candidates with confidence scores instead of guessing from text search.
+
+## Why Distil.
+
+Most codebases have more dead paths than teams realize. Some are safe cleanup candidates. Others are more interesting: half-connected features, stale diagnostics, forgotten API surfaces, or code that explains why a system behaves differently from the way the source appears to promise.
+
+Distil. is built for that review loop. It is not a deletion engine. It is a precision-first signal generator for humans and agents that need to understand where Java code has drifted away from actual use.
+
+## Real-World Signal
+
+Distil. has been tested on internal Java tools, including framework-heavy and agent-facing codebases.
+
+In one recent validation pass, Distil. scanned 117 Java files across two real projects and produced 32 review candidates. One small candidate set led directly to an unwired diagnostic path behind a real tool-visibility bug.
+
+That is the intended shape of the tool: low-noise findings that help reviewers find both cleanup opportunities and suspicious disconnected code paths.
 
 ## Current Status
 
-Distil. is in pre-release development. Treat its findings as review candidates, not as automatic deletion instructions.
+Distil. is in pre-release development. Treat findings as review candidates, not deletion instructions.
 
 | Area | Status |
 |------|--------|
@@ -16,6 +39,8 @@ Distil. is in pre-release development. Treat its findings as review candidates,
 | Output formats | Terminal, JSON, SARIF |
 | Distribution | Source build only until release binaries are published |
 
+Official release binaries are not yet published. For now, install from source.
+
 ## What It Detects
 
 | Layer | Detects |
@@ -27,6 +52,24 @@ Distil. is in pre-release development. Treat its findings as review candidates,
 
 Distil. prefers precision over recall. When confidence is too low, it should stay silent rather than produce noisy findings.
 
+Example finding:
+
+```text
+L3 95% src/main/java/com/example/TaskContextFilter.java:58
+   com.example.TaskContextFilter#getCurrentContext()
+   Public method with zero project-wide calls.
+```
+
+The right next step is review, not blind deletion. This kind of signal may be a cleanup candidate, a missing integration point, or a diagnostic surface that should be wired into an error path.
+
+## Where It Helps
+
+- Cleanup reviews before a refactor.
+- Agent-assisted coding reviews where you need compact, high-signal evidence.
+- Spring application maintenance, where entry points and framework callbacks can make naive dead-code checks noisy.
+- Debugging investigations where a method exists but no project code appears to call it.
+- CI or release checks that should report suspicious code without mutating files.
+
 ## Framework Awareness
 
 Distil. recognizes common Java framework patterns that often confuse simple dead-code scanners, including:
@@ -46,7 +89,7 @@ Framework awareness reduces false positives, but it does not make deletion risk
 
 Distil. is detect-only.
 
-It does not:
+It never:
 
 - Delete files.
 - Edit source code.
@@ -155,7 +198,8 @@ See [docs/user/configuration.md](docs/user/configuration.md) for details.
 ## Known Limitations
 
 - Findings are cleanup candidates, not proof that deletion is safe.
-- Dynamic framework behavior, reflection, generated code, and custom dependency injection can hide live code.
+- Public APIs may be used by external callers that are not visible inside the scanned repository.
+- Reflection, dynamic dispatch, generated code, and custom dependency injection can hide live code.
 - Gradle parsing is based on common declaration patterns and may miss custom configurations or version catalogs.
 - Multi-module Maven support follows declared modules; unusual reactor setups may need manual review.
 - Java is the only supported language in the current release line.