Chronicle Help Guide

1. Overview

Chronicle is a visually intelligent document reader that reads and restructures content from scans and digital files into accessible outputs. The interface is designed around a friendly queue-first workflow, document profiles that choose the best reading path automatically, and readable logs.

Chronicle is especially strong on difficult real-world material: degraded scans, long-form books, archival pages, repeated page furniture, mixed-format queues, and documents that need a careful review-and-rerun workflow rather than a one-click pass.

Back to top

2. Privacy and API Keys

Open File > API Keys... (Alt + K) and use the labelled field for each provider.

• Google Gemini: create a key in Google AI Studio. New authorisation keys, usually beginning with AQ., and older AIza keys are supported. Choose the Google Cloud project with your intended API billing or credits. See Google’s API-key guide.
• Anthropic Claude: create an API key in the Claude Console, scoped to the workspace you will use. This lets Chronicle select the workspace using the key alone. Claude chat access is separate from API access.
• OpenAI: use a key from the OpenAI developer platform, including a project key. ChatGPT access is separate from API access.

Google One AI credits are separate from Gemini API billing and do not fund Chronicle’s API requests. Check billing for the project associated with your key in Google AI Studio. See Google’s plan and credit explanation.

Paste only the key, without quotes, spaces within the key or an HTTP header such as Authorization: Bearer. Surrounding whitespace is removed; no fixed prefix or length is required. Leave unused fields blank. All fields may be blank for Private Offline Mode.

Save API Keys stores entries locally and Cancel discards edits. Saving does not contact providers or verify authentication, permissions, model access, quota or billing. Use a short extraction to check access; online extraction can incur provider charges. Existing saved keys only need changing when you replace them. Known Google, OpenAI and Claude key formats are redacted from logs and support bundles; keep keys private.

• Chronicle stores keys locally in your OS app-data profile.
• Keys can be saved to your OS keychain/keyring (Keychain on macOS) when available, and this is the recommended storage mode.
• When keychain/keyring is used, local files keep masked placeholders rather than raw secrets.
• API key vault supports Gemini, Claude, and OpenAI keys.
• The key vault includes a Show API keys checkbox so users can verify typed characters.
• Saving keys shows an in-app confirmation message.

• You only need keys for providers you intend to use.
• If a provider key is missing, Chronicle's automatic engine selection avoids using that provider.
• If you force a model whose provider key is missing or invalid, extraction will fail with an authentication error.
• Google Gemini API keys from Google AI Studio can work on Google's free tier, subject to current model availability, region support, quotas, and rate limits.
• Important practical warning: free Gemini keys may be enough to test Chronicle, but they can still fail on difficult PDFs, long batches, magazines, newspapers, or repeated reruns with quota or rate-limit errors.
• Even with valid keys, live providers can occasionally return temporary high-demand or unavailable responses during busy periods. A later rerun may succeed without any Chronicle code change.
• Anthropic Claude API access is separate from the consumer Claude.ai chat plans. A free Claude account does not include API access, and Claude chat plans still require separate Claude Console/API billing setup.
• Provider retention/training behavior depends on your provider account tier and settings.
• Chronicle stores keys locally, but extraction content is sent to the selected provider for processing.

Back to top

Private Offline Mode

Private Offline Mode lets Chronicle attempt extraction on the local computer without uploading the document to an online provider. It is intended for sensitive documents, internet outages, and emergency scans where a possible accessible result is better than no result.

Private Offline Mode uses your own local Ollama installation. Install and open Ollama, then download the model with ollama pull qwen2.5vl:7b. Chronicle can also ask the Ollama command-line tool to download the model when it is available. Packaged app users do not need Python. Internet is needed for initial setup and model download.

Best offline candidates

• Clean modern typed PDFs.
• Bank statements, transaction summaries, invoices, receipts, tax records, and account notices.
• Typed medical forms and claim forms.
• Typed legal forms, contracts, notices, regulations, and compliance documents.
• Government forms with clear labels and checkboxes.
• Simple manuals, operation guides, letters, memos, and short reports.

Use offline with care

• Moderately complex tables.
• Forms with many repeated labels, boxes, or checkbox states.
• Dense legal pages where numbering and clause structure must be checked.
• Simple academic articles and manuals with light diagrams.

