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.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: a screen-reader-friendly helper provides recipe presets, plain-language explanations, editable sample text, live match previews, and copy-pattern actions.
• 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 with the raw python-docx extract as 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.
• 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. A single unnamed, one-shot jump point, distinct from named bookmarks: Ctrl+Shift+K sets it at the cursor with no dialog; Alt+Shift+K jumps to it with no picker. Session-only by design (never written to DocumentMemory) — it is disposable scratch state, not a durable anchor. Implemented as MainFrame.set_temp_bookmark/go_to_temp_bookmark, aliased per-tab exactly like the named-bookmark dict.

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).
• 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.
• 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:

• Alt+Up / Alt+Down: move the current line (or all selected lines) up or down. Announces the swap.
• Ctrl+Shift+D: duplicate the current line or selection.
• Ctrl+Shift+K: delete the entire current line.
• Ctrl+L: select the current line (repeat to extend by line).
• Ctrl+J: 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.).
• Ctrl+Shift+/: toggle block comment where supported.
• 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).

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.

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 Audio Studio (Tools → Speech → Audio Studio…). 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 (Tools → Speech → Audio Studio…) — 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.
• Audio Studio shared listening modules + workbench player-observation contract (shipped, surfaced by the standalone). 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 (fully backward compatible — its single call site is unchanged), and the standalone QUILL-AS Studio shell wires them to route media keys (Play/Pause, Stop, Next/Previous chapter via RegisterHotKey), persist per-book volume/mute, stamp Recently Played history, and auto-advance the play queue on finish-then-close. 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. All are vendored into QUILL-AS; 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).
• 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, five surfaces. A single wx-free engine (core/audio/convert.py, presets.py, dsp.py, url_import.py, convert_cli.py) is surfaced through: the Audio Studio dialog (Voices → Convert Audio…, ui/audio_studio/convert_audio_dialog.py); a standalone Quill Converter app (apps/converter.py, an AppShellFrame registered in core/app_launcher.py); a headless quill convert CLI; a Windows Explorer “Convert with Quill” shell verb (core/shell_verbs.py, gated by shell_verb_convert, routed through --action convert to the converter app); and Convert from URL (on-demand yt-dlp, consent-gated, egress-audited).
• 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.
• Deferred: the standalone app’s PyInstaller build entry + launcher tile icon (after the build refactor settles); the app runs today via python -m quill.apps.converter.

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 → Report a Bug… is the unified support flow. It opens an in-app review screen with the report summary and destination URL, supports optional diagnostics zip generation, copies the environment summary to the clipboard, and then opens a pre-filled Community Access support-hub issue form in the default browser with no logs; the user reviews and submits manually.
• 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.

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.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 → 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) links to the release notes for the version it is offering, shows the published date when the feed provides it, and lets the user Skip this version, Download, or decide Later.
• 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): Compare with File…, Compare Open Documents…, Next Difference, Previous Difference, Announce Current Difference, Difference List…, Toggle Synchronized Navigation, Compare Options…, Create Difference Summary, Copy Current Difference, Copy All Differences. A Navigate → Compare submenu carries the same commands under the tools.compare_* ids.
• Core navigation (Navigate → Compare, 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.

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.

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

**Special blocks inside steps:**

| Block type | Purpose |
| --- | --- |
| `` `input` `` | Appends literal data to the prompt text |
| `` `condition` `` | Branches execution: `if: "X" contains "Y" / then: step3 / else: step4` |
| `` `output` `` | On last step: `format` (text/list/json), `label`, `accept_into` (selection/clipboard/none) |
| `` `use-prompt` `` | Delegates to a named prompt from the Prompt Library |
| `` `use-skill` `` | Calls another skill (depth-bounded) |

**Variables.** `{selection}`, `{document}`, `{title}`, `{clipboard}`, `{stepN.output}`, `{parameters.name}`.

**Validation tool.** `python -m quill.tools.sqp_validator <path>` validates one file or a directory. Exit 0 clean, exit 1 errors, `--strict` also checks for missing metadata.

**Bundled skills.** The `ai-writing-skills` Quillin ships four sample skills: Accessible Rewrite, Research and Draft, Meeting Notes to Action Items, Argument Strengthener.

**Implementation map.**

| File | Role |
| --- | --- |
| `quill/core/skill_pack.py` | `SkillPack` dataclass, `.sqp` parser, validator, synchronous runner |
| `quill/tools/sqp_validator.py` | CLI validator |
| `quill/quillins_bundled/ai-writing-skills/` | Four bundled `.sqp` skill files |
| `tests/unit/core/test_skill_pack.py` | 23 tests: parsing, validation, runner, branching, bundled files |

---

### 5.84a Unified AI Library and the four-pillar AI menu (2.0)

**Goal.** Replace the scattered AI submenu and its overlapping dialogs with one
confident, top-level `&AI` menu built on four pillars, so the user feels QUILL has
*one* AI that knows where they are.

**The four pillars.**

1. **Ask Quill** — the single, context-aware conversation. The legacy "Ask AI" and
   "Writing Assistant" chat dialogs are retired into it (`AskAIDialog` deleted;
   `open_ask_ai` / `tools.ask_ai` removed), so there is exactly one chat door.
2. **Do** — context-first actions: the Concierge's "What can I do here?"
   (`quill/ui/concierge_menu.py`), the Selection Action Ring ("Rewrite & Improve"),
   and Run Agent.
3. **AI Library** (`quill/ui/ai_library_dialog.py`) — Prompts, Skills, and Agents in
   one `wx.Notebook` with one verb set (Run, New, Edit, Enable/Disable, Import,
   Export) and a real **Promote** continuum. `prompt_to_skill_source` grows a Prompt
   into a Skill; `skill_to_agent_markdown` + `save_user_agent` grow a Skill into a
   first-class user Agent saved in `agent_catalog.user_agents_dir`, loaded alongside
   the bundled catalog by `load_full_catalog`. Prompt Studio and Agent Center are
   retired into this surface; the full agent linter is the Agents-tab **Validate**.
4. **AI Hub** — the single configuration front door: provider, key, model, engine
   switching (Engines tab), GitHub Copilot setup, and **Session Branches** (Sessions
   tab). The old "Engine & Sessions" submenu is removed.

**The menu shape.** The top-level `&AI` menu reads, in order: Set Up AI (the on-ramp,
§5.84c) · Ask Quill (+ by Voice) · Accessibility Tune-Up · the context "Do" entries
(hidden in Basic mode) · Proofread / Translate / Read Aloud / Transcribe / More
submenus · AI Library · AI Hub · Use Artificial Intelligence (and Show advanced AI
features). Item count dropped from ~36 scattered entries to a short, scannable list,
each a single high-value action or a clearly-labeled one-level-deep submenu.

**Confirmed product decisions.** (1) AI is a real top-level `&AI` menu unconditionally
— the former `future.ai_menu_top_level` flag is retired as a placement switch. (2)
"AI Library" is the name for the unified Prompt/Skill/Agent manager. (3) The
Prompt → Skill → Agent **Promote** continuum is in scope and shipped. (4) Accessibility
Tune-Up stays a first-class, top-of-menu item given the screen-reader audience.

**Invariants.** Every list item and dynamic menu entry has a meaningful accessible
name; all dialogs go through `_show_modal_dialog` + `apply_modal_ids`; running any
action announces start and result; nothing is more than one level deep; the Library
and continuum are wx-free at the core (`quill/core/ai/library.py`,
`quill/core/skill_store.py`). One custom-prompt store: `prompt_migration` consolidates
the legacy `assistant_prompts` into the canonical `PromptLibrary` at startup
(reversible, idempotent). Deprecated dialogs retired; the live `assistant_agents`
plan/profile helpers stay (they back a live agent-run path), and `assistant_prompts`
stays until the prompt migration is sunset.

---

### 5.84b The Listening Companion — Transcript Actions and the Action Builder (2.0)

**Goal.** Make transcription the *beginning* of an agentic writing experience, not
the end: turn audio into the document the user actually needs, with a gentle, guided,
adjustable path. Folds the agentic transcription magic of BITS Whisperer into QUILL's
unified AI framework.

**Transcript Actions** (`quill/core/ai/transcript_actions.py`, wx-free). Ten
built-in actions — Meeting Minutes, Action Items, Executive Summary, Interview Notes,
Study Notes, Q&A Extraction, Clean Up & Draft, Follow-Up Email, Key Quotes, and
Decisions Log — each a named, plain-language, *adjustable* instruction with a prompt
builder. `recommend_actions` orders them for the transcript in front of the user
(multi-speaker leads with Minutes / Action Items / Decisions / a follow-up email;
question-dense with Q&A / Interview / Key Quotes; single voice with Clean Up & Draft)
while keeping every action available. Reachable two ways: the post-transcription "What
would you like me to make of this?" chooser (`quill/ui/transcript_actions_ui.py`,
hooked into `_show_transcription_result`) and an `AI > Transcribe Audio > Transcript
Actions...` item that runs them on the current selection/document. Results open in a
new buffer; the original transcript is never overwritten. Generation uses the unified
`ProviderChatBackend`; the flow degrades gently when AI is off, and offers the AI
Setup Wizard (§5.84c) at that high-intent moment instead of a dead end.

**Guided Action Builder** (`quill/ui/action_builder_dialog.py`). A no-syntax,
form-based builder (name, start-from preset, plain-language instructions, optional
**reference attachment**, Save) reached from the AI Library Skills tab. It writes a
real Skill via `action_to_skill_source` + `SkillStore`, so a user-defined action
immediately gains Run / Edit / Enable / Export / Promote. A reference document (txt /
md directly, docx and friends via markitdown) is woven into the saved action so its
output matches the user's template, terminology, and house style.

**Automation.** A watch-folder transcribe profile can chain "transcribe → run a
Transcript Action → save the document" next to the audio
(`watch_transcribe._maybe_make_action_document`), Do-Not-Disturb-aware. AI off / no
provider / a failed action skips the document step with a clear note and always keeps
the transcript.

**Principles (non-negotiable for this audience).** Easy (one choice, one keystroke),
delightful, guided, principled (consent + preview + undo + private by default),
powerful (the full agentic stack underneath), adjustable by instruction and prompt,
and gentle for learners.

**Status: complete.** Shipped: Transcript Actions (post-transcription and anytime),
the guided Action Builder, reference attachments, watch-folder automation, and the AI
onboarding wizard with Basic mode and on-ramps (§5.84c). **Live + diarized streaming
actions were deliberately not built:** most of that value is already delivered by file
transcription plus watch-folder automation, and its one genuinely unique kernel — live
captioning — is a separate accessibility feature that would need real-time audio
capture infrastructure; if it is ever wanted it should be scoped on its own merits, not
bolted onto this companion.

---

### 5.84c AI onboarding — the Setup Wizard, on-ramps, and experience modes (2.0)

**Goal.** Make getting started with AI a gentle, magical, screen-reader-first
experience across the whole AI landscape — no jargon, no dead ends, finished in
seconds — and let newcomers grow into the full surface on their own timeline.

**AI Setup Wizard** (`quill/ui/ai_setup_wizard.py` over wx-free
`quill/core/ai/onboarding.py`). A one-step-at-a-time wizard (each step a single
announced focus context): a welcome, the one real choice — **on your device with
Ollama** (private, free), **use an AI account** (Claude / OpenAI / Gemini / OpenRouter
/ Ollama Cloud, with a key pasted once and stored in the OS secure store, plus a
**Test connection** button), or **not right now** — a frictionless connect step, and a
tailored celebration. Neither path lets the user finish into a broken state: cloud
offers Test connection, and the on-device path **verifies a reachable local Ollama with
an installed model (`ollama_status`) before it commits** — if Ollama isn't running or
has no models, the step stays put with plain-language guidance (install from
ollama.com / `ollama pull ...`) rather than configuring something that won't work. The wx-free model owns the copy, the paths, the cloud-provider
options, the apply helpers (`apply_cloud_setup` / `apply_on_device_setup`), and the
persisted state, so it is fully unit-testable. Reachable as the first AI menu item
(**"Set Up AI... (start here)"** until done).

**On-ramps, not dead ends.** `maybe_offer_ai_setup` offers the wizard at the moment a
user first reaches for AI before it is configured — Ask Quill, the AI Library, and
Transcript Actions all route through it — and never nags someone who has already been
through setup. Because the AI Library's Run, Ask Quill, Transcript Actions, and agents
all share the one `ProviderChatBackend` (AI Hub) connection the wizard configures,
setting AI up once makes everything work.

