# Errata Submission User Flow Source-of-truth specification of the `errata-submission` user flow for `agentic-spec.com`. The flow lets a reader report an error in the book; submission is delegated to the user's default email client rather than transmitted by the site itself. ## Flow ### 1. Reader visits the `errata-submission` web page A single, named page is the entry point for every errata report. The book's back-matter and any "report an error" prompt elsewhere point at this one URL. **Rationale.** A single named entry keeps the surface the book has to expose stable and small — one URL the print and digital editions can reference for the life of the title. It also lets all errata-related behavior (navigation, form, submission) live in one place rather than spread across per-chapter pages. ### 2. The page displays the book's table of contents as an always-visible, fully expanded tree The tree exposes three nested levels — **top-level entry**, **sub-entry**, and **sub-sub-entry** — sourced from `specs/book-toc.md` (the source-of-truth for the book's TOC data). Every node is rendered expanded; the tree has no collapse / expand affordance and no expand / collapse controls of any kind. Top-level, sub-entry, and sub-sub-entry nodes are rendered as clickable links — not radio buttons, checkboxes, or any other selectable control — and the tree itself carries no persistent selected state. The user can browse the tree at any time. The tree is the primary content of the page and remains visible throughout the flow. A top-level entry, sub-entry, or sub-sub-entry is clickable on its own, whether or not it has children. Manuscript headings deeper than sub-sub-entry are intentionally not exposed as clickable nodes; an erratum that falls inside such a deeper heading is reported against the enclosing sub-sub-entry. **Rationale — TOC, not a per-chapter button.** A per-chapter "report errata in this chapter" button would mean every chapter (and every back-matter listing of chapters) carries its own errata link, multiplying the surfaces the book has to expose and keep in sync as the book is reprinted or revised. A single TOC-driven entry point keeps that responsibility on the site: the book points to one URL, and the site owns navigation to a specific location. The TOC also helps readers who recognize an error but are not sure which top-level entry, sub-entry, or sub-sub-entry it belongs to — they can browse the structure of the book rather than guess from a list of buttons. **Rationale — fully expanded, no collapse.** Collapse / expand controls add interaction the reader has to perform before they can find the node they want, and create state (which nodes are open) the reader has to manage. Fully expanding the tree at all times trades vertical length for a single browse-and-click action: the entire structure is scrollable, every node is one click away, and there is no "I clicked the wrong arrow" failure mode. ### 3. Reader clicks the entry where the erratum is Clicking a node in the tree opens the submission modal (Step 4) with that node as the modal's location context. The clicked node becomes the location of the report. The user can click whichever level fits the erratum — a top-level point clicks the top-level entry (e.g., something wrong with Front Matter as a whole), a chapter-level point clicks the chapter (which is itself a top-level entry under the new structure), a finer point clicks a sub-entry or sub-sub-entry. **Rationale.** Forcing the user to identify the location before writing the report (a) gives every report a structurally consistent location field rather than free-text wording like "in chapter X around the part about Y", (b) lets the site key the form's pre-composed email to a canonical location, and (c) makes the location explicit and visible inside the modal. The user self-corrects a wrong location by cancelling the modal (via the X or the Esc key) and clicking a different node in the tree; the cancel discards any draft text the user has typed, so a mid-typing change of mind costs the in-progress draft. The trade-off is accepted in exchange for the modal's stateless behavior (Step 4). ### 4. The submission modal appears with the clicked location displayed The clicked node opens a modal dialog containing the entire submission form. The location of the report — the entry that was clicked (top-level entry, sub-entry, or sub-sub-entry) — is shown at the top of the modal for confirmation, and it is not editable from the modal itself. To change the location, the user dismisses the modal and clicks a different node in the tree (Step 3); there is no in-modal way to re-select. The form has two fields: - **Explanation of the error** — required, multi-line text. Accepts up to 5,000 characters, with a visible character counter near the field. Longer inputs are truncated client-side. - **Proposed correction** — optional, multi-line text. The modal is dismissed in three ways: clicking Submit (which advances to Step 5), clicking the X in the upper-right corner of the modal, or pressing the Esc key. The X and the Esc key both cancel the submission and discard any draft text the user has typed; reopening the same node afterwards opens an empty modal. **Rationale — location not editable from the modal.** The tree click is the single way the location is established. Allowing edits inside the modal would create two independent location-entry paths (tree click and modal text field) that could disagree, and would invite free-text locations ("see the footnote near figure 3") that the canonical tree click is meant to avoid. The roundtrip back to the tree is cheap — close the modal, click another node — even though it now costs the draft text (per Step 3's rationale). **Rationale — explanation required, proposed correction optional.** The explanation answers the only question the report has to answer: what is wrong. Without it the report has no content. The proposed correction is helpful when the user is confident enough to suggest one, but many valid reports come from readers who can identify a problem without knowing how to repair it — a missing definition, a contradictory claim, a broken cross-reference. Making the correction required would suppress those reports. **Rationale — draft discarded on cancel.** Persisting per-node drafts across modal sessions would require keeping reader-typed text in client-side storage and would create an expectation that draft state survives navigation, page reload, or tab close — guarantees the site is not designed to make. The cancel-clears-draft behavior keeps the modal stateless: each open is a fresh report, and the only persistence is the email the user's own client receives at Step 5. ### 5. Reader clicks Submit Submit assembles the email and invokes the `mailto:` handoff in one step; the modal closes once the handoff has been issued. The assembled message has the following shape: - **To.** `errata@agentic-spec.com` - **Subject.** `Erratum: ` — where `` is the `/`-joined ancestor labels of the clicked node, from the top-level entry down to the clicked node itself. Examples: `Erratum: Afterword` (clicked the Afterword top-level entry), `Erratum: Chapter 1: Prerequisites / Domain Expertise` (clicked a sub-entry under a chapter), `Erratum: Front Matter / Why This Book? / Why Now` (clicked a sub-sub-entry). The path contains one segment when the clicked node is a top-level entry, two segments when it is a sub-entry, and three when it is a sub-sub-entry. - **Body.** Well-structured plain text containing the location (the same `/`-joined path used in the subject), the explanation, and — if the user provided one — the proposed correction. Labels appear on their own lines so the email is readable in any mail client. The user's default email client opens a compose window pre-filled with that content. The site has no further role: it does not see the message and does not retain the submission. The site MUST NOT transmit the message or any of its contents over the network. The `mailto:` handoff is the entire submission mechanism. **Rationale — delegated to the user's email client, not POST-ed to a server.** A server endpoint would mean the site has to (a) accept and store reader input, (b) defend that endpoint against spam, abuse, and attempts to plant PII or harmful content in a public-facing system, (c) operate a mail-sending pipeline with deliverability, retries, and bounce handling, and (d) carry a data-retention surface (errata reports as user-submitted content). Routing through the user's own email client produces the same outcome — a structured email arrives at the errata mailbox — while leaving sending, sender identity, and any retained record entirely on the user's side. The site itself remains a static page with no input-handling responsibilities. **Rationale — no on-site preview before mailto.** The site does not preview or otherwise display the assembled email to the user before invoking `mailto:`. The user reviews and edits the message inside their own email client, which is where the final Send action also lives. This design accepts a dependency on email-client behavior — some clients open a minimal compose window, some hide the body until the user interacts with the message, and inline editing of pre-composed messages varies by platform — in exchange for keeping the site free of an in-page preview surface and keeping the submission a single Submit click rather than a Submit-then-Confirm sequence.