Verify numbers, names, dates, totals, checkbox states, and table relationships before relying on offline output.

Avoid offline when possible

• Degraded handwriting, cursive diaries, faded scans, skewed pages, or torn pages.
• Historical newspapers, magazines, comics, manga, and graphic novels.
• Long books where paragraph continuity across many pages matters.
• Equation-heavy papers, complex charts, maps, technical diagrams, and detailed visual descriptions.
• Public accessibility remediation where final legal or WCAG sign-off is required.

Advantages and limitations

• Advantages: documents stay local, no internet is required, provider quotas do not block emergency work, and Chronicle still applies semantic accessibility cleanup.
• Limitations: offline accuracy is not equal to the strongest online Gemini path on hard documents, local RAM/disk/CPU resources are used, and human review remains required.

What to expect

Tests with a small sample of documents found offline mode most useful for clear typed pages. Handwriting and damaged pages were less reliable. Always compare important results with the original.

Use qwen2.5vl:7b for this release. Its download is about 6 GB. It provided the best balance of speed and useful results among the models tested with Chronicle.

See docs/user/PRIVATE_OFFLINE_MODE.md for the full offline guide.

Back to top

3. Quick Start

1. Open File > API Keys... and save at least one provider key.
2. Choose an output format and a document profile.
3. Add files with Add Files..., or bring in a folder or scanned pages from the File menu if needed.
4. Pick a Document Preset for the kind of document you are reading.
5. Press Start Reading to run now, or Schedule Reading... to run later.

Back to top

4. Interface Walkthrough

Queue and toolbar commands

• Add Files...: opens a multi-select file picker for supported formats.
• Add Folder...: scans a chosen folder and adds supported files; can work flat or recursively depending on the folder-scanning picker.
• Find Connected Devices...: checks for connected input devices and presents a summary list.
• Scan via NAPS2...: opens page-acquisition settings, starts a scan import run, and auto-imports the resulting files into the queue.
• Remove Selected: removes only the selected queue rows.
• Task Actions...: opens the same task-action menu available from the queue context menu.
• Select All / Deselect All: changes queue selection without changing queue contents.
• Clear List: removes the entire queue.

Run-time reading settings on the main window

• Document Preset chooses the reading behavior for the document type, and Chronicle automatically routes to the appropriate engine for that preset.
• Tabular Data & Spreadsheets preset: best for CSV, XLS, and XLSX material where Chronicle should generate one accessible HTML table with row and column headers, a short spoken summary, and clearer total rows.
• Output Format for Next Run: output type for upcoming queued work.
• Translation: disable translation, keep original with bracketed translation, or translate only.
• Punctuation: preserve archival punctuation or modernize legacy punctuation. If modernization or abbreviation expansion is enabled, reading may take a bit longer because Chronicle has to correct punctuation, suppress false punctuation from broken layouts, and expand abbreviations.
• Units/Currency: keep original units only or add bracketed modern equivalents.
• Abbreviations: keep abbreviations as printed or expand them in brackets.
• Image Descriptions: enable or disable generated image descriptions.
• Original Page Numbers: suppress standalone folios or preserve them as explicit original-page references in the output.
• Seamless Merge: save each queued source separately or merge them into one continuous output.
• PDF Display: standard PDF or large-print PDF.
• PDF Pages: optional page scope for PDF jobs. Use values like 1,3,5-7 to limit reading to specific pages. Leave it blank to read the whole PDF.
• Folder Scanning: current folder only or include subfolders recursively.
• Save Output To: same folder as source or a custom output folder.
• Custom Folder: target folder used when custom destination mode is enabled.
• Document Preset: preset tuned to the document class.
• Preserve source folder structure: mirrors source subfolders into the output folder when scanning directories into a custom destination.
• Delete originals after successful reading: permanently deletes each source file only after a successful output write and after confirmation at run start.
• Apply Current Settings To Selected: this action now sits below the safety checkboxes and copies the current output format, document profile, and run-time reading settings to the selected rows. If nothing is selected, Chronicle applies the settings to all queued or paused rows.

Progress and status displays

