docs: polish repo and app copy

Author: M3RCU3Y

QA.md

@@ -1,6 +1,6 @@
 # QA Checklist
 
-Use this for browser smoke checks after changes that touch UI, imports, reader modes, persistence, or app shell state.
+Use this after changes that touch UI, imports, reader modes, persistence, or app shell state.
 
 ## Automated First
 
@@ -33,20 +33,20 @@ Open `http://localhost:3000`.
 - PDF: import a text PDF and verify progress messaging reaches the reader.
 - PDF cancel: cancel a PDF import mid-process and confirm the app returns to idle without a generic error.
 - URL success: import a normal article URL and confirm the cleanup preview appears before loading.
-- URL blocked: import a challenge-heavy URL and confirm fallback actions appear (`Open Source Page`, `Paste from Clipboard`).
+- URL blocked: import a URL that hits a bot check or login wall and confirm fallback actions appear (`Open Source Page`, `Paste from Clipboard`).
 - Forum URL: verify RSVP does not surface giant URL-like tokens after cleanup.
 
 ## Persistence
 
 - Save a book, leave it, reopen it, and verify progress is restored.
 - Change reader mode and Bionic settings, reopen the book, and verify settings persist.
 - Change theme, refresh, and verify selected theme persists.
-- Edit imported text and confirm the library source badge does not silently downgrade to `Paste`.
+- Edit imported text and confirm the library source badge stays accurate.
 
 ## Notes, Bookmarks, And Session Recap
 
 - Add a bookmark and a note, close/reopen the panel, and verify local panel search/edit UI resets cleanly.
-- Finish a meaningful reading session and verify the session recap does not auto-open.
+- Read long enough to create a session recap, then verify the recap does not auto-open.
 - Confirm the manual session recap button appears only when the active book has recap data.
 
 ## Mobile Layout

README.md

@@ -1,6 +1,6 @@
 # Flow Reader
 
-Flow Reader is a local-first reading workspace for moving through long text with speed, focus, and control. It combines RSVP, Bionic Flow, document imports, themes, bookmarks, notes, and session summaries in a polished browser app.
+Flow Reader helps you read long articles, PDFs, notes, and saved text in the browser. It gives you RSVP, Bionic Flow, imports, themes, bookmarks, notes, and session recaps without sending your library anywhere.
 
 Everything is stored locally in your browser (no accounts, no sync).
 
@@ -10,9 +10,9 @@ https://m3rcu3y.github.io/Flow-Reader/
 
 ## Features
 
-- RSVP word-by-word reading with smart timing and comfort controls.
-- RSVP+ for context-enhanced reading on desktop and landscape layouts.
-- Bionic Flow for scrollable, focused reading with progress-aware navigation.
+- RSVP word-by-word reading with adjustable speed and pauses.
+- RSVP+ shows nearby words for more context on wider screens.
+- Bionic Flow gives you scrollable reading that keeps progress in sync.
 - PDF import with text extraction, password handling, cancellation, and OCR fallback for scanned pages.
 - DOCX, TXT, pasted text, and article URL import.
 - URL cleanup preview for removing page chrome, forum noise, references, and long raw links.
@@ -24,7 +24,7 @@ https://m3rcu3y.github.io/Flow-Reader/
 ## Project Map
 
 - App source lives in `src/`.
-- Future agents should start with `docs/CODEMAP.md` for the codebase tour.
+- Start with `docs/CODEMAP.md` for the codebase tour.
 - Development commands and environment notes live in `docs/DEVELOPMENT.md`.
 - Import behavior is documented in `docs/IMPORT_PIPELINE.md`.
 - Manual verification flows live in `QA.md`.

docs/CODEMAP.md

@@ -1,13 +1,13 @@
 # Flow Reader Codemap
 
-This is the high-signal map for future agents. Read this before changing behavior.
+Use this as the quick map before changing app behavior.
 
 ## Entry Points
 
-- `index.html` owns document metadata, font/CDN scripts, Tailwind runtime config, and the PDF.js worker bootstrap.
+- `index.html` sets document metadata, font/CDN scripts, Tailwind runtime config, and the PDF.js worker bootstrap.
 - `src/index.tsx` mounts React, installs the PWA service worker, imports global styles, and wraps the app in `ErrorBoundary`.
