Quill: Product Requirements Document

A magical, screen-reader-first writing and document environment, built in wxPython

Status: This document specifies Quill 1.0. The current shipping build is 0.7.0 Beta, which implements the v1.0 checklist (section 21.1–21.16) plus the post-1.0 foundation work in section 21.17 and later. Section 21 is the living implementation map and is kept current as features land. Public name: QUILL for All Owner: Community Access Independence notice: QUILL for All is developed independently of any assistive-technology vendor. Vendor and screen-reader names appear throughout this document for compatibility and certification purposes only; they remain the property of their respective owners. Target platform: Windows 10 and Windows 11 Target screen readers: NVDA (primary), JAWS, Narrator UI framework: wxPython (wxWidgets 3.2 or newer) Language: Python 3.12 or newer

1. Vision

Quill is a focused writing and document-reading workstation for blind and low-vision users. It opens almost anything, turns it into clean, navigable text in a familiar Windows edit field, and gives the writer a quiet, predictable place to think.

1. Open by default. Free, open source, with no proprietary scripting layer required. Works first class with NVDA out of the box, and equally well with JAWS or Narrator.
2. Screen-reader-native. Every surface is a standard Windows control (wx.TextCtrl multiline, wx.ListBox, wx.Dialog) so MSAA, UIA, IAccessible2 and braille routing all just work. No custom drawn controls in the writing path.
3. Magical, not flashy. “Magic” means the right thing happens without ceremony. PDFs become readable. Bookmarks survive edits. Backups are automatic. The command palette knows what you mean. Nothing surprises the screen reader.
4. Local first, cloud optional. Heavy lifting (PDF extraction, OCR, layout repair, spell checking) runs locally when possible. Cloud assistance is opt-in per action, transparent, and never silent.

If a sighted person watched a Quill user work, they would see almost nothing on screen. That is the point.

2. Goals and non-goals

2.1 Goals

• Provide a dependable plain-text writing surface that NVDA, JAWS and Narrator can read without quirks.
• Open a wide range of document formats and present them as editable text in a standard edit field.
• Preserve the original source file. Extracted or rendered text saves through “Save As” so originals are never overwritten.
• Offer practical writer tools: find and replace, bookmarks that survive edits, magical spell check, word count, page navigation, multiple documents, backups, recent files.
• Offer a discoverable command palette modelled on Visual Studio Code so users do not need to memorise every shortcut.
• Let every shortcut be reassigned through a friendly keymap editor.
• Offer optional, transparent AI assistance for awkward PDFs, scanned images and broken layouts.
• Integrate cleanly with Windows: file associations, “Open with”, jump lists, taskbar.
• Be themable for low vision (high contrast, large fonts) without breaking screen-reader behaviour.

2.2 Non-goals

• Not a visual word processor. No bold, italic, fonts, colour styling in the writing surface for v1.
• Not a desktop publishing tool.
• Not a replacement for Microsoft Word or LibreOffice Writer.
• Not a book reader with pagination and reflow. Quill renders documents as editable text.
• Not an AI chat product. AI is used only to repair reading order or extract text.

2.3 Update Strategy and Micro-Updates

Quill uses app_updater (AccessibleApps, MIT license) for cross-platform incremental updates, enabling smaller, faster patches:

• Incremental delivery: Updates are distributed as small ZIP packages containing only changed files, not full reinstalls.
• Automatic bootstrapper: Platform-specific bootstrappers (bootstrap.exe, bootstrap-mac.sh, bootstrap-lin.sh) apply updates atomically after app exit and restart.
• Accessible UX: Update checks and progress are announced through the screen reader with clear prompts for user consent.
• Backwards-compatible install: Full installers (Inno Setup on Windows, .dmg on macOS) remain available for fresh installs or offline scenarios.
• Signed feeds: Update feeds are cryptographically signed (Ed25519 or RSA) to prevent tampering; signatures are verified client-side.

This enables shipping bug fixes and security patches as micro-updates without re-downloading the entire application, while maintaining security and platform best practices.

2.3.1 Remote feature kill switch (signed feature advisories)

QUILL can remotely disable a feature if a serious problem is found after release, without shipping a new build. This is a safety valve, deliberately narrow and fail-safe.

• Transport. Kill switches ride as advisories inside the existing signed update manifest (quill/core/updates.py), so they inherit its protections and add no new network path or consent surface: HTTPS only, a trusted-host allowlist, and a signature the client verifies. The advisories are part of the signed canonical form, so they cannot be added or altered in transit; a feed with no advisories keeps its exact prior signature (backward-compatible).
• Capability (one direction only). An advisory can only make a known feature id (quill/core/feature_command_map.py) unavailable, for a version range (min_version/max_version). It can never enable, execute, or reconfigure anything. The worst a forged advisory could do — if signing were ever broken — is disable a feature, which the user can override locally. This keeps the mechanism from becoming a remote-control attack surface.
• Enforcement (at dispatch, not per handler). Locks are enforced at the command dispatch chokepoint — CommandRegistry.run consults a gate before invoking any handler, so keybindings and the command palette (which both route through it) are blocked uniformly rather than relying on each handler to self-check. Menu items whose feature is locked are disabled on every menu build (so their click and accelerator are inert). A blocked command surfaces a plain-language “turned off by a safety update” notice. _feature_enabled also consults the locks, so any handler self-check stays correct too.
• Dependency cascade. A lock propagates through the feature dependency graph (FeatureDefinition.dependencies): a feature is effectively locked when it, or anything it transitively depends on, is directly locked. Locking a parent (e.g. core.editor) therefore disables everything built on it — mirroring how FeatureManager disables dependents when a feature is turned off — so an advisory never leaves a half-working subtree. The dependency graph is gated as acyclic with all dependencies defined (check_feature_tags).
• Portable builds covered. Portable builds fetch the signed manifest for advisories too (they only skip its installer URL for the update prompt), so a kill switch reaches them and, crucially, can be lifted on them.
• Persistence & fail-safe. The locked set is cached locally (quill/core/safety/feature_lock.py) and honored on the next launch even offline — a kill switch you can only reach while online would be useless during an incident. It clears only when a later verified manifest drops the advisory (or the running build moves past its max_version), which is how a fix lifts the lock.
• Consent & escape hatch. Locks apply when the user’s update check runs (the same consent that governs update checks). QUILL_IGNORE_FEATURE_LOCKS=1 disables all remote locks for that run — for an administrator who must use a disabled feature, or to recover if an advisory is ever wrong.
• Publishing. The owner manages locks with scripts/manage_feature_locks.py — an accessible console (run it with no arguments for a numbered menu, or use --list / --add <id> --reason "…" [--max-version X] / --remove <id> / --publish). Every --lock-feature/--add id is validated against the feature catalog before signing (a typo hard-fails with suggestions, so an incident lock can’t silently no-op). It edits only the feed’s advisories, re-signs with the same QUILL_UPDATE_MANIFEST_KEY used for releases (verifying the result before it writes), and --publish runs git add/commit/push on the feed. Lifting a lock is --remove (or a --max-version below the fixed build). generate_update_feed.py also accepts the same --lock-feature flags when regenerating a full feed.

3. Target users and primary scenarios

3.1 Personas

1. Mira, blind university student. Reads PDF lecture notes daily. Needs them to make sense linearly, with reliable search and bookmarks she can name.
2. Ade, blind technical writer. Writes long Markdown and HTML. Wants to write in a quiet edit field, preview structure in a browser, and export cleanly.
3. Pat, blind admin assistant. Opens invoices and Word documents from email. Wants to copy reference numbers and totals quickly.
4. Sam, low-vision novelist. Uses Narrator with a large font and high contrast. Writes long manuscripts, restores from yesterday’s backup occasionally.
5. Jamie, blind sysadmin. Edits INI, JSON, log and config files. Wants a calm editor that does not fight tooling.

3.2 Primary scenarios

• Open a 30-page PDF invoice, find the payment reference, copy it.
• Start a blank document, write a 2000-word article in Markdown, preview it in the browser, export to Word.
• Open a DOCX from a colleague, read it, save the extracted text as a .txt for archival without touching the original.
• Open a scanned receipt, ask Quill to OCR it through a cloud service, get a plain text rendering.
• Restore the version of chapter-7.md from two saves ago.
• Reassign Ctrl+G from Go To Line to Go To Bookmark because the user prefers a different convention.

4. Product principles

1. The edit field is sacred. The writing surface is a standard multi-line wx.TextCtrl. Nothing exotic. Screen readers see plain text. Always.
2. Predictable keyboard. Shortcuts match Windows conventions where they exist. New shortcuts are documented, discoverable, and reassignable.
3. Speak the result, not the process. After every meaningful action, Quill announces a short, useful result through the screen reader.
4. Originals are read-only by default. Anything rendered or extracted saves through Save As. Plain-text formats save in place.
5. No silent network calls. Any cloud assistance asks first, shows progress, and reports the outcome.
6. Quiet by default. No surprise toasts. No animated UI. No tabs that announce themselves on every switch. Cues that merely duplicate what the screen reader already says ship off: e.g. announce_dialog_transitions (the spoken “Entered/Exited name dialog”) defaults to off, since every supported reader already announces a dialog and reads its title on focus. The lever stays in Preferences > Accessibility for anyone who wants the extra cue. Settings reach existing users on upgrade because the on-disk store is a delta from code defaults (see settings_migration), so a changed default flows to everyone who never deliberately overrode it.
7. Recoverable. Backups happen on save. Crash recovery on launch. Nothing the user wrote should ever be lost.
8. Discoverable. A searchable command palette lists every action with its current binding.

5. Functional requirements

5.1 Application shell

• Single window per running instance, with multiple documents inside.
• Three primary regions, always present: menu bar (5.1a), central editor, status bar (5.1b).
• Window title shows document-name [modified] – Quill. The word “modified” appears only when the document has unsaved changes.
• Tray icon optional, off by default.
• No splash screen.
• Single-instance mode is on by default. A second launch with a path opens that path in the existing window and brings it to the foreground. A setting allows multi-instance for advanced users.
• F6 region cycling moves keyboard focus through the three regions in order (editor → menu bar → status bar → editor). Shift+F6 cycles in reverse. The region name is announced on entry (“Status bar”). If the Outline Navigator (5.16) is pinned, it joins the cycle between editor and menu bar.
• All regions are stock wx controls (wx.MenuBar, wx.TextCtrl, wx.StatusBar with a custom layout) so MSAA/UIA expose them correctly without scripts.

5.1a The magical menu bar

The menu bar is standards-based, predictable, and exhaustive. Every menu item is also a command in the palette, every item shows its current keybinding to the right of its label, and the displayed binding updates live when the user rebinds it. No menu item is hidden; disabled items remain visible with a short tooltip explaining why they are disabled in the current context.

Menu structure:

• File: New/Open/New from Clipboard/Open Recent/Open from URL, Open from Remote / Save to Remote / Save Copy to Remote / Manage Remote Sites (FTP, SFTP, HTTPS, WebDAV, S3 — verified TLS, host-allow-listed, explicit consent, screen-reader announcements), Snapshots (save/open workspace snapshot), Notebook submenu (New Notebook / New from Folder / Open Notebook / Save Snapshot / Manage Snapshots — multi-document workspace with entries panel, daily goal, and named snapshots), Save/Save As/Save All/Save as plain text, Reload/Restore backup, print flows, Run current file / Open target at cursor / Rename / Delete current file, close/exit.
• Edit: Undo/redo, clipboard (including Paste HTML as Markdown), Find/Replace plus Find Next/Previous/All Matches, selection helpers, delete-to-line/document and delete-paragraph, link insertion/follow, and Recent Marks (Ring) with plain-language labels.
• View: shell behavior, theme and visual controls (preference toggles such as persistent undo, spell-check-as-you-type, word prediction, dark mode, tray mode, title-path and dirty-title style now live in Settings).
• Insert: table/list/code/footnote/tag insertion helpers plus special character, date and time, calculated date, and file content.
• Format: case/comment/indent controls, rich text and heading controls, a single Transform Lines submenu (number/hard-wrap lines plus sort/reverse/dedup/whitespace/indentation conversions), and a Sort & Filter group with three structured-list sorts — Sort Lines Numerically, Sort Lines by Length, and Sort Lines by Date (date-aware: recognizes ISO, slash/dot, and month-name styles and infers d/m/y vs m/d/y from the user’s region; undated lines sink to the bottom).
• Navigate: line/page/bookmark movement, heading/block/structure movement, outline, bracket match, region movement, go to percent / first / last non-blank, and Go to Entry / Heading / Bookmark / Sticky Note in Notebook (cross-entry navigation when a Notebook is open).
• Search: in-files Find and Replace-across-files, plus regex count/extract matches and block set-operations (line filtering by block membership).
• Tools: regrouped into discoverable submenus (≤ 2 levels deep):
  • Sticky Notes
  • Writing and Language
  • Read Aloud
  • Integrations
  • Document Intake
  • AI Assistant (demoted from top level; promotable back via Customize Menus)
  • Authoring and Automation
  • Macros
  • Compare Documents
  • Accessibility (includes cursor address / document status / selection-length status queries)
  • Support
  • Customize
  • Power Tools (editor-behavior power toggles grouped together where no other menu is a natural home)
  • Quillins (includes Text Tools for line transforms/regex and Insert Tools for date/time placeholders)
• Window: document/tab management actions.
• Help: contextual help, onboarding docs, feature profile support, updates, and About.

All menu strings are translatable. Every menu item has a unique mnemonic. The menu bar may be hidden via View; when hidden, pressing Alt reveals it temporarily and Esc dismisses it again, matching Windows convention.

5.1b The magical status bar

The status bar is not a passive label strip. It is a fully keyboard-navigable row of items that any user can reach with F6 and arrow through with Left and Right. Each item is a small interactive cell, and Enter on a cell either toggles a state, opens a chooser, or runs a related command. This is modelled on Visual Studio Code’s status bar, adapted for screen-reader-first interaction.

Design rules:

• Container: a custom layout inside wx.StatusBar composed of small wx.Window-derived focusable buttons (wx.lib.agw.AquaButton style is rejected; we use plain wx.Button with flat styling). Each cell exposes itself as an MSAA button with name, role, value, and description so NVDA, JAWS, and Narrator read it as a real interactive control.
• Reachable: F6 from the editor moves focus into the status bar at the cell the user last interacted with (or the leftmost cell on first entry). Left/Right arrow moves between cells with wrap-around. Home/End jump to first/last. Esc returns focus to the editor. Tab and Shift+Tab also move between cells inside the status bar.
• Announced: when focus enters the status bar, the region name and the focused cell are announced (“Status bar, Line 12, Column 7, button”). Cells announce their value when arrowed to.
• Activated: Enter or Space triggers the cell’s primary action. Shift+F10 or the Application key opens a context menu of related actions for that cell. Right-clicking is equivalent.
• Live updates: cell values update without stealing focus. Updates marshal via wx.CallAfter and use a debounced single accessibility event per cell per 200 ms to avoid speech spam.
• Hideable per cell: a context menu item “Hide this item” tucks any cell behind an overflow group. Overflow is reached at the right end (“More items, button”); Enter opens a small list of hidden cells, any of which can be restored.
• Plugin-extensible (v1.1): plugins may register status-bar cells with the same MSAA contract.

Cells shipped in v1.0, in left-to-right order:

Default visibility: Document name, Modified state, Line/Column, Word count, Encoding, Line endings, Spell check, Background tasks, Notifications. Other cells are present but tucked into overflow until first relevant use; they auto-surface when their context becomes relevant (for example Page appears as soon as a paged document is opened; Search term appears the moment a search term is set).

When title mode is configured to show the full file path, Quill suppresses a duplicate file-path status item to avoid repeated location noise.

5.1c Trust and verification

Quill explains what it did, how confident it is, and how to recover if extraction looked wrong.

• Document Intake Report: every non-plain-text open announces a short, screen-reader-friendly summary and exposes a full report with format, engine, page/sheet/slide counts, OCR use, AI use, confidence, detected structures, and sidecar path.
• Copy With Source: selected text can be copied with source location appended (file, page/line/column, engine, confidence) and the source map stays available for future citations.
• Extraction quality review: PDF-derived documents expose page-by-page confidence warnings and allow retry/review flows.
• Cleanup recipes: deterministic review-and-apply transforms for OCR/PDF cleanup (dehyphenate, remove headers/footers, normalize ligatures, line reflow).
• Report Bad Extraction: creates a support package with version, metadata, and no document content unless the user explicitly opts in.
• What Can I Do Here?: context-sensitive help for the current surface, available from the Help menu and command palette.
• Safe mode: a startup-safe mode disables plugins, experimental features, AI integrations, startup restore, background indexing, file watchers, custom themes, custom snippets, and network services for troubleshooting.
• Portable mode clarity: portable builds can store settings locally next to Quill.exe or in AppData, with a first-run choice and an independence command.
• Golden document corpus: release testing includes a canonical corpus of PDFs, DOCX, XLSX, PPTX, EPUB, Markdown, HTML, and OCR samples with expected extraction and announcement snapshots.

5.1c-ES The error-specificity programme (phase 1 shipped 1.0.0)

A sighted user opens the failing file or dialog and sees the problem; a blind user cannot, so every user-visible error must carry the whole diagnosis and the next step. The programme rule: a new user-visible error names the specific condition (“The [APIKey] section is missing”, not “could not read the file”) and, where a next action exists, says it. Three mechanisms shipped in phase 1:

• What-to-do sentences on coded errors. core/error_codes.py gains a USER_HINTS catalogue (code -> next-step sentence: the menu path, the setting, the command), CodedError.user_message() (diagnosis + hint), and user_facing_message(exc) for any exception (never returns an empty string — a blank error is indistinguishable from a crash by ear). First adopters: the Document Q&A dialog and Ask Quill route their worker exceptions through it. The catalogue covers the highest-traffic families first (AI chat/Q&A/TTS/transcription, Pandoc and OCR unavailable, remote transports, SSH, component downloads, speech providers, Quillins, document conversion); every new user-visible error should either add its code to the catalogue or set user_hint on the class.
• “Say why it is unavailable.” The command registry gains a side-effect-free availability probe (set_availability_probe/unavailable_reason) — the spoken counterpart of the run gate. The palette displays and speaks the reason on the row and on a refused run (“Sync Notes (unavailable: Turned off by a safety update: …)”), instead of a bare “(unavailable)”. MainFrame’s probe reads the same remote-lock state as the dispatch gate.
• “Never silently deliver less than was asked.” Assistant.answer/answer_stream/write_for_document record last_context_note — a user-facing sentence stating the working size whenever a request was trimmed to fit the model (“The answer used the first 6,000 of the document’s 40,000 characters.”) — and Ask Quill announces it after the response. QAAnswer carries used_chars/total_chars so Document Q&A states the working size, and that dialog now speaks its status changes (answer received, truncation, errors) rather than only painting a label.

5.1c-SR Screen-reader death watchdog (shipped 1.0.0)

Detection was a one-shot startup probe; a reader dying mid-session was invisible to QUILL. core/sr_watchdog.py is a wx-free two-strikes state machine (30 s cadence, MISSES_BEFORE_DEATH = 2 so a routine JAWS/NVDA restart never fires it; arms only after a reader has been seen, so self-voice/sighted sessions never trigger; probe errors count as misses but never raise). ui/main_frame_sr_watchdog.py applies the collapse rule — flush first, then act: on confirmed death every open tab is snapshotted through the existing autosave machinery (active editor synced first; one failing tab never stops the rest), then the event is announced through the engine’s fallback chain and recorded in Notifications with severity warning. Recovery is announced too. The watchdog never closes QUILL. Generalised rule, recorded as product law: any code path that closes or degrades the app without the user asking persists work first.

5.1c-HD Hardening conventions (shipped 1.0.0)

Four shared foundations from the hardening pass, each wx-free, strict-typed, and unit-tested; new code should reach for these instead of hand-rolling:

• core/generation.py GenerationCounter — the named generation-token idiom for deferred announcements and background work (advance on schedule, is_current on completion). Browse-mode’s prewarm is the first adopter; the remaining ~9 hand-rolled counters should migrate as they are touched.
• core/swr.py — stale-while-revalidate: structural_signature (tuple compare, key-selectable identity fields) + decide_refresh, whose decision is constitutionally silent and selection-preserving (a background refresh never announces and never moves the user’s position). Slow-enumerated lists (recent files, Quillins, stations, episodes, voice catalogues) adopt this as they are touched.
• core/path_input.py clean_typed_path — every path field accepts Explorer “Copy as path” quotes, smart quotes, NBSPs, file:// URLs, environment variables, and ~. First adopter: the Simple File Open path field.
• core/type_ahead.py — the type-ahead buffer for custom list surfaces with the field-proven timings: 800 ms open suppression, 1.2 s buffer timeout, last-character retry on a failed multi-character buffer, wrap-from-selection matching, and an explicit failure result the caller must speak (“No match for X”).
• Destructive-default gate (GATE extension): tools/dialog_button_contract.py now also fails the build for any Yes/No confirmation whose text reads as destructive (delete/remove/discard/overwrite/reset/…) without wx.NO_DEFAULT; 27 pre-existing sites across QUILL and the companion apps were fixed in the same pass. Dynamic message text is invisible to the AST audit, so the review rule stands: a destructive confirmation defaults to No.

5.1c-AU Audio identity (shipped 1.0.0)

The competitive assessment’s audio lesson, adopted whole (item 8): sounds get an identity, not just a presence, and everything rides the existing QSP pack system so packs stay swappable. Forty-eight new events, all synthesized in scripts/gen_ink_sounds.py (deterministic, regenerable) and mapped in the bundled Ink pack:

• Per-slot earcons. copy_slot_1..12 and bookmark_slot_0..9 map slot number to a degree of a C-major pentatonic; copy-tray slots are marimba-voiced taps (noise attack + sine-with-octave body), bookmarks are triangle chirps gliding up into the slot note, so family reads from timbre and identity from pitch. Fired on copy-to-slot, paste-from-slot, first-empty copy, quick-bookmark set and jump.
• Progress ladder. progress_5..progress_100 (5-percent steps; pitch climbs one octave 320->640 Hz; 25/50/75 add a perfect fifth; 100 resolves with a second note) plus progress_tick for indeterminate. core/sound_events.py progress_sound_event(percent) maps a percent to its step id; the sound fires from AIProgressDialog.set_progress only when the step changes, so every consumer of the shared progress dialog gained audio progress at once, and it never interrupts speech (the spoken 25/50/75 milestones remain).
• Selection and boundaries. selection_started/selection_completed are exact time-mirrors (a rising fourth and its reverse) on the F8 anchor commands; document_top (1318 Hz ceiling tick) and document_bottom (165 Hz floor thud) fire on the token-navigation boundaries.
• Soundcard keep-alive. keepalive (two seconds of true silence) played every 20 s by an opt-in loop in the sound manager (sound_keepalive_enabled, default off, searchable spec) so USB/Bluetooth devices never power down and clip the first earcon after a pause. The loop thread exists only while enabled and stops on shutdown.
• All 48 events are disableable per-event in Sound Events (labels auto-generated per family) and overridable by any QSP pack; scripts/audition_ink_sounds.py plays the set family by family for review.

5.1c-FA Field-by-field AI apply (shipped 1.0.0)

The field counterpart of the word-level change review, taken from the competitive assessment’s strongest generic pattern (finding 5e.38): structured LLM output is applied to user data one reviewable item at a time, never as a bulk overwrite. core/ai/field_apply.py holds the wx-free model — FieldSuggestion, ApplySession (pending/accepted/skipped, accepted_values(), wrap-around next_pending), and guess_target_field (normalized exact > prefix > substring scoring; a guess only preselects, the reviewer confirms). ui/field_apply_dialog.py presents each suggestion with the field, its current value, and the proposal (Accept / Accept and Next / Skip / Copy Value / Apply Accepted), warns with a No-defaulted confirmation before replacing a non-empty field, and never writes — the caller applies accepted() as one undo step. First consumer: Suggest Document Metadata (ai.suggest_metadata, palette command) — core/ai/metadata_suggest.py asks the configured provider for title/summary/tags/category with defensive JSON parsing (fence stripping, outermost-brace fallback, its own QUILL-AI-METADATA-FAILED coded error), and the mixin applies accepted fields into the document’s front matter via the story front-matter codec, preserving list shape for tags and refusing to apply over a document that changed mid-request.

5.1c-ES2 Error specificity, phase 2 (shipped 1.0.0)

Phase 1’s mechanisms spread to the remaining high-traffic surfaces: all 29 user-visible error sites in the speech/component download flows, the three Quillin failure surfaces, and the remote-transport (SSH/FTP/S3/WebDAV) open/save errors now route through user_facing_message; the USER_HINTS catalogue grew eight entries (Whisper download 404/network/checksum, speech engine and ffmpeg installs, microphone capture, unsupported save format, AI metadata); a menu item disabled by a remote safety lock now carries the reason in its help string (the spoken counterpart of the palette’s reason suffix); and the review rule is codified in CONTRIBUTING.md. AI engine honesty joined the programme: make_default_backend records last_backend_note whenever resolution falls back past a provider the user explicitly configured, Ask Quill announces it at open, and the connectivity-fallback hint now computes real availability on both sides (a stored cloud key counts as cloud-available), so a failed on-device model offers the configured cloud provider — always as an offer, never a switch, with the privacy consequence stated.

5.1c-WR Word-level AI change review (AI-7, upgraded 1.0.0)

Every AI edit that touches the document routes through the accessible “Review AI Changes” dialog (core/ai/diff_review.py + DiffReviewDialog): an ordered checklist of hunks the user can accept or reject independently, applied as one text replacement (one undo step). Shipped 1.0.0, the model gained a second-stage word diff with sentence context, because line hunks are too coarse for prose — when the AI changes one word in a 90-character line, a line diff makes the user hear the whole line twice and spot the difference by ear.

• Each “changed” hunk carries word_changes: tokens are words (internal apostrophes kept), whitespace runs, and punctuation runs (SequenceMatcher(autojunk=False) — autojunk silently degrades prose diffs); adjacent edits separated only by whitespace merge into one phrase (“quick brown” -> “rapid red” is one change, not two).
• Every word change carries the enclosing sentence from both sides (terminator-bounded, line-break-bounded, whitespace-collapsed) — “changed ‘quick’ to ‘rapid’” is meaningless alone; with the sentence it is reviewable by ear.
• The hunk list row speaks the word-level summary (‘Changed “quick” to “rapid” at line 3.’; ‘Changed 2 phrases at line 7.’), and the detail pane leads with each change’s verb phrase plus Sentence before / Sentence after, followed by the full removed/added lines, which stay reviewable exactly as before.
• Degradation is deliberate: a hunk falls back to plain line presentation when it has more than 8 word edits or any single “phrase” exceeds 100 characters (a rewrite spoken as forty word pairs is worse than hearing the lines whole), and spacing-only edits are never spoken as word changes.
• Pure model change: DiffReviewDialog, the agent editor host, and the tool gateway all read describe()/detail_lines(), so every consumer upgraded with no UI changes.

5.1f Profile safety and recovery

Feature profiles must be safe, explainable, reversible, and recoverable.

• Why don’t I see this? explains why a named feature is hidden, quiet, unavailable, or gated by the current profile.
• Profile switch preview shows visible, quiet, and off features before applying a profile change.
• Undo last profile change is available from Notifications after a profile switch.
• Emergency reset to Essential is available from launch and from the recovery flow.
• Profile health check validates feature IDs, dependencies, visibility paths, and profile JSON integrity.
• Feature-coverage gate fails CI when commands, menus, cells, pages, or help topics lack a valid feature ID.
• Profile-aware keyboard reference can filter to current profile, quiet features, off features, or diff views.
• Shortcut wiring is consistent across the product. Commands exposed in menus, the command palette, and the keymap editor must all resolve to the same accelerator path, including proofread, translate, compare-navigation, and dark-mode commands.
• Profile-aware welcome guide adapts onboarding to the active profile.
• Privacy and network labels declare local-only, external-helper, metadata-only, and network-sending features.
• Feature maturity labels distinguish core, stable, advanced, helper-required, and unavailable features.
• Profile import safety schema-validates profiles and prevents silent enablement of recovery-sensitive features.
• Show what changed produces a plain-text summary after profile switches.

5.1g Feature registry and user profiles

Quill’s feature-profile system is a first-class product surface, not a cosmetic preference layer.

• Feature Registry: a central registry assigns every feature an id, category, description, default state, dependencies, conflicts, privacy impact, network impact, accessibility notes, and profile tags.
• Profile layering: user overrides sit above custom profiles, shipped profiles, default registry state, and locked safety rules.
• Shipped profiles: Essential, Casual Writer, Author or Student, Reader and Student, Office and Admin, Accessibility Professional, Developer and Power Text, Low Vision, Braille and Screen Reader Power User, Full Quill, and Custom.
• Settings UI: Profiles and Features page with search, feature table, explain/related commands, compare profiles, and profile management actions.
• Custom profile creation: users can create named custom profiles, select a parent shipped profile, and optionally inherit that parent’s feature baseline.
• Bare-bones start: custom profile creation also supports an explicit non-inherited baseline (locked core safety features only), with a warning before commit.
• Quick profile picker: Alt+Shift+P opens fast switching for built-in and custom profiles.
• Onboarding: first run asks how Quill should start and chooses a profile.
• Command/menu/status/help integration: feature IDs govern command palette, menus, status-bar cells, settings rows, help topics, and format handlers.
• Dependency enforcement: enabling a feature can enable required dependencies; disabling a feature warns about affected features.
• Storage: feature flags and profiles are stored locally as JSON and can be imported/exported safely.
• Safety rules: locked-on features cannot be disabled by shipped profiles, custom profiles, imported profiles, plugins, or user overrides.
• Feature metadata: each feature declares risk, maturity, privacy, and network labels for use in settings and help.

5.1d Power search, regex, and special characters

Search and Unicode cleanup are first-class accessibility features, not power-user extras.