• Scheduled Extraction Status: shows whether a future run is scheduled.
• Task Progress Gauge: visual progress bar based on terminal queue states.
• Task Progress Summary: accessible text summary of queued, processing, paused, done, review, stopped, and error states.
• Processing Log: engine-focused log window intended for readable screen-reader review.
• Save Log...: exports the current processing log to a text file.
• Status bar: brief status updates such as model guidance, queue progress, schedule changes, and reading start notices.

Back to top

5. Automatic Reading Engine and Best Use

Back to top

6. Document Presets

Presets align reading rules with document class and automatically choose the most suitable engine behind the scenes. When Engine Override stays on Automatic, Chronicle can start easier PDFs on the faster Gemini path and keep Gemini 3.1 Pro Preview in reserve for hard pages or hard whole-document cases. Manual engine overrides belong in Preferences and advanced settings. Gemini 2.5 Flash and Gemini 2.5 Pro remain available there for compatibility. Handwriting and comic profiles use Gemini 3.8 Flash automatically; military records use Gemini 3.1 Pro Preview. Gemini 3.1 Pro Preview availability can change; provider charges and processing time can differ from the older models.

The broadest presets are now designed so that ordinary PDFs, damaged Word exports, messy HTML, and public-sector reports still come back as something cleaner and more accessible, not just as a literal copy of the source defects.

Back to top

7. Preferences (All Pickers)

Chronicle uses picker-style controls for multi-choice settings so screen readers announce options consistently.

Reading fidelity: Chronicle is configured for zero guessing and no broad spelling correction. A narrow readability exception allows intelligent column splicing, false-punctuation cleanup, and obvious print-artifact repair when the intended reading is clearly recoverable and factual meaning is preserved. If Legacy Punctuation Mode is enabled, only punctuation/spacing can be normalized beyond those layout repairs. Reading may also take a bit longer when punctuation modernization or abbreviation expansion is enabled, because Chronicle has to correct punctuation, suppress false punctuation from broken layouts, and expand abbreviations before finalizing the output. Spacing repair also keeps adjacent words from joining after punctuation cleanup.

Intelligent Column Splicing and Print Artifact Correction

• Chronicle can rejoin words split across line or column breaks when the visible hyphen exists only because of physical layout constraints.
• Chronicle suppresses false punctuation created by column edges, broken type, or visual artifacts so sentences read continuously.
• Chronicle may correct minor optical print defects when the intended word is obvious and the correction improves screen-reader readability without changing factual truth.
• This helps create a more seamless continuous reading experience for screen reader users without sacrificing historical accuracy.

Tabular Data & Spreadsheets

• Chronicle can map CSV and spreadsheet-style material into a single accessible HTML5 table for each logical dataset.
• Column headers are emitted with <th scope="col">, and the primary row key can be emitted with <th scope="row">.
• A short summary paragraph can be placed before the table so screen reader users hear the overall structure before navigating rows and cells.
• Total and summary rows can be marked with the chronicle-total-row class and an ARIA label for clearer subtotal announcements.
• Entirely empty or redundant metadata columns may be omitted to reduce clutter for VoiceOver users.

Malformed source recovery

• Chronicle can rebuild broken but readable HTML, poor Word exports, duplicated OCR overlays, damaged paragraph wrapping, and weak list structure into something more accessible.
• It does this conservatively: the output may become cleaner and easier to navigate, but it should not become less faithful to the visible source.
• True tables are reconstructed only when Chronicle can preserve the real row/column relationships confidently.

• Document Profile
• Engine Override (Automatic, Gemini 3.8 Flash, Gemini 3.1 Pro Preview, Gemini 2.5 Flash, Gemini 2.5 Pro, Claude Sonnet 4.6, GPT-4o, or Private Offline Mode)
• Language Translation
• Translation Target Language
• Legacy Punctuation Mode
• Historical Units/Currency handling (keep, bracketed modern equivalent, or modern-only replacement)
• Abbreviation Handling (keep, bracketed expansion, or expanded-only replacement)
• Image Description Mode
• PDF Display Mode (including large print)
• PDF page scope for targeted testing or partial reruns
• Merge Mode
• Academic Footnote Handling (Academic profile)
• Academic Annotation Handling (Academic profile)
• Source File Deletion
• File Collision Mode

Preference dialog behavior

