Upload 4 files

README.md

@@ -30,24 +30,32 @@ Shortcut buttons link the tools: *Humanize this text →* (Detector → Smart Hu
 
 ## Plans (plans.py)
 
-| Plan | Price | Documents | Paste | Smart passes |
+| Plan | Price | Documents (reports) | Paste | Smart passes |
 |---|---|---|---|---|
 | Guest | free | — | 300 words, 15 runs/day | 2 |
 | Free account | free | 2 (lifetime trial) | 300 words, 25 runs/day | 2 |
-| Student | $5.99 / ₹299 per month | 30 per 30 days | 2,000 words, 100/day | 4 |
-| Pro researcher | $14.99 / ₹799 per month | 150 per 30 days | 3,000 words, 300/day | 4 |
-| Agency | from $99 / ₹5,999 per month | 1,000 per 30 days | 3,000 words | 4 |
-| Single document | $2.99 / ₹149 | 1 credit (never expires) | — | — |
+| Student | ₹4,999 / $59 per month | 5 per day | 2,000 words, 100/day | 4 |
+| Agency | ₹7,999 / $95 per month | 10 per day | 3,000 words, 300/day | 4 |
+| Pro | ₹10,000 / $119 per month | unlimited | 5,000 words, unlimited | 4 |
 | **Admin** (`ADMIN_EMAILS`) | **free, unlimited, never charged** | ∞ | 20,000 words | 4 |
 
-Order used for a document: plan quota → purchased credits → free trial. Guests and free users see an
-upgrade tip after each run, a 💎 Upgrade button, and the 💎 Pricing tab. "Buy" buttons log an upgrade
-request (Admin → Users → Upgrade requests) and show UPI/bank instructions until online payment is live.
+Prices can be changed with the Space variables `PRICE_STUDENT`, `PRICE_AGENCY`, `PRICE_PRO` (₹) and
+`PRICE_STUDENT_USD`, `PRICE_AGENCY_USD`, `PRICE_PRO_USD` ($); `PRICE_CURRENCY` (INR / USD) sets which one the Pricing page shows first. Daily limits reset at
+midnight IST (`DAY_TZ_OFFSET_MIN`, default 330).
 
-**Activating a paid plan today:** Admin → Users → 💎 Plans & credits → Activate plan / Add credits.
+**Monthly subscriptions.** The users table keeps `plan_started` (subscribed since), `period_start` (current month
+from), `plan_until` (paid until: the same date next calendar month) and `plan_status` (active / expired / free).
+A plan that is not renewed by `plan_until` is switched off automatically (checked every hour and whenever the user
+signs in or runs a document): the user goes back to the free plan, gets an email, and the event is written to
+`plan_history`. Renewing before the end date adds a month to the end date; renewing after it starts a new
+subscription from that day. Admin → Users shows every subscription (start date, paid until, days left, status) and
+the full plan history.
+
+**Activating / renewing a plan today:** Admin → Users → 💎 Plans & credits → choose the plan and number of months →
+Activate plan. Document credits can still be added there for special cases.
 
 **Razorpay (next step):** in the payment webhook, after verifying the signature, call
-`plans.activate_plan(email, "student", 30, source="razorpay", amount=...)` or
+`plans.activate_plan(email, "student", 1, source="razorpay", amount=...)` (1 = months) or
 `plans.add_credits(email, 1, source="razorpay", amount=...)` — the same functions the admin buttons use.
 
 Optional variables: `PAY_WHATSAPP` (digits with country code), `PAY_EMAIL`, `PROMO_TEXT`, `FREE_TRIAL_DOCS` (default 2).
@@ -216,3 +224,35 @@ kept only if it changes at most 25% of a sentence's words (`HUM_GRAMMAR_MAX_EDIT
 number and citation. Smart Humanize runs it once on the final version and drops it if it raises the AI score by more
 than 3 points. `HUM_GRAMMAR=0` turns it off. Without a Groq key the step is skipped.
 
+## Report-guided rewriting (Smart Humanize) — image processing
+Upload an AI or similarity report PDF from any checker (Turnitin, iThenticate, GPTZero, ZeroGPT, Copyleaks, Academi,
+scanned reports too). `report_flags.py` renders every page to an image and, for every word, looks at the pixels in
+the word's box: a tinted background (cyan, purple, yellow ... even very pale tints) = highlighted; coloured letters =
+coloured text. Word positions come from the PDF text layer, or from Tesseract OCR for scanned pages (parallel).
+Flagged words are grouped into the report's sentences (cyan = High, purple = Moderate), matched to the document
+(word-trigram overlap >= 50%) and only those sentences are rewritten in one pass. The result shows the report's own
+score -> an estimated score, and a table of every flagged sentence with its rephrased version.
+Flagged sentences get the strongest rewrite: `restructure.py` reshapes them first (clause order, splits,
+stock openers; rule-based, no AI model), then Parrot with the 100% AI settings and a 60% new-wording target.
+Rows where less than half the wording changed are marked "Likely still flagged" for the writer to revise.
+Needs `tesseract-ocr` (packages.txt) and `pytesseract` (requirements.txt) for scanned reports.
+
+
+## Final polish (Groq)
+
+After all rewriting, the finished text goes through a final polish, paragraph by paragraph. Groq sees each
+paragraph together with the author's ORIGINAL paragraph. **Unclear or garbled sentences are repaired** to the
+original meaning (clarity wins over the AI score for these); a repair that adds facts or drifts in meaning is
+rejected and the clear original sentence is put back. Clear sentences get the light polish: grammar, technical
+academic wording (wrong-sense or informal words, redundancy) and flow between sentences (logical links, varied
+openings, smoother word order). Sentences are never merged, split, dropped or reordered, so the Word layout stays
+intact. A polished sentence is kept only if it keeps every term, number and citation, keeps its meaning (meaning
+check), changes at most `POLISH_MAX_EDIT` of its words and, with `POLISH_KEEP_HUMAN=1`, does not turn a sentence
+the detector reads as human into one it reads as AI-written; otherwise the grammar-only correction is used.
+LanguageTool then fixes any remaining mechanical errors.
+
+| Variable | Default | Effect |
+|---|---|---|
+| `POLISH` | `1` | `0` = grammar-only final check |
+| `POLISH_MAX_EDIT` | `0.6` | Largest share of a sentence's words the polish may change |
+| `POLISH_KEEP_HUMAN` | `1` | `0` = always keep the polished wording, even if the AI score rises |

groqai.py

@@ -341,56 +341,68 @@ def grammar(sentences, glossary, progress=None, lo=0.9, hi=0.95):
     return out
 
 
-# ---------------------------------------------------------------- final polish: grammar + academic register + flow
+# ---------------------------------------------------------------- final polish: repair + grammar + register + flow
 POLISH_SYSTEM = f"""You are the final copy-editor of a technical academic manuscript (journal / thesis quality).
-The text is given paragraph by paragraph; each numbered item is one sentence. Edit every sentence so that the
-paragraph reads as clear, natural, formal technical academic English written by a careful researcher:
-1. Grammar: fix grammar, spelling, punctuation, agreement, articles, verb forms, tense, prepositions, missing or
-   doubled words and broken or run-on sentence structure.
-2. Academic register: replace informal, odd or wrong-sense words with the precise technical word (e.g. "spotted"
-   -> "repeated", "absurd" -> "inappropriate"); remove redundancy ("an optimization framework for optimization");
-   no first person singular, no "you", no contractions, no opinions.
-3. Flow: make each sentence follow naturally from the one before it in the same paragraph. Use clear logical
-   links where they are needed (however, therefore, in contrast, as a result, for example), vary repetitive
-   sentence openings, and smooth awkward word order. Keep the paragraph's order of ideas.
-Rules: keep the meaning, claims, hedging and level of certainty of every sentence exactly. Do NOT add or remove
-facts, names, numbers, results or citations. Do NOT merge, split, drop or reorder sentences: return exactly one
-sentence per id. Keep every technical term, acronym, formula, symbol, number, unit and citation (e.g. [12],
-(Kumar et al., 2021)) exactly as written, including every item in PROTECTED TERMS. Keep the author's wording
-wherever it is already correct and clear; change only what improves correctness, precision or flow.
+The text was produced by an automatic paraphrasing tool, which sometimes substitutes wrong words, drops words or
+joins phrases so that a sentence no longer makes sense. It is given paragraph by paragraph; each numbered item is
+one sentence of the CURRENT text. When available, the author's ORIGINAL paragraph is shown first: use it ONLY to
+understand what each sentence is meant to say.
+For every numbered sentence:
+1. Clarity first. If the sentence is unclear, garbled, ungrammatical in a way that hides its meaning, or says
+   something different from the original, REPAIR it: rewrite it so that it says exactly what the original means,
+   in clear academic English, keeping the current wording wherever that wording is correct. status "repaired".
+2. Otherwise edit it lightly (status "edited") or keep it (status "ok"):
+   - grammar: agreement, articles, verb forms, tense, prepositions, missing or doubled words, run-on sentences;
+   - academic register: precise technical words instead of informal, odd or wrong-sense words (e.g. "spotted"
+     -> "repeated", "comprehension" -> "understanding" where that is meant); remove redundancy; no first person
+     singular, no "you", no contractions, no opinions;
+   - flow: each sentence should follow naturally from the previous one in the paragraph; add a logical link only
+     where it is needed (however, therefore, in contrast, for example) and vary repetitive openings.
+Rules: keep the meaning, claims and hedging of the original exactly. Do NOT add facts, names, numbers, results or
+citations that are not in the sentence or the original. Do NOT merge, split, drop or reorder sentences: return
+exactly one sentence per id. Keep every technical term, acronym, formula, symbol, number, unit and citation (e.g.
+[12], (Kumar et al., 2021)) exactly as written, including every item in PROTECTED TERMS. Do not copy the
+original back word for word unless the current sentence cannot be repaired any other way.
 Do not add these words: {_AI_WORDS}. No em dashes.
-Answer only with JSON: {{"items": [{{"id": 1, "text": "edited sentence"}}, ...]}} — one per id."""
+Answer only with JSON: {{"items": [{{"id": 1, "status": "ok|edited|repaired", "text": "sentence"}}, ...]}} —
+one per id."""
 
 
 def _polish_batch(items, glossary):
-    """items: list of (paragraph_key, sentence) in document order -> list of edited sentences (None = missing)."""
-    sents = [t for _, t in items]
+    """items: list of (paragraph_key, sentence, original_paragraph_or_None) in document order
+    -> list of (status, edited sentence) (None, None = missing)."""
+    sents = [t for _, t, _ in items]
     terms = _surface_terms(" ".join(sents), glossary)
     lines, last, para = [], object(), 0
-    for i, (g, t) in enumerate(items, 1):
+    for i, (g, t, orig) in enumerate(items, 1):
         if g != last:
             para += 1
             lines.append(f"\n[Paragraph {para}]")
+            if orig:
+                lines.append(f"ORIGINAL: {orig}")
+                lines.append("CURRENT:")
             last = g
         lines.append(f"{i}. {t}")
     user = "PROTECTED TERMS: " + ("; ".join(terms) if terms else "(none)") + "\n" + "\n".join(lines)
-    max_tokens = min(8000, 500 + int(sum(len(t) for t in sents) * 0.7))
+    max_tokens = min(8000, 600 + int(sum(len(t) for t in sents) * 0.8))
     content = _chat([{"role": "system", "content": POLISH_SYSTEM}, {"role": "user", "content": user}], 0.2,
                     max_tokens)
-    return [t for _, t in _parse(content, len(sents))]
+    return _parse(content, len(sents))
 
 
-def polish(sentences, groups=None, glossary=(), progress=None, lo=0.9, hi=0.95, size=None):
-    """Grammar + academic wording + flow edit of `sentences`. `groups` gives a paragraph key per sentence so that
-    whole paragraphs are edited together (sentences of one paragraph stay in one request where possible).
-    Returns one entry per sentence: the edited text, or None if its batch could not be edited.
+def polish(sentences, groups=None, glossary=(), progress=None, lo=0.9, hi=0.95, size=None, originals=None):
+    """Repair + grammar + academic wording + flow edit of `sentences`. `groups` gives a paragraph key per sentence
+    (a paragraph is edited as a whole); `originals` gives, per sentence, the author's original paragraph (or
+    sentence) it came from, so garbled sentences can be repaired to the intended meaning.
+    Returns one (status, text) per sentence; (None, None) if its batch could not be edited.
     Raises Unavailable only if nothing could be edited."""
     from concurrent.futures import ThreadPoolExecutor, as_completed
     n = len(sentences)
-    out = [None] * n
+    out = [(None, None)] * n
     if not n:
         return out
     groups = list(groups) if groups is not None else list(range(n))
+    originals = list(originals) if originals is not None else [None] * n
     size = size or max(BATCH, 16)
     batches, cur = [], []
     i = 0
@@ -411,9 +423,10 @@ def polish(sentences, groups=None, glossary=(), progress=None, lo=0.9, hi=0.95,
         batches.append(cur)
     done, ok_batches, first_err = 0, 0, None
     if progress is not None:
-        progress(lo, desc=f"Final polish of {n} sentences: grammar, academic wording and flow (Groq)")
+        progress(lo, desc=f"Final polish of {n} sentences: clarity, grammar, academic wording and flow (Groq)")
     with ThreadPoolExecutor(max_workers=min(PARALLEL, len(batches))) as pool:
-        futs = {pool.submit(_polish_batch, [(groups[k], sentences[k]) for k in b], glossary): b for b in batches}
+        futs = {pool.submit(_polish_batch, [(groups[k], sentences[k], originals[k]) for k in b], glossary): b
+                for b in batches}
         for f in as_completed(futs):
             b = futs[f]
             done += 1
@@ -423,8 +436,8 @@ def polish(sentences, groups=None, glossary=(), progress=None, lo=0.9, hi=0.95,
                 first_err = first_err or err
                 continue
             ok_batches += 1
-            for k, t in zip(b, res):
-                out[k] = t
+            for k, r in zip(b, res):
+                out[k] = r
             if progress is not None:
                 progress(lo + (hi - lo) * done / len(batches), desc=f"Final polish: {done}/{len(batches)} batches")
     if not ok_batches and first_err is not None:

humanizer.py

@@ -698,37 +698,78 @@ def _edit_share(a, b):
     return sum(max(i2 - i1, j2 - j1) for op, i1, i2, j1, j2 in sm.get_opcodes() if op != "equal") / len(wa)
 
 
-def _polish(sentences, out, idx, groups, glossary, progress, lo, hi):
-    """Groq polish of out[idx] (grammar + academic wording + flow). Returns (indices polished, indices that still
-    need a grammar-only check)."""
-    res = G.polish([out[i] for i in idx], [groups[i] for i in idx], glossary, progress, lo, hi)
-    cand = {}
-    for i, r in zip(idx, res):
-        if not r or r.strip() == out[i].strip():
+def _polish(sentences, out, idx, groups, glossary, progress, lo, hi, orig_par, orig_sent, stats):
+    """Groq repair + polish of out[idx]. Garbled sentences are REPAIRED to the meaning of the author's original
+    (clarity wins over the AI score); clear sentences get the light polish (grammar, academic wording, flow) with
+    the usual limits. A garbled sentence that cannot be repaired safely gets the original sentence back when it is
+    known. Returns the indices that still need the grammar-only check."""
+    ctx = [orig_par[i] or orig_sent[i] for i in idx]
+    ctx = [c if c and c.strip() != out[i].strip() else None for c, i in zip(ctx, idx)]
+    res = G.polish([out[i] for i in idx], [groups[i] for i in idx], glossary, progress, lo, hi, originals=ctx)
+    edited, repaired, missing, broken = {}, {}, [], []
+    for i, (st, r) in zip(idx, res):
+        if not r:
+            missing.append(i)
+            continue
+        if r.strip() == out[i].strip():
+            continue
+        ref = orig_sent[i] or sentences[i]
+        if st == "repaired":
+            ok = TP.guard(ref, TP.restore_terms(ref, r.strip(), glossary), glossary)
+            if not ok and orig_sent[i]:
+                ok = TP.guard(sentences[i], TP.restore_terms(sentences[i], r.strip(), glossary), glossary)
+            if ok:
+                repaired[i] = TP.basic_grammar(ok)
+            else:
+                broken.append(i)
             continue
         ok = TP.guard(sentences[i], TP.restore_terms(sentences[i], r.strip(), glossary), glossary)
         if ok and _edit_share(out[i], ok) <= max(POLISH_MAX_EDIT, 3 / max(1, len(out[i].split()))):
-            cand[i] = TP.basic_grammar(ok)
-    if cand:                                           # meaning must stay the same
-        keys = list(cand)
-        for i, k in zip(keys, MEANING.keeps_meaning([(sentences[i], cand[i]) for i in keys])):
+            edited[i] = TP.basic_grammar(ok)
+        else:
+            missing.append(i)
+    # meaning: a repair must be at least as close to the original as the garbled sentence was
+    if repaired:
+        keys = list(repaired)
+        refs = [orig_sent[i] or orig_par[i] or sentences[i] for i in keys]
+        sim = MEANING.similarities([(r_, repaired[i]) for r_, i in zip(refs, keys)]
+                                   + [(r_, out[i]) for r_, i in zip(refs, keys)])
+        m = len(keys)
+        for n_, i in enumerate(keys):
+            exact = orig_sent[i] is not None
+            if (exact and sim[n_] < MEANING.MIN_SIM) or (not exact and sim[n_] < sim[m + n_] - 0.02):
+                repaired.pop(i)
+                broken.append(i)
+    if edited:                                         # light edits must keep the meaning ...
+        keys = list(edited)
+        for i, k in zip(keys, MEANING.keeps_meaning([(sentences[i], edited[i]) for i in keys])):
             if not k:
-                cand.pop(i)
-    if cand and POLISH_KEEP_HUMAN:                     # do not undo the humanization
-        keys = list(cand)
-        sc = _detector_scores([cand[i] for i in keys] + [out[i] for i in keys])
+                edited.pop(i)
+                missing.append(i)
+    if edited and POLISH_KEEP_HUMAN:                   # ... and must not undo the humanization
+        keys = list(edited)
+        sc = _detector_scores([edited[i] for i in keys] + [out[i] for i in keys])
         if sc:
             m = len(keys)
             for n_, i in enumerate(keys):
                 if sc[n_] >= 0.5 > sc[m + n_] or sc[n_] > sc[m + n_] + 0.35:
-                    cand.pop(i)
-    for i, t in cand.items():
+                    edited.pop(i)
+                    missing.append(i)
+    for i, t in list(edited.items()) + list(repaired.items()):
         out[i] = t
-    missing = [i for i, r in zip(idx, res) if r is None or (i not in cand and r.strip() != out[i].strip())]
-    return set(cand), missing
+    restored = 0
+    for i in broken:                                   # unclear and not safely repairable: the clear original
+        if orig_sent[i] and orig_sent[i].strip() != out[i].strip():
+            out[i] = orig_sent[i]
+            restored += 1
+        else:
+            missing.append(i)
+    stats.update(edited=len(edited), repaired=len(repaired), restored=restored)
+    return sorted(set(missing))
 
 
-def grammar_fix_sentences(sentences, glossary=None, progress=None, lo=0.9, hi=0.95, groups=None):
+def grammar_fix_sentences(sentences, glossary=None, progress=None, lo=0.9, hi=0.95, groups=None,
+                          orig_par=None, orig_sent=None):
     """Final correction of `sentences`. Returns (sentences, n_fixed, note).
     1. rule-based clean-up (doubled words, a/an, 'will opening', spacing, capitals, final full stop) - always runs;
     2. Groq final polish (POLISH=1, default): whole paragraphs (`groups` = paragraph key per sentence) are edited
@@ -741,14 +782,17 @@ def grammar_fix_sentences(sentences, glossary=None, progress=None, lo=0.9, hi=0.
         return list(sentences), 0, ""
     out = [TP.basic_grammar(t) if len(t.split()) >= 3 else t for t in sentences]
     groups = list(groups) if groups is not None else list(range(len(sentences)))
-    note, polished = "", set()
+    orig_par = list(orig_par) if orig_par is not None else [None] * len(sentences)
+    orig_sent = list(orig_sent) if orig_sent is not None else [None] * len(sentences)
+    note, stats = "", dict(edited=0, repaired=0, restored=0)
     if G.available():
         glossary = glossary if glossary is not None else (TP.build_glossary(out) | TP.GLOSSARY.get())
         idx = [i for i, t in enumerate(out) if len(t.split()) >= 3]
         todo = idx
         if POLISH and idx:
             try:
-                polished, todo = _polish(sentences, out, idx, groups, glossary, progress, lo, lo + (hi - lo) * 0.7)
+                todo = _polish(sentences, out, idx, groups, glossary, progress, lo, lo + (hi - lo) * 0.7,
+                               orig_par, orig_sent, stats)
             except G.Unavailable as err:               # fall back to the grammar-only check
                 print(f"[humanizer] Groq final polish skipped, grammar-only check instead: {err}", flush=True)
         try:
@@ -778,22 +822,39 @@ def grammar_fix_sentences(sentences, glossary=None, progress=None, lo=0.9, hi=0.
         if n_lt:
             note += f" 🔎 LanguageTool fixed {n_lt} sentence(s)."
     n = sum(1 for a, b in zip(sentences, out) if a.strip() != b.strip())
-    pol = sum(1 for i in polished if out[i].strip() != sentences[i].strip())
-    head = (f" 📝 Final polish (grammar, academic wording, flow): {n} sentence(s) improved"
-            + (f", {pol} of them edited for wording and flow." if pol else ".")) if n else \
-        " 📝 Final polish: no changes needed."
+    parts = [f"{stats[k]} {lbl}" for k, lbl in (("repaired", "unclear sentence(s) repaired to the original meaning"),
+                                                 ("restored", "restored to your original wording"),
+                                                 ("edited", "edited for wording and flow")) if stats[k]]
+    head = (f" 📝 Final polish (clarity, grammar, academic wording, flow): {n} sentence(s) improved"
+            + (f" ({'; '.join(parts)})." if parts else ".")) if n else " 📝 Final polish: no changes needed."
     return out, n, head + note
 
 
-def grammar_pass(paragraphs, progress=None, lo=0.9, hi=0.95):
-    """Grammar-correct whole paragraphs sentence by sentence. Returns (paragraphs, n_fixed, note)."""
-    groups, sents = [], []
-    for p in paragraphs:
+def originals_for(new_sents, orig_paragraph):
+    """Per sentence of a rewritten paragraph: (original paragraph, original sentence or None). The sentence is
+    known only when the original paragraph has the same number of sentences (one-to-one rewrite)."""
+    if not orig_paragraph:
+        return [(None, None)] * len(new_sents)
+    os_ = split_sentences(orig_paragraph) or [orig_paragraph]
+    same = len(os_) == len(new_sents)
+    return [(orig_paragraph, os_[k] if same else None) for k in range(len(new_sents))]
+
+
+def grammar_pass(paragraphs, progress=None, lo=0.9, hi=0.95, originals=None):
+    """Final polish of whole paragraphs, sentence by sentence. `originals` (same order as `paragraphs`) are the
+    author's original paragraphs, used to repair garbled sentences. Returns (paragraphs, n_fixed, note)."""
+    groups, sents, op, os_ = [], [], [], []
+    if originals is not None and len(originals) != len(paragraphs):
+        originals = None
+    for k, p in enumerate(paragraphs):
         ss = split_sentences(p) or [p]
         groups.append((len(sents), len(sents) + len(ss), len(ss) > 1 or ss[0] != p))
         sents.extend(ss)
+        for a_, b_ in originals_for(ss, originals[k] if originals is not None else None):
+            op.append(a_)
+            os_.append(b_)
     para_of = [k for k, (a, b, _) in enumerate(groups) for _ in range(a, b)]
-    fixed, n, note = grammar_fix_sentences(sents, None, progress, lo, hi, groups=para_of)
+    fixed, n, note = grammar_fix_sentences(sents, None, progress, lo, hi, groups=para_of, orig_par=op, orig_sent=os_)
     if not n:
         return list(paragraphs), 0, note
     out = []
@@ -809,7 +870,7 @@ def paraphrase_paragraphs(texts, temperature, progress=None, lo=0.15, hi=0.85, m
     defers it to its own end) Groq corrects the grammar of the finished paragraphs."""
     out, note = _paraphrase_local(texts, temperature, progress, lo, hi, mode)
     if GRAMMAR and not GRAMMAR_DEFER.get():
-        out, _, gnote = grammar_pass(out, progress, hi, min(0.97, hi + 0.08))
+        out, _, gnote = grammar_pass(out, progress, hi, min(0.97, hi + 0.08), originals=list(texts))
         note += gnote
     return out, note
 

smart.py

@@ -295,7 +295,8 @@ def _report_rewrite(sentences, temperature, mode, rep, lo, hi):
         # grammar now, so the results table shows exactly the wording that goes into the document
         idx = [i for i, (o, b) in enumerate(zip(sentences, best)) if b.strip() != o.strip()]
         if idx and H.GRAMMAR:
-            fixed, _, _ = H.grammar_fix_sentences([best[i] for i in idx], gl, rep, hi, hi)
+            fixed, _, _ = H.grammar_fix_sentences([best[i] for i in idx], gl, rep, hi, hi,
+                                                  orig_sent=[sentences[i] for i in idx])
             for i, f in zip(idx, fixed):
                 ok = guard(sentences[i], f)
                 if ok and MEANING.ok(sentences[i], ok):
@@ -368,30 +369,44 @@ def _better(cand, best, k):
     return cand[1] >= best[1]
 
 
-def _grammar_docx(doc, rep):
+def _grammar_docx(doc, rep, orig_path=None):
     """Final Groq grammar check of every sentence in the document's prose, written back in place (only plain
     text runs are touched, so citation fields, links and sub/superscripts keep their formatting)."""
-    jobs = []
-    for b in D.docx_blocks(doc):
+    jobs, op, os_ = [], [], []
+    blocks = list(D.docx_blocks(doc))
+    orig = None
+    if orig_path:                                      # the author's original paragraphs, block by block
+        try:
+            ob = list(D.docx_blocks(DX.open_clean(orig_path)))
+            orig = ob if len(ob) == len(blocks) else None
+        except Exception as err:
+            print(f"[smart] original paragraphs not available for the final polish: {err}", flush=True)
+    for bi, b in enumerate(blocks):
         if b.kind != "para" or b.el is None or not b.raw:
             continue
         raws = D.split_sentences(b.raw)
-        for sp in DX.sentence_char_spans(b.raw, raws):
+        o_raw = orig[bi].raw if orig is not None and orig[bi].kind == "para" else None
+        ctx = H.originals_for(raws, o_raw)
+        for sp, (cp, cs) in zip(DX.sentence_char_spans(b.raw, raws), ctx):
             if not sp:
                 continue
             sub = safe_subspan(b.el, *sp)
             if sub:
                 jobs.append((b, sub, b.raw[sub[0]:sub[1]]))
+                op.append(cp)
+                os_.append(cs if sub == tuple(sp) or list(sub) == list(sp) else None)
     if not jobs:
         return 0, ""
     fixed, n, note = H.grammar_fix_sentences([j[2] for j in jobs], None, rep, 0.9, 0.95,
-                                             groups=[id(j[0]) for j in jobs])
+                                             groups=[id(j[0]) for j in jobs], orig_par=op, orig_sent=os_)
     done = 0
     for (b, (a, e), t), f in sorted(zip(jobs, fixed), key=lambda x: (id(x[0][0]), -x[0][1][0])):
         if f != t and replace_span(b.el, a, e, f):
             done += 1
     if done:
-        return done, f" 📝 Final polish by Groq (grammar, academic wording, flow): {done} sentence(s) improved."
+        m = re.search(r"improved \((.*?)\)\.", note or "")
+        return done, (f" 📝 Final polish by Groq (clarity, grammar, academic wording, flow): {done} sentence(s) "
+                      f"improved" + (f" ({m.group(1)})." if m else "."))
     return 0, note if "unavailable" in note else ""
 
 
@@ -517,7 +532,7 @@ def smart_docx(path, target, passes, temperature, mode, hi, mod, rep):
     blocks = best[2][1]
     after = D.summarise(blocks, hi, mod)
     if H.GRAMMAR:                                      # final step: Groq grammar check of the finished text
-        n, gnote = _grammar_docx(doc, rep)
+        n, gnote = _grammar_docx(doc, rep, path)
         if n:                                          # always kept: the final text must read correctly
             blocks = _score_doc(doc)
             after = D.summarise(blocks, hi, mod)
@@ -621,7 +636,9 @@ def smart_text(text, target, passes, temperature, mode, hi, mod, rep):
     after = D.summarise(blocks, hi, mod)
     if H.GRAMMAR:                                      # final step: Groq grammar check of the finished text
         idx = [i for i, b in enumerate(blocks) if b.kind == "para" and i < len(paras)]
-        newp, n, gnote = H.grammar_pass([paras[i] for i in idx], rep, 0.9, 0.95)
+        o_paras = [p for p, _ in parts]
+        newp, n, gnote = H.grammar_pass([paras[i] for i in idx], rep, 0.9, 0.95,
+                                        originals=[o_paras[i] if i < len(o_paras) else None for i in idx])
         if n:                                          # always kept: the final text must read correctly
             for i, p in zip(idx, newp):
                 paras[i] = p