File Documents

File documents

Use this when the person asks to find, rename, sort or file documents: "find the invoice from Acme in my Downloads, rename it properly and put it where it belongs", "file the invoices in this folder", "sort out these scans", "where did the plumber's invoice go?". Names like scan0001.pdf, document(3).pdf or IMG_2231.pdf say nothing about the file: read the documents themselves.

1. Find the candidates

• The folder is the one they name ("my Downloads" is ~/Downloads). "This folder" or "this file" is what is on screen: spoken requests carry it in the conversation context ("Screen: the Files page shows …"); otherwise os_ui action=state returns it under files (folder and selected file).
• system_documents action=read path=<folder> reads every PDF and image directly inside the folder, scans and photos of documents through OCR on this computer. Pass paths for several files. Documents past the limit come back under skipped: read them in a second call.
• Searching the whole computer for a word: system_find_files kind=pdf text=Acme first. On macOS Spotlight looks inside PDFs (not inside scans); on Linux it matches names only, so read the likely folders (Downloads, Desktop, Documents) instead.

2. Identify the right document

• Each document comes back with its text and hints: kind, vendor, date (issued), due_date, number, total, currency, and a suggested_name. Hints are guesses: confirm them in the text. The vendor is who issued the document, never the bill-to customer; the date is the invoice date, not the due date.
• Receipts, statements, quotes, payslips and contracts are not invoices: leave files that do not match alone unless they asked to sort everything.
• date_ambiguous: 03/09/2026 is 3 September or 9 March. Use the document's other dates, its country (currency, address) or ask.
• Files listed together under duplicates are byte-for-byte copies: file one and offer to move the other to the Trash (that always asks). Same vendor, number and total but different files is the same invoice twice (an emailed copy and a scan, say): ask which to keep.
• Several matches for "the invoice from Acme": choose by what they said (the latest, the amount, the month) or ask, naming two or three by date and total. No match: say what you found instead ("two receipts and a bank statement, no invoice from Acme").

3. Name it

• Follow the person's convention when their filed documents show one (the samples from system_documents action=places, such as 2026-08-02 Telstra invoice 9921 $89.00.pdf): the same date format, word order and whether the amount is included.
• No convention to follow: YYYY-MM-DD Vendor kind number total.ext, for example 2026-09-14 Acme Corp invoice INV-1234 $560.00.pdf. suggested_name has this shape already. Leave out what is not known rather than guess, keep the extension, and use short vendor names (no "Pty Ltd" or "GmbH").

4. Find where it belongs

• system_documents action=places lists the folders documents are already filed in (Invoices, Receipts, Finances, Bills, Tax, Statements and the like under Documents, Desktop, the home folder and cloud drives), each with its layout, subfolders and newest files.
• Follow the structure: by year means the year of the document's date; by vendor or topic means the matching subfolder (invoices with invoices, receipts with receipts); flat means the folder itself. A place they name ("put it in my tax folder") wins.
• In a by-year layout you may create the missing year folder (one level, same pattern). Anything bigger, or no filing place at all: ask where these should go and suggest one (for example ~/Documents/Invoices/2026). Never invent a new folder tree on your own.