From first drop to a safe rename.

01

How Lumen works

Lumen reads a file, identifies useful details and proposes a consistent filename. It does not rename the file until you approve the proposal and execute the rename.

Supported files

Video, audio, archives, design files and legacy .doc, .ppt and .xls files are not analysed. Visible unsupported items normally appear in Unprocessed with a reason; hidden or internal folder items may be omitted from a scan. Files above roughly 500 MB are also skipped.

02

Run your first set of files

1. Prepare the AI model.

   Local AI is selected by default. On an Apple-silicon Mac with 24 GB+ memory, open Settings → AI Provider and start the Phi-4 14B model download of approximately 8.26 GB before first use. On an Intel Mac, configure and enable a cloud provider instead.

2. Add files in Drop Zone.

   Drag in individual files or one or more folders, or use Choose Folder… / Choose Files…. Multiple folders remain grouped by source.

3. Check the queue.

   Press Space to open Quick Look for the first highlighted row, or click any row’s eye button. Highlight several rows with ⌘-click, ⇧-click or ⌘A; Y and N tick or untick every highlighted row. Tick files and choose Remove to leave them out; Restore brings them back.

4. Confirm the essentials.

   At the bottom of Drop Zone, check the active AI model, the Photo naming switch and the provider-ready chip. The chip opens Settings when the model or API key needs attention.

5. Process, then review.

   Click Process Files. The Progress tab shows the active model, current file and running counts. When a run completes, it adds a short note when there is something to report — how many skipped files the AI declined for safety and, for cloud runs, approximate input and output tokens when reported. If a run contains both documents and photos, Results separates them into Documents and Images segments.

03

Choose an AI model

Open Settings → AI Provider to choose the analyser for the next run.

Set up a cloud provider

The steps are the same for every provider; only where you get the key differs.

1. Create an account with the provider and generate an API key (per-provider notes below). Copy it straight away — most providers show a key only once.
2. In Lumen, paste the key into that provider’s row in Settings → Cloud providers and click Test. Lumen sends a short fixed check with your key (no document) and reports “Key works”, “Key rejected”, or that the account has no credit or usage left.
3. Switch the provider on. Enabled means Lumen may run it and use your account; it is off until you switch it on.
4. Choose it as the active model — under AI Provider in Settings, or the Model menu on the Drop Zone.
5. On the first document you send, read the disclosure and accept it.

Getting a key, per provider (as of August 2026 — providers change their sites, plans and prices; their own pages are authoritative)

• Ollama Cloud — Sign up free at ollama.com (one account per person), then create a key under Settings → Keys (ollama.com/settings/keys); keys don’t expire. A free account is enough for the key to work: the Free plan gives light usage of Ollama’s cloud models with a session limit and a weekly limit, and paid plans raise them. Usage counts against your plan’s limits — Ollama publishes no per-token price — so Lumen shows token counts for it but no cost estimate; you can see how much of your plan you have used at ollama.com/settings, and Ollama e-mails you at 90% of a limit. Lumen talks to ollama.com directly and does not use or need the Ollama app on your Mac; it uses gemma4:31b, one of Ollama’s low-usage open-weight models, which runs on Ollama’s cloud service, not on your Mac. Ollama states (its privacy policy, March 2026) that prompts and responses are processed transiently and never used for training.
• OpenAI — Sign in at platform.openai.com → API keys (platform.openai.com/api-keys) → Create new secret key; the key is shown once, so copy it then (some countries ask for a one-off phone verification for the first key). The key works only after you add a payment method and buy prepaid credit under Settings → Billing (minimum US$5; auto-recharge is on by default — switch it off if you don’t want automatic top-ups). A ChatGPT subscription does not cover the API. OpenAI states API inputs and outputs are not used for training unless you opt in. Lumen uses gpt-5.6-luna (list price US$0.20 in / US$1.20 out per million tokens).
• xAI — Sign in at accounts.x.ai, open the console at console.x.ai → API Keys → Create API Key (keys belong to a team; the default team is fine), then buy prepaid credit under Billing → API spend management before use — there is no free tier, the card you pay with stays on file for top-ups, and Indian payment cards are not accepted. xAI states API data is not used for training unless you opt in. Lumen uses grok-4.3 (US$1.25 / US$2.50).
• Gemini — Sign in at aistudio.google.com → API Keys (aistudio.google.com/apikey) → Create API key. The key works immediately on Google’s Free tier with no card — but on the Free tier (outside the EEA, UK and Switzerland) Google uses what you send to improve its products, human reviewers may read it, and its terms tell you not to submit sensitive or personal information. For personal documents, set up billing in AI Studio (a Google Cloud billing account and at least US$10 prepaid) so the paid-tier terms apply, under which Google states it does not use your prompts to improve its products. If a Gemini key that used to work is suddenly rejected, create a fresh one — Google is retiring its older key type. Lumen uses gemini-3.5-flash (US$1.50 / US$9 on the paid tier).
• Claude — Sign in at platform.claude.com → Settings → API keys (platform.claude.com/settings/keys) → create a key (choose an expiry; pick “Never” if you don’t want to re-paste it later). A brand-new account is first asked for a short organisation/use-case form and payment details; the key won’t work without credit on the account, so expect to buy prepaid credit under Settings → Billing. Anthropic states API inputs and outputs are not used for training by default. Lumen uses claude-sonnet-5 (US$2 / US$10).