**Experience modes.** `is_basic_mode()` / `save_experience_mode()` persist a Basic vs
Advanced choice (default **advanced**, so existing users never lose anything; the
wizard's "keep it simple" checkbox puts a newcomer into Basic). In Basic mode the AI
menu hides the power-user agentic entries ("What can I do here?", "Rewrite & Improve",
"Run Agent") so the surface stays calm; a **"Show advanced AI features"** toggle flips
it instantly. Everyday features (Ask Quill, Transcribe, Proofread, Translate, Read
Aloud, the AI Library) always stay.

---

### 5.84d Free / low-cost AI for everyone (writing-first)

**Goal.** Give every user a meaningful AI writing experience without a paid
flagship account, and without the project carrying unbounded per-user cost.
Flagship models are better, but the point is options for people who cannot afford
one and a sane default that meets people where they are. Agents work on the free
path too.

**Cost posture — bring-your-own free key + local, $0 to the project.** There is
no shared or hosted key. Each user either runs a local model (no key) or brings
their **own free key** (their own free daily quota), so there is no shared limit
and no cost or liability to the project. A subsidized/hosted proxy is explicitly
out of scope; the data layer is designed so a *capped* proxy could later be added
as an opt-in provider without reworking this.

**Two strongly-advised free paths, with good defaults** (`recommended_free_paths`
in `quill/core/ai/free_models.py`, surfaced on the wizard's connect step via
`FREE_PATH_GUIDANCE`):

1. **Best quality, free** — OpenRouter with the user's own free key. QUILL
   preselects a strong free writing model (`best_free_writing_model`, currently a
   Llama 3.3 70B free model). The model step's recommendation now leads with this
   free model rather than `openrouter/auto` (which can route to paid).
2. **Most private, free** — a fully on-device model (Ollama / bundled llama.cpp):
   no account, offline, nothing leaves the device; more modest quality.

The copy is honest: free hosted models can be slower and are rate-limited to the
user's own quota, and may log/train on prompts under their terms, so QUILL advises
keeping confidential writing on the on-device path.

**Get API key.** Every keyed provider in the wizard has a **Get API key** button
that opens that provider's signup page (`CloudProviderOption.signup_url`) in the
browser — no hunting for where to get a key. Disabled for on-device Ollama.

**Model dropdown (wizard + AI Hub).** The model is chosen from an editable
dropdown seeded with the provider's recommended ids (free-first for OpenRouter),
with a **List models** action to load everything the account/device exposes
(`onboarding.list_provider_models`); the AI Hub Provider tab uses the same pattern
(`_populate_hub_models` / `_on_hub_list_models`), replacing its old free-text
field, and refreshes suggestions when the provider changes.

**The free-model catalog** (`quill/core/ai/free_models.py`, pure/wx-free). Free
is **derived, not hardcoded**: a model is free when the provider reports zero
prompt+completion pricing, or (OpenRouter) its id ends in the documented `:free`
suffix — so classification survives OpenRouter rotating its free line-up. Models
carry a `cost_tier` (`free`/`low`/`flagship`), a coarse `writing_quality` rank,
and a `tool_use` capability flag. `fetch_classified_models` reuses the already
network-audited `ai_chat.list_models_raw` (no new egress site) to classify live
`/models` data by price. `resolve_model_for_task` advises the cheapest capable
model for a task verb (light verbs → free; heavy/agentic verbs → tool-capable).
The wizard's model description speaks a **Free** / **Local, free** cue
(`_cost_note`) so cost is audible where models are chosen.

**Agents degrade gracefully on small/free models.** Single-shot transform agents
(Rewrite, Summarize, Expand, Table of Contents — via `_run_agent_task` +
`build_agent_plan`) already run on any chat model. The multi-step Ask Quill
companion (`ConversationSession` tool loop) is capped to a near-single-shot step
budget on a model the catalog flags as unreliable at tool use
(`agent_editor_host._companion_loop_budget`), so a weak model **answers instead
of looping** on malformed tool calls — the turn's document context is already in
the prompt, so answering needs no tools. It is never a hard block, and the engine
label reads "simplified for a small model." Agent specs may declare
`needs_tool_use: true` (schema + `AgentSpec`) so the UI can note "works best with
a stronger model" (`free_models.stronger_model_hint`) while still offering them.

---

### 5.84e Agent harnesses — interchangeable agentic engines (shipped)

**Goal.** Let a user drive QUILL's agent with the AI agent they already pay for
— GitHub Copilot, OpenAI (ChatGPT), or Claude — without a second API key or
per-token cost, while keeping QUILL's edit-safety contract exactly as it is.

**The harness layer (`quill/core/ai/harness/`).** A *harness* is an
interchangeable engine that drives an agent session above the AI backend. QUILL
ships the **Native** harness (its own loop, always available) plus three
optional **SDK harness packs** in `quill/ai_packs/` — `copilot.py` (extra
`ai-copilot`, `github-copilot-sdk`), `claude.py` (extra `ai-claude`,
`claude-agent-sdk`), and `openai_agents.py` (extra `ai-openai`, `openai-agents`).
Every harness, native or SDK, drives the **same** `SafeEditorToolGateway` and
`PermissionBroker` and emits the **same** normalized `AgentEvent`s; a
`HarnessRegistry` tracks availability, and the Hub hides capabilities a harness
lacks rather than presenting a broken control.

**Safety law (non-negotiable).** The SDK packs run the vendor agent
**text-only** (`allowed_tools=[]`): the vendor's own file-editing and shell tools
are denied, and QUILL applies the produced text through its reviewed gateway —
permission broker, diff preview, one-step undo. The agent proposes; only QUILL
touches the document, and only with user approval. All of this is off by default
and disabled in Safe Mode.

**On-demand install (`quill/core/ai/sdk_install.py`).** The packs are never
bundled (large, fast-moving, and most users want exactly one). The first time a
user picks an engine, QUILL installs its extra with `pip` into the running
interpreter behind a consent + progress surface; the pack self-registers on the
next probe. An uninstalled pack reports `is_available() == (False, reason)` and
QUILL keeps working.

**Surfaces.** (1) **AI Hub → Engines tab** (`ai_hub_engines_panel.py`): list the
engines, **Set Up / Install...** (installs the pack, or opens the Copilot
onboarding dialog), and **Set as Active Engine**. (2) **AI Setup Wizard**: the
onboarding path *"Use an AI agent you already pay for"* finishes by opening the
Engines tab. (3) **GitHub Copilot sign-in** (`copilot_auth.py`): OAuth 2.0 device
flow (a short, speakable code) when a build provides `QUILL_GITHUB_CLIENT_ID`,
with a graceful fallback to the Copilot/GitHub CLI sign-in when it is not — so
Copilot works either way; the token lives in the OS secure store.

**Value.** Use the subscription you already hold ($0 extra), vendor-grade
orchestration inside QUILL's guardrails, and interchangeable engines that install
on demand so the base app stays lean.

---

### 5.84f Internet Radio (shipped)

**Goal.** Let a QUILL user listen to live internet radio in the background
while writing, without ever leaving the keyboard or the editor, and without
depending on an undocumented commercial API.

**Station discovery (`quill/core/radio/radio_browser.py`).** Search, tag, and
country lookups against [RadioBrowser](https://api.radio-browser.info), a
free, keyless, community-run station directory — chosen deliberately over
FastPlay's other two backends (TuneIn's OPML search, iHeartRadio's v2/v3
APIs), both undocumented, reverse-engineered commercial APIs with no public
terms. The client resolves a shuffled list of RadioBrowser's own mirror hosts
once per process and fails over across them on request failure, per
RadioBrowser's own documented recipe, rather than hammering one hardcoded
host. `core/radio/acb_media.py` bundles the American Council of the Blind's
ten Live365 stations as a static, always-available category (no network call
needed to see it) — researched from BITS's own `acb_link_desktop` project.
`core/radio/soma_fm.py` blends in [SomaFM](https://somafm.com), a second
free, keyless, curated directory, into the same Browse Stations results —
chosen over Shoutcast (revocable Developer-ID-gated API) and Live365
(partner-only distribution), neither of which offers an open public search.
`core/radio/link_finder.py` fetches one user-typed page and parses it
(`html.parser`, no embedded browser) for stream-shaped links, for stations
not in RadioBrowser's directory.

**JavaScript players — the Triton Digital / StreamTheWorld resolver
(`core/radio/triton.py`).** A large class of broadcast stations (thousands of
US AM/FM stations, and the entire `player.listenlive.co` network) put their
"Listen Live" button behind a Triton Digital web player. That player is a
JavaScript PWA: the actual stream URL is *never* in the page HTML — it is
computed at runtime when the player's JS calls Triton's provisioning API. So
the plain-HTML scanner above finds nothing on those pages, even though a Play
button is plainly visible. This was a real, reported gap
(`player.listenlive.co/34461`, "Magic 104.1"/KMGL).

The stream is nonetheless fully derivable **without running any JavaScript**,
from two static facts the page already exposes:

1. The station **callsign** (mount name) appears verbatim in the Triton PWA's
   own asset URLs — the station-logo image is served from
   `pwaimg.listenlive.co/<CALLSIGN>_<id>_config_station_logo_image_….png`
   (`callsign_from_page`, with a `station=<callsign>` query fallback).
2. Triton's **provisioning API** answers a plain HTTPS GET
   (`playerservices.streamtheworld.com/api/livestream?station=<CALLSIGN>&transports=http&version=1.9`)
   with an XML `<live_stream_config>` document listing every mountpoint (one
   per codec — MP3, HE-AAC — MP3 first) and its CDN servers. A playable URL is
   simply `https://<server>/<mount>` (`parse_livestream_config` →
   `resolve_station_streams`, parsed through the hardened `core/safe_xml` so a
   crafted response cannot mount an entity-expansion attack).

The scan only takes this path when the page *looks* like a Triton player
(`page_is_triton_player`) and advertises a callsign the API validates
(status 200), so a non-Triton page or a bad guess degrades to "nothing found",
never a wrong stream. It surfaces the resolved mount(s) as ordinary scan
candidates labelled "*MP3/AAC* stream from the station's player (*mount*)".
The one follow-on egress (`triton.py::_fetch_api`) is a reviewed entry in
`network_egress_audit.py`, reached only from the same explicit **Scan** button,
HTTPS-only, and disabled in Safe Mode via `triton.refuse_in_safe_mode`. This
also generically improves every Triton/StreamTheWorld station, not just the
one that prompted it. It cannot solve a fully generic JS player with no static
callsign hint — QUILL deliberately has no embedded arbitrary-site browser — but
Triton/listenlive.co is the large, tractable case.

**Self-healing stream recovery (`core/radio/recovery.py`, #1065).** A directory
station's listed stream can be dead even though the station is perfectly live —
usually because the real stream is behind a Triton/JavaScript player, so the URL
the directory carries (or one a user copied off the site's play button) is a
web-player address, not a stream. Rather than just failing, on a playback error
QUILL runs a confidence-ordered recovery ladder off-thread (`recover_stream`),
one attempt per station per session:

1. **Re-resolve a StreamTheWorld mount (high, always on).** If the failed URL is
   `*.streamtheworld.com/<MOUNT>`, that mount is re-resolved through Triton's API
   to its current server — deterministic, same station and provider.
2. **Refresh from the directory (high).** If the station has a RadioBrowser id,
   its current URL is re-fetched; a genuinely different URL is the directory
   self-healing (this subsumes the older byuuid-only fallback).
3. **Scan the station's website (opt-in, default on, off in Safe Mode).** The
   station's homepage — and the failed URL itself, when it is a web page — is
   scanned with the same Triton + "Listen Live" link-following logic Find Streams
   uses (`link_finder` now follows a bounded allowlist of listen/live/play/tune-in
   `<a>` links one level deep, since most homepages *link* to the player rather
   than hosting it). A single unambiguous result — a resolved Triton player, or
   exactly one stream candidate — is played automatically and self-heals the
   saved favorite; several candidates are announced so the user can pick them up
   in Find Streams, never auto-played.

Confident recoveries are announced and self-heal the favorite so the next play
starts from the good URL. Strategy 3 is a single opt-out
(`RadioHistory.recover_from_website`, Preferences) because it adds one homepage
fetch on failure; strategies 1–2 always run. All network goes through the
already-reviewed egress sites (`triton._fetch_api`, `radio_browser`,
`link_finder._fetch_html`); `recovery.py` itself makes no direct network call.

**Playback (`quill/ui/radio/player_controller.py`).** One
`RadioPlayerController`, owned by `MainFrame` for the process's lifetime,
wraps the Audio Studio's `WxMediaEngine` (never libmpv — `MpvAudioEngine`'s
poll loop gates "loaded" on a positive `duration`, which a live stream never
reports, so mpv cannot currently drive radio; this is a named, deliberately
deferred follow-up, not an oversight). Every dialog (station browser, add
custom station, website link finder) drives this same controller, so closing
any of them never stops playback — the mechanism that makes "listen in the
background while editing" work with zero new non-modal-panel architecture.
Radio's own volume (`set_volume`/`toggle_mute`) is independent of the system
volume mixer and of screen-reader speech volume.

**Surfaces.** `Tools > Media > Internet Radio` (Browse Stations, Add Custom
Station, Find Streams from a Website, Play/Pause, Stop, Mute, Volume Up/Down)
registers every command in `CommandRegistry` (command-palette visible, unlike
the Audio Studio's `tools.speech_batch_export`, found during this feature's
research to bypass the registry). A `radio_player` status-bar cell
(auto-surfaces on first play) and a system-tray right-click section
(Play/Pause, Stop, Mute, Favorite Stations, Now Playing) both drive the same
controller. Three in-app QUILL-key chords (`Ctrl+Shift+Grave, N/0/9` for
play-pause/stop/mute) cover the explicit "hotkeys from the editor" ask —
scoped to app-focused, matching every QUILL-key chord except the one
existing OS-level `RegisterHotKey` precedent (sticky notes), which stays a
narrow, Windows-only exception.

**Persistence.** `core/radio/favorites.py` — atomic JSON via
`core.storage.write_json_atomic`, the standard settings-surface pattern (no
SQLite, unlike both FastPlay and ACB Link). Each favorite carries an unused
`folder` field, present only so the podcasts feature (§5.84g) could grow real
folders out of the same on-disk shape — it ended up with its own dedicated
`PodcastFolder` model instead, since a show belongs to exactly one folder
while a radio favorite's `folder` is a looser, unenforced tag.

**Recording and scheduled recording (`quill/core/radio/recording.py`,
`recording_schedule.py`).** `RadioRecorder` launches ffmpeg via
`subprocess.Popen` (not `stability.safe_subprocess.run_subprocess_safely`,
which blocks until the process exits — a live stream recording needs a
controllable start/stop instead) and stops it by writing the `q` keypress
ffmpeg's own stdin-driven quit handler reads, the same graceful stop a
person pressing "q" in a terminal gets, so the output file's container
closes properly rather than a hard kill truncating it. `RecordingSettings`
(format, bitrate, destination, filename pattern, and a `max_duration_minutes`
safety cap applied via ffmpeg's own `-t` flag, so a forgotten recording
cannot grow unbounded even if `stop()` is never called) is a global,
persisted default. Alongside the re-encoding formats (mp3/ogg/flac/wav)
the format list offers **Raw stream — exactly as sent, no re-encoding
(lossless)** (`format="copy"`, a community request): `build_record_command`
stream-copies the server's audio packets with `-c:a copy` — no decode, no
re-encode — so the saved file is bit-for-bit the original broadcast, the
most faithful capture possible for a listener who wants to do their own
lossless editing/conversion. Because nothing is decoded, a bitrate and any
Sound Enhancements filter graph are meaningless and are dropped in this mode.
The output container matches the stream's own codec: `RadioRecorder.start`
runs a bounded `ffprobe` (`build_probe_codec_command`/`parse_probe_codec`,
`_PROBE_TIMEOUT_SECONDS`) once to read the first audio stream's codec and
picks its natural extension (`raw_capture_extension`: mp3→`.mp3`, aac→`.aac`,
vorbis→`.ogg`, opus→`.opus`, flac→`.flac`, …), falling back to Matroska audio
(`.mka`) for any unrecognized codec — a universal container that stream-copies
anything losslessly. The probed extension is resolved once and reused across
auto-reconnect continuation files (stored in `_active_params`) so a resumed
recording never re-probes or switches container; a missing/failed `ffprobe`
degrades to `.mka` rather than blocking the recording. `RecordingScheduler` is an in-process polling thread
(`_POLL_SECONDS = 20`) — deliberately not an OS-level scheduled task; "while
QUILL is running" is the explicit, simpler scope requested. Schedule entries
support `once`/`daily`/`weekly` recurrence, each carrying its own `ZoneInfo`
time zone (record an Eastern show at its Eastern time from any coast;
daylight saving handled automatically). Recording reuses the existing,
already-optional `ffmpeg` component (`quill.core.speech.ffmpeg`) rather than
introducing a second ffmpeg dependency path, and the Media submenu's
Record Now/Schedule Recording/Recording Settings items are hidden outright
(not merely disabled) when `ffmpeg_available()` is false — closing a
gap from the original Phase 1 ship where recording did not yet exist to gate.

**Recording reliability — resume across restart, the scheduler window
model, and pipeline hardening (R1-R4, 2026-07-17).** A reported round of
bugs around the Recordings list, the scheduler, and reconnects was closed
in four phases (audit + decisions in `x.md` Part 2; all lands in `quill/`,
none vendored into QUILL-AS):

- *R1 — display and dialog.* `RecordingsManagerDialog` refresh is now an
  in-place diff keyed by full path (no `DeleteAllItems`; a no-op when the
  snapshot is unchanged; selection/focus/scroll preserved), so a screen
  reader is no longer yanked to the top mid-read. The active recording is
  counted from `RadioRecorder.is_recording` + `current_destination`
  regardless of folder (a recording writing to a temp dir is no longer
  invisible; `recordings_index.py`), a firing schedule is no longer
  double-counted, completed `once` entries drop out of the scheduled count,
  the active row shows a live elapsed time, scheduled entries show their
  zone-labeled times, and the tray tooltip carries "(recording)".
- *R2 — scheduler reliability.* `recording_schedule.py` was rewritten onto
  a next-due-timestamp window model: an entry is due from `start` through
  `start + duration` (`is_due`), so a late arrival starts with the remaining
  minutes (`remaining_minutes`) and launch-time catch-up is free
  (`missed_occurrences` filters out windows still open at `now`, so catch-up
  is not double-announced). `last_fired` is stamped by entry id only on a
  successful start (`_fire`); a failure retries on the next poll within the
  window; `once` entries auto-disable after firing; a same-minute conflict
  (two schedules due while the recorder is busy) defers the second via
  `on_busy` instead of burning it. The scheduler's `self.entries` is an
  `RLock` shared with the UI thread and `_run` is wrapped in a catch-log-
  continue so the thread can never die silently. Missed-recording reporting
  and `last_seen` stamping moved into the shared `RadioMixin`
  (`_report_missed_recordings`, `_stamp_radio_last_seen`) so embedded QUILL
  gets the same behavior as standalone Quill Radio.
- *R3 — resume across restart (new feature).* The new wx-free
  `quill/core/radio/recording_resume.py` defines `ActiveRecordingMarker`
  (station, url, temp/output path, started_at, scheduled_end, duration,
  entry id), with strict-discard `from_dict` (a corrupt marker yields
  `None`, never a bogus resume), `load/save/clear_marker`,
  `remaining_minutes(marker, now)` floored at 0, `within_resume_grace`
  (`DEFAULT_RESUME_GRACE_MINUTES = 10`), and `reconcile_temp_strays` (moves
  recording-extension files from `temp_dir` to `dest_root` when their mtime
  is older than `_STILL_WRITING_SECS = 30`; leaves a file still being written
  untouched; ignores non-recording files; no-op when no temp dir or temp ==
  dest). `RadioHistory` gained `recording_resume_choice` (`ask`|`always`|
  `never`, default `ask`; bad value degrades to `ask`). The `RadioMixin`
  persists the marker from the recorder's live state on start
  (`_persist_radio_recording_marker`, via `_apply_radio_recording_changed`)
  and clears it on a clean stop — a crash leaves it for next launch. At
  startup `_reconcile_and_offer_radio_resume` (a `wx.CallAfter`) reconciles
  temp strays, then per `recording_resume_choice` asks/always/never offers
  to resume for the remaining minutes via the new
  `quill/ui/radio/resume_recording_dialog.py` (Resume = affirmative/Enter,
  Skip = Escape, "Don't ask me again" checkbox; `None` when dismissed is
  treated as skip and the marker is left to age out past grace). A periodic
  `_radio_last_seen_timer` (60 s) keeps the missed-recording window accurate
  across a crash. The dialog goes through the shared `_show_modal_dialog` /
  `apply_modal_ids` contract and is registered in the dialog inventory.
- *R4 — pipeline hardening.* (1) Absolute end-time across reconnects:
  `RadioRecorder` stores `_scheduled_end = started + duration` on a fresh
  start, and `_maybe_reconnect` records only the remaining minutes
  (`ceil((end - now)/60)`, floored at 1; gives up when `<= 0`), never a fresh
  full duration. (2) `uniquify()` (in `recording_commands.py`) replaces the
  unconditional `-y` overwrite (appends `" (2)".." (999)"` before the
  extension; returns the path unchanged if it does not exist) and
  continuation parts keep the original start timestamp in their
  `{date}`/`{time}` tokens (grouped by name, `" (part N)"` appended) instead
  of rebuilding from `now()`. (3) Fatal vs transient: `_drain_stderr`
  captures a `_stderr_tail` (`deque(maxlen=32)`); `_FATAL_STDERR_RE` (no
  space left / disk full / enospc / read-only / HTTP 4xx / 403 / 404 / 410 /
  451) classifies a drop as fatal, and `_monitor` then skips
  `_maybe_reconnect` — a stream the server took down is gone; reconnecting
  only wastes the budget and spams continuation files. A 5xx / network
  timeout / bare EOF stays transient and is retried. (4) Host-tied child +
  off-thread stop: `_assign_kill_on_close_job` puts ffmpeg in a Windows job
  object with `JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE` (ctypes against
  `kernel32`, best-effort — `None` off-Windows or on any failure, degrading
  to the pre-job behavior), so a crashed/killed QUILL closes the handle and
  the OS kills the child instead of stranding a bare ffmpeg in the temp dir.
  `stop()` sends `q` synchronously (a pipe write) and spawns a daemon
  `_await_stop` thread for the wait/terminate fallback (`_STOP_GRACE_SECONDS`
  then `terminate()`), so the UI/close path never blocks. `_monitor` closes
  the job handle after `process.wait()` returns (child already dead) so a
  long session leaks no handles.

**The mpv playback engine (`quill/ui/radio/mpv_radio_engine.py` +
`player_controller.py`, #1076).** Radio has two backends.
`MpvRadioEngine` — a radio-specific, live-stream-aware libmpv engine — is
preferred whenever libmpv is present (`RadioHistory.playback_engine` =
"auto", the same philosophy as the podcast/Audio Studio `create_engine`);
`WxMediaEngine` (wx.media/WMP) remains the zero-dependency fallback and the
"Windows Media (classic)" escape hatch in Preferences. The shared
`MpvAudioEngine` could not be reused: its poll gates "loaded" on a positive
`duration`, which a live stream never reports. The radio engine's readiness
state machine is a pure, unit-tested function (`next_poll_action`): loaded =
`core-idle` goes false (audio actually being output); error = a return to
`idle-active` before ready (bounded by mpv's own `network-timeout`);
finished = `eof-reached`/idle after playing — a live stream's "ended" is a
disconnect. The mpv engine is what delivers, in one stroke: **output-device
routing** (`audio-device`; enumerated via `audio-device-list` read as JSON
through a short-lived handle, pseudo-entries filtered; the Preferences
"Radio output device" dropdown keeps an unplugged saved device rather than
silently resetting it; `RadioHistory.output_device`); **live DVR** — a
seekable 50 MiB demuxer cache (~45 min at 128 kbps) makes pausing live
radio and Rewind/Forward 30 Seconds/Back to Live real commands
(`radio.rewind`/`radio.forward`/`radio.jump_to_live`, with a spoken
"N behind live" phrase); **Volume Boost** (`radio.volume_boost`,
`volume-max=150` — up to 50% past unity for quiet streams; the 0-100 user
scale is untouched, the boost is applied on the way to the engine, and the
wx engine clamps at 100 so it is safe everywhere); **wider station support**
— effectively every stream format in real-world use now plays: MP3, AAC
and HE-AAC (AAC+), Ogg Vorbis, Opus, FLAC streams, and HLS (m3u8) — WMP
cannot decode Ogg Vorbis, Opus, or HLS at all — and either direction
gets one silent **cross-engine rescue** per play attempt (a stream the
current engine cannot open is retried once on the other before an error is
declared); **engine-native track titles** (mpv `media-title` as the
What's-Playing fallback when the out-of-band ICY tap gets nothing — some
hosts reject it, HLS has no ICY); and **buffering announcements**
(`paused-for-cache` polled once per stall — "Buffering..." instead of dead
air). libmpv is the existing pinned assets-v1 component (§ Audio Studio);
Quill Radio's installer bundles it under `tools\mpv` exactly as ffmpeg under
`tools\ffmpeg`, GPL texts and source-offer note alongside.

**Sound Enhancements (`quill/core/audio_enhance.py`, shared with Podcasts
§5.84g).** A three-band equalizer (Bass/Mid/Treble sliders, -12 to +12 dB
each, `EQ_BAND_MIN_DB`/`MAX_DB`, freely adjustable — the named presets,
Flat/Bass Boost/Voice Clarity/Podcast plus the 1.1.0 additions Small
Speakers and Late Night, survive only as a "Quick preset" shortcut that
sets all three sliders at once), a compressor, and the 1.1.0
**listener-level sound options**: **mono downmix** (`pan=mono`, both
channels blended equally — an accessibility option for single-sided hearing
or a single earbud, where hard-panned stereo content simply disappears) and
**night mode** (`dynaudnorm`, real-time loudness normalization that lifts
quiet program material — the complement to the compressor's "tame the loud
parts"). Deliberately global rather than per-station: they describe the
listener's ears and situation, not a station
(`RadioHistory.mono_enabled`/`night_mode_enabled`). One filter graph
(`build_filter_graph`, order deliberate: mono first, EQ, compressor, night
mode last) drives all three delivery paths so every option behaves
identically everywhere: the loopback-only ffmpeg relay on the wx engine;
**natively via mpv's `af`** on the mpv engine — no relay, no second ffmpeg
process, and a settings change is heard live with no reconnect at all
(`set_filter_graph`); and recordings, via
`RecordingSettings.apply_sound_enhancements` threading the same graph into
`build_record_command`. Off by default; the engine loads the station's own
URL directly until the user opts in. The EQ + compressor remain
**remembered per favorite station**
(`core/radio/favorites.py::FavoriteStation.has_sound_enhancement_override`,
a whole-record override mirroring Podcasts' own per-show override below):
opening Sound Enhancements while a favorite plays edits that station's own
settings; `RadioPlayerController` resolves which applies via an injected
`resolve_enhancement` callback at the top of every `play_station`, rather
than threading the choice through each of the 11+ places a station can
start playing. (The earlier "not a new audio backend" note about BASS
stands — the second backend chosen, libmpv, was already a first-class
optional component of the product, adds no licensing exposure, and touches
nothing but radio playback: earcons and every other product sound stay on
winsound and the system default device.)

**Non-goals reversed 2026-07-17 — TuneIn and iHeart are now in scope.** The
original non-goal left TuneIn and iHeartRadio out for lack of public API terms
QUILL could safely depend on. That was reversed with explicit approval on
2026-07-17: both are now supported through their own no-auth, open endpoints —
TuneIn via RadioTime's OPML API (`opml.radiotime.com` search/browse/`Tune.ashx`
resolve; `partnerId=RadioTime` is the web player's own public string) in
`quill/core/radio/tunein.py`, and iHeart via its public XML sitemap
(`iheart.com/sitemap.xml` → livestations sub-sitemap; per-station stream URLs
extracted lazily from the page the sitemap points to) in
`quill/core/radio/iheart.py`. Both return only what the user searched for or
what a page already advertises — the same shape as the Triton provisioning
resolver QUILL already ships — and neither scrapes a competitor's data files
(per the no-competitor-data stance). Each funnels through one reviewed egress
site, HTTPS-only over a verified TLS context, and is refused in Safe Mode.

**Non-goals (deliberate).** YouTube audio (any form) —
`requirements.txt` already excludes `yt-dlp`/`youtube-transcript-api` to keep
the installed surface small, and this feature does not reopen that call. A
full DSP effects rack in FastPlay's sense — reverb, tempo/pitch/rate,
spatial audio, center-channel/vocal cancellation — remains out of scope
(Sound Enhancements, above, is a small, purpose-built EQ preset and
compressor, not a general effects rack). A full embedded interactive browser for the website link finder —
QUILL has no general-purpose accessible WebView for arbitrary-site
navigation, and `core/browser_reader.py` already shows a house preference for
the user's real browser over an embedded one on accessibility-sensitive
tasks; a static fetch-and-parse covers the real case (station pages list
literal stream links).

**Planned next, not yet built.** Recording and scheduled recording, above,
close out the two biggest items, but not everything: a read-only ACB Media
events/meetings calendar view (a new, not-yet-verified egress site against
`link.acb.org`), a live-refresh fetcher for the currently
static/hand-maintained ACB Media station list, and optional OS-level
global hotkeys remain — see `docs/planning/roadmap.md` §1.7. (The mpv
backend for live streams and ICY "now playing" metadata, once listed here,
both shipped — see the mpv playback engine above and What's Playing.)

**Value.** A genuine, on-mission "why QUILL and not a dedicated player"
answer for a screen-reader-first audience: the ACB Media category exists
nowhere else this convenient, and podcasts (§5.84g) chain a downloaded
episode directly into the Listening Companion (§5.84b) for transcribe-and-
summarize, which no standalone radio/podcast app offers.

---

### 5.84g Podcasts (Phase 1-2, shipped)

**Goal.** Subscribe to, organize, download, and play podcasts inside QUILL,
sharing Internet Radio's (§5.84f) proven "one player that outlives any
dialog" architecture rather than inventing a second one. Covers Phase 1 of
the original 5-phase plan (discovery, subscriptions,
nested folders, OPML, two-control downloads, retention, playback with
per-show speed and resume position) plus chapters, sorting, and rich
context menus pulled forward from Phase 3. Transcript UI, the Inbox, the
Play Queue, and local (imported-file) podcasts remain later phases in that
same document.

**Data model (`quill/core/podcasts/models.py`).** `PodcastShow` (one per
subscription, or one `is_local` show for a later phase) owns a flat list of
`PodcastEpisode` and an optional `PodcastSettings` override; `PodcastFolder`
is a plain adjacency-list node (`parent_folder_id`), letting a show nest
arbitrarily deep. `PodcastEpisode` carries `chapters_url`/`transcript_url`/
`transcript_type` today as forward schema the feed reader already populates,
even though Phase 1 has no UI that reads them yet — landing the on-disk
shape now means the later chapters/transcript phase needs no migration.
`position_ms` is the resume-position field the plan's sync design (§5.84f's
persistence note) already anticipated.

**Discovery and subscription.** `core/podcasts/itunes_search.py` queries
Apple's free, keyless iTunes Search API — the same starting point FastPlay
uses — for `search_podcasts()`. `core/podcasts/feed_reader.py` is a
deliberate two-step design: QUILL fetches feed bytes itself
(`_fetch_feed_bytes`, the one reviewed egress site, HTTPS-only, optional
HTTP Basic auth for private feeds sent preemptively), then hands those bytes
to `feedparser` for parsing only — never letting `feedparser`'s own fetch
path make the network call, which would move it outside QUILL's audited
egress surface. Podcasting 2.0's `<podcast:chapters>`/`<podcast:transcript>`
tags aren't reliably exposed by `feedparser` across versions, so those two
are extracted with a tolerant regex pass scoped per-`<item>` fragment as a
fallback that doesn't depend on guessing `feedparser`'s internal key
mapping. `core/podcasts/subscriptions.py`'s `PodcastLibrary` is the one
atomic-JSON store (shows, folders, global settings); `merge_episodes()`
refreshes a known episode's feed-supplied metadata but never drops one just
because a refreshed feed no longer lists it, and never resets its local
state (played, position, downloaded file, mode override) — an old episode
scrolling off a feed's live listing must not erase what you already did
with it.

**OPML (`core/podcasts/opml.py`).** Export walks the folder tree into nested
`<outline>` elements (local shows excluded — they have no feed URL to
export); import reconstructs that same tree from the nesting and reuses
`PodcastLibrary.add_show`'s existing duplicate-feed-URL detection, so
re-importing a list you already have adds nothing twice. Untrusted OPML is
parsed through `quill.core.safe_xml` (entity-expansion attacks disabled),
never the bare stdlib parser; exporting uses plain `ElementTree`
construction, which is not a parsing-of-untrusted-input operation.

**Downloads (`core/podcasts/download_queue.py`).** One dedicated worker
thread per process (not the shared `QuillTaskManager` pool), so a backlog of
podcast downloads never competes with AI calls or transcription for a pool
slot. Two independent pause controls, matching the plan's explicit
requirement that this not be one setting wearing two hats:
`pause_all`/`resume_all` stop the worker from *starting* new transfers,
letting anything mid-transfer finish; `pause_item`/`resume_item` halt one
specific transfer immediately via a per-item `threading.Event`, checked
between each bounded chunk read so pause takes effect within a chunk, not
only between whole-file attempts. Resuming reads the partial file's size and
sends an HTTP `Range` request, falling back to a clean restart when the
server doesn't honor it. `core/podcasts/retention.py` applies
`keep_last_n` pruning after every completed download and
`delete_after_play` after every finished episode — pure functions, testable
without a real download or a real file.

**Playback (`quill/ui/podcasts/player_controller.py`).** One
`PodcastPlayerController`, owned by `MainFrame` for the process's lifetime —
the exact same shape as `RadioPlayerController` (§5.84f), including the
"every dialog drives the shared controller, none of them own it" rule that
makes closing the Podcasts dialog never stop playback, and makes starting a
new episode always replace whatever was playing rather than layering two
streams. Unlike Radio, podcast episodes are bounded files (even mid-stream,
the enclosure reports a real `Content-Length`), so this uses Audio Studio's
normal `create_engine()` (mpv-preferred, `WxMediaEngine` fallback) rather
than being restricted to Radio's wx.media-only backend. Per-show playback
speed (`PodcastSettings.speed`, 0.75x-2.0x in the UI) is applied via
`set_rate()` once the engine reports loaded, not before — some backends
only accept a rate change after a file is open. Finishing an episode marks
it played and applies `delete_after_play` before the state resets.

**Surfaces.** `Tools > Media > Podcasts...` (Podcast Manager: folder tree +
episode list, Add Podcast/New Folder/Import/Export OPML, Download/Pause
Download/Remove Download, Unsubscribe) registers eight commands in
`CommandRegistry` (`feature_id="core.podcasts"`), command-palette visible.
Rich context menus close the plan's explicit "even playback and pause, etc."
requirement: the episode list's menu covers Play/Pause, Stop, Download,
Pause/Resume Download, Remove Downloaded Copy, Mark as Played/Unplayed, and
Copy Episode Link; the folder tree's menu covers Refresh Feed, Pause/Resume
Downloads for This Podcast (keeps the show and its episodes in the library
while stopping new fetches — the plan's "mark a podcast to not download but
keep in the library" ask), Unsubscribe, and New Folder. A `podcast_player`
status-bar cell (auto-surfaces on first play, same pattern as Radio's cell)
and a system-tray section (Play/Pause, Stop, Pause/Resume All Downloads)
both drive the shared controller. Two QUILL-key chords
(`Ctrl+Shift+Grave, 8/7` for play-pause/stop) sit adjacent to, not
overlapping, Radio's `N/0/9`.

**Chapters (`core/podcasts/chapters.py`).** Fetches and parses the
Podcasting 2.0 JSON chapters format the feed's `<podcast:chapters>` tag
points at, the same fetch-then-parse split `feed_reader.py` uses (one
reviewed egress site, pure parsing). `chapter_at_position()`/
`next_chapter()`/`previous_chapter()` are pure functions over a sorted
chapter list, driving both the Chapters dialog's jump action and the
global `podcasts.next_chapter`/`podcasts.previous_chapter` commands.
Chapters for the currently-playing episode are fetched once per episode
change (tracked by a `(show_id, episode_guid)` key, not re-fetched on every
play/pause toggle) via a background `_task_manager.submit()` call, never
blocking playback.

**Sorting and unheard counts (`core/podcasts/sorting.py`).** Pure
`sort_episodes()`/`sort_shows()` functions — six episode sort modes
(newest/oldest/title/duration-longest/duration-shortest/unplayed-first) and
three show sort modes (title/most-unheard-first/recently-updated-first),
each with a sensible fallback for an unrecognized mode rather than raising.
Publish dates are parsed via `email.utils.parsedate_to_datetime` (the
typical RSS `pubDate` format), falling back to the oldest possible sort
position for an unparseable or missing date rather than erroring. Unheard
counts are computed recursively per folder (a folder's count includes every
subfolder's shows) and per show, rendered as `"{name} (N unheard)"` in the
tree only when non-zero.

**Show notes (`core/podcasts/show_notes.py`).** `html_to_plain_text()`
converts an episode's HTML description to plain text with real paragraph
line breaks (block-level tag ends become newlines) so a screen reader's
line-by-line navigation moves by line, not by wrapping a single giant line
word by word — the specific, named failure mode this was built to avoid.
Links become `text (url)` rather than being silently dropped.
`strip_html_images()` removes every `<img>` tag before any HTML is handed
to the "rich" `wx.html.HtmlWindow` view: an HTML renderer that itself
fetches `<img src="...">` would be a silent, unreviewed network egress site
invisible to a static audit of QUILL's own `urlopen` call sites, so images
are removed rather than rendered. **Send Show Notes to Editor** reuses the
existing `_power_tools_open_text_in_new_buffer()` new-document path (the
same one AI transcribe/translate use).

**Global settings and delete-on-remove (`PodcastSettings.
delete_files_on_remove`).** A new `"ask"`/`"always"`/`"never"` field,
consulted in the Unsubscribe flow via `effective_settings()` (so a show's
own override wins over the library global): `"ask"` prompts a second
confirmation naming the downloaded-episode count only when there are any to
delete; `"always"`/`"never"` act without asking. `PodcastLibrary.settings`
(playback mode, retention, speed, download root) existed in the data model
since Phase 1 but had no UI until this pass's Podcast Settings dialog.

**Non-goals (deliberate).** Video podcasts, in any form — audio only,
matching every other QUILL playback surface; this was an explicit,
repeated constraint during planning, not an oversight. TuneIn/iHeartRadio
apply to Radio, not here; podcast feeds are an open standard (RSS/Atom),
so there is no equivalent commercial-API question for this feature.

**Planned next (Phase 3+), not yet built.** Transcript viewing/export/
QUILL-transcription (the feed already parses the URL; §5.84b's
transcription engines are the intended target), a separate Inbox view with
its own folder tree, a cross-show reorderable Play Queue, local
(imported-file) podcasts and watched folders, virtual views
(Favorites/New Episodes/Continue Listening), and rich filtering (including
Search Everywhere) — all shipped; see the Phase 4 block below for the full
plan.

**Value.** Closes the other half of the "why QUILL and not a dedicated
player" answer §5.84f opened: a downloaded episode chains directly into the
Listening Companion (§5.84b) for transcribe-and-summarize, something no
standalone podcast app offers, and the same QUILL Sync story that already
carries settings between machines now carries listening position too.

#### Phase 4 (shipped): views, Inbox, queue, transcripts, notes, local, sync

Everything the original phased plan deferred, now shipped. Every core is
wx-free and unit-tested; the manager UI additions live in
``quill/ui/podcasts/manager_phase4.py`` (a mixin, per the manager's CQ-1
decomposition note) and ``play_queue_dialog.py``; standalone QUILL Cast
(§5.89e) inherits all of it and adds matching menu items.

- **Pinned virtual views (P4-1).** Favorites / New Episodes / Continue
  Listening / Inbox sit above the folder tree with live counts
  (``virtual_views.py``; Favorites via ``PodcastShow.is_favorite``, toggled
  from the show context menu). Cross-show rows always carry the show name.
- **The Inbox (P4-2, ``inbox.py``).** An episode-level curation layer:
  ``route_to_inbox`` shows surface unplayed episodes in the Inbox regardless
  of library folder; a second, independent nested folder tree
  (``PodcastLibrary.inbox_folders``) files episodes
  (``inbox_assignments``); the first manual filing per show is remembered
  (``inbox_default_folder_id``, announced) with Forget to revert. Folder
  deletion only promotes contents; Inbox actions never delete an episode;
  the whole layer is excluded from OPML both directions.
- **Play Queue (P4-3, ``queue.py`` + ``PlayQueueDialog``).** Cross-show
  ordered queue persisted on the library; Play Next / Add to Queue on any
  episode; auto-advance on natural finish via ``pop_next_playable`` (stale
  slots self-heal); reordering is nudge (Move Up/Down) plus mark-and-move
  (Move Marked Above/Below) -- the Interactive Rebase pattern.
- **Search Everywhere + filters (P4-4, ``filtering.py``).** One query over
  shows, episodes, episode notes, and cached transcripts (never a network
  fetch), grouped by type with jump-to-result; episode-state and show
  filters narrow the manager live.
- **Transcripts (P4-5, ``transcripts.py``).** Feed-provided Podcasting 2.0
  transcripts (VTT/SRT/JSON parsed to plain text) save to a file or open in
  the editor; fetched transcripts cache locally (searchable, instant
  reopen).
- **Episode notes (P4-6, ``episode_notes.py``).** Timestamped notes on the
  playing episode; the notes dialog jumps playback to a note's moment.
- **Local podcasts + watched folders (P4-7, ``local_import.py``).** Audio
  files become an ``is_local`` show (one episode per file); stored under
  ``~/.quill-local/podcasts`` -- outside the syncable data directory *by
  construction*, per the sync-safety requirement. A per-show
  ``watched_folder`` turns dropped files into episodes on scan. Never
  exported to OPML.
- **ACB Media directory (P4-8, ``acb_media_podcasts.py``).** One idempotent
  command subscribes the live ACB directory into its own folder, every
  arrival stream-only (``import_opml``'s ``stream_only``/``into_folder``).
- **Always Sync (P4-9).** ``always_sync_full_catalog`` (per-show
  overridable): refresh backfills the catalog and queues downloads for
  download-mode shows; the settings checkbox nudges retention to keep-all
  (announced) since backfill fights keep-last-N.
- **Download processing + volume boost (P4-10, ``audio_processing.py``).**
  Optional auto-trim-silence and loudness-normalization on each finished
  download (the audiobook builder's ffmpeg passes, off-thread);
  ``set_volume_boost`` (0.5x-3.0x clamp) scales live gain only --
  ``volume_percent`` stays unboosted so the Sleep Timer's restore is honest.
- **Position checkpoints (P4-11).** ``on_position_checkpoint`` fires with
  the outgoing episode's position at pause/stop/switch/shutdown and the
  mixin persists it -- the write half of resume, which previously only read.
- **Status page rows (P4-12, ``status_report.py``).** Podcast library
  summary rows and download-task rows (with started/finished timestamps)
  for the Help Status page.

#### Phase 5 (shipped): Sound Enhancements + Smart Speed

Shares Radio's ``core/audio_enhance.py`` (§5.84f) rather than duplicating
it, with the one real wrinkle Radio doesn't have: episodes support seeking
and a duration/scrub bar, which a live one-way ffmpeg relay has neither of
natively. Full parity was built, not a degraded no-seek mode.

- **Three-band EQ + compressor.** Same as Radio (§5.84f): Bass/Mid/Treble
  sliders plus a compressor, applied live via the shared relay. Off by
  default; a "Quick preset" shortcut still sets all three sliders at once
  from the four original named presets.
- **Smart Speed (podcasts only).** A ``silenceremove`` filter trims silence
  anywhere in the audio (not just leading/trailing), for the gaps between
  sentences a spoken-word episode is full of -- reversible and live, not the
  one-time, permanent leading/trailing trim ``audio_processing.py`` (P4-10)
  already does to a saved download. Not exposed for Radio: a live stream has
  no fixed content to trim ahead of time, and "silence" in music is often
  intentional.
- **Seek while enhanced (``player_controller.py``).** There is no way to
  seek within an already-running relay, so scrubbing restarts it with an
  ffmpeg ``-ss`` offset -- an async reload, not the engine's normal instant
  seek. ``_pending_play_after_load`` carries play/pause intent through that
  reload so scrubbing or toggling enhancement mid-episode never forces a
  paused episode to resume.
- **Duration (``probe_source_duration_ms``).** The relay's own MP3 output
  never declares a length for the engine to compute a scrub bar from, so
  duration comes from an independent ``ffprobe`` call instead.

#### Phase 6 (shipped): Download All Episodes / Remove All Episodes

Two new show-level context-menu actions, implemented once in
``quill/ui/podcasts/show_actions.py`` and called from both surfaces that act
on a subscribed show (the Podcast Manager dialog and QUILL Cast's own
library tree) rather than duplicating the logic a third time.

- **Download All Episodes.** Queues every not-yet-downloaded,
  not-already-queued episode of a show -- purely additive, no confirmation,
  matching the existing single-episode Download action's own behavior.
- **Remove All Episodes.** A two-step confirm mirroring Unsubscribe's shape:
  confirm the removal, then -- only if any episode has a downloaded file --
  a follow-up asking whether to also delete those files. The show stays
  subscribed (unlike Unsubscribe); a future feed refresh can repopulate its
  episode list from the feed itself. Cancels any in-flight/queued download
  for a removed episode first, so nothing is left running against a guid
  about to disappear.

#### Phase 7 (shipped): Inbox grouping + per-podcast sort for every cross-show view

The Inbox (and every other cross-show virtual view -- New Episodes,
Continue Listening, Favorites) previously rendered ``(show, episode)``
pairs in raw feed-fetch order, with the Podcast Manager's existing "Sort
episodes" control silently doing nothing outside a single show's own
episode list. Root-caused from a direct user question about whether Inbox
episodes were grouped by show or interleaved, and whether that order could
be controlled; the first shipped design (a single "Group by Show" checkbox)
was corrected mid-review into the fuller shape below once it became clear
"folder" meant a real tree, and "resettable per podcast" meant a genuine
per-show override, not a global-only toggle.

- **``PodcastSettings.episode_list_view_mode``** (global only -- a single
  show has no "grouped vs flat" shape of its own): ``"flat"`` (one stream
  sorted by the library's global sort mode across every show), ``"grouped"``
  (the pre-existing look -- pairs grouped contiguously by show, shows
  ordered by title), or ``"folders"`` (the same per-show grouping, presented
  as real expandable tree nodes instead of a flat list). Default
  ``"grouped"`` matches the pre-existing de-facto order.
- **``PodcastSettings.episode_sort_mode``**, per-show overridable the same
  way ``speed`` already was. **``core/podcasts/sorting.py::sort_pairs``**
  (pure, unit-tested): in ``"flat"`` mode every pair sorts by the one global
  mode (per-show overrides don't apply -- there's no single well-defined
  order once different shows compare by different keys); in
  ``"grouped"``/``"folders"`` mode each show's own group sorts by *that
  show's* effective mode, so one podcast can read oldest-first while
  another reads newest-first.
- **``PodcastLibrary.apply_show_override``**, the one correct way to write
  any per-show settings override: clones the currently effective settings
  (the show's own override if it has one, else the global default) via
  ``dataclasses.replace``, so setting one field never resets sibling
  overrides to class defaults. Also fixed ``_on_speed_choice``, which
  predates this and hand-cloned only 5 of the (now) 14 ``PodcastSettings``
  fields -- setting a show's playback speed silently wiped any other
  override that show already had.
- **UI (``manager_dialog.py``, ``manager_phase4.py``).** A "View cross-show
  lists as" combo box (Flat list / Grouped in list / Folders per podcast)
  and a context-aware "Sort episodes" control: it reads and writes the
  selected podcast's own override when a single show (or its Folders tree
  node) is selected, or the shared global default otherwise.
  ``_add_virtual_view_show_children`` builds the Folders mode's per-podcast
  tree nodes fresh on every ``refresh_tree()`` -- auto-generated, never
  persisted, distinct from the existing manual freeform Inbox folder tree.

#### Phase 8 (shipped): per-podcast Sound Enhancements, Skip Forward/Back, auto-skip intro/outro

A competitive pass against Downcast/Overcast/Pocket Casts/Castro surfaced two
gaps: Sound Enhancements (Phase 5, above) was global-only, and there was no
skip-by-N-seconds command at all (only absolute chapter-boundary seeks).

- **Per-podcast Sound Enhancements.** ``PodcastSettings`` gained
  ``eq_bass_db``/``eq_mid_db``/``eq_treble_db``/``compressor_enabled``/
  ``smart_speed_enabled``, per-show overridable via ``apply_show_override``
  exactly like ``episode_sort_mode`` (Phase 7). Opening Sound Enhancements
  while an episode is playing edits that show's own override; with nothing
  playing, it edits the shared default. Every ``play_episode`` call site (6,
  across the Manager, the Play Queue, Recently Played, and both standalone
  apps) resolves ``effective_settings(show)`` and passes the result through
  new optional ``bass_db``/``mid_db``/``treble_db``/``compressor_enabled``/
  ``smart_speed_enabled`` kwargs.
- **Skip Forward / Skip Back.** ``PodcastSettings.skip_forward_seconds``/
  ``skip_back_seconds`` (global default + per-show override, 30/15 by
  default) back two new commands (``podcasts.skip_forward``/``skip_back``,
  Episode-menu items, default chords) that jump the player controller's
  position by that many seconds, clamped to ``[0, length_ms]``.
- **Auto-skip intro/outro** (``auto_skip_intro_seconds``/
  ``auto_skip_outro_seconds``, per-show only -- a global "skip N seconds of
  every podcast" default isn't a thing anyone wants). Intro-skip applies
  once, only on a fresh start (``resume_ms <= 0``) -- a checkpointed
  position is never jumped past. Outro-skip is a new 1-second
  ``PodcastPlayerController`` position poll that ends the episode early
  through the exact same ``_on_finished`` path a natural end uses, so
  auto-advance and delete-after-play still fire.
- **New context-aware Skip Settings... dialog** (``skip_settings_dialog.py``)
  mirrors Sound Enhancements exactly: edits the currently-loaded show's
  override, or the shared default with the intro/outro fields hidden
  entirely when nothing is loaded (they have no meaningful global value).
- Also fixed a real bug found while touching ``PodcastSettingsDialog``:
  ``_on_save`` built a fresh ``PodcastSettings(...)`` that silently reset 7
  unedited fields (view mode, sort mode, EQ, smart speed) to class defaults
  on every save. Now ``dataclasses.replace(self._settings, **edits)``, the
  same pattern ``apply_show_override`` already uses.

#### Phase 9 (shipped): saved Playlists -- Smart (rule-based) and manual

The other half of the same competitive pass: no way to save a curated or
rule-based cross-show episode list, only the four fixed pinned views and the
transient Play Queue -- a real gap against Pocket Casts' Smart Playlists/
Filters and curated Playlists.

- **``Playlist``/``PlaylistRules``** (``models.py``, mirrors ``QueueItem``'s
  own data-class-in-``models.py``/operations-in-a-sibling-module split).
  ``kind="smart"`` resolves live against ``rules`` every time it's opened
  (which shows -- empty means every show, episode status, published-within-
  days, min/max duration, sort mode, reusing ``sorting.py``'s own sort-key
  builder so results order exactly like every other episode list in the
  app); ``kind="manual"`` is a named, ordered, persistent list of specific
  episode references (``QueueItem``s) -- the saved counterpart to the
  transient Play Queue, self-healing against a since-unsubscribed show or
  vanished episode the same way the Play Queue already does.
  ``core/podcasts/playlists.py::resolve_playlist`` is pure and fully unit
  tested.
- **``PodcastLibrary.playlists``** + find/add/remove/rename CRUD, persisted
  the same hand-rolled-dict way ``queue``/``inbox_folders`` already are.
- **Tree integration** (``manager_phase4.py``) mirrors the existing
  pinned-views/Inbox-folder pattern exactly: a "Playlists" node (context
  menu: New Smart Playlist.../New Playlist...), one child per saved
  playlist showing its live-resolved count, Edit Rules.../Rename/Delete on
  each, F2 rename support, and the episode list fills via
  ``resolve_playlist`` the same way a virtual view fills via
  ``virtual_view_pairs``.
- **New ``playlist_rules_dialog.py``** (the Smart Playlist rule editor) uses
  individual ``wx.CheckBox`` controls in a ``wx.ScrolledWindow`` for the show
  picker, not ``wx.CheckListBox`` -- caught by the banned-patterns gate
  (A11Y-SR-1: screen readers do not announce ``CheckListBox`` item checked
  state as it's navigated, only the label text).
- Episode context menu gained "Add to Playlist..." (a native
  ``wx.SingleChoiceDialog`` among existing manual playlists, or create one
  inline).

---

### 5.84h Shared media Sleep Timer, and start-at-Windows-login

**Goal.** A sleep timer that covers both Internet Radio (§5.84f) and
Podcasts (§5.84g) from one place, since duplicating it per-feature would
mean two timers, two dialogs, and no guarantee they agree on what "active"
means; and a way to launch QUILL automatically at login, requested
alongside the media work though unrelated to it in scope.

**Sleep timer (`quill/ui/media_sleep_timer.py`).** `SleepTimerController`
is owned by `MainFrame`, not either media mixin, and takes `get_radio_
controller`/`get_podcast_controller` callables rather than direct
references, so it works whether one, both, or neither feature is enabled.
A single `wx.Timer` ticks every second; over the final `_FADE_WINDOW_
SECONDS` (20) of the countdown, every controller currently in a
`PLAYING`/`PAUSED` state has its volume faded linearly toward zero
(captured once at fade-start per controller, so a mid-fade cancel restores
the pre-fade level exactly, not whatever the fade had reached). At zero,
every active controller is stopped, then every faded controller's volume is
restored — stopping first, then restoring, so the fade-out is never briefly
audible again between "stopped" and "volume restored." Radio and Podcasts
are independent players (nothing stops one when the other starts), so both
are faded/stopped if both happen to be active at once. `PodcastPlayerController`
gained a `volume_percent` property/tracked field for this — Phase 1 shipped
with a `set_volume()` method but no readable state, since nothing needed to
read it back before the sleep timer did.

**Start at Windows login (`quill/platform/windows/startup.py`).**
`set_launch_at_startup()`/`is_launch_at_startup_enabled()` read/write a
per-user `HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Run`
value — the same no-elevation, easily-reversible mechanism most everyday
Windows apps use, not an installer or Task Scheduler change. A new
`Settings.launch_at_windows_startup` field, rendered automatically by the
generic Preferences dialog from its `SettingSpec` entry (placed immediately
after `tray_enabled`'s), is applied in `_settings_dialog_apply_refresh()` —
the same shared hook every Settings-apply path (OK, Apply, Reset, Import)
already funnels through. Checking it also forces `tray_enabled` on: a QUILL
that launches silently at login with no tray icon would leave no visible
way back into a hidden window, so the two settings are kept consistent
rather than left to conflict. A no-op, never-raising module on non-Windows
platforms (`winreg` import guarded, mirroring `shell_integration.py`'s
existing pattern).

---

### 5.84z Signed offline unlock codes (Help > Redeem Unlock Code...)

**Goal.** Enable a locked feature (`FeatureDefinition.locked_off`) for a
specific user — early testers, partners, staged rollouts — without a build,
a server, or an account. A code is a signed capability, not a serial number.

**Model (`quill/core/unlock_codes.py`, wx-free).** A code is
`QUILL-<base32(payload || Ed25519 signature)>` where the payload is
`feature_id|expiry` (expiry optional, ISO date). Verification uses a bundled
Ed25519 public key (PyNaCl, the optional `[signing]` extra) entirely
offline; `quill/tools/mint_unlock_code.py` mints codes with the private key,
which never ships. Redeemed codes persist in an atomic JSON store
(`UnlockCodeStore`), and `unlocked_feature_ids()` re-verifies every stored
code on each read — a tampered or expired stored code silently stops
unlocking, it is never trusted from disk.

**Feature-gate integration.** `FeatureManager.unlocked_feature_ids` is
populated from the store at load and refreshed after a successful
redemption; `state_for` treats an unlocked id as ON where `locked_off`
would otherwise force OFF. This is the single sanctioned path past a lock.

**UI.** **Help > Redeem Unlock Code...** (`help.redeem_unlock_code`, also in
the command palette) opens a one-field dialog; the result announcement names
the unlocked feature (from `FEATURE_DEFINITIONS`) or speaks the specific
rejection reason. Absent PyNaCl, redemption reports the missing extra rather
than failing silently.

### 5.84z2 Sticky Notes Browser and user-definable global hotkeys

**Goal.** Two connected capture-and-recall features: find any sticky note in
seconds from anywhere in Windows, and let users put their own keys on the
handful of commands that are genuinely safe to trigger without QUILL having
focus.

**Sticky Notes Browser (`quill/ui/sticky_notes_browser.py`).** A modal
finder: search field (live substring filter over title + body,
case-insensitive, newest first — `filter_notes` is pure and unit-tested),
Down moves from search into the results list, Tab reaches a read-only
multi-line preview, Edit/Enter/double-click opens the existing
`StickyNoteEditorDialog` for the selected note, Escape closes. Every control
is named via `dialog_contract.set_accessible_name`. Command id
`notes.sticky_browser` (Tools menu + palette + global-hotkey allowlist).

**Global hotkeys (`quill/ui/main_frame_hotkeys.py`).** Generalizes the
original single hardcoded sticky-note `RegisterHotKey` into a
user-configurable table with one hard rule: **only
`GLOBAL_HOTKEY_SAFE_COMMANDS` can ever register**, whatever
`Settings.global_hotkeys` contains — the allowlist is the enforcement
boundary, not the settings file, and a meta-test pins the list's shape
(media transport / notes / the Mastodon *compose* dialog only; nothing
document-editing or destructive). Requirements:

- Dispatch goes through `CommandRegistry.run`, so feature gating and the
  remote kill switch govern global presses exactly as they do menus and the
  palette.
- Commands flagged needs-window restore the frame from the tray before
  running; transport commands act in place. Every outcome routes through
  the announcement engine, so a press from another app is always spoken.
- The manager (`quill/ui/global_hotkeys_dialog.py`): per-command Assign
  (captures the next combination; must include Ctrl or Alt so a bare key is
  never swallowed system-wide), Clear, cross-command steal on reassign;
  nothing applies until Save. `RegisterHotKey` refusal (another app owns
  the key) is reported naming the failed binding, which stays inactive.
- `Settings.global_hotkeys: dict[str, str]` persists command_id → binding
  with defensive load; the legacy `tools.sticky_note_capture` keymap
  binding keeps registering unless overridden by the table.
- Windows-only (`RegisterHotKey`); macOS states the limitation once via the
  status bar, and every allowlisted command remains reachable in-app.

**Show/Hide to the tray — a family-wide global hotkey, one unique chord per
app.** A new allowlisted command `view.toggle_window_to_tray`
(`toggle_window_to_tray` on `GlobalHotkeysMixin`) hides QUILL to the tray when
it is showing and restores+focuses it when hidden, reusing the existing
`send_to_tray` / `_restore_from_tray` paths. It is a **window-visibility**
command — not document-editing, not destructive — so the allowlist meta-test
was widened to admit exactly this one new prefix, keeping the boundary explicit.
Because the command toggles both directions itself, it is registered *not*
needs-window (the dispatcher must not pre-restore before it runs). Requirements:

- A unique default per app so the family never collides: QUILL
  **Ctrl+Alt+Shift+Q**, Quill Radio **Ctrl+Alt+Shift+R**, Quill Weather
  **Ctrl+Alt+Shift+W**. In QUILL the default is supplied by
  `_global_hotkey_bindings` when the settings table has no entry, so it works
  out of the box yet remains an ordinary, rebindable/clearable row in the
  manager.
- The standalone apps (`AppShellFrame`) gain `_register_tray_hotkey(chord)` and
  `toggle_window_to_tray`, reusing the same `RegisterHotKey` + `EVT_HOTKEY`
  pattern already proven by `_register_media_keys` (hardware media keys), with
  the hotkey released on teardown alongside the media keys. Hiding uses
  `frame.Hide()` (the tray icon keeps the app reachable); the toggle speaks
  "hidden to the tray" / "shown".
- The chord→(flags, virtual-key) parser is the new wx-free, unit-tested
  `quill/ui/tray_hotkey.py` (`parse_hotkey(wx, chord)`), shared by QUILL and
  both standalone apps so the parse is identical everywhere.
- Best-effort and non-fatal: a chord another program already owns simply is not
  grabbed (registration fails quietly), never blocking startup or shutdown.

### 5.85 Portable API key store

By default QUILL stores AI provider keys in the Windows Credential Manager, which ties them to the current Windows user account. Portable mode offers an alternative: a DPAPI-encrypted file (`keys.enc`) in the QUILL data directory, activated by the presence of a `data/` folder next to `quill.exe` in the portable bundle.

**Motivation.** Some users run QUILL from a self-contained folder on a network share or external drive. They want all QUILL data — settings, data files, and keys — to live in one directory without requiring Credential Manager access on each machine. A DPAPI-encrypted file achieves this: everything stays in the folder, and the file is protected by the Windows user-account key.

**Access priority chain (highest wins):**

1. Environment variable (`QUILL_OPENROUTER_KEY`, `QUILL_OPENAI_KEY`, `QUILL_OLLAMA_KEY`, `QUILL_ASSISTANT_KEY`) — for CI pipelines and developer overrides.
2. Portable file store (`keys.enc`) — used automatically when the running install is recognised as portable (a verified bundle anchor with `quill.exe` + `data/`).
3. Windows Credential Manager — default for standard installations.

**Activation.** Portable mode is a property of the bundle, not of the running environment. The portable build ships `quill.exe` at the bundle root and an empty `data/` folder next to it; that folder is the deliberate filesystem opt-in. No environment variable to set. If you want to convert an installed build into a portable one, copy the install folder to a USB drive and create an empty `data/` folder at its root; QUILL will switch to portable mode automatically. The previous `QUILL_PORTABLE=1` activation mechanism is no longer required and is ignored — detection is filesystem-driven. The `keys.enc` file is created automatically in `app_data_dir()` on first key save.

**Security properties.** The file is encrypted with Windows DPAPI using a QUILL-specific entropy token. It is decryptable only on the same Windows machine by the same user account that encrypted it. Moving `keys.enc` to a different machine or a different Windows account will fail to decrypt; the user must re-enter their keys.

**Implementation map.**

| File | Role |
| --- | --- |
| `quill/platform/windows/credential_store.py` | Unified load/save/delete with env-var, portable file, and Credential Manager backends |
| `quill/platform/windows/dpapi.py` | DPAPI `protect_secret`/`unprotect_secret` (existing) |
| `quill/ui/ai_chat_dialog.py` | `_load_api_key`/`_save_api_key` updated to use credential_store |
| `quill/core/assistant_ai.py` | `_load/save/delete_api_key_from_credential_manager` updated to use credential_store |

---

### 5.86 Configurable data location (#615)

Where QUILL stores its data directory (`app_data_dir()` — settings, recovery, undo history, logs, and everything else under it) is a user choice, not a hardcoded path, satisfying the "Portable mode clarity" goal in §5.

**Storage modes.** `quill/core/storage_mode.py` persists one of three modes to `storage-mode.json`:

1. `appdata` (default) — `%APPDATA%\Quill`.
2. `portable` — `<app root>/data`, only available when the running install is verified portable.
3. `custom` — any user-chosen folder, stored alongside the mode as a `path` field.

**Portable detection without reopening L-9.** A prior security fix (commit `a4fec36`) gated `QUILL_PORTABLE_ROOT` behind `_DEV_BUILD` because trusting an attacker-controlled environment variable's *value* could redirect a user's data directory. That fix stands: this feature never trusts an env var's value directly, in any build. `storage_mode._resolve_app_root()` derives a candidate anchor from `QUILL_APP_ROOT` or by walking up from `sys.executable`, then only treats it as a real portable install when `quill.exe` and a sibling `data/` folder both exist at that anchor — filesystem evidence, not the env var's say-so. `run-quill.cmd` is accepted as back-compat evidence so a beta-1 portable bundle without a `data/` folder keeps working. `tests/unit/core/test_storage_mode.py::test_arbitrary_quill_app_root_alone_does_not_redirect_data` is a regression test mirroring the original L-9 threat model, and `test_quill_exe_alone_without_data_folder_is_not_portable` and `test_data_folder_alone_without_quill_exe_is_not_portable` lock in the new evidence rule.

**Where it's surfaced.**
- The first-run Setup Wizard's new Data Location page (`quill/ui/setup_wizard_pages.py::_DataLocationPage`) offers AppData, Portable (when available), or a custom folder via `wx.DirDialog`. On Finish this writes `storage-mode.json` directly — there is nothing to migrate yet on a fresh install.
- **Preferences → General** has the same three-way choice (`quill/ui/main_frame.py::_build_data_location_block`), for changing the location on an existing install.

**Restart-deferred migration.** A live move is unsafe: `CopyTray` caches its data directory at construction, `Settings` is loaded once at startup, and Windows has no atomic directory-move primitive that's safe against transient file locks. `quill/core/data_location.py` instead:
1. `request_data_location_change(mode, custom_path=None)` validates the target and writes a `pending-data-location.json` marker into the *current* data directory. Nothing moves yet; the current install keeps working normally until restart.
2. `apply_pending_data_location_migration()` runs first in `quill/__main__.py::main()`, before `ensure_app_directories()`. If a marker is present, it moves the old directory's contents to the new location (per-entry, via `core.storage.retry_on_transient_lock` for Windows' transient `EACCES`/`EAGAIN`/`EBUSY` locks), writes the new `storage-mode.json` at the destination, and leaves a one-time migration notice. On failure, the old location is left untouched and the notice explains what went wrong — data is never silently lost.
3. Preferences shows a "Restart Now" / "Later" prompt (`MainFrame._confirm_restart_for_data_location`) immediately after a change is requested, since the move only takes effect on the next launch.

**Implementation map.**

| File | Role |
| --- | --- |
| `quill/core/storage_mode.py` | Mode persistence; trusted-anchor + filesystem-evidence portable detection |
| `quill/core/data_location.py` | Pending-migration marker, restart-deferred move, migration notice |
| `quill/core/paths.py` | `app_data_dir()` resolves `appdata`/`portable`/`custom` via `storage_mode` |
| `quill/core/storage.py` | `retry_on_transient_lock` (shared by atomic JSON writes and directory moves) |
| `quill/ui/setup_wizard_pages.py` | `_DataLocationPage` (first-run choice) |
| `quill/ui/main_frame.py` | Preferences control, restart prompt, relaunch |

---

### 5.87 Timer Events

**Design goals.** Let a Quillin perform periodic, low-frequency background work — refreshing a status cell, polling a watched resource, housekeeping — without polling on the UI thread or observing keystrokes. A Quillin declares a `schedule` contribution: one or more named timers, each with an `interval_seconds` and a handler.

**Interval constraints.** `interval_seconds` is bounded to 60–86400 (one minute to one day). The lower bound keeps timers from becoming a high-frequency surface that could degrade screen-reader predictability or burn CPU; the upper bound keeps the value meaningful (anything longer is better modelled as a lifecycle event).

**Threading model.** Each tick runs its handler in a daemon thread via the out-of-process `ExtensionHost`, so a slow or faulty handler can never block the editor. The timer itself is a `wx.Timer` owned by the host frame; timers start when the Quillin loads, stop on disable/remove/reload, and never run in Safe Mode.

**Error handling.** A handler that raises is caught in the worker thread; the error is marshalled back to the UI thread and shown in the status bar. A timer error never crashes the editor and never stops the timer — the next tick still fires.

### 5.88 File-Type Contributions

**Design goals.** Let a Quillin react to opening a document of a declared file type — announce a braille page count for `.brf`, report CSV headers for `.csv`, timestamp a `.log` — without subscribing to every `document.opened` event and filtering by hand.

**Extension matching.** A `file_types` entry lists lowercase, dot-prefixed extensions (`.csv`, `.brf`). On open, the host looks up the document's suffix (lower-cased) in a per-extension index built at load time and fires every registered handler for that suffix. Because the handler runs real out-of-process code, `file_types` reuses the `document.events` capability and requires a `main` module.

**Dispatch model.** File-type handlers fire immediately after the general `document.opened` event, on a background thread, with a context of `{file_path, extension, filename}`. Dispatch is non-blocking; multiple Quillins may register for the same extension and all fire.

### 5.89 Snippet Gallery

**Design goals.** Give Quillins a way to ship a library of named, parameterized templates that users can browse and insert, without binding each to a command or hotkey. Gallery snippets run no code — pure text expansion — so they need no capability and no `main` module.

**Picker UX.** **Insert → Snippet Gallery...** opens a list of every gallery snippet from every enabled Quillin, grouped by Quillin, with a read-only preview of the selected snippet's body. Insert expands the snippet at the cursor (replacing any selection); Cancel closes the dialog.

**Parameter prompting.** A snippet body may contain `{param_name}` placeholders. Each declared param has a `name` (matching a placeholder), a `label`, and an optional `default`. On insert, QUILL prompts for each param in turn through the shared single-line prompt; cancelling any prompt cancels the whole insertion (nothing is inserted).

**Accessibility requirements.** The gallery is a hardened `wx.Dialog` routed through `_show_modal_dialog`/`apply_modal_ids` for the keyboard contract. The snippet list, preview field, and buttons all carry accessible names; selecting a snippet announces its name and source Quillin; Insert is the default button and Escape cancels. Param prompts are individually labelled and cancellable.

---

### 5.89a Classic-editor power features — Repeat, Restore Deleted Text, Describe Character

**Motivation.** Three keyboard-first conveniences from the lineage of the WordPerfect Editor that have no prior equivalent in QUILL. Each targets the same audience as the rest of the power-tool suite: writers who work entirely from the keyboard with a screen reader, and who value precise, repeatable, inspectable editing. All three ship **unbound** (no default shortcut), registered through the standard command registry so they appear in the Command Palette and Keymap Editor and recirculate into their conventional menus.

#### Repeat Next Command (`edit.repeat_command`, Edit menu)

A numeric repeat prefix for *any* command. The user invokes Repeat Next Command, enters a count in a native, focus-managed prompt, and the very next command dispatched through the command registry runs that many times — move down twenty lines, delete ten words, insert forty dashes, or replay a recorded macro N times — in one gesture.

- **Mechanism.** The count lives on `CommandRegistry` (wx-free): `arm_repeat(count)` clamps the value to `[1, MAX_REPEAT]` (`MAX_REPEAT = 1000`, so a typo can never spin the editor unbounded). `run(command_id)` consumes the pending count at the top of dispatch, resets it to 1, and loops the handler that many times; the run listener fires once per iteration so macro recording captures each step faithfully. The count persists only until the next eligible `run` — it does not leak across a session.
- **Self-protection.** The arming command registers itself as non-repeatable (`register_non_repeatable`), so re-arming while a count is pending never multiplies the prompt.
- **Scope.** Repeats commands dispatched through the registry (the keyboard path screen-reader users rely on). Re-entrant handlers that themselves call `run` see a cleared count and are not double-counted.

#### Restore Deleted Text (`edit.restore_deletion`, Edit menu)

A small kill-ring distinct from both Undo and the Copy Tray. QUILL's structured delete commands (`delete_to_line_start`/`_end`, `delete_to_document_start`/`_end`, `delete_paragraph`) record the removed span into a deletion ring; Restore Deleted Text presents the recent deletions in an accessible list and re-inserts the chosen one at the cursor.

- **Why it is distinct.** Undo reverts the last edit *in place*; the Copy Tray captures *copies*. The deletion ring captures *deletions* and lets the writer place recovered text *anywhere* — the modern form of the WordPerfect Editor "Cancel" buffer.
- **Mechanism.** `quill/core/deletion_ring.py` holds `DeletionRing` (newest-first, capped at three, collapses consecutive identical deletions) and `removed_span(before, after)`, which recovers the contiguous removed run by stripping the common prefix and suffix. `_apply_line_operation` records `removed_span` after every structured delete. The UI presents a `wx.SingleChoiceDialog` of speakable previews (`"Most recent (12 characters): ..."`); a single entry inserts immediately.
- **Read-only and bounds.** Honours the read-only guard; an empty ring announces "No deleted text to restore".

#### Describe Character at Cursor (`power.describe_character`, Tools → Advanced)

The screen-reader descendant of "Reveal Codes". An accessible dialog — rendered in the same read-only `ContextHelpDialog` the F1 help uses, so a screen reader reads the whole description in one pass — names the exact character under the caret.

- **What it reports.** Glyph (or a speakable stand-in for non-printing characters), Unicode name, code point in hexadecimal and decimal, general category in plain language, and a note for invisibles that bite writers: no-break space, narrow no-break space, zero-width space/joiner/non-joiner, BOM, smart quotes, en/em dash, soft hyphen, tab, and line endings. Non-ASCII characters are flagged.
- **Mechanism.** `quill/core/char_describe.py` exposes `describe_character(text, position) -> CharacterDescription` (a `summary` for the status line and a `detail` block for the dialog). Positions at or past end of text report "End of document" rather than raising. The special-character map is keyed by code point (built via `chr`) so invisibles are unambiguous in source.

**Implementation map.** `quill/core/commands.py` (`arm_repeat`, `pending_repeat`, `register_non_repeatable`, repeat loop in `run`), `quill/core/deletion_ring.py`, `quill/core/char_describe.py`, `quill/ui/main_frame_power_tools.py` (`repeat_command`, `restore_deletion`, `describe_character`, `_deletion_preview`), `quill/ui/main_frame.py` (`_deletion_ring` init, non-repeatable registration, `removed_span` capture in `_apply_line_operation`), `quill/ui/main_frame_power_tools_menu.py` (manifest entries), `quill/core/feature_command_map.py`, `quill/core/help/topics.json`. Tests: `tests/unit/core/test_command_repeat.py`, `test_deletion_ring.py`, `test_char_describe.py`.

---

### 5.89b Reveal Codes (WordPerfect-style synchronized code inspector)

QUILL keeps formatting codes hidden so the editing buffer stays clean plain text (see the rich-text hidden-codes model). **Reveal Codes** is the on-demand companion: a second, synchronized view that makes every hidden formatting code and structural/invisible character explicit, navigable, and individually announced — the beloved WordPerfect feature, rebuilt screen-reader-first. The full design rationale is preserved in this PRD (this section is canonical; the former `docs/planning/reveal-codes-design.md` was retired into it on shipment).

**Activation and layout.** `view.reveal_codes_toggle` (**Alt+F3**, the WordPerfect chord; also **View → Reveal Codes**, a checkable item) shows/hides a pane docked **below the editor, above the status bar**. Hidden by default and zero-cost while hidden (the token stream is not built). The visible/view/verbosity state persists in settings.

**The F6 region cycle.** The pane is a first-class focus region. When shown it joins QUILL's existing rotation, so **F6** moves **Editor → Reveal Codes → Status Bar** (with Document Tabs / Preview when present) and **Shift+F6** cycles back — no new keybinding (`_current_focus_region_labels` / `_detect_active_region` / `_focus_region` in `main_frame.py` gained one entry each). `edit.find_all_matches` moved off Alt+F3 to `Ctrl+Shift+F3` to free the chord.

**Synchronized carets — movement-agnostic.** Both views share one logical position via the markup↔visible offset map. Moving in the pane drives the editor caret to the matching markup offset; moving the editor caret re-places the pane caret on the matching cell/token. The editor→pane direction is a throttled idle tick (off the typing hot path) keyed on the editor's caret **offset**, so it follows *any* movement type equally — arrow, Ctrl+arrow word jump, Home/End, Page Up/Down, mouse click, or a programmatic jump from Find/Go To — not just arrow keys. The editor buffer is the markup, so the markup offset is the editor caret space directly.

**The token model (`quill/core/reveal_codes.py`, wx-free).** `build_code_stream(markup) -> list[CodeToken]` linearizes the document, built on `rtf_model.analyze_markdown` (per-character offset map + formatting) and `char_describe` (invisibles). Each `CodeToken` records `kind` (TEXT / FORMAT_ON / FORMAT_OFF / BLOCK / STRUCTURE / INVISIBLE), a display `label` and `spoken` phrase, both `markup_*` and `visible_*` offset ranges, an optional `pair_index` linking an ON code to its matching OFF, and `attrs`. Inline formatting (bold/italic/underline/strike/super/subscript/font/size/color/highlight/link) becomes paired ON/OFF codes; paragraph attributes (heading, bullet, named style, alignment, spacing, indent) become BLOCK codes at the line head; paragraph breaks become `[¶ Hard Return]`; tabs and notable invisibles (no-break/zero-width spaces, smart quotes, dashes) become their own tokens; everything else groups into TEXT runs. `token_at_markup_offset`, `pair_distance`, and `describe_token` support sync, pairing, and verbosity-aware announcements.

**Presentations and verbosity.** `reveal_codes_view` selects **Flowed** (a read-only `wx.TextCtrl` rendering codes inline within the text, `[Bold On]Hello[Bold Off]` — now the interactive surface **and the default**) or **Structured** (a read-only `wx.ListBox`, one labelled/announced item per token — a discrete scanning alternative). `reveal_codes_verbosity` (quiet / balanced / detailed) gates how much each move announces. In-pane commands work in both views: `reveal.next_code` / `reveal.previous_code` (scan code-to-code) and `reveal.go_to_pair` (ON↔OFF).

**Navigation model (`quill/core/reveal_nav.py`, wx-free).** The token stream is deliberately coarse (a whole run is one TEXT token) — the right grain for a *list*, the wrong grain for a *caret*. `build_flow_view(tokens) -> FlowView` flattens it into **navigation cells**: one cell per visible character, and one **atomic** cell per code. Each cell records its `markup_offset` (editor caret space), `visible_offset`, `flow_start`/`flow_end` (offset into the flowed string, kept in lockstep with the rendered text so the visible caret always lands correctly), and a logical `line`. The caret is a single integer index into the cells. Pure movers — `move_char` (Left/Right: one character in text, one whole code atomically), `move_word` (Ctrl+Left/Right, codes are hard stops), `move_line` (Up/Down by logical line, column-preserving), `line_home`/`line_end`, `cell_for_markup_offset` (editor→pane sync), `cell_at_flow_offset` (mouse) — clamp and never raise, so the pane binds them straight to keys. `announce_cell` / `word_at` / `announce_line` produce the spoken phrase for each move (a character, a word, or the whole line read like the editor reads a line move).

**Single-speaker announcements.** In Flowed mode the pane's key handler consumes the navigation key (it does **not** call `event.Skip()`), so the screen reader has no keystroke to pair with the programmatic caret move and stays silent — the pane is the sole voice via `host._announce`, speaking a *bare* phrase with no "Reveal Codes:" prefix (the region name is spoken once on focus entry). This is the fix for two long-standing symptoms: (1) "Reveal Codes" was repeated on every arrow press, and (2) JAWS and NVDA announced the same move differently — both were the result of two channels (the SR narrating the control **and** QUILL's Prism/pyttsx3 status speech) firing on one move and the two readers arbitrating the overlap differently. Structured mode likewise mirrors its rich phrase to the status bar *silently* (`_set_status_quiet`), leaving the SR's own item read as the single channel.

**F2 region editing.** Pressing **F2** on a content token (TEXT / STRUCTURE / INVISIBLE) that sits inside a formatting pair enters an in-place edit restricted to that region. `enclosing_region(tokens, token_index)` finds the **innermost** enclosing `FORMAT_ON`/`FORMAT_OFF` pair and returns the span of the whole inner region (first content token after the ON to last content token before the OFF); `region_source(markup, region)` yields the current buffer text and `splice_region(markup, region, new_text)` writes the edit back as a literal `markup[start:end] = new_text`. The flowed control becomes editable and shows just the region's source; **Enter** commits (splice into the editor buffer, caret placed after the edit, rebuild), **Escape** cancels. Because the span is the whole region, a run carrying a `[Tab]` or a nested code edits as one unit — nested codes appear as their markup and are spliced straight back, losslessly.

**Accessibility.** Character/word/line navigation that mirrors the editor (Flowed) makes the pane feel like a place you edit, not a list you inspect; codes are still conveyed by bracketed text + label and named as atomic units ("bold on"), never colour alone; entering the pane announces the region once and never chatters beyond the chosen verbosity; the single-speaker rule guarantees JAWS and NVDA behave identically. Structured remains a discrete, individually-named list for scanning, and SAPI/braille users get the literal bracketed codes in Flowed mode.

**Scope note.** Read-only navigation, interrogation, movement-agnostic bidirectional sync, and **in-place editing of a formatting-bounded region (F2)** ship now. Region editing is a literal buffer splice over the region's markup span, so it is safe against the zero-width code boundaries `analyze_markdown` exposes. The remaining editing gaps are the defined next step: *deleting* a code to strip its effect, and *inserting/replacing* a code, both of which need the formatting markers' exact character spans (which `analyze_markdown` abstracts away) and so ride on the marker-span work rather than the zero-width boundaries.

**Implementation map.** `quill/core/reveal_codes.py` (token model), `quill/core/reveal_nav.py` (caret/navigation-cell model + region-edit helpers, wx-free), `quill/ui/reveal_codes_pane.py` (the pane: flowed interactive navigation, single-speaker announcements, F2 editing, sync controller), `quill/ui/main_frame_reveal_codes.py` (`RevealCodesMixin`: toggle, idle sync, in-pane command delegates), `quill/ui/main_frame.py` (pane creation in the layout; region-cycle entries; command registration), `quill/ui/main_frame_menu.py` (View item + EVT_MENU) / `main_frame_menu_bindings.py` (EVT_IDLE binding), `quill/core/settings.py` (`reveal_codes_visible` / `reveal_codes_view` default **flowed** / `reveal_codes_verbosity`), `quill/core/keymap.py` + `keymap_packs.py` (Alt+F3, friendly title). Tests: `tests/unit/core/test_reveal_codes.py`, `tests/unit/core/test_reveal_nav.py`, `tests/unit/ui/test_reveal_codes_pane.py`.

---

### 5.89c Story Studio — manuscript and long-form organization

**Goal.** Give a screen-reader user a first-class way to organize a book-length project — manuscript, characters, places, plot threads, research, and brainstorming — without a visual corkboard, while keeping every word in plain, portable text. Optional and additive; inert until opened.

**Model (`quill/core/story`, wx-free, strict-typed).** A *project* is a folder of plain-text files plus an advisory `project.quillstory.json` sidecar recording a title, the ordered manuscript spine (relative POSIX paths), and non-manuscript *elements* (`character`, `location`, `plot`, `research`, `brainstorm`). Loading is corrupt-tolerant in the spirit of the settings-migration delta store (a bad entry is dropped, the rest kept) and the sidecar never duplicates prose: with no sidecar the folder is still a project (its text files become the manuscript spine), so deleting it loses nothing. Persistence uses `write_json_atomic`.

**Binder.** `build_binder(project, read_text)` derives a tree — a Manuscript group whose file nodes carry heading-derived chapter/scene children (nested by level from the files' Markdown ATX headings), then element groups (Characters, Places, Plot threads, Research, Brainstorm). The tree is derived, never stored, so it cannot drift from the prose. File IO is injected as a `read_text` callable, keeping the core pure and unit-tested without a display.

**Front matter and fields.** Each element file may carry an optional leading `---` block of light structured fields, encoded by a small dependency-free codec (`key: value` scalars and `- item` lists; round-trips, preserves field order and unknown keys — deliberately no PyYAML dependency). Per-kind default field sets (`quill/core/story/fields.py`): character → role/goal/motivation/arc; location → significance; plot → status; research → source; plus a universal `tags` list. Empty fields are dropped on save; unknown keys and `type` are preserved.

**Compile.** `compile_manuscript(project, read_text)` concatenates the manuscript spine in order with each file's front matter stripped, producing plain text for the existing export pipeline (`quill/io/export.py`) — no new export engine.

**UI (`quill/ui`).** `Tools → Story Studio...` (command `story.open_studio`, also on the command palette; no default key, assignable in the keymap editor) picks a project folder and opens `StoryStudioDialog`, an accessible `wx.TreeCtrl` binder. Activating a file/heading/element opens it in the editor at the heading offset and closes the binder; activating a group expands/collapses it. **Edit details...** opens `StoryElementFormDialog`, a labelled field-per-row form that writes changes back to the element's front matter. **Compile manuscript...** opens the compiled text as a new untitled document tab for export. Both dialogs route through `_show_modal_dialog`/`apply_modal_ids` and are classified in the dialog inventory.

**Status.** Introduced in the 0.8.1 line. Deferred: richer field types in the details form (choices, dates), saved views and tag filters, and a one-step compile-and-export action.

---

### 5.89d Accessible Vault — linked notes, backlinks, and knowledge navigation

**Goal.** Deliver a linked-notes model — a folder of notes that link to each other, with searchable, bidirectional links — through spoken, keyboard-native surfaces rather than a visual graph. A backlinks *list* read aloud beats a backlinks *picture*. Optional and additive; the editor is unchanged when no vault is open. The Accessible Vault is **feature-complete for 0.9.0**: Phases 0–7 all ship with a wx-free, unit-tested core under `quill/core/vault` and accessible `Tools → Vault` surfaces. The small remaining polish (in-editor `[[`/`#` autocomplete popups, live-preview link/embed resolution, and a Vault Explorer tree) is tracked in [`roadmap.md`](../../planning/roadmap.md) §1.7.

**Model (`quill/core/vault`, wx-free, strict-typed).** A *vault* is a folder of Markdown/plain-text notes plus a `.quill/` cache (regenerable). `scan_vault` parses every note into `NoteInfo` — title (front matter `title`, else H1, else filename), aliases, tags (front-matter `tags:` + inline `#tag`), headings, block ids, and outgoing wikilinks — keeping file-relative offsets so a UI can open at a heading or block. The wikilink codec (`links.py`) parses `[[Note]]`, `[[Note|alias]]`, `[[Note#Heading]]`, `[[Note#^block]]`, and `![[embed]]`, leaving Markdown `[x](y)` and code spans/fences alone. `resolve.py` maps a wikilink to a note + anchor offset, reporting **unresolved** (→ create-on-follow) and **ambiguous** (→ a spoken chooser, never a guess). `index.py` builds forward + reverse adjacency; `backlinks()` quotes each linking line for context, `unlinked_mentions()` finds plain-text name occurrences not yet linked, and `neighborhood()` returns a note's outgoing links (with titles) and backlinks together for "traverse the web by ear." The higher phases add, each wx-free and unit-tested: `search.py` (title-ranked full-text search + a subsequence fuzzy quick switcher), `tags.py` (a nested-tag-aware index — `#area/sub` also answers to `#area` — with counts and `#` suggestions), `render.py` (`[[link]]`→HTML resolution for preview/export, plus `![[embed]]` expansion of a block, heading section, or whole note with cycle detection), `templates.py`/`dailynotes.py` ({{date}}/{{time}}/{{title}}/{{prompt}}/{{cursor}} substitution and daily-note path math), `site_export.py` (a static linked HTML site as `{path: html}`), `sync.py` (commit/pull/push over an injected subprocess runner with conflict detection), `publish.py` (a **gated** single-note publish payload), and `refactor.py` (offset-precise inbound-link edits for a rename). Story Studio (§5.89c) is a curated collection view over this vault and shares the front-matter/heading machinery.

**UI (`Tools → Vault`, all palette-reachable + keymap-assignable with no default keys; dialogs route through `_show_modal_dialog`/`apply_modal_ids` and are classified in the dialog inventory).**

- *Phases 0–2 — links & backlinks.* **Open Vault...** (`vault.open`) indexes a folder and remembers it (`Settings.vault_root`), announcing "Vault X: N notes, M links." **Follow Wikilink** (`vault.follow_link`) opens the note under the caret's `[[link]]` at its heading/block; a missing target offers to create the note, an ambiguous name opens an accessible chooser. **Show Backlinks** (`vault.backlinks`) lists the notes that link here, each read with its linking line (Enter opens the source at the link). **Note Neighborhood** (`vault.neighborhood`) lists outgoing links (→) and backlinks (←) together for traverse-by-ear, and **Unlinked Mentions** (`vault.unlinked_mentions`) lists plain-text occurrences of the note's name not yet linked (Enter opens the source at the mention). **Insert Link to Note...** (`vault.insert_link`) inserts `[[Title]]`. **Rename Note...** (`vault.rename`) renames the current note over `refactor.plan_note_rename` — after a confirm that counts the affected links, it rewrites every inbound `[[link]]`, renames the file, retitles a matching H1, and reopens the note. **Vault Explorer...** (`vault.explorer`) is a keyboard `wx.TreeCtrl` of every note by folder (`explorer.build_note_tree`); **Complete Link or Tag at Cursor** (`vault.complete`) completes an in-progress `[[note`/`#tag` from a spoken filtered list (`autocomplete.py`) — the accessible alternative to a floating popup.
- *Phase 3 — find.* **Go to Note** (`vault.quick_switch`) is a filter-as-you-type switcher (Down moves to the results, Enter opens the top/selected match) and **Search Vault** (`vault.search`) is vault-wide full-text search with Regex / Whole-word toggles, opening a result at its matching line. Both live in `VaultFilterDialog`, which speaks the running count as you type.
- *Phase 4 — tags.* **Show Tags** (`vault.tags`) is the spoken tag pane: filter tags with counts, then list a tag's notes (nesting rolls up).
- *Phase 5 — embeds.* **Speak Embed at Cursor** (`vault.speak_embed`) reads an `![[embed]]` target without changing text; **Resolve Embed Inline** (`vault.resolve_embed`) replaces it with its content as one undoable edit.
- *Phase 6 — notes.* **Insert Template...** (`vault.insert_template`) picks from the vault's `Templates/` folder, speaks each `{{prompt}}`, and lands the caret at `{{cursor}}`; **Open Today's Note** (`vault.today`) and **Previous/Next Daily Note** (`vault.prev_daily`/`vault.next_daily`) create-and-open along the daily pattern.
- *Phase 7 — share.* **Export Vault as Website...** (`vault.export_site`) builds a static, linked HTML site off-thread (links → relative anchors, embeds inlined) using QUILL's own Markdown renderer; **Sync Vault** (`vault.sync`) commits/pulls/pushes over the user's own git remote off-thread (Safe-Mode gated; conflicts listed, never pushed); **Publish Note** (`vault.publish_note`) is registered `feature_id=future.publishing` and stays **hidden** until publishing is unlocked. **Vault Settings...** (`vault.settings`) sets the Templates folder (`Settings.vault_templates_folder`, default `Templates`) and daily-note pattern (`Settings.vault_daily_pattern`, default `Journal/{{date:YYYY-MM-DD}}.md`).

**Preview & freshness.** Previewing a note that lives in the open vault resolves it (`preview.resolve_for_preview`: `[[links]]` as titled inert anchors, `![[embeds]]` inlined) via a defensive passthrough that leaves every other document untouched. Saving an in-vault note re-parses just that note into the cached index (`apply_note_change`), so backlinks, search, tags, and the neighborhood stay fresh without reopening the vault.

**Non-goals.** No visual graph view or canvas (the link *relationships* are delivered as lists and navigation); no *hosted* sync/publish — Sync is the user's own git remote, and Publish is gated off. The Accessible Vault is **complete for 0.9.0** with no open work.

---

### 5.89e Standalone companion apps — Quill Radio and QUILL Cast

**Goal.** Radio and Podcasts are useful without the editor: someone who wants
to listen to internet radio or manage a podcast queue should not have to load
all of QUILL to do it. Quill Radio and QUILL Cast are small standalone
executables — their own window, their own menu bar, their own system tray
icon — that reuse QUILL's feature code *unchanged* rather than forking it.

**Architecture (`quill/ui/app_shell.py` + `quill/apps/`).** The feature
mixins `MainFrame` already uses (`RadioMixin`, `PodcastsMixin`) only ever
touch a small, fixed host protocol on their owner: `self.frame`, `self._wx`,
`self._safe_mode`, `self._task_manager`, `self._announce`,
`self._show_message_box`, `self._set_status`, `self.settings`,
`self.commands`, `self._binding_for`, `self._refresh_statusbar`.
`AppShellFrame` implements exactly that protocol over a plain `wx.Frame`, so
`class RadioAppFrame(AppShellFrame, RadioMixin)` gets the entire feature —
commands, dialogs, favorites, recording, scheduling — with zero changes to
the mixin. Consequences that matter:

- **No fork, ever.** A bug fix or feature added to `quill/core/radio`,
  `quill/core/podcasts`, or the shared dialogs lands in the standalone apps
  automatically — same modules, same imports.
- **One data store.** The apps load the same `core.settings`/`core.keymap`
  and read/write the same favorites, subscription library, and download
  state under `app_data_dir()` — what you subscribe to in QUILL Cast is
  subscribed in QUILL, with no sync layer.
- **Same accessibility contract.** Announcements route through the same
  `AnnouncementEngine`; dialogs keep their existing keyboard/naming
  behavior because they are the same dialog classes.

**Per-app surfaces.**

- **Quill Radio** (`python -m quill.apps.radio`; `run-quill-radio.bat` from
  source). Menu bar: Station (Browse Stations, Add Custom Station, Find
  Streams from a Website, Favorite Stations inline), Playback (disabled
  now-playing status line, Play/Pause, Stop, Mute, Volume Up/Down), Record
  (Record Now/Stop, Schedule Recording, Recording Settings), Help (Open in
  Quill, About). Tray icon: Show/Exit plus the same radio section
  (`_build_radio_tray_menu`) QUILL's own tray shows.
- **QUILL Cast** (`python -m quill.apps.podcasts`; `run-quill-cast.bat`).
  Menu bar: Subscriptions (Open Podcast Manager, Add Podcast, Import/Export
  OPML, Podcast Settings), Episode (now-playing line, Play/Pause, Stop,
  Next/Previous Chapter), Downloads (Pause All / Resume All), Help. Tray
  icon mirrors QUILL's podcast tray section. One behavioral override: "Send
  Show Notes to Editor" copies to the clipboard instead (there is no editor
  buffer standalone), announced as such.

**Open in Quill.** Both apps carry a Help > Open in Quill command that
launches the full editor as a separate process (v1: always a new process; a
focus-existing-instance IPC variant is deliberately deferred — see
`docs/planning/apps.md`).

**Platform notes.** The tray icon follows `MainFrame`'s own rule: on macOS,
`wx.adv.TaskBarIcon` produces a Dock tile rather than a menu-bar extra, so
the apps skip the tray there instead of misrepresenting it. `QUILL_SAFE_MODE`
is honored on launch.

**Installer integration.** The Windows installer creates Start Menu entries
for both companion apps ("Quill Radio", "QUILL Cast") alongside QUILL's own,
launching them via the bundled Python runtime (`-m quill.apps.radio` /
`-m quill.apps.podcasts`), with both launcher variants (bundled runtime and
exe) covered. Desktop icons for the companions are an opt-in installer task
(`companionicons`, unchecked by default) so a default install never adds
desktop clutter unasked. Defined in the `.iss` generator
(`scripts/build_windows_distribution.py`), never the generated script.

**Keyboard-first main panel.** Each app opens on a real, tabbable main
surface — never a bare frame: a live now-playing line, the app's primary
list (favorite stations / subscribed shows) focused on launch with Enter to
act, and its core action buttons, every control named via
`dialog_contract.set_accessible_name`.

**Non-goals (v1).** No single-instance enforcement; no Audio Studio
standalone app yet — the phased plan, including those, lives in
`docs/planning/apps.md`.

---

### 5.90 AI Writing Toolkit: architecture and feature matrix

This section documents the AI writing layer shipped in QUILL 0.6.0, covering provider abstraction, the connection model, per-feature design, and the data-disclosure posture.

#### 5.90.1 Provider abstraction

All AI features route through `quill/core/assistant_ai.py::generate_assistant_response(connection, api_key, prompt, *, max_tokens, timeout_seconds) -> (text | None, error | None)`. This function:

- Accepts an `AssistantConnectionSettings` dataclass (provider, host, model) and a bare API key string.
- Dispatches to the appropriate HTTP client (OpenAI-compatible, Anthropic Messages API, Google Gemini, or Foundation Models on macOS).
- Returns a `(text, None)` tuple on success or `(None, error_string)` on failure.
- Never raises; all exceptions are caught and returned as the error string.
- Is imported at module level (not lazily) in every AI module so that test suites can monkeypatch it.

Supported providers:

| Provider ID | Host type | Auth |
|---|---|---|
| `openai` | OpenAI cloud | API key (Credential Manager) |
| `claude` | Anthropic cloud | API key (Credential Manager) |
| `gemini` | Google cloud | API key (Credential Manager) |
| `openrouter` | OpenRouter cloud | API key (Credential Manager) |
| `ollama` | Local or self-hosted | URL only (no key) |
| `custom` | User-specified endpoint | Optional API key |

#### 5.90.2 Connection settings and AI Hub

Provider, host, and model are stored in `AssistantConnectionSettings` (serialized via `core/storage.py`). The API key is stored separately in the Windows Credential Manager via `platform/windows/credential_manager.py`, keyed per provider.

**AI Hub** (`quill/ui/ai_hub_dialog.py`) is the single entry point for all AI configuration. It is a five-tab `wx.Notebook` dialog:

1. **Provider** — provider choice, API key field, host override, model choice, Test Connection button.
2. **On-Device** — Ollama URL, recommended model list with size and capability notes.
3. **Audio Services** — Deepgram API key (with reveal toggle), max speakers (SpinCtrl, 2–20).
4. **Instructions** — per-task custom system prompt editor. See §5.90.7.
5. **Advanced** — consent summary, settings reset, safe mode documentation.

All writes in `_on_ok()` are atomic: API keys saved via `credential_manager.credential_save`, settings saved via `write_json_atomic`.

#### 5.90.3 Custom instructions

`quill/core/ai/custom_instructions.py` provides a per-task system-prompt layer.

**Data model:**

InstructionSet(task_id, title, default_prompt, user_prompt=““, enabled=True) .active_prompt -> user_prompt if non-empty, else default_prompt .is_customised() -> user_prompt.strip() !=”” and user_prompt != default_prompt .reset_to_default() -> user_prompt = “”

**12 built-in tasks:** `chat`, `spell_check`, `grammar_check`, `rewrite`, `summarize`, `expand`, `toc`, `translate`, `thesaurus`, `document_qa`, `research`, `accessibility_agent`.

**Persistence:** Only user-modified fields (`task_id`, `user_prompt`, `enabled`) are written to `%APPDATA%\Quill\ai_custom_instructions.json`. Built-in defaults always live in code; a QUILL update that improves a default is automatically picked up unless the user has customised that task.

**Application:** `apply_instruction(task_id, base_prompt) -> str` prepends the active system prompt if the task is enabled. It never raises — any failure (missing file, corrupt JSON, unknown task) silently returns `base_prompt` unchanged. This is called at the top of every AI feature's prompt-building path.

#### 5.90.4 AI writing features

| Feature | Shortcut | Module | Dialog |
|---|---|---|---|
| AI Thesaurus | Ctrl+Alt+Shift+H | `core/ai/thesaurus.py` | `ui/ai_thesaurus_dialog.py` |
| AI Spell Check | — | `core/ai/spell_check.py` | `ui/ai_spell_check_dialog.py` |
| AI Grammar Check | — | `core/ai/grammar_check.py` | `ui/ai_grammar_check_dialog.py` |
| Rewrite Selection | — | `core/ai/agent_session.py` | `ui/ai_agent_result_dialog.py` |
| Summarize Selection | — | `core/ai/agent_session.py` | `ui/ai_agent_result_dialog.py` |
| Expand Selection | — | `core/ai/agent_session.py` | `ui/ai_agent_result_dialog.py` |
| Generate TOC | — | `core/ai/agent_session.py` | `ui/ai_agent_result_dialog.py` |
| Document Q&A | — | `core/ai/document_qa.py` | `ui/ai_document_qa_dialog.py` |
| Translate | Ctrl+Shift+T | `core/ai/translation.py` | `ui/ai_translation_dialog.py` |
| Transcribe Audio | — | `core/ai/transcription.py` | `ui/ai_transcribe_dialog.py` |
| Read with AI Voice | — | `core/ai/cloud_tts.py` (dispatch), `core/ai/tts.py` (OpenAI), `core/ai/gemini_tts.py` (Gemini), `core/ai/elevenlabs_tts.py` (ElevenLabs SDK gateway, audio export only — roadmap §4.1), `core/ai/tts_chunk.py` (boundary-safe split) | inline in `main_frame.py` |
| Ask Quill chat | Alt+Q | `core/ai_chat.py` | `ui/ai_chat_dialog.py` |

#### 5.90.5 Agentic task architecture

Four commands (Rewrite, Summarize, Expand, Generate TOC) share a common agent session architecture in `quill/core/ai/agent_session.py`:

- **`AgentPlan`** — profile (from `assistant_agents.py`) + rendered prompt.
- **`AgentContext`** — plan + connection + api_key + `threading.Event` (stop_event) + optional `on_progress` callback.
- **`run_agent(ctx, *, refine=False) -> AgentResult`** — one or two AI calls; step outputs collected into `AgentResult.steps`; optional second refinement pass; refine errors are non-fatal (keeps first draft).
- **`AgentResult`** — `plan_id`, `steps: list[AgentStep]`, `final_output`, `cancelled`, `error`.

All agent runs are launched on daemon threads via `threading.Thread`; UI updates go through `wx.CallAfter`. The stop event is checked between steps and after each AI call.

**Result dialog** (`ui/ai_agent_result_dialog.py`): two-panel layout — step log (ListCtrl, read-only) and final output (TextCtrl, read-only). Buttons: Insert (cursor), Replace (selection), Copy, Re-Run, Close.

#### 5.90.6 AI Thesaurus

`quill/core/ai/thesaurus.py::get_synonyms(word, connection, api_key, context_sentence) -> list[ThesaurusEntry]`:

- Truncates word to 80 chars and context to 400 chars before including in the prompt.
- Calls `apply_instruction("thesaurus", prompt)` then `generate_assistant_response` with `max_tokens=512`, `timeout=30s`.
- Parses the JSON array response via `_parse_response` which strips markdown fences and extracts the first JSON array.
- Returns `list[ThesaurusEntry(synonym, note)]`.

The context sentence is extracted in `main_frame.py::open_ai_thesaurus()` by searching outward from the caret position to the nearest newlines, giving the model enough context to disambiguate polysemous words (e.g. "bank" financial vs. river).

#### 5.90.7 Custom Instructions UI

The Instructions tab in AI Hub presents:

- **Task list** (`wx.ListBox`): shows all 12 tasks; customised tasks show a `*` suffix.
- **Enable checkbox**: per-task toggle; when disabled, `apply_instruction` returns the base prompt unchanged.
- **User prompt editor** (`wx.TextCtrl`, multiline): editable field for the user's override.
- **Default display** (`wx.TextCtrl`, read-only): shows the built-in default for reference.
- **Reset to Default button**: clears `user_prompt`; the `*` marker disappears live.
- **Copy Default to Editor button**: copies the default into the editor as a starting point.

The `*` marker updates live as the user types (via `EVT_TEXT` on the editor). On OK, `save_instructions()` writes only the changed fields.

#### 5.90.8 Data disclosure posture

Every AI feature that transmits data outside the local machine is disclosed in the setup consent screen and in the user guide's AI Privacy Reference table. Summary:

| Data sent | Destination | Feature |
|---|---|---|
| Selected text or document text | Configured AI provider | Spell check, grammar check, rewrite, summarize, expand, TOC, thesaurus, translate, Document Q&A |
| Audio file (up to 25 MB chunks) | Deepgram or OpenAI Whisper | Transcription |
| Selected text or document (TTS, sentence-aware chunks) | OpenAI TTS API, Google Gemini TTS API, or ElevenLabs (SDK gateway, audio export only) per Settings > Read Aloud | Read with AI Voice, Export Document as Audio |
| Document text (up to 80k chars) | Configured AI provider | Document Q&A |
| Nothing (on-device) | Ollama local | All features when Ollama is the configured provider |

Custom instructions, provider settings, and API keys never leave the local machine.

#### 5.90.9 Safety and safe mode

All AI features are gated behind the `future.ai` feature flag. When `QUILL_SAFE_MODE=1` or `--safe-mode` is passed at startup, `generate_assistant_response` returns an error immediately without making any network calls. The Watch Folder `CloudTranscribeAction` also refuses to run in safe mode.

The AI-enabled gating tuple in `main_frame.py` disables every AI menu item when AI is not configured, so no network call can be triggered from the UI in an unconfigured state.

#### 5.90.10 Test coverage

| Module | Test file | Count |
|---|---|---|
| `core/ai/agent_session.py` | `tests/unit/core/ai/test_agent_session.py` | 23 |
| `core/ai/thesaurus.py` | `tests/unit/core/ai/test_ai_thesaurus.py` | 16 |
| `core/ai/custom_instructions.py` | `tests/unit/core/ai/test_custom_instructions.py` | 22 |
| `core/ai/spell_check.py` | `tests/unit/core/ai/test_spell_check.py` | 9 |
| `core/ai/grammar_check.py` | `tests/unit/core/ai/test_grammar_check.py` | 19 |
| `core/ai/translation.py` | `tests/unit/core/ai/test_translation.py` | 18 |
| `core/ai/transcription.py` | `tests/unit/core/ai/test_transcription.py` | 16 |
| `core/ai/document_qa.py` | `tests/unit/core/ai/test_document_qa.py` | 20 |
| `core/ai/tts.py` | `tests/unit/core/ai/test_tts.py` | 18 |

All tests follow the module-level import pattern so `generate_assistant_response` can be monkeypatched in tests without live provider credentials.

#### 5.90.11 Prompt caching

**Goal.** Reduce per-request token cost by sending the stable custom-instruction text as a cacheable system prefix rather than re-sending it inline with every call.

**Design.**

`custom_instructions.split_instruction(task_id, base_prompt) -> (str, str)` is the canonical split point. It returns the active system prompt and the user content as separate strings. Every AI module calls `split_instruction` instead of `apply_instruction` and passes the system_prompt through to `generate_assistant_response`.

`generate_assistant_response` accepts `system_prompt: str = ""` and threads it into `build_chat_body` and `build_chat_headers`. `apply_instruction` is preserved as a legacy convenience wrapper (it calls `split_instruction` internally and joins the parts).

**Provider behaviour.**

| Provider | Caching mechanism | Cost effect |
|---|---|---|
| Anthropic Claude | `cache_control: {"type": "ephemeral"}` block in the `system` array; `anthropic-beta: prompt-caching-2024-07-31` header | ~10% of normal input rate on cache hit; 5-minute TTL |
| OpenAI / OpenRouter | `role=system` message; caching is automatic above 1024 tokens | ~50% of normal input rate on cache hit |
| Gemini | `systemInstruction` field | provider-defined |
| Ollama | `role=system` message in the chat messages array | model-server internal |

**Invariants.**
- When `system_prompt` is empty, the request body is identical to the pre-caching form (no extra fields, no extra headers). No regressions for callers that do not pass a system prompt.
- `apply_instruction` is backward compatible; existing call sites that have not yet migrated continue to work with the combined-string path.
- The Anthropic beta header is only added when the provider is `claude` AND `system_prompt` is non-empty, so the header never appears for other providers.

### 5.91 Startup-speech gating (verbosity shim)

QUILL's `quill.a11y.announce(...)` funnel (§9.5) is the single code path every spoken line passes through. As of 0.7.0, two startup announcements are gated through user-facing settings so the screen reader stays quiet on first run unless the user opts in:

1. The Document Guardian Quillin activation cue (`Document Guardian is now active.` / `is now inactive.`).
2. The screen-reader detection result (`Detected screen reader: <name>. Adaptive hints enabled.`).

#### 5.91.1 Settings and defaults

Two new settings live under the **Accessibility** group:

| Setting | Type | Default | Purpose |
|---|---|---|---|
| `verbosity_speech_enabled` | bool | `True` | Master gate for the spoken output channel. When off, every spoken announcement from built-in startup events and Quillin extensions is suppressed. The status bar still receives the same text. Acts as the shim for the 0.7.1 verbosity rebuild. |
| `announce_screen_reader_detected` | bool | `False` | When on, speaks the `Detected screen reader: <name>. Adaptive hints enabled.` line at startup, but only if `verbosity_speech_enabled` is also on. |

Document Guardian adds its own per-Quillin preference under **Preferences → Document Guardian → Lifecycle Announcements**:

| Setting | Type | Default | Purpose |
|---|---|---|---|
| `enabled_announcements` | bool | `False` | When on, speaks the activation / deactivation cue from `on_enabled` and `on_disabled`. The Quillin always writes its state to the status bar regardless. |

#### 5.91.2 Enforcement layers

Two layers enforce the gates so a regression in either one cannot re-introduce the spoken line:

1. **Per-Quillin check.** The Quillin reads its own setting before calling `api.announce`. `api.get_setting("enabled_announcements", False)` is the per-Quillin value, defaulting to off.
2. **Host dispatcher check.** `quill.core.quillins.host.ApiDispatcher._dispatch` checks `services.is_verbosity_speech_enabled()` before forwarding the `announce` method to `services.announce(...)`. The same gate exists in `quill.plugins.node_quillin_runner._dispatch_action` for the Node.js Quillin runtime. The new `HostServices.is_verbosity_speech_enabled` method is implemented by `_EditorHostServices` (the live-frame adapter) and faked in every test double.

The screen-reader detection result flows through `MainFrame._set_status_quiet` (status bar only) unless both `announce_screen_reader_detected` and `verbosity_speech_enabled` are on, in which case it flows through `MainFrame._set_status` (status bar + spoken). The status bar always receives the text, so sighted and low-vision users get the same information regardless of the speech state.

#### 5.91.3 Why two layers

The per-Quillin check exists because the user's preference for the lifecycle cue is **Quillin-local** — it travels with the extension, not with the global app setting. The host-dispatcher check exists because `verbosity_speech_enabled` is a global master gate that should silence every Quillin announcement, not just one. Together they keep the user in control at both levels.

#### 5.91.4 Verbosity system (shipped)

The full verbosity rebuild (roadmap §1.1; the deferred 2.0 polish backlog is consolidated in roadmap §6) replaces the single `announcement_verbosity` knob with a per-verb, channel-aware, user-customizable announcement system. It has **shipped for 1.0**: the pure-domain core lives in `quill/core/verbosity/` (wx-free, strict-typed, in `mypy` scope) and is live in the app. Beyond the foundation table below, the system now includes the **routing engine** (`engine.py`) reached through the single `VerbosityController.process()` choke-point that `main_frame` routes its announce path through; the **runtime modes** Quiet (`Ctrl+Shift+Q`) and Meeting (`Ctrl+Shift+B`) with status-bar badges, **Quiet Undo** (`Ctrl+Shift+Z`), and the status-query commands **Where am I?**, **What changed?**, and **Speak Status**; **mastery step-down**, **announcement history**, the **"Why did QUILL say that?"** explain trace, **Safe Mode/reset**, **QVP packs + library + preview lab**, **task-aware profiles**, and **import/export**; and the eleven `quill/ui/verbosity_*` UI surfaces (preferences, token editor, data-order editor, chord editor, library, history, preview lab, safe-mode reset, import/export, QVP install). **Announcement anti-spam** (`throttle.py`, §1.1 #408/#409): repetition collapse drops identical consecutive *speech* within a short window and an optional budget caps spoken announcements per rolling window — both applied at `process()`, affecting only the spoken channel (the visual status-bar floor is never throttled), configured by `verbosity_collapse_repeats` and `verbosity_max_announcements_per_window`. The remaining speculative "polish backlog" long-tail items are deferred to 2.0 (roadmap §5). The pure-domain foundation table:

| Module | Responsibility |
|---|---|
| `channels.py` | `Channel(Flag)` — SPEECH, BRAILLE, SOUND, VISUAL. `route_channels()` always folds in the VISUAL floor, which can never be disabled (the accessibility floor). |
| `tokens.py` | `TokenSpec` (name, type, description, derive, per-token filter allowlist) and the **twelve** engine filters (`upper`, `lower`, `title`, `ordinal`, `pad`, `pluralize`, `singular`, `duration_human`, `date_long`, `date_short`, `time`, `truncate`). No custom filters exist — the security boundary that keeps templates and QVP packs data-only. |
| `parser.py` | Strict template parser for `{name}`, `${filter:name}`, `${filter:arg:name}`; returns structured errors, never raises. `validate()` enforces the §13 contract (token allowlist, filter existence, type compatibility, per-token allowlist, argument rules) and produces the spoken summary. |
| `profiles.py` | Built-in `Beginner` / `Normal` / `Expert` / `Quiet` profiles + `CustomProfile` (JSON round-trip). `profile_for_announcement_verbosity()` / `active_profile()` give the legacy `announcement_verbosity` knob (`minimal`→Expert, `normal`→Normal, `verbose`→Beginner) its first real consumer. |
| `verbs.py` / `registry.py` | `VerbSpec` + `Severity` and the initial verb catalog (the 34 verbs enumerated in §15, across `nav.*`, `edit.*`, `doc.*`, `search.*`, `system.*`, and `_legacy`); `VerbRegistry` with duplicate-id protection and id-sorted `all()`. |
| `data_order.py` | Frozen, hashable `DataOrder` (verb id, ordered fields, separator) with move-up/down/reset/render. When both a custom template and a custom data order exist for a verb, the template wins. |
| `schema.py` | Draft-07 JSON schemas for verbosity settings, the custom-profile store, QVP packs (`additionalProperties: false`, required metadata), and profile import/export — the data contracts the later sub-PRs validate against. |

Tested by `tests/unit/core/test_verbosity_*.py` (102 cases; parser coverage 99%).

#### 5.91.5 Verbosity rebuild — engine and runtime modes (sub-PR 1.2)

Sub-PR 1.2 adds the routing layer on top of the foundation, still wx-free and in `mypy` scope. No user-facing surface yet (chords, status-bar badges, and dialogs land with the UI sub-PR), but the full decision layer exists and `VerbosityEngine.speak()` is reachable from the assistant-panel and AI-Hub announce paths through a no-op `speak_legacy_text()` passthrough.

| Module | Responsibility |
|---|---|
| `engine.py` | `VerbosityEngine.speak(verb_id, ctx, *, quiet, meeting, chord, trigger)` returns a `RenderedAnnouncement` (per-channel text, sound event, channels, profile, severity, template source, suppressed flag, and an `ExplanationTrace`). Template precedence: per-chord override → per-verb override → QVP → default. Channels are routed with the always-on visual floor; Quiet drops speech+sound, Meeting drops sound; the profile's `suppress_routine` hides routine confirmations (errors always speak); sound follows the profile's all / errors-only / off policy. |
| `quiet.py` | `QuietMode` (enter/exit/toggle + phrasing) and `VerbosityUndoStack` — the bounded §11 undo stack of reversible verbosity transitions. |
| `meeting.py` | `MeetingMode` controller (hard-mute sound, reduced speech, braille+visual remain). |
| `mastery.py` | `MasteryTracker` — per-verb success counter that signals a step-down offer exactly once at threshold (default 25), then resets so it never nags; per-verb and global disable. |
| `history.py` | `AnnouncementHistory` — bounded ring buffer of `HistoryEntry` records with filter-by verb/profile/severity/warnings; `redact_text` (on by default) keeps raw token values out of the record, storing only the user-facing rendered text. |
| `explain.py` | `ExplanationTrace` — the full "Why did QUILL say that?" account (verb, trigger, profile, channels, template source, per-channel output, suppression reason, mode/override/QVP flags) rendered to plain copyable text. |
| `safe_mode.py` | `VerbositySafeMode` (toggle + `QUILL_SAFE_MODE` / `QUILL_VERBOSITY_SAFE_MODE` env detection) and non-destructive `reset_verb` / `reset_chord` / `restore_builtin` helpers that return a new `CustomProfile`. |
| `feedback_tuning.py` | `FeedbackStore` — local Too Much / Too Little / Just Right tallies per verb with a gentle one-shot suggestion; declined verbs never re-suggest. No telemetry. |
| `task_profiles.py` | `TaskProfileSuggester` — opt-in, **off by default**, per-extension profile suggestions with accept/reject memory. |
| `import_export.py` | `.quill-verbosity-profile.json` import/export. Strictly data: structure is validated by hand and nothing from the file is executed (no `exec`/`eval`/`__import__` path), verified by test. |
| `storage.py` | Atomic `verbosity_custom.json` read/write via `write_json_atomic`; a corrupt file loads as empty defaults plus a load error for a nonblocking warning, never throwing the user out. |

Tested by 11 more `tests/unit/core/test_verbosity_*.py` modules (180 verbosity cases total; engine coverage 96%). The 16 `VerbositySettings` fields and the chord/badge/dialog surfaces are deferred to the call-site-migration and UI sub-PRs.

#### 5.91.6 Verbosity rebuild — QVP packs, library, and preview (sub-PR 1.3)

Sub-PR 1.3 adds the shareable-pack and preview core, still wx-free.

| Module | Responsibility |
|---|---|
| `quill/core/schemas/qvp.json` | The canonical `.qvp.json` schema (§20): nested `pack` metadata, a `templates` array, `kind` fixed to `quill-verbosity-pack`, `additionalProperties:false`. For humans/tools — validation is by hand (no jsonschema runtime dep). |
| `qvp.py` | Loads and validates packs by hand (structured errors, never executing pack content — no `exec`/`eval`/`__import__`, test-asserted) and runs the §21 install flow: JSON → schema → kind → `min_quill_version` gate → metadata → unique template ids → namespace-collision check → dependency check (missing deps warn) → validate each template against its target verb → install → announce. Returns `QVPInstallResult(accepted, rejected_templates, warnings, spoken_sequence, errors)`. |
| `library.py` | `TemplateLibrary` — a flat collection across built-in / user / QVP sources with save / rename / delete CRUD (read-only built-ins and QVP entries) and cross-verb `apply()`, which strips tokens the target verb doesn't track and reports them. |
| `preview.py` | The fourteen built-in Preview Lab scenarios and `preview_scenario` / `preview_all`, which render each through a `VerbosityEngine` and surface per-channel output plus profile, template source, channel mix, and suppressed content. |

Tested by `test_verbosity_qvp.py`, `test_verbosity_library.py`, `test_verbosity_preview.py`, and golden snapshots under `tests/golden/verbosity/` (220 verbosity cases total; qvp coverage 95%). The Library CRUD UI, the QVP install dialog, and the Preview Lab dialog are deferred to the UI sub-PR.

#### 5.91.7 Verbosity rebuild — the wxPython UI (sub-PR 1.4)

Sub-PR 1.4 adds the user-facing surfaces under `quill/ui/`, each A11Y-4 hardened (label-then-control via mnemonics, `SetName`/`SetHint`, `apply_modal_ids`, deterministic focus, no icon-only buttons, registered in the dialog inventory) and wired to the already-tested pure core. The dialogs are not yet menu/chord-reachable — that is sub-PR 1.5.

| Surface | Responsibility |
|---|---|
| `verbosity_prefs.py` | The embeddable `wx.Panel`: profile picker, the four-channel mix (Visual checked + disabled — the always-on floor), validation-mode and mastery boxes, tool buttons (Preview Lab / History / Templates / Safe Mode / Import-Export), and a filterable verb table (master list + detail) whose Edit-announcement / Data-order buttons launch the editors. Initial focus is the filter. |
| `verbosity_token_editor.py` | Simple/Advanced **RadioBox** (not a notebook, §5 decision 6) over one template field; `Ctrl+T` validates and speaks the §13 summary, `Ctrl+Shift+P` previews (via `EVT_CHAR_HOOK`); Save is disabled with a tooltip while blocking errors exist; Insert-token and Speak-current-template. |
| `verbosity_data_order.py` | Move Up / Down / Reset / Preview over a verb's field order. |
| `verbosity_chord_editor.py` | Per-chord template overrides, validated against the chord's verb. |
| `verbosity_library.py` | Template CRUD (Save/Rename/Delete, read-only built-ins & QVP) + Install QVP. |
| `verbosity_qvp_install.py` | Browse → validate → install a `.qvp.json`, reading back the spoken sequence, accepted templates, rejected (with reasons), and dependency warnings; Install is disabled until a valid pack is selected. |
| `verbosity_history.py` | Review / replay / copy / explain recent announcements with a live filter; the explanation pane shows the full trace. |
| `verbosity_preview_lab.py` | The 14 scenarios with per-channel output (speech/braille/visual/sound), profile, template source, channel mix, and suppressed content. |
| `verbosity_safe_mode.py` | Scoped, non-destructive resets (disable custom / reset verb / reset chord / restore built-ins) with export-first. |
| `verbosity_import_export.py` | Data-only `.quill-verbosity-profile.json` import/export. |

The 3-tab About dialog already ships (About Quill, §"About"). Tested by `tests/unit/ui/test_verbosity_ui.py` (62 source-contract cases); the A11Y-4 banned-pattern, dialog-button-contract, escape-z-order, and GATE-11 gates pass, and `dialog_inventory.json` was regenerated with 12 new hardened surfaces.

#### 5.91.8 Verbosity rebuild — live wiring and polish (sub-PRs 1.5 and 1.6)

Sub-PR 1.5 makes the system live. `quill/core/verbosity/controller.py` (`VerbosityController`, wx-free) owns the engine, Quiet/Meeting controllers, the undo stack, announcement history, mastery, and Safe Mode. `MainFrame` gains `VerbosityCommandsMixin` (`quill/ui/main_frame_verbosity.py`) and registers eight `verbosity.*` commands (palette- and Keyboard-Manager-reachable). The announce choke-point (`MainFrame._announce`) routes through `VerbosityController.process` **only once the controller exists** (created on first verbosity use), so the default path is unchanged until then; once live, Quiet/Meeting suppress speech while the status-bar visual floor remains. Default chords avoid all conflicts (`edit.quote_lines` keeps `Ctrl+Shift+Q`): Quiet = QUILL key + Q, Meeting = QUILL key + Shift+Q, Verbosity Undo = `Ctrl+Shift+Z`; the rest are palette/Keyboard-Manager reachable. Eight scalar `verbosity_*` settings persist (mastery enabled/threshold, validation mode, history enabled/limit/clear-on-exit, task-profile suggestions, Safe Mode); collection-typed state stays in `verbosity_custom.json`. Live in-app behavior warrants a manual smoke run before release.

Sub-PR 1.6 (the original "100-item addendum") was **consolidated** into the deduplicated *Polish backlog*, now the authoritative status list in **roadmap §6** (the standalone `verbosity-system.md` archive was retired once verbosity shipped). Rather than 100 separate features: the duplicates and already-built items are folded into the foundation/engine/UI shipped in 1.1–1.5; the themed survivors (per-category verbosity via the verb registry, status-query commands, announcement flow control, safety announcements, friendly names, status-bar surfacing, scope profiles, sound learnability, coaching/discovery, braille polish) are tracked there; and the screen-reader-redundant items — **typing echo, command echo, speech rate/pause, punctuation/symbol profiles** — are recorded as **recommend do not build**, because QUILL speaks alongside the screen reader and must not duplicate or fight the settings (echo, rate, punctuation level) the screen reader already owns.

### 5.92 GLOW — Guided Layout and Output Workflow (shipped, experimental opt-in)

GLOW is QUILL's accessibility review and repair system: **guided confidence, not a
compliance dashboard**. It reviews what is in front of the user, explains each
finding in plain language, and applies only deterministic, reviewable fixes. The
`core.glow` feature flag shipped `locked_off` through 0.8.1 while the engine
deployment was finished; for 0.9.0 it ships as an **experimental opt-in**: the
catalog flag is unlocked, but every GLOW surface is additionally gated by the
Experimental tab (`experimental_acknowledged` + `glow_experimental_enabled`,
both default off) through `MainFrame._feature_enabled`, so GLOW is off by
default and user-flippable with no restart. The flag remains a normal
profile-controllable feature.

#### 5.92.1 Surfaces

All commands live under **Tools > GLOW** and in the command palette:

| Command | Behavior |
|---|---|
| GLOW Audit Current Document | In-editor deterministic audit of the whole buffer (plain text, Markdown, HTML); report opens as a named scratch tab. |
| GLOW Audit Selection / Paragraph | The same audit scoped to the selection, or the paragraph/line at the caret. |
| GLOW Fix Current Document | Deterministic fixes into a *named preview tab* plus an immediate compare session against the original — accept with full knowledge, never a silent rewrite. |
| GLOW Fix Selection / Paragraph | Quick in-place fix of the scoped block; the replacement is selected afterward so it can be reviewed or undone in one step. |
| GLOW Audit File... | **(new with the unlock)** Structured-document audit — DOCX, PPTX, XLSX, PDF, EPUB, Markdown — through the shared engine on the background task pool; report tab carries score, grade, and findings. |
| GLOW Fix File... | **(new with the unlock)** Structured-document fix that writes a repaired copy beside the source (`name-accessible.ext`, numbered on collision). The original is **never** modified; consent names the output path before anything runs. |
| Check for GLOW Updates... (Help) | Opt-in engine update: signed manifest, per-wheel SHA-256, offline `--no-index` install, rollback to the vendored wheels on failure, restart to apply (GLOW-8). |

Handlers for the file-level commands live in the `GlowFileMixin`
(`quill/ui/main_frame_glow.py`); in-editor handlers remain in `main_frame.py`.

#### 5.92.2 Rules (in-editor, always available)

Markdown: heading-marker spacing (auto-fix), heading-level jumps, image alt text,
generic link text. HTML: missing `lang` (auto-fix), heading jumps, `img` alt
(auto-fix), generic link text, tables without header cells. Plain text: tab-indent
hazards. All formats: plain-language phrasing and dense-paragraph warnings, and
trailing-whitespace trim on fix. Implemented wx-free in `quill/core/glow.py`.

#### 5.92.3 The shared engine (structured documents)

Structured audit/fix flows through the `quill_glow_core` contract package
(`audit_by_extension` / `fix_by_extension` / `convert_to_markdown`), which bridges
to the `acb-large-print` backend when installed. Deployment contract (hardened
2026-07-02 after the MCP-era split broke it): QUILL's `glow` extra pins
**`quill-glow-core[glow]>=0.1.1` plus `acb-large-print>=8.0.0`** — 8.0.0 is the
first release that ships the split `acb_large_print_core` dispatch backend the
contract wheel bridges to; older backends satisfy the contract wheel's own loose
floor (>=3.0.0) and leave the engine silently unavailable. Vendored wheels live in
`vendor/wheels` for fully offline install. The seam (`quill/core/glow.py`)
degrades honestly: engine absent means an "engine not installed" report, never a
crash (GLOW-1), and severities map onto QUILL's error/warning/info levels.

#### 5.92.4 Privacy and consent

The default GLOW path is entirely on-device. The engine's optional networked
features — AI alt-text, Presidio PII redaction, WCAG language processing — are
structurally off: the seam forwards no feature-enabling kwargs unless the caller
passes a `GlowNetworkConsent` with a feature explicitly set after per-action
consent (GLOW-7). The engine update check is the only other network touchpoint,
runs only on explicit invocation, and is registered in the network-egress audit
(GATE-9).

#### 5.92.5 Accessibility contract

Reports are plain, heading-structured text in ordinary tabs (searchable, brailled,
speakable); every finding carries rule id, severity, location when known, and a
plain-language suggestion; fix flows announce counts and destinations; file fixes
are non-destructive by construction; background parses never block the UI thread.

### 5.93 Import / Convert Document — free-first conversion and OCR (shipped, all three tiers)

The supported document-rescue tool, now the **canonical spec** (the standalone
OCR planning PRD has been retired into this section; remaining depth items are
tracked in roadmap §5). The routing principle: **free first, local first, and
nothing is ever uploaded without explicit consent** — the paid cloud tier is
reached only when the free local tiers fall short, and only after a per-upload
consent dialog.

#### 5.93.1 The three tiers

| Tier | Engine | Handles | Cost / privacy |
|---|---|---|---|
| 1 | MarkItDown (`quill/io/markitdown_bridge.py`, ships with the `pages` extra) | Born-digital DOCX/DOC, PPTX/PPT, XLSX/XLS, HTML, EPUB, CSV, ODT/ODP/ODS, and PDFs with a text layer | Free, local, no upload |
| 2 | Local Tesseract OCR (`quill/io/tesseract_ocr.py`) | Images (PNG/JPG/TIFF/BMP/GIF/WebP) and image-based PDFs; CPU-only, no GPU | Free, local, no upload |
| 3 | Datalab Chandra cloud OCR (`quill/core/datalab_ocr.py`) | The accuracy escalation: complex tables, forms, handwriting, math, dense layouts, poor scans; returns Markdown/HTML/JSON | Paid (BYOK, per page on the user's Datalab account), cloud, **consent-gated per upload** |

The router (`quill/io/docconvert.py`, wx-free, strict-typed) implements the
free-first flow: born-digital types go to Tier 1; images go straight to
Tier 2; PDFs try Tier 1 and are measured by the **chars-per-page heuristic**
(`text_layer_looks_empty`, threshold 50 chars/page) — a PDF that comes back
looking scanned is flagged `offer_local_ocr`, never silently opened empty.
Tier 2 rasterizes PDF pages via `pypdfium2` (~150 dpi) and recognizes them one
at a time with cancel checks between pages, joining pages with the
screen-reader-searchable `<!-- Page N -->` delimiter. Tesseract's TSV output
supplies per-word confidence; a mean below 60 flags the outcome `looks_weak`
— the Tier 2 -> 3 escalation point. Tier 3 (`convert_with_cloud_ocr`) adapts
the Datalab result into the same `ConversionOutcome`, so every downstream
surface (open-as-tab, review, announcements) is tier-agnostic.

#### 5.93.2 Escalation prompts (never silent, cost/upload named exactly once)

Tier 1 -> 2 (stays free and local): *"QUILL could not find readable text in
<file>. It looks scanned or image-based. Run free on-device OCR (local
Tesseract)? This stays on your computer and does not upload anything."* —
Yes runs OCR, No opens the empty result anyway, Cancel imports nothing.

Tier 2 -> 3 (the only prompt that mentions money or upload; shown only when
the service is configured): *"On-device OCR finished, but the result looks
low-quality or the layout is complex. For higher accuracy you can convert it
with Datalab cloud OCR. This uploads the file to a cloud service and may cost
money."* — accepting leads to the §5.93.2a consent dialog; declining keeps
the local result. When Tier 2 is unavailable (engine not installed) and the
user declines the free install, the same offer applies — free-first order is
structural.

##### 5.93.2a Upload consent (every time, no exceptions)

Before **every** cloud upload, a consent dialog states: the document will be
sent to Datalab; continue only if allowed to upload it; consider
private/medical/legal/educational/financial/employment/confidential content;
Datalab deletes results ~1 hour after processing and QUILL retrieves promptly,
keeping the result only in the opened document. A **filename heuristic**
(`looks_sensitive`: tax/medical/patient/ssn/legal/IEP/... fragments — names
only, content is never inspected) prepends an extra CAUTION line. There is no
"don't ask again": consent is per-action by design.

#### 5.93.2b Cloud client contract (`quill/core/datalab_ocr.py`)

REST against the Datalab Convert API (`POST /api/v1/convert`, multipart, key
in `X-API-Key`; poll `request_check_url` with cancel checks until complete).
BYOK: the key lives in the credential vault
(`QUILL/services/datalab/api_key`) with a `DATALAB_API_KEY` env fallback —
never in settings files. HTTPS enforced; Safe-Mode blocked; injectable opener
keeps tests offline; GATE-9 entry `core/datalab_ocr.py::_request`. Errors map
to the PRD's friendly table (rejected key / billing issue / too large / rate
limited / unreachable / incomplete / empty / timeout), and logging carries
state transitions and page counts only — never content, output, keys, or
bodies. Non-secret knobs persist as settings: `datalab_enabled` (default
off), `datalab_endpoint` (HTTPS-validated), `datalab_mode`
(fast/balanced/accurate), `datalab_output` (markdown/html/json),
`datalab_paginate`.

#### 5.93.2c AI Hub Services tab

**AI Hub > Services** is the customer-facing service manager (opened directly
by **OCR Service Settings...**): a plain-language intro naming the free tiers
first, then the Datalab card with a live status line (Ready / Needs API key /
Not configured), enable checkbox, key field (saved to the vault), endpoint,
default mode/output, page delimiters, an always-on "confirm before upload"
statement, **Test Connection** (key-presence + endpoint sanity only — states
explicitly that no document is uploaded), **Copy Service Summary**
(secret-free, `API key value: Not included`), and six provider link buttons
(website, API keys, pricing, privacy/security, API docs, supported file
types), each announcing that it opens in the browser. `open_ai_hub` folds the
saved Datalab fields back into the live settings object so the next
conversion sees them without a restart.

#### 5.93.2d OCR Review Mode (v1: the spoken checklist)

**Review Last OCR Result...** opens a named tab over the most recent
conversion: source, producing tier/service, page count, mean confidence,
warnings, and every low-confidence line pre-formatted as
`Page N: [NN%] text` (populated by Tier 2 from per-word TSV confidence).
The reviewer walks exactly the flagged lines and jumps into the converted
document by searching the page marker — review by ear, not re-proofreading.
Cloud/Tier-1 results state honestly that no per-line confidence exists.
(The full §12 review workspace — outline tree, per-block accept/re-run,
table review — is tracked as future depth in roadmap §5.)

#### 5.93.2e Temporary files

**Delete OCR Temporary Files** clears leftovers under the app-data
`ocr_jobs` folder (crash residue) and reports what was removed; the local
tiers use per-run auto-cleaned temp directories, so normally there is
nothing to delete. Results live only in the opened (unsaved) document until
the user saves.

#### 5.93.3 Engine acquisition (verified downloadable component)

Tesseract is never bundled. `quill/core/tesseract_install.py` downloads the
**byte-identical official UB-Mannheim 5.4.0 installer** (Apache-2.0) from
QUILL's pinned `assets-v1` release, SHA-256-verified (SEC-6), HTTPS-enforced,
Safe-Mode-blocked, then **launches the installer visibly** for the user to
complete — NSIS has no admin-free extraction analogous to `msiexec /a`, and
QUILL never silently elevates. Discovery
(`quill.io.tesseract_ocr.discover_tesseract_executable`) then finds the engine
with no restart: settings override (`tesseract_path`) -> QUILL-managed folder
-> `PATH` -> the conventional `C:\Program Files\Tesseract-OCR` location. The
download call site is registered in the network-egress audit (GATE-9). On
macOS the managed download is not offered; a Homebrew-installed `tesseract`
on PATH is picked up automatically.

#### 5.93.4 Surfaces

- **File > Import > Import / Convert Document (OCR)...** (leads the submenu)
  and the same command in **Tools > Reading & Dictation**; palette id
  `file.import_convert`.
- **Tools > Reading & Dictation > Install Local OCR Engine (Tesseract)...**
  (`tools.install_local_ocr`) — consent names the size and exactly what will
  happen before any download.
- **Tools > Reading & Dictation > OCR and Conversion Services...**
  (`tools.ocr_services`) — the customer-facing services overview: a friendly
  card per tier (what it does, best for, local-or-cloud, cost, limits, setup)
  plus the live engine install status, in plain language per the OCR PRD's
  Services-tab content requirements. A full AI Hub Services tab ships with the
  first cloud provider.

Handlers live in `quill/ui/main_frame_docconvert.py` (`DocConvertMixin`).
Settings: `ocr_language` (Tesseract three-letter code, default `eng`) and
`tesseract_path` (explicit override). Commands map to `core.ocr` (the install
and services surfaces) so OCR-less profiles stay clean.

---

### 5.94 Math in QUILL — equation input, rendering, structural exploration, and Word export (shipped)

**Goal.** Close the gap the bundled math-equations Quillin always had: an
equation could be typed in, but nothing rendered it, nothing let a
screen-reader user explore its structure, and Word never saw a real
equation object. This section is now the canonical record; the original
planning doc (`docs/planning/math.md`) is retired now that the feature has
shipped in full.

**Canonical model (`quill/core/math/`, wx-free, unit-tested).**
`mathml.py` holds the canonical in-memory representation — MathML, the same
input MathCAT and every screen-reader math engine already expects — with
the original LaTeX source recoverable via a `semantics`/`annotation` pair
(the same interop convention MathJax's own `tex2mathml` uses), so no general
MathML-to-LaTeX parser is needed. `latex_bridge.py` is a `latex2mathml`-backed
LaTeX-to-MathML bridge (the optional `math` extra; the module degrades to a
clear `LatexBridgeUnavailable` rather than failing at import time when it is
absent). `navigator.py` is a lightweight structural navigator — not a
MathCAT-quality math-speech engine — that steps through an equation's parts
(numerator/denominator, base/exponent, a root's radicand) and produces a
plain-English linear reading with a small set of template rules; it is the
"basic algebra, useful today" alternative to real Nemeth/UEB math speech.

**Input (math-equations Quillin).** `Ctrl+Shift+E` / **Insert → Insert
Equation...** takes LaTeX or MathML and wraps LaTeX as `\(...\)` (inline) or
a single-line `$$...$$` (display) — both MathJax's own default-recognized
delimiters, chosen specifically so no rendering template needs a config
change and so a bare `$` in ordinary dollar-amount prose is never
mistaken for math (the earlier `$...$` convention was replaced for exactly
this reason). **Insert → Snippet Gallery...** carries ten static
`$$...$$` formulas (quadratic formula, Pythagorean theorem, slope-intercept
and point-slope forms, slope/distance/midpoint formulas, difference of
squares, circle area/circumference) contributed via the existing
`contributes.snippet_gallery` manifest mechanism — no new UI. 88 Math
AutoCorrect-style abbreviations (seeded from the DAISY-published Word list,
daisy.org/MSMathCodes) are contributed via the existing Insert Automation
abbreviation system; `\delta`/`\Delta` and similar case-differentiated pairs
depend on a fix in `quill/core/abbreviations.py` — `build_contributed_library`
was silently dropping the manifest's `case_sensitive` field.

**Structural exploration.** **Insert → Explore Equation Structure...**
(`Ctrl+Shift+Grave, F`) parses the selection (or a fresh prompt) via
`navigator.py` and drives a sequence of `ui.choices` calls — no new core UI,
entirely within the existing Quillin capability model. Each `ui.choices`
call is a `wx.SingleChoiceDialog` (standard listbox semantics: arrow keys
move the highlight, type-ahead jumps to a match, Enter/OK activates the
highlighted item); **Escape/Cancel at any depth ends the whole session
immediately**, identically to choosing **Done exploring** — it is not "go
up one level," which is the dedicated **Back up one level** choice.
Descending into a numbered child re-announces (`ctx.announce`, speech only)
the new node and reopens the list for its children (role labels: Numerator,
Denominator, Base, Exponent, ...); **Read this part aloud** speaks a full
reading of only the current node via `quill.core.math.speech.speak()`
(below) and reopens the same list at the same position.

**Real math speech (`quill/core/math/mathcat_engine.py`,
`quill/core/math/speech.py`).** **Read this part aloud** is the one part of
Explore Equation Structure that upgrades: `speech.speak(element)` tries the
real MathCAT engine first and falls back to `navigator.read_aloud()` (the
template renderer) on any failure or absence — never raises, always
returns a usable string. The structural walk itself (numerator/denominator/
base/exponent stepping, the ambient per-step labels) is intentionally left
on the lightweight template system even when MathCAT is installed: those
labels are meant to be short list items ("Fraction", "Numerator: Group"),
and MathCAT's fuller natural-language prose would make them unwieldy;
`navigator.py` stays MathCAT-free by design so the mandatory install-nothing
path never depends on it.

MathCAT itself has no pip-installable Python binding, but a maintained,
separate C-interface project (`daisy/MathCATForC`, MIT) publishes prebuilt
Windows DLLs, header, and Rules data as GitHub release assets — no Rust
toolchain or PyO3 wrapper needed at all. `mathcat_engine.py` binds that DLL
via plain `ctypes` against its C-string API (`SetMathML`, `GetSpokenText`,
`SetRulesDir`, ...). The API is process-global mutable state (`SetMathML`
sets "the" current equation for the whole process), so every call is
serialized behind a lock. **Memory safety note, found and fixed the hard
way**: declaring a string-returning function's `restype` as
`ctypes.c_char_p` makes ctypes copy the string into a new Python `bytes`
object and discard the original pointer — freeing "it" afterwards then
frees memory Rust's allocator never allocated (confirmed by hand:
`STATUS_HEAP_CORRUPTION`). Every string-returning function is declared
`c_void_p` instead; a dedicated `_read_and_free` helper casts that exact
address to read it, then frees that exact address.

Distribution follows the existing `quill.core.release_assets` pattern
(whisper.cpp, kokoro, vosk, the braille pack, libmpv, spell dictionaries):
a byte-identical re-publish, pinned by SHA-256, on QUILL's own `assets-v1`
release tag, fetched on demand (**Help → Download Optional Components... →
MathCAT math speech engine**, ~3 MB) with the same already-installed/consent
dialog pair and Safe Mode gate every other component in that list uses.
`quill.core.optional_components._mathcat_installed()` is the availability
check surfaced in that dialog.

Known open item: MathCAT's own speech phrasing has at least one rough edge
observed directly (an implicit-multiplication connector rendered oddly in
one tested equation) that needs a real screen-reader user's ears and
possibly a `SetPreference` tuning pass (verbosity, `ImpliedTimes` style)
before this is the polished default experience — tracked as a follow-up,
not blocking the current shipment. Real Nemeth/UEB math **braille** (the
crate also produces it) is not wired here; that is a further follow-up once
speech quality is validated.

**Rendering.** Browser Preview and HTML export already carried a MathJax
CDN `<script>` tag; the actual fix was recognizing that MathJax's default
`inlineMath` delimiter is `\(...\)`, not bare `$...$` (dollar signs are
opt-in specifically to avoid colliding with prose), so switching the
Quillin's own delimiters to MathJax's defaults made both surfaces render
correctly with **zero template changes**. Verified empirically (headless
browser screenshot), not assumed.

**Word export and round-trip (`quill/io/docx_math.py`).** The native
python-docx writer (`quill/io/docx_writer.py`) had no math model; math spans
in a run's text are now detected and each converted to a real
`<m:oMath>`/`<m:oMathPara>` fragment via a one-equation Pandoc round-trip
(write a tiny Markdown file containing just that equation, convert to docx,
extract the fragment, splice it into the run stream via
`docx.oxml.parse_xml`). Falls back to the literal delimited text — never
silently drops the equation — when Pandoc is unavailable or a specific
conversion fails. `omml_fragment_for_latex` is memoized (`functools.lru_cache`)
so a document repeating the same formula does not spawn a Pandoc subprocess
per occurrence. The docx *read* path (both the default MarkItDown engine and
the Pandoc engine) already round-tripped a native equation back to `\(...\)`
text correctly; regression tests lock that in.

**AI.** A read-only `math-tutor` agent (`default_scope: selection`,
`modify_selection: deny`) explains a selected equation in plain language
without solving anything or touching the document.

**Shipped after all: real MathCAT speech.** An earlier pass through this
section concluded MathCAT integration meant QUILL building its own
PyO3/Rust binding against the `libmathcat` crate and standing up a new
native-build CI pipeline (comparable to `table_uia`) — that conclusion was
wrong, corrected once `daisy/MathCATForC` (a separate, actively maintained,
MIT-licensed C-interface project publishing prebuilt Windows DLLs) was
found. See "Real math speech" above: the binding is a `ctypes` wrapper
against an already-compiled binary, not a new Rust toolchain. Real Nemeth/
UEB math **braille** (MathCAT also produces it) is not wired yet — a
follow-up once the speech path is validated by ear, not a native-build
blocker.

**Explicitly skipped.** DAISY MathML export: `quill/io/daisy.py` is a
DAISY 2.02 *text-only* writer (no OPF/NCX/EPUB3), and no DAISY 2.02 player
has real MathML rendering/speech support, so embedding raw `<math>` there
would be inert markup, not real accessibility.

**Tutorial:** [07-type-math-like-a-pro.md](../tutorials/07-type-math-like-a-pro.md)
teaches the whole surface end to end — gallery first, then typed input, the
structure explorer, Browser Preview, and the Word round trip.

---

## 6. Spell checking deep dive

### 6.1 The TinySpell question

TinySpell is a small, fast Windows spell-checker that watches the clipboard or current input field and alerts on misspellings. It is genuinely useful for many users. So the question is: should Quill integrate tightly with TinySpell, or build its own engine?

We have chosen to **build our own engine**, tightly integrated into Quill, for the following reasons:

1. **Screen-reader fidelity.** TinySpell speaks through its own UI surfaces and conventions. Quill needs total control over how misspellings are announced, navigated, and corrected so that NVDA, JAWS, and Narrator hear the same predictable patterns. A loose integration would create a second source of speech that competes with our own.
2. **Document context.** TinySpell works across applications and therefore cannot use document-level context (heading structure, surrounding paragraph, language metadata, per-document dictionary). Quill knows exactly what document the cursor is in and can do much better.
3. **Per-document and per-paragraph language detection.** Multi-language documents need language switches mid-stream. An external tool will not know.
4. **Suggestion ranking that learns.** TinySpell's suggestion order is fixed. Quill ranks suggestions using the user's own writing and the surrounding sentence, which is the single biggest quality-of-life upgrade in modern spell check.
5. **Offline guarantee.** Quill commits to spell check working with zero network. An external dependency complicates that guarantee.
6. **Distribution.** Bundling TinySpell would create a licence and update story we do not control.
7. **Keymap and palette parity.** Every Quill action is in the palette and reassignable. Spell-check commands must be too.

We will, however, ship a small **TinySpell interop plugin** for v1.1 for users who already rely on TinySpell elsewhere and want a unified personal dictionary. That plugin imports/exports the personal dictionary file and otherwise stays out of the way.

### 6.2 Engine architecture: "Quill Spell"

Quill Spell is a layered local engine:

- **Layer 1: Tokeniser.** Unicode-aware word splitter that understands code (CamelCase, snake_case, kebab-case), contractions, hyphenation, URLs, emoji, file paths, and Markdown/HTML syntax tokens. It hands the next layer a stream of `(word, span, context_kind)` tuples where `context_kind` is one of `prose`, `code`, `identifier`, `url`, `markup`, `path`.
- **Layer 2: Dictionary stack.** A priority-ordered stack of dictionaries: per-document, per-project (if applicable), user personal, language-base (Hunspell), plus optional jargon packs (medical, legal, technical, scientific). The first dictionary that accepts the word wins.
- **Layer 3: Hunspell backend.** Bundled via `cyhunspell`. Dictionaries shipped: en-US, en-GB, en-CA, en-AU, es-ES, es-MX, fr-FR, de-DE, pt-BR, pl-PL, ja-JP (with MeCab). Others available via a one-click downloader.
- **Layer 4: Suggestion engine.** Combines Hunspell's edit-distance suggestions with a character-level n-gram model and a small contextual reranker (a tiny on-device transformer; runs on CPU in <10 ms per call). Top 5 suggestions, ranked by combined score.
- **Layer 5: Learning loop.** When the user accepts a suggestion, the engine increments its frequency. When the user adds a word, it goes to the appropriate dictionary (with a prompt asking which). When the user repeatedly rejects a suggestion in favour of another, the reranker learns the preference. Learning is 100 percent local and resettable.
- **Layer 6: Context awareness.** The tokeniser tells the engine when it is inside a code fence, an inline code span, a URL, or a Markdown link target. Those regions are skipped by default. Settings let the user enable code spell checking with a programming-aware dictionary.

### 6.3 User experience

- **Status indicator.** The status bar shows the active dictionary stack as a short label, for example `en-GB + tech + personal`.
- **`F7` Spelling Review.** *(Implemented 0.7.0 Beta 2 — see §6.4 for the full specification.)* A modal guided dialog. Focus opens in a read-only multiline **Context** field with the misspelled word selected within its sentence. Tab order: Context → Change to → Suggestions → Change → Change All → Ignore Once → Ignore All → Add to Dictionary → Undo Last → Close. All actions available without a mouse. Announcements are configurable (Concise / Balanced / Detailed). Optional letter-by-letter spelling of the wrong word after a configurable pause. Scope detects selection vs. whole document. Case-preserving Change All. Session-scoped Ignore All. Position-aware undo.
- **`Ctrl+F7` / `Ctrl+Shift+F7` next/previous misspelling.** Jumps directly to the next or previous misspelling from the caret without opening the full review dialog.
- **Background pass.** A debounced background tokenise runs as the user types. Results live in a sidecar model. No visual squiggles. The screen reader is never interrupted by background work.
- **Per-document language.** A YAML-style sidecar (`<doc>.quill.yml`) can pin language and dictionaries. Detected automatically from a magic comment on the first line if present.
- **Magic touches.**
  - When you add a word, Quill says "Added <word> to your personal dictionary" or "Added <word> to this document's dictionary" so you always know where it went.
  - When you reject the same suggestion three times for the same misspelling, Quill quietly asks once whether you want to add the rejected word to your personal dictionary.
  - When pasting a large block of text, the spell pass is queued at a lower priority so the paste itself is instant.
  - When entering a code fence in Markdown, the engine switches automatically to identifier mode and stops complaining about variable names.

### 6.4 F7 Spelling Review — Full Specification

> **Status: Implemented in 0.7.0 Beta 2.** This section is the canonical
> specification for the shipped feature; the original standalone planning PRD was
> retired to git history once delivered.

---

#### 6.4.1 Executive Summary

QUILL provides a classic, guided spelling-review experience invoked with **F7**. The feature preserves what made the traditional Microsoft Word spelling dialog effective — one issue at a time, clear suggestions, predictable actions, and an obvious path through the document — while substantially improving that experience for screen-reader and keyboard users.

The defining feature is a focusable **multiline, read-only Context field** that contains the misspelled word in meaningful surrounding text. The current word is selected when the field receives focus so users can hear it in context, review it character by character, move by word or line, copy text, and understand punctuation and sentence structure without leaving the spelling-review dialog.

#### 6.4.2 Product Vision

Pressing F7 in QUILL should feel reassuring and familiar:

1. QUILL finds the next potentially misspelled word.
2. The Spelling Review dialog opens.
3. Focus lands in a read-only multiline Context field.
4. The problem word is selected inside its sentence or paragraph.
5. The screen reader announces the issue, progress, and context without excessive repetition.
6. The user can inspect the text with normal editing-navigation commands.
7. The user can Tab to the replacement field, suggestions, and actions.
8. Every action immediately confirms what happened and advances to the next issue.
9. At completion, QUILL reports a useful summary and returns focus exactly where the user expects.

#### 6.4.3 Goals

**Primary goals:**

- Provide a complete spelling review through F7.
- Present each misspelled word in meaningful, navigable context.
- Make the entire workflow usable without a mouse.
- Make the workflow excellent with NVDA, JAWS, Narrator, and other screen readers using standard Windows accessibility APIs.
- Use standard controls and predictable focus behavior wherever possible.
- Provide concise, useful speech for state changes without duplicating what the screen reader already announces.
- Support Ignore Once, Ignore All, Change, Change All, Add to Dictionary, Undo Last Action, and Close.
- Preserve document integrity, undo history, caret position, selection, viewport, formatting, and accessibility state.
- Keep local document text private by default.
- Scale to large documents without freezing QUILL.

**Secondary goals:**

- Support multiple dictionaries and document languages.
- Provide configurable context size and speech verbosity.
- Provide a reusable review framework that could later support grammar, terminology, style, and accessibility checks.

#### 6.4.4 Non-Goals for Initial Release

- Grammar, style, readability, or inclusive-language review in the same dialog.
- Sending document text to an online service by default.
- Require direct integration with a specific screen reader.
- Automatically rewrite text without explicit user action.
- An always-open proofing sidebar.

#### 6.4.5 Design Principles

- **Familiar, but better.** Retain the strengths of classic sequential spell checking while resolving focus uncertainty, insufficient context, repeated speech, ambiguous button behavior, and loss of position.
- **Context is a first-class control.** The Context field is a standard, focusable, multiline, read-only edit control — not a static label.
- **Standard controls before custom controls.** Use native wxPython controls with reliable name, role, state, value, selection, and keyboard behavior.
- **Speech should inform, not compete.** QUILL announces transitions and results. It does not speak what the screen reader will already announce on focus.
- **No keyboard traps.** Every control is reachable and escapable. Tab and Shift+Tab move predictably. Escape never leaves the user uncertain.
- **User control over every edit.** No spelling correction is applied until the user activates an explicit action.
- **Preserve the document experience.** When the dialog closes, the user returns to the document with caret, selection, and scroll position restored.

#### 6.4.6 Terminology

| Term | Meaning |
|---|---|
| Issue | A token QUILL's spelling provider considers unknown or misspelled |
| Current word | The word under review |
| Context | Surrounding document text shown in the read-only multiline field |
| Replacement | Text that will replace the current word when Change is activated |
| Suggestion | A spelling-provider recommendation |
| Review session | The complete F7 workflow from invocation until completion or cancellation |
| Review scope | Selection or full document, depending on caret/selection state at F7 |
| Session ignore | A word ignored until the current review session ends |
| User dictionary | A persistent, language-specific list of accepted words |

#### 6.4.7 Invocation and Review Scope

- **F7:** Start Spelling Review. Also available from **Tools > Spell Check...**
- **Scope rules:**
  1. If the editor has a nonempty selection, F7 checks the selection only.
  2. If there is no selection, F7 checks the entire document.
  3. If the document is empty, QUILL reports that and takes no action.
- The opening announcement states the scope: *"Spelling review. Checking selected text."* or *"Spelling review. Checking document."*

#### 6.4.8 Main Dialog Specification

**Dialog model:** Modal. Title format: **Spelling Review — Issue 3 of 18**

**Tab order:**
1. Context field
2. Change to field
3. Suggestions list
4. Change button
5. Change All button
6. Ignore Once button
7. Ignore All button
8. Add to Dictionary button
9. Undo Last button
10. Close button

**Issue label:** A bold static text label above Context showing *"Not in dictionary: word"*.

#### 6.4.9 Context Field

- Standard multiline `wx.TextCtrl` with read-only and multiline styles.
- Labeled **Context around word (Alt+W to reselect)**.
- Focusable; included in Tab order.
- Supports character, word, line navigation and Ctrl+C copy.
- Protected from modification, pasting, or deletion.
- On each new issue: populates, computes word offsets, selects the word, moves focus via `wx.CallAfter`.
- **Alt+W** at any time refocuses Context and reselects the current word.

**Context construction** (`quill/core/spelling/context_builder.py`):

- Splits on sentence boundaries using `re.split(r"(?<=[.!?])\s+", ...)`.
- Includes the sentence containing the issue plus adjacent sentences.
- Character ceiling: 900 characters (configurable via `spell_review_context_mode` setting).
- Falls back to a character window when sentence splitting finds no boundaries.
- Preserves original punctuation and Unicode characters.

#### 6.4.10 Change to Field

- Standard single-line `wx.TextCtrl` labeled **Change to** (`Chan&ge to:`).
- Pre-filled with the highest-ranked suggestion, or the original word if no suggestions.
- Full text selected on populate so typing immediately replaces it.
- Enter activates Change.

#### 6.4.11 Suggestions List

- Standard `wx.ListBox` labeled **Suggestions** (`&Suggestions:`).
- First suggestion selected by default.
- Changing selection updates the Change to field.
- Empty when no suggestions; list stays present, Change to pre-filled with original word; announcer says "No suggestions."

#### 6.4.12 Actions

**Change** — Replaces the current occurrence with the Change to field value. Confirms action, advances to the next issue.

**Change All** — Replaces all matching occurrences within scope for the session. Case-preserving: `teh→the`, `Teh→The`, `TEH→THE`. Reports replacement count. Entire operation is undoable.

**Ignore Once** — Skips this occurrence, advances.

**Ignore All** — Ignores all occurrences for the remainder of the session only. Does not persist.

**Add to Dictionary** — Adds the word to the personal dictionary via `core.spellcheck.add_word_to_scope("personal", ...)`. Reversible within the session via Undo Last.

**Undo Last** — Reverses the most recent spell-review action without closing the dialog. Supports: Change, Change All, Ignore Once, Ignore All, Add to Dictionary. Disabled when nothing has been done. Restores prior Context, Change to state, and counters.

**Close** — `Escape` or the Close button. Changes already applied remain in the document's normal undo history.

#### 6.4.13 Keyboard Map

| Key | Action |
|---|---|
| Tab / Shift+Tab | Move forward / backward through controls |
| Alt+W | Focus Context and reselect current word |
| Enter (in Change to) | Change |
| Escape | Close |
| Chan&ge mnemonic (Alt+G) | Change button |
| Change &All (Alt+A) | Change All button |
| &Ignore Once (Alt+I) | Ignore Once button |
| Ignore A&ll (Alt+L) | Ignore All button |
| Add to &Dictionary (Alt+D) | Add to Dictionary button |
| &Undo Last (Alt+U) | Undo Last button |
| &Close (Alt+C) | Close button |

#### 6.4.14 Screen-Reader Experience

**Announcement service** (`quill/core/spelling/announcements.py` — `AccessibilityAnnouncer`):

Three verbosity modes:

| Mode | What is announced |
|---|---|
| **Concise** | Progress numbers and action results only |
| **Balanced** *(default)* | Issue type, current word, progress, and results |
| **Detailed** | Balanced plus control hints and scope reminders |

**Optional spell-word feature:** After announcing the misspelling, QUILL can spell it letter by letter. Enabled by `spell_review_spell_word` setting. Delay before spelling starts is configurable via `spell_review_spell_word_pause_ms` (default 800 ms, range 100–3000). Implemented with `wx.CallLater`.

**Avoiding duplicate speech:** QUILL does not announce control names before moving focus. It announces only what the focused control will not convey: scope, progress, action results, completion summary, errors.

**Opening (balanced):** *"Spelling review. Issue 1 of 12. Not in dictionary: accomodate."*

**After Change:** *"Changed accomodate to accommodate. Issue 2 of 12."*

**After Ignore Once:** *"Ignored once. Issue 3 of 12."*

**Completion:** *"Spelling review complete. 9 changes, 2 ignored once, 1 word ignored for this session, and 1 word added to the dictionary."*

**Focus rules:**
- Focus lands in Context for every new issue.
- Focus never disappears after an action.
- Disabled controls do not receive focus.
- Closing the dialog returns focus to the originating editor.

#### 6.4.15 Session Data Model

Implemented in `quill/core/spelling/` package:

quill/core/spelling/ init.py — exports SpellingIssue, ReviewCounters, ReviewSession, build_context models.py — ActionKind, SpellingIssue, ReviewCounters, ReviewAction context_builder.py — build_context(text, word_start, word_end, max_chars) -> tuple session.py — ReviewSession (owns text copy, rescan logic, undo stack) announcements.py — AccessibilityAnnouncer

quill/ui/spelling_review_dialog.py — SpellingReviewDialog (presentation only)

**ReviewSession** owns a `_text` copy, rescans after every action via `list_misspellings`, tracks ignored-once positions with offset adjustment (`_shift_ignored_positions`), and maintains an undo stack of `_UndoRecord` objects.

**`_UndoRecord`** stores: action kind, prior text, all_ranges (for Change All), prior ignore state, prior counters.

**Case matching** (`_case_match(original, replacement)`): checks `.isupper()` → uppercase, `.istitle()` → capitalize, else lowercase.

#### 6.4.16 Settings

Settings group added in `quill/core/settings_specs.py` and `quill/core/settings.py`:

| Setting key | Type | Default | Description |
|---|---|---|---|
| `spell_review_verbosity` | choice | `"balanced"` | Announcement verbosity: concise / balanced / detailed |
| `spell_review_spell_word` | bool | `True` | Spell the wrong word letter by letter after announcing it |
| `spell_review_spell_word_pause_ms` | int (100–3000) | `800` | Milliseconds before letter-spelling starts |
| `spell_review_wrap_to_beginning` | bool | `True` | After reaching end of document, wrap to beginning |
| `spell_review_context_mode` | choice | `"sentence"` | Context extraction mode: sentence / paragraph |

#### 6.4.17 Acceptance Criteria

The feature is considered complete when:

1. F7 starts Spelling Review from the active editable document.
2. A nonempty selection is checked without modifying text outside the selection.
3. The dialog uses standard accessible controls throughout.
4. Initial focus lands in the multiline read-only Context field.
5. The active word is selected in Context.
6. Users can navigate Context by character, word, and line and can copy text.
7. Users can reselect the active word with Alt+W.
8. Replacement and Suggestions are fully keyboard operable.
9. Change, Change All, Ignore Once, Ignore All, Add to Dictionary, Undo Last, and Close work correctly.
10. Every action results in a concise, understandable state update.
11. Focus never becomes lost or trapped.
12. Closing returns focus to the originating editor.
13. Changes participate correctly in QUILL's undo history.
14. Change All respects scope and capitalisation rules.
15. Missing dictionaries and provider failures produce accessible messages.
16. NVDA, JAWS, and Narrator can complete the workflow without mouse input.
17. The dialog works in high contrast and at 200% scaling without clipping essential controls.
18. Automated tests cover context offsets, session actions, scope boundaries, position-drift after replacements, and completion behavior.
19. User documentation explains F7, review scope, all actions, and keyboard commands.

#### 6.4.18 Future Enhancements

These remain out of scope for the initial release but can reuse the review session framework:

- Grammar and repeated-word detection
- Style and clarity review
- Terminology enforcement
- Custom organisational and domain dictionaries
- "Explain this suggestion" for advanced providers
- Resume an interrupted review session
- Review only comments, headings, or selected structural regions
- Plugin-contributed proofing providers
- Braille-optimised announcement mode
- A compact review mode for experienced users
- Optional modeless review pane after the modal workflow is mature and proven accessible

---

## 7. Command palette deep dive

The command palette is modelled directly on Visual Studio Code's, adapted for screen readers.

### 7.1 Opening and dismissing

- `Ctrl+Shift+P` opens the palette in command mode.
- `F1` does the same.
- Each prefix shortcut (below) opens the palette pre-seeded with that prefix.
- `Esc` closes without action.
- `Enter` runs the selected entry (and remembers it).
- `Tab` from the input moves into the list. `Shift+Tab` returns to the input.

### 7.2 Prefix modes

A single edit field, one list. The first character of the input may be a mode prefix:

| Prefix | Shortcut to open directly | Meaning |
| --- | --- | --- |
| (none) or `>` | `Ctrl+Shift+P` | Run a command |
| `?` | `Ctrl+Shift+?` | Show help for all prefixes |
| `:` | `Ctrl+G` (when no page markers) | Go to line |
| `@` | `Ctrl+R` | Jump to bookmark in current document |
| `#` | `Ctrl+T` | Jump to bookmark across all open documents |
| `!` | `Ctrl+Shift+M` | Show issues (spell check, bookmark, format) |
| `<` | `Ctrl+E` | Open a recent file |
| `~` | `Ctrl+Shift+O` | Switch open document |
| `=` | (palette only) | Open a setting |

These prefixes are themselves reassignable (see [section 8](#8-keymap-and-keystroke-reassignment)).

### 7.3 Matching

- Fuzzy subsequence match across the visible label.
- Each match scored by: subsequence tightness, prefix bonus, word-boundary bonus, recency, frequency.
- Top 100 results displayed, lazily.
- Ties broken alphabetically.

### 7.4 Rows

Each row in command mode shows three regions, all announced as one string by the screen reader (with internal punctuation chosen to read well):

```text
<Command title> — <current keybinding or "unassigned"> — <source>

For example:

Improve Reading Order with AI — unassigned — Quill
Spell Check Document — F7 — Quill
Find Next — F3 — Quill
Pandoc: Convert to DOCX — Ctrl+Alt+P — Plugin: Pandoc Bridge

7.5 Inline keybinding edit

While the palette is open and a command is highlighted:

• Right Arrow enters keybinding edit mode for that command.
• A small inline edit prompt says “Press the new shortcut, or Escape to cancel, or Delete to unassign.”
• The next keystroke (chord or sequence) becomes the binding.
• Conflicts are detected immediately and announced (see section 8.4).
• Enter commits, Esc cancels.

7.6 Recently used and pinned

• The most recently run 10 commands always appear at the top when the palette opens fresh, before any typing.
• Users can pin commands with Shift+Enter from the palette. Pinned commands always appear above recents.

7.7 Help

• ? plus Enter, or Ctrl+Shift+?, shows a “How to use the Command Palette” topic in the palette itself: a list of prefixes, their meanings, and their shortcuts, each line runnable with Enter to invoke an example.
• Where Am I (Ctrl+Shift+I) in the palette announces: current mode, number of matches, selected entry, current binding.

7.8 Accessibility specifics

• The palette is a non-modal top-level wx.Frame over the main window with focus capture. Underlying widgets are a wx.SearchCtrl and a wx.ListBox. Both are stock controls, so all screen readers get correct announcements without scripts.
• Each list update fires a single accessibility event with the count of results; we do not spam announcements as the user types.
• Live region is set on the help/result line below the list for status messages such as “Keybinding updated” and “Conflict with Find Next.”

8. Keymap and keystroke reassignment

Every Quill action is identified by a stable command id (quill.editor.save, quill.palette.open, quill.spell.checkDocument, etc.) and may have zero, one, or many keybindings.

8.1 Where keystrokes live

Three layers, in priority order:

1. User keymap (%APPDATA%\Quill\keymap.json). User edits win.
2. Profile keymap (optional, shipped alternatives). For example, “Word-like”, “Vim-friendly”, “Emacs-friendly”. The user picks one as the base.
3. Default keymap (built into Quill).

The effective keymap is the merge of these three, with user > profile > default.

8.2 Keyboard settings page

Ctrl+, then “Keyboard” (or palette =keyboard).

The page contains:

• A profile selector: System (defaults), Word-like, Vim-friendly, Emacs-friendly, Custom.
• A search field that filters the table below.
• A bindings table (wx.ListCtrl in report mode, fully accessible) with columns:
  • Command title
  • When (context: editor, palette, dialog, global)
  • Keybinding
  • Source (default, profile, user)
  • Conflicts (a short marker if any)
• Buttons: Add, Change, Remove, Reset to default, Reset all to profile, Import, Export.
• A “Press a key” capture field for visual users who want to find what a chord does today.

8.3 Editing a single binding

Three equivalent ways:

1. From the command palette: highlight a command and press Right Arrow.
2. From the Keyboard settings page: select the row and press Change (or Enter).
3. From the menu bar: every menu item has a context-menu entry “Change keybinding”.

In all three, the same small “Press the new shortcut” capture dialog appears. It:

• Captures any chord or two-key sequence (VS Code style, e.g. Ctrl+K Ctrl+S).
• Announces the captured keystroke as it is built.
• Refuses to capture purely modifier keys.
• Refuses to capture keystrokes reserved by the OS or by the active screen reader (NVDA, JAWS, Narrator) and explains which one it conflicts with.

8.4 Conflict handling

When a keystroke is already used:

• The dialog announces the conflict: “Ctrl+G is currently used by Go To Line in editor context.”
• Three choices, each on its own button: Replace (the old command becomes unbound and the new one is bound), Add (both commands have this binding; the active “when” context disambiguates), Cancel.
• “Add” is only offered when contexts are distinct. Same-context dual binding is not allowed for safety.

8.5 “When” contexts

Each command declares which contexts it is valid in:

• editor — focus is in the main editor.
• palette — focus is in the command palette.
• dialog — focus is in any Quill dialog.
• global — anywhere in the app.
• format:md — editor focus, current document is Markdown.
• format:pdf — editor focus, current document was extracted from PDF.
• selection — there is a non-empty selection.

Contexts can be combined with && in advanced editing.

8.6 Profiles in detail

• System: clean, modern Windows conventions (default).
• Word-like: brings Quill close to Microsoft Word for users migrating from there.
• Vim-friendly: a modal layer overlaid via plugin, off by default in the profile selector but available to install.
• Emacs-friendly: chord-heavy bindings (Ctrl+X Ctrl+S etc.), again via the chord engine.

8.7 Storage format

keymap.json is plain JSON, human readable, version controlled friendly:

{
  "version": 1,
  "profile": "System",
  "bindings": [
    { "command": "quill.editor.save", "key": "Ctrl+S", "when": "editor" },
    { "command": "quill.palette.open", "key": "Ctrl+Shift+P", "when": "global" },
    { "command": "quill.spell.checkDocument", "key": "F7", "when": "editor" },
    { "command": "quill.editor.gotoLine", "key": "Ctrl+G", "when": "editor && !format:pdf" }
  ]
}

8.8 Import, export, sync

• Export the active keymap to a single JSON file.
• Import from a file (with a preview dialog showing every change).
• Sync via a user-chosen folder (OneDrive, Dropbox, Syncthing). Quill watches the file and reloads on change, announcing “Keymap reloaded from disk.”

8.9 Safety net

• A “Reset all keybindings” button exists at the bottom of the Keyboard settings page.
• Recovery: if keymap.json is corrupt, Quill renames it to keymap.broken-<timestamp>.json and falls back to defaults, announcing what happened.

8.10 QUILL key chord dispatch

The QUILL key (Ctrl+Shift+Grave by default) operates as a two-layer prefix system managed by QuillKeyMixin in quill/ui/main_frame_quill_key.py.

Layer 1 — Prefix armed. The first press arms a short-lived prefix state (_quill_key_prefix_pending). The following keys are handled as hardcoded mode gates and are not reassignable:

• N — enter Quick Nav (browse) mode
• G — open Go to Anything
• QUILL key again — enter sticky browse mode
• A (with selection active) — open selection actions surface
• ? — show the prefix cheat sheet
• Esc — cancel without action

Layer 2 — Chord command dispatch. Any key pressed while the prefix is armed that is not a mode gate is dispatched via a data-driven lookup: _chord_command_for_event scans the live keymap for entries whose binding matches <prefix>, <second-key> and runs the matching command via _run_command. This means every chord command (read aloud, snippets, headings, copy tray, etc.) is fully reassignable in the Keymap Editor without any code change.

Key detection. The QUILL prefix key is recognized by three independent strategies so it works on any keyboard layout and Windows driver: 1. wxPython key code or Unicode key equals ord("“)orord(”~“)2. Windows virtual-keyVK_OEM_3(0xC0) viaGetRawKeyCode()3. Physical scan code0x29(key below Esc / above Tab on PC keyboards) via bits 16–23 ofGetRawKeyFlags()`

Keymap Editor validation. Chord bindings (containing ,) are validated separately from simple bindings: the prefix part must be a known modifier+key combination and the second-key part must be a parseable single key or modifier+key.

8.11 The Ctrl+Alt+ policy (revised 0.7.0)

Quill’s long-standing policy was to forbid Ctrl+Alt+ bindings outright because NVDA, JAWS, and Windows Speech Recognition intercept most of those chords app-globally. The 0.7.0 release (EdSharp port) revises the policy to permit a Ctrl+Alt+ binding when one of two conditions holds:

1. The command id is in the _CTRL_ALT_DOCUMENTED allowlist in quill/tools/menu_lint.py. Each allowlist entry is paired with a screen-reader-binding justification in docs/keybinding-standard.md. The historical view.send_to_tray and view.toggle_tab_control entries predate the relaxation; the new heading entries (1..6) are documented because they override NVDA’s switch-to-synth-N.
2. The binding line in keymap.py ends with the inline comment # §edsharp-ok — <justification>. The per-binding escape hatch lets future one-off bindings enter the keymap without a code change in menu_lint.py.

The rename from _CTRL_ALT_ALLOWED to _CTRL_ALT_DOCUMENTED makes the narrower scope explicit: the allowlist is “documented exceptions,” not a free pass. The gate continues to reject every other Ctrl+Alt+ binding, and the regression test in tests/unit/tools/test_menu_lint.py (test_ctrl_alt_uncommented_still_fails) pins the contract.

The full audit lives in the new docs/keybinding-standard.md document. The new EdSharp-port chord pairs (heading 1..6, list 7/8, section-move Alt+Shift+Up/Down) are all documented there with their justification comments and the screen-reader bindings they override.

8.12 The list-toggle chord pair (revised 0.7.0)

Ctrl+Alt+7 and Ctrl+Alt+8 are the EdSharp-port toggle variants of the existing format.insert_bullet_list / format.insert_numbered_list commands. Each chord inspects the caret: if it is on a line that is already a list item, the markers are stripped and the line returns to plain text; otherwise a new list is inserted. This decision is encoded in the pure helper is_caret_inside_list so the toggle behaviour can be tested without spinning up a MainFrame. Plain-text documents announce the chord is unavailable; the action is skipped.

Numbered-list insertion is governed by a new list_auto_fill_numbers setting (SettingsGroup = “editing”, default off) and a per-document five-minute arming flag. The three OR together in should_auto_fill_numbers():

1. The active document surface is markdown (the default-experience rule — a user who explicitly authored a Markdown file wants filled markers).
2. The list_auto_fill_numbers setting is on.
3. The user just toggled a numbered list on the active document — the arming flag is set to time.monotonic() + 300 the first time the chord runs in the document and cleared on document close.

Outside of the three conditions, today’s behaviour of one marker on the first item is preserved, so the change is strictly opt-in. Ctrl+Alt+9 for link insertion is intentionally not added because Ctrl+K already covers that command.

8.13 The Section status bar cell (revised 0.7.0)

A new Section cell appears in the status bar and reads Section: Heading N (ordinal of total) whenever the caret is on a heading in a Markdown or HTML document. The cell is hidden by default so it does not push other useful cells out of the bar for writers who do not work at heading-level granularity; opt in via Preferences -> Status Bar and place the cell where it helps.

The cell dispatches on infer_markup_kind(document.path). Plain-text documents and carets on a non-heading line return an empty string. The cell inherits the same try / except RuntimeError dead-widget guard as the other live-editor cells (line_column, word_count, selection) so a queued caret event after Ctrl+F4 cannot crash the status-bar refresh when the underlying C++ TextCtrl has been deleted.

The HTML path reuses the existing fence-aware parse_heading_blocks and current_section_at from quill/core/markdown_sections.py; both already handle <hN>...</hN> headings in the same way they handle #-prefixed markdown headings.

8.14 QUILL Key branding and menu label clarity (0.7.0)

Two changes ship together so the QUILL key is recognizable on first encounter and so every menu item shows its keybinding.

Branding the chord. The QUILL key chord is presented to the user as QUILL Key + <key> everywhere the editor exposes it: menus, the About > Keyboard Reference page, the QUILL Key Help dialog, the cheat sheet, and the status-bar / announce messages that fire while a chord prefix is pending. The stored binding (Ctrl+Shift+Grave in DEFAULT_KEYMAP, keymap.json, the quill_key_binding setting, the legacy_rebindings comparison table, and any saved keymap/profile_*.json) is unchanged — only the display layer rewrites the prefix. quill.core.keymap_format.format_binding_for_display is the single source of truth; quill.branding.QUILL_KEY_LABEL = "QUILL Key" is the single constant. Test coverage: 18 cases in tests/unit/core/test_keymap_format.py. A second helper, format_quill_key_chord(prefix, second_key), composes a chord without inspecting a stored binding string so power-user status bar code can mention a chord without one in hand.

Binding/label gap detection. quill.tools._check_binding_label_consistency is the 4th menu_lint invariant. The check walks the AST of quill/ui/main_frame_menu.py and flags three regression classes:

1. _menu_label("", "command.with.binding") — empty title literal routed through the builder for a command that has a keybinding. This is the regression that motivated the gate: a blank title + a bound command produced a menu slot with no readable name.
2. <name>\t<binding> literal drift — hand-written labels (the wx stock items and the editor’s own Close &Other Documents\tCtrl+Shift+F4, Help on This &Control\tF1, &What Can I Do Here?\tShift+F1, Open User &Guide\tCtrl+F1) whose binding portion disagrees with the DEFAULT_KEYMAP entry or the wx stock binding.
3. Trailing-tab labels — labels that end with \t and no binding portion. The user would see a menu name with a trailing tab and no accelerator.

The runtime gap-check in MainFrame._menu_label (a one-shot logger.warning per affected item at first menu build) is the safety net for user-customization drift — a user who renames a label through the Customize dialog still gets a custom label; only the silent “blank menu slot” case is reported.

The check is wired into python -m quill.tools.menu_lint and exposed via 12 new test cases in tests/unit/tools/test_binding_label_consistency.py. The gate is part of CI; a regression anywhere in the binding/label chain now fails the build.

Single source of truth for product name. tools/generate_build_info.py, scripts/generate_update_feed.py, and scripts/build_windows_distribution.py import APP_DISPLAY_NAME and APP_ORGANIZATION from quill.branding so a rebrand touches one file. The TOML path still wins when build/version.toml provides a value (the installer and feed can be re-branded per release); the constant is the safety net for older checkouts and dev builds.

8.15 The Page status bar indicator (0.9.0 Beta 2, #872)

Every document shows a Page status bar cell, on by default (unlike most cells, which are opt-in), positioned right after the line/column position cell rather than first. For PDFs, it reports an exact page count and current page, derived from page boundaries preserved as form-feed characters at import (quill/io/pdf.py), reusing quill/core/navigation.py’s previously-dormant page_starts()/page_start_for_number(). For every other format (plain text, Markdown, DOCX), it reports an estimate derived from word count (page_estimate_words_per_page, default 300, clamped 150-600, Preferences > Navigation and QUILL Key) — this is explicitly not an exact science, and the cell’s text always says so: "Page ~N of ~M (estimated)". The tilde and the word “estimated” always appear together, never one without the other, so an estimate is never mistaken for a fact.

BRF/braille documents keep their own richer page system (the "braille" status cell); the generic "page" cell is suppressed whenever that one is active, so the two never compete for the same space.

Go To Page (Ctrl+Shift+G, also reachable by activating the Page cell) is track-aware the same way: an exact jump for form-feed-bearing documents via the existing page_start_for_number, an estimated jump (word-count-derived, via estimate_page_start_for_number) otherwise, with the prompt text stating which kind of jump is about to happen.

DOCX real page breaks are a known gap, not an oversight: DOCX import goes through Pandoc/MarkItDown text conversion (quill/io/structured.py:_read_docx), which does not preserve page-break positions, so DOCX stays on the estimate track pending a follow-up.

8.16 Speech Hub: Offline/Online split and Set as Default (0.9.0 Beta 2, #847)

The Speech Settings dialog splits into four tabs instead of two (quill/ui/speech_hub_dialog.py): Speech (Offline), Speech (Online), Dictation (Offline), Dictation (Online) — TAB_SPEECH_OFFLINE/TAB_SPEECH_ONLINE/TAB_DICTATION_OFFLINE/TAB_DICTATION_ONLINE. Before this, one flat “Dictation” tab mixed local engines (whisper.cpp, Faster Whisper, Vosk — install once, no ongoing cost) with any registered cloud provider (a Quillin-based transcription service — an API key, a per-use network cost) in a single radio list (build_engine_descriptors); a “Read Aloud” tab did the same for SAPI5/DECtalk/Piper/Kokoro/ eSpeak alongside ElevenLabs. Local and cloud are different enough resource models that mixing them read as confusing. Both VoiceBrowserDialog (Speech) and SpeechSetupDialog (Dictation) already took their engine/provider list as a caller-supplied parameter, so the split is achieved by constructing two instances of each with a filtered list rather than rewriting either dialog: VoiceBrowserDialog’s engine_options is partitioned into the five offline engines and the one (elevenlabs) online engine at the call site (MainFrame.open_speech_hub); SpeechSetupDialog gained an engine_scope: "all" | "offline" | "online" parameter that filters build_engine_descriptors()’s output. When no cloud dictation provider is registered — the common case, since those arrive only via a transcription Quillin — Dictation (Online) shows a plain explanatory message instead of attempting to build a dialog around an empty engine list (a wx.RadioBox cannot hold zero choices).

“Set as Default” is now explicit and reachable everywhere, not just an implicit side effect of closing the dialog. Read Aloud already applied the OK button’s current engine+voice selection as the default (VoiceBrowserResult(action="select", ...)); it now also has a dedicated Set as Default button and a right-click context menu on the voice list (_do_set_default/_show_voice_context_menu), so the choice can be made without closing the dialog. Dictation previously had no equivalent for the model (only the engine, via the engine radio switching settings.speech_provider as a side effect of any dispatched action) — a new speech_default_model_id setting, a Set as Default button, and a matching context menu (_on_set_default/_show_model_context_menu in SpeechSetupDialog) close that gap. SpeechCommandsMixin._default_model_id (the one function every dictation/transcription/ captions call site funnels through to pick a model) now prefers speech_default_model_id when it names a model that is actually installed, falling back to the catalog’s recommended model otherwise. The guided offline-speech picker (§ above) also writes both speech_provider and speech_default_model_id automatically after a successful install, so downloading an engine + model there is itself sufficient to make it the default — the explicit buttons are for changing that choice later without re-running the picker.

Fixed in the same pass: settings.speech_provider’s valid-value set had never included "vosk", silently resetting it to "" on load — harmless before Vosk was reachable from the guided picker, a real bug once it was.

8.17 Status bar: the Message cell suppresses exact duplicates (0.9.0 Beta 2)

The generic Message cell (_status_message, e.g. “Ready”, “Saved”) is the one status bar cell shown by default regardless of status_bar_order/status_bar_hidden — _statusbar_items() (quill/ui/main_frame_statusbar.py) force-inserts it, and falls back to it alone when every other cell is hidden. A user report surfaced a real gap in that always-on guarantee: Message can end up showing the exact same text as another currently-visible cell (observed with the Page cell), which reads as a confusing double-announcement rather than useful information. After the rest of _statusbar_items() resolves the visible list, it now computes Message’s own text (_statusbar_text_for_item("message")) and compares it against every other visible cell’s text; an exact match drops Message from the list for that refresh. any() short-circuits on the first match, so the (rare) no-match case is the only one that pays for computing every other visible cell’s text — and several cells already re-derive from the live document on every refresh (line/ column, page, word-count-family), so this is not a new class of cost, just one more consumer of it. The rule is general (any cell pair), not hard-coded to Page specifically.