• Document Profile updates its tooltip dynamically so the dialog explains the selected preset.
• Engine Override lets you keep automatic preset-based routing or force a specific engine from Preferences.
• When Engine Override is left on Automatic, Chronicle follows the preset recommendation, can start supported easy PDFs on the faster Gemini path, and then falls back only to providers with configured API keys instead of trying to use an unavailable provider.
• Automatic routing is designed to keep easy technical/business/government-style PDFs moving faster while preserving the deeper engine for hard pages, hard documents, and specialist profiles that still need the conservative path.
• For PDF-heavy work, Automatic is usually the safest choice unless you have a specific reason to force Claude or GPT.
• If you manually force a model, Chronicle stays on that choice instead of using the fast-first adaptive Gemini path.
• Claude PDF jobs now prefer Anthropic Files API transport when available and fall back to inline PDF mode with a log message if that route is unavailable.
• OpenAI PDF jobs are still more limited in Chronicle's current integration and may fall back to text-layer recovery with an explicit log message.
• Translation Target Language is enabled only when translation mode is active.
• Academic Footnote Handling and Academic Annotation Handling are intended for the Academic preset and are disabled for non-academic presets.
• File Collision Mode controls whether Chronicle skips, overwrites, or auto-numbers when an output filename already exists.
• Source File Deletion only applies after a successful write; Chronicle does not delete the source after a failed or interrupted run.
• Save writes the preference set to Chronicle's local configuration file immediately.
• Cancel closes the dialog without writing changes.

Advanced Preferences

• Custom Prompt Additions (appended to core rule set).
• Custom Command/Rule Strings.
• Enable PDF text-layer omission audit (default on).
• Enable page confidence scoring (default off).
• Enable custom page/slide selection for PDF and PPTX queue rows using the text input field (not a slider). Use a hyphen for ranges (for example 30-45), and use commas only to combine groups (for example 1-5,8,11).

Back to top

8. Output Formats (HTML and Word Included)

Back to top

9. Working with HTML and Word Outputs

HTML output details

• Chronicle writes semantic HTML with language metadata (lang) and direction support (dir).
• Headings and tables are designed for screen-reader structural navigation.
• Use browser shortcuts to jump by headings, regions, and tables.

Word (DOCX) output details

• Chronicle maps heading-like text, lists, and pipe-table structure into Word-friendly structure.
• Major report boundaries can be emitted as internal [[PAGE BREAK]] markers so the DOCX exporter can create cleaner page navigation for title pages, appendices, and section starts.
• During processing, Chronicle may show a hidden recovery file such as .chronicle_progress_My File.docx.txt.tmp. This is intentional: it is a readable in-progress recovery snapshot, not the final Word file.
• Progress wording is now format-aware, so long DOCX and other text-like files report extraction chunks instead of pretending the whole file is one page.
• If you enable Original Page Numbers, Chronicle preserves visible printed page numbers as explicit references instead of suppressing them as page furniture.
• Use Word styles and Navigation Pane for manual cleanup and fast section movement.
• For accessibility review, run Word's built-in accessibility checker before final distribution.

Back to top

10. Queue Rules and Selection Behavior

• Queue status values include Queued, Processing, Done, Error, Skipped, and Missing.
• Start Reading processes all queued rows, not only selected rows.
• PDF Pages applies only to PDF files. Non-PDF formats ignore that field.
• Schedule Reading... also processes all queued rows when the scheduled time is reached.
• Selection is used for row-level actions (remove selected, apply engine to selected).
• Advanced Page Selection applies per row for PDF/PPTX input and uses text syntax: hyphen ranges like 30-45; commas only when combining groups (for example 1-5,8,11); plus quick presets (First 5, Odd, Even, Last 10).
• Quick syntax reference: 30-45 (range), 15 (single page/slide), 1-5,8,11 (multiple groups). Invalid form: 30 to 45.
• If custom page selection is set for an unsupported source type, Chronicle logs the scope as ignored and continues full-file extraction.
• The main Extraction Settings include a Seamless Merge control so you can switch between one-output-per-source and one continuous merged output.
• When Merge Mode is enabled, Chronicle can produce one seamless merged output file.
• If an output filename already exists, File Collision Mode decides the result: Skip leaves the existing file untouched, Overwrite replaces it with the finished run, and Auto-Number keeps the old file and writes the new result with an incremented filename.
• For filename patterns like page 01, page 02, sequence lock is applied in merge mode.
• Synthetic filename headings (for example page 002.JPG) are removed from merged output unless printed in source content.
• DOCX, PDF, EPUB, JSON, and CSV runs can also keep a hidden text recovery file beside the intended result in the destination folder while Chronicle is still assembling the final output.
• Progress counters are format-specific: PDF files report pages, slide decks report slides, and other text documents report sections of text.
• Original page-number handling is user-selectable, so you can keep printed folios for source cross-reference or suppress them for smoother continuous reading.