For the exact models and cloud file-handling differences, see the supported-model comparison.

04

Shape the filename

Under Settings → Filename Format, choose the included fields, drag them into order and select a separator. Lumen automatically uses separate schemas for personal and transactional documents.

• Personal documents include passports, certificates, IDs and visas.
• Transactional documents include invoices, statements, letters, contracts and warranties.
• A required field Lumen cannot determine appears as UNKNOWN.
• Optional Brand and ID Suffix fields are left out when they do not apply. Brand is available in the default transactional schema.

05

Name photos by content and metadata

Photo naming is off by default. Turn on Photo naming in Drop Zone or Settings → Photo Naming to name images that contain little or no readable text.

Choose and reorder these under Settings → Photo Naming → Photo files. A selected Description, Place, Date or Label is left out when that value is unavailable or blank. If no selected field resolves, the photo goes to Unprocessed. Photo filenames use the same separator as documents. When two photos would receive the same name, Lumen adds (2), (3) and so on.

Photo location modes

Off

No place is included.

Raw

Coordinates stay on your Mac and can appear directly in the name.

Resolved

The default. After separate consent, coordinates are sent to Apple’s geocoding service to obtain a place name such as Dubai, AE.

06

Keep people’s names consistent

When Lumen finds a person it does not recognise, the name appears in Name Review. For each name, choose one action:

• Map the variation to an existing canonical name, or choose Or enter a new canonical name.
• Ignore permanently a word or person who should never be treated as an owner.
• Use the clock button to set the name aside for now, or choose Ignore all pending to ignore every undecided name at once.

Click the dynamic Save Decision / Save Decisions button. Mappings and permanent ignores are applied to matching proposals in the current run and remembered for later files; setting a name aside is not persisted.

07

Approve and execute names

Each row in Results shows the original name, proposed name, notes, document type and confidence. New proposals arrive approved (ticked) by default, but no file is renamed until you click Execute Renames. Review every ticked row first.

• Approve or Reject a row, or use Select all to change every tick in the active Documents or Images segment.
• Highlight several rows with ⌘-click, ⇧-click or ⌘A. Y approves and N rejects every highlighted row; Space previews the first and Return edits a name.
• Use Edit Name… for a one-off correction. Use Name Review when the same person’s name needs fixing across several files.
• Use Try with [provider] when it is offered on an eligible low- or medium-confidence result, or on a Local AI photo that has no visual description.
• Send to Batch Rename moves ticked, resolved rows instead of renaming them here. Choose with Suggested Names or with Original Names; nothing moves on disk until you execute in Batch Rename. Return to Results restores sent rows until they are renamed there or a new run starts.
• Click Execute Renames only after checking the approved subset.

