45: GLOW - Audit and Fix - transcript
Jessica: The QUILL Cast, episode forty-five. I'm Jessica. Today is the first stop on the final part of a fifty-four-episode course, the part we are calling production and trust. The whole arc from here to the finale is about what leaves your hands: the documents you send, the documents you publish, the documents you sign with your name. And the first tool we are going to meet is the one that decides whether a document you wrote for sighted readers will actually work for everyone else. Its name is GLOW, and we will spend the whole episode on it.
Liam: I'm Liam. GLOW stands for Guided Layout and Output Workflow, and the framing in the documentation is exactly the framing we want you to hold in your head. This is not a compliance dashboard. This is not a regulator's report card. This is guided confidence, a second reader who speaks your language. Before we go further, a quick recap of where we have been, because this course lives or dies on its memory.
Jessica: Episode forty-four was the integration episode. It wired three big systems together: Story Studio from episode forty-two, the Accessible Vault from episodes forty and forty-one, and the AIs from episodes thirty-four through thirty-nine. The thesis was simple. Story Studio owns the manuscript, the binder, the character details, and the compile. The Vault owns the worldbuilding web, the wikilinks, the backlinks, the tags, the templates, the daily notes, the embeds, and the site export. The AIs own the conversation model: branchable, resumable sessions that can read both and write back into both. The three systems are integrated at the format level, not at the menu level. Story Studio element files and Vault notes are the same shape on disk. Move a file from one world to the other, and it is still readable.
Liam: And there were two honest corrections in forty-four that you should know we are still standing behind. The first: the brief pointed at a singular session file, but the file is plural, sessions dot py, in quill core ai. The second: the continuity pass, where the agent reads the binder, the vault, and the link index, and writes a report, is a composition of pieces, not a single registered command. You can do it today with the parts you have, but you are not clicking a button to do it. Today takes that same posture and asks, what is the equivalent composition for accessibility, and is the answer a deterministic tool, an agent, or both? The answer is both, and today is the deterministic half. Tomorrow is the structured file half. Episode forty-seven is the agent half. We will earn the agent when we get there.
Jessica: Today's plan. First, a "where the code is" pass, because this course has earned its reputation for honesty and the only way to keep that reputation is to read the actual files. Second, a do-this-now beat, before any hands-on segment, so you can do the work in your own time and come back. Third, we walk the four in-editor GLOW commands, audit current document, audit selection, fix current document, fix selection, with the actual line numbers and the actual code. Fourth, we look at what GLOW does and does not check, because the rule set is smaller than you might hope and the gaps are honest. Fifth, a four-step homework, a setup for episode forty-six, and both of us sign off.
Liam: Five major beats, plus the closing, and a tight one for each. Same posture as forty-three and forty-four. Verify every claim against the code. If a previous version of the script, or any doc, drifts from the code, we name the drift. The code wins. That has been the rule for forty-four episodes, and it will hold for the last ten.
Jessica: The "where the code is" pass, with two small corrections to the previous short version of this episode that we are going to call out honestly. The GLOW in-editor commands live in main frame dot py, in the MainFrame class, not in their own mixin. The mixin exists, but it is for the file-level half: glow audit file and glow fix file, in quill ui main frame glow dot py, GlowFileMixin. Today's episode is the in-editor half, so the file we are reading is quill slash ui slash main frame dot py, and the symbols are glow audit document, glow audit selection, glow fix document, glow fix selection, plus three helpers: glow scope, ensure glow enabled, and make document accessible, which is the AI agent we will meet in a moment. The analysis itself, the regex set, the rule set, the report renderer, lives in quill slash core slash glow dot py.
Liam: First correction to the previous short version. The previous version said "Audit Selection reviews just the block at your caret." That is half right and half wrong, and the code is the source of truth. The actual method is glow scope, and it returns four things: the text, the start offset, the end offset, and a scope label. The logic is this. If you have a selection, that is the scope and the label is the word selection. If you do not have a selection, the code grabs the current paragraph, the block of text between blank lines, and the label is current paragraph. If that paragraph is empty, the code falls back to the current line, and the label is current line. So the menu label, "GLOW Audit Selection / Paragraph", is honest: with a selection you audit the selection, without one you audit the current paragraph, and the report tab title reflects the actual scope. The previous version under-reported what the command does. We will over-report it, because over-reporting in this case is what honesty looks like.
Jessica: Second correction to the previous short version. The previous version said "Findings that GLOW can repair itself are marked auto-fix." That is true, but vague, and the vagueness hides an important truth. The auto-fixable rules, the ones whose fixable flag is true, are exactly three. Markdown heading spacing, the rule id is GLOW-MD-HEADING-SPACING, inserts a space after the hash marks. HTML language attribute, the rule id is GLOW-HTML-LANG, adds lang equals quote en quote to the html element. And HTML image alt text, the rule id is GLOW-HTML-IMG-ALT, adds an empty alt attribute to img elements that lack one. Everything else, the heading jumps, the click-here link text, the missing alt on Markdown images, the table without header cells, the dense paragraph, the bureaucratic phrasing, every other rule, is informational. It is surfaced, named, and given a suggestion. It is not auto-fixed. The previous version gave the impression that GLOW would silently rewrite the document. The code does not do that. The code only auto-fixes the three mechanical rules, and it does so through a review-first compare, which is the part of the story we are about to walk.
Liam: Now the do-this-now beat, the one that has to come before the hands-on walkthrough, because the walkthrough will land much harder if you have done the setup. Pause the audio. Open QUILL. Create a new file, or open any existing Markdown or HTML file you are willing to mess with. Now make the document a little messy on purpose. Add a Markdown heading with no space after the hashes, like three hashes stuck to a word. Add a link with the words click here, the kind of link you were told to stop writing in episode fourteen but probably still write. Add a paragraph longer than six hundred characters, the kind of paragraph a tired Tuesday night produces. Save the file. Pause the audio, do the steps, then come back. We are going to audit this exact document in a moment.
Jessica: Welcome back. If you did the steps, you have a four-finding document before you even opened GLOW. The heading without a space, the click-here link, the dense paragraph, and probably a fourth finding you did not intend: a Markdown heading jump, the kind that scrambles a screen reader's mental model. We will audit this exact document in a moment, and we will name the findings, and we will use the verify-against-the-code discipline to confirm what the audit says versus what we expect. Resume the audio when you have the document open and your cursor parked somewhere in it.
Liam: Now the four in-editor commands, walked against the code. The first two are audits, which only read. The second two are fixes, which can change your document but only through a review-first contract. Each handler starts with a call to ensure glow enabled, which is a small guard that returns True if both the experimental master switch and the GLOW checkbox are on, and returns False otherwise. When the function returns False, the handler shows a message box that tells you exactly where to go in preferences and exactly which boxes to tick. The message is verbatim: "GLOW is an experimental feature and is currently turned off. To enable it, open Preferences, Experimental, tick Enable experimental features, then tick GLOW accessibility review and repair. It takes effect as soon as you apply Settings, no restart needed." The dialog title is "GLOW (Experimental)". If GLOW is off, the command refuses and explains. If GLOW is on, the work begins.
Jessica: Audit Current Document, the simplest of the four. The handler calls ensure glow enabled, calls current markup context, which is a small helper that returns markdown, html, or plain based on the file extension or the pinned markup, then calls the core function build audit report with the document name, the entire editor buffer, the markup kind, and the scope label "current document." The core function calls audit text, which dispatches to audit markdown, audit html, or audit plain, then layers in audit common for plain language and dense paragraphs, then sorts the findings by line then column then rule id. The report is built into a plain text block and opened as a named scratch tab. The tab title is "GLOW Audit - document name." Status line updates. The buffer is untouched.
Liam: Audit Selection is the same call, but with a smaller scope. The handler calls ensure glow enabled, calls glow scope to get the selection or the current paragraph, calls current markup context, and calls build audit report with the same four arguments, just with the smaller text and a different scope label. The tab title is "GLOW Audit - Selection", "GLOW Audit - Current Paragraph", or "GLOW Audit - Current Line", depending on what glow scope returned. Three scope labels, three possible tab titles, all driven by the same audit function. The audit is deterministic, so running it on the same scope twice yields the same report. The audit is also fast, because it is pure regex and a plain language dictionary lookup, no model, no network, no IO. The same data the audit reads is the data the fix reads, which is part of why the fix is so trustworthy.
Jessica: Fix Selection is the first of the two write paths, and it is the gentler one. The handler calls ensure glow enabled, calls glow scope, calls current markup context, calls the core function fix text with the scoped text and the markup kind, and inspects the result. The core fix function is a small, deliberate set of transformations. It trims trailing whitespace, which is a universal GLOW fix. If the markup is markdown, it inserts the missing space after heading hash marks. If the markup is html, it adds a lang attribute to the html element and an empty alt attribute to any img element that lacks one. For plain text, only the trailing whitespace fix runs. That is the entire fix surface, and that is the entire fix surface for a reason. If the result text equals the input text, the handler updates the status line to "No deterministic GLOW fixes were available for selection" and returns without touching the editor.
Liam: If the result text differs, the handler replaces the editor range with the fixed text, sets the selection to the replaced range, marks the document as modified, builds a fix report, records a notification whose first line is the report headline, and updates the status line. There is no compare session, because the change is in place and the user is staring at the same buffer. The compare session belongs to the bigger fix, the one that is deliberately ceremonial.
Jessica: Fix Current Document is the ceremonial one, and this is the part of the story that the rest of QUILL's safety discipline earned. The handler calls ensure glow enabled, grabs the entire editor buffer, calls current markup context, calls fix text, and compares. If nothing changed, the handler builds a fix report, opens it as a named scratch tab, updates the status to "No deterministic GLOW fixes were available," and returns. If something did change, the handler does three deliberate things. First, it creates a new tab whose document is the fixed text, marks the tab page with the title "document name - GLOW Fix Preview", and selects that tab. Second, it builds the fix report and records the notification. Third, it calls start compare session with a list of two source documents, the original and the preview, and the compare session announces the first difference, plays the compare-enter sound, and waits for you to walk through with F8, Shift+F8, and Control-F8, exactly the keys episode eleven taught you. That is the contract. The repaired text is never silently swapped into the original. It is opened next to the original, the diff is announced, and you decide what to do with the original. Propose, then dispose. Always.
Liam: The compare session is not a flourish. It is the structural proof that QUILL does not silently rewrite your work. The same compare session, the same F8 navigation, the same screen-reader-friendly difference annunciator, the one that named the post-fix audit in tomorrow's episode, is the one that names the in-editor fix today. The buffer you typed remains untouched. The buffer GLOW produced sits beside it. The differences are walked, line by line, by you, with the keyboard, by ear, in your own time. If you do not like the rewrite, you close the preview tab, no harm done, your original is the one still selected. If you do like it, you copy the changed regions across, or you adopt the preview as the working buffer, or you keep both, the choice is yours. The contract is the same as the AI rewrite contract from episode twenty-five and the smart clip contract from episode fifteen. Tools propose, the human disposes. That is the house philosophy, and GLOW is one of the cleanest expressions of it.
Jessica: What GLOW actually checks, walked rule by rule, because the rule set is smaller than you might hope and the gaps are honest. The plain text branch catches one thing: a tab character. The rule id is GLOW-TAB-INDENT, the severity is warning, the suggestion is to replace tabs with spaces before sharing or exporting. The Markdown branch catches four things. GLOW-MD-HEADING-SPACING, the missing space after hash marks, fixable. GLOW-MD-HEADING-JUMP, a heading level that jumps by more than one from the previous heading, not fixable. GLOW-MD-IMAGE-ALT, an image whose alt text is empty, severity is error, not fixable. GLOW-MD-LINK-TEXT, a link whose visible text is one of the generic phrases: click here, here, read more, more, link, this, not fixable. The HTML branch catches five things. GLOW-HTML-LANG, the missing lang attribute, fixable. GLOW-HTML-HEADING-JUMP, the same jump rule as Markdown, not fixable. GLOW-HTML-IMG-ALT, the missing alt attribute, fixable but with an empty alt, which is the right choice for decorative images and the wrong choice for informative ones, so the author still has to make a judgment call. GLOW-HTML-LINK-TEXT, the same generic link text rule. GLOW-HTML-TABLE-HEADERS, a table that contains no th elements, not fixable. That is the markup-aware half.
Liam: The common half, the one that runs for every markup, catches two more things. GLOW-PLAIN-LANGUAGE, which delegates to a function in quill core plain language dot py, lint plain language, and surfaces bureaucratic phrases with a suggested replacement. GLOW-DENSE-PARAGRAPH, which is triggered by any paragraph longer than six hundred characters and asks the author to split it. Both of these are informational. They are surfaced, named, and given a suggestion, but GLOW does not rewrite the prose for you, because rewriting prose is not a deterministic operation. The author still owns the words. The total rule set is eleven. Three of those are auto-fixable. The other eight are advisory. That is the entire GLOW rule engine for in-editor content, and we want you to know the exact size of it, because knowing what GLOW does not catch is just as important as knowing what it does.
Jessica: A small honesty note about the rule set, because this course has been honest since episode two. The rule set is small, deliberately small, and it is the small set QUILL is willing to vouch for. There is no color-contrast check, because color is visual and the audit is meant to be useful by ear. There is no reading-level score, because the plain language check is a phrase dictionary, not a Flesch-Kincaid computation. There is no full WCAG sweep, because the WCAG sweep is a structured-document thing and the in-editor audit is a buffer thing. The in-editor GLOW is the deterministic floor: a small, vetted set of rules that catch the most common, most embarrassing, most fixable mistakes a writer can make when they are typing. The structured-document GLOW in episode forty-six is the ceiling, the deeper analysis on the file you are about to send. And the Accessibility Tune-Up agent from episode twenty-eight, which is the AI half, is the ambitious third layer, the one that reads the document the way a human editor would and proposes a fuller pass. Floor, ceiling, third layer, all in the same review-first family. The agent is for a moment when you are ready to be ambitious. The deterministic audit is for every other moment.
Liam: The rule IDs are also worth naming, because they appear in the audit report and they are the keys you would search for if you wanted to filter the findings list. GLOW-MD-HEADING-SPACING, GLOW-MD-HEADING-JUMP, GLOW-MD-IMAGE-ALT, GLOW-MD-LINK-TEXT. GLOW-HTML-LANG, GLOW-HTML-HEADING-JUMP, GLOW-HTML-IMG-ALT, GLOW-HTML-LINK-TEXT, GLOW-HTML-TABLE-HEADERS. GLOW-TAB-INDENT for plain text. GLOW-PLAIN-LANGUAGE and GLOW-DENSE-PARAGRAPH for the common sweep. Each finding in the report is rendered with the severity in caps, the rule id, the line and column when the rule could place them, the message, and the suggestion. A finding that is auto-fixable gets a literal "auto-fix" suffix in the header. The report is plain text, it opens in a tab, and because it is a tab, you can arrow through it, search it with the find bar from episode eleven, and keep it beside your draft. The same data, in the same shape, every time.
Jessica: The severity vocabulary, also small and deliberate. Three levels: error, warning, info. The lang attribute is missing, that is an error, because a screen reader will mispronounce the entire document without it. The image alt text is missing, that is an error. The heading jumps, the link text, the tab indent, the dense paragraph, those are warnings. The plain language phrase, that is info. Three levels, mapped from the engine, but the report reads them as the words error, warning, info, in capital letters, with the rule id right after. The screen reader announces them as a triplet, severity, rule, message, which is the right order for an ear that has to decide which finding to act on first. Errors first, warnings next, info last, by design, by discipline, by the same trust-the-user posture the rest of QUILL holds.
Liam: The other thing worth naming, because the previous short version touched it and the long version should nail it, is the relationship between GLOW and the AI Accessibility Tune-Up. GLOW is the deterministic floor. The agent is the ambitious ceiling. The two are not redundant. The agent, in quill core accessibility agent dot py, runs a plan, generate, optionally refine loop, returns an agent result with applied changes, findings before, findings after, and a report, and is invoked from a dialog called AccessibilityAgentDialog that is opened by the main frame method make document accessible. The dialog is the user-facing surface. The agent reads the document, plans a pass, shows the plan, asks the user to apply, applies, then runs GLOW again on the result and reports the new findings count. GLOW is the verification step of the agent, and the agent is the higher-effort path that uses GLOW as its floor. The same review-first contract. The same compare-first output. The same "tools propose, the human disposes" posture. We will walk that path in detail in a later episode, but the integration is the right place to be in your head right now.
Jessica: One last honest correction before we close the technical walk, this one about the location of the audit selection "selection" label. The previous short version of this episode said the menu item was "GLOW Audit Selection." The actual menu label, in the live menu builder, is "GLOW Audit Selection / Paragraph." Same for the fix command, which is labeled "GLOW Fix Selection / Paragraph." The slash in the label is the in-code acknowledgement that the command does two different things: audit what is selected, or audit the current paragraph if nothing is selected. The label is more honest than the short version, and the report tab title is the place where the actual scope is named in full. If you ever read a doc that quotes the short label, the menu says otherwise. The menu wins.
Liam: And the same honesty about the role reversal. Most accessibility software helps you consume inaccessible things. GLOW helps you produce accessible things. For a blind professional who has to send documents to sighted colleagues, the irony is that the problems of an inaccessible document are themselves invisible in a screen reader. A missing alt attribute sounds the same as a present one. A click-here link sounds the same as a meaningful one. A heading jump from H1 to H4 sounds like any other heading transition, until a screen reader user tries to navigate by heading and finds a wall. GLOW is the second reader who speaks your language, and the second reader names the things the first one cannot. That is the role reversal, and the role reversal is the point. The people most affected by inaccessible documents are the best equipped to never produce one. GLOW is the tool that makes that capability first-class.
Jessica: The integration into a writing routine, and the routine matters more than the tool. Our recommendation, drawn from the same philosophy as the spell pass in episode twelve: draft freely, audit at natural pauses, fix the judgment calls yourself, the click-here link, the missing alt on a meaningful image, the dense paragraph you can break in two with a heading, then let Fix Document handle the mechanical ones through the compare. Two minutes per document. Structural accessibility stops being a special project and becomes hygiene, the same way a spell pass is hygiene. The first few audits will be humbling, the way the first few spell passes are humbling. The audits after that are routine. The audits after that are muscle memory. The contract is the same on every pass: GLOW proposes, you dispose.
Liam: Homework. Four steps, all doable in a sitting. One: audit the messiest document you own, the one you have been avoiding, and just listen to the whole report. No fixing, no compare, just listen. Learn the findings vocabulary. Notice which rule ids recur for you. Notice which severities you are accumulating. Two: run Fix Current Document on a real document and actually read the compare. Walk the differences with F8. Notice which ones you would have caught yourself, which ones you would not have, and which ones are mechanical enough that you are happy to let GLOW do them. Three: fix one click-here link by hand, and notice you now know why it mattered. The link's destination, not the words click here, is the part a screen reader user hears when they pull up the list of links on a page. Click here is an empty list. A descriptive label is a real one. Four: open Preferences, Experimental, confirm the master switch and the GLOW checkbox are on, and run Tools, GLOW, Audit Selection with no selection, so the scope falls back to the current paragraph, and confirm the report tab title says "GLOW Audit - Current Paragraph." The contract is real, the code is the contract, and the code is right there in quill core glow dot py.
Jessica: Next episode, episode forty-six, takes GLOW beyond the editor. We look at the file picker path, the Tools, GLOW, Audit File and Fix File commands, the shared GLOW engine seam in quill core glow dot py, the structured-document engine that the editor version delegates to when the buffer becomes a file, the score and grade that come back from a structured audit, the no-silent-overwrite fix that writes an accessible copy next to the original, and the privacy posture that keeps the audit on the box by default. Same posture as today: review first, fix second, the human disposes. We are nine episodes from the finale after that, and they cover dictation, transcription, the audio studio, the listening companion, the AI library, agents, accessible vault basics, vault power, the Quillins and console, trust, community, and the finale. The series is fifty-four episodes in total. Forty-five down, nine to go.
Liam: I'm Liam.
Jessica: I'm Jessica. Build the accessible habit, and the documents will follow.
Liam: The QUILL Cast is a fifty-four-episode audio course on QUILL. This has been episode forty-five. Thanks for listening.