Queue status values

• Queued: waiting to run.
• Processing: currently being processed.
• Paused: paused by the user or loaded in a paused state.
• Done: completed successfully.
• Done (Review): completed but flagged for manual review.
• Error: processing failed.
• Skipped: skipped due to output collision rules or other skip logic.
• Missing: source file is no longer available.
• Unsupported: source file type is not supported.
• Stopped: stopped by the user.

Selection, keyboard, and context-menu behavior

• The queue supports extended selection for row-level actions.
• Double-clicking a queue row opens the containing folder for that item.
• Task Actions... and the queue context menu provide Stop Task, Pause Task, Resume Task, Delete Task, and Open Containing Folder.
• Space toggles the current queue-row selection.
• Delete removes the selected queue rows when Chronicle is not actively running.
• Shift+F10 or the menu/context key opens the queue context menu.
• Escape clears queue selection.
• Ctrl/Cmd+A selects all queued rows.

Session recovery and close-safety behavior

• At startup, Chronicle can show Recover Previous Session when it finds unfinished work.
• Resume Previous Task reloads the saved queue and starts processing again.
• Load but Pause restores the queue without starting extraction.
• Start Fresh deletes the saved active session and clears the queue.
• If you try to close Chronicle while work is active, the close-safety dialog offers Keep Working, Pause and Stay Open, or Save and Exit.

Back to top

11. Accessibility and Screen Reader Notes

• Multi-choice controls use native picker widgets.
• Pickers include explanatory tooltips and accessible names.
• Queue uses explicit row/state presentation and is intended to be workable with NVDA, JAWS, and VoiceOver.
• The processing log is engine-focused for lower-noise assistive reading.
• Use Save Processing Log to export diagnostics; default directory follows scan context when possible.
• Document profiles provide contextual hints so users can decide without opening external docs, while the reading engine is chosen automatically in the background.
• Windows validation should explicitly test menu shortcuts, queue traversal, Preferences, API Keys, connected-device lookup, NAPS2 import flow, and saved-log export with NVDA and JAWS.

Back to top

12. Troubleshooting and Diagnostics

Welcome and first-run behavior

• If no provider keys are stored yet, Chronicle may show a welcome dialog offering Open API Key Vault or Later.
• If you choose Later, you can still open the vault afterward from File > API Keys....

Device import details

• Scan via NAPS2 opens a page-import dialog with input device, scan preset, DPI, and output folder controls.
• Scan presets include Text (300 DPI), Archival (600 DPI), Draft (200 DPI), and Custom.
• Chronicle validates DPI values and output-folder creation before starting the scan import.
• Imported pages are added to the queue for review first; Chronicle does not auto-start reading from the scan dialog in the current workflow.

Scheduling details

• The schedule dialog uses local date, local time, and the local timezone shown in the dialog.
• Clear Schedule removes any pending scheduled run.
• If reading is started manually while a schedule exists, Chronicle clears the schedule and starts immediately.
• Chronicle must remain open for the scheduled run to trigger.

Gemini 403 file permission during gearshift

This was addressed by delaying file cleanup until stream completion. If seen again, verify key scope and network/proxy behavior.

Output path issues

• If custom destination is enabled, make sure the folder exists and is writable.
• If files are skipped, review collision mode.

Help and external links

• If Open User Guide reports a missing file, reinstall or rebuild Chronicle so the bundled help files are present.
• If donation links do not open, check the default browser configuration and any OS prompts for opening external links.

Confidence and quality signals

• When enabled, page confidence logs appear as score out of 10 with a short condition description.
• Image quality notes may flag faded writing, blur, or possible stain/water-damage artifacts.
• Confidence scoring is diagnostic guidance, not a guaranteed correctness metric.

