[iLevyTate]

Summary

From a review of 85 real analysis results from one session, 33 of which landed in Uncategorized, plus a replay over the full history of 1,164 stored results. Each fix stays inside an existing code path: no new services, settings or dependencies.

• Archives are filed by their contents. documentAnalysis.js read the entry listing and then hardcoded the category to 'archive', so every zip of .stl parts reached Uncategorized even though the 3D print folder lists .stl. When at least half of the file entries share one type, that type now picks the folder through the existing getIntelligentCategory. The result is used only when it lands on one of the user's own folders.
• The filename fallback matches whole words. It used filename.includes(word), so the folder name "Work" matched "network" and the description word "code" matched "barcode". Matching is now on whole words; a plural in the file name still matches a singular folder word.
• Filename-only results report their confidence honestly. These are results where the file's contents were never read. They used to report 65–75%, higher than many real content analyses. createFallbackAnalysis, the Office-extraction fallback and an unmatched archive now report FILENAME_ONLY_CONFIDENCE (50). That is below auto-organize's 75% default, so these files are left for review.
• dropPromptEchoes clears answers the model copied from its own prompt. It checks summary, purpose, project, reasoning, type and entity. A field is cleared when it reproduces a schema instruction or a smart-folder description: nearly all of its words come from that text, and it covers at least 40% of the text. Confidence is then capped at 50. Replayed over the 1,164 stored results, the guard cleared 64 files, all of them genuine copies, with no false positives. Examples: "Art, graphic design, images not related to other categories, logos" (32 times), "A concise 1-2 sentence summary of the document's content." (13), and "Research on SCANUE…", which had filed a banner under Research at 90%. The guard runs in the document, image and media paths.
• Disagreement now caps confidence. When the AI's folder is kept but the similarity matcher confidently prefers a different folder, calibrateConfidence caps the score at 65 (llm_embedding_disagree).
• "Create folder for " can now actually appear on Organize. It grouped files on a single field by exact text. For a filename-only analysis that field is the file's own name, so no group ever formed. The new findRecurringTheme keeps one tally per term across named entities and shared keywords, and skips file-name keys and form words such as file types or "document". A theme still needs at least 3 files.

Scope

• Area(s): analysis (document / image / media), folder matching, Organize's uncategorized bar
• Risk Level: medium. Confidence values change, which affects auto-organize gating: filename-only results are no longer auto-moved.
• Breaking Changes: none

Type of Change

• Bug fix
• Enhancement
• New feature
• Refactor
• Documentation update
• Breaking change

Test Plan

Automated

• npm run format:check / npm run lint (changed files, plus pre-commit hooks)
• npm test: full suite, 940 suites green after adding dropPromptEchoes to two test mocks of analysis/utils
• npm run typecheck, npm run verify:checkjs-ratchet (floor raised 493 → 494 for the new uncategorizedThemes.js), npm run verify:analysis-routing
• Additional tests added or updated:
  • an archive of .stl files goes to 3D print at 70%; a mixed archive stays in the generic bucket at 50%
  • whole-word matching: network ≠ Work, barcode ≠ code, plural and phrase matches still work
  • fallback confidence cap
  • the echo guard, tested on real copied values and on real answers that only share some words with a folder description
  • the disagreement cap
  • findRecurringTheme, including the old bug where files grouped on their own file names
  • the .psd fallback test now expects 50

Manual QA

• Manual checklist completed (see docs/TESTING.md)
• Not applicable (explain below)

Manual QA notes: not run in the app yet. To check, re-analyze a zip of .stl files (it should go to 3D print), an unreadable .docx (it should show 50%), and three uncategorized files that share a keyword (the Organize bar should offer a folder).

Checklist

• I scoped this PR to one logical change (categorization accuracy)
• I self-reviewed code and naming for clarity
• I updated docs/config references where needed (the checkjs count in CLAUDE.md)
• I called out follow-up work or known limitations

Known limitations / follow-ups

• On the reviewed session's remaining uncategorized files, no theme reaches 3 files once the zips are filed; the largest are pairs. The threshold stays at 3, because junk fallback keywords such as "technical, manual, guide" would otherwise create noise.
• scan-2025-03-19.docx still matches Research, because "scan" is a whole word in its name and the Research description mentions SCAN. It is now reported at 50% and left for review rather than shown at 70%.
• Some misfiles need folder-description edits, not code: no description mentions tax forms (W-4), health insurance or ID documents.
• Existing history isn't rewritten. The fixes apply to new and re-analyzed files.