For loose files, macOS may ask you to grant access to each parent folder before an in-place rename. Folders selected or dragged into Drop Zone already carry that access. Lumen reuses saved access when available, but macOS may ask again.

08

Restore a previous session

Your results and review state are saved automatically as you work. If Lumen quits before you rename — after a crash, a restart or an ordinary quit — the next launch can show a Restore previous session? card on the Drop Zone with the saved counts.

• Restore Session brings back saved proposed names, approvals, hand edits, photo numbering and the Name Review queue. Rows previously sent to Batch Rename return to Results or Unprocessed.
• Restored document proposals are reconciled with your current Name Mappings and filename-safety rules. A filename you edited by hand remains authoritative.
• Discard starts fresh. A later run replaces the saved session once it produces recoverable results.

09

Handle files Lumen could not name

A file appears in Unprocessed when it is unsupported, unreadable or could not be named confidently. The Reason column explains why.

• Manually Name File lets you type a safe name yourself. Highlight it and press Space for Quick Look or Return to open the editor. Renaming shows a confirmation first, and duplicate typed names in the same folder are caught before anything moves.
• Try with [provider] re-attempts an eligible file with an enabled cloud model. Try Selected with… handles a ticked subset. Successful rechecks move to Results; files that still cannot be named remain here.
• Rename [n] Tagged File(s) executes safe manual names directly from Unprocessed.
• Send to Batch Rename moves the ticked rows — or every visible row when none are ticked — to Batch Rename. Return to Unprocessed sends them back with typed names intact; clearing or replacing the Batch working set also returns them. Returning stops once a row is renamed there or a new run starts.

Common reasons

Media — cannot be read by AI

Video and audio have no supported text extraction path.

Legacy Excel (.xls)

Open it in Excel, save it as .xlsx, then process the copy.

Too large for processing

Files above roughly 500 MB are skipped. For an accepted PDF larger than about 30 MB, Lumen reads text from a temporary copy of up to the first five pages; if identifying information appears later, use a smaller focused copy.

AI refused

The provider may decline sensitive or credential-like content. Name it manually.

Content too generic or limited

Try a cloud model or enter a name manually.

Encrypted or password-protected

Remove the password and save an unprotected copy first.

10

Build rule-based names with Batch Rename

Batch Rename is for predictable transformations: adding counters, removing repeated text, changing case or rebuilding names from a date and prefix. Use Pick folder…, drag in folders or files, or receive rows sent from Results or Unprocessed. Results rows can arrive with their suggested names as the working text. Multiple folders stay grouped.

Rows sent from Results or Unprocessed can return with Return to Results or Return to Unprocessed; clearing or replacing the working set returns them automatically. They reappear exactly as they were, until they are renamed here or a new processing run replaces the source list.

Rules run in this order

1. Find / Replace changes the existing filename.
2. Discard original filename, when enabled, clears the remaining stem.
3. Prefix and Suffix are added and their tokens are substituted.
4. Case changes the filename stem; the extension is left unchanged.

Tokens and regular expressions