• Search modes: Find, Find All, Replace, Replace All, Find in Selection, and saved search recipes support plain text, whole word, regular expression, and wildcard modes.
• Regex helper (2.0 as of 1.0.0, #1328 P1): a category tree of 100+ recipes across 14 categories (cleanup, words, lines, numbers, dates, contact/web, Markdown, HTML, punctuation, writing checks, OCR cleanup, code identifiers, capture-and-replace with ready templates), a deterministic plain-language explain engine that narrates any pattern step by step and diagnoses broken patterns at the exact character position, sentence-style match previews with replace previews, and Use in Find All Matches (seeds the search flow with regex mode on — no clipboard hop). Architecture: wx-free strict-typed quill/core/regex_helper/ (catalog.py data + schema tests that compile and match-verify every recipe, explain.py, runner.py with bounded execution and zero-width-safety), dialog in quill/ui/regex_helper_dialog.py (the former inline main_frame implementation was removed, −162 lines).
• QUILL Find dialog (unified search F1, #1327, opt-in): behind settings.find_use_quill_dialog (default off until the JAWS/NVDA validation pass), Ctrl+F/Ctrl+H open quill/ui/find_dialog.py::QuillFindDialog instead of the native wx.FindReplaceDialog. Document scope; Normal + Extended modes (escape translator \n \t \xNN \uNNNN \N{NAME} plus a 40-entry named special-character picker); debounced spoken incremental count; peek navigation (Ctrl+Up/Down walk matches while focus stays in the query field); spoken sentence context for every match; wrap announced; labeled Direction RadioBox (the group-name-announcement report that opened #1327); Count button; range-based replacements that preserve editor undo; Ctrl+F refocuses / Ctrl+H switches action in place / Ctrl+L returns to the query field. Match logic is wx-free quill/core/find_model.py (strict-typed, 52 tests); the dialog talks to its host only through the FindHost callback bundle, so every behavior is unit-tested with a stub host plus real-widget tests. Later phases (results list, files/Vault scopes, history, Extract, the Settings > Search page) are specified in #1327.
• Plain-English errors: regex errors are reported in single-sentence form with character positions and no traceback.
• Match review: users can review captured groups for a match, including named groups.
• Replace preview: Replace All shows a preview before applying, with undo as one step.
• Saved searches: common search/replace recipes can be stored with mode, scope, and description.
• Special characters: the Find dialog can insert special search tokens for tabs, line endings, non-breaking spaces, zero-width characters, smart quotes, ellipses, bullets, and Unicode character classes.
• Character Inspector: reports the character under the cursor by name, code point, category, and common encodings.
• Invisible character view: users can switch to an inspection view that describes invisible characters textually.
• Unicode cleanup: normalization and cleanup commands remove or rewrite common noisy characters with a preview first.

Menu and window stability requirement:

• Menu mutation guard: while native menus are open, Quill defers menu label/check/enable mutations and applies them on menu close. This avoids crash-prone churn during rapid keyboard menu navigation.

5.1e Feature flags and profiles

Quill should stay calm by default and unlock power features intentionally.

• Feature states: on, quiet, off, locked on, locked off.
• Core stays locked on: editor, open/save, backups, crash recovery, help, accessibility announcements, settings.
• Advanced features can be quiet/off: regex search, regex helper, saved searches, OCR, AI repair, document intake reports, extraction review, character tools, compare/diff helpers, diagnostics, plugin surfaces.
• Profiles: Essential, Casual Writer, Author or Student, Reader and Student, Office and Admin, Accessibility Professional, Developer and Power Text, Low Vision, Braille and Screen Reader Power User, Full Quill, Custom.
• Settings: a Profiles and Features page lets the user switch profiles, compare them, and expose quiet features when desired.
• Command/menu gating: menus, palette entries, status-bar cells, help topics, and settings pages only surface features appropriate to the active profile.

5.2 Documents and the editor

• The editor is a multi-line wx.TextCtrl with wx.TE_MULTILINE | wx.TE_RICH2 | wx.TE_NOHIDESEL | wx.TE_AUTO_URL. wx.TE_RICH2 is used only for selection and undo behaviour, not styling.
• UTF-8 internally. Line endings preserved on open, normalised to platform default on new documents.
• Soft wrap on by default; toggle with Alt+Z.
• Standard editing: cursor movement, selection, clipboard, undo and redo, all via the native edit control.
• Ctrl+Delete deletes the next word; Ctrl+Backspace deletes the previous word; result announced.
• Case conversion: Ctrl+Shift+U upper, Ctrl+L lower, Ctrl+Shift+T title. Selection if present, otherwise whole document.
• Multiple documents: Ctrl+Tab and Ctrl+Shift+Tab cycle. Switching announces document name only.
• Close current document: Ctrl+W or Ctrl+F4. Prompt to save if modified.
• Exit: Alt+F4 on Windows, Cmd+Q on macOS. Prompts for each modified document.
• Quill does not restore previous documents on launch by default. Opt-in setting available.

5.2a QUILL Quick Nav mode

Quill provides a browse-style, cursor-only navigation mode for long-form reading and structural movement in editable text surfaces.

• Activation: Ctrl+Shift+Grave enters QUILL Quick Nav mode.
• Exit: Esc exits QUILL Quick Nav mode.
• Direction rule: pressing Shift with a Quick Nav key reverses direction.
• Editing rule: no editing commands run while Quick Nav mode is active.
• Status rule: status bar reports Quick Nav mode state while active.
• Auto-exit rule: find and replace entry points return to normal command mode automatically.

Default Quick Nav keys:

• H / Shift+H: next and previous heading.
• 1 to 6 / Shift+1 to Shift+6: next and previous heading at level 1 through 6.
• A / Shift+A: next and previous link anchor.
• L / Shift+L: next and previous list container.
• I / Shift+I: next and previous list item.
• T / Shift+T: next and previous table.
• Q / Shift+Q: next and previous block quote.
• B / Shift+B: next and previous bookmark.
• ' / Shift+': next and previous code block.
• C: open table of contents (outline navigator).
• P / Shift+P: next and previous paragraph.
• S / Shift+S: next and previous sentence.
• Tab / Shift+Tab: next and previous block.

Artifact tracking model:

• Quill maintains an in-memory navigation index per active document.
• Index key: full document text plus markup kind.
• Headings: parsed from Markdown and HTML heading structure.
• Links: indexed from Markdown link forms and HTML anchor tags.
• Lists: indexed from Markdown list block starts and HTML ul/ol tags.
• List items: indexed from Markdown list markers and HTML <li> tags.
• Tables: indexed from Markdown table starts and HTML <table> tags.
• Block quotes: indexed from Markdown quote starts and HTML <blockquote> tags.
• Code blocks: indexed from Markdown fenced code boundaries and HTML <pre>/<code> tags.
• Bookmarks: indexed from active bookmark positions.
• Paragraph anchors: blank-line paragraph boundaries for text/Markdown; block-level HTML tags (p, li, blockquote, pre, h1 to h6, td, th) for HTML.

Edit-surviving bookmark anchors (“Points”). A bookmark stores more than a bare character offset: core/bookmark_anchor.py captures a small text window around the caret (before/after snippet + line) at set time. On jump, resolve_anchor relocates the bookmark to where that snippet actually lives now — fast-path when the stored offset still matches, else the nearest occurrence of the snippet to the old offset, else a clamped fallback when the text was deleted. Named bookmarks and numbered quick-bookmarks both capture anchors; anchors persist per-document in document_memory.json alongside the legacy int map and are fully backward-compatible (older files without anchors simply use the offset). This realizes the “Bookmarks survive edits” principle so a mark no longer drifts when text is inserted or removed above it.

• Sentence anchors: sentence-ending punctuation boundaries.

Performance and invalidation:

• Quick Nav movement reuses cached anchors to avoid reparsing per keystroke.
• Index invalidates when document text changes, when full-text replacement occurs, and when active tab changes.
• Missing-target announcements are plain-language and surface-aware (for example, “No list items found in this HTML document”).

Customization:

• Settings include wrap behavior for Quick Nav boundary traversal, feedback mode (speech, sound, both, none), and move-announcement detail (browse_mode_move_detail: position, line, none) — the latter controls whether a completed move reports line and column, line only, or nothing. Heading and block movement announce through the same path and setting as every other Quick Nav element type.
• Keyboard manager can reassign Quick Nav actions and leader sequences.

5.3 File operations

• Ctrl+N new blank document.
• Ctrl+O open via the user-selected dialog. When Settings > General > Use simple file open dialog is on, QUILL shows a keyboard-friendly picker (issue #620) with a path field, a small file-type filter, a recent-locations list, a hidden-files toggle, and a Use Windows Dialog button that opens the standard picker for one invocation. When the setting is off, QUILL shows the standard wx.FileDialog directly. The setting is off by default; the simple dialog is opt-in. The full supported list is in section 5.3a. The headline groups are:
  • Plain text and config: txt, log, cue, ini, json, jsonc, json5, xml, csv, tsv, yaml, yml, toml, nfo, env, properties, conf, cfg, dotenv.
  • Markdown family: md, markdown, mdx, mdown, mdwn, mkd, mkdn, mkdown, ronn, qmd (Quarto), rmd (R Markdown).
  • Lightweight markup: rst (reStructuredText), adoc/asciidoc, textile, org (Org-mode), wiki/mediawiki, bbcode, tex/latex, bib/bibtex, typ (Typst).
  • HTML family: html, htm, xhtml, mhtml/mht, svg (read as text + extracted <text> content).
  • Office, modern: docx, docm, dotx, dotm, pptx, pptm, xlsx, xlsm, ods, odt, odp, odg, pages, key, numbers.
  • Office, legacy (best-effort, with AI escalation): doc, ppt, xls, wpd (WordPerfect), wps (Works), wri (Windows Write), sxw/sxc/sxi (StarOffice).
  • PDF and PostScript: pdf, ps, eps, xps, oxps.
  • E-books: epub, epub3, azw, azw3, mobi, kfx, fb2, lit, lrf, prc, pdb (Palm), tcr, cbz/cbr (comic, text layers + OCR).
  • Rich text: rtf, rtfd.
  • Subtitles and captions: srt, vtt, sbv, ass/ssa, sub, ttml/dfxp, scc, stl, cap.
  • Spreadsheets as text tables: csv, tsv, xlsx, xls, ods, numbers, parquet (read-only), feather (read-only). Rendered as accessible plain-text tables with column headers, with Ctrl+Shift+Right/Left moving by column.
  • Email and calendar: eml, msg (Outlook), mbox, pst (one message at a time, with index), ics (calendar), vcf (contact card).
  • Notes and journals: one (OneNote, best-effort), enex (Evernote export), note (Apple Notes via iCloud export), bear (Bear export), simplenote JSON exports.
  • Source code and scripts (opened with syntax-aware tokenisation but presented as plain text): py, pyw, pyi, js, mjs, cjs, ts, tsx, jsx, c, h, cpp, hpp, cs, java, kt, rs, go, rb, pl, pm, php, lua, swift, m, mm, r, jl, dart, scala, clj, cljs, ex, exs, erl, hs, fs, vb, ps1, psm1, psd1, bat, cmd, sh, bash, zsh, fish, sql, graphql/gql, proto, thrift.
  • Build, package and lock files: Makefile, CMakeLists.txt, *.gradle, *.sbt, package.json, pyproject.toml, requirements.txt, Pipfile, Cargo.toml, go.mod, pom.xml, *.csproj/*.sln, Dockerfile, *.dockerfile, *.tf/*.tfvars, *.bicep, *.k8s.yaml.
  • Diff, patch and VCS artefacts: diff, patch, gitignore, gitattributes, gitmodules, gitconfig, gitlog (text dumps), hgrc.
  • Data and notebook: ipynb (Jupyter, read as a linear cell-by-cell document with role headers), qmd/rmd rendered notebooks, pickle/joblib (refused with explanation), sqlite/db (schema + sampled rows view, read-only).
  • Logs and trace: log, gz/zip/tar/7z (auto-extract single-text-file archives), evtx (Windows Event Log, summarised), etl (limited), journal JSON.
  • Web feeds: rss, atom, opml, json-feed.
  • Chat and transcript exports: WhatsApp .txt exports, Telegram .json/.html exports, Slack export JSON, Discord JSON exports, Teams transcript .docx/.vtt, Zoom .vtt/.txt, Otter .txt, ChatGPT export .json (rendered as linear conversation).
  • DAISY and accessible publishing: daisy (2.02, 3), nimas, bbeb, pef (braille). Read as plain text with section markers.
  • Braille files: brf, brl, pef, ueb (with optional back-translation to print via liblouis).
  • Audio with transcripts (transcript only): pairs of .mp3/.wav/.m4a/.opus with a sibling .vtt/.srt/.txt are opened as the transcript with playback shortcuts via plugin.
  • Image with OCR (opt-in OCR, local by default via Tesseract, AI escalation available): png, jpg/jpeg, tif/tiff, bmp, webp, heic, avif, gif, jp2. Multi-page TIFF supported.
  • Scanned documents: djvu, cbz/cbr, multi-page TIFF, image-only PDFs (handled by the PDF pipeline).
  • Subtitle bundles in containers: mkv/mp4 (extract embedded text tracks only; no media playback).
  • Web archives: warc, wacz, single-file .html saves from browsers, webarchive (Safari, best-effort).
  • Code-block exchange: GitHub Gist URLs and .gist.json, Pastebin .txt, snippet bundles.
• Ctrl+S saves. For editable text formats, saves in place. For rendered/extracted formats, opens Save As.
• Ctrl+Shift+S opens Save As directly.
• Recent files: last N (default 10, range 5 to 50). If empty, announce “No recent files.”
• File Explorer integration: settings panel lets the user register Quill with Windows for chosen extensions and add an “Open with Quill” verb.

5.3a Extended format support

The table below lists every format family Quill adds, why each matters, and how Quill renders it. Every renderer follows the same rules: present text in a standard edit field, preserve the original file, escalate to the enhanced extractor or AI repair only when local extraction is poor and the user asks.

Some renderers (notably KFX, PST, legacy proprietary office, and some iWork variants) require optional helper tools installed locally. Quill detects what is present at startup and the Open dialog only advertises formats it can actually read on this machine. The long-term design is a full Settings → Format Support page; the current beta already ships an External Tools and Format Support dialog that shows supported helpers, the capabilities they unlock, and copy-to-clipboard installation hints (never an automatic install).

Editable vs. read-only matrix

Not every format we open is something a user should edit. Quill is explicit about which formats round-trip in place vs. require Save As:

• Save in place: every plain-text and lightweight-markup format, source code, configs, subtitles, braille (BRF), SVG, JSON/XML/YAML/TOML, notebooks (when the user has explicitly chosen to keep notebook structure on save), and the two rich formats QUILL genuinely writes — DOCX and RTF — which round-trip through the canonical buffer and are re-serialized on every save (see 5.3a.1.1a).
• Save As only (originals protected): DOC, PPTX/PPT, XLSX/XLS, ODT/ODP/ODS, Pages/Keynote/Numbers, PDF, PS/EPS, XPS, EPUB and other e-books, DjVu, comics, MHTML and web archives, email (eml, msg, pst, mbox), calendar and contact files, OneNote, data files (sqlite, parquet, feather), all image formats. Enforced at the io layer by EXPORT_ONLY_SUFFIXES + UnsupportedSaveFormatError (5.3a.1.1a), not just by UI convention.
• Read-only with explicit refusal-to-edit message: PST archives, parquet/feather, evtx, AZW3/KFX, anything DRM-protected.

Plugin escalation

Where bundling a large dependency would balloon installer size (Calibre, Ghostscript, Tesseract trained-data packs, MeCab for Japanese, LibreOffice headless for legacy office), Quill ships a thin shim and offers a one-click plugin install from the Format Support page. Plugins announce their license clearly before installing.

5.3a.1 Pandoc Import / Export and Batch Conversion (issue #262)

QUILL ships a curated Tier-1 list of Pandoc-supported formats in the File menu and a four-page batch conversion wizard under Tools. The list is curated rather than exhaustive because not every Pandoc format is a good fit for a screen-reader-first editor; the menu and the wizard show only formats that meet the bar.

Tier-1 inputs: Markdown, CommonMark, GitHub-Flavored Markdown, HTML, Word documents (.docx), OpenDocument Text (.odt), Rich Text (.rtf), plain text, CSV / TSV tables, EPUB books, LaTeX / TeX.

Tier-1 outputs: the same set plus PDF (export only).

Non-Pandoc export — DAISY talking book (#251): File > Export > DAISY Talking Book writes a DAISY 2.02 text-only talking book. This export does not go through Pandoc; the wx-free, strict-typed quill/io/daisy.py (write_daisy_textonly) renders the live buffer directly. Because a DAISY book is a folder rather than a single file, the chosen name becomes a folder holding ncc.html (Navigation Control Center: dc:/ncc: metadata, multimediaType=textNCX, and heading links), content.html (XHTML 1.0 with an id on every readable element), and book.smil (SMIL 1.0 reading-order container with zero-duration <par>s, since the book carries no audio). Headings become player navigation points; a document with no h1 gets a synthetic title heading so navigation is well-formed. The output opens in DAISY software readers and hardware players (Victor Reader Stream, Plextalk, APH units) and in APH Book Wizard Producer for adding TTS audio.

5.3a.1.1 Single-file Import / Export

File > Import > converts a single file from disk into a new Markdown buffer in a new tab. File > Export > converts the current buffer to the named format on a background thread. Both routes use Pandoc and quill.stability.safe_subprocess.run_subprocess_safely so a misbehaving Pandoc cannot take QUILL down.

Post-conversion prompt rule (issue #262): when the target format is editable in QUILL (Markdown, CommonMark, GFM, HTML, plain text, CSV / TSV) the editor asks whether to open the new file in a new window. PDF, DOCX, EPUB, ODT, and RTF do not prompt; the file path is on the clipboard for pasting into File Explorer.

5.3a.1.1a Save As conversion pipeline and format truthfulness (shipped 0.9.0 Beta 1)

Save As converts; it never just renames. The editor’s canonical text is QUILL Markdown-style markup. quill/io/export.py::write_document_as is the single dispatcher every save routes through, keyed by target extension: .rtf re-serializes through the native RTF writer, .docx through write_docx_document, .html/.htm/.xhtml through the standalone HTML renderer, and .txt/.md/unknown text extensions are written verbatim (#649 round-trip contract; the explicit Save As Plain Text command is the stripping path, with the Illumination options).

The mark-saved contract (Caroline’s 0.8.0 report). Every writer in the dispatch — including both docx branches — must call document.mark_saved(target) on success, so the window title, the modified flag, the tab title, and the next plain Ctrl+S are truthful. The .docx writer’s missing mark_saved produced the “Untitled [modified] after a successful save, then an empty Save As dialog” failure; regression tests pin the contract for every format.

Line-break policy — one editor line is one paragraph, everywhere. The editor is line-oriented (what a screen reader user hears line by line is the document’s structure). The native writers already work this way (markdown_to_rich maps each editor line to a paragraph); every Pandoc call whose source is QUILL canonical text must therefore use gfm+hard_line_breaks, never bare gfm (where a single newline is a soft wrap that silently joins the user’s lines). This applies to the docx Pandoc fallback and to every File > Export format. Convert File / Batch Conversion of arbitrary on-disk files keep their detected source semantics.

Export-only extension guard (data-loss invariant). EXPORT_ONLY_SUFFIXES (.pdf .doc .odt .epub .pages .ppt .pptx .xls .xlsx .sqlite .db) marks formats QUILL can open (as extracted text) but cannot write. write_document_as raises UnsupportedSaveFormatError for them: Ctrl+S on an opened PDF/EPUB/spreadsheet must never overwrite the binary original with text (the UI explains and routes to Save As), and a typed notes.pdf in Save As must never mint a Markdown file wearing a .pdf name (the UI offers the Pandoc Export hand-off for .pdf/.odt/.epub and refuses the rest). This implements the “Save As only (originals protected)” row of the editable-vs-read-only matrix above as an enforced io-layer invariant rather than a UI convention. .brf-family and unknown text extensions stay verbatim by design.

The editing surface stays QUILL text — audibly. After a converting Save As (.docx/.rtf/HTML) the file on disk is the converted artifact and each subsequent save re-converts; the editor does not switch to the target format. _announce_save_as_conversion speaks this (“Saved as report.docx, Word format. You are still editing QUILL text; each save converts it to Word.”) so the model is explicit for a screen reader user. No auto-reload is offered for .docx: a reload would round-trip through a different engine (MarkItDown) and silently lose formatting just saved.

Filename suggestion from the first line. first_line_as_title (default on) pre-fills Save/Export dialogs for an untitled document from its first meaningful line via quill/core/titles.py (markup leaders stripped, Windows-invalid characters removed, 60-char cap). It only ever suggests a name for an untitled document.

Rich-mode Save As converts the RichDocument, not the plain-text mirror. When a .docx opens in rich mode, document.text is a flattened plain-text mirror, so routing a .md/.html Save As through the classic writer lost all formatting. main_frame_rich_mode._save_rich_as_markup now intercepts .md/.markdown/.html/.htm/.xhtml in rich mode, reconstructs the RichDocument from the control’s RTF (rtf_to_rich), and renders it with rich_to_markdown (Markdown) / markdown_to_html (HTML). The Save As dialog and its extension routing were correct; the defect was a missing converter wiring on the rich path.

Cross-format fidelity matrix (measured; tests/unit/io/test_save_as_format_fidelity.py). Everything routes through the shared RichDocument / canonical-Markdown hub, so preservation is per-feature, not per-pair. ✅ native, ◑ carried as portable markup/text, ✕ lost.

1. Hidden-codes markup ([text]{…} spans / ::: {…} divs) in Markdown; materialised natively on HTML/Word/RTF export.
2. Markdown-native and native in HTML; literal markers in Word/RTF (the RichDocument model has no blockquote/code/hr structure).
3. Tables round-trip as real tables across Markdown, HTML, and Word: Word tables read → GFM tables (_table_to_rich_paragraphs), and GFM-table paragraphs written to Word are reconstructed into native w:tbl objects (_table_block_length/_emit_table in docx_writer), with the header row bold and marked <w:tblHeader> (repeating header, screen-reader-announced). RTF remains the exception — a table written to RTF is pipe-text, not a native RTF table.
4. Image references round-trip in Markdown and render as <img> in HTML; images are not embedded into Word, and embedded Word images are not read.

Round-trip improvements (0.9.0, quill/io). docx hyperlinks round-trip both ways — rich_to_docx writes a real w:hyperlink with an OPC relationship, read_docx_rich recovers the href via iter_inner_content (previously links degraded to plain text). Numbered lists are first-class: a numbered RichParagraph style plus list_number carried through markdown_to_rich/rich_to_markdown (identity, keeps a non-1 start), docx List Number read/write (sequential numbering assigned on read), and the offset map. markdown_to_html now emits <img> for images and <blockquote> for quote lines. Tables round-trip as real tables between Markdown, HTML, and Word: docx_writer detects consecutive GFM-table paragraphs (_table_block_length) and rebuilds a native w:tbl (_emit_table) with a bold, repeating <w:tblHeader> header row — so Markdown→Word and HTML→Word (via the hub) now produce editable Word tables, and Word→Markdown/HTML already preserved them. Remaining honest gaps: RTF drops alignment and page breaks and writes tables as pipe-text; docx drops page breaks on read; inline formatting inside a Markdown-authored table cell flattens to plain text on the way to Word; Word-embedded images are not extracted.

Conversion engine preferences. Two settings expose the engine choice with speakable outcome descriptions: docx_read_engine (auto | markitdown | pandoc — auto is MarkItDown-first, then the python-docx render (quill/io/docx_text.py: headings, lists, tables), with the raw word/document.xml walk as the last resort; the pandoc preference degrades to auto when Pandoc is missing, so a preference never fails an open) and docx_write_engine (auto | native | pandoc — native is the hidden-codes-preserving python-docx writer; pandoc maps structure to Word styles and drops run-level font/size/color). The Convert File dialog carries a per-operation Conversion engine choice (Auto/Pandoc/MarkItDown) whose description follows the selection; MarkItDown is honored only where it honestly applies (Office/PDF source, Markdown/plain output) and the handler asks before substituting Pandoc, never silently. Engine evidence: docs/qa/converter-bakeoff.md (2026-07-04) — MarkItDown and Pandoc passed the full corpus; the python-docx reader loses tables/footnotes/links (fallback only); pydocx is rejected permanently (cannot import on Python 3.10+, last release 2016); mammoth is not adopted (no current gap) with a standing decision tree: if a MarkItDown fidelity gap appears, mammoth is the candidate and would be bundled (pure-Python; frozen builds cannot pip-install at runtime), lazily imported, and offered as a third read-engine choice.

5.3a.1.2 Batch Conversion wizard

File > Import > Batch Conversion… and File > Export > Batch Conversion… (or QUILL key, B) open a hand-rolled wx.Dialog modeled on setup_wizard_pages.py. Four pages: Introduction (with live Pandoc version probe), Folder and options (folder picker, recursive checkbox, output-layout radio, overwrite radio), Format and profile (direction radio, Tier-1 source/target lists, profile picker), Review and start (human-readable summary).

Defaults come from Settings.import_export_recursive, import_export_output_layout, import_export_overwrite, and the wizard-overridable import_export_last_folder. The wizard can override any of these per run; the Preferences dialog is the canonical place to change defaults.

The wizard’s _SummaryPage.refresh(choices) reads the plan aloud through _announce() so the user hears what they are about to apply before the batch starts. Back / Next / Start / Cancel are stock wx.Button controls under the standard apply_modal_ids modal-id contract; the wizard is keyboard-first end to end and never depends on the mouse.

5.3a.1.3 Batch execution

The wizard returns a BatchRequest carrying a BatchPlan dataclass. The caller submits the plan to MainFrame._run_background_task so the work runs on stability.task_manager.QuillTaskManager (a ThreadPoolExecutor wrapper) instead of the UI thread. Progress is reported through the Status Page (Help > Status Page > Tasks & Downloads) with one live (Task, Status, Progress, Started, Finished) row per file. The worker honours a threading.Event cancel between files and raises PandocCancelledError if cancellation fires mid-run.

Output naming follows the issue #262 rule verbatim: keep the originating stem, replace the extension. With output_layout="subfolder" (the default) the output lands in an Output/ subfolder created lazily per file; with output_layout="same_folder" the output lands next to the source. The three-way overwrite policy — ask, never, always — is enforced both at the batch level (one prompt per batch for the ask policy) and per file (skip on never, overwrite on always).

5.3a.1.4 Conversion profiles

Seven built-in conversion profiles ship in this release (quill.core.convert_profiles):

• Clean Word Document — --standalone plus aggressive header/footer stripping.
• Accessible HTML Page — --standalone with title-block and lang metadata.
• EPUB Book — --standalone --toc plus the EPUB-3 metadata block.
• GitHub README — GitHub-Flavored Markdown with no wrapper.
• Print PDF — --pdf-engine=<default> plus the standard PDF metadata.
• Instructor Handout — --standalone with geometry: margin=1in and a top-level numbered section structure.
• Plain Text for Screen Readers — plain text with no HTML wrapper, no smart quotes, fixed 80-column width.

Each profile is a ConvertProfile dataclass holding its CLI flags and a plain-language description. The wizard’s profile picker reads each profile aloud so the screen reader can announce what is being applied before the batch starts.

5.3a.1.5 Completion announcement

When the batch finishes, _announce() is called with the completion line:

“Batch conversion complete. of files converted in seconds. skipped. failed.”

The line routes through the existing announce() -> _announce() -> AnnouncementEngine path, which already honours announcement_backend and verbosity_speech_enabled. The Status Page row updates regardless of the user’s verbosity setting so sighted and low-vision users see the same result.

A short report dialog lists every file that produced warnings or failed, with the exact error string. Successful files do not appear in the report, so the dialog stays small and quick to read.

5.3a.1.6 Settings

Three new SettingSpec entries appear in Preferences > Editing (issue #262):

• import_export_recursive — boolean, default True. Label: “Include subfolders in batch conversion”.
• import_export_overwrite — choice, default ("ask", "Ask each time"). Choices: ask, never, always. Label: “Overwrite behaviour for batch conversion”.
• import_export_output_layout — choice, default ("subfolder", "Output subfolder per source folder"). Choices: subfolder, same_folder. Label: “Default output layout for batch conversion”.

A fourth field, import_export_last_folder (string, default ""), is intentionally not exposed in Preferences. The wizard writes it when it starts a batch so the next run lands the user where they left off. All four fields are validated in Settings.from_dict against the issue #262 value sets.

5.3a.1.7 Key binding

QUILL key, B opens the Batch Conversion wizard. The chord was added to quill.core.keymap and is wired through MainFrame._on_quill_key_b. The B key was chosen because it does not collide with any existing QUILL-key second-key in main_frame_quill_key.py.

5.3a.1.8 Out of scope for this release

• PDF import. Pandoc cannot do it reliably; the dedicated braille and DAISY pipelines remain the right tools.
• Tier 2 / Tier 3 formats. A future release will replace the Tools > Pandoc Conversion Center… placeholder with the full format picker.
• MarkItDown integration. Tracked as a follow-up issue. The integration belongs in a Quillin so its dependencies stay out of the core.
• Dedicated per-verb token for batch completion. The verbosity system has shipped (engine, UI, runtime modes, anti-spam — see §5.91.4), and the batch-conversion completion announcement already routes through it (MainFrame._announce → VerbosityController.process()), today as the _legacy passthrough. Binding it to the existing system.operation_complete verb with a custom token template is optional polish, not done for this release.

Cross-links: this section is referenced from ### 5.25b Watch Folder automation (the Watch Folder Quillin can use the same BatchPlan shape when it needs batch-style conversion) and from §22 Startup Wizard (the Startup wizard’s “What kind of writing do you do?” intent picker exposes the Import / Export and Batch Conversion entries only when the chosen profile warrants them).

5.3b Microsoft Word document support (DOCX / DOC)

This section is the canonical, scoped statement of what Quill 1.0 does with Microsoft Word files (.docx and .doc). Anything not listed here is explicitly out of scope for v1.0 and tracked in the backlog.

5.3b.1 Complexity and Risk Context

Microsoft Word documents (.docx = XML-based, .doc = binary OLE2 format) present genuine complexity risks:

1. Formatting metadata: fonts, sizes, colors, styles, themes, templates
2. Complex structure: headers, footers, text boxes, shapes, comments, tracked changes
3. Media embedding: images, charts, SmartArt, embedded objects, videos
4. Advanced features: fields, macros (VBA), content controls, form controls, ActiveX
5. Reading order challenges: columns, text boxes in non-linear positions, floating shapes
6. Legacy cruft: corrupted documents, OLE objects, mixed encodings, malformed XML

Quill’s design principle (“The edit field is sacred”) prevents visual formatting preservation in v1.0. Word files must be extracted to plain, linear text in wx.TextCtrl for guaranteed screen-reader compatibility with NVDA, JAWS, and Narrator.

5.3b.2 Supported Features (What Gets Extracted)

Core content (via Pandoc extraction):

• ✅ Body text and paragraphs
• ✅ Headings (levels 1–6) → rendered as Markdown #, ##, ###, etc.
• ✅ Bullet and numbered lists (nested up to 3 levels)
• ✅ Hyperlinks → preserved as plain-text URLs or Markdown links
• ✅ Comments and tracked changes → extracted as plain text with attributions
• ✅ Footnotes and endnotes → appended as footnote text
• ✅ Tables → converted to plain-text table representation (Markdown or ASCII)
• ✅ Page breaks → rendered as visual markers --- Page Break ---
• ✅ Basic structural integrity: proper paragraph separation, list context

Conversion support (via Pandoc bridge):

• ✅ Word → Markdown (for universal editing)
• ✅ Word → HTML (for preview/export)
• ✅ Word → Plain text
• ✅ Word → RTF (via Pandoc if needed)
• ✅ Cross-format roundtrip: Markdown ↔︎ Word, HTML ↔︎ Word

Metadata (stored in Document.source_metadata):

• ✅ Document title, author, subject
• ✅ Creation/modification dates
• ✅ Word count, page count (if available)
• ✅ Character encoding detection and preservation
• ✅ Extraction engine name and version (Pandoc 3.1+)
• ✅ Quality score (0–100) quantifying extraction fidelity

5.3b.3 Unsupported Features (Not Extracted, User Warned)

Formatting (intentionally dropped for v1.0 compatibility):

• ❌ Font names, sizes, colors, bold/italic/underline
• ❌ Paragraph alignment (left, center, right, justify)
• ❌ Line spacing, paragraph spacing, indentation
• ❌ Themes, master pages, custom styles
• ❌ Watermarks, page backgrounds

Advanced structures (extracted with limitations or skipped):

• ⚠️ Images: Filenames and captions only; image content is NOT OCR’d unless user opts in v1.1+
• ⚠️ Charts: Extracted as text labels only; visual data is lost
• ⚠️ Text boxes and shapes: Attempted extraction; may appear out of order or be skipped
• ⚠️ Headers and footers: Extracted, appended as a section at end of document
• ⚠️ Columns: Flattened to single column; reading order may be unpredictable

Security-sensitive (explicitly blocked or sanitized):

• ❌ VBA macros: Silently ignored; Pandoc subprocess does not execute any code
• ❌ Embedded executables or ActiveX controls
• ❌ External links to remote templates or resources (not followed)
• ❌ OLE embedded objects (attempted extraction of embedded text only)

Deferred to v1.1+ (not attempted in v1.0):

• ❌ Revision history or multi-user collaboration metadata
• ❌ Form fields and fillable controls
• ❌ Custom numbering or multi-level list hacks
• ❌ Mail merge fields
• ❌ Document protection or permissions (file access checked by OS only)

5.3b.4 Architecture: I/O Module Design

New module: quill/io/word.py

• read_word_document(path, timeout_sec=60.0, fallback_to_plaintext=True) → Document

  • Extracts text from .docx or .doc file
  • Returns Document with extracted text, metadata, quality_score, and warnings
  • Timeout protection: max 60 seconds to prevent runaway conversions
  • Error cascade on failure: Pandoc → python-docx → plaintext fallback
  • Raises UnsupportedFormatError or ExtractionTimeoutError on fatal errors

• write_word_document_safe(document, path=None, format="docx", warn_on_formatting_loss=True) → Path

  • Safely writes extracted text back to Word format
  • Shows warning dialog: “Saving as plain text. Original Word formatting will be lost.”
  • Uses Pandoc (Markdown → .docx) for clean roundtrip
  • Never overwrites original without explicit user confirmation

• convert_word_to_markdown(path) → str

  • Converts Word document to GitHub-flavored Markdown
  • Uses Pandoc with specific output flags for best compatibility

Enhanced module: quill/io/pandoc.py

Add Word-specific conversion routes:

READER_MAP: dict[str, str] = {
    "docx": "docx",  # NEW: from .docx
    "doc": "doc",  # NEW: from .doc (legacy)
}

WRITER_MAP: dict[str, str] = {
    "word": "docx",  # NEW: export to .docx
    "word-old": "doc",  # NEW: export to .doc (legacy)
}


@dataclass(frozen=True, slots=True)
class WordMetadata:
    title: str | None
    author: str | None
    subject: str | None
    created: str | None
    modified: str | None
    word_count: int
    page_count: int

Updated module: quill/io/detect.py

TEXT_EXTENSIONS = {
    # ... existing ...
    ".docx",  # NEW
    ".doc",  # NEW
}


def looks_like_word_document(path: Path) -> bool:
    return path.suffix.lower() in {".docx", ".doc"}

5.3b.5 Error Handling: Graceful Cascade

Word extraction implements a three-tier fallback strategy to ensure the app never crashes on corrupted, malicious, or malformed files:

Tier 1: Pandoc (primary path)

• Subprocess-isolated extraction via Pandoc 3.1+
• Timeout: 60 seconds (hard limit)
• Success: quality_score ≥ 60
• On failure → Tier 2

Tier 2: python-docx (fallback)

• Basic paragraph/heading extraction only
• No Pandoc dependency required
• quality_score ~40 (limited feature set)
• Errors logged; user sees warning banner
• On failure → Tier 3

Tier 3: Emergency UTF-8 read

• Last-resort: read file as text
• Returns garbled but won’t crash
• quality_score 0
• Clear error message: “Document could not be fully read. Try opening in Microsoft Word first.”

5.3b.6 User-Facing Messaging (Document Intake Report)

When opening a .docx or .doc file, Quill displays an in-app banner (stored in source_metadata, displayed by main_frame.py):

📄 Word Document Opened
This document has been converted to plain text for editing in Quill.
• Formatting (fonts, colors, styles) has been removed.
• Tables and lists have been simplified for readability.
• Images and charts have been replaced with captions only.
• If you need the original formatting, open this file in Microsoft Word.

Original file: Z:\documents\report.docx
Engine: Pandoc 3.1.0 | Quality score: 85/100

[🔄 Retry extraction]  [💾 Save as .txt]  [📖 Show details]

The banner is concise and accessible: each item is announced separately via screen reader, and action buttons are navigable via Tab.

Where Am I enhancement: When cursor is at the start of an extracted Word document, Ctrl+Alt+W (Where Am I) announces:

“Word document. Title: Q2 Report. Author: Jane Doe. 8 pages, 2,451 words. Extracted by Pandoc 3.1.0. Quality: 85 out of 100. Formatting not preserved.”

5.3b.7 Pandoc Integration and Format Bridge

Pandoc is a universal document converter supporting 30+ input and output formats. Full integration enables:

Phase 1 (v1.0 — this release):

• Pandoc reads .docx and .doc files
• Export to Markdown, HTML, RTF via File > Save As
• Metadata extraction for document properties
• Fallback pipeline: Pandoc → python-docx → plaintext

Phase 2 (v1.1):

• Pandoc template engine for styled exports
• Batch conversion: Tools > Convert Document
• Support for .odt (LibreOffice), .tex (LaTeX)
• Optional: OCR images in Word documents (cloud service or local Tesseract)

Phase 3 (v1.2+):

• Pandoc filters for custom transformations
• Plugin API for format extension

Installation and resource limits:

• Pandoc is bundled with Quill on Windows (or installed via choco install pandoc)
• Subprocess isolation: Pandoc runs out-of-process; malicious code cannot harm Quill
• Timeout: 60 seconds per document (hard limit)
• Memory: Monitored via psutil; warns if > 500 MB used during extraction
• File size: Pre-check before extraction; if > 100 MB, warn and offer async extraction

5.3b.8 Editable Rendering, Protected Original

Word files follow Quill’s principle: originals are read-only by default.

• The extracted text is presented in the standard multi-line editor
• Ctrl+S opens Save As so the original .docx / .doc cannot be overwritten
• Ctrl+Shift+S opens Save As directly
• Save dialog offers: .txt, .md (Markdown), .html, .docx (new Word), or All Files
• Before saving to .docx, a warning dialog appears:

  “Saving as plain text. Original Word formatting will be lost. Continue?”

5.3b.9 Metadata and Quality Scoring

Extracted metadata is stored in the Document.source_metadata dict:

source_metadata = {
    "source_kind": "word",
    "format": "docx",  # or "doc"
    "engine": "pandoc",
    "engine_version": "3.1.0",
    "quality_score": 85,  # 0–100
    "extraction_warnings": [
        "Images not extracted (captions only)",
        "Tracked changes simplified to plain text",
        "Columns flattened to single column",
    ],
    "word_metadata": {
        "title": "Q2 Report",
        "author": "Jane Doe",
        "subject": "Financial Review",
        "created": "2026-03-15T10:30:00Z",
        "modified": "2026-05-28T14:22:00Z",
        "word_count": 2451,
        "page_count": 8,
    },
}

Quality score calculation (0–100):

• Start at 100
• Subtract 5 per non-extracted image
• Subtract 10 per text box with suspected out-of-order content
• Subtract 15 if complex shapes or columns detected
• Subtract 20 if corrupted sections skipped
• Floor at 0, never negative

5.3b.10 Risk Mitigation and Safety

5.3b.10a Extraction Quality Diagnostics

Quill applies accessibility-aware diagnostic techniques to deeply analyze Word documents and produce actionable extraction warnings:

Paragraph-level diagnostics:

• Fake lists detection: Scan paragraphs for manually typed bullet characters (•, ‣, ◯, ◯, ◦, ⁃) or numbered patterns (“1.”, “a)”) instead of built-in list styles; flag as “Potential fake list” in source_metadata
• All-caps content: Detect paragraphs in ALL CAPS (not formatting, but typed caps); if > 3 words, flag as potential heading that should be restyles
• Long sections without headings: If > 20 paragraphs appear without a heading, flag as “Consider adding structure” in extraction warnings
• Repeated spaces for layout: Detect runs of 3+ consecutive spaces used for visual alignment (e.g., Qty: ___Price:___); flag as “Document uses spaces for layout, which may reflow unexpectedly in Quill”
• Repeated font families in paragraph: Track non-Arial fonts per paragraph; cap reporting at 3 example locations + summary count to avoid spam

Document-level diagnostics:

• Title and language metadata: Extract document properties (title, language, author); if missing, flag “Document title not set in properties” as info-level warning
• Page setup: Extract margin configuration; compare against expected values; if margins are unusual (< 0.5“ or > 1.5“), note in warnings
• Hyphenation: Detect if auto-hyphenation is enabled; flag as “Hyphenation may break words unexpectedly when text reflows”
• Heading hierarchy: Scan for missing levels (e.g., H1 followed by H3) or skipped levels; flag as structural issue

Extraction engine diagnostics:

• Track extraction path: Note which engine extracted each paragraph (Pandoc, python-docx, plaintext)
• Per-paragraph confidence: If Pandoc succeeded but python-docx fallback was triggered for some content, track which paragraphs used fallback
• Engine switch detection: If Pandoc extracted pages 1–8 but python-docx took pages 9–12, surface this as “Extraction method changed mid-document” warning

Example source_metadata structure with accessibility-aware diagnostics:

source_metadata = {
    "source_kind": "word",
    "format": "docx",
    "engine": "pandoc",
    "engine_version": "3.1.0",
    "quality_score": 78,  # Reduced from 85 due to diagnostics
    # accessibility-aware diagnostics
    "extraction_diagnostics": {
        "fake_lists_detected": 2,  # Manually typed bullets
        "all_caps_paragraphs": 1,  # Heading-like caps text
        "long_sections_without_headings": ["Pages 5-6 (23 paragraphs)"],
        "repeated_space_paragraphs": 3,  # Layout abuse detected
        "non_arial_fonts": {"Times New Roman": 5, "Courier": 2},
        "hyphenation_enabled": True,
        "heading_hierarchy_issues": ["H1 at page 1, then H3 at page 2"],
        "extraction_engine_switches": ["Pandoc pages 1-8, python-docx pages 9-10"],
    },
    "extraction_warnings": [
        {
            "id": "FAKE_LISTS_DETECTED",
            "severity": "warning",
            "message": "2 paragraphs detected with manually typed bullet characters instead of built-in list styles",
            "location": "Paragraph 5, Paragraph 12",
            "user_action": "review",
            "suggestion": "Consider reformatting as proper lists in Word",
        },
        {
            "id": "LONG_SECTION_NO_HEADING",
            "severity": "info",
            "message": "23 paragraphs without a heading (pages 5-6)",
            "location": "Paragraphs 45-68",
            "user_action": "review",
            "suggestion": "Add section heading for readability",
        },
        {
            "id": "HYPHENATION_ENABLED",
            "severity": "warning",
            "message": "Automatic hyphenation is enabled; hyphenated words may reflow unexpectedly in Quill",
            "location": "Document Settings",
            "user_action": "accept",
            "suggestion": "Consider disabling hyphenation in Word for cleaner reflow",
        },
    ],
    "word_metadata": {
        "title": "Q2 Report",
        "author": "Jane Doe",
        "subject": "Financial Review",
        "created": "2026-03-15T10:30:00Z",
        "modified": "2026-05-28T14:22:00Z",
        "word_count": 2451,
        "page_count": 8,
        "language": "en-US",
        "margins": {
            "top_in": 1.0,
            "bottom_in": 1.0,
            "left_in": 1.0,
            "right_in": 1.0,
        },
    },
}

User experience enhancement:

Instead of a flat banner, Quill displays diagnostics with context:

📄 Word Document Opened
Extracted via Pandoc 3.1.0 | Quality: 78/100 (down from 85 due to structural issues)

✓ 8 pages extracted, 2,451 words
✓ 12 headings (H1-H3) converted
⚠ 2 paragraphs with typed bullet characters (should be proper lists)
⚠ Long section without headings (23 paragraphs on pages 5-6)
⚠ Hyphenation enabled (may cause unexpected line breaks)
ℹ Document title: "Q2 Report" | Language: en-US

[🔍 View diagnostics] [💾 Save as .txt] [Learn more]

Clicking [🔍 View diagnostics] opens a detailed panel showing each diagnostic with suggestions and locations.

5.3b.11 Testing Strategy

Test corpus (stored in tests/fixtures/word/):

Unit tests (tests/unit/io/test_word.py):

def test_read_docx_simple():
    doc = read_word_document(Path("tests/fixtures/word/simple_heading.docx"))
    assert "Heading" in doc.text
    assert doc.source_metadata["quality_score"] > 80


def test_read_doc_legacy_format():
    doc = read_word_document(Path("tests/fixtures/word/legacy_format.doc"))
    assert doc.text.strip()  # Non-empty
    assert "engine" in doc.source_metadata


def test_read_corrupted_falls_back():
    doc = read_word_document(Path("tests/fixtures/word/corrupted.docx"))
    assert doc.source_metadata.get("quality_score", 0) < 50
    assert len(doc.text) > 0  # No crash; degraded gracefully


def test_read_timeout_protection():
    with pytest.raises(ExtractionTimeoutError):
        read_word_document(
            Path("tests/fixtures/word/large_50mb.docx"),
            timeout_sec=0.1,
        )


def test_macros_not_executed():
    doc = read_word_document(Path("tests/fixtures/word/malicious_macros.docx"))
    assert "VBA" not in doc.text and "Sub " not in doc.text

Integration tests (tests/integration/test_word_open.py):

• Open .docx via UI; verify text loads, no crash
• Check source_metadata banner appears
• Verify status bar shows correct word count, page count
• Save extracted text back to .docx; verify roundtrip produces sensible output
• Verify warning dialog appears before save

Accessibility tests (tests/a11y/test_word_screen_reader.py):

• NVDA/JAWS reading of extracted text
• Verify metadata banner is announced properly
• Keyboard-only workflow: open → read → navigate → save

Performance tests (tests/perf/test_word_extraction_speed.py):

• Load 5, 50, 500-page documents; measure extraction time and memory
• Confirm 60-second timeout stops runaway conversions
• Verify UI remains responsive during extraction

5.3b.12 Rollout and Communication

Word documents should open through a direct/native Word-document path by default when the local engine can handle them. If that path is unavailable or fails on a particular file, Quill should offer an explicit choice to fall back to extracted-text import so the user always knows which mode they are entering.

Pre-release (release notes):

• Announce: “New: Microsoft Word support (v1.0)”
• Link to knowledge base: “Opening Word Documents in Quill”
• Highlight limitations: “Formatting is not preserved; use Save As for best results”

In-app messaging (on first Word document open):

• Display metadata banner with quality score
• Offer [📖 Learn more], [💾 Save as .txt], [📝 Open as extracted text], [❌ Close] actions when the direct/native path is not available
• Help menu entry: “Opening Word Documents in Quill”

Documentation:

• README: “Supported Formats” section lists .docx/.doc with caveats
• Knowledge base: Step-by-step guide for opening, extracting, saving Word documents
• Command palette: “Open Word Document” command has full description
• FAQ: Proactive entries for “What happens to my formatting?” and “Can I edit the original Word file?”

5.3b.13 Success Criteria

By end of v1.0:

1. ✅ Functional: Users open .docx/.doc through a direct/native Word path when available; extracted text remains readable/navigable with screen readers as a fallback, content (headings, lists, tables, links) preserved accurately, save to .txt/Markdown/new .docx
2. ✅ Safe: No crashes on corrupted/malicious/large files, VBA not executed, timeout prevents runaway conversions, user warned before formatting loss
3. ✅ Discoverable: File > Open shows .docx/.doc as supported, File > Save As offers Word formats, in-app banner explains changes, help docs explain workflow
4. ✅ Tested: 10+ real-world documents tested, unit/integration/a11y/perf tests passing, no regressions in existing formats
5. ✅ Documented: User docs explain what is and is not supported, known limitations transparent, troubleshooting guide provided

5.3b.14 Future Enhancements (Post-v1.0)

• Async extraction: Large files extract in background without blocking UI
• OCR images: Option to OCR images in Word documents (local Tesseract or cloud service)
• Format bridge UI: Visual flow chart of all supported conversions (Word native/direct ↔︎ Markdown ↔︎ HTML ↔︎ PDF)
• Batch conversion: “Convert 50 Word docs to Markdown” automation
• Metadata editor: Simple UI to edit document title, author, creation date
• Plugin API: Allow plugins to register custom Word extraction filters
• Roundtrip fidelity: Preserve more metadata on Word → edit → Word cycles
• Document audit mode (v1.1+): Scan incoming Word docs for structural issues (fake lists, poor heading hierarchy, orphaned paragraphs) and warn user
• MarkItDown fallback: If available, use Microsoft’s MarkItDown for improved .doc and .docx extraction before Pandoc
• VML namespace awareness: Enhanced python-docx fallback with VML shape and text-box extraction for legacy .doc files
• Paragraph-level diagnostics: Track which extraction engine handled each paragraph, surface problematic content for review
• Styled template export: When saving as .docx, offer ACB-style or custom templates for accessibility compliance

5.3c Microsoft PowerPoint document support (PPTX / PPT)

This section is the canonical specification for PowerPoint support in Quill 1.0. Anything not listed is explicitly out of scope for v1.0 and tracked in the backlog.

5.3c.1 Complexity and Risk Context

PowerPoint presentations (.pptx = XML-based, .ppt = binary OLE2 format) present unique extraction challenges:

1. Non-linear content: Slides arranged by visual layout, not reading order; multiple shapes per slide
2. Visual-first design: Slide transitions, animations, speaker notes separate from visible content
3. Nested structure: Master slides, slide layouts, themes, custom templates, shapes groups
4. Embedded media: Images, charts, SmartArt, embedded audio/video, links
5. Layout complexity: Text boxes, shapes, grouped objects with reading-order dependencies
6. Presenter-specific data: Speaker notes, slide timings, presentation settings
7. Legacy cruft: .ppt binary format, corrupted presentations, mixed encoding, malformed XML

Quill prioritizes linear text extraction and speaker notes over slide visual preservation. The design principle (“The edit field is sacred”) prevents visual formatting preservation in v1.0.

5.3c.2 Supported Features (What Gets Extracted)

Read (Pandoc extraction):

• ✅ Slide titles
• ✅ Body text and bullet points (nested up to 3 levels)
• ✅ Text from text boxes (best-effort reading order)
• ✅ Speaker notes (always extracted, separately indexed)
• ✅ Hyperlinks → preserved as plain-text URLs or Markdown links
• ✅ Slide numbers and slide count
• ✅ Presentation metadata: title, author, subject, creation date
• ✅ Basic slide structure: explicit slide markers for boundary detection
• ✅ Chart and SmartArt labels (text-only; visual data is lost)

Conversion support (via Pandoc bridge):

• ✅ PowerPoint → Markdown (slide-by-slide structure)
• ✅ PowerPoint → HTML (presentation as linear HTML document)
• ✅ PowerPoint → Plain text

Metadata:

• ✅ Presentation title, author, subject, keywords
• ✅ Creation/modification dates
• ✅ Slide count, speaker notes count
• ✅ Character encoding detection and preservation

5.3c.3 Unsupported Features (Not Extracted, Logged, User Warned)

Visual design (intentionally dropped for v1.0 compatibility):

• ❌ Slide backgrounds, themes, custom templates
• ❌ Font names, sizes, colors, bold/italic/underline
• ❌ Slide transitions and animations (detected but not played)
• ❌ Master slides and slide layouts (flattened to content only)
• ❌ Alignment, positioning, spacing of text boxes
• ❌ Watermarks, headers, footers

Advanced structures (extracted with limitations or skipped):

• ⚠️ Images and pictures: Filenames and captions only; image content is NOT OCR’d unless user opts in v1.1+
• ⚠️ Charts: Extracted as text labels only; visual data is lost; title and data labels if readable
• ⚠️ SmartArt: Converted to bullet-point approximation; visual hierarchy is lost
• ⚠️ Embedded video/audio: NOT extracted; presence flagged with duration if available
• ⚠️ Text boxes and shapes: Attempted extraction; may appear out of slide reading order
• ⚠️ Slide layouts and masters: Flattened to content only; layout structure is not preserved
• ⚠️ Animations and timing: Detected and reported but not executed; all animated content extracted

Security-sensitive (explicitly blocked or sanitized):

• ❌ Embedded ActiveX controls or macros (VBA) — silently ignored; Pandoc does not execute
• ❌ External links to remote templates or resources (not followed)
• ❌ OLE embedded objects

Deferred to v1.1+ (not attempted in v1.0):

• ❌ Presentation handout mode or notes pages export
• ❌ Custom animations or presentation sequences (click-through, auto-play)
• ❌ Form controls or interactive content
• ❌ Presenter view or presenter notes as a separate stream

5.3c.4 Slide Linearization with Reading-Order Detection

PowerPoint is inherently non-linear. Quill converts to linear text with intelligent, accessibility-aware reading-order analysis:

Screen readers follow the XML tree order of shapes, not the visual layout. When these don’t match, screen readers read slides in the wrong order. Quill analyzes both orders and extracts in visual order (what user sees) while flagging reading-order mismatches to the user.

Output: Intelligent slide extraction with reading-order diagnostics

--- Slide 2: Agenda ---
[Title appears first - reading order verified]
Agenda

[3 text boxes detected on slide; visual order verified]
Left column (top-left position):
  • Introduction
    • Background
    • Scope

Right column (top-right position):
  • Main topics
    • Topic 1
    • Topic 2

Center callout (center position):
  🔹 All topics are in scope

📊 Reading Order Analysis:
  ✓ Visual order matches XML order (correct for screen readers)
  ✓ Title reads first (best practice)
  Shapes in reading order: Title → Left → Right → Center

5.3c.5 Smart Speaker Notes Extraction

Speaker notes are always extracted and separately indexed with intelligent metadata:

• Presence detection: slide has/lacks notes
• Timing hints: notes mentioning “2 minutes”, “pause here”, “auto-advance”
• Visual references: notes mentioning images, charts, diagrams on the slide
• Presenter guidance: transitions, animation, pacing guidance

Example metadata:

{
    "slide": 5,
    "slide_title": "Results",
    "notes": "Reference the chart. This slide auto-advances in 5 seconds.",
    "notes_has_timing": True,
    "notes_mentions_visuals": True,
    "notes_word_count": 18,
}

Magical UI integration: When user navigates to a slide with speaker notes, Quill announces:

“Slide 5 of 15: Results. Speaker notes mention slide visuals and timing. Notes say: ‘Reference the chart. This slide auto-advances in 5 seconds.’”

5.3c.6 Animations and Timing Detection with WCAG Analysis

Animations are detected, categorized, and intelligently reported using WCAG timing analysis:

• Slide-level auto-advance timing (WCAG 2.2.1): < 3 seconds flagged as violation
• Shape-level animations: entrance, exit, click-triggered animations categorized
• Animation impact: content appearing on click is flagged as potentially hidden

Example output:

⏱ Animation Timing Analysis:
  • Title: "Fade in" (0.5s, starts with slide)
  • Content: "Fly in" (1.0s, appears on click)

🎯 Accessibility Notes:
  → Title auto-animates, so screen reader reads immediately
  → Content requires manual click to reveal
  → Quill has extracted ALL text; no content lost
  ⚠ Warning: Slide 3 auto-advances in 2.5s (< 3s WCAG recommendation)

5.3c.7 Slide Title Analysis

Duplicate or missing slide titles break outline navigation. Quill analyzes titles:

• Missing titles: slide has no title shape
• Duplicate titles: same title on multiple slides
• Weak titles: titles that don’t describe slide content

Example diagnostics:

"extraction_diagnostics": {
    "slide_titles": [
        {"slide": 1, "title": "Title Slide", "issue": None},
        {"slide": 5, "title": "[No title]", "issue": "missing"},
        {"slide": 6, "title": "Agenda", "issue": "duplicate", "also_on_slides": [2]},
    ],
}

5.3c.8 Link and Alt-Text Quality Analysis

Quill checks for accessibility patterns in hyperlinks and alt text:

• Bad link text: “click here”, “here”, “link”, “more”
• Bare URLs: raw URLs used as link text instead of descriptive text
• Missing alt text: images and charts without descriptions
• Filename alt text: alt text that’s just the image filename (unhelpful)

5.3c.9 Chart and Visual Content Analysis

Quill detects charts, SmartArt, and images. For charts:

• Extracts chart type (column, line, pie, etc.)
• Extracts chart title and axis labels from XML
• Checks for alt text describing the chart
• Attempts to infer data values from label positions (with caution warnings)

5.3c.10 Extraction Quality Diagnostics (Comprehensive Scoring)

Instead of simple text-density scoring, Quill implements findings-based quality scoring:

Quality scoring system:

• Baseline: 100 points
• Per-finding penalties (e.g., missing alt text: -5, auto-advance < 3s: -8, duplicate title: -3)
• Bonuses for best practices (speaker notes on >80% of slides: +2, correct reading order: +1)

Example breakdown:

Quality Score: 78/100

Baseline:                                          100
-5 (Images without alt text)                        -5
-5 (Chart without alt text)                         -5
-8 (Slide 3: Auto-advance 2.5s < 3s WCAG)          -8
-3 (Duplicate title)                                -3
+1 (Reading order verified)                         +1
___________________________________________
Quality:                                            78

In-app quality dashboard:

📊 PowerPoint Presentation Opened
Quality Score: 78/100

Extraction Summary:
  • 15 slides extracted
  • 12 slides have speaker notes
  • 5 animations detected
  • 8 images (5 with alt text, 3 missing)
  • 3 charts (1 with alt text, 2 missing)

⚠ Issues Found (3):
  1. Slide 3: Auto-advance too fast (2.5s < 3s) - WCAG 2.2.1
  2. Slides 2, 6: Duplicate title "Agenda"
  3. 3 images without alt text

✓ All text extracted successfully (no content lost)

5.3c.11 User-Facing Messaging

When opening a .pptx or .ppt file, Quill displays:

📊 PowerPoint Presentation Opened
This presentation has been converted to plain text for editing in Quill.
• Slide structure, formatting, and animations are not preserved.
• Text boxes and shapes have been simplified to plain text.
• Images, charts, and embedded media have been replaced with captions only.
• Speaker notes are available (12 slides have notes).
• If you need the original presentation, open this file in PowerPoint.

Original file: Z:\documents\Q2-review.pptx
Engine: Pandoc 3.1.0 | Slides: 15 | Quality score: 82/100

[📖 View notes]  [💾 Save as .txt]  [📖 Learn more]

Where Am I enhancement: When cursor is at document start, Ctrl+Alt+W announces:

“PowerPoint presentation. Title: Q2 Review. 15 slides, 5,847 words. Speaker notes on 12 slides. Extracted by Pandoc 3.1.0. Quality: 82 out of 100.”

5.3c.12 Editable Rendering, Protected Original

Presentations follow Quill’s principle: originals are read-only by default.

• Extracted text is presented in the standard editor
• Ctrl+S opens Save As so original .pptx cannot be overwritten
• Save dialog offers: .txt, .md (Markdown), .html, new .pptx, or All Files
• Before saving to .pptx, warning appears: “Saving as plain text. Original slide structure will be lost. Continue?”

5.3c.13 Metadata and Extraction Diagnostics

Extracted metadata stored in Document.source_metadata:

source_metadata = {
    "source_kind": "powerpoint",
    "format": "pptx",  # or "ppt"
    "engine": "pandoc",
    "quality_score": 82,  # 0–100 (findings-based)
    "powerpoint_metadata": {
        "title": "Q2 Review",
        "author": "Jane Doe",
        "subject": "Quarterly Business Review",
        "created": "2026-02-15T10:30:00Z",
        "modified": "2026-05-28T14:22:00Z",
        "slide_count": 15,
        "speaker_notes_count": 12,
    },
    "extraction_diagnostics": {
        "total_slides": 15,
        "slides_with_speaker_notes": 12,
        "animations_detected": 5,
        "auto_advance_violations": 1,  # < 3s
        "images_detected": 8,
        "charts_detected": 3,
        "reading_order_mismatches": 1,
        "findings": [
            {"type": "auto_advance_fast", "slide": 3, "timing_ms": 2500},
            {"type": "duplicate_title", "slides": [2, 6], "title": "Agenda"},
        ],
    },
}

5.3c.14 Testing Strategy

Test corpus (stored in tests/fixtures/powerpoint/):

Unit tests (tests/unit/io/test_powerpoint.py):

def test_read_pptx_simple():
    doc = read_powerpoint_presentation(Path("tests/fixtures/powerpoint/simple_title_slide.pptx"))
    assert "Slide 1" in doc.text
    assert doc.source_metadata["quality_score"] > 80


def test_speaker_notes_extracted():
    doc = read_powerpoint_presentation(Path("tests/fixtures/powerpoint/with_speaker_notes.pptx"))
    assert len(doc.source_metadata["speaker_notes"]) > 0


def test_animations_detected():
    doc = read_powerpoint_presentation(Path("tests/fixtures/powerpoint/with_animations.pptx"))
    assert doc.source_metadata["extraction_diagnostics"]["animations_detected"] > 0

5.3c.15 Safety and Security

• ✅ Sandbox execution: Pandoc runs in subprocess
• ✅ Resource limits: Timeout (60s), memory monitoring
• ✅ No code execution: VBA macros NOT executed
• ✅ Fallback chain: Pandoc → python-pptx → plaintext
• ✅ User consent: Warning before overwriting original

5.3c.16 Success Criteria

1. ✅ Functional: Users open .pptx/.ppt, extract text readable with screen readers, speaker notes accessible
2. ✅ Safe: No crashes on corrupted/malicious files, VBA not executed, user warned before data loss
3. ✅ Discoverable: File > Open shows .pptx/.ppt as supported, in-app banner explains changes
4. ✅ Tested: 10+ real presentations tested, unit/integration/a11y tests passing
5. ✅ Documented: User docs explain what is and is not supported

5.3c.17 Future Enhancements (Post-v1.0)

• Async extraction: Large presentations extract in background without blocking UI
• OCR images: Option to OCR images in presentations (local Tesseract or cloud service)
• Handout export: Linearized slides + speaker notes as single document
• Presentation outline navigator: Slide titles as expandable tree with speaker notes
• Batch conversion: “Convert 10 presentations to Markdown”
• Plugin API: Allow plugins to register custom presentation extraction filters
• MarkItDown fallback: Use Microsoft’s MarkItDown for improved extraction before Pandoc
• Chart extraction: Better chart data extraction (tables from visual charts via OCR)

5.4 Excel and CSV support (XLSX / XLS / CSV)

This section specifies Quill’s support for tabular data formats: Excel workbooks (.xlsx, .xls) and CSV files (.csv, .tsv). The design prioritizes accessible grid-based editing mode as an alternative to traditional spreadsheet UIs, with keyboard-first navigation and accessibility-aware data quality analysis.

5.4.1 Design Philosophy: Accessible Grid, Not Spreadsheet

Traditional spreadsheets (Excel, LibreOffice Calc) are visual-first and mouse-oriented. Quill reimagines grid editing for keyboard and screen-reader users:

• Linear keyboard navigation: Arrow keys move through cells top-to-bottom, left-to-right
• F2 cell editing: Edit mode restricted to cell content only; cursor never leaves the cell
• Status bar context: “Row 5, Column C (Sales): $75,000” announced before user types
• Accessible sorting/filtering: Shift+F10 or right-click to sort columns ascending/descending, filter by value
• No visual formatting preserved: Bold, colors, borders intentionally dropped (edit field is sacred)
• All transformations in plain-text mode: Pivot tables, transpose, statistics available without leaving CSV Mode

5.4.2 Scope: CSV Mode as Universal Tabular Editor

CSV files (native support):

• Open directly in CSV Mode
• Auto-detect delimiters (comma, semicolon, tab, pipe)
• Auto-detect column types (text, integer, float, date, currency, boolean)
• User can toggle first row as column headers
• Full grid editing capabilities (add/delete rows/columns, sort, filter)
• Save back to CSV (or export to Excel, TSV, JSON, SQL, HTML, Markdown)

Excel files (.xlsx / .xls) - via MarkItDown bridge:

• Detect format on open
• Auto-convert to CSV using MarkItDown (primary) or openpyxl (fallback)
• Multi-sheet support: user prompted to load sheet, combine all, or create separate documents
• All CSV Mode features work on converted Excel data
• Save options: back to CSV, new Excel file, or export to original Excel format
• Legacy .xls (binary) support via openpyxl fallback

Why CSV as universal format:

• Plain-text, version-control friendly, universally accessible
• No hidden metadata, macro viruses, or formatting complexity
• MarkItDown converts any table → CSV automatically
• Screen-reader friendly; structure is explicit (headers, rows, columns)
• Easy to validate, transform, and audit

5.4.3 CSV Mode UI and Keyboard Shortcuts

Status bar in CSV Mode shows:

📊 CSV Mode (15 rows × 4 columns) | Headers: ✓ | Delimiter: Comma

Navigation (arrow keys):

• Arrow keys: Move to adjacent cell (up/down/left/right)
• Ctrl+Home: Go to cell A1 (first cell)
• Ctrl+End: Go to last cell with data
• Ctrl+Right/Left: Jump to next/previous non-empty cell in row
• Ctrl+Down/Up: Jump to next/previous non-empty cell in column
• Page Up / Page Down: Move up/down by 10 rows

Cell editing (F2 mode):

• Press F2 to enter edit mode for current cell
• Cursor restricted to cell content only; cannot move to adjacent cells
• Backspace/Delete/Ctrl+A work as expected within the cell
• Escape cancels edit without saving
• Enter commits and moves to next row
• Shift+Enter commits and moves to previous row

Sorting and filtering (Shift+F10 / Right-click):

• Shift+F10 or right-click to open column context menu
  • “Sort Ascending” (A→Z, 0→9, empty at bottom)
  • “Sort Descending” (Z→A, 9→0, empty at top)
  • “Move Column Left / Right”
  • “Delete Column / Insert Column”
  • “Filter by Value” (if headers present)
• Ctrl+Shift+L: Toggle filter row (when headers present)

Selection (Shift+arrows):

• Shift+Arrow keys: Extend selection to adjacent cells
• Shift+Spacebar: Select entire row
• Ctrl+A: Select all cells

5.4.4 Transformational Features (Data Quality Analysis)

Quick stats (Ctrl+Alt+S): When a numeric column is selected, Ctrl+Alt+S opens statistics panel showing Sum, Average, Median, Min, Max, Standard Deviation.

Data validation and quality (Ctrl+Alt+V): Findings-based approach: detect empty cells, duplicates, type mismatches, outliers, inconsistent formatting with quality score and auto-fix suggestions.

Pivot table (Ctrl+Alt+P): Group by column with aggregation (Sum, Average, Count, Min, Max).

Transpose (Ctrl+Alt+T): Flip rows and columns.

Find and replace with regex (Ctrl+H): Full regex support with capture groups.

Concatenate / Split columns (Ctrl+Alt+C / Ctrl+Alt+X): Combine or split columns by delimiter.

Unique values (Ctrl+Alt+U): Extract distinct values and create new sheet or copy to clipboard.

Conditional formatting as comments (Ctrl+Alt+F): Mark cells based on conditions (e.g., “Salary > $90,000” adds comment).

5.4.5 Multi-Sheet Excel Support

When opening Excel files with multiple sheets, user is prompted to load sheet, combine all, or create separate documents. Sheet navigation via Ctrl+Page Down/Up.

5.4.6 Format Detection (Type Inference)

When opening CSV or Excel files, Quill auto-detects column types (Text, Integer, Float, Date, Boolean, Currency), date format, currency symbols, encoding, and delimiters with quality assessment.

5.4.7 Save and Export Options

Users can save to CSV, TSV, Pipe-delimited, Excel (.xlsx), JSON, HTML table, Markdown table, or SQL INSERT statements with accessibility options (include column types, freeze headers, set widths).

5.4.8 MarkItDown Integration for Universal Format Conversion

Quill uses Microsoft’s MarkItDown library as a Tier 1 converter for Excel files, PDF tables, and web tables, converting all tabular formats to CSV for consistent editing.

5.4.9 Data Quality and Accessibility Patterns

Built-in audits for column type consistency, dataset completeness, duplicate detection, and outlier analysis with actionable suggestions.

5.4.10 Testing Strategy

Comprehensive test corpus including simple CSV, headers, mixed types, large files (10k rows), special characters, sparse data, malformed CSV, multi-sheet Excel, formulas, and legacy .xls files. Unit, integration, a11y, and performance tests all included.

5.4.11 Safety and Security

• ✅ Formula injection prevention: CSV exports escape Excel formula indicators
• ✅ Encoding safety: Detects and preserves UTF-8, UTF-16, ANSI
• ✅ Macro safety: Excel macros NOT extracted or executed
• ✅ Large file handling: Warn if CSV > 50MB; streaming mode available
• ✅ Local-only processing: No network access

5.4.12 Success Criteria

1. ✅ Functional: Users open CSV/Excel in accessible CSV Mode; grid navigation, sorting, filtering, transformations work
2. ✅ Accessible: Screen readers announce cell position/type/content; all operations keyboard-available
3. ✅ Magical: Quick stats, data quality audits, pivot tables, format conversion seamless
4. ✅ Safe: No formula injection; large files handled gracefully; macros never executed
5. ✅ Tested: Unit, integration, a11y, performance tests passing

5.4.13 Future Enhancements (Post-v1.0)

• Inline formulas: Support Excel-like formulas (SUM, AVERAGE, IF) in CSV cells
• Data source connections: Live links to external CSV/Excel for refresh
• Advanced pivot UI: Keyboard-accessible pivot table builder
• Chart generation: Text-based charts from CSV data
• Database import: Import from SQL, JSON, APIs
• VLOOKUP / INDEX-MATCH: Lookup functions for multi-sheet joins
• Macro recording: Record/replay keyboard sequences
• Data sanitization tools: Trim spaces, standardize dates, fix typos

5.4.14 Table Studio — the accessible grid (shipped, experimental)

Goal. One genuinely usable, screen-reader-first surface for building and editing tables by ear — the accessible grid the CSV/tabular story above needs — so a blind user can create a table, or open a CSV, and navigate it cell by cell with the column spoken as they cross a row.

One surface, two entry points. Tools > Table Studio starts a new table; Tools > Open CSV in Table Studio (and, when the feature is enabled, opening a .csv/.tsv from File > Open in grid view) loads a file into the same grid. This consolidates what were two grid implementations into one: the legacy CsvGridSurface remains only as the fallback when Table Studio is disabled.

Architecture. A wx-free core (quill/core/table_studio/) owns the data — a format-neutral TableDocumentModel (cells/rows/columns, listeners, Markdown + HTML serialization), a TableController with a SpokenCellFormatter (Concise / Standard / Detailed profiles, JAWS-style “changed header” announcing), and CSV I/O with delimiter auto-detection. The UI (quill/ui/table_studio.py) renders it on a virtual wx.ListCtrl (SysListView32) with a row-indexed MSAA provider so NVDA/JAWS speak the active column; an optional compiled native UIA provider (quill/native/table_uia/, pybind11 → _quill_table_uia.pyd, staged into Windows builds when the toolchain is present) supplies richer cell-level focus/value/structure events, with the MSAA path as a transparent fallback.

Interaction. Arrow keys move by cell (Left/Right speak the column); Home/End, Ctrl+Home/End, Page Up/Down navigate; F2/Enter edit; Alt+arrows move a row or column; Ctrl+Insert adds a row; Delete clears a cell. A context menu (Shift+F10 / Applications key / right-click) exposes every action: Sort Ascending/Descending (numeric-aware, blanks last), Insert/Delete/Move rows, Insert/Delete columns, Rename Column Header, Promote First Row to Header (for a CSV whose header row was read as data), and Use First Column as Row Headers. All the same actions are also on buttons.

Industry-standard markup. Column and row headers are stored and exported the standard way — <th scope="col"> / <th scope="row"> in HTML and a proper header row (with alignment markers) in Markdown — so the structure round-trips and is legible to assistive technology and downstream tools. Finish by inserting the table into the document as Markdown or HTML, or Save to CSV to write it back to a file (a full round trip for an opened CSV).

Gating & safety. Experimental opt-in behind table_studio_experimental_enabled (Preferences > Experimental), which follows the Experimental master switch; the menu items appear only when it is on. No network, no external process; the native provider is a pure enhancement that never blocks a build or a run.

5.5 PDF handling in v1.0

This section is the canonical, scoped statement of what Quill 1.0 does with PDF files. Anything not listed here is explicitly out of scope for v1.0 and tracked in the backlog (section 17).

What v1.0 ships

1. Tier 1, local extraction (automatic on open). A layered pipeline runs pdfplumber and pypdfium2 (with pdfminer.six as a third fallback) per page, scores each extraction for readability (line count, alphabetic ratio, average line length, presence of suspicious one-word-per-line patterns), and picks the best result per page. Pages are concatenated with explicit page markers so page navigation is exact.
2. Page navigation. Page Up / Page Down move to the previous/next page marker. Ctrl+G opens Go To Page when page markers exist. The status bar’s Page cell shows Page n of m. Reaching the first or last page is announced.
3. Embedded bookmarks (shipped). On open, a PDF’s embedded outline (Adobe’s bookmark tree) is imported into Quill’s own bookmark store so its entries appear in the Bookmarks Manager (Ctrl+Shift+G). io/pdf.py::extract_pdf_outline flattens pypdf’s outline tree to (title, page) pairs; _format_pdf carries them in source_metadata["pdf_outline"]; and main_frame.py::_import_pdf_outline_bookmarks resolves each destination page to a character offset (via the form-feed page markers, the same mapping “Go To Page” uses) and adds a bookmark. Import runs once, on first open — it is skipped when the document already has bookmarks, so it never duplicates entries or resurrects deleted ones. They are read-only with respect to the original PDF; renaming, adding, and deleting affect Quill’s own bookmark store.
4. Password-protected PDFs (shipped). On open, Quill detects an encrypted (real user-password) PDF and prompts for the password through a standard modal dialog (wx.PasswordEntryDialog via _show_modal_dialog). The entered password is threaded through the read path (read_open_document → read_structured_document → extract_pdf_text(path, password=…)) to both extractors — pdfplumber.open(..., password=…) and pypdf’s reader.decrypt(…) — and the read runs off the UI thread like every other office/PDF open. A wrong password re-prompts (“that password did not open …”); Cancel aborts the open. The password is used in-memory only and is never written to disk, never logged, never sent over the network — reopening the file prompts again. Permissions-only “encrypted” PDFs (empty user password) open with no prompt. (io/pdf.py, io/structured.py, io/open_read.py, ui/main_frame.py::_ask_pdf_password.)
5. Editable rendering, protected original. The extracted text is presented in the standard editor. Ctrl+S opens Save As so the original .pdf cannot be overwritten by extracted text. The Save dialog offers Text, Markdown, HTML, and All Files.
6. Document metadata. Author, title, subject, keywords, creation date, modification date, and page count are accessible via File > Document Properties… and announced in Where Am I when the document is a PDF.
7. PDF document statistics. Document Statistics (5.19) reports page count, image count per page (informational), tagged-structure presence, and language metadata.
8. Accessibility audit, informational. The Accessibility Audit (5.20) reports whether the PDF has tagged structure, whether it has embedded bookmarks, the image-only page count, language metadata, and password protection state. It does not modify the PDF.
9. Tier 3, AI-assisted reading order (opt-in, manual) — shipped. AI > More > Improve Reading Order… (also on the command palette) sends the current document’s text to the user-configured LLM provider (the user supplies the API key; nothing is bundled) to repair a jumbled reading order — multi-column PDFs, sidebars/text boxes, out-of-sequence lines. The action always asks for confirmation before sending, naming the provider and its host plus the approximate page size, and reports the outcome on the status line. It refuses, with a clear spoken message, if the document exceeds the configured page-count limit (settings.reading_order_max_pages, default 40), and is disabled in Safe Mode. Results open as a new unsaved document whose Save defaults to Save As; the original is never changed. (core/ai/assistant.py reading_order operation, ui/main_frame_ai_reading_order.py.)
10. OCR for scanned PDFs. When tier 1 yields no readable text on a page, Quill offers a one-click escalation to local OCR via the bundled Tesseract (English shipped, additional languages downloadable). For longer scanned PDFs the user may instead escalate to tier 3 AI rendering.
11. Selection and copy. Standard selection works in the extracted text. Ctrl+C copies as plain text. There is no copy-with-formatting target in v1.0 (the extracted text has none).
12. Find, Outline, Bookmarks, Word Count, Document Statistics, Read Aloud, Accessibility Audit all work over the extracted text exactly as they do for any other document.
13. Compare (Tools > Compare With File…) works against the extracted text representation; comparing two PDFs compares their extracted plain-text forms.

What v1.0 does not ship (deferred to backlog)

• Tier 2 “enhanced local” extractor. No pure-Python local layout analyser meets the v1.0 quality bar. v1.0 has tier 1 and tier 3 only.
• Heading synthesis from font-size analysis when no embedded bookmarks exist. Off by default; available as an opt-in experimental switch in Advanced settings, clearly labelled as experimental.
• PDF form filling and signing. Not in v1.0.
• Writing back to PDF (annotation, highlight, comment). Not in v1.0; original PDF is read-only by design.
• Embedded media (audio, video, 3D, attachments inside the PDF). Not in v1.0.
• XFA forms. Not in v1.0.
• Tagged-structure tree editor. Reading the structure summary is in; editing it is backlog.

5.6 Improve reading order (shipped)

A general action under the AI menu (AI > More > Improve Reading Order…) and the command palette:

• Text-layer repair (shipped). Sends the current document’s text to the configured LLM for reading-order repair — reordering columns and out-of-sequence text, merging columns into one flow, joining lines broken mid-sentence, and inferring headings/lists/tables — via the assistant’s reading_order operation. Works for any text document (extracted PDF, Markdown, plain text, HTML source).
• Service is the user’s own AI backend — nothing bundled or vendor-locked. The command routes through the standard assistant seam (Assistant.transform → make_default_backend), so it uses whatever the user configured in AI Setup: OpenAI, Claude, Google Gemini, OpenRouter, Ollama (local), Ollama Cloud, or a custom OpenAI-compatible endpoint (bring-your-own-key). With no cloud provider configured it falls back to the bundled on-device model (Apple Foundation Models on macOS; llama.cpp CPU elsewhere), so the repair can run fully offline with no upload. It inherits every provider QUILL supports for free and requires no reading-order-specific provider code.
• Always asks first, naming the provider + host + approximate size; disabled in Safe Mode; refuses over the page limit (default 40). Never used to answer questions about the document.
• Result opens as a new unsaved document; Save defaults to Save As. The original document is untouched.
• Follow-up (not yet shipped): sending the original binary file (PDF/legacy DOC/PPTX) so the model can analyse visual text boxes and columns from the raw layout. This depends on file-upload/vision support that is not uniform across the configured providers, so the shipped command operates on the extracted text layer, which closes the common “text layer in the wrong order” case.

5.7 HTML and Markdown

• HTML files open as plain text in the editor.
• File > Preview as HTML writes a temporary HTML file and opens the default browser.
• Markdown files open as plain text.
• File > Preview Markdown as HTML renders via markdown-it-py and opens the browser.
• File > Export Markdown as HTML saves a standalone HTML file.
• File > Export Markdown as Word produces a .docx via python-docx, preserving headings, lists, links, tables, code blocks.

5.8 Find and replace

Find in Quill is designed to feel like Microsoft editors and Visual Studio Code at the same time: F3 just works once a term is known, the search term is remembered everywhere it makes sense, and everything is announced.

The search term, the central concept. Quill maintains a single “current search term” per editor. The term is set by any of:

• typing in the Find dialog and pressing Enter,
• pressing Ctrl+F3 with a selection (the selection becomes the search term),
• pressing Ctrl+F3 with no selection (the word under the cursor becomes the search term),
• restoring it from session storage on launch (when enabled),
• arrow-selecting a previous term from the Find dialog’s history dropdown.

The status bar’s Search term cell (5.1b) displays the current search term and its options. Enter on the cell reopens Find pre-filled.

Keystrokes

• Ctrl+F opens Find. Pressing Enter searches forward, sets the search term, selects the match, and announces Found on line 12: <line text>.
• Ctrl+Shift+F opens Find anchored to backwards search.
• F3 advances to the next occurrence of the current search term without opening any dialog. If no term is set, F3 opens Find with focus in the input. If a term is set, F3 simply selects the next match and announces line + context. At end of document, search wraps to the start (announced as “Wrapped to top”).
• Shift+F3 does the same in reverse, wrapping at the start to the end (“Wrapped to bottom”).
• Ctrl+F3 sets the current word or selection as the search term and advances. Ctrl+Shift+F3 sets it and retreats. This is the Visual Studio convention.
• Alt+F3 opens Find All: a list of every match with line number and context line, in a stock wx.ListBox. Enter jumps to a match; the dialog stays open so the user can iterate. The cell at the bottom shows Match 3 of 17.
• Ctrl+H opens Replace. Options: case sensitive, whole word, regex, in selection (pre-checked when a selection is present on open). Replace, Replace All, Find Next, Find Previous buttons. Replace All reports Replaced 12 occurrences. Undo is one step.
• Esc from any Find or Replace dialog closes it and returns focus to the editor at the previous cursor position (not at the last match unless the user pressed Enter).
• “Not found” is always spoken, never silent. After two consecutive not-found beeps, Quill suggests opening Find All to verify the term.

History and persistence

• Find and Replace remember the last 20 terms per session (in-memory) and the last 100 across sessions (on-disk, in %APPDATA%\Quill\search-history.json; cleared from a single button in Settings → Privacy). Replacement strings have their own parallel history.
• The dropdown arrow on the Find input opens history; Up/Down arrows in the input cycle through history when the input is empty.

Incremental preview (opt-in, off by default)

• A Settings switch Editing → Incremental Find Preview makes the editor preview the next match as the user types in the Find dialog (Notepad++ style). Escape returns the cursor to where it was before Find opened. Enter commits and closes. Off by default because preview-driven cursor movement can confuse screen readers; we expose it for users who prefer it.

Predictable announcements

• On every match Quill announces a structured one-liner: Found on line N: <line text>. The line text is truncated to 200 characters with an ellipsis to keep speech short. Long lines are abbreviated around the match so the matched text is always in the spoken slice.
• On wrap: Wrapped to top or Wrapped to bottom, followed by the match announcement.
• On Replace All: Replaced N occurrences in document or Replaced N occurrences in selection.
• On regex error: a single sentence, no traceback.

Find in current selection. When the editor has a non-empty selection at the moment Find or Replace is opened, the “In selection” checkbox is pre-checked; Replace All scopes its work to the selection. F3 and Shift+F3 continue to operate document-wide regardless, because muscle memory expects that.

Find next while typing. When the Find dialog is closed and the search term is set, typing in the editor does not interfere with F3; the search term is preserved until the user clears it (Ctrl+Shift+\ or status-bar cell context menu → Clear Search).

Project-wide Find (Find in Folder) is deferred to v1.2.

5.9 Spell checking (local-first, guided F7 review)

This section was significantly expanded in v0.2 of this PRD. See section 6 for the full architecture and decision rationale, and §6.4 for the complete F7 dialog specification.

QUILL ships its own spell checking engine, built on Hunspell dictionaries, designed from the ground up for screen-reader speed and predictability. It does not depend on TinySpell or any other external spell-checker process.

• F7 opens the Spelling Review dialog — a guided, modal, fully keyboard-operable review of every misspelling in the document or active selection. The dialog surfaces each issue inside a readable, navigable, sentence-level context window. See §6.4 for the complete specification. Implemented in 0.7.0 Beta 2.
• Ctrl+F7 / Ctrl+Shift+F7 jump to the next or previous misspelling without leaving the editor.
• Alt+F7 (tools.spell_check_word_at_cursor) — Spell Check Word, shipped 0.9.0 Beta 3. Checks only the word at the caret (or the current selection), with no full-document scan. A correctly spelled word is announced and nothing else happens; a misspelling opens the same suggestions/Add to Dictionary/Ignore choices as the right-click spelling context menu (reusing suggest_words/misspelling_at_position from the spell-check core), in a lightweight wx.SingleChoiceDialog rather than the full Spelling Review dialog. The keyboard equivalent of pressing F7 on a focused word in Microsoft Office.
• Ctrl+Shift+L (tools.misspelling_list_ranked) — Ranked spelling, shipped 0.9.0 Beta 3, community feature request (Kurzweil 1000 parity). Opens the same tree-navigator dialog as the existing document-order tools.misspelling_list (Alt+Shift+L), but ordered by rank_misspellings_by_frequency() (new, pure, in core/spellcheck.py): most-recurring word first, case-insensitive grouping, ties broken by first-occurrence position for a stable/reproducible order. Each entry’s label includes its occurrence count (_build_misspelling_navigator_nodes(..., show_counts=True)). Rationale: a single OCR misread or repeated typo often accounts for the bulk of a long misspelling list, so fixing the most-frequent entry first clears the most ground fastest. Pure reordering — every occurrence still appears in the result, nothing is deduplicated or hidden.
• Alt+Shift+F7 (tools.spell_check_ranked) — Ranked Spelling Review, shipped 0.9.0 Beta 3, same community request. The other half of ranked spelling: the full guided F7 workflow (Change/Change All/Ignore/Ignore All/Add to Dictionary/Undo, SpellingReviewDialog/ReviewSession), not just a jump-to-occurrence list, walked in ranked order. ReviewSession gained a ranked: bool constructor flag; _rescan() (called after every action) re-applies rank_misspellings_by_frequency() and, in ranked mode, always resets to the freshly-ranked list’s top entry rather than “next by position” — so as Change All clears the current top offender, the next-most-frequent word rises to the front automatically instead of the ranking going stale mid-session. open_spell_check_dialog/spell_check_ranked share one _open_spelling_review(ranked=...) implementation in MainFrame.
• As-you-type checking is on by default. Misspellings are tracked in a sidecar model (not visual squiggles) and announced gently on word boundary if the user opts in. Shipped 1.0.0: the live alert is an earcon (SoundEvent.SPELLING_ALERT, toggleable in Sound Events, system-bell fallback when the active pack lacks the sound) rather than speech, so it never interrupts the screen reader mid-sentence; and it is suppressed inside URLs, email addresses, Markdown inline code spans, and fenced code blocks (core/spellcheck_live.py live_alert_suppressed — those regions are wall-to-wall false positives that a sighted user filters visually, so the checker filters them for everyone).
• Suggestions come from Hunspell plus an n-gram reranker trained on the user’s writing for personalised top suggestions.
• Personal dictionary persists per user; per-document dictionary persists in a sidecar file.
• Multiple simultaneous dictionaries: e.g. English (UK) plus a technical jargon list plus the document’s own dictionary, merged with priority.
• All entirely local. No cloud round-trip ever for spell check.

5.10 Word count and navigation

• Ctrl+Shift+W reports words, characters, and paragraphs. Reports on selection if present.
• Page Up / Page Down navigate by real page markers (PDF). Announces page on move.
• Ctrl+G opens Go To Line, or Go To Page when page markers exist.

5.10 Bookmarks

• Bookmarks are named jump points intended for durable anchors a user wants to revisit by name.
• Ctrl+B sets a bookmark at the current position. Prompts for a name.
• Stored per bookmark: name, line number, column, ~120 characters of surrounding text, document path, ISO timestamp.
• Ctrl+Shift+G opens Bookmarks Manager.
• On jump: if the stored line still contains the surrounding text, go there. If not, search for the surrounding text and update the bookmark. If still not found, fall back to line number and announce “approximate position.”
• Bookmarks for saved documents persist in %APPDATA%\Quill\bookmarks\<hash>.json.

Note: the section above predates the shipped implementation and describes an earlier design (Ctrl+B, surrounding-text fuzzy resolution); the as-shipped named-bookmark commands (navigate.set_bookmark/go_to_bookmark/list_bookmarks, default Alt+Shift+B for List Bookmarks) live in quill/core/bookmarks.py and MainFrame, storing name→position pairs per document via DocumentMemory. Reconciling this section with the shipped design is a separate follow-up; the two additions below are accurate as of 0.9.0 Beta 3.

Temporary bookmark — shipped 0.9.0 Beta 3; re-registered 1.0.0 (#1317). A single unnamed, one-shot jump point, distinct from named bookmarks: Set Temporary Bookmark (navigate.set_temp_bookmark, Ctrl+J) sets it at the cursor with no dialog; Go to Temporary Bookmark (navigate.go_to_temp_bookmark, Ctrl+Shift+J) jumps to it with no picker. Both live in the Navigate > Bookmarks submenu (immediately after List Bookmarks) and the command palette. Session-only by design (never written to DocumentMemory) — it is disposable scratch state, not a durable anchor; it stores a raw caret position and does not re-anchor to surrounding text the way persistent bookmarks do. Implemented as MainFrame.set_temp_bookmark/go_to_temp_bookmark, aliased per-tab exactly like the named-bookmark dict. The handlers shipped in 0.9.0 Beta 3 but lost their registration when their historical chords were reassigned — Ctrl+Shift+K to Unquote Lines (edit.unquote_lines, #608) and Alt+Shift+K to Keep Unique Lines (power.keep_unique_lines, §4.22) — leaving the feature unreachable from the UI; 1.0.0 restores the command ids, keymap entries, menu items, palette labels, and F1 topics on the previously-unbound Ctrl+J / Ctrl+Shift+J.

Numbered quick bookmarks — shipped 0.9.0 Beta 3. Ten fixed slots (0-9). The original design (see the now-superseded PRD draft in x.md) proposed routing set/jump through Quick Nav’s “press a letter, then a qualifier” grammar; direct user feedback during review asked for one-keystroke access with no sub-mode, so the shipped implementation instead intercepts Alt+Shift+<digit> (set) and Ctrl+Alt+Shift+<digit> (jump) directly in MainFrame._on_char_hook, alongside the existing frame-level Ctrl+K/Ctrl+W handling — the declarative keymap table has no “any digit” wildcard, so these 20 chords are intercepted rather than declared. Deliberately not a parallel storage system: quick_slot_name(slot) in core/bookmarks.py generates a reserved name ("Quick 3") that reuses the existing named-bookmark store, so numbered bookmarks get persistence, save/load, and crash-safety for free rather than needing a new DocumentMemory schema field.

Favorite folders — shipped 0.9.0 Beta 3, community feature request. A short, user-curated list of folders (quill/core/favorite_folders.py, wx-free, modeled on BookmarkVault), distinct from Windows’ recency-based recent-folders. Ctrl+Alt+Shift+A/Ctrl+Alt+Shift+R add/remove the current document’s folder; Ctrl+Alt+Shift+O opens Open From Favorite Folder — a VSCode-Quick-Open-style type-to-filter dialog (list_files_in_favorites/filter_favorite_files, both pure and unit-tested) scanning every favorite folder’s top-level files (non-recursive by design, to keep the filter instant) and matching by case-insensitive filename substring. Quill has no single-project-root “workspace” concept to scan the way VSCode does, so this is intentionally scoped to the curated favorites list rather than the whole disk.

5.11 Selection helpers and Where Am I

• Ctrl+Shift+, marks selection anchor; Ctrl+Shift+. extends selection.
• Ctrl+Shift+I Where Am I. In the editor: line, column, word count, modified state, page if available. In dialogs: structured description of the current field.

5.12 Command palette (Visual Studio Code style)

This is a centrepiece of v0.2. See section 7 for the complete design.

• Single shortcut: Ctrl+Shift+P (also F1).
• Prefix-driven modes inside one input field, exactly like VS Code:
  • No prefix: command search.
  • > explicit command prefix (typing it is optional; a fresh palette starts in command mode).
  • ? shows help for available prefixes.
  • : go to line.
  • @ go to bookmark in current document.
  • # go to bookmark across all open documents.
  • ! show warnings and errors (spell check issues, broken bookmarks, unsupported features used).
  • < open a recent file.
  • ~ switch open document.
  • = open a setting.
• Fuzzy matching with subsequence scoring, recency boost, and frequency boost (most-recently-used commands float to the top).
• Search shape (shipped 1.0.0): multi-word queries are order-independent AND matches over title + id + shortcut + aliases (url open and open url both find Open From URL…); a curated intent-alias table (core/palette.py COMMAND_ALIASES) maps the words users actually think of (settings, quit, theme) to the commands they mean; and the shortcut text itself is searchable. Result navigation speaks the command’s shortcut with its title — the palette teaches the keystroke while it dispatches, for screen-reader users exactly as the visual Title [binding] label does for sighted users.
• Toggle state rides in the title (shipped 1.0.1, #1383). The palette lists Command.title verbatim and has no checkmark column, so a toggle registered once reads identically whichever way it is currently set — the one fact the user opened the palette to learn. Every boolean command therefore carries (currently On) / (currently Off), stamped by _refresh_palette_toggle_titles immediately before the palette is built (quill/ui/main_frame_palette_labels.py), so no individual handler has to remember to retitle itself. Reported for Internet Radio’s Announce Track Titles; generalised to soft wrap, dark mode, find wrap, the tab control, persistent undo, spell check as you type, word prediction, overwrite mode, extend-selection mode, tab insert mode, and abbreviation expansion.
• Each row shows: command title, current keybinding, source (core or plugin), and a short hint.
• Right-arrow on a command edits its keybinding inline (see section 8).
• Fully keyboard driven. Standard wx.ListBox underneath, with a wx.SearchCtrl on top. All accessible via stock screen-reader behaviour.

5.13 Document backups

• On every save of an existing file, the previous saved bytes are copied to %APPDATA%\Quill\backups\<hash>\<iso-timestamp>.bak.
• File > Restore Document Backup lists backups for the current document, newest first.
• Restore prompts for confirmation. Before overwriting the editor, the current buffer is backed up too.
• Restored text is marked modified; user saves with Ctrl+S.
• Write contract (shipped 1.0.1, #1390). A backup is written atomically (temp file + os.replace) and always as UTF-8, matching the autosave-snapshot contract in core/autosave.py: an interrupted backup must never be what a user restores, and a document opened in a narrower encoding (a BRF read as ASCII, say) must not make the backup raise the moment the buffer gains an out-of-range character. core.backups.read_backup_text decodes UTF-8 first and falls back to the document’s encoding, so backups written by earlier builds still restore.
• A backup can never abort a save. backup_document is called inside its own guard (_backup_before_save); an OSError degrades to a spoken status line and the save proceeds. This is a correctness requirement, not a nicety: before #1390 the backup call sat outside the save path’s try/except OSError, so a full disk raised out of save_file before the real file was ever touched, the close path’s #210 safety net swallowed it, and QUILL exited with the document unsaved.
• A failed save is never consent to close. _prompt_to_save_active_document catches a raising save_file and returns False; _on_close vetoes once via _veto_close_after_failed_save when a document is still modified, with a message naming the remedy. The veto is one-shot, so #210’s “the window must always close” guarantee still holds even if this path itself has a bug.
• Failure wording (#1390). _report_save_failure gives ENOSPC and the read-only family (EACCES/EPERM/EROFS) their own sentences naming what to do; everything else keeps the errno text. Raw errno strings are not an acceptable user-facing message for a save failure.
• Retention: default keep last 50 per document, prune older than 90 days, never delete the most recent 5.
• Crash recovery: autosave snapshot every 30 seconds while a document is dirty; on launch, Quill offers to recover any orphan snapshots.

5.14 Settings

Ctrl+, opens Settings, organised in a wx.Treebook:

• General, Editing, Reading, Spell check, PDF and AI, Files, Appearance, Backups, Keyboard (see section 8), Privacy.

5.14a Persistence and migration contract

All persisted user state follows one release-to-release contract so upgrades never strand users, hide new defaults, or pin stale ones. Canonical reference: docs/design/persistence-and-migration.md.

• Defaults in code; disk stores only the delta. Each store (settings.json, keymap.json, features.json) persists only the fields the user changed from the code-defined default, plus a schema/epoch version stamp. Consequences: a newly added setting arrives at its default automatically (absent from old files); a changed default reaches every user who did not override that field; user customizations are the only thing written, so they survive verbatim. A full snapshot — the prior settings.json shape (schema_version 1) and the prior keymap.json shape — pinned every field and was the root cause of changed defaults never reaching users; both are now deltas (schema_version 2 / _defaults_epoch 1).
• Migrate-and-back-up on load. A file predating the current schema is rewritten to the canonical delta exactly once; the original is first copied to migration-backups/<store>-v<old>-<timestamp>.json (most-recent-few retained) so the conversion is reversible. Validation is field-by-field: a corrupt value falls back to its default without discarding siblings. Persistence is best-effort (a read-only/locked dir never blocks startup).
• Reusable plumbing. quill/core/versioned_store.py (load_with_migration(path, *, store_name, parse, serialize, is_legacy, default)) encapsulates the load→migrate→backup→resave dance; quill/core/migration_backup.py provides the shared pre-migration backup. A new store supplies four callables; a new schema bump changes serialize/parse and raises the version. Settings serialization lives in quill/core/settings_migration.py.
• Recommended (force-once) updates. When an important default change must reach users who already overrode the field (canonical case: restoring Find to Ctrl+F), quill/core/recommended_updates.py holds a versioned registry of RecommendedKeymapUpdates. Each applies at most once per user — the applied id is recorded in settings.applied_recommended_updates — then the binding is never force-touched again. The whole mechanism is opt-out via settings.apply_recommended_keymap_updates (default on); applied at startup by MainFrame._apply_recommended_keymap_updates() after settings + keymap load.
• Migration notice (surfacing). A rich migration_notice setting (silent / announce / prompt, default announce; Administration group, searchable spec) controls how a migration is surfaced. migration_backup.pop_recent_migrations() reports stores migrated this launch; MainFrame._surface_migration_notice() (a startup task) briefly announces or shows a summary dialog accordingly. Recommended keymap updates are reversible: _apply_recommended_keymap_updates captures the prior bindings, and undo_recommended_keymap_updates() (command tools.undo_recommended_updates, and the prompt’s Undo button) restores them while leaving the update ids marked applied so the change does not re-fire.
• One-time startup maintenance. quill/core/startup_maintenance.py runs epoch-gated, run-once cleanups of regenerable diagnostic clutter (logs/, crash-reports/, diagnostics/) so upgraders from the early beta start clean. It runs in quill.__main__.main() after ensure_app_directories() and before configure_logging() (so clearing logs/ is safe), gated by a startup-maintenance.json marker; it never touches documents, autosaves, backups, recovery, or settings.
• Installer interaction. The Windows installer (scripts/build_windows_distribution.py, [InstallDelete]) cleanly replaces the first-party quill package (and stray __pycache__) on every install to prevent version-skew import crashes, while leaving the embedded runtime, bundled tools, and %APPDATA%\Quill user data untouched — the migration contract above, not an installer wipe, is what keeps config safe across releases.
• Reset surfaces. Each subsystem has a factory reset behind a warning: Settings dialog Reset to Factory Defaults (registry.reset_all), Reset Keymap (reset_keymap), and the Menu Editor reset. A unified Reset Everything to Factory Defaults (tools.reset_all_defaults, MainFrame.reset_all_to_factory_defaults, in Tools → Customize & Support) resets settings + keymap + menu customization + feature profile in one confirmed step; each writes its clean factory delta, and user documents/autosaves/backups/recovery are never touched.

5.15 Plugin system (v1.1)

• Plugins are Python packages discovered in %APPDATA%\Quill\plugins.
• Each plugin can register commands, file format readers and writers, settings pages, palette entries, and default keybindings (which the user can override).
• Plugin manifest must declare network and filesystem use.

5.16 Outline Navigator (heading tree)

One of Quill’s signature productivity wins for readers and writers. Opens a tree of every heading in the current document, fully accessible, and lets the user jump anywhere in two keystrokes.

• Ctrl+Shift+H opens the Outline Navigator. The window contains a filter wx.SearchCtrl, a wx.TreeCtrl of headings, and standard OK/Cancel/Jump buttons. Everything stock; screen readers handle it natively.
• The outline is computed deterministically per format:
  • Markdown: ATX (#) and Setext (===, ---) headings, parsed via markdown-it-py AST.
  • HTML/XHTML/MHTML: <h1>…<h6> and <section><h*> patterns via beautifulsoup4. ARIA role="heading" aria-level="n" is honoured.
  • reStructuredText: title underline conventions via docutils.
  • AsciiDoc: = through ====== lines.
  • Org-mode: * through ****** lines.
  • LaTeX/Typst: \part, \chapter, \section, \subsection, \subsubsection, \paragraph; Typst = heading syntax.
  • DOCX: paragraphs styled Heading 1–9 (via python-docx).
  • EPUB: nav.xhtml first, falling back to toc.ncx.
  • PDF: embedded document bookmarks (the same tree shown in Adobe Reader’s bookmarks pane); also synthesised from font-size analysis when no bookmarks exist (opt-in, off by default).
  • DAISY: navigation document.
  • Subtitle files: chapter markers if present; otherwise time-bucketed sections every five minutes.
  • Jupyter notebooks: each Markdown heading inside Markdown cells, plus a synthetic node per cell.
  • Generic fallback: lines that look like headings (ALL CAPS short lines, numbered sections like 1., 1.1) are offered as a flat list with a warning that the document has no real structure.
• Tree behaviour:
  • Up/Down arrow navigates between headings. Right Arrow expands; Left Arrow collapses. * (numpad or shift+8) expands all descendants of the focused node.
  • Typing in the filter field narrows the visible tree to headings whose text matches (substring, case-insensitive). The first match is announced. Tab returns focus to the tree.
  • Enter jumps the editor to the selected heading, closes the dialog, and announces Jumped to heading level 2: <text>.
  • F2 renames the heading in place (editable formats only) and updates the document.
  • Ctrl+C copies the heading title; Ctrl+Shift+C copies the path (Chapter 3 › Section 2 › Subsection 1).
• The Outline Navigator also lives in the command palette under the # prefix when the current document has structure, so headings appear inline with document switching.
• Targets: build the tree for any text-based document up to 1 MB in under 50 ms; up to 10 MB in under 500 ms.

5.17 Jump-by-structure shortcuts

In-editor navigation by document structure, alongside the Outline dialog:

• Ctrl+PgDn / Ctrl+PgUp: next / previous heading of any level. Announces Heading level 2: <text>.
• Ctrl+Alt+1 through Ctrl+Alt+6: next heading of level 1–6. Ctrl+Alt+Shift+1–6 for previous.
• Ctrl+Alt+0: jump to the next paragraph that is not a heading (useful for skimming).
• Ctrl+] / Ctrl+[: next / previous block boundary (code fence, list, table, blockquote) in Markdown and HTML.
• Ctrl+Alt+B: jump to the start of the current logical block; Ctrl+Alt+E to the end.
• All shortcuts reassignable.

5.18 Line and block operations

VS Code-style editor productivity, all standard text-control operations:

• Move Line Up / Move Line Down (format.move_line_up / format.move_line_down): move the current line (or all selected lines) up or down. Announces the swap.
• Duplicate Line (format.duplicate_line): duplicate the current line or selection.
• Delete Line (format.delete_line): delete the entire current line.
• Select Line (edit.select_line): select the current line (repeat to extend by line).
• Join Lines (format.join_lines): join the current and next line with a single space.
• Tab / Shift+Tab on a multi-line selection: indent or outdent.
• Ctrl+/: toggle line comment using the current document’s comment marker (#, //, <!-- -->, etc.).
• Shift+Alt+A: toggle block comment where supported.

The five line-manipulation commands above ship unbound in the default keymap — every VS Code-style chord this section once claimed for them (Ctrl+Shift+D, Ctrl+Shift+K, Ctrl+L, Ctrl+J) is now spoken for by a different command (format.describe_formatting, edit.unquote_lines, per-pack, and navigate.set_temp_bookmark respectively). They are reachable from the Format menu and the command palette, carry ready-made chords in the Notepad++ and VS Code keyboard packs (quill/core/keymap_packs.py), and can be bound to anything in Preferences > Keyboard Shortcuts.

• Tools menu: Sort Selected Lines (ascending/descending, case-sensitive option, natural-numeric option), Remove Duplicate Lines, Reverse Lines, Trim Trailing Whitespace, Convert Indent (tabs↔︎spaces), Normalize Whitespace, Wrap to Column N.
• Smart list continuation (Markdown, opt-in): pressing Enter on a -, *, or 1. line continues the list and increments numeric markers; pressing Enter on an empty list item ends the list.
• Bracket and quote auto-pair (off by default; per-format toggle in Settings). Never enabled in plain text.

5.19 Document statistics and reading metrics

Local, instant, never sends content anywhere.

• Ctrl+Alt+S opens the Document Statistics dialog.
• Reports: characters with and without spaces, words, sentences, paragraphs, lines, headings per level, links, images, code blocks, tables, footnotes.
• Estimated reading time at a configurable rate (default 200 wpm) and speaking time (default 150 wpm).
• Readability scores: Flesch Reading Ease, Flesch–Kincaid Grade Level, Gunning Fog, SMOG, Automated Readability Index. Each line in the dialog is a separate wx.StaticText so screen readers can read them one at a time.
• Longest sentence (with click-to-jump), average sentence length, longest paragraph.
• If a selection exists, statistics report on the selection and the title says so explicitly.
• Status bar shows running word count for the current document or selection.

5.20 Accessibility auditor

Quill’s audience is exactly the audience that needs to produce accessible documents. v1.0 ships a first-class auditor.

• Ctrl+Alt+A runs an Accessibility Audit on the current document and opens the Issues dialog. (The same list is reachable via the command palette ! prefix.)
• Markdown and HTML checks: heading-level skips (h2 to h4), missing or empty alt text on images, alt text equal to the filename, generic link text (click here, here, read more, link), empty links, duplicate link text pointing to different targets, tables without header rows, deeply nested lists (>5), paragraphs longer than 500 words, missing lang attribute on <html>, missing page title.
• DOCX checks: missing alt text on inline images, heading-style skips, generic link text, tables without header rows, document language not set, missing title.
• PDF checks (informational): whether the PDF has any tagged structure, presence of embedded bookmarks, image-only page count, language metadata, password protection.
• Markdown front-matter checks: required keys present (configurable per project).
• Issues panel: list with severity (error/warning/info), location, message, and “Why this matters” explanation. Enter jumps to the issue, Delete dismisses for the session, Ctrl+I ignores the rule in this document (persisted in the document’s sidecar).
• Two companion catalogs:
  • Alt-text catalog (Ctrl+Alt+I): every image with its current alt text, edit in place for editable formats, jump-to-source.
  • Link inventory (Ctrl+Alt+L): every link with target and accessible name; flags duplicates and internal-vs-external; copy URLs.
• Audit completes in under 200 ms for documents up to 100 KB; up to 5 s for documents up to 5 MB.

5.21 Table mode for Markdown and HTML tables

When the editor cursor enters a Markdown pipe table, a Markdown grid table, or an HTML <table>, Quill enters Table Mode and announces it.

• Ctrl+Shift+Right / Ctrl+Shift+Left: next or previous cell; the column header is announced first, then the cell content (Column "Price": $4.99).
• Ctrl+Shift+Down / Ctrl+Shift+Up: next or previous row in the same column.
• F2: open the current cell in a small editor dialog with the column header in the title.
• Ctrl+Alt+T: insert a row below; Ctrl+Alt+Shift+T: insert a column after.
• Ctrl+Alt+R: delete the current row; Ctrl+Alt+C: delete the current column. Both confirm.
• Ctrl+Alt+H: toggle the current row as the header row (Markdown only).
• Tables remain valid Markdown or HTML on save: Quill re-aligns pipes and pads columns on every edit so the underlying text stays readable as plain text.

5.21a Structured List Studio (F2) — shipped

Build and edit lists by concept, not syntax, so the user never types -, 1., [ ], <ul>, or <dl> by hand. The design PRD was retired to git history once delivered; this section is the canonical record. Implementation: wx-free quill/core/lists/ (model, parse/interpretation, render, nesting, convert, validate, settings, announce — fully unit-tested) behind quill/ui/list_studio_dialog.py and list_studio_settings_dialog.py.

• Context-sensitive F2 (also Insert > List > Structured List Studio…): turns a selection into a list or starts a new one; with the caret inside an existing list and no selection, loads that block to edit and rewrites just it. F2 displaced Insert Special Character to Shift+F2 with a legacy-binding migration. Excellent defaults work with no Settings visit.
• Four types (Bulleted / Numbered / Checklist / Definition) in Markdown or HTML, with a live read-only source preview and an accessible items/entries outline that announces text, number/checked state, and position. Apply is one undoable edit.
• Nesting (Indent / Outdent / Add child; Move up/down carries a subtree), multiple terms and definitions per entry (multiple <dt> / <dd>), type-switch conversion with information-loss confirmation, import from clipboard/file with the preview as the interpretation, and reparse-and-validate before commit (rejects an empty list, a term-less definition entry, or injected markup, leaving the document unchanged).
• Definition-list Markdown profile (§7.6/§21.3): HTML emits semantic <dl>/<dt>/<dd>; Markdown follows a configurable profile (Pandoc / Markdown Extra / MultiMarkdown / embedded HTML / plain). When no profile is configured for the document, QUILL prompts — embedded HTML (recommended), a native profile, or a plain “Term: Definition” list — rather than silently guessing.
• Settings/presets with scoped precedence (§3). Effective settings resolve as app-default → format → document → this-operation (quill/core/lists/scopes.py; workspace is a supported layer with no source today, §3 “where applicable”). The app-default persists in settings.list_studio_settings; the format scope pins the definition-Markdown profile to the document’s markup; a per-document override lives on the document (source_metadata["list_studio_override"], stored as the diff from the app-default); and the List Studio Settings dialog saves for all documents or this document only.
• Remaining: a formal live screen-reader pass (JAWS/NVDA/Narrator) — manual, tracked in docs/planning/roadmap.md §1.8.

5.22 Editor essentials

A group of small, individually unremarkable features whose absence would feel cheap. All ship in v1.0.

• Encoding picker: File > Open With Encoding…, File > Reload With Encoding…. Status bar shows the active encoding. Auto-detection on open via charset-normalizer; user can always override.
• Line endings: File > Line Endings (LF, CRLF, CR). Status bar shows the active style. “Convert on save” is an opt-in setting.
• Reload from disk: Ctrl+Shift+R. If the editor has unsaved changes, prompt.
• External-change watcher: detect when the file changes outside Quill; offer to reload (auto-reload if the editor is unmodified).
• Insert date / time: Ctrl+Alt+D (with a one-time format chooser that the user can re-open from Settings).
• Templates: File > New From Template…. Templates live in %APPDATA%\Quill\templates\. Ships with: Markdown article, Meeting notes, Daily journal, Letter, Issue report, README, Changelog, MIT license header, Markdown blog post with front-matter.
• Word prediction: Ctrl+. opens an IntelliSense-style picker for document words plus HTML and Markdown tag completions. It can also run automatically while typing when enabled in Settings.
• Snippets: per-format snippet packs with trigger + Tab expansion. Ctrl+Alt+Space opens Insert Snippet; Ctrl+Alt+Shift+Space opens Manage Snippets. Off by default in prose, on by default in code. Editable in Settings.
• Save options (per document and per workspace): trim trailing whitespace on save, ensure final newline, normalise line endings on save.
• Smart paste: by default, strip rich-text formatting when pasting from sources that include it.
• Sessions: File > Save Session… and File > Open Session… preserve the set of open documents and per-document cursor position.
• Print: Ctrl+P opens the system print dialog, preserving the editor font and encoding.
• Extract to plain text: Tools > Save As Plain Text works for any opened format and is the canonical way to harvest text from a non-editable source.
• Compare two documents: Tools > Compare With File… supports an interactive compare session and can also produce a unified-diff document in a new editor tab. Interactive compare mode moves the cursor between differing line groups, offers a difference list, and supports synchronized compare navigation. Diff hunks remain navigable with Ctrl+] / Ctrl+[.

5.23 Recent locations history (browser-style back/forward)

• Ctrl+Alt+Left moves back through cursor jump points; Ctrl+Alt+Right moves forward.
• Push triggers: Find match, F3/Shift+F3 jump, bookmark jump, outline jump, Go To Line, Go To Page, opening a document, switching documents.
• The ring holds up to 100 entries per editor, deduplicated when consecutive entries collapse to the same line.
• A small Navigate → List Recent Locations… dialog shows the ring as a list with document, line, and the line text; Enter jumps. Stock wx.ListBox.
• Each location remembers document path, line, column, and a hash of nearby text so jumps survive small edits exactly as bookmarks do (5.10).

5.24 Mark ring

A second, lighter-weight navigation system for power users. Inspired by Emacs but adapted to Windows muscle memory. Marks are temporary jump points; bookmarks (5.10) are named and more durable.

• Ctrl+Shift+M sets an anonymous mark at the cursor; status bar briefly announces Mark set.
• Ctrl+M pops to the most recent mark; further presses walk back through the ring.
• Ctrl+Shift+X exchanges point (cursor) and mark, useful for jumping to where the user was and back.
• Edit → Mark Ring → List Marks… shows the ring in a stock wx.ListBox with document, line, column, and surrounding text snippet.
• Up to 50 marks in a circular buffer per session. Marks do not persist across sessions in v1.0.
• All keystrokes reassignable. Ctrl+. is reserved for Word Prediction by default, so users who rely on another screen-reader chord can reassign it; the conflict detector (8.4) flags the well-known cases at install time.

5.25 Read Aloud (secondary voice, not the screen reader)

Quill ships a read-aloud feature that uses a secondary voice the user picks from a list. It deliberately does not compete with the screen reader: the screen reader keeps doing its job while read-aloud plays, and the user can use a different voice for each so they are easy to tell apart.

• Backend: SAPI 5 voices and Windows OneCore voices via pywin32/comtypes. Detected at startup; the list is presented in Settings → Read Aloud and in the Read Aloud voice chooser.
• Ctrl+Alt+P starts/pauses read-aloud from the current cursor; Ctrl+Alt+S stops; Ctrl+Alt+. skips to the next sentence; Ctrl+Alt+, previous.
• Granularity: sentence by default; settings allow paragraph or word.
• Follow cursor (optional, off by default): the Move cursor to follow Read Aloud setting (Settings → Read Aloud; read_aloud_follow_cursor) selects each sentence in the editor as it is spoken so the cursor tracks the reading and stops where the user last heard. It is off by default because, with a screen reader running, moving the selection makes the screen reader announce the selection (“…selected”) over the Read Aloud voice; sighted and low-vision users can opt in. The status bar’s Read Aloud cell shows progress regardless of the setting.
• Selection-only mode: when invoked with a selection, read-aloud reads only the selection and stops at the end.
• Voice, speed, pitch, volume all configurable. Three named profiles (Reading, Proofreading, Skim) save preferred values.
• The read-aloud voice never overrides the screen reader’s announcements; if a screen reader speaks something while read-aloud is active, read-aloud continues but is briefly ducked.

Read Document in Browser (experimental, opt-in — edge_read_aloud_enabled). The embedded WebView2 only exposes the local SAPI voices; a real browser exposes its full Web Speech voice set, including Edge’s “Online (Natural)” voices. So, gated behind Settings → Experimental (and the experimental acknowledgement), QUILL can build a self-contained, accessible reader page (quill/core/browser_reader.py: labelled voice picker, Speed, Play/Pause/Stop, an aria-live status, keyboard focus on Play, the document text carrying its own lang) and open it in the user’s chosen browser via the existing preview-open path. The page builder is wx-free and unit-tested. Privacy contract: QUILL itself makes no network call for this; on-device voices synthesize locally, but the browser’s “Online (Natural)” voices synthesize in the vendor’s cloud, so choosing one sends the selected text to that service. This is disclosed in the setting description and in the network-egress audit’s documented (out-of-package) egress notes; the generated page carries the full document text as plaintext in app-data and is therefore deleted on exit (browser_reader.remove_reader_pages) so no copy lingers. Playback speaks chunk-by-chunk and treats Stop’s interrupted/canceled events as normal teardown (never surfaced as errors).

Voice preview feedback

Voice preview (Voice Browser dialog and the Download Optional Components hub’s Test button) reports its own state: starting a new preview always stops/supersedes a prior one (no overlapping audio or announcements), a one-shot “generating, please wait” cue (earcon + optional spoken announcement, voice_preview_announce_generating, default on) fires only when synthesis is still running after a short delay, and the Preview/Test button toggles to Stop while a preview is generating or playing. No true pause/resume; Stop cancels outright. An in-flight external synthesis call that gets superseded is not force-killed — it completes in the background and its result is discarded.

Reliability fixes (2026-07-08)

A batch of fixes from real user feedback and crash reports, landed alongside voice preview feedback:

• Sound backend on macOS. quill/platform/sound_player.py’s _detect_backend() previously tried only sound_lib (a licensed engine excluded from every build) and winsound (Windows-only), so macOS had no audio backend at all and every earcon — including the bundled Ink pack, which is correctly included in the .app bundle — was silently unplayable. Added an AppKit NSSound backend via pyobjc (already a macos build extra, used elsewhere for screen-reader announcements).
• AI Setup Wizard stuck-active state. SdkHarness.is_available() and sdk_install.is_pack_importable() only confirmed importlib.util.find_spec(), which a partially-written (crash-interrupted) pip install --target still satisfies. Both now attempt a real importlib.import_module, so an interrupted install correctly reports as not-installed and the existing Set Up retry path works.
• macOS file-open + keybinding gaps. run_app() now constructs a MacOpenFileApp (quill/ui/mac_open_file_app.py) overriding wx.App.MacOpenFile/MacOpenFiles, since Finder/Dock/open -a file-open requests arrive via an Apple Event, not argv, and QUILL previously never saw them. _parse_keybinding gained cmd/command as ACCEL_CTRL aliases (any Cmd+... binding, including the already-shipped back/forward-location shortcuts, previously produced no accelerator table entry at all on any platform). Document switching gets a darwin-specific default (Cmd+Shift+]/[) since Ctrl+Tab maps to macOS’s reserved App Switcher shortcut there.
• Clipboard read retry. The literal “Failed to get data from the clipboard (error N: …)” dialog is wxWidgets’ own C++ wxClipboard::GetData error (wxLogSysError, not a Python exception QUILL’s own try/except could catch), surfaced on the first transient CLIPBRD_E_CANT_OPEN contention with another process/AT holding the clipboard. quill/ui/clipboard_retry.py (with_clipboard_read_retry/read_clipboard_text) retries up to 10 attempts, 20ms apart, suppressing the dialog via wx.LogNull() on every attempt but the last; wired into every clipboard-read call site (magic_paste, abbreviation expansion, Copy Tray, Power Tools plain-text/HTML paste, Quillins).
• Four crash-report fixes (#915–#918): a missing label argument on a _show_modal_dialog call (Spell Check Language chooser); _IntellisensePopup.is_visible() now catches RuntimeError from a deleted C/C++ Frame (a crash-recovery restart could rebuild MainFrame without recreating the popup, leaving a stale reference); and the AI Hub Engines tab’s background-install completion callback now tolerates the panel having been closed/destroyed before the install finished.
• Crash opening the Quillins Manager when PyNaCl is not installed (#919). PyNaCl is a dev/CI-only dependency (Quillin Hub artifact signing/publishing), never a shipping one, but quill/tools/signing.py imported it unconditionally at module level — so simply viewing a Quillin’s details (which checks its signature status) crashed with ModuleNotFoundError on every real build. The import is now lazy (TYPE_CHECKING + function-local), and verify_artifact/signature_status — whose own docstrings already promised “fail-closed, never raises” — now catch a missing nacl the same way they catch every other verification failure, reporting “PyNaCl is not installed” instead of crashing.
• Quillin signature verification is now real on shipping builds (#919 follow-up). The #919 fix stopped the crash but left the feature inert: PyNaCl stayed a [signing]/[dev] extra no shipping build installed, so the Quillins Manager’s “Signature: verified/unsigned” lines never ran for end users — only the “PyNaCl is not installed” fallback did. PyNaCl is now a runtime dependency (the [ui] extra, mirrored in requirements.txt and the macOS py2app includes), so verify_artifact/signature_status run on every install. The graceful missing-nacl path in quill/tools/signing.py stays as defense in depth. A regression guard (test_pynacl_is_bundled_in_the_ui_extra_for_quillin_signature_verification) locks PyNaCl into the bundled [ui] set so it can’t silently revert to dev-only.
• The Report a Bug token is mandatory on every build (#919, hardened). The bundled issues-only GitHub token (quill/_feedback_token.py, baked from QUILL_FEEDBACK_GITHUB_TOKEN by tools/generate_feedback_token.py) is what lets the in-app bug reporter file straight to the issue tracker instead of dead-ending. An earlier beta shipped it empty on Windows (only macOS baked it), so upgrades showed “no token”; a first fix made a missing token hard-fail the release build, but still left an --allow-missing-feedback-token escape hatch so an ad-hoc local or beta build could silently ship tokenless. The token is now required on every build, Windows and macOS, with no opt-out: scripts/build_windows_distribution.py always passes --require-token to the generator and _assert_bundled_token_nonempty asserts the file that actually lands in the bundled quill/ package is non-empty (the exact “upgraded and got No token” symptom, locked out); scripts/build_macos.sh always runs the generator with --require-token. The --require-feedback-token flag is kept as an accepted no-op so the release workflow is unchanged. Regression guards in tests/unit/scripts/test_build_windows_distribution.py (test_build_guard_refuses_an_empty_token, test_build_guard_refuses_a_missing_token_file, test_build_guard_accepts_a_real_token) lock the guard.

API-key onboarding for env-var-authenticated harnesses

openai_agents and claude_agent_sdk both declare requires_api_key=True but, unlike GitHub Copilot’s OAuth device flow, authenticate by reading OPENAI_API_KEY/ANTHROPIC_API_KEY directly from the process environment with no QUILL-specific hook — so a successfully installed harness previously had no in-app way to add a key at all. quill/core/ai/harness_credentials.py bridges this the same way copilot_auth.py bridges GitHub tokens: the key is persisted in QUILL’s existing per-provider secure store (assistant_ai.save_provider_api_key, keyed by pack_id) and exported to the environment immediately so the SDK picks it up without a restart; apply_all_stored_keys() runs at startup so a key saved in an earlier session is already in place before anything checks harness availability. HarnessApiKeyDialog (quill/ui/harness_api_key_dialog.py, modeled on CopilotOnboardingDialog but simpler — one pasted key, no OAuth) is reached from the AI Hub Engines tab’s Set Up action once a harness is installed.

5.25b Watch Folder automation

Quill provides an optional watch-folder workflow under Tools -> Watch Folder for low-friction document intake. Users can point Quill at one or more folders, drop supported files into them, and have Quill process those files automatically without leaving the editor.

The original single-folder watcher has been replaced by a multi-profile Watch Service built on the wx-free quill.core.watch_service facade. Each watch profile is an independent rule set with its own watched folder, recursion and polling behaviour, file filters, and action (for example: open in editor, or run an intake action). Profiles are stored through watch_profile_store and validated against a schema, so an invalid or partial profile can never start a worker.

• Multiple named watch profiles can be configured and enabled or disabled independently.
• Supported drop formats follow Quill’s core supported file-extension set, optionally narrowed per profile.
• Polling, subfolder recursion, and the per-profile action are configurable from Watch Folder Settings.
• A dedicated, fully accessible Watch Queue Monitor (Watch menu) lists queued, in-progress, completed, and failed items so users can track and retry automation without a visual dashboard.
• Watch work runs off the UI thread through watch_worker/watch_queue; results marshal back through wx.CallAfter and surface in the status/notification channel. No silent failures.
• Watch-folder automation is configured from Preferences (Watch Folder Automation). A first-run wizard onboarding step for it is planned (see docs/planning.md).
• A watch profile can use the same BatchPlan shape from ### 5.3a.1 when its action is “convert to QUILL” or “convert from QUILL” - the Watch Service reuses quill.core.batch_convert.run_batch so a folder of dropped .docx files becomes a folder of opened Markdown tabs without a separate Batch Conversion wizard run. The action field on the watch profile chooses between the inline batch path and the open-in-editor path; both run on the background task pool.

5.25c Offline speech and transcription

Quill’s on-device speech engine (whisper.cpp by default) ships under Tools -> Speech and runs entirely on the user’s machine. The deferred, locked-off core.bw_whisperer brand surface (superseded by this flat menu) is tracked in the locked-features register in roadmap.md §2; this section describes only what ships today.

On-demand engine acquisition (release-asset). The whisper.cpp engine is not bundled (see §5.25f, Recommended host and redistribution rules): it downloads on demand from QUILL’s verified release asset to %APPDATA%\Quill\speech-engine, which the runtime searches. The first time offline dictation/transcription is used without it, QUILL offers the download in-flow (the dictation pre-flight prompts), and it is also at Tools -> Speech -> Download Offline Speech Engine.... Acquisition is quill/core/release_assets.py (wx-free): a pinned, SHA-256-verified download from QUILL’s controlled GitHub release asset (assets-v1), HTTPS-only, with retry/resumable download, atomic verified install, and a clean error on failure; gated by an explicit user action, the GATE-9 network-egress audit, and Safe Mode. Upgraders keep their existing {app}\tools\speech\whispercpp copy (Inno never removes it; [InstallDelete] does not touch it; the resolver still checks it), so upgrades never lose offline speech. Only components QUILL is licensed to redistribute are hosted this way (whisper.cpp is MIT, Kokoro Apache-2.0); license-unclear engines are not re-hosted, and ffmpeg is never re-hosted (it stays user-installed).

Family-wide non-goals, recorded so they are not relitigated without new information. Telemetry of any kind – no Sentry, no PostHog, no counters. A crash-report bundle is a local file the user reads and chooses to send, which is a different thing and stays. System-wide clipboard anything – QUILL keeps the clips it was given and helps assemble them; it does not watch the system clipboard and keeps no clipboard history, because a writing tool that silently records everything you copy is not one people should have to trust. Competitor data files – study a competitor’s ideas, never their data; interop is via open standards only (OPML, M3U, EPUB, VTT), never by reading another product’s private store.

Sound Enhancements: two engines, one of them upstream’s own (quill/core/optilab.py, quill/core/optilab_adapter.py, quill/native/optilab/). The three broadcast-polish modes are a faithful adaptation of OptiLab Core by Lanes Audio / dgl1984 (https://github.com/dgl1984/optilab, Apache-2.0 with the Commons Clause v1.0), rebuilt as ffmpeg filter chains. That adaptation carries one documented limitation: upstream eases its lift and withdraws bass assistance while final limiting runs heavy, and an ffmpeg graph is feed-forward – no stage can observe how hard a later one is working – so the feedback loop cannot be expressed there at all.

Upstream’s engine is therefore also vendored unmodified at v1.4.0 under quill/native/optilab/upstream/ (with its LICENSE and NOTICE) and linked into an adapter QUILL owns (quill/core/audio/exact_optilab.py runs it).

One setting, three states, named for the surface and not for the engine: off (the built-in chain everywhere, the default), when saving (radio recordings and audio conversion), or when saving and while listening. A control named after an engine would imply it applies wherever that engine’s name appears; naming the surface removes the whole class of confusion, and the third option states its own cost inside the option (rule A-9: no control may silently apply to only part of what it names).

Saved files are the recommended state and cost nothing. Recordings and conversion already shell out to ffmpeg offline. A recording is post-processed after it finishes and after any dropped-and-resumed parts are joined, into a temp file that replaces the original only on success – a fault in the engine must never be able to cost somebody the show they were recording – and a raw capture is never post-processed at all, because re-encoding it is exactly what raw capture exists to avoid.

Live playback through the engine is possible, opt-in, and normatively not the default. The reason is structural, not a missing feature: the engine is a separate process (upstream’s API is explicitly not a stable C ABI), and nothing on QUILL’s live path ever holds a PCM sample – mpv applies enhancement natively from a filter string, which is why every enhancement previews instantly with no gap and why one graph serves live radio, podcasts and recordings. There is no filter string that expresses another product’s DSP, and mpv does not host CLAP. So live means relaying: decode, pipe through the engine, re-encode, play a loopback URL (EnhanceRelay, on both engines, with mpv’s native graph cleared so nothing is processed twice). The costs are a slower start, an MP3 re-encode generation, more CPU, and a reconnect on every settings change, because the engine is prepared with a mode and a sample rate at start-up and cannot be re-parameterised mid-stream. Rejected alternatives, recorded so they are not re-proposed: a custom libavfilter wrapping optilab-core, an in-process Python extension over an ABI upstream does not offer, and an mpv CLAP host.

Never both engines on the same audio. Whenever the real engine will run, the OptiLab filters leave the ffmpeg graph; everything else (EQ, compressor, channel mode, night mode) still applies.

State the differences; do not imply them. The chain contains none of upstream’s gated AGC, six-band density processing, adaptive bass and top control, stereo processing or hybrid final stage; its Podcast and Limiter ceilings are -1.5 and -2.0 dBFS where upstream delivers to -0.1; its Input default is 0 dB where upstream’s inputDriveDb is 3.5; and the limiter feedback loop cannot be expressed in a feed-forward graph at all, which is the one difference that can be claimed with confidence. On gentle material the two may be indistinguishable, and no QUILL text may suggest otherwise.

An adapter executable rather than a Python extension, because upstream’s native/API.md states its C++ API is “not a stable C ABI” and asks consumers to “wrap this C++ class in a small adapter owned by your project”. QUILL’s adapter contains no DSP. Entirely optional: absent adapter -> available() is False and every caller uses the chain. Upstream’s NOTICE grants royalty-free commercial use of OptiLab Core as a tool for producing, processing, broadcasting or streaming audio; the Commons Clause withholds the right to sell the Software itself, which QUILL does not do.

**Crash fingerprinting (quill/core/crash_fingerprint.py, feedback-hub

=1.1.0).** A repeat of a crash somebody already reported comments on that issue instead of filing a new one. QUILL files crash reports from two places holding different things – the excepthook has a live exception, the crash-recovery dialog has saved text from a session that already ended – and they must produce the same fingerprint for the same crash, or one crash reported live and later from its file lands on two issues and the deduplication has bought nothing. Both entry points therefore live in one module, and a test raises a real exception and compares the two paths. Two invariants: an empty fingerprint means “do not deduplicate”, never a real value (a hash of nothing would collapse every unparseable report onto one issue), and deduplication can never lose a report – every failure path falls through to creating a new issue. The id ignores line numbers (they shift every release, exactly when duplicates arrive fastest), the exception message, and absolute paths (which carry usernames and frozen-build layout).

Transient-failure retry, as one policy (quill/core/net_retry.py). A feed that answers 503 because its host is briefly overloaded, a connection dropped mid-read, and a request that timed out all usually succeed on the second or third try seconds later; a 404 and an unresolvable hostname never do, and retrying them only makes the failure take longer to report. The module draws that line – not “did it fail” but “is failing again the likely outcome” – and it is deliberately a short allowlist rather than “anything that is not a 404”: an unrecognized failure is treated as permanent, so a new failure mode surfaces at once instead of being silently retried three times. Two retries, a second then two seconds apart. Adopted by podcast feed refresh, the podcast directory search, and the OPML reachability sweep; the sweep uses a shorter schedule, because it runs across thousands of feeds and its verdict is what the import report offers to prune out of a listener’s subscription list – a false “dead feed” from one flaky moment is the most expensive wrong answer in the podcast stack. Downloads deliberately do not use it: they already have a resumable reconnect with a Range header, which is the better answer for a partially transferred file. sleep is injected, and resolved at call time rather than captured as a default argument, so a test that thinks it has disabled the waiting actually has.

Revealing a file in the file manager (quill/core/file_manager.py). Four surfaces had grown their own copy of this, and two were wrong the same way: Windows Explorer parses /select, and the path as a single argument, and split across two it drops the switch and opens Documents instead. The feature appeared to work – a window opened – while doing something else entirely, which for a screen-reader user comes with no cue at all that the wrong folder just appeared. One pure, tested argv builder now serves the editor’s Reveal in Explorer, the app shell’s post-update Open folder, Audio Studio, the radio Recordings list, and QUILL Cast’s Show in File Explorer. The path is treated as text rather than re-parsed through Path, because Path applies the running machine’s flavour and would mangle a POSIX path on Windows.

Kokoro voices unbundled (proof of concept). The ~120 MB Kokoro neural voices are no longer shipped in the installer; they download on demand through the same release_assets path (pinned kokoro-models.zip on assets-v1, SHA-256-verified) to %APPDATA%\Quill\kokoro-models, which the runtime prefers. This shrinks the base installer and proves release-asset hosting for a model component. Upgraders are protected automatically: Inno only overlays new [Files] and never removes old ones, [InstallDelete] does not touch kokoro-models, and runtime resolution still checks {app}\kokoro-models (read_aloud._bundled_kokoro_model_dir) — so a user upgrading from a release that bundled Kokoro keeps their copy with nothing to re-download. Kokoro is in the “safe to unbundle” class (other read-aloud voices remain available offline if the download has not happened). The kokoro-onnx package is now also unbundled (0.9.0 Beta 2): it was still shipped in the base runtime (dragging in onnxruntime, phonemizer, espeakng-loader, and babel) even though the models were on-demand. It now installs on first use via install_kokoro_onnx() into an engine-pack that activate_engine_packs() puts on sys.path, trimming the installer ~23 MB. Lesson banked (#881): the build’s runtime-prune step must not drop babel — kokoro-onnx imports babel.numbers transitively, so pruning it broke Kokoro’s onnx path on a clean build; the on-demand install now pulls babel with the rest of the tree.

DECtalk and eSpeak NG unbundled. The classic DECtalk runtime (~2 MB) and the eSpeak NG engine with its voice data (~40 MB) are no longer shipped in the installer; each downloads on demand from assets-v1 (DECtalk via quill/core/dectalk_runtime.py, pinned vs2022.zip, SHA-256-verified, to %APPDATA%\Quill\speech\dectalk; eSpeak via quill/core/speech/espeak_install.py, pinned espeak-ng.msi, SHA-256-verified and extracted admin-free with msiexec /a, to %APPDATA%\Quill\speech\espeak-ng) — both folders the resolver already searches. The two MSI/zip assets are QUILL-hosted, byte-identical re-publishes of the upstream releases (matching the bundled-build pins) so the on-demand path has one controlled, verified acquisition point. Windows’ built-in SAPI 5 voices remain the always-present offline floor while a download has not happened, so the user is never left without a voice. Upgraders keep any existing {app}\tools\speech\dectalk / espeak-ng copy (Inno never removes it; [InstallDelete] does not touch it; the resolver still checks it). eSpeak NG is GPLv3 and DECtalk is BSD-licensed; both are already covered by QUILL’s redistribution/compliance notices, so re-hosting carries the same terms as bundling did.

Cloud providers ship as Quillins, not core. Per the consolidation plan (#669), the cloud provider matrix is delivered as extensions rather than baked into core. A Quillin declares a provider through the transcription_providers manifest contribution; QUILL’s host implements it. The contract is host-mediated and least-privilege: the Quillin ships no code and requests no net capability — it only declares the provider (id, display_name, a host-vetted kind, optional credential label and max_file_mb). The host performs the upload through its existing network-egress-audited transcription path, so the sandbox never receives audio bytes or the API key, and a manifest can never target an arbitrary endpoint (only known kinds are accepted). Host adapters implement the SpeechToTextProvider ABC and register into the speech registry, so a contributed provider appears in Manage Speech Models and the transcribe pickers. Providers are tagged network-backed and are excluded from the offline paths (the offline Watch Folder transcribe action only ever uses on-device engines); they are unavailable in Safe Mode or without a configured key. Implementation: quill/core/speech/quillin_providers.py, the transcription_providers model/validation/schema in quill/core/quillins/, and the bundled reference Quillin openai-whisper-transcription. Developer reference: docs/quillins/quillins.md §“Transcription providers”.

Offline speech & dictation reengineering (#617). The full provider-architecture plan — one offline-first speech engine (whisper.cpp default, with Windows, cloud, and Faster Whisper providers), two user verbs (Dictate / Transcribe), an accessible model manager, captions, and gated voice commands — was sequenced into small waves S0–S5. Wave S0 (shipped): the dictation_engine setting was made honest — it now uses the offline/windows/cloud model (default windows, the only functional engine today), legacy vosk/whisper values migrate to offline, and the dead local-recognizer stub was removed. Dictation behavior is unchanged: it still drives the OS dictation panel until the offline engine lands in S2–S3.

Waves S1–S4 (shipped). The offline engine landed: a whisper.cpp provider with an accessible model manager (Hugging Face Hub downloads, Safe-Mode gated), Transcribe (plain text / Markdown / HTML), Generate Captions (SRT / VTT), push-to-talk Dictate at the cursor (distinct earcons, status-bar state, microphone picker, QUILL Key + Shift+D), and speaker attribution via the whisper.cpp speaker-detection model. The whisper.cpp engine downloads on demand (unbundled, §5.25c above), and sounddevice is bundled for capture. S4 added Faster Whisper as an optional, GPU-aware second engine (fasterwhisper extra): when present it appears in a Speech Engine chooser, the choice is saved in speech_provider, and it is used for transcription, captions, and dictation. whisper.cpp remains the default and needs nothing extra; Faster Whisper does not attribute speakers.

Locked Dictation (shipped, 1.0-complete). One keyboard-only dictation mode on the offline engine: Ctrl+F9 toggles a hands-free Locked session (Ctrl+Shift+F9 pause/resume, Alt+F9 speak-state, Escape keep / Shift+Escape discard). Hold-to-Dictate (hold F9) shipped in 0.7.0 and was removed: a held key repeats and announces itself endlessly under a screen reader, so the single locked gesture is the reliable one (the controller’s hold states remain in the wx-free core for compatibility, but no UI binds them). Built as a protected transaction in quill/core/speech/dictation/: an explicit DictationController state machine (single-recorder invariant; no bare boolean), audio saved to recovery/dictation/ before transcription, a five-minute / focus-loss auto-stop, and a transcript that can’t be safely inserted is kept for review rather than lost. Two accessible surfaces under Tools > Speech > Locked Dictation: a Dictation Settings panel (session time limit, stop on focus loss, intelligent spacing, reset of the one-time hint) and a Dictation History & Review window (insert/copy/discard recovered recordings; doubles as the startup-recovery prompt). Locked Dictation has distinct earcons and a one-time onboarding hint. File synthesis runs with no console-window flash and a timeout.

Dictation reliability pass (2026-08-17). Five changes landed together, studied against the Handy project’s production dictation experience (an MIT-licensed offline speech app whose design notes and failure catalogue proved directly transferable; local clone at D:\code\handy). The through-line is reliability a listener can hear, not accuracy percentages:

• Parakeet 3, and an engine preference ladder. NVIDIA parakeet-tdt-0.6b-v3 (25 languages, automatic language detection, ~650 MB int8, CC-BY-4.0) joins the engine set as providers/parakeet_onnx.py on sherpa-onnx — CPU-only, torch-free, mirrored SHA-pinned on assets-v1 like every model. Dictation now resolves its engine through service.preferred_dictation_provider_id: an explicit engine choice always wins; otherwise an installed Parakeet outranks the whisper.cpp default. The reasoning is structural, not taste: a transducer emits tokens only for audio evidence, so it cannot hallucinate text from silence — the Whisper-family failure (“thank you” typed into the document after a quiet pause) that dictation, all short utterances and pauses, meets constantly. whisper.cpp stays the default because it works before any large download; the ladder promotes Parakeet only after the user installs it, an explicit and reversible act. Every model row in Manage Speech Models now speaks its capabilities (“detects the spoken language; never invents text from silence”) before download — the catalog is the manifest of truth and the picker promises only what it lists.
• A silence pre-pass (speech_vad.py) between recorder and engine: a pure stdlib RMS tier trims quiet lead-in/out from every captured WAV (calibrated identically to the Hey-QUILL turn detector), and an all-quiet recording short-circuits to the honest NO_SPEECH feedback without paying for a transcription that could only invent. When the Parakeet bundle is installed its silero_vad.onnx (shipped inside the model zip) refines the same decision neurally — best-effort, and only ever narrowing the RMS span.
• Transcript refinement (dictation/refine.py, PRD §17 addendum), two pure passes in fixed order, both wx-free and unit-tested. Custom vocabulary (speech/vocabulary.py): the dictation.md profile’s term list — already biasing Whisper’s initial_prompt — now also drives a fuzzy corrector (Soundex + Levenshtein + 1–3-word n-grams, a 25 % length gate, ASCII-only fallback) so engines with no prompt support, Parakeet included, still learn the user’s names and jargon, and split renderings (“charge b”) rejoin to the user’s exact casing (“ChargeBee”). Filler removal (speech/fillers.py), off by default: a universal tier (“uh”, “hmm”) plus a language-gated tier that removes “um” only with language evidence — because “um” is Portuguese for “a/an” and German for “at/around”, and a filler pass that deletes real words is worse than none. A custom list replaces both tiers. Settings: dictation_remove_fillers; evidence comes from the existing dictation_language.
• The streaming contract, ahead of need (speech/streaming.py). When a streaming engine lands, live text must be two fields: an append-only committed prefix and a volatile tentative tail — and speech/braille announce only newly committed text, exactly once. Repainting partials through a screen reader speaks the same words repeatedly as the decoder rewrites its tail; this contract makes that impossible by construction (same single-speaker discipline as Reveal Codes). StreamAnnouncer enforces it and survives a misbehaving provider without double-speaking. Landed now, with tests, so the future streaming provider is built into the contract rather than retrofitted.

5.25f AI footprint, on-demand acquisition, and optimization

QUILL’s guiding aim is to be as capable as possible on whatever hardware the user has, while keeping its on-disk and in-memory footprint small — fitting more capability onto modest, CPU-only machines, never trimming features off the low end. This section is the durable reference for that stance and for the acquisition model every on-demand component obeys. It absorbs the former standalone footprint/optimization plan. The wx-free cores for the runtime-memory policy (quill/core/model_lifecycle.py), the machine-aware upgrade advisor (quill/core/model_upgrade.py), the consent-safe cloud↔︎local fallback (quill/core/ai/fallback.py), and the in-app measurement sampler (quill/core/footprint_sampler.py) have landed with unit tests, along with two accessible settings (Low-resource mode and Unload idle models after…) and a build-only Babel prune. Their live wiring into the running app, and the build/hardware-gated measurements and installer-size wins, are tracked in roadmap.md §1.2.

Design principles (firm constraints).

• Capable on any hardware. The full feature set runs on a modest, CPU-only Windows machine with limited RAM. Optimization exists to extend capability downward to low-end hardware, never to disable features on it.
• AI and speech available wherever feasible. Prefer enabling AI and speech — on-device when it fits, cloud when the user opts in — over gating them behind hardware. A weaker machine gets a smaller/slower model, not “no feature.”
• No GPU requirement, ever. The default, fully-supported path is CPU-only. Nothing may require a discrete GPU or degrade when one is absent.
• GPU is a welcome bonus when present. If a usable GPU is detected, engines may auto-accelerate (e.g. Faster Whisper’s CUDA float16 path) — automatically and optionally, never as a precondition and never something the user must configure.

Already optimized on the model side. QUILL ships quantized models throughout (Faster Whisper CTranslate2 int8 on CPU / float16 on CUDA; Kokoro int8 ONNX; whisper.cpp GGML-quantized; local LLMs as GGUF Q4/Q5 via Ollama / llama_cpp_backend), with lazy, optional loading (heavy ML imports deferred via importlib.util.find_spec, imported only on use), warm/unload lifecycle primitives on the speech and Kokoro providers, optional install components with on-demand downloads, and machine-aware recommendations that size suggestions to the user’s RAM / GPU / disk. So the remaining wins are in packaging, runtime memory, and routing — not in re-quantizing models.

Reliable acquisition model. Anything QUILL does not bundle becomes something it must fetch dependably, possibly years later when an upstream URL may have moved. Every on-demand asset obeys all of the following (the quill/core/release_assets.py, ai/model_manager._download, and scripts/fetch_bootstrappers.py paths encode this):

1. Pinned, versioned source + SHA-256. Every asset has a pinned URL (or pinned release tag/commit) and a recorded SHA-256; bytes are verified before use, and a moving ref (HEAD/latest/main) is refused for the pinned path.
2. GATE-9 / no-silent-network. Each download call site has a reviewed entry in network_egress_audit.py and a visible, consented surface (progress dialog / explicit action). No silent fetches; Safe Mode disables all of it.
3. Atomic + verified install. Download to a temp path, verify the SHA, then atomically place it (temp + replace) so a partial/failed download never leaves a half-installed asset that looks present.
4. Retry + resumability. Bounded retry with backoff and resumable (HTTP Range) download so a dropped connection on a large asset does not force a full restart.
5. Source resilience. Pin to a stable host and record a mirror/fallback URL where licensing allows, so a single upstream outage cannot strand a feature. The verified SHA makes any mirror safe to trust.
6. Graceful offline / failure UX. On no-network, timeout, 404, checksum mismatch, rate-limit, or low disk (enough_disk_for), surface a clear, screen-reader-friendly message and leave the app fully usable for everything else. Never crash, never silently degrade.
7. Integrity over time. A periodic/CI acquisition healthcheck resolves every pinned URL and re-checks reachability + checksum, so a dead upstream is caught by us, not by a user offline at the worst moment.
8. Already-present is smart, not silent. An installed component is not re-downloaded; QUILL offers to replace it, and declining keeps the existing copy.
9. Newer-version awareness. Each asset records its upstream version; a lightweight check compares installed vs. pinned manifest and offers a newer verified version — never auto-replacing a working component.

Recommended host and redistribution rules. The strongest way to satisfy source resilience is to host redistributable assets ourselves as GitHub Release assets on a Community-Access repo (the pinned assets-v1 tag). This re-points the runtime on-demand path at a release we control, with stable …/releases/download/<tag>/<asset> direct-download URLs (not the rate-limited releases API), each SHA-256-pinned and honouring HTTP Range for resumability. Hard constraints:

• License/redistribution gate (per asset). Re-host only what we are licensed to redistribute. whisper.cpp (MIT), Kokoro (Apache-2.0), and Piper are fine; eSpeak NG is GPLv3 (allowed with the source-offer obligation already in the compliance notices); DECtalk is BSD. All four are re-hosted on assets-v1 as byte-identical re-publishes of the upstream binaries. ffmpeg is explicitly excluded — QUILL never bundles or re-hosts it (see quill/core/speech/ffmpeg.py); it stays user-installed. Every re-hosted asset needs a third-party-notices entry.
• 2 GB per-asset limit. GitHub caps a single release asset at 2 GB, so multi-GB assets — speech large-v3 (~3.1 GB) and the GGUF LLMs (phi-4-mini ~2.5 GB) — stay on their canonical Hugging Face hosts, which the code already uses.
• Verify regardless of host. The SHA-256 check stays even for assets we control; it defends against a replaced/corrupted asset and lets any mirror be trusted.

The download experience is accessible by contract. Each on-demand download runs behind an accessible, cancelable progress dialog (AIProgressDialog) with spoken milestones; focus is owned and returns to the feature that needed the component. Downloads are reachable where the user already is (the feature surface, a Help-menu “Download optional components…” entry, and an optional first-run Setup-Wizard offer), never block the UI thread, are disabled by Safe Mode, and present one consistent surface across OCR, Scribe, speech, and voices (the AI Hub Services framework).

The Download Optional Components hub is a first-class place (design spec: docs/superpowers/specs/2026-07-07-download-components-experience-design.md). The wx-free status model (quill/core/optional_components.py) sorts components by importance (Pandoc and the braille pack first) and covers every component QUILL can fetch — a completeness guard test asserts each hosted release_assets component is catalogued (Vosk and libmpv are hosted assets folded into other rows rather than standalone ones — see below — and are explicitly exempted from that guard), and Piper and Node.js (missing before) are now listed. The dialog (quill/ui/optional_components_dialog.py) shows a size on every row and a rich, read-only description of the focused component (describe_component), and gathers the list on a worker thread so it opens instantly rather than stalling on tool version probes. For an installed component it offers Test — a per-component self-test that maintains confidence: voice engines speak a sample (the phrase lives in scripts/phrase.txt), offline STT engines run a SAPI→transcribe→compare loop and report what they heard (verify_component), and tools report their version — and Remove (removable_path/remove_component), which deletes only QUILL-downloaded copies under the active data dir (the portable data folder in portable mode; never a system tool, a bundled {app} copy, or anything outside it) and closes the loop by resetting the active Read Aloud engine to SAPI 5 when the removed engine was in use. Any download or self-test failure is captured (DownloadFailure, plus the pip error logged to quill.log) and offered as a one-click bug report through the diagnostics bundle. The scattered startup braille-pack prompt now routes into this hub, preselected on the braille pack with a guiding popup, rather than running its own installer.

Rows were folded together for a flatter, less repetitive list (0.9.0 Beta 2, #847). Vosk (a third offline dictation engine, alongside whisper.cpp and Faster Whisper) no longer has its own row — the hub’s single “Dictation (offline speech)” row (renamed from “Offline speech engine (whisper.cpp)” so it names the outcome, not the implementation) opens a guided picker to choose an engine and a model together (quill/core/speech/guided_setup.py, quill/ui/guided_speech_dialog.py); Vosk is simply a third OfflineSpeechEngineOption there, installed via the same _ensure_offline_engine/install_vosk path as the other two. Separately, FFmpeg (compressed-audio export), mpv playback, and MP3 chapter markers — three export/playback extras — are now one row, “Audio: export, playback & chapters” (_audio_extras_installed, download_audio_extras; FFmpeg is fetched on demand at export time via download_ffmpeg, not as part of the row’s own download), so there is one place for audio extras instead of three; the standalone FFmpeg row is gone. Node.js moved to the bottom of the list as the least-used extra (priority=110).

The dictation setup is a guided Engine→Model→Test→Default journey (0.9.0 Beta 2). A wx-free brain, guided_setup.dictation_setup_status() (unit-tested), computes the three-step state (install an engine → download a model → test and set default) for the selected engine, and the Manage Speech Models panel (quill/ui/speech_setup_dialog.py) renders it as a “you are here / do this next” banner, auto-selects the recommended model, and adds an inline Test dictation button. The panel now opens on the user’s saved engine even when it is not yet ready (MainFrame._configured_speech_provider, resolved from the shared registry so the engine radio matches by identity), instead of the availability-fallback default that made it always reopen on whisper.cpp. The self-test (optional_components.verify_component → _verify_stt) targets the selected provider (transcribe.transcribe_audio_file(provider_id=…) / provider_has_installed_model) so it proves the exact engine, covers all three offline engines (whisper.cpp, Faster Whisper, Vosk), and logs its OK/FAILED outcome so failures reach the diagnostics bundle rather than living only in the on-screen dialog. Testing an engine with no model installed still routes to the guided picker (open_guided_offline_speech); a successful Test also persists the engine as the dictation default, so Test doubles as “use this engine.”

Size / RAM reference (current observations, to be re-baselined by the footprint report). scripts/footprint_report.py emits the diffable size/machine baseline under docs/planning/footprint/. Offline speech models (download size; Faster Whisper’s on-disk int8 is smaller), with the RAM tier service.required_ram_gb maps each to:

Speech recommender (service.recommend_model_id) by total RAM: <3 GB → tiny; <6 → base; <12 → small; <16 → medium; ≥16 → medium (or large-v3 with a GPU). On-device LLM (GGUF Q4_K_M, ai/model_manager.py; auto-downloaded + SHA-256-verified): Llama 3.2 1B Instruct ~0.8 GB (default under 8 GB RAM), Phi-4-mini Instruct ~2.5 GB (8 GB+). The Windows installer (0.8.1 local build) is ≈ 245 MB, dominated by the embedded CPython 3.13 runtime + wheels; the embeddable stdlib is already lean (python313.zip 3.6 MB; tkinter, test, idlelib, ensurepip, lib2to3, distutils all absent), so the footprint lever is large data inside wheels (spell-check dictionaries, CLDR locale data — Babel is now pruned as build-only) and optional engines that qualify for on-demand, not stdlib modules. The largest optional engine, Vosk (~51 MB libvosk wheel), is no longer bundled: it installs on demand via quill/core/speech/engine_install.install_vosk (Tools → Speech → Download Vosk), preferring QUILL’s own pinned, SHA-256-verified wheel on the assets-v1 release and falling back to PyPI. No offline speech engine ships in the installer now — the tiny default whisper.cpp (~8 MB) is itself fetched on demand — so the base download stays small while capability is a one-time verified fetch away.

5.25d Batch Document-to-Speech, pronunciation, and SSML (shipped)

QUILL converts whole folders of documents to speech audio and gives the user fine control over how that audio sounds. This section records the shipped behavior; the original design plan and project-format spec were retired to git history once delivered (their remaining follow-ups are tracked in roadmap.md §1.2). All synthesis logic is wx-free and headless-testable; the UI wraps it on the background task pool.

QUILL’s audiobook and batch-speech wizard (Tools → Speech → Audiobook & Batch Speech…; the menu label was “Audio Studio…” until 1.0.0, renamed to remove the clash with the standalone app’s name). A guided, journey-aware wizard (it replaced the single-page Batch Export to Speech Audio dialog at full option parity; the tools.speech_batch_export command id is unchanged so keymaps and menu customizations keep working). The start page picks a journey — narrate documents or combine audio files into one chaptered audiobook — and the following pages adapt: What should I read? (folder, types, filters) → Who should read it? (engine, voice + preview, pace, round-robin rotation, translated editions) → How should chapters work? (mode, spoken headings, the transition sounder + volume, article/sentence/tail gaps) → Output and diagnostics (format, existing-file policy, ACX loudness, dry run, spoken-text sidecars, temp folder) → the book page → a plain-sentence summary. Back/Next/Start follow the standard wizard keyboard contract, every step is announced (“Step 2 of 7: What should I read?”), and Skip to summary fast-forwards a returning user whose project profile already fills every page. AudioStudioWizard (quill/ui/audio_studio/) collects the same BatchSpeechRequest the classic dialog produced, so the tested runner and profile persistence are unchanged. The run reports per-file progress and is cancelable; the conversion uses the same shared pipeline as live Read Aloud (normalize → pronounce → polish → synthesize), so audition matches output.

• Pipeline modules. quill/core/speech/batch_export.py (per-file pipeline), batch_discovery.py (folder scan + filters), batch_manifest.py (run report), chapters.py / chapter_assemble.py (MP3 ID3v2.3 CHAP/CTOC chapter markers + heading-aware assembly with inter-article/sentence pauses, optional transition earcon, spoken headings, anti-clipping tail pad), ffmpeg.py (encode to compressed formats, metadata, WAV conform), and document_speech.py.
• Chapterization options. MP3 (ID3 chapter markers) or M4B audiobook (native MP4 chapter atoms via ffmpeg FFMETADATA) output; over-long sections auto-chunk on safe sentence/word boundaries (tts_chunk) so no synthesis call exceeds the engine timeout; the run reports each document’s chapter count. The transition earcon defaults to the bundled page-turn cue (quill/assets/audio/page_turn.wav); a configured batch_speech_chapter_sound_id overrides it from the active sound pack (batch_speech_runner._resolve_chapter_sound_path). Any chosen or default sound is conformed to the section PCM format (resample / channel-mix / width via earcon.conform_wav_frames) so it splices cleanly regardless of its own format — the synthesized chime is only a last-resort fallback. A Chapter mode selects one chaptered file or Separate file per article (document_speech.synthesize_document_to_separate_files, one NNN - <heading> file per section). A Dry run writes a <doc>.preview.txt of the exact post-pipeline spoken text (with the substitution count) for proofing without synthesizing. Combine empty headings (opt-in) folds bodyless headings into the next article and joins their titles (text_polish.combine_heading_only_sections, the ACB rule). Normalize loudness (opt-in) runs each output through a two-pass loudnorm (loudness.normalize_wav_loudness: measure with print_format=json, then apply with the measured values, linear=true) on the assembled WAV before encoding, so MP3/M4B chapter markers and timing survive — the ChapterForge/ACB method, matching the audiobook builder’s ACX option. Round-robin voices voices each section by the next entry in a user-ordered voice list (assemble_chaptered_audio(..., synthesizers=…), section i → voice i mod N); the rotation uses voices of the selected engine so all sections share one PCM format. The batch dialog builds the voice list with the accessible add-from-combobox + reorderable-ListBox pattern (no checkboxes in lists). Both options persist in ChapterProfile (.quill/speech-project.json).
• Discovery. Extension set, recursion, semicolon/comma-separated include/exclude globs (matched against name and relative path), and a max-file-size cap.
• Output. wav (always available) plus mp3/m4a/m4b/opus/flac/ogg via ffmpeg, falling back to WAV with a per-file note when ffmpeg is absent; selectable MP3 VBR quality; optional uniform WAV sample-rate/channel conform; audiobook metadata (album, author/narrator, genre, year; per-file title and track derived from heading/index).
• Layout and resume. Existing-file policy skip/overwrite/rename; mirror or flatten; filename_template ({stem}/{index}/{index0}/{total}); optional manifest.json/.csv.
• Reliability and throughput. Per-file retry, stop_on_error, and max_workers parallelism — clamped to one worker for the single-apartment engines (SAPI 5, Kokoro). Per-engine shaping is exposed for eSpeak (pitch, word gap) and Piper (length/noise scales).
• Project profile. A folder remembers its whole speech setup in <folder>/.quill/speech-project.json (schema quill/core/schemas/speech_project.json): synthesizer, discovery, output, chapters, normalization, pronunciation, metadata, and execution. project_profile.to_batch_options drives the pipeline straight from a project file. The batch dialog applies the profile on open and auto-remembers choices on Start (batch_speech_runner._apply_project_profile / _save_project_profile), with precedence this-run > project profile > global defaults.
• Translated audio export (shipped — local and cloud voices). Synthesizes a document in additional languages: the text is translated per section, then narrated with a voice for that language, written as <doc> (<Language>).<ext>. Two surfaces: the batch “Also export in other languages” picker (folder) and a single-document action Tools → Speech → Export to Translated Speech Audio (quill/ui/translated_speech_export_dialog.py + translated_speech_runner.py, reusing the batch _export_translations core). Translation rides QUILL’s AI gateway (any configured AI provider) or LibreTranslate, with bounded-backoff retries that halt a language on persistent failure and a translation cache (speech/translate_sections.py). Voices come from the per-language model (speech/voice_languages.py) local-first — eSpeak NG (universal offline, with dialects), installed SAPI 5 matched by LCID — then the premium cloud tier (OpenAI / Gemini / ElevenLabs), which synthesizes through cloud_tts and is conformed to WAV via ffmpeg so chapter splicing holds (document_speech.make_synthesizer cloud branch; SynthesisSpec.api_key/model). A cloud target with no configured key is skipped with a status note. Pronunciation dictionaries are language-scoped (PronunciationDictionary.language); the full chaptered treatment applies per language. Remaining 2.0 nicety: persisting the chosen targets in the project profile.
• Cost surfacing (shipped). A translated cloud run can meter twice (translate + synthesize), so speech/cost_estimate.py produces an honest combined estimate — TTS priced precisely per provider/model via cloud_tts; translation free for LibreTranslate or a local AI model and estimated from a blended per-character rate for a paid cloud AI — surfaced for confirmation before any metered run (batch_speech_runner.confirm_cloud_cost). Local-only runs are never interrupted.
• Voice-failure blacklist (shipped). A voice that fails synthesis is recorded and skipped on later runs (speech/voice_blacklist.py, persisted atomically in the app data dir): document_speech drops blacklisted ids from the round-robin rotation and wraps each synthesizer to record a failure (then re-raise, so the current run is unchanged); the runners load the blacklist once and save it after the run.
• Subprocess hardening. The Piper and eSpeak-NG file-synthesis subprocesses launch with CREATE_NO_WINDOW (no console flash between files) and the eSpeak-NG synthesis carries a timeout that raises a clean ReadAloudUnavailableError rather than stalling the run.

Pronunciation dictionaries (Tools → Speech → Manage Pronunciations…). Ordered substitution rules (literal or regex, optional case sensitivity, per-engine scope) stored in global (app-data) and project (<folder>/.quill/pronunciation/) dictionaries (quill/core/speech/pronunciation.py, schema pronunciation.json). Applied as a silent text transform before synthesis in both batch and live Read Aloud, so a correction is heard everywhere; the manager previews entries with live Read-Aloud audio. A bundled starter dictionary ships common terms.

TTS text normalization. quill/core/speech/text_normalize.py deterministically cleans typography (quotes, dashes, ellipses, invisibles, ligatures, bullets, symbols, fractions, emoji) and speaks structured tokens — phone numbers, emails, URLs — clearly (announce / speak / speak-then-repeat, with a long-URL threshold). It also speaks publication shorthand (Vol.→“Volume”, No.→“Number”) and resolution-style numbers (2025-02→“2025 dash 2”), both on by default and opt-out (ACB pipeline learnings). Opt-in via the tts_normalization setting and carried per project.

SSML. An SSML Builder dialog composes <speak> markup (emphasis, <break>, say-as, phoneme, prosody) from accessible controls with a source preview. Read Aloud renders SSML natively on SAPI 5 and eSpeak-NG (markup mode), passing utterances through intact (no punctuation verbalization that would corrupt the markup).

5.25e Build Audiobook from Folder — ChapterForge surface (shipped)

The ChapterForge-aligned “folder of audio → one chaptered master” feature (design source: the sibling ChapterForge project; only the surfaces that fit QUILL’s audiobook vision are ported). Audiobook building is folded into the Audio Studio wizard (Tools → Speech → Audiobook & Batch Speech…) — the combine audio files journey goes straight to it, and in the narrate documents journey the book page’s Assemble the results into one audiobook reveals the book tags (title/author/narrator/genre/year), a cover-image picker, the book format, and a save-as path. After the documents are synthesized (one chapter per document), the produced — plus any pre-recorded — audio in the folder is combined into a single chaptered MP3 (ID3 CHAP/CTOC) or M4B (native MP4 chapter atoms) master. Implementation: wx-free quill/core/speech/audiobook.py — folder scan + natural sort, title_from_filename (strips a leading track prefix), find_cover (preferred-name image discovery), probe_duration_ms (ffprobe), and the ffmpeg concat-demuxer build (chapters from chapters.compute_chapters, tags + cover from FFMETADATA / attached picture; MP3 chapters via mutagen). The book’s tags and an auto-detected cover are written, and the build runs on the background task pool. (The former standalone audiobook_builder_dialog.py was retired into this dialog so the two near-identical surfaces share one accessible path.)

• Run diagnostics and progress. The batch dialog also exposes a temporary files folder (each run gets a quill-batch-<timestamp> scratch subfolder) and a Save the text sent to speech option (writes a <doc>.spoken.txt sidecar of the exact normalized/pronounced/polished text). A timestamped diagnostic log is opened in the output folder before conversion starts (quill/core/speech/conversion_log.py) and records discovery, per-document progress/timings, skips, errors, and the book build. Progress is shown in a focused, screen-reader-announced AIProgressDialog (percentage = words processed / total words) that can be minimized to the status bar.
• Chapter granularity and review. In the consolidated flow each document (or each pre-recorded file) becomes one chapter, titled from its heading/filename. Ticking Review chapters before building (and always, for a folder of pre-recorded audio) opens audiobook_chapter_editor_dialog.py after synthesis — the rename/reorder/merge editor from the old standalone builder — whose edited plan flows through audiobook.chapters_from_plan (AudiobookChapter.extra_paths carries merged files). The runner shows it by marshalling the modal to the UI thread and blocking the background worker until the user closes it.
• Automation + listening extras (shipped). quill/core/watch_audiobook.py registers the build_audiobook watch action (WATCH-10) in the default registry: an arriving audio file rebuilds its folder’s <folder> - Master.<fmt>; a master newer than the trigger file skips, so dropped batches coalesce to one build. Library mode (library_mode request field, combine-audio journey): the runner builds one unattended book per subfolder (title = folder name, review editor suppressed, per-book errors isolated). Workbench Split into files… cuts the open master into per-chapter files via audio_edit.split_into_files (podcast-episode mode). Player extras: listening_positions.py (app-data store keyed by path+size; the Workbench resumes where the user stopped and records on close), a pitch-preserving playback speed choice (engine set_rate, WMP SetPlaybackRate), and Where am I? — a spoken glance of chapter n-of-m, elapsed/left in chapter, and position/remaining in the book.
• Publishing (shipped). quill/core/publish/: rss.py (RSS 2.0 + iTunes + Podcasting 2.0 feed generation, pure XML, chapters linked to the …chapters.json sidecar; local file write only), destinations.py (saved SFTP destinations, atomic JSON, no secrets on disk — passwords under quill:publish:sftp:<name> in the Credential Manager), sftp_publish.py (streams the book + companions via core/ssh/client.connect, so SEC-9 host-key policy holds), and auphonic.py (compact client for the user’s own account: presets, account_info username/credits, multipart upload + start via the simple API — preset_uuid honored — status poll, result download; token under quill:publish:auphonic; single reviewed egress site; the publish dialog’s “Check account and load presets” fills an accessible preset picker and the send confirmation names the preset and credit balance; the token is also managed in AI Hub > Services beside the other service keys; OAuth was considered and deliberately deferred — it needs a registered Auphonic client app, and the token flow with vault storage meets the same no-secrets-on-disk bar). UI: the Workbench’s Publish… button opens publish_dialog.py (three sections, each an explicit action; Auphonic confirms before upload; dirty chapter edits must be saved first; refused in Safe Mode). Egress-audit entries for the lookup and Auphonic sites. Transfer progress + cancel: both transfer paths report real byte progress and honor cancel — publish_files threads paramiko’s sftp.put callback into on_bytes(name, sent, total)/is_cancelled (raising PublishCancelled aborts mid-file; completed files stay), and the Auphonic client streams uploads through a file-like _ProgressReader (Content-Length preserved, so urlopen remains the single audited egress site) and downloads in blocks, raising AuphonicCancelled between blocks. The dialog shows an AIProgressDialog with whole-percent throttled updates (never per-block, so the UI queue and screen reader aren’t flooded), mirrors progress to the status bar via the frame’s background-task progress contract, and announces the exact cancel outcome (SFTP: completed files stay; Auphonic pre-upload-complete: no production started; after: production continues in the account, download skipped).
• AI chapter titles + voice casting (shipped). Titles: quill/core/speech/chapter_titles.py — slice_chapter_opening (pure ffmpeg argv builder + safe_subprocess runner; 16 kHz mono, whisper’s shape), transcription via the installed offline model (transcribe.transcribe_audio_file; audio never leaves the machine), propose_chapter_titles sends only the transcript to the caller’s ask callable (the frame’s Assistant.ask, absent in Safe Mode) with a strict short-title prompt, clean_title normalizes replies (strips quotes/prefixes/periods, clamps to 8 words) and any per-chapter failure keeps the existing title. Workbench: Propose AI titles… — consent dialog states the exact data flow, runs on the background pool, proposals land through the same _apply path as silence proposals (review-first, Restore original undoes; Pod-2.0 url/img preserved). Casting: quill/core/speech/casting.py — ordered (pattern, voice) rules; #N matches section number (1-based), anything else is a case-insensitive fnmatch glob on the heading title; first match wins. document_speech._build_casting builds one wrapped synthesizer per cast voice (same engine/pace = one PCM format; pronunciation + failure-recording wrappers; blacklisted voices lose their rules) and assemble_chaptered_audio consults the new synthesizer_for(index, title) seam before the rotation. BatchSpeechRequest.casting_rules rides job files (typed load in job_file.py); the wizard’s voice page has the pattern + voice + Add-rule editor with a first-match-wins list (engine change clears it, like the rotation). Remaining nicety: persisting casting rules in the project profile (schema v3), as with translation targets.
• Incremental rebuilds (shipped). quill/core/speech/synth_cache.py: fingerprint(source, settings) = SHA-256 over the document’s bytes + settings_digest (canonical sorted JSON of every audio-shaping setting; secrets never enter it); entries persist at <source folder>/.quill/speech-cache.json (classified cache in the persistence audit — regenerable). The batch runner builds the settings map once per run (engine/voice/rate/speed, format, sounder id+volume, gaps, spoken headings, combine-headings, loudness, round-robin, translations + provider, dictionaries digest) and, per document, reuses the existing output when can_reuse matches — counted as skipped with the message “Reused (unchanged since last run)”. Gated by BatchSpeechRequest.reuse_unchanged (default True; checkbox on the wizard’s output step) and active only on the chaptered path with the overwrite policy — never on dry runs, auditions, skip, or rename. Any settings change invalidates every fingerprint by construction.
• Folder feeds (shipped). quill/core/publish/feed_folder.py: a folder of masters run as one show. FeedFolderConfig (show title/author/description, media URL base, feed URL, cover URL, per-episode title/description overrides) persists atomically at <folder>/.quill/feed.json (same project dir as the speech profile). discover_masters orders MP3/M4B/M4A oldest-first (episode 1 = oldest); folder_feed_items builds one FeedItem per master — title from override else tags (read_book) else stem, duration via ffprobe when available (0 otherwise, never fatal), has_chapters from the sidecar, per-episode pubDate from file mtime (rss.rfc2822); write_folder_feed regenerates <folder>/feed.rss on demand (refuses an empty folder); write_show_notes writes an accessible show-notes.html (h1 show / h2 episodes / h3 chapters, all text escaped, no scripts). rss.py items now carry per-episode pub_date and a stable non-permalink guid. Chapter gained Podcasting 2.0 url/image fields, emitted as url/img in chapters_to_pod2 (omitted when empty) and preserved through Pod-2.0 import in parse_chapter_text. UI: feed_dialog.FolderFeedDialog (from the Publish dialog’s “Folder feed (all episodes)…” button) — show fields, an accessible episode ListBox with apply-to-selected title/description editing, “Write feed.rss now”, “Write show notes page”; config saved on every write. All local file IO; uploading stays the SFTP destination’s explicit job.
• Job files, lookup, audition, credits (shipped). .quilljob files (quill/core/speech/job_file.py): a portable JSON recipe pinning every BatchSpeechRequest field, written atomically, loaded tolerantly (unknown keys ignored, missing keys keep defaults) — saved from the wizard’s summary page, loaded from its start page (the wizard reopens pre-filled). Look up book details (quill/core/metadata_lookup.py): Open Library + MusicBrainz search behind one reviewed egress site (_http_json, HTTPS-only, verified TLS, MusicBrainz 1-req/s throttle, consent stated before the first call; entry in network_egress_audit.py); results in an accessible single-choice list, chosen match fills the tags. Cover art: Open Library matches carry cover_i (LookupResult.cover_id); after a pick, if the cover field is empty the book page offers a second consented fetch — fetch_cover downloads the -L.jpg jacket from covers.openlibrary.org (?default=false so a missing cover 404s; payloads under 1 KB rejected as placeholders) to cover.jpg in the source folder (own reviewed egress entry metadata_lookup.py::fetch_cover). Audition (audition request field): discovery slices to the first document. Spoken credits (book_credits; quill/core/speech/credits.py): opening/closing announcements synthesized with the run’s own spec ride as the first/last chapters, best-effort (a credits failure never sinks the book).
• Chapter Workbench + player (shipped). The Studio’s third journey, Edit an existing audiobook (quill/ui/audio_studio/chapter_workbench.py): book_file.py reads tags/chapters/duration from an existing MP3 (ID3 CHAP/CTOC + text frames via mutagen) or M4B (one ffprobe -show_format -show_chapters call); a chapterless file opens as one chapter. The Workbench pairs the chapter list (real times in every row) with the ported ChapterForge PlayerPanel (player_panel.py) over an engine protocol (audio_engine.py, default backend wx.media.MediaCtrl/WMP — no new native dependency; the mpv backend is now implemented: mpv_engine.MpvAudioEngine, a minimal ctypes binding over the libmpv client API — create/initialize/command/get-set property/destroy — with a wx.Timer polling duration/eof-reached so every call and callback stays on the UI thread; create_engine prefers it whenever find_libmpv() locates libmpv-2.dll in engine-packs/mpv, beside the executable, or via QUILL_LIBMPV, and any mpv failure falls back to wx.media; the DLL is never bundled — it is a pinned assets-v1 component (ASSETS["libmpv"]: libmpv-pack.zip, stable-anchored — the shinchiro 2025-12-28 weekly, mpv git a58dd8a, the first prebuilt after the v0.41.0 stable tag (upstream publishes no DLL of the exact tag); DLL byte-identical to upstream, SHA-256-pinned, expect_member="libmpv-2.dll"; the zip carries GPLv2/GPLv3 texts, mpv’s Copyright, and a corresponding-source offer, the same GPL redistribution posture as the liblouis braille pack) surfaced as “mpv player engine” in Help > Download Optional Components (download_libmpv, Safe-Mode-blocked, background progress)): Play/Pause, Stop, Previous/Next chapter, Rewind/Forward, spoken position slider, volume, and chapter-crossing announcements. Surgery buttons drive the tested core ops — Split at playhead, Set start to playhead, Merge, Restore — plus full chapter-list import/export and in-place tag editing. Saving: MP3 in place (tag frames only, audio untouched), M4B as a lossless -c copy re-mux (save_m4b_book_as; in-place is refused with a speakable message). Long saves run on the background pool.
• Shared listening modules + workbench player-observation contract (shipped). The Workbench player (player_panel.py) gained a Mute button (caches the pre-mute volume, restores on unmute, announces the state), public transport (play_pause/stop_playback/next_chapter/previous_chapter/apply_book_prefs), and per-book volume/mute applied on load via BookPrefs (quill/core/audio_studio/book_prefs.py). open_book_in_workbench and ChapterWorkbenchDialog now thread optional host callbacks — on_player_ready(player, path), on_finished(path), on_volume(path, pct), on_mute(path, muted), on_closed(path, position_ms, chapter) — down to PlayerPanel; embedded QUILL passes none, so its single call site is unchanged and fully backward compatible. New wx-free stores in quill/core/audio_studio/: library.py (book entries + user folders), history.py (Recently Played), play_queue.py (ordered queue + next_entry), sleep_timer.py (SleepTimerSetting + SleepTimerWatcher). New shared UI: library_tree.py (Favorites / In Progress / Recently Played / Inbox groups + folders + a keyboard-complete context menu), play_queue_dialog.py, sleep_timer_dialog.py. Each save_* site is classified content in the persistence audit, every focusable control carries an accessible name (audited by accessible_name_audit), and each new dialog is registered in the dialog inventory. The two Workbench helper dialogs (SilenceParamsDialog, AcxResultDialog) moved to chapter_workbench_dialogs.py to keep chapter_workbench.py within the GATE-11 size ratchet (the ratchet only decreases). (What the gated standalone Studio shell wires those host callbacks up to is recorded in docs/audio-studio/README.md.)
• Chapter power tools (core). quill/core/speech/chapter_io.py imports/exports chapter lists in five formats (Audacity labels, plain timestamps, CUE, Podcasting 2.0 JSON, CSV — import auto-detects, including any CSV with a Title column); chapters.py gained the surgery ops (merge_chapter, split_chapter at a millisecond point, set_chapter_start retiming, clamp_chapters) with speakable ChapterEditError messages; silence.py proposes chapters at detected silences (always reviewed, never applied blind) and trims head/tail silence; audio_edit.py provides trim/fades/pitch-preserving tempo/split-master-into-chapter-files. All wx-free, strict-typed, and unit-tested (test_chapter_io.py, test_chapter_edits.py, test_silence.py, test_audio_edit.py).
• Pre-flight, estimate, verification, sidecars. Before a book build the runner logs a pre-flight stream check (preflight_check names files whose sample rate/channels/codec differ — the build still proceeds; it re-encodes) and a duration/size estimate. After the build, verify_audiobook re-reads the master (ID3 CHAP via mutagen, or M4B chapter atoms via ffprobe) and the summary reports “verified N chapters” or the exact issues. write_book_sidecars drops a plain-text chapter report and the Podcasting 2.0 …chapters.json next to every book. The review editor adds Remove, Restore original, Import titles… (all chapter_io formats), and Export titles….
• ACX loudness. A Normalize to ACX option applies an ffmpeg loudnorm pass (targeting RMS ≈ -20 dB, true-peak -3.1 dB) during the existing re-encoding build, so chapters/tags are preserved. After the build the master is measured with volumedetect and the RMS/peak verdict against ACX’s -23…-18 dB / -3 dB window is surfaced in the completion status (quill/core/speech/loudness.py). FLAC/Opus output is intentionally not offered — neither carries chapter markers (both stay accepted as source files).
• Deferred to 2.0 (docs/planning/roadmap.md §5): direct publishing (#140, WordPress/etc., a likely-Quillin integration) and the off-vision ChapterForge surfaces — Auphonic post-processing, RSS podcast feeds, SFTP publishing, and MusicBrainz/Open Library metadata lookup.

5.25g Universal Audio Converter (shipped, #1255)

A general-purpose audio format converter — distinct from the audiobook/speech pipeline — that changes audio files between formats and extracts audio from video, entirely on-device through the bundled FFmpeg.

• One engine, three public surfaces. A single wx-free engine (core/audio/convert.py, presets.py, dsp.py, url_import.py, convert_cli.py) is surfaced through: the audiobook/batch-speech dialog (Voices → Convert Audio…, ui/audio_studio/convert_audio_dialog.py); a headless quill convert CLI; and Convert from URL (on-demand yt-dlp, consent-gated, egress-audited). (Two further surfaces — the standalone Quill Converter app and the Windows Explorer “Convert with Quill” shell verb — are gated out of the public 1.0.0 build and are documented in docs/apps/converter/README.md.)
• Formats & capability probe. Output formats are filtered to what the resolved FFmpeg can actually encode (available_output_formats parses ffmpeg -encoders); WAV/AIFF/CAF are always available. Video inputs auto-extract their audio track.
• Presets. just_convert, mp3_128/192/320, podcast, audiobook, voice_memo, web_opus, archival_flac, hearing_aid_mono.
• Advanced DSP catalog (§6). Bit rate (CBR) / sample rate / channels / bit depth, plus loudness-normalize (audiobook −20 LUFS / podcast −16 LUFS), gain, high-pass, trim silence, tempo (no pitch shift), compressor, leveler, and fades — composed by dsp.build_dsp_filters from the same tested filter builders used elsewhere (audio_enhance, speech.loudness, speech.audio_edit).
• Batch model. Mixed file/folder queue with source-tree mirroring, a conflict policy (auto-number / skip / overwrite), multi-worker off-thread execution with tray-aware progress, and a spoken summary that names failures (never a silent success). Temp-then-move writes; pure argv command building (build_convert_command).
• Safety. Fully offline through bundled FFmpeg, so available in Safe Mode. Only URL import touches the network: yt-dlp is never bundled, installs on demand after an explicit consent + rights notice, is recorded in the network-egress audit (YoutubeDL marker), and is refused in Safe Mode.
• Gated for 1.0.0: the standalone app and its Explorer shell verb, with the remaining build work, are recorded in docs/apps/converter/README.md.

5.25a Speech Experience Platform (planned before implementation)

This section defines the next speech milestone as a complete user-facing platform, not a single settings dialog.

Goals:

• Add a first-class Speech submenu under the top-level AI menu.
• Add two downloadable local speech engines: Kokoro and Piper.
• Keep DECtalk and eSpeak NG as bundled local engines for immediate read-aloud availability.
• Provide voice lifecycle UX end to end: discover, download, preview, set preferred, configure, remove.
• Keep installer size lean by making heavier engines download-only while preserving bundled fallback voices.
• Preserve screen-reader-first behavior with predictable announcements, keyboard-first flows, and no surprise network actions.

5.25a.1 AI menu information architecture

The top-level AI menu gains a Speech submenu with discoverable, keyboard-rebindable commands:

• AI -> Speech -> Open Speech Center...
• AI -> Speech -> Browse Voice Library...
• AI -> Speech -> Download Voices...
• AI -> Speech -> Preview Current Voice
• AI -> Speech -> Set Preferred Voice...
• AI -> Speech -> Manage Installed Voices...
• AI -> Speech -> Speech Settings...

The Speech submenu mirrors the command palette and status surfaces, with live keybinding labels exactly like other menu items.

5.25a.2 Engine model and no-bundle policy

Supported engines for this milestone:

• windows-native (existing SAPI/OneCore path)
• dectalk-local (bundled)
• espeak-local (bundled)
• kokoro-local
• piper-local

Policy:

• DECtalk and eSpeak NG ship with QUILL as local bundled engines.
• No Kokoro or Piper voices are bundled in installer or portable artifacts.
• Voice models are downloaded on demand into %APPDATA%\Quill\speech\voices\....
• Downloads require explicit user action and clear size disclosure before start.
• Speech onboarding includes preview-first guidance and availability announcements before model download.
• Read Aloud is not English-only (0.9.0). The voice catalogs are multilingual: the Windows engine lists every installed system voice in any language; the Kokoro catalog includes the Spanish, French, Hindi, Italian, and Brazilian Portuguese voices already contained in its downloaded model (synthesis passes the matching language code per voice); the Piper catalog includes the published Italian voices, and its downloader resolves HuggingFace URLs for any lang_REGION-name-quality id; the eSpeak catalog lists the same non-English language set (its data directory ships all languages). Catalogs live in quill/core/voice_catalog.py. Japanese and Mandarin Kokoro voices are deliberately excluded until a proper G2P dependency is added.

5.25a.3 Voice library and download UX

Speech Center includes a searchable voice catalog with filters:

• engine (Windows Native, Kokoro, Piper)
• language and region
• gender/style tags where available
• size band (small/medium/large)
• installed vs not installed

Each voice row exposes:

• voice name and engine
• language and locale
• on-disk size
• install state
• preferred marker

Download behavior:

• resumable downloads with progress and remaining size
• hash verification before activation
• cancellation without corrupt partial state
• failed-download recovery with retry guidance

5.25a.4 Voice preview and A/B comparison

Users can preview voices before and after install.

• Preview text field with stock sample text button
• A/B preview mode for rapid compare between two selected voices
• playback controls: play, stop, replay
• optional “Preview with current speaking settings” toggle

When pre-install preview audio is available from metadata, Quill may fetch a small sample clip on demand. If no preview clip exists, preview requires install and Quill states this clearly.

5.25a.5 Preferred voice and defaults model

Users can star one voice as Preferred with one command.

Resolution order for active voice:

1. explicit per-document override (future-compatible field)
2. explicit per-language preferred voice
3. global preferred voice
4. engine fallback voice

Setting a voice as preferred is immediate and announced in plain language.

5.25a.6 Per-voice configuration and platform defaults

Every installed voice has editable settings saved as a profile, and users can mark any profile as default.

Per-voice settings (minimum set):

• rate
• pitch
• volume
• pause style and punctuation pause behavior
• sentence/paragraph chunk size
• output device selection

Platform-aware defaults:

• Windows native voices keep their own defaults
• Kokoro and Piper voices each keep separate defaults
• users can apply “Use as default for this engine” or “Use as global default”

This gives users both broad defaults and precise per-voice control.

5.25a.7 Voice removal and storage hygiene

Manage Installed Voices supports safe removal:

• remove one voice
• remove all voices for selected engine
• show reclaimed disk size before confirmation
• preserve user settings history without dangling references

If the removed voice was preferred, Quill prompts for a replacement or applies deterministic fallback and announces it.

5.25a.8 Speech onboarding flow

First-time speech onboarding starts when the user opens Speech Center with no installed downloadable voices.

Flow:

1. Explain available engines and that voices are optional downloads.
2. Ask preferred language/locale.
3. Recommend starter voices for Kokoro and Piper.
4. Offer quick preview where possible.
5. Download selected voices.
6. Ask user to mark preferred voice.
7. Offer one-click “Make these settings my default”.

The onboarding flow can be re-run via Help -> Run Onboarding Again and AI -> Speech -> Open Speech Center....

5.25a.9 Accessibility and safety requirements

• Every Speech Center control is a stock wx control with correct label, role, and state.
• Progress updates are announced without flooding speech output.
• No auto-downloads or silent background network actions.
• All destructive actions (remove voice, reset defaults) require confirmation.
• All errors are plain-language and actionable.

5.25a.10 Delivery phases (bold, realistic)

Phase 1: Foundation

• AI menu Speech submenu
• Speech Center shell
• installed-voice management for existing Windows native voices

Phase 2: Downloadable voices

• Kokoro and Piper catalog
• download, verify, install, remove
• preferred voice and per-engine defaults

Phase 3: Advanced polish

• A/B preview panel
• storage budget manager and cleanup recommendations
• per-language preferred voice routing
• richer voice profile presets (Narration, Proofread, Fast skim)

5.25a.11 Acceptance criteria

• A new user can install at least one Kokoro or Piper voice in under 3 minutes from Speech Center.
• A user can preview at least two voices and set one preferred without opening Settings.
• A user can remove a voice and recover disk space with clear confirmation and fallback behavior.
• All commands are available through menu, command palette, and keybindings.
• Installer size does not increase due to bundled voice payloads.

5.25a.12 DECtalk compatibility evaluation track

Quill should explicitly evaluate adding DECtalk as an optional speech engine path.

Why consider it:

• DECtalk remains important to many long-time screen-reader and speech users.
• It offers a distinctive speech character some users actively prefer for proofreading and navigation tasks.
• Community-maintained projects (including modern build efforts) suggest practical integration paths worth exploration.

Plan scope (evaluation first, not automatic ship):

• Add dectalk-local as a candidate engine in Speech Center behind an experimental flag.
• Prototype voice discovery, preview, and preferred-voice selection through the same Speech lifecycle model used for Kokoro and Piper.
• Keep no-bundle policy: no DECtalk voice payloads included in installer or portable builds.

Hard gates before general availability:

• Licensing and redistribution clarity: legal review confirms what can be downloaded, redistributed, or user-supplied.
• Accessibility parity: DECtalk path must pass the same screen-reader announcement, keyboard-only, and status reporting requirements as other engines.
• Stability and performance: startup, preview, and long-form read-aloud must meet baseline responsiveness and failure-recovery standards.
• Configuration parity: preferred voice, per-voice settings, per-engine defaults, and removal behavior must match other engines.

User experience requirements if approved:

• DECtalk appears in AI -> Speech as another engine option, not a separate workflow.
• Voice install/onboarding language is plain and explicit about source, size, and any licensing constraints.
• Users can preview and set a DECtalk voice as preferred in one flow.
• Users can remove DECtalk voices and recover storage with deterministic fallback behavior.

Positioning:

• DECtalk is treated as a high-value compatibility and user-preference path.
• It does not replace Windows native, Kokoro, or Piper; it complements them when available and compliant.

5.26 Number lines and strip line numbers

A small tool that addresses a real recurring user request.

• Tools → Number Lines… opens a dialog with format options: 1., [1], 1:, 1), 001, and a custom Python str.format template using {n}.
• Start index, increment, zero-padding, and “only number non-blank lines” options.
• Applies to the whole document or selection.
• Tools → Strip Line Numbers reverses by regex; the regex used to add numbers is also the regex used to strip them.
• Undo is one step; the tool reports Numbered 482 lines or Stripped numbers from 482 lines.

5.27 Open from URL

• Ctrl+Alt+O opens a small dialog with a URL field. Accepts http://, https://, raw GitHub URLs, gist URLs, and Pastebin URLs.
• Quill downloads the resource to a per-session temp file, detects the format from the response Content-Type and the URL extension, and opens it with the appropriate reader.
• Network announcement: the dialog shows the host name and an estimate of bytes (where the server reports Content-Length) before download starts; the download is cancellable.
• The opened document has the URL as its display path, no associated file on disk; Ctrl+S opens Save As.
• Redirects are followed up to 5 hops; redirects to a different host prompt for confirmation.
• All TLS errors and 4xx/5xx responses are reported with a single readable sentence, no stack traces.

5.27a Remote Sites (FTP, SFTP, HTTPS, WebDAV, S3)

Remote I/O is the natural extension of “Open from URL”: once a user has a saved site, opening and saving is one click, with the same explicit-safety guarantees.

• File menu → Open from Remote (default key: QUILL key then R) opens a two-pane site list + remote directory browser. Sites are sorted alphabetically; the user can search/filter. The dialog uses native wx controls; the directory pane is a stock wx.ListCtrl so screen readers can read filenames in order with no synthesized markup.
• Save to Remote (QUILL key then Shift+R) and Save Copy to Remote… (menu only) use the same dialog in a “Save” mode that includes a target file name field.
• Manage Remote Sites… (QUILL key then Shift+M) opens the site list editor with New site… / Edit site… / Delete site buttons and a per-protocol sub-dialog (FTP, SFTP, WebDAV, S3) that validates required fields before enabling Save.
• A site is RemoteSite(id, name, protocol, host, port, username, root_dir, trust_first_use, extra) with protocol-specific fields in extra (e.g. s3_bucket, webdav_base, s3_endpoint, s3_region, s3_access_key, s3_secret_key). Sites are persisted to %APPDATA%\Quill\remote-sites.json via atomic write; passwords are persisted separately through quill/core/remote_sites.py using the Windows Credential Manager → DPAPI file → macOS Keychain ladder.
• Five transport modules live in quill/io/, all wx-free:
  • remote_transport.py — RemoteTransport ABC + RemoteEntry, DownloadResult, RemoteTransportError/RemoteAuthError/RemoteNotFoundError, chunked_copy, merge_headers.
  • http_transport.py — download_url(url, *, timeout, progress, max_bytes) -> HttpDownload with verified TLS, default _MAX_BYTES cap, visible progress.
  • ftp_transport.py — FTP and FTPS open/save, MLSD time parser, listing normalization.
  • sftp_transport.py — paramiko SFTP open/save; honours settings.ssh_trust_first_use and paramiko.AutoAddPolicy.
  • webdav_transport.py — depth-1 PROPFIND directory listing, basic auth, parsed through quill.core.safe_xml.fromstring to refuse DTD/entity expansion.
  • s3_transport.py + s3_sigv4.py — manual AWS SigV4 signer for Amazon S3 and any S3-compatible endpoint; boto3 path is opportunistic and falls back to the signer when boto3 is missing.
• A document opened from a remote site is read-only by default; the title shows (from site:path) so the user always knows where it came from. Save on a read-only remote document opens Save Copy to Remote… instead of overwriting the remote.
• Network egress is gated by quill/tools/network_egress_audit.py; every transport call site has a written rationale. The audit is a CI gate.
• All Save to Remote writes use the SSH-style tilde backup: a copy of the previous file lives next to the target as <name>~, written in the original newline style.

5.28 Format-aware bracket and quote navigation

• Ctrl+] and Ctrl+[ already navigate by block in editor-mode (5.17); when inside a code-aware context (code file, Markdown code fence, HTML tag), they instead jump to the matching bracket, quote, fence, or HTML tag.
• Ctrl+Shift+\ is the explicit “Match Bracket” command (also reachable from Navigate menu).
• Ctrl+Shift+] extends the selection from the cursor to the matching bracket.
• Bracket matching is language-aware: respects strings and comments in supported languages; Markdown respects fence boundaries.
• The match is announced as Matched bracket on line N, column C so screen-reader users do not lose context.

5.28a Document Language profiles and auto-detection (#181)

Each document has a language profile (quill/core/language_profile.py) describing one programming/markup language: extensions, indent convention, comment syntax, brackets, keyword set, and a markup_kind ("html", "markdown", or "plain"). Recognised languages: HTML, Markdown, CSS, Python, JavaScript, TypeScript, C, C++, C#, PHP, Go, Rust, Kotlin, Shell, YAML, JSON, TOML, SQL, plus a plain-text fallback. The profile is wx-free, pure data.

• Auto-assignment. On open and on tab creation the profile is set from the file extension (get_profile_for_path), unless the user has pinned one.
• User override. set_document_language pins a profile for the current tab (_DocumentTab._language_profile + _language_profile_pinned). Reachable via navigate.set_language (default Ctrl+Shift+L), Navigate > Set Document Language…, the Format > Document Language radio submenu (Auto-detect + every profile + Plain text, current item checked), and Enter on the status-bar Language segment (which appends “(set)” when pinned). “Auto-detect from file” clears the override.
• The pin drives editing characteristics. A pinned profile is the source of truth ahead of path/content inference via _pinned_markup_kind(), _current_markup_context(), and _effective_markup_kind(): bold/italic surface, the heading/table/list/tag menu enablement, comment toggling (format_ops.toggle_line/block_comment accept the profile), heading and structure navigation, the outline, link insertion, and live preview all follow it.
• Editing aid, not a rename. Pinning never changes the file format; when the profile’s extension doesn’t match the file, a Save As hint is announced. The override is tab-only (not persisted across reopen).

Automatic detection (quill/core/language_detect.py, wx-free, deterministic, no ML) scores the buffer over the languages above using weighted structural signals, then applies confidence discipline modelled on VS Code’s detector: an absolute floor, a relative margin over the runner-up, ambiguity penalties (YAML/TOML/SQL), optional session-history bias, and a should_switch() hysteresis gate. It returns language=None (plain) when unsure and does not misfire on prose or ASCII-braille.

• Setting: language_detection_mode ∈ {off (default), hint, prompt, auto}, exposed in Settings > Editing.
• Trigger: LanguageDetectMixin debounces content changes (~800 ms) and runs only on unpinned untitled/.txt-like documents; it never overrides a real extension or a user pin.
• Behaviour by mode: hint updates the status bar silently; prompt announces a dismissible suggestion; auto calls set_document_language and announces the change. A screen-reader user is informed in every mode (no silent or visual-only switch). Braille content is out of scope — Braille Mode owns it.

5.29 Format menu (text transforms, no styling)

A dedicated menu surfacing transforms that are otherwise reachable via Tools or shortcuts. The menu exists because discoverability matters more than purity.

• Capitalisation: Upper Case, Lower Case, Title Case, Sentence Case, Toggle Case.
• Lines: Move Line Up/Down, Duplicate Line, Delete Line, Join Lines, Toggle Line Comment, Toggle Block Comment.
• Indent: Indent, Outdent, Convert to Tabs, Convert to Spaces, Set Indent Width….
• Markdown helpers: Insert Heading (levels 1–6), Insert Bullet List, Insert Numbered List, Insert Task List, Insert Table…, Insert Block Quote, Insert Horizontal Rule, Insert Link…, Insert Code Block, Insert Footnote.
• Format-aware structured inserts: block quote, horizontal rule, table, and image resolve the document’s markup (Markdown vs HTML) through a single _resolve_structured_markup chokepoint. When the surface is known (by pin, extension, or content sniff), it is used; when it is not (a fresh/unsaved/plain buffer), the user is asked “Markdown or HTML?” once, the choice is remembered on the tab (structured_markup_choice) and pins the markup kind so later inserts and menu state agree without re-asking. Insert Block Quote and Insert Horizontal Rule are menu-driven with no default keybinding (§10.8 bars new Ctrl+Alt chords and the QUILL-key leader space is saturated); users assign their own via the Keymap Editor, consistent with Insert Table.
• Markdown list editing behavior: Enter continues bullet/numbered/task items, Enter on an empty marker exits the list, and Tab/Shift+Tab nest or promote list items when the caret is on a list line.
• List Manager: Format -> List -> List Manager... (Ctrl+Alt+L) opens a keyboard-first tree editor for moving, promoting/demoting, adding, editing, and deleting list items.
• Magical tag helpers: Insert HTML Tag… (with attribute picker) and Insert Markdown Tag… (semantic snippet picker).
• Snippet helpers: Insert Snippet… (Ctrl+Alt+Space) and Manage Snippets… (Ctrl+Alt+Shift+Space) with searchable filtering, placeholder prompts, and starter-pack onboarding.
• Prediction helpers: Word Prediction… (Ctrl+.) with words, HTML tags, and Markdown tag completions.
• Surface-aware formatting shortcuts (Markdown/HTML only): Ctrl+B bold, Ctrl+I italic, and heading levels Ctrl+Alt+1 through Ctrl+Alt+6.
• Re-flow: Wrap to Column…, Re-flow Paragraph.

5.29a Magical HTML and Markdown tag picker

• Format → Insert HTML Tag… opens a keyboard-first picker of common tags (section, article, headings, list/table tags, inline emphasis, links, images, code).
• After selecting a tag, Quill prompts for optional attributes in a compact key=value; key2=value2 format and inserts valid tag text into the editor.
• If text is selected, Quill wraps the selection in the chosen non-void tag. If not selected, Quill inserts an opening/closing pair and places the cursor between them. Void tags (img, br, hr, input) are inserted self-closing.
• Format → Insert Markdown Tag… opens a semantic picker (Bold, Italic, Inline Code, Code Block, Heading, List, Task List, Blockquote, Link, Image, Table, Footnote) and inserts the matching markdown snippet.
• For Link and Image, Quill asks for the target URL and composes the final markdown in one action.
• All picker actions are mirrored in the command palette and are keybindable through the keymap system.
• Edit → Insert Link… (Ctrl+K) uses a format-aware inserter: markdown links in Markdown docs, <a href> in HTML docs, and text (url) form in plain text.

5.29b Snippet insertion and trigger expansion

• Snippets are stored locally under %APPDATA%\Quill\snippets\snippets.json with atomic writes.
• Format → Insert Snippet… opens the same keyboard-first searchable picker pattern used across Quill insertion flows.
• Supported placeholders in snippet bodies: ${input:name}, ${choice:a|b}, ${date}, ${time}, ${cursor}.
• Trigger expansion can run while typing (for example ;meeting plus a delimiter), and remains user-controllable via General Preferences.
• Starter packs are installable from Preferences and snippet management so onboarding can begin with practical templates.

5.29c Word prediction and tag IntelliSense

• Ctrl+. opens a prediction picker that reuses the same accessible searchable-pattern UX as other insertion dialogs.
• Predictions draw from the current document words, the merged spell dictionaries, and the HTML/Markdown tag vocabularies Quill already ships.
• When enabled in General Preferences, the same helper can auto-refresh while typing so the prediction list follows the current fragment.
• Accepting a prediction inserts the chosen word or tag completion at the caret; Escape dismisses the popup without changing text.

5.30 Bookmark export and import

• Tools → Bookmarks → Export… writes the bookmark set for the current document to a single JSON file alongside its hash so it round-trips cleanly.
• Tools → Bookmarks → Import… adds bookmarks from a file, with a preview dialog showing each bookmark and a per-row checkbox.
• Conflict resolution: on import, identical names produce a numbered suffix; identical positions are merged.
• A second action, Tools → Bookmarks → Export All…, writes every bookmark across every document the user has ever opened, useful for moving machines.

5.31 Trusted locations (Office-style)

• Settings → Privacy → Trusted Locations is a list of folders Quill opens without extra prompts.
• Files opened from outside trusted locations that are unusually large (default >25 MB), password-protected, or in a Grade B/C format show a one-time prompt: Open <path>? with Open, Open and Trust this folder, Cancel.
• Network-mounted folders are never auto-trusted; a setting must enable them explicitly.
• The trusted locations list is editable, exportable, and importable.

5.32 Jump List and shell integration

• Windows Taskbar Jump List shows Recent Files (last 10) and Pinned Files; Tasks include New Document, Open File…, and Open from URL….
• Implementation via pywin32’s ICustomDestinationList.
• Shell context menu entries (registered from Settings → Files):
  • Open with Quill for every registered extension.
  • Open with Quill (As Plain Text) for every text-like extension, forcing the plain-text reader regardless of detected format.
  • Open Folder With Quill is deferred to v1.1 (it implies a folder-tree panel).
• All shell verbs install per-user (no admin elevation required) and uninstall cleanly.

5.33 Diagnostics and bug reporting

• Help → Get Help from Support… (Ctrl+Alt+F2) is the unified support flow, in every app in the family (2026-09-11; it was Report a Bug…, and it existed in four of ten surfaces). One shared form – category, subject, what happened, what you expected, steps, an optional reply address, screen reader – built once in quill/ui/support_dialog.py over the pure quill/core/support_message.py, and appended to every Help menu by support_menu.append_get_help_item.
  • The destination is support@community-access.org, never a GitHub issue. Community-Access/quill is public and a support message is somebody’s own words about their own machine; the reasoning is docs/design/2026-08-26-feedback-redesign-for-freescout.md §2(a), and the absence of a GitHub fallback is the enforcement. The old path also gave the reporter no way to be answered – a GitHub issue is not a conversation you can join without an account.
  • Two transports, in order. The submission server when the build has one and the installed feedback-hub accepts server_url (feedback_token.server_transport_available()); otherwise the reader’s own mail client, via a mailto: URL capped at 1,800 characters with the full text placed on the clipboard when it has to be shortened. The app holds no credential on either path.
  • Nothing is sent until the person sends it. The mail path opens their mail program with the message written out and says so in those words; a machine with no mail handler gets the whole message and the address on the clipboard rather than a dead end. The reply address is optional, and the form says a reply is impossible without one rather than refusing to send.
  • The live bug this replaced: submission_kwargs() passed server_url to a feedback-hub 1.1.0 that has no such parameter, so FeedbackDialog(...) raised TypeError and every Report a Bug fell through to the browser fallback. The transport is now read from the installed signature (feedback_token.hub_accepts_server_url()), the same technique issue_submit._submit_parameters already used for the crash reporter.
• Help → Save Diagnostics… remains available for standalone diagnostics export and writes a zip with:
  • the last 7 days of logs (action names and outcomes only; no document content),
  • settings (with API keys redacted),
  • the active keymap,
  • the last 50 commands executed,
  • the screen-reader detection result and version (if available),
  • basic environment info (Windows build, Python build, wxPython build, locale).
• Nothing leaves the machine. The user chooses where to save the zip and what to do with it.

5.33a Crash reports offer to submit (#622)

• When an unhandled exception closes QUILL, the excepthook writes the traceback to a timestamped file under app_data_dir()/crash-reports/, then schedules a crash-submit dialog on the UI thread via wx.CallAfter. The dialog shows a redacted preview (the last 10 commands, the active document’s name and encoding, the platform and screen-reader information, the last 12 traceback frames), three free-text fields (“What were you doing?”, “What command triggered it?”, “Expected behaviour”), and three buttons: Send report, Copy to clipboard, Don’t send.
• The default button is Don’t send so a user who opens the dialog by accident does not accidentally send anything. Escape is bound to Don’t send. Initial focus lands on the What were you doing field so the screen reader announces the first input first, not the buttons.
• Send report calls quill.core.issue_submit.submit_crash_issue with the redacted body and metadata. A configured GitHub token is required; if the token is absent the report is copied to the clipboard instead, and nothing is submitted silently.
• Every step is wrapped in try/except so a misbehaving dialog path can never prevent the local crash file from being saved or the standard interpreter traceback from firing. The native ctypes.windll.user32.MessageBoxW from finding #51 remains the always-on fallback when wx is unavailable, no wx.App is running yet, the user turned the setting off, or the dialog path raised.
• Settings > General > Offer to send crash reports automatically (auto_ask_crash_submit) controls whether the dialog appears; the default is True during the beta phase so the team can hear about crashes without forcing the user to opt in every time. The local crash file is always written regardless of the setting.
• The dialog is added to the dialog inventory and follows the same apply_modal_ids + _show_modal_dialog contract as every other modal in QUILL. The dialog’s parent is the real wx.Frame (MainFrame.frame), not the MainFrame mixin, per the #624 fix in quill/ui/main_frame_hygiene.py.

5.34 Welcome and Keyboard Reference

• Welcome opens a tutorial document in a new tab that walks new users through the editor, command palette, outline navigator, find/F3, spell check, and accessibility audit. The document is editable; users can save their own annotated copy.

• Keyboard Reference is auto-generated from the active command registry and the current feature profile. It is available in two formats:

  1. Markdown Document: Grouped by menu, opens in the editor for easy searching and navigation. 2 la Dynamic HTML Export: A self-contained, accessible HTML page that reflects all active bindings, including custom re-assignments.

  The reference explicitly documents the QUILL Key layered system, including the one-shot Prefix Layer and the locked Browse Layer (Quick Nav). This ensures the reference is a precise mirror of the current editor state.

• Tip of the Day is off by default; when on, it appears once per launch as a small dismissible dialog with a single tip drawn from real palette actions, each tip a one-liner with a Try it button that runs the action.

5.35 Notifications centre

• The status bar’s Notifications cell holds Quill’s announcements: available updates, recovered autosave snapshots offered on launch, finished AI tasks, finished long-running OCR or extraction jobs, and any plugin messages.
• Enter on the cell opens a small Notifications dialog (stock wx.ListBox with timestamps); Delete dismisses individual entries; Shift+Delete dismisses all.
• Quill never raises toast or balloon notifications. All asynchronous events surface here and on the status bar’s Background Tasks cell.

5.36 “What changed on save” (opt-in)

• Off by default. When on (Settings → Reading → Announce save summary), every successful save announces a one-liner: Saved chapter-7.md, 4 lines changed, 38 words added.
• Computed by diffing the previous saved bytes against the new bytes; cheap on documents up to 5 MB.
• Useful for ambient awareness during long editing sessions; trivially ignorable for users who prefer silence.

5.37 Link tools

A small family of related commands that make working with links comfortable for screen-reader users.

• Insert link (Ctrl+K): opens a small dialog with URL and display text fields. If a URL is on the clipboard, the URL field is pre-filled. If a selection exists, it becomes the display text. Enter inserts [text](url) in Markdown, <a href="url">text</a> in HTML, a plain URL in plain text, and a properly escaped link in reStructuredText, AsciiDoc, Org, and Textile. Cancel restores the cursor.
• Insert quoted text (Ctrl+Shift+>): indents the selection by one level of > for Markdown and email-style replies. Ctrl+Shift+< dedents one level. Tools → Strip Quote Markers removes them entirely. Idempotent: re-indenting a block already at level N goes to N+1, not back to 1.
• Follow link (Ctrl+Enter): when the cursor is on a Markdown link, HTML href, or a plain URL, opens it in the default browser. The status bar announces the destination host first (Opening github.com…) so the user always knows what they are about to open. Anchor links inside the current document jump in-editor instead.
• Reveal link target (Ctrl+Shift+Enter): announces the target without opening it (Link target: https://example.com/path).
• Copy link target (Ctrl+Alt+K): copies the URL of the link under the cursor.

5.38 Document properties and front-matter

• Document properties dialog (File → Document Properties…): edit document language (BCP-47 tag), title, author, description, keywords. For DOCX, EPUB, HTML, ODT these write into the document’s metadata in place; for plain text, Markdown, reStructuredText, AsciiDoc, Org, and Typst they write into a sidecar <filename>.quill.yml. The document language drives the spell-check dictionary stack automatically.
• Front-matter editor (Ctrl+Alt+F): when the cursor is in or above YAML or TOML front-matter (Jekyll, Hugo, Zola, Quarto, Pandoc styles), opens a structured editor. Each key becomes a labelled wx.StaticText plus wx.TextCtrl pair. Save writes back as valid YAML or TOML, preserving comments and ordering wherever possible. New keys can be added; required keys (configurable per project) are highlighted.
• The front-matter editor recognises common keys (title, date, author, tags, categories, draft, slug, description, lang, permalink) and gives them sensible widgets (date picker for dates, multi-line for description, etc.). Unknown keys get a plain text field.

5.39 Autosave control and persistent undo

• Autosave is on by default at 30-second intervals. The status bar gains an Autosave cell showing Autosave: 30 s or Autosave: off. Enter cycles 15 s, 30 s, 60 s, 5 min, off. Settings dialog exposes the same plus a custom interval.
• Persistent undo keeps each document’s undo stack alongside its autosave snapshots. Reopening a recently closed document restores up to 100 undo steps. Off by default for plain-text files larger than 5 MB. Stored in %APPDATA%\Quill\undo\<hash>.undo, atomically written, auto-pruned at 30 days.
• Crash-safe autosave: snapshots write to …snap.tmp and rename to …snap on flush so a power loss mid-write cannot corrupt the recovery store.
• Autosave never breaks editing, and never fails silently (shipped 1.0.1, #1386). An OSError from the snapshot write is swallowed so typing continues — but silence would mean the user’s crash-recovery net is gone with nothing said. After two consecutive failures the frame announces once per failure streak: “Autosave paused — the disk is full. Your work is not being snapshotted.” The counter resets on the first success.
• Autosave writes off the UI thread (shipped 1.0.1, #1346). Everything the writers need — a detached Document snapshot, the rich-mode RTF payload, the caret position — is captured on the UI thread; the three writes (text snapshot, .rtfsnap, cursor position) then run on QuillTaskManager, with the failure notice marshalled back through call_ui_safely. A synchronous multi-hundred-millisecond write was a recurring mid-sentence hitch on a large document. A synchronous fallback covers the case where no task manager exists (early startup, headless tests), so a snapshot is never simply skipped.

5.39a Restore points — per-save document history (shipped 0.9.0 Beta 1)

The first shipped slice of the QUILL Sync plan (docs/planning/quill-sync-plan.md, section 7): document versioning, entirely offline, with no sync engine involved.

Model. Every successful save snapshots the document’s canonical text into a content-addressed store (restore_points/<doc-key>/blobs/<sha256>.txt + an atomically-written index.json, under the QUILL data dir). Content addressing makes unchanged saves free and gives dedup without reference counting. The store is wx-free, strict-typed quill/core/restore_points.py.

Invariants.

• Recording is best-effort by contract: the save-path hook (_record_save_restore_point, called from the _write_document_to_disk chokepoint so every save path is covered) is fully guarded — a snapshot failure can never be the reason a save fails.
• Restoring is itself reversible: the current text is recorded as a restore point (source restore) before it is replaced, and the restore lands in the editor as a modified buffer — nothing touches disk until the user saves.
• Retention thins by age (keep 7 days fully, then daily to 30 days, then weekly) under a per-document size cap (restore_points_max_mb, default 200, clamped 10-5000); the newest five versions are never pruned regardless of the cap.
• Documents over 20 MB of text are not snapshotted (the cap would be consumed by a handful of saves).

UI. File > Restore Previous Version... (command file.restore_previous_version, assignable, no default key) lists versions with speakable labels (“Today at 4:12 PM - 2,341 words”, “(before a restore)” marking pre-restore snapshots), skips the version identical to the current editor text, and offers Restore (confirmed, announced, one editor-level undo of a restore via the pre-restore snapshot) and Open as Copy (a new untitled tab). Settings: Keep restore points when saving (default on) and the disk limit, both with speakable specs.

Relationship to the other safety nets. Persistent undo is in-session; core.backups keeps the single pre-save .bak; restore points are the cross-session, long-horizon history above both. The Sync plan’s later phases reuse this exact store as the sync engine’s version layer.

5.40 Paragraph, line, and footnote refinements

• Join paragraph (Ctrl+Shift+J): collapses a wrapped paragraph (the kind produced by plain-text email or older PDF extracts) into a single line, preserving sentence-internal spacing. Works on the current paragraph or selection. Idempotent.
• Move line preserves selection: Alt+Up / Alt+Down (line move, 5.18) keep the same logical selection range so the user does not lose context after moving.
• Markdown heading auto-numbering (Tools → Toggle Heading Numbers): adds 1., 1.1, 1.1.1 prefixes across all headings, re-numbering in document order. Re-running removes them. Idempotent. Works in HTML, AsciiDoc, reStructuredText, Org, Typst as well.
• Footnote helper:
  • Ctrl+Alt+. (period) inserts a Markdown footnote pair at the cursor and jumps the cursor into the definition block; pressing Ctrl+Alt+. again returns to the reference site.
  • Tools → Renumber Footnotes reorders footnote labels into document order (1, 2, 3…), updating both references and definitions.
  • The same command works for reStructuredText auto-numbered footnotes ([#]_) and Pandoc-style inline notes.

5.41 Search-and-replace preview and saved searches

• Replace preview: when a Replace All would change more than 25 occurrences (threshold configurable), Quill shows a preview dialog listing up to the first 50 changes with line numbers and before/after text. Buttons: Replace All, Cancel, Replace Selected (in case the user unticks rows). Always shows the total count.
• Saved searches: a search term plus its options (case, whole word, regex, in-selection) can be saved under a name via Find → Save This Search…. Ctrl+Shift+F3 opens the saved-search picker (stock wx.ListBox); Enter runs it as if F3 had been pressed. Stored in %APPDATA%\Quill\saved-searches.json, exportable/importable.

5.42 Sort and transform details

Tools → Sort Selected Lines… and the related transforms (5.18) are spec’d here in full:

• Direction: ascending or descending.
• Case sensitivity: on or off.
• Numeric mode: lexicographic (item10 before item2) or natural-numeric (item2 before item10).
• Date-aware mode: parse leading ISO-8601 or dd/mm/yyyy dates; sort chronologically.
• Header row: preserved as the first line if checked.
• Stable sort always; equal lines preserve their relative order.
• Remove Duplicate Lines: optional “keep first” vs. “keep last”; reports Removed 13 duplicate lines, 287 remain.
• Reverse Lines: simple reverse, preserves blank lines.

5.43 Save All with conflict detection and per-file format memory

• Save All (Ctrl+Alt+S reserved; default is Ctrl+Shift+Alt+S so it doesn’t clash with Document Statistics) saves every modified document. If the external watcher detects that one or more files changed on disk since they were opened, Save All opens a per-file resolution dialog: Keep Mine, Take Theirs, Open Diff. Defaults to Keep Mine with no destructive action until the user confirms.
• Per-file format memory: Quill remembers per-path the user’s last choices for encoding, line endings, wrap, indent width, tabs-vs-spaces, and spell-check language. On reopening the file those settings are restored. Setting toggle: Settings → Files → Remember per-file format choices (on by default). Storage in %APPDATA%\Quill\file-prefs.json, keyed by SHA-1 of the path.

5.44 Per-document scratchpad

• Ctrl+Alt+N opens a small non-modal Scratchpad window tied to the current document. The Scratchpad is a second wx.TextCtrl with its own save and word count.
• Each scratchpad is persisted at %APPDATA%\Quill\notes\<hash>.md keyed by document path.
• When the underlying document is moved or renamed, Quill detects the orphan note next time the document is opened and offers Re-attach note to current document? (Yes / No / Show note).
• Scratchpads use the same spell-check stack as their parent document but are excluded from accessibility audits.

5.45 Section folding (announce-only) — shipped 0.9.0 Beta 3

A folding model designed for screen-reader users: fold state is spoken metadata, never visual line-hiding, and the document text is never mutated. Implemented in quill/core/code_folding.py (pure region detection, wx-free) plus MainFrame command wiring; see x.md’s original “PRD: Code Folding” for the accessibility rationale behind the design decisions below.

Two kinds of foldable region are detected, both reusing existing infrastructure rather than adding a new parser: heading sections (via the existing extract_outline_entries, so a heading’s region runs to the next heading at the same-or-higher level) and fenced code blocks (```…```, each complete fence is one atomic region). The original spec above called for heading-only folding with a fold-to-level chord sequence; the shipped version covers headings and code fences with a simpler single-toggle model, and does not yet implement fold-to-level or Find auto-unfold — both remain open follow-ups (see below).

• Ctrl+Alt+Shift+F (edit.toggle_fold) — folds or unfolds the smallest foldable region containing the cursor, announcing "Folded: 14 lines under 'Background'" / "Unfolded: 'Background'". (The original spec’s Ctrl+Shift+[/Ctrl+Shift+] were reused for other bindings by the time this shipped; a single toggle command was chosen over a separate fold/unfold pair for a smaller keymap footprint.)
• Alt+Shift+] / Alt+Shift+[ (navigate.next_fold / navigate.previous_fold) — jump between foldable region boundaries, folded or not, announcing the region’s label, fold state, and line count on arrival. This is the safe, honest version of “skip folded content”: it only fires on a command that already jumps by structural unit, never on literal arrow-key movement, which is never intercepted.
• Ctrl+Alt+Shift+L (tools.list_folds) — the accessible equivalent of scanning gutter fold triangles: a dialog (reusing the same tree-navigator pattern as list_bookmarks/Outline Navigator) listing every foldable region with its fold state and line count, letting a user jump or toggle without ever needing to encounter a region by scrolling past it.
• Folding state is per-tab and session-only, never written to file or DocumentMemory — deliberately, since persisting it would need edit-resilient position tracking (like InlineNote’s quote-anchoring) for a feature whose entire value is “reduce clutter right now.”
• Outline Navigator (5.16) remains the primary navigation tool; folding is the in-editor companion, and List Folds is folding’s own navigator-style surface.

Not yet implemented (open follow-ups from the original spec): fold-to-level chord sequences (Ctrl+Shift+K Ctrl+Shift+0/J); Find auto-unfolding a region it matches inside (moot today since folding never hides text from Find or any other text-reading operation — only the four commands above are fold-aware); per-function/indentation-based folding for real source files edited via a Quillin (fenced-block granularity is the right scope for a writing app with embedded code, not an IDE, and was an explicit scope decision, not an oversight).

5.46 Spell-check ignore directives and manual bilingual flag

• Per-document ignore directives. Quill honours a magic comment that lists words to ignore in this document only:
  • HTML / Markdown: <!-- quill: ignore-spell "frobnicate", "wibble" -->
  • Plain text and code (using the file’s comment marker): # quill: ignore-spell frobnicate, wibble
  • YAML / TOML front-matter: quill_ignore_spell: [frobnicate, wibble]
• The ignore set is merged into the active dictionary stack as a transient per-document layer.
• Manual bilingual paragraph flag (Ctrl+Alt+B): toggles a per-paragraph language override. The user types or picks a BCP-47 tag; the paragraph is marked in the sidecar .quill.yml; the spell-check stack swaps for that paragraph. Per-paragraph auto-detection remains in the backlog; this manual flow is reliable today.

5.47 Word boundary mode, trailing whitespace, case-change announcement

• Word boundary mode (Settings → Editing → Word Boundary Mode):
  • Default: Unicode word breaks (UAX #29). Best for prose.
  • Whitespace: only whitespace separates words. Best for log files.
  • Programmer: also breaks on _, -, ., and case transitions (getFoo is three “words”: get, Foo, plus the case boundary). Best for code.
• The mode affects Ctrl+Left/Right, Ctrl+Delete/Backspace, double-click selection, word count, and the spell-check tokeniser.
• Trailing whitespace announcement: when the cursor lands on a line that ends with trailing whitespace, the status bar’s Line/Column cell appends (trailing whitespace) and a screen-reader-friendly hint is available via Where Am I. No visual highlight; no extra speech while typing.
• Case-change announcement guard: when Ctrl+Shift+U, Ctrl+L, or Ctrl+Shift+T apply to the whole document because nothing was selected, the announcement explicitly says so and reminds the user Press Ctrl+Z to undo full-document case change.

5.48 Multi-format export and reading view

• Export panel (File → Export…): one dialog with target format choices: HTML, DOCX, plain text, Markdown, reStructuredText, and PDF (via Markdown → HTML → system print-to-PDF). Per-format options inline (heading numbering, table-of-contents inclusion, embedded CSS yes/no, page size for PDF).
• Reading view (View → Toggle Reading View): toggles the editor between source view and a clean reading representation for HTML and Markdown. Still a wx.TextCtrl — same accessibility, just a different render: links unwrapped to text (url), headings prefixed by their level, lists rendered with consistent markers, code blocks framed by a horizontal rule. Editing is disabled in reading view (the cell announces this); toggle off to edit.

5.49 Welcome-back snapshot

• On launch, if the user closed Quill cleanly with N documents open last time, a single prompt offers Reopen the 3 documents from your last session? with Yes / No / Show me.
• “Show me” opens a small list of the documents (paths, last cursor positions) and lets the user pick a subset.
• Always opt-in per launch; the global “restore session” setting is separate and stays off by default.

5.50 Per-document keymap override (with explicit consent)

• A document’s sidecar .quill.yml may declare a keymap_override block.
• Quill never applies it silently. On opening such a document, the user sees a one-time confirmation: This document requests a different keymap. Apply for this document only? with Yes / No / Always for this document. The decision is remembered per-document path.
• Overrides are scoped: they only apply while the document has focus, never global.
• A small lock icon appears in the document name status-bar cell (announced as keymap override active) whenever an override is in effect.

5.51 Settings export, import, and partitioned reset

• Settings → Export… writes a single zip containing settings, keymap, templates, snippets, personal dictionary, saved searches, and bookmarks. API keys are excluded; the user is told so explicitly in the dialog.
• Settings → Import… previews every change in a stock wx.ListBox and requires Enter to commit. Conflicts (e.g. a keymap rebind that contradicts the current keymap) are flagged inline.
• Settings → Reset to Defaults… opens a partitioned reset dialog with checkboxes for: Keymap, Appearance, Spell-check learning, Templates and snippets, Recent files, Bookmarks, Everything. Never silent; every reset shows a confirmation listing what will be lost.

5.52 Document fingerprint

• Every saved document has a SHA-256 fingerprint of its bytes shown in File → Document Properties… and copyable from a button.
• Useful for accessibility certification workflows where the user must prove they reviewed a specific version, and for forensic comparison.
• The fingerprint also surfaces in the diagnostics bundle (5.33) for any open document, scrubbed of path.

5.53 Unicode insert

• Ctrl+Alt+U opens a search dialog over the Unicode name database (unicodedata from the standard library). Type any part of a character name; matching characters appear in a stock wx.ListBox with code point, name, and the literal character.
• Categories shown as one-line filters: Letters, Marks, Numbers, Punctuation, Symbols, Separators, Other. Click or type the category prefix to scope.
• Pinned favourites for common needs: em-dash, en-dash, ellipsis, smart quotes, currency symbols, mathematical operators.
• Recent characters list keeps the last 20.

5.54 Idle-time prefetch

• When the user opens a file from a folder, Quill background-extracts the next and previous files alphabetically into the in-memory document cache so opening them feels instant.
• Bounded by available memory and by a hard cap of 50 MB total prefetch.
• Cancelled immediately on any other extraction or AI task.
• Opt-out switch in Settings → General → Prefetch neighbouring files.

5.55 Atomic on-disk stores

• All Quill-managed JSON stores (bookmarks, settings, keymap, recent, saved searches, file prefs, notes index) write to <store>.tmp and rename atomically.
• A <store>.bak is kept of the last good version. On startup, if the primary store fails to parse, Quill renames it to <store>.broken-<timestamp>.json, falls back to the .bak, and announces Recovered <store> from backup.
• This eliminates the worst class of “my bookmarks vanished after a crash” bugs.

5.56 First-run onboarding

A five-step welcome flow the first time Quill launches. Each step is a normal modal page (no carousel, no animation). Skip is always available; the chosen values are written through the same Settings code path as any later change.

1. Profile: System, Word-like, Vim, Emacs.
2. Theme: System, Light, Dark, High Contrast.
3. Spell-check languages: multi-select from the bundled launch set; the active document language is added automatically when later opened.
4. AI provider: Off (default), Ollama local, Ollama Cloud, OpenAI, Anthropic/Claude, OpenRouter, Gemini, or a custom OpenAI-compatible endpoint. (Azure OpenAI is not currently supported; it is a possible future addition — see AI-15.) Providers include sensible default hosts where possible; advanced custom mode allows manual endpoint override. If a provider is picked, the API-key dialog opens when required; the key is stored via Windows Credential Manager with a DPAPI-encrypted fallback (10.11). Network is never used without explicit per-action consent.
5. Telemetry: confirms it stays off (default). A short plain-language sentence explains what telemetry would collect if turned on later.

The onboarding completion writes %APPDATA%\Quill\onboarding-complete.json. Trust and privacy consent acknowledgement is stored separately in %APPDATA%\Quill\trust-consent.json and is versioned so policy text updates can require re-acknowledgement. Re-running Help → Run Onboarding Again reopens the flow without resetting anything else.

5.57 Privacy summary

• A single-screen plain-language statement of what Quill does and does not send over the network. Linked from Help → Privacy Summary and shown once during onboarding.
• Content is audited by the cognitive-accessibility plain-language linter (9.8): Flesch ≥ 60, controlled vocabulary, one idea per sentence.
• Says explicitly: documents never leave the machine without an explicit per-action confirmation; the only outbound calls v1.0 makes without confirmation are the manual update check and the optional crash-report upload (5.71), both opt-in.

5.58 Licenses screen

• Help → Licenses opens THIRD-PARTY-NOTICES.md (auto-generated at build time, 10.2.4) in the editor.
• The file lists every bundled component, its version, its license text, and a one-line use justification.
• Required for procurement; required by some bundled licenses.

5.59 Crash recovery transparency

When Quill detects an autosave snapshot newer than the on-disk file on launch:

• The recovery dialog names the file, the snapshot timestamp, the byte count, and offers four actions: Recover, Compare with on-disk, Discard snapshot, Cancel (decide later).
• Compare with on-disk opens the diff view (5.22) immediately.
• The dialog is screen-reader-friendly first: every value is a separate labelled wx.StaticText so it reads cleanly.
• Choosing Recover writes the snapshot as a new unsaved document; the on-disk file is never overwritten without an explicit Save.

Offer suppression on inconclusive exits — shipped 0.9.0 Beta 3 (#940/#948). begin_session() in core/recovery.py now calls _log_shows_actionable_error(logs_dir) before appending a RecoveryOffer: it scans the tail (last 256 KB) of quill.log for ERROR/CRITICAL/Traceback markers, and suppresses the offer entirely when none are found – an exit with no error evidence in the log is indistinguishable from an external termination (OS shutdown, forced close) and gets no “Quill detected an unclean exit” prompt. A missing log file fails open (still offers recovery) since an absent log is inconclusive, not evidence of nothing having happened. The autosave snapshot itself is untouched either way; only the offer is gated.

5.59b A file that is not there is a sentence, not a crash (shipped 2026-08-19; #1423)

Opening a document must never reach the crash handler because the file moved. Reported against a OneDrive path – a placeholder whose contents were never downloaded – and equally reachable from a renamed Recent entry or a disconnected drive.

• One funnel refuses. io/open_read.read_open_document is the single entry point every open path uses (synchronous, worker-thread, office, PDF, EPUB), and it now validates the path before reading, raising DocumentUnavailableError (QUILL-IO-OPEN-UNAVAILABLE) with a sentence naming the file and the likely reasons. A directory chosen where a file was expected is named as a directory rather than failing partway through a read.
• The synchronous path was the gap. The office/PDF/large-file reads already ran under MainFrame._run_background_task, whose worker catches and marshals exceptions to the UI thread. The cheap read of a small .txt/.md/.html had no such path, so FileNotFoundError escaped to the excepthook. ui/open_guard.read_document_or_report closes it: status bar and announcement, then return – the frame is left exactly where it was.
• The error code is not spoken. str(CodedError) carries the [QUILL-IO-OPEN-UNAVAILABLE] prefix for the log and the crash bundle; the announcement uses args[0], because a support code read aloud is noise to the person who just wanted their file.
• Recent is not pruned from this path. core.recent.prune_missing_recent_files owns that decision and is bound by rules the open path cannot see (#14: only confirmed fixed drives are probed, so a detached USB or an offline share never loses its history; the whole behaviour sits behind recent_files_auto_clear_missing, default off). A quiet prune here would overrule a user setting and the removable-drive rule. Enforced by a test asserting ui/open_guard.py cannot even import the recent module.
• Placement is a GATE-11 consequence. main_frame.py and main_frame_simple_open.py are both at their size ceilings, so the behaviour lives in its own module and the mixin holds a delegate; the call site in main_frame.py is one line either way, and the helper is underscore-prefixed so the GATE-6 public-surface snapshot is unchanged.

5.59c A dialog’s required arguments cannot drift from its caller (shipped 2026-08-19; #1422/#1417/#1395)

SpeechSetupDialog gained two required keyword-only parameters and MainFrame was updated to supply them in the same change – but nothing checked the two agreed, so the window between them shipped and three people hit it while installing a Kokoro voice. A missing keyword-only argument is a TypeError at construction: the Speech Hub does not open at all, so there is no dictation, no voices, and a crash report instead.

The rule is that a constructor contract crossing a module boundary is checked by a test, not by review: tests/unit/ui/test_speech_setup_kwargs_contract.py reads the dialog’s real signature (inspect.signature, required keyword-only parameters) against the dict literals MainFrame builds (parsed with ast, since building them for real needs a live frame and a machine probe), and fails when a required parameter is added without being supplied.

5.59a Application Status page (Help → Status Page)

HelpStatusDialog (quill/ui/status_dialog.py) is a non-modal wx.Notebook of four tabs – Status (Overview/Whisperer/Speech key-value rows), Tasks & Downloads, Features, and Actions – each backed by a wx.ListCtrl (except Actions, a read-only text box) so screen readers get native column navigation instead of Browse-mode HTML table traversal. While the dialog is open, a wx.Timer calls refresh() every two seconds so background-task progress and downloads stay live without the user pressing the Refresh button.

Live-refresh focus loss, fixed 0.9.0 Beta 3 (#969). refresh() rebuilds each wx.ListCtrl from scratch (DeleteAllItems() then re-InsertItem() every row) so the displayed data always matches _build_help_status_data() exactly – but the rebuild silently dropped the list’s focused-row marker too. With the timer firing every two seconds, a user arrowing down the list got returned to the top (or to no focused row at all) before they could act on where they had navigated, reported verbatim as “Move down through the list. The focus will be put back at the top of the list.” refresh() now captures each list’s focused row index before the rebuild (_capture_focus) and restores it afterward (_restore_focus, clamped to the new row count in case it shrank), independently per list – so a live-update tick can never undo the user’s own navigation. Covered by tests/unit/ui/test_status_dialog.py against a real wx.ListCtrl, not a fake.

5.59b QUILL Sync (folders + GitHub, shipped 0.9.0 Beta 3)

Decision on record: QUILL does not build its own sync engine. A full QUILL-native sync service (a quill/core/sync/ engine with SQLite state, content-addressed version history, and per-provider OAuth adapters for OneDrive/Dropbox/Google Drive) was designed in detail in the now-retired docs/planning/quill-sync-plan.md and explicitly decided against for 0.9.0 Beta 3. The full reasoning is preserved in docs/engineering/sync-engine-history.md; the short version is that a folder is already a solved sync problem (OneDrive, Dropbox, Google Drive, and iCloud already replicate one reliably) and git is already a solved sync problem for structured, conflict-aware content — so “QUILL Sync” reuses both instead of reinventing either. Two small, honest features ship instead:

1. Sync via a folder (local or cloud) — quill/core/data_location.py (pre-existing, #615). Relocating QUILL’s entire settings/snippets/ dictionaries/keymap directory to a user-chosen folder already shipped for a different reason (keeping data off the system drive); it turns out to already be exactly the mechanism a lightweight sync story needs. Point that folder at one a cloud client (OneDrive, Dropbox, Google Drive, iCloud) or a folder-sync tool already mirrors, or at a USB drive, and QUILL’s data travels with it — QUILL never talks to any cloud provider’s API. The first-run wizard’s “Where should QUILL store your data?” page (_DataLocationPage in quill/ui/setup_wizard_pages.py) now states this explicitly, including the honest caveat: QUILL has no cross-device conflict resolution for this path, so two devices must not run QUILL against the same folder at the same time. No code changed here beyond the wizard’s description text — the mechanism already worked; only the framing and documentation were missing.

**2. Sync Folder with GitHub — new, general-purpose (quill/core/git_sync.py

• quill/ui/main_frame_git_sync.py, GitSyncMixin).** Accessible Vault’s “Sync Vault” (quill/core/vault/sync.py::run_vault_sync, §Vault Phase 7) already implements commit/pull/push over a user’s own git remote with conflicts surfaced as a spoken, itemized list rather than an auto-merge — and has zero Vault-specific logic in it at all; it takes a bare folder path and three git-plumbing commands. quill/core/git_sync.py gives that exact engine a general-purpose home, adding only what Vault didn’t need:

• check_repo_status(root, *, runner) -> GitRepoStatus — whether root is a git repository, has a remote configured, and its current branch. Never raises; every probe tolerates a non-zero exit (not a repo yet, no remote, detached HEAD) by reporting the negative case.
• init_repo_with_remote(root, remote_url, *, runner) -> SyncResult — git init (only if needed) then git remote add origin <url> (only if no remote exists yet); never overwrites an existing origin.
• sync_folder_via_git(root, *, runner, ...) -> SyncResult — delegates to run_vault_sync for the actual commit/pull/push (one implementation in the tree, not two), but detects the branch to sync from the repository itself (git rev-parse --abbrev-ref HEAD) rather than assuming "main" the way Vault’s own always-main convention does — a general folder may plausibly be on master or any other branch name.

Tools → Git and GitHub → GitHub → Sync Folder with GitHub… (sync.sync_folder, empty default keymap chord, assignable) prompts for a folder (remembered in Settings.git_sync_last_folder for next time), checks its status in the background, and either syncs directly (already a git repo with a remote) or explains exactly what setup is needed and asks first: “‘<folder>’ is not a git repository yet. QUILL can set it up: this runs ‘git init’ in the folder, then adds the remote repository you provide as ‘origin’. Continue?” — never silently. On confirmation, a plain text field collects the remote URL, then init_repo_with_remote followed by sync_folder_via_git run as background tasks. Conflicts (never auto-resolved) are listed via the same accessible list dialog (show_vault_list_modal) Vault Sync’s own conflict report uses.

Credentials and safety, matching the Vault Sync precedent exactly: relies entirely on the user’s own git installation and its own credential handling (an SSH key, or a stored HTTPS credential via the system git credential manager) — QUILL does not store or inject a separate token for these subprocess calls. Blocked outright in Safe Mode. The git pull/git push network calls are subprocess-based (not an urlopen/requests call the AST-based egress scanner can see) and are manually documented in quill/tools/network_egress_audit.py for auditability, alongside the pre-existing (previously undocumented) Vault Sync call sites.

5.60 Read-only document mode

• View → Read-Only Mode (Ctrl+Shift+L by default) toggles the editor’s editability without touching file permissions.
• Toggle state is per-document; announced when toggled (Read-only mode on / off).
• Status bar’s Modified state cell shows Read-only while on; attempts to type are silently ignored and a single discreet announcement (Editor is read-only; press Ctrl+Shift+L to allow editing) fires the first time per session.
• All navigation, Find, Outline, Read Aloud, Statistics, and Accessibility Audit continue to work.

5.61 File-related menu helpers

• File → Reveal in File Explorer opens Explorer with the current file selected.
• File → Copy Full Path, File → Copy File Name copy the corresponding string to the clipboard with a confirmation announcement.
• File → Show Containing Folder in Quill is deferred to v1.1 (depends on the folder panel).

5.62 Open Recent enhancements

• File → Open Recent includes per-entry Pin / Unpin and a top-level Open All Pinned action.
• Pinned items are not subject to the recent-list cap (default 10) and appear at the top of the submenu.
• Pinned entries are persisted in recent.json and survive Clear Recent (which only clears unpinned entries).

5.63 Document timeline

• Tools → Document Timeline… opens a chronological list (stock wx.ListBox) of every backup and autosave snapshot for the current document, with timestamp, size, and source (save backup vs. autosave snapshot).
• Each row has Open in new tab, Compare with current, and Restore (with confirmation) actions.
• The backing store already exists (5.13 + 5.39); this is the unified UI on top.
• Per-document, never global.

5.64 Sentence and paragraph navigation

• Ctrl+Up / Ctrl+Down already navigate by paragraph (standard wx behaviour).
• Alt+Right / Alt+Left move to the next / previous sentence and announce the sentence text (truncated to 200 characters around the cursor for braille and speech).
• Sentence detection uses the regex Unicode word-boundary tables plus a per-language abbreviation list (Mr., Dr., e.g., etc.) that ships with each Hunspell language pack and is user-extendable in Settings.
• Ctrl+Shift+Alt+Right / Ctrl+Shift+Alt+Left extend the selection by sentence.

5.65 Word-count goal per document

• File → Document Properties… gains a Word goal integer field (0 disables).
• The status bar’s Word count cell appends (243 of 1500) when a goal is set; on crossing the threshold Quill announces Word goal reached: 1500 words.
• The goal is stored alongside other metadata in the document container or in the .quill.yml sidecar.

5.66 Reading position memory per document

• On close, Quill records cursor line/column and scroll offset for the current document.
• On reopen, the cursor is restored; the status bar announces Restored to line N on first focus into the editor.
• Storage keyed by the document’s path SHA-1 in file-prefs.json (10.5).
• Setting toggle Settings → Editing → Restore reading position (on by default).
• Independent of Welcome-Back snapshot (5.49); works even when only a single document is opened directly from Explorer.

5.67 Compare with clipboard

• Tools → Compare With Clipboard runs the unified-diff machinery (5.22) with the current document as before and the clipboard contents as after.
• Useful when reviewing a single suggestion pasted from chat or email.
• Refuses if the clipboard is empty or larger than 5 MB; explains why.

5.68 Insert from file

• File → Insert From File… inserts another file’s text at the current cursor without opening it as a separate document.
• Uses the same format detection as Open; for non-text formats Quill extracts plain text and confirms before inserting.
• Files over 1 MB show a confirmation dialog with the byte count and the first line of content.

5.69 Selection-statistics direct shortcut

• Ctrl+Alt+Shift+S runs Document Statistics scoped to the current selection without first opening the full-document dialog.
• Same dialog as 5.19 but with the title prefixed Statistics — Selection.
• Reassignable like any other binding.

5.70 Sound notifications and QSP sound packs (opt-in)

QUILL plays short, screen-reader-respectful audio cues (earcons) at meaningful editing moments. The system is built around QSP (QUILL Sound Packs): swappable bundles that map event IDs to audio files. Playback is non-blocking, fire-and-forget, and pre-buffered so there is no perceptible lag between event and sound. Earcons supplement speech; they never replace it. (This section absorbs the former docs/wsp.md sound-design notes and docs/sound-packs.md pack guide.)

Pack selection and resolution. Bundled packs live as directories under quill/assets/sound_packs/ (the default earcon pack is ink, “QUILL’s pack”; indent_* are the separate indentation-tone overlays). sound_pack.available_sound_packs() discovers the bundled earcon packs (default first, indent_* excluded) for the first-run wizard’s Sound-pack dropdown — which replaced a *.qsp file picker that could not select the shipped packs at all, since they are folders, not files. The chosen pack is stored in settings.sound_pack_path as one of: "" (the default pack, for back-compat), bundled:<id> (another bundled pack, resolved against the install so it survives a move/reinstall), or a direct path (a user’s own pack). sound_pack.resolve_sound_pack_path() maps any of those to a pack path, and SoundManager._load_pack uses it, so enabling sound always falls back to QUILL’s pack rather than going silent.

5.70.1 QSP format

A .qsp file is a ZIP archive whose root holds manifest.json and the referenced WAV files. During development a directory with the same layout is accepted; the loader treats a directory and a ZIP identically. The manifest is validated at load time against quill/core/schemas/sound_pack.json:

{
  "format": "qsp",
  "version": "1",
  "name": "Ink",
  "author": "Jeff Bishop",
  "description": "Crisp synthesised earcons for focused writing.",
  "license": "CC0",
  "events": { "abbreviation_expanded": "expand.wav", "document_saved": "save.wav" }
}

Any event key absent from the manifest is silently skipped (no sound, no error), which allows minimal partial packs that cover only a subset of events. The QSP schema places no constraint on event-key names, so a Quillin can register additional event IDs and ship its own pack.

5.70.2 Event taxonomy

Canonical event IDs are defined as a StrEnum in quill/core/sound_events.py (no wx, no platform code). Groups: Editing (abbreviation_expanded, abbreviation_deleted, snippet_inserted, autocomplete_accepted, word_corrected), Document lifecycle (document_created/saved/closed), Navigation (heading_jumped, table_entered, list_entered, browse_mode_on/off), Search (search_found/not_found/wrapped), AI and transcription (ai_thinking_started, ai_response_received, ai_error, transcription_started/stopped/word_inserted), Connectivity (ssh_connected/disconnected), Compare (compare_enter_mode, compare_exit_mode, compare_next_difference, compare_previous_difference, compare_no_more_differences), Indentation tones (indent_level_0..7_up / _down), and System (error, warning, sound_on, sound_off). The complete table with triggers is maintained in this section’s source and surfaced to pack authors via the Sound Events dialog.

5.70.3 Audio file requirements

• Format: WAV (PCM, 16-bit, 44100 Hz, mono) — plays from memory with no decode step, the key to zero-lag earcons.
• Duration: earcons 50–150 ms; state-change sounds (browse mode, SSH) up to 300 ms; nothing longer.
• Headroom: normalize to about −6 dBFS so the volume control stays meaningful.
• OGG/MP3 are not accepted for core events because codec init adds 20–80 ms of jitter on first play.
• Every scripted earcon in a bundled pack must be acoustically unique — no two events share an identical sound (audited byte-wise and by manifest mapping).

5.70.4 Cross-platform backend

quill/platform/sound_player.py auto-detects the best backend at startup: (1) _SoundLibBackend (BASS via the MIT-licensed accessibleapps/sound_lib, all platforms, native mixing); (2) _WinsoundBackend (Windows stdlib, serialising queue); (3) _NSSoundBackend (AppKit NSSound via pyobjc, macOS fallback); (4) _NullBackend. sound_lib is an optional, licensed extra (pip install quill[audio]) never bundled by default; absent it, QUILL falls back to winsound on Windows or NSSound on macOS (both ship with their respective build extras already) before going silent. Any object satisfying the _WavBackend protocol (play_wav(bytes), shutdown(timeout)) can be injected, which is how tests use a synchronous recording backend.

5.70.5 Module layout and posting

sound_events.py (enum) → sound_pack.py (QSP loader + validator; reads every WAV into bytes at load, zero disk I/O at play time) → sound_player.py (SoundPlayer: 80 ms per-event cooldown, mute toggle, per-event disable list) → quill/ui/sound_manager.py (singleton wired to settings and a custom wx event). Any module posts a sound without importing wx:

from quill.core.sound_events import SoundEvent
from quill.ui.sound_manager import post_sound
post_sound(SoundEvent.ABBREVIATION_EXPANDED)   # thread-safe, < 1 ms, no-op if disabled

5.70.6 Indentation tones and overlay packs

For code, an indent-tone pack maps the 16 indent_level_N_up/down events to pitched tones so the caret crossing indent levels rises and falls in pitch. Four scales ship — pentatonic, whole-tone, diatonic, chromatic — generated by scripts/gen_indent_tones.py. An indent-tone pack overlays a primary earcon pack, so the user can combine, say, the Ink earcons with pentatonic indent tones. The indent_tone_scale setting (empty = off) selects the scale; blank lines stay silent and hold the previous level.

5.70.7 Settings, packs, and Quillins

Settings (group accessibility): sound_enabled (bool), sound_pack_path (text; empty = bundled Ink pack), sound_volume (0–100), sound_events_disabled (comma-separated IDs), indent_tone_scale (choice). A global mute is bound to the sound.toggle_mute keymap action. The bundled Ink pack ships in the wheel at quill/assets/sound_packs/ink/ (generated by scripts/gen_ink_sounds.py). A Quillin manifest may declare a sound_pack directory and sound_events map; the runner registers those IDs with SoundManager at load time, and the user can silence them individually via sound_events_disabled.

5.70.8 Safe mode

When QUILL_SAFE_MODE=1, SoundPlayer.play() is a no-op, keeping safe mode strictly minimal-resource.

5.70a Post to Mastodon (lean poster)

A deliberately small way to publish a status to Mastodon from the editor — not a full client (no timelines, replies, media, or polls in v1).

• Compose flow. tools.post_to_mastodon (default QUILL Key + Shift+P, also Tools → Share → Post to Mastodon…) takes the editor selection, or the whole document when nothing is selected, and opens MastodonComposeDialog: editable text, an account picker (by nickname), a visibility choice (public/unlisted/private/direct), a live character count, and Post. Disabled in Safe Mode. If no account exists, the accounts manager is offered first, then compose continues if one was added.
• Accounts. tools.manage_mastodon_accounts opens MastodonAccountsDialog (add/remove/set-default). Adding registers an app named QUILL on the user’s instance (so posts read “via QUILL”) and uses the OAuth out-of-band flow: open the browser to authorize, paste the code back. Non-secret metadata (nickname, instance, @handle, client id) is stored in mastodon-accounts.json; the access token and client secret go to the Windows Credential Manager / DPAPI via credential_store, never the JSON.
• Post language and per-instance character limit (#922). post_status accepts an optional language (an ISO 639-1 code such as "en" or "it"); when given it is sent as the post’s language field so the instance files the post under the right language preset instead of the account’s default, and None omits the field. The compose dialog exposes this as a Post language wx.Choice next to visibility; the first entry (“Default (instance)”) maps to None, the rest send their code. The live counter uses instance_character_limit(instance_url), which fetches GET /api/v2/instance, reads configuration.statuses.max_characters, and falls back to DEFAULT_CHARACTER_LIMIT; the result is cached in-process per normalized instance URL (clear_character_limit_cache is the test hook) so the counter reflects an instance like one with a 9999-character limit without re-querying on every keystroke. LANGUAGES in mastodon_dialogs.py lists the presets, “Default (instance)” first.
• Implementation. All API + account logic is wx-free in quill/core/mastodon/ — client.py (a single audited urllib egress site _http_json, HTTPS-only over a verified TLS context: app registration, OAuth token exchange, verify_credentials, status post, and the GET /api/v2/instance character-limit lookup) and accounts.py. Dialogs in quill/ui/mastodon_dialogs.py. The egress sites are recorded in network_egress_audit.py.

5.71 Quiet mode

• View → Quiet Mode (Ctrl+Alt+Q by default) is a single toggle that:
  • hides the status bar (still reachable via F6 announcement only),
  • suppresses non-critical announcements (autosave summary, idle-prefetch chatter, Tip of the Day),
  • sets audio cues volume to zero for the session,
  • leaves all critical announcements intact (errors, save failures, AI completion).
• Announced on toggle (Quiet mode on / off).
• Useful for high-focus writing sessions; state is per-session and not persisted.

5.72 Temporary trust for untrusted-location opens

• The Trusted Locations prompt (5.31) gains a third button: Open this time only.
• The file opens; the folder is not added to trusted locations.
• Useful for one-off opens from Downloads or temp folders without expanding the trust footprint.

5.73 Settings search

• A search field at the top of the Settings dialog (Ctrl+F when focus is in Settings).
• Indexes setting key, label, description, and a synonym list maintained alongside each setting.
• As the user types, the tree filters to matching settings; the first match is announced.
• Esc clears the filter; Tab moves to the tree.
• The synonym list is gettext-translated alongside labels.

5.74 In-app changelog and update transparency

• Help → Release Notes opens a Markdown document with one section per version. Auto-generated from CHANGELOG.md at build time.
• The manual update dialog (5.34, 10.12) shows the release notes for the version it is offering, shows the published date when the feed provides it, and lets the user Update, Skip this version, or Close.
• One update dialog, every app (2026-09-12). quill/ui/update_notice.py is the single “an update is available” surface for QUILL, the eight companion apps and QuillLite; quill/ui/update_download.py is the single download, progress-milestone and Install-and-restart path behind it. The dialog always carries a summary of what is new (the release body, flattened out of Markdown, capped, never empty), an Update button as the affirmative and default, and a Close button as the escape; focus lands on the notes rather than on a button, so the first thing read is what changed. QUILL alone adds Skip this version, because QUILL alone has a settings field to remember the answer in. Before this the companion apps showed a bare Yes/No box (“Download it now?”) that said nothing about the release at all.
• QuillLite checks for its own updates (2026-09-12). Help > Check for Updates… on the family key Ctrl+Alt+U (Page Setup moved to Ctrl+Alt+P to free it), plus a silent once-a-day check at launch governed by check_updates_on_launch in QuillLite’s own settings. The launch check says nothing while it runs, nothing when there is nothing, and nothing when the network is down; only a genuine newer version speaks. Releases resolve from RELEASE_REPO / RELEASE_ASSET_PREFIX in quill/core/lite/__init__.py – deliberately not from companion_install.ASSET_PREFIX, which is the set of siblings QUILL can offer to install. See quill/apps/lite_updates.py.
• Past release notes remain reachable through the document’s own outline (5.16).

5.75 Crash-report opt-in (per recovery)

• When Quill recovers from a crash, the recovery dialog includes an opt-in checkbox: Send crash details to the Quill team (no document content).
• If checked, the diagnostics bundle (5.33) is uploaded over HTTPS to a host shown explicitly in the dialog before send; the upload is cancellable and shows a progress announcement.
• Off by default; the choice is remembered per recovery session only, never globally — this prevents accidental long-term opt-in.
• Crash reports include logs, environment, and the last 50 commands, never document content or API keys.

5.76 Interactive compare mode

Quill provides two complementary comparison workflows: an accessible interactive compare session and a generated diff report.

• Compare commands (Tools → Comparison, the single canonical home): Compare with File…, Compare Open Documents…, Next Difference, Previous Difference, Announce Current Difference, Difference List…, Toggle Synchronized Navigation, Toggle Ignore Whitespace, Compare Options…, Generate Accessible Report, Create Difference Summary, Copy Current Difference, Copy All Differences. (The former Navigate → Compare duplicate submenu was removed in 1.0.0 — it repeated a subset of these under separate ids and mislabeled two of them; its two unique items, Toggle Ignore Whitespace and Generate Accessible Report, moved into Tools → Comparison.)
• Core navigation (post-#357 chord class): Ctrl+Alt+Shift+. next difference, Ctrl+Alt+Shift+, previous difference, Ctrl+Alt+Shift+D read current difference. The Difference List and Toggle Synchronized Navigation have no default key; assign them in the Keymap Editor.
• Interactive session: focus stays in the active editor; moving to a difference places the cursor on the changed line and announces both sides in plain language.
• Difference List: a stock list control containing all differences with document names, line numbers, type, and a short preview; Enter jumps to the selected difference.
• Compare options: ignore leading/trailing spaces, all whitespace, blank lines, line endings, case, punctuation, repeated spaces, Markdown heading markers, HTML tag differences, and normalized Unicode.
• Difference summary: users may create a plain-text summary document listing all differences, options used, and short before/after excerpts.
• Diff report: Quill may also generate a unified-diff document in a new editor tab. Diff hunks remain navigable with Ctrl+] and Ctrl+[.
• Extracted document compare: PDF, DOCX, EPUB, OCR, and repaired text compare against Quill’s extracted text representation, with a warning that extraction quality may affect results.
• Feature profiles: interactive compare is on in Casual Writer, Author or Student, Reader and Student, Office and Admin, Accessibility Professional, Developer and Power Text, and Full Quill; it is quiet in Essential.

5.58 Ask Quill — on-device AI chat (WebView)

Ask Quill is a conversational assistant that runs entirely on the user’s machine — no cloud, no API keys. It can answer questions, write or rewrite text for the document, and run Quill commands, but it is screen-reader-first and approval-gated: nothing touches the document until the user approves it. This is the crawl-before-run 1.0 surface; a deeper native integration is future work.

On-device backends (platform-selected). make_default_backend() picks the backend by platform — Apple Foundation Models on macOS, and llama.cpp (llama-cpp-python, CPU, GGUF) on Windows and Linux. There is no server and no GPU requirement. On Windows the model runs in-process on the CPU.

• Model manager (RAM-tiered, auto-download). On first use the backend resolves a model: QUILL_LLAMA_MODEL (explicit .gguf path) → an existing *.gguf in <app data>/models → otherwise it downloads the RAM-appropriate model with progress announced. Machines under ~8 GB RAM get Llama 3.2 1B; otherwise Phi-4-mini (Q4).
• Model is a setting, not a chore. The model choice is exposed in the AI Model settings dialog (dropdown + Download Now) and during onboarding — users are never asked to “drop a GGUF.” Onboarding first asks “Do you want to use AI?”; the model controls only appear if they say yes. Model descriptions avoid em-dashes.
• Graceful CPU fallback. If the prebuilt llama.cpp hits an unsupported CPU instruction (STATUS_ILLEGAL_INSTRUCTION 0xC000001D — e.g. AVX2 missing under x64-on-ARM emulation such as Parallels on Apple Silicon), the backend converts the OSError into a plain-language message explaining that the CPU lacks AVX2 and suggesting a no-AVX / native build, instead of crashing.

The whole chat lives in a WebView (Edge WebView2 on Windows). Transcript, suggestions, and the message edit field are all rendered as HTML in wx.html2.WebView — which is Edge WebView2 on Windows (WKWebView on macOS, WebKitGTK on Linux). We deliberately render in the WebView rather than a plain list box + separate text field because it gives us formatted Markdown (the assistant’s headings, lists, and code render properly) together with the browser engine’s native, mature accessibility, and keeps the user in one place. wx.html2.WebView is a factory-created native control and cannot be meaningfully subclassed, so accessibility is driven by the HTML we render, via a thin wrapper (AccessibleWebView):

• An ARIA live region (<main role="log" aria-live="polite">) so each new message is announced automatically by NVDA / JAWS / Narrator without the user moving focus.
• An assertive role="status" region for transient state (“Quill is responding”, “Quill responded”).
• Each message is an <article> with a heading (the speaker), so users can navigate the transcript by heading.
• The edit field is in the page — a labelled <textarea> with a Send button. Enter sends, Shift+Enter inserts a newline. Submissions post back to Python over a script-message bridge (window.quill.postMessage ↔︎ EVT_WEBVIEW_SCRIPT_MESSAGE_RECEIVED) which drives the on-device assistant directly. The wx text field only appears in the list-box fallback when no WebView backend exists.
• Suggested prompts disappear after the first message (like Apple Intelligence): they show on open so the user has a starting point, then hide themselves once the conversation begins so they never sit in the way of the chat.
• lang, viewport, readable type, and high-contrast / forced-colors CSS.
• The greeting is baked into the initial page so there is no “empty then rendered” flash on open. Messages and state changes that arrive before the page finishes loading are queued and replayed on the LOADED event.

Focus lands in the web view’s edit field on open (screen-reader behavior). When the chat opens, focus is moved directly into the in-page message field (AccessibleWebView.focus() → focuses the <textarea>, via wx.CallAfter) rather than onto surrounding chrome — so the user “jumps into the web view” ready to type, and the screen reader starts inside the live conversation. After a reply we do not steal focus back (the live region already announced it); after an approval we return focus to the edit field. (Implemented in AskQuillChatDialog.show() / _focus_composer().)

Prism announcements (screen-reader-first). In addition to the WebView’s ARIA live region, Quill uses the Prism (prismatoid) bridge on Windows to send response text straight to the active screen reader, so the user hears new replies even without alt-tabbing to the chat. Prism never speaks over a running screen reader — its SAPI 5 self-voicing fallback is suppressed whenever a screen reader is detected.

Approval before anything is applied. Each turn the assistant decides (answer / insert / replace / run) but never edits the document automatically. Insert/replace text and command runs are shown as a proposal with an Approve / Discard bar; focus moves to Approve and the screen reader is told a change is proposed. Only on Approve does Quill insert, replace the selection, or run the command. There is also Copy Last Response and labeled suggestion prompts.

Discoverability and reliability. Ask Quill lives under a top-level AI menu (Alt+I) alongside the “Use Artificial Intelligence” toggle and AI Model settings. Generation runs off the UI thread. The single-instance lock self-heals (PID + creation-time identity) so a stale lock from a crash never blocks launch.

Voice reply delivery (core/ai/voice_reply.py, ui/voice_reply_dialog.py, ui/assistant_reply_delivery.py). Ask Quill has always supported a spoken question (Ctrl+F9 → offline transcription → send), but the answer had exactly one delivery path: _announce_incoming, a whitespace-collapsed 140-character summary handed to the screen reader. Two full speech stacks already existed and were wired only to document read-aloud — QUILL’s offline voices, and the cloud AI voices in core/ai/cloud_tts.py (OpenAI 11 voices, Gemini 30, ElevenLabs export-only). The join was missing.

ai_voice_reply_mode selects one of four deliveries — announce (default, unchanged behaviour), text, local_tts, ai_voice — and ai_voice_reply_announce_limit (0–2000, 0 = no cap) governs announcements only. Truncation is deliberately not applied to the spoken modes: a character cap is the right shape for a summary and the wrong shape for speech, where stopping mid-sentence is worse than not speaking.

truncate_announcement() is the single rule every announcement in the chat shares — replies, errors, and edit proposals alike. It replaces a literal 140 that lived inside the panel’s announcement helper, which meant the configured length governed replies while errors and proposals silently kept the old number. Errors and proposals remain announcements whatever the reply mode (a 4,000-character error read out in full helps nobody); they simply respect the same length. The limit is read once per chat session rather than per utterance, since it sits on the path of every announcement and reading settings is file I/O.

Policy lives in plan_voice_reply(), which is wx-free, synchronous, and returns a VoiceReplyPlan the UI performs; the mechanics (threads, wx, TTS calls) stay in the UI mixin. Two invariants hold in the policy layer: a plan never both speaks and announces (that would talk over itself), and every degradation moves towards the offline default, never away from it. An ai_voice mode with no API key, or with an export-only provider (ElevenLabs), falls back to local_tts and then to announce, carrying a fallback_reason the UI states once — silently doing something other than what a setting says is how trust in the setting is lost.

The dialog is the single place the whole chain is configured, and it closes a real defect: ai_tts_voice was surfaced in the generic settings list as one flat catalog of every provider’s voices, so a Gemini voice could be selected while ai_tts_provider was OpenAI, failing only at synthesis. The model and voice lists are rebuilt from the selected provider, making the invalid pairing unrepresentable. Cost and egress are stated in the dialog body (not a footnote) with a live estimate from estimate_cost_usd, because ai_voice is the only mode that bills money and transmits the reply text off the machine. It is opt-in and never selected on the user’s behalf.

Voice conversation mode (Alt+Shift+Q) predates the setting and has always spoken its answers; while the setting is at its default it continues to, so entering voice mode does not silently become text-only. An explicit choice always wins.

5.77 Copy Tray — twelve-slot persistent clipboard

Copy Tray gives users twelve independently addressable clipboard slots that survive application restarts. Each slot holds text explicitly placed there; slots are written atomically to disk on every change.

Motivation. The system clipboard holds one item and is shared across every running application. Screen-reader users who work across multiple documents, do research from multiple sources, or paste recurring fragments (signatures, disclaimers, code boilerplate) lose clipboard contents constantly because any copy from any app overwrites it. Copy Tray is a private, persistent alternative.

Core operations.

• Copy to slot N — copies the current selection to slot N (1–12). Reports the slot number, optional label, and a text preview through the screen-reader bridge.
• Paste from slot N — inserts the slot’s text at the cursor (or replaces the selection). Reports slot number and label. Supports multi-press: single=paste, double=peek, triple=open dialog.
• Copy to Next Empty Slot (edit.copy_to_next_slot) — copies the selection to the first unoccupied, unpinned slot in order 1–12. Announces which slot was used. If all slots are occupied, announces this rather than silently overwriting.
• Search Tray Slots (edit.search_tray_slots) — opens a minimal search dialog. User types a query; QUILL searches all slot text and labels and announces matches. The user can press a digit key to paste that slot directly.
• Open Copy Tray dialog — shows all twelve slots with slot number, optional label, and a text preview. Inline editing of content and label; auto-save on slot change. Includes Pin/Unpin button.
• Set label — names a slot with a short string. Labels are spoken in all subsequent announcements, visible in the dialog, and shown in the Paste from Tray submenu alongside a text preview.
• Pin / Unpin — marks a slot as pinned from the dialog. Pinned slots are never overwritten by next-empty routing and are announced with a “pinned” prefix.
• Clear All Tray Slots — empties all twelve slots after a Yes/No confirmation defaulting to No.

Multi-press paste. The paste chord supports three levels of intent:

The press window is configurable via multi_press_window_ms (default 400 ms, range 100–1000 ms; found in App > Preferences > Editing). This lets expert users check what a slot holds before committing — useful for a crowded tray where memory may be unreliable.

Paste submenu slot labels. The Edit > Copy Tray > Paste from Tray menu shows each slot’s label and a text preview inline (e.g. “1 signature — Hi, I wanted to follow…”). Screen readers read both columns when navigating the submenu.

Status bar cell. The copy_tray_slots status bar cell shows Slots: X/12 (occupied count). Clicking it opens the Copy Tray dialog.

Keyboard defaults.

The paste bindings use the number row directly for maximum speed. The copy bindings use the QUILL-key prefix to distinguish from heading shortcuts. All bindings are reassignable via the Keymap Editor.

Storage. copy_tray.json in the QUILL user data directory. Atomic write (os.replace). Version-tagged JSON; corrupt files fail silently (fresh state, no crash).

Accessibility guarantees. Every operation announces through the screen-reader bridge: “Copied to slot 1”, “Pasted from slot 3 (signature)”, “Slot 5 is empty”, “Slot 2: by the way” (peek). The dialog list receives focus on open. Empty and non-empty slots are announced distinctly. The clear-all confirmation defaults to No.

Implementation map. quill/core/copy_tray.py (pure model, mypy-clean; TraySlot with pinned field, pin_slot, unpin_slot, first_empty_slot, search_slots), quill/core/multi_press.py (MultiPressDispatcher, wx-free), quill/ui/main_frame_copy_tray.py (mixin: multi-press wiring, copy_to_next_slot, search_tray_slots, _TraySearchDialog, _update_paste_tray_labels), quill/ui/copy_tray_dialog.py (dialog with Pin/Unpin button), quill/core/keymap.py (24 slot commands + 4 management commands). Menu: Edit > Copy Tray submenu including “Copy to Next Empty Slot” and “Search Tray Slots…”.

5.78 Abbreviation Expansion — TextExpander-style bare-word shortcuts

Abbreviation Expansion replaces short trigger words with longer text automatically as you type, when enabled (it ships off by default so nothing changes under the user’s hands unannounced). It complements the snippet system (which requires an explicit trigger prefix) by firing on any bare word followed by a delimiter.

Motivation. Typing common phrases repeatedly is fatiguing and slow. TextExpander and similar tools are widely used but require separate purchase and licensing. QUILL’s built-in abbreviation engine gives screen-reader users the same productivity gain with no external dependency and full keyboard control over every setting.

How it works. When the user types a trigger word (e.g. btw) followed by any delimiter character — space, period, comma, semicolon, colon, exclamation mark, question mark, closing bracket, closing brace, tab, or newline — QUILL:

1. Detects the trigger at the cursor.
2. Looks up the trigger in the library (longest match first; case-insensitive by default).
3. Replaces the trigger with the expanded text.
4. Positions the cursor as specified (at ${cursor} if present, otherwise after the expansion).
5. Optionally plays a configured sound.
6. Announces the expansion through the screen-reader bridge.

Default library. Fifteen built-in abbreviations ship out-of-the-box: afaik → as far as I know, afaict → as far as I can tell, asap → as soon as possible, atm → at the moment, btw → by the way, fwiw → for what it’s worth, imo → in my opinion, imho → in my humble opinion, irl → in real life, omw → on my way, tbh → to be honest, tbc → to be confirmed, tbd → to be determined, ttyl → talk to you later, wrt → with regard to. These are declared as _BUILTINS in abbreviations.py.

Variables. Expansion bodies support:

Keyboard defaults.

Per-abbreviation settings (schema v2). Every entry decides its own behaviour rather than inheriting one global policy. abbreviations.json is stamped version 2; each new field has a default, so a v1 library loads unchanged and a v2 library opened by an older build simply ignores the extra keys and still expands.

Unknown values in a hand-edited file degrade to the safe default rather than failing the load. Abbreviation.accepts_trigger(char) is the single place the trigger rule is decided, used by both the editor matcher and the system-wide one.

Fill-in fields. ${field:Label} and ${field:Label=default} make an expansion ask before it finishes; a label used twice is asked once and filled everywhere (matched case- and whitespace-insensitively). The rules are one wx-free module (core/expansion/fields.py) and the form one shared dialog (ui/fill_in_dialog.py, entry point prompt_for_fields), so a template behaves identically in the editor, in Quick Insert, and in Quill Inkwell. The expansion is re-resolved from the filled template rather than patched afterwards, so ${cursor} still lands correctly once the answers have changed the text’s length; a cancelled form leaves the typed text untouched.

Quick Insert. quill/ui/quick_insert_dialog.py – a type-to-filter picker over every enabled abbreviation, ordered most-used first, with a live preview of the full expansion. Inserts at the caret, resolving variables and honouring ${cursor}. Shared verbatim with Quill Inkwell (§5.86), which is the point: one library, one picker, two hosts.

System-wide expansion. Abbreviations also expand outside QUILL, through Quill Inkwell – see §5.89f. Both read and write the same abbreviations.json; neither imports from the other.

Only one expander per window. QUILL’s editor expansion always wins inside QUILL: it edits the document directly, so it is instant, keeps the editor’s own undo, fires abbreviation.expanded for Quillins, can run handler-based contributed abbreviations, and works in Safe Mode where no keyboard hook exists. AbbreviationsMixin._claim_own_expansion marks the frame with the QuillHandlesOwnExpansion window property at startup and a running Inkwell refuses that window outright. Without the marker a single keystroke would fire both paths and mangle the text.

Settings. Four settings in Editing preferences:

• abbreviation_expansion (bool, default False) — master on/off. Off by default so text never auto-changes as the user types without their knowledge; the user opts in and the choice is then remembered.
• abbreviation_expansion_sound (bool, default False) — play a sound on expansion.
• abbreviation_expansion_sound_file (text) — path to a .wav file; blank = system default beep.
• multi_press_window_ms (int, default 400, range 100–1000) — time window for double/triple press detection across all multi-press chords (copy tray peek, command palette re-run, etc.).

Status bar. The abbreviations status bar cell shows ABR: On or ABR: Off. Clicking it toggles expansion. Hidden by default; add via status bar settings.

Storage. abbreviations.json in the QUILL user data directory. Atomic write. Default library written on first launch if file is absent.

Interaction with snippets. Abbreviation expansion fires before snippet expansion in _on_text_changed. If an abbreviation match is found, snippet expansion is skipped for that keystroke. The ;-prefix snippet trigger is disjoint from bare-word abbreviation triggers so conflicts are practically impossible.

Accessibility guarantees. Every expansion announces “Expanded: <preview>” through the screen-reader bridge. Manual trigger (Ctrl+Shift+Grave, A) announces “Expanded to: <preview>” or “No abbreviation match”. Toggle announces “Abbreviation expansion on/off”.

Abbreviation Manager dialog. quill/ui/abbreviation_manager_dialog.py — A11Y-4 compliant, registered in the dialog inventory. Features: search field (filters the list in real time), Import button (merges a JSON file, skips duplicate IDs, announces count), Export button (saves full library to a JSON file). Disabled abbreviations shown with “(disabled)” suffix.

AbbreviationLibrary class API (all methods on quill/core/abbreviations.AbbreviationLibrary):

• add(abbr, expansion, **kwargs) -> Abbreviation — adds a new abbreviation, generates a UUID.
• remove(id) -> None — removes by ID.
• enable(id) / disable(id) -> None — toggle without deletion.
• update(id, **fields) -> Abbreviation — updates one or more fields; uses object.__setattr__ for slots=True dataclass.
• all() -> list[Abbreviation] — full library in insert order.
• enabled_only() -> list[Abbreviation] — only enabled entries.
• find_by_trigger(text, case_sensitive) -> Abbreviation | None — looks up by trigger word.

Implementation map. quill/core/abbreviations.py (pure model, mypy-clean: Abbreviation dataclass, AbbreviationLibrary, try_expand, resolve_expansion, _BUILTINS), quill/ui/main_frame_abbreviations.py (AbbreviationsMixin), quill/ui/abbreviation_manager_dialog.py (management dialog with search + import/export). Menu: Insert > Expand Abbreviation, Insert > Manage Abbreviations..., Insert > Toggle Abbreviation Expansion.

5.78a Quillin-contributed insert automation — abbreviations and smart triggers

Quillins declare two Insert Automation contribution types in their manifests (contributes.abbreviations, contributes.smart_triggers); QUILL dispatches both.

Contributed abbreviations. At Quillin load, abbreviations.build_contributed_library merges every installed manifest’s static abbreviation entries (those with an expansion) into a separate in-memory AbbreviationLibrary — deterministic namespaced ids (quillin:<id>:<trigger>), rebuilt on every reload, never persisted into the user’s abbreviations.json. Handler-based entries (e.g. Smart Insert’s qbrf) are skipped: the bare-word expander cannot run a handler mid-type, so dynamic content is reached via a smart trigger or menu command instead. Expansion order: the user’s own library is tried first, the contributed library only on a miss, so a user abbreviation always beats a contributed one with the same trigger; across Quillins, first-loaded wins. Each entry honours the Quillin’s own enable_abbrev_<trigger> setting (default: the manifest’s enabled_by_default), and the global Abbreviation Expansion master toggle gates everything. Core: quill/core/abbreviations.py; host wiring: main_frame_quillins.py (build) + main_frame_abbreviations.py (_try_expand_contributed). Unit-tested in tests/unit/core/test_abbreviations_contributed.py.

Smart triggers (=name(args)). A smart trigger is a line that is exactly =name(arg, arg) (whitespace-tolerant) activated with Enter. The parser (quill/core/quillins/smart_triggers.py, pure/wx-free, unit-tested) requires the trigger to occupy the whole line and a name-then-parens shape, so prose containing =foo(), a bare =5, or spreadsheet-style =a+b never fires. Arguments are comma-separated, stripped, empties dropped. Resolution checks: name known (index across installed manifests, first definition wins on collision), trigger enabled (per-Quillin enable_<name> setting; non-bundled commands also require the SEC-8 third-party flag), and declared min_args/max_args bounds. On dispatch the editor removes the trigger line, runs the linked command at that position with a context of {"trigger", "args"} (handlers receive the args — e.g. =todo(10) builds a ten-item list, =rand(3,4) three paragraphs of four lines, both clamped to sane maxima), and fires the smart_trigger.entered Quillin event with the same payload. A disabled or unknown trigger leaves the line untouched and Enter behaves normally. Host wiring: MainFrame._handle_smart_trigger_return (Enter interception, before Markdown list continuation) → QuillinsMenuMixin.dispatch_smart_trigger_line.

5.79 Ask AI — lightweight in-editor AI chat

Retired in 2.0 (see §5.84a). Ask AI has been folded into the single context-aware Ask Quill conversation; the standalone dialog and its command were removed so there is one chat door. This section is retained for history.

Ask AI is a modal dialog that lets users send a prompt to a configured AI provider and read the response without leaving QUILL. No document text is changed; the dialog is purely informational.

Motivation. Screen-reader users frequently need to ask a quick question while writing — define a term, check a fact, explore a phrasing option — and switching to a browser or a separate AI client breaks flow, especially when using NVDA or JAWS where switching applications involves extra navigation. Ask AI keeps the interaction entirely within the QUILL keyboard model.

Entry point. AI > Ask AI... (Command Palette) and AI > Writing Assistant... (Alt+Q default chord). The Command Palette entry is “Ask AI”. The binding is user-reassignable.

Providers. Three providers are supported. QUILL detects which keys are configured and only shows available providers.

Smart focus. When the dialog opens, focus lands in the Prompt field if the provider and model are already configured. If not yet configured, focus starts on the Provider choice so the user is guided to set it up first.

Dialog layout.

Provider:  [OpenRouter v]
Model:     [claude-3-5-sonnet v]
Prompt:    [multiline — Ctrl+Enter to send]
[Send]  [Clear]  [Close]

The response opens in a separate read-only dialog (model label at top, scrollable text area, Copy to Clipboard, Close). Closing the response dialog returns focus to the Ask AI dialog so the user can ask a follow-up without reopening.

Settings (in Preferences > AI):

Keys stored in Windows Credential Manager (never in settings.json): quill-openrouter-api-key, quill-openai-api-key.

Safe Mode. The Ask AI menu item and dialog are disabled when QUILL_SAFE_MODE=1.

Network egress. Audited in network_egress_audit.py: openrouter_chat, openai_chat, ollama_chat, openrouter_models, openai_models, ollama_models. Timeout: 60 s for chat, 10 s for model list.

Implementation map. quill/core/ai_chat.py (provider abstraction: send_prompt, list_models), quill/ui/ai_chat_dialog.py (Ask AI dialog + AI Response dialog, A11Y-4 hardened, registered in dialog inventory).

5.80 Check Grammar with AI

Check Grammar with AI sends the current selection (or full document if nothing is selected) to the configured AI model with a grammar-review prompt and displays the result in the AI Response dialog. No edits are applied automatically.

Entry point. Edit > Grammar > Check Grammar with AI. Command Palette: “Check Grammar with AI”. User-assignable binding; no default chord.

Default prompt.

You are a grammar and style editor. Review the following text and list
only the corrections needed. For each correction, give: the original
phrase, the corrected phrase, and a one-sentence reason. Do not rewrite
the whole passage. If the text is correct, say "No issues found."

Text:
{selection}

When Phase 3 (§5.81) is active, the command uses the user’s “Check Grammar” prompt from the Prompt Library instead, so the instruction text is fully customisable.

Model selection. Uses settings.ai_prompt_default_model when set, otherwise falls back to settings.ai_chat_default_model. This lets users choose a different (e.g. more capable) model for grammar review than for casual chat.

Implementation. Single method check_grammar_with_ai() in MainFrame. Runs on a background thread (threading.Thread, daemon=True); UI updates via wx.CallAfter. Command id: tools.check_grammar_ai.

5.81 AI Prompt Library

The Prompt Library is a named, user-expandable collection of AI instructions. Each prompt operates on the current selection or document: the user picks a prompt, QUILL sends the text and the prompt to the AI, and a response dialog shows the result. No document text changes without explicit action.

Motivation. Power users accumulate a personal set of AI instructions they run repeatedly — improve clarity, vary sentence rhythm, convert to bullets, generate an outline. Without a library, these prompts must be retyped or pasted from an external file each time. The Prompt Library turns these into first-class named commands, accessible from the keyboard, the command palette, and the dialog.

Entry point. AI > Prompt Library.... Command Palette: “Prompt Library”. User-assignable binding.

Prompt object fields.

Built-in prompts (12). Shipped defaults, always present, user-editable:

• Editing: Check Grammar, Improve Clarity, Fix Grammar, Make Concise, Active Voice, Formal Tone, Conversational Tone
• Writing: Continue from Here
• Structure: Convert to Bullet Points
• Research: Define This Term, Find Counterarguments
• Custom: (none shipped; user-created)

Prompt Library Dialog. Split layout: left panel shows a searchable list of all prompts (filtered by the search field in real time); right panel shows the selected prompt’s text and an optional input override. Buttons: Run with AI, New Prompt, Edit, Disable/Enable, Delete, Import .pqp, Export .pqp, Close. A11Y-4 hardened, registered in the dialog inventory.

Settings.

Storage. %APPDATA%\Quill\prompts.json — atomic write, schema-validated. Built-in prompts are not persisted; only user additions and overrides to built-ins are stored.

Quillin bridge. A Quillin may ship a prompts.json file alongside its manifest. QUILL loads it automatically when the Prompt Library opens, adding those prompts to the library for the session (not persisted to disk). The bundled ai-writing-prompts Quillin ships 7 additional prompts this way: Expand This, Vary Sentence Rhythm, Make More Vivid (Writing); Write a Title, Generate Outline (Structure); Suggest Supporting Evidence (Research); Plain Language (Editing).

Implementation map. quill/core/prompt_library.py (Prompt dataclass, PromptLibrary CRUD, .pqp import/export, Quillin prompt loading), quill/ui/prompt_library_dialog.py (Prompt Library dialog), quill/quillins_bundled/ai-writing-prompts/ (bundled prompt pack).

5.82 Prompt Quill Pack (.pqp) — shareable prompt collections

A .pqp (Prompt Quill Pack) file is a JSON document that packages a named collection of prompts for sharing or backup.

File format.

{
  "schema": "quill.prompt-pack/1",
  "name": "My Writing Prompts",
  "prompts": [
    {
      "name": "Make Punchy",
      "text": "Rewrite this as a punchy one-liner: {selection}",
      "category": "Editing"
    }
  ]
}

Import. Via the Import .pqp button in the Prompt Library dialog. Prompts whose name already exists in the library are skipped; the count of newly added prompts is announced.

Export. Via the Export .pqp button. Exports all user-defined prompts (or a selected subset). Built-in prompts can optionally be included when the user has edited them.

Use case. A writing team can share a .pqp file containing their house-style prompts. A power user can back up their library and restore it on a new machine. A Quillin author can distribute prompts as a .pqp for users who prefer not to install a Quillin.

5.83 Quillin Manager — install, update, and remove extensions

The Quillin Manager (Tools > Quillins) lets users discover, enable, disable, and uninstall Quillins. As of this version it also supports installing a new Quillin directly from a local folder.

Install from Folder. The Install from Folder button opens a system folder picker. QUILL reads the selected folder’s manifest.json, validates it, copies the directory into the per-user extensions root (%APPDATA%\Quill\extensions\<id>\), enables the Quillin, and refreshes the list. If an extension with the same id is already installed, it is replaced. Path containment is enforced: a crafted extension id cannot install files outside the extensions root.

Remove. Selecting an extension and pressing Remove deletes its directory and removes its state entry. Confirmation is required.

Enable/Disable. Toggle without uninstalling. A disabled Quillin’s prompts and commands are not loaded.

Manifest display. Selecting a Quillin shows its name, version, author, description, declared capabilities, and any validation errors. This gives users the information they need to make an informed trust decision before enabling.

Security model (SEC-8). Third-party Quillin discovery (auto-scanning the extensions root) is locked off for QUILL 1.0 (core.third_party_plugins feature flag is locked_off). Install from Folder is the only way to add a third-party Quillin. The user must explicitly choose the folder, providing informed consent equivalent to “install this extension”. Bundled Quillins (shipped inside the QUILL install tree) are always discovered and are not affected by the SEC-8 lock.

Implementation map. quill/core/quillins/loader.py (install_extension, remove_extension, set_enabled), quill/ui/main_frame_quillins.py (QuillinsManagerMixin — manager panel, Install from Folder button and handler).

5.83a The Quillin Hub — community distribution for every shareable artifact

The Quillin Hub (hub.quillforall.org; service code in quillin-hub/) is the community store and submission surface for every shareable QUILL artifact type, not just Quillin extensions. Seven artifact families are accepted for review and publication:

One validation authority. python -m quill.tools.artifact_validate <path> [--type ID] [--strict] [--json] detects the artifact type (by suffix, manifest sniffing, or schema markers) and dispatches to the per-type validator listed above. The Hub’s Submission Forge, CI, and the in-app submission check all run this same tool, so an author never sees three different verdicts. Exit codes follow the validator convention (0 pass, 1 issues, 2 not found/undetectable); --json emits the machine-readable report the Forge consumes.

The Submission Forge. The Hub’s /forge/submit flow accepts any supported file, auto-detects the type (with a manual override), and runs a three-stage audit: (1) artifact_validate validation; (2) for Quillins only, a Bandit scan plus the AST SecurityWatchdog capability-honesty check (undeclared fs/net/stability imports and eval/exec fail the submission); (3) metadata extraction from the artifact’s own manifest or front matter so authors never retype name/version/description. The result is an accessible plain-language Forge Report; publication itself stays GitHub-native (a guided pull request), keeping review transparent.

Registry API. /api/v1/types, /api/v1/artifacts[?type=…], and /api/v1/artifacts/<id>/latest serve the verified catalog to clients; the original /api/v1/plugins endpoints remain as Quillin-only aliases. A sync worker mirrors artifacts that land on main (bundled/example Quillins, catalog agents, bundled .sqp skills) into the storefront as Verified.

In-app tie-in. Tools > Quillins > Submit to Quillin Hub… (tools.quillin_hub_submit) runs the identical artifact_validate checks locally and reports pass/fail in an accessible hardened dialog. Picking a Quillin’s manifest.json validates the whole folder (the accessible alternative to a directory picker). The Quillin Hub website opens in the browser only on the explicit “Open the Quillin Hub” button — QUILL itself makes no network call anywhere in the flow, so the command needs no egress-audit entry.

Roadmap linkage. Public deployment of the Hub is #517 (O14); the signing/marketplace trust model that would let vetted third-party Quillins load off the SEC-8 experimental flag is #519 (O16). This section covers the submission/validation platform and the in-app surface; signing and deployment remain open acceptance criteria on those issues.

Implementation map. quill/tools/artifact_validate.py (detection + dispatch; tests in tests/unit/tools/test_artifact_validate.py), quill/ui/quillin_hub_submit.py (submission-check dialog), quill/ui/main_frame_quillins.py (menu item + command), quillin-hub/ (Flask service: app/artifacts/registry.py, app/forge/, app/api/, worker/sync_to_pages.py, smoke_test.py).

5.84 Skill Quill Pack (.sqp) — multi-step AI workflows in plain text

A .sqp (Skill Quill Pack) file is a Markdown document with YAML front matter where level-1 headings define sequential AI steps. It extends .pqp prompt packs from single instructions to multi-step workflows with parameters, variable chaining, and conditional branching.

Motivation. Many real AI tasks are not single-shot prompts. Research then draft. Analyse then rewrite. Detect intent then branch. Encoding this logic in JSON means writing a DSL nobody can author without tooling. Writing it in Markdown means any user can open the file, read every step, and edit it — no schema browser, no visual designer. The skill is the document.

Key design choices:

• No streaming — each step sends a full prompt and receives a full response before the next step runs. This makes step outputs reliable as inputs to subsequent steps.
• Synchronous execution from the caller’s perspective; threading is the UI layer’s responsibility.
• Depth limit of 2 for nested skill calls to keep execution predictable.

File format (quill.skill/1).

---
schema: quill.skill/1
name: Research and Draft
description: Extracts topic, gathers facts, drafts a paragraph.
author: QUILL Project
version: 1.0.0
parameters:
  - name: tone
    label: Tone
    type: choice
    choices: [formal, conversational, neutral]
    default: neutral
---

# Step 1: Extract topic

Identify the main topic in: {selection}

# Step 2: Research

List five facts about "{step1.output}".

# Step 3: Draft

Write a {parameters.tone} paragraph weaving in those facts.
Facts: {step2.output}

```output
format: text
label: Drafted paragraph
accept_into: selection