About the implementation and examples
Engineering notes draw on author-supplied MailTrace development reports through 13 October 2026. They describe the documented revision, including local work, rather than independently verified live deployment. Experiment designs and architecture proposals describe work to evaluate. Examples are educational, use synthetic data and are not copied production code.
Translate a state into its consequence
“No active vector generation” is useful to a developer. “Prepare evidence to search its contents” gives a user a next action. “OCR unavailable” should explain that a scanned document can be viewed but its text is not yet available to answers. A successful upload and successful text extraction deserve different statuses.
The documented evidence work supports saved titles, previews, source links, filters, reversible exclusions and retries. These are the foundations for a comprehensible library. Each item can explain whether it is included, searchable, waiting for preparation or needs attention without asking the user to diagnose infrastructure.
Keep progress separate from completion
This proposed copy map illustrates the level of detail. It is interface wording, not a statement that every listed state already appears in the deployed product.
{
"queued": "Waiting to prepare your evidence",
"running": "Preparing 8 of 24 items",
"ready": "Ready for evidence search",
"stale": "Evidence changed. Prepare it again to include the updates.",
"unsupported_scan": "You can view this scan. Text extraction is not available yet."
}Make paid actions deliberate and ordinary browsing stable
A user opening a case expects saved issues and evidence, not an invisible analysis run. Preparation, asking a question and reviewing a consolidation should be explicit actions with understandable scope. Reopening a saved result should not request consent again for work that is already complete.
Assess the interface through a task rather than a screenshot. Can someone find a PDF, see where it came from, understand why it is unavailable to Q&A, retry preparation and reopen the result? If they can, the interface is explaining the system. If they must read logs to distinguish “uploaded” from “searchable,” it is exposing the system instead.