• {date} inserts a date in YYYY-MM-DD format. Choose File modified, Today or EXIF under Date for {date}.
• {#}, {##}, {###} and {####} insert a padded counter beginning at the starts at value.
• Find accepts regular expressions. Reuse capture groups in Replace as $1, $2 and so on.
• Case options are As-is, lowercase, UPPERCASE and Title Case.

Counters follow the order currently shown in the preview. Highlight several rows with ⌘-click, ⇧-click or ⌘A; Space previews the first, while Y includes and N excludes every highlighted row.

11

Undo a rename

Lumen writes a local rename log after successful Results, Batch Rename and manual Unprocessed renames. The logs live inside the app and remain available after relaunch.

1. Open Revert Renames and choose a previous run.
2. Tick the files to restore, or use Select All.
3. Click Revert [n] Selected and confirm.

Lumen warns when a selected file appears to have been modified or replaced since it was renamed. The warning is advisory: if you continue, the file is reverted as it exists now. A revert can fail if the file moved, the original name is no longer available or folder access is missing.

Undoing keeps a per-file recovery record and stops before later files if an update cannot be confirmed. If Lumen quits mid-revert or cannot write the final status into the rename log, revisiting or refreshing Revert Renames tries to apply the recovery information already recorded. A Revert History notice explains what was recovered or still needs attention.

Use Open log file… to open a rename log kept outside Lumen’s data folder. Lumen reads it under a size limit, validates every usable entry, asks for the required folder access and identifies where the files will be restored. If that log contains pending recovery information, Lumen tries to apply it when the file is reopened.

12

Maintain Name Mappings

Name Mappings is Lumen’s name database, stored on your Mac. A mapping connects a name as found to the canonical spelling used in filenames.

• Canonical Mappings connect variations to a preferred spelling, keeping one person’s documents consistent.
• Use Add Mapping or Edit Mapping to maintain those relationships.
• Permanently Ignored entries are never proposed as owners. This is useful for third parties who appear in a document but do not own it.
• Mappings persist between launches and are used in later analyses. Up to 300 saved mappings are sent with each document request when you use a cloud provider; see Privacy and permissions.

Changes are written when you save. If a write fails, Lumen names the affected file and keeps the edit sheet open when it contains your submitted change. Before a normal save overwrites a names file, Lumen tries to refresh a .bak safety copy alongside it.

Back up or restore the whole names database

Open Settings → Advanced → Names Backup to export your mappings, ignored names and document/photo naming setup as one file. Import validates the complete file before anything changes and makes verified safety copies of the current names first. Choose Merge to keep existing entries when they conflict, or Replace All. Restore waits until processing and any Try with… re-checks have finished.

13

Understand privacy and permissions

• Local by default.Local extraction, OCR and Local AI analysis remain on your Mac.
• Cloud is optional.Your own API key connects Lumen directly to the selected provider after a per-provider consent prompt.
• What cloud AI receives.A document’s filename and locally extracted text are normally sent, together with up to 300 of your saved name mappings, including documents those people do not appear in. For an accepted PDF larger than about 30 MB, Lumen reads text locally from a temporary copy of up to the first five pages, whichever provider you use. Only when an initial result is weak may Claude or OpenAI receive PDF bytes inline — the original for an ordinary PDF, or that temporary excerpt for an oversized PDF — or a re-encoded copy of an image document, and only where it fits the request limit. Cloud photo descriptions send a re-encoded copy of eligible images plus the capture date where recorded, never the original file.
• Location has separate consent.Resolved photo location sends embedded GPS coordinates to Apple’s geocoding service, not to the developer.
• File access is scoped.Lumen can scan only the files and folders you select or drag in. macOS may ask for folder access again when a rename or revert needs it.
• Recovery stays local.Session snapshots are stored in Lumen’s sandboxed container and may include filenames, paths, proposed names, extracted fields and review state. They contain no API credentials or document content, are not transmitted and are excluded from share-safe log export.
• No Lumen account or tracking.Lumen requires no account and includes no analytics, advertising or tracking. Its separate software-update request is described below.

14

Keep Lumen up to date

Automatic update checks are on by default in Lumen 1.2.1. The control is in Settings → Advanced → Software Updates.

When on, Lumen contacts lumen-ai.eu after launch when a daily check is due. The request identifies Lumen and its version; the server also receives your IP address and the time. No document data or Mac system profile is sent. Available updates download from GitHub Releases. Turn this off to stop automatic checks; you can still use Lumen → Check for Updates… at any time.

15

Keyboard shortcuts

Click a row first so it is highlighted. In Drop Zone, Results, Unprocessed and Batch Rename, highlight several rows with ⌘-click, ⇧-click or ⌘A once the list has focus. A tick has a different purpose in each tab: it marks a file for removal in Drop Zone, approves it in Results, marks the wand/send subset in Unprocessed and includes it in Batch Rename. The blue highlight remains the keyboard and set-action scope.

16

Troubleshooting