-- `src/App.tsx` is the main shell and state coordinator. It owns the active book, library list, reader mode, chrome visibility, session summaries, keyboard shortcuts, sprint timers, and most cross-component callbacks.
-- `src/styles.css` owns global CSS variables, scrollbar styling, idle backdrop animation classes, and motion reduction behavior.
+- `src/App.tsx` is the main shell and state coordinator. It handles the active book, library list, reader mode, chrome visibility, session summaries, keyboard shortcuts, sprint timers, and most cross-component callbacks.
+- `src/styles.css` contains global CSS variables, scrollbar styling, idle backdrop animation classes, and motion reduction behavior.
 
 ## Source Layout
 
@@ -29,7 +29,7 @@ This is the high-signal map for future agents. Read this before changing behavio
 
 ### Reading Modes
 
-- `src/hooks/useRSVP.ts` parses text into words and owns RSVP playback timing.
+- `src/hooks/useRSVP.ts` parses text into words and handles RSVP playback timing.
 - `src/components/RSVPReader.tsx` renders the focused single-word view.
 - `src/components/RSVPEnhancedReader.tsx` renders the context-enhanced RSVP view.
 - `src/components/BionicFlowReader.tsx` renders scrollable bionic reading and maps scroll position back to progress.
@@ -45,25 +45,25 @@ This is the high-signal map for future agents. Read this before changing behavio
 
 ### Notes, Bookmarks, And Sessions
 
-- `src/components/BookmarksPanel.tsx` owns the bookmarks/notes panel UI.
+- `src/components/BookmarksPanel.tsx` handles the bookmarks/notes panel UI.
 - `src/services/sessionSummary.ts` builds session summaries.
 - `src/App.tsx` decides when a session is meaningful, persists summaries, and exposes the manual session recap action.
 
 ### Themes And Brand
 
-- `src/services/themes.ts` owns preset/custom theme definitions and CSS variable application.
-- `src/components/ThemeSelector.tsx` owns the theme editor UI.
+- `src/services/themes.ts` contains preset/custom theme definitions and CSS variable application.
+- `src/components/ThemeSelector.tsx` handles the theme editor UI.
 - `src/components/IdleBackdrop.tsx` pairs with `src/styles.css` for the landing background.
 - `src/components/BrandMark.tsx`, `public/pwa-icon.svg`, and `public/pwa-maskable.svg` should stay visually aligned.
 
-## Current Pressure Points
+## Places To Be Careful
 
-- `src/App.tsx` is large and mixes app state, reading session lifecycle, global listeners, and layout chrome behavior. Safe future extractions: session lifecycle, reader chrome visibility, active-book mutations, and bionic hotspot behavior.
-- `src/components/TextInput.tsx` is large and mixes editor UI, import orchestration, URL preview, PDF password flow, and fullscreen editing. Safe future extractions: URL import hook, file import hook, password prompt, import progress UI, fullscreen editor.
-- Keep `pdfService.ts`, `urlImportService.ts`, `bookState.ts`, and `sessionSummary.ts` as examples for future service boundaries.
+- `src/App.tsx` is large and mixes app state, reading session lifecycle, global listeners, and layout chrome behavior. Good extraction targets: session lifecycle, reader chrome visibility, active-book mutations, and bionic hotspot behavior.
+- `src/components/TextInput.tsx` is large and mixes editor UI, import orchestration, URL preview, PDF password flow, and fullscreen editing. Good extraction targets: URL import hook, file import hook, password prompt, import progress UI, fullscreen editor.
+- Use `pdfService.ts`, `urlImportService.ts`, `bookState.ts`, and `sessionSummary.ts` as the service-boundary pattern for new import, persistence, or summary logic.
 
 ## Verification Pointers
 
 - Run `npm run check` for TypeScript plus Vitest.
-- Use `QA.md` for browser smoke flows after UI, import, persistence, or reader-mode changes.
+- Use `QA.md` for browser checks after UI, import, persistence, or reader-mode changes.
 - Avoid relying only on static checks when touching layout or reader state machines.

docs/DEVELOPMENT.md

@@ -36,7 +36,7 @@ npm run build
 
 ## Environment Notes
 
-- The app is local-first. Library entries, preferences, themes, and summaries are stored in browser localStorage.
+- Library entries, preferences, themes, and summaries are stored in browser localStorage.
 - PDF parsing depends on PDF.js loaded from CDN in `index.html`.
 - OCR fallback uses `tesseract.js`.
 - DOCX import uses `mammoth`.