PDF omission audit output

• Text-layer audit can append recovered lines when coverage appears low.
• For severe mismatch, Chronicle may append a full text-layer safety appendix for manual review.

OpenAI PDF fallback message

If Chronicle logs that OpenAI PDF handling is falling back to the PDF text layer, the current OpenAI route in Chronicle could not continue on a direct PDF path for that request. Chronicle will then try to recover text from the PDF text layer instead of silently skipping the file.

Claude PDF transport fallback

If Chronicle logs that Claude Files API is unavailable for a PDF slice, the app will fall back to inline Claude PDF mode for that slice. This usually means the local Anthropic SDK or environment does not expose the newer Files API route yet.

Back to top

13. Build and Frozen App Notes

Help, About, and Support entries

Choose Help > About Chronicle for the Chronicle Website, Email Michael, and GitHub Issues actions. Email Michael opens your email app to chronicle.vir@gmail.com. The website is https://harry6116.github.io/. About also offers optional one-time and monthly GitHub sponsorship; Buy Me a Coffee and PayPal remain in the Support menu.

Support is optional. Give once with GitHub Sponsors for a single payment with no monthly commitment, or choose monthly sponsorship. GitHub sign-in is required.

• Help > Open User Guide opens this documentation in the default browser.
• Help > About Chronicle... shows build and runtime details, plus a GitHub Sponsors button. One-time support is available without a monthly commitment.
• Help > Support Chronicle... opens a donation chooser with GitHub Sponsors: One-time, GitHub Sponsors: Monthly, Buy Me a Coffee, and PayPal.
• On macOS, File > Check Mac Folder Access... prompts for folder-access remediation when permission issues block scanning or folder ingestion.

• macOS build launcher: build.command
• Windows build launcher: build_windows.bat (which calls build_windows.ps1).
• Windows staged bundles must include build_windows.ps1, build_windows.bat, chronicle_app/, assets/, and docs/.
• Build scripts include broad dependency collection to reduce missing-runtime issues on new systems/drives.

• Help > About Chronicle... shows build and runtime details, plus a GitHub Sponsors button.
• Help > Check for Updates checks for a newer download. Release notes use a standard read-only text field: use arrow keys to read, select and copy text, and Tab or Shift+Tab to visit the update actions. Escape closes the notes. Packaged apps can install an available update after confirmation; the queue-close choice is completed before installation starts.
• Remind Me Later closes the update notes and keeps Chronicle running. A quiet reminder appears in the status bar and processing log next time Chronicle starts, until that version is installed. It does not schedule a restart. When ready, return to Check for Updates and choose Install and Restart Now. Go to Release opens the selected release in your browser.
• Help > Support Chronicle... opens the in-app donation chooser with GitHub Sponsors: One-time, GitHub Sponsors: Monthly, Buy Me a Coffee, and PayPal.

Back to top

14. System Requirements

Chronicle can run from source or as a frozen app bundle. Requirements vary by workload size and output mode.

Low-memory systems

• Enable Low-Memory Mode in Preferences for constrained devices.
• Prefer non-merge runs and smaller queue batches.
• For very large PDFs, disable optional diagnostic features if stability is the priority.
• For Private Offline Mode on 8 GB systems, prefer short clean documents, HTML or TXT output, and one job at a time.
• Close other heavy apps before starting offline scans on constrained machines.

Offline processing is kept conservative by default: one parallel offline request at a time and small PDF page batches rather than one huge local model request.

Back to top

15. Keyboard Shortcuts

• F1: Open context-sensitive help for the focused Chronicle control. Tab moves from the help text to Open Full User Guide, then Close. Escape closes help.
• Shift + F1: Check for Chronicle updates.
• Alt + P: Preferences.
• Alt + K: API Keys.
• Alt + S: Find connected devices.
• Alt + N: Scan via NAPS2.
• Alt + L: Save processing log.
• Alt + M (macOS): Check Mac folder access.
• Space: Toggle selection of the current queue row.
• Escape: Deselect all queue rows.
• Shift + F10: Open the queue context menu.
• Delete: Remove selected queue rows.
• Ctrl/Cmd + A: Select all queue rows.

Back to top