@@ -46,6 +46,6 @@ npm run build
 ## Source Conventions
 
 - Keep app code under `src/`.
-- Prefer service modules for pure or side-effect-isolated logic.
+- Prefer service modules for pure logic and browser-storage wrappers.
 - Prefer focused components/hooks over adding more responsibilities to `App.tsx` or `TextInput.tsx`.
 - Keep import and reading-mode changes covered by either Vitest or `QA.md` manual checks.

docs/IMPORT_PIPELINE.md

@@ -1,10 +1,10 @@
 # Import Pipeline
 
-Flow Reader supports paste, TXT, PDF, DOCX, and URL imports. The import surface is intentionally local-first: imported text becomes a `Book`, and source provenance is stored on `Book.settings.sourceMeta`.
+Flow Reader supports paste, TXT, PDF, DOCX, and URL imports. Imported text becomes a `Book`, and source details are stored on `Book.settings.sourceMeta`.
 
 ## Entry Surface
 
-`src/components/TextInput.tsx` owns the import UI:
+`src/components/TextInput.tsx` handles the import UI:
 
 - paste/manual text entry
 - TXT file reading
@@ -13,7 +13,7 @@ Flow Reader supports paste, TXT, PDF, DOCX, and URL imports. The import surface
 - URL import profile selection, cleanup preview, and blocked-page fallback
 - fullscreen editor
 
-This file is a good candidate for future hook/component extraction, but behavior should stay covered by the QA flows before and after any split.
+If this file gets split into hooks or smaller components, run the related QA flows before and after the change.
 
 ## PDF
 
@@ -47,9 +47,9 @@ The fixture-backed test is `src/services/urlImportService.test.ts`, using `src/s
 
 For the ESP32 forum fixture, the cleaner should:
 
-- keep core post content such as `I am trying to use multiple usb serial devices with ESP32-S3 host.`
-- keep readable context such as `I followed this reference, and also checked the example.`
-- remove forum chrome such as `ESP32 Forum`, `Board index`, `Quick links`, `FAQ`, `Login`, and `Register`
+- keep the main post content, including `I am trying to use multiple usb serial devices with ESP32-S3 host.`
+- keep useful context, including `I followed this reference, and also checked the example.`
+- remove forum chrome like `ESP32 Forum`, `Board index`, `Quick links`, `FAQ`, `Login`, and `Register`
 - remove reference definitions like `[1]: https://...`
 - avoid giant URL-like RSVP tokens
 

index.html

@@ -13,7 +13,6 @@
     <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
     <link href="https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600&family=Merriweather:wght@300;400;700;900&family=Playfair+Display:wght@400;600;700&display=swap" rel="stylesheet">
 
-    <!-- Tailwind CSS -->
     <script src="https://cdn.tailwindcss.com"></script>
     <script>
       tailwind.config = {
@@ -42,7 +41,6 @@
     <!-- PDF.js for parsing PDFs -->
     <script src="https://cdnjs.cloudflare.com/ajax/libs/pdf.js/3.11.174/pdf.min.js"></script>
     <script>
-      // Initialize PDF.js worker
       if (window.pdfjsLib) {
         window.pdfjsLib.GlobalWorkerOptions.workerSrc = 'https://cdnjs.cloudflare.com/ajax/libs/pdf.js/3.11.174/pdf.worker.min.js';
       }

src/App.tsx

@@ -114,7 +114,6 @@ export default function App() {
   const bionicHintFadeRef = useRef<number | null>(null);
   const bionicHintHideRef = useRef<number | null>(null);
 
-  // Initialize library
   useEffect(() => {
     setLibrary(getLibrary());
   }, []);
@@ -214,7 +213,6 @@ export default function App() {
     saveBook(newBook);
     setLibrary(getLibrary());
     setActiveBook(newBook);
-    // Enter Focus Mode
     setIsSidebarOpen(false);
   };
 
@@ -246,7 +244,6 @@ export default function App() {
     }
     setActiveBook(nextBook);
     setResumePromptBook(null);
-    // Enter Focus Mode
     setIsSidebarOpen(false);
   };
 
@@ -266,7 +263,6 @@ export default function App() {
       setLibrary(getLibrary());
     }
     setActiveBook(null);
-    // Return to Dashboard View
     setIsSidebarOpen(true);
   };
 
@@ -439,10 +435,8 @@ export default function App() {
     return slice ? `“${slice}…”` : '';
   };
 
-  // Toggle Sidebar manually
   const toggleSidebar = () => setIsSidebarOpen(!isSidebarOpen);
 
-  // RSVP Hook
   const rsvp = useRSVP({
     initialText: activeBook?.text,
     initialIndex: activeBook?.progressIndex,
@@ -1456,7 +1450,6 @@ export default function App() {
         </div>
       </aside>
 
-      {/* 2. RIGHT MAIN STAGE */}
       <main className="flex-1 h-full min-h-0 relative flex flex-col bg-app-bg">
 
         {/* Top Floating Toggle (Visible when sidebar is closed) */}
@@ -1591,8 +1584,8 @@ export default function App() {
 	                       type="button"
 	                       onClick={() => setIsSessionRecapOpen(true)}
 	                       className="h-9 px-3 flex items-center justify-center gap-2 rounded-lg bg-black/30 border border-text-primary/5 text-text-secondary hover:text-text-primary hover:border-text-primary/20 transition-colors text-xs font-semibold uppercase tracking-widest"
-	                       aria-label="Session review"
-	                       title="Session review"
+	                       aria-label="Session recap"
+	                       title="Session recap"
 	                     >
                          <ChartColumn className="w-3.5 h-3.5" />
                          <span className="hidden sm:inline">Session</span>

src/components/ControlCenter.tsx

@@ -66,7 +66,6 @@ export const ControlCenter: React.FC<ControlCenterProps> = ({
 	    return () => window.clearInterval(t);
 	  }, [sprintEndsAt]);
 
-	  // Calculate remaining time
 	  const currentWordNumber = total > 0 ? Math.min(progress + 1, total) : 0;
 	  const wordsLeft = Math.max(0, total - progress);
 	  const minutesLeft = Math.ceil(wordsLeft / wpm);
@@ -173,7 +172,7 @@ export const ControlCenter: React.FC<ControlCenterProps> = ({
 	                  onClick={() => {
 	                    const next = !comfortModeEnabled;
 	                    onComfortModeChange?.(next);
-	                    if (next) showToast('Comfort mode on: ramps up smoothly and eases after rewinds.');
+	                    if (next) showToast('Comfort mode on: starts gently and slows down after rewinds.');
 	                  }}
 	                  className={`inline-flex items-center gap-2 px-3 py-2 rounded-full border transition-colors cursor-pointer select-none focus-visible:outline-none focus-visible:border-accent-red/60 focus-visible:shadow-glow ${
 	                    comfortModeEnabled

src/components/ErrorBoundary.tsx

@@ -17,7 +17,7 @@ export class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundarySt
   }
 
   componentDidCatch(error: Error, errorInfo: React.ErrorInfo) {
-    // Keep a breadcrumb in the console for debugging; UI stays user-friendly.
+    // Keep crash details in the console for debugging.
     console.error('Flow Reader crashed:', error, errorInfo);
     this.setState({ error, errorInfo });
   }
@@ -47,7 +47,7 @@ export class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundarySt
             </button>
           </div>
 
-          {/* Keep details available for devs without overwhelming normal users. */}
+          {/* Expose stack details behind a collapsed disclosure. */}
           <details className="mt-5 text-xs text-text-secondary/80">
             <summary className="cursor-pointer select-none">Error details</summary>
             <pre className="mt-2 whitespace-pre-wrap break-words bg-black/20 border border-text-primary/10 rounded-lg p-3">

src/components/HelpOverlay.tsx

@@ -108,7 +108,7 @@ export const HelpOverlay: React.FC<HelpOverlayProps> = ({
           <section className="rounded-xl border border-text-primary/10 bg-black/15 p-4 sm:p-5">
             <div className="flex items-center gap-2 text-sm font-bold text-text-primary">
               <MousePointer2 className="w-4 h-4 text-text-secondary" />
-              Bionic Mode (Zen UI)
+              Bionic mode controls
             </div>
             <p className="mt-2 text-sm text-text-secondary">
               In Bionic mode, the UI stays hidden by default. Reach